@zhushanwen/subagent-engine-sdk 0.9.0 → 0.10.0

package/dist/node-executor.cjs

@@ -30,6 +30,32 @@ module.exports = __toCommonJS(node_executor_exports);
 var import_node_child_process = require("child_process");
 
 // src/protocol/error-codes.ts
+var SET_MODEL_ERROR_CODES = [
+  /** 目标模型不在当前进程快照（子进程模型快照冻结于 spawn 时刻——模型本身有效，
+   *  下一轮 spawn 现取目录即可用；宿主按「写覆盖意图」处置，设计 §7.2 快照型失败行）。 */
+  "engine_model_not_in_snapshot",
+  /** 凭据校验失败（子进程 set_model checkAuth 抛错——宿主预检通过后 registry 态漂移
+   *  的权威兜底；宿主按校验型失败处置，设计 §7.5 凭据行）。 */
+  "engine_credential_missing",
+  /** 命令已发出（set_model 可能已执行）但读应答 / get_state 回读无回执、生效值未知
+   *  （非进程退出情形——退出归无活进程路径；宿主按「写覆盖意图 + 错误应答」处置，
+   *  设计 §7.5 回读失败行）。 */
+  "engine_state_readback_failed"
+];
+var SET_MODEL_NOT_ACTIVE_CODE = "engine_run_not_active";
+var ENGINE_PROTOCOL_ERROR_CODES = [
+  "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",
+  ...SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE
+];
 var EngineSdkError = class extends Error {
   code;
   recovery;

package/dist/node-executor.js

@@ -4,8 +4,8 @@ import {
   probeNodeExecutor,
   resetEngineNodeProbeCache,
   resolveEngineNodeLaunch
-} from "./chunk-KADRNFG2.js";
-import "./chunk-VDKR7MLG.js";
+} from "./chunk-NTOLHLCL.js";
+import "./chunk-JZN76I3S.js";
 import "./chunk-JSBRDJBE.js";
 export {
   ENGINE_NODE_ENV,

package/dist/port-contract.d.cts

@@ -1,4 +1,5 @@
-import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-DqOD58r-.cjs';
+import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-jSa1g28F.cjs';
+import { S as SetModelParams, a as SetModelResult } from './methods-BLxg4ZFr.cjs';
 
 /**
  * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
@@ -125,6 +126,15 @@ interface EnginePort {
     validateModel?(modelRef: string | undefined): {
         canonicalRef: string;
     };
+    /**
+     * [subagent-model-switch §7.3] 可选面：执行中模型热切换（协议 setModel 正向方法的
+     * 进程内承载）。实现引擎须 capabilities.setModel = 'native' 同批声明（位与方法
+     * 成对进出——capabilities 注释的消费点登记）；server 分发行在位非 native 时回
+     * engineSetModelUnsupportedError 结构化错误（契约行为 = 明确错误而非崩）。
+     * 实现语义 = 定位活跃子进程 → 命令写入 → 读应答 → 状态回读 → 应答生效值
+     * （SetModelResult），竞态窗口处置见设计 §7.3。
+     */
+    setModel?(params: SetModelParams): Promise<SetModelResult>;
     dispose?(): Promise<void>;
 }
 /** ctx.ctxModel（"provider/id" canonical 词形）→ EngineCtxModel。 */

package/dist/port-contract.d.ts

@@ -1,4 +1,5 @@
-import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-DqOD58r-.js';
+import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-jSa1g28F.js';
+import { S as SetModelParams, a as SetModelResult } from './methods-C2zvZqhP.js';
 
 /**
  * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
@@ -125,6 +126,15 @@ interface EnginePort {
     validateModel?(modelRef: string | undefined): {
         canonicalRef: string;
     };
+    /**
+     * [subagent-model-switch §7.3] 可选面：执行中模型热切换（协议 setModel 正向方法的
+     * 进程内承载）。实现引擎须 capabilities.setModel = 'native' 同批声明（位与方法
+     * 成对进出——capabilities 注释的消费点登记）；server 分发行在位非 native 时回
+     * engineSetModelUnsupportedError 结构化错误（契约行为 = 明确错误而非崩）。
+     * 实现语义 = 定位活跃子进程 → 命令写入 → 读应答 → 状态回读 → 应答生效值
+     * （SetModelResult），竞态窗口处置见设计 §7.3。
+     */
+    setModel?(params: SetModelParams): Promise<SetModelResult>;
     dispose?(): Promise<void>;
 }
 /** ctx.ctxModel（"provider/id" canonical 词形）→ EngineCtxModel。 */

