@zhushanwen/subagent-core 0.7.1 → 0.9.0

package/dist/engine-discovery-scan-Da4Dkzsi.d.cts

@@ -0,0 +1,818 @@
+import { WorktreeHandle, AgentFailureKind, AgentOutcomeUsage, ToolCallEntry, EngineHandleData, EngineCapabilities, ProbeReport, AgentEvent, ResumeAnchor, AgentOutcome, SessionView, ModelCatalogEntry } from '@zhushanwen/subagent-engine-sdk';
+import { ChildProcess } from 'node:child_process';
+
+/**
+ * Workflow Extension — Engine 共享类型
+ *
+ * Engine 层全局基础类型。零 infra 依赖——不 import 任何 infra 文件，
+ * 可独立编译测试（D-12 三层架构，AC-1）。
+ *
+ * 核心内容：
+ * - 状态机：RunStatus = "running" | "done"（2 态，一次性生命周期，FR-3）
+ * + DoneReason（completed/failed/aborted/budget_limited/time_limited）
+ * - AgentCallOpts / AgentResult（单次 agent 调用的输入/输出，宿主面 SSOT 留守本地）
+ * + AgentUsage / ToolCallEntry / AgentFailureKind（自 SDK re-export，S4 簇 3 收编）
+ * - ExecutionTraceNode / TracePatch / ToolCallEntry / WorkerLogEntry（trace 数据）
+ *
+ * 层归属：Engine（数据结构 + 不变式守卫）。
+ */
+
+/**
+ * 状态机：2 态（D-12 / FR-3，一次性生命周期——run 不可挂起）。
+ *
+ * running → done
+ *
+ * `done` 是唯一终态，具体原因由 DoneReason 区分。
+ */
+type RunStatus = "running" | "done";
+/** 终态原因。done 时必有（WorkflowRun 不变式）。 */
+type DoneReason = "completed" | "failed" | "aborted" | "budget_limited" | "time_limited" | "invalid_args";
+/**
+ * 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 派生说明），
+ * 与字段同文件；subagent-actions-core（slug 校验）、subagent-service（record slug 截断）
+ * 与壳侧 tool schema maxLength 共享引用。
+ */
+declare 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 形状保持兼容。
+ */
+interface AgentCallOpts {
+    /** The task prompt to send to the agent. */
+    prompt: string;
+    /**
+    * Optional JSON schema for structured output.
+    * When provided, the schema is passed via PI_WORKFLOW_SCHEMA env to the subprocess,
+    * which activates the structured-output tool + turn_end hook.
+    * The tool's execute validates model output against the schema.
+    * On success, `parsedOutput` on the result is set to `tool_execution_end.result.details`
+    * (the validated, parsed data object — not the raw tool call args).
+    */
+    schema?: Record<string, unknown>;
+    /**
+    * Model to use (e.g. "router-openai/glm-5.1").
+    * When omitted, pi's default model is used.
+    */
+    model?: string;
+    /**
+    * Thinking level override (e.g. "high", "medium", "low").
+    * M2: Added to align with subagent path's ExecuteOptions.thinkingLevel.
+    * When omitted, agent .md frontmatter thinkingLevel is used (via resolveIdentity/getAgentConfig).
+    */
+    thinkingLevel?: string;
+    /** Scene name passed through to the worker for model-selection hints. */
+    scene?: string;
+    /**
+    * Wall-clock timeout in milliseconds. When > 0, aborts the subprocess
+    * if it runs longer than this, regardless of external signal.
+    * Per-call，归 AgentCall 实体（G-027）。
+    */
+    timeoutMs?: number;
+    /**
+     * 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.
+    */
+    skill?: string;
+    /**
+    * Resolved absolute path to the skill directory or SKILL.md file.
+    * Set by agent-opts-resolver when opts.skill is present.
+    */
+    skillPath?: string;
+    /** Human-readable description for logging and debugging. */
+    description?: string;
+    /**
+    * Agent ref (absolute .md path). Resolved by resolveIdentity via getAgentConfig,
+    * which injects the agent's systemPrompt/model/tools/thinkingLevel. Not handled by
+    * resolveAgentOpts (single-responsibility: agent ref ownership belongs to resolveIdentity,
+    * M2 fix — previously overlapped causing double-injection + model-tier confusion).
+    */
+    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).
+     * pi 边界直出为 ExecuteOptions.appendSystemPrompt（同名同义透传，D6 合流后无中间映射层）。
+     */
+    appendSystemPrompt?: string[];
+    /**
+     * 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。
+    *
+    * 用于 worktree 隔离：传入 worktree 绝对路径，spawn 的 pi 子进程绑定到该目录，
+    * 其内部的 createAgentSession/ResourceLoader/bash 工具都在该目录运行。
+    * undefined 时 spawn 继承 workflow 进程的 cwd（向后兼容）。
+    */
+    cwd?: string;
+    /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
+    fork?: boolean;
+    /**
+     * fork-from 显式分叉源 session 文件（fork-from 断联恢复通道的唯一 lossless 载体）。
+     * 来源 = ExecuteOptions.forkFromSessionFile（host-task-spec 映射时的唯一改名点——
+     * 本形状起与 SDK 协议字段、引擎侧 SpawnRunParams.forkSource 三层同名，降低跨层
+     * 双名漂移面）。区别于 fork:true（主 session 作分叉源）：本字段点名任意已有
+     * session 文件。chat 域唯一写入方 = fork-from action。
+     */
+    forkSource?: string;
+    /**
+     * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
+     * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
+     * engine——环境差异由 frontmatter/全局默认承载）；透传链 worker-script-builder
+     * agent() → execute-agent-call → SAR 路由层。
+     */
+    engine?: string;
+    /** 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 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;
+}
+
+/**
+ * 单次 agent 调用的结果（统一形态）。
+ *
+ * Engine 直接消费 SubprocessAgentRunner 返回值；callCache replay 时 worker
+ * 取 parsedOutput ?? content（见 worker-script-builder.ts 消息处理）。
+ */
+interface AgentResult {
+    /** Raw text output from the agent. */
+    content: string;
+    /**
+    * [D5-③] 失败分诊结构化标签（AgentFailureKind）。产出侧唯一识别点 =
+    * execution/engine/inproc 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）。
+    */
+    parsedOutput?: unknown;
+    /** Token and cost usage accumulated across all assistant turns. */
+    usage?: AgentOutcomeUsage;
+    /** Wall-clock duration in milliseconds. */
+    durationMs?: number;
+    /** True when the pi process exited with code 0. */
+    error?: string;
+    /**
+    * Pi session ID for the subagent process (uuidv7).
+    * Present when pi emits a session header (default in --mode json).
+    * Can be used to locate the session JSONL file for post-run inspection (G-017)。
+    */
+    sessionId?: string;
+    /**
+    * Session JSONL 绝对路径（不含目录的文件名在 subagents 侧 AgentResult.sessionFile）。
+    * 由 mapToWorkflowAgentResult 从 subagents AgentResult 透传——让 workflow 编排层
+    * 继承 subagent 执行管道产出的 session 文件路径，overlay/GUI 可直接定位。
+    * 窗口期内可能 undefined（session 尚未创建成功）。
+    */
+    sessionFile?: string;
+    /**
+    * Absolute path of the git worktree used for filesystem isolation (set when
+    * worktree isolation is active). Injected by executeAndAwait from record.worktreeHandle.path.
+    *
+    * ⚠️ Diagnostic only, may not exist: executeAndAwait's finalizeRecord cleans up the
+    * worktree (git worktree remove --force) before returning, so by the time this field
+    * reaches the caller the directory has typically been deleted. Use it only for log/trace
+    * correlation (e.g. attributing a session jsonl to its worktree origin) — never as a cwd
+    * for a subsequent agent or filesystem operation (would ENOENT).
+    */
+    worktreePath?: string;
+    /** All tool calls collected from JSONL stream (FR-7). */
+    toolCalls?: ToolCallEntry[];
+}
+/**
+ * 执行追踪节点（事件流 D-10 单一来源）。
+ */
+interface ExecutionTraceNode {
+    stepIndex: number;
+    agent: string;
+    task: string;
+    model: string;
+    status: "pending" | "running" | "completed" | "failed";
+    /** Phase name for TUI grouping. Set from explicit opts.phase or global _currentPhase. */
+    phase?: string;
+    startedAt?: string;
+    completedAt?: string;
+    result?: AgentResult;
+    error?: string;
+    /**
+    * Pi session ID (uuidv7) for the subagent process.
+    * Used to locate the session JSONL for post-run inspection.
+    */
+    sessionId?: string;
+    /**
+     * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
+     * 持久化到快照（serializeRun），跨 session 重水合后保留。
+     */
+    sessionFile?: string;
+}
+/**
+ * Trace.update 用的 patch（字段全可选）。
+ *
+ * 不变式：只改单个 node 的 status/result/error/completedAt/sessionId。
+ * callId 不存在时 update 为 no-op（D-10）。
+ */
+interface TracePatch {
+    status?: "pending" | "running" | "completed" | "failed";
+    result?: AgentResult;
+    error?: string;
+    completedAt?: string;
+    sessionId?: string;
+    sessionFile?: string;
+}
+/**
+ * Worker console.* 捕获条目（run 级诊断，仅展示在 TUI widget，不泄漏到 input area）。
+ */
+interface WorkerLogEntry {
+    level: "log" | "warn" | "error" | "info";
+    message: string;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 引擎会话句柄（run 返回、read 入参；[H1 U5/U6] interact 面退役后不再有 interact
+ * 消费方）。
+ *
+ * 契约三条（D1）：不透明（上层不解构——唯一例外是 record 持久化层序列化 data 字段与
+ * read 降级链）、可持久化（data 是纯 JSON，主会话 reload 后 read 仍可用）、自描述
+ * （data 含 engineId + 引擎 session 定位符 + pool key + adapter 版本）。
+ */
+interface EngineHandle {
+    /** 持久化数据。上层不得解构其内部字段（见契约三条）。 */
+    readonly data: EngineHandleData;
+}
+
+/**
+ * subagent text_delta streaming sink。
+ *
+ * background subagent 执行期间，session-runner 的 agentEvent 出口把每个 text_delta
+ * 传到 SubagentStream.onDelta。本模块做 100ms 时间窗合并后，通过 StreamSink.setWidget
+ * 转发到 RPC stdout（经 ctx.ui.setWidget → extension_ui_request 通道）。
+ *
+ * SubagentStream 是一个生命周期对象——内聚 buffer/timer 状态 + onDelta/dispose 方法。
+ * 调用方（subagent-service）创建后只需在 text_delta 时调 onDelta、终态时调 dispose，
+ * 不需要拆散 push/clear 两个函数跨层透传。
+ *
+ * 设计要点：
+ * - leading edge：第一个 delta 立即 flush（前端尽快看到开始）
+ * - trailing edge：后续 delta 追加 buffer，timer 到期后 flush
+ * - 每次 flush 把 buffer 的累积文本 split("\n") 截尾 MAX_WIDGET_LINES 行传给 setWidget
+ * - dispose 清除 widget + 清 timer
+ */
+
+/** UI streaming sink 的最小接口（ctx.ui.setWidget 的 duck-typed 子集）。
+ *
+ * 当前只有一个 adapter（index.ts session_start 包装 ctx.ui.setWidget）。
+ * 保留接口而非裸函数类型，因为 StreamSink 的语义是「UI sink 契约」——
+ * 测试 mock 和未来可能的第二 sink（如写文件）都走此契约。 */
+interface StreamSink {
+    setWidget(key: string, lines: string[] | undefined): void;
+}
+/**
+ * subagent text_delta streaming 生命周期对象。
+ *
+ * 创建后：
+ * - `onDelta(delta)`：session-runner 每次 text_delta 调
+ * - `dispose()`：subagent 终态时调，清除 widget + 清 timer
+ *
+ * buffer/timer 状态全部内聚在此对象，调用方不需要关心合并逻辑。
+ */
+declare class SubagentStream {
+    private readonly widgetKey;
+    private readonly sink;
+    private buffer;
+    private timer;
+    private hasFlushed;
+    private disposed;
+    constructor(recordId: string, sink: StreamSink);
+    /** 接收一个 text_delta 增量。空串静默丢弃（不消耗 leading edge）。 */
+    onDelta(delta: string): void;
+    /** 终态清理：清除 widget + 清 timer（幂等）。 */
+    dispose(): void;
+    private flush;
+}
+
+/**
+ * run 的运行期上下文。任务声明（AgentCallOpts，D6 合流后的单一形状）与运行期句柄
+ * 分离——signal/ctxModel/onComplete 从 ExecuteOptions 移出（设计 §3.3.5 删字段去向），
+ * 因为它们是宿主注入的运行期对象，不属于跨引擎持久化的任务声明。
+ *
+ * 常驻进程友好（D1）：onEvent 回调式（而非迭代器式）+ AbortSignal——引擎内部换常驻
+ * server 实现（未来 driver host）时接口不动。
+ */
+interface RunContext {
+    /** = record.id（bg-N-xxx / run-N）——journal 文件名与池引用计数 key（P2 消费）。 */
+    taskId: string;
+    /** D5 隔离池（宿主分配，设计 §3.3.9；pi 无池化恒 'shared'）。 */
+    poolKey: string;
+    /** abort 分级入口（D1：引擎原生中断 → 公共杀链兜底）。 */
+    signal?: AbortSignal;
+    /** 事件流出口（host 消费后统一落 journal，D6 第②级）。 */
+    onEvent?: (event: AgentEvent) => void;
+    /**
+     * model 解析第三层兜底（现有 D-008 语义不变）——**pi 链路专属兜底**：经
+     * taskSpecToExecuteOptions → resolveModel 第三层消费（PiEngine 直通）。自带
+     * provider 体系与缺省模型的引擎（如 zcode：requested > 引擎缺省常量链）按自身
+     * 默认链解析，不消费本字段（zcode 侧在「ctx 有模型但被忽略」时出声留痕，
+     * zcode-engine.warnIgnoredCtxModel）。
+     */
+    ctxModel?: ModelInfo;
+    /**
+     * text_delta streaming 通道（宿主侧 UI widget）。与 onEvent 平行的 text_delta 出口：
+     * background 路径 onEvent=undefined 但流式仍需送达（双通道互斥设计，见 session-runner
+     * agentEvent 出口注释）。pi 回填期承载 AgentRunner port 的 stream 透传（行为零变化），
+     * 语义上是宿主设施而非引擎专有——未来引擎的 text_delta 同样可走此通道。
+     */
+    stream?: SubagentStream;
+    /**
+     * [P1 pi 回填透传] 调用方已持有的 schema 激活预编码值（AgentCallOpts.schemaEnv 直传
+     * 形态）。生产路径中 resolveAgentOpts 恒耦合产出 schema+schemaEnv（值 = JSON.stringify
+     * (schema)），引擎从 task.schema 派生即可逐字节等值；解耦形态（有 schemaEnv 无
+     * schema）生产不可达、仅见于直构调用，派生无源——本字段是其唯一透交通道。
+     * 引擎在 task.schema 存在时忽略此值（派生优先，设计 §3.3.5 删字段去向）。
+     */
+    schemaEnv?: string;
+    /**
+     * [P4 D9①] 引擎 fallback 留痕（probe 失败路由回默认引擎）。路由层（routing.ts）
+     * 产出，引擎投影到 outcome.engineFallback（zcode 等无 record 通路的引擎以此留痕；
+     * pi 引擎另经 ExecuteOptions 投影进 record）。
+     */
+    engineFallback?: {
+        from: string;
+        reason: string;
+    };
+    /**
+     * [F6] 根 session id（SubagentService.sessionRootId 注入）——pi 引擎 relay 归属键
+     * SESSION_ID 的权威来源（经 wire ctx.sessionRootId → server 还原 → SpawnRunParams
+     * → buildChildEnv）。刻意走 per-run ctx 而非 EngineClient 的进程级 env：客户端按
+     * 引擎缓存为惰性单例，进程级 env 在 pi fork 换 sessionId 后会陈旧；per-run ctx 恒
+     * 新鲜，且与 RECORD_ID 已有的 per-run 形态一致。additive：undefined/null/空串不
+     * 上 wire，zcode 等引擎忽略。
+     */
+    sessionRootId?: string;
+    /**
+     * [Option C 协议化] 权威 subagent session 目录（getSubagentSessionDir(agentDir,
+     * rootCwd) 宿主推导值）——经 wire ctx.sessionDir 送达 pi 引擎组装 `--session-dir`。
+     * 生产注入方 = RemoteEngine（cli 形态引擎的唯一宿主侧适配点，env 同源推导，见
+     * remote-engine buildRunParams）；编排层显式注入（ctx.sessionDir 有值）时优先于
+     * RemoteEngine 自推导。zcode 等不消费 session 目录的引擎忽略本字段。编排层可
+     * 不注入；RemoteEngine 缺省以同源 env 推导值补齐后恒上 wire；[LEGACY] fallback
+     * 仅旧宿主/独立运行引擎形态可达。
+     */
+    sessionDir?: string;
+    /**
+     * [P4 对齐点③] 引擎声明实际隔离池 key（journal 落盘路径权威）。宿主创建 journal
+     * writer 时只能用缺省占位 poolKey（pi 恒 'shared'），非池化稳定的引擎（zcode 按
+     * provider+model 池化）在 prepare 期确定 poolKey 后回调本方法重定向 writer——
+     * 保证 journal 落盘路径与 handle.poolKey 同源（单一权威，不再两边推导）。
+     * 契约：必须在首个事件 emit 之前调用（zcode coarse 事件在终态后合成，天然满足；
+     * 未来流式引擎需在事件出口前调用）。
+     */
+    onPoolResolved?: (poolKey: string) => void;
+    /**
+     * [R4 §3.4 不变量 3] 运行中句柄回填通道：引擎在「session/create 应答到达后」
+     * 立即回调（早于 run resolve——stream 引擎的 run 生命周期远长于会话建立）。
+     * 与 onPoolResolved 分立两个时点：poolKey 在 prepare 期（onPoolResolved，连接
+     * 建立前即可知），sessionRef 在 create 应答后（本回调）。编排层收到后立即回填
+     * record.engineHandle 并落 entry——运行中的 GUI 经 entry 重建 record 即拿到
+     * ①②级读取钥匙，不再等 run resolve 后的终态回填。可选回调：不支持运行中回填
+     * 的引擎（spawn 单轮、终态即回填）不调用，宿主语义不受影响。
+     */
+    onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
+    /**
+     * [U0 D10] 引擎 spawn 的子进程句柄注册钩子（宿主终止链记账）。引擎在 spawn 成功后
+     * 同步回调（与 pi runSpawn 的 spawnedChildren.set 同构时机）；宿主据此把 child 注册进
+     * session-runner 的 spawnedChildren Map（cancel SIGTERM / dispose 收割兜底 / killAll
+     * 全量清理对非 pi 引擎 record 生效）。close/error 后由宿主按句守卫移除。可选：引擎
+     * 内部不 spawn 进程（如未来常驻 driver host 实现）时不调用，宿主记账自然为空。
+     *
+     * 边界声明（R1 D6）：本钩子只用于 per-record 一次性 spawn（一任务一进程模态）。
+     * 引擎持有的常驻进程（跨任务共享，如 app-server 常驻连接）不经本钩子注册、不进
+     * spawnedChildren Map——其生命周期完全归引擎 dispose 管理（防 per-record 重复
+     * SIGTERM / 单任务 abort 误杀共享进程）。
+     */
+    onChildSpawned?: (child: ChildProcess) => void;
+    /**
+     * [W3 v1.x → H1 U6 终态] 会话形态参数（协议 run.params.resume 的 RunContext
+     * 承载位，键已随 U6 键切换从 `chat` 泛化为 `resume`）：
+     *   - recordId：core 预建 record 的关联键（引擎据此上报 childSpawned/childStateChanged
+     *     的 record 键形态与 handle 锚定）——会话形态轮（task.conversation === true）必传；
+     *   - resume：续聊锚点（record.sessionFile 续写原文件；pi 消费
+     *     sessionRef.sessionFile——对照协议化设计前 SpawnResumeOpts.sessionFile 的锚点面）。
+     * 类型权威 = SDK RunResumeParams（remote-engine 直传，结构互证由 implements 关系
+     * 在 typecheck 期承载）。一次性轮不传，wire 上不出现该键。
+     */
+    resume?: {
+        recordId: string;
+        resume?: ResumeAnchor;
+    };
+}
+/**
+ * run 的返回：终态 + 可持久化 handle。
+ *
+ * handle 语义（设计 §3.3.5 run 错误语义三条）：prepare 期错误（credential_missing /
+ * model_not_available / prompt_too_large）在进程创建前 reject、不产生 handle；运行中
+ * 失败不 reject——合成 error outcome + 正常 handle 返回（record 必须收尾）；abort 走
+ * 完杀链后同前（exitCode=null + error 含杀链标记）。
+ */
+interface EngineRunResult {
+    handle: EngineHandle;
+    outcome: AgentOutcome;
+}
+/**
+ * subagent 执行引擎的唯一契约点（D1）。实现方：PiEngine（回填）/ ZcodeEngine（P3）/
+ * 未来各引擎适配器。上层（工具面/workflow 引擎/GUI）只消费中立类型，不感知引擎。
+ *
+ * 贯穿纪律（设计 §3.3.1）：宿主编排——引擎只当单 agent 执行器，六家原生多 agent 机制
+ * 一律禁用不依赖。
+ */
+interface EnginePort {
+    /** 注册表 key（'pi' | 'zcode' | ...）。 */
+    readonly id: string;
+    /** D3（同步无副作用——调用前拒绝的判据）。 */
+    capabilities(): EngineCapabilities;
+    /** D7（factory 初始化 + 版本变化检测触发；opts.force 跳过缓存强探）。 */
+    probe(opts?: {
+        force?: boolean;
+    }): Promise<ProbeReport>;
+    /** D1 主语义：fire-to-completion。[D6 合流] task = AgentCallOpts（单一任务形状，
+     *  原 AgentTaskSpec 已并入——字段裁定见 orchestration/models/types.ts）。会话形态
+     *  续聊轮同走本方法（resume 锚点经 ctx.resume 携带，[H1 U6] interact 面退役）。 */
+    run(task: AgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
+    /** D6 三级降级链：①引擎原生读取 → ②宿主 event journal（P2）→ ③outcome-only。 */
+    read(handle: EngineHandle): Promise<SessionView>;
+    /**
+     * [U7] 可选面：模型可发现性——引擎自带 provider/model 体系时（如 zcode 的 v2 桌面
+     * 登录态），列出当前环境实际可用的模型清单（带凭据校验），供 system prompt 引擎段
+     * 与 GUI 引擎选择器消费。省略/返回 null = 「与主 agent 模型体系一致」（pi 的语义：
+     * system prompt 已有 <available_provider_models> 段，无需引擎再列）。
+     * engine-neutral：未来引擎（AcpEngine 等）实现本方法即自动获得注入与展示，宿主
+     * 侧零改动。
+     */
+    listModels?(): Array<{
+        id: string;
+        name?: string;
+    }> | null;
+    /**
+     * [u-h2 D2-2] 可选面：派发同步期 model 校验（引擎 registry 单源裁决）。实现引擎复用其
+     * prepare 期同一校验函数（zcode: resolveZcodeModelRef——同一函数两处消费，canonicalRef
+     * 归一化与短名缺省 provider 决策不产生双实现漂移）；校验失败同步 throw（编排层包装为
+     * 「引擎与模型不配套」错误，见 engine/model-validation.ts）。
+     *
+     * modelRef undefined = 查询引擎缺省模型（D2-1：主 agent 的 pi id 不透传给非 pi 引擎，
+     * 缺省语义归引擎——zcode 落 ZCODE_FALLBACK_DEFAULT_MODEL）。返回 canonical ref 供
+     * record.model 留痕。[W3 契约变更④] 协议化后 canonicalRef 允许**无斜杠**形态
+     * （引擎原样返回的 ref）——core 侧按 provider=""/id=ref/整串进 name 拆分留痕
+     * （splitEngineModelRef 单一权威），不落 "<ref>/" 畸形。
+     *
+     * 未实现：model 透传，引擎自身 prepare 期校验兜底（现状语义）；pi 不实现（pi 链走
+     * 既有三层解析 + assertCanonicalModelRef 裁决，搬迁是大重构，设计 D2-2 被否②）。
+     */
+    validateModel?(modelRef: string | undefined): {
+        canonicalRef: string;
+    };
+    /**
+     * [R1 D6] 可选停机面：释放引擎持有的常驻资源（如 app-server 常驻进程 / 长连接）。
+     * 幂等契约（§3.4 不变量 4）：重复调用无副作用；dispose 后首个 run 自动重建（与
+     * 「进程死后重建」同一代码路径）。可选成员保持向后兼容——无常驻资源的引擎（pi
+     * 现状 spawn 单轮）不必实现。等待策略（D6①「触发不等待」）：宿主收割入口
+     * （registry disposeEngines → killAllSpawnedChildren）只同步调用拿 Promise 不
+     * await，引擎实现须自行保证同步面（立即 fire close 帧 + 同步 SIGTERM）在返回
+     * Promise 前完成；grace→SIGKILL 升级序列属异步面（promise 段）。
+     */
+    dispose?(): Promise<void>;
+    /**
+     * [u7a D5] 可选面：引擎在途任务只读快照（滚动重启推迟谓词的引擎侧输入——
+     * 权威源：docs/design/crash-forensics-and-watchdog.md §3.3 D5「推迟判定源 =
+     * relay ∪ 引擎池在途 ∪ pi 侧 extension 聚合上报」）。同步纯读、无副作用。
+     *
+     * 返回 null = 引擎不提供快照；成员缺席（undefined，pi 引擎不实现）= 无引擎侧
+     * 在途面——pi 形态的在途由 subagent-workflow extension 聚合上报覆盖（EnginePort
+     * 之外的第 4 通道，两通道互不替代）。可选成员保持向后兼容（port.ts 既有扩展
+     * 先例：listModels / validateModel / dispose 全为可选成员）。
+     *
+     * zcode 实现语义（显式裁决）：在途 = activeSessions 非空——poolKey 'shared' 的
+     * app-server 空闲常驻进程恒活，**禁止按进程存在判定**（会恒真、推迟常态化）。
+     */
+    inFlightSnapshot?(): {
+        inFlight: number;
+    } | null;
+}
+
+/** 引擎工厂：惰性创建引擎实例（getEngine 首次取用时执行）。 */
+type EngineFactory = () => EnginePort;
+/**
+ * 引擎包 manifest 注册期快照（session_start 扫描所得，非握手缓存——设计 §3.3「同步
+ * 成员清单」单一同步源原则）。descriptor 携带，cli 形态 port（RemoteEngine）的同步
+ * 成员（capabilities/listModels/validateModel）直读本快照。
+ *
+ * 与 client/remote-engine.ts 的 RemoteEngineManifestSnapshot 是结构闭包（后者多出
+ * core 中立类型包装；漂移由 protocol-closure 同族结构互证断言守卫）。
+ */
+interface EngineManifestSnapshot {
+    /** manifest `capabilities`（同步能力位权威，注册期读，无缓存）。 */
+    capabilities: EngineCapabilities;
+    /**
+     * manifest `modelCatalog` 三态（W4 §2.4：缺省 = 不注入保持 undefined；null 合法等价
+     * 省略；`models: []` 仅作者显式声明）。解析器不得把省略填成 `[]`——否则「无枚举面」
+     * 语义不可达。
+     */
+    modelCatalog?: {
+        dynamic: boolean;
+        models: ModelCatalogEntry[];
+    } | null;
+    /** manifest `displayName`（可选，缺省 = id；D4 缺省引擎回落序的排序键）。 */
+    displayName?: string;
+}
+/** cli 形态 descriptor（目标形态）：引擎 CLI 启动参数 + manifest 快照 + port 装配器。 */
+interface CliEngineDescriptor {
+    kind: "cli";
+    /** 引擎 CLI 命令（发现器解析后的绝对路径/可执行名；不依赖 PATH）。 */
+    command: string;
+    /** 引擎 CLI 参数（不含 command 本身）。 */
+    args: readonly string[];
+    /** manifest `capabilities`（同步能力位权威——gate 同步消费，无缓存）。 */
+    capabilities: EngineCapabilities;
+    /**
+     * cli 形态 EnginePort 实例装配器（core 侧接线通道，非 manifest 面）。生产 = W4
+     * 发现器装载 descriptor 时装配（W2 `RemoteEngine` + `EngineClient` + 宿主侧参数
+     * dataDir/hostKind/engineConfig 等——registry 不越权猜宿主形态）。必须构造同步、
+     * 不 throw（§3.5.3 代理形态：缺包/坏包的失败推迟到首次协议调用）。
+     */
+    portFactory: EngineFactory;
+    /** manifest 快照余项（modelCatalog/displayName；capabilities 已提升为直读字段）。 */
+    manifest?: Omit<EngineManifestSnapshot, "capabilities">;
+}
+/**
+ * 缺省引擎 id（D4 重定义：**配置的缺省引擎 id**——config defaultEngine 未配置时的
+ * 归一名，不再表达「内置 pi 永久兜底」）。配置值不在已发现清单 → warn + 回落第一个
+ * 可用引擎（manifest displayName 稳定序，D4）；全不可用 → 派发期 engine_not_found
+ * （「未发现任何引擎包」+ 安装指引）。
+ */
+declare const DEFAULT_ENGINE_ID = "pi";
+/**
+ * defaultEngine 缺省归一（单一权威源）：空白 / undefined 归一到缺省引擎（'pi'）。
+ * 引擎感知检测 diff 与状态段渲染必须对同一读取结果给出同一引擎 id——若两处各自
+ * 内联归一，一致性只靠注释人工耦合，漂移即两处说谎；故收敛到本函数供各处调用。
+ * sanitize 保证透传值非空，但可能带首尾空格，故 trim 后再判。
+ */
+declare function normalizeEngineId(engine: string | undefined): string;
+
+/** 单个引擎包的检查产物。 */
+type PackageInspection = {
+    status: "ok";
+    entry: DiscoveredEngine;
+} | {
+    status: "skip";
+    reason: string;
+} | {
+    status: "unusable";
+    id: string | undefined;
+    reason: string;
+};
+/** 发现成功的引擎条目（装载序；同 id 后者覆盖前者）。 */
+interface DiscoveredEngine {
+    id: string;
+    /** 发现源标签（env 名 / 宿主根 source / node-modules / config.json）。 */
+    source: string;
+    /** L3 显式 config（initialize.engineConfig 透传；L1/L2 manifest 发现无此项）。 */
+    engineConfig?: Record<string, string>;
+    descriptor: CliEngineDescriptor;
+}
+/**
+ * 检查单个候选包目录（读 package.json → manifest 字段级解析 → bin 可执行验证）。
+ * 三态：ok（装载）/ skip（必需字段缺失/不可解析——warn 跳过该包）/ unusable
+ * （protocol 不兼容、bin 不可执行——标记不可用，不进清单）。
+ */
+declare function inspectEnginePackage(pkgDir: string, source: string, hostKind: string, env: NodeJS.ProcessEnv): PackageInspection;
+
+/** L1 引擎发现根 env（设计 §3.4；值形态 = path.delimiter 分隔的绝对路径列表）。 */
+declare const ENGINE_ROOTS_ENV = "XYZ_AGENT_ENGINE_ROOTS";
+/** L1 env 根解析：path.delimiter 分隔；空段跳过；非绝对路径丢弃 + warn；去重（大小写敏感）。 */
+declare function parseEngineRootsEnv(env: NodeJS.ProcessEnv): string[];
+/**
+ * L2 根推导：宿主进程入口（process.argv[1]）所在目录逐级上溯的 node_modules——与
+ * createRequire(<宿主入口>) 的 require.resolve 候选目录链同构（「宿主 node_modules
+ * require.resolve」的扫描化：零枚举发现要求扫目录而非 resolve 具体包名）。打包态
+ * （staged 扩展 / Bun standalone 无 node_modules 结构）与 zsw vendor 态自然为空——
+ * 规格明确两态 L2 无效。argv[1] 不可得（嵌入式 / worker）→ L2 缺席。
+ */
+declare function deriveNodeModuleRoots(argvEntry?: string | undefined): string[];
+
+/** 日志级别。级别集合对齐 pi-extension-logger（其 LogLevel 为包内部类型、含 info 四值；实例 API 仅 debug/warn/error 三方法，core facade 据此收窄为三值）。 */
+type LogLevel = "debug" | "warn" | "error";
+/** core logger 接口。与 pi-extension-logger 的 ExtensionLogger 结构兼容——
+ *  u0-log 批次替换是纯 import 源替换，调用面（方法名/参数序）逐文件等价。 */
+interface CoreLogger {
+    debug(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    error(msg: string, data?: unknown): void;
+}
+declare function getLogger(component: string): CoreLogger;
+
+/** 发现根条目：dir 为扫描根路径；source 是宿主提供的语义标签（遮蔽报告透传用）。
+ *  source 不枚举封闭集——core 只透传不解释（宿主如 pi 壳用 user-pi/npm/npm-dev）。 */
+interface DiscoveryRoot {
+    dir: string;
+    source: string;
+}
+interface HostServices {
+    /** 数据根目录：引擎隔离池 / journal / record 派生存放的锚点。
+     *  pi 壳返回 getAgentDir()（独立 pi 用户 journal 不漂目录）；zsw 壳返回 zsw 数据根。 */
+    dataRoot(): string;
+    /** 结构化日志：对齐现 getLogger 调用面（level/component/message/data）。缺省 sink 按级分化：
+     *  warn/error 走 console、debug no-op（对齐 pi-extension-logger 语义，见 NULL_HOST.log）。 */
+    log(level: LogLevel, component: string, message: string, data?: unknown): void;
+    /** agent/skill/workflow/引擎包 资源发现根（可选端口，缺席 = 调用方降级）。宿主只提供根列表
+     *  （按优先级低→高）；扫描 / 同名遮蔽（last-writer-wins）/ 遮蔽报告语义归 core 统一。
+     *
+     *  engines kind（W4，设计 §3.4 L1 第二通道）：引擎包发现根——dir 下一级（及 org 分组
+     *  二级）子项 = 候选引擎包目录，命中 package.json `xyz-agent.subagentEngine` manifest
+     *  即发现。打包态主通道是 env `XYZ_AGENT_ENGINE_ROOTS`（W9 注入），此端口承载宿主
+     *  自身模块域（如 pi 宿主包 node_modules 的引擎包 dependencies 安装位）。 */
+    discoveryRoots?(): {
+        agents?: DiscoveryRoot[];
+        skills?: DiscoveryRoot[];
+        workflows?: DiscoveryRoot[];
+        engines?: DiscoveryRoot[];
+    };
+}
+/** core 缺省数据根（~/.subagent-core，homedir 推导——禁止写死绝对路径，排查规则）。
+ *  供无自有数据根的轻宿主显式采用；core 自身不静默兜底到该值。 */
+declare const DEFAULT_DATA_ROOT: string;
+declare function configureCore(host: HostServices): void;
+declare function getHostServices(): HostServices;
+
+/** 扫描结果（诊断面：skip/unusable 逐包留痕原因，对应 A12 负面场景）。 */
+interface DiscoveryScanResult {
+    discovered: DiscoveredEngine[];
+    skipped: Array<{
+        pkgDir: string;
+        reason: string;
+    }>;
+    unusable: Array<{
+        pkgDir: string;
+        id: string | undefined;
+        reason: string;
+    }>;
+}
+interface DiscoverEnginesOptions {
+    /** 宿主种类（EngineClient pidfile 实例维度命名段：pi 壳 'pi'、runtime 'runtime'）。 */
+    hostKind: string;
+    /** L3 显式配置目录（<dir>/subagents/config.json 的 engines 段）。缺省 = 无 L3。 */
+    agentDir?: string;
+    /** 引擎数据根（EngineClient dataDir；缺省 portFactory 执行期 getEngineDataDir 解析）。 */
+    dataDir?: string;
+    /** env 覆盖（L1 根读取；缺省 process.env——测试注入隔离宿主 env）。 */
+    env?: NodeJS.ProcessEnv;
+    /** L2 覆盖（测试注入；缺省 = 宿主入口上溯 node_modules 链）。 */
+    nodeModuleRoots?: string[];
+    /** 附加发现根（调用方/测试追加的 L1 根，语义同 HostServices.engines）。 */
+    extraRoots?: DiscoveryRoot[];
+}
+/** 纯扫描（不装载注册表）。装载序 = L1 env → L1 宿主/附加根 → L2 → L3（后者覆盖前者）。 */
+declare function scanEngines(opts: DiscoverEnginesOptions): DiscoveryScanResult;
+/**
+ * 扫描 + 装载：descriptor 经 registerEngineDescriptor 进注册表（幂等覆盖——重复扫描
+ * 安全）。装载覆盖既有注册（含过渡期 inproc pi/zcode——auto 模式下 cli descriptor
+ * 胜出即设计 D3 语义）时 debug 留痕。
+ */
+declare function discoverAndRegisterEngines(opts: DiscoverEnginesOptions): DiscoveryScanResult;
+/**
+ * 历史发现装载的引擎 id 快照（投影源计算消费面，见 engine-discovery.ts）。
+ */
+declare function loadedDiscoveryIds(): string[];
+/**
+ * hasEngine 的补扫面（§3.4 发现时机：快照未命中触发一次同步补扫，只读 manifest
+ * 不握手）。消费方 = agent 解析期/路由期的存在性校验接线（宿主侧注入 hasEngineFn
+ * 时用本函数替代裸 hasEngine）——「装了包 → 下次解析即可用」。
+ */
+declare function ensureEngineDiscovered(id: string, opts: DiscoverEnginesOptions): boolean;
+
+export { type AgentConfig as A, parseEngineRootsEnv as B, type CoreLogger as C, type DiscoverEnginesOptions as D, type EnginePort as E, scanEngines as F, type HostServices as H, type LogLevel as L, type ModelInfo as M, type PackageInspection as P, type ResolvedModel as R, SubagentStream as S, type TracePatch as T, type WorkerLogEntry as W, type ModelRegistryLike as a, type AgentResult as b, type StreamSink as c, type AgentCallOpts as d, type ExecutionTraceNode as e, type RunStatus as f, type DoneReason as g, type DiscoveryRoot as h, DEFAULT_DATA_ROOT as i, DEFAULT_ENGINE_ID as j, type EngineHandle as k, type EngineRunResult as l, type RunContext as m, SLUG_MAX_LENGTH as n, configureCore as o, getHostServices as p, getLogger as q, normalizeEngineId as r, type DiscoveredEngine as s, type DiscoveryScanResult as t, ENGINE_ROOTS_ENV as u, deriveNodeModuleRoots as v, discoverAndRegisterEngines as w, ensureEngineDiscovered as x, inspectEnginePackage as y, loadedDiscoveryIds as z };