@zhushanwen/subagent-engine-sdk 0.2.0

package/src/protocol/reverse-channels.ts

@@ -0,0 +1,274 @@
+// src/protocol/reverse-channels.ts
+//
+// 9 反向通道（引擎 → core，帧④，必须应答）载荷与超时二分。设计权威源：
+// 设计 §3.3 方法集表 host/* 行 + impl-plan §2.1「8 反向通道」与「反向请求超时二分」
+// + chat 域 v1.x 增量（docs/design/chat-domain-v1x-liveness-governance.md §3.2 D1-A：
+// 第 9 通道 host/roundLifecycle 承载轮次终态事件与 record 回写）。
+//
+// 应答约定：数据面类回 {ok:true}（REVERSE_REQUEST_TIMEOUT_MS=10s 未答 = 引擎故障 →
+// 杀进程 + 在途 run 失败）；人机交互类走 ack 两阶段——先回 {ack:true}，结果异步到达
+// （R9-2：已 ack 的等待不计入任何 in-flight 超时；ADR-0047 静默 ≠ 卡死）；
+// 未实现的交互能力回 {unsupported:true}（引擎自行降级，不重试）。
+
+import type { ReverseRequestTimeoutClass } from "./engine-protocol.ts";
+import type { UiRequest, UiResponse } from "../ui-types.ts";
+import type { AgentUsage, ResumeAnchor } from "./contract-types.ts";
+import type { ProtocolError } from "./frames.ts";
+
+/** 反向通道名联合（恰好 9 个；REVERSE_CHANNELS 常量数组与之同源互证）。 */
+export type ReverseChannel =
+  | "host/log"
+  | "host/askUser"
+  | "host/permission"
+  | "host/streamDelta"
+  | "host/poolResolved"
+  | "host/handleReady"
+  | "host/childSpawned"
+  | "host/childStateChanged"
+  | "host/roundLifecycle";
+
+export const REVERSE_CHANNELS = [
+  "host/log",
+  "host/askUser",
+  "host/permission",
+  "host/streamDelta",
+  "host/poolResolved",
+  "host/handleReady",
+  "host/childSpawned",
+  "host/childStateChanged",
+  "host/roundLifecycle",
+] as const satisfies readonly ReverseChannel[];
+
+/**
+ * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
+ * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
+ * host/roundLifecycle 属数据面（终态回执语义：宿主必须确认收到，10s 未答 = 引擎故障）。
+ */
+export const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseRequestTimeoutClass> = {
+  "host/log": "data-plane",
+  "host/streamDelta": "data-plane",
+  "host/poolResolved": "data-plane",
+  "host/handleReady": "data-plane",
+  "host/childSpawned": "data-plane",
+  "host/childStateChanged": "data-plane",
+  "host/roundLifecycle": "data-plane",
+  "host/askUser": "interaction",
+  "host/permission": "interaction",
+};
+
+// ============================================================
+// 通道载荷（params）
+// ============================================================
+
+/** host/log：引擎日志落宿主日志（对齐 core HostServices.log 调用面）。 */
+export interface HostLogParams {
+  level: "debug" | "warn" | "error";
+  component: string;
+  message: string;
+  data?: unknown;
+}
+
+/** host/askUser：UI 请求经反向通道送达宿主（core 壳侧 uiRequestHandler 应答）。 */
+export interface HostAskUserParams {
+  runId: string;
+  /** Pi extension_ui_request 平铺形态（类型 SSOT = SDK ui-types.ts，core 反向 re-export）。 */
+  request: UiRequest;
+}
+
+/** host/askUser 的最终结果（ack 两阶段第二阶段，异步应答帧②的 result）。 */
+export type HostAskUserResult = UiResponse;
+
+/**
+ * host/permission：权限询问（引擎请求宿主裁决工具执行）。
+ * v1 骨架字段（设计未钉死载荷细节，细化归各引擎提取设计；W2 实装 core 应答端时
+ * 若需扩展走 additive 演进）。
+ */
+export interface HostPermissionParams {
+  runId: string;
+  toolName: string;
+  args?: unknown;
+  /** 请求方向引擎给出的原因/说明（展示用）。 */
+  reason?: string;
+}
+
+/** host/permission 两阶段结果。 */
+export 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 收窄。
+ */
+export type HostStreamDeltaParams =
+  | { runId: string; recordId?: undefined; delta: string }
+  | { recordId: string; runId?: undefined; delta: string };
+
+/** streamDelta 载荷结构判定（关联键互斥 + delta 形状；消费侧共用，防双侧各写一份）。 */
+export function isHostStreamDeltaParams(value: unknown): value is HostStreamDeltaParams {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  const hasRunId = typeof v.runId === "string";
+  const hasRecordId = typeof v.recordId === "string";
+  // 恰一键：无键 / 双键 / 键非 string 都拒
+  if (hasRunId === hasRecordId) return false;
+  return typeof v.delta === "string";
+}
+
+/**
+ * host/poolResolved：journal 落盘路径单一权威（契约：必须在首个事件 emit 前调用——
+ * 否则 journal 归属错）。载荷 = core onPoolResolved(poolKey) 的 runId 关联形态。
+ */
+export interface HostPoolResolvedParams {
+  runId: string;
+  poolKey: string;
+}
+
+/**
+ * host/handleReady：运行中句柄回填（core onHandleReady 语义：session/create 应答后、
+ * 早于 run resolve；AGENTS.md 关键规则 9「重开 session 仍可见」的前提）。
+ */
+export interface HostHandleReadyParams {
+  runId: string;
+  sessionRef: Record<string, string>;
+  poolKey: string;
+}
+
+/**
+ * host/childSpawned：引擎内一次性子进程 pid 上报。
+ * 用途 = isResumable 镜像谓词 + 诊断留痕；**不供杀链/收割**（v6 已删按 pid 补杀，
+ * 收割只靠进程组）；常驻进程不报（归 dispose）。
+ */
+export interface HostChildSpawnedParams {
+  pid: number;
+  recordId: string;
+}
+
+/**
+ * host/childStateChanged：childSpawned 的状态面（core 侧镜像数据源，
+ * hasLiveProcessHandle/isResumable 同步读镜像，不跨进程查询）。
+ * **killed 必含**（判据 `child !== undefined && !child.killed`）——类型层 required。
+ */
+export interface HostChildStateChangedParams {
+  pid: number;
+  recordId: string;
+  state: "running" | "exited";
+  /** 必含：true = 已被杀/已终止（镜像置死判据）。 */
+  killed: boolean;
+  exitCode?: number;
+  signal?: string;
+}
+
+// ============================================================
+// [v1.x] host/roundLifecycle：轮次生命周期载荷（chat 域 v1.x 唯一新通道）
+// ============================================================
+
+/**
+ * 轮次关联键（D1-A 裁定的类型面）：run 域轮 = runId（v1 现状）；interact 续聊轮 =
+ * recordId（经 handle.sessionRef）。undefined 孪生位保证两键互斥。
+ */
+export interface RoundKeyedByRun {
+  runId: string;
+  recordId?: undefined;
+}
+
+export 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 对照——后者镜像进程内事件流基线，本帧无基线可镜像）。
+ */
+export interface RoundSettledPhase {
+  phase: "settled";
+  usage?: AgentUsage;
+}
+
+export interface RoundIdlePhase {
+  phase: "idle";
+  usage?: AgentUsage;
+  /** 冷续锚点回填（session 滚动/compaction 后锚点可能变化，宿主按帧刷新）。 */
+  anchor?: ResumeAnchor;
+}
+
+export interface RoundFailedPhase {
+  phase: "failed";
+  /** 失败原因（结构对齐协议 error 帧——code/message/recovery 可操作闭环）。 */
+  error: ProtocolError;
+  anchor?: ResumeAnchor;
+}
+
+/** 相位联合（消费侧 switch(phase) 判别用）。 */
+export type RoundLifecyclePhase = RoundSettledPhase | RoundIdlePhase | RoundFailedPhase;
+
+/** host/roundLifecycle 载荷：关联键（run|record）× 相位（settled|idle|failed）。 */
+export type HostRoundLifecycleParams =
+  | (RoundKeyedByRun & RoundSettledPhase)
+  | (RoundKeyedByRun & RoundIdlePhase)
+  | (RoundKeyedByRun & RoundFailedPhase)
+  | (RoundKeyedByRecord & RoundSettledPhase)
+  | (RoundKeyedByRecord & RoundIdlePhase)
+  | (RoundKeyedByRecord & RoundFailedPhase);
+
+/**
+ * roundLifecycle 载荷结构判定：关联键互斥 + phase 词表 + 各相位专属形状
+ * （failed 必含 error.code/message）。引擎侧发帧前自检与 core 侧消费共用，
+ * 防两侧各写一份判别（与 isHostStreamDeltaParams 同理）。
+ */
+export function isHostRoundLifecycleParams(value: unknown): value is HostRoundLifecycleParams {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  const hasRunId = typeof v.runId === "string";
+  const hasRecordId = typeof v.recordId === "string";
+  if (hasRunId === hasRecordId) return false;
+  if (v.phase === "settled" || v.phase === "idle") return true;
+  if (v.phase !== "failed") return false;
+  const err = v.error;
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    typeof (err as Record<string, unknown>).code === "string" &&
+    typeof (err as Record<string, unknown>).message === "string"
+  );
+}
+
+/** 通道 → 载荷类型映射。 */
+export 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）。 */
+export 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 };
+}

