@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/protocol/index.d.ts

@@ -0,0 +1,685 @@
+import { P as ProtocolError } from '../error-codes-Dhss2Kmk.js';
+export { A as AnyFrame, E as ENGINE_ERROR_CODE_PREFIX, a as ENGINE_PROTOCOL_ERROR_CODES, b as ENGINE_TIMEOUT_RECOVERY, c as EngineProtocolErrorCode, d as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as STDOUT_TAIL_ECHO_CHARS, j as SuccessResponseFrame, k as assertChatConversationSupported, l as engineConversationUnsupportedError, m as engineProtocolMismatchError, n as engineTimeoutDetail, o as isEngineErrorPassthroughCode, p as isEngineProtocolErrorCode, q as isNotificationFrame, r as isRequestFrame, s as isResponseFrame, t as isReverseRequestFrame, u as schemaEmulationFailedDetail } from '../error-codes-Dhss2Kmk.js';
+import { E as EngineCapabilities, M as ModelCatalogEntry, h as EngineHandleData, I as InteractAction, A as AgentCallOpts, k as ResumeAnchor, P as ProbeReport, c as AgentOutcome, i as InteractResult, S as SessionView, e as AgentUsage } from '../contract-types-sSlgppBC.js';
+export { a as AgentEvent, b as AgentFailureKind, d as AgentOutcomeUsage, f as AgentUsageTotal, g as AssertMutuallyAssignable, j as InternalToolCall, R as ReplayedTurn, T as ToolCall, l as ToolCallEntry, m as ToolCallResult, n as Turn, W as WorktreeHandle } from '../contract-types-sSlgppBC.js';
+import { UiRequest, UiResponse } from '../ui-types.js';
+
+/** 协议版本（引擎包 manifest `xyz-agent.subagentEngine.protocol` 与 initialize 应答同值）。 */
+declare const ENGINE_PROTOCOL_VERSION = 1;
+/**
+ * core 侧支持的协议版本区间（半开区间 [min, max)）：当前 = [1, 2)。
+ * 引擎版本落在区间外 → engine_protocol_mismatch。
+ */
+declare const SUPPORTED_PROTOCOL_RANGE: {
+    readonly min: 1;
+    readonly max: 2;
+};
+/** 版本兼容判定（core 握手判据；引擎侧对称用于拒绝过旧/过新宿主）。 */
+declare function isProtocolVersionCompatible(version: number): boolean;
+/** 正向数据面反向请求（帧④数据面类）未应答容忍时长：10s 未答 = 引擎故障 → 杀进程 + 在途 run 失败。 */
+declare const REVERSE_REQUEST_TIMEOUT_MS = 10000;
+/** initialize 握手超时（ms）：超时 → engine_handshake_timeout，该引擎不可用。 */
+declare const HANDSHAKE_TIMEOUT_MS = 10000;
+/** cancel 后引擎收敛终态的窗口（ms）；超时 core 走杀链。 */
+declare const CANCEL_SETTLE_GRACE_MS = 3000;
+/** engine_crashed 后重建上限与指数退避序列（ms）：1s / 2s / 4s，超限标记不可用至宿主重启。 */
+declare const CRASH_REBUILD_MAX_ATTEMPTS = 3;
+declare const CRASH_REBUILD_BACKOFF_MS: readonly [1000, 2000, 4000];
+/** stderr 内存环形缓冲保留的尾部字符数（engine_crashed 帧携带崩溃现场）。 */
+declare const STDERR_TAIL_CHARS = 400;
+/** 事件合并开关 env 名（设计级默认关闭 = 值 "0"；A1 要求事件逐字段等价，合并不可开）。 */
+declare const ENGINE_EVENT_COALESCE_ENV = "XYZ_ENGINE_EVENT_COALESCE";
+declare const ENGINE_EVENT_COALESCE_DEFAULT = "0";
+/**
+ * 反向请求超时二分（帧④注释，R9-2）：
+ * - 数据面类（host/log / host/streamDelta / host/poolResolved / host/handleReady /
+ *   host/childSpawned / host/childStateChanged / host/roundLifecycle[v1.x]）：10s 未答 =
+ *   引擎故障；
+ * - 人机交互类（host/askUser / host/permission）：不设统一超时——core 先回 {ack:true}，
+ *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
+ */
+type ReverseRequestTimeoutClass = "data-plane" | "interaction";
+
+/** 正向方法名联合（恰好 10 个；PROTOCOL_METHODS 常量数组与之同源互证）。 */
+type ProtocolMethod = "initialize" | "probe" | "run" | "cancel" | "interact" | "read" | "listModels" | "validateModel" | "dispose" | "ping";
+/** 方法名全集（运行时顺序化枚举；与 ProtocolMethod 的同源关系由测试断言）。 */
+declare const PROTOCOL_METHODS: readonly ["initialize", "probe", "run", "cancel", "interact", "read", "listModels", "validateModel", "dispose", "ping"];
+/**
+ * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
+ */
+interface RunContextParams {
+    /** 隔离池归属（journal 归属错 = 缺失后果）。 */
+    poolKey: string;
+    /** 任务工作目录（worktree 隔离时 = worktree 路径）。 */
+    cwd: string;
+    /** 请求模型 ref（未传 = 引擎缺省模型）。 */
+    model?: string;
+    /** 结构化输出 schema 的 env 注入形态（schemaEnv 降级通道）。 */
+    schemaEnv?: string;
+    /** 上下文模型 ref（与 run 模型分离的 ctx 模型）。 */
+    ctxModel?: string;
+    /** fallback 留痕（引擎回填 outcome.engineFallback 的种子）。 */
+    engineFallback?: {
+        from: string;
+        reason: string;
+    };
+    /** 事件粒度请求（引擎按 capabilities.eventGranularity 实际能力执行）。 */
+    streamMode?: "stream" | "coarse";
+}
+/**
+ * [v1.x] chat 会话形态参数——HostChatRoundTicket 五字段过协议映射中「record」的
+ * 承载位（docs/design/chat-domain-v1x-liveness-governance.md §3.2 D1 五字段映射）：
+ *   - recordId：core 预建 record 的关联键（引擎据此回填 handle.sessionRef、上报
+ *     host/childSpawned|childStateChanged 与 host/roundLifecycle 的 record 键形态）；
+ *   - resume：冷续锚点（重开已 idle 的 session 续聊；缺省 = 新 session）。对照
+ *     core SpawnResumeOpts——sessionFile 经 anchor.sessionRef 携带，model/
+ *     thinkingLevel 防漂移覆盖走既有 task/ctx 字段，不双写。
+ * task.conversation === true 时必传（chat 路由前置 gate：manifest conversation 位
+ * unsupported 的引擎同步拒 engine_capability_unsupported——见 error-codes.ts）。
+ */
+interface RunChatParams {
+    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;
+    /**
+     * [v1.x 可选增量] chat 会话形态参数（task.conversation=true 的 chat 路由承载）。
+     * 缺省 = 一次性任务形态，v1 引擎/宿主语义不变（向后兼容：旧引擎忽略未知字段，
+     * 帧级 schema params 不做深校验）。续聊/关断不经此参数——走既有 interact。
+     */
+    chat?: RunChatParams;
+}
+/** 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 InteractParams {
+    handle: EngineHandleData;
+    action: InteractAction;
+}
+interface ReadParams {
+    handle: EngineHandleData;
+    /** 数据根必填：存量池时代引擎自算池/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;
+    interact: InteractParams;
+    read: ReadParams;
+    listModels: ListModelsParams;
+    validateModel: ValidateModelParams;
+    dispose: DisposeParams;
+    ping: PingParams;
+}
+/** 方法 → result 类型映射。 */
+interface ProtocolResultMap {
+    initialize: InitializeResult;
+    probe: ProbeReport;
+    run: RunResult;
+    cancel: CancelResult;
+    interact: InteractResult;
+    read: SessionView;
+    listModels: ListModelsResult;
+    validateModel: ValidateModelResult;
+    dispose: DisposeResult;
+    ping: PingResult;
+}
+
+/** 反向通道名联合（恰好 9 个；REVERSE_CHANNELS 常量数组与之同源互证）。 */
+type ReverseChannel = "host/log" | "host/askUser" | "host/permission" | "host/streamDelta" | "host/poolResolved" | "host/handleReady" | "host/childSpawned" | "host/childStateChanged" | "host/roundLifecycle";
+declare const REVERSE_CHANNELS: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged", "host/roundLifecycle"];
+/**
+ * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
+ * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
+ * host/roundLifecycle 属数据面（终态回执语义：宿主必须确认收到，10s 未答 = 引擎故障）。
+ */
+declare const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseRequestTimeoutClass>;
+/** host/log：引擎日志落宿主日志（对齐 core HostServices.log 调用面）。 */
+interface HostLogParams {
+    level: "debug" | "warn" | "error";
+    component: string;
+    message: string;
+    data?: unknown;
+}
+/** host/askUser：UI 请求经反向通道送达宿主（core 壳侧 uiRequestHandler 应答）。 */
+interface HostAskUserParams {
+    runId: string;
+    /** Pi extension_ui_request 平铺形态（类型 SSOT = SDK ui-types.ts，core 反向 re-export）。 */
+    request: UiRequest;
+}
+/** host/askUser 的最终结果（ack 两阶段第二阶段，异步应答帧②的 result）。 */
+type HostAskUserResult = UiResponse;
+/**
+ * host/permission：权限询问（引擎请求宿主裁决工具执行）。
+ * v1 骨架字段（设计未钉死载荷细节，细化归各引擎提取设计；W2 实装 core 应答端时
+ * 若需扩展走 additive 演进）。
+ */
+interface HostPermissionParams {
+    runId: string;
+    toolName: string;
+    args?: unknown;
+    /** 请求方向引擎给出的原因/说明（展示用）。 */
+    reason?: string;
+}
+/** host/permission 两阶段结果。 */
+type HostPermissionResult = {
+    approved: boolean;
+} | {
+    unsupported: true;
+};
+/**
+ * host/streamDelta：UI 实时通道（双通道之一；与 event 通知并行的渲染加速面）。
+ *
+ * [v1.x 关联键扩展——D1-A 裁定，W1 落地不再临场选择]：
+ *   - run 域轮（含 run 会话形态首轮）：runId 关联（v1 现状不变，runId 由 core 在
+ *     run 帧分配）；
+ *   - interact 发起的续聊轮：**recordId** 关联（续聊轮无独立 runId——InteractParams/
+ *     InteractResult 均不含，recordId 经 handle.sessionRef 送达引擎）。
+ * 两键互斥（undefined 孪生位防双填），消费侧经 isHostStreamDeltaParams 收窄。
+ */
+type HostStreamDeltaParams = {
+    runId: string;
+    recordId?: undefined;
+    delta: string;
+} | {
+    recordId: string;
+    runId?: undefined;
+    delta: string;
+};
+/** streamDelta 载荷结构判定（关联键互斥 + delta 形状；消费侧共用，防双侧各写一份）。 */
+declare function isHostStreamDeltaParams(value: unknown): value is HostStreamDeltaParams;
+/**
+ * host/poolResolved：journal 落盘路径单一权威（契约：必须在首个事件 emit 前调用——
+ * 否则 journal 归属错）。载荷 = core onPoolResolved(poolKey) 的 runId 关联形态。
+ */
+interface HostPoolResolvedParams {
+    runId: string;
+    poolKey: string;
+}
+/**
+ * host/handleReady：运行中句柄回填（core onHandleReady 语义：session/create 应答后、
+ * 早于 run resolve；AGENTS.md 关键规则 9「重开 session 仍可见」的前提）。
+ */
+interface HostHandleReadyParams {
+    runId: string;
+    sessionRef: Record<string, string>;
+    poolKey: string;
+}
+/**
+ * host/childSpawned：引擎内一次性子进程 pid 上报。
+ * 用途 = isResumable 镜像谓词 + 诊断留痕；**不供杀链/收割**（v6 已删按 pid 补杀，
+ * 收割只靠进程组）；常驻进程不报（归 dispose）。
+ */
+interface HostChildSpawnedParams {
+    pid: number;
+    recordId: string;
+}
+/**
+ * host/childStateChanged：childSpawned 的状态面（core 侧镜像数据源，
+ * hasLiveProcessHandle/isResumable 同步读镜像，不跨进程查询）。
+ * **killed 必含**（判据 `child !== undefined && !child.killed`）——类型层 required。
+ */
+interface HostChildStateChangedParams {
+    pid: number;
+    recordId: string;
+    state: "running" | "exited";
+    /** 必含：true = 已被杀/已终止（镜像置死判据）。 */
+    killed: boolean;
+    exitCode?: number;
+    signal?: string;
+}
+/**
+ * 轮次关联键（D1-A 裁定的类型面）：run 域轮 = runId（v1 现状）；interact 续聊轮 =
+ * recordId（经 handle.sessionRef）。undefined 孪生位保证两键互斥。
+ */
+interface RoundKeyedByRun {
+    runId: string;
+    recordId?: undefined;
+}
+interface RoundKeyedByRecord {
+    recordId: string;
+    runId?: undefined;
+}
+/**
+ * 轮次终态相位（事件即 record 回写载体——chat 域 record 处置由相位一一映射，
+ * 设计 D2 裁决表 conversation 行：settled/idle 轮收口不终态、failed 标 failed）：
+ *   - settled：轮收敛（输出完整）。消费点 = settled-watchdog disarm + D3 abort
+ *     收敛判据（cancel 受理后等本事件，超 CANCEL_SETTLE_GRACE_MS 走杀链）；
+ *   - idle：轮收口 + 会话进 idle 稳态（core 侧 doFinalizeRoundToIdle + idle 定时器
+ *     锚点）。settled 与 idle 是两个锚点：watchdog 在 settled 即解除，idle 管置闲；
+ *   - failed：轮异常终止（引擎自知失败，如 EPIPE 兜底耗尽）——error 如实上报，
+ *     record 标 failed（与 run 域 AgentOutcome.error 的「失败收口」语义对齐）。
+ * usage 为本轮 message_end 增量（interact 续聊轮无 event 通知通道，用量经本帧回填）。
+ * 不设 seq：stdio NDJSON 单连接有序 + 数据面应答确认，无重排/重放面（与 event
+ * 通知的 seq 对照——后者镜像进程内事件流基线，本帧无基线可镜像）。
+ */
+interface RoundSettledPhase {
+    phase: "settled";
+    usage?: AgentUsage;
+}
+interface RoundIdlePhase {
+    phase: "idle";
+    usage?: AgentUsage;
+    /** 冷续锚点回填（session 滚动/compaction 后锚点可能变化，宿主按帧刷新）。 */
+    anchor?: ResumeAnchor;
+}
+interface RoundFailedPhase {
+    phase: "failed";
+    /** 失败原因（结构对齐协议 error 帧——code/message/recovery 可操作闭环）。 */
+    error: ProtocolError;
+    anchor?: ResumeAnchor;
+}
+/** 相位联合（消费侧 switch(phase) 判别用）。 */
+type RoundLifecyclePhase = RoundSettledPhase | RoundIdlePhase | RoundFailedPhase;
+/** host/roundLifecycle 载荷：关联键（run|record）× 相位（settled|idle|failed）。 */
+type HostRoundLifecycleParams = (RoundKeyedByRun & RoundSettledPhase) | (RoundKeyedByRun & RoundIdlePhase) | (RoundKeyedByRun & RoundFailedPhase) | (RoundKeyedByRecord & RoundSettledPhase) | (RoundKeyedByRecord & RoundIdlePhase) | (RoundKeyedByRecord & RoundFailedPhase);
+/**
+ * roundLifecycle 载荷结构判定：关联键互斥 + phase 词表 + 各相位专属形状
+ * （failed 必含 error.code/message）。引擎侧发帧前自检与 core 侧消费共用，
+ * 防两侧各写一份判别（与 isHostStreamDeltaParams 同理）。
+ */
+declare function isHostRoundLifecycleParams(value: unknown): value is HostRoundLifecycleParams;
+/** 通道 → 载荷类型映射。 */
+interface ReverseChannelParamsMap {
+    "host/log": HostLogParams;
+    "host/askUser": HostAskUserParams;
+    "host/permission": HostPermissionParams;
+    "host/streamDelta": HostStreamDeltaParams;
+    "host/poolResolved": HostPoolResolvedParams;
+    "host/handleReady": HostHandleReadyParams;
+    "host/childSpawned": HostChildSpawnedParams;
+    "host/childStateChanged": HostChildStateChangedParams;
+    "host/roundLifecycle": HostRoundLifecycleParams;
+}
+/** 通道 → 异步/同步结果类型映射（ack 两阶段通道的第二阶段 result）。 */
+interface ReverseChannelResultMap {
+    "host/log": {
+        ok: true;
+    };
+    "host/askUser": HostAskUserResult;
+    "host/permission": HostPermissionResult;
+    "host/streamDelta": {
+        ok: true;
+    };
+    "host/poolResolved": {
+        ok: true;
+    };
+    "host/handleReady": {
+        ok: true;
+    };
+    "host/childSpawned": {
+        ok: true;
+    };
+    "host/childStateChanged": {
+        ok: true;
+    };
+    "host/roundLifecycle": {
+        ok: true;
+    };
+}
+
+/** 协议错误对象 schema。 */
+declare const protocolErrorSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "EngineProtocolError";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["code", "message", "recovery"];
+    readonly properties: {
+        readonly code: {
+            readonly type: "string";
+            readonly pattern: "^engine_";
+        };
+        readonly message: {
+            readonly type: "string";
+        };
+        readonly recovery: {
+            readonly type: "string";
+        };
+        readonly data: {
+            readonly type: "object";
+        };
+    };
+};
+/** ① 请求帧（core → 引擎）。 */
+declare const requestFrameSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "EngineProtocolRequestFrame";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["id", "method", "params"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "number";
+        };
+        readonly method: {
+            readonly type: "string";
+            readonly enum: readonly ["initialize", "probe", "run", "cancel", "interact", "read", "listModels", "validateModel", "dispose", "ping"];
+        };
+        readonly params: {};
+    };
+};
+/** ② 应答帧（引擎 → core；result 与 error 互斥）。 */
+declare const successResponseFrameSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "EngineProtocolSuccessResponseFrame";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["id", "result"];
+    readonly properties: {
+        readonly id: {
+            readonly type: readonly ["number", "string"];
+        };
+        readonly result: {};
+    };
+};
+declare const errorResponseFrameSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "EngineProtocolErrorResponseFrame";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["id", "error"];
+    readonly properties: {
+        readonly id: {
+            readonly type: readonly ["number", "string"];
+        };
+        readonly error: {
+            readonly $schema: "http://json-schema.org/draft-07/schema#";
+            readonly title: "EngineProtocolError";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["code", "message", "recovery"];
+            readonly properties: {
+                readonly code: {
+                    readonly type: "string";
+                    readonly pattern: "^engine_";
+                };
+                readonly message: {
+                    readonly type: "string";
+                };
+                readonly recovery: {
+                    readonly type: "string";
+                };
+                readonly data: {
+                    readonly type: "object";
+                };
+            };
+        };
+    };
+};
+/** ③ 通知帧（引擎 → core，无 id；method 恒 "event"）。 */
+declare const notificationFrameSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "EngineProtocolNotificationFrame";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["method", "params"];
+    readonly properties: {
+        readonly method: {
+            readonly type: "string";
+            readonly const: "event";
+        };
+        readonly params: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["runId", "seq", "event"];
+            readonly properties: {
+                readonly runId: {
+                    readonly type: "string";
+                };
+                readonly seq: {
+                    readonly type: "number";
+                };
+                readonly event: {
+                    readonly type: "object";
+                    readonly required: readonly ["type"];
+                    readonly properties: {
+                        readonly type: {
+                            readonly type: "string";
+                            readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "error"];
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+/** ④ 反向请求帧（引擎 → core，必须应答；method 恒 host/*）。 */
+declare const reverseRequestFrameSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "EngineProtocolReverseRequestFrame";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["id", "method", "params"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+        };
+        readonly method: {
+            readonly type: "string";
+            readonly enum: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged", "host/roundLifecycle"];
+        };
+        readonly params: {};
+    };
+};
+/** 帧型 → schema 索引（校验入口按帧型取用）。 */
+declare const ENGINE_PROTOCOL_SCHEMAS: {
+    readonly request: {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly title: "EngineProtocolRequestFrame";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["id", "method", "params"];
+        readonly properties: {
+            readonly id: {
+                readonly type: "number";
+            };
+            readonly method: {
+                readonly type: "string";
+                readonly enum: readonly ["initialize", "probe", "run", "cancel", "interact", "read", "listModels", "validateModel", "dispose", "ping"];
+            };
+            readonly params: {};
+        };
+    };
+    readonly successResponse: {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly title: "EngineProtocolSuccessResponseFrame";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["id", "result"];
+        readonly properties: {
+            readonly id: {
+                readonly type: readonly ["number", "string"];
+            };
+            readonly result: {};
+        };
+    };
+    readonly errorResponse: {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly title: "EngineProtocolErrorResponseFrame";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["id", "error"];
+        readonly properties: {
+            readonly id: {
+                readonly type: readonly ["number", "string"];
+            };
+            readonly error: {
+                readonly $schema: "http://json-schema.org/draft-07/schema#";
+                readonly title: "EngineProtocolError";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["code", "message", "recovery"];
+                readonly properties: {
+                    readonly code: {
+                        readonly type: "string";
+                        readonly pattern: "^engine_";
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                    };
+                    readonly recovery: {
+                        readonly type: "string";
+                    };
+                    readonly data: {
+                        readonly type: "object";
+                    };
+                };
+            };
+        };
+    };
+    readonly notification: {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly title: "EngineProtocolNotificationFrame";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["method", "params"];
+        readonly properties: {
+            readonly method: {
+                readonly type: "string";
+                readonly const: "event";
+            };
+            readonly params: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["runId", "seq", "event"];
+                readonly properties: {
+                    readonly runId: {
+                        readonly type: "string";
+                    };
+                    readonly seq: {
+                        readonly type: "number";
+                    };
+                    readonly event: {
+                        readonly type: "object";
+                        readonly required: readonly ["type"];
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "error"];
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+    readonly reverseRequest: {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly title: "EngineProtocolReverseRequestFrame";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["id", "method", "params"];
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+            };
+            readonly method: {
+                readonly type: "string";
+                readonly enum: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged", "host/roundLifecycle"];
+            };
+            readonly params: {};
+        };
+    };
+    readonly protocolError: {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly title: "EngineProtocolError";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["code", "message", "recovery"];
+        readonly properties: {
+            readonly code: {
+                readonly type: "string";
+                readonly pattern: "^engine_";
+            };
+            readonly message: {
+                readonly type: "string";
+            };
+            readonly recovery: {
+                readonly type: "string";
+            };
+            readonly data: {
+                readonly type: "object";
+            };
+        };
+    };
+};
+/**
+ * 协议面凭据禁区键名（不变量 5 的测试断言依据）：帧 schema 与深载荷 TS 类型面
+ * 不得出现。词表覆盖常见拼写（子串匹配，非精确枚举）。
+ */
+declare const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS: readonly ["apikey", "api_key", "token", "credential", "password", "secret"];
+/** 反向通道名词表导出（schema enum 与 W2 路由同源）。 */
+declare const REVERSE_CHANNEL_NAMES: readonly ReverseChannel[];
+
+export { AgentCallOpts, AgentOutcome, AgentUsage, CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, type CancelParams, type CancelResult, type DisposeParams, type DisposeResult, ENGINE_EVENT_COALESCE_DEFAULT, ENGINE_EVENT_COALESCE_ENV, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, EngineCapabilities, EngineHandleData, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostPermissionParams, type HostPermissionResult, type HostPoolResolvedParams, type HostRoundLifecycleParams, type HostStreamDeltaParams, type InitializeParams, type InitializeResult, InteractAction, type InteractParams, InteractResult, type ListModelsParams, type ListModelsResult, ModelCatalogEntry, PROTOCOL_METHODS, type PingParams, type PingResult, type ProbeParams, ProbeReport, ProtocolError, type ProtocolMethod, type ProtocolParamsMap, type ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_NAMES, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReadParams, ResumeAnchor, type ReverseChannel, type ReverseChannelParamsMap, type ReverseChannelResultMap, type ReverseRequestTimeoutClass, type RoundFailedPhase, type RoundIdlePhase, type RoundKeyedByRecord, type RoundKeyedByRun, type RoundLifecyclePhase, type RoundSettledPhase, type RunChatParams, type RunContextParams, type RunParams, type RunResult, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, SessionView, type ValidateModelParams, type ValidateModelResult, errorResponseFrameSchema, isHostRoundLifecycleParams, isHostStreamDeltaParams, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, successResponseFrameSchema };