@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/round-settlement.ts

@@ -1,93 +0,0 @@
-// [D4-② 轮次结算职责轴] chatMode 轮次完成的业务闭包（原 SubagentService
-// buildSessionRunnerContext 内的 onRoundSettled 回调 ~95 行区域）整体搬移至此
-// （行为逐字节等价：搬移 + 依赖注入，不重写逻辑）。变化轴：改轮次增量派生 /
-// notify 时序 / base 推进 / closeAfterRound 消费语义，只改本文件；Service 经
-// buildSessionRunnerContext 注入三个依赖回调（notify / 持久化上报 / close 兑现）。
-
-import { getLogger } from "../core/logger.ts";
-
-import { getFullTextFrom, nextRoundBaseTurnIndex } from "./execution-record.ts";
-import type { ExecutionRecord } from "./types.ts";
-
-const logger = getLogger("subagents");
-
-/** 轮次结算的依赖注入（Service 侧供给）。 */
-export interface RoundSettlementDeps {
-  /** 本轮增量的通知投递（Service.notifyComplete——经 notifyHost）。 */
-  notifyComplete: (record: ExecutionRecord) => void;
-  /** 轮终迁移持久化上报（store.reportRecordTransition——live ≡ reload 等价性）。 */
-  reportRecordTransition: (record: ExecutionRecord) => void;
-  /** closeAfterRound 兑现（Service.closeAfterRoundSettled——chatMode 优雅关闭的终态化）。 */
-  closeAfterRoundSettled: (record: ExecutionRecord) => Promise<void>;
-}
-
-/** 构造 onRoundSettled 回调（session-runner agent_settled 时调用）。
- *
- * [V2 决策 2] chatMode 首轮闭环：session-runner 已 arm idle timer，
- * isIdle=true 让 notify 守卫放行（时序：armIdleTimer → onRoundSettled）。
- * 回调体原为 subagent-service.ts buildSessionRunnerContext 的内联闭包，D4-② 拆出。 */
-export function createRoundSettler(deps: RoundSettlementDeps): (record: ExecutionRecord) => void {
-  return (record) => {
-    // v4 B-1：status 保持 running（旧 idle 折入 running）；session-runner 已 arm idle timer，
-    // isIdle=true 让 notify 守卫放行（时序：armIdleTimer → onRoundSettled，见 session-runner.ts:670）。
-    // round 可能初始 undefined（与 notifier.ts `record.round ?? 0` 兜底一致），
-    // 首轮 0+1=1。round 是 notifier dedup key 的组成部分，递增后同 id 下一轮不被 60s dedup 吞。
-    record.round = (record.round ?? 0) + 1;
-    // [N2][增量] 轮次回复写点（增量语义）：roundText 自 roundBaseTurnIndex 起派生本轮增量
-    //（undefined 视为 0——首轮增量 = 全量，与改造前首轮逐字节一致）。成功轮次的 MF-2 原写点
-    //（doFinalizeRoundToIdle）不可达——agent_settled 恒 arm idle timer → runAndFinalize 恒
-    // early return。写入 record.result 后再 notify；本轮无非空增量且无 lastError（纯工具轮 /
-    // interrupt 抢占轮 / 模型空回复）时固定占位 "(no output this round)"（D5：增量语义下沿用
-    // 旧 record.result = 上一轮增量 → 本轮通知正文 = 上一轮内容，父 agent 误读为原样重复回复；
-    // lastError 兜底保留让失败轮通知可读）。后续 closeAfterRoundSettled 的合成 result 读
-    // record.result，同样携带本轮增量。
-    const roundText = getFullTextFrom(record, record.roundBaseTurnIndex ?? 0);
-    record.result = roundText ||
-      (record.lastError ? `round did not complete: ${record.lastError}` : "(no output this round)");
-    // 先送达本轮增量（notify），再推进 base / 消费 closeAfterRound——终态通知由
-    // closeAfterRoundSettled / closeChatIdle 的 notifyClosed 显式发出（dedup 身份为裸 id，
-    // 与本次 round notify 的 id:round key 区分），保证「本轮增量 + 终态通知」都送达；
-    // 轮次收尾 .then 的冷路径 notifyComplete 仍与本次 round notify 同 key 被 60s
-    // dedup 吞（不构成第三条）。
-    //
-    // 幂等性（覆盖面如实限定）：同步路径 at-least-once——notifyComplete（同步 void）抛错时
-    // 推进/消费被跳过 → base 不推进 → 增量未消费，下轮 roundText 必含本轮文本（重发载体为
-    // 后续轮次增量拼接）。轮次收尾 .then 的冷路径 notifyComplete 不构成重发通道
-    // （notifier dedup.set 与 pending.splice 均先于 sendMessage，同 key `${id}:${round}`——
-    // round 已递增——60s 窗内重入被吞）。异步 flush 窗口不保证：合并 timer armed（其他 busy
-    // background 在场）或 isIdle 退避期间 notify 的『成功』只是入队，实际 sendMessage 发生在
-    // base 推进之后的异步时机；该窗口进程崩溃或 sendMessage 失败 → 丢失不可重发（现状全量
-    // 重发的次轮自愈在增量语义下消失），wave1 期恢复通道仅父 agent 经 /subagents 详情读取
-    // record.result，wave2 指针行落地后补全。反序（先推进后 notify）在同步路径 notify 失败时
-    // 静默丢增量且无任何重算机会，故 notify 后推进是定案。重复发送由 notifier dedup key
-    // 60s 窗界定。
-    deps.notifyComplete(record);
-    // R1 观测哨（不变式违反形态）：推进前检查末 turn 未闭合且 text 非空——pi 现序下不可达
-    //（带 usage 的 message_end 恒先于 turn_end，settle 时 turn 全闭合，见 types.ts
-    // roundBaseTurnIndex 注释的行号锚定），ES1 单测自造事件序列锁不住 pi 层变化；pi 升级若
-    // 改变 turn_end/agent_end 时序，此哨兵留痕（该形态下公式仍把文本计入本轮，不丢数据）。
-    const lastTurn = record.turns[record.turns.length - 1];
-    if (lastTurn !== undefined && !lastTurn.closed && lastTurn.text.length > 0) {
-      logger.warn(
-        `[subagents] round settle with unclosed non-empty turn (record=${record.id}, turnIndex=${record.turns.length - 1}) — pi turn_end/agent_end ordering may have changed`,
-      );
-    }
-    // [增量] base 推进（notify 之后）：下一轮增量从本轮边界起。滞后空 turn 不计入边界
-    //（防御分支，留在下一轮增量内防丢文本——nextRoundBaseTurnIndex 注释）。
-    record.roundBaseTurnIndex = nextRoundBaseTurnIndex(record);
-    // 轮终迁移持久化（residual-fixes U3 补全）：热路径轮终不经 doFinalizeRoundToIdle
-    //（agent_settled 恒 arm idle timer → runAndFinalize 恒 early return，MF-2 原写点
-    // 不可达）——不 appendEntry 则 runtime/W18 派生缓存不失效，renderer 停留在
-    // register 快照（无 result），chat 等续聊的 waiting 形态显示不出来、spinner
-    // 卡死。显式上报：entry 携带本轮 result/round/chatMode（§5.4：result 有值 +
-    // chatMode=true → waiting）。closeAfterRound 的终态 entry 在此后追加，序不变。
-    deps.reportRecordTransition(record);
-    // [M5] closeAfterRound 消费点：chatMode 每轮完成的统一汇聚点（热路径轮不经
-    // runAndFinalize CAS 分支——agent_settled 恒 arm idle timer → runAndFinalize 恒
-    // early return，旧消费点对 chatMode 不可达，标志置了无人消费、tool 谎报 closed:true）。
-    if (record.closeAfterRound) {
-      record.closeAfterRound = undefined;
-      void deps.closeAfterRoundSettled(record);
-    }
-  };
-}

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

