@zhushanwen/subagent-engine-sdk 0.7.0 → 0.8.0

package/dist/error-codes-C3oVToMr.d.cts

@@ -0,0 +1,311 @@
+import { A as AgentEvent, d as EngineCapabilities, M as ModelCatalogEntry, b as AgentCallOpts, e as ResumeAnchor, E as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from './contract-types-DqOD58r-.cjs';
+
+/** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
+interface ProtocolError {
+    /** 错误码（error-codes.ts 词表 + 其余 engine_* 引擎自报透传）。 */
+    code: string;
+    /** 人类可读详情。 */
+    message: string;
+    /** 恢复指引：指向具体下一步（命令 / 配置路径 / 升级动作），非安慰性文案。 */
+    recovery: string;
+    /** 结构化附参（如 engine_protocol_mismatch 的双方版本）。 */
+    data?: Record<string, unknown>;
+}
+interface RequestFrame {
+    id: number;
+    method: string;
+    params: unknown;
+}
+interface SuccessResponseFrame {
+    id: number | string;
+    result: unknown;
+}
+interface ErrorResponseFrame {
+    id: number | string;
+    error: ProtocolError;
+}
+type ResponseFrame = SuccessResponseFrame | ErrorResponseFrame;
+/** event 通知载荷：runId 关联在途 run；seq 单调递增（基线①结构等价断言对象）。 */
+interface EventNotificationParams {
+    runId: string;
+    seq: number;
+    event: AgentEvent;
+}
+interface NotificationFrame {
+    method: "event";
+    params: EventNotificationParams;
+}
+interface ReverseRequestFrame {
+    id: string;
+    method: string;
+    params: unknown;
+}
+/** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
+type ReverseResponseResult = 
+/** 数据面类：处理确认。 */
+{
+    ok: true;
+}
+/** 人机交互类（askUser）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+ | {
+    ack: true;
+}
+/** 未实现或宿主未知的通道（宽容语义③：由 askUser 语境泛化到全通道——宿主对未知 host/* 通道回 unsupported，引擎自行降级）。 */
+ | {
+    unsupported: true;
+};
+/** ① 请求：有数字 id + method + params，且无 result/error（与②应答区分）。 */
+declare function isRequestFrame(frame: unknown): frame is RequestFrame;
+/** ② 应答：有 id（number|string）且 result/error 二选一。 */
+declare function isResponseFrame(frame: unknown): frame is ResponseFrame;
+/** ③ 通知：无 id，method === "event"，params 含 runId/seq/event。 */
+declare function isNotificationFrame(frame: unknown): frame is NotificationFrame;
+/** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
+declare function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame;
+
+/**
+ * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
+ * [H1] `interact` 成员已随 chat-run 统一退役（docs/architecture/subagent-chat-run-unification.md
+ * §3.3 D5：续聊轮统一为「新 run + resume 锚点」，U5 删除）。
+ */
+type ProtocolMethod = "initialize" | "probe" | "run" | "cancel" | "read" | "listModels" | "validateModel" | "dispose" | "ping";
+/** 方法名全集（运行时顺序化枚举；与 ProtocolMethod 的同源关系由测试断言）。 */
+declare const PROTOCOL_METHODS: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
+/**
+ * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
+ */
+interface RunContextParams {
+    /** 任务工作目录（worktree 隔离时 = worktree 路径）。缺省不上 wire——引擎侧
+     *  回退自身进程 cwd（spawn 继承语义）。 */
+    cwd?: string;
+    /** 请求模型 ref（未传 = 引擎缺省模型）。 */
+    model?: string;
+    /** 上下文模型 ref（与 run 模型分离的 ctx 模型）。 */
+    ctxModel?: string;
+    /** 事件粒度请求（引擎按 capabilities.eventGranularity 实际能力执行）。 */
+    streamMode?: "stream" | "coarse";
+    /**
+     * [F6] 根 session id——pi 引擎 relay 归属键 SESSION_ID 的权威来源（生产三来源
+     * ①本字段 ②宿主 env ③根进程 env 中，宿主派发恒走①）。additive 可选：旧引擎忽略
+     * 未知字段，undefined 不上 wire。
+     */
+    sessionRootId?: string;
+    /**
+     * [Option C 协议化] 权威 subagent session 目录——宿主以 getSubagentSessionDir
+     * (agentDir, rootCwd) 推导（宿主单一权威，Fix Gate B S6：引擎本地推导与宿主布局
+     * 三处不等价 → 跨重启续聊链断裂）。引擎用它组装 pi `--session-dir`，不自推导；
+     * 缺省（独立运行/测试）走引擎内 [LEGACY] fallback。additive 可选：旧引擎忽略
+     * 未知字段，undefined 不上 wire。
+     */
+    sessionDir?: string;
+    /**
+     * [D2 扩展加载显式化] 孙进程显式加载的扩展路径集（pi 引擎侧逐项拼
+     * `--extension` argv）。per-host 常量而非 per-run 变量，故落 ctx。宿主侧来源
+     * 双形态：taiji 宿主 = extension-service 下发的白名单收窄集（经 pi-host 注入）；
+     * 独立 pi = subagent-workflow 自身 optional peerDep 解析回退。additive 可选：
+     * 旧引擎忽略未知字段，undefined 不上 wire。
+     */
+    extensionPaths?: string[];
+    /**
+     * [D4 record 身份信封] 本次 run 的 **record 级身份**（引擎把它整封写进任务子进程的
+     * 身份 env；见 SDK `identity-env.ts` 的 `SUBAGENT_IDENTITY_ENV`）。
+     *
+     * 为什么是信封而不是三个平铺键：`slug` 与 task 侧 `description` 是同一语义的两种写法，
+     * 平铺进 ctx 会撞 wire 层绝对条款「同一语义不得 task/ctx 双写」（`wire-field-locks.test.ts`
+     * 的 `keyof AgentCallOpts & keyof RunContextParams = never`）；信封把「record 身份」立成
+     * 一个独立概念（与「怎么执行这次调用」的 task 面正交），也给后续身份字段一个归处。
+     *
+     * 字段语义（缺省即不写该键，读者按各自回落语义工作）：
+     *   - `slug`：record 短标签（宿主侧由 record 的 description 派生的展示标签）；
+     *   - `startedAt`：record 起始时刻（epoch ms；宿主派发时刻即权威值，引擎不得改写）；
+     *   - `mode`：执行形态（`background` / `chat`，record 级事实）。
+     *
+     * additive 可选：旧引擎忽略未知字段，undefined 不上 wire。
+     */
+    identity?: {
+        slug?: string;
+        startedAt?: number;
+        mode?: string;
+    };
+}
+/**
+ * [H1] run 的 resume 会话形态参数（设计 docs/architecture/subagent-chat-run-unification.md
+ * §3.3 D3 + §5 U1/U6 行）：原 RunChatParams（v1.x chat 会话形态参数）的泛化改名终态，
+ * 载荷同形（recordId + resume 锚点，ResumeAnchor 不变），仅键名从「chat 会话形态」
+ * 泛化为「resume 续聊」。
+ *   - recordId：core 预建 record 的关联键（引擎据此回填 handle.sessionRef、上报
+ *     host/childSpawned|childStateChanged 的 record 键形态）；
+ *   - resume：冷续锚点（重开已 idle 的 session 续聊；缺省 = 新 session）。对照
+ *     core SpawnResumeOpts——sessionFile 经 anchor.sessionRef 携带，model/
+ *     thinkingLevel 防漂移覆盖走既有 task/ctx 字段，不双写。
+ * [H1 U6 已切换] `chat` 键整体退役（读写端同批切换，无「写新读旧」窗口），本键为
+ * 唯一会话形态参数。载荷 schema 权威 = runSessionParamsSchema（schema.ts）。
+ */
+interface RunResumeParams {
+    recordId: string;
+    resume?: ResumeAnchor;
+}
+/** initialize 参数（engineConfig = L3 显式配置 engines.<id>.config 透传，不放凭据）。 */
+interface InitializeParams {
+    protocolVersion: number;
+    hostInfo: {
+        name: string;
+        version: string;
+        dataRoot: string;
+    };
+    engineConfig: Record<string, string>;
+}
+/** initialize 应答（仅诊断面：capabilities/models 与 manifest 不一致 → warn，不参与判据）。 */
+interface InitializeResult {
+    protocolVersion: number;
+    engineId: string;
+    engineVersion: string;
+    adapterVersion: string;
+    capabilities: EngineCapabilities;
+    /** 模型目录（诊断面；省略/null = 无枚举面语义）。 */
+    models?: ModelCatalogEntry[] | null;
+}
+interface ProbeParams {
+    force?: boolean;
+}
+interface RunParams {
+    runId: string;
+    task: AgentCallOpts;
+    ctx: RunContextParams;
+    /**
+     * [H1 U6 终态] resume 续聊参数（唯一会话形态键；原 v1.x `chat` 键已随键切换退役，
+     * 见 RunResumeParams）。缺省 = 一次性任务形态（向后兼容：旧引擎忽略未知字段，
+     * 帧级 schema params 不做深校验）。additive 可选：undefined 不上 wire。
+     */
+    resume?: RunResumeParams;
+}
+/** run 终态应答（期间事件经 event 通知；长运行方法，应答到达即终态）。 */
+interface RunResult {
+    handle: EngineHandleData;
+    outcome: AgentOutcome;
+}
+interface CancelParams {
+    runId: string;
+    reason: string;
+}
+/**
+ * cancel 应答（受理确认）。终态本体由该 run 的 run 终态应答承载（abort 合成终态经
+ * event/终态应答到达）；引擎须 CANCEL_SETTLE_GRACE_MS（3s）内收敛，超时 core 走杀链。
+ */
+interface CancelResult {
+    ok: true;
+}
+interface ReadParams {
+    handle: EngineHandleData;
+    /** 数据根（core 每次 read 都发送——remote-engine 构造注入的数据目录）。两引擎
+     *  server 现行均不消费该字段：定位走 handle.data（recordPath 等）或引擎自身
+     *  数据目录。保留为协议帧字段（历史：存量池时代引擎自算池/journal 相对 dbPath
+     *  的定位需要它）。 */
+    dataDir: string;
+}
+interface ListModelsParams {
+    /** 占位空参（帧形状一致性；未来诊断参数在此扩展）。 */
+    _placeholder?: never;
+}
+interface ListModelsResult {
+    /** 数组 = 有枚举面；null = 无枚举面（buildCoreAlignedHint 语义，与 manifest 省略对齐）。 */
+    models: ModelCatalogEntry[] | null;
+}
+interface ValidateModelParams {
+    modelRef?: string;
+}
+interface ValidateModelResult {
+    canonicalRef: string;
+}
+interface DisposeParams {
+    /** 占位空参（帧形状一致性；幂等语义）。 */
+    _placeholder?: never;
+}
+interface DisposeResult {
+    ok: true;
+}
+interface PingParams {
+    /** 占位空参（帧形状一致性）。 */
+    _placeholder?: never;
+}
+interface PingResult {
+    pong: true;
+}
+/** 方法 → params 类型映射。 */
+interface ProtocolParamsMap {
+    initialize: InitializeParams;
+    probe: ProbeParams;
+    run: RunParams;
+    cancel: CancelParams;
+    read: ReadParams;
+    listModels: ListModelsParams;
+    validateModel: ValidateModelParams;
+    dispose: DisposeParams;
+    ping: PingParams;
+}
+/** 方法 → result 类型映射。 */
+interface ProtocolResultMap {
+    initialize: InitializeResult;
+    probe: ProbeReport;
+    run: RunResult;
+    cancel: CancelResult;
+    read: SessionView;
+    listModels: ListModelsResult;
+    validateModel: ValidateModelResult;
+    dispose: DisposeResult;
+    ping: PingResult;
+}
+
+/** 协议核心错误码（引擎 error 帧 + core 同步拦截共用的固定词表）。 */
+declare const ENGINE_PROTOCOL_ERROR_CODES: readonly ["engine_not_found", "engine_protocol_mismatch", "engine_capability_unsupported", "engine_capability_mismatch", "engine_model_unknown", "engine_model_mismatch", "engine_handshake_timeout", "engine_crashed", "engine_probe_failed"];
+type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
+/** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
+declare function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode;
+/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+declare const ENGINE_ERROR_CODE_PREFIX = "engine_";
+declare function isEngineErrorPassthroughCode(value: string): boolean;
+
+/**
+ * 结构化引擎错误（message 恒为 `<code>: <detail>` 前缀格式——AgentOutcome.error 与
+ * 协议 error 帧共用的错误码前缀约定）；recovery 指向恢复动作。
+ * toStructured() 产出即协议 ProtocolError 形态（error 帧载荷直用）。
+ */
+declare class EngineSdkError extends Error {
+    readonly code: string;
+    readonly recovery: string;
+    readonly data?: Record<string, unknown>;
+    constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>);
+    /** 协议 error 帧载荷投影。 */
+    toStructured(): ProtocolError;
+}
+declare function engineProtocolMismatchError(engineVersion: number): EngineSdkError;
+/**
+ * 引擎 conversation 位拒绝的具名错误（[modeless 波2] 语义：无 resume 续聊通道的
+ * 引擎，message 续聊资格被拒——manifest conversation 能力轴消费；[modeless 波5
+ * 收尾] core capability-gate 的显式参数分支随派发参数删除退役，本构造器消费方 =
+ * 引擎侧 resume gate（assertChatConversationSupported）与 message 资格门）。
+ * 文案契约：错误码 engine_capability_unsupported + 「换引擎续聊 / 修 manifest /
+ * 升级引擎包」恢复指引，两侧一致防漂移。
+ */
+declare function engineConversationUnsupportedError(engineId: string): EngineSdkError;
+/**
+ * resume 会话形态（run.params.resume——唯一会话形态键）派发前的同步 gate：
+ * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError
+ * ——进程/record 创建前同步拒（A6 方向防御：manifest/实装漂移时引擎侧自拒，
+ * 与 core capability-gate 同一能力位，防两侧判据漂移）。[modeless 波2] 协议
+ * task 的 conversation 键已删，本 gate 只对 resume 形态键生效。
+ */
+declare function assertChatConversationSupported(engineId: string, capabilities: Pick<EngineCapabilities, "conversation">): void;
+/** stdout 尾部回显上限（engine_timeout / engine_run_failed 的错误规格载体系数）。 */
+declare const STDOUT_TAIL_ECHO_CHARS = 2000;
+/** engine_timeout 的恢复指引（kill-chain 超时杀链收尾文案）。 */
+declare const ENGINE_TIMEOUT_RECOVERY: string;
+/**
+ * engine_timeout 的 outcome.error 文案：含 stdout 尾部 2000 字 + 恢复指引
+ * （kill-chain synthesizeTimeoutOutcome 消费；与 core errors.ts engineTimeoutDetail 逐字等价）。
+ */
+declare function engineTimeoutDetail(stdoutTail: string): string;
+/** schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）。 */
+declare function schemaEmulationFailedDetail(error: string, tail: string): string;
+
+export { type ValidateModelResult as A, assertChatConversationSupported as B, type CancelParams as C, type DisposeParams as D, EngineSdkError as E, engineConversationUnsupportedError as F, engineProtocolMismatchError as G, engineTimeoutDetail as H, type InitializeResult as I, isEngineErrorPassthroughCode as J, isEngineProtocolErrorCode as K, type ListModelsParams as L, isNotificationFrame as M, type NotificationFrame as N, isRequestFrame as O, PROTOCOL_METHODS as P, isResponseFrame as Q, type RunContextParams as R, STDOUT_TAIL_ECHO_CHARS as S, isReverseRequestFrame as T, schemaEmulationFailedDetail as U, type ValidateModelParams as V, type InitializeParams as a, type CancelResult as b, type DisposeResult as c, ENGINE_ERROR_CODE_PREFIX as d, ENGINE_PROTOCOL_ERROR_CODES as e, ENGINE_TIMEOUT_RECOVERY as f, type EngineProtocolErrorCode as g, type ErrorResponseFrame as h, type EventNotificationParams as i, type ListModelsResult as j, type PingParams as k, type PingResult as l, type ProbeParams as m, type ProtocolError as n, type ProtocolMethod as o, type ProtocolParamsMap as p, type ProtocolResultMap as q, type ReadParams as r, type RequestFrame as s, type ResponseFrame as t, type ReverseRequestFrame as u, type ReverseResponseResult as v, type RunParams as w, type RunResult as x, type RunResumeParams as y, type SuccessResponseFrame as z };

