@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,317 @@
+/**
+ * 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 () => {}),
+  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?: { getPath: 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 ?? {
+    getPath: 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/__tests__/workflow-script-lint-memo.test.ts

@@ -0,0 +1,110 @@
+/**
+ * WorkflowScript.validate lint memo（IF9/#15，TC9/DM2）— 引用相等键缓存测试。
+ *
+ * vi.mock script-lint 模块统计 lintScript 调用次数（design IF9 测试面）：
+ * - 同 path + sourceCode 相等（含等值异字面量）→ 二次 validate 只 1 次 lint 调用
+ * - 【设计修正】design 原文「异引用等值 miss」在 JS 不可构造：字符串 === 是值相等
+ *   （实测等值异字面量命中）。lintScript 是纯函数，值相等 ⟹ 结果相同，值键 memo
+ *   语义严格正确且是引用键意图的超集（registry 等值重建实例同样命中）。
+ * - 同 path 新内容（值不等）→ 重 lint 并更新条目
+ * - clearLintMemo → 重 lint（config-loader.invalidateCache 挂载点）
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const lintCalls = vi.hoisted(() => ({ count: 0 }));
+
+vi.mock("../script-lint.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../script-lint.ts")>();
+  const realLintScript = actual.lintScript;
+  const countingLintScript = ((source: string) => {
+    lintCalls.count++;
+    return realLintScript(source);
+  }) as typeof actual.lintScript;
+  return { ...actual, lintScript: countingLintScript };
+});
+
+import { WorkflowScript, clearLintMemo, type WorkflowMeta } from "../models/workflow-script.ts";
+
+const meta: WorkflowMeta = {
+  kind: "workflow",
+  name: "w",
+  description: "",
+  phases: [],
+};
+
+function makeScript(path: string, sourceCode: string): WorkflowScript {
+  return new WorkflowScript({
+    name: "w",
+    source: "saved",
+    path,
+    sourceCode,
+    meta,
+    available: true,
+  });
+}
+
+const VALID = '/* @pi-meta name: w */\nagent({ prompt: "x" });\n';
+
+beforeEach(() => {
+  clearLintMemo();
+  lintCalls.count = 0;
+});
+
+describe("WorkflowScript.validate — lintMemo（IF9）", () => {
+  it("同 sourceCode 引用：二次 validate 只 1 次 lint 调用", () => {
+    const src = VALID;
+    const a = makeScript("/ws/.pi/workflows/w.js", src);
+    const b = makeScript("/ws/.pi/workflows/w.js", src); // registry 重建实例场景
+
+    const ra = a.validate();
+    const rb = b.validate();
+
+    expect(lintCalls.count).toBe(1);
+    expect(rb).toEqual(ra); // 缓存返回同一 lint 结果
+  });
+
+  it("等值异字面量同样命中（JS === 值相等；lintScript 纯函数 ⟹ 值键 memo 正确）", () => {
+    const a = makeScript("/ws/.pi/workflows/w.js", VALID);
+    const b = makeScript("/ws/.pi/workflows/w.js", `/* @pi-meta name: w */\nagent({ prompt: "x" });\n`);
+
+    a.validate();
+    b.validate();
+
+    // 设计原文预期「异引用 miss → 2 次」，但字符串 === 是值相等，等值必命中；
+    // lintScript(source) 纯函数，同值同结果，缓存正确性不受影响（实测锚定）。
+    expect(lintCalls.count).toBe(1);
+  });
+
+  it("同 path 新内容（值不等）：重 lint 并更新条目", () => {
+    const path = "/ws/.pi/workflows/w.js";
+    const old = makeScript(path, VALID);
+    old.validate();
+    expect(lintCalls.count).toBe(1);
+
+    const edited = makeScript(path, '/* @pi-meta name: w */\nagent({ prompt: "y", outputSchema: {} });\n');
+    edited.validate();
+    expect(lintCalls.count).toBe(2); // 新引用 → miss → 重 lint
+
+    // 新条目已覆写：再以 edited 同引用 validate 命中缓存
+    const replay = makeScript(path, edited.sourceCode);
+    replay.validate();
+    expect(lintCalls.count).toBe(2);
+  });
+
+  it("clearLintMemo 后重 lint（invalidateCache 挂载点）", () => {
+    const a = makeScript("/ws/.pi/workflows/w.js", VALID);
+    a.validate();
+    expect(lintCalls.count).toBe(1);
+
+    clearLintMemo();
+    a.validate();
+    expect(lintCalls.count).toBe(2);
+  });
+
+  it("不同 path 互不共享条目", () => {
+    const src = VALID;
+    makeScript("/ws/.pi/workflows/a.js", src).validate();
+    makeScript("/ws/.pi/workflows/b.js", src).validate();
+    expect(lintCalls.count).toBe(2);
+  });
+});

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

