src/contracts.ts

@@ -81,7 +81,8 @@ export type StreamEventType =
   | 'run.phase' | 'hitl.request' | 'hitl.resolved' | 'plan.update' | 'todo.update'
   | 'agent.spawn' | 'agent.progress' | 'agent.result'
   | 'artifact.created' | 'artifact.updated'
-  | 'run.completed' | 'run.failed' | 'error';
+  | 'run.completed' | 'run.failed' | 'error'
+  | 'card.created' | 'card.updated' | 'card.status' | 'card.resolved';
 
 export interface StreamEvent<P = unknown> {
   seq: number; runId?: ID; conversationId: ID; ts: string; v: number;
@@ -106,6 +107,28 @@ export interface ContextObservation {
 }
 export interface RunFailedPayload { code: string; message: string }
 
+// ---- 收件箱卡片 ----
+
+export type CardKind =
+  | 'progress' | 'confirm' | 'compare' | 'review-list'
+  | 'result' | 'error' | 'status';
+
+export type CardStatus =
+  | 'active' | 'action_required' | 'done'
+  | 'resolved' | 'failed' | 'dismissed';
+
+export interface ActivityCard {
+  id: ID; projectId: ID; conversationId?: ID;
+  sourceRunId?: ID; anchorMessageId?: ID;
+  kind: CardKind; title: string; status: CardStatus; tone?: string;
+  body?: UINode[]; actions?: { id: string; label: string; style?: 'primary' | 'default' | 'danger'; command?: string }[];
+  pinned?: boolean; createdAt: string; updatedAt: string;
+}
+
+export interface CardPayload { card: ActivityCard }
+export interface CardStatusPayload { cardId: ID; status: CardStatus; tone?: string; note?: string }
+export interface CardResolvedPayload { cardId: ID; actionId?: string; answer?: string }
+
 // ---- HITL ----
 
 export type HITLKind = 'choice' | 'input' | 'confirm' | 'form';
@@ -118,6 +141,7 @@ export interface HITLCard {
   id: ID; runId: ID; conversationId: ID; question: string; kind: HITLKind;
   choices?: HITLChoice[]; allowFreeInput: boolean; freeInputHint?: string;
   timeoutSec?: number | null; form?: UINode[]; createdAt: string; resolved: boolean;
+  anchorMessageId?: ID; blocked?: boolean; blockReason?: string;
 }
 
 export interface HITLResponse {
@@ -127,7 +151,8 @@ export interface HITLResponse {
 // ---- UI 词汇 ----
 
 export type UINodeType =
-  | 'section' | 'list' | 'kv' | 'form' | 'markdown' | 'doc-ref' | 'actions' | 'chart-lite';
+  | 'section' | 'list' | 'kv' | 'form' | 'markdown' | 'doc-ref' | 'actions' | 'chart-lite'
+  | 'progress' | 'compare' | 'tree' | 'table' | 'steps' | 'tabs' | 'timeline';
 
 export interface UINode {
   type: UINodeType;
@@ -140,6 +165,25 @@ export interface UINode {
   actions?: { id: string; label: string; style?: 'primary' | 'default' | 'danger' }[];
   chart?: { kind: 'bar' | 'line'; labels: string[]; series: number[] };
   children?: UINode[];
+
+  progress?: { label?: string; value: number; tone?: string };
+  compare?: {
+    left: { title?: string; tone?: string; nodes?: UINode[] };
+    right: { title?: string; tone?: string; nodes?: UINode[] };
+  };
+  tree?: {
+    nodes: {
+      id: string; label: string; tone?: string; badge?: string; count?: number;
+      selected?: boolean; children?: unknown[];
+    }[];
+  };
+  table?: {
+    columns: { key: string; label: string }[];
+    rows: { id?: string; cells: [string, string][]; actions?: UINode['actions'] }[];
+  };
+  steps?: { current: number; steps: { label: string; status?: 'pending' | 'active' | 'done' | 'failed'; tone?: string }[] };
+  tabs?: { active?: string; tabs: { id: string; label: string; nodes?: UINode[] }[] };
+  timeline?: { items: { time?: string; title: string; tone?: string; markdown?: string; ref?: string }[] };
 }
 
 export interface UIField {
@@ -179,6 +223,7 @@ export interface PluginManifest {
   provides: {
     tools?: string[]; workflows?: string[]; intents?: string[];
     prompts?: string[]; panels?: string[]; cards?: string[]; settings?: string[];
+    commands?: string[]; workspaces?: string[];
   };
 }
 
@@ -186,6 +231,11 @@ export interface PluginPanel {
   id: string; title: string; icon?: string; body: UINode[]; refreshTool?: string;
 }
 
+export interface PluginWorkspace {
+  id: string; title: string; icon?: string; shortcut?: string;
+  badgeTool?: string; body: UINode[]; refreshTool?: string;
+}
+
 // ---- 摄取 / 检索 ----
 
 export interface ParsedDocument {