dsh-code-server-app 0.3.20 → 0.3.22

package/lib/bridge-approval.mjs

@@ -0,0 +1,189 @@
+/**
+ * lib/bridge-approval.mjs — 让编辑器面板也能就地处理 DSH 的授权请求(0.3.22)。
+ *
+ * ## 为什么需要
+ * DSH 把"敏感动作需要人确认"收敛到 `@deepseek-ai/dsh-user-approval` 的 `approval` 服务:
+ * `approval/request` 是一个 **agent 作用域的 waterfall 事件**,答案方可以是服务端监听器,
+ * 也可以是通过 Remote 参与进来的**浏览器客户端**(官方 `ui-approval` 卡片,
+ * `packages/api/remotes/src/remote-events.ts:18` 把它注册为 waterfall 远程事件)。
+ * outcome 只有四种:`allowed-once | rejected | cancelled | unavailable`,**没有答案者就 fail closed**。
+ * 于是"从编辑器里提问"的场景会撞上一堵墙:agent 想**写工作区外的文件**或**执行命令**时,
+ * 授权卡片只出现在 DSH 界面里 —— 而用户人在编辑器,既看不到、也可能因为超时而失败关闭。
+ *
+ * ## 策略(先面板、后官方;绝不自动放行)
+ * 只对**被面板 watch 的会话**注册监听(`agent.ctx.on('approval/request', …)`,agent 作用域天然只收本会话):
+ *   1. 生成 pending 记录 → 面板随 `/sync` 的 `approvals` 字段看到卡片(工具名 / 原因 / 参数摘要);
+ *   2. 等面板决策,最多 `HOLD_MS`(默认 8s):
+ *      - 窗口内作答 → **返回该 outcome**(settle;官方卡片不出现,人在编辑器就地处理);
+ *      - 无人作答 / 面板没开 → `return next()`,**原样交给官方链路**(DSH 界面照旧弹卡);
+ *   3. 永不返回自动授权:`allowed-once` 只能来自用户点击。
+ *
+ * ## 安全
+ * 面板的决策只能通过桥的 `POST /approve` 进来(令牌 + 带 Origin 一律 403),而且:
+ *   - `id` 必须是**本进程发起、仍未决**的请求(单次使用,用后即废);
+ *   - outcome 只接受 `allowed-once` 与 `rejected` 两个白名单值;
+ *   - 不接受任何自由文本 / 路径 / 命令参数 —— 这条路由**只能回答既有的问题**,不能发起动作。
+ */
+
+/** 面板优先的等待窗口(毫秒);超过就交给官方链路。 */
+export const DEFAULT_HOLD_MS = 8000;
+
+/** 同时挂起的授权请求上限(超了直接交给官方,避免堆积)。 */
+export const MAX_PENDING = 4;
+
+/** 允许的面板决策值(白名单;其余一律拒绝)。 */
+export const PANEL_OUTCOMES = ['allowed-once', 'rejected'];
+
+/** 造一个 pending 注册表(纯逻辑,可单测)。 */
+export function createApprovalBoard({ holdMs = DEFAULT_HOLD_MS, maxPending = MAX_PENDING, now = () => Date.now() } = {}) {
+  /** requestId → {id, toolName, callId, reason, at, settle} */
+  const pending = new Map();
+
+  return {
+    size() {
+      return pending.size;
+    },
+    /** 面板要显示的待决列表(纯 JSON)。 */
+    snapshot() {
+      return [...pending.values()].map((item) => ({
+        id: item.id,
+        toolName: item.toolName,
+        callId: item.callId ?? null,
+        reason: item.reason ?? '',
+        at: item.at,
+      }));
+    },
+    get(id) {
+      return pending.get(id) ?? null;
+    },
+    /** 登记一条请求,返回它的 Promise(面板点击前一直挂着)。 */
+    open({ id, toolName, callId, reason }) {
+      if (typeof id !== 'string' || id === '' || pending.has(id)) return null;
+      if (pending.size >= maxPending) return null;
+      let settle;
+      const decision = new Promise((resolve) => { settle = resolve; });
+      pending.set(id, { id, toolName, callId: callId ?? null, reason: reason ?? '', at: now(), settle });
+      return decision;
+    },
+    /** 面板作答:只接受白名单值;未知 / 已决 → false。 */
+    answer(id, outcome) {
+      const item = typeof id === 'string' ? pending.get(id) : undefined;
+      if (item === undefined) return false;
+      if (!PANEL_OUTCOMES.includes(outcome)) return false;
+      pending.delete(id);
+      item.settle(outcome);
+      return true;
+    },
+    /** 窗口到点 / 面板关闭:把这条请求撤出面板(调用方随后 `next()` 交给官方)。 */
+    drop(id) {
+      const item = typeof id === 'string' ? pending.get(id) : undefined;
+      if (item === undefined) return false;
+      pending.delete(id);
+      item.settle(undefined);
+      return true;
+    },
+    /** 丢弃全部(卸载 / 面板关闭)。 */
+    clear() {
+      for (const id of [...pending.keys()]) this.drop(id);
+    },
+  };
+}
+
+/**
+ * 注册授权拦截。
+ *
+ * @param {object} deps
+ * @param {ReturnType<typeof createApprovalBoard>} deps.board
+ * @param {(message: string) => void} [deps.log]
+ * @param {number} [deps.holdMs]
+ * @param {() => boolean} deps.hasPanel 面板是否在看着(关掉时立刻交给官方,不做无谓等待)
+ * @returns {{intercept: (agent: object, sessionId: string) => () => void}}
+ */
+export function createApprovalInterceptor(deps) {
+  const board = deps.board;
+  const log = deps.log ?? (() => {});
+  const holdMs = deps.holdMs ?? DEFAULT_HOLD_MS;
+  const hasPanel = deps.hasPanel ?? (() => true);
+  /** agent → disposer(每个被 watch 的 agent 一个监听器) */
+  const registered = new Map();
+
+  async function handle(request, next) {
+    try {
+      // 面板没在看:完全不拦截,保持今天的行为。
+      if (!hasPanel()) return await next();
+      const id = typeof request?.id === 'string' ? request.id : null;
+      if (id === null) return await next();
+      const decision = board.open({
+        id,
+        toolName: typeof request.toolName === 'string' ? request.toolName : 'tool',
+        callId: request.callId ?? null,
+        reason: typeof request.reason === 'string' ? request.reason : '',
+      });
+      if (decision === null) {
+        // 上限已满 / id 重复:不抢,交给官方。
+        return await next();
+      }
+      let timer = null;
+      const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), holdMs);
+        if (typeof timer.unref === 'function') timer.unref();
+      });
+      const outcome = await Promise.race([decision, timeout]);
+      if (timer !== null) clearTimeout(timer);
+      if (typeof outcome === 'string' && PANEL_OUTCOMES.includes(outcome)) {
+        board.drop(id); // 幂等:answer() 已删过也没关系
+        log(`授权由编辑器面板决定:${request.toolName ?? 'tool'} → ${outcome}`);
+        return outcome;
+      }
+      board.drop(id);
+      log(`授权 ${request.toolName ?? 'tool'} 面板未作答(${holdMs}ms),交给 DSH 界面`);
+      return await next();
+    } catch (err) {
+      // 拦截器出问题绝不能把授权变成"放行":退回官方链路(它自己会 fail closed)。
+      log(`授权拦截异常,交回官方链路:${err && err.message ? err.message : String(err)}`);
+      return await next();
+    }
+  }
+
+  return {
+    /**
+     * 为某个 agent 注册拦截(agent 作用域 ⇒ 只收到该会话的请求)。
+     * @returns {() => void} disposer(永不抛)
+     */
+    intercept(agent, sessionId) {
+      if (agent === null || typeof agent !== 'object') return () => {};
+      const scope = agent.ctx ?? null;
+      if (scope === null || typeof scope.on !== 'function') return () => {};
+      if (registered.has(agent)) return registered.get(agent);
+      let dispose = () => {};
+      try {
+        const result = scope.on('approval/request', handle);
+        if (typeof result === 'function') dispose = result;
+      } catch (err) {
+        log(`注册授权拦截失败(${sessionId}):${err && err.message ? err.message : String(err)}`);
+        return () => {};
+      }
+      const wrapped = () => {
+        registered.delete(agent);
+        board.clear();
+        try {
+          dispose();
+        } catch {
+          // 注销失败无关正确性
+        }
+      };
+      registered.set(agent, wrapped);
+      log(`授权拦截已启用(会话 ${sessionId},面板优先 ${holdMs}ms,之后交给 DSH 界面)`);
+      return wrapped;
+    },
+    /** 当前注册的 agent 数(诊断 / 测试)。 */
+    size() {
+      return registered.size;
+    },
+    /** 全部撤销。 */
+    dispose() {
+      for (const dispose of [...registered.values()]) dispose();
+      registered.clear();
+    },
+  };
+}

