@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/subprocess-agent-runner.ts

@@ -30,7 +30,10 @@ import type { AgentEvent } from "../shared/agent-event.ts";
 import { assertTaskShapeSupported } from "./engine/common/capability-gate.ts";
 import { HOST_TIMEOUT_ABORT_REASON } from "./engine/common/kill-chain.ts";
 import { JOURNAL_INITIAL_POOL_KEY, wireEventJournal } from "./engine/common/journal-wiring.ts";
-import { createPiEngine } from "./engine/engines/pi/registration.ts";
+// [W6 R1 MF-5] pi EnginePort 解析改经 host 公共面（engine/host/pi-host-binding.ts）：
+// registry cli 形态经 descriptor 路由（W3 双模 getEngine），inproc/未注册回落 per-session
+// DI 直构（行为与改线前 createPiEngine 逐点一致）。
+import { resolveHostPiEnginePort } from "./engine/host/pi-host-binding.ts";
 import type { EnginePort, RunContext } from "./engine/port.ts";
 import { validateModelForEngine } from "./engine/model-validation.ts";
 import { routeEngineForHost, type EngineRouteResult, type EngineRoutingInput } from "./engine/routing.ts";
@@ -39,7 +42,9 @@ import type { AgentOutcome } from "./engine/types.ts";
 import { getModelConfigService } from "./model-config-service.ts";
 import type { ModelInfo } from "./model-resolver.ts";
 import { modelRefFromVerified } from "../shared/model-ref";
-import { registerSpawnedChildForRecord } from "./engine/engines/pi/session-runner.ts";
+// [W6 R1 MF-5] 子进程注册改经 spawnedChildren 状态镜像公共面（engine/host/
+// spawned-children.ts——镜像 + inproc 过渡委托，不再深路径 import inproc pi 引擎目录）。
+import { registerSpawnedChildForRecord } from "./engine/host/spawned-children.ts";
 import type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
 import { toErrorMessage } from "../core/error-message.ts";
