@zhushanwen/pi-subagent-workflow 0.1.0

package/src/execution/subprocess-agent-runner.ts

@@ -0,0 +1,108 @@
+// src/execution/subprocess-agent-runner.ts
+//
+// Wave 4: SubprocessAgentRunner 委托重写
+//
+// 从"自己 spawn pi"改为"委托 SubagentService.executeAndAwait"。
+// MF-3: 从 orchestration/infra 迁入 execution，同层委托 SubagentService。
+//
+// 接线层级：
+//   [跨模块 port] implements AgentRunner（orchestration/models/ports.ts）
+//   [模块内直调] mapToExecuteOptions + mergeTimeoutSignal（execute-options-mapper）
+//   [模块内直调] this.subagentService.executeAndAwait
+//
+// 设计基线：
+//   D-A2（映射归 adapter）/ D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
+//   D-008（model 填底，不调 resolveModel）/ BC-9（timeoutMs 行为）/ BC-10（live-record 进度）
+
+import type { AgentEvent } from "../shared/agent-event.ts";
+import type { AgentRunner } from "../orchestration/models/ports.ts";
+import type { AgentCallOpts, AgentResult } from "../orchestration/models/types.ts";
+import type { ModelInfo } from "./model-resolver.ts";
+import type { SubagentService } from "./subagent-service.ts";
+import type { ExecuteOptions } from "./types.ts";
+import { mapToExecuteOptions, mergeTimeoutSignal } from "./execute-options-mapper.ts";
+
+// ── 构造依赖（per-session 注入）──
+
+/**
+ * SAR 构造参数。
+ *
+ * per-session（makeDeps 时创建，随 session 销毁）：
+ *   - subagentService: 进程单例（getSubagentService()），委托目标
+ *   - ctxModel: 当前 session 主 agent 模型（D-008 model 填底，opts.model 空时用此）
+ *
+ * 不含 agentRegistry/sessionDir/activeTempFiles——resolveAgentOpts 在 orchestration 层
+ * 完成（D-A3），结果已填进 AgentCallOpts.skillPath/schemaEnv，SAR 收已解析的 opts。
+ */
+export interface SubprocessAgentRunnerDeps {
+  subagentService: SubagentService;
+  ctxModel?: ModelInfo;
+}
+
+/**
+ * AgentRunner port 实现——委托 SubagentService.executeAndAwait。
+ *
+ * 层归属：execution（MF-3 从 orchestration 迁入）。implements orchestration 层 port。
+ *
+ * 行为契约（BC-1/BC-2/BC-9/BC-10）：
+ *   - opts 形状不变（AgentCallOpts，含 resolveAgentOpts 填的 skillPath/schemaEnv）
+ *   - result 形状不变（workflow AgentResult: content/parsedOutput/usage/error/toolCalls）
+ *   - 不 reject——失败信息入 result.error（与 executeAgentCall 契约一致）
+ *   - timeoutMs 合并 signal（D-A9）；onEvent 桥接 AgentEvent→workflow liveRecord（D-A8）
+ */
+export class SubprocessAgentRunner implements AgentRunner {
+  private readonly subagentService: SubagentService;
+  private readonly ctxModel: ModelInfo | undefined;
+
+  constructor(deps: SubprocessAgentRunnerDeps) {
+    this.subagentService = deps.subagentService;
+    this.ctxModel = deps.ctxModel;
+  }
+
+  /**
+   * 执行单次 agent 调用：委托 SubagentService.executeAndAwait。
+   *
+   * 接线链路：
+   *   mergeTimeoutSignal → mapToExecuteOptions →
+   *   this.subagentService.executeAndAwait → 返回 AgentResult
+   *
+   * 错误处理：不 reject。
+   *   - executeAndAwait 内部失败 → 返回 AgentResult(success:false) → 已映射 error 字段
+   *   - executeAndAwait throw（嵌套超限 BC-12）→ catch → AgentResult.error
+   *   - spawn 级失败已由 runSpawn 内部收口为 failed AgentResult（不逃逸）
+   */
+  async run(
+    opts: AgentCallOpts,
+    signal: AbortSignal,
+    onEvent?: (event: AgentEvent) => void,
+  ): Promise<AgentResult> {
+    const startedAt = Date.now();
+
+    try {
+      // ── D-A9: timeoutMs 合并 signal ──
+      const mergedSignal = mergeTimeoutSignal(signal, opts.timeoutMs);
+
+      // ── D-A2 + D-008: AgentCallOpts → ExecuteOptions 映射 ──
+      const mappedOpts: ExecuteOptions = mapToExecuteOptions(opts, this.ctxModel);
+
+      // ── D-A8: onEvent 桥接 ──
+      // executeAndAwait 发强类型 AgentEvent（session-runner handleSdkEvent 出口）。
+      // workflow 的 onEvent 闭包（error-recovery.ts dispatchAgentCall）类型已升级为
+      // (event: AgentEvent) => updateFromEvent(liveRecord, event)（D-005）。
+      // SAR 直接透传 onEvent——类型对齐后零桥接开销。
+      const bridgedOnEvent = onEvent;
+
+      // ── 核心委托 ──
+      return await this.subagentService.executeAndAwait(mappedOpts, mergedSignal, bridgedOnEvent);
+    } catch (err) {
+      // executeAndAwait throw（嵌套超限 ForkDepthExceededError，BC-12）或未预期异常 → 不 reject，入 error。
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        content: "",
+        durationMs: Date.now() - startedAt,
+        error: message,
+        toolCalls: [],
+      };
+    }
+  }
+}

