@zhushanwen/pi-subagent-workflow 0.2.0 → 0.3.0

package/src/execution/ui-channels.ts

@@ -0,0 +1,216 @@
+// src/execution/ui-channels.ts
+//
+// UI channel 提取（marker 解析）+ channel 注册表。
+//
+// channel 是扩展协议自定义的业务路由标识，由 NUL 前缀 marker 标记。
+// 已知 marker（来自 @xyz-agent/extension-protocol）：
+//   - ASK_USER_MARKER   = "\0XYZ_ASK_USER"     走 select method，出现在 title
+//     （options[0] = JSON payload {questions, allowCancel}）
+//   - GUI_WIDGET_MARKER = "\0XYZ_GUI_WIDGET:"  走 setWidget method，出现在 widgetLines[0]
+//     （同行 marker 后紧跟 JSON payload {component}）
+//
+// channel 提取位置随 method 变（.fix-plans/00-master-summary.md §一冲突 2）：
+//   - select   → 从 title 解析 NUL 前缀（payload 从 options[0] 取）
+//   - setWidget → 从 widgetLines[0] 解析 NUL 前缀（payload 从同行 marker 后取）
+//   - 其他 method → 无 channel（返回 {}）
+//
+// channel 名规范化：去 "XYZ_" 命名空间前缀，去尾部 ":"，小写化。
+//   XYZ_ASK_USER   → ask_user
+//   XYZ_GUI_WIDGET → gui_widget
+//
+// 本模块是协议层工具（method/marker 都是协议概念），不感知业务。
+
+/** NUL 前缀字符。Pi extension-protocol 用 NUL（\0）标记控制行，
+ *  避免与用户可见文本冲突。 */
+const NUL = "\0";
+
+/** channel 提取结果。channel 无 NUL 前缀、字段缺失、JSON parse 失败时
+ *  channel 与 channelPayload 均为 undefined（返回 {}）。 */
+export interface ParsedChannel {
+  /** 规范化后的 channel 名（如 "ask_user"、"gui_widget"）。
+   *  无 marker 或解析失败时为 undefined。 */
+  channel?: string;
+  /** marker 标记的结构化 payload（已 JSON.parse）。
+   *  ask_user: {questions, allowCancel}；gui_widget: {component}。
+   *  payload 来源缺失或 JSON parse 失败时为 undefined（channel 仍可解析）。 */
+  channelPayload?: unknown;
+}
+
+/** parseChannel 入参的最小形状。
+ *  method 是判别字段；按 method 不同，对应字段（select 的 title/options、
+ *  setWidget 的 widgetLines）可选出现。其他 method 的字段统称 [key:string]。 */
+export interface ExtensionUiRequestLike {
+  method: string;
+  /** select method：title 字段（可能含 ASK_USER_MARKER NUL 前缀）。 */
+  title?: string;
+  /** select method：options 数组（options[0] 可能是 channel payload 的 JSON）。 */
+  options?: string[];
+  /** setWidget method：widgetKey 字段。 */
+  widgetKey?: string;
+  /** setWidget method：widgetLines 数组（widgetLines[0] 可能含 GUI_WIDGET_MARKER）。 */
+  widgetLines?: string[] | undefined;
+  /** 其他 method 的任意字段（容错：允许测试和未来扩展传入额外字段）。 */
+  [key: string]: unknown;
+}
+
+/** channel handler 签名：接收 UiRequest，返回 UiResponse。
+ *  具体类型定义在 session-runner.ts（W2 工作），此处用最小形状避免循环依赖。
+ *  handler 实现方按 channel 注册，由 session-runner 按 req.channel 分派。 */
+export type ChannelHandler = (req: unknown) => Promise<unknown>;
+
+/** channel 注册表接口。职责单一：只管业务路由，不管排队、不管透传判定。
+ *  - register(channel, handler)：注册 channel 对应的 handler（同名覆盖）
+ *  - resolve(channel)：取 channel 对应的 handler，未注册返回 undefined
+ *  - list()：列举所有已注册 channel 名 */
+export interface UiChannelRegistry {
+  register(channel: string, handler: ChannelHandler): void;
+  resolve(channel: string): ChannelHandler | undefined;
+  list(): string[];
+}
+
+/** 规范化 channel 名。
+ *  输入是 NUL 前缀后的字面量（如 "XYZ_ASK_USER"、"XYZ_GUI_WIDGET:"）。
+ *  规则：
+ *    1. 去 "XYZ_" 命名空间前缀（协议命名空间标识，非业务语义）
+ *    2. 去尾部 ":"（GUI_WIDGET 等"行内 payload"型 marker 的分隔符）
+ *    3. 小写化（XYZ_ASK_USER → ask_user）
+ *
+ *  例：
+ *    "XYZ_ASK_USER"    → "ask_user"
+ *    "XYZ_GUI_WIDGET:" → "gui_widget"
+ *    "FOO_BAR"         → "foo_bar"（无 XYZ_ 前缀也容忍，去前缀仅当字面量以 XYZ_ 开头） */
+function normalizeChannelName(markerLiteral: string): string {
+  let name = markerLiteral;
+  // 去 "XYZ_" 命名空间前缀（仅当以此开头）
+  if (name.startsWith("XYZ_")) {
+    name = name.slice("XYZ_".length);
+  }
+  // 去尾部 ":"（行内 payload 型 marker 的分隔符）
+  if (name.endsWith(":")) {
+    name = name.slice(0, -1);
+  }
+  return name.toLowerCase();
+}
+
+/** 从 marker 字面量字符串解析 channel 名。
+ *  输入 str 形如 "\0XYZ_ASK_USER"（marker 占满整个字段，payload 在别处）。
+ *  无 NUL 前缀返回 undefined。 */
+function parseMarkerFromField(str: string): string | undefined {
+  if (!str.startsWith(NUL)) return undefined;
+  // 去掉 NUL 前缀，取剩余字面量作为 marker literal
+  const literal = str.slice(NUL.length);
+  if (literal === "") return undefined;
+  return normalizeChannelName(literal);
+}
+
+/** 从 marker + 行内 payload 字符串解析 channel 名 + payload。
+ *  输入 str 形如 "\0XYZ_GUI_WIDGET:{...json...}"（marker 与 payload 在同一行）。
+ *  无 NUL 前缀返回 undefined。
+ *  payload 解析失败时不抛（返回 channel 名，payload 由调用方处理）。 */
+function parseInlineMarkerFromField(str: string): { channel: string } | undefined {
+  if (!str.startsWith(NUL)) return undefined;
+  const rest = str.slice(NUL.length);
+  // marker literal 与 payload 的分界：第一个 ":" 或行尾
+  // GUI_WIDGET_MARKER 格式为 "\0XYZ_GUI_WIDGET:" + json，分界是 ":"
+  const colonIdx = rest.indexOf(":");
+  let literal: string;
+  if (colonIdx >= 0) {
+    literal = rest.slice(0, colonIdx + 1); // 含 ":"，normalizeChannelName 会去尾部 ":"
+  } else {
+    literal = rest;
+  }
+  if (literal === "") return undefined;
+  return { channel: normalizeChannelName(literal) };
+}
+
+/** 从 select.title 解析 channel（payload 从 options[0] 取）。
+ *  - title 无 NUL 前缀 → undefined
+ *  - title 含 marker → channel 名；payload 从 options[0] JSON.parse（失败/缺失 → undefined） */
+function parseFromMarkerString(
+  title: string | undefined,
+  options: string[] | undefined,
+): ParsedChannel {
+  if (title === undefined) return {};
+  const channel = parseMarkerFromField(title);
+  if (channel === undefined) return {};
+  // payload 从 options[0] 取（ask_user 协议：title 是 marker，options[0] 是 JSON payload）
+  let payload: unknown;
+  if (options !== undefined && options.length > 0) {
+    try {
+      payload = JSON.parse(options[0]);
+    } catch {
+      payload = undefined; // JSON parse 失败：不抛，channel 仍解析
+    }
+  }
+  return { channel, channelPayload: payload };
+}
+
+/** 从 setWidget.widgetLines[0] 解析 channel（payload 从同行 marker 后取）。
+ *  - widgetLines 缺失/空数组/首行无 NUL 前缀 → undefined
+ *  - 首行含 marker → channel 名；payload 从 marker 后的 JSON 取（失败 → undefined） */
+function parseFromMarkerArray(
+  widgetLines: string[] | undefined,
+): ParsedChannel {
+  if (widgetLines === undefined || widgetLines.length === 0) return {};
+  const firstLine = widgetLines[0];
+  if (typeof firstLine !== "string") return {};
+  const parsed = parseInlineMarkerFromField(firstLine);
+  if (parsed === undefined) return {};
+  // payload 从 marker 后的 JSON 取（GUI_WIDGET 协议：marker 与 payload 同行）
+  let payload: unknown;
+  const rest = firstLine.slice(NUL.length);
+  const colonIdx = rest.indexOf(":");
+  if (colonIdx >= 0) {
+    const jsonStr = rest.slice(colonIdx + 1);
+    if (jsonStr !== "") {
+      try {
+        payload = JSON.parse(jsonStr);
+      } catch {
+        payload = undefined; // JSON parse 失败：不抛，channel 仍解析
+      }
+    }
+  }
+  return { channel: parsed.channel, channelPayload: payload };
+}
+
+/** 按 method 分派解析 channel。
+ *
+ *  - select → 从 title 解析 NUL 前缀（payload 从 options[0]）
+ *  - setWidget → 从 widgetLines[0] 解析 NUL 前缀（payload 从同行 marker 后）
+ *  - 其他 method → {}（无 channel 提取位置）
+ *
+ *  边界（均不抛错）：
+ *    - title/widgetLines 字段缺失 → {}
+ *    - 无 NUL 前缀 → {}
+ *    - JSON parse 失败 → channel 仍解析，channelPayload 为 undefined
+ *
+ *  @param req ExtensionUiRequestLike（method + 对应字段）
+ *  @returns ParsedChannel（channel/channelPayload 可选） */
+export function parseChannel(req: ExtensionUiRequestLike): ParsedChannel {
+  switch (req.method) {
+    case "select":
+      return parseFromMarkerString(req.title, req.options);
+    case "setWidget":
+      return parseFromMarkerArray(req.widgetLines);
+    default:
+      return {};
+  }
+}
+
+/** 创建 channel 注册表实例。
+ *  进程级单例（通常由 SubagentService 持有一个实例，跨所有子进程共享）。
+ *  register 同名 channel 会覆盖旧 handler。 */
+export function createUiChannelRegistry(): UiChannelRegistry {
+  const handlers = new Map<string, ChannelHandler>();
+  return {
+    register(channel: string, handler: ChannelHandler): void {
+      handlers.set(channel, handler);
+    },
+    resolve(channel: string): ChannelHandler | undefined {
+      return handlers.get(channel);
+    },
+    list(): string[] {
+      return Array.from(handlers.keys());
+    },
+  };
+}

