@zhushanwen/pi-subagent-workflow 0.1.0

package/src/orchestration/__tests__/workflow-nesting-e2e.test.ts

@@ -0,0 +1,319 @@
+/**
+ * workflow() 嵌套调用 — E2E 集成测试。
+ *
+ * 从 handleWorkerMessage 入口（发 workflow-call 消息）出发，走完完整链路：
+ * handleWorkerMessage → dispatchWorkflowCall → deps.onWorkflowCall(executeNestedWorkflow)
+ * → runWorkflow(mock) → pollRunToResult → postMessage(workflow-result)。
+ *
+ * 验证 Wave 1（协议层 dispatchWorkflowCall）与 Wave 2（实现 executeNestedWorkflow）
+ * 的端到端对接正确。
+ *
+ * Mock 策略：
+ * - vi.mock("../lifecycle.ts") 控制 runWorkflow：返回固定 runId + 把预构造的 child run
+ *   注入 deps.runs（使 pollRunToResult 首轮命中 done）
+ * - deps.registry.get 返回预定义 WorkflowScript
+ * - parent runtime.worker.postMessage 捕获 workflow-result 消息
+ * - deps.onWorkflowCall 用真实的 executeNestedWorkflow 注入（模拟 Interface 层 makeDeps）
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// vi.mock 必须在 import 之前（hoisting 保证拿到 mock 版本）
+vi.mock("../lifecycle.ts", () => ({
+  runWorkflow: vi.fn(),
+  abortRun: vi.fn(async () => {}),
+  pauseRun: vi.fn(async () => {}),
+  resumeRun: vi.fn(async () => {}),
+  scheduleTimeBudget: vi.fn(() => undefined),
+}));
+
+import { handleWorkerMessage } from "../error-recovery.ts";
+import { executeNestedWorkflow, type LauncherDeps } from "../launcher.ts";
+import { runWorkflow } from "../lifecycle.ts";
+import { Budget } from "../models/budget.ts";
+import type { RunSpec } from "../models/run-spec.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import type { WorkflowRun } from "../models/workflow-run.ts";
+import type { WorkflowScript } from "../models/workflow-script.ts";
+import type { LintResult } from "../script-lint.ts";
+
+const MOCK_RUN_ID = "wf-e2e-child";
+
+// ── helpers ──────────────────────────────────────────────────
+
+/** flush microtask 队列，让 void .then().catch() 异步链路跑完。 */
+async function flushMicrotasks(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/** 构造 mock WorkflowScript（validate / toExecutable 可控）。 */
+function makeScript(opts: { valid?: boolean; lintErrorMsg?: string } = {}): WorkflowScript {
+  const valid = opts.valid ?? true;
+  return {
+    name: "child-wf",
+    path: "/fake/child-wf.js",
+    meta: { name: "child-wf", description: "child workflow", phases: [] },
+    toExecutable: () => "const meta = {}; execute() {}",
+    validate: (): LintResult => ({
+      valid,
+      findings: valid
+        ? []
+        : [
+            {
+              severity: "error",
+              line: 3,
+              message: opts.lintErrorMsg ?? "lint boom",
+              suggestion: "fix it",
+            },
+          ],
+    }),
+  } as unknown as WorkflowScript;
+}
+
+/**
+ * 构造 mock parent WorkflowRun（status="running"，有 postMessage + controller）。
+ *
+ * 同时满足 handleWorkerMessage（需 status + runtime.worker）和 executeNestedWorkflow
+ * （需 spec.scriptName/chain + runtime.controller.signal + state.budget）的要求。
+ */
+function makeParentRun(opts: {
+  scriptName?: string;
+  parentWorkflowChain?: readonly string[];
+  budget?: Budget;
+  postMessage?: ReturnType<typeof vi.fn>;
+} = {}): WorkflowRun {
+  const controller = new AbortController();
+  const postMessage = opts.postMessage ?? vi.fn();
+  return {
+    spec: {
+      scriptName: opts.scriptName ?? "parent-wf",
+      parentWorkflowChain: opts.parentWorkflowChain,
+    },
+    state: {
+      status: "running",
+      budget: opts.budget ?? new Budget({ maxTokens: 10000 }),
+    },
+    runtime: { controller, worker: { postMessage } },
+  } as unknown as WorkflowRun;
+}
+
+/** 构造 mock child WorkflowRun（done 终态，pollRunToResult 首轮命中）。 */
+function makeDoneChildRun(opts: {
+  reason?: "completed" | "failed" | "aborted";
+  scriptResult?: unknown;
+  error?: string;
+  usedTokens?: number;
+  usedCost?: number;
+}): WorkflowRun {
+  const reason = opts.reason ?? "completed";
+  return {
+    runId: MOCK_RUN_ID,
+    spec: { scriptName: "child-wf" },
+    state: {
+      status: "done",
+      reason,
+      scriptResult: opts.scriptResult,
+      error: opts.error,
+      budget: { usedTokens: opts.usedTokens ?? 0, usedCost: opts.usedCost ?? 0 },
+    },
+  } as unknown as WorkflowRun;
+}
+
+/** 构造 LauncherDeps mock：registry + runs（Map）+ 占位 port。 */
+function makeDeps(opts: {
+  script?: WorkflowScript;
+  childRun?: WorkflowRun;
+  registry?: { get: ReturnType<typeof vi.fn> };
+} = {}): LauncherDeps {
+  const runs = new Map<string, WorkflowRun>();
+  if (opts.childRun) runs.set(MOCK_RUN_ID, opts.childRun);
+  const registry = opts.registry ?? {
+    get: vi.fn(async () => opts.script),
+  };
+  return {
+    registry,
+    runs,
+    store: { save: vi.fn(async () => {}), loadAll: vi.fn(async () => []) },
+    workerHost: { start: vi.fn(() => ({ postMessage: vi.fn() })) },
+    runner: { run: vi.fn(async () => ({})) },
+    log: vi.fn(),
+    eventBus: { emit: vi.fn() },
+  } as unknown as LauncherDeps;
+}
+
+/** 配置 runWorkflow mock：把 childRun 注入 deps.runs 并返回 MOCK_RUN_ID。 */
+function setupRunWorkflow(childRun: WorkflowRun): void {
+  vi.mocked(runWorkflow).mockImplementation(async (_spec, deps) => {
+    deps.runs.set(MOCK_RUN_ID, childRun);
+    return MOCK_RUN_ID;
+  });
+}
+
+/** WorkerHandlers 占位（workflow-call 路径不触发 handler 回调）。 */
+function makeHandlers(): WorkerHandlers {
+  return {
+    onMessage: vi.fn(async () => {}),
+    onError: vi.fn(async () => {}),
+    onExit: vi.fn(async () => {}),
+  } as unknown as WorkerHandlers;
+}
+
+interface PostedMsg {
+  type: string;
+  callId: number;
+  result: { content: string; parsedOutput?: unknown; error?: string };
+}
+
+/** 从 postMessage mock 取第 0 次调用的第 0 参，类型安全窄化。 */
+function firstPosted(postMessage: ReturnType<typeof vi.fn>): PostedMsg {
+  return postMessage.mock.calls[0]![0] as PostedMsg;
+}
+
+/**
+ * 把 executeNestedWorkflow 绑定为 deps.onWorkflowCall（模拟 Interface 层 makeDeps）。
+ *
+ * 闭包引用 deps——与 index.ts makeDeps 的模式一致。
+ */
+function wireOnWorkflowCall(deps: LauncherDeps): void {
+  (deps as LifecycleDeps).onWorkflowCall = (name, args, parentRun) =>
+    executeNestedWorkflow(name, args, parentRun, deps);
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+// ── tests ────────────────────────────────────────────────────
+
+describe("workflow() nesting end-to-end", () => {
+  it("end-to-end: workflow-call → executeNestedWorkflow → workflow-result posted back", async () => {
+    const postMessage = vi.fn();
+    const parent = makeParentRun({ postMessage });
+    const childRun = makeDoneChildRun({
+      reason: "completed",
+      scriptResult: { data: "test" },
+    });
+    const deps = makeDeps({ script: makeScript(), childRun });
+    setupRunWorkflow(childRun);
+    wireOnWorkflowCall(deps);
+
+    await handleWorkerMessage(
+      parent,
+      { type: "workflow-call", callId: 1, name: "child", args: {} },
+      deps,
+      makeHandlers(),
+    );
+    await flushMicrotasks();
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const sent = firstPosted(postMessage);
+    expect(sent.type).toBe("workflow-result");
+    expect(sent.callId).toBe(1);
+    expect(sent.result.content).toBe(JSON.stringify({ data: "test" }));
+    expect(sent.result.parsedOutput).toEqual({ data: "test" });
+    expect(sent.result.error).toBeUndefined();
+  });
+
+  it("end-to-end: circular call returns error result", async () => {
+    const postMessage = vi.fn();
+    // parent chain ["a"], scriptName "b" → target "a" 触发 a→b→a 循环
+    const parent = makeParentRun({
+      scriptName: "b",
+      parentWorkflowChain: ["a"],
+      postMessage,
+    });
+    const deps = makeDeps({ script: makeScript() });
+    wireOnWorkflowCall(deps);
+
+    await handleWorkerMessage(
+      parent,
+      { type: "workflow-call", callId: 2, name: "a", args: {} },
+      deps,
+      makeHandlers(),
+    );
+    await flushMicrotasks();
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const sent = firstPosted(postMessage);
+    expect(sent.result.error).toContain("Circular workflow call detected");
+    expect(sent.result.content).toBe("");
+    expect(runWorkflow).not.toHaveBeenCalled();
+  });
+
+  it("end-to-end: workflow not found returns error result", async () => {
+    const postMessage = vi.fn();
+    const parent = makeParentRun({ postMessage });
+    const deps = makeDeps({ script: undefined });
+    wireOnWorkflowCall(deps);
+
+    await handleWorkerMessage(
+      parent,
+      { type: "workflow-call", callId: 3, name: "missing", args: {} },
+      deps,
+      makeHandlers(),
+    );
+    await flushMicrotasks();
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const sent = firstPosted(postMessage);
+    expect(sent.result.error).toContain("not found");
+    expect(sent.result.content).toBe("");
+  });
+
+  it("end-to-end: child workflow failure propagates error", async () => {
+    const postMessage = vi.fn();
+    const parent = makeParentRun({ postMessage });
+    const childRun = makeDoneChildRun({
+      reason: "failed",
+      error: "agent crashed",
+    });
+    const deps = makeDeps({ script: makeScript(), childRun });
+    setupRunWorkflow(childRun);
+    wireOnWorkflowCall(deps);
+
+    await handleWorkerMessage(
+      parent,
+      { type: "workflow-call", callId: 4, name: "child", args: {} },
+      deps,
+      makeHandlers(),
+    );
+    await flushMicrotasks();
+
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const sent = firstPosted(postMessage);
+    expect(sent.result.error).toBe("agent crashed");
+    expect(sent.result.content).toBe("");
+  });
+
+  it("end-to-end: child shares parent budget reference (no sync-back)", async () => {
+    const postMessage = vi.fn();
+    const parentBudget = new Budget({ maxTokens: 10000 });
+    parentBudget.usedTokens = 100;
+    const parent = makeParentRun({ budget: parentBudget, postMessage });
+    const childRun = makeDoneChildRun({
+      reason: "completed",
+      scriptResult: "ok",
+    });
+    const deps = makeDeps({ script: makeScript(), childRun });
+
+    // 捕获传给 runWorkflow 的 spec——验证 budgetRef 共享父 Budget 引用
+    let capturedSpec: RunSpec | undefined;
+    vi.mocked(runWorkflow).mockImplementation(async (spec, d) => {
+      capturedSpec = spec;
+      d.runs.set(MOCK_RUN_ID, childRun);
+      return MOCK_RUN_ID;
+    });
+    wireOnWorkflowCall(deps);
+
+    await handleWorkerMessage(
+      parent,
+      { type: "workflow-call", callId: 5, name: "child", args: {} },
+      deps,
+      makeHandlers(),
+    );
+    await flushMicrotasks();
+
+    // 子 run 直接复用父 Budget 引用（budgetRef），无需 sync-back
+    expect(capturedSpec?.budgetRef).toBe(parentBudget);
+    expect(parent.state.budget.usedTokens).toBe(100);
+  });
+});

package/src/orchestration/agent-opts-resolver.ts

@@ -0,0 +1,128 @@
+/**
+ * Agent options resolver — resolves agent name / skill / schema to system
+ * prompt files + env vars on every dispatch (BL-1).
+ *
+ * BL-1：解析 workflow 脚本里 `agent({agent,skill,schema})` 的 inline override，
+ * 否则 pi 子进程只收到原始 prompt，没有 --append-system-prompt / --skill /
+ * PI_WORKFLOW_SCHEMA。AgentCallOpts 从 engine/models/types 引入。
+ *
+ * 调用方：engine/error-recovery.ts dispatchAgentCall（每次 agent-call 消息）。
+ * - agent → AgentRegistry.resolve → systemPrompt 写临时文件 → systemPromptFiles（--append-system-prompt）
+ * - skill → resolveSkillPath → skillPath（--skill）
+ * - schema → 结构化输出指令写临时文件 → systemPromptFiles + schemaEnv（PI_WORKFLOW_SCHEMA）
+ *
+ * 临时文件在 activeTempFiles 集合注册，session_shutdown 时由 cleanupAllTempFiles 统一回收。
+ */
+
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { AgentCallOpts } from "./models/types.ts";
+import type { AgentRegistry } from "../execution/agent-registry.ts";  // type-only（本文件不 new，只接收实例参数）
+import { resolveSkillPath } from "./skill-discovery.ts";
+
+const UUID_SLICE_LEN = 8;
+
+export interface ResolveResult {
+  opts: AgentCallOpts;
+  error?: string;
+}
+
+/**
+ * Resolve agent name and schema into systemPromptFiles + skillPath + schemaEnv.
+ *
+ * - Agent systemPrompt -> temp file via --append-system-prompt
+ * - Skill name -> resolved SKILL.md dir path via --skill
+ * - Schema JSON -> temp file with structured-output instruction + PI_WORKFLOW_SCHEMA env
+ *
+ * Returns the enriched opts and any temp files created (registered in activeTempFiles).
+ * Caller is responsible for cleaning up files via cleanupAllTempFiles (session-scoped).
+ */
+export function resolveAgentOpts(
+  opts: AgentCallOpts,
+  agentRegistry: AgentRegistry,
+  sessionDir: string,
+  activeTempFiles: Set<string>,
+): ResolveResult {
+  const systemPromptFiles: string[] = [];
+
+ // Resolve agent system prompt
+  if (opts.agent) {
+    const discovered = agentRegistry.get(opts.agent);  // 新 API: get() 替代 resolve()，返回 AgentConfig（含 systemPrompt+model）
+    if (!discovered) return { opts, error: `Agent not found: ${opts.agent}` };
+
+    const hasSystemPrompt = discovered.systemPrompt.trim().length > 0;
+    if (hasSystemPrompt) {
+      try {
+        const tmpDir = path.join(sessionDir, "workflow-tmp");
+        fs.mkdirSync(tmpDir, { recursive: true });
+        const tmpFile = path.join(tmpDir, `agent-prompt-${randomUUID()}.md`);
+        fs.writeFileSync(tmpFile, discovered.systemPrompt, "utf-8");
+        activeTempFiles.add(tmpFile);
+        systemPromptFiles.push(tmpFile);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { opts, error: `Temp file write error: ${msg}` };
+      }
+    }
+
+    opts = { ...opts, model: opts.model || discovered.model };
+  }
+
+ // Resolve skill name to SKILL.md path
+  if (opts.skill) {
+    const skillPath = resolveSkillPath(opts.skill);
+    if (!skillPath) {
+      return { opts, error: `Skill not found: ${opts.skill}. Searched .agents/skills/ and ~/.pi/agent/skills/` };
+    }
+    opts = { ...opts, skillPath };
+  }
+
+ // Inject schema as structured-output instruction via --append-system-prompt
+ // and set environment variable for conditional tool + hook activation.
+  if (opts.schema) {
+    try {
+      const tmpDir = path.join(sessionDir, "workflow-tmp");
+      fs.mkdirSync(tmpDir, { recursive: true });
+      const tmpFile = path.join(tmpDir, `so-${randomUUID().slice(0, UUID_SLICE_LEN)}.txt`);
+      const schemaJson = JSON.stringify(opts.schema);
+      const content = [
+        "## MANDATORY: Structured Output Requirement",
+        "",
+        "This task requires structured output.",
+        "Your FINAL action must be calling the `structured-output` tool.",
+        "",
+        `structured-output parameters:`,
+        `  schema = ${schemaJson}`,
+        `  data = <your result conforming to the schema above>`,
+        "",
+        "Rules:",
+        "- Do NOT output JSON in your text response — use the structured-output tool.",
+        "- Do NOT skip this step. The structured-output call IS your result.",
+        "- Complete all other work FIRST, then call structured-output as the last action.",
+      ].join("\n");
+      fs.writeFileSync(tmpFile, content, "utf-8");
+      activeTempFiles.add(tmpFile);
+      systemPromptFiles.push(tmpFile);
+
+ // Set env var for structured-output extension to activate tool + hook
+      opts = { ...opts, schemaEnv: schemaJson };
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { opts, error: `Schema temp file write error: ${msg}` };
+    }
+  }
+
+  return {
+    opts: { ...opts, ...(systemPromptFiles.length > 0 ? { systemPromptFiles } : {}) },
+  };
+}
+
+/** Remove all remaining active temp files (called from session_shutdown). */
+export function cleanupAllTempFiles(activeTempFiles: Set<string>): void {
+  for (const fp of activeTempFiles) {
+    try { fs.unlinkSync(fp); } catch { /* already deleted */ void undefined; }
+  }
+  activeTempFiles.clear();
+}

package/src/orchestration/concurrency-gate.ts

@@ -0,0 +1,69 @@
+/**
+ * Workflow Extension — Concurrency Gate
+ *
+ * 并发信号量薄封装。Engine 层 dispatchAgentCall 通过 withSlot 包装
+ * executeAgentCall，gate 仅处理 signal abort 检查。实际并发调度
+ * 由 SubagentService 内部的 ConcurrencyPool 统一管理。
+ *
+ * Wave 3 (D-A7)：withSlot 退化为 abort 薄封装，不独立占池。
+ * 并发槽位由 execution/ConcurrencyPool（SubagentService 持有）统一管理，
+ * 消除 gate + pool 双重计数的 2N 问题（T3.20）。
+ *
+ * 层归属：Infra（D-12）。RunRuntime 直接持有具体类。
+ */
+
+// ── Constants ─────────────────────────────────────────────────
+
+/**
+ * 默认并发上限（D-13）。保留常量向后兼容。
+ * 实际并发由 ConcurrencyPool 管理。
+ */
+export const DEFAULT_CONCURRENCY = 4;
+
+// ── Public options ────────────────────────────────────────────
+
+export interface ConcurrencyGateOptions {
+ /** 最大并发数，缺省 4（D-13）。保留向后兼容。 */
+  maxConcurrency?: number;
+}
+
+// ── ConcurrencyGate ───────────────────────────────────────────
+
+export class ConcurrencyGate {
+  private readonly maxConcurrency: number;
+
+  constructor(opts: ConcurrencyGateOptions | number = {}) {
+    this.maxConcurrency =
+      typeof opts === "number" ? opts : (opts.maxConcurrency ?? DEFAULT_CONCURRENCY);
+  }
+
+ /** 当前在飞的 agent 调用数（不独立计槽，恒为 0）。 */
+  get activeCount(): number {
+    return 0;
+  }
+
+ /** 排队等待派发的调用数（不独立计槽，恒为 0）。 */
+  get queueLength(): number {
+    return 0;
+  }
+
+ /**
+  * 获取一个并发槽位，执行 `fn`。
+  *
+  * Wave 3 简化：不独立管理槽位。仅做 signal pre-abort 检查，
+  * 直接执行 fn。实际并发调度由 SubagentService 的 ConcurrencyPool 负责。
+  *
+  * @param fn 槽位获取后执行的异步函数
+  * @param signal 外部 abort signal（pre-aborted 时立即 reject）
+  * @returns fn 的返回值
+  * @throws AbortError（signal 已 abort 时）
+  */
+  async withSlot<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    if (signal?.aborted) {
+      const err = new Error("Operation aborted before start");
+      err.name = "AbortError";
+      throw err;
+    }
+    return fn();
+  }
+}