@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/dist/{types-BxyAidGf.d.ts → types-DpUO16pj.d.ts}

@@ -1,3 +1,54 @@
+/**
+ * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
+ * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐。
+ */
+interface ModelRegistryLike {
+    /** 返回所有已配置鉴权的可用模型。 */
+    getAvailable(): ModelInfo[];
+    /** 按 (provider, modelId) 查找。 */
+    find(provider: string, modelId: string): ModelInfo | undefined;
+    /** 校验模型鉴权是否就绪。 */
+    hasConfiguredAuth(model: unknown): boolean;
+}
+/**
+ * 模型信息（registry 返回元素 / ctx.model 鸭子类型兼容）。
+ * ctx.model（SDK Model<Api>）是此类型的超集，运行时直接当 ModelInfo 用。
+ */
+interface ModelInfo {
+    id: string;
+    name: string;
+    provider: string;
+    reasoning: boolean;
+    thinkingLevelMap?: Record<string, unknown>;
+    contextWindow?: number;
+}
+/** agent .md frontmatter 解析结果。 */
+interface AgentConfig {
+    /** agent 名（文件名 basename）。 */
+    name: string;
+    /** system prompt（markdown 正文）。 */
+    systemPrompt: string;
+    /** tool allowlist（三层过滤之一）。 */
+    tools?: string[];
+    /** 默认模型 override（"provider/modelId"）。agent 作者显式指定。 */
+    model?: string;
+    /** 默认 thinkingLevel override。 */
+    thinkingLevel?: string;
+    /** 默认 background 模式（true 时无显式 wait 走 background）。 */
+    defaultBackground?: boolean;
+    /**
+     * 执行引擎 id（agent .md frontmatter engine 字段，D9 per-agent 主通道）。
+     * 解析期已对注册表校验（未注册 id 在 agent-registry 抛 EngineNotFoundError）；
+     * 执行侧（P4 路由层）按 调用参数 > 本字段 > 全局默认 三层取值。
+     */
+    engine?: string;
+}
+/** 解析结果（model 实例 + 生效的 thinkingLevel）。 */
+interface ResolvedModel {
+    model: ModelInfo;
+    thinkingLevel: string | undefined;
+}
+
 /**
  * 唯一执行状态。所有路径共用。v4 B-1 两态收敛：旧 idle 折入 running、
  * 旧 cancelled 折入 closed（closedReason='cancelled' 区分）。
@@ -28,6 +79,13 @@ type ExecutionStatus = "running" | "closed";
  *                     不分），message/fork-from 据此给出可行动指引。
  */
 type ClosedReason = 'parent-shutdown' | 'parent-fork' | 'parent-new' | 'user-close' | 'cancelled' | 'gc' | 'disconnected';
+/**
+ * [v8.5 D] 透明重生守卫拒绝专用错误：messageHandler 的 endedMessageGuard 必须原样
+ * 透传本类错误（自带完整行动语言），不得按 A1 分流规则改写——否则 worktree/异进程
+ * 占用文案会被「fork-from 指引」覆盖，误导 agent 走已被判死的通道。
+ */
+declare class ResurrectDeniedError extends Error {
+}
 /**
  * 终态三态对外语义（U3 C-outcome 一等披露）。
  *
@@ -40,6 +98,27 @@ type ClosedReason = 'parent-shutdown' | 'parent-fork' | 'parent-new' | 'user-clo
  * 「父进程关闭时子 agent 未完成即失败」，选定行为而非疏漏，勿当 bug 改回 cancelled。
  */
 type ExecutionOutcome = "completed" | "failed" | "cancelled";
