@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/core/subagents.ts

@@ -0,0 +1,78 @@
+/** Shared wire format for native CLI subagents. These are not Center tasks. */
+export interface SubagentInfo {
+  id: string;
+  parentId?: string;
+  title: string;
+  task?: string;
+  status: "running" | "completed" | "failed" | "cancelled" | "unknown";
+  detailAvailability: "full" | "partial" | "unavailable";
+  detailReason?: string;
+  updatedAt?: number;
+}
+
+export interface SubagentMessage {
+  subagentId: string;
+  role: "user" | "assistant" | "tool" | "system";
+  content: string;
+  tool?: { id: string; title: string; detail?: string; result?: string; isError?: boolean };
+  eventId: string;
+  updatedAt?: number;
+}
+
+export interface SubagentFields {
+  subagent?: SubagentInfo;
+  subagentMessage?: SubagentMessage;
+}
+
+type Row = { id: string; role: string; content: string; generation: number; ts?: number; created_at?: number };
+export interface SubagentTranscript { subagent: SubagentInfo; messages: Row[]; refreshable?: boolean; older?: number }
+export type LoadSubagent = (id: string, generation: number, before?: string) => Promise<SubagentTranscript>;
+
+const cache = new WeakMap<Row, SubagentFields>();
+export function subagentFields(row: Row): SubagentFields {
+  const known = cache.get(row);
+  if (known) return known;
+  const fields: SubagentFields = {};
+  if (row.role === "tool") {
+    try {
+      const value = JSON.parse(row.content);
+      const info = value?.subagent;
+      if (info && typeof info.id === "string" && typeof info.title === "string") fields.subagent = {
+        id: info.id, title: info.title,
+        parentId: typeof info.parentId === "string" ? info.parentId : undefined,
+        task: typeof info.task === "string" ? info.task : undefined,
+        status: ["running", "completed", "failed", "cancelled", "unknown"].includes(info.status) ? info.status : "unknown",
+        detailAvailability: ["full", "partial", "unavailable"].includes(info.detailAvailability) ? info.detailAvailability : "partial",
+        detailReason: typeof info.detailReason === "string" ? info.detailReason : undefined,
+        updatedAt: typeof info.updatedAt === "number" && Number.isFinite(info.updatedAt) ? info.updatedAt : undefined,
+      };
+      if (value?.subagentMessage && typeof value.subagentMessage.subagentId === "string" && typeof value.subagentMessage.content === "string"
+        && ["user", "assistant", "tool", "system"].includes(value.subagentMessage.role)) fields.subagentMessage = value.subagentMessage;
+    } catch { /* Ordinary or malformed tool output is handled by the existing renderer. */ }
+  }
+  cache.set(row, fields);
+  return fields;
+}
+
+/** Keep child activity out of the parent timeline, but retain an entry if its card is outside the loaded tail. */
+export function parentMessages<T extends Row>(rows: T[]): T[] {
+  const cardKeys = new Set(rows.flatMap(row => {
+    const info = subagentFields(row).subagent;
+    return info ? [`${row.generation}:${info.id}`] : [];
+  }));
+  const emitted = new Set<string>();
+  return rows.flatMap(row => {
+    const { subagent, subagentMessage } = subagentFields(row);
+    if (subagent?.parentId && cardKeys.has(`${row.generation}:${subagent.parentId}`)) return [];
+    if (!subagentMessage) return [row];
+    const key = `${row.generation}:${subagentMessage.subagentId}`;
+    if (cardKeys.has(key) || emitted.has(key)) return [];
+    emitted.add(key);
+    const info: SubagentInfo = { id: subagentMessage.subagentId, title: "子代理", status: "unknown", detailAvailability: "partial", detailReason: "正在读取子代理详情" };
+    return [{ ...row, id: `subagent-entry:${key}`, role: "tool", content: JSON.stringify({ title: info.title, subagent: info }) }];
+  });
+}
+
+export function childMessages(rows: Row[], id: string, generation: number) {
+  return rows.filter(row => row.generation === generation && (subagentFields(row).subagentMessage?.subagentId === id || subagentFields(row).subagent?.parentId === id));
+}