package/dist/protocol/index.cjs

@@ -34,12 +34,17 @@ __export(protocol_exports, {
   REVERSE_CHANNELS: () => REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS: () => REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS: () => REVERSE_REQUEST_TIMEOUT_MS,
+  SET_MODEL_ERROR_CODES: () => SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE: () => SET_MODEL_NOT_ACTIVE_CODE,
+  SET_MODEL_REQUEST_TIMEOUT_MS: () => SET_MODEL_REQUEST_TIMEOUT_MS,
+  SET_MODEL_STAGE_TIMEOUT_MS: () => SET_MODEL_STAGE_TIMEOUT_MS,
   STDERR_TAIL_CHARS: () => STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS: () => STDOUT_TAIL_ECHO_CHARS,
   SUPPORTED_PROTOCOL_RANGE: () => SUPPORTED_PROTOCOL_RANGE,
   assertChatConversationSupported: () => assertChatConversationSupported,
   engineConversationUnsupportedError: () => engineConversationUnsupportedError,
   engineProtocolMismatchError: () => engineProtocolMismatchError,
+  engineSetModelUnsupportedError: () => engineSetModelUnsupportedError,
   engineTimeoutDetail: () => engineTimeoutDetail,
   errorResponseFrameSchema: () => errorResponseFrameSchema,
   isEngineErrorPassthroughCode: () => isEngineErrorPassthroughCode,
@@ -68,6 +73,8 @@ function isProtocolVersionCompatible(version) {
 var REVERSE_REQUEST_TIMEOUT_MS = 1e4;
 var HANDSHAKE_TIMEOUT_MS = 1e4;
 var CANCEL_SETTLE_GRACE_MS = 3e3;
+var SET_MODEL_STAGE_TIMEOUT_MS = 3e3;
+var SET_MODEL_REQUEST_TIMEOUT_MS = 1e4;
 var STDERR_TAIL_CHARS = 400;
 
 // src/protocol/frames.ts
@@ -102,7 +109,8 @@ var PROTOCOL_METHODS = [
   "listModels",
   "validateModel",
   "dispose",
-  "ping"
+  "ping",
+  "setModel"
 ];
 
 // src/protocol/reverse-channels.ts
@@ -124,6 +132,19 @@ var REVERSE_CHANNEL_TIMEOUT_CLASS = {
 };
 
 // src/protocol/error-codes.ts
+var SET_MODEL_ERROR_CODES = [
+  /** 目标模型不在当前进程快照（子进程模型快照冻结于 spawn 时刻——模型本身有效，
+   *  下一轮 spawn 现取目录即可用；宿主按「写覆盖意图」处置，设计 §7.2 快照型失败行）。 */
+  "engine_model_not_in_snapshot",
+  /** 凭据校验失败（子进程 set_model checkAuth 抛错——宿主预检通过后 registry 态漂移
+   *  的权威兜底；宿主按校验型失败处置，设计 §7.5 凭据行）。 */
+  "engine_credential_missing",
+  /** 命令已发出（set_model 可能已执行）但读应答 / get_state 回读无回执、生效值未知
+   *  （非进程退出情形——退出归无活进程路径；宿主按「写覆盖意图 + 错误应答」处置，
+   *  设计 §7.5 回读失败行）。 */
+  "engine_state_readback_failed"
+];
+var SET_MODEL_NOT_ACTIVE_CODE = "engine_run_not_active";
 var ENGINE_PROTOCOL_ERROR_CODES = [
   "engine_not_found",
   "engine_protocol_mismatch",
@@ -133,7 +154,9 @@ var ENGINE_PROTOCOL_ERROR_CODES = [
   "engine_model_mismatch",
   "engine_handshake_timeout",
   "engine_crashed",
-  "engine_probe_failed"
+  "engine_probe_failed",
+  ...SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE
 ];
 function isEngineProtocolErrorCode(value) {
   return typeof value === "string" && ENGINE_PROTOCOL_ERROR_CODES.includes(value);
@@ -183,6 +206,14 @@ function assertChatConversationSupported(engineId, capabilities) {
     throw engineConversationUnsupportedError(engineId);
   }
 }
+function engineSetModelUnsupportedError(engineId, declared) {
+  return new EngineSdkError(
+    "engine_capability_unsupported",
+    `engine '${engineId}' does not support hot model switching (capabilities.setModel = ${declared ?? "unsupported (undeclared)"}); the host pre-check (design \xA77.2 step 2) must not dispatch setModel to it`,
+    `Route the switch to an engine that declares capabilities.setModel = 'native', or record the override for the next run instead. If this engine actually supports hot switching, fix the manifest capabilities declaration.`,
+    { engineId, capability: "setModel", declared: declared ?? "unsupported" }
+  );
+}
 var DETAIL_ECHO_MAX_CHARS = 200;
 var STDOUT_TAIL_ECHO_CHARS = 2e3;
 function truncate(text, max) {
@@ -364,12 +395,17 @@ var runSessionParamsSchema = {
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
+  SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE,
+  SET_MODEL_REQUEST_TIMEOUT_MS,
+  SET_MODEL_STAGE_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
   SUPPORTED_PROTOCOL_RANGE,
   assertChatConversationSupported,
   engineConversationUnsupportedError,
   engineProtocolMismatchError,
+  engineSetModelUnsupportedError,
   engineTimeoutDetail,
   errorResponseFrameSchema,
   isEngineErrorPassthroughCode,

package/dist/protocol/index.d.cts

@@ -1,6 +1,7 @@
-export { C as CancelParams, b as CancelResult, D as DisposeParams, c as DisposeResult, d as ENGINE_ERROR_CODE_PREFIX, e as ENGINE_PROTOCOL_ERROR_CODES, f as ENGINE_TIMEOUT_RECOVERY, g as EngineProtocolErrorCode, E as EngineSdkError, h as ErrorResponseFrame, i as EventNotificationParams, a as InitializeParams, I as InitializeResult, L as ListModelsParams, j as ListModelsResult, N as NotificationFrame, P as PROTOCOL_METHODS, k as PingParams, l as PingResult, m as ProbeParams, n as ProtocolError, o as ProtocolMethod, p as ProtocolParamsMap, q as ProtocolResultMap, r as ReadParams, s as RequestFrame, t as ResponseFrame, u as ReverseRequestFrame, v as ReverseResponseResult, R as RunContextParams, w as RunParams, x as RunResult, y as RunResumeParams, S as STDOUT_TAIL_ECHO_CHARS, z as SuccessResponseFrame, V as ValidateModelParams, A as ValidateModelResult, B as assertChatConversationSupported, F as engineConversationUnsupportedError, G as engineProtocolMismatchError, H as engineTimeoutDetail, J as isEngineErrorPassthroughCode, K as isEngineProtocolErrorCode, M as isNotificationFrame, O as isRequestFrame, Q as isResponseFrame, T as isReverseRequestFrame, U as schemaEmulationFailedDetail } from '../error-codes-C3oVToMr.cjs';
+export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_TIMEOUT_RECOVERY, d as EngineProtocolErrorCode, E as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, j as SET_MODEL_NOT_ACTIVE_CODE, k as STDOUT_TAIL_ECHO_CHARS, l as SetModelErrorCode, m as SuccessResponseFrame, n as assertChatConversationSupported, o as engineConversationUnsupportedError, p as engineProtocolMismatchError, q as engineSetModelUnsupportedError, r as engineTimeoutDetail, s as isEngineErrorPassthroughCode, t as isEngineProtocolErrorCode, u as isNotificationFrame, v as isRequestFrame, w as isResponseFrame, x as isReverseRequestFrame, y as schemaEmulationFailedDetail } from '../error-codes-f-UO4a8D.cjs';
+export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from '../methods-BLxg4ZFr.cjs';
 import { UiRequest, UiResponse } from '../ui-types.cjs';
-export { f as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, g as AgentEventTypeName, h as AgentFailureKind, c as AgentOutcome, i as AgentOutcomeUsage, j as AgentUsage, a as AgentUsageTotal, k as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, l as EngineProcessModel, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, m as ToolCall, n as ToolCallEntry, o as ToolCallResult, T as Turn, W as WorktreeHandle } from '../contract-types-DqOD58r-.cjs';
+export { g as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, h as AgentEventTypeName, i as AgentFailureKind, c as AgentOutcome, j as AgentOutcomeUsage, k as AgentUsage, a as AgentUsageTotal, l as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, I as InternalToolCall, f as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, n as ToolCall, o as ToolCallEntry, p as ToolCallResult, T as Turn, W as WorktreeHandle } from '../contract-types-jSa1g28F.cjs';
 
 /** 协议版本（引擎包 manifest `taiji.subagentEngine.protocol` 与 initialize 应答同值）。 */
 declare const ENGINE_PROTOCOL_VERSION = 1;
@@ -20,6 +21,20 @@ declare const REVERSE_REQUEST_TIMEOUT_MS = 10000;
 declare const HANDSHAKE_TIMEOUT_MS = 10000;
 /** cancel 后引擎收敛终态的窗口（ms）；超时 core 走杀链。 */
 declare const CANCEL_SETTLE_GRACE_MS = 3000;
+/**
+ * setModel 引擎侧单阶段控制窗（ms）：pi 实现等子进程 `set_model` 应答、等
+ * `get_state` 回读各占一窗（设计 subagent-model-switch §7.3——命令与回读全程带
+ * 存活检查，超时上限复用现役取消收敛窗量级：控制面单请求 = 秒级）。窗满且进程
+ * 仍存活 → `engine_state_readback_failed`；窗满时进程已退出 → 无活进程形态
+ * （`SET_MODEL_NOT_ACTIVE_CODE`）——两种处置不可混淆。
+ */
+declare const SET_MODEL_STAGE_TIMEOUT_MS = 3000;
+/**
+ * setModel 正向方法的宿主侧单请求上界（ms）：≥ 引擎侧两阶段最坏时延
+ * （2 × SET_MODEL_STAGE_TIMEOUT_MS）+ 协议余量；量级锚 = 数据面单请求
+ * REVERSE_REQUEST_TIMEOUT_MS 的 10s 先例（控制面单请求必须秒级有界——宿主不悬挂）。
+ */
+declare const SET_MODEL_REQUEST_TIMEOUT_MS = 10000;
 /** stderr 内存环形缓冲保留的尾部字符数（engine_crashed 帧携带崩溃现场）。 */
 declare const STDERR_TAIL_CHARS = 400;
 /**
@@ -138,7 +153,7 @@ declare const requestFrameSchema: {
         };
         readonly method: {
             readonly type: "string";
-            readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
+            readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping", "setModel"];
         };
         readonly params: {};
     };
@@ -260,7 +275,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
             };
             readonly method: {
                 readonly type: "string";
-                readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
+                readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping", "setModel"];
             };
             readonly params: {};
         };
@@ -431,4 +446,4 @@ declare const runSessionParamsSchema: {
     };
 };
 
-export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReverseChannel, type ReverseRequestTimeoutClass, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };
+export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReverseChannel, type ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };

package/dist/protocol/index.d.ts

@@ -1,6 +1,7 @@
-export { C as CancelParams, b as CancelResult, D as DisposeParams, c as DisposeResult, d as ENGINE_ERROR_CODE_PREFIX, e as ENGINE_PROTOCOL_ERROR_CODES, f as ENGINE_TIMEOUT_RECOVERY, g as EngineProtocolErrorCode, E as EngineSdkError, h as ErrorResponseFrame, i as EventNotificationParams, a as InitializeParams, I as InitializeResult, L as ListModelsParams, j as ListModelsResult, N as NotificationFrame, P as PROTOCOL_METHODS, k as PingParams, l as PingResult, m as ProbeParams, n as ProtocolError, o as ProtocolMethod, p as ProtocolParamsMap, q as ProtocolResultMap, r as ReadParams, s as RequestFrame, t as ResponseFrame, u as ReverseRequestFrame, v as ReverseResponseResult, R as RunContextParams, w as RunParams, x as RunResult, y as RunResumeParams, S as STDOUT_TAIL_ECHO_CHARS, z as SuccessResponseFrame, V as ValidateModelParams, A as ValidateModelResult, B as assertChatConversationSupported, F as engineConversationUnsupportedError, G as engineProtocolMismatchError, H as engineTimeoutDetail, J as isEngineErrorPassthroughCode, K as isEngineProtocolErrorCode, M as isNotificationFrame, O as isRequestFrame, Q as isResponseFrame, T as isReverseRequestFrame, U as schemaEmulationFailedDetail } from '../error-codes-CiDwaODz.js';
+export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_TIMEOUT_RECOVERY, d as EngineProtocolErrorCode, E as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, j as SET_MODEL_NOT_ACTIVE_CODE, k as STDOUT_TAIL_ECHO_CHARS, l as SetModelErrorCode, m as SuccessResponseFrame, n as assertChatConversationSupported, o as engineConversationUnsupportedError, p as engineProtocolMismatchError, q as engineSetModelUnsupportedError, r as engineTimeoutDetail, s as isEngineErrorPassthroughCode, t as isEngineProtocolErrorCode, u as isNotificationFrame, v as isRequestFrame, w as isResponseFrame, x as isReverseRequestFrame, y as schemaEmulationFailedDetail } from '../error-codes-DnFru4L4.js';
+export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from '../methods-C2zvZqhP.js';
 import { UiRequest, UiResponse } from '../ui-types.js';
-export { f as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, g as AgentEventTypeName, h as AgentFailureKind, c as AgentOutcome, i as AgentOutcomeUsage, j as AgentUsage, a as AgentUsageTotal, k as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, l as EngineProcessModel, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, m as ToolCall, n as ToolCallEntry, o as ToolCallResult, T as Turn, W as WorktreeHandle } from '../contract-types-DqOD58r-.js';
+export { g as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, h as AgentEventTypeName, i as AgentFailureKind, c as AgentOutcome, j as AgentOutcomeUsage, k as AgentUsage, a as AgentUsageTotal, l as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, I as InternalToolCall, f as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, n as ToolCall, o as ToolCallEntry, p as ToolCallResult, T as Turn, W as WorktreeHandle } from '../contract-types-jSa1g28F.js';
 
 /** 协议版本（引擎包 manifest `taiji.subagentEngine.protocol` 与 initialize 应答同值）。 */
 declare const ENGINE_PROTOCOL_VERSION = 1;
@@ -20,6 +21,20 @@ declare const REVERSE_REQUEST_TIMEOUT_MS = 10000;
 declare const HANDSHAKE_TIMEOUT_MS = 10000;
 /** cancel 后引擎收敛终态的窗口（ms）；超时 core 走杀链。 */
 declare const CANCEL_SETTLE_GRACE_MS = 3000;
+/**
+ * setModel 引擎侧单阶段控制窗（ms）：pi 实现等子进程 `set_model` 应答、等
+ * `get_state` 回读各占一窗（设计 subagent-model-switch §7.3——命令与回读全程带
+ * 存活检查，超时上限复用现役取消收敛窗量级：控制面单请求 = 秒级）。窗满且进程
+ * 仍存活 → `engine_state_readback_failed`；窗满时进程已退出 → 无活进程形态
+ * （`SET_MODEL_NOT_ACTIVE_CODE`）——两种处置不可混淆。
+ */
+declare const SET_MODEL_STAGE_TIMEOUT_MS = 3000;
+/**
+ * setModel 正向方法的宿主侧单请求上界（ms）：≥ 引擎侧两阶段最坏时延
+ * （2 × SET_MODEL_STAGE_TIMEOUT_MS）+ 协议余量；量级锚 = 数据面单请求
+ * REVERSE_REQUEST_TIMEOUT_MS 的 10s 先例（控制面单请求必须秒级有界——宿主不悬挂）。
+ */
+declare const SET_MODEL_REQUEST_TIMEOUT_MS = 10000;
 /** stderr 内存环形缓冲保留的尾部字符数（engine_crashed 帧携带崩溃现场）。 */
 declare const STDERR_TAIL_CHARS = 400;
 /**
@@ -138,7 +153,7 @@ declare const requestFrameSchema: {
         };
         readonly method: {
             readonly type: "string";
-            readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
+            readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping", "setModel"];
         };
         readonly params: {};
     };
@@ -260,7 +275,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
             };
             readonly method: {
                 readonly type: "string";
-                readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
+                readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping", "setModel"];
             };
             readonly params: {};
         };
@@ -431,4 +446,4 @@ declare const runSessionParamsSchema: {
     };
 };
 
-export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReverseChannel, type ReverseRequestTimeoutClass, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };
+export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReverseChannel, type ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };

package/dist/protocol/index.js

@@ -12,7 +12,7 @@ import {
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "../chunk-DIIYVO4O.js";
+} from "../chunk-LM7P7OTA.js";
 import {
   isNotificationFrame,
   isRequestFrame,
@@ -28,18 +28,23 @@ import {
   EngineSdkError,
   HANDSHAKE_TIMEOUT_MS,
   REVERSE_REQUEST_TIMEOUT_MS,
+  SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE,
+  SET_MODEL_REQUEST_TIMEOUT_MS,
+  SET_MODEL_STAGE_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
   SUPPORTED_PROTOCOL_RANGE,
   assertChatConversationSupported,
   engineConversationUnsupportedError,
   engineProtocolMismatchError,
+  engineSetModelUnsupportedError,
   engineTimeoutDetail,
   isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "../chunk-VDKR7MLG.js";
+} from "../chunk-JZN76I3S.js";
 import "../chunk-JSBRDJBE.js";
 export {
   AGENT_EVENT_TYPE_NAMES,
@@ -56,12 +61,17 @@ export {
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
+  SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE,
+  SET_MODEL_REQUEST_TIMEOUT_MS,
+  SET_MODEL_STAGE_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
   SUPPORTED_PROTOCOL_RANGE,
   assertChatConversationSupported,
   engineConversationUnsupportedError,
   engineProtocolMismatchError,
+  engineSetModelUnsupportedError,
   engineTimeoutDetail,
   errorResponseFrameSchema,
   isEngineErrorPassthroughCode,

package/dist/server/index.cjs

@@ -51,6 +51,32 @@ function toErrorMessage(e) {
 var ENGINE_PROTOCOL_VERSION = 1;
 
 // src/protocol/error-codes.ts
+var SET_MODEL_ERROR_CODES = [
+  /** 目标模型不在当前进程快照（子进程模型快照冻结于 spawn 时刻——模型本身有效，
+   *  下一轮 spawn 现取目录即可用；宿主按「写覆盖意图」处置，设计 §7.2 快照型失败行）。 */
+  "engine_model_not_in_snapshot",
+  /** 凭据校验失败（子进程 set_model checkAuth 抛错——宿主预检通过后 registry 态漂移
+   *  的权威兜底；宿主按校验型失败处置，设计 §7.5 凭据行）。 */
+  "engine_credential_missing",
+  /** 命令已发出（set_model 可能已执行）但读应答 / get_state 回读无回执、生效值未知
+   *  （非进程退出情形——退出归无活进程路径；宿主按「写覆盖意图 + 错误应答」处置，
+   *  设计 §7.5 回读失败行）。 */
+  "engine_state_readback_failed"
+];
+var SET_MODEL_NOT_ACTIVE_CODE = "engine_run_not_active";
+var ENGINE_PROTOCOL_ERROR_CODES = [
+  "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",
+  ...SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE
+];
 var EngineSdkError = class extends Error {
   code;
   recovery;

package/dist/server/index.d.cts

@@ -1,5 +1,6 @@
-import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-DqOD58r-.cjs';
-import { I as InitializeResult, R as RunContextParams, a as InitializeParams, E as EngineSdkError } from '../error-codes-C3oVToMr.cjs';
+import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-jSa1g28F.cjs';
+import { E as EngineSdkError } from '../error-codes-f-UO4a8D.cjs';
+import { I as InitializeResult, R as RunContextParams, b as InitializeParams } from '../methods-BLxg4ZFr.cjs';
 import { ReverseRequestClock } from '../spawn.cjs';
 import 'node:child_process';
 import '../env.cjs';
@@ -83,7 +84,7 @@ interface FrameLoopContext {
         result?: unknown;
         error?: unknown;
     }): void;
-    /** 正向请求分发（9 方法表；抛出的错误经 `toError` 转错误帧）。 */
+    /** 正向请求分发（引擎装配表；抛出的错误经 `toError` 转错误帧）。 */
     dispatch(id: number, method: string, params: unknown): unknown;
     /** 错误 → 错误帧载荷（各引擎的恢复指引文案不同，故由引擎注入）。 */
     toError(err: unknown): ProtocolErrorPayload;

package/dist/server/index.d.ts

@@ -1,5 +1,6 @@
-import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-DqOD58r-.js';
-import { I as InitializeResult, R as RunContextParams, a as InitializeParams, E as EngineSdkError } from '../error-codes-CiDwaODz.js';
+import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-jSa1g28F.js';
+import { E as EngineSdkError } from '../error-codes-DnFru4L4.js';
+import { I as InitializeResult, R as RunContextParams, b as InitializeParams } from '../methods-C2zvZqhP.js';
 import { ReverseRequestClock } from '../spawn.js';
 import 'node:child_process';
 import '../env.js';
@@ -83,7 +84,7 @@ interface FrameLoopContext {
         result?: unknown;
         error?: unknown;
     }): void;
-    /** 正向请求分发（9 方法表；抛出的错误经 `toError` 转错误帧）。 */
+    /** 正向请求分发（引擎装配表；抛出的错误经 `toError` 转错误帧）。 */
     dispatch(id: number, method: string, params: unknown): unknown;
     /** 错误 → 错误帧载荷（各引擎的恢复指引文案不同，故由引擎注入）。 */
     toError(err: unknown): ProtocolErrorPayload;

package/dist/server/index.js

@@ -8,7 +8,7 @@ import {
 import {
   ENGINE_PROTOCOL_VERSION,
   EngineSdkError
-} from "../chunk-VDKR7MLG.js";
+} from "../chunk-JZN76I3S.js";
 import "../chunk-JSBRDJBE.js";
 
 // src/server/index.ts

package/dist/spawn.cjs

@@ -98,6 +98,34 @@ function toErrorMessage(e) {
   return String(e);
 }
 
+// src/protocol/error-codes.ts
+var SET_MODEL_ERROR_CODES = [
+  /** 目标模型不在当前进程快照（子进程模型快照冻结于 spawn 时刻——模型本身有效，
+   *  下一轮 spawn 现取目录即可用；宿主按「写覆盖意图」处置，设计 §7.2 快照型失败行）。 */
+  "engine_model_not_in_snapshot",
+  /** 凭据校验失败（子进程 set_model checkAuth 抛错——宿主预检通过后 registry 态漂移
+   *  的权威兜底；宿主按校验型失败处置，设计 §7.5 凭据行）。 */
+  "engine_credential_missing",
+  /** 命令已发出（set_model 可能已执行）但读应答 / get_state 回读无回执、生效值未知
+   *  （非进程退出情形——退出归无活进程路径；宿主按「写覆盖意图 + 错误应答」处置，
+   *  设计 §7.5 回读失败行）。 */
+  "engine_state_readback_failed"
+];
+var SET_MODEL_NOT_ACTIVE_CODE = "engine_run_not_active";
+var ENGINE_PROTOCOL_ERROR_CODES = [
+  "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",
+  ...SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE
+];
+
 // src/kill-chain.ts
 var logger = getLogger("subagents");
 var MS_PER_SECOND = 1e3;

package/dist/spawn.js

@@ -5,10 +5,10 @@ import {
   armEngineSelfDestruct,
   pumpNdjsonLines,
   spawnEngineChild
-} from "./chunk-6QE3OODO.js";
-import "./chunk-EF2F5YOM.js";
+} from "./chunk-HSNDUHFH.js";
+import "./chunk-CNCFMPEH.js";
 import "./chunk-PYO3YR7W.js";
-import "./chunk-VDKR7MLG.js";
+import "./chunk-JZN76I3S.js";
 import "./chunk-NXNNXGTY.js";
 import "./chunk-JSBRDJBE.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-engine-sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Engine-side SDK for the subagent engine protocol: NDJSON stdio contract types, engine primitives (schema emulation, nesting guard, kill chain, journal replay projection, data-dir/paths resolution) — the shared contract root between subagent-core and engine CLI packages (engines import SDK only, never core)",
   "type": "module",
   "license": "MIT",