@@ -95,7 +100,8 @@ export class SubprocessAgentRunner implements AgentRunner {
     this.subagentService = deps.subagentService;
     this.ctxModel = deps.ctxModel;
     // [D4 聚合连带] 经 asEngineService 显式视图适配（原结构化直绑依赖查询面 public）。
-    this.piEngine = createPiEngine(() => this.subagentService.asEngineService);
+    // [W6] 解析经 host 公共面（descriptor 路由 / inproc DI，见 pi-host-binding 注释）。
+    this.piEngine = resolveHostPiEnginePort(() => this.subagentService.asEngineService);
   }
 
   /**
@@ -138,10 +144,12 @@ export class SubprocessAgentRunner implements AgentRunner {
 
     // ── P4 路由（D3-② 单点：routeEngineForHost）+ D3-④ 预检 ──
     // 路由在最前——引擎身份决定 journal 路径与后续一切执行面。pi 快路径同步短路
-    //（routed 非 Promise，零微任务——缺省路径时序与 P1 接线前完全一致，下游依赖
-    // 「run 内首个 await 前已触达 executeAndAwait」的时序契约）。路由失败（未注册
-    // id / probe 失败 + strict/守卫）与预检命中（capabilities 驱动，含 worktree——
-    // workflow 域漏拦缺口修复）一并按「不 reject」契约转 result.error。
+    //（routed 非 Promise，零微任务）——首个 await 前完成**路由决策**（engine id 已定，
+    // A2 观测点）；其后的执行经进程边界（cli 形态 spawn + 握手 + 帧往返必经 await），
+    // 旧「run 内首个 await 前已触达 executeAndAwait」时序契约由引擎协议化设计
+    // §3.5.3 作废放宽。路由失败（未注册 id / probe 失败 + strict/守卫）与预检命中
+    //（capabilities 驱动，含 worktree——workflow 域漏拦缺口修复）一并按「不 reject」
+    // 契约转 result.error。
     let route: EngineRouteResult;
     try {
       const routed = routeEngineForHost({
@@ -227,7 +235,7 @@ export class SubprocessAgentRunner implements AgentRunner {
       const { handle, outcome } = await route.engine.run(
         // [D6 合流] opts 直传——AgentCallOpts 即 EnginePort 任务形状（缺省路径零映射；
         // pi 边界一次直出由 PiEngine.agentCallToExecuteOptions 承担，逐字段等值由
-        // engines/pi/__tests__/spawn-opts-direct.test.ts 对照表锁定）
+        // inproc pi 引擎目录/__tests__/spawn-opts-direct.test.ts 对照表锁定）
         opts,
         runCtx,
       );

package/src/execution/sync-rebuild.ts

@@ -0,0 +1,87 @@
+// src/execution/sync-rebuild.ts
+//
+// [E1 恢复批语义修复] sync 批崩溃恢复（E1）与批闭合 flush（S11 兜底）的两条
+// BgNotifyRecord/SubagentRecord 映射，从 subagent-service 拆出（D4 按变化轴拆分：
+// 改恢复批的通知语义 / 落标数据源形态，只改本文件）。两函数均纯映射——零 service/
+// store 依赖，rootSessionId 由调用方注入。
+
+import { deriveOutcome } from "./execution-record.ts";
+import type { BgNotifyRecord } from "./notifier.ts";
+import type { SubagentRecord } from "./types.ts";
+
+/**
+ * E1 末条 entry 终态快照 → BgNotifyRecord（补发成员；sync 仅 one-shot，round/
+ * sessionFile 不透传——与 route() 缓冲快照的 one-shot 形态对齐）。
+ *
+ * [E1 恢复批语义修复] status/outcome/patchFile 三点对齐 notify-host toNotifyRecord
+ * 的映射（正常 flush 路径对同一成员的补发形态），不再直通 rec.status：
+ * - status：one-shot 成功成员崩溃时末条 entry 恒为 running+resumable（SP-5 轮终
+ *   形态，resumable 豁免正据此放行其入批）——直通会让补发记录仍是 running 形态：
+ *   buildBatchLlmContent 批头只统计 closed 成员（全员成功的恢复批显示
+ *   「0 finished, 0 failed, 0 cancelled」），条目文案落「finished a round」
+ *   （对话轮次语义）。同 toNotifyRecord：closed 或非 chatMode → "closed"（仅
+ *   chatMode 轮次形态保持 running——sync 成员恒 one-shot，此分支为防御完整性）。
+ * - outcome：closed 状态物化（单一权威 deriveOutcome）——resumable 成员末条未
+ *   终态化，closedReason 缺省与正常 flush 路径同形，无 error 即 completed、有
+ *   error 即 failed；notifier.notifyBatch 投影边界的 `??` 兜底对此幂等。
+ * - patchFile：透传（依赖 rebuildEntryRecord 的同名投影）——worktree one-shot
+ *   成员的 git-apply 回收指针只在 closed+completed 分支文案携带（running 分支
+ *   不含），正常 flush 路径经 toNotifyRecord 特意携带，恢复批不得缺失。
+ */
+export function syncRebuildToNotifyMember(rec: SubagentRecord): BgNotifyRecord {
+  const status: BgNotifyRecord["status"] =
+    rec.status === "closed" || !rec.chatMode ? "closed" : "running";
+  return {
+    id: rec.id,
+    status,
+    closedReason: rec.closedReason,
+    outcome: status === "closed" ? deriveOutcome(rec.closedReason, rec.error) : undefined,
+    agent: rec.agent,
+    model: rec.model,
+    result: rec.result,
+    error: rec.error,
+    startedAt: rec.startedAt,
+    endedAt: rec.endedAt,
+    patchFile: rec.patchFile,
+  };
+}
+
+/**
+ * [S11] getFullRecord miss 成员的缓冲快照兜底 → 最小 SubagentRecord（batchFinalized
+ * 落标数据源）。getFullRecord 不可达（子 session 文件缺失/已 GC）时，缓冲的
+ * BgNotifyRecord 是该成员唯一残存数据。最小形态只保标记链路必需字段：
+ * id/agent/task/startedAt 是 rebuildEntryRecord 的解析门槛（缺 task 的 entry 会被
+ * E1 扫描判损坏跳过——标记失效方向，task 占位空串保 entry 可解析）；终态字段
+ * （closedReason/result/error/endedAt/model/patchFile）自缓冲快照如实投影；
+ * rootSessionId 取当前 session 根（E1 候选过滤的归属口径）。
+ */
+export function bufferedMemberFallbackRecord(
+  m: BgNotifyRecord,
+  rootSessionId: string | undefined,
+): SubagentRecord {
+  return {
+    id: m.id,
+    agent: m.agent,
+    task: "",
+    slug: "",
+    status: "closed",
+    closedReason: m.closedReason,
+    mode: "background",
+    startedAt: m.startedAt,
+    rootSessionId,
+    parentRecordId: undefined,
+    depth: 0,
+    endedAt: m.endedAt,
+    turns: 0,
+    totalTokens: 0,
+    model: m.model ?? "",
+    thinkingLevel: undefined,
+    eventLog: [],
+    displayItems: [],
+    result: m.result,
+    error: m.error,
+    sessionFile: undefined,
+    chatMode: false,
+    patchFile: m.patchFile,
+  };
+}