package/src/core/textDecode.ts

@@ -0,0 +1,24 @@
+/**
+ * 工作区文本文件的解码：智能体写的多是 UTF-8，但业务导出的 CSV / TXT 常常是 GBK（GB18030），
+ * 按 UTF-8 硬解会满屏乱码。顺序：BOM（UTF-8 / UTF-16）→ 严格 UTF-8 → GB18030。
+ *
+ * 只读了文件的一段（开头 / 末尾）时：开头那段末尾可能切在一个字中间——按流式解码，把不完整的尾巴留下不报错；
+ * 末尾那段开头可能切在一个 UTF-8 字中间——跳过开头最多 3 个续字节。
+ */
+export function decodeText(bytes: Uint8Array, opts: { fromMiddle?: boolean } = {}): { text: string; encoding: string } {
+  if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return { text: new TextDecoder("utf-8").decode(bytes.subarray(3), { stream: true }), encoding: "utf-8" };
+  if (bytes[0] === 0xff && bytes[1] === 0xfe) return { text: new TextDecoder("utf-16le").decode(bytes.subarray(2), { stream: true }), encoding: "utf-16le" };
+  if (bytes[0] === 0xfe && bytes[1] === 0xff) return { text: new TextDecoder("utf-16be").decode(bytes.subarray(2), { stream: true }), encoding: "utf-16be" };
+  let start = 0;
+  if (opts.fromMiddle) while (start < 3 && start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
+  const body = bytes.subarray(start);
+  try {
+    return { text: new TextDecoder("utf-8", { fatal: true }).decode(body, { stream: true }), encoding: "utf-8" };
+  } catch {
+    try {
+      return { text: new TextDecoder("gb18030").decode(bytes, { stream: true }), encoding: "gb18030" };
+    } catch {
+      return { text: new TextDecoder("utf-8").decode(body, { stream: true }), encoding: "utf-8" };
+    }
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,505 @@
+import type { SubagentInfo, SubagentMessage } from "./subagents";
+/**
+ * 两套数据形状：
+ *   · center 服务（cli-task-center）对话任务接口的返回（snake_case，原样保留，便于对照 API 文档）；
+ *   · Operator 节点转录的消息与事件（center 的实时流原样转发，界面按 Operator 的规则渲染）。
+ */
+
+// ── center：对话任务 ────────────────────────────────────────────────
+
+export type JobStatus = "queued" | "bound" | "idle" | "running" | "paused" | "succeeded" | "failed" | "cancelled" | string;
+export type TurnStatus = "queued" | "dispatching" | "running" | "succeeded" | "failed" | "cancelled" | "merged" | string;
+
+export interface CenterTurn {
+  turn_id: string;
+  job_id: string;
+  task_id: string;
+  seq: number;
+  business_id: string | null;
+  status: TurnStatus;
+  input: string;
+  /** 合并了后面排队的消息时，实际发给 Agent 的全文；否则为 null（= input）。 */
+  sent_input: string | null;
+  merged_into_turn_id: string | null;
+  reply: string | null;
+  /** true = 这一轮以 Agent 提问结束：reply 是问题，下一条消息就是回答。 */
+  asked: boolean;
+  last_error: string | null;
+  attempt: number;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  /** true = 节点上的会话重建了，这一轮起之前的对话没带过去（工作区文件还在）。 */
+  context_reset: boolean;
+  /** 这一轮的改动是否已合并回项目基线。 */
+  merged?: boolean;
+  merge_error?: string | null;
+  /** 保存本任务分支与合并项目主分支分别记录；旧版中枢不返回。 */
+  saved?: boolean;
+  saved_at?: string | null;
+  save_error?: string | null;
+  created_at: string;
+  started_at: string | null;
+  ended_at: string | null;
+  queue_position?: number | null;
+}
+
+/** Node-observed human wait state. Missing/null means unavailable, not confirmed idle. */
+export interface AwaitingInputState {
+  awaiting_input?: boolean | null;
+  awaiting_input_observed_at?: string | null;
+}
+
+export interface CenterTask extends AwaitingInputState {
+  id: string;
+  job_id: string;
+  seq?: number;
+  title: string;
+  status: string;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  browser?: boolean;
+  last_error: string | null;
+  /** 接续出来的对话：指回旧对话任务里对应的那个对话。 */
+  continue_from_task_id?: string;
+}
+
+/** 对话任务里的一个对话（一个子任务、一个 Agent 会话）。conversation.conversations 的一项。 */
+export interface ConversationInfo extends AwaitingInputState {
+  task_id: string;
+  seq: number;
+  title: string;
+  status: string;
+  /** 关掉了（单独关闭这一个，或整个对话任务结束）。 */
+  closed: boolean;
+  turns: number;
+  queued_turns: number;
+  running_turn: boolean;
+  last_turn: CenterTurn | null;
+  remote_task_id: string | null;
+  continue_from_task_id: string | null;
+  created_at: string | null;
+}
+
+export interface ConversationSummary extends AwaitingInputState {
+  /** 里面的每个对话（按开的先后）。旧版 center 没有这个字段：当作只有一个对话。 */
+  conversations?: ConversationInfo[];
+  turns: number;
+  queued_turns: number;
+  running_turn: boolean;
+  last_turn: CenterTurn | null;
+  last_activity_at: string | null;
+  expires_at: string | null;
+  closed_reason: string | null;
+  continued_from_job_id: string | null;
+  continued_by_job_id: string | null;
+}
+
+/** GET /api/jobs/:id */
+export interface CenterJob {
+  id: string;
+  title: string;
+  status: JobStatus;
+  mode?: "conversation" | string;
+  conversation?: ConversationSummary;
+  tasks: CenterTask[];
+}
+
+/** POST /api/jobs/:id/messages、POST /api/jobs/:id/conversations */
+export interface SendResult {
+  job_id: string;
+  /** 实际接收这条消息的对话（对话任务过期接续后是新对话任务里对应的那个）。 */
+  task_id?: string;
+  status: JobStatus;
+  duplicate: boolean;
+  /** true = 原对话已结束，这条消息开了一个新对话（job_id 是新的）。 */
+  new_conversation: boolean;
+  previous_job_id: string | null;
+  queue_position: number | null;
+  turn: CenterTurn;
+}
+
+/** 每次浏览器操作前的随机等待范围；合法范围由任务中心与节点共同校验。 */
+export interface BrowserPacing {
+  min_seconds: number;
+  max_seconds: number;
+}
+
+/** 新建对话时可带的参数（POST /api/jobs，mode=conversation）。 */
+export interface NewConversationOptions {
+  /** 首轮执行配置。由服务端校验、持久化，并用于后续派发和重试。 */
+  executionConfig?: import("./execution").ExecutionOptions;
+  title?: string;
+  /** 业务自己的 ID（tasks[0].business_id）：第一轮的回调里原样带回，用来和业务数据对应。 */
+  businessId?: string;
+  workspace?: { name?: string; context?: string; branch?: string };
+  callback?: { url: string; code: string };
+  agent?: string;
+  timeoutSeconds?: number;
+  browser?: boolean;
+  /** Ego 操作手册的 YAML 正文（不是文件名或 URL）；必须显式 browser:true。 */
+  browserPlaybook?: string;
+  /** 转发至节点执行器和浏览器脚本；必须显式 browser:true。 */
+  browserPacing?: BrowserPacing;
+}
+
+// ── Operator：节点转录 ─────────────────────────────────────────────
+
+export type MsgRole = "user" | "assistant" | "tool" | "system" | "session_break";
+
+export interface Message {
+  id: string;
+  task_id?: string;
+  generation: number;
+  role: MsgRole;
+  content: string;
+  created_at: number;
+}
+
+export interface PendingMessage {
+  id: string;
+  generation: number;
+  content: string;
+  created_at: number;
+}
+
+export interface Msg {
+  id: string;
+  /** queued：中枢里还在排队、没送到节点的消息（界面上是可撤回的「排队中」气泡）。 */
+  role: MsgRole | "queued";
+  content: string;
+  generation: number;
+  toolId?: string;
+  ts?: number;
+  /** queued 气泡对应的中枢轮次，撤回时用。 */
+  turnId?: string;
+  /** queued 气泡：中枢给出的等待原因（节点连不上、没有可用节点……），正常排队时为空。 */
+  note?: string;
+}
+
+export interface AskOption { label: string; description?: string }
+export interface AskQuestion { question: string; header: string; multiSelect?: boolean; options: AskOption[] }
+export type AskAnswers = string[][];
+
+export interface InputField { label: string; secret?: boolean; options?: string[]; placeholder?: string }
+export interface InputRequest {
+  id: string;
+  message: string;
+  fields: InputField[];
+  status: "pending" | "answered" | "cancelled";
+  values?: string[];
+}
+
+export type DiffLine = { sign: "+" | "-" | " "; text: string };
+
+export type ToolPeek =
+  | { kind: "count"; text: string }
+  | { kind: "diff"; added: number; removed: number; label?: string; lines: DiffLine[]; truncated?: number }
+  | { kind: "lines"; label?: string; lines: string[]; truncated?: number }
+  | { kind: "todos"; items: { text: string; status: string }[] };
+
+export interface ToolData {
+  subagent?: SubagentInfo;
+  subagentMessage?: SubagentMessage;
+  title: string;
+  detail?: string;
+  result?: string;
+  isError?: boolean;
+  peek?: ToolPeek;
+  diff?: DiffLine[];
+  ask?: { id: string; questions: AskQuestion[]; answers?: AskAnswers };
+  input?: InputRequest;
+}
+
+export interface TurnUsage {
+  cost_usd: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+}
+
+/** 节点回合事件（center 流里 `{type:"node", event}` 的 event）。 */
+export type NodeEvent =
+  | { type: "user"; content: string; msgId: string; generation: number; ts?: number }
+  | { type: "queued"; msgId: string; content: string; generation: number; ts?: number }
+  | { type: "dequeued"; msgId: string }
+  | { type: "model"; model: string }
+  | { type: "assistant"; content: string; msgId?: string; generation?: number; ts?: number }
+  | { type: "tool"; id: string; title: string; detail: string; peek?: ToolPeek; diff?: DiffLine[]; subagent?: SubagentInfo; subagentMessage?: SubagentMessage; msgId?: string; generation?: number; ts?: number }
+  | { type: "tool_result"; id: string; content: string; isError: boolean; peek?: ToolPeek; subagent?: SubagentInfo; subagentMessage?: SubagentMessage; msgId?: string; generation?: number; ts?: number }
+  | { type: "ask"; id: string; questions: AskQuestion[]; msgId?: string; generation?: number }
+  | { type: "ask_answered"; id: string; answers: AskAnswers; msgId?: string; awaiting_input?: 0 | 1 }
+  | { type: "input"; input: InputRequest; msgId?: string; generation?: number; awaiting_input?: 0 | 1 }
+  | { type: "usage"; usage: TurnUsage }
+  | { type: "notice"; content: string; msgId?: string; generation?: number }
+  | { type: "error"; content: string; msgId?: string; generation?: number }
+  | { type: "turn_end" }
+  | { type: string; [key: string]: unknown };
+
+/** center 实时流 chunk.events 里的一项。 */
+export type StreamItem =
+  /** remote_task_id：一次性任务的流里才有（大任务里可能同时有几个节点对话）。 */
+  /** older：快照只有最新一段时，更早还有几条（往上翻时经 history 分页取）。旧版中枢没有 = 全量。 */
+  | { type: "transcript"; remote_task_id?: string; messages: Message[] | null; pending: PendingMessage[] | null; running: boolean | null; older?: number }
+  | { type: "node"; remote_task_id?: string; event: NodeEvent }
+  | { type: "turn"; turn: CenterTurn }
+  | { type: "job"; job: { id: string; status: JobStatus; closed_reason?: string | null; node_id: string | null } }
+  /** 正在看的这个对话的状态变化（关闭了：closed=true）；一次性任务的流里是子任务（BatchStreamTask）。 */
+  | { type: "task"; task: StreamTask | BatchStreamTask };
+
+/** 实时流看的那个对话（GET /api/jobs/:id/stream?task=）。 */
+export interface StreamTask extends AwaitingInputState { id: string; seq: number; title: string; status: string; closed: boolean; remote_task_id: string | null; continue_from_task_id: string | null }
+
+export interface StreamSnapshot {
+  job: { id: string; status: JobStatus; closed_reason: string | null; node_id: string | null; mode: string; title: string; conversation: ConversationSummary };
+  /** 旧版 center 没有。 */
+  task?: StreamTask;
+  turns: CenterTurn[];
+}
+
+/**
+ * 一次性任务（含续派）的子任务，实时流里的样子。cli-chat 只读查看这类任务时用。
+ * prompt / opener_prompt：指定了 ?task= 时看的那个子任务才有（opener_prompt = 开出它所在节点对话的那个子任务的原文）。
+ */
+export interface BatchStreamTask extends AwaitingInputState {
+  id: string;
+  seq: number;
+  task_key: string | null;
+  title: string;
+  status: string;
+  round: number;
+  attempt: number;
+  remote_task_id: string | null;
+  continue_from_task_id: string | null;
+  last_error: string | null;
+  prompt?: string;
+  opener_prompt?: string;
+  /**
+   * 对话式子任务（续派时 mode=conversation）：指定 ?task= 看它时，它和续派接着它聊的子任务算一个对话——
+   * 这条是其中最新的；conversation_remote_task_id 是它们共用的节点对话，queued 是还没派发的消息。旧版中枢没有。
+   */
+  conversation?: boolean;
+  conversation_remote_task_id?: string | null;
+  queued?: Array<{ id: string; prompt: string; created_at?: string }>;
+}
+
+/** 一次性任务（含续派，mode 不是 conversation）的实时流首个事件：没有轮次，只有子任务。 */
+export interface BatchStreamSnapshot {
+  job: { id: string; status: JobStatus; node_id: string | null; round: number; terminal_revision: number; mode: string; title: string };
+  tasks: BatchStreamTask[];
+  /** 指定了 ?task= 时：看的那个子任务。 */
+  task?: BatchStreamTask;
+}
+
+export const isBatchSnapshot = (snapshot: StreamSnapshot | BatchStreamSnapshot): snapshot is BatchStreamSnapshot =>
+  !Array.isArray((snapshot as StreamSnapshot).turns) && Array.isArray((snapshot as BatchStreamSnapshot).tasks);
+
+export interface StreamEnd {
+  /** 对话任务的结束原因；只是这个对话被关闭时为 conversation_closed。 */
+  reason: string;
+  task_id?: string;
+  continued_by_job_id?: string | null;
+  /** 接续这个对话的新对话（新对话任务里的子任务）；还没有为 null。 */
+  continued_by_task_id?: string | null;
+}
+
+// ── center 回调体（与中枢 conversation.ts turnCallbackPayload / job-callback.ts 的字段一一对应） ──
+//
+// 组件在前端发出的 conversation_turn / conversation_closed 事件，载荷与中枢投递给 callback.url 的请求体同名同义，
+// 业务方可以用同一套代码处理「后端回调」和「前端事件」。前端拿不到的字段（event_id、callback_seq、cumulative、
+// carried）不出现；以后端回调为准落库，前端事件只用来刷新界面。
+
+/** 每轮一次：type = "conversation_turn"。 */
+export interface ConversationTurnCallback {
+  type: "conversation_turn";
+  /** 投递顺序号（= seq）。同一对话里按它从小到大处理；结束事件是最后一轮 + 1。 */
+  callback_seq: number;
+  job_id: string;
+  task_id: string;
+  turn_id: string;
+  seq: number;
+  business_id: string | null;
+  /** succeeded / failed / cancelled（被合并的消息不单独回调，见 messages）。 */
+  status: TurnStatus;
+  occurred_at: string;
+  /** 实际发给 Agent 的正文（合并了排队消息时是拼起来的全文）。 */
+  input: string;
+  /** 这一轮包含的全部消息，按发送顺序（排队的消息会合并进来）。 */
+  messages: Array<{ turn_id: string; seq: number; business_id: string | null; input: string }>;
+  reply: string | null;
+  /** true = 这一轮以 Agent 提问结束（reply 是问题），status 仍是 succeeded；下一条消息就是回答。 */
+  asked: boolean;
+  /** 失败 / 取消原因（中枢原文）。 */
+  message: string | null;
+  continued_from_job_id: string | null;
+  context_reset: boolean;
+  merged: boolean;
+  merge_error: string | null;
+  saved?: boolean;
+  saved_at?: string | null;
+  save_error?: string | null;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  started_at: string | null;
+  ended_at: string | null;
+}
+
+/** 对话结束一次：type = "conversation_closed"。 */
+export interface ConversationClosedCallback {
+  type: "conversation_closed";
+  mode: "conversation";
+  /** 投递顺序号：最后一轮的 seq + 1，永远排在这个对话所有 conversation_turn 之后。 */
+  callback_seq: number;
+  job_id: string;
+  /** 只关掉了对话任务里的这一个对话时才有（前端事件；center 只在整个对话任务结束时回调）。 */
+  task_id?: string;
+  /** succeeded（关闭 / 过期 / 换线）/ cancelled / failed。 */
+  status: JobStatus;
+  /** closed / cancelled / expired / node_reassigned / node_lost。 */
+  closed_reason: string | null;
+  /** 一共几轮（= 最大的 seq，被合并的消息也算）。 */
+  turns: number;
+  /** 接续出来的新对话（过期、换线、节点丢失后再发消息时才有）。 */
+  continued_by_job_id: string | null;
+  occurred_at: string;
+}
+
+export type ConversationCallback = ConversationTurnCallback | ConversationClosedCallback;
+
+/** 一轮结束时 onTurnEnd 收到的载荷（字段与 center 的 conversation_turn 回调体一致）。 */
+export type TurnEndPayload = ConversationTurnCallback;
+/** 对话结束时 onConversationEnd 收到的载荷（字段与 center 的 conversation_closed 回调体一致）。 */
+export type ConversationEndPayload = ConversationClosedCallback;
+
+// ── 右侧看板（cli-board）：center 的 /api/jobs/:id/board、files、diff、browser ──
+
+export interface BoardInfo {
+  job_id: string;
+  /** false = 还没派发到执行节点（文件和浏览器都还没有）。 */
+  dispatched: boolean;
+  detail?: string;
+  task_id?: string;
+  remote_task_id?: string;
+  node?: { id: string; health: string };
+  files: boolean;
+  /** 节点开了浏览器功能。null = 这次没探测出来（节点慢 / 暂时连不上），照常显示浏览器页签。 */
+  browser: boolean | null;
+}
+
+export interface FileEntry {
+  name: string;
+  /** 相对工作目录的路径，用 / 分隔。 */
+  path: string;
+  type: "dir" | "file";
+  size: number;
+  mtime: number;
+  /** Opaque metadata fingerprint for reconnect reconciliation, not an immutable content version. */
+  changeToken?: string;
+}
+
+export interface DirListing { type: "dir"; path: string; entries: FileEntry[]; truncated: boolean; /** 目录里的条目总数（新版节点给）。 */ total?: number; nextCursor?: string; revision?: string }
+export interface FileInfo { type: "file"; path: string; name: string; size: number; mtime: number; contentType: string; inline: boolean }
+
+export interface DiffFile {
+  path: string; status: string; additions: number; deletions: number; binary: boolean; patch: string; truncated?: boolean;
+  /** 改动太多，这个文件的 diff 没有带上（节点对整个 diff 有总量上限）；文件本身照常可以打开。 */
+  omitted?: boolean;
+}
+/** Operator 的 /api/tasks/:id/diff（经 center 原样转发）。 */
+export interface DiffResult {
+  isolated?: boolean;
+  reason?: string;
+  branch?: string;
+  baseLabel?: string;
+  files?: DiffFile[];
+  isDirty?: boolean;
+  ahead?: number;
+  alreadyMerged?: boolean;
+  /** 因为总量上限没带 diff 的文件数。 */
+  patchesOmitted?: number;
+  error?: string;
+  /** 有的节点只给一整段 unified diff。 */
+  diff?: string;
+  patch?: string;
+}
+
+/** Operator 的任务浏览器状态（/api/tasks/:id/browser）。 */
+export interface BrowserStatus {
+  feature: boolean;
+  state: "none" | "opening" | "running" | "closing";
+  origin: "ai" | "manual" | "check" | null;
+  control: "ai" | "human";
+  handoff: { instruction: string; by: "ai" | "user" | "browser" | "kept" } | null;
+  capability: "config" | "manual" | "ai" | null;
+  viewers: number;
+  spaceName: string;
+  instance: { running: boolean; spaces: number };
+  shownLocally: boolean;
+  error: string | null;
+}
+
+/** 浏览器画面流里的一条消息（节点原样转发）。 */
+export interface BrowserTab { id: string; title: string; url: string }
+/** 新节点用页面身份隔离输入；旧节点可以省略这两个字段。 */
+export interface BrowserTarget { targetId?: string; targetEpoch?: number }
+export type BrowserMessage = BrowserTarget & (
+  | { type: "frame"; data: string; metadata?: { deviceWidth: number; deviceHeight: number } }
+  | { type: "page"; url?: string; title?: string }
+  /** 只包含当前任务内的网页；只有明确声明 canSelect 才显示可切换标签。 */
+  | { type: "tabs"; tabs: BrowserTab[]; activeId: string | null; canSelect?: boolean }
+  | { type: "error"; message?: string }
+  /** 按了复制 / 剪切：选中的文字（只发给按键的人），写进本机剪贴板。 */
+  | { type: "clipboard"; text: string }
+  /** 网页弹出了 alert / confirm / prompt（画面里看不到，单独显示）。 */
+  | { type: "dialog"; dialogType: "alert" | "confirm" | "prompt" | "beforeunload"; message: string; defaultPrompt?: string }
+  | { type: "dialog_closed" });
+
+/** 浏览器实时连接（GET /browser/live）的画面连接状况。 */
+export type BrowserFramesState = { state: "idle" | "connecting" | "live" | "retrying"; detail?: string };
+
+
+export interface WorkspaceFileChange {
+  kind: "created" | "modified" | "deleted";
+  path: string;
+  file?: FileEntry;
+  previous?: FileEntry;
+}
+export type WorkspaceFileBatch =
+  | { type: "snapshot"; files: FileEntry[]; revision?: string; complete: boolean }
+  | { type: "changes"; changes: WorkspaceFileChange[]; revision?: string; complete: boolean }
+  | { type: "resync"; reason: string; complete: false; revision?: string };
+export interface WorkspaceChangeEvent {
+  type: "files_changed";
+  /** 对话键；节点适配下是 task.id。 */
+  jobId: string;
+  mode: "events" | "poll";
+  coverage: "workspace" | "listed-files";
+  complete: boolean;
+  changes: WorkspaceFileChange[];
+  revision?: string;
+  resync?: boolean;
+}
+export interface WorkspaceWatchStatus {
+  type: "files_watch";
+  jobId: string;
+  state: "connecting" | "ready" | "reconnecting" | "error";
+  mode: "events" | "poll";
+  coverage: "workspace" | "listed-files";
+  complete: boolean;
+  error?: string;
+}