@zhushanwen/pi-subagent-workflow 0.1.0 → 0.3.0

package/src/execution/spawn-event-adapter.ts

@@ -2,9 +2,11 @@
 //
 // pi 子进程 stdout JSON 事件流的解析器。Core 叶子原语（仅依赖 types.ts）。
 //
-// spawn 改造的基座模块。pi --mode json 子进程通过 stdout 输出两种行：
-//   1. header 行（首行）：{ type: "session", id, timestamp, cwd, ... }
-//      —— session 元信息，含 session id（文件路径由 W2 runSpawn 配合 --session-dir 推导）
+// spawn 改造的基座模块。session-runner runSpawn 用 `pi --mode rpc` spawn 子进程。
+// RPC mode 不向 stdout 输出 header 行（只有 json/print mode 才输出），故 runSpawn 额外
+// 通过 get_state RPC 握手回填 sessionFile/sessionId。两种 stdout 行形态本模块统一解析：
+//   1. header 行（json/print mode 首行）：{ type: "session", id, timestamp, cwd, ... }
+//      —— session 元信息，含 session id（RPC mode 不发，靠 get_state 握手替代）
 //   2. 事件行：{ type: "tool_execution_start" | "message_end" | ..., ... }
 //      —— 与 in-process session.subscribe 收到的 SdkEvent 同源同构
 //
@@ -30,10 +32,68 @@ export interface SpawnSessionHeader {
   readonly version?: number;
 }
 
-/** parseSpawnLine 的分类结果。 */
+/** Pi 原生 extension_ui_request 的方法特定字段（按 method 平铺）。
+ *  与 Pi rpc-types.ts L230-265 的 RpcExtensionUIRequest 1:1 对应。
+ *  method 是判别字段；每个变体仅列出该 method 的已知字段（可选字段保持可选）。
+ *  未知 method 走 string fallback（保留 raw 字段，避免协议演进时丢字段）。 */
+export type ExtensionUiRequest =
+  | { method: "select"; title: string; options: string[]; timeout?: number }
+  | { method: "confirm"; title: string; message: string; timeout?: number }
+  | { method: "input"; title: string; placeholder?: string; timeout?: number }
+  | { method: "editor"; title: string; prefill?: string }
+  | { method: "notify"; message: string; notifyType?: "info" | "warning" | "error" }
+  | { method: "setStatus"; statusKey: string; statusText: string | undefined }
+  | {
+      method: "setWidget";
+      widgetKey: string;
+      widgetLines: string[] | undefined;
+      widgetPlacement?: "aboveEditor" | "belowEditor";
+    }
+  | { method: "setTitle"; title: string }
+  | { method: "set_editor_text"; text: string }
+  // 未知 method fallback：保留原始字段，避免协议演进时丢信息
+  | { method: string; raw: Record<string, unknown> };
+
+/** 解析后的 extension_ui_request 顶层形状（type 守卫用）。
+ *  id 和 method 在顶层，method 特定字段平铺（与 Pi 原生格式一致）。 */
+interface ExtensionUiRequestEnvelope {
+  type: "extension_ui_request";
+  id: string;
+  method: string;
+  [key: string]: unknown;
+}
+
+/** Pi 原生 RPC response 顶层形状（type 守卫用）。
+ *  与 Pi rpc-types.ts 的 RpcResponse 一致：type:"response" + command + success。 */
+interface RpcResponseEnvelope {
+  type: "response";
+  command: string;
+  success: boolean;
+  id?: string;
+  data?: unknown;
+  error?: string;
+  [key: string]: unknown;
+}
+
+/** parseSpawnLine 的分类结果。
+ *
+ *  关键改动（W1 协议层重写）：
+ *    - extension_ui_request 分支：从 {id, params:Record} 改为 {id, request: ExtensionUiRequest}
+ *      （request 按 method 平铺，与 Pi rpc-types.ts 1:1）
+ *    - response 分支：从 {id, result, error} 改为 {id?, command, success, data?, error?}
+ *      （Pi 原生 RpcResponse 格式，SR-1 根因 1b） */
 export type ParsedSpawnLine =
   | { kind: "header"; header: SpawnSessionHeader }
   | { kind: "event"; event: SdkEvent }