package/lib/bridge-session.mjs

@@ -143,5 +143,7 @@ export async function deliverEditorPrompt(ctx, input) {
   const sessionId = agent.session !== undefined && agent.session !== null && typeof agent.session === 'object'
     ? (agent.session.id ?? agent.id ?? null)
     : (agent.id ?? null);
-  return { ok: true, sessionId, text };
+  // `agent` 是给调用方用的**内部句柄**(授权拦截要拿 `agent.ctx` 注册 agent 作用域监听),
+  // 路由返回前必须剥掉:它不可 JSON 序列化,也不该泄漏进编辑器。
+  return { ok: true, sessionId, text, agent };
 }

package/lib/bridge-thread.mjs

@@ -0,0 +1,345 @@
+/**
+ * lib/bridge-thread.mjs — 把「被面板观看的会话」投影成有界的对话条目流(0.3.22)。
+ *
+ * 方向:DSH → 编辑器。编辑器里的「问 DSH」面板要像 DSH 对话那样显示内容,数据来自
+ * **正规的实时通道** `sessionController.follow()`(冷安全:开帧给 `cursor`,之后是
+ * gap-free 的耐久事件帧 + 无游标的助手流帧)。
+ *
+ * 为什么不用别的(都核查过):
+ *   - 同步读会话历史(`Session.snapshotEvents/eventAt/ownEvents`)已被 DSH 明令禁止新增调用
+ *     (`.agents/notes/.../2026-09-09-deprecate-synchronous-session-event-reads.zh.md`);
+ *   - `sessionController.page()` 是**历史分页** —— 本版本按用户要求**只渲染新内容**,不调用它;
+ *   - 投影(`turnOutline` 等)只给有界预览(50/120 字符),不够渲染正文。
+ *
+ * `follow` 的帧形状(源码实证,`packages/api/session-controller/src/types.ts:515`):
+ *   | { type:'snapshot'; cursor; records[]; assistantStream? }   ← 开帧(历史,本版本**丢弃**)
+ *   | { type:'event'; event: SessionWireEvent }                  ← 耐久事件
+ *   | { type:'assistant-stream'; frame: { type:'start'|'chunk'; turn; chunk } }
+ *
+ * 有界:每会话 ≤ `MAX_ENTRIES` 条、单条正文 ≤ `MAX_TEXT`、同时 watch ≤ `MAX_WATCHED`(LRU + abort)。
+ */
+
+/** 每个会话保留的条目上限(丢最旧的;更早的内容本版本不提供)。 */
+export const MAX_ENTRIES = 120;
+
+/** 单条正文上限(超出截断并标注)。 */
+export const MAX_TEXT = 8000;
+
+/** 同时 watch 的会话上限。 */
+export const MAX_WATCHED = 4;
+
+/** 工具参数 / 原因摘要上限。 */
+export const MAX_SUMMARY = 160;
+
+/** 截断到上限并标注。 */
+function clip(text, limit = MAX_TEXT) {
+  if (typeof text !== 'string') return '';
+  return text.length > limit ? `${text.slice(0, limit)}…(已截断)` : text;
+}
+
+/** 从消息内容块里取正文(text 块拼接;reasoning / tool-call 不进面板)。 */
+export function textOfContent(content) {
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const block of content) {
+    if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+      parts.push(block.text);
+    }
+  }
+  return clip(parts.join(''));
+}
+
+/** 工具调用摘要:从原始 JSON 参数里抽一个最有信息量的字段(路径 / 命令首行)。 */
+export function summarizeToolArguments(rawArguments) {
+  if (typeof rawArguments !== 'string' || rawArguments.trim() === '') return '';
+  let args;
+  try {
+    args = JSON.parse(rawArguments);
+  } catch {
+    return clip(rawArguments, MAX_SUMMARY);
+  }
+  if (args === null || typeof args !== 'object' || Array.isArray(args)) return '';
+  for (const key of ['file_path', 'path', 'command', 'pattern', 'query', 'url', 'prompt']) {
+    const value = args[key];
+    if (typeof value === 'string' && value.trim() !== '') return clip(value.split('\n')[0], MAX_SUMMARY);
+  }
+  const keys = Object.keys(args);
+  return keys.length === 0 ? '' : clip(keys.slice(0, 4).join(', '), MAX_SUMMARY);
+}
+
+/** 一个会话的投影状态(纯数据,便于单测)。 */
+export function createThreadState(sessionId) {
+  return {
+    sessionId,
+    entries: [],
+    /** tool/call 的 callId → entries 下标(用于 result 回填)。 */
+    callIndex: new Map(),
+    /** 流式条目在 entries 里的下标(没有则 null)。 */
+    streamingIndex: null,
+    /** 流式条目属于哪一轮;换轮时新建条目。 */
+    streamingTurn: null,
+    error: null,
+  };
+}
+
+/** 重建 callId / 流式条目索引(条目数很小,整表扫一遍最不容易错)。 */
+function rebuildIndex(state) {
+  state.callIndex.clear();
+  state.streamingIndex = null;
+  for (let i = 0; i < state.entries.length; i += 1) {
+    const item = state.entries[i];
+    if (item.callId !== undefined) state.callIndex.set(String(item.callId), i);
+    if (item.streaming === true) state.streamingIndex = i;
+  }
+}
+
+/** 追加一条条目;超上限时丢最旧。 */
+function push(state, entry) {
+  state.entries.push(entry);
+  if (state.entries.length > MAX_ENTRIES) state.entries.shift();
+  rebuildIndex(state);
+  return state.entries.length - 1;
+}
+
+/** 助手流帧(SessionAssistantStreamFrame):只取正文 text-delta。 */
+export function applyStreamFrame(state, frame) {
+  if (frame === null || typeof frame !== 'object' || frame.type !== 'chunk') return false;
+  const chunk = frame.chunk;
+  if (chunk === null || typeof chunk !== 'object' || chunk.type !== 'text-delta' || typeof chunk.text !== 'string') return false;
+  const turn = Number.isSafeInteger(frame.turn) ? frame.turn : null;
+  if (state.streamingIndex !== null && state.streamingTurn === turn) {
+    const current = state.entries[state.streamingIndex];
+    current.text = clip(current.text + chunk.text);
+    return true;
+  }
+  state.streamingIndex = push(state, { role: 'assistant', text: clip(chunk.text), streaming: true });
+  state.streamingTurn = turn;
+  return true;
+}
+
+/**
+ * 把一个会话事件投影进状态。
+ * @param {ReturnType<typeof createThreadState>} state
+ * @param {{type: string, seq?: number, data?: object}} event `SessionWireEvent`
+ * @returns {boolean} 是否变化
+ */
+export function applyEvent(state, event) {
+  if (state === null || event === null || typeof event !== 'object') return false;
+  const data = event.data ?? {};
+
+  if (event.type === 'user/message') {
+    const text = textOfContent(data.content);
+    if (text === '') return false;
+    push(state, { role: 'user', text });
+    return true;
+  }
+
+  if (event.type === 'assistant/message') {
+    const text = textOfContent(data.message?.content);
+    const streamingIndex = state.streamingIndex;
+    state.streamingIndex = null;
+    state.streamingTurn = null;
+    if (streamingIndex !== null && state.entries[streamingIndex] !== undefined) {
+      // 耐久消息落地:原地替换同一轮的流式临时条目(不重复显示,顺序也不变)。
+      if (text === '') {
+        state.entries.splice(streamingIndex, 1);
+        rebuildIndex(state);
+        return true;
+      }
+      state.entries[streamingIndex] = { role: 'assistant', text };
+      rebuildIndex(state);
+      return true;
+    }
+    if (text === '') return false;
+    push(state, { role: 'assistant', text });
+    return true;
+  }
+
+  if (event.type === 'tool/call') {
+    const callId = typeof data.callId === 'string' ? data.callId : undefined;
+    const index = push(state, {
+      role: 'tool',
+      callId,
+      name: typeof data.name === 'string' ? data.name : 'tool',
+      summary: summarizeToolArguments(data.arguments),
+      status: 'running',
+    });
+    if (callId !== undefined) state.callIndex.set(callId, index);
+    return true;
+  }
+
+  if (event.type === 'tool/result') {
+    const callId = data.message?.source?.callId;
+    const index = callId === undefined ? undefined : state.callIndex.get(String(callId));
+    if (index === undefined) return false;
+    const block = Array.isArray(data.message?.content) ? data.message.content[0] : undefined;
+    state.entries[index].status = block !== undefined && block.isError === true ? 'error' : 'ok';
+    return true;
+  }
+
+  // 授权审计(会话事件,log-only):面板据此显示"已授权一次 / 已拒绝"。
+  if (event.type === 'approval/asked') {
+    push(state, {
+      role: 'approval',
+      approvalId: typeof data.id === 'string' ? data.id : undefined,
+      toolName: typeof data.toolName === 'string' ? data.toolName : 'tool',
+      summary: typeof data.reason === 'string' ? clip(data.reason, MAX_SUMMARY) : '',
+      status: 'asked',
+    });
+    return true;
+  }
+
+  if (event.type === 'approval/decided') {
+    const id = typeof data.id === 'string' ? data.id : undefined;
+    for (let i = state.entries.length - 1; i >= 0; i -= 1) {
+      const item = state.entries[i];
+      if (item.role === 'approval' && (id === undefined || item.approvalId === id)) {
+        item.status = typeof data.outcome === 'string' ? data.outcome : 'unavailable';
+        return true;
+      }
+    }
+    return false;
+  }
+
+  return false;
+}
+
+/**
+ * 收一帧 `follow` 输出。
+ * 开帧(`snapshot`)只取 `cursor` 与助手流基线 —— 历史记录按"只渲染新内容"丢弃。
+ */
+export function consumeFrame(state, frame) {
+  if (state === null || frame === null || typeof frame !== 'object') return false;
+  if (frame.type === 'snapshot') {
+    state.cursor = Number.isSafeInteger(frame.cursor) ? frame.cursor : state.cursor ?? 0;
+    return false; // 不渲染历史
+  }
+  if (frame.type === 'assistant-stream') return applyStreamFrame(state, frame.frame);
+  if (frame.type === 'event') return applyEvent(state, frame.event);
+  // 兼容:调用方直接喂会话事件(测试与降级路径)
+  if (typeof frame.type === 'string' && frame.data !== undefined) return applyEvent(state, frame);
+  return false;
+}
+
+/** 给 `/sync` 的快照(纯 JSON)。 */
+export function threadSnapshot(state) {
+  return {
+    cursor: Number.isSafeInteger(state.cursor) ? state.cursor : null,
+    entries: state.entries.map((entry) => ({
+      role: entry.role,
+      text: entry.text ?? null,
+      streaming: entry.streaming === true,
+      name: entry.name ?? null,
+      callId: entry.callId ?? null,
+      summary: entry.summary ?? null,
+      status: entry.status ?? null,
+      approvalId: entry.approvalId ?? null,
+    })),
+  };
+}
+
+/**
+ * watch 注册表。
+ *
+ * @param {{resolveController: () => object|undefined, log?: (message: string) => void,
+ *          maxWatched?: number}} deps `resolveController()` 每次现取(host 侧一律 `ctx.get`)。
+ */
+export function createThreadRegistry(deps) {
+  const log = deps.log ?? (() => {});
+  const maxWatched = deps.maxWatched ?? MAX_WATCHED;
+  /** sessionId → {state, abort} */
+  const watched = new Map();
+
+  function controller() {
+    try {
+      return deps.resolveController();
+    } catch (err) {
+      log(`取 sessionController 失败:${err && err.message ? err.message : String(err)}`);
+      return undefined;
+    }
+  }
+
+  function unwatch(sessionId) {
+    const entry = watched.get(sessionId);
+    if (entry === undefined) return false;
+    watched.delete(sessionId);
+    try {
+      entry.abort.abort();
+    } catch {
+      // abort 失败不影响正确性
+    }
+    return true;
+  }
+
+  async function run(sessionId, entry, signal) {
+    try {
+      const service = entry.service;
+      const stream = service.follow(
+        { address: { kind: 'session', sessionId }, maxMessages: 50, assistantStream: true },
+        signal,
+      );
+      for await (const frame of stream) {
+        if (signal.aborted) break;
+        consumeFrame(entry.state, frame);
+      }
+    } catch (err) {
+      if (!signal.aborted) {
+        entry.state.error = `会话订阅失败:${err && err.message ? err.message : String(err)}`;
+        log(`会话 ${sessionId} 订阅结束:${entry.state.error}`);
+      }
+    }
+  }
+
+  function watch(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId === '') return false;
+    if (watched.has(sessionId)) return true;
+    const service = controller();
+    if (service === undefined || typeof service.follow !== 'function') return false;
+    while (watched.size >= maxWatched) {
+      const oldest = watched.keys().next().value;
+      log(`watch 超过 ${maxWatched} 个,丢弃最旧的会话 ${String(oldest)}`);
+      unwatch(oldest);
+    }
+    const abort = new AbortController();
+    const entry = { service, state: createThreadState(sessionId), abort };
+    watched.set(sessionId, entry);
+    void run(sessionId, entry, abort.signal);
+    return true;
+  }
+
+  return {
+    watch,
+    unwatch,
+    /** 按扩展声明的 watch 列表对齐(多余的停止、缺的建立)。 */
+    sync(sessionIds) {
+      if (!Array.isArray(sessionIds)) return;
+      const wanted = new Set(sessionIds.filter((id) => typeof id === 'string' && id !== ''));
+      for (const id of [...watched.keys()]) if (!wanted.has(id)) unwatch(id);
+      for (const id of wanted) watch(id);
+    },
+    /** 快照:返回面板关心的那个会话(数组首个);没 watch 到就返回空壳。 */
+    snapshot(sessionIds) {
+      const wanted = Array.isArray(sessionIds) ? sessionIds : [...watched.keys()];
+      for (const id of wanted) {
+        const entry = watched.get(id);
+        if (entry !== undefined) {
+          return { available: true, sessionId: id, ...threadSnapshot(entry.state), error: entry.state.error ?? null };
+        }
+      }
+      return { available: watched.size > 0, sessionId: null, cursor: null, entries: [], error: null };
+    },
+    /** 有没有可用的会话服务(面板据此区分"宿主没能力"与"没在 watch")。 */
+    supported() {
+      const service = controller();
+      return service !== undefined && typeof service.follow === 'function';
+    },
+    /** 该会话是否在 watch 中(授权拦截据此判断"面板是否在看")。 */
+    isWatched(sessionId) {
+      return watched.has(sessionId);
+    },
+    /** 卸载:abort 全部订阅。 */
+    dispose() {
+      for (const id of [...watched.keys()]) unwatch(id);
+    },
+  };
+}