package/src/execution/temp-prompt.ts

@@ -0,0 +1,57 @@
+// src/core/temp-prompt.ts
+//
+// 将 agent systemPrompt 写入临时文件，供 pi CLI --append-system-prompt 使用。
+// Core 叶子原语（仅依赖 node 内置）。
+//
+// pi CLI 的 --append-system-prompt 接受文件路径（非内联字符串），故 spawn 前
+// 需把 systemPrompt 落盘。每次调用创建唯一临时目录，用完由 runSpawn 清理。
+//
+// 移植自 nicobailon subagent example，去掉 withFileMutationQueue（目录已唯一，
+// 无并发写入风险，queue 冗余）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** 临时 prompt 文件创建结果。dir 供调用方清理。 */
+export interface TempPromptFile {
+  /** 临时目录绝对路径（mkdtemp 创建，调用方负责删除）。 */
+  dir: string;
+  /** prompt 文件绝对路径（dir 下）。 */
+  filePath: string;
+}
+
+/**
+ * 将 systemPrompt 写入临时文件。
+ *
+ * @param agentName agent 名称（用于文件名，非法字符替换为 _）
+ * @param prompt systemPrompt 全文
+ * @returns 临时文件信息（dir + filePath）
+ *
+ * 安全：文件权限 0o600（仅 owner 读写），防止其他用户读取 prompt 内容。
+ * 目录用 mkdtemp 保证唯一，无需额外锁。
+ */
+export async function writePromptToTempFile(
+  agentName: string,
+  prompt: string,
+): Promise<TempPromptFile> {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
+  const safeName = agentName.replace(/[^\w.-]+/g, "_");
+  const filePath = path.join(dir, `prompt-${safeName}.md`);
+  await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+  return { dir, filePath };
+}
+
+/**
+ * 删除临时 prompt 目录（含文件）。best-effort，失败不抛。
+ *
+ * runSpawn 的 finally 调用，确保临时文件不泄漏。子进程可能仍持有文件句柄
+ * （--append-system-prompt 读取后即释放），rm 用 recursive 容错。
+ */
+export async function cleanupTempPrompt(file: TempPromptFile): Promise<void> {
+  try {
+    await fs.promises.rm(file.dir, { recursive: true, force: true });
+  } catch {
+    // best-effort：临时文件泄漏不影响功能，OS tmpdir 清理机制兜底
+  }
+}

package/src/execution/tombstone-store.ts

@@ -0,0 +1,72 @@
+// src/runtime/execution/tombstone-store.ts
+//
+// Cancelled 状态的 sidecar 持久化。
+//
+// 背景：用户 cancel background subagent 时 session.abort() → prompt() reject →
+// session.jsonl 被中途截断（无最终 assistant message，无 stopReason 标记）。所以
+// cancelled 状态无法从 session.jsonl 可靠检测。本模块在 session.jsonl 旁写一个
+// `.cancelled` sidecar 文件（单行 JSON），collectRecords 重建时读它 override status。
+//
+// 设计：单条 cancelled = 单 sidecar，无全局 index 可损坏，无并发问题，被现有
+// session-file-gc 的目录扫描自然清理（GC 已扩展为也清理 .cancelled）。YAGNI 更重方案。
+
+import * as fs from "node:fs";
+
+// ============================================================
+// 类型
+// ============================================================
+
+/** Tombstone 内容（单行 JSON）。 */
+export interface CancelledTombstone {
+  id: string;
+  status: "cancelled";
+  agent: string;
+  startedAt: number;
+  endedAt: number;
+}
+
+// ============================================================
+// 公开函数
+// ============================================================
+
+/**
+ * 在 session.jsonl 旁写 cancelled tombstone。
+ * best-effort：任何 I/O 错误静默（cancel 已成功，持久化是次要的——内存 record 即将被
+ * archive 淘汰，下次读靠 tombstone 标记 cancelled）。
+ */
+export function writeCancelledTombstone(sessionFile: string, meta: CancelledTombstone): void {
+  try {
+    const tombstonePath = `${sessionFile}.cancelled`;
+    fs.writeFileSync(tombstonePath, `${JSON.stringify(meta)}\n`, "utf-8");
+  } catch (_e) {
+    void _e; // 静默：写失败不阻断 cancel 主流程（status 已在内存 record 上设好）。
+  }
+}
+
+/**
+ * 读 session.jsonl 旁的 cancelled tombstone。
+ * 返回 undefined：sidecar 不存在 / 损坏 / 解析失败。
+ */
+export function readCancelledTombstone(sessionFile: string): CancelledTombstone | undefined {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(`${sessionFile}.cancelled`, "utf-8");
+  } catch {
+    return undefined; // sidecar 不存在（正常——非 cancelled record 无 sidecar）。
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<CancelledTombstone>;
+    if (
+      typeof parsed.id === "string" &&
+      parsed.status === "cancelled" &&
+      typeof parsed.agent === "string" &&
+      typeof parsed.startedAt === "number" &&
+      typeof parsed.endedAt === "number"
+    ) {
+      return parsed as CancelledTombstone;
+    }
+    return undefined; // 结构不合法 → 降级。
+  } catch {
+    return undefined; // JSON 损坏 → 降级。
+  }
+}