@@ -0,0 +1,174 @@
+/**
+ * Agent options resolver — resolves skill / schema to append-system-prompt
+ * content + env vars on every dispatch (BL-1).
+ *
+ * BL-1：解析 workflow 脚本里 `agent({skill,schema})` 的 inline override，
+ * 否则 pi 子进程只收到原始 prompt，没有 --append-system-prompt /
+ * --skill / PI_WORKFLOW_SCHEMA。
+ *
+ * 职责范围（M2 修正）：仅处理 schema SO 指令（内容直传 appendSystemPrompt）+ skill。
+ * agent ref 处理（systemPrompt/model/thinkingLevel）已移交 resolveIdentity（execution 层，
+ * 经 getAgentConfig + resolveModel 完整覆盖），消除双重注入与 model 层级混乱。
+ *
+ * 调用方：engine/error-recovery.ts dispatchAgentCall（每次 agent-call 消息）。
+ * - skill → resolveSkillPath → skillPath（--skill）
+ * - schema → 结构化输出指令内容直传 appendSystemPrompt（--append-system-prompt）+ schemaEnv（PI_WORKFLOW_SCHEMA）
+ *
+ * M2 bug 修正：旧实现把 schema 指令写成临时文件、push 文件路径（而非内容）给下游，
+ * 下游 mapper/session-runner 把路径当文本拼进最终 append 文件，导致 schema 指令从未
+ * 进入子进程。改为指令内容直传（不写盘、无临时文件）。
+ */
+
+import type { AgentCallOpts } from "./models/types.ts";
+import { resolveSkillPath } from "./skill-discovery.ts";
+import { stringifySchemaCached } from "../shared/schema-jsonify.ts";
+
+export interface ResolveResult {
+  opts: AgentCallOpts;
+  error?: string;
+}
+
+// ── 根类型判定（与 structured-output 同源，本地副本） ──────────────
+
+/** plain object 判定（isPlainObject，与 @zhushanwen/pi-structured-output schema-guards.ts 同语义）。 */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * [U3 本地副本·同源锚定] 判定权威 schema 的根数据形态是否为 object。
+ *
+ * 与 @zhushanwen/pi-structured-output `src/execute.ts` 的 `isObjectRootSchema`
+ * 逐语义一致（该函数是 structured-output 工具 parameters {value} 包装/解包的唯一
+ * 判定源）。两包是独立 npm 包不能直接 import——optional peer 依赖在独立安装场景
+ * （pi 用户单独装本包）不保证存在，顶层值 import 会让整个 extension 加载崩溃；
+ * 且 builtin esbuild bundle 会把 import 的包内联成双实例（先例：session-runner.ts
+ * 的 PI_WORKFLOW_SCHEMA env 契约注释）。故本地复制，任一端改动判定逻辑必须同步
+ * 另一端（两端 docstring 互相锚定）。
+ *
+ * draft-07 语义：无 type 时类型关键字按值形态适用——properties/required 等
+ * object 特有关键字的存在意味着作者在描述 object 输出，算 object 根；组合根
+ * （anyOf/oneOf/allOf/$ref/enum）可能接受非 object 值，保真起见一律按非 object
+ * （{value} 包装可容纳任意成员类型）。
+ */
+function isObjectRootSchema(schema: unknown): schema is Record<string, unknown> {
+  if (!isPlainObject(schema)) return false;
+  if (schema.type === "object") return true;
+  if (Array.isArray(schema.type) && schema.type.includes("object")) return true;
+  const OBJECT_ONLY_KEYS = [
+    "properties",
+    "required",
+    "patternProperties",
+    "additionalProperties",
+    "minProperties",
+    "maxProperties",
+    "dependencies",
+    "dependentRequired",
+    "propertyNames",
+  ];
+  return OBJECT_ONLY_KEYS.some((k) => k in schema);
+}
+
+/**
+ * 构造 schema structured-output 指令——resolver 单点注入的唯一文案源。
+ *
+ * [审查项#2] 消费链：resolveAgentOpts → appendSystemPrompt（ASP 稳定前缀区）。
+ * 此前 session-runner 有一份措辞相近的同名函数并把指令拼进 task 末尾，形成
+ * ASP + task 双重静态注入；task 后缀已删（task 每 agent 变化不可缓存，工具
+ * parameters 是 pi 必然注入的权威展示——注册工具 schema 随每次请求下发进
+ * provider 请求体，机制登记 PS-21：pi-ai dist/api/anthropic-messages.js
+ * convertTools :1000/:1008 → :1017 input_schema、openai-completions.js :1099
+ * parameters——schema 全文不必在 task 重复，文本重复浪费 ~730 tokens/子进程）。
+ *
+ * [审查项#4] AP 告知：注入侧校验用 additionalProperties:false 收窄后的
+ * parameters，模型自带 schema 外字段会被拒——不前置告知，拒绝显得凭空。
+ *
+ * JSON 序列化用 compact（stringifySchemaCached），与 schemaEnv 复用同串（IF7 #13）。
+ */
+export function formatSchemaInstruction(schema: Record<string, unknown>): string {
+  const schemaJson = stringifySchemaCached(schema, "compact");
+  // [U3] 根类型条件化：判定与 structured-output 的工具 parameters {value} 包装/解包
+  // 同源（上方 isObjectRootSchema 本地副本）。object 根 arguments 即 data；非 object
+  // 根参数层实为 {value} 包装——ASP 文案必须与工具 description 同语汇告知包装契约
+  // （{value: <data>} + value. 错误路径前缀），否则模型直传裸值必首调失败。
+  const isObjectRoot = isObjectRootSchema(schema);
+  const argsContractLine = isObjectRoot
+    ? "Your call arguments ARE the result data itself — the tool's parameter schema IS the required shape of your result."
+    : "The tool's single argument must be an object `{value: <data>}` — put the result itself in `value`, and it must conform to the schema below. " +
+      "Validation errors may reference paths starting with `value.` (e.g. `value.0`, `value.name`): " +
+      "that prefix addresses the wrapper, not your data.";
+  const rulesCallLine = isObjectRoot
+    ? "- Call the structured-output tool with your result data as its arguments. The system validates them against the schema above automatically."
+    : "- Call the structured-output tool with `{value: <your result data>}`. The system validates the `value` field against the schema above automatically.";
+  // [AP 告知条件化] 根级 additionalProperties 未声明时 D4 注入 false（见
+  // structured-output tool-definition）——额外字段恒拒绝，强承诺成立；作者显式声明
+  // true / 子 schema 时 injection 侧尊重不动，额外字段按作者声明放行，无条件
+  // 「一律拒绝」文案与参数层行为不符（保守方向误导：模型不敢传合法字段）。
+  const apLine = schema.additionalProperties === undefined
+    ? "- Fields not defined in this schema are rejected — do not add extra fields."
+    : "- Extra fields follow this schema's own additionalProperties declaration.";
+  return [
+    "## MANDATORY: Structured Output Requirement",
+    "",
+    "This task requires structured output.",
+    "Your FINAL action must be calling the `structured-output` tool.",
+    "",
+    argsContractLine,
+    `Your result must conform to this schema:`,
+    "```json",
+    schemaJson,
+    "```",
+    "",
+    "Rules:",
+    rulesCallLine,
+    "- 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.",
+    apLine,
+  ].join("\n");
+}
+
+/**
+ * Resolve skill and schema into appendSystemPrompt (content array) + skillPath + schemaEnv.
+ *
+ * - Skill name -> resolved SKILL.md dir path via --skill
+ * - Schema JSON -> structured-output instruction string pushed into appendSystemPrompt
+ *   (content, not file path) + PI_WORKFLOW_SCHEMA env
+ *
+ * Agent ref is intentionally NOT handled here — resolveIdentity (execution layer)
+ * covers it via getAgentConfig + resolveModel. Handling agent here would cause
+ * double-injection (agentConfig.systemPrompt at session-runner + appendSystemPrompt)
+ * and model-tier confusion.
+ *
+ * Returns the enriched opts.
+ */
+export function resolveAgentOpts(opts: AgentCallOpts): ResolveResult {
+  const appendSystemPrompt: string[] = [];
+
+ // 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 into appendSystemPrompt (content,
+ // not temp file) and set environment variable for conditional tool + hook activation.
+ // M2 fix: previously wrote the instruction to a temp file and pushed the FILE PATH,
+ // which got concatenated into the final append file as path garbage — the SO instruction
+ // never reached the subprocess. Now the instruction content is pushed directly.
+  if (opts.schema) {
+    // IF7(#13)：formatSchemaInstruction 与 schemaEnv 对同一 schema 对象引用共享
+    // WeakMap 缓存条目（compact stringify 整个 dispatch 只发生一次）
+    appendSystemPrompt.push(formatSchemaInstruction(opts.schema));
+
+ // Set env var for structured-output extension to activate tool + hook
+    opts = { ...opts, schemaEnv: stringifySchemaCached(opts.schema, "compact") };
+  }
+
+  return {
+    opts: { ...opts, ...(appendSystemPrompt.length > 0 ? { appendSystemPrompt } : {}) },
+  };
+}