minimal-agent 0.13.0 → 0.15.0

package/src/web/protocol.ts

@@ -17,11 +17,46 @@
  * ============================================================
  */
 
-import type { AskAnswer, AskOption, AskQuestionSpec, AskSource } from '../askBridge.js';
-import type { PluginEvent } from '../plugins/pluginApi.js';
-import type { AgentResultMetadata, ConversationFilePurpose, DeliverableManifest, FileActivityMetadata, LoopEvent, Message, MessageAttachmentRef, MessageBrowserReference, ProgressStage, SubagentProgress, ToolCall, ToolProgressDetail, ToolResultMetadata } from '../types.js';
-import type { ConversationSearchResult, MemoryCategory, MemoryDiagnostic, MemoryEditablePatch, MemoryRecord, MemorySettings, MemoryUpdate, PersonaDocument } from '../memory/memoryService.js';
+import type {
+  AskAnswer,
+  AskOption,
+  AskQuestionSpec,
+  AskSource,
+} from '../askBridge.js';
 import type { HumanInterventionReason } from '../humanIntervention.js';
+import type { ModelFallbackReason, ModelRef } from '../modelRef.js';
+import type { OnlineModelAvailability } from '../team/onlineToolContract.js';
+export type {
+  ModelFallbackReason,
+  ModelRef,
+  SessionModelPreference,
+} from '../modelRef.js';
+import type {
+  ConversationSearchResult,
+  MemoryCategory,
+  MemoryDiagnostic,
+  MemoryEditablePatch,
+  MemoryRecord,
+  MemorySettings,
+  MemoryUpdate,
+  PersonaDocument,
+} from '../memory/memoryService.js';
+import type { PluginEvent } from '../plugins/pluginApi.js';
+import type {
+  AgentResultMetadata,
+  ConversationFilePurpose,
+  DeliverableManifest,
+  FileActivityMetadata,
+  LoopEvent,
+  Message,
+  MessageAttachmentRef,
+  MessageBrowserReference,
+  ProgressStage,
+  SubagentProgress,
+  ToolCall,
+  ToolProgressDetail,
+  ToolResultMetadata,
+} from '../types.js';
 
 /**
  * 桌面控制的**线路观测形状**（协议自持，不 import 具体工具）。
@@ -60,7 +95,13 @@ export interface ComputerObservation {
  */
 export type BrowserControlState =
   | { owner: 'none'; status: 'idle' }
-  | { owner: 'agent'; status: 'running'; runId: string; conversationKey?: string; action?: string }
+  | {
+      owner: 'agent';
+      status: 'running';
+      runId: string;
+      conversationKey?: string;
+      action?: string;
+    }
   | {
       owner: 'user';
       status: 'waiting_human';
@@ -71,7 +112,12 @@ export type BrowserControlState =
       resumeToken: string;
       ownerId: string;
     }