package/dist/error-codes-CiDwaODz.d.ts

@@ -0,0 +1,311 @@
+import { A as AgentEvent, d as EngineCapabilities, M as ModelCatalogEntry, b as AgentCallOpts, e as ResumeAnchor, E as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from './contract-types-DqOD58r-.js';
+
+/** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
+interface ProtocolError {
+    /** 错误码（error-codes.ts 词表 + 其余 engine_* 引擎自报透传）。 */
+    code: string;
+    /** 人类可读详情。 */
+    message: string;
+    /** 恢复指引：指向具体下一步（命令 / 配置路径 / 升级动作），非安慰性文案。 */
+    recovery: string;
+    /** 结构化附参（如 engine_protocol_mismatch 的双方版本）。 */
+    data?: Record<string, unknown>;
+}
+interface RequestFrame {
+    id: number;
+    method: string;
+    params: unknown;
+}
+interface SuccessResponseFrame {
+    id: number | string;
+    result: unknown;
+}
+interface ErrorResponseFrame {
+    id: number | string;
+    error: ProtocolError;
+}
+type ResponseFrame = SuccessResponseFrame | ErrorResponseFrame;
+/** event 通知载荷：runId 关联在途 run；seq 单调递增（基线①结构等价断言对象）。 */
+interface EventNotificationParams {
+    runId: string;
+    seq: number;
+    event: AgentEvent;
+}
+interface NotificationFrame {
+    method: "event";
+    params: EventNotificationParams;
+}
+interface ReverseRequestFrame {
+    id: string;
+    method: string;
+    params: unknown;
+}
+/** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
+type ReverseResponseResult = 
+/** 数据面类：处理确认。 */
+{
+    ok: true;
+}
+/** 人机交互类（askUser）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+ | {
+    ack: true;
+}
+/** 未实现或宿主未知的通道（宽容语义③：由 askUser 语境泛化到全通道——宿主对未知 host/* 通道回 unsupported，引擎自行降级）。 */
+ | {
+    unsupported: true;
+};
+/** ① 请求：有数字 id + method + params，且无 result/error（与②应答区分）。 */
+declare function isRequestFrame(frame: unknown): frame is RequestFrame;
+/** ② 应答：有 id（number|string）且 result/error 二选一。 */
+declare function isResponseFrame(frame: unknown): frame is ResponseFrame;
+/** ③ 通知：无 id，method === "event"，params 含 runId/seq/event。 */
+declare function isNotificationFrame(frame: unknown): frame is NotificationFrame;
+/** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
+declare function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame;
+
+/**
+ * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
+ * [H1] `interact` 成员已随 chat-run 统一退役（docs/architecture/subagent-chat-run-unification.md
+ * §3.3 D5：续聊轮统一为「新 run + resume 锚点」，U5 删除）。
+ */
+type ProtocolMethod = "initialize" | "probe" | "run" | "cancel" | "read" | "listModels" | "validateModel" | "dispose" | "ping";
+/** 方法名全集（运行时顺序化枚举；与 ProtocolMethod 的同源关系由测试断言）。 */
+declare const PROTOCOL_METHODS: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
+/**
+ * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
+ */
+interface RunContextParams {
+    /** 任务工作目录（worktree 隔离时 = worktree 路径）。缺省不上 wire——引擎侧
+     *  回退自身进程 cwd（spawn 继承语义）。 */
+    cwd?: string;
+    /** 请求模型 ref（未传 = 引擎缺省模型）。 */
+    model?: string;
+    /** 上下文模型 ref（与 run 模型分离的 ctx 模型）。 */
+    ctxModel?: string;
+    /** 事件粒度请求（引擎按 capabilities.eventGranularity 实际能力执行）。 */
+    streamMode?: "stream" | "coarse";
+    /**
+     * [F6] 根 session id——pi 引擎 relay 归属键 SESSION_ID 的权威来源（生产三来源
+     * ①本字段 ②宿主 env ③根进程 env 中，宿主派发恒走①）。additive 可选：旧引擎忽略
+     * 未知字段，undefined 不上 wire。
+     */
+    sessionRootId?: string;
+    /**
+     * [Option C 协议化] 权威 subagent session 目录——宿主以 getSubagentSessionDir
+     * (agentDir, rootCwd) 推导（宿主单一权威，Fix Gate B S6：引擎本地推导与宿主布局
+     * 三处不等价 → 跨重启续聊链断裂）。引擎用它组装 pi `--session-dir`，不自推导；
+     * 缺省（独立运行/测试）走引擎内 [LEGACY] fallback。additive 可选：旧引擎忽略
+     * 未知字段，undefined 不上 wire。
+     */
+    sessionDir?: string;
+    /**
+     * [D2 扩展加载显式化] 孙进程显式加载的扩展路径集（pi 引擎侧逐项拼
+     * `--extension` argv）。per-host 常量而非 per-run 变量，故落 ctx。宿主侧来源
+     * 双形态：taiji 宿主 = extension-service 下发的白名单收窄集（经 pi-host 注入）；
+     * 独立 pi = subagent-workflow 自身 optional peerDep 解析回退。additive 可选：
+     * 旧引擎忽略未知字段，undefined 不上 wire。
+     */
+    extensionPaths?: string[];
+    /**
+     * [D4 record 身份信封] 本次 run 的 **record 级身份**（引擎把它整封写进任务子进程的
+     * 身份 env；见 SDK `identity-env.ts` 的 `SUBAGENT_IDENTITY_ENV`）。
+     *
+     * 为什么是信封而不是三个平铺键：`slug` 与 task 侧 `description` 是同一语义的两种写法，
+     * 平铺进 ctx 会撞 wire 层绝对条款「同一语义不得 task/ctx 双写」（`wire-field-locks.test.ts`
+     * 的 `keyof AgentCallOpts & keyof RunContextParams = never`）；信封把「record 身份」立成
+     * 一个独立概念（与「怎么执行这次调用」的 task 面正交），也给后续身份字段一个归处。
+     *
+     * 字段语义（缺省即不写该键，读者按各自回落语义工作）：
+     *   - `slug`：record 短标签（宿主侧由 record 的 description 派生的展示标签）；
+     *   - `startedAt`：record 起始时刻（epoch ms；宿主派发时刻即权威值，引擎不得改写）；
+     *   - `mode`：执行形态（`background` / `chat`，record 级事实）。
+     *
+     * additive 可选：旧引擎忽略未知字段，undefined 不上 wire。
+     */
+    identity?: {
+        slug?: string;
+        startedAt?: number;
+        mode?: string;
+    };
+}
+/**
+ * [H1] run 的 resume 会话形态参数（设计 docs/architecture/subagent-chat-run-unification.md
+ * §3.3 D3 + §5 U1/U6 行）：原 RunChatParams（v1.x chat 会话形态参数）的泛化改名终态，
+ * 载荷同形（recordId + resume 锚点，ResumeAnchor 不变），仅键名从「chat 会话形态」
+ * 泛化为「resume 续聊」。
+ *   - recordId：core 预建 record 的关联键（引擎据此回填 handle.sessionRef、上报
+ *     host/childSpawned|childStateChanged 的 record 键形态）；
+ *   - resume：冷续锚点（重开已 idle 的 session 续聊；缺省 = 新 session）。对照
+ *     core SpawnResumeOpts——sessionFile 经 anchor.sessionRef 携带，model/
+ *     thinkingLevel 防漂移覆盖走既有 task/ctx 字段，不双写。
+ * [H1 U6 已切换] `chat` 键整体退役（读写端同批切换，无「写新读旧」窗口），本键为
+ * 唯一会话形态参数。载荷 schema 权威 = runSessionParamsSchema（schema.ts）。
+ */
+interface RunResumeParams {
+    recordId: string;
+    resume?: ResumeAnchor;
+}
+/** initialize 参数（engineConfig = L3 显式配置 engines.<id>.config 透传，不放凭据）。 */
+interface InitializeParams {
+    protocolVersion: number;
+    hostInfo: {
+        name: string;
+        version: string;
+        dataRoot: string;
+    };
+    engineConfig: Record<string, string>;
+}
+/** initialize 应答（仅诊断面：capabilities/models 与 manifest 不一致 → warn，不参与判据）。 */
+interface InitializeResult {
+    protocolVersion: number;
+    engineId: string;
+    engineVersion: string;
+    adapterVersion: string;
+    capabilities: EngineCapabilities;
+    /** 模型目录（诊断面；省略/null = 无枚举面语义）。 */
+    models?: ModelCatalogEntry[] | null;
+}
+interface ProbeParams {
+    force?: boolean;
+}
+interface RunParams {
+    runId: string;
+    task: AgentCallOpts;
+    ctx: RunContextParams;
+    /**
+     * [H1 U6 终态] resume 续聊参数（唯一会话形态键；原 v1.x `chat` 键已随键切换退役，
+     * 见 RunResumeParams）。缺省 = 一次性任务形态（向后兼容：旧引擎忽略未知字段，
+     * 帧级 schema params 不做深校验）。additive 可选：undefined 不上 wire。
+     */
+    resume?: RunResumeParams;
+}
+/** run 终态应答（期间事件经 event 通知；长运行方法，应答到达即终态）。 */
+interface RunResult {
+    handle: EngineHandleData;
+    outcome: AgentOutcome;
+}
+interface CancelParams {
+    runId: string;
+    reason: string;
+}
+/**
+ * cancel 应答（受理确认）。终态本体由该 run 的 run 终态应答承载（abort 合成终态经
+ * event/终态应答到达）；引擎须 CANCEL_SETTLE_GRACE_MS（3s）内收敛，超时 core 走杀链。
+ */
+interface CancelResult {
+    ok: true;
+}
+interface ReadParams {
+    handle: EngineHandleData;
+    /** 数据根（core 每次 read 都发送——remote-engine 构造注入的数据目录）。两引擎
+     *  server 现行均不消费该字段：定位走 handle.data（recordPath 等）或引擎自身
+     *  数据目录。保留为协议帧字段（历史：存量池时代引擎自算池/journal 相对 dbPath
+     *  的定位需要它）。 */
+    dataDir: string;
+}
+interface ListModelsParams {
+    /** 占位空参（帧形状一致性；未来诊断参数在此扩展）。 */
+    _placeholder?: never;
+}
+interface ListModelsResult {
+    /** 数组 = 有枚举面；null = 无枚举面（buildCoreAlignedHint 语义，与 manifest 省略对齐）。 */
+    models: ModelCatalogEntry[] | null;
+}
+interface ValidateModelParams {
+    modelRef?: string;
+}
+interface ValidateModelResult {
+    canonicalRef: string;
+}
+interface DisposeParams {
+    /** 占位空参（帧形状一致性；幂等语义）。 */
+    _placeholder?: never;
+}
+interface DisposeResult {
+    ok: true;
+}
+interface PingParams {
+    /** 占位空参（帧形状一致性）。 */
+    _placeholder?: never;
+}
+interface PingResult {
+    pong: true;
+}
+/** 方法 → params 类型映射。 */
+interface ProtocolParamsMap {
+    initialize: InitializeParams;
+    probe: ProbeParams;
+    run: RunParams;
+    cancel: CancelParams;
+    read: ReadParams;
+    listModels: ListModelsParams;
+    validateModel: ValidateModelParams;
+    dispose: DisposeParams;
+    ping: PingParams;
+}
+/** 方法 → result 类型映射。 */
+interface ProtocolResultMap {
+    initialize: InitializeResult;
+    probe: ProbeReport;
+    run: RunResult;
+    cancel: CancelResult;
+    read: SessionView;
+    listModels: ListModelsResult;
+    validateModel: ValidateModelResult;
+    dispose: DisposeResult;
+    ping: PingResult;
+}
+
+/** 协议核心错误码（引擎 error 帧 + core 同步拦截共用的固定词表）。 */
+declare const ENGINE_PROTOCOL_ERROR_CODES: readonly ["engine_not_found", "engine_protocol_mismatch", "engine_capability_unsupported", "engine_capability_mismatch", "engine_model_unknown", "engine_model_mismatch", "engine_handshake_timeout", "engine_crashed", "engine_probe_failed"];
+type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
+/** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
+declare function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode;
+/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+declare const ENGINE_ERROR_CODE_PREFIX = "engine_";
+declare function isEngineErrorPassthroughCode(value: string): boolean;
+
+/**
+ * 结构化引擎错误（message 恒为 `<code>: <detail>` 前缀格式——AgentOutcome.error 与
+ * 协议 error 帧共用的错误码前缀约定）；recovery 指向恢复动作。
+ * toStructured() 产出即协议 ProtocolError 形态（error 帧载荷直用）。
+ */
+declare class EngineSdkError extends Error {
+    readonly code: string;
+    readonly recovery: string;
+    readonly data?: Record<string, unknown>;
+    constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>);
+    /** 协议 error 帧载荷投影。 */
+    toStructured(): ProtocolError;
+}
+declare function engineProtocolMismatchError(engineVersion: number): EngineSdkError;
+/**
+ * 引擎 conversation 位拒绝的具名错误（[modeless 波2] 语义：无 resume 续聊通道的
+ * 引擎，message 续聊资格被拒——manifest conversation 能力轴消费；[modeless 波5
+ * 收尾] core capability-gate 的显式参数分支随派发参数删除退役，本构造器消费方 =
+ * 引擎侧 resume gate（assertChatConversationSupported）与 message 资格门）。
+ * 文案契约：错误码 engine_capability_unsupported + 「换引擎续聊 / 修 manifest /
+ * 升级引擎包」恢复指引，两侧一致防漂移。
+ */
+declare function engineConversationUnsupportedError(engineId: string): EngineSdkError;
+/**
+ * resume 会话形态（run.params.resume——唯一会话形态键）派发前的同步 gate：
+ * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError
+ * ——进程/record 创建前同步拒（A6 方向防御：manifest/实装漂移时引擎侧自拒，
+ * 与 core capability-gate 同一能力位，防两侧判据漂移）。[modeless 波2] 协议
+ * task 的 conversation 键已删，本 gate 只对 resume 形态键生效。
+ */
+declare function assertChatConversationSupported(engineId: string, capabilities: Pick<EngineCapabilities, "conversation">): void;
+/** stdout 尾部回显上限（engine_timeout / engine_run_failed 的错误规格载体系数）。 */
+declare const STDOUT_TAIL_ECHO_CHARS = 2000;
+/** engine_timeout 的恢复指引（kill-chain 超时杀链收尾文案）。 */
+declare const ENGINE_TIMEOUT_RECOVERY: string;
+/**
+ * engine_timeout 的 outcome.error 文案：含 stdout 尾部 2000 字 + 恢复指引
+ * （kill-chain synthesizeTimeoutOutcome 消费；与 core errors.ts engineTimeoutDetail 逐字等价）。
+ */
+declare function engineTimeoutDetail(stdoutTail: string): string;
+/** schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）。 */
+declare function schemaEmulationFailedDetail(error: string, tail: string): string;
+
+export { type ValidateModelResult as A, assertChatConversationSupported as B, type CancelParams as C, type DisposeParams as D, EngineSdkError as E, engineConversationUnsupportedError as F, engineProtocolMismatchError as G, engineTimeoutDetail as H, type InitializeResult as I, isEngineErrorPassthroughCode as J, isEngineProtocolErrorCode as K, type ListModelsParams as L, isNotificationFrame as M, type NotificationFrame as N, isRequestFrame as O, PROTOCOL_METHODS as P, isResponseFrame as Q, type RunContextParams as R, STDOUT_TAIL_ECHO_CHARS as S, isReverseRequestFrame as T, schemaEmulationFailedDetail as U, type ValidateModelParams as V, type InitializeParams as a, type CancelResult as b, type DisposeResult as c, ENGINE_ERROR_CODE_PREFIX as d, ENGINE_PROTOCOL_ERROR_CODES as e, ENGINE_TIMEOUT_RECOVERY as f, type EngineProtocolErrorCode as g, type ErrorResponseFrame as h, type EventNotificationParams as i, type ListModelsResult as j, type PingParams as k, type PingResult as l, type ProbeParams as m, type ProtocolError as n, type ProtocolMethod as o, type ProtocolParamsMap as p, type ProtocolResultMap as q, type ReadParams as r, type RequestFrame as s, type ResponseFrame as t, type ReverseRequestFrame as u, type ReverseResponseResult as v, type RunParams as w, type RunResult as x, type RunResumeParams as y, type SuccessResponseFrame as z };