+/**
+ * 对外投影的 outcome 联合：含历史 record（outcome 字段诞生前的存量数据）兼容态。
+ * 投影层（projectOutcome 唯一出口）对无 outcome 字段的 closed record 按
+ * deriveOutcome(closedReason, error) 兜底派生；"closed-legacy" 预留给连派生输入都
+ * 不足以判读的存量形态，消费方必须处理该成员（不得因未知值崩溃）。
+ */
+type ProjectedOutcome = ExecutionOutcome | "closed-legacy";
+/**
+ * 对外四态（设计决策 10 细则 3）：内部 ExecutionStatus（v4 B-1 两态）收敛为 agent
+ * 可理解的状态语义。真实映射只有两条：
+ *   running → active / closed → ended（closed 统一终态，含 cancelled）。
+ * mapExternalState 不消费 ClosedReason——closed 恒映射 ended。
+ *
+ * waiting / error 是历史多态映射（idle→waiting / failed+crashed→error）的遗留声明：
+ * 对外四态联合契约不变，但当前状态机不产生这两个值。
+ *
+ * 原始 ExecutionStatus 进 list item 的 status 字段供调试；state 是对外主字段。
+ * 映射实现见 subagent-actions.ts mapExternalState——未来内部加态必须扩展该处，
+ * 漏加会在 default 分支编译报错，不影响对外契约。
+ */
+type ExternalState = "active" | "waiting" | "ended" | "error";
 /** 执行模式。background = 调用方立即拿 handle 返回，子 agent 在 detached promise 里跑。 */
 type ExecutionMode = "background";
 /**
@@ -101,6 +180,39 @@ interface AgentUsageTotal extends AgentUsage$1 {
     /** 累计成本（USD，来自 SdkEvent.message.usage.cost.total 求和）。无成本数据时为 0。 */
     cost: number;
 }
