@zhushanwen/pi-subagent-workflow 0.4.3 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "0.4.3",
+  "version": "2.0.1",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -46,8 +46,8 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-tui": "*",
-    "@sinclair/typebox": "*",
-    "@zhushanwen/pi-structured-output": "0.3.5"
+    "typebox": "*",
+    "@zhushanwen/pi-structured-output": "2.0.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/execution/__tests__/crash-recovery.test.ts

@@ -29,7 +29,7 @@ vi.mock("@earendil-works/pi-ai", () => ({
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
     Optional: (schema: unknown) => ({ ...(schema as object), optional: true }),

package/src/execution/__tests__/format-schema-instruction.test.ts

@@ -46,12 +46,15 @@ describe("formatSchemaInstruction", () => {
     const out = formatSchemaInstruction({ type: "object" });
     // 完整结构快照——任何指令措辞/顺序/缩进漂移都会被捕获。
     // 注意第三行末尾的 em-dash（—），防止有人把它替换成普通连字符。
+    // [HISTORICAL] 方案 A 后文案更新：告知 LLM schema 由系统注入，只需传 data。
     expect(out).toBe(
       [
         "MANDATORY: Structured Output Requirement",
         "You MUST call the `structured-output` tool with your final answer.",
         "Do NOT output the JSON directly in your text response — you MUST use the structured-output tool.",
-        "The schema for the structured output is:",
+        "The schema is enforced by the system — call structured-output with ONLY the `data` parameter.",
+        "Do NOT pass a `schema` parameter; the system validates `data` against the authoritative schema automatically.",
+        "The schema for your `data` is:",
         "```json",
         '{',
         '  "type": "object"',

package/src/execution/__tests__/index-session-start.test.ts

@@ -51,7 +51,7 @@ vi.mock("@earendil-works/pi-ai", () => ({
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
     Optional: (schema: unknown) => ({ ...(schema as object), optional: true }),

package/src/execution/__tests__/sdk-contract.test.ts

@@ -12,19 +12,19 @@
 // 不导入 index.ts（它经 getAgentDir 值导入触发 alias 解析失败——alias 指向
 // .d.ts-only stub）。改测叶子注册函数。session_start 的
 // (event, ctx) 双参数契约由 tsconfig 的精确 stub 类型在编译期强制（见
-// shared/types/mariozechner/index.d.ts 注释：modelRegistry/cwd/ui 不在 event 上）。
+// 注释：modelRegistry/cwd/ui 不在 event 上）。
 
 import { describe, expect, it, vi } from "vitest";
 
 // registerSubagentTool 经 subagent-tool.ts 值导入 StringEnum（pi-ai）+ Type（typebox）。
-// shared/types stub 是 .d.ts（仅类型），pnpm optional-peer-dep 插件拦截值导入 → vi.mock 兜底。
+// stub 是 .d.ts（仅类型），pnpm optional-peer-dep 插件拦截值导入 → vi.mock 兜底。
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
     Optional: (schema: unknown) => ({ ...schema as object, optional: true }),
@@ -263,7 +263,7 @@ describe("subagent tool contract [MANDATORY]", () => {
 // ============================================================
 describe("session_start handler signature (compile-time guarantee)", () => {
   it("ExtensionHandler<SessionStartEvent> is (event, ctx) two-param — enforced by stub type", () => {
-    // 此测试是编译期断言：shared/types/mariozechner/index.d.ts:111 声明
+    // 此测试是编译期断言：stub 类型声明
     //   ExtensionHandler<E, R> = (event: E, ctx: ExtensionContext) => Promise<R|void> | R | void;
     // 且 SessionStartEvent 注释明确 modelRegistry/cwd/ui 不在 event 上（在 ctx）。
     // index.ts:66 `pi.on("session_start", (_event, ctx) => {...})` 通过此类型检查即证明契约。

package/src/execution/__tests__/session-start-reaper.test.ts

@@ -21,7 +21,7 @@ vi.mock("@earendil-works/pi-ai", () => ({
 vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: (values: string[]) => ({ type: "string", enum: values }),
 }));
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
     Optional: (schema: unknown) => ({ ...schema as object, optional: true }),

package/src/execution/dialog-queue.ts

@@ -144,7 +144,7 @@ interface QueueItem {
  *
  * 单 session 假设（M-2，与 index.ts lastSessionId 同源）：本队列是进程级单例（实例挂在
  * globalThis[Symbol.for("@zhushanwen/pi-subagents.dialogQueue")]，见 getOrCreateDialogQueue）。
- * rejectAll()/clear() 清空所有 pending dialog——无 per-session 隔离。Pi 当前架构保证单进程
+ * rejectAll() 清空所有 pending dialog——无 per-session 隔离。Pi 当前架构保证单进程
  * 单 session 串行（同进程不会并发多个 session），故 session_shutdown 调 rejectAll() 只会清掉
  * 当前 session 的 pending。若未来 Pi 支持同进程多 session 并发，session A 退出会误清 session B
  * 的 pending dialog——届时需改为 per-session 隔离（入队项 QueueItem 带 sessionId，rejectAll
@@ -314,9 +314,10 @@ export class DialogGlobalQueue {
     this.processing = false;
   }
 
-  /** 清空队列（dispose 用）。pending 项的 Promise 不 settle（dispose 时调用方已不关心）。
-   *  如需 settle，dispose 前应先 rejectChildDialogs 或 rejectAll。 */
-  clear(): void {
+  /** 清空队列状态（仅在 rejectAll 之后调用）。pending Promise 必须先由 rejectAll settle。
+   *  不 settle Promise 的纯状态重置——单独调用会导致 Promise 永挂（footgun），故设为 private。
+   *  外部调用方应使用 rejectAll()（它 settle 所有 pending + 重置状态，是原子操作）。 */
+  private resetState(): void {
     this.queue = [];
     this.current = undefined;
     this.processing = false;

package/src/execution/host-mode.ts

@@ -16,7 +16,11 @@
 //     集中到单一修改点，未来 Pi 新增 mode 值时只改本文件。
 //   - 业务语义命名（"gui"/"headless"）比原始枚举值更清晰表达意图。
 
-import type { ExtensionMode } from "@earendil-works/pi-coding-agent";
+// ExtensionMode 在 Pi SDK 的 core/extensions/types.d.ts 中定义为
+// `"tui" | "rpc" | "json" | "print"`（ExtensionContext.mode 的类型），但未从包根
+// 导出。这里定义与 SDK 同构的本地别名（ctx.mode 的字面量联合），由同包其他模块复用，
+// 避免依赖未导出的内部类型。
+export type ExtensionMode = "tui" | "rpc" | "json" | "print";
 
 /** 主进程运行模式分类。基于 ExtensionMode 聚合为业务语义。
  *  - "tui"：纯 Pi TUI，ctx.ui.custom 可用，用户在终端交互

package/src/execution/model-resolver.ts

@@ -10,7 +10,7 @@
 
 /**
  * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
- * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐（见 shared/types stub）。
+ * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐。
  */
 export interface ModelRegistryLike {
   /** 返回所有已配置鉴权的可用模型。 */

package/src/execution/session-runner.ts

@@ -9,7 +9,7 @@
 import { type ChildProcess,execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
 
-import type { ExtensionMode } from "@earendil-works/pi-coding-agent";
+import type { ExtensionMode } from "./host-mode.ts";
 
 import { type MirrorFlags, mirrorMainProcessFlags } from "./argv-mirror.ts";
 import { writeAliveMarker } from "./alive-store.ts";
@@ -109,6 +109,17 @@ function computeWatchdogMs(maxTurns: number | undefined | null): number {
 /** stderr 累积上限（字符）。防止失控子进程打满父进程内存。保留尾部便于诊断。 */
 const STDERR_MAX_CHARS = 64 * 1024;
 
+/**
+ * 跨包契约 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/structured-output/src/index.ts）。
+ * 两包是独立 npm 包不能直接 import，故各自保留常量但显式标注此契约关系——
+ * 任一端改名必须同步另一端，否则权威 schema 注入会静默断桥（子进程不注册 tool/hook）。
+ */
+const SCHEMA_ENV_VAR = "PI_WORKFLOW_SCHEMA";
+
 // ============================================================
 // W4: ask_user RPC 系统提示词
 // ============================================================
@@ -266,7 +277,7 @@ export interface RunOptions {
    *  workflow 路径（executeAndAwait）不传此字段——其 onEvent 是开的，
    *  text_delta 经 onEvent 到 workflow liveRecord，不走 streaming 通道。 */
   stream?: SubagentStream;
-  /** D-A6 bridge: workflow schema JSON 字符串，存在时注入 childEnv.PI_WORKFLOW_SCHEMA。
+  /** D-A6 bridge: workflow schema JSON 字符串，存在时注入 childEnv[SCHEMA_ENV_VAR]（PI_WORKFLOW_SCHEMA）。
    *  workflow 编排层通过 ExecuteOptions.schemaEnv 透传此处，
    *  runSpawn 将其注入子进程环境变量，激活 structured-output 扩展注册 tool。
    *  tool 层 execute 不传此字段 → childEnv 不注入 → BC-6 行为不变。 */
@@ -287,7 +298,7 @@ export interface RunOptions {
  * 将 schemaEnv 注入 childEnv（D-A6 bridge）。
  *
  * [模块内直调] —— 纯 env 赋值。从 runSpawn 的 childEnv 构造块调用。
- * 存在时设 childEnv.PI_WORKFLOW_SCHEMA → 子进程 structured-output 扩展读取并注册 tool。
+ * 存在时设 childEnv[SCHEMA_ENV_VAR] → 子进程 structured-output 扩展读取并注册 tool。
  * 不存在时 childEnv 不变（BC-6：tool 层不传 schemaEnv → 行为与合并前一致）。
  */
 export function applySchemaEnvToChildEnv(
@@ -295,7 +306,7 @@ export function applySchemaEnvToChildEnv(
   schemaEnv?: string,
 ): void {
   if (schemaEnv) {
-    childEnv.PI_WORKFLOW_SCHEMA = schemaEnv;
+    childEnv[SCHEMA_ENV_VAR] = schemaEnv;
   }
 }
 
@@ -315,7 +326,9 @@ export function formatSchemaInstruction(schema: Record<string, unknown>): string
     "MANDATORY: Structured Output Requirement",
     "You MUST call the `structured-output` tool with your final answer.",
     "Do NOT output the JSON directly in your text response — you MUST use the structured-output tool.",
-    "The schema for the structured output is:",
+    "The schema is enforced by the system — call structured-output with ONLY the `data` parameter.",
+    "Do NOT pass a `schema` parameter; the system validates `data` against the authoritative schema automatically.",
+    "The schema for your `data` is:",
     "```json",
     JSON.stringify(schema, null, SCHEMA_JSON_INDENT),
     "```",

package/src/execution/subagent-service.ts

@@ -4,7 +4,7 @@
 
 import { AsyncLocalStorage } from "node:async_hooks";
 
-import type { ExtensionMode } from "@earendil-works/pi-coding-agent";
+import type { ExtensionMode } from "./host-mode.ts";
 
 import type { AgentResult as WorkflowAgentResult } from "../orchestration/models/types.ts";
 // D-A10: workflow 侧 AgentResult 映射（executeAndAwait 出口）

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

@@ -3,7 +3,7 @@
 // UI 请求可观测性状态（从 subagent-service.ts 提取，降低主文件行数）。
 // 持有 sessionMode + handler 缺失告警去重集合，供 SubagentService 委托调用。
 
-import type { ExtensionMode } from "@earendil-works/pi-coding-agent";
+import type { ExtensionMode } from "./host-mode.ts";
 
 // ── 跨模块桥接（ui-request-queue 无 ctx.service 引用时走这里） ──
 //

package/src/index.ts

@@ -17,7 +17,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import type { ExtensionAPI, ExtensionContext, ModelSelectEvent, ResourcesDiscoverEvent, ResourcesDiscoverResult, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 import type { AgentRegistry } from "./execution/agent-registry.ts";
@@ -90,7 +90,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // resources_discover：不再注入额外 skill 目录（ADR-031 废弃 discovery.json）。
   // pi 核心 auto-discovery 已覆盖 .agents/skills 等标准目录，子 session 的
   // --skill 由 agent({skill}) 调用方显式传入，无需 extension 额外补充。
-  pi.on("resources_discover", (_event: ResourcesDiscoverEvent, _ctx: ExtensionContext): ResourcesDiscoverResult => {
+  pi.on("resources_discover", (_event, _ctx: ExtensionContext) => {
     return {};
   });
 
@@ -342,7 +342,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   //  model_select：用户切换 model 时刷新缓存
   // ════════════════════════════════════════════════════════════
-  pi.on("model_select", (event: ModelSelectEvent, ctx: ExtensionContext) => {
+  pi.on("model_select", (event, ctx: ExtensionContext) => {
     const service = getModelConfigService();
     if (service && typeof service.setCtxModel === "function") {
       service.setCtxModel(event.model);
@@ -396,10 +396,9 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     }
 
     // M2: 清理 dialog queue 运行时状态（queue/current/processing）。
-    // [#10] 先 rejectAll() settle 所有 pending dialog Promise（防闭包泄漏：未 settle 的
+    // [#10] rejectAll() settle 所有 pending dialog Promise（防闭包泄漏：未 settle 的
     // Promise 持有 resolve/reject 闭包及 handler 上下文，session 退出后仍挂在全球队列上），
-    // 再 clear() 重置 queue/current/processing（防异常退出后 processing=true 卡死下次 session）。
-    // rejectAll() 由 dialog-queue.ts 提供（Group B 新增）；若其内部已 reset 状态，此处 clear() 为幂等兜底。
+    // 并内部重置 queue/current/processing（原子操作，无 footgun）。
     // 单 session 假设（M-2，同 lastSessionId）：rejectAll() 清空进程级单例的所有 pending，
     // 依赖 Pi 单进程单 session 串行保证——不会误清其他 session。多 session 并发的迁移策略
     // 见 DialogGlobalQueue 类注释（rejectAllForSession）。
@@ -407,7 +406,6 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     // 在 /new /resume /fork 时不丢失注册）。
     const dialogQueue = getOrCreateDialogQueue();
     dialogQueue.rejectAll();
-    dialogQueue.clear();
   });
 
   // ════════════════════════════════════════════════════════════

package/src/interface/subagent-tool.ts

@@ -12,7 +12,7 @@
 import type { Component } from "@earendil-works/pi-tui";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { type Static, Type } from "typebox";
 
 import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
 import { getSubagentService } from "../execution/subagent-service.ts";
@@ -27,44 +27,15 @@ import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./t
 // ============================================================
 
 /**
- * execute 回调的 params 类型（手写副本——stub registerTool 是 unknown，
- * 无法从 SubagentParams schema 反向推断参数类型）。
+ * execute 回调的 params 类型由 SubagentParams schema 经 Static 投影得出（见下方 cb 签名）。
  * action 与对应 param 不匹配时 handler 内 throw。
  */
-interface ListParam {
-  includeFinished?: boolean;
-  limit?: number;
-}
-
-interface CancelParam {
-  subagentId: string;
-}
-
-interface SubagentExecuteParams {
-  action: "start" | "list" | "cancel";
-  // action:"start" 的 13 字段拍平到顶层（弱模型常省略 startParam 嵌套层导致调用失败）。
-  // 拍平后这些字段直接在顶层（全部 optional——schema flat 无法表达「action 条件必填」，
-  // 由 startHandler runtime 校验 task/slug 必填）。
-  task?: string;
-  slug?: string;
-  agent?: string;
-  model?: string;
-  thinkingLevel?: string;
-  skillPath?: string;
-  appendSystemPrompt?: string[];
-  schema?: Record<string, unknown>;
-  maxTurns?: number;
-  graceTurns?: number;
-  fork?: boolean;
-  worktree?: boolean;
-  cwd?: string;
-  listParam?: ListParam;
-  cancelParam?: CancelParam;
-}
-
 type SubagentExecuteCb = (
   toolCallId: string,
-  params: SubagentExecuteParams,
+  // Pi SDK 从 parameters schema 反向推断 params 类型。typebox v1 的 StringEnum
+  // 在 Static 投影下退化为 string（非字面量联合），因此 action 在 cb 入参里是 string，
+  // 由下方 isSubagentAction 类型守卫收窄到字面量联合后再 switch。
+  params: Static<typeof SubagentParams>,
   signal: AbortSignal | undefined,
   onUpdate?: (partialResult: AgentToolResult<SubagentToolResult>) => void,
   // ctx 在 SDK 契约里必填；此处保持 optional 以兼容 onUpdate? 在前（TS 参数顺序约束），
@@ -166,6 +137,16 @@ function assertNever(value: never): string {
   return String(value);
 }
 
+/** Subagent action 字面量联合（与 parameters schema 的 StringEnum 取值一致）。 */
+type SubagentAction = "start" | "list" | "cancel";
+
+/** 类型守卫：把 schema 投影出的 string 形式 action 收窄回字面量联合。
+ *  typebox v1 的 StringEnum Static 退化为 string，需运行时校验 + 类型收窄
+ *  才能恢复 switch 的 exhaustiveness 约束。 */
+function isSubagentAction(value: string): value is SubagentAction {
+  return value === "start" || value === "list" || value === "cancel";
+}
+
 /** unknown 是否为含 model/thinkingLevel 的对象（类型守卫，替代全可选结构 `as`）。 */
 function isModelOverrideObj(a: unknown): a is { model?: unknown; thinkingLevel?: unknown } {
   return typeof a === "object" && a !== null;
@@ -324,6 +305,11 @@ const executeSubagent: SubagentExecuteCb = async (
   const service = getSubagentService();
   if (!service) throw new Error("subagents runtime not initialized");
 
+  // typebox v1 的 StringEnum 在 Static 投影下退化为 string，此处类型守卫收窄回
+  // 字面量联合，恢复 switch 的 exhaustiveness 约束（default 分支 = never）。
+  if (!isSubagentAction(params.action)) {
+    throw new Error(`Unknown subagent action: ${params.action}`);
+  }
   switch (params.action) {
     case "start":
       // 拍平后直接传顶层 params（StartHandlerInput 是 SubagentExecuteParams 子集，

package/src/interface/views/WorkflowsView.ts

@@ -109,7 +109,7 @@ function walled(theme: ThemeLike, content: string, contentWidth: number): string
 }
 
 // ── Minimal TUI duck-types（避免直接 import TUI/KeybindingsManager 类型 ──
-// 共享类型 fallback shared/types/mariozechner/index.d.ts 不导出 TUI 类，
+// 共享类型 fallback 不导出 TUI 类，
 // workspace 跨包 typecheck 会报 "no exported member 'TUI'"。
 // 此处用结构化接口替代——只声明 view 实际用到的成员（requestRender + terminal）。
 

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

@@ -102,11 +102,14 @@ export function resolveAgentOpts(
         "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>`,
+        "The schema is enforced by the system (PI_WORKFLOW_SCHEMA). You only pass `data` — do NOT pass a `schema` parameter.",
+        `Your \`data\` must conform to this schema:`,
+        "```json",
+        schemaJson,
+        "```",
         "",
         "Rules:",
+        "- Call structured-output with ONLY the `data` parameter. The system validates it against the schema above automatically.",
         "- 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.",