@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/orchestration/models/run-runtime.ts

@@ -7,11 +7,11 @@
  * 职责：封装一次 running-segment 的所有技术资源（worker 线程 +
  * abort controller），统一 release 入口（AC-2：单 release 替代多 boolean flag）。
  * （旧并发门闩 gate 抽象已删——no-op，实际并发由 SubagentService ConcurrencyPool 管理；
- * 原 withSlot 的 pre-abort 检查内联到 error-recovery dispatchAgentCall。）
+ * 原 withSlot 的 pre-abort 检查内联到 worker-message-pump dispatchAgentCall。）
  *
  * 一次性生命周期（G3-001）：runtime 释放后不再复用——AbortController 一次性
  * 语义决定 controller 无法跨释放复用，所以整个 RunRuntime 重建。唯一注入路径：
- * assignRuntime（runWorkflow 创建）与 replaceRuntime（error-recovery 崩溃重试）。
+ * assignRuntime（runWorkflow 创建）与 replaceRuntime（worker-message-pump 崩溃重试）。
  *
  * 参考：domain-models.md §10、clarification.md G3-001。
  */

package/src/orchestration/models/trace.ts

@@ -153,7 +153,7 @@ export class Trace {
   /**
  * 按 stepIndex 移除节点（崩溃重建清理在飞 call 用）。
  *
- * 正常运行不调用（append-only 不变式）。仅 error-recovery 的 discardInFlightCalls
+ * 正常运行不调用（append-only 不变式）。仅 worker-message-pump 的 discardInFlightCalls
  * （rebuildRuntime 内，F2）清理被旧 runtime abort 的在飞 call 时用——移除其 trace
  * 节点，让重跑重发 agent-call 时 append 全新节点走全新执行路径（避免 stale
  * "running" 节点残留 + trace.update 命中旧节点导致新节点 orphan）。

package/src/orchestration/models/types.ts

@@ -13,7 +13,7 @@
  * 层归属：Engine（数据结构 + 不变式守卫）。
  */
 
-import type { ExecutionRecord } from "../../execution/types.ts";
+import type { ExecutionRecord, WorktreeHandle } from "../../execution/types.ts";
 
 // ── 状态机 ────────────────────────────────────────────────────
 
@@ -65,7 +65,37 @@ export function canRunTransition(from: RunStatus, to: RunStatus): boolean {
 // ── Agent 调用 ────────────────────────────────────────────────
 
 /**
- * 单次 agent 调用的输入选项。
+ * slug 最大长度（D6 合流迁入本文件，原权威定义在已删除的 execution/execute-options-mapper.ts）。
+ * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/ "fix-subagent-wf-tools"（21）
+ * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
+ * 放本文件的原因：约束对象是 AgentCallOpts.description（slug 的源字段，见下方 slug 派生说明），
+ * 与字段同文件；worker-message-pump（live record slug 截断）与壳侧 tool schema maxLength 共享引用。
+ */
+export const SLUG_MAX_LENGTH = 35;
+
+/**
+ * 单次 agent 调用的任务声明（D6 任务形状合流后的单一形状）。
+ *
+ * [D6 合流裁决] 本类型 = 原 AgentCallOpts（workflow 调用方声明，18 字段）与原
+ * AgentTaskSpec（engine 中立任务声明，已删除）的合流形态，从模型脚本 agent() API
+ * 到 EnginePort.run 直达 pi 边界一次映射——SAR 链路上的 ExecuteOptions/AgentTaskSpec
+ * 中间态消除（设计 docs/design/subagent-dual-track-convergence.md §3.3 D6 / 终态四）。
+ *
+ * 终态命名按变化轴裁定为 AgentCallOpts，理由：
+ *   - 字段演进的首要驱动轴是「调用方要表达的任务语义」（agent() API 是唯一生产写入方，
+ *     合流字段中 prompt/description/skill/skillPath/schemaEnv/thinkingLevel 等多数派
+ *     已是调用方命名）；
+ *   - 原 AgentTaskSpec 的中立重命名层（task/slug/effort/persona）与调用方命名是
+ *     形式同构、语义同构的假差异（prompt≡task、slug=description 截断、effort≡thinkingLevel、
+ *     persona≡skillPath+appendSystemPrompt 平铺），按「消假差异」原则并入调用方命名；
+ *   - 持久化兼容反向锁定 prompt 形态：jsonl run 快照的 AgentCall.opts 与 worker 消息
+ *     opts 均以 prompt 字段落盘，改名会破坏旧快照重水合。
+ *
+ * 引擎中立字段的并入方式（可选字段，原 AgentTaskSpec 独有字段去向）：
+ *   - graceTurns / conversation / idleTimeoutMs / denyTools / permissionMode：可选并入；
+ *   - persona.agentRef：裁撤（无生产写入方、无消费者——pi 走 agent 字段解析身份）；
+ *   - requires：裁撤（P4 形状预留、无生产写入方；且并入需 import EngineCapabilities
+ *     形成 orchestration↔engine 类型环）。将来能力依赖声明下钻时在本形状上加回。
  *
  * D-12 仅重组执行编排，AgentCallOpts 形状保持兼容。
  */
@@ -101,14 +131,20 @@ export interface AgentCallOpts {
  */
   timeoutMs?: number;
  /**
- * Turn 上限（turn limiter 用）。
- *
- * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
- * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
- * session-runner.resolveSpawnWatchdogMs）。mapToExecuteOptions 原样透传到
- * ExecuteOptions.maxTurns → 引擎 task-spec → runSpawn。
- */
+  * Turn 上限（turn limiter 用）。
+  *
+  * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
+  * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
+  * session-runner.resolveSpawnWatchdogMs）。pi 边界直出为 ExecuteOptions.maxTurns
+  * → runSpawn（D6 合流后无中间映射层）。
+  */
   maxTurns?: number;
+ /**
+  * Turn limiter 的宽限轮数（原 AgentTaskSpec.graceTurns 并入）：超 maxTurns 后
+  * 允许继续的轮数（等待在途工具收尾）。pi 引擎消费；workflow agent() 无写入方，
+  * chat 域（ExecuteOptions.graceTurns 同名透传）经 host-task-spec 填充。
+  */
+  graceTurns?: number;
  /**
  * Skill name to load (e.g. "code-review"). Resolved to SKILL.md path
  * and injected via --skill flag in the subprocess.
@@ -129,18 +165,18 @@ export interface AgentCallOpts {
  */
   agent?: string;
  /**
- * System prompt injection CONTENT (not file paths).
- * Set by agent-opts-resolver: schema structured-output instruction string.
- * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
- * mapToExecuteOptions passes this through to ExecuteOptions.appendSystemPrompt
- * (same name/semantics, transparent passthrough).
- */
+  * System prompt injection CONTENT (not file paths).
+  * Set by agent-opts-resolver: schema structured-output instruction string.
+  * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
+  * pi 边界直出为 ExecuteOptions.appendSystemPrompt（同名同义透传，D6 合流后无中间映射层）。
+  */
   appendSystemPrompt?: string[];
  /**
- * Schema JSON for PI_WORKFLOW_SCHEMA env var.
- * Set by agent-opts-resolver when opts.schema is present; passed as env var
- * to activate the structured-output tool + hook.
- */
+  * Schema JSON for PI_WORKFLOW_SCHEMA env var.
+  * Set by agent-opts-resolver when opts.schema is present (值 = stringifySchemaCached
+  * compact，与 schema 派生等值); passed as env var to activate the structured-output
+  * tool + hook. pi 边界直出时 schema 派生优先、本字段兜底（解耦形态通道，生产不可达）。
+  */
   schemaEnv?: string;
  /**
  * Per-call 工作目录（ADR-029 决策 1）。传给 child_process.spawn 的 cwd option。
@@ -159,11 +195,36 @@ export interface AgentCallOpts {
    * agent() → execute-agent-call → SAR 路由层。
    */
   engine?: string;
-  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
-  worktree?: boolean;
+  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork.
+   * [D6 合流] 类型扩展为 boolean | WorktreeHandle（原 AgentTaskSpec.worktree 的超集）——
+   * WorktreeHandle 形态仅在 chat 域（复用外部已创建的 worktree）出现，workflow agent()
+   * 恒传 boolean。 */
+  worktree?: boolean | WorktreeHandle;
   /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.
-   * Worker-layer flag only — not forwarded to ExecuteOptions (mapToExecuteOptions drops it). */
+   * Worker-layer flag only — not consumed by any engine (dropped at the pi boundary). */
   returnMeta?: boolean;
+ /**
+  * 可持续对话模式（原 AgentTaskSpec.conversation 并入）：true = record 标记 chatMode，
+  * 轮次完成进 idle 态等待 message 续聊。chat 域（ExecuteOptions.conversation 同名）经
+  * host-task-spec 填充；workflow agent() 无写入方。
+  */
+  conversation?: boolean;
+ /**
+  * 空闲超时毫秒数（原 AgentTaskSpec.idleTimeoutMs 并入，仅 conversation 模式有意义）。
+  * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms；显式 0/负 = 禁用
+  * idle GC。chat 域经 host-task-spec 填充。
+  */
+  idleTimeoutMs?: number;
+ /**
+  * 工具 denylist（原 AgentTaskSpec.denyTools 并入，中立新增面）：各引擎做语法映射
+  * （zcode buildZcodeArgv 消费；pi 链路暂无对应面）。无 workflow 写入方，预留形状。
+  */
+  denyTools?: string[];
+ /**
+  * 中立权限模式（原 AgentTaskSpec.permissionMode 并入，预留形状）：映射按各引擎
+  * capabilities.permissionMode。无生产写入方/消费者。
+  */
+  permissionMode?: string;
 }
 
 /**
@@ -189,6 +250,24 @@ export interface ToolCallEntry {
   input: string;
 }
 
+/**
+ * 失败分诊结构化标签（D5-③，r1 MF4 钉正语义）。
+ *
+ * - stale_context：pi session context 被 compact/cancel/替换——重试无意义（同 call
+ *   再次失败），不重试。
+ * - schema_deterministic：确定性 schema 失败（SO tool 从未调用 / gate 终止 /
+ *   不可满足 schema）——同 schema 重试必同结果，不重试。
+ * - unknown：其余一切失败（瞬态 provider 错误、spawn 失败等）——**默认可重试**。
+ *
+ * **语义守恒（最高优先约束）**：unknown（含字段缺省）= 可重试——保持收敛前的
+ * 默认重试语义；仅 stale_context 与 schema_deterministic 两态维持不重试特判。
+ * 词表归属（产出侧单点识别）：stale_context / schema_deterministic 的识别词表
+ * （stale 词表与确定性 schema 失败标记前缀）保留在产出侧
+ * execution/engine/engines/pi/output-collector.ts 包内——词表漂移的失效模式是
+ * failureKind=unknown → 保守重试（安全默认），不再是静默漏诊。
+ */
+export type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
+
 /**
  * 单次 agent 调用的结果（统一形态）。
  *
@@ -199,6 +278,16 @@ export interface AgentResult {
  /** Raw text output from the agent. */
   content: string;
  /**
+ * [D5-③] 失败分诊结构化标签（AgentFailureKind）。产出侧唯一识别点 =
+ * execution/engine/engines/pi/output-collector.ts（collectResult 对最终 error
+ * 分类后写入，经 agent-result-mapper / AgentOutcome 透传到本形态）；消费侧
+ * execute-agent-call 读本字段分诊，不再扫 error 文案子串。
+ *
+ * 仅在 error !== undefined 时有意义（成功时缺省）；缺省视为 unknown = 可重试
+ * （语义守恒，见 AgentFailureKind）。
+ */
+  failureKind?: AgentFailureKind;
+ /**
  * Parsed structured output.
  * Present when `schema` was provided and the output was valid JSON.
  * Source: tool_execution_end.result.details（validated data object）。

package/src/orchestration/models/workflow-run.ts

@@ -39,7 +39,7 @@ import { canRunTransition } from "./types.ts";
 /**
  * 聚合根级 meta（非 RunState 的一部分，不随 trace 持久化到 worker JSONL）。
  *
- * workerErrorCount/scriptErrorCount 跨 runtime 存活（C.5：error-recovery 重试计数载体），
+ * workerErrorCount/scriptErrorCount 跨 runtime 存活（C.5：worker-message-pump 重试计数载体），
  * 因为 retry 会 replaceRuntime，但计数是 run 级而非 runtime 级。
  */
 export interface WorkflowRunMeta {

package/src/orchestration/script-lint.ts

@@ -136,6 +136,36 @@ function stripStringsAndComments(line: string): string {
     .replace(/\/\*[\s\S]*?\*\//g, "");
 }
 
+/** 注释行判定：行注释开头或块注释续行开头（* 与斜杠星号前缀）。 */
+function isCommentLine(trimmed: string): boolean {
+  return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
+}
+
+/** 括号平衡增量：圆/花/方括号开符计 +1，闭符计 -1，其余 0。 */
+function bracketDepthDelta(text: string): number {
+  let delta = 0;
+  for (const ch of text) {
+    if (ch === "(" || ch === "{" || ch === "[") delta++;
+    if (ch === ")" || ch === "}" || ch === "]") delta--;
+  }
+  return delta;
+}
+
+// 检测行内「agent(」字面量对象调用起点；命中返回替换后的调用头圆括号及其后原文
+//（计括号用），未命中 / 非字面量实参返回 undefined。
+//
+// 非字面量实参（agent(callVar) / agent(expr)）返回 undefined：description 等选项在调用点
+// 静态不可见，checkAgentDescription 无法验证运行时构造的调用——继续报 warning 即误报
+// （review-fix-loop 的 agent(call) 三连误报根因）。
+// 形如 agent( 换行 { 的多行字面量调用（argTail 为空）保留原追踪行为。
+function matchAgentCallHead(codeLine: string): string | undefined {
+  if (!/\bagent\s*\(/.test(codeLine)) return undefined;
+  const afterAgent = codeLine.replace(/^.*?\bagent\s*\(/, "(");
+  const argTail = afterAgent.trimStart().slice(1).trimStart();
+  if (argTail.length > 0 && !argTail.startsWith("{")) return undefined;
+  return afterAgent;
+}
+
 /**
  * 遍历 source 中所有 agent 调用的行范围，对每个调用执行 callback。
  *
@@ -150,9 +180,6 @@ function stripStringsAndComments(line: string): string {
  * 内嵌的 agent() 调用——它们同样被 `\bagent\s*\(` 匹配）。
  *
  * 匹配前逐行剔除字符串/注释内容（MF-4）：字符串字面量里的 "agent(s)" 不再误触发。
- * 非字面量实参（agent(callVar) / agent(expr)）跳过不回调：description 等选项在调用点
- * 静态不可见，checkAgentDescription 无法验证运行时构造的调用——继续报 warning 即误报
- * （review-fix-loop 的 agent(call) 三连误报根因）。
  *
  * @param callback (startLine, endLine) 0-based 行号
  */
@@ -170,31 +197,22 @@ function forEachAgentCallRange(
     const trimmed = line.trim();
 
     // 跳过注释
-    if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+    if (isCommentLine(trimmed)) {
       continue;
     }
 
     // 匹配/计括号都用剔除字符串与注释后的行，避免字面量内容干扰
     const codeLine = stripStringsAndComments(line);
 
-    // 检测 agent 调用开始
-    if (!inAgentCall && /\bagent\s*\(/.test(codeLine)) {
+    if (!inAgentCall) {
+      // 检测 agent 调用开始（非字面量实参 → undefined，跳过本行）
+      const afterAgent = matchAgentCallHead(codeLine);
+      if (afterAgent === undefined) continue;
       inAgentCall = true;
       depth = 0;
       agentStartLine = i;
       // 从 agent( 开始计括号
-      const afterAgent = codeLine.replace(/^.*?\bagent\s*\(/, "(");
-      // 非字面量实参（agent(callVar) / agent(expr)）→ 跳过（见函数头注释）。
-      // 形如 `agent(` 换行 `{` 的多行字面量调用（argTail 为空）保留原追踪行为。
-      const argTail = afterAgent.trimStart().slice(1).trimStart();
-      if (argTail.length > 0 && !argTail.startsWith("{")) {
-        inAgentCall = false;
-        continue;
-      }
-      for (const ch of afterAgent) {
-        if (ch === "(" || ch === "{" || ch === "[") depth++;
-        if (ch === ")" || ch === "}" || ch === "]") depth--;
-      }
+      depth += bracketDepthDelta(afterAgent);
       if (depth <= 0) {
         // 单行 agent 调用
         callback(agentStartLine, i);
@@ -203,15 +221,10 @@ function forEachAgentCallRange(
       continue;
     }
 
-    if (inAgentCall) {
-      for (const ch of codeLine) {
-        if (ch === "(" || ch === "{" || ch === "[") depth++;
-        if (ch === ")" || ch === "}" || ch === "]") depth--;
-      }
-      if (depth <= 0) {
-        callback(agentStartLine, i);
-        inAgentCall = false;
-      }
+    depth += bracketDepthDelta(codeLine);
+    if (depth <= 0) {
+      callback(agentStartLine, i);
+      inAgentCall = false;
     }
   }
 }
@@ -613,6 +626,54 @@ function checkMetaFieldQuality(field: string, value: string): LintFinding[] {
   return findings;
 }
 
+/** 对象的 keys 全部收集进集合（非对象安全退化：不加任何 key）。 */
+function collectObjectKeys(src: unknown, out: Set<string>): void {
+  if (src === null || typeof src !== "object") return;
+  for (const k of Object.keys(src as Record<string, unknown>)) out.add(k);
+}
+
+/** patternProperties 的 `^word\\d+$` 形态提取 word 前缀作参数名（其余形态不加）。 */
+function collectPatternPropertyNames(pp: unknown, out: Set<string>): void {
+  if (pp === null || typeof pp !== "object") return;
+  for (const p of Object.keys(pp as Record<string, unknown>)) {
+    const m = p.match(/^\^([a-zA-Z]+)\\d\+\$$/);
+    if (m) out.add(m[1] as string);
+  }
+}
+
+/** W1 参数名集合 = parameters.properties keys + patternProperties 的 word 前缀。 */
+function collectDeclaredParamNames(parameters: unknown): Set<string> {
+  const paramNames = new Set<string>();
+  if (parameters === null || typeof parameters !== "object") return paramNames;
+  const params = parameters as Record<string, unknown>;
+  collectObjectKeys(params.properties, paramNames);
+  collectPatternPropertyNames(params.patternProperties, paramNames);
+  return paramNames;
+}
+
+/** W1：单字段内已声明参数名的 ':'/'=' 形态检查（文案见 finding）。 */
+function findParamNameFindings(
+  field: string,
+  value: string,
+  paramNames: ReadonlySet<string>,
+): LintFinding[] {
+  const findings: LintFinding[] = [];
+  // W1：已声明参数名的 ':'/'=' 形态（参数名转义防 RegExp 注入崩溃——exec-review F2；
+  // ':' 形态加 \\b 前缀防子串误报（subtask: 不命中 task——exec-review F6））
+  for (const name of paramNames) {
+    const nameEsc = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`\\b${nameEsc}:\\s`).test(value) || new RegExp(`\\b${nameEsc}=\\S`).test(value)) {
+      findings.push({
+        severity: "error",
+        line: 1,
+        message: `meta.${field} 包含已声明参数名 '${name}'（'${name}:' / '${name}=' 形态）——参数契约请 read 脚本文件的 @pi-meta parameters 查询，description/when/notFor 只放路由信息`,
+        suggestion: `从 meta.${field} 移除 '${name}: ...' / '${name}=...'，改在 parameters/usage 中声明`,
+      });
+    }
+  }
+  return findings;
+}
+
 /**
  * W1-W3：SSOT lint（m4）——保 §5.1 注入段 description 短单句、不含已声明参数名。
  * 仅对 parseResourceMeta 解析成功的 meta 执行（旧 const meta 格式不检查）。
@@ -624,44 +685,16 @@ function checkMetaFieldQuality(field: string, value: string): LintFinding[] {
  */
 function checkMetaQuality(meta: { description?: string; when?: string; notFor?: string; parameters?: Record<string, unknown> }): LintFinding[] {
   const findings: LintFinding[] = [];
-  const description = meta.description ?? "";
-
-  // W1 参数名集合
-  const paramNames = new Set<string>();
-  if (meta.parameters && typeof meta.parameters === "object") {
-    const props = (meta.parameters as Record<string, unknown>).properties;
-    if (props !== null && typeof props === "object") {
-      for (const k of Object.keys(props as Record<string, unknown>)) paramNames.add(k);
-    }
-    const pp = (meta.parameters as Record<string, unknown>).patternProperties;
-    if (pp !== null && typeof pp === "object") {
-      for (const p of Object.keys(pp as Record<string, unknown>)) {
-        const m = p.match(/^\^([a-zA-Z]+)\\d\+\$$/);
-        if (m) paramNames.add(m[1] as string);
-      }
-    }
-  }
+  const paramNames = collectDeclaredParamNames(meta.parameters);
 
   const fields: Array<[string, string]> = [
-    ["description", description],
+    ["description", meta.description ?? ""],
     ["when", meta.when ?? ""],
     ["notFor", meta.notFor ?? ""],
   ];
   for (const [field, value] of fields) {
     if (value.length === 0) continue;
-    // W1：已声明参数名的 ':'/'=' 形态（参数名转义防 RegExp 注入崩溃——exec-review F2；
-    // ':' 形态加 \\b 前缀防子串误报（subtask: 不命中 task——exec-review F6））
-    for (const name of paramNames) {
-      const nameEsc = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      if (new RegExp(`\\b${nameEsc}:\\s`).test(value) || new RegExp(`\\b${nameEsc}=\\S`).test(value)) {
-        findings.push({
-          severity: "error",
-          line: 1,
-          message: `meta.${field} 包含已声明参数名 '${name}'（'${name}:' / '${name}=' 形态）——参数契约请 read 脚本文件的 @pi-meta parameters 查询，description/when/notFor 只放路由信息`,
-          suggestion: `从 meta.${field} 移除 '${name}: ...' / '${name}=...'，改在 parameters/usage 中声明`,
-        });
-      }
-    }
+    findings.push(...findParamNameFindings(field, value, paramNames));
     findings.push(...checkMetaFieldQuality(field, value));
   }
   return findings;