+/**
+ * eventLog 条目（getEventLog 派生产出的元素）。所有字段 readonly。
+ *
+ * text_output / thinking 类型已移除——它们是 100 字切片的碎片副产物，
+ * 现在完整内容收口在 record.turns[] 里，eventLog 只承载离散语义事件
+ * （tool 调用 / turn 边界 / error）。
+ */
+interface AgentEventLogEntry {
+    readonly type: "tool_start" | "tool_end" | "turn_end" | "error";
+    readonly label: string;
+    /** 事件发生的墙钟时间戳（Date.now()，ms）。由 getEventLog 从 turns[] 派生时记录。 */
+    readonly ts: number;
+    readonly status?: "running" | "done" | "failed";
+}
+/**
+ * [STEP3] displayItem：从 turns[] 派生的展示项（对齐 nicobailon getDisplayItems）。
+ *
+ * 与 eventLog 的区别：eventLog 承载离散语义事件（tool_start/tool_end/turn_end），
+ * displayItem 承载「可渲染单元」（toolCall 含完整 name+args 供 formatToolCall 格式化；
+ * text 含 assistant 正文）。renderResult compact 分支改用 displayItems 后，
+ * 行格式与 nicobailon 完全一致（→ formatToolCall）。
+ */
+interface DisplayItem {
+    readonly type: "toolCall" | "text";
+    /** toolCall：tool 名称（bash/read/edit...）；text：无。 */
+    readonly name?: string;
+    /** toolCall：tool 原始 args（供 formatToolCall 提取路径/命令）；text：无。 */
+    readonly args?: Record<string, unknown>;
+    /** toolCall：执行状态（running 时无✓/✗标记）；text：正文文本。 */
+    readonly status?: "running" | "done" | "failed";
+    /** text：assistant 正文（compact 时取首行/截断）。 */
+    readonly text?: string;
+}
 /** tool 调用结果（tool_execution_end 时累积，含 structured-output 的 details）。 */
 interface ToolCallResult {
     content?: unknown[];
@@ -188,6 +300,20 @@ interface WorktreeHandle {
     /** 主仓库根目录（cleanup/scan 需要，不再靠路径反推）。 */
     readonly mainCwd: string;
 }
+/** alive marker：子进程存活标记，用于心跳检测和 crash 推断。 */
+interface AliveMarker {
+    readonly pid: number;
+    readonly id: string;
+    readonly startedAt: number;
+}
+/** fork depth 超限错误。 */
+declare class ForkDepthExceededError extends Error {
+    constructor(message: string);
+}
+/** worktree 有未提交变更错误。 */
+declare class DirtyWorktreeError extends Error {
+    constructor(message: string);
+}
 /**
  * 所有执行路径的唯一状态源。
  *
@@ -354,6 +480,343 @@ interface ExecutionRecord {
     hadWorktree?: boolean;
     controller: AbortController | undefined;
 }
+/**
+ * Tool 返回的 details（内层扁平结构）。
+ * 由 project(record) 唯一产出——sync/bg 两路径字段一致。
+ * 含 mode + sessionFile（供外层 SubagentToolResult 分组 + spinner 判断）。
+ *
+ * 分层（spec FR-3）：此为**内层**，不感知 action/外层分组。
+ * 外层 SubagentToolResult 由 adapter 包裹产出（加 action/subagentId/sessionFile + 分组）。
+ */
+interface SubagentToolDetails {
+    status: ExecutionStatus;
+    /**
+     * 终态三态对外语义（U3 C-outcome，projectOutcome 唯一出口）。running → undefined；
+     * 历史数据无 outcome 字段时兜底派生（见 ProjectedOutcome）。
+     */
+    outcome?: ProjectedOutcome;
+    mode: ExecutionMode;
+    agent: string;
+    model: string;
+    thinkingLevel: string | undefined;
+    /** 短标签（≤35 字符），来自 record.slug。旧 record 反序列化时为空串。 */
+    slug: string;
+    turns: number;
+    totalTokens: number;
+    elapsedSeconds: number;
+    eventLog: AgentEventLogEntry[];
+    /** [STEP3] 从 turns[] 派生的展示项（对齐 nicobailon getDisplayItems）。 */
+    displayItems: DisplayItem[];
+    result?: string;
+    error?: string;
+    /** running 时的当前活动行（tool/thinking/text 优先级）。 */
+    currentActivity?: {
+        type: "tool" | "text" | "thinking";
+        label: string;
+    };
+    /** schema 模式下，structured-output tool 的 result.details（对齐 workflow agent-pool）。 */
+    parsedOutput?: unknown;
+    /** session jsonl 文件名（不含目录）。窗口期内可能 undefined（session 尚未创建成功）。 */
+    sessionFile?: string;
+    /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
+    patchFile?: string;
+}
+/** Hub.execute 的入参（sync/bg 共用）。mode 由 Hub 内部判定，不暴露给调用方。 */
+interface ExecuteOptions {
+    task: string;
+    /**
+     * 短标签（≤35 字符），简述本次执行用途，展示在 TUI。必填。
+     * workflow 内 agent() 调用时从 AgentCallOpts.description 透传而来。
+     */
+    slug: string;
+    agent?: string;
+    model?: string;
+    thinkingLevel?: string;
+    skillPath?: string;
+    appendSystemPrompt?: string[];
+    schema?: Record<string, unknown>;
+    /** D-A6 bridge: workflow schemaEnv 经 ExecuteOptions 透传到 runSpawn childEnv。 */
+    schemaEnv?: string;
+    /**
+     * Turn 上限 limiter。显式 0/负 = 显式不限：压过 SPAWN_WATCHDOG_ENV 兑底不挂
+     * watchdog（SP-6 参数 > env，U5）；undefined 未传才由 env 兑底。
+     */
+    maxTurns?: number;
+    graceTurns?: number;
+    /** sync 模式来自 Pi tool 框架；background 模式 hub 忽略，自建 controller。 */
+    signal?: AbortSignal;
+    /** 主 agent 当前模型（模型解析第三层兼底）。execute 调用方从 ctx.model 传入。 */
+    ctxModel?: ModelInfo;
+    /** background 完成回调（sync 不调）。 */
+    onComplete?: (record: RecordSnapshot) => void;
+    /** 是否继承父会话上下文（fork 模式，只继承上下文）。 */
+    fork?: boolean;
+    /**
+     * [v8.5 B] fork-from 显式指定继承源 session 文件（非主 session）。
+     * 与 fork:true 的区别：fork:true 用主 session 作 --fork 源；本字段用任意已有
+     * session 文件（断联 subagent 接续场景）作源。优先级高于 fork；传了本字段时
+     * fork 取值不影响 spawn 参数。仅 pi 引擎支持（同 fork）。仅 background tool
+     * 层 fork-from action 使用；workflow / executeAndAwait 不消费。
+     */
+    forkFromSessionFile?: string;
+    /** 文件系统隔离：true=创建新 git worktree，WorktreeHandle=复用外部已创建的；undefined=不隔离（parent cwd）。 */
+    worktree?: boolean | WorktreeHandle;
+    /** 覆盖执行 cwd（默认 mainCwd）。 */
+    cwd?: string;
+    /**
+     * 可持续对话模式（决策 8：独立 chatMode 标志，不扩展 ExecutionMode）。
+     * true = record 标记 chatMode，轮次完成进 idle 态（保留 record + worktree，等待 message 续聊）；
+     * undefined/false = 一次性模式（默认，行为完全不变）。service.execute 透传到 createRecordForMode。
+     */
+    conversation?: boolean;
+    /**
+     * 空闲超时毫秒数（仅 conversation 模式有意义）。覆盖默认 5min idle timeout。
+     * 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
+     * 显式传 0/负数 = 禁用 idle GC（不挂 timer；旧实现 0 会落成 setTimeout(0) 立即 kill）。
+     */
+    idleTimeoutMs?: number;
+    /**
+     * 实际执行引擎 id（P4 路由留痕）：pi 引擎由 PiEngine.run 在还原 opts 时写入；
+     * 缺省（历史调用方不设）= pi 投影。createRecordForMode 读入 record identity。
+     */
+    engine?: string;
+    /**
+     * 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎时由路由层写入）。
+     * from = 请求引擎 id，reason 恒 'engine_probe_failed'（GUI 警告条数据源）。
+     */
+    engineFallback?: {
+        from: string;
+        reason: string;
+    };
+}
+/**
+ * execute 返回值。
+ *   background: { mode:"background", subagentId, sessionFile, details } —— 立即返回。
+ *            subagentId 供后续 cancel/list 用；sessionFile 窗口期可能 undefined。
+ */
+type ExecutionHandle = {
+    mode: "background";
+    subagentId: string;
+    sessionFile: string | undefined;
+    details: SubagentToolDetails;
+};
+/** list 的 item 结构。 */
+interface SubagentListItem {
+    subagentId: string;
+    agent: string;
+    /** 短标签（≤35 字符），来自 record.slug。旧 record 反序列化时为空串。 */
+    slug: string;
+    /** 对外四态（决策 10 细则 3，主字段）。由 mapExternalState(status) 派生。 */
+    state: ExternalState;
+    /** 原始内部状态（调试用，供 details 展示）。 */
+    status: ExecutionStatus;
+    mode: ExecutionMode;
+    /** 运行秒数（running 态实时计算，终态 endedAt-startedAt）。 */
+    duration: number;
+    model: string;
+    totalTokens: number;
+    /** session jsonl 文件名（窗口期内可能 undefined）。 */
+    sessionFile?: string;
+    /** 直接父 subagent record ID（顶层 record 为 undefined）。[v4 A-6] 从
+     *  record.parentRecordId 派生，配合 A-5 直接父守卫（message/close 仅作用于直接子）。 */
+    parent?: string;
+    /** 可冷路径 resume（running 且无活进程句柄）。[v4 A-6] B-1「可续聊」对外表达，
+     *  agent 据 list 判断哪些 running subagent 实际可续聊（vs 正在忙）。 */
+    resumable?: boolean;
+    /**
+     * 终态三态对外语义（U3 C-outcome 一等披露，projectOutcome 唯一出口）：
+     * completed / failed / cancelled，历史 record 无 outcome 字段时兜底派生，
+     * 不可判读的存量形态为 "closed-legacy"。GUI pane / agent 据此判读成败，
+     * 无需翻 error 字段原文（S5）。
+     */
+    outcome?: ProjectedOutcome;
+}
+/** background 启动的内层响应（挂在 SubagentToolResult.bgResponse）。 */
+interface BgResponse {
+    status: "running";
+    mode: "background";
+    /** 启动提示文案（"detached, will notify on completion"）。 */
+    message: string;
+    /**
+     * 终态三态语义（U3 C-outcome 对外 JSON 契约完备位）。start 时点 record 尚未终态，
+     * 恒 undefined（JSON.stringify 落键省略）；终态成败语义经 list items[].outcome
+     * 披露。旧字段 status/mode/message 原样保留（向后兼容）。
+     */
+    outcome?: ProjectedOutcome;
+    /**
+     * 通知投递契约回显位（U1 预置，U2 通知账本的契约声明）。恒值
+     * "ledger+at-least-once"：主 agent 在当前 run 结束或有限延迟内收到完成通知，
+     * 送达保证为 at-least-once + notifyId 幂等可识别。字段与填充由 U1 负责，
+     * 值语义由 U2（execution/notify-ledger.ts）兑现。
+     */
+    notifyContract: "ledger+at-least-once";
+}
+/** list 的内层响应（挂在 SubagentToolResult.listResponse）。 */
+interface ListResponse {
+    /** items 中 status==="running" 的计数（受 limit 截断如实反映，非全局总数）。 */
+    running: number;
+    items: SubagentListItem[];
+}
+/** cancel 的内层响应（挂在 SubagentToolResult.cancelResponse）。 */
+interface CancelResponse {
+    cancelled: true;
+}
+/**
+ * message 的内层响应（挂在 SubagentToolResult.messageResponse，决策 10 瘦身）。
+ *
+ * [R1 删除记录] 旧 PendingMessage（在途消息缓存条目，消费确认制，设计决策 6 状态×
+ * interrupt 映射）已随 deliverToRunning 一并删除——SP-5 upgrade 后无生产调用方，
+ * 配套三段消费链（push / message_start shift / redeliverPending 补投）全部不可达。
+ * 详见 subagent-service.ts 的删除记录注释。
+ */
+interface MessageResponse {
+    delivered: true;
+}
+/** close 的内层响应（挂在 SubagentToolResult.closeResponse，决策 10 瘦身）。 */
+interface CloseResponse {
+    closed: true;
+}
+/** fork-from 的内层响应：新 subagent id + 作为继承源的旧记录 session 文件。
+ *  [v8.5 B] 断联恢复通道——新 subagent 以 --fork 方式继承旧会话历史，源文件只读
+ *  不续写（pi fork 建 branched session，copy-on-write）。 */
+interface ForkFromResponse {
+    /** 新 subagent record id（接续对话用 action:'message'）。 */
+    newSubagentId: string;
+    /** 作为继承源的旧 subagent session jsonl 绝对路径。 */
+    sourceSessionFile: string;
+}
+/** /subagents list 左列展示单元。来自内存(running) 或 session.jsonl 重建(终态)。 */
+interface SubagentRecord {
+    id: string;
+    agent: string;
+    /** 任务提示词（详情面板置顶展示）。磁盘/内存源均有。 */
+    task: string;
+    /** 短标签（≤35 字符）。磁盘重建源旧文件可能缺失→兜底空串。 */
+    slug: string;
+    status: ExecutionStatus;
+    /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。SP-1 新增。 */
+    closedReason?: ClosedReason;
+    mode: ExecutionMode;
+    startedAt: number;
+    /** 根 Pi session ID（session 隔离过滤用）。递归链上所有层 record 同值。 */
+    rootSessionId: string | undefined;
+    /** 直接父 subagent record ID（层级树构建用）。顶层 record 为 undefined。 */
+    parentRecordId: string | undefined;
+    /** subagent 递归深度。顶层 =0，每层嵌套 +1。 */
+    depth: number;
+    endedAt: number | undefined;
+    turns: number;
+    totalTokens: number;
+    model: string;
+    thinkingLevel: string | undefined;
+    eventLog: AgentEventLogEntry[];
+    /** [STEP3] 从 turns[] 派生的展示项（对齐 nicobailon getDisplayItems）。 */
+    displayItems: DisplayItem[];
+    /** running 时的当前活动行（仅内存源；磁盘重建无此数据）。streaming 可观测性用。 */
+    currentActivity?: {
+        type: "tool" | "text" | "thinking";
+        label: string;
+    };
+    result?: string;
+    error?: string;
+    sessionFile?: string;
+    /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
+    patchFile?: string;
+    /**
+     * [review round2] 创建时启用 worktree 隔离（磁盘重建源从 session entry 恢复；内存源由
+     * recordToSubagent 从 worktreeHandle 投影）。getRecordForAction 跨重启重建时据此拒绝续聊。
+     */
+    worktree?: boolean;
+    /**
+     * 对话轮次计数（仅 chatMode idle record 有意义）。round 仅在内存维护（doFinalizeRoundToIdle
+     * 递增），跨重启不恢复（round 无磁盘持久化）；非对话模式 / 非 idle record 为 undefined。内存源由 recordToSubagent 从
+     * ExecutionRecord.round 投影。
+     */
+    round?: number;
+    /**
+     * 对话模式标志（与 ExecutionRecord.chatMode 同义；投影给 GUI 侧 streaming/waiting/done
+     * 细分判据——one-shot 轮终（chatMode 非 true + result 有值）显示完成态，chat 轮终显示
+     * 等续聊。内存源由 recordToSubagent 投影，磁盘源经 subagent-record entry 重建）。
+     */
+    chatMode?: boolean;
+    /**
+     * 执行态信号（与 ExecutionRecord.resumable 同义）：true = 无活进程驱动的 running
+     * （轮终 idle / 重建孤儿兜底），GUI 侧据此排除「真在跑」判定。
+     */
+    resumable?: boolean;
+    /** 外部 Pi 实例（进程隔离模式下由外部启动的子进程）。 */
+    externalInstance?: AliveMarker;
+    /** fork 模式下的 worktree handle。 */
+    worktreeHandle?: WorktreeHandle;
+    /**
+     * 实际执行引擎 id（P4 路由留痕）。缺省 = pi 投影（存量 record 零迁移）；
+     * GUI 警告条/引擎标记的数据源之一。
+     */
+    engine?: string;
+    /** 引擎 fallback 留痕（D9①：probe 失败路由回默认引擎）。GUI 警告条数据源。 */
+    engineFallback?: {
+        from: string;
+        reason: string;
+    };
+    /**
+     * 引擎自描述定位符（U1：EngineHandleData 的持久化消费面子集，引擎无关——
+     * sessionRef 整体透传不枚举内部键）。read 降级链①②级的数据源（runtime
+     * subagent-engine-history）；缺省 = pi（走 JSONL 直读链）。
+     */
+    engineHandle?: {
+        sessionRef: Record<string, string>;
+        journalPath?: string;
+        poolKey: string;
+    };
+}
+/**
+ * 全局配置（~/.pi/agent/subagents/config.json）。
+ *
+ * 模型解析已退化为「主 agent model 优先，仅 override 时查 registry」——
+ * 不再有 category/fallback/yolo 字段。config.json 只保留 maxConcurrent
+ * （pool 大小）。旧 config.json 中的 categories/fallback 等字段读取时忽略。
+ */
+interface SubagentsGlobalConfig {
+    version: number;
+    maxConcurrent: number;
+    /**
+     * 全局默认执行引擎（D9 三层优先级的最底层：调用参数 > agent frontmatter > 本值）。
+     * 缺省 'pi'（P4 路由层 DEFAULT_ENGINE_ID）。加载期只做类型校验，注册表校验归路由层。
+     */
+    defaultEngine?: string;
+    /** 引擎路由策略（D9①）：strict=true 时一切 probe 失败直接报错（不 fallback）。 */
+    engineRouting?: {
+        strict: boolean;
+    };
+}
+/**
+ * Record 的只读视图。store.snapshot() 返回。
+ * TUI 拿到此类型，保证不会回写 Core 状态。
+ *
+ * 不含 eventLog——snapshot 的消费点（cancel 判 mode/status、hasRunning 判 mode、
+ * toNotifyRecord 取 result/error）均不读 eventLog。需要 eventLog 的场景用 project()
+ * 投影的 SubagentToolDetails。需要完整内容用 record.turns[]（Core 内部）。
+ */
+interface RecordSnapshot {
+    readonly id: string;
+    readonly agent: string;
+    readonly model: string;
+    readonly thinkingLevel: string | undefined;
+    readonly mode: ExecutionMode;
+    readonly task: string;
+    /** 短标签（≤35 字符）。来自 record.slug。 */
+    readonly slug: string;
+    readonly status: ExecutionStatus;
+    /** 对话模式标志（与 ExecutionRecord.chatMode 同源）。cancel 别名判定用。 */
+    readonly chatMode?: boolean;
+    readonly turns: number;
+    readonly totalTokens: number;
+    readonly startedAt: number;
+    readonly endedAt: number | undefined;
+    readonly result: string | undefined;
+    readonly error: string | undefined;
+    readonly sessionFile: string | undefined;
+}
 
 /**
  * Workflow Extension — Engine 共享类型
@@ -872,4 +1335,4 @@ type InteractResult = {
     message: string;
 };
 
-export type { AgentTaskSpec as A, DoneReason as D, EngineCapabilities as E, InteractAction as I, ProbeReport as P, RunStatus as R, SessionView as S, TracePatch as T, WorkerLogEntry as W, AgentEvent as a, EngineHandle as b, AgentOutcome as c, InteractResult as d, AgentUsage as e, AgentCallOpts as f, AgentResult as g, ExecutionTraceNode as h, EngineHandleData as i, PersonaSpec as j, ReplayedTurn as k };
+export { type AgentTaskSpec as A, type BgResponse as B, type ClosedReason as C, type DoneReason as D, type EngineCapabilities as E, type ForkFromResponse as F, type SubagentListItem as G, DirtyWorktreeError as H, type InteractAction as I, ForkDepthExceededError as J, type PersonaSpec as K, type ListResponse as L, type ModelInfo as M, type ReplayedTurn as N, ResurrectDeniedError as O, type ProbeReport as P, type RunStatus as R, type SessionView as S, type TracePatch as T, type WorkerLogEntry as W, type AgentEvent as a, type EngineHandleData as b, type EngineHandle as c, type AgentOutcome as d, type InteractResult as e, type AgentUsage as f, type AgentCallOpts as g, type AgentResult as h, type ExecutionTraceNode as i, type SubagentsGlobalConfig as j, type ModelRegistryLike as k, type AgentConfig as l, type ResolvedModel as m, type ExecutionRecord as n, type RecordSnapshot as o, type SubagentRecord as p, type ExecuteOptions as q, type ExecutionHandle as r, type ExecutionStatus as s, type ExecutionMode as t, type AgentEventLogEntry as u, type DisplayItem as v, type CancelResponse as w, type CloseResponse as x, type MessageResponse as y, type ExternalState as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Cross-host shared subagent execution layer and workflow orchestration core (dual-form npm package: TS source for workspace, dist ESM+CJS for npm)",
   "type": "module",
   "license": "MIT",
@@ -76,13 +76,15 @@
   "files": [
     "src/",
     "workflows/",
-    "dist/"
+    "agents/",
+    "dist/",
+    "dist.bundle/"
   ],
   "dependencies": {
     "ajv": "^8.20.0",
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.7.0"
+    "@xyz-agent/extension-protocol": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -93,6 +95,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "build:bundle": "tsup",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }

package/src/__tests__/review-fix-loop-script.test.ts

@@ -12,11 +12,14 @@
 //         （旧实现不排除 error 分支，agent 失败被误诊为引擎透传未上线并烧掉 once 名额）
 //   - A11：model 缺省回退 "(default)"（请求时参数语义）
 //   - A12：promptMode=null（aggregator/fixer）必须保持 null，不被 || 误转 "full"
-import { readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { copyFileSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { promisify } from "node:util";
 import vm from "node:vm";
 
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 const WORKFLOW_SOURCE = readFileSync(
   join(__dirname, "..", "..", "workflows", "review-fix-loop.js"),
@@ -286,3 +289,88 @@ describe("review-fix-loop.js 模块形态约束", () => {
     await expect(import("../../workflows/review-fix-loop.js")).rejects.toThrow();
   });
 });
+
+// ── RX2-F2：fixAgent=fallow-scan 显式拒收（脚本顶层参数校验，非函数段） ──
+// 拒收逻辑位于脚本顶层（FIX_AGENT_RAW 解析后、resolveAgentDefs 前），函数段抽取法
+// 覆盖不到；改用 review-fix-loop-scriptpath-failfast.test.ts 同款「AsyncFunction 包装
+// + node -e 真实子进程」探针跑整脚本顶层副本。拒收点在 RUN_ROOT 落盘 / lockReviewBase
+// 之前，探针无文件系统副作用、恒非零退出。
+describe("review-fix-loop.js fixAgent=fallow-scan 显式拒收（RX2-F2）", () => {
+  const run = promisify(execFile);
+
+  /** execFile reject 侧的最小形状（Node ExecException 子集）。 */
+  interface ExecFailure extends Error {
+    code?: number | string;
+    stderr?: string;
+  }
+
+  function isExecFailure(e: unknown): e is ExecFailure {
+    return e instanceof Error;
+  }
+
+  let sandboxDir = "";
+
+  beforeEach(() => {
+    sandboxDir = mkdtempSync(join(tmpdir(), "rfl-fixagent-guard-"));
+    const workflowsDir = join(__dirname, "..", "..", "workflows");
+    // 副本以 .cjs 落 sandbox（require 解析形态对齐 worker 宿主）；utils 锚定加载经
+    // workerData.scriptPath（副本同目录），白名单校验前即需要它
+    copyFileSync(join(workflowsDir, "review-fix-loop.js"), join(sandboxDir, "review-fix-loop.cjs"));
+    copyFileSync(join(workflowsDir, "review-fix-loop-utils.cjs"), join(sandboxDir, "review-fix-loop-utils.cjs"));
+  });
+
+  afterEach(() => {
+    rmSync(sandboxDir, { recursive: true, force: true });
+  });
+
+  /** -e 探针体：AsyncFunction 复刻 worker 模板宿主形态（workerData/$ARGS/log 注入）。 */
+  function probeCode(argsJson: string): string {
+    const copyPath = join(sandboxDir, "review-fix-loop.cjs");
+    return [
+      "const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;",
+      "const src = require('fs').readFileSync(" + JSON.stringify(copyPath) + ", 'utf8');",
+      "const runner = new AsyncFunction('workerData', '$ARGS', 'require', 'log', src + '\\n');",
+      "const workerData = { scriptPath: " + JSON.stringify(join(sandboxDir, "review-fix-loop.cjs")) + " };",
+      "const $ARGS = " + argsJson + ";",
+      // $MODEL 是 worker 模板全局（主模型注入）——对照用例会推进到 fixAgent 解析之后
+      // 的 MODEL = $MODEL 行（:204），缺席会 ReferenceError 而非到达批次校验
+      "const $MODEL = 'probe-model';",
+      "runner(workerData, $ARGS, require, function () {}).catch(function (e) {",
+      "  require('fs').writeSync(2, String((e && e.message) || e) + '\\n');",
+      "  process.exit(1);",
+      "});",
+    ].join("\n");
+  }
+
+  async function runProbeExpectFailure(argsJson: string): Promise<string> {
+    const outcome = await run(process.execPath, ["-e", probeCode(argsJson)], {
+      cwd: sandboxDir,
+      timeout: 30_000,
+    }).then(
+      (): ExecFailure | null => null,
+      (e: unknown): ExecFailure | null => (isExecFailure(e) ? e : null),
+    );
+    if (outcome === null) {
+      throw new Error("expected non-zero exit, but node exited 0 with args: " + argsJson);
+    }
+    return String(outcome.stderr ?? "");
+  }
+
+  it("fixAgent=fallow-scan → 非零退出 + 保留字错误 + fallowScan=true 恢复指引", async () => {
+    const stderr = await runProbeExpectFailure(
+      '{ targetType: "file", target: "probe", fixAgent: "fallow-scan" }',
+    );
+    expect(stderr).toContain("内部保留字");
+    expect(stderr).toContain("fallowScan=true");
+    // 旧实现静默映射 FALLOW_DEF（fix 派发退化为通用 subagent）——不会到达此处报错
+  });
+
+  it("对照：合法形态 fixAgent（.md 路径）不触发保留字拒收（后续批次校验照常 fail）", async () => {
+    const stderr = await runProbeExpectFailure(
+      '{ targetType: "file", target: "probe", fixAgent: "/tmp/rx2-f2-fake-agent.md" }',
+    );
+    // 推进到批次解析才失败（缺批次参数）——证明拒收只对字面值 fallow-scan 触发
+    expect(stderr).toContain("缺少批次参数");
+    expect(stderr).not.toContain("内部保留字");
+  });
+});