-  | { owner: 'user'; status: 'interactive'; runId?: string; conversationKey?: string };
+  | {
+      owner: 'user';
+      status: 'interactive';
+      runId?: string;
+      conversationKey?: string;
+    };
 
 export type {
   ConversationFilePurpose,
@@ -90,12 +136,12 @@ export type {
   PersonaDocument,
 } from '../memory/memoryService.js';
 import type {
+  CronListFilter,
   CronMissedRecord,
   CronRunRecord,
   CronTask,
   CronTaskDraft,
   CronTaskPatch,
-  CronListFilter,
 } from '../../plugins/cron-runner/src/types.js';
 
 export type AgentEvent = LoopEvent | PluginEvent;
@@ -253,10 +299,19 @@ export type ApiFormat = 'openai' | 'anthropic';
 /** 模型列表的一个条目（脱敏视图——apiKey 只给 configured 布尔位，不下发原文）。 */
 export interface ModelView {
   id: string;
+  /** 展示来源；本机模型省略此字段以兼容旧 Runtime。 */
+  source?: 'local' | 'gateway';
+  /** Server catalog only; local model lists leave this unset. */
+  isDefault?: boolean;
+  maxToolCategories?: string[];
+  defaultToolCategories?: string[];
+  capabilities?: { vision: boolean; tools: boolean; structuredOutput: boolean };
+  availability?: OnlineModelAvailability;
   apiFormat: ApiFormat;
   displayName?: string;
-  baseURL: string;
-  apiKeyConfigured: boolean;
+  /** Only local model views include provider endpoint metadata. */
+  baseURL?: string;
+  apiKeyConfigured?: boolean;
   model: string;
   contextWindow: number;
   maxTokens?: number;
@@ -392,7 +447,12 @@ export interface ToolConfigView {
   message?: string;
 }
 
-export type ToolConfigName = 'advisor' | 'webSearch' | 'imageGeneration' | 'openRouter' | 'textToSpeech';
+export type ToolConfigName =
+  | 'advisor'
+  | 'webSearch'
+  | 'imageGeneration'
+  | 'openRouter'
+  | 'textToSpeech';
 /** 'provider' 分区已删除——models/baseModelId/advisor 都走立即生效的 config/update，不再自动保存。 */
 export type ConfigAutosaveSection = 'general' | 'tools' | 'browser';
 
@@ -406,7 +466,15 @@ export interface ArchiveEntry {
 export interface DirEntry {
   name: string;
   path: string;
-  kind?: 'home' | 'desktop' | 'documents' | 'downloads' | 'cloud' | 'volume' | 'network' | 'root';
+  kind?:
+    | 'home'
+    | 'desktop'
+    | 'documents'
+    | 'downloads'
+    | 'cloud'
+    | 'volume'
+    | 'network'
+    | 'root';
 }
 
 export interface DirListing {
@@ -447,6 +515,11 @@ export interface SessionSummary {
   updatedAt: number;
   lastMessagePreview?: string;
   modelId?: string;
+  preferredModel?: ModelRef;
+  effectiveModel?: ModelRef;
+  fallbackReason?: ModelFallbackReason;
+  restoreWhenAvailable?: boolean;
+  onlineToolCategories?: string[];
 }
 
 export type ConversationTarget =
@@ -614,9 +687,13 @@ export interface UserProfile {
   /** 旧版账号兼容显示；新账号不再依赖 username 作为身份。 */
   username?: string;
   displayName: string;
+  /** Small user avatar stored as a validated image data URL. */
+  avatarData?: string;
   createdAt: number;
   /** 站长（首个注册用户）：可操作服务器本地工作目录/配置/cron；普通用户经 Agent Node 挂自己的 agent。 */
   isAdmin?: boolean;
+  /** 初始引导密码或管理员重置密码后，必须先完成改密。 */
+  passwordChangeRequired?: boolean;
 }
 
 export interface FriendEntry {
@@ -684,7 +761,6 @@ export interface WorkspaceSessionAgent {
   ownerUserId: string;
   displayName: string;
   status: 'online' | 'offline' | 'busy';
-  boundGroupId?: string;
   lastActiveAt?: number;
 }
 
@@ -752,9 +828,24 @@ export type ProjectStatus = 'active' | 'archived';
 export type ProjectProvider = 'github' | 'gitlab' | 'local-git';
 export type ParticipantKind = 'human' | 'agent';
 export type RoleScope = 'project' | 'task';
-export type WorkItemStatus = 'backlog' | 'ready' | 'in_progress' | 'review' | 'blocked' | 'done';
+/**
+ * 任务卡状态。`proposed`＝方案待审，是"人只对方案负责"的强制停顿点；
+ * `review`＝待验收。流转规则与拍板权限的唯一真值在 `minimal-agent/task-flow`。
+ */
+export type WorkItemStatus =
+  | 'backlog'
+  | 'ready'
+  | 'proposed'
+  | 'in_progress'
+  | 'review'
+  | 'blocked'
+  | 'done';
 export type CollaborationMode = 'parallel' | 'alternative' | 'pair' | 'review';
-export type HandoffStatus = 'offered' | 'accepted' | 'changes_requested' | 'completed';
+export type HandoffStatus =
+  | 'offered'
+  | 'accepted'
+  | 'changes_requested'
+  | 'completed';
 
 export interface ProjectRepository {
   id: string;
@@ -921,7 +1012,15 @@ export interface ProjectArtifact {
   id: string;
   projectId: string;
   workItemId?: string;
-  kind: 'diff' | 'commit' | 'pull_request' | 'test_report' | 'document' | 'design' | 'database_script' | 'file';
+  kind:
+    | 'diff'
+    | 'commit'
+    | 'pull_request'
+    | 'test_report'
+    | 'document'
+    | 'design'
+    | 'database_script'
+    | 'file';
   title: string;
   contentHash?: string;
   attachmentId?: string;
@@ -976,15 +1075,56 @@ export type NodeClientFrame =
   | { t: 'node/register'; token: string; name: string }
   | { t: 'node/heartbeat' }
   | { t: 'workspace/publish'; workspaceKey: string; displayName: string }
-  | { t: 'session/publish'; workspaceAgentId: string; sessionKey: string; displayName: string }
+  | {
+      t: 'session/publish';
+      workspaceAgentId: string;
+      sessionKey: string;
+      displayName: string;
+      /** 由 session/create 触发时回带，服务端据此把新会话自动加进发起的那个群。 */
+      requestId?: string;
+    }
+  | { t: 'session/createFailed'; requestId: string; error: string }
   | { t: 'session/revoke'; workspaceSessionId: string }
   | { t: 'workspace/revoke'; workspaceAgentId: string }
-  | { t: 'workspace/status'; workspaceAgentId: string; status: WorkspaceRepositoryStatus }
+  | {
+      t: 'workspace/status';
+      workspaceAgentId: string;
+      status: WorkspaceRepositoryStatus;
+    }
   | { t: 'group/ack'; deliveryId: string }
   | { t: 'agent/event'; requestId: string; event: AgentEvent }
-  | { t: 'agent/question'; requestId: string; deliveryId: string; questions: AskQuestionSpec[]; source?: AskSource }
-  | { t: 'agent/questionResolved'; requestId: string; deliveryId: string; state: 'answered' | 'cancelled' }
-  | { t: 'agent/reply'; requestId: string; text: string; files?: AgentFileMetadata[]; error?: string }
+  | {
+      t: 'agent/question';
+      requestId: string;
+      deliveryId: string;
+      questions: AskQuestionSpec[];
+      source?: AskSource;
+    }
+  | {
+      t: 'agent/questionResolved';
+      requestId: string;
+      deliveryId: string;
+      state: 'answered' | 'cancelled';
+    }
+  | {
+      t: 'agent/reply';
+      requestId: string;
+      text: string;
+      files?: AgentFileMetadata[];
+      error?: string;
+    }
+  | {
+      t: 'agent/groupUpdate';
+      requestId: string;
+      deliveryId: string;
+      update: GroupAgentUpdate;
+    }
+  | {
+      t: 'agent/groupDelegate';
+      requestId: string;
+      deliveryId: string;
+      delegation: GroupAgentDelegation;
+    }
   | {
       /** 外部成员委托必须在 LLM 启动前获得主人批准。 */
       t: 'agent/delegationRequest';
@@ -999,13 +1139,49 @@ export type NodeClientFrame =
       deliveryId: string;
       toolName: string;
       argsPreview: string;
+    }
+  | {
+      /** 取一条群消息里引用的附件（publicContext 里的 `[attachment:<fileId>]` 句柄）。
+       *  服务端只回一次性下载票据，字节由节点自己走 HTTP GET —— 不把大二进制塞进这条
+       *  「都是小 JSON 控制帧」的连接（base64 还膨胀 33%，且会队头阻塞）。 */
+      t: 'attachment/fetch';
+      requestId: string;
+      deliveryId: string;
+      fileId: string;
+    }
+  | {
+      /** 请求把一个**交付物**上传成群附件的一次性票据（导出前的同意已在节点侧问过主人）。
+       *  同样只发票据，字节由节点自己 PUT 上去。 */
+      t: 'attachment/uploadRequest';
+      requestId: string;
+      deliveryId: string;
+      name: string;
+      mime: string;
     };
 
 export type NodeServerFrame =
   | { t: 'node/registered'; nodeId: string }
   | { t: 'workspace/published'; workspaceAgent: WorkspaceAgent }
-  | { t: 'session/published'; workspaceSession: WorkspaceSessionAgent; sessionKey: string }
+  | {
+      t: 'session/published';
+      workspaceSession: WorkspaceSessionAgent;
+      sessionKey: string;
+    }
   | { t: 'node/error'; message: string }
+  /** The server accepted and durably published this Agent reply. */
+  | { t: 'agent/replyAck'; requestId: string }
+  /** Server could no longer deliver a queued turn before its retention TTL. */
+  | {
+      t: 'agent/deliveryExpired';
+      deliveryId: string;
+      workspaceAgentId: string;
+      workspaceSessionId?: string;
+      eventId?: string;
+      groupId?: string;
+      agentMemberId?: string;
+      displayName?: string;
+      kind: 'group' | 'direct';
+    }
   | {
       t: 'group/deliver';
       deliveryId: string;
@@ -1027,7 +1203,20 @@ export type NodeServerFrame =
       text: string;
     }
   | { t: 'agent/abort'; requestId: string }
-  | { t: 'agent/answer'; requestId: string; deliveryId: string; answers: AskAnswer[] }
+  | {
+      /** 请节点在某个工作目录下新建一个会话（用户按"工作目录"入群时由服务端发起）。
+       *  节点建好后用 session/publish 回带同一个 requestId；失败发 session/createFailed。 */
+      t: 'session/create';
+      requestId: string;
+      workspaceAgentId: string;
+      title: string;
+    }
+  | {
+      t: 'agent/answer';
+      requestId: string;
+      deliveryId: string;
+      answers: AskAnswer[];
+    }
   | { t: 'agent/questionCancel'; requestId: string; deliveryId: string }
   | {
       /** 节点侧同意请求的裁决下发（服务端 → 节点）；节点据此 resolve 挂起的 toolGate。 */
@@ -1039,6 +1228,33 @@ export type NodeServerFrame =
       t: 'agent/delegationRespond';
       requestId: string;
       grant: DelegationGrant | null;
+    }
+  | {
+      t: 'agent/groupActionResult';
+      requestId: string;
+      ok: boolean;
+      referenceId?: string;
+      error?: string;
+    }
+  | {
+      /** attachment/fetch 的应答：一次性下载票据 + 文件元信息，或拒绝原因。
+       *  节点拿 ticket 自己拼 `<serverUrl>/api/files/<fileId>?ticket=…` 去 GET
+       *  —— URL 由节点侧拼装，服务端因此不需要知道自己在反代后的对外地址。 */
+      t: 'attachment/ticket';
+      requestId: string;
+      fileId: string;
+      ticket?: string;
+      name?: string;
+      mime?: string;
+      size?: number;
+      error?: string;
+    }
+  | {
+      /** attachment/uploadRequest 的应答：一次性上传票据，或拒绝原因。 */
+      t: 'attachment/uploadTicket';
+      requestId: string;
+      ticket?: string;
+      error?: string;
     };
 
 export interface GroupSummary {
@@ -1067,8 +1283,18 @@ export interface GroupMessageAttachment {
   size: number;
 }
 
-export type ConversationFileKind = 'workspace-file' | 'user-attachment' | 'group-attachment' | 'agent-file';
-export type ConversationFileActivity = 'referenced' | 'read' | 'created' | 'modified' | 'generated' | 'deleted';
+export type ConversationFileKind =
+  | 'workspace-file'
+  | 'user-attachment'
+  | 'group-attachment'
+  | 'agent-file';
+export type ConversationFileActivity =
+  | 'referenced'
+  | 'read'
+  | 'created'
+  | 'modified'
+  | 'generated'
+  | 'deleted';
 
 /** Safe metadata an Agent Node may publish to a group. Absolute paths and file bytes are forbidden. */
 export interface AgentFileMetadata {
@@ -1079,6 +1305,12 @@ export interface AgentFileMetadata {
   mime?: string;
   activity: ConversationFileActivity;
   purpose?: ConversationFilePurpose;
+  /**
+   * 该交付物已被导出为群附件时的 fileId（群成员据此下载）。
+   * 只有 `purpose === 'deliverable'` 且经本机主人批准导出的文件才有；
+   * 其余文件只有元信息，拿不到内容。
+   */
+  fileId?: string;
   lastSeenAt: number;
 }
 
@@ -1129,9 +1361,20 @@ export interface ConversationArtifactGroup {
   deliveries: ConversationDelivery[];
 }
 
-export type ConversationAssetCategory = 'document' | 'code' | 'image' | 'link' | 'other';
-export type ConversationAssetOrigin = 'user-upload' | 'user-reference' | 'ai-delivery';
-export type ConversationAssetKind = 'workspace-file' | 'user-attachment' | 'web-link';
+export type ConversationAssetCategory =
+  | 'document'
+  | 'code'
+  | 'image'
+  | 'link'
+  | 'other';
+export type ConversationAssetOrigin =
+  | 'user-upload'
+  | 'user-reference'
+  | 'ai-delivery';
+export type ConversationAssetKind =
+  | 'workspace-file'
+  | 'user-attachment'
+  | 'web-link';
 
 /** A durable, session-scoped item explicitly supplied by the user or formally delivered by the Agent. */
 export interface ConversationAsset {
@@ -1182,6 +1425,268 @@ export interface GroupChatMessage {
   kind?: 'system';
 }
 
+export type CollaborationEventVisibility = 'public' | 'owner-private';
+export type CollaborationConversationKind = 'group' | 'direct' | 'agent';
+
+export interface CollaborationConversationRef {
+  kind: CollaborationConversationKind;
+  id: string;
+}
+
+export interface CollaborationArtifactRef {
+  id: string;
+  name: string;
+  mime: string;
+  size: number;
+  sha256?: string;
+  version?: number;
+}
+
+export interface CollaborationEventPayloads {
+  'message.created': {
+    text: string;
+    mentions: string[];
+    attachments?: CollaborationArtifactRef[];
+    senderKind: 'human' | 'agent' | 'system';
+  };
+  'goal.drafted': {
+    title: string;
+    objective: string;
+    deliverables: string[];
+    acceptanceCriteria: string[];
+    scope?: string;
+  };
+  'goal.confirmed': {
+    goalId: string;
+    contractVersion?: number;
+    contractHash?: string;
+  };
+  'task.created': {
+    title: string;
+    objective: string;
+    acceptanceCriteria: string[];
+    parentTaskId?: string;
+    assigneeIds?: string[];
+    /** 目标确认后默认直接运行；保留 planned 只用于显式暂存。 */
+    initialState?: 'planned' | 'running';
+  };
+  'task.updated': {
+    state:
+      | 'planned'
+      | 'running'
+      | 'stopped'
+      | 'blocked'
+      | 'verifying'
+      | 'awaiting_acceptance'
+      | 'completed'
+      | 'cancelled';
+    summary?: string;
+    reason?: string;
+    assigneeIds?: string[];
+  };
+  'decision.recorded': {
+    title: string;
+    conclusion: string;
+    sourceIds: string[];
+  };
+  'activity.recorded': {
+    phase:
+      | 'planning'
+      | 'producing'
+      | 'checking'
+      | 'handoff'
+      | 'waiting'
+      | 'blocked';
+    summary: string;
+    agentMemberId?: string;
+  };
+  'artifact.published': {
+    artifact: CollaborationArtifactRef;
+    summary?: string;
+  };
+  'verification.recorded': {
+    verifier: string;
+    passed: boolean;
+    summary: string;
+    evidenceIds: string[];
+    criterionResults?: Array<{
+      criterion: string;
+      passed: boolean;
+      evidence?: string;
+    }>;
+  };
+  'acceptance.requested': {
+    artifactIds: string[];
+    selfCheck: Array<{ criterion: string; passed: boolean; evidence?: string }>;
+    risks?: string[];
+  };
+  'acceptance.resolved': {
+    decision: 'accepted' | 'rework';
+    reason?: string;
+  };
+  'attention.raised': {
+    reason:
+      | 'business_ambiguity'
+      | 'scope_exceeded'
+      | 'irreversible_action'
+      | 'sensitive_export'
+      | 'execution_failed';
+    summary: string;
+    requestedFromUserId: string;
+  };
+  'attention.resolved': { resolution: string };
+  'approval.requested': {
+    requestId: string;
+    agentMemberId: string;
+    agentDisplayName?: string;
+    reason: string;
+    capability: string;
+    argsPreview?: string;
+  };
+  'approval.status': {
+    requestId: string;
+    agentMemberId: string;
+    agentDisplayName?: string;
+    state:
+      | 'waiting'
+      | 'approved'
+      | 'denied'
+      | 'expired'
+      | 'revoked'
+      | 'stopped';
+    ownerDisplayName?: string;
+  };
+  'membership.changed': {
+    memberId: string;
+    action: 'joined' | 'left' | 'removed';
+    displayName: string;
+    memberKind: 'human' | 'agent';
+  };
+}
+
+export type CollaborationEventType = keyof CollaborationEventPayloads;
+
+interface CollaborationEventBase<T extends CollaborationEventType> {
+  version: 1;
+  id: string;
+  type: T;
+  conversation: CollaborationConversationRef;
+  author: { id: string; name: string; kind: 'human' | 'agent' | 'system' };
+  visibility: CollaborationEventVisibility;
+  createdAt: number;
+  causedBy: string[];
+  taskId?: string;
+  objectId?: string;
+  revision?: number;
+  /** Optional Goal Runtime correlation. Older clients treat a missing version as v1. */
+  contractVersion?: number;
+  contractHash?: string;
+  attemptId?: string;
+  agentMemberId?: string;
+  payload: CollaborationEventPayloads[T];
+}
+
+export type CollaborationEvent = {
+  [T in CollaborationEventType]: CollaborationEventBase<T>;
+}[CollaborationEventType];
+
+/** Client-authored events are always public; owner-private events are server-authored. */
+export type CollaborationEventDraft = {
+  [T in CollaborationEventType]: Omit<
+    CollaborationEventBase<T>,
+    'id' | 'author' | 'createdAt' | 'visibility'
+  > & { clientEventId: string };
+}[CollaborationEventType];
+
+/** Durable local-only batch awaiting a relay acknowledgement. */
+export interface CollaborationOutboxItem {
+  id: string;
+  serverUrl: string;
+  userId: string;
+  events: CollaborationEventDraft[];
+  createdAt: number;
+}
+
+export interface RelayDelivery {
+  deliveryId: string;
+  /** Device-local monotonic sequence. Required on the PostgreSQL relay path. */
+  sequence?: number;
+  /** Identifies which device continuity stream owns sequence. */
+  deviceId?: string;
+  event: CollaborationEvent;
+}
+
+export interface RelayContinuityState {
+  deviceId: string;
+  highestAssignedSequence: number;
+  /** More unacknowledged rows remain after this batch. */
+  hasMore: boolean;
+}
+
+export interface RelayMissingRange {
+  from: number;
+  to: number;
+}
+
+/** Content-free metadata used to repair a settled device-local relay gap. */
+export interface RelayGapCandidate {
+  eventId: string;
+  sequence: number;
+  conversationKind: 'group' | 'direct' | 'agent';
+  conversationId: string;
+  eventType: string;
+  payloadHash: string;
+  attachmentIds: string[];
+  createdAt: number;
+  /** Devices that originally received the same event and may have a local copy. */
+  sourceDeviceIds: string[];
+}
+
+export interface RelayGapRepairRequest {
+  requestId: string;
+  targetDeviceId: string;
+  candidate: RelayGapCandidate;
+}
+
+export interface LocalRelayContinuity {
+  deviceId: string;
+  highestStoredSequence: number;
+  missing: RelayMissingRange[];
+  /** False until the Server reports that all current rows have been pulled. */
+  settled: boolean;
+}
+
+export type GroupUpdateKind =
+  | 'progress'
+  | 'decision'
+  | 'artifact'
+  | 'verification'
+  | 'handoff';
+export interface GroupAgentUpdate {
+  kind: GroupUpdateKind;
+  summary: string;
+  parentTaskId?: string;
+  references?: string[];
+  /** Required for verification updates; omitted means the check did not pass. */
+  passed?: boolean;
+  /** Stable evidence/artifact ids supporting the check. */
+  evidenceIds?: string[];
+}
+
+export interface GroupAgentDelegation {
+  /**
+   * Optional: when omitted the server chooses an eligible Agent in the same
+   * group. An explicit offline target may also be replaced by an eligible
+   * online/busy Agent so a temporary device outage does not stop the parent
+   * task.
+   */
+  targetAgentMemberId?: string;
+  parentTaskId: string;
+  objective: string;
+  acceptanceCriteria?: string[];
+  references?: string[];
+}
+
 /** Local, read-only social snapshot. It never contains auth tokens, absolute paths or Agent private history. */
 export interface OfflineSocialCache {
   version: 1;
@@ -1193,6 +1698,35 @@ export interface OfflineSocialCache {
   groupMessages: Record<string, GroupChatMessage[]>;
 }
 
+/**
+ * A durable, local-only social send waiting for a server acknowledgement.
+ * The server never stores this queue; the stable id is used only for
+ * at-least-once delivery and duplicate suppression.
+ */
+export interface SocialOutboxItem {
+  id: string;
+  serverUrl: string;
+  userId: string;
+  kind: 'group' | 'direct';
+  conversationId: string;
+  text: string;
+  mentions?: string[];
+  attachments?: string[];
+  createdAt: number;
+}
+
+/**
+ * A conversation read marker, owned entirely by Desktop. Under the relay-only server design
+ * the server never persists message bodies, so it has no place to keep a per-user read cursor
+ * either — `unreadCount`/`mentioned` on `GroupSummary`/`ConversationNavigation` are honestly `0`/
+ * `false` from the server. Desktop derives the real values from its own local event replica plus
+ * this cursor (see minimal-desktop's `runtime/unreadProjection.ts` / `runtime/readCursors.ts`).
+ */
+export interface ReadCursor {
+  eventId: string;
+  at: number;
+}
+
 /**
  * 用户级事件：不管用户当前打开哪个群都会推送（连接建立、解析出登录身份后订阅）。
  * 与 group/message（只推给"正打开该群"的连接）互补——未读徽标、被 @ 提醒、
@@ -1233,7 +1767,11 @@ export type UserSocialEvent =
       t: 'conversation/workspace/changed';
       conversation: ConversationRef;
     }
-  | { t: 'agent/directMessage'; workspaceSessionId: string; message: AgentDirectMessage }
+  | {
+      t: 'agent/directMessage';
+      workspaceSessionId: string;
+      message: AgentDirectMessage;
+    }
   | { t: 'agent/directEvent'; workspaceSessionId: string; event: AgentEvent }
   | {
       /** 群 Agent 的完整运行事件，仅推送给该 Agent 所有者。 */
@@ -1250,7 +1788,15 @@ export type UserSocialEvent =
       agentMemberId: string;
       displayName: string;
       toolCallId: string;
-      phase: 'queued' | 'preparing' | 'analyzing' | 'using_tool' | 'drafting' | 'waiting_owner' | 'completed' | 'failed';
+      phase:
+        | 'queued'
+        | 'preparing'
+        | 'analyzing'
+        | 'using_tool'
+        | 'drafting'
+        | 'waiting_owner'
+        | 'completed'
+        | 'failed';
     }
   | {
       t: 'agent/question';
@@ -1258,7 +1804,14 @@ export type UserSocialEvent =
       deliveryId: string;
       questions: AskQuestionSpec[];
       source?: AskSource;
-      context: { kind: 'group'; groupId: string; agentMemberId: string; agentDisplayName: string } | { kind: 'direct'; workspaceSessionId: string };
+      context:
+        | {
+            kind: 'group';
+            groupId: string;
+            agentMemberId: string;
+            agentDisplayName: string;
+          }
+        | { kind: 'direct'; workspaceSessionId: string };
     }
   | {
       t: 'agent/questionStatus';
@@ -1294,79 +1847,437 @@ export type UserSocialEvent =
 
 export type ClientFrame =
   | { t: 'runtime/hello' }
-  | { t: 'local/conversation/start'; requestId: string; target: ConversationTarget; text: string; attachments?: string[]; browserReferences?: BrowserElementReference[]; modelId?: string }
+  | {
+      t: 'goal/get';
+      requestId: string;
+      workspaceId: string;
+      sessionId: string;
+    }
+  | {
+      t: 'goal/control';
+      requestId: string;
+      workspaceId: string;
+      sessionId: string;
+      action:
+        | 'start'
+        | 'pause'
+        | 'resume'
+        | 'update'
+        | 'cancel'
+        | 'accept'
+        | 'rework';
+      actorId: string;
+      objective?: string;
+      deliverables?: string[];
+      acceptanceCriteria?: string[];
+      scope?: string;
+      reason?: string;
+      source?: import('../goal/types.js').GoalSource;
+      acceptorHumanIds?: string[];
+    }
+  | {
+      t: 'local/conversation/start';
+      requestId: string;
+      target: ConversationTarget;
+      text: string;
+      attachments?: string[];
+      browserReferences?: BrowserElementReference[];
+      modelId?: string;
+    }
   | { t: 'plain/list' }
   | { t: 'plain/open'; sessionId: string; requestId?: string }
-  | { t: 'plain/send'; sessionId: string; text: string; attachments?: string[]; browserReferences?: BrowserElementReference[]; requestId?: string; modelId?: string }
+  | {
+      t: 'plain/send';
+      sessionId: string;
+      text: string;
+      attachments?: string[];
+      browserReferences?: BrowserElementReference[];
+      requestId?: string;
+      modelId?: string;
+    }
   | { t: 'plain/clear'; sessionId: string }
   | { t: 'plain/compact'; sessionId: string; requestId?: string }
   | { t: 'plain/rename'; sessionId: string; title: string }
   | { t: 'plain/delete'; sessionId: string }
   | { t: 'resource/files/list'; dir: string; sessionId: string }
-  | { t: 'resource/assets/list'; requestId: string; target: ConversationTarget & { sessionId: string } }
-  | { t: 'resource/assets/pin'; requestId: string; target: ConversationTarget & { sessionId: string }; assetId: string; pinned: boolean }
-  | { t: 'resource/assets/open'; requestId: string; target: ConversationTarget & { sessionId: string }; assetId: string; source?: 'default' | 'original' | 'archive' }
-  | { t: 'resource/assets/reveal'; requestId: string; target: ConversationTarget & { sessionId: string }; assetId: string; source?: 'original' | 'archive' }
-  | { t: 'resource/files/open'; requestId: string; target: ConversationTarget & { sessionId: string }; relativePath: string }
-  | { t: 'resource/files/pin'; dir: string; sessionId: string; relativePath: string; pinned: boolean }
-  | { t: 'resource/files/reveal'; requestId?: string; dir?: string; target?: ConversationTarget & { sessionId: string }; relativePath: string }
+  | {
+      t: 'resource/assets/list';
+      requestId: string;
+      target: ConversationTarget & { sessionId: string };
+    }
+  | {
+      t: 'resource/assets/pin';
+      requestId: string;
+      target: ConversationTarget & { sessionId: string };
+      assetId: string;
+      pinned: boolean;
+    }
+  | {
+      t: 'resource/assets/open';
+      requestId: string;
+      target: ConversationTarget & { sessionId: string };
+      assetId: string;
+      source?: 'default' | 'original' | 'archive';
+    }
+  | {
+      t: 'resource/assets/reveal';
+      requestId: string;
+      target: ConversationTarget & { sessionId: string };
+      assetId: string;
+      source?: 'original' | 'archive';
+    }
+  | {
+      t: 'resource/files/open';
+      requestId: string;
+      target: ConversationTarget & { sessionId: string };
+      relativePath: string;
+    }
+  | {
+      t: 'resource/files/pin';
+      dir: string;
+      sessionId: string;
+      relativePath: string;
+      pinned: boolean;
+    }
+  | {
+      t: 'resource/files/reveal';
+      requestId?: string;
+      dir?: string;
+      target?: ConversationTarget & { sessionId: string };
+      relativePath: string;
+    }
   | { t: 'resource/memories/list'; workspaceId?: string; query?: string }
-  | { t: 'resource/memories/settings/update'; autoRemember: boolean; workspaceId?: string }
-  | { t: 'resource/memories/update'; id: string; scope: 'personal' | 'workspace'; expectedVersion: string; patch: MemoryUpdate; workspaceId?: string }
-  | { t: 'resource/memories/confirm'; id: string; scope: 'personal' | 'workspace'; expectedVersion: string; evidenceQuote: string; sourceSessionId: string; sourceMessageId: string; workspaceId?: string }
-  | { t: 'resource/memories/review'; scope?: 'personal' | 'workspace'; workspaceId?: string }
-  | { t: 'resource/memories/persona/set'; content: string; evidenceQuote: string; sourceSessionId: string; sourceMessageId: string }
+  | {
+      t: 'resource/memories/settings/update';
+      autoRemember: boolean;
+      workspaceId?: string;
+    }
+  | {
+      t: 'resource/memories/update';
+      id: string;
+      scope: 'personal' | 'workspace';
+      expectedVersion: string;
+      patch: MemoryUpdate;
+      workspaceId?: string;
+    }
+  | {
+      t: 'resource/memories/confirm';
+      id: string;
+      scope: 'personal' | 'workspace';
+      expectedVersion: string;
+      evidenceQuote: string;
+      sourceSessionId: string;
+      sourceMessageId: string;
+      workspaceId?: string;
+    }
+  | {
+      t: 'resource/memories/review';
+      scope?: 'personal' | 'workspace';
+      workspaceId?: string;
+    }
+  | {
+      t: 'resource/memories/persona/set';
+      content: string;
+      evidenceQuote: string;
+      sourceSessionId: string;
+      sourceMessageId: string;
+    }
   | { t: 'resource/memories/persona/clear' }
-  | { t: 'resource/memories/conversations/search'; requestId: string; query: string; workspaceId: string; scope?: 'workspace' | 'all'; explicitCrossWorkspace?: boolean; limit?: number }
-  | { t: 'resource/memories/forget'; id: string; scope: 'personal' | 'workspace'; workspaceId?: string }
-  | { t: 'resource/memories/clear'; scope: 'personal' | 'workspace'; workspaceId?: string }
+  | {
+      t: 'resource/memories/conversations/search';
+      requestId: string;
+      query: string;
+      workspaceId: string;
+      scope?: 'workspace' | 'all';
+      explicitCrossWorkspace?: boolean;
+      limit?: number;
+    }
+  | {
+      t: 'resource/memories/forget';
+      id: string;
+      scope: 'personal' | 'workspace';
+      workspaceId?: string;
+    }
+  | {
+      t: 'resource/memories/clear';
+      scope: 'personal' | 'workspace';
+      workspaceId?: string;
+    }
   | { t: 'resource/memories/manage/load'; requestId: string }
-  | { t: 'resource/memories/manage/update'; requestId: string; id: string; scope: 'personal' | 'workspace'; workspaceId?: string; expectedVersion: string; patch: MemoryEditablePatch; includeState?: boolean }
-  | { t: 'resource/memories/manage/confirm'; requestId: string; id: string; scope: 'personal' | 'workspace'; workspaceId?: string; expectedVersion: string; includeState?: boolean }
-  | { t: 'resource/memories/manage/persona/update'; requestId: string; content: string; expectedVersion: string; includeState?: boolean }
-  | { t: 'resource/memories/manage/persona/clear'; requestId: string; expectedVersion: string; includeState?: boolean }
-  | { t: 'resource/memories/manage/settings/update'; requestId: string; patch: Partial<MemorySettings>; expectedVersion: string; includeState?: boolean }
-  | { t: 'resource/memories/manage/forget'; requestId: string; id: string; scope: 'personal' | 'workspace'; workspaceId?: string; expectedVersion: string; includeState?: boolean }
-  | { t: 'resource/memories/manage/clear'; requestId: string; scope: 'personal' | 'workspace'; workspaceId?: string; includeState?: boolean }
-  | { t: 'resource/memories/overview/load'; requestId: string; currentWorkspaceId?: string }
-  | { t: 'resource/memories/topics/list'; requestId: string; scope: 'personal' | 'workspace'; workspaceId?: string; query?: string; category?: MemoryCategory | 'all'; lifecycle?: MemoryLifecycleFilter; cursor?: string; limit?: number }
-  | { t: 'resource/memories/topic/detail'; requestId: string; scope: 'personal' | 'workspace'; workspaceId?: string; topicKey: string }
-  | { t: 'resource/context/status'; requestId: string; target: { kind: 'plain'; sessionId: string } | { kind: 'workspace'; dir: string; sessionId: string } }
-  | { t: 'resource/subagents/worktrees/diff'; requestId: string; dir: string; id: string }
-  | { t: 'resource/subagents/worktrees/apply'; requestId: string; dir: string; id: string }
-  | { t: 'resource/subagents/worktrees/discard'; requestId: string; dir: string; id: string }
-  | { t: 'open'; dir: string; sessionId?: string; requestId?: string }
-  | { t: 'send'; dir: string; text: string; sessionId?: string; attachments?: string[]; browserReferences?: BrowserElementReference[]; requestId?: string; modelId?: string }
-  | { t: 'session/model/set'; target: { kind: 'plain' } | { kind: 'workspace'; dir: string }; sessionId: string; modelId: string | null }
-  | { t: 'input/queue'; item: Omit<QueuedUserInput, 'id' | 'createdAt' | 'restored'> }
-  | { t: 'input/queue/update'; id: string; text?: string; attachmentIds?: string[]; browserReferences?: BrowserElementReference[]; priority?: 'next' | 'interrupt'; activate?: boolean }
-  | { t: 'input/queue/remove'; id: string }
-  | { t: 'input/queue/get' }
-  | { t: 'conversation/run/list' }
   | {
-      t: 'conversation/view/open';
+      t: 'resource/memories/manage/update';
       requestId: string;
-      target:
-        | { kind: 'plain'; sessionId: string }
-        | { kind: 'workspace'; dir: string; sessionId: string };
+      id: string;
+      scope: 'personal' | 'workspace';
+      workspaceId?: string;
+      expectedVersion: string;
+      patch: MemoryEditablePatch;
+      includeState?: boolean;
     }
-  | { t: 'conversation/run/abort'; conversation: LocalConversationRef; runId: string }
-  | { t: 'conversation/run/answer'; conversation: LocalConversationRef; runId: string; requestId: string; answers: AskAnswer[] }
-  | { t: 'conversation/run/cancel-ask'; conversation: LocalConversationRef; runId: string; requestId: string }
-  | { t: 'conversation/result/mark-seen'; conversation: LocalConversationRef; runId?: string }
-  | { t: 'conversation/run/configure'; maxConcurrent: number }
-  | { t: 'answer'; requestId: string; answers: AskAnswer[] }
-  | { t: 'cancelAsk'; requestId: string }
-  | { t: 'abort' }
-  | { t: 'new'; dir: string; sessionId?: string }
-  | { t: 'compact'; dir: string; sessionId?: string; requestId?: string }
-  | { t: 'listDirs' }
-  | { t: 'workspace/index/get' }
-  | { t: 'workspace/recovery/preview' }
+  | {
+      t: 'resource/memories/manage/confirm';
+      requestId: string;
+      id: string;
+      scope: 'personal' | 'workspace';
+      workspaceId?: string;
+      expectedVersion: string;
+      includeState?: boolean;
+    }
+  | {
+      t: 'resource/memories/manage/persona/update';
+      requestId: string;
+      content: string;
+      expectedVersion: string;
+      includeState?: boolean;
+    }
+  | {
+      t: 'resource/memories/manage/persona/clear';
+      requestId: string;
+      expectedVersion: string;
+      includeState?: boolean;
+    }
+  | {
+      t: 'resource/memories/manage/settings/update';
+      requestId: string;
+      patch: Partial<MemorySettings>;
+      expectedVersion: string;
+      includeState?: boolean;
+    }
+  | {
+      t: 'resource/memories/manage/forget';
+      requestId: string;
+      id: string;
+      scope: 'personal' | 'workspace';
+      workspaceId?: string;
+      expectedVersion: string;
+      includeState?: boolean;
+    }
+  | {
+      t: 'resource/memories/manage/clear';
+      requestId: string;
+      scope: 'personal' | 'workspace';
+      workspaceId?: string;
+      includeState?: boolean;
+    }
+  | {
+      t: 'resource/memories/overview/load';
+      requestId: string;
+      currentWorkspaceId?: string;
+    }
+  | {
+      t: 'resource/memories/topics/list';
+      requestId: string;
+      scope: 'personal' | 'workspace';
+      workspaceId?: string;
+      query?: string;
+      category?: MemoryCategory | 'all';
+      lifecycle?: MemoryLifecycleFilter;
+      cursor?: string;
+      limit?: number;
+    }
+  | {
+      t: 'resource/memories/topic/detail';
+      requestId: string;
+      scope: 'personal' | 'workspace';
+      workspaceId?: string;
+      topicKey: string;
+    }
+  | {
+      t: 'resource/context/status';
+      requestId: string;
+      target:
+        | { kind: 'plain'; sessionId: string }
+        | { kind: 'workspace'; dir: string; sessionId: string };
+    }
+  | {
+      t: 'resource/subagents/worktrees/diff';
+      requestId: string;
+      dir: string;
+      id: string;
+    }
+  | {
+      t: 'resource/subagents/worktrees/apply';
+      requestId: string;
+      dir: string;
+      id: string;
+    }
+  | {
+      t: 'resource/subagents/worktrees/discard';
+      requestId: string;
+      dir: string;
+      id: string;
+    }
+  | { t: 'open'; dir: string; sessionId?: string; requestId?: string }
+  | {
+      t: 'send';
+      dir: string;
+      text: string;
+      sessionId?: string;
+      attachments?: string[];
+      browserReferences?: BrowserElementReference[];
+      requestId?: string;
+      modelId?: string;
+    }
+  | {
+      t: 'session/model/set';
+      target: { kind: 'plain' } | { kind: 'workspace'; dir: string };
+      sessionId: string;
+      modelId: string | null;
+    }
+  | {
+      t: 'session/tools/set';
+      target: { kind: 'plain' } | { kind: 'workspace'; dir: string };
+      sessionId: string;
+      categories: string[];
+    }
+  | {
+      t: 'input/queue';
+      item: Omit<QueuedUserInput, 'id' | 'createdAt' | 'restored'>;
+    }
+  | {
+      t: 'input/queue/update';
+      id: string;
+      text?: string;
+      attachmentIds?: string[];
+      browserReferences?: BrowserElementReference[];
+      priority?: 'next' | 'interrupt';
+      activate?: boolean;
+    }
+  | { t: 'input/queue/remove'; id: string }
+  | { t: 'input/queue/get' }
+  | { t: 'conversation/run/list' }
+  | {
+      t: 'conversation/view/open';
+      requestId: string;
+      target:
+        | { kind: 'plain'; sessionId: string }
+        | { kind: 'workspace'; dir: string; sessionId: string };
+    }
+  | {
+      t: 'conversation/run/abort';
+      conversation: LocalConversationRef;
+      runId: string;
+    }
+  /** Retry the last persisted user turn in the same Session after a failed/interrupted run. */
+  | {
+      t: 'conversation/run/retry';
+      conversation: LocalConversationRef;
+      runId: string;
+    }
+  | {
+      t: 'conversation/run/answer';
+      conversation: LocalConversationRef;
+      runId: string;
+      requestId: string;
+      answers: AskAnswer[];
+    }
+  | {
+      t: 'conversation/run/cancel-ask';
+      conversation: LocalConversationRef;
+      runId: string;
+      requestId: string;
+    }
+  | {
+      t: 'conversation/result/mark-seen';
+      conversation: LocalConversationRef;
+      runId?: string;
+    }
+  | { t: 'conversation/run/configure'; maxConcurrent: number }
+  | { t: 'answer'; requestId: string; answers: AskAnswer[] }
+  | { t: 'cancelAsk'; requestId: string }
+  | { t: 'abort' }
+  | { t: 'new'; dir: string; sessionId?: string }
+  | { t: 'compact'; dir: string; sessionId?: string; requestId?: string }
+  | { t: 'listDirs' }
+  /** 探测局域网内的 minimal-server（UDP 只能在本机 Runtime 里发，浏览器上下文发不了）。 */
+  | { t: 'server/discover' }
+  | { t: 'workspace/index/get' }
+  | { t: 'workspace/recovery/preview' }
   | { t: 'workspace/recovery/apply' }
   | { t: 'social/cache/get'; serverUrl: string }
   | { t: 'social/cache/save'; cache: OfflineSocialCache }
   | { t: 'social/cache/clear'; serverUrl: string; userId?: string }
+  | {
+      t: 'social/outbox/get';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+    }
+  | {
+      t: 'social/outbox/save';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+      items: SocialOutboxItem[];
+    }
+  | {
+      t: 'social/outbox/clear';
+      requestId: string;
+      serverUrl: string;
+      userId?: string;
+    }
+  | {
+      t: 'collaboration/outbox/get';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+    }
+  | {
+      t: 'collaboration/outbox/save';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+      items: CollaborationOutboxItem[];
+    }
+  | {
+      t: 'collaboration/outbox/clear';
+      requestId: string;
+      serverUrl: string;
+      userId?: string;
+    }
+  | {
+      t: 'collaboration/read/get';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+    }
+  /**
+   * Fire-and-forget: Desktop advances its own read cursor (conversation opened, or a real-time
+   * bump arrived while it was open). No reply — losing one on a crash just means one extra
+   * unread badge next launch, never a false "read" state.
+   */
+  | {
+      t: 'collaboration/read/mark';
+      serverUrl: string;
+      userId: string;
+      conversationId: string;
+      cursor: ReadCursor;
+    }
+  | { t: 'collaboration/device/get'; requestId: string }
+  | {
+      /** Local Runtime only: append before the social connection may ACK. */
+      t: 'collaboration/events/append';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+      deliveries: RelayDelivery[];
+      continuity?: RelayContinuityState;
+    }
+  | {
+      /** Local Runtime only: rebuild UI projections from the durable event log. */
+      t: 'collaboration/events/load';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+      conversation?: CollaborationConversationRef;
+    }
+  | {
+      t: 'collaboration/events/find';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+      eventIds: string[];
+    }
   | { t: 'workspace/register'; requestId: string; path: string }
   | { t: 'browseDir'; path?: string }
   | { t: 'file/browse'; requestId: string; path?: string }
@@ -1380,19 +2291,47 @@ export type ClientFrame =
   | { t: 'copySession'; dir: string; sessionId: string; title?: string }
   | { t: 'deleteSession'; dir: string; sessionId: string }
   | { t: 'config/get' }
-  | { t: 'config/update'; requestId: string; revision?: number; patch: WebchatConfigPatch }
-  | { t: 'config/autosave'; requestId: string; revision?: number; section: ConfigAutosaveSection; patch: WebchatConfigPatch }
+  | {
+      t: 'config/update';
+      requestId: string;
+      revision?: number;
+      patch: WebchatConfigPatch;
+    }
+  | {
+      t: 'config/autosave';
+      requestId: string;
+      revision?: number;
+      section: ConfigAutosaveSection;
+      patch: WebchatConfigPatch;
+    }
   | { t: 'config/tool/test'; tool: ToolConfigName }
   /**
    * 模型列表条目的连通性测试——跟 config/tool/test 同一先例的延伸（测试从来不是配置变更，
    * 一直走独立于 patch 的姊妹帧），只是模型是开放式按 id 索引的动态集合，ToolConfigName
    * 的封闭枚举表达不了。modelId 测已保存条目；draft 测弹窗里还没提交的正在填写的值。
    */
-  | { t: 'config/model/test'; requestId: string; modelId?: string; draft?: { apiFormat: ApiFormat; baseURL: string; apiKey?: string; model: string } }
+  | {
+      t: 'config/model/test';
+      requestId: string;
+      modelId?: string;
+      draft?: {
+        apiFormat: ApiFormat;
+        baseURL: string;
+        apiKey?: string;
+        model: string;
+      };
+    }
   | { t: 'getSkills'; dir?: string }
   | { t: 'resource/crons/list'; filter?: CronListFilter }
   | { t: 'resource/crons/show'; id: string }
-  | { t: 'resource/crons/draft'; requestId: string; text: string; cwd?: string; sessionId?: string; model?: string }
+  | {
+      t: 'resource/crons/draft';
+      requestId: string;
+      text: string;
+      cwd?: string;
+      sessionId?: string;
+      model?: string;
+    }
   | { t: 'resource/crons/create'; requestId: string; task: CronTaskDraft }
   | { t: 'resource/crons/update'; requestId: string; patch: CronTaskPatch }
   | { t: 'resource/crons/delete'; requestId: string; id: string }
@@ -1412,39 +2351,149 @@ export type ClientFrame =
   | { t: 'conversation/navigation/get' }
   | { t: 'conversation/open'; conversationId: string }
   | { t: 'conversation/start'; friendUserId: string }
-  | { t: 'conversation/send'; conversationId: string; text: string; attachments?: string[] }
-  | { t: 'conversation/history'; conversationId: string; beforeId?: string; limit?: number }
+  | {
+      t: 'conversation/send';
+      conversationId: string;
+      text: string;
+      attachments?: string[];
+      requestId?: string;
+    }
+  | {
+      t: 'conversation/history';
+      conversationId: string;
+      beforeId?: string;
+      limit?: number;
+    }
   | { t: 'agent/direct/open'; workspaceSessionId: string }
   | { t: 'agent/direct/send'; workspaceSessionId: string; text: string }
   | { t: 'agent/direct/abort'; workspaceSessionId: string }
-  | { t: 'conversation/actions/suggest'; kind: 'group' | 'direct' | 'agent'; id: string }
+  | {
+      t: 'conversation/actions/suggest';
+      kind: 'group' | 'direct' | 'agent';
+      id: string;
+    }
   | { t: 'node/pairing/create'; name: string }
   | { t: 'node/list' }
   | { t: 'workspace/list' }
   | { t: 'conversation/workspace/open'; conversation: ConversationRef }
-  | { t: 'conversation/task/save'; conversation: ConversationRef; task: Omit<WorkItemDraft, 'projectId'> }
-  | { t: 'conversation/task/delete'; conversation: ConversationRef; taskId: string }
-  | { t: 'conversation/decision/save'; conversation: ConversationRef; decision: Omit<ProjectDecision, 'id' | 'projectId' | 'createdAt' | 'updatedAt' | 'createdBy'> & { id?: string } }
-  | { t: 'conversation/handoff/save'; conversation: ConversationRef; handoff: Omit<ProjectHandoff, 'id' | 'projectId' | 'createdAt' | 'updatedAt'> & { id?: string } }
-  | { t: 'conversation/handoff/status'; conversation: ConversationRef; handoffId: string; status: HandoffStatus }
-  | { t: 'conversation/repository/add'; conversation: ConversationRef; provider: ProjectProvider; remoteUrl: string; defaultBranch: string; name?: string }
-  | { t: 'conversation/repository/remove'; conversation: ConversationRef; repositoryId: string }
-  | { t: 'conversation/artifact/save'; conversation: ConversationRef; artifact: Omit<ProjectArtifact, 'id' | 'projectId' | 'createdAt' | 'createdBy'> & { id?: string } }
-  | { t: 'conversation/artifact/delete'; conversation: ConversationRef; artifactId: string }
+  | {
+      t: 'conversation/task/save';
+      conversation: ConversationRef;
+      task: Omit<WorkItemDraft, 'projectId'>;
+    }
+  | {
+      t: 'conversation/task/delete';
+      conversation: ConversationRef;
+      taskId: string;
+    }
+  | {
+      t: 'conversation/decision/save';
+      conversation: ConversationRef;
+      decision: Omit<
+        ProjectDecision,
+        'id' | 'projectId' | 'createdAt' | 'updatedAt' | 'createdBy'
+      > & { id?: string };
+    }
+  | {
+      t: 'conversation/handoff/save';
+      conversation: ConversationRef;
+      handoff: Omit<
+        ProjectHandoff,
+        'id' | 'projectId' | 'createdAt' | 'updatedAt'
+      > & { id?: string };
+    }
+  | {
+      t: 'conversation/handoff/status';
+      conversation: ConversationRef;
+      handoffId: string;
+      status: HandoffStatus;
+    }
+  | {
+      t: 'conversation/repository/add';
+      conversation: ConversationRef;
+      provider: ProjectProvider;
+      remoteUrl: string;
+      defaultBranch: string;
+      name?: string;
+    }
+  | {
+      t: 'conversation/repository/remove';
+      conversation: ConversationRef;
+      repositoryId: string;
+    }
+  | {
+      t: 'conversation/artifact/save';
+      conversation: ConversationRef;
+      artifact: Omit<
+        ProjectArtifact,
+        'id' | 'projectId' | 'createdAt' | 'createdBy'
+      > & { id?: string };
+    }
+  | {
+      t: 'conversation/artifact/delete';
+      conversation: ConversationRef;
+      artifactId: string;
+    }
   | { t: 'group/list' }
-  | { t: 'group/create'; name: string; memberIds?: string[]; workspaceSessionIds?: string[] }
+  | {
+      t: 'group/create';
+      name: string;
+      memberIds: string[];
+      workspaceSessionIds?: string[];
+    }
   | { t: 'group/rename'; groupId: string; name: string }
   | { t: 'group/setAnnouncement'; groupId: string; announcement: string }
   | { t: 'group/transferOwner'; groupId: string; newOwnerUserId: string }
   | { t: 'group/delete'; groupId: string }
   | { t: 'group/addHuman'; groupId: string; friendUserId: string }
-  | { t: 'group/addAgent'; groupId: string; workspaceSessionId: string }
-  | { t: 'group/setMemberPolicy'; groupId: string; memberId: string; policy: 'mention' | 'proactive' | 'all' | 'disabled' }
+  /**
+   * 把一个已有 Session Agent 拉进群。群聊和工作目录私聊共用同一 Session，
+   * 只替换当前回合的会话模式提示词与可用工具集。
+   * `workspaceAgentId` 仅保留给旧客户端兼容，不应再由新 UI 发出。
+   */
+  | {
+      t: 'group/addAgent';
+      groupId: string;
+      workspaceSessionId?: string;
+      workspaceAgentId?: string;
+    }
+  | {
+      t: 'group/setMemberPolicy';
+      groupId: string;
+      memberId: string;
+      policy: 'mention' | 'proactive' | 'all' | 'disabled';
+    }
   | { t: 'group/removeMember'; groupId: string; memberId: string }
+  /** 叫停某个 agent 成员当前的活（只停这一次，不改它以后是否响应）。 */
+  | { t: 'group/abort'; groupId: string; memberId: string }
   | { t: 'group/open'; groupId: string }
-  | { t: 'group/send'; groupId: string; text: string; mentions?: string[]; attachments?: string[] }
+  | {
+      t: 'group/send';
+      groupId: string;
+      text: string;
+      mentions?: string[];
+      attachments?: string[];
+      requestId?: string;
+    }
   | { t: 'group/history'; groupId: string; beforeId?: string; limit?: number }
   | { t: 'group/read'; groupId: string; messageId: string }
+  | { t: 'relay/device/register'; installationId: string; label?: string }
+  | { t: 'relay/pull'; limit?: number }
+  | { t: 'relay/ack'; eventId: string }
+  | { t: 'relay/gap/request'; ranges: RelayMissingRange[] }
+  | {
+      t: 'relay/repair';
+      requestId: string;
+      targetDeviceId: string;
+      event: CollaborationEvent;
+    }
+  | { t: 'relay/publish'; requestId: string; event: CollaborationEventDraft }
+  /** Publish a small set of related facts atomically (goal/confirmation/task). */
+  | {
+      t: 'relay/publishBatch';
+      requestId: string;
+      events: CollaborationEventDraft[];
+    }
   | {
       /** owner 对跨机指令同意请求的裁决；remember 记住信任（免以后再问）。 */
       t: 'group/consentRespond';
@@ -1455,9 +2504,19 @@ export type ClientFrame =
       readScopes?: string[];
       capabilities?: string[];
     }
+  | {
+      /** Agent 主人主动撤销一项已批准的授权，并停止仍在运行的对应投递。 */
+      t: 'group/consentRevoke';
+      requestId: string;
+    }
   | { t: 'agent/answer'; requestId: string; answers: AskAnswer[] }
   | { t: 'agent/questionCancel'; requestId: string }
-  | { t: 'human-intervention/get'; requestId?: string; conversationKey?: string; runId?: string }
+  | {
+      t: 'human-intervention/get';
+      requestId?: string;
+      conversationKey?: string;
+      runId?: string;
+    }
   | {
       t: 'human-intervention/resume';
       requestId?: string;
@@ -1477,11 +2536,25 @@ export type ClientFrame =
       runId: string;
     }
   // ---- Browser automation frames (product-grade) ----
-  | { t: 'browser/context/set'; conversationKey: string; runId?: string; requestId?: string }
+  | {
+      t: 'browser/context/set';
+      conversationKey: string;
+      runId?: string;
+      requestId?: string;
+    }
   // Mode control
-  | { t: 'browser/start'; requestId?: string; headless?: boolean; viewport?: { width: number; height: number } }
+  | {
+      t: 'browser/start';
+      requestId?: string;
+      headless?: boolean;
+      viewport?: { width: number; height: number };
+    }
   | { t: 'browser/stop'; requestId?: string }
-  | { t: 'browser/mode'; mode: 'browse' | 'assist' | 'auto'; requestId?: string }
+  | {
+      t: 'browser/mode';
+      mode: 'browse' | 'assist' | 'auto';
+      requestId?: string;
+    }
   | { t: 'browser/control/get'; requestId?: string }
   | { t: 'browser/control/takeover'; requestId?: string }
   | { t: 'browser/control/resume'; requestId?: string; resumeToken?: string }
@@ -1498,33 +2571,110 @@ export type ClientFrame =
   | { t: 'browser/reload'; requestId?: string }
   // AI interaction (Agent actions)
   | { t: 'browser/snapshot'; requestId?: string; interactive?: boolean }
-  | { t: 'browser/screenshot'; requestId?: string; annotate?: boolean; fullPage?: boolean; path?: string }
+  | {
+      t: 'browser/screenshot';
+      requestId?: string;
+      annotate?: boolean;
+      fullPage?: boolean;
+      path?: string;
+    }
   | { t: 'browser/eval'; requestId?: string; js: string }
-  | { t: 'browser/click'; requestId?: string; selector: string; byRef?: boolean }
+  | {
+      t: 'browser/click';
+      requestId?: string;
+      selector: string;
+      byRef?: boolean;
+    }
   | { t: 'browser/fill'; requestId?: string; selector: string; value: string }
   | { t: 'browser/type'; requestId?: string; selector: string; value: string }
   | { t: 'browser/hover'; requestId?: string; selector: string }
-  | { t: 'browser/scroll'; requestId?: string; x?: number; y?: number; selector?: string; direction?: 'up' | 'down' | 'top' | 'bottom' }
-  | { t: 'browser/select'; requestId?: string; selector: string; value: string | string[] }
+  | {
+      t: 'browser/scroll';
+      requestId?: string;
+      x?: number;
+      y?: number;
+      selector?: string;
+      direction?: 'up' | 'down' | 'top' | 'bottom';
+    }
+  | {
+      t: 'browser/select';
+      requestId?: string;
+      selector: string;
+      value: string | string[];
+    }
   | { t: 'browser/press'; requestId?: string; key: string; selector?: string }
-  | { t: 'browser/wait'; requestId?: string; ms?: number; selector?: string; text?: string }
-  | { t: 'browser/upload'; requestId?: string; selector: string; files: string[] }
-  | { t: 'browser/drag'; requestId?: string; fromSelector: string; toSelector: string }
+  | {
+      t: 'browser/wait';
+      requestId?: string;
+      ms?: number;
+      selector?: string;
+      text?: string;
+    }
+  | {
+      t: 'browser/upload';
+      requestId?: string;
+      selector: string;
+      files: string[];
+    }
+  | {
+      t: 'browser/drag';
+      requestId?: string;
+      fromSelector: string;
+      toSelector: string;
+    }
   // User input (browse mode - direct interaction via canvas)
-  | { t: 'browser/user/input'; eventType: 'mouseMoved' | 'mousePressed' | 'mouseReleased' | 'mouseWheel' | 'keyDown' | 'keyUp' | 'char'; x?: number; y?: number; button?: string; clickCount?: number; deltaX?: number; deltaY?: number; key?: string; code?: string; text?: string; modifiers?: number; windowsVirtualKeyCode?: number }
+  | {
+      t: 'browser/user/input';
+      eventType:
+        | 'mouseMoved'
+        | 'mousePressed'
+        | 'mouseReleased'
+        | 'mouseWheel'
+        | 'keyDown'
+        | 'keyUp'
+        | 'char';
+      x?: number;
+      y?: number;
+      button?: string;
+      clickCount?: number;
+      deltaX?: number;
+      deltaY?: number;
+      key?: string;
+      code?: string;
+      text?: string;
+      modifiers?: number;
+      windowsVirtualKeyCode?: number;
+    }
   // JS dialog handling (alert/confirm/prompt)
   | { t: 'browser/dialog/accept'; requestId?: string; text?: string }
   | { t: 'browser/dialog/dismiss'; requestId?: string }
   // Agent pointer visualization (sent FROM server to UI to show where AI is acting)
   // Element marking (UI markers / pick mode)
   | { t: 'browser/pick'; requestId?: string; x: number; y: number }
-  | { t: 'browser/mark/element'; requestId?: string; selector: string; label?: string; color?: string }
+  | {
+      t: 'browser/mark/element';
+      requestId?: string;
+      selector: string;
+      label?: string;
+      color?: string;
+    }
   | { t: 'browser/mark/clear'; requestId?: string }
   | { t: 'browser/mark/mode'; enabled: boolean; requestId?: string }
   // Viewport & device
   | { t: 'browser/viewport'; width: number; height: number; requestId?: string }
-  | { t: 'browser/device'; preset?: string; width?: number; height?: number; requestId?: string }
-  | { t: 'browser/media'; scheme?: 'light' | 'dark' | 'no-preference'; offline?: boolean; requestId?: string }
+  | {
+      t: 'browser/device';
+      preset?: string;
+      width?: number;
+      height?: number;
+      requestId?: string;
+    }
+  | {
+      t: 'browser/media';
+      scheme?: 'light' | 'dark' | 'no-preference';
+      offline?: boolean;
+      requestId?: string;
+    }
   // Recording
   | { t: 'browser/record/start'; requestId?: string; path?: string }
   | { t: 'browser/record/stop'; requestId?: string }
@@ -1533,7 +2683,16 @@ export type ClientFrame =
   | { t: 'browser/pdf'; requestId?: string; path?: string }
   // Cookies & auth
   | { t: 'browser/cookies/get'; requestId?: string }
-  | { t: 'browser/cookies/set'; requestId?: string; cookies: Array<{ name: string; value: string; domain?: string; path?: string }> }
+  | {
+      t: 'browser/cookies/set';
+      requestId?: string;
+      cookies: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+        path?: string;
+      }>;
+    }
   | { t: 'browser/cookies/clear'; requestId?: string }
   | { t: 'browser/profile/clear'; requestId?: string }
   // Read-only developer diagnostics. Full CDP access remains a separate, disabled-by-default setting.
@@ -1545,21 +2704,70 @@ export type ClientFrame =
   | { t: 'browser/debug/trace/start'; requestId?: string }
   | { t: 'browser/debug/trace/stop'; requestId?: string; path?: string }
   // Agent pointer visualization control (sent to frontend to show agent cursor)
-  | { t: 'browser/agent/pointer'; x: number; y: number; visible: boolean; action?: 'move' | 'click' | 'type' | 'scroll' | 'idle' | 'hover'; elementRef?: string }
+  | {
+      t: 'browser/agent/pointer';
+      x: number;
+      y: number;
+      visible: boolean;
+      action?: 'move' | 'click' | 'type' | 'scroll' | 'idle' | 'hover';
+      elementRef?: string;
+    }
   // Native desktop Computer Use is controlled by the trusted host.
-  | { t: 'computer/status'; requestId?: string; conversationKey?: string; runId?: string }
+  | {
+      t: 'computer/status';
+      requestId?: string;
+      conversationKey?: string;
+      runId?: string;
+    }
   | { t: 'computer/permissions'; requestId?: string }
-  | { t: 'computer/observe'; requestId?: string; conversationKey: string; runId: string }
-  | { t: 'computer/control/takeover'; requestId?: string; conversationKey: string; runId: string }
-  | { t: 'computer/control/resume'; requestId?: string; conversationKey: string; runId: string; interventionId?: string; resumeToken?: string; ownerId?: string }
-  | { t: 'computer/control/stop'; requestId?: string; conversationKey: string; runId: string; interventionId?: string; resumeToken?: string; ownerId?: string }
+  | {
+      t: 'computer/observe';
+      requestId?: string;
+      conversationKey: string;
+      runId: string;
+    }
+  | {
+      t: 'computer/control/takeover';
+      requestId?: string;
+      conversationKey: string;
+      runId: string;
+    }
+  | {
+      t: 'computer/control/resume';
+      requestId?: string;
+      conversationKey: string;
+      runId: string;
+      interventionId?: string;
+      resumeToken?: string;
+      ownerId?: string;
+    }
+  | {
+      t: 'computer/control/stop';
+      requestId?: string;
+      conversationKey: string;
+      runId: string;
+      interventionId?: string;
+      resumeToken?: string;
+      ownerId?: string;
+    }
   | { t: 'computer/control/emergency-stop-all'; requestId?: string }
   // 终端不走 WS：改由 Tauri 原生真 PTY（minimal-desktop src-tauri/src/pty.rs）承载。
   // ---- 工作台任意路径文件预览（工作目录内） ----
   | { t: 'file/preview/open'; requestId: string; path: string };
 
 export type ServerFrame =
-  | { t: 'runtime/hello'; protocolVersion: number; runtimeVersion: string; capabilities: string[] }
+  | {
+      t: 'runtime/hello';
+      protocolVersion: number;
+      runtimeVersion: string;
+      capabilities: string[];
+    }
+  | {
+      t: 'goal/snapshot';
+      requestId: string;
+      goal?: import('../goal/types.js').Goal;
+      error?: string;
+    }
   | {
       t: 'human-intervention/started' | 'human-intervention/changed';
       intervention: PendingHumanInterventionSummary & {
@@ -1589,103 +2797,511 @@ export type ServerFrame =
       runSnapshot?: ConversationRunSnapshot;
       contextUsage?: Extract<LoopEvent, { type: 'context_usage' }>;
     }
-  | { t: 'conversation/delivery/changed'; conversationKey: string; delivery: ConversationDelivery }
-  | { t: 'conversation/assets/changed'; conversationKey: string; assets: ConversationAsset[] }
-  | { t: 'resource/files/list'; dir: string; sessionId: string; files: ConversationFileRef[] }
-  | { t: 'resource/assets/list'; requestId: string; conversationKey: string; assets?: ConversationAsset[]; error?: string }
-  | { t: 'resource/assets/pinned'; requestId: string; ok: boolean; error?: string }
-  | { t: 'resource/assets/opened'; requestId: string; ref?: ConversationFileRef; error?: string }
-  | { t: 'resource/assets/revealed'; requestId: string; ok: boolean; error?: string }
-  | { t: 'resource/files/opened'; requestId: string; ref?: ConversationFileRef; error?: string }
-  | { t: 'resource/files/revealed'; requestId: string; ok: boolean; error?: string }
-  | { t: 'resource/memories'; records: MemoryRecord[]; settings: MemorySettings; workspaceId?: string; reviewRecords?: MemoryRecord[]; persona?: PersonaDocument | null }
-  | { t: 'resource/memories/conversations'; requestId: string; results: ConversationSearchResult[]; error?: string }
-  | { t: 'resource/memories/manage/state'; requestId: string; state: MemoryManagementState }
-  | { t: 'resource/memories/manage/result'; requestId: string; action: MemoryManagementAction; ok: boolean; state?: MemoryManagementState; error?: string; conflict?: boolean }
-  | { t: 'resource/memories/overview'; requestId: string; overview?: MemoryCenterOverview; error?: string }
-  | { t: 'resource/memories/topics'; requestId: string; page?: MemoryTopicPage; error?: string; errorCode?: 'stale_cursor' }
-  | { t: 'resource/memories/topic'; requestId: string; detail?: MemoryTopicDetail; error?: string }
-  | { t: 'resource/context/status'; requestId: string; status?: ContextStatusView; error?: string }
-  | { t: 'resource/subagents/worktree/result'; requestId: string; action: 'diff' | 'apply' | 'discard'; ok: boolean; id: string; diff?: string; changedFiles?: string[]; error?: string }
-  | { t: 'ready'; dirs: RecentDir[]; workspaceIndex?: WorkspaceTreeEntry[]; defaultDir?: string; localAttachmentToken?: string }
+  | {
+      t: 'conversation/delivery/changed';
+      conversationKey: string;
+      delivery: ConversationDelivery;
+    }
+  | {
+      t: 'conversation/assets/changed';
+      conversationKey: string;
+      assets: ConversationAsset[];
+    }
+  | {
+      t: 'resource/files/list';
+      dir: string;
+      sessionId: string;
+      files: ConversationFileRef[];
+    }
+  | {
+      t: 'resource/assets/list';
+      requestId: string;
+      conversationKey: string;
+      assets?: ConversationAsset[];
+      error?: string;
+    }
+  | {
+      t: 'resource/assets/pinned';
+      requestId: string;
+      ok: boolean;
+      error?: string;
+    }
+  | {
+      t: 'resource/assets/opened';
+      requestId: string;
+      ref?: ConversationFileRef;
+      error?: string;
+    }
+  | {
+      t: 'resource/assets/revealed';
+      requestId: string;
+      ok: boolean;
+      error?: string;
+    }
+  | {
+      t: 'resource/files/opened';
+      requestId: string;
+      ref?: ConversationFileRef;
+      error?: string;
+    }
+  | {
+      t: 'resource/files/revealed';
+      requestId: string;
+      ok: boolean;
+      error?: string;
+    }
+  | {
+      t: 'resource/memories';
+      records: MemoryRecord[];
+      settings: MemorySettings;
+      workspaceId?: string;
+      reviewRecords?: MemoryRecord[];
+      persona?: PersonaDocument | null;
+    }
+  | {
+      t: 'resource/memories/conversations';
+      requestId: string;
+      results: ConversationSearchResult[];
+      error?: string;
+    }
+  | {
+      t: 'resource/memories/manage/state';
+      requestId: string;
+      state: MemoryManagementState;
+    }
+  | {
+      t: 'resource/memories/manage/result';
+      requestId: string;
+      action: MemoryManagementAction;
+      ok: boolean;
+      state?: MemoryManagementState;
+      error?: string;
+      conflict?: boolean;
+    }
+  | {
+      t: 'resource/memories/overview';
+      requestId: string;
+      overview?: MemoryCenterOverview;
+      error?: string;
+    }
+  | {
+      t: 'resource/memories/topics';
+      requestId: string;
+      page?: MemoryTopicPage;
+      error?: string;
+      errorCode?: 'stale_cursor';
+    }
+  | {
+      t: 'resource/memories/topic';
+      requestId: string;
+      detail?: MemoryTopicDetail;
+      error?: string;
+    }
+  | {
+      t: 'resource/context/status';
+      requestId: string;
+      status?: ContextStatusView;
+      error?: string;
+    }
+  | {
+      t: 'resource/subagents/worktree/result';
+      requestId: string;
+      action: 'diff' | 'apply' | 'discard';
+      ok: boolean;
+      id: string;
+      diff?: string;
+      changedFiles?: string[];
+      error?: string;
+    }
+  | {
+      t: 'ready';
+      dirs: RecentDir[];
+      workspaceIndex?: WorkspaceTreeEntry[];
+      defaultDir?: string;
+      localAttachmentToken?: string;
+    }
   | { t: 'workspace/index'; workspaces: WorkspaceTreeEntry[] }
   | { t: 'workspace/index/changed'; workspaces: WorkspaceTreeEntry[] }
-  | { t: 'workspace/recovery'; applied: boolean; workspaces: number; sessions: number; recoverable: Array<{ fileName: string; reason: string; suggestedPath?: string }> }
+  | {
+      t: 'workspace/recovery';
+      applied: boolean;
+      workspaces: number;
+      sessions: number;
+      recoverable: Array<{
+        fileName: string;
+        reason: string;
+        suggestedPath?: string;
+      }>;
+    }
   | { t: 'social/cache'; serverUrl: string; cache: OfflineSocialCache | null }
+  | {
+      t: 'social/outbox';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+      items: SocialOutboxItem[];
+    }
+  | {
+      t: 'collaboration/outbox';
+      requestId: string;
+      serverUrl: string;
+      userId: string;
+      items: CollaborationOutboxItem[];
+    }
+  | {
+      t: 'collaboration/read';
+      requestId: string;
+      cursors: Record<string, ReadCursor>;
+    }
+  | {
+      t: 'collaboration/device';
+      requestId: string;
+      installationId: string;
+      label: string;
+    }
+  | {
+      t: 'collaboration/events/persisted';
+      requestId: string;
+      eventIds: string[];
+      continuity?: LocalRelayContinuity;
+    }
+  | {
+      t: 'collaboration/events';
+      requestId: string;
+      events: CollaborationEvent[];
+    }
+  | {
+      t: 'collaboration/events/found';
+      requestId: string;
+      events: CollaborationEvent[];
+    }
   | { t: 'dirs'; dirs: RecentDir[] }
-  | { t: 'workspace/registered'; requestId: string; dir?: RecentDir; dirs?: RecentDir[]; error?: string }
+  /** 局域网发现结果；空数组 = 没找到（网络受限时也走这条，不是错误）。 */
+  | {
+      t: 'server/discovered';
+      servers: Array<{
+        url: string;
+        version: string;
+        protocolVersion: number;
+        /** 同一台服务器的其它网卡地址；首选地址不通时可切换，不必重搜。 */
+        alternativeUrls: string[];
+      }>;
+    }
+  | {
+      t: 'workspace/registered';
+      requestId: string;
+      dir?: RecentDir;
+      dirs?: RecentDir[];
+      error?: string;
+    }
   | { t: 'dirListing'; listing: DirListing }
   | { t: 'archives'; dir: string; entries: ArchiveEntry[] }
   | { t: 'sessions'; dir: string; sessions: SessionSummary[] }
   | { t: 'history'; dir: string; sessionId?: string; messages: Message[] }
-  | { t: 'event'; event: AgentEvent; dir?: string; sessionId: string; runId: string; sequence?: number }
+  | {
+      t: 'event';
+      event: AgentEvent;
+      dir?: string;
+      sessionId: string;
+      runId: string;
+      sequence?: number;
+    }
   | { t: 'conversation/run/snapshot'; snapshot: ConversationRunSnapshot }
-  | { t: 'conversation/run/changed'; snapshots: ConversationRunSnapshot[]; maxConcurrent: number }
+  | {
+      t: 'conversation/run/changed';
+      snapshots: ConversationRunSnapshot[];
+      maxConcurrent: number;
+    }
   | { t: 'input/queue/changed'; items: QueuedUserInput[] }
   | { t: 'input/queue/started'; item: QueuedUserInput }
   | { t: 'config'; config: WebchatConfig | null }
-  | { t: 'config/updated'; requestId: string; revision: number; config: WebchatConfig }
-  | { t: 'config/autosaved'; requestId: string; revision: number; state: 'applied' | 'draft'; config: WebchatConfig; draftFields?: string[] }
-  | { t: 'config/update-failed'; requestId: string; message: string; fieldErrors?: Record<string, string>; currentRevision?: number }
-  | { t: 'config/tool/tested'; tool: ToolConfigName; ok: boolean; message: string }
-  | { t: 'config/model/tested'; requestId: string; ok: boolean; message: string }
+  | {
+      t: 'config/updated';
+      requestId: string;
+      revision: number;
+      config: WebchatConfig;
+    }
+  | {
+      t: 'config/autosaved';
+      requestId: string;
+      revision: number;
+      state: 'applied' | 'draft';
+      config: WebchatConfig;
+      draftFields?: string[];
+    }
+  | {
+      t: 'config/update-failed';
+      requestId: string;
+      message: string;
+      fieldErrors?: Record<string, string>;
+      currentRevision?: number;
+    }
+  | {
+      t: 'config/tool/tested';
+      tool: ToolConfigName;
+      ok: boolean;
+      message: string;
+    }
+  | {
+      t: 'config/model/tested';
+      requestId: string;
+      ok: boolean;
+      message: string;
+    }
   | { t: 'skills'; skills: SkillInfo[] }
   | { t: 'server_error'; message: string }
   | { t: 'resource/crons/list'; tasks: CronTaskWithRuns[]; missedCount: number }
   | { t: 'resource/crons/draft'; draft: CronDraftResult }
   | { t: 'resource/crons/show'; task: CronTaskWithRuns | null }
   | { t: 'resource/crons/missed'; missed: CronMissedRecord[] }
-  | { t: 'resource/crons/changed'; tasks: CronTaskWithRuns[]; missedCount: number }
+  | {
+      t: 'resource/crons/changed';
+      tasks: CronTaskWithRuns[];
+      missedCount: number;
+    }
   | { t: 'resource/commands/list'; commands: CommandDescriptor[] }
   | { t: 'social/me'; user: UserProfile | null }
   | { t: 'social/friends'; friends: FriendEntry[] }
   | { t: 'social/searchResults'; users: UserProfile[] }
-  | { t: 'social/error'; message: string }
+  | { t: 'social/error'; message: string; requestId?: string }
   | { t: 'conversation/list'; conversations: DirectConversationSummary[] }
   | { t: 'conversation/navigation'; navigation: ConversationNavigation }
   | { t: 'conversation/detail'; conversation: DirectConversationSummary }
-  | { t: 'conversation/message'; conversationId: string; message: DirectChatMessage }
-  | { t: 'conversation/history'; conversationId: string; messages: DirectChatMessage[]; hasMore: boolean }
-  | { t: 'agent/direct/history'; workspaceSessionId: string; messages: AgentDirectMessage[] }
-  | { t: 'agent/direct/message'; workspaceSessionId: string; message: AgentDirectMessage }
+  | {
+      t: 'conversation/message';
+      conversationId: string;
+      message: DirectChatMessage;
+    }
+  | {
+      t: 'conversation/sent';
+      requestId: string;
+      conversationId: string;
+      message: DirectChatMessage;
+    }
+  | {
+      t: 'conversation/history';
+      conversationId: string;
+      messages: DirectChatMessage[];
+      hasMore: boolean;
+    }
+  | {
+      t: 'agent/direct/history';
+      workspaceSessionId: string;
+      messages: AgentDirectMessage[];
+    }
+  | {
+      t: 'agent/direct/message';
+      workspaceSessionId: string;
+      message: AgentDirectMessage;
+    }
   | { t: 'agent/direct/event'; workspaceSessionId: string; event: AgentEvent }
   | { t: 'agent/direct/error'; workspaceSessionId?: string; message: string }
-  | { t: 'conversation/actions'; kind: 'group' | 'direct' | 'agent'; id: string; actions: ConversationActionSuggestion[] }
+  | {
+      t: 'conversation/actions';
+      kind: 'group' | 'direct' | 'agent';
+      id: string;
+      actions: ConversationActionSuggestion[];
+    }
   | { t: 'node/pairing'; code: string; expiresAt: number }
   | { t: 'node/list'; nodes: AgentNodeSummary[] }
-  | { t: 'workspace/list'; agents: WorkspaceAgent[]; sessions: WorkspaceSessionAgent[] }
+  | {
+      t: 'workspace/list';
+      agents: WorkspaceAgent[];
+      sessions: WorkspaceSessionAgent[];
+    }
   | { t: 'conversation/workspace'; workspace: ConversationWorkspace | null }
   | { t: 'conversation/workspace/error'; message: string }
   | { t: 'group/list'; groups: GroupSummary[] }
   | { t: 'group/detail'; group: GroupDetail }
   | { t: 'group/message'; groupId: string; message: GroupChatMessage }
-  | { t: 'group/history'; groupId: string; messages: GroupChatMessage[]; hasMore: boolean }
+  | {
+      t: 'group/sent';
+      requestId: string;
+      groupId: string;
+      message: GroupChatMessage;
+    }
+  | {
+      t: 'group/history';
+      groupId: string;
+      messages: GroupChatMessage[];
+      hasMore: boolean;
+    }
+  | {
+      t: 'relay/device/registered';
+      deviceId: string;
+      /** This device cannot receive relay history authored before this instant. */
+      historyStartsAt: number;
+      /** True only when this installation was first enrolled for the account. */
+      newDevice: boolean;
+    }
+  | {
+      t: 'relay/events';
+      deliveries: RelayDelivery[];
+      continuity?: RelayContinuityState;
+    }
+  | {
+      t: 'relay/gap/candidates';
+      targetDeviceId: string;
+      candidates: RelayGapCandidate[];
+    }
+  | { t: 'relay/gap/requested'; request: RelayGapRepairRequest }
+  | {
+      t: 'relay/repaired';
+      requestId: string;
+      eventId: string;
+      targetDeviceId: string;
+    }
+  | { t: 'relay/published'; requestId: string; eventId: string }
+  | { t: 'relay/publishedBatch'; requestId: string; eventIds: string[] }
+  | { t: 'relay/acked'; eventId: string }
+  | {
+      t: 'relay/error';
+      code: string;
+      message: string;
+      retryable: boolean;
+      requestId?: string;
+    }
   /** agent 回合的流式预览增量（只推给正打开该群的连接）；尽力而为，最终 group/message 是真值。 */
-  | { t: 'group/agentStream'; groupId: string; agentMemberId: string; displayName: string; delta: string }
+  | {
+      t: 'group/agentStream';
+      groupId: string;
+      agentMemberId: string;
+      displayName: string;
+      delta: string;
+    }
   | UserSocialEvent
   // ---- Browser automation server frames (product-grade) ----
-  | { t: 'browser/context/changed'; requestId?: string; conversationKey: string; runId: string; tabId?: string }
-  | { t: 'browser/started'; requestId?: string; streamPort: number; pid?: number; sessionId?: string; conversationKey?: string; runId?: string }
+  | {
+      t: 'browser/context/changed';
+      requestId?: string;
+      conversationKey: string;
+      runId: string;
+      tabId?: string;
+    }
+  | {
+      t: 'browser/started';
+      requestId?: string;
+      streamPort: number;
+      pid?: number;
+      sessionId?: string;
+      conversationKey?: string;
+      runId?: string;
+    }
   | { t: 'browser/stopped'; requestId?: string }
-  | { t: 'browser/mode'; mode: 'browse' | 'assist' | 'auto'; requestId?: string }
-  | { t: 'browser/status'; connected: boolean; screencasting: boolean; viewportWidth: number; viewportHeight: number; engine: string; recording?: boolean; mode?: 'browse' | 'assist' | 'auto'; url?: string; title?: string }
-  | { t: 'browser/frame'; data: string; metadata?: Record<string, unknown>; sessionId?: string; tabId?: string; conversationKey?: string; runId?: string; frameWidth?: number; frameHeight?: number; viewportWidth?: number; viewportHeight?: number; deviceScaleFactor?: number; pageRevision?: string }
-  | { t: 'browser/tabs'; tabs: Array<{ id: string; url: string; title?: string; active: boolean; favicon?: string }>; timestamp?: number }
+  | {
+      t: 'browser/mode';
+      mode: 'browse' | 'assist' | 'auto';
+      requestId?: string;
+    }
+  | {
+      t: 'browser/status';
+      connected: boolean;
+      screencasting: boolean;
+      viewportWidth: number;
+      viewportHeight: number;
+      engine: string;
+      recording?: boolean;
+      mode?: 'browse' | 'assist' | 'auto';
+      url?: string;
+      title?: string;
+    }
+  | {
+      t: 'browser/frame';
+      data: string;
+      metadata?: Record<string, unknown>;
+      sessionId?: string;
+      tabId?: string;
+      conversationKey?: string;
+      runId?: string;
+      frameWidth?: number;
+      frameHeight?: number;
+      viewportWidth?: number;
+      viewportHeight?: number;
+      deviceScaleFactor?: number;
+      pageRevision?: string;
+    }
+  | {
+      t: 'browser/tabs';
+      tabs: Array<{
+        id: string;
+        url: string;
+        title?: string;
+        active: boolean;
+        favicon?: string;
+      }>;
+      timestamp?: number;
+    }
   | { t: 'browser/tab/activated'; tabId: string }
   | { t: 'browser/url'; url: string; tabId?: string }
   | { t: 'browser/title'; title: string; tabId?: string }
-  | { t: 'browser/navigation'; url: string; state: 'start' | 'commit' | 'load' | 'domcontentloaded' }
+  | {
+      t: 'browser/navigation';
+      url: string;
+      state: 'start' | 'commit' | 'load' | 'domcontentloaded';
+    }
   | { t: 'browser/console'; level?: string; text: string; source?: string }
   | { t: 'browser/page_error'; text: string }
-  | { t: 'browser/download'; url: string; filename?: string; path?: string; state: 'start' | 'progress' | 'complete' | 'canceled'; receivedBytes?: number; totalBytes?: number }
-  | { t: 'browser/dialog'; type: 'alert' | 'confirm' | 'prompt' | 'beforeunload'; message: string; defaultValue?: string }
+  | {
+      t: 'browser/download';
+      url: string;
+      filename?: string;
+      path?: string;
+      state: 'start' | 'progress' | 'complete' | 'failed' | 'canceled';
+      id?: string;
+      mime?: string;
+      error?: string;
+      receivedBytes?: number;
+      totalBytes?: number;
+    }
+  | {
+      t: 'browser/dialog';
+      type: 'alert' | 'confirm' | 'prompt' | 'beforeunload';
+      message: string;
+      defaultValue?: string;
+    }
   | { t: 'browser/snapshot'; requestId?: string; tree: string }
-  | { t: 'browser/screenshot'; requestId?: string; path?: string; data?: string; error?: string }
+  | {
+      t: 'browser/screenshot';
+      requestId?: string;
+      path?: string;
+      data?: string;
+      error?: string;
+    }
   | { t: 'browser/content'; requestId?: string; text: string }
-  | { t: 'browser/picked'; requestId?: string; reference?: BrowserElementReference; ref?: string; tag?: string; text?: string; boundingBox?: { x: number; y: number; width: number; height: number }; attributes?: Record<string, string>; error?: string }
-  | { t: 'browser/marked/elements'; elements: Array<{ ref: string; tag: string; text?: string; boundingBox?: { x: number; y: number; width: number; height: number } }> }
-  | { t: 'browser/agent/pointer'; x: number; y: number; visible: boolean; action?: 'move' | 'click' | 'type' | 'scroll' | 'idle' | 'hover'; elementRef?: string }
-  | { t: 'browser/agent/acting'; acting: boolean; action?: string; target?: string }
+  | {
+      t: 'browser/picked';
+      requestId?: string;
+      reference?: BrowserElementReference;
+      ref?: string;
+      tag?: string;
+      text?: string;
+      boundingBox?: { x: number; y: number; width: number; height: number };
+      attributes?: Record<string, string>;
+      error?: string;
+    }
+  | {
+      t: 'browser/marked/elements';
+      elements: Array<{
+        ref: string;
+        tag: string;
+        text?: string;
+        boundingBox?: { x: number; y: number; width: number; height: number };
+      }>;
+    }
+  | {
+      t: 'browser/agent/pointer';
+      x: number;
+      y: number;
+      visible: boolean;
+      action?: 'move' | 'click' | 'type' | 'scroll' | 'idle' | 'hover';
+      elementRef?: string;
+    }
+  | {
+      t: 'browser/agent/acting';
+      acting: boolean;
+      action?: string;
+      target?: string;
+    }
   /**
    * 一次定位失败后，引擎从当前页面挑出的最像目标的元素。
    *
@@ -1717,26 +3333,85 @@ export type ServerFrame =
   | { t: 'browser/control/changed'; state: BrowserControlState }
   | {
       t: 'browser/challenge/detected';
-      reason: Exclude<import('../humanIntervention.js').HumanInterventionReason, 'manual'>;
+      reason: Exclude<
+        import('../humanIntervention.js').HumanInterventionReason,
+        'manual'
+      >;
       summary: string;
       resumeToken: string;
       runId: string;
       conversationKey?: string;
     }
-  | { t: 'browser/result'; requestId?: string; action: string; ok: boolean; conversationKey?: string; runId?: string; tabId?: string; content?: string; error?: string; data?: unknown }
-  | { t: 'browser/cookies'; requestId?: string; cookies: Array<{ name: string; value: string; domain?: string; path?: string }> }
+  | {
+      t: 'browser/result';
+      requestId?: string;
+      action: string;
+      ok: boolean;
+      conversationKey?: string;
+      runId?: string;
+      tabId?: string;
+      content?: string;
+      error?: string;
+      data?: unknown;
+    }
+  | {
+      t: 'browser/cookies';
+      requestId?: string;
+      cookies: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+        path?: string;
+      }>;
+    }
   | { t: 'browser/device'; preset?: string; width: number; height: number }
-  | { t: 'browser/profile/status'; configured: boolean; profileId: 'default'; developerMode: boolean; engine: string }
+  | {
+      t: 'browser/profile/status';
+      configured: boolean;
+      profileId: 'default';
+      developerMode: boolean;
+      engine: string;
+    }
   | { t: 'browser/error'; message: string; code?: string }
-  | { t: 'computer/status'; requestId?: string; available: boolean; serviceVersion?: string; implementation?: string; capabilities?: string[]; error?: string }
-  | { t: 'computer/permissions'; requestId?: string; permissions?: unknown; error?: string }
-  | { t: 'computer/observed'; requestId?: string; conversationKey: string; runId: string; state?: ComputerObservation; data?: unknown; error?: string }
+  | {
+      t: 'computer/status';
+      requestId?: string;
+      available: boolean;
+      serviceVersion?: string;
+      implementation?: string;
+      capabilities?: string[];
+      error?: string;
+    }
+  | {
+      t: 'computer/permissions';
+      requestId?: string;
+      permissions?: unknown;
+      error?: string;
+    }
+  | {
+      t: 'computer/observed';
+      requestId?: string;
+      conversationKey: string;
+      runId: string;
+      state?: ComputerObservation;
+      data?: unknown;
+      error?: string;
+    }
   /**
    * A privacy-preserving live action cue for the supervised Computer Use
    * workbench. It intentionally carries neither typed text nor an absolute
    * screen coordinate: x/y stay in the existing 0-1000 display-relative space.
    */
-  | { t: 'computer/action'; conversationKey: string; runId: string; action: string; x?: number; y?: number; displayId?: string; occurredAt: number }
+  | {
+      t: 'computer/action';
+      conversationKey: string;
+      runId: string;
+      action: string;
+      x?: number;
+      y?: number;
+      displayId?: string;
+      occurredAt: number;
+    }
   | {
       t: 'computer/control/changed';
       /**
@@ -1750,9 +3425,26 @@ export type ServerFrame =
        * 真正全局的状态（服务不可用、helper 缺失）走 `computer/status`，不混进来。
        */
       state:
-        | { owner: 'none'; status: 'idle'; conversationKey: string; runId: string }
-        | { owner: 'agent'; status: 'running'; conversationKey: string; runId: string; action?: string; targetApp?: string }
-        | { owner: 'user'; status: 'interactive'; conversationKey: string; runId: string }
+        | {
+            owner: 'none';
+            status: 'idle';
+            conversationKey: string;
+            runId: string;
+          }
+        | {
+            owner: 'agent';
+            status: 'running';
+            conversationKey: string;
+            runId: string;
+            action?: string;
+            targetApp?: string;
+          }
+        | {
+            owner: 'user';
+            status: 'interactive';
+            conversationKey: string;
+            runId: string;
+          }
         | {
             owner: 'user';
             status: 'waiting_human';
@@ -1764,10 +3456,21 @@ export type ServerFrame =
             resumeToken: string;
             sanitizedSummary: string;
           }
-        | { owner: 'none'; status: 'error'; conversationKey: string; runId: string; message: string };
+        | {
+            owner: 'none';
+            status: 'error';
+            conversationKey: string;
+            runId: string;
+            message: string;
+          };
     }
   // 终端不走 WS：改由 Tauri 原生真 PTY 承载（server 帧无 terminal/*）。
-  | { t: 'file/preview/opened'; requestId: string; ref?: ConversationFileRef; error?: string }
+  | {
+      t: 'file/preview/opened';
+      requestId: string;
+      ref?: ConversationFileRef;
+      error?: string;
+    }
   | { t: 'file/browse/result'; requestId: string; listing: FileBrowserListing };
 
 export interface CommandDescriptor {