@@ -1,215 +0,0 @@
-// src/execution/ui-request-queue.ts
-//
-// W3/W2: 子进程 extension_ui_request 的 FIFO 串行队列 + 转发处理。
-//
-// 从 session-runner.ts 提取（保持文件 < 1000 行）。职责单一：
-//   - createUiRequestQueue：每个子进程一个队列，保证多个 UI 请求（ask_user 等）
-//     FIFO 串行处理，防止并发询问用户导致交错。
-//   - handleUiRequest：从 ExtensionUiRequest 构造 UiRequest → 调主 agent uiRequestHandler
-//     → 按 UiResponse 形状回写 stdin。
-//   - extractMethodFields：method-specific 字段类型安全复制。
-//
-// session-runner.runSpawn 在 stdout pump 中拿到 extension_ui_request 后调 enqueue 入队。
-
-import type { ChildProcess } from "node:child_process";
-
-import { getLogger } from "../core/logger.ts";
-
-import type { UiRequest } from "./dialog-queue.ts";
-// 类型再导出：dialog-queue.ts 是 UiRequest/UiResponse/UiRequestHandler 的规范来源，
-// 本模块再导出供测试 import（避免测试直接依赖 dialog-queue 内部实现）。
-export type { UiRequest, UiRequestHandler, UiResponse } from "./dialog-queue.ts";
-import type { SessionRunnerContext } from "./engine/engines/pi/session-runner.ts";
-import type { ExtensionUiRequest } from "./engine/engines/pi/spawn-event-adapter.ts";
-import { respond } from "./engine/engines/pi/stdin-writer.ts";
-import { parseChannel } from "./ui-channels.ts";
-import { notifyMissingHandlerGlobal } from "./ui-request-observability.ts";
-import { toErrorMessage } from "../core/error-message.ts";
-
-const logger = getLogger("subagents");
-
-/**
- * 创建 UI 请求队列。返回 enqueue 函数，调用方将 extension_ui_request 入队。
- *
- * 多个 extension_ui_request 并发到达时，队列保证 FIFO 串行处理：
- * 前一个请求的 uiRequestHandler resolve 后，才将下一个请求发给主 agent UI。
- * 防止并发询问用户导致交错（用户同时看到多个问题）。
- *
- * 设计：队列是 runSpawn 生命周期内的闭包状态（非模块级），
- * 每个子进程实例独立队列，无跨 session 泄漏。
- *
- * @param child 子进程（stdin 写入 extension_ui_response）
- * @param ctx SessionRunnerContext（含 uiRequestHandler 回调）
- * @returns enqueue 函数：(id, request) => void，将请求入队并触发顺序处理
- */
-export function createUiRequestQueue(
-  child: ChildProcess,
-  ctx: SessionRunnerContext,
-): (id: string, request: ExtensionUiRequest) => void {
-  // [R3] AbortController 取消 pending handler——子进程退出时队列不再阻塞
-  const abortController = new AbortController();
-  const queue: Array<{ id: string; request: ExtensionUiRequest; signal: AbortSignal }> = [];
-  let processing = false;
-  let closed = false;
-
-  function processNext(): void {
-    if (processing || queue.length === 0 || closed) return;
-    processing = true;
-    const { id, request, signal } = queue.shift()!;
-    // [F2] .catch 在 .finally 之前：handleUiRequest 是 async 函数，任何同步异常（parseChannel
-    // 解析 throw / respond → writeStdinLine 的 EPIPE 同步 throw / catch 分支内 respond 再次
-    // throw）都会变成 rejection。旧链只有 .finally——rejection 穿透后无人接 →
-    // unhandledRejection（Node 15+ 默认 mode=throw）可崩父进程。记 error 后吞掉，
-    // .finally 照常释放 processing 推进队列（单个请求失败不阻塞后续 UI 请求）。
-    handleUiRequest(child, id, request, ctx, signal)
-      .catch((err: unknown) => {
-        const m = toErrorMessage(err);
-        logger.error(`[subagents] ui request ${id} (${request.method}) failed unexpectedly: ${m}`);
-      })
-      .finally(() => {
-        processing = false;
-        processNext();
-      });
-  }
-
-  // [R3] 子进程退出时 abort 所有 pending handler，队列不再阻塞
-  // [SR-4] 同步清理 L2 队列中该 child 的 pending dialog——child 在 dialog 等 L2 时退出，
-  //   L2 里该项永不 settle → processing 永远 true → 所有其他子进程 dialog 永久阻塞（全局死锁）。
-  //   pid 缺省（spawn 后极短窗口 child.pid 可能为 undefined）时跳过——此时该 child 还未在 L2
-  //   注册过任何 dialog（handleUiRequest 构造 UiRequest 时用同样的 child.pid，pid undefined 时
-  //   不填 _childPid，rejectChildDialogs 也匹配不到），无清理必要。
-  const onClose = (): void => {
-    // #19/#17 幂等守卫：close + error 可能都触发，二次调用会重复 rejectChildDialogs（虽依赖 L2 的 settled 幂等，
-    // 但 close 状态本身需守卫——避免 closed=true 后 queue.length=0 + abort 重复执行，以及重复 reject 导致语义噪声）。
-    if (closed) return;
-    closed = true;
-    abortController.abort();
-    queue.length = 0;
-    if (child.pid !== undefined) {
-      ctx.dialogQueue?.rejectChildDialogs({ pid: child.pid });
-    }
-  };
-  child.on("close", onClose);
-  child.on("error", onClose);
-
-  return function enqueue(id: string, request: ExtensionUiRequest): void {
-    if (closed) return;
-    queue.push({ id, request, signal: abortController.signal });
-    processNext();
-  };
-}
-
-/**
- * 处理子进程发来的 extension_ui_request（ask_user 及其他 Pi UI method）。
- *
- * 流程：从 ExtensionUiRequest 构造 UiRequest（含 channel/channelPayload）
- *  → 调用主 agent uiRequestHandler → 按 UiResponse 形状回写 stdin。
- *
- * handler 未设置时不再静默忽略——console.warn 兜底（FR-9 可观测性），
- * W3 接入 SubagentService.notifyMissingHandler 的 appendEntry。
- *
- * @param child 子进程（stdin 写入响应）
- * @param id 请求 id（子进程用它关联 response）
- * @param request ExtensionUiRequest（method 平铺，从 enqueueUiRequest 传入）
- * @param ctx SessionRunnerContext（含 uiRequestHandler 回调）
- * @param signal abort signal（子进程退出时触发，取消正在等待的 handler）
- * @returns Promise（队列等待用：resolve 表示响应已写入 stdin 或已放弃）
- */
-async function handleUiRequest(
-  child: ChildProcess,
-  id: string,
-  request: ExtensionUiRequest,
-  ctx: SessionRunnerContext,
-  signal?: AbortSignal,
-): Promise<void> {
-  const handler = ctx.uiRequestHandler;
-  if (!handler) {
-    // #9 + #11：handler 缺失时不再静默 return（会让子进程永久挂起等 response）。
-    //   - notifyMissingHandlerGlobal：经 globalThis 桥接到 observability 单例做 per-session 去重告警
-    //     （FR-9 可观测性；未注册时走 fallback warn 不丢日志）
-    //   - respond(cancelled)：让子进程收到明确取消，不再永久挂起。等价于用户主动取消的语义。
-    // 去重 key 用 child.pid（队列内拿不到真实 sessionId；pid 是子进程会话的稳定标识，
-    // 去重粒度正确——同一子进程多次 handler 缺失只告警一次）。
-    notifyMissingHandlerGlobal(child.pid?.toString() ?? id);
-    respond(child, id, { cancelled: true }, signal);
-    return;
-  }
-
-  // 从 ExtensionUiRequest 构造 UiRequest（含 channel/channelPayload）
-  const { channel, channelPayload } = parseChannel(request);
-  // [SR-4] 填入 child.pid 作为内部元数据：L2 队列的 rejectChildDialogs 据此关联 child close
-  //   清理。factory 层 enqueue 时读 req._childPid 传给 opts.child。pid undefined（spawn 后极短
-  //   窗口）时不填——rejectChildDialogs 也匹配不到（onClose 同样用 child.pid 守卫），无副作用。
-  const uiReq: UiRequest = {
-    id,
-    method: request.method,
-    ...(child.pid !== undefined ? { _childPid: child.pid } : {}),
-    ...(channel !== undefined ? { channel } : {}),
-    ...(channelPayload !== undefined ? { channelPayload } : {}),
-    ...extractMethodFields(request),
-  };
-
-  try {
-    const result = await handler(uiReq);
-    // [R3] 子进程已退出，跳过写入
-    if (signal?.aborted) return;
-    respond(child, id, result, signal);
-  } catch (err) {
-    // [R3] 子进程已退出，跳过写入
-    if (signal?.aborted) return;
-    logger.error("[subagents] uiRequestHandler threw", {
-      detail: toErrorMessage(err),
-    });
-    respond(child, id, { cancelled: true }, signal);
-  }
-}
-
-/** method-specific 字段值守卫（与原 inline 判定 1:1：`typeof === "string"` / `"number"` / `Array.isArray`）。 */
-function isStringValue(value: unknown): boolean {
-  return typeof value === "string";
-}
-
-function isNumberValue(value: unknown): boolean {
-  return typeof value === "number";
-}
-
-function isArrayValue(value: unknown): boolean {
-  return Array.isArray(value);
-}
-
-/** extractMethodFields 字段复制规格表（与 Pi rpc-types.ts 1:1，序 = 原复制序）。
- *  guard = in 命中后的值类型守卫（验不过不复制）；null = 仅 in 检查直赋
- *（原 statusText/widgetLines/widgetPlacement 无类型守卫的形态）。 */
-const METHOD_FIELD_COPY_SPECS: ReadonlyArray<{
-  key: string;
-  guard: ((value: unknown) => boolean) | null;
-}> = [
-  { key: "title", guard: isStringValue },
-  { key: "options", guard: isArrayValue },
-  { key: "message", guard: isStringValue },
-  { key: "placeholder", guard: isStringValue },
-  { key: "prefill", guard: isStringValue },
-  { key: "notifyType", guard: isStringValue },
-  { key: "statusKey", guard: isStringValue },
-  { key: "statusText", guard: null },
-  { key: "widgetKey", guard: isStringValue },
-  { key: "widgetLines", guard: null },
-  { key: "widgetPlacement", guard: null },
-  { key: "text", guard: isStringValue },
-  { key: "timeout", guard: isNumberValue },
-];
-
-/** 从 ExtensionUiRequest 提取 method-specific 字段到 UiRequest（与 Pi rpc-types.ts 1:1）。
- *  按 method 变体类型安全地复制对应字段；缺失字段不复制（保持 UiRequest 可选）。
- *  断言说明：source/out 的 Record 断言仅为动态 key 索引，复制经 in 检查 + guard 运行时守卫。 */
-function extractMethodFields(req: ExtensionUiRequest): Partial<UiRequest> {
-  const out: Partial<UiRequest> = {};
-  const source: Record<string, unknown> = req;
-  for (const { key, guard } of METHOD_FIELD_COPY_SPECS) {
-    if (!(key in source)) continue;
-    const value = source[key];
-    if (guard !== null && !guard(value)) continue;
-    (out as Record<string, unknown>)[key] = value;
-  }
-  return out;
-}