package/src/execution/turn-limiter.ts

@@ -0,0 +1,88 @@
+// src/core/turn-limiter.ts
+//
+// soft/hard turn 限制器。maxTurns 到达 → steer 提醒收尾；
+// graceTurns 后仍不结束 → abort。
+
+/** steer 提醒消息：要求 agent 总结已完成/未完成/下一步，不得谎报完成。 */
+const WRAP_UP_MESSAGE = [
+  "You have reached your turn limit. Wrap up now:",
+  "1. Summarize what you have completed (with evidence: file paths, command output).",
+  "2. List what remains undone and why.",
+  "3. State the single most important next step for whoever continues.",
+  "Do NOT claim the task is complete if any part remains unfinished.",
+].join(" ");
+
+/**
+ * 预防性 wrap-up 提示（启动时注入 --append-system-prompt）。
+ *
+ * spawn 模式下 runSpawn 无法在达 maxTurns 时运行时注入 steer（pi `--mode json` 是
+ * single-shot，无 stdin 命令通道；见 session-runner.ts limiter 注释）。作为短期补偿，
+ * 在启动时预置此预防性指令，让 agent 在感知接近上限时主动收尾。
+ *
+ * 长期方案是切到 pi `--mode rpc`（支持运行时 steer 命令），见 follow-up。
+ */
+export const WRAP_UP_HINT = [
+  `You have a turn limit. As you sense you are approaching it, proactively wrap up:`,
+  "1. Summarize what you have completed (with evidence: file paths, command output).",
+  "2. List what remains undone and why.",
+  "3. State the single most important next step for whoever continues.",
+  "Do NOT claim the task is complete if any part remains unfinished.",
+].join(" ");
+
+/** turn limiter 配置。 */
+export interface TurnLimiterOptions {
+  maxTurns: number;
+  graceTurns: number;
+  steer: (msg: string) => void;
+  abort: () => void;
+}
+
+/**
+ * soft/hard turn 限制。
+ *
+ *   onTurnEnd(currentTurns):
+ *     已 aborted 或 maxTurns<=0（禁用）→ 直接 return
+ *     currentTurns >= maxTurns 且未 steer → steer(WRAP_UP_MESSAGE)（仅一次）
+ *     已 steer 且 currentTurns >= maxTurns + graceTurns → abort()（仅一次）
+ *
+ * maxTurns<=0 表示不限（limit=Infinity，永不触发）。
+ * graceTurns<=0 时 steer 后下一 turn 即 abort。
+ */
+export interface TurnLimiter {
+  /** 每次 turn_end 调用。 */
+  onTurnEnd(currentTurns: number): void;
+  /** 是否已发过 steer（诊断用）。 */
+  readonly didSteer: boolean;
+  /** 是否已 abort（诊断用）。 */
+  readonly didAbort: boolean;
+}
+
+/** 工厂函数。 */
+export function createTurnLimiter(opts: TurnLimiterOptions): TurnLimiter {
+  let steered = false;
+  let aborted = false;
+  const limit = opts.maxTurns > 0 ? opts.maxTurns : Infinity;
+  const grace = opts.graceTurns > 0 ? opts.graceTurns : 0;
+
+  const onTurnEnd = (turn: number): void => {
+    if (aborted || !Number.isFinite(limit)) return;
+    if (!steered && turn >= limit) {
+      steered = true;
+      opts.steer(WRAP_UP_MESSAGE);
+    }
+    if (steered && turn >= limit + grace) {
+      aborted = true;
+      opts.abort();
+    }
+  };
+
+  return {
+    onTurnEnd,
+    get didSteer(): boolean {
+      return steered;
+    },
+    get didAbort(): boolean {
+      return aborted;
+    },
+  };
+}