+  | {
+      kind: "response";
+      id?: string;
+      command: string;
+      success: boolean;
+      data?: unknown;
+      error?: string;
+    }
+  | { kind: "extension_ui_request"; id: string; request: ExtensionUiRequest }
   | { kind: "invalid"; raw: string; error: string };
 
 /**
@@ -52,15 +112,149 @@ function isSessionHeader(obj: unknown): obj is SpawnSessionHeader {
   );
 }
 
+/**
+ * 判断解析出的 JSON 是否为 Pi 原生 RPC response。
+ *
+ * SR-1 根因 1b 修复：旧守卫判 JSON-RPC 2.0（jsonrpc + id + result/error），
+ * 但 Pi 实际发 {type:"response", command, success, data?, error?}。
+ * 新守卫只认 Pi 原生格式：
+ *   - type === "response"
+ *   - command: string（调用的命令名，如 "run_tool"）
+ *   - success: boolean
+ * id 可选（通知型 response 无 id）。
+ *
+ * 旧 JSON-RPC 2.0 response（{jsonrpc, id, result}）不再被识别 → 落 invalid 分支。
+ */
+function isRpcResponse(obj: unknown): obj is RpcResponseEnvelope {
+  if (typeof obj !== "object" || obj === null) return false;
+  const r = obj as Record<string, unknown>;
+  return (
+    r.type === "response" &&
+    typeof r.command === "string" &&
+    typeof r.success === "boolean"
+  );
+}
+
+/**
+ * 判断解析出的 JSON 是否为 Pi 原生 extension_ui_request。
+ *
+ * 关键改动（W1）：旧守卫判 JSON-RPC 2.0（jsonrpc + method:"extension_ui_request" + params），
+ * 但 Pi 实际发平铺格式 {type:"extension_ui_request", id, method, ...method特定字段}。
+ * 新守卫：
+ *   - type === "extension_ui_request"（顶层 type 字段，非 method 字段值）
+ *   - id: string
+ *   - method: string（select/confirm/.../set_editor_text 等具体方法名）
+ *
+ * 删掉 jsonrpc 守卫（Pi 不发 JSON-RPC 2.0 envelope）和 params 守卫（字段平铺，无 params 包裹）。
+ * 旧 JSON-RPC 2.0 格式（{jsonrpc, method:"extension_ui_request", params}）不再被识别。
+ */
+function isExtensionUiRequest(obj: unknown): obj is ExtensionUiRequestEnvelope {
+  if (typeof obj !== "object" || obj === null) return false;
+  const r = obj as Record<string, unknown>;
+  return (
+    r.type === "extension_ui_request" &&
+    typeof r.id === "string" &&
+    typeof r.method === "string"
+  );
+}
+
+/**
+ * 从已通过 isExtensionUiRequest 守卫的 envelope 构造 ExtensionUiRequest 变体。
+ *
+ * 按 method 平铺提取字段（与 Pi rpc-types.ts L230-265 1:1）。已知 method
+ * 走对应变体；未知 method 走 string fallback（保留 raw 字段全量字段）。
+ *
+ * 字段类型容错：协议字段类型不符（如 options 非数组）时，该字段降级为空数组/undefined
+ *（数组类字段做元素类型过滤，剔除非字符串元素），仍归类为已知 method（不丢 method 信息）。
+ */
+function buildExtensionUiRequest(env: ExtensionUiRequestEnvelope): ExtensionUiRequest {
+  const r: Record<string, unknown> = env;
+  switch (env.method) {
+    case "select":
+      return {
+        method: "select",
+        title: typeof r.title === "string" ? r.title : "",
+        options: Array.isArray(r.options)
+          ? r.options.filter((x): x is string => typeof x === "string")
+          : [],
+        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+      };
+    case "confirm":
+      return {
+        method: "confirm",
+        title: typeof r.title === "string" ? r.title : "",
+        message: typeof r.message === "string" ? r.message : "",
+        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+      };
+    case "input":
+      return {
+        method: "input",
+        title: typeof r.title === "string" ? r.title : "",
+        ...(typeof r.placeholder === "string" ? { placeholder: r.placeholder } : {}),
+        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+      };
+    case "editor":
+      return {
+        method: "editor",
+        title: typeof r.title === "string" ? r.title : "",
+        ...(typeof r.prefill === "string" ? { prefill: r.prefill } : {}),
+      };
+    case "notify":
+      return {
+        method: "notify",
+        message: typeof r.message === "string" ? r.message : "",
+        ...(r.notifyType === "info" || r.notifyType === "warning" || r.notifyType === "error"
+          ? { notifyType: r.notifyType }
+          : {}),
+      };
+    case "setStatus":
+      return {
+        method: "setStatus",
+        statusKey: typeof r.statusKey === "string" ? r.statusKey : "",
+        statusText: typeof r.statusText === "string" ? r.statusText : undefined,
+      };
+    case "setWidget": {
+      const placement = r.widgetPlacement;
+      const widgetLines = Array.isArray(r.widgetLines)
+        ? r.widgetLines.filter((x): x is string => typeof x === "string")
+        : undefined;
+      return {
+        method: "setWidget",
+        widgetKey: typeof r.widgetKey === "string" ? r.widgetKey : "",
+        widgetLines,
+        ...(placement === "aboveEditor" || placement === "belowEditor"
+          ? { widgetPlacement: placement }
+          : {}),
+      };
+    }
+    case "setTitle":
+      return {
+        method: "setTitle",
+        title: typeof r.title === "string" ? r.title : "",
+      };
+    case "set_editor_text":
+      return {
+        method: "set_editor_text",
+        text: typeof r.text === "string" ? r.text : "",
+      };
+    default:
+      // 未知 method：保留全部原始字段，避免协议演进时丢信息
+      return { method: env.method, raw: r };
+  }
+}
+
 /**
  * 解析 pi stdout 的一行。
  *
  * @param line stdout 的一行（不含换行符；空行返回 null）
  * @returns 分类结果，或 null（空行/仅空白）
  *
- * 分类规则：
+ * 分类规则（判定顺序关键，见 W1 bug 修复）：
  *   - 空白行 → null（pi 可能输出空行，跳过）
- *   - 合法 JSON + type:"session" + 有 id → header
+ *   - 合法 JSON + type:"session" + 必需字段 → header
+ *   - 合法 JSON + type:"extension_ui_request" + id + method → extension_ui_request
+ *     （必须在 event 分支之前，否则被 typeof obj.type===string 吞为 event）
+ *   - 合法 JSON + type:"response" + command + success → response
  *   - 合法 JSON + 有 type 字段 → event（SdkEvent，type schema 由调用方校验）
  *   - 合法 JSON 但无 type → invalid
  *   - 非法 JSON → invalid（记录 error，不抛——单行损坏不应中断整个流）
@@ -87,6 +281,25 @@ export function parseSpawnLine(line: string): ParsedSpawnLine | null {
     return { kind: "header", header: obj };
   }
 
+  // extension_ui_request：必须在 event 分支之前判定（W1 判定顺序 bug 修复）。
+  // 原因：extension_ui_request 也有 type 字段，若 event 分支（typeof obj.type===string）
+  // 在前，会被当 event 静默吞掉。现在先于 event 判定，命中后按 method 构造 request。
+  if (isExtensionUiRequest(obj)) {
+    return { kind: "extension_ui_request", id: obj.id, request: buildExtensionUiRequest(obj) };
+  }
+
+  // RPC response：Pi 原生格式 {type:"response", command, success, data?, error?}
+  if (isRpcResponse(obj)) {
+    return {
+      kind: "response",
+      ...(typeof obj.id === "string" ? { id: obj.id } : {}),
+      command: obj.command,
+      success: obj.success,
+      ...(obj.data !== undefined ? { data: obj.data } : {}),
+      ...(typeof obj.error === "string" ? { error: obj.error } : {}),
+    };
+  }
+
   // 事件行：必须有 type 字段（SdkEvent 契约）
   if (
     typeof obj === "object" &&

package/src/execution/stdin-writer.ts

@@ -0,0 +1,106 @@
+// src/execution/stdin-writer.ts
+//
+// 向 rpc 子进程 stdin 写入命令的 helper 集合。
+//
+// pi --mode rpc 通过 stdin 的 JSON RpcCommand / RpcExtensionUIResponse 驱动：
+//   - extension_ui_response（主进程回答子进程的 UI 请求，如 ask_user）
+//   - prompt（驱动子进程开始处理 task）
+// 两者共用 child.stdin.write + 背压检查，提取到此模块统一维护。
+
+import type { ChildProcess } from "node:child_process";
+import * as crypto from "node:crypto";
+
+import type { UiResponse } from "./dialog-queue.ts";
+
+/**
+ * 按 UiResponse 形状构造 Pi 原生 extension_ui_response 并写 stdin。
+ *
+ * SR-5：ack（fire-and-forget）不写 stdin——Pi 对 fire-and-forget method 不期待响应，
+ * 写入会触发协议错配。其他三种 shape（value/confirmed/cancelled）按对应字段写。
+ *
+ * [R1] 背压检查：child.stdin.write 返回 false 时记 warn（不阻塞，内核缓冲会随后排空）。
+ * [R2] 序列化在本函数内逐分支完成。JSON.stringify 可能抛错（out.value 含循环引用 /
+ *     BigInt 等不可序列化结构），try/catch 降级为 cancelled——宁可取消单次 dialog 也不让
+ *     父进程崩溃（UI 请求通道不应被脏数据拖垮）。
+ *
+ * @param child 子进程（stdin 写入响应）
+ * @param id 请求 id（关联 response）
+ * @param out UiResponse（{value}/{confirmed}/{cancelled}/{ack}）
+ * @param signal abort signal（已 aborted 时跳过写入）
+ */
+export function respond(child: ChildProcess, id: string, out: UiResponse, signal?: AbortSignal): void {
+  if (signal?.aborted) return;
+  let line: string | undefined;
+  try {
+    if ("value" in out) line = JSON.stringify({ type: "extension_ui_response", id, value: out.value });
+    else if ("confirmed" in out) line = JSON.stringify({ type: "extension_ui_response", id, confirmed: out.confirmed });
+    else if ("cancelled" in out) line = JSON.stringify({ type: "extension_ui_response", id, cancelled: true });
+  } catch (err) {
+    // [R2] out.value 含循环引用/BigInt 等不可序列化结构——降级 cancelled，避免父进程崩溃。
+    console.warn(`[subagents] JSON.stringify failed for ui response ${id}, degrading to cancelled:`, err);
+    line = JSON.stringify({ type: "extension_ui_response", id, cancelled: true });
+  }
+  // ack: fire-and-forget，不写 stdin（SR-5）
+  if (line === undefined) return;
+  writeStdinLine(child, line, `ui response for request ${id}`);
+}
+
+/**
+ * spawn 后向 rpc 子进程 stdin 写 prompt 命令，驱动 agent 开始处理 task。
+ *
+ * pi 的 runRpcMode 只通过 stdin RpcCommand 驱动——positional task arg / -p flag
+ * 在 rpc mode 下被 resolveAppMode 无视。必须在 spawn 后主动喂 prompt 命令，
+ * 否则子进程阻塞等 stdin、永不进入推理（totalTokens 恒 0）。
+ *
+ * 时机：spawn 后立即写。stdin 是 pipe，内核缓冲保证数据不丢；
+ * pi 在 await rebindSession() 后才挂 stdin reader（rpc-mode.ts:778-781），
+ * reader 处理 prompt 时 session 已就绪。
+ *
+ * @param child 子进程（stdin 写入 prompt 命令）
+ * @param task 完整 task 文本（含 schema 指令）
+ */
+export function sendPromptCommand(child: ChildProcess, task: string): void {
+  if (!child.stdin || child.stdin.destroyed) return;
+  const command = JSON.stringify({
+    id: crypto.randomUUID(),
+    type: "prompt",
+    message: task,
+  });
+  writeStdinLine(child, command, "prompt command");
+}
+
+/**
+ * 向 rpc 子进程 stdin 写 get_state 命令，查询 sessionFile/sessionId。
+ *
+ * FR-4: RPC get_state 握手。当 stdout header 未携带 sessionFile 时，
+ * 通过此命令向子进程查询当前 session 状态。子进程收到后返回
+ * {type:"response", command:"get_state", success:true, data:{sessionFile, sessionId}}。
+ *
+ * @param child 子进程（stdin 写入 get_state 命令）
+ * @returns 请求 id（用于匹配 response）
+ */
+export function sendGetStateCommand(child: ChildProcess): string {
+  const id = crypto.randomUUID();
+  const command = JSON.stringify({
+    id,
+    type: "get_state",
+  });
+  writeStdinLine(child, command, "get_state command");
+  return id;
+}
+
+/**
+ * 向子进程 stdin 写一行（自动补换行），带背压检查。
+ *
+ * [R1] write 返回 false 时记 warn（不阻塞，内核缓冲会随后排空）。
+ * stdin 已关闭/销毁时跳过——respond 已检查 signal，sendPromptCommand 已检查 destroyed。
+ *
+ * @param child 子进程
+ * @param line JSON 行（不含换行）
+ * @param warnTag warn 日志的语义标记
+ */
+function writeStdinLine(child: ChildProcess, line: string, warnTag: string): void {
+  if (!child.stdin || child.stdin.destroyed) return;
+  const ok = child.stdin.write(line + "\n");
+  if (!ok) console.warn(`[subagents] stdin backpressure on ${warnTag}`);
+}