package/src/execution/types.ts

@@ -8,6 +8,14 @@
 //   - TUI 只读 Record/Details 快照，永不持有可变引用
 
 import type { GuiRenderResult } from "@xyz-agent/extension-protocol";
+import type {
+  AgentUsage,
+  AgentUsageTotal,
+  ToolCall,
+  ToolCallResult,
+  Turn,
+  WorktreeHandle,
+} from "@zhushanwen/subagent-engine-sdk";
 
 import type { AgentFailureKind } from "../orchestration/models/types.ts";
 import type { ModelInfo, ModelRegistryLike } from "./model-resolver.ts";
@@ -146,47 +154,35 @@ export type ExecutionMode = "background";
 // Agent 事件流（Core → Record 的唯一更新驱动）
 // ============================================================
 
-/**
- * Pi session.subscribe 上报的事件。Runtime 把它喂给 updateFromEvent。
- *
- * 设计：AgentEvent 携带 updateFromEvent 收口进 record 所需的**全部数据**——
- * tool_end 带 result（供 turn.toolCalls 存完整 ToolCall），无需翻译层旁路累积。
- *
- * ACP 词汇对照（D11 注记级校准，零行为变更；新引擎实现者按本表对齐语义，
- * 详见 docs/architecture/subagent-engine-gui-visibility.md §3.3 D11）：
- *   text_delta / thinking_delta ↔ ACP content blocks（text / thinking）
- *   tool_start / tool_end      ↔ ACP tool_call / tool_call_update
- *   turn_end / message_end     ↔ ACP prompt turn 终态（stop_reason + usage）
- *   compaction                 ↔ ACP session/compaction
- * 本协议以 pi 为语义锚点（D3）——命名不迁移，对照表仅保证未来 AcpEngine 适配器
- * 与跨引擎 trace 映射的翻译成本最低。
- */
-export type AgentEvent =
-  | { type: "tool_start"; toolName: string; args?: unknown }
-  | { type: "tool_end"; toolName: string; args?: unknown; result?: ToolCallResult; isError?: boolean }
-  | { type: "text_delta"; delta: string }
-  | { type: "thinking_delta"; delta: string }
-  | { type: "turn_end"; summary?: string }
-  | { type: "message_end"; usage?: AgentUsage; error?: string }
-  | { type: "compaction" }
-  | { type: "error"; message: string };
-
-/** token 用量（message_end 时由 Core 累加进 record.totalTokens）。 */
-export interface AgentUsage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  /** 本 message 的成本（USD，来自 SDK usage.cost.total）。可选——无成本数据时缺省。 */
-  cost?: number;
-}
-
-export interface AgentUsageTotal extends AgentUsage {
-  /** 上述四项之和。投影时不再手工求和。 */
-  total: number;
-  /** 累计成本（USD，来自 SdkEvent.message.usage.cost.total 求和）。无成本数据时为 0。 */
-  cost: number;
-}
+// [S4 簇 3 收编] 事件面契约类型单源化（type-only）：AgentEvent / AgentUsage /
+// AgentUsageTotal / ToolCallResult / ToolCall / InternalToolCall / Turn 的本地定义
+// 已删除，自 @zhushanwen/subagent-engine-sdk re-export（SDK protocol/contract-types.ts
+// 是类型闭包 SSOT，core 反向 re-export 保上层消费面——import 方路径零改动；
+// shared/agent-event.ts 转发层链条保持）。结构等价由 protocol-closure.test.ts
+// 断言族守卫。
+//
+// AgentEvent 语义锚定（SDK 侧注释指向本处的对照权威源，勿删）：
+//   - Pi session.subscribe 上报的事件。Runtime 把它喂给 updateFromEvent。
+//   - 设计：AgentEvent 携带 updateFromEvent 收口进 record 所需的**全部数据**——
+//     tool_end 带 result（供 turn.toolCalls 存完整 ToolCall），无需翻译层旁路累积。
+//
+//   ACP 词汇对照（D11 注记级校准，零行为变更；新引擎实现者按本表对齐语义，
+//   详见 docs/architecture/subagent-engine-gui-visibility.md §3.3 D11）：
+//     text_delta / thinking_delta ↔ ACP content blocks（text / thinking）
+//     tool_start / tool_end      ↔ ACP tool_call / tool_call_update
+//     turn_end / message_end     ↔ ACP prompt turn 终态（stop_reason + usage）
+//     compaction                 ↔ ACP session/compaction
+//   本协议以 pi 为语义锚点（D3）——命名不迁移，对照表仅保证未来 AcpEngine 适配器
+//   与跨引擎 trace 映射的翻译成本最低。
+export type {
+  AgentEvent,
+  AgentUsage,
+  AgentUsageTotal,
+  InternalToolCall,
+  ToolCall,
+  ToolCallResult,
+  Turn,
+} from "@zhushanwen/subagent-engine-sdk";
 
 /**
  * eventLog 条目（getEventLog 派生产出的元素）。所有字段 readonly。
@@ -249,69 +245,6 @@ export type SdkEvent = {
   reason?: string;
 };
 
-/** tool 调用结果（tool_execution_end 时累积，含 structured-output 的 details）。 */
-export interface ToolCallResult {
-  content?: unknown[];
-  details?: unknown;
-}
-
-/**
- * tool 调用（导出的纯净数据形状，不含内部状态）。
- *
- *   tool_start 到达但 tool_end 未到时，调用为进行中；一旦 tool_end 到达，
- *   result/isError 填充完成。对外投影（AgentResult.toolCalls / getAllToolCalls）
- *   一律返回此类型——**不泄漏 running/done/failed 内部状态机**。
- *
- * 进行中状态由 execution-record 内部的 `InternalToolCall`（= ToolCall + _status）承载，
- * 只存在于 record.turns[].toolCalls，跨边界导出时由 getAllToolCalls strip _status。
- */
-export interface ToolCall {
-  toolName: string;
-  args?: unknown;
-  result?: ToolCallResult;
-  isError?: boolean;
-}
-
-/**
- * 内部 ToolCall：在 ToolCall 基础上追加 _status 进行中状态标记与 startedTs 时间戳。
- *
- *   running = tool_start 已收到但 tool_end 未到；
- *   done/failed = tool_end 已到。
- *
- * 仅存在于 ExecutionRecord.turns[].toolCalls（Core 内部可变状态）。
- * 跨边界导出（getAllToolCalls → AgentResult.toolCalls / 持久化）由 getAllToolCalls
- * 映射回 ToolCall（丢弃 _status / startedTs），保证导出形状清洁。
- */
-export interface InternalToolCall extends ToolCall {
-  _status: "running" | "done" | "failed";
-  /** tool_start 到达时的墙钟时间戳（Date.now()，ms）。getEventLog 派生 tool 条目 ts 用。 */
-  startedTs: number;
-}
-
-/**
- * 一个 turn 的完整内容（ExecutionRecord.turns[] 的元素）。
- *
- * 收口设计：text/thinking 流式累积**完整内容**（非 100 字切片），
- * toolCalls 存完整 ToolCall（含 result + _status 内部状态）。turn_end 到达后 closed=true，
- * 下次 text/thinking/tool 时开新 turn。
- *
- * eventLog / currentActivity / result 均从 turns[] 派生，不再独立存储。
- */
-export interface Turn {
-  /** 本 turn assistant 正文（text_delta 流式累积，完整）。 */
-  text: string;
-  /** 本 turn 推理（thinking_delta 流式累积，完整）。 */
-  thinking: string;
-  /** 本 turn 工具调用（InternalToolCall：含完整 result + _status 进行中标记）。 */
-  toolCalls: InternalToolCall[];
-  /** 本 turn message_end 的 token 增量（聚合得 totalUsage）。 */
-  usageDelta?: AgentUsage;
-  /** turn_end 是否已到达。false=正在进行；true=已闭合，下次内容开新 turn。 */
-  closed: boolean;
-  /** turn_end 到达时的墙钟时间戳（Date.now()，ms）。getEventLog 派生 turn_end 条目 ts 用。 */
-  closedTs?: number;
-}
-
 /** 一次 session 执行的完整结果。collectResult 产出，写入 Record.outcome。 */
 export interface AgentResult {
   text: string;
@@ -341,19 +274,10 @@ export interface AgentResult {
 // 本 section 先声明 ExecutionRecord 的组成值对象（WorktreeHandle / AliveMarker /
 // PatchResult 等），ExecutionRecord 本体及其文档注释在 section 末尾。
 
-/**
- * worktree handle 值对象。仅 worktree:true 时持有——worktree 是独立维度，
- * 需显式开启，fork alone 不创建 worktree。
- * Object.freeze 守卫保证不可变。
- */
-export interface WorktreeHandle {
-  /** checkout 目录（子 agent 工作目录，tmpdir 下）。 */
-  readonly path: string;
-  readonly branch: string;
-  readonly baseCommit: string;
-  /** 主仓库根目录（cleanup/scan 需要，不再靠路径反推）。 */
-  readonly mainCwd: string;
-}
+// [S4 簇 3 收编] WorktreeHandle 本地定义已删除，自 SDK re-export（原为结构等价
+// 副本，单源化后 SDK contract-types 是唯一定义点；「仅 worktree:true 时持有、
+// Object.freeze 守卫不可变」的语义注释见消费方 worktree-manager / worktree-git-ops）。
+export type { WorktreeHandle } from "@zhushanwen/subagent-engine-sdk";
 
 /** alive marker：子进程存活标记，用于心跳检测和 crash 推断。 */
 export interface AliveMarker {
@@ -479,6 +403,14 @@ export interface ExecutionRecord {
    * 回填（sessionFile 即定位符）。持久化经 subagent-record entry。
    */
   engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
+  /**
+   * 同步收集模式标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+   * 创建时确定不可变；undefined = async（缺省语义，旧记录零迁移）。持久化经
+   * subagent-record entry（record-entry.ts 序列化白名单，entry 唯一写点）。
+   * 消费方：U2 collectCoordinator 路由（sync→批缓冲）、U5 E1 重建投影。
+   * U2 接线点：service.createRecordForMode 从 ExecuteOptions.collect 读入 identity。
+   */
+  readonly collectMode?: "sync";
 
   // ── 状态（实时更新）──
   status: ExecutionStatus;
@@ -492,6 +424,13 @@ export interface ExecutionRecord {
    * record 无此字段，投影层按 projectOutcome 兜底（closed-legacy 语义）。
    */
   outcome?: ExecutionOutcome;
+  /**
+   * 离开批的终局标记（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+   * 两出口统一落标：① 批闭合 flush 写账成功后；② E9 dispose 逐条转 async 写账后
+   * （均 appendEntry 持久化，U3/U5 写点）。undefined = 未离开批 / 旧记录零迁移。
+   * 消费方：U5 E1 重建扫描只收「collectMode=sync 且无本标记」的成员（防双重通知）。
+   */
+  batchFinalized?: boolean;
   /** 完整执行内容，按 turn 组织。createRecord 初始化为 [空 turn]。 */
   turns: Turn[];
   /** turn 计数（= turns.filter(closed).length，冗余存储供投影直接读）。 */
@@ -676,6 +615,17 @@ export interface ExecuteOptions {
    * undefined/false = 一次性模式（默认，行为完全不变）。service.execute 透传到 createRecordForMode。
    */
   conversation?: boolean;
+  /**
+   * 同步收集模式（subagent-sync-collect 设计 §3.1.3，U1 foundation 契约）。
+   * undefined = config collectSync.default（缺省 "async"，新 session 生效）。
+   * schema 层枚举限 "async"|"sync"；运行时宽收 string 与 engine 字段同风格
+   * （非法值 ≠ "sync" 按 async 处理）。
+   * "sync" + conversation:true 组合在 startHandler E4 校验即拒
+   * （immediate throw，不产生半启动 record）。
+   * U2 接线点：service.createRecordForMode 读入 createRecord identity.collectMode
+   * （U1 打通类型与 startHandler 透传，record 落点归 U2）。
+   */
+  collect?: string;
   /**
    * 空闲超时毫秒数（仅 conversation 模式有意义）。覆盖默认 5min idle timeout。
    * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
@@ -764,6 +714,13 @@ export interface BgResponse {
    * 值语义由 U2（execution/notify-ledger.ts）兑现。
    */
   notifyContract: "ledger+at-least-once";
+  /**
+   * 同步收集登记回显段（subagent-sync-collect 设计 §3.1.1 交互样例，U1 foundation）。
+   * 仅 resolved 模式为 sync 时附带（async 响应字节零变化，G3）：mode = 生效模式；
+   * pendingSyncCount = 当前未闭合批的 sync 成员总数（含本条；跨轮派发续累不重置，
+   * 与 D2 隐式批一致）。
+   */
+  collect?: { mode: "sync"; pendingSyncCount: number };
 }
 
 /** list 的内层响应（挂在 SubagentToolResult.listResponse）。 */
@@ -902,12 +859,37 @@ export interface SubagentRecord {
    * subagent-engine-history）；缺省 = pi（走 JSONL 直读链）。
    */
   engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
+  /**
+   * 同步收集模式标记（与 ExecutionRecord.collectMode 同源投影/重建，U1 foundation）。
+   * 缺省（存量 record）= async 投影，消费方零迁移。
+   */
+  collectMode?: "sync";
+  /**
+   * 离开批终局标记（与 ExecutionRecord.batchFinalized 同源投影/重建，U1 foundation）。
+   * 缺省 = 未离开批；U5 E1 重建扫描据此排除已离场成员。
+   */
+  batchFinalized?: boolean;
 }
 
 // ============================================================
 // 配置（global + session）
 // ============================================================
 
+/**
+ * 同步收集（sync collect）配置节类型（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+ * 权威默认值在 config.ts DEFAULT_COLLECT_SYNC；坏值 sanitize 回默认不炸启动（E5，
+ * 与 maxConcurrent 同判）。类型定义于 types.ts（避免 config → types 反向依赖成环），
+ * config.ts re-export。
+ */
+export interface CollectSyncConfig {
+  /** start 未显式传 collect 时的缺省模式。新 session 生效（与 engine 配置时机一致）。 */
+  default: "async" | "sync";
+  /** 批通知单条目结果正文预算（字符）：超出截断并接 session_read 指针行。flush 时热读。 */
+  perItemChars: number;
+  /** 批通知结果正文总量预算（字符）：Σ 超限时统一收紧 effectivePerItem（U4 算法）。flush 时热读。 */
+  totalChars: number;
+}
+
 /**
  * 全局配置（~/.pi/agent/subagents/config.json）。
  *
@@ -925,6 +907,11 @@ export interface SubagentsGlobalConfig {
   defaultEngine?: string;
   /** 引擎路由策略（D9①）：strict=true 时一切 probe 失败直接报错（不 fallback）。 */
   engineRouting?: { strict: boolean };
+  /**
+   * 同步收集配置节（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+   * 整节缺省 = DEFAULT_COLLECT_SYNC（config.ts）；逐字段 sanitize 回默认（E5）。
+   */
+  collectSync?: CollectSyncConfig;
 }
 
 // ============================================================