package/src/protocol/schema.ts

@@ -0,0 +1,154 @@
+// src/protocol/schema.ts
+//
+// 帧校验 JSON Schema（draft-07）。设计权威源：impl-plan §2.1 W1 职责「JSON Schema
+// （帧校验用）」+ 设计 §3.10 不变量 5「凭据不过协议：协议里不出现 apiKey / token
+// 字段（schema 层禁止 + 测试断言）」。
+//
+// schema 层禁止凭据的实现口径：所有对象帧 additionalProperties:false + 属性白名单，
+// 凭据类键名（apiKey/token/credential 等）不在任何白名单内；测试侧另断言白名单全集
+// 无凭据键（src/__tests__/protocol-frames.test.ts）。params/result 的深载荷结构由
+// TS 类型承载（protocol/methods.ts / reverse-channels.ts / contract-types.ts），
+// 帧级 schema 只定形状骨架（id/method/params/result/error 的存在性与类型）——
+// 帧校验的目的是行解析器快速拒格式坏帧，不做深校验（深校验成本高于收益，坏载荷
+// 由消费方结构化报错）。
+
+import type { ReverseChannel } from "./reverse-channels.ts";
+import { REVERSE_CHANNELS } from "./reverse-channels.ts";
+import { PROTOCOL_METHODS } from "./methods.ts";
+
+/** 任意 JSON 值（draft-07 空约束）。 */
+const ANY_JSON = {} as const;
+
+/** 协议错误对象 schema。 */
+export const protocolErrorSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolError",
+  type: "object",
+  additionalProperties: false,
+  required: ["code", "message", "recovery"],
+  properties: {
+    code: { type: "string", pattern: "^engine_" },
+    message: { type: "string" },
+    recovery: { type: "string" },
+    data: { type: "object" },
+  },
+} as const;
+
+/** ① 请求帧（core → 引擎）。 */
+export const requestFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolRequestFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "method", "params"],
+  properties: {
+    id: { type: "number" },
+    method: { type: "string", enum: [...PROTOCOL_METHODS] },
+    params: ANY_JSON,
+  },
+} as const;
+
+/** ② 应答帧（引擎 → core；result 与 error 互斥）。 */
+export const successResponseFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolSuccessResponseFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "result"],
+  properties: {
+    id: { type: ["number", "string"] },
+    result: ANY_JSON,
+  },
+} as const;
+
+export const errorResponseFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolErrorResponseFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "error"],
+  properties: {
+    id: { type: ["number", "string"] },
+    error: protocolErrorSchema,
+  },
+} as const;
+
+/** ③ 通知帧（引擎 → core，无 id；method 恒 "event"）。 */
+export const notificationFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolNotificationFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["method", "params"],
+  properties: {
+    method: { type: "string", const: "event" },
+    params: {
+      type: "object",
+      additionalProperties: false,
+      required: ["runId", "seq", "event"],
+      properties: {
+        runId: { type: "string" },
+        seq: { type: "number" },
+        event: {
+          type: "object",
+          required: ["type"],
+          properties: {
+            type: {
+              type: "string",
+              enum: [
+                "tool_start",
+                "tool_end",
+                "text_delta",
+                "thinking_delta",
+                "turn_end",
+                "message_end",
+                "compaction",
+                "error",
+              ],
+            },
+          },
+        },
+      },
+    },
+  },
+} as const;
+
+/** ④ 反向请求帧（引擎 → core，必须应答；method 恒 host/*）。 */
+export const reverseRequestFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolReverseRequestFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "method", "params"],
+  properties: {
+    id: { type: "string" },
+    method: { type: "string", enum: [...REVERSE_CHANNELS] },
+    params: ANY_JSON,
+  },
+} as const;
+
+/** 帧型 → schema 索引（校验入口按帧型取用）。 */
+export const ENGINE_PROTOCOL_SCHEMAS = {
+  request: requestFrameSchema,
+  successResponse: successResponseFrameSchema,
+  errorResponse: errorResponseFrameSchema,
+  notification: notificationFrameSchema,
+  reverseRequest: reverseRequestFrameSchema,
+  protocolError: protocolErrorSchema,
+} as const;
+
+/**
+ * 协议面凭据禁区键名（不变量 5 的测试断言依据）：帧 schema 与深载荷 TS 类型面
+ * 不得出现。词表覆盖常见拼写（子串匹配，非精确枚举）。
+ */
+export const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS = [
+  "apikey",
+  "api_key",
+  "token",
+  "credential",
+  "password",
+  "secret",
+] as const;
+
+/** 反向通道名词表导出（schema enum 与 W2 路由同源）。 */
+export const REVERSE_CHANNEL_NAMES: readonly ReverseChannel[] = REVERSE_CHANNELS;

