@zhushanwen/subagent-engine-sdk 0.2.0

package/src/spawn.ts

@@ -0,0 +1,246 @@
+// src/spawn.ts
+//
+// 引擎子进程 spawn 原语 + 引擎侧自灭（W12，impl-plan §2.12 / §2.2 R9-4② / §7.2 R9-2）。
+//
+// spawnEngineChild 是全部引擎 CLI 任务子进程的唯一 spawn 入口（W10 静态断言目标符号）：
+// - 硬编码 POSIX/Windows detached:false（+ windowsHide:true），不暴露 detached 选项
+//   ——引擎一代子进程不脱离进程组，宿主杀组即连带收割；
+// - 不把引擎自身的 stdin fd 传给后代：子进程 stdin 恒为自有 pipe（'pipe'），
+//   禁止 'inherit'/fd 形态——否则宿主死后代仍持写端、EOF 永不到达，自灭主判据失效
+//   （R9-4②）。
+//
+// armEngineSelfDestruct 是引擎 CLI 的宿主死亡自灭守卫：主判据 stdio EOF，
+// 辅助判据 in-flight 反向请求计时超时（已 ack 的人机交互 / 两阶段长运行请求除外）。
+
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { getLogger } from "./logger.ts";
+import type { buildEngineChildEnv } from "./env.ts";
+
+const logger = getLogger("engine-sdk/spawn");
+
+/** spawnEngineChild 的 env 必须来自 buildEngineChildEnv（三层契约终态）。 */
+export type EngineChildEnv = ReturnType<typeof buildEngineChildEnv>;
+
+/** 引擎子进程 spawn 选项（刻意不暴露 detached / stdio / stdin——形态硬编码，见文件头）。 */
+export interface SpawnEngineChildOptions {
+  command: string;
+  args: readonly string[];
+  /** 须由 buildEngineChildEnv 构建（类型即契约：三层 env 终态） */
+  env: EngineChildEnv;
+  cwd?: string;
+  /** 子进程 stdout/stderr 形态；缺省 'pipe'（协议帧走 stdout，stderr 走日志/轮转） */
+  stdout?: "pipe" | "ignore" | "inherit";
+  stderr?: "pipe" | "ignore" | "inherit";
+  /** AbortSignal 触发即 SIGTERM 杀子（缺省无） */
+  signal?: AbortSignal;
+}
+
+/** 这些键出现即拒绝：spawn 形态是本原语的契约面，不允许调用方绕过硬编码值。 */
+const FORBIDDEN_OPTION_KEYS = ["detached", "stdio", "stdin", "windowsHide"] as const;
+
+/**
+ * 引擎任务子进程唯一 spawn 入口。
+ *
+ * 形态硬编码：detached:false、windowsHide:true、子进程 stdin 恒 'pipe'（自有 pipe，
+ * 绝不继承引擎自身 stdin fd）。传入被禁止的形态键（detached/stdio/stdin/windowsHide）
+ * 直接抛错——契约破坏应在配置期出声，不静默降级。
+ */
+export function spawnEngineChild(opts: SpawnEngineChildOptions): ChildProcess {
+  for (const key of FORBIDDEN_OPTION_KEYS) {
+    if (key in opts) {
+      throw new Error(
+        `spawnEngineChild: option "${key}" is hardcoded by the engine spawn contract `
+          + `(detached:false / windowsHide:true / child stdin is always its own pipe); `
+          + `remove it from the call site`,
+      );
+    }
+  }
+
+  const child = spawn(opts.command, [...opts.args], {
+    cwd: opts.cwd,
+    env: opts.env,
+    detached: false,
+    windowsHide: true,
+    stdio: ["pipe", opts.stdout ?? "pipe", opts.stderr ?? "pipe"],
+  });
+
+  if (opts.signal !== undefined) {
+    opts.signal.addEventListener(
+      "abort",
+      () => {
+        child.kill("SIGTERM");
+      },
+      { once: true },
+    );
+  }
+  return child;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 引擎侧自灭（宿主死亡检测）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** in-flight 未 ack 反向请求的计时超时缺省值（辅助判据，30s）。 */
+export const DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS = 30_000;
+
+/** 计时超时覆盖 env 名（引擎 CLI 启动时读；非法值 warn + 回落缺省）。 */
+export const ENGINE_HOST_REQUEST_TIMEOUT_ENV = "XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS";
+
+/** 计时巡检周期（ms）。仅为辅助判据的采样粒度，不构成行为契约。 */
+const SWEEP_INTERVAL_MS = 1_000;
+
+/** 反向请求计时面操作接口（消费方 = 引擎 CLI 的反向通道分发层）。 */
+export interface ReverseRequestClock {
+  /** 反向请求已发出（未 ack）——进入计时面。 */
+  started(id: string): void;
+  /**
+   * 收到 ack（两阶段第一阶段：已 ack 的 host/askUser、HostBridge.executeAndAwait
+   * 的 ack）——移出计时面但不终结（R9-2：已 ack 的等待不计入 in-flight 超时，
+   * ADR-0047 静默 ≠ 卡死）。
+   */
+  acked(id: string): void;
+  /** 请求终结（应答完成/失败/取消）——彻底移出。 */
+  settled(id: string): void;
+  /** 卸载守卫（引擎正常 shutdown 路径；自灭后幂等）。 */
+  dispose(): void;
+}
+
+export interface EngineSelfDestructOptions {
+  /** 主判据数据源：宿主→引擎的协议 stdin（EOF = 宿主死亡 → 立即自灭）。 */
+  stdin: NodeJS.ReadableStream;
+  /** 辅助判据超时（缺省 30s；显式传值优先于 env XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS）。 */
+  hostRequestTimeoutMs?: number;
+  /** 计时超时的 env 覆盖源（缺省读 process.env；测试注入用）。 */
+  timeoutEnv?: Record<string, string | undefined>;
+  /** 自灭执行器（缺省 = 杀自己进程组再杀自己；测试注入用）。 */
+  killSelf?: () => void;
+}
+
+/** 解析计时超时：显式 opt > env > 缺省；env 非法（非正整数）warn + 回落缺省。 */
+function resolveHostRequestTimeoutMs(opts: EngineSelfDestructOptions): number {
+  if (opts.hostRequestTimeoutMs !== undefined) return opts.hostRequestTimeoutMs;
+  const raw = (opts.timeoutEnv ?? process.env)[ENGINE_HOST_REQUEST_TIMEOUT_ENV];
+  if (raw === undefined || raw === "") return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    logger.warn(
+      `invalid ${ENGINE_HOST_REQUEST_TIMEOUT_ENV}=${JSON.stringify(raw)}, falling back to `
+        + `${DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS}ms`,
+    );
+    return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
+  }
+  return parsed;
+}
+
+/** 缺省自灭：先杀自己进程组（-pid，收割引擎 spawn 的任务子进程），失败回落杀自己。 */
+function killOwnProcessGroup(): void {
+  const pid = process.pid;
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch (err) {
+    // 进程组杀失败（非组长 / Windows 形态差异）——回落单进程杀，任务子进程由
+    // 各自的 stdio EOF / 宿主回收层兜底。
+    logger.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
+    process.kill(pid, "SIGKILL");
+  }
+}
+
+/**
+ * 武装引擎侧自灭守卫。返回 ReverseRequestClock 给反向通道分发层登记请求生命周期。
+ *
+ * 判据：
+ * - 主判据 stdio EOF：stdin 'end'（数据面读尽）或 'close'（fd 关闭）→ 立即自灭
+ *   （宿主死后无人再写协议帧，引擎继续跑只烧 token）；
+ * - 辅助判据 in-flight 反向请求计时：未 ack 的反向请求超过 hostRequestTimeoutMs
+ *   仍无 ack → 宿主大概率已死（EOF 未达或正在关闭）→ 自灭。**排除面**：已 ack 的
+ *   host/askUser 与两阶段 ack 的长运行 HostBridge.executeAndAwait（ack 后等待任意
+ *   时长合法，漏此项即「>30s pi 任务被自灭」turnTimeoutMs 同型事故）。
+ *
+ * 自灭执行 = 引擎自杀并杀自己进程组（spawnEngineChild 硬编码 detached:false，
+ * 任务子进程同组连带收割）。
+ */
+export function armEngineSelfDestruct(opts: EngineSelfDestructOptions): ReverseRequestClock {
+  const timeoutMs = resolveHostRequestTimeoutMs(opts);
+  const killSelf = opts.killSelf ?? killOwnProcessGroup;
+
+  // pending = 已发出未 ack（计时面）；settled/acked 请求不在面内。
+  const pending = new Map<string, number>();
+  let disposed = false;
+
+  const destroy = (reason: string): void => {
+    if (disposed) return;
+    disposed = true;
+    clearInterval(timer);
+    opts.stdin.removeAllListeners?.("end");
+    opts.stdin.removeAllListeners?.("close");
+    logger.warn(`engine self-destruct: ${reason}`);
+    killSelf();
+  };
+
+  // 主判据：stdio EOF（'end' 与 'close' 双挂——pipe 半关闭与 fd 销毁都算宿主死亡）
+  opts.stdin.once("end", () => destroy("host stdin EOF (end)"));
+  opts.stdin.once("close", () => destroy("host stdin closed"));
+
+  // 辅助判据：未 ack 反向请求计时巡检（timer 声明于 destroy 之后——destroy 仅经
+  // 事件/回调异步触发，调用时已初始化）
+  const timer = setInterval(() => {
+    const now = Date.now();
+    for (const [id, startedAt] of pending) {
+      if (now - startedAt > timeoutMs) {
+        destroy(`unacked reverse request ${id} exceeded ${timeoutMs}ms without host ack`);
+        return;
+      }
+    }
+  }, SWEEP_INTERVAL_MS);
+  timer.unref?.();
+
+  return {
+    started(id) {
+      if (!disposed) pending.set(id, Date.now());
+    },
+    acked(id) {
+      pending.delete(id);
+    },
+    settled(id) {
+      pending.delete(id);
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      clearInterval(timer);
+      opts.stdin.removeAllListeners?.("end");
+      opts.stdin.removeAllListeners?.("close");
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NDJSON 行泵（子进程 stdout 拆行）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 流式 NDJSON 行泵：utf8 解码 + 缓冲累积 + "\n" 拆行循环（S4 簇 5b 收编：pi
+ * spawn-run-pump 与 zcode connection 的逐字同构段单源化，实现以 pi 版为基线）。
+ * 末行无换行符时滞留缓冲（NDJSON 语义：行以 \n 定界）；不监听 end/close/error——
+ * 生命周期接线（close 收尾/error 兜底）由调用方自行挂接。stream 为 null/undefined
+ * （无 stdio）时无操作，与原调用点 `child.stdout?.` 可选链语义等价。
+ */
+export function pumpNdjsonLines(
+  stream: NodeJS.ReadableStream | null | undefined,
+  onLine: (line: string) => void,
+): void {
+  if (stream === null || stream === undefined) return;
+  stream.setEncoding("utf8");
+  let buffer = "";
+  stream.on("data", (chunk: string) => {
+    buffer += chunk;
+    let nl = buffer.indexOf("\n");
+    while (nl >= 0) {
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      onLine(line);
+      nl = buffer.indexOf("\n");
+    }
+  });
+}

package/src/ui-channels.ts

@@ -0,0 +1,219 @@
+// src/ui-channels.ts
+//
+// UI channel 提取（marker 解析）+ channel 注册表（引擎侧原语，自 core
+// execution/ui-channels.ts 移入 @zhushanwen/subagent-engine-sdk，实现体逐字等价；
+// round1-reuse R1：core execution 副本与 pi 引擎 CLI 副本自本模块 re-export 收编，
+// 消逐字等价双副本——core → SDK、pi → SDK 均正向合法）。
+//
+// 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/ui-types.ts

@@ -0,0 +1,84 @@
+// src/ui-types.ts
+//
+// UI 请求/响应契约类型（自 core execution/dialog-queue.ts :94/:113/:150/:159 迁入
+// @zhushanwen/subagent-engine-sdk，结构等价）。迁移处置（impl-plan §2.1 类型闭包表
+// R3 S-A / R4-S③）：**UiMethod / UiRequest / UiResponse / UiRequestHandler 入 SDK
+// 类型闭包**——该模块是三类型的规范来源（dialog-queue.ts:87 注释自证）；`UiMethod`
+// 是 `UiRequest.method` 的依赖类型（:94，R4-S③ 补录，包外零消费方）。队列实现本体
+// 留 core；core 侧改再导出 SDK 类型（`export type { ... } from
+// "@zhushanwen/subagent-engine-sdk"`，§2.7 MF-X2 既定决策，引用切换归 W2/W7）；
+// 双向可赋值断言挂 core typecheck 断言族。
+//
+// 协议消费面：反向通道 host/askUser 的载荷携带 UiRequest（reverse-channels.ts），
+// 两阶段结果 = UiResponse（ack 先行、结果异步到达，R9-2）。
+
+/** Pi extension_ui_request 的方法枚举（dialog + fire-and-forget 两类）。
+ *  dialog 类：select/confirm/input/editor（占输入焦点，等响应）。
+ *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
+ *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
+export type UiMethod =
+  | "select"
+  | "confirm"
+  | "input"
+  | "editor"
+  | "notify"
+  | "setStatus"
+  | "setWidget"
+  | "setTitle"
+  | "set_editor_text"
+  | (string & {});
+
+/** UI 请求（session-runner 构造后传给 handler）。
+ *
+ *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
+ *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
+ *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
+ *
+ *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
+export interface UiRequest {
+  /** Pi rpc-types.ts 的 method（select/confirm/input/editor 为 dialog 类）。 */
+  method: UiMethod;
+  /** 请求 id（从 extension_ui_request envelope 顶层提取，用于 response 关联）。 */
+  id: string;
+  // method 特定字段（按 method 可选，与 ExtensionUiRequest 1:1）
+  title?: string;
+  options?: string[];
+  message?: string;
+  placeholder?: string;
+  prefill?: string;
+  notifyType?: string;
+  statusKey?: string;
+  statusText?: string | undefined;
+  widgetKey?: string;
+  widgetLines?: string[] | undefined;
+  widgetPlacement?: "aboveEditor" | "belowEditor";
+  text?: string;
+  timeout?: number;
+  /** channel 名（从 method 对应字段的 NUL 前缀解析）。
+   *  select → 从 title 解析；setWidget → 从 widgetLines[0] 解析；其他 → undefined。
+   *  已知值："ask_user"（select）、"gui_widget"（setWidget）。handler 按 channel 分发。 */
+  channel?: string;
+  /** channel 解析后的结构化 payload（已 JSON.parse）。
+   *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
+  channelPayload?: unknown;
+  /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
+   *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
+   *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
+  _childPid?: number;
+}
+
+/** UI 响应（handler 返回，session-runner 按 shape 回写 stdin）。
+ *  - {value}: select/input/editor 的答案
+ *  - {confirmed}: confirm 的答案
+ *  - {cancelled}: 取消（child close / handler 抛错 / 用户取消）
+ *  - {ack}: fire-and-forget（当前不透传到 TUI，留作协议完整） */
+export type UiResponse =
+  | { value: string }
+  | { confirmed: boolean }
+  | { cancelled: true }
+  | { ack: true };
+
+/** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
+ *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
+ *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
+export type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;