package/src/execution/ui-interaction-model.ts

@@ -0,0 +1,48 @@
+// src/execution/ui-interaction-model.ts
+//
+// Pi ctx.ui method 的交互模型分类。
+//
+// 固化 Pi rpc-mode.ts（--mode rpc 子进程的 ctx.ui 实现）中 10 个会发
+// extension_ui_request 的 method 的交互模型分类，供 session-runner 决定：
+//   - 是否透传到主进程 handler（dialog 类才透传，fire-and-forget 不透传）
+//   - 是否进 L2 全局串行队列（dialog 类才排队，争输入焦点）
+//
+// 分类依据（.fix-plans/00-master-summary.md §一冲突 2「维度 1」）：
+//
+//   | 交互模型 | method | 行为 | 子进程不回会怎样 |
+//   |---|---|---|---|
+//   | dialog（占输入焦点，等响应） | select confirm input editor |
+//     子进程在 pendingExtensionRequests 注册 Promise 等 id 对应 response |
+//     Promise 永挂 + 内存泄漏 |
+//   | fire-and-forget（纯展示/写入，不等响应） |
+//     notify setStatus setWidget setTitle set_editor_text | output() 完即返回 |
+//     无影响 |
+//
+// 未知 method 默认按 fire-and-forget 处理（保守：不透传、不排队），
+// 避免 Pi 未来新增 method 时误判为 dialog 导致不必要的串行。
+
+/** dialog 类 method 集合：占输入焦点、等响应、需透传 + 排队。
+ *  与 Pi rpc-mode.ts 的 pendingExtensionRequests 注册逻辑一一对应。 */
+const DIALOG_METHODS: ReadonlySet<string> = new Set([
+  "select",
+  "confirm",
+  "input",
+  "editor",
+]);
+
+/** 判断 method 是否为 dialog 类（占输入焦点，等响应）。
+ *
+ *  dialog 类（select/confirm/input/editor）：
+ *    - 子进程在 pendingExtensionRequests 注册 Promise 等对应 id 的 response
+ *    - 主进程必须透传 + 进 L2 全局串行队列（争输入焦点）
+ *    - 不响应会导致子进程 Promise 永挂 + 内存泄漏
+ *
+ *  fire-and-forget 类（notify/setStatus/setWidget/setTitle/set_editor_text 及未知 method）：
+ *    - 子进程 output() 完即返回，不注册 pending
+ *    - 默认不透传（TUI 下不影响输入交互），不排队
+ *
+ *  @param method Pi rpc-types.ts 的 method 字段值
+ *  @returns dialog 类返回 true，fire-and-forget 类（含未知 method）返回 false */
+export function isDialogMethod(method: string): boolean {
+  return DIALOG_METHODS.has(method);
+}