package/src/relay-env.ts

@@ -0,0 +1,60 @@
+// src/relay-env.ts
+//
+// subagent relay 通道 env 名与协议常量 SSOT（docs/architecture/subagent-realtime-channel.md
+// §5.1/§5.2/§3.1）。跨进程契约单源：core（./relay-env 子入口）与 pi 引擎 CLI
+// 的副本（round1-reuse R9）自本模块 re-export 收编——边界合法（引擎 CLI → SDK、
+// core → SDK 均正向）。runtime 侧消费经 core 子入口间接取本单源。
+//
+// 为什么独立成模块：三方消费同一份常量——extension 侧（pi-invocation 激活判定 /
+// buildChildEnv 归属写入）、runtime 侧（env 注入与镜像校验）、代理脚本 relay.mjs
+// （零依赖脚本不能 import workspace 包，只能内嵌镜像，镜像一致性由 conformance
+// relay 变体断言锁定）。禁各处手写字符串。
+//
+// env 语义：SOCKET/NODE/SCRIPT 三者同时非空 = relay 激活（全有或全无，无中间态）；
+// SESSION_ID/RECORD_ID 是 tee 帧归属键（缺失由代理握手前自检拒绝，退出码 13）。
+
+export const RELAY_ENV_SOCKET = "XYZ_SUBAGENT_RELAY_SOCKET";
+export const RELAY_ENV_NODE = "XYZ_SUBAGENT_RELAY_NODE";
+export const RELAY_ENV_SCRIPT = "XYZ_SUBAGENT_RELAY_SCRIPT";
+export const RELAY_ENV_SESSION_ID = "XYZ_SUBAGENT_RELAY_SESSION_ID";
+export const RELAY_ENV_RECORD_ID = "XYZ_SUBAGENT_RELAY_RECORD_ID";
+
+/** relay 协议版本（握手帧 v 字段；runtime 与代理同包分发，不匹配=安装损坏）。 */
+export const RELAY_PROTOCOL_VERSION = 1;
+
+/** 代理专用退出码（extension/引擎侧表现为「子进程非零退出」→ engine_run_failed 语义）。 */
+export const RELAY_EXIT_CODES = {
+  /** 握手被拒：协议版本不匹配（安装损坏，重装应用）。 */
+  VERSION_MISMATCH: 10,
+  /** relay socket 不可达（runtime 未运行或已重启）。 */
+  SOCKET_UNREACHABLE: 11,
+  /** socket 中途断开（runtime 崩溃等）——代理生命线断即退。 */
+  SOCKET_CLOSED: 12,
+  /** 归属 env（SESSION_ID/RECORD_ID）缺失——防无归属帧污染广播。 */
+  MISSING_IDENTITY: 13,
+} as const;
+
+/** 激活判定：三 env 同时非空才走 relay，任一缺失回落直连 spawn 真实引擎（TUI/独立引擎零回归）。 */
+export function isRelayActive(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean {
+  return Boolean(env[RELAY_ENV_SOCKET] && env[RELAY_ENV_NODE] && env[RELAY_ENV_SCRIPT]);
+}
+
+/**
+ * [W8 H12] 宿主 env → relay 连接三键的转发提取（原样转发语义的单一实现）。
+ *
+ * 三键同时非空（isRelayActive 同判）才返回——全有或全无，无中间态；身份键
+ * SESSION_ID/RECORD_ID 不在本提取面（它们是父身份归属键，引擎子进程 env 由
+ * SDK buildEngineChildEnv L1 deny 剥除、引擎按 run.params.ctx 重写，不靠 env 继承）。
+ *
+ * 消费方：D8 createZcodeEngine 薄壳（zsw 宿主链路的 relay 透传）；宿主 env 形态
+ * 与 SDK EngineRelayEnv 结构等价（字段名 socket/node/script），TS 结构类型直接赋值。
+ */
+export function readRelayForwardEnv(
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>,
+): { socket: string; node: string; script: string } | undefined {
+  const socket = env[RELAY_ENV_SOCKET];
+  const node = env[RELAY_ENV_NODE];
+  const script = env[RELAY_ENV_SCRIPT];
+  if (!isRelayActive(env)) return undefined;
+  return { socket: socket as string, node: node as string, script: script as string };
+}

package/src/schema-emulation.ts

@@ -0,0 +1,192 @@
+// src/schema-emulation.ts
+//
+// schema 仿真降级（引擎侧原语，自 core execution/engine/common/schema-emulation.ts
+// 迁入 @zhushanwen/subagent-engine-sdk，实现体逐字等价）。迁移处置：无 core 内部
+// 依赖 → 直接搬（impl-plan §2.1 原语迁移处置表）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D4（native/emulated 硬分流）+ §3.3.3
+// schema_emulation_failed 行 + §5 P2 行。
+//
+// ─── D4 硬分流（违反 = 历史事故形态） ───────────────────────────────
+// 本模块只服务 capabilities.schemaEnforcement === 'emulated' 的引擎
+// （zcode / opencode / kimi-code）。capabilities.schemaEnforcement === 'native' 的引擎
+// （pi 的 PI_WORKFLOW_SCHEMA env 注入链路、claude-code --json-schema、codex
+// --output-schema）**禁止** import 本模块做二次校验或改写其结果——宿主侧再叠一层
+// ajv 会制造第二校验权威，恰是 structured-output 方案 A [HISTORICAL]
+// （2026-08-01「校验自报 schema 致修复静默丢失」事故）的形态。
+// ajv 只允许出现在 emulated 路径（本模块），这是全仓唯一例外。
+//
+// 重试语义：本模块两个函数保持纯——校验失败/提取失败由调用方（宿主编排层）决定
+// 重试，语义与 structured-output 的 workflow-hook 对齐（重试一次、强化 prompt；
+// 仍失败报 schema_emulation_failed，错误含原始输出尾部）。
+//
+// 文案对齐：错误回显风格对齐 structured-output 的 execute.ts（"Schema validation
+// failed: ..."），但不 import 其内部模块（公共层自实现；structured-output 是
+// peer 依赖且可选，import 会造成公共层对 sibling extension 的硬依赖）。
+
+import Ajv, { type ValidateFunction } from "ajv";
+
+/** 原始输出尾部回显长度（结果对象的 tail 字段，供错误展示与重试 prompt 回灌）。 */
+export const SCHEMA_EMULATION_TAIL_CHARS = 500;
+
+// ============================================================
+// prompt 注入段
+// ============================================================
+
+/**
+ * 构造 prompt 注入段：schema 声明 + 输出格式约定（emulated 引擎的 launcher 把它拼进
+ * 最终 prompt，替代引擎不存在的 schema 强制通道）。
+ *
+ * 文案风格对齐 structured-output 的 promptGuidelines（"Do not output JSON in text"：emulated 引擎没有工具可调，JSON 必须出现在文本里）。
+ */
+export function buildSchemaEmulationSegment(schema: object): string {
+  const schemaJson = JSON.stringify(schema);
+  return [
+    "## Structured Output Requirement",
+    "Your final answer MUST contain exactly one JSON value conforming to this JSON Schema (draft-07):",
+    schemaJson,
+    "Output rules:",
+    "- Output ONLY the JSON value — no prose before or after it.",
+    "- If you wrap it in a markdown code fence, use a single ```json fence.",
+    "- Do not output multiple JSON values; the first complete JSON value is extracted.",
+  ].join("\n");
+}
+
+// ============================================================
+// 三级容错提取 + ajv 校验
+// ============================================================
+
+/** 提取结果联合：ok=true 携带通过校验的 parsed；ok=false 携带 error 简述 + 原始输出尾部。 */
+export type StructuredOutputResult =
+  | { ok: true; parsed: unknown }
+  | { ok: false; error: string; tail: string };
+
+/**
+ * 从模型文本输出提取并校验结构化 JSON（三级容错 → ajv）。
+ *
+ * 三级容错（逐级降级，任一级提取成功即进 ajv）：
+ *   1. 直接 JSON.parse（trim 后整体是合法 JSON）；
+ *   2. 剥 markdown code fence（```json ... ``` / ``` ... ```）取围栏内内容；
+ *   3. 首尾括号扫描（首个 '{'/'[' 到末个 '}'/']' 的子串——容纳前后杂文本）。
+ *
+ * ajv 校验失败/三级提取失败返回 ok:false（不 throw）——重试与否是宿主编排层的
+ * 决策（见文件头重试语义），本函数每次调用独立无状态。
+ */
+export function extractAndValidateStructuredOutput(
+  text: string,
+  schema: object,
+): { ok: true; parsed: unknown } | { ok: false; error: string; tail: string } {
+  return extractImpl(text, schema);
+}
+
+/** 实现体（签名拆分只为让导出签名与契约声明逐字一致，见 StructuredOutputResult）。 */
+function extractImpl(text: string, schema: object): StructuredOutputResult {
+  const tail = text.length > SCHEMA_EMULATION_TAIL_CHARS
+    ? text.slice(text.length - SCHEMA_EMULATION_TAIL_CHARS)
+    : text;
+
+  const extracted = extractJsonCandidate(text);
+  if (extracted === undefined) {
+    return {
+      ok: false,
+      error:
+        "could not extract JSON from model output after 3-stage fallback " +
+        "(direct parse -> code-fence strip -> bracket scan)",
+      tail,
+    };
+  }
+
+  const validate = getOrCompileValidator(schema);
+  if (validate === undefined) {
+    return {
+      ok: false,
+      error: "host-side JSON Schema compilation failed (invalid schema object)",
+      tail,
+    };
+  }
+
+  const valid = validate(extracted);
+  if (!valid) {
+    // 错误格式对齐 structured-output："instancePath message" 逐条 join
+    const errors = validate.errors?.map((err) => `${err.instancePath} ${err.message}`).join("; ");
+    return {
+      ok: false,
+      error: `Schema validation failed: ${errors ?? "(no detail)"}`,
+      tail,
+    };
+  }
+  return { ok: true, parsed: extracted };
+}
+
+// ── 内部：三级提取 ──────────────────────────────────────────────
+
+/** 三级容错提取 JSON candidate；全部失败返回 undefined。 */
+function extractJsonCandidate(text: string): unknown {
+  // 第 1 级：整体直接 parse（最常见——严格遵守输出约定的模型）
+  const direct = tryParse(text.trim());
+  if (direct.ok) return direct.value;
+
+  // 第 2 级：markdown code fence 剥离（模型爱用 ```json 包裹）
+  const fenced = extractFirstFencedBlock(text);
+  if (fenced !== undefined) {
+    const parsed = tryParse(fenced.trim());
+    if (parsed.ok) return parsed.value;
+  }
+
+  // 第 3 级：首尾括号扫描（前后杂文本："Here is the result: {...} Hope this helps"）
+  const scanned = extractByBracketScan(text);
+  if (scanned !== undefined) {
+    const parsed = tryParse(scanned.trim());
+    if (parsed.ok) return parsed.value;
+  }
+
+  return undefined;
+}
+
+/** JSON.parse 包装：失败返回 ok:false（malformed 不是异常态，是三级降级的输入）。 */
+function tryParse(raw: string): { ok: true; value: unknown } | { ok: false } {
+  if (raw === "") return { ok: false };
+  try {
+    return { ok: true, value: JSON.parse(raw) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/** 取第一个 markdown code fence 块内容（```json / ``` 均可）；无 fence 返回 undefined。 */
+function extractFirstFencedBlock(text: string): string | undefined {
+  const match = /```(?:json)?\s*([\s\S]*?)\s*```/.exec(text);
+  return match?.[1];
+}
+
+/** 首尾括号扫描：首个 '{'/'[' 到末个 '}'/']' 的子串；边界不合法返回 undefined。 */
+function extractByBracketScan(text: string): string | undefined {
+  const objOpen = text.indexOf("{");
+  const arrOpen = text.indexOf("[");
+  const open = objOpen === -1 ? arrOpen : arrOpen === -1 ? objOpen : Math.min(objOpen, arrOpen);
+  const objClose = text.lastIndexOf("}");
+  const arrClose = text.lastIndexOf("]");
+  const close = Math.max(objClose, arrClose);
+  if (open === -1 || close === -1 || open >= close) return undefined;
+  return text.slice(open, close + 1);
+}
+
+// ── 内部：ajv 编译缓存 ──────────────────────────────────────────
+
+// WeakMap 缓存（schema 对象引用即 key，GC 友好）——模式对齐 structured-output 的
+// ajv-validator.ts（自实现，不跨包 import；见文件头依赖边界说明）。
+// CJS 多 entry 内联副本的实例分裂影响 = 缓存 miss 重新编译，无语义后果。
+const ajvCache = new WeakMap<object, ValidateFunction>();
+
+/** 编译（或取缓存）validator；schema 非法（ajv 抛错）返回 undefined 由调用方报错。 */
+function getOrCompileValidator(schema: object): ValidateFunction | undefined {
+  const cached = ajvCache.get(schema);
+  if (cached) return cached;
+  try {
+    // strict:false 对齐 structured-output 的宽容度（非标 keyword 不炸编译）
+    const validate = new Ajv({ strict: false }).compile(schema);
+    ajvCache.set(schema, validate);
+    return validate;
+  } catch {
+    return undefined;
+  }
+}