@zhushanwen/pi-subagent-workflow 0.1.0

package/skills/workflow-script-format/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: workflow-script-format
+description: >-
+  Reference for writing workflow JS scripts. Auto-loaded when using workflow-generate
+  or writing/editing workflow scripts for Pi. Covers runtime environment, injected
+  globals, constraints, and script patterns. Not for general coding or subagent usage.
+---
+
+# Workflow Script Format Reference
+
+## Runtime Environment
+
+- Script runs inside an **async IIFE in a Worker thread**. Top-level await IS supported.
+- **DO NOT use `import`/`export` (ESM) syntax**. Use `require()` for Node.js built-ins.
+- The script's **`return` value IS captured** and sent back to the main thread.
+
+### [MANDATORY] Do NOT wrap your script in another async IIFE
+
+The worker already wraps your script in an async IIFE. If you add your own `(async function main() { ... })();` wrapper **without `await`**, the worker's outer IIFE resolves immediately (fire-and-forget), posts `return` to the main thread, and the main thread tears down the runtime — **killing any in-flight `agent()` subprocess via SIGKILL within ~2ms**.
+
+```javascript
+// ❌ WRONG: bare IIFE — outer worker IIFE doesn't await this, posts return immediately
+(async function main() {
+  const result = await agent({ prompt: 'analyze' });  // subprocess killed ~2ms after spawn
+})();
+
+// ✅ CORRECT: top-level await directly (the worker wraps this in its own async IIFE)
+const result = await agent({ prompt: 'analyze' });
+
+// ✅ ALSO OK: awaited IIFE (rarely needed — prefer top-level await)
+await (async function main() {
+  const result = await agent({ prompt: 'analyze' });
+})();
+```
+
+This is enforced by `lintScript`:
+- **error** (workflow refuses to run): bare IIFE as a standalone statement + contains agent/parallel/pipeline.
+- **warning** (workflow runs, but flagged): IIFE assigned to a variable or returned from a function + contains agent/parallel/pipeline. Review whether the surrounding code actually awaits the Promise; if not, the same kill-on-spawn bug applies.
+
+## Required: Meta Declaration
+
+Every script MUST declare `meta` at the top level:
+
+```javascript
+const meta = { name: 'workflow-name', description: '...', phases: ['phase1', 'phase2'] };
+```
+
+`name` must match the filename stem. `phases` is for display only.
+
+## Injected Globals (pre-defined, do NOT redeclare)
+
+### `agent(...)` — Call an AI agent
+
+支持三种签名：
+- `agent(promptString)` — 最简，prompt 字符串，返回 content 字符串
+- `agent(promptString, { label?, schema?, ... })` — 字符串 + opts（`label` 是 `description` 的别名）
+- `agent({ prompt, schema?, description?, agent?, skill?, timeoutMs?, model?, scene? })` — 完整 opts 对象
+
+Returns `parsedOutput` (structured data when schema provided) or `content` (string).
+
+**[MANDATORY] Structured output rule:** When you need JSON/structured data from an agent, you MUST pass `schema`. The `schema` parameter triggers a tool-call mechanism where the LLM calls a `structured-output` tool to return validated JSON — this is reliable. NEVER ask the agent to "output JSON in a code block" or use regex to extract JSON from text.
+
+```javascript
+// ✅ CORRECT: use schema parameter — returns parsed JS object directly
+const result = await agent({
+  prompt: 'Analyze this code and rate it',
+  schema: {
+    type: 'object',
+    properties: {
+      score: { type: 'number' },
+      issues: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['score'],
+  },
+  description: 'code-analysis',
+});
+// result is already a parsed object: { score: 8, issues: [...] }
+```
+
+```javascript
+// ❌ WRONG: prompt-based JSON extraction — fragile, LLM often wraps in markdown
+const result = await agent({ prompt: 'Analyze code. Output JSON: { "score": N }' });
+// result is a string, you'd need regex to extract — DON'T do this
+```
+
+### `parallel(calls)` — Run multiple agent calls concurrently
+
+```javascript
+const [r1, r2, r3] = await parallel([
+  agent({ prompt: 'Review file A', description: 'review-a' }),
+  agent({ prompt: 'Review file B', description: 'review-b' }),
+  agent({ prompt: 'Review file C', description: 'review-c' }),
+]);
+```
+
+并发默认上限 6（ConcurrencyPool 限流，`maxConcurrent=6` 来源 ADR-030 决策 3），超出自动排队。元素也可以是返回 Promise 的函数，会被直接调用：
+
+### `pipeline(...)` — Execute stages sequentially
+
+**模式一：顺序模式** — 传入 stage 数组，每个 stage 收到上一个 stage 的结果：
+
+```javascript
+const final = await pipeline([
+  () => agent({ prompt: 'Analyze code', description: 'analyze' }),
+  (prev) => agent({ prompt: `Write tests for: ${prev}`, description: 'test-gen' }),
+]);
+```
+
+**模式二：笛卡尔积模式** — 传入 items 数组 + 多个 stage，对每个 item 依次跑完所有 stage（批处理杀手锏）：
+
+```javascript
+// 对每个 file 依次跑 review → fix
+await pipeline(
+  files,                                      // items
+  (file) => agent({ prompt: `Review ${file}`, description: `review-${file}`, schema: {...} }),
+  (review, file) => agent({ prompt: `Fix ${file}: ${JSON.stringify(review)}`, description: `fix-${file}` }),
+);
+// stage 函数签名：(prevResult, currentItem) => result；第一个 stage 只收 currentItem
+```
+
+### `workflow(name, args?)` — Call another workflow (nested orchestration)
+
+调用已定义的子 workflow（by name），实现 workflow 嵌套编排（顺序 chain / 并行 parallel / scatter-gather / map-reduce）。被调用的 workflow 必须已通过 `workflow-script save` 或放在 `.pi/workflows/` / `~/.pi/agent/workflows/` 可被发现。
+
+**签名**：`workflow(name: string, args?: object) => Promise<AgentResult>`
+
+**参数**：
+- `name` — 目标 workflow 的名称（`meta.name`，即文件名 stem）
+- `args` — 传给子 workflow 的参数对象，子 workflow 内通过 `$ARGS` 读取
+
+**返回值**：`AgentResult`，与 `agent()` 返回结构同构：
+- `content: string` — 子 workflow 的 return 值（字符串化）
+- `parsedOutput?: unknown` — 子 workflow return 的对象（当 return 是对象时）
+- `usage?: {...}` — token 消耗
+- `error?: string` — 失败原因（成功时无此字段）
+
+**嵌套配额**：`workflow()` 调用走同一 ConcurrencyPool，按 depth 分层分配配额（`max(1, 6 - depth)`，保底 1 槽防饿死）。`parallel()` 内的 `workflow()` 调用共享父 workflow 的配额池，超出自动排队（不报错）。嵌套深度受 `MAX_FORK_DEPTH` 护栏保护（见 ADR-030 决策 3）。
+
+**返回值**：`workflow()` 返回 `AgentResult` 对象（与 `agent()` 一致）：
+- 成功：`{ content: string, parsedOutput?: object }`——content 是子 workflow execute() 返回值的 JSON 字符串；parsedOutput 是返回值为对象时的原样回传
+- 失败：`{ content: "", error: string }`——子 workflow 未找到/lint 失败/执行异常/被 abort
+
+**循环检测**：`workflow()` 自动追踪调用链（A→B→C），如果目标 name 已在当前调用链中（如 A→B→A），立即返回 error result（`Circular workflow call detected: A → B → A`），不执行子 workflow。
+
+**预算继承**：子 workflow 的 token 预算继承父 workflow 的剩余预算。子 workflow 消耗的 tokens/cost 执行后累加回父 workflow 的预算池。父 workflow abort 时子 workflow 级联 abort。
+
+**chain 基础示例**（顺序：每步输出作下步输入）：
+```javascript
+const a = await workflow("extract", { source: inputPath });
+const b = await workflow("transform", { raw: a.content });
+const c = await workflow("load", { normalized: b.content });
+```
+
+**parallel 基础示例**（并行：多个独立子 workflow 同时跑）：
+```javascript
+const results = await parallel(
+  tasks.map((t) => workflow(t, { target }))
+);
+```
+
+> 完整模式模板（chain / parallel / scatter-gather / map-reduce，含 `meta` + `$ARGS` + try-catch 错误处理）见 `extensions/subagent-workflow/examples/`。本段教 API，examples 教模式。
+
+### Other globals
+
+- `$ARGS` — Object with workflow arguments (from `--args key=val`)
+- `$WORKSPACE` — Absolute path to the project workspace root
+- `$BUDGET` — Budget info（getter + 方法，**不是**扁平字段）：
+  - `$BUDGET.total` — token 预算上限（未设预算时为 0）
+  - `$BUDGET.spent()` — 已用 token
+  - `$BUDGET.remaining()` — 剩余 token（最小为 0）
+  - 例：`if ($BUDGET.remaining() < 5000) { phase('wrap-up'); }`
+- `phase(name)` — 设置当前阶段名，影响 TUI 分组显示。`meta.phases` 只是声明，TUI 实际分组靠运行时 `phase()` 调用或 agent opts 的 `phase` 字段
+- `log(msg)` — 输出诊断信息（收集到 workerLogs，失败时附在错误消息里，不泄漏到主进程 stderr）
+- `module.exports = { meta, execute }` — 脚本可导出 `execute({ agent, parallel, pipeline, phase, log, $ARGS, $WORKSPACE, $BUDGET })`，运行时会自动调用（兼容 Claude Code 写法）
+
+### `description` naming convention [MANDATORY]
+
+`description` 用作 TUI 显示的 agent 标识，必须简短可读。规则：kebab-case，单词间用 `-` 分隔，不含 round/iteration 后缀。
+
+```javascript
+// ✅ CORRECT: kebab-case，单词间用 - 分隔
+agent({ prompt: '...', description: 'review-business-logic' });
+agent({ prompt: '...', description: 'fix-imports' });
+agent({ prompt: '...', description: 'parse-must-fix' });
+
+// ❌ WRONG: 无分隔符拼接（不可读）
+agent({ prompt: '...', description: 'reviewbusinesslogic' });
+agent({ prompt: '...', description: 'fiximports' });
+
+// ❌ WRONG: 冗长描述（不是 label 用途）
+agent({ prompt: '...', description: 'Review business logic against spec requirements' });
+
+// ❌ WRONG: 不必要的 round/iteration 后缀（TUI 自带序号）
+agent({ prompt: '...', description: 'review-business-logic-round-1' });
+// ✅ CORRECT: 去掉 round 后缀
+agent({ prompt: '...', description: 'review-business-logic' });
+```
+
+## Constraints
+
+- `agent()` calls **must be deterministic in order** for pause/resume to work correctly. 根因：调用结果按单调递增的 callId（从 0 起、按调用顺序）缓存，pause 时杀 Worker 但保留 callCache，resume 时按 callId 重放。`parallel()` 内的调用顺序不能随机，否则重放会错位命中旧结果。注意：无 script hash 校验，**改脚本后 resume 会用旧结果**，开发期改脚本应重新 run。
+- `parallel()` 并发默认上限 6（ConcurrencyPool，超出自动排队；来源 ADR-030 决策 3）。
+- Throwing an error aborts the workflow (after retries).
+- Use `require()` for Node.js built-ins: `const fs = require('node:fs');`
+
+## Complete Example
+
+```javascript
+const meta = { name: 'review-fix-loop', description: 'Loop: review → fix → commit until clean', phases: ['review-fix'] };
+
+const MAX_ROUNDS = 10;
+let round = 0;
+
+while (round < MAX_ROUNDS) {
+  round++;
+  const result = await agent({
+    prompt: `Round ${round}: Review git diff main...HEAD. Fix all issues. Commit with: fix: review round ${round}.`,
+    schema: {
+      type: 'object',
+      properties: {
+        mustFix: { type: 'number', description: 'Number of MUST-fix issues found' },
+        suggestions: { type: 'number', description: 'Number of suggestions' },
+        summary: { type: 'string' },
+      },
+      required: ['mustFix'],
+    },
+    description: `review-${round}`,
+  });
+
+  // result is already a parsed object thanks to schema
+  if (result.mustFix === 0) break;
+}
+
+return { rounds: round, clean: true };
+```
+
+## Script Size Guideline
+
+Keep scripts under **100 lines**. Scripts are orchestration glue, not business logic.
+If a script exceeds 100 lines, split into multiple smaller workflow scripts.
+
+## Verification Patterns
+
+Workflow nodes should be **verifiable** — every critical execution path needs a check that the AI's output is correct. Two patterns are supported:
+
+### Pattern A: Node-Internal Verification
+
+Embed self-check instructions directly in the prompt and require a structured output that includes validation. Best for: trivial classification, single-step lookups, format checks.
+
+```javascript
+// Example: classify severity of a code review finding
+const result = await agent({
+  prompt: `Classify the severity of this finding: "${findingText}".
+The selfCheck field MUST reflect whether severity and reason are both present and consistent.`,
+  schema: {
+    type: 'object',
+    properties: {
+      severity: { type: 'string', enum: ['high', 'medium', 'low'] },
+      reason: { type: 'string' },
+      selfCheck: { type: 'object', properties: { valid: { type: 'boolean' }, reason: { type: 'string' } } },
+    },
+    required: ['severity', 'reason', 'selfCheck'],
+  },
+  description: 'classify-severity',
+});
+
+if (!result.selfCheck.valid) {
+  throw new Error(`self-check failed: ${result.selfCheck.reason}`);
+}
+```
+
+**Pros:** Single call, low overhead. **Cons:** Self-check is part of the same call — AI can lie about validation.
+
+### Pattern B: Follow-up Verify Node
+
+A second `agent()` call that explicitly verifies the previous result. Best for: critical mutations, data transforms, anything where errors propagate downstream.
+
+```javascript
+// Example: review a file, then verify the review is complete
+const review = await agent({
+  prompt: `Review ${file} for issues. Report each finding with severity and reason.`,
+  schema: {
+    type: 'object',
+    properties: {
+      findings: { type: 'array', items: { type: 'object', properties: { severity: { type: 'string' }, reason: { type: 'string' } } } } },
+    },
+    required: ['findings'],
+  },
+  description: `review-${file}`,
+});
+
+const verify = await agent({
+  prompt: `You are verifying a code review. The previous output was:
+${JSON.stringify(review)}
+Did the review cover: (1) all functions in the file, (2) at least 3 potential issues, (3) severity rating for each?`,
+  schema: {
+    type: 'object',
+    properties: {
+      valid: { type: 'boolean' },
+      missingItems: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['valid'],
+  },
+  description: `verify-review-${file}`,
+});
+
+if (!verify.valid) {
+  throw new Error(`verification failed for ${file}: ${verify.missingItems.join(', ')}`);
+}
+```
+
+**Pros:** Independent check, harder to game. **Cons:** Doubles agent calls.
+
+### Decision Tree
+
+```
+Is the step a critical data transform or mutation?
+├─ YES → Use Pattern B (follow-up verify)
+└─ NO
+   ├─ Trivial classification / format check?
+   │  └─ YES → Use Pattern A (node-internal)
+   └─ Read-only / informational?
+      └─ No verification needed
+```
+
+### Anti-pattern
+
+- **Never skip verification entirely on critical execution paths** — even with strong prompts, AI outputs are probabilistic. A verify step catches hallucinations before they propagate.