package/lib/bridge.mjs

@@ -31,13 +31,22 @@
  *
  * ## 安全不变量(改这个文件之前先读这四条)
  *
- * 1. **`BRIDGE_BASE`(`/code-server-bridge`)命名空间永久只读。** 不允许出现任何写文件、改文档、执行命令、
- *    拉起进程的路由 —— `bridge.json` 里那个令牌对本机同用户进程可读,爆炸半径必须封在
- *    "泄露编辑器里的信息",绝不能变成任意文件写 / 任意命令执行。
- * 2. **带 `Origin` 的请求一律 403。** 浏览器发起的请求必带 Origin,扩展宿主进程不带。
+ * 1. **`BRIDGE_BASE`(`/code-server-bridge`)命名空间只读**,只有一个写例外:`POST /approve`
+ *    (0.3.22,见下)。其余一律不允许出现写文件、改文档、执行命令、拉起进程的路由 ——
+ *    `bridge.json` 里那个令牌对本机同用户进程可读,爆炸半径必须封在"泄露编辑器里的信息",
+ *    绝不能变成任意文件写 / 任意命令执行。
+ * 2. **`/approve` 的四条约束(缺一条就等于开了任意命令执行的后门,不许放宽)**:
+ *    (a) 它只能**回答**已经存在的授权请求,不能发起任何动作 —— 请求体只有 `{id, outcome}`,
+ *        不接受自由文本 / 路径 / 命令参数;
+ *    (b) `id` 必须是本进程自己发起、且**仍未决**的请求(用后即废,单次使用);
+ *    (c) `outcome` 只接受 `allowed-once` / `rejected` 两个白名单值,没有"永久允许";
+ *    (d) 没有面板在看 / 窗口超时(默认 8s)→ **交回官方链路**,绝不自动放行(DSH 的
+ *        `approval/request` 本身 fail closed,这里只能把"没人答"保持成"没人答")。
+ * 3. **带 `Origin` 的请求一律 403。** 浏览器发起的请求必带 Origin,扩展宿主进程不带。
  *    这条只排除浏览器,不误伤扩展(也顺带挡住 CSRF / DNS rebinding 这类"用你的浏览器打本机端口")。
- * 3. **路径收敛在编辑器当前工作区**(由扩展侧 `workspace.getWorkspaceFolder` 判定)。
- * 4. **有界。** 事件缓冲 64 条、请求/响应体上限见下方常量。
+ * 4. **路径收敛在编辑器当前工作区**(由扩展侧 `workspace.getWorkspaceFolder` 判定)。
+ * 5. **有界。** 事件缓冲 64 条、请求/响应体上限见下方常量;对话流每会话 ≤120 条、单条正文 ≤8000 字符、
+ *    同时 watch ≤4 个会话,待决授权 ≤4 条(见 lib/bridge-thread.mjs / lib/bridge-approval.mjs)。
  */
 
 import { randomBytes, timingSafeEqual } from 'node:crypto';