package/src/__tests__/review-fix-loop-utils.test.ts

@@ -1140,6 +1140,27 @@ describe("findIssueKey — 归一化键空间查找", () => {
     expect(findIssueKey(issues, "MF-1")).toBe("MF-1 (fixed)");
     expect(findIssueKey(issues, "mf-1 (by design)")).toBe("MF-1 (fixed)");
   });
+
+  it("原型链键（__proto__/toString/constructor）→ 不命中（Object.hasOwn 首查，zsw 侧同款修复上收）", () => {
+    // 旧 truthy 查表（issues[issueId]）会让 Object.prototype 上的成员误命中：
+    // issues["__proto__"] 取到原型对象（truthy）→ 返回 "__proto__" 当台账键 →
+    // 调用方读 issues["__proto__"].severity 得 undefined/函数污染 fix 对账。
+    // ID 来自 LLM 产出，原型链键是真实攻击面而非理论边界。
+    const issues = { "MF-1": { severity: "major" } };
+    expect(findIssueKey(issues, "__proto__")).toBeUndefined();
+    expect(findIssueKey(issues, "toString")).toBeUndefined();
+    expect(findIssueKey(issues, "constructor")).toBeUndefined();
+    expect(findIssueKey(issues, "hasOwnProperty")).toBeUndefined();
+  });
+
+  it("own 键且值 falsy（null）→ 仍命中该键（hasOwn 与 truthy 查表的等价性由归一化回退段兜底）", () => {
+    // 旧 truthy 查表在值 falsy 时不直接命中，但归一化回退段（Object.keys 只枚举
+    // own 键）会命中同一键——两形态最终返回一致，hasOwn 只是路径更短、且对原型链
+    // 键正确拒绝。断言钉住该等价性，防未来有人「顺手」改回 truthy 形态。
+    const issues = { "MF-1": null };
+    expect(findIssueKey(issues, "MF-1")).toBe("MF-1");
+    expect(findIssueKey(issues, "mf-1")).toBe("MF-1");
+  });
 });
 
 describe("T-2 端到端：normIssueId/findIssueKey 在 validateFixResult 的真实消费", () => {