package/src/execution/__tests__/agent-registry.test.ts

@@ -0,0 +1,164 @@
+// src/__tests__/agent-registry.test.ts
+//
+// AgentRegistry 测试（ADR-031 统一资源发现版）。
+//
+// agent 发现走 shared/resource-discovery，扫描路径由 workspaceRoot + agentDir 推导：
+// - project 级：workspaceRoot/.pi/agents/ + workspaceRoot/.agents/agents/
+// - user 级：agentDir/agents/ + ~/.agents/agents/
+// - npm/dev：agentDir/npm/node_modules/*/ + agentDir/extensions/*/
+//
+// 测试用 tmp 目录作 workspaceRoot，在约定路径下放 agent 文件验证发现 + 优先级。
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { BuiltinAgentRegistry } from "../agent-registry.ts";
+import { AgentRegistry, createPackageBuiltinRegistry, parseAgentFrontmatter } from "../agent-registry.ts";
+
+// ============================================================
+// helpers
+// ============================================================
+
+function tmpWorkspace(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "agent-reg-test-"));
+}
+
+function writeAgent(dir: string, name: string, body: string): string {
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, `${name}.md`);
+  fs.writeFileSync(filePath, body, "utf-8");
+  return filePath;
+}
+
+const emptyBuiltin: BuiltinAgentRegistry = { get: () => undefined, list: () => [] };
+
+/** 构造 AgentRegistry，workspaceRoot=ws，agentDir=ws/.fake-agent（隔离 user 级） */
+function newRegistry(ws: string): AgentRegistry {
+  return new AgentRegistry({
+    workspaceRoot: ws,
+    agentDir: path.join(ws, ".fake-agent"),
+  });
+}
+
+// ============================================================
+// parseAgentFrontmatter
+// ============================================================
+
+describe("parseAgentFrontmatter", () => {
+  it("parses name from filename + body as systemPrompt when no frontmatter", () => {
+    const cfg = parseAgentFrontmatter("/x/worker.md", "You are a worker.");
+    expect(cfg.name).toBe("worker");
+    expect(cfg.systemPrompt).toBe("You are a worker.");
+  });
+  it("extracts model/thinkingLevel/tools from frontmatter", () => {
+    const cfg = parseAgentFrontmatter("/x/coder.md", `---
+model: anthropic/claude-sonnet-4-5
+thinkingLevel: high
+tools: bash, read, edit
+---
+You write code.`);
+    expect(cfg.name).toBe("coder");
+    expect(cfg.model).toBe("anthropic/claude-sonnet-4-5");
+    expect(cfg.thinkingLevel).toBe("high");
+    expect(cfg.tools).toEqual(["bash", "read", "edit"]);
+    expect(cfg.systemPrompt).toBe("You write code.");
+  });
+});
+
+// ============================================================
+// AgentRegistry.discoverAll — 统一资源发现
+// ============================================================
+
+describe("AgentRegistry.discoverAll", () => {
+  let ws: string;
+  beforeEach(() => { ws = tmpWorkspace(); });
+  afterEach(() => { fs.rmSync(ws, { recursive: true, force: true }); });
+
+  it("discovers all .md agents in project .pi/agents/", () => {
+    const piAgents = path.join(ws, ".pi", "agents");
+    writeAgent(piAgents, "worker", "do work");
+    writeAgent(piAgents, "scout", "explore");
+    const reg = newRegistry(ws);
+    reg.discoverAll(emptyBuiltin);
+    expect(reg.list().sort()).toEqual(["scout", "worker"]);
+  });
+
+  it("project .agents/agents overrides project .pi/agents on name clash (priority)", () => {
+    writeAgent(path.join(ws, ".pi", "agents"), "worker", "pi-body");
+    writeAgent(path.join(ws, ".agents", "agents"), "worker", "agents-body");
+    const reg = newRegistry(ws);
+    reg.discoverAll(emptyBuiltin);
+    // .agents 优先级高于 .pi（buildScanTargets 顺序：project-pi 先于 project-agents）
+    expect(reg.get("worker")?.systemPrompt).toBe("agents-body");
+  });
+
+  it("file agents override builtin on name clash", () => {
+    writeAgent(path.join(ws, ".pi", "agents"), "worker", "file-worker");
+    const builtin: BuiltinAgentRegistry = {
+      get: (n) => (n === "worker" ? { name: "worker", systemPrompt: "builtin-worker" } : undefined),
+      list: () => ["worker"],
+    };
+    const reg = newRegistry(ws);
+    reg.discoverAll(builtin);
+    expect(reg.get("worker")?.systemPrompt).toBe("file-worker");
+  });
+
+  it("builtin fills in when no file agent exists", () => {
+    const builtin: BuiltinAgentRegistry = {
+      get: (n) => (n === "oracle" ? { name: "oracle", systemPrompt: "builtin-oracle" } : undefined),
+      list: () => ["oracle"],
+    };
+    const reg = newRegistry(ws);
+    reg.discoverAll(builtin);
+    expect(reg.get("oracle")?.systemPrompt).toBe("builtin-oracle");
+  });
+
+  it("get with require=true throws listing discovered agents", () => {
+    writeAgent(path.join(ws, ".pi", "agents"), "worker", "x");
+    const reg = newRegistry(ws);
+    reg.discoverAll(emptyBuiltin);
+    expect(() => reg.get("nonexistent", true)).toThrow(/Agent "nonexistent" not found.*Discovered: worker/);
+  });
+
+  it("ignores files not ending in .md, starting with _, or .chain.md", () => {
+    const piAgents = path.join(ws, ".pi", "agents");
+    writeAgent(piAgents, "real", "body");
+    writeAgent(piAgents, "_skip", "ignored");
+    writeAgent(piAgents, "trace", "ignored"); // trace.chain.md → 被跳过
+    fs.renameSync(path.join(piAgents, "trace.md"), path.join(piAgents, "trace.chain.md"));
+    fs.writeFileSync(path.join(piAgents, "readme.txt"), "not an agent");
+    const reg = newRegistry(ws);
+    reg.discoverAll(emptyBuiltin);
+    expect(reg.list()).toEqual(["real"]);
+  });
+
+  it("nonexistent directory is silently skipped", () => {
+    // workspaceRoot 下无任何 agents 目录 → 空结果，不抛错
+    const reg = newRegistry(ws);
+    expect(() => reg.discoverAll(emptyBuiltin)).not.toThrow();
+    expect(reg.list()).toEqual([]);
+  });
+});
+
+// ============================================================
+// createPackageBuiltinRegistry — 包内 agents/ 扫描（走 pi.agents manifest）
+// ============================================================
+
+describe("createPackageBuiltinRegistry", () => {
+  it("discovers packaged agents/*.md (worker, reviewer, scout, etc.)", () => {
+    // [HISTORICAL] S6: 包内 agents/ 此前未被接通——discoverAll 从未调用，
+    // 导致 pi install 后包内 agent 定义开箱不可用。
+    const builtin = createPackageBuiltinRegistry();
+    const names = builtin.list();
+    // 包内至少有 worker/reviewer/scout 等核心 agent
+    expect(names).toEqual(expect.arrayContaining(["worker", "reviewer", "scout", "researcher", "planner", "oracle", "context-builder"]));
+    // 每个 agent 都有 systemPrompt
+    for (const name of names) {
+      const cfg = builtin.get(name);
+      expect(cfg).toBeDefined();
+      expect(cfg?.systemPrompt.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/execution/__tests__/agent-result-mapper.test.ts

@@ -0,0 +1,128 @@
+// src/execution/__tests__/agent-result-mapper.test.ts
+//
+// T3.14 (NFR-兼容性): AgentResult 映射字段对齐 —— D-A10 纯函数单测
+// T3.1  (正常): executeAndAwait 返回 content → 间接覆盖（subagent-service.test.ts 集成验证）
+//
+// 测试范围: mapToWorkflowAgentResult 所有字段映射分支（success/error/usage/toolCalls）
+
+import { describe, expect, it } from "vitest";
+
+import { mapToWorkflowAgentResult } from "../agent-result-mapper.ts";
+import type { AgentResult as SubagentsAgentResult, AgentUsageTotal, ToolCall } from "../types.ts";
+
+describe("mapToWorkflowAgentResult (D-A10)", () => {
+  const minimalResult: SubagentsAgentResult = {
+    text: "Hello",
+    turns: 3,
+    durationMs: 1200,
+    success: true,
+    sessionId: "session-123",
+    toolCalls: [],
+  };
+
+  // ── T3.14: 正常成功路径 ──
+
+  it("映射成功结果: text→content, durationMs/sessionId 透传", () => {
+    const result = mapToWorkflowAgentResult(minimalResult);
+    expect(result.content).toBe("Hello");
+    expect(result.durationMs).toBe(1200);
+    expect(result.sessionId).toBe("session-123");
+    expect(result.error).toBeUndefined();
+    expect(result.parsedOutput).toBeUndefined();
+    expect(result.usage).toBeUndefined();
+    expect(result.toolCalls).toEqual([]);
+  });
+
+  it("映射 parsedOutput 透传（structured-output 契约 BC-8）", () => {
+    const parsedData = { score: 0.95, label: "positive" };
+    const r: SubagentsAgentResult = { ...minimalResult, parsedOutput: parsedData };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.parsedOutput).toEqual(parsedData);
+  });
+
+  // ── T3.14: 失败路径 ──
+
+  it("映射失败: success=false 且 error → 填入 error 字段", () => {
+    const r: SubagentsAgentResult = { ...minimalResult, success: false, error: "timeout" };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.error).toBe("timeout");
+    expect(result.content).toBe("Hello"); // content 仍保留（可能有部分输出）
+  });
+
+  it("映射失败: success=false 但无 error → error=undefined", () => {
+    const r: SubagentsAgentResult = { ...minimalResult, success: false };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.error).toBeUndefined();
+  });
+
+  it("映射成功: success=true 且 error 存在 → error=undefined（不误填）", () => {
+    const r: SubagentsAgentResult = { ...minimalResult, success: true, error: "stale" };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.error).toBeUndefined();
+  });
+
+  // ── T3.14: usage 映射 ──
+
+  it("映射 usage: AgentUsageTotal → AgentUsage（字段形状转换）", () => {
+    const usage: AgentUsageTotal = {
+      input: 1000,
+      output: 500,
+      cacheRead: 200,
+      cacheWrite: 100,
+      total: 1800,
+      cost: 0.005,
+    };
+    const r: SubagentsAgentResult = { ...minimalResult, usage };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.usage).toEqual({
+      input: 1000,
+      output: 500,
+      cacheRead: 200,
+      cacheWrite: 100,
+      cost: 0.005,
+      contextTokens: 1800, // total → contextTokens
+      turns: 3, // 来自 AgentResult.turns
+    });
+  });
+
+  it("映射 usage: 无 usage → usage undefined", () => {
+    const result = mapToWorkflowAgentResult(minimalResult);
+    expect(result.usage).toBeUndefined();
+  });
+
+  // ── T3.14: toolCalls 映射 ──
+
+  it("映射 toolCalls: ToolCall → ToolCallEntry（name/input 形状转换）", () => {
+    const calls: ToolCall[] = [
+      { toolName: "read", args: { path: "/a.txt" } },
+      { toolName: "bash", args: { command: "ls" }, result: { content: ["ok"] }, isError: false },
+    ];
+    const r: SubagentsAgentResult = { ...minimalResult, toolCalls: calls };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.toolCalls).toBeDefined();
+    expect(result.toolCalls!).toHaveLength(2);
+    expect(result.toolCalls![0]).toEqual({ name: "read", input: '{"path":"/a.txt"}' });
+    expect(result.toolCalls![1].name).toBe("bash");
+  });
+
+  it("映射 toolCalls: args=undefined → input=''", () => {
+    const calls: ToolCall[] = [{ toolName: "list" }];
+    const r: SubagentsAgentResult = { ...minimalResult, toolCalls: calls };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.toolCalls![0].input).toBe("");
+  });
+
+  it("映射 toolCalls: 长 args 截断（>500 chars）", () => {
+    const longStr = "x".repeat(600);
+    const calls: ToolCall[] = [{ toolName: "write", args: { content: longStr } }];
+    const r: SubagentsAgentResult = { ...minimalResult, toolCalls: calls };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.toolCalls![0].input.length).toBeLessThanOrEqual(503); // 500 + "..."
+  });
+
+  it("映射 toolCalls: 无 toolCalls → undefined", () => {
+    const r: SubagentsAgentResult = { ...minimalResult, toolCalls: undefined };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.toolCalls).toBeUndefined();
+  });
+});