package/src/execution/stream-sink.ts

@@ -0,0 +1,83 @@
+/**
+ * subagent text_delta streaming sink。
+ *
+ * background subagent 执行期间，session-runner 的 agentEvent 出口把每个 text_delta
+ * 传到 SubagentStream.onDelta。本模块做 100ms 时间窗合并后，通过 StreamSink.setWidget
+ * 转发到 RPC stdout（经 ctx.ui.setWidget → extension_ui_request 通道）。
+ *
+ * SubagentStream 是一个生命周期对象——内聚 buffer/timer 状态 + onDelta/dispose 方法。
+ * 调用方（subagent-service）创建后只需在 text_delta 时调 onDelta、终态时调 dispose，
+ * 不需要拆散 push/clear 两个函数跨层透传。
+ *
+ * 设计要点：
+ * - leading edge：第一个 delta 立即 flush（前端尽快看到开始）
+ * - trailing edge：后续 delta 追加 buffer，timer 到期后 flush
+ * - 每次 flush 把 buffer 的累积全文 split("\n") 传给 setWidget
+ * - dispose 清除 widget + 清 timer
+ */
+
+/** UI streaming sink 的最小接口（ctx.ui.setWidget 的 duck-typed 子集）。
+ *
+ * 当前只有一个 adapter（index.ts session_start 包装 ctx.ui.setWidget）。
+ * 保留接口而非裸函数类型，因为 StreamSink 的语义是「UI sink 契约」——
+ * 测试 mock 和未来可能的第二 sink（如写文件）都走此契约。 */
+export interface StreamSink {
+  setWidget(key: string, lines: string[] | undefined): void;
+}
+
+/** delta 合并窗口时间（ms）。与 onEventThrottled 的节流间隔对齐。 */
+const STREAM_FLUSH_MS = 100;
+
+/**
+ * subagent text_delta streaming 生命周期对象。
+ *
+ * 创建后：
+ * - `onDelta(delta)`：session-runner 每次 text_delta 调
+ * - `dispose()`：subagent 终态时调，清除 widget + 清 timer
+ *
+ * buffer/timer 状态全部内聚在此对象，调用方不需要关心合并逻辑。
+ */
+export class SubagentStream {
+  private readonly widgetKey: string;
+  private readonly sink: StreamSink;
+  private buffer = "";
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private hasFlushed = false;
+  private disposed = false;
+
+  constructor(recordId: string, sink: StreamSink) {
+    this.widgetKey = `subagent-stream-${recordId}`;
+    this.sink = sink;
+  }
+
+  /** 接收一个 text_delta 增量。空串静默丢弃（不消耗 leading edge）。 */
+  onDelta(delta: string): void {
+    if (this.disposed || delta.length === 0) return;
+    this.buffer += delta;
+    if (!this.hasFlushed) {
+      // leading edge：第一个 delta 立即 flush
+      this.hasFlushed = true;
+      this.flush();
+    } else if (this.timer === undefined) {
+      // trailing edge：后续 delta 经 timer 合并
+      this.timer = setTimeout(() => this.flush(), STREAM_FLUSH_MS);
+    }
+  }
+
+  /** 终态清理：清除 widget + 清 timer（幂等）。 */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    this.sink.setWidget(this.widgetKey, undefined);
+  }
+
+  private flush(): void {
+    this.timer = undefined;
+    if (this.buffer.length === 0 || this.disposed) return;
+    this.sink.setWidget(this.widgetKey, this.buffer.split("\n"));
+  }
+}