@spzxg/cli-ui 0.6.2 → 0.6.6

package/src/core/store.ts

@@ -10,12 +10,18 @@
  *
  * 单独用某个组件时它会自己建一个仓库；放进同一个 <CliCenterProvider>（或同一个 group 的 Web Component）就共享一个。
  */
-import { CenterError, createCenterClient, firstLine, type CenterClient, type CenterClientOptions } from "./client.js";
-import { addTurnsIfAbsent, applyItems, applyOlderPage, applySnapshot, closedCallback, convEnded, convKey, emptyConv, isChatTask, NEW_TASK, parseConvKey, TERMINAL_JOB, TERMINAL_TURN, turnCallback, upsertTurns, type ConvState } from "./conversation.js";
-import { formatAnswersText } from "../ui/format.js";
-import { backgroundBlock, charCount, MAX_MESSAGE_CHARS, serializeBlock } from "./blocks.js";
-import { createWorkspace, type BoardView, type CliWorkspace } from "../board/workspace.js";
-import type { AskAnswers, AskQuestion, CenterJob, CenterTurn, ConversationClosedCallback, ConversationTurnCallback, NewConversationOptions } from "./types.js";
+import { clientId } from "./id";
+import { connectionDraftScope } from "./identity";
+import { notifyCallback } from "./callbacks";
+import { CenterError, createCenterClient, firstLine, type CenterClient, type CenterClientOptions } from "./client";
+import { addTurnsIfAbsent, applyItems, applyOlderPage, applySnapshot, closedCallback, convEnded, convKey, emptyConv, isChatTask, NEW_TASK, parseConvKey, TERMINAL_JOB, TERMINAL_TURN, turnCallback, upsertTurns, type ConvState } from "./conversation";
+import { formatAnswersText } from "../ui/format";
+import { backgroundBlock, charCount, MAX_MESSAGE_CHARS, serializeBlock } from "./blocks";
+import { cloneBoardView, reportBoardOwner, activateBoardOwner, selectedBoardOwner, mergeBoardHistory, rememberBoardFile } from "../board/context";
+import { cloneWorkspaceChange, subscribeWorkspaceFiles, retryWorkspaceFiles, type WorkspaceWatchOptions } from "../board/fileWatch";
+import type { WorkspaceChangeEvent, WorkspaceWatchStatus } from "./types";
+import { createWorkspace, type BoardView, type CliWorkspace } from "../board/workspace";
+import type { AskAnswers, AskQuestion, CenterJob, CenterTurn, ConversationClosedCallback, ConversationTurnCallback, NewConversationOptions } from "./types";
 
 export interface JobEntry {
   job: CenterJob | null;
@@ -46,6 +52,8 @@ export interface CliState {
   viewing: Record<string, { ref: BoardRef; off: boolean }>;
   /** 看板现在的样子（按对话键）：正在看的文件、开着的文件页签、当前页签。没有看板时没有。 */
   boards: Record<string, BoardView>;
+  /** 最近看板背景，收起/卸载后保留，供下一条消息被动参考。 */
+  boardContext: Record<string, BoardView>;
   /** 业务方补充的项目背景（按对话键；"" = 还没建的新对话），随下一条消息发出（见 appendContext）。 */
   context: Record<string, ContextItem[]>;
 }
@@ -100,12 +108,27 @@ export type CliEvent =
   | { type: "board_ref"; key: string; refs: BoardRef[] }
   /** 看板上切了页签、打开 / 关掉了文件（view 为 null = 看板关了）。 */
   | { type: "board_change"; key: string; view: BoardView | null }
+  | { type: "board_context"; jobId: string; view: BoardView }
+  | WorkspaceChangeEvent
+  | WorkspaceWatchStatus
   /**
    * 补充背景变了：追加 / 去掉（pending 是还没发出的），或随消息发出了（sent 是这次发出的）。
    * key 是对话键；新对话还没建时是 ""。
    */
   | { type: "context"; key: string; pending: ContextItem[]; sent?: ContextItem[] };
 
+/** Public workspace metadata must not be shared between business listeners. */
+export function cloneWorkspaceEvent(event:CliEvent):CliEvent {
+  if(event.type==='files_changed')return cloneWorkspaceChange(event);
+  if(event.type==='files_watch')return {...event};
+  if(event.type==='board_ref')return {...event,refs:event.refs.map(ref=>({...ref}))};
+  if(event.type==='context')return {...event,pending:event.pending.map(item=>({...item})),...(event.sent?{sent:event.sent.map(item=>({...item}))}:{})};
+  if(event.type==='open')return {...event,target:{...event.target}};
+  if(event.type==='board_context')return {...event,view:cloneBoardView(event.view)};
+  if(event.type==='board_change')return {...event,view:event.view?cloneBoardView(event.view):null};
+  return event;
+}
+
 /** 看板要打开的东西。 */
 export type OpenTarget = { kind: "file"; path: string } | { kind: "browser" } | { kind: "changes" } | { kind: "files"; path?: string }
   /** 宿主用 extraTabs 加的页签。 */
@@ -199,7 +222,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
   // 列表只放宿主给的 jobIds 和本页里新建 / 接续出来的对话：不从 center 发现，也不从本地存储恢复——
   // 不传就不加载，免得把这个产品线令牌下别的业务、别的用户的对话列出来。
 
-  let state: CliState = { selected: null, jobIds: [], jobs: {}, convs: {}, listLoading: false, listError: null, refs: {}, viewing: {}, boards: {}, context: {} };
+  let state: CliState = { selected: null, jobIds: [], jobs: {}, convs: {}, listLoading: false, listError: null, refs: {}, viewing: {}, boards: {}, boardContext: {}, context: {} };
   const listeners = new Set<() => void>();
   const eventListeners = new Set<(event: CliEvent) => void>();
   const settledTurns = new Set<string>();
@@ -210,9 +233,18 @@ export function createCliStore(options: CliStoreOptions = {}) {
 
   const set = (next: Partial<CliState>) => {
     state = { ...state, ...next };
-    for (const fn of listeners) fn();
+    for (const fn of [...listeners]) notifyCallback(fn, undefined);
+  };
+  // Business callbacks may synchronously navigate or register more listeners.
+  // Preserve emission order and keep a fixed audience for each notification.
+  const eventQueue:Array<{event:CliEvent;listeners:Array<(event:CliEvent)=>void>}>=[];
+  let dispatching=false;
+  const emit = (event:CliEvent) => {
+    eventQueue.push({event,listeners:[...eventListeners]});if(dispatching)return;
+    dispatching=true;
+    try{while(eventQueue.length){const next=eventQueue.shift()!;for(const fn of next.listeners)notifyCallback(fn,cloneWorkspaceEvent(next.event));}}
+    finally{dispatching=false;}
   };
-  const emit = (event: CliEvent) => { for (const fn of eventListeners) fn(event); };
   const patchConv = (key: string, fn: (conv: ConvState) => ConvState) => {
     const prev = state.convs[key] ?? emptyConv(key);
     const next = fn(prev);
@@ -286,7 +318,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
 
   function removeJob(jobId: string) {
     const ids = state.jobIds.filter((id) => id !== jobId);
-    set({ jobIds: ids, selected: state.selected === jobId ? null : state.selected });
+    set({ jobIds: ids, selected: state.selected && parseConvKey(state.selected).jobId === jobId ? null : state.selected });
   }
 
   /** 对话接续：旧 job 换成新 job（列表位置不变，选中跟过去）。oldId / newId 可以是对话键。 */
@@ -355,24 +387,27 @@ export function createCliStore(options: CliStoreOptions = {}) {
   function connect(key: string) {
     const entry = streams.get(key);
     if (!entry || entry.refs <= 0) return;
+    const previous = entry.stop;
+    entry.stop = null;
+    previous?.();
+    if (streams.get(key) !== entry || entry.refs <= 0) return;
     const { jobId, taskId } = parseConvKey(key);
-    patchConv(key, (conv) => ({ ...conv, stream: entry.attempt ? "reconnecting" : "connecting", streamError: null }));
-    let ended = false;
-    entry.stop = client.stream(jobId, {
-      onOpen: () => { entry.attempt = 0; patchConv(key, (conv) => ({ ...conv, stream: "live", streamError: null })); },
-      onSnapshot: (snapshot) => patchConv(key, (conv) => applySnapshot(conv, snapshot)),
-      onChunk: (items) => patchConv(key, (conv) => applyItems(conv, items)),
-      onEnd: (end) => {
-        ended = true;
-        // 接续的新对话：指定了对话的跟到接续它的那个对话（还没有就不跟，再发消息时 center 会开出来）；只有 job_id 的照旧跟新 job。
-        const continuedBy = taskId ? (end.continued_by_job_id && end.continued_by_task_id ? convKey(end.continued_by_job_id, end.continued_by_task_id) : null) : end.continued_by_job_id ?? null;
-        patchConv(key, (conv) => ({ ...conv, stream: "ended", endReason: end.reason, continuedBy, nodeRunning: false }));
-        void refreshJob(jobId, true);
-      },
-      onClose: (error) => {
-        entry.stop = null;
-        const current = streams.get(key);
-        if (!current || current.refs <= 0) return;
+    let ended = false, retired = false;
+    let cleanup: (() => void) | null = null;
+    const owns = () => streams.get(key) === entry && entry.refs > 0 && entry.stop === retire;
+    const active = () => !retired && owns();
+    const retire = () => {
+      if (retired) return;
+      retired = true;
+      if (entry.stop === retire) entry.stop = null;
+      const dispose = cleanup; cleanup = null;
+      notifyCallback(dispose ?? undefined, undefined);
+    };
+    const close = (error: CenterError | null) => {
+      if (!active()) return;
+      retire();
+      const current = streams.get(key);
+      if (current !== entry || current.refs <= 0 || current.stop) return;
         // 对话结束（end）不再连；中枢停机（server_shutdown）稍后重连。
         if (ended && state.convs[key]?.endReason !== "server_shutdown") return;
         // 404：对话不存在，重连也没用。
@@ -393,8 +428,32 @@ export function createCliStore(options: CliStoreOptions = {}) {
         current.attempt += 1;
         patchConv(key, (conv) => ({ ...conv, stream: "reconnecting", streamError: error?.message ?? null }));
         current.timer = setTimeout(() => { current.timer = null; connect(key); }, jitter(delay));
-      },
-    }, undefined, taskId);
+    };
+    entry.stop = retire;
+    patchConv(key, (conv) => ({ ...conv, stream: entry.attempt ? "reconnecting" : "connecting", streamError: null }));
+    if (!active()) return;
+    try {
+      cleanup = client.stream(jobId, {
+        onOpen: () => { if (!active()) return; entry.attempt = 0; patchConv(key, (conv) => ({ ...conv, stream: "live", streamError: null })); },
+        onSnapshot: (snapshot) => { if (active()) patchConv(key, (conv) => applySnapshot(conv, snapshot)); },
+        onChunk: (items) => { if (active()) patchConv(key, (conv) => applyItems(conv, items)); },
+        onEnd: (end) => {
+          if (!active()) return;
+          ended = true;
+          const continuedBy = taskId ? (end.continued_by_job_id && end.continued_by_task_id ? convKey(end.continued_by_job_id, end.continued_by_task_id) : null) : end.continued_by_job_id ?? null;
+          patchConv(key, (conv) => ({ ...conv, stream: "ended", endReason: end.reason, continuedBy, nodeRunning: false }));
+          void refreshJob(jobId, true);
+        },
+        onClose: close,
+      }, undefined, taskId);
+      // Some custom transports close synchronously before returning cleanup.
+      if (retired || !owns()) {
+        const dispose = cleanup; cleanup = null;
+        notifyCallback(dispose ?? undefined, undefined);
+      }
+    } catch (error) {
+      close(error instanceof CenterError ? error : new CenterError(String(error), "NETWORK", 0));
+    }
   }
 
   // 网络恢复 / 标签页切回来时，正在退避等待的连接立刻重连，不用等完退避时间。
@@ -443,16 +502,22 @@ export function createCliStore(options: CliStoreOptions = {}) {
       void refreshJob(jobId);
       connect(key);
     }
+    const owned = entry;
+    let active = true;
     return () => {
+      if (!active) return;
+      active = false;
       const current = streams.get(key);
-      if (!current) return;
+      if (current !== owned) return;
       current.refs -= 1;
       if (current.refs > 0) return;
-      current.stop?.();
-      if (current.timer) clearTimeout(current.timer);
+      // Retire the registry before calling host cleanup: it may synchronously
+      // acquire a new lease for the same task.
       streams.delete(key);
+      if (current.timer) { clearTimeout(current.timer); current.timer = null; }
       syncLive();
-      patchConv(key, (conv) => ({ ...conv, stream: conv.stream === "ended" ? "ended" : "idle" }));
+      current.stop?.();
+      if (!streams.has(key)) patchConv(key, (conv) => ({ ...conv, stream: conv.stream === "ended" ? "ended" : "idle" }));
     };
   }
 
@@ -523,6 +588,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
         return target;
       }
       if (!key || !ref) {
+        const selectedBeforeCreate = state.selected;
         let newId: string;
         if (createConversation) {
           newId = await createConversation(text);
@@ -534,7 +600,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
         }
         addJob(newId);
         // 共享选中只由「跟着选中走」的组件改；传了 jobId、自己接管的对话组件新建对话不去动别人的选中。
-        if (overrides.select !== false) set({ selected: newId });
+        if (overrides.select !== false && state.selected === selectedBeforeCreate) set({ selected: newId });
         emit({ type: "job_change", jobId: newId, previousJobId: null, taskId: null, key: newId, previousKey: null });
         void refreshJob(newId, true);
         return newId;
@@ -666,7 +732,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
 
   function setRefs(key: string, refs: BoardRef[]) {
     const next = { ...state.refs };
-    if (refs.length) next[key] = refs; else delete next[key];
+    if (refs.length) next[key] = refs.map(ref => ({ ...ref })); else delete next[key];
     set({ refs: next });
     emit({ type: "board_ref", key, refs });
   }
@@ -723,15 +789,44 @@ export function createCliStore(options: CliStoreOptions = {}) {
   }
 
   // ── 看板现在的样子（给业务方：当前打开的文件等）────────
-  function reportBoard(key: string, view: BoardView | null, owner = "default") {
-    const top = latestReport(boardSources, key, owner, view ? { ...view, files: [...view.files] } : null);
-    const cur = state.boards[key];
-    if (!top && !cur) return;
-    if (top && cur && cur.tab === top.tab && cur.dir === top.dir && cur.file === top.file && cur.files.join("\n") === top.files.join("\n")) return;
-    const next = { ...state.boards };
-    if (top) next[key] = top; else delete next[key];
-    set({ boards: next });
-    emit({ type: "board_change", key, view: top ? { ...top, files: [...top.files] } : null });
+  function applyBoardSelection(key:string,top:BoardView|null,history:import("../board/workspace").BoardFile[]) {
+    const current=state.boards[key],previous=state.boardContext[key];
+    const boardChanged=JSON.stringify(top)!==JSON.stringify(current??null);
+    const retained=top?{...cloneBoardView(top),history,visible:top.visible!==false}:previous?{...cloneBoardView(previous),history,visible:false}:null;
+    const contextChanged=!!retained&&JSON.stringify(previous)!==JSON.stringify(retained);
+    if(!boardChanged&&!contextChanged)return;
+    const boards={...state.boards};if(top)boards[key]=cloneBoardView(top);else delete boards[key];
+    // Commit both public views before subscribers can read them or navigate again.
+    set({...(boardChanged?{boards}:{}),...(contextChanged?{boardContext:{...state.boardContext,[key]:retained!}}:{})});
+    if(boardChanged&&state.boards[key]===boards[key])emit({type:"board_change",key,view:top?cloneBoardView(top):null});
+    // A reentrant callback may already have selected a newer file. Do not emit
+    // or restore the older automatic context over that newer selection.
+    if(contextChanged&&state.boardContext[key]===retained)emit({type:"board_context",jobId:key,view:cloneBoardView(retained!)});
+  }
+  function reportBoard(key:string,view:BoardView|null,owner="default") {
+    const sources=boardSources.get(key)??new Map<string,BoardView>();
+    let history=state.boardContext[key]?.history??[];
+    if(view){history=mergeBoardHistory(history,sources.get(owner),view);reportBoardOwner(sources,owner,cloneBoardView(view));}
+    else sources.delete(owner);
+    if(sources.size)boardSources.set(key,sources);else boardSources.delete(key);
+    const top=selectedBoardOwner(sources)?.[1]??null;applyBoardSelection(key,top,history);
+  }
+  function activateBoard(key:string,owner:string) {
+    const sources=boardSources.get(key);if(!sources)return;
+    const top=activateBoardOwner(sources,owner)?.[1];if(!top)return;
+    const file=top.current??(top.file?{path:top.file,sourceId:key}:null);
+    const history=file?rememberBoardFile(state.boardContext[key]?.history??[],file):state.boardContext[key]?.history??[];
+    applyBoardSelection(key,top,history);
+  }
+  const fileSubscriptions = new Map<string,{listeners:Set<{change?:(event:WorkspaceChangeEvent)=>void;status?:WorkspaceWatchOptions['onStatus']}>;stop:()=>void;status?:WorkspaceWatchStatus}>();
+  function watchWorkspace(key:string,listener?:(event:WorkspaceChangeEvent)=>void,options:WorkspaceWatchOptions={}) {
+    if(!client.board) throw new Error("当前后端不支持工作区文件订阅");
+    const item={change:listener,status:options.onStatus};let subscription=fileSubscriptions.get(key);
+    if(!subscription){
+      subscription={listeners:new Set([item]),stop:()=>{}};fileSubscriptions.set(key,subscription);const owned=subscription;
+      owned.stop=subscribeWorkspaceFiles(client.board,key,event=>{emit(event);for(const next of [...owned.listeners])notifyCallback(next.change,cloneWorkspaceChange(event));},{...options,onStatus:status=>{owned.status=status;emit(status);for(const next of [...owned.listeners])notifyCallback(next.status,{...status});}});
+    }else{subscription.listeners.add(item);if(subscription.status)notifyCallback(item.status,{...subscription.status});retryWorkspaceFiles(client.board,key);}
+    const owned=subscription;let active=true;return()=>{if(!active)return;active=false;owned.listeners.delete(item);if(!owned.listeners.size){if(fileSubscriptions.get(key)===owned)fileSubscriptions.delete(key);owned.stop();}};
   }
 
   // ── 补充背景：业务方随时追加，随下一条消息发给智能体 ────────
@@ -764,7 +859,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
     if (next.length !== list.length) setContext(k, next);
   }
   /** 还没发出的补充背景。 */
-  const pendingContext = (key: string | null): ContextItem[] => [...(state.context[ctxKey(key)] ?? [])];
+  const pendingContext = (key: string | null): ContextItem[] => (state.context[ctxKey(key)] ?? []).map(item => ({ ...item }));
 
   function workspace(key?: string | null): CliWorkspace {
     const k = key ?? state.selected;
@@ -773,6 +868,8 @@ export function createCliStore(options: CliStoreOptions = {}) {
       backend: client.board,
       key: k,
       view: () => state.boards[k],
+      context: () => state.boardContext[k] ? cloneBoardView(state.boardContext[k]) : null,
+      watch: (listener, options) => watchWorkspace(k,listener,options),
       open: (path) => openInBoard(k, { kind: "file", path }),
     });
   }
@@ -795,13 +892,18 @@ export function createCliStore(options: CliStoreOptions = {}) {
 
   function openInBoard(jobId: string, target: OpenTarget): boolean {
     let handled = false;
-    for (let i = surfaces.length - 1; i >= 0 && !handled; i--) handled = surfaces[i](jobId, target);
+    for (const surface of [...surfaces].reverse()) {
+      try { handled = surface(jobId, { ...target }); }
+      catch (error) { console.error("[@spzxg/cli-ui] board surface callback failed", error); }
+      if (handled) break;
+    }
     emit({ type: "open", jobId, target, handled });
     return handled;
   }
 
   return {
     client,
+    draftScope: connectionDraftScope(options),
     getState: () => state,
     /** 在看板里打开文件 / 浏览器 / 改动。返回有没有看板接住。 */
     openInBoard,
@@ -821,11 +923,11 @@ export function createCliStore(options: CliStoreOptions = {}) {
     addRef, removeRef, takeRefs, restoreRefs,
     setViewing, dismissViewing, takeViewing, restoreViewing,
     /** 看板报告自己的样子（看板组件用）。 */
-    reportBoard,
+    reportBoard, activateBoard,
     /** 业务方追加项目背景：随下一条消息发给智能体。 */
     appendContext, removeContext, pendingContext,
     /** 工作区文件接口（不显示看板也能用）：列文件、读文件、下载、打包。不传 = 当前选中的对话。 */
-    workspace,
+    workspace, watchWorkspace,
     open, send, answerAsk, cancelTurn, close, loadOlder,
   };
 }
@@ -854,8 +956,4 @@ async function retryOnce<T>(fn: () => Promise<T>): Promise<T> {
   }
 }
 
-function uid() {
-  const cryptoObj = globalThis.crypto as Crypto | undefined;
-  if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
-  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-}
+const uid = clientId;

package/src/core/types.ts

@@ -43,7 +43,13 @@ export interface CenterTurn {
   queue_position?: number | null;
 }
 
-export interface CenterTask {
+/** 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;
@@ -63,7 +69,7 @@ export interface CenterTask {
 }
 
 /** 对话任务里的一个对话（一个子任务、一个 Agent 会话）。conversation.conversations 的一项。 */
-export interface ConversationInfo {
+export interface ConversationInfo extends AwaitingInputState {
   task_id: string;
   seq: number;
   title: string;
@@ -79,7 +85,7 @@ export interface ConversationInfo {
   created_at: string | null;
 }
 
-export interface ConversationSummary {
+export interface ConversationSummary extends AwaitingInputState {
   /** 里面的每个对话（按开的先后）。旧版 center 没有这个字段：当作只有一个对话。 */
   conversations?: ConversationInfo[];
   turns: number;
@@ -117,6 +123,12 @@ export interface SendResult {
   turn: CenterTurn;
 }
 
+/** 每次浏览器操作前的随机等待范围；合法范围由任务中心与节点共同校验。 */
+export interface BrowserPacing {
+  min_seconds: number;
+  max_seconds: number;
+}
+
 /** 新建对话时可带的参数（POST /api/jobs，mode=conversation）。 */
 export interface NewConversationOptions {
   title?: string;
@@ -127,6 +139,10 @@ export interface NewConversationOptions {
   agent?: string;
   timeoutSeconds?: number;
   browser?: boolean;
+  /** Ego 操作手册的 YAML 正文（不是文件名或 URL）；必须显式 browser:true。 */
+  browserPlaybook?: string;
+  /** 转发至节点执行器和浏览器脚本；必须显式 browser:true。 */
+  browserPacing?: BrowserPacing;
 }
 
 // ── Operator：节点转录 ─────────────────────────────────────────────
@@ -213,8 +229,8 @@ export type NodeEvent =
   | { type: "tool"; id: string; title: string; detail: string; peek?: ToolPeek; diff?: DiffLine[]; msgId?: string; generation?: number }
   | { type: "tool_result"; id: string; content: string; isError: boolean; peek?: ToolPeek; msgId?: string }
   | { type: "ask"; id: string; questions: AskQuestion[]; msgId?: string; generation?: number }
-  | { type: "ask_answered"; id: string; answers: AskAnswers; msgId?: string }
-  | { type: "input"; input: InputRequest; 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 }
@@ -233,7 +249,7 @@ export type StreamItem =
   | { type: "task"; task: StreamTask | BatchStreamTask };
 
 /** 实时流看的那个对话（GET /api/jobs/:id/stream?task=）。 */
-export interface StreamTask { id: string; seq: number; title: string; status: string; closed: boolean; remote_task_id: string | null; continue_from_task_id: string | null }
+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 };
@@ -246,7 +262,7 @@ export interface StreamSnapshot {
  * 一次性任务（含续派）的子任务，实时流里的样子。cli-chat 只读查看这类任务时用。
  * prompt / opener_prompt：指定了 ?task= 时看的那个子任务才有（opener_prompt = 开出它所在节点对话的那个子任务的原文）。
  */
-export interface BatchStreamTask {
+export interface BatchStreamTask extends AwaitingInputState {
   id: string;
   seq: number;
   task_key: string | null;
@@ -380,6 +396,8 @@ export interface FileEntry {
   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 }
@@ -424,15 +442,52 @@ export interface BrowserStatus {
 }
 
 /** 浏览器画面流里的一条消息（节点原样转发）。 */
-export type BrowserMessage =
+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" };
+  | { 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;
+}