package/src/execution/ui-request-handler-factory.ts

@@ -0,0 +1,175 @@
+// src/execution/ui-request-handler-factory.ts
+//
+// UI 请求 handler 工厂（透传 + 排队总控）。
+//
+// 按 ctx.mode（ExtensionMode）创建合适的 UiRequestHandler，让 SubagentService 持有后
+// 经 session-runner 透传给子进程的 extension_ui_request。本模块是「handler 注入链路」的
+// 组装点：把 channel registry（业务路由）+ dialog queue（L2 跨子进程串行）+ mode 分流
+//（TUI/GUI/headless）粘合成一个 handler。
+//
+// 设计依据（.fix-plans/00-master-summary.md）：
+//   - §一冲突 2「透传矩阵」：
+//       TUI  dialog 透传 + L2 排队；fire-and-forget 不透传（回 ack，不影响 TUI 输入交互）
+//       GUI  全透传；dialog 走 L2 排队，fire-and-forget 直接转发
+//       headless  不注入（返回 undefined）
+//   - §一冲突 3「L2 队列接入点」：dialog 类进 dialogQueue.enqueue 串行
+//   - §二 2.7「handler 工厂 + 透传/排队总控」：createUiRequestHandlerForMode 完整实现
+//
+// SR-3：调用方（index.ts session_start）无论 new 还是 existing SubagentService 都必须调
+//   setUiRequestHandler——/resume /fork 复用 existingService 时旧 handler 可能已失效。
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { DialogGlobalQueue, type UiRequest, type UiRequestHandler, type UiResponse } from "./dialog-queue.ts";
+import { type HostMode, resolveHostMode } from "./host-mode.ts";
+import type { UiChannelRegistry } from "./ui-channels.ts";
+import { isDialogMethod } from "./ui-interaction-model.ts";
+
+/** 按 ctx.mode 创建 UI 请求 handler（透传 + 排队总控）。
+ *
+ *  透传矩阵（§一冲突 2）：
+ *    - headless（json/print/undefined）：返回 undefined（不注入任何 UI handler）
+ *    - TUI：dialog 透传 + L2 排队；fire-and-forget 回 ack 不透传（不影响 TUI 输入交互）
+ *    - GUI（rpc）：全透传；dialog 走 L2 排队，fire-and-forget 直接转发
+ *
+ *  业务路由（§一冲突 2 维度 2）：
+ *    - channel 命中 registry（ask_user/gui_widget）→ 走注册的 channel handler
+ *    - 无 channel 的 dialog → defaultDialogForward（调主 agent ctx.ui.select/confirm/...）
+ *
+ *  SR-3：调用方（index.ts session_start）无论 new 还是 existing SubagentService 都必须调
+ *  setUiRequestHandler。headless 下本函数返回 undefined，调用方应据此走不注入路径。
+ *
+ *  @param ctx Pi ExtensionContext（读 ctx.mode 分流）
+ *  @param registry channel 注册表（业务路由；W3 当前为空，ask-user 扩展 Stage 4a 注册）
+ *  @param dialogQueue L2 跨子进程全局 dialog 串行队列
+ *  @returns UiRequestHandler（tui/gui）；headless 返回 undefined */
+export function createUiRequestHandlerForMode(
+  ctx: ExtensionContext,
+  registry: UiChannelRegistry,
+  dialogQueue: DialogGlobalQueue,
+): UiRequestHandler | undefined {
+  const hostMode = resolveHostMode(ctx.mode);
+  if (hostMode === "headless") return undefined;
+
+  const realHandler = createRealHandler(ctx, hostMode, registry);
+
+  return async (req: UiRequest): Promise<UiResponse> => {
+    // 维度 1：TUI 下 fire-and-forget 不透传（回 ack，不写 stdin——由 session-runner respond 处理）
+    if (hostMode === "tui" && !isDialogMethod(req.method)) {
+      return { ack: true };
+    }
+    // L2 全局队列：dialog 类必须串行（争输入焦点）。fire-and-forget（GUI 下）直接转发。
+    // [SR-4] 透传 req._childPid（session-runner 从 child.pid 填入）给 enqueue——
+    //   L2 据此关联 child close 时的 rejectChildDialogs 批量 reject（防全局死锁）。
+    if (isDialogMethod(req.method)) {
+      return dialogQueue.enqueue(req, realHandler, {
+        child: req._childPid !== undefined ? { pid: req._childPid } : undefined,
+      });
+    }
+    // GUI 下 fire-and-forget 直接转发
+    return realHandler(req);
+  };
+}
+
+/** 创建实际处理请求的 handler（channel 路由 + 默认转发）。
+ *  - channel 命中 registry（ask_user）→ channel handler（结果经 coerceUiResponse 形变）
+ *  - 无 channel 的 dialog → defaultDialogForward（主 agent ctx.ui.*） */
+function createRealHandler(
+  ctx: ExtensionContext,
+  _hostMode: HostMode,
+  registry: UiChannelRegistry,
+): UiRequestHandler {
+  return async (req: UiRequest): Promise<UiResponse> => {
+    // 维度 2：channel 业务路由。channel handler 签名是 (unknown)=>Promise<unknown>
+    //（ui-channels.ts 定义，避免循环依赖），此处经 coerceUiResponse 形变为 UiResponse。
+    const channelHandler = registry.resolve(req.channel ?? "");
+    if (channelHandler) {
+      const raw = await channelHandler(req);
+      return coerceUiResponse(raw, req.id);
+    }
+
+    // 无 channel 的 dialog → 默认转发到主 agent ctx.ui.*
+    return defaultDialogForward(req, ctx);
+  };
+}
+
+/** channel handler 返回值（unknown）形变为 UiResponse。
+ *  channel handler 由扩展注册（如 ask-user 扩展返回 {value}/{confirmed}/{cancelled}），
+ *  但 ChannelHandler 类型签名用 unknown（协议层避免循环依赖）。本函数做运行时收窄：
+ *    - 已是合法 UiResponse shape → 原样返回
+ *    - 形状不匹配 → 降级 {cancelled:true}（保守，不阻塞队列） */
+function coerceUiResponse(raw: unknown, reqId: string): UiResponse {
+  if (typeof raw !== "object" || raw === null) {
+    console.warn("[subagents] channel handler returned non-object, coercing to cancelled (req=", reqId, ")");
+    return { cancelled: true };
+  }
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.value === "string") return { value: obj.value };
+  if (typeof obj.confirmed === "boolean") return { confirmed: obj.confirmed };
+  if (obj.cancelled === true) return { cancelled: true };
+  if (obj.ack === true) return { ack: true };
+  console.warn("[subagents] channel handler returned unrecognized shape, coercing to cancelled (req=", reqId, ")");
+  return { cancelled: true };
+}
+
+/** 无 channel 的 dialog 默认转发：调主 agent 的 ctx.ui.select/confirm/input/editor。
+ *  ask_user channel 未注册时（ask-user 扩展未安装）也会落到这里——
+ *  select 请求转发为普通 select（title 可能含 marker，主 agent 会忽略或当普通 select 渲染）。
+ *
+ *  实现依据（SDK ExtensionUIContext 真实签名，read from
+ *  @mariozechner/pi-coding-agent dist/core/extensions/types.d.ts）：
+ *    select(title: string, options: string[], opts?): Promise<string | undefined>
+ *    confirm(title: string, message: string, opts?): Promise<boolean>
+ *    input(title: string, placeholder?: string, opts?): Promise<string | undefined>
+ *    editor(title: string, prefill?: string): Promise<string | undefined>
+ *  注意：SDK 是位置参数（非对象参数）；返回 undefined 表示用户取消。
+ *
+ *  Stage 4 风险点：TUI 下 ask_user channel 未注册时，select 会以普通列表渲染
+ *  （title 可能含 marker）。channel 注册后由 createRealHandler 优先走 channel handler，
+ *  不进这里。editor 不可用/抛错时降级 cancelled + warn，不卡队列。 */
+async function defaultDialogForward(
+  req: UiRequest,
+  ctx: ExtensionContext,
+): Promise<UiResponse> {
+  const ui = ctx.ui;
+  switch (req.method) {
+    case "select": {
+      const selected = await ui.select(req.title ?? "", req.options ?? []);
+      return selected === undefined ? { cancelled: true } : { value: selected };
+    }
+    case "confirm": {
+      // SDK confirm 必传 message（req.message 缺失时降级空串，不报错阻塞）
+      const confirmed = await ui.confirm(req.title ?? "", req.message ?? "");
+      return { confirmed };
+    }
+    case "input": {
+      const text = await ui.input(req.title ?? "", req.placeholder);
+      return text === undefined ? { cancelled: true } : { value: text };
+    }
+    case "editor": {
+      // SDK editor 必填，但部分 host 运行时未实现——try/catch 降级 cancelled + warn（不卡队列）。
+      // 不用 typeof 守卫：editor 在类型上必填，typeof 检查会被 TS2367 拒（条件永假）。
+      try {
+        const text = await ui.editor(req.title ?? "", req.prefill);
+        return text === undefined ? { cancelled: true } : { value: text };
+      } catch (err) {
+        console.warn(
+          "[subagents] ctx.ui.editor unavailable/threw, returning cancelled for",
+          req.id,
+          err,
+        );
+        return { cancelled: true };
+      }
+    }
+    default: {
+      // 未知 dialog method（非 select/confirm/input/editor）——保守 cancelled 不阻塞子进程
+      console.warn(
+        "[subagents] defaultDialogForward: unknown dialog method",
+        req.method,
+        "for",
+        req.id,
+      );
+      return { cancelled: true };
+    }
+  }
+}