package/src/shared/schema-env.ts

@@ -1,44 +0,0 @@
-/**
- * schema env 跨包契约常量（零依赖叶子模块）。
- *
- * 抽取自 session-runner.ts（S5 记账项）：session-runner 依赖树沉重（pi SDK /
- * spawn 链），跨包契约测试若从它 import 常量会把整条依赖树拖进测试进程。
- * 本模块只含常量与纯函数、零 import，为 structured-output 侧（及任何消费者）
- * 的跨包契约测试提供稳定 import 点。
- *
- * 层归属：Shared（orchestration 与 execution 共用，先例 timer-delay.ts）。
- */
-
-/**
- * 跨包契约 env 名：workflow 子进程把权威 JSON Schema 通过此 env 传给 structured-output 扩展。
- *
- * [跨包契约 SSOT] 此字面量是两个独立 npm 包（@zhushanwen/pi-subagent-workflow 与
- * @zhushanwen/pi-structured-output）之间的隐式 env 契约。structured-output 包内同名常量为
- * `ENV_SCHEMA = "PI_WORKFLOW_SCHEMA"`（见 extensions/universal/structured-output/src/index.ts）。
- * 两包是独立 npm 包不能直接 import，故各自保留常量但显式标注此契约关系——
- * 任一端改名必须同步另一端，否则权威 schema 注入会静默断桥（子进程不注册 tool/hook）。
- */
-export const SCHEMA_ENV_VAR = "PI_WORKFLOW_SCHEMA";
-
-/**
- * schema env 值的字节上限（256 KiB）：超过则注入前 fail-fast 拒绝。
- *
- * 背景（SO-DATA-4）：schema 经 childEnv 注入子进程，env 值随 spawn argv/env 块走
- * execve 语义——单条 env 值过大叠加全量继承的 process.env 时可能触发 E2BIG
- *（ARG_MAX 约束，Linux 通常 ~2MB 总上限，macOS 更紧），spawn 直接失败且错误难归因
- *（E2BIG 报在 spawn 调用点，与 schema 内容无关的表象）。256KB 对 JSON Schema 是
- * 宽裕上限（正常 schema 数 KB），提前拒绝把「难归因的 spawn 失败」变成
- * 「注入点处含实际大小的明确报错」。
- */
-/** 1 KiB 字节数（换算基数，SCHEMA_ENV_MAX_BYTES 组合用）。 */
-const BYTES_PER_KIB = 1024;
-/** 上限的 KiB 形态（256 KiB = 262144 bytes，注释与文档引用值）。 */
-const SCHEMA_ENV_MAX_KIB = 256;
-export const SCHEMA_ENV_MAX_BYTES = SCHEMA_ENV_MAX_KIB * BYTES_PER_KIB;
-
-/**
- * 计算 schema env 值的 UTF-8 字节长度（注入大小 = 该值，用于超限判定与错误消息）。
- */
-export function schemaEnvByteLength(schemaEnv: string): number {
-  return Buffer.byteLength(schemaEnv, "utf8");
-}