package/src/execution/ui-request-observability.ts

@@ -0,0 +1,77 @@
+// src/execution/ui-request-observability.ts
+//
+// UI 请求可观测性状态（从 subagent-service.ts 提取，降低主文件行数）。
+// 持有 sessionMode + handler 缺失告警去重集合，供 SubagentService 委托调用。
+
+import type { ExtensionMode } from "@mariozechner/pi-coding-agent";
+
+// ── 跨模块桥接（ui-request-queue 无 ctx.service 引用时走这里） ──
+//
+// ui-request-queue.handleUiRequest 在 ctx.uiRequestHandler 缺失时需要触发去重告警，
+// 但 SessionRunnerContext 不持有 service 引用（改 ctx 签名超出本组 4 文件范围）。
+// 解法：SubagentService 构造后调 registerGlobalObservability(this.uiObservability)
+// 把进程单例挂到 globalThis；queue 走 notifyMissingHandlerGlobal 路径调到同一实例，
+// 共享 warnedMissingHandlerSessions 去重集合。
+//
+// 遗留：SubagentService 接线（构造/初始化时调 registerGlobalObservability）需在后续 PR 完成，
+// 本组仅提供桥接入口 + queue 侧调用。未注册时 notifyMissingHandlerGlobal 走 fallback warn（不去重），
+// 保证可观测性不回归。
+const GLOBAL_OBSERVABILITY_KEY = Symbol.for("pi-subagent-workflow.ui-observability");
+
+/** 注册进程级 observability 单例（SubagentService 构造后调用一次）。 */
+export function registerGlobalObservability(obs: UiRequestObservability): void {
+  (globalThis as Record<symbol, unknown>)[GLOBAL_OBSERVABILITY_KEY] = obs;
+}
+
+/** 触发 handler 缺失告警（经全局单例，per-session 去重）。
+ *  未注册全局单例时走 fallback warn（不去重），保证可观测性不丢。 */
+export function notifyMissingHandlerGlobal(sessionId: string): void {
+  const obs = (globalThis as Record<symbol, unknown>)[GLOBAL_OBSERVABILITY_KEY] as
+    | UiRequestObservability
+    | undefined;
+  if (obs) {
+    obs.notifyMissingHandler(sessionId);
+  } else {
+    console.warn(
+      `[subagents] uiRequestHandler missing (session=${sessionId}, global observability not registered)`,
+    );
+  }
+}
+
+/** warnedMissingHandlerSessions 容量上限（#14 防 Set 无界增长）。
+ *  长生命周期进程（GUI 主进程长开）下，不同子进程会话 id 不断积累；
+ *  超过阈值时清空集合（简单策略，LRU 留作后续优化）。 */
+const MAX_WARNED_SESSIONS = 1024;
+
+/** UI 请求可观测性状态。
+ *  持有 sessionMode（主进程运行模式，W4 守卫透传）+ handler 缺失告警去重集合。
+ *  外部通过 setMode/resetMissingHandlerWarnings/notifyMissingHandler 驱动。 */
+export class UiRequestObservability {
+  private sessionMode: ExtensionMode | undefined;
+  private warnedMissingHandlerSessions = new Set<string>();
+
+  setMode(mode: ExtensionMode | undefined): void {
+    this.sessionMode = mode;
+  }
+
+  getMode(): ExtensionMode | undefined {
+    return this.sessionMode;
+  }
+
+  /** handler 变化时重置告警去重（新 handler 就位后允许重新 warn）。 */
+  resetMissingHandlerWarnings(): void {
+    this.warnedMissingHandlerSessions.clear();
+  }
+
+  /** 记录 handler 缺失（per-session 去重，每 session 只 warn 一次）。
+   *  #14：Set 加 cap——超 MAX_WARNED_SESSIONS 时先清空再 add，防无界增长。
+   *  清空策略：当前会话首条告警丢失可接受（去重本身只是降噪，非数据完整性约束）。 */
+  notifyMissingHandler(sessionId: string): void {
+    if (this.warnedMissingHandlerSessions.has(sessionId)) return;
+    if (this.warnedMissingHandlerSessions.size >= MAX_WARNED_SESSIONS) {
+      this.warnedMissingHandlerSessions.clear();
+    }
+    this.warnedMissingHandlerSessions.add(sessionId);
+    console.warn(`[subagents] uiRequestHandler missing (session=${sessionId}, mode=${this.sessionMode})`);
+  }
+}