dsh-session-bridge 0.3.1 → 0.3.2-alpha.2

package/README.md

@@ -119,13 +119,25 @@ time — not just its final reply — and act on it:
 # type-check + bundle the host build + pack a tgz (DSH_CHECKOUT points at the dsh source checkout)
 bash scripts/build.sh && npm run build:client
 
+# type-check src/ against the dsh that is actually installed (no checkout needed)
+npm run check:compat
+
 # via the injector toolchain
 dev_build_plugin dsh-session-bridge
 ```
 
 `build.sh` type-links against a local DSH checkout and is only for local dev.
+That checkout frequently lags the harness the plugin is loaded into, so a green
+`build.sh` does **not** prove the plugin works on the running DSH — `build.sh`
+warns when the two versions differ. Use `npm run check:compat` for that: it
+type-checks `src/` against the `lib/types/*.d.ts` shipped inside the installed
+DSH package, then reads the built `lib/index.js.map` to verify the
+self-contained bundle actually inlined that same DSH version. (Type-checking
+alone is not enough — a stale checkout type-checks green while the artifact
+ships old DSH code.)
+
 The GitHub Actions CI (`ci.yml`) instead resolves the `@deepseek-ai/dsh-*`
-prereleases from the registry — pinned to the `0.1.2-alpha.2` line, which is
+prereleases from the registry — pinned to the `0.1.6-alpha.2` line, which is
 the DSH API surface this code targets — then runs `pnpm typecheck` and
 `pnpm build:client` (the self-contained `tsdown` bundle). Bump that pin
 together with the code when you migrate to a newer DSH API.
@@ -149,6 +161,14 @@ publishing.
 npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-session-bridge
 ```
 
+A prerelease tag (`v0.3.2-alpha.1`) is published to its own dist-tag (`alpha`,
+`beta`, `rc`) instead of `latest`, so it cannot displace the stable release for
+other users. Opt in explicitly:
+
+```bash
+npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-session-bridge@alpha
+```
+
 pnpm installs the published tarball and runs its `prepare` script (`tsdown`) to
 ensure `lib/` is present, then `dsh` activates the bundle.
 
@@ -259,6 +279,19 @@ scripts/
   build.sh    type-check + link types against the DSH checkout
 ```
 
+## Lifecycle and unloading
+
+DSH ≥ 0.1.6 mounts and **unloads plugins at runtime** (Settings → Plugins, and
+the injector's hot reload). This plugin unloads cleanly: it registers no
+loader-level state, its tools are disposed with the plugin fiber, and the
+monitor's timer is released through `ctx.effect` on unload.
+
+One consequence of that ownership model: sessions created by
+`session_bridge_create` are owned by the plugin fiber (the agent is created
+under the plugin's context), so **unloading or reloading the plugin stops their
+live agents**. The sessions themselves are persisted and show as offline; bring
+one back with `session_bridge_resume`. Monitor watchdogs also stop on unload.
+
 ## License
 
 MIT

package/README.zh.md

@@ -87,10 +87,19 @@
 # 类型检查 + 打包 host bundle + 生成 tgz（DSH_CHECKOUT 指向 dsh 源码 checkout）
 bash scripts/build.sh && npm run build:client
 
+# 针对"实际安装的 dsh"做类型检查（不需要 checkout）
+npm run check:compat
+
 # 或经注入器工具链
 dev_build_plugin dsh-session-bridge
 ```
 
+`build.sh` 按本地 dsh 源码 checkout 做类型链接，仅用于本地开发。该 checkout 常常
+落后于插件实际加载进的 harness，因此 `build.sh` 通过**并不**代表插件在运行中的
+DSH 上可用——两者版本不一致时 `build.sh` 会给出警告。要验证运行版本请用
+`npm run check:compat`：它按已安装 DSH 包内随附的 `lib/types/*.d.ts`（即插件真正
+加载的 API 面）对 `src/` 做类型检查。
+
 ## 部署
 
 DSH web 从活动 profile 加载外部插件。本包是一个 **bundle**：`package.json` 声明了
@@ -107,6 +116,13 @@ DSH web 从活动 profile 加载外部插件。本包是一个 **bundle**：`pac
 npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-session-bridge
 ```
 
+预发布标签（`v0.3.2-alpha.1`）会发布到自己的 dist-tag（`alpha`/`beta`/`rc`），
+而不会占用 `latest`，因此不会顶掉其他用户使用的稳定版。需要显式选用：
+
+```bash
+npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-session-bridge@alpha
+```
+
 pnpm 会安装发布的 tarball 并运行其 `prepare` 脚本（`tsdown`）以确保 `lib/` 就绪，
 随后 `dsh` 激活该 bundle。
 
@@ -208,6 +224,17 @@ scripts/
   build.sh    类型检查 + 链接 DSH checkout 类型
 ```
 
+## 生命周期与卸载
+
+DSH ≥ 0.1.6 支持**运行时挂载/卸载**插件（设置 → 插件页开关、注入器热重载）。
+本插件可干净卸载：不注册 loader 级状态，工具随插件 fiber 一并释放，监控定时器
+经 `ctx.effect` 在卸载时清理。
+
+该所有权模型带来一个后果：`session_bridge_create` 创建的会话归插件 fiber 所有
+（agent 在插件上下文下创建），因此**卸载/重载插件会停止这些会话的活动 agent**。
+会话本身已持久化并显示为离线，可用 `session_bridge_resume` 重新上线；守护循环
+同样在卸载时停止。
+
 ## License
 
 MIT

package/dsh.plugin.json

@@ -1,10 +1,10 @@
 {
   "id": "dsh-external/dsh-session-bridge",
-  "version": "0.3.1",
+  "version": "0.3.2-alpha.2",
   "main": "./lib/index.js",
   "description": "会话桥：创建主会话 / 向任意会话发消息 / 等待回复 / 读取消息 / 按名或 id 查找会话（支持跨工作区）；另含监控/调度主任务与归档会话。",
   "engines": {
-    "dsh": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0"
+    "dsh": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0"
   },
   "contributes": {
     "tools": [

package/lib/index.js

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-//#region node_modules/.pnpm/@deepseek-ai+dsh-home-paths@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-home-paths/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-home-paths@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-home-paths/lib/index.js
 /**
 * Shared filesystem path helpers for DeepSeek Harness user data.
 *
@@ -2200,7 +2200,7 @@ var Service = class Service {
 	}
 };
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-typert-protocol@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-typert-protocol/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-typert-protocol@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-typert-protocol/lib/index.js
 /** The one Remote failure class shared by owners, the Gateway, and consumers. */
 /**
 * One Remote call failure: a real Error carrying its stable code and typed
@@ -2345,7 +2345,7 @@ function validateName(subject, value) {
 	if (!isTypertRemoteSegment(value)) throw new TypeError(`typert-protocol: ${subject} must contain only RPC endpoint segment characters`);
 }
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-util-values@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-util-values/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-util-values@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-util-values/lib/index.js
 /** Duplicate-install-safe JSON and immutable-value helpers. @module @deepseek-ai/dsh-util-values */
 /**
 * Mark an unreachable closed-union branch.
@@ -2557,7 +2557,7 @@ function deepFreeze(value) {
 	return value;
 }
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-util-crypto@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-util-crypto/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-util-crypto@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-util-crypto/lib/index.js
 /**
 * Random v4 UUID, minted from `crypto.getRandomValues`.
 * @returns the UUID string.
@@ -2570,7 +2570,7 @@ function randomUUID$1() {
 	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-brand@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-brand/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-brand@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-brand/lib/index.js
 /**
 * Duplicate-install-safe nominal primitive helpers.
 *
@@ -3187,11 +3187,11 @@ defineMethod("transform", [
 	"preserve"
 ], ({ inner }, isInner) => inner.toString(isInner));
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-timeout@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-timeout/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-timeout@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-timeout/lib/index.js
 /** Largest delay Node schedules without clamping it to one millisecond. */
 const MAX_TIMER_DELAY_MS = 2147483647;
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-llm@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-llm/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-llm@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-llm/lib/index.js
 /**
 * Bound one `notice` summary to {@link CONTEXT_SUMMARY_MAX_CHARS}.
 * @param summary - the producer's one-line account, of any length.
@@ -3441,13 +3441,15 @@ function failureSnapshot(value) {
 		const status = candidate.status;
 		const providerRetryAfterMs = candidate.providerRetryAfterMs;
 		const requestId = candidate.requestId;
-		if (typeof message !== "string" || message.length === 0 || typeof code !== "string" || code.length === 0 || status !== void 0 && (!Number.isInteger(status) || status < 100 || status > 599) || providerRetryAfterMs !== void 0 && (!Number.isFinite(providerRetryAfterMs) || providerRetryAfterMs <= 0) || requestId !== void 0 && (typeof requestId !== "string" || requestId.length === 0)) return void 0;
+		const offloadImages = candidate.offloadImages;
+		if (typeof message !== "string" || message.length === 0 || typeof code !== "string" || code.length === 0 || status !== void 0 && (!Number.isInteger(status) || status < 100 || status > 599) || providerRetryAfterMs !== void 0 && (!Number.isFinite(providerRetryAfterMs) || providerRetryAfterMs <= 0) || requestId !== void 0 && (typeof requestId !== "string" || requestId.length === 0) || offloadImages !== void 0 && (!Number.isSafeInteger(offloadImages) || offloadImages <= 0)) return void 0;
 		return Object.freeze({
 			message,
 			code,
 			...status === void 0 ? {} : { status },
 			...providerRetryAfterMs === void 0 ? {} : { providerRetryAfterMs },
-			...requestId === void 0 ? {} : { requestId }
+			...requestId === void 0 ? {} : { requestId },
+			...offloadImages === void 0 ? {} : { offloadImages }
 		});
 	} catch (_sdkFailureGetter) {
 		return;
@@ -3686,7 +3688,8 @@ var LlmError = class extends HarnessError {
 			code,
 			...options?.status === void 0 ? {} : { status: options.status },
 			...options?.providerRetryAfterMs === void 0 ? {} : { providerRetryAfterMs: options.providerRetryAfterMs },
-			...options?.requestId === void 0 ? {} : { requestId: options.requestId }
+			...options?.requestId === void 0 ? {} : { requestId: options.requestId },
+			...options?.offloadImages === void 0 ? {} : { offloadImages: options.offloadImages }
 		});
 	}
 };
@@ -3954,7 +3957,8 @@ var LlmError = class extends HarnessError {
 					id: model.id,
 					...model.name === void 0 ? {} : { name: model.name },
 					...model.contextWindow === void 0 ? {} : { contextWindow: model.contextWindow },
-					...model.maxTokens === void 0 ? {} : { maxTokens: model.maxTokens }
+					...model.maxTokens === void 0 ? {} : { maxTokens: model.maxTokens },
+					...model.inputModalities === void 0 ? {} : { inputModalities: [...model.inputModalities] }
 				});
 			}
 			return models;
@@ -9077,7 +9081,7 @@ function superRefine(fn, params) {
 	return /* @__PURE__ */ _superRefine(fn, params);
 }
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-storage@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-storage/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-storage@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2/node_modules/@deepseek-ai/dsh-storage/lib/index.js
 /**
 * Backend-facing vocabulary of the storage hub: a backend owns one medium
 * (a file-tree root, a database file) and exposes operation groups over it.
@@ -9088,7 +9092,7 @@ function superRefine(fn, params) {
 /** Allowed format for unit and table names: safe as a file name and as a SQL identifier segment without escaping. */
 const UNIT_NAME_RE = /^[a-z][a-z0-9_]*$/;
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-storage-domain@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2_@deepseek-ai+ds_8f094eabec231701d08ef59df76cca5d/node_modules/@deepseek-ai/dsh-storage-domain/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-storage-domain@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2_@deepseek-ai+ds_5fa439225de576bdb2338dd42cd57e82/node_modules/@deepseek-ai/dsh-storage-domain/lib/index.js
 /**
 * Domain declaration vocabulary. A spec object is the single source of a
 * domain's identity, layout, and record schemas: the owning package defines
@@ -9211,11 +9215,19 @@ Service.init;
 */
 /**
 * 兼容读取不同 dsh-session 版本上的会话事件：
-* - 旧版 `Session` 暴露 `get events(): readonly SessionEvent[]`；
-* - 新版（如宿主实际运行的 0.1.2-rc.x）将 `get events` 改为
-*   `snapshotEvents(fromSeq?, toSeqExclusive?)` 方法——`.events` 直接读取会
-*   得到 `undefined`，对 for...of 迭代即抛 `events is not iterable`。
+* - 旧版 \`Session\` 暴露 \`get events(): readonly SessionEvent[]\`；
+* - 新版将 \`get events\` 改为 \`snapshotEvents(fromSeq?, toSeqExclusive?)\` 方法——
+*   \`.events\` 直接读取会得到 \`undefined\`，对 for...of 迭代即抛
+*   \`events is not iterable\`。
 * 两者都读不到（或 session 不存在）时回退为空数组，绝不抛迭代错误。
+*
+* 注意：dsh 0.1.6-alpha.1 起 \`snapshotEvents()\`（连同 \`eventAt()\` /
+* \`ownEvents()\`）已标记 @deprecated —— 官方策略是"现有逻辑可暂不迁移，但禁止
+* 新增调用"；其替代不是同步读，而是（a）恢复后读取 Session 投影/派生状态，或
+* （b）按需异步分页读取历史窗口（见 dsh 决策
+* 2026-09-09-deprecate-synchronous-session-event-reads）。本函数的调用方
+* （foldMessages / segmentsSince / wait 基线）仍依赖完整同步快照，故按该决定暂缓
+* 迁移；将来官方补齐分页读后，只需改造这一个入口。
 */
 function sessionEvents(session) {
 	const s = session;
@@ -10038,7 +10050,7 @@ var SessionMonitor = class {
 	}
 };
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-scope@0.1.5-alpha.2_@deepseek-ai+cordis@4.0.2_@deepseek-ai+dsh-invaria_a35c65afc1061b4908fad5a531841731/node_modules/@deepseek-ai/dsh-scope/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-scope@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2_@deepseek-ai+dsh-invaria_8802cbeca2a66ef97a5b4e663664f4cd/node_modules/@deepseek-ai/dsh-scope/lib/index.js
 /**
 * Shared insertion-ordered storage and effect ownership for scope-aware registries.
 *
@@ -10317,7 +10329,89 @@ function scopeTarget(base, key) {
 	return carrier;
 }
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-tools@0.1.5-alpha.2_2b754afda902b21956a20e8a701ed6ef/node_modules/@deepseek-ai/dsh-tools/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-sandbox@0.1.6-alpha.2_@deepseek-ai+cordis@4.0.2_@deepseek-ai+dsh-llm@0_5328c6913d63e98a7878ca36cab93ca2/node_modules/@deepseek-ai/dsh-sandbox/lib/index.js
+/**
+* The escalation vocabulary and choreography shared by every sandbox-enforcing
+* tool family (`@deepseek-ai/dsh-tool-bash`, `@deepseek-ai/dsh-tool-fs`): the
+* strictly-wider ladder, the argument-pairing validation, the model-facing
+* denial/hint markers, and {@link approveEscalation} — the ordered fail-closed
+* sequence that resolves a `sandbox_permissions` request through a
+* user-approval channel BEFORE anything executes. One home keeps the two
+* families' approval ordering and verbatim error texts from drifting apart.
+*
+* The channel is a minimal STRUCTURAL function shape ({@link EscalationAsk}),
+* not the approval service type: the tool layer — which owns the agent, the
+* call id, and the tool name — closes over `ctx.approval.request(...)` and
+* hands the closure down, so this package never depends on the approval or
+* agent packages.
+*
+* @module dsh-sandbox/escalation
+*/
+/**
+* The strictly-wider table: what a call whose effective mode is the key may
+* escalate TO. Checked at EXECUTION, never baked into a tool schema — the
+* schema's enum is {@link ESCALATION_TARGETS}, because schemas are
+* registry-global while the effective mode is per-call truth.
+*/
+const WIDER_MODES = {
+	"read-only": ["workspace-write", "danger-full-access"],
+	"workspace-write": ["danger-full-access"]
+};
+/**
+* The closed escalation-target vocabulary — every mode a call could ever
+* escalate TO (`read-only` is the floor; nothing escalates to it). Advertised
+* whenever the mounted capability confines: cutting the enum down to the modes
+* wider than the composition's DEFAULT would strand a session whose effective
+* mode sits below it (a `danger-full-access` default would advertise nothing
+* while a narrower-switched session stays confined with no lever).
+*/
+const ESCALATION_TARGETS = ["workspace-write", "danger-full-access"];
+/**
+* Validate the escalation argument pairing a tool schema cannot express:
+* `sandbox_permissions` and `justification` travel together — an approval
+* prompt without a reason, or a reason driving nothing, is a malformed ask —
+* and the justification must be a non-empty sentence.
+* @param sandboxPermissions - the raw `sandbox_permissions` argument, if given.
+* @param justification - the raw `justification` argument, if given.
+*/
+function validateEscalationArgs(sandboxPermissions, justification) {
+	if (sandboxPermissions !== void 0 && justification === void 0) throw new Error("invalid escalation: sandbox_permissions requires a justification");
+	if (justification !== void 0 && sandboxPermissions === void 0) throw new Error("invalid escalation: justification is only valid together with sandbox_permissions");
+	if (justification !== void 0 && justification.trim().length === 0) throw new Error("invalid justification: expected a non-empty sentence");
+}
+/**
+* Resolve a sandbox permission request before execution. Repeating the call's
+* effective mode returns it without approval. A strictly wider mode requires
+* approval and applies only to this call. Narrower or unsupported targets,
+* missing approval services or agents for widening, and non-grant outcomes
+* throw before execution.
+* @param request - the escalation to judge (see {@link EscalationRequest}).
+* @param approval - the approval ingredients the tool holds (see {@link EscalationApproval}).
+* @returns the granted mode, consumed by the one call that asked.
+*/
+async function approveEscalation(request, approval) {
+	const { requestedMode: mode, effectiveMode, justification, subject } = request;
+	if (mode === effectiveMode) return effectiveMode;
+	if (!(WIDER_MODES[effectiveMode] ?? []).includes(mode)) throw new Error(`sandbox escalation to "${mode}" is not strictly wider than this call's current "${effectiveMode}" mode`);
+	if (approval.approver === void 0) throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval service is composed`);
+	if (approval.agent === void 0) throw new Error(`sandbox escalation to "${mode}" requires approval, but the call has no agent to route it through`);
+	const outcome = await approval.approver.request({
+		agent: approval.agent,
+		toolName: approval.toolName,
+		callId: approval.callId,
+		reason: `escalate sandbox to ${mode}: ${justification}`,
+		...approval.signal ? { signal: approval.signal } : {}
+	});
+	switch (outcome) {
+		case "allowed-once": return mode;
+		case "rejected": throw new Error(`the user rejected escalating this ${subject} to "${mode}"`);
+		case "cancelled": throw new Error(`approval for escalating to "${mode}" was cancelled`);
+		case "unavailable": throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval channel is available`);
+		default: return assertNever(outcome, "EscalationOutcome");
+	}
+}
+//#endregion
+//#region node_modules/.pnpm/@deepseek-ai+dsh-tools@0.1.6-alpha.2_e8d664b8446198a3dac4043bd11091d7/node_modules/@deepseek-ai/dsh-tools/lib/index.js
 /**
 * Enforced JSON Schema subset shared by tool outputs, generated PTC mode
 * types, subagents, and workflows. The subset accepts any JSON root, an
@@ -11188,7 +11282,7 @@ const TYPESCRIPT_FLAVOR = {
 	description: "Execute a TypeScript program against the available tools. Takes two required arguments: `code`, the BODY of an async function (erasable syntax only; top-level `await` and `return` work), and `description`, a short summary of what the program does. Call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return is program output — curate it. Image-bearing subtool results are attached after the run.",
 	codeDescription: "The program: the body of an async TypeScript function."
 };
-/** Per-language `run_code` schema flavors (see {@link RunCodeFlavor}); one entry per {@link CodeSdkLanguage}. */
+/** Per-language `run_code` schema flavors (see {@link RunCodeFlavor}); one entry per {@link PtcSdkLanguage}. */
 const RUN_CODE_FLAVORS = {
 	typescript: TYPESCRIPT_FLAVOR,
 	python: {
@@ -11203,17 +11297,48 @@ const RUN_CODE_FLAVORS = {
 * can never drift.
 */
 const RUN_CODE_DESCRIPTION_PARAM_DESCRIPTION = "Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\".";
+const RUN_CODE_CONTROLS = {
+	timeoutMs: {
+		type: "number",
+		description: "Positive elapsed-time budget in milliseconds, capped by the deployment maximum."
+	},
+	sandbox_permissions: {
+		type: "string",
+		enum: [...ESCALATION_TARGETS],
+		description: "Wider sandbox mode for this complete program execution; requires justification and approval."
+	},
+	justification: {
+		type: "string",
+		description: "Reason this complete program needs wider access, shown to the user for approval."
+	}
+};
+function controlParameters(runtime) {
+	if (runtime === void 0) return RUN_CODE_CONTROLS;
+	return {
+		...runtime.timeout === void 0 ? {} : { timeoutMs: {
+			...RUN_CODE_CONTROLS.timeoutMs,
+			description: `Positive elapsed-time budget in milliseconds, including nested tool and approval waits. Default ${runtime.timeout.defaultMs}; capped at ${runtime.timeout.maxMs}. Zero does not disable the deadline.`
+		} },
+		...runtime.sandboxMode === void 0 ? {} : {
+			sandbox_permissions: RUN_CODE_CONTROLS.sandbox_permissions,
+			justification: RUN_CODE_CONTROLS.justification
+		}
+	};
+}
+function escalationGuidance(runtime) {
+	return runtime?.sandboxMode === void 0 ? "" : " A sandbox escalation approves this complete program for one execution only. Nested tools retain their own policies and approvals. Request wider access only after evidence of a denial. Earlier effects may already have completed: inspect them before explicitly retrying. Programs are never replayed automatically.";
+}
 /**
 * Resolve the {@link RunCodeFlavor} for the loaded runtime's language, read at
 * schema-emission time so the model-visible `run_code` schema always matches
 * the SDK section's language. `peekRuntime` returns `undefined` only when no
 * runtime is mounted, which reaches this function through definition readers
 * and `schemas()` — the doc-catalog harvest is the only shipped one, and none
-* of them feeds a model, because `wireSchemas` calls `requireCodeRuntime`
+* of them feeds a model, because `wireSchemas` calls `requirePtcRuntime`
 * before projecting — so that path degrades to {@link TYPESCRIPT_FLAVOR}. A
 * mounted runtime whose language has no flavor entry fails loud, exactly as
-* `requireCodeRuntime` rejects it at assembly. Keeping this table in step with
-* `SDK_RENDERERS` is the compiler's job ({@link CodeSdkLanguage}); what this
+* `requirePtcRuntime` rejects it at assembly. Keeping this table in step with
+* `SDK_RENDERERS` is the compiler's job ({@link PtcSdkLanguage}); what this
 * guard owns is the runtime-supplied language neither table knows, which never
 * yields a wrong-language schema for a real runtime.
 */
@@ -11382,7 +11507,8 @@ function createRunCodeTool(registry, options) {
 				type: "string",
 				required: true,
 				description: RUN_CODE_DESCRIPTION_PARAM_DESCRIPTION
-			}
+			},
+			...RUN_CODE_CONTROLS
 		},
 		output: {
 			schema: {
@@ -11394,12 +11520,37 @@ function createRunCodeTool(registry, options) {
 						required: true,
 						items: { type: "string" }
 					},
-					result: { type: "json" }
+					result: { type: "json" },
+					sandbox: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							mode: {
+								type: "string",
+								required: true,
+								enum: [
+									"read-only",
+									"workspace-write",
+									"danger-full-access"
+								]
+							},
+							denied: {
+								type: "boolean",
+								required: true
+							},
+							enforcement: {
+								type: "string",
+								enum: ["full", "partial"]
+							}
+						}
+					}
 				}
 			},
 			render: (_args, value) => {
 				const rendered = value.result === void 0 ? "" : renderValue(value.result);
 				const parts = [value.logs.join("\n"), rendered].filter((part) => part.length > 0);
+				if (value.sandbox?.enforcement === "partial") parts.push("File sandbox enforcement is partial on this host.");
+				if (value.sandbox?.denied) parts.push(`The ${value.sandbox.mode} file sandbox denied an operation.${escalationGuidance(peekRuntime())}`);
 				return [{
 					type: "text",
 					text: parts.length > 0 ? parts.join("\n") : "(run_code completed with no output)"
@@ -11409,6 +11560,31 @@ function createRunCodeTool(registry, options) {
 		async execute(args, exec) {
 			if (args.description.trim().length === 0) throw new Error("invalid description: expected a non-empty string");
 			const runtime = requireRuntime();
+			validateEscalationArgs(args.sandbox_permissions, args.justification);
+			if (args.timeoutMs !== void 0 && runtime.timeout === void 0) throw new Error("timeoutMs is not available for this PTC runtime");
+			if (args.timeoutMs !== void 0 && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new Error("invalid timeoutMs: expected a positive finite number");
+			const standingPolicy = runtime.sandboxMode === void 0 ? void 0 : options.resolveSandboxPolicy(exec);
+			let policy = standingPolicy;
+			if (args.sandbox_permissions !== void 0 && args.justification !== void 0) {
+				if (standingPolicy === void 0) throw new Error("sandbox_permissions is not available for this PTC runtime");
+				const approvedMode = await approveEscalation({
+					requestedMode: args.sandbox_permissions,
+					justification: args.justification,
+					effectiveMode: standingPolicy.mode,
+					subject: "program"
+				}, {
+					approver: options.peekApprover(),
+					agent: exec.agent,
+					callId: exec.callId,
+					toolName: RUN_CODE_NAME,
+					signal: exec.signal
+				});
+				policy = {
+					...standingPolicy,
+					mode: approvedMode
+				};
+			}
+			exec.signal.throwIfAborted();
 			const runController = new AbortController();
 			const onOuterAbort = () => {
 				runController.abort(exec.signal.reason);
@@ -11490,7 +11666,8 @@ function createRunCodeTool(registry, options) {
 				while (logWork.size > 0) await Promise.allSettled([...logWork]);
 			};
 			const runOver = () => runController.signal.aborted;
-			const binding = (name) => async (rawArgs) => {
+			const binding = (schema) => async (rawArgs) => {
+				const { name } = schema;
 				if (runOver()) throw new Error(`run_code run is over (${String(runController.signal.reason)}); ${name} not dispatched`);
 				const normalized = jsonNormalizeArgs(rawArgs);
 				const n = ++dispatches;
@@ -11499,6 +11676,7 @@ function createRunCodeTool(registry, options) {
 					callId: subCallId,
 					rootCallId: exec.rootCallId,
 					name,
+					schema,
 					arguments: normalized.dispatched,
 					...exec.agent ? { agent: exec.agent } : {},
 					parent: exec.token,
@@ -11533,6 +11711,7 @@ function createRunCodeTool(registry, options) {
 								name,
 								arguments: normalized.logged,
 								isError: result.isError,
+								...result.error?.info === void 0 ? {} : { error: result.error.info },
 								content: logged
 							});
 						})().finally(() => {
@@ -11603,13 +11782,13 @@ function createRunCodeTool(registry, options) {
 				if (schema.name === "run_code") continue;
 				Object.defineProperty(functions, schema.name, {
 					enumerable: true,
-					value: binding(schema.name)
+					value: binding(deepFreeze(schema))
 				});
 			}
 			try {
 				let result;
 				try {
-					result = await runtime.run({
+					result = await runtime.run(runtime.resolve({
 						program: args.code,
 						bindings: [{
 							global: "tools",
@@ -11619,18 +11798,23 @@ function createRunCodeTool(registry, options) {
 								memberNameProperty: "toolName"
 							}
 						}],
-						signal: runController.signal
-					});
+						signal: runController.signal,
+						...exec.agent?.session.header.cwd !== void 0 ? { cwd: exec.agent.session.header.cwd } : {},
+						...policy !== void 0 ? { sandboxPolicy: policy } : {},
+						...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {}
+					}));
 				} finally {
 					runController.abort("run_code settled");
 					await drainDispatches();
 				}
 				if (result.error) {
 					const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join("\n")}` : "";
-					throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}`);
+					const sandboxText = result.sandbox === void 0 ? "" : `\nFile sandbox: ${result.sandbox.mode}${result.sandbox.enforcement === void 0 ? "" : `; enforcement: ${result.sandbox.enforcement}`}${result.sandbox.denied ? "; operation denied" : ""}.`;
+					throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}${sandboxText}${result.sandbox?.denied ? escalationGuidance(runtime) : ""}`);
 				}
 				return {
 					logs: result.logs,
+					...result.sandbox === void 0 ? {} : { sandbox: result.sandbox },
 					...result.value !== void 0 ? { result: result.value } : {}
 				};
 			} finally {
@@ -11646,7 +11830,11 @@ function createRunCodeTool(registry, options) {
 	});
 	Object.defineProperty(definition, "description", {
 		enumerable: true,
-		get: () => resolveFlavor(peekRuntime).description
+		get: () => {
+			const runtime = peekRuntime();
+			const instructions = runtime?.executionInstructions;
+			return resolveFlavor(peekRuntime).description + (instructions ? ` ${instructions}` : "") + (runtime === void 0 ? "" : " The working directory is the Session's current directory.") + escalationGuidance(runtime);
+		}
 	});
 	Object.defineProperty(definition, "parameters", {
 		enumerable: true,
@@ -11660,7 +11848,8 @@ function createRunCodeTool(registry, options) {
 				type: "string",
 				required: true,
 				description: RUN_CODE_DESCRIPTION_PARAM_DESCRIPTION
-			}
+			},
+			...controlParameters(peekRuntime())
 		})
 	});
 	return definition;
@@ -11945,7 +12134,7 @@ function renderToolsSdk(schemas) {
 * PTC mode codegen — Python flavor. The pure projection from registered tool schemas to the
 * Python SDK text the model programs against under `runtime.language === 'python'`. Sibling of
 * {@link ./ts-types.ts | ts-types.ts}; the two files are two projections of the same registry
-* store, keyed by the loaded {@link @deepseek-ai/dsh-code-runtime#CodeRuntime.language | code
+* store, keyed by the loaded {@link @deepseek-ai/dsh-ptc-runtime#PtcRuntime.language | PTC
 * runtime's language}.
 *
 * Under `mode: 'ptc'` the native tool schemas are omitted from the request, so this generated
@@ -12632,17 +12821,17 @@ function renderToolsSdkPy(schemas) {
 */
 /**
 * Language → SDK-section renderer. The registry looks up the loaded
-* `ctx.codeRuntime.language` in this table when assembling the `tools:sdk`
+* `ctx.ptcRuntime.language` in this table when assembling the `tools:sdk`
 * section under a non-native mode; a runtime whose language is not a key
 * fails the assembly loudly (same idiom as `toolOrder` violations). Adding a
-* new backend language is three parallel edits — a {@link CodeSdkLanguage}
+* new backend language is three parallel edits — a {@link PtcSdkLanguage}
 * member, an entry here, and a `RUN_CODE_FLAVORS` entry in `ptc.ts` for
 * its `run_code` schema strings — plus the renderer function this table points
 * at. The `satisfies` clause pins this table's key set to that union, which
 * the flavor table is checked against too, so any of the three left out is a
 * typecheck failure. What no check reaches is the prose that names the values
-* instead of deriving them: the seam's `dsh-code-runtime` README pair, its
-* `CodeRuntime.language` JSDoc, and `docs/subsystems/code-runtime.md`
+* instead of deriving them: the seam's `dsh-ptc-runtime` README pair, its
+* `PtcRuntime.language` JSDoc, and `docs/subsystems/ptc-runtime.md`
 * with its zh pair, plus this package's own README pair and the
 * {@link Config.mode} JSDoc.
 */
@@ -12881,12 +13070,13 @@ var ToolRuntime = class extends Service {
 		return {
 			name: "tools:sdk",
 			order: this.ctx.systemPrompt.getSectionOrder("TOOLS_SDK"),
+			interpolate: false,
 			text: (context) => {
 				const mode = this.modeFor(context.scope);
 				if (mode === "native") return "";
-				const runtime = this.requireCodeRuntime(mode);
+				const runtime = this.requirePtcRuntime(mode);
 				const render = SDK_RENDERERS[runtime.language];
-				/* v8 ignore next -- requireCodeRuntime rejects an unknown language before this runs. */
+				/* v8 ignore next -- requirePtcRuntime rejects an unknown language before this runs. */
 				if (render === void 0) throw new Error(`dsh-tools: no SDK renderer for ${runtime.language}`);
 				return render(this.sdkSchemas(context.scope));
 			}
@@ -12915,10 +13105,16 @@ var ToolRuntime = class extends Service {
 	* and only for scopes whose mode actually presents it.
 	* @returns the shared transport definition.
 	*/
-	requireCodeTransport() {
+	requirePtcTransport() {
 		this.ptcTransport ??= createRunCodeTool(this, {
-			requireRuntime: () => this.requireCodeRuntime(this.defaultMode),
-			peekRuntime: () => this.ctx.get("codeRuntime"),
+			requireRuntime: () => this.requirePtcRuntime(this.defaultMode),
+			peekApprover: () => this.ctx.get("approval"),
+			resolveSandboxPolicy: (exec) => {
+				const policy = this.ctx.get("sandboxPolicy");
+				if (policy === void 0) throw new Error("dsh-tools: confined PTC runtime requires sandboxPolicy");
+				return policy.resolve(exec.agent === void 0 ? {} : { session: exec.agent.session });
+			},
+			peekRuntime: () => this.ctx.get("ptcRuntime"),
 			maxParallel: this.maxParallelSubCalls,
 			shapeDispatchLog: (dispatch) => this.shapeDispatchLog(dispatch)
 		});
@@ -12963,7 +13159,7 @@ var ToolRuntime = class extends Service {
 			schemas: [...view.visible.values()].map((definition) => this.schemaOf(definition, false)),
 			knownNames: [...view.knownNames]
 		};
-		this.requireCodeRuntime(mode);
+		this.requirePtcRuntime(mode);
 		const schemas = [...view.visible.values()].map((definition) => this.schemaOf(definition, false));
 		if (mode === "ptc") return {
 			schemas: schemas.filter((schema) => schema.name === RUN_CODE_NAME),
@@ -12975,10 +13171,10 @@ var ToolRuntime = class extends Service {
 		};
 	}
 	/**
-	* Resolve the code runtime or throw the actionable misconfiguration error.
+	* Resolve the PTC runtime or throw the actionable misconfiguration error.
 	* Read at use time (assembly / run_code execution), NOT via static
 	* `inject`: an inject entry would hold `ctx.tools` — and every tool plugin
-	* behind it — hostage to a code runtime existing even under `mode:
+	* behind it — hostage to a PTC runtime existing even under `mode:
 	* 'native'`.
 	*
 	* Assembly and `run_code` execution read separately, so the language is not
@@ -12988,9 +13184,9 @@ var ToolRuntime = class extends Service {
 	* other. Binding it is deferred until a second backend ships (the first
 	* point it is testable).
 	*/
-	requireCodeRuntime(mode) {
-		const runtime = this.ctx.get("codeRuntime");
-		if (!runtime) throw new Error(`dsh-tools: mode "${mode}" requires a code runtime — load a ctx.codeRuntime implementation (e.g. @deepseek-ai/dsh-code-runtime-worker-thread) or set tools mode to "native"`);
+	requirePtcRuntime(mode) {
+		const runtime = this.ctx.get("ptcRuntime");
+		if (!runtime) throw new Error(`dsh-tools: mode "${mode}" requires a PTC runtime — load a ctx.ptcRuntime implementation (e.g. @deepseek-ai/dsh-ptc-runtime-node) or set tools mode to "native"`);
 		if (!Object.hasOwn(SDK_RENDERERS, runtime.language)) {
 			const known = Object.keys(SDK_RENDERERS).map((name) => JSON.stringify(name)).join(", ");
 			throw new Error(`dsh-tools: no SDK renderer registered for runtime language ${JSON.stringify(runtime.language)} (known: ${known})`);
@@ -13104,7 +13300,7 @@ var ToolRuntime = class extends Service {
 			knownNames.add(name);
 			visible.set(name, definition);
 		}
-		if (this.modeFor(scope) !== "native") visible.set(RUN_CODE_NAME, this.requireCodeTransport());
+		if (this.modeFor(scope) !== "native") visible.set(RUN_CODE_NAME, this.requirePtcTransport());
 		return {
 			visible,
 			knownNames,
@@ -13275,6 +13471,7 @@ var ToolRuntime = class extends Service {
 			signal,
 			...agent !== void 0 ? { agent } : {},
 			...parent !== void 0 ? { parent } : {},
+			...exec.schema !== void 0 ? { schema: exec.schema } : {},
 			deferContext(context) {
 				deferredContexts.push(context);
 			},
@@ -13357,7 +13554,13 @@ var ToolRuntime = class extends Service {
 				exec,
 				result: toolAbortedBeforeDispatchResult()
 			});
+			if (decision.kind === "cancel") return await next({
+				kind: "post-result",
+				exec,
+				result: toolAbortedBeforeDispatchResult()
+			});
 			const denialReason = decision.kind === "allow" ? this.guardReason(exec) : decision.reason;
+			const denialInfo = decision.kind === "deny" ? decision.info : void 0;
 			if (denialReason !== void 0) return await next({
 				kind: "post-result",
 				exec,
@@ -13367,7 +13570,10 @@ var ToolRuntime = class extends Service {
 						text: `Error: ${denialReason}`
 					}],
 					isError: true,
-					error: { message: denialReason }
+					error: {
+						message: denialReason,
+						...denialInfo === void 0 ? {} : { info: denialInfo }
+					}
 				})
 			});
 			if (this.callerCancelled(exec)) return await next({
@@ -13818,7 +14024,7 @@ function toolAbortedBeforeDispatchResult(prior) {
 	};
 }
 //#endregion
-//#region node_modules/.pnpm/@deepseek-ai+dsh-agent@0.1.5-alpha.2_cfc1690176e5c008b05d52ad11161b75/node_modules/@deepseek-ai/dsh-agent/lib/index.js
+//#region node_modules/.pnpm/@deepseek-ai+dsh-agent@0.1.6-alpha.2_44110910133b3cc261ea9dfdcaed39ee/node_modules/@deepseek-ai/dsh-agent/lib/index.js
 /**
 * Agent-scoped model selection shared by runtime entry points.
 * @module @deepseek-ai/dsh-agent/model-selection
@@ -14057,8 +14263,10 @@ function registerCreate(env) {
 					...model !== "" ? { model } : {},
 					...reasoningEffort === void 0 ? {} : { reasoningEffort }
 				},
-				setup: (agentCtx) => {
-					if (caller !== void 0) env.ctx.agentPresets.composeFrom(agentCtx, caller.ctx);
+				setup: async (agentCtx) => {
+					const requestedPreset = typeof args.agentPreset === "string" && args.agentPreset.trim() !== "" ? args.agentPreset.trim() : void 0;
+					if (requestedPreset !== void 0) await env.ctx.agentPresets.mount(agentCtx, requestedPreset);
+					else if (caller !== void 0) env.ctx.agentPresets.composeFrom(agentCtx, caller.ctx);
 					if (installModelSelection$1 !== void 0) {
 						installModelSelection$1(agentCtx, selection);
 						return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-bridge",
-  "version": "0.3.1",
+  "version": "0.3.2-alpha.2",
   "description": "会话桥（dsh-session-bridge）：通过提示词创建新的主会话（顶层 UI 会话）、向任意会话发送消息、等待会话的下一条回复、读取会话消息，并按会话名或 id 跨工作区查找会话；此外支持监控/调度主任务与归档会话。",
   "private": false,
   "type": "module",
@@ -52,28 +52,28 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-workspace": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-workspace": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-brand": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-util-values": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
-    "@deepseek-ai/dsh-workspace": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-brand": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-util-values": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
+    "@deepseek-ai/dsh-workspace": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.5-0 || ^0.1.6-0",
     "@types/node": "^24.0.0",
     "cordis": "^4.0.0-rc.7",
     "tsdown": "^0.22.14",
@@ -82,6 +82,7 @@
   "scripts": {
     "build": "bash scripts/build.sh",
     "build:client": "tsdown",
+    "check:compat": "node scripts/check-dsh-compat.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/scripts/build.sh

@@ -14,6 +14,24 @@ if [ -z "$CHECKOUT" ] || [ ! -d "$CHECKOUT/packages" ]; then
   exit 1
 fi
 
+# The type-check below runs against $DSH_CHECKOUT, which commonly lags the dsh
+# that actually loads this plugin — a stale checkout type-checks green while the
+# running harness has already moved on. Warn loudly rather than implying support.
+read_pkg_version() {
+  node -e "try{process.stdout.write(String(require(process.argv[1]).version))}catch(e){process.stdout.write('unknown')}" "$1" 2>/dev/null || echo unknown
+}
+CHECKOUT_VERSION="$(read_pkg_version "$CHECKOUT/package.json")"
+INSTALLED_VERSION="unknown"
+GLOBAL_ROOT="$(npm root -g 2>/dev/null | head -n1 || true)"
+if [ -n "$GLOBAL_ROOT" ] && [ -f "$GLOBAL_ROOT/@deepseek-ai/dsh/package.json" ]; then
+  INSTALLED_VERSION="$(read_pkg_version "$GLOBAL_ROOT/@deepseek-ai/dsh/package.json")"
+fi
+if [ "$INSTALLED_VERSION" != "unknown" ] && [ "$CHECKOUT_VERSION" != "$INSTALLED_VERSION" ]; then
+  echo "build: WARNING — checkout is $CHECKOUT_VERSION but the installed dsh is $INSTALLED_VERSION." >&2
+  echo "build: the type-check below therefore does NOT cover the running harness;" >&2
+  echo "build: run 'npm run check:compat' to type-check against the installed dsh." >&2
+fi
+
 TSC="$CHECKOUT/node_modules/.bin/tsc"
 if [ ! -x "$TSC" ]; then
   echo "build: tsc not found at $TSC" >&2

package/scripts/check-dsh-compat.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * Type-check src/ against the DSH packages that are ACTUALLY INSTALLED,
+ * rather than against $DSH_CHECKOUT.
+ *
+ * Why this exists: scripts/build.sh type-checks against a DSH *source* checkout.
+ * That checkout routinely lags the harness the plugin is loaded into (e.g. the
+ * checkout sat at 0.1.5-alpha.2 while the running harness was 0.1.6-alpha.1), so
+ * a green `build.sh` silently proves nothing about the running version. This
+ * script reads the `lib/types/*.d.ts` that ship inside the installed DSH npm
+ * package, i.e. the exact API surface the plugin loads against — so an upstream
+ * break shows up here even when the checkout is stale.
+ *
+ * Usage:
+ *   node scripts/check-dsh-compat.mjs [--dsh <path>]
+ *
+ * <path> may be either the DSH package directory or the `@deepseek-ai` scope
+ * directory that holds dsh-session, dsh-agent, ... . When omitted, the installed
+ * location is probed (DSH_INSTALLED_MODULES, then `npm root -g`).
+ *
+ * Exits 0 when the plugin's src/ type-checks against those types, 1 otherwise.
+ */
+import { execFileSync, execSync } from 'node:child_process'
+import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** Read a JSON file, or return undefined when it is absent/unreadable. */
+function readJson(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return undefined }
+}
+
+/** True when `dir` looks like the `@deepseek-ai` scope directory. */
+function isScopeDir(dir) {
+  return dir !== undefined && existsSync(join(dir, 'dsh-session', 'package.json'))
+}
+
+/**
+ * Resolve the `@deepseek-ai` scope directory holding the installed DSH packages.
+ * Accepts an explicit path (package dir or scope dir) and otherwise probes.
+ */
+function resolveScopeDir(argv) {
+  const flagAt = argv.indexOf('--dsh')
+  const explicit = flagAt !== -1 ? argv[flagAt + 1] : (process.env.DSH_INSTALLED_MODULES ?? undefined)
+  const candidates = []
+  if (explicit !== undefined && explicit !== '') {
+    const base = resolve(explicit)
+    // Accept the scope dir itself, the dsh package dir, or a node_modules tree.
+    candidates.push(base, join(base, 'node_modules', '@deepseek-ai'), join(base, '@deepseek-ai'))
+  }
+
+  // Anchor 1: the global install root. execSync (string command) rather than
+  // execFileSync, because npm is a .cmd shim on Windows that cannot be spawned
+  // without a shell.
+  let globalRoot
+  try {
+    globalRoot = execSync('npm root -g', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  } catch { globalRoot = undefined }
+  if (globalRoot !== undefined && globalRoot !== '') {
+    // npm layout, then the common "dsh nests its own deps" layout.
+    candidates.push(join(globalRoot, '@deepseek-ai'), join(globalRoot, '@deepseek-ai', 'dsh', 'node_modules', '@deepseek-ai'))
+  }
+
+  // Anchor 2: walk up from the `dsh` executable itself. Its path is usually a
+  // symlink (scoop/volta), so resolve it first or the walk misses the real tree.
+  try {
+    const found = execSync(process.platform === 'win32' ? 'where dsh' : 'which dsh', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .split(/\r?\n/).map((line) => line.trim()).filter((line) => line !== '')
+    for (const line of found) {
+      let dir
+      try { dir = dirname(realpathSync(line)) } catch { dir = dirname(line) }
+      for (let hop = 0; hop < 4 && dir !== dirname(dir); hop++) {
+        candidates.push(join(dir, 'node_modules', '@deepseek-ai', 'dsh', 'node_modules', '@deepseek-ai'))
+        candidates.push(join(dir, 'node_modules', '@deepseek-ai'))
+        dir = dirname(dir)
+      }
+    }
+  } catch { /* dsh not on PATH; the other anchors decide */ }
+
+  for (const candidate of candidates) if (isScopeDir(candidate)) return candidate
+  return undefined
+}
+
+/** Resolve a package's types entry point inside the scope directory. */
+function typesEntry(scope, pkg) {
+  const dir = join(scope, pkg)
+  const manifest = readJson(join(dir, 'package.json'))
+  if (manifest === undefined) return undefined
+  const declared = typeof manifest.types === 'string' ? manifest.types : undefined
+  const candidates = [
+    ...(declared !== undefined ? [join(dir, declared)] : []),
+    join(dir, 'lib', 'types', 'index.d.ts'),
+    join(dir, 'index.d.ts'),
+  ]
+  return candidates.find((c) => existsSync(c))
+}
+
+function fail(message) {
+  console.error('check-dsh-compat: ' + message)
+  process.exit(1)
+}
+
+const scope = resolveScopeDir(process.argv.slice(2))
+if (scope === undefined) {
+  fail('could not locate the installed DSH packages. Pass --dsh <path> (the DSH package dir or its @deepseek-ai scope dir) or set DSH_INSTALLED_MODULES.')
+}
+
+/** Read the version of the `dsh` package that owns this scope directory. */
+function dshVersionOf(scopeDir) {
+  // Nested layout puts dsh two levels above its own scope dir; a flat global
+  // install puts it beside the other packages.
+  for (const candidate of [join(scopeDir, 'dsh', 'package.json'), join(scopeDir, '..', '..', 'package.json')]) {
+    const manifest = readJson(candidate)
+    if (manifest?.name === '@deepseek-ai/dsh' && typeof manifest.version === 'string') return manifest.version
+  }
+  return undefined
+}
+
+/**
+ * Inspect the built tsdown bundle's source map for the DSH version it INLINED.
+ *
+ * `check:compat` type-checks src/ against the installed harness, but src/ is not
+ * what loads: lib/index.js is a self-contained bundle that inlines every
+ * @deepseek-ai/* import. A stale checkout therefore type-checks green while the
+ * artifact ships old DSH code (observed: checkout 0.1.5-alpha.2 / host
+ * 0.1.6-alpha.2). This reads the map's sources — a checkout path names the root
+ * whose package.json carries the version; a .pnpm path encodes it.
+ *
+ * @returns { versions: Set<string>, roots: Set<string> } or undefined when no map exists.
+ */
+function artifactProvenance() {
+  const mapPath = join(ROOT, 'lib', 'index.js.map')
+  if (!existsSync(mapPath)) return undefined
+  let map
+  try { map = JSON.parse(readFileSync(mapPath, 'utf8')) } catch { return undefined }
+  const versions = new Set()
+  const roots = new Set()
+  for (const source of Array.isArray(map.sources) ? map.sources : []) {
+    if (typeof source !== 'string') continue
+    // Source checkout: <root>/packages/... or <root>/vendor/... (relative to the map in lib/).
+    const checkout = source.match(/^(.*?)[/\\](?:packages|vendor)[/\\]/)
+    if (checkout !== null) { roots.add(resolve(ROOT, 'lib', checkout[1])); continue }
+    // Registry install: .../.pnpm/@deepseek-ai+<name>@<version>[_hash]/node_modules/...
+    const registry = source.match(/[\\/]\.pnpm[\\/]@deepseek-ai\+[a-z0-9-]+@([^\\/]+)[\\/]node_modules/)
+    if (registry !== null) {
+      const version = registry[1].replace(/_.*$/, '')
+      if (/^\d/.test(version)) versions.add(version)
+    }
+  }
+  for (const root of roots) {
+    const manifest = readJson(join(root, 'package.json'))
+    if (typeof manifest?.version === 'string') versions.add(manifest.version)
+  }
+  return { versions, roots }
+}
+
+const dshVersion = dshVersionOf(scope) ?? '(unknown)'
+
+// Every DSH package src/ imports, plus the plain `cordis` specifier that
+// package.json declares as a peer.
+const manifest = readJson(join(ROOT, 'package.json')) ?? {}
+const declared = [...Object.keys(manifest.peerDependencies ?? {}), ...Object.keys(manifest.devDependencies ?? {})]
+const wanted = new Set(declared.filter((name) => name.startsWith('@deepseek-ai/')))
+wanted.add('@deepseek-ai/cordis')
+wanted.add('@deepseek-ai/schemastery')
+
+const paths = {}
+const missing = []
+for (const name of [...wanted].sort()) {
+  const entry = typesEntry(scope, name.slice('@deepseek-ai/'.length))
+  if (entry === undefined) { missing.push(name); continue }
+  paths[name] = [entry]
+}
+// tsconfig.json maps the bare `cordis` specifier; keep that working under the
+// installed layout too, where cordis is published scoped.
+if (paths['@deepseek-ai/cordis'] !== undefined) paths['cordis'] = paths['@deepseek-ai/cordis']
+
+if (missing.length > 0) {
+  fail('installed DSH is missing the packages this plugin imports: ' + missing.join(', ') + '\n  (looked in ' + scope + ')')
+}
+
+// The generated config must live in the repo root: tsconfig.json's `include`
+// is relative to the config that declares it, so a config placed elsewhere
+// would look for src/ in the wrong directory. Every mapped path is absolute,
+// so only `include`/`extends` depend on the location. Removed again below.
+const configPath = join(ROOT, '.dsh-compat.tsconfig.json')
+writeFileSync(configPath, JSON.stringify({ extends: './tsconfig.json', compilerOptions: { paths } }, null, 2))
+
+// Run tsc's JS entry through the current node binary. Spawning the .bin shell
+// shim instead would need a shell on Windows (npm .cmd/.bat shims cannot be
+// spawned directly), and this way the exit code and output stay unambiguous.
+const tsc = join(ROOT, 'node_modules', 'typescript', 'bin', 'tsc')
+if (!existsSync(tsc)) { rmSync(configPath, { force: true }); fail('local typescript not found at ' + tsc + ' (run the package manager install first)') }
+
+console.log('check-dsh-compat: type-checking src/ against installed dsh ' + dshVersion)
+console.log('check-dsh-compat: scope ' + scope)
+let failure
+try {
+  execFileSync(process.execPath, [tsc, '-p', configPath, '--noEmit'], { cwd: ROOT, stdio: 'inherit' })
+} catch (error) {
+  failure = error
+} finally {
+  rmSync(configPath, { force: true })
+}
+if (failure !== undefined) {
+  const status = typeof failure.status === 'number' ? ' (tsc exit ' + failure.status + ')' : ''
+  fail('src/ does NOT type-check against installed dsh ' + dshVersion + status + ' — this is a real incompatibility with the running harness.')
+}
+console.log('check-dsh-compat: OK — src/ type-checks against installed dsh ' + dshVersion)
+
+const provenance = artifactProvenance()
+if (provenance === undefined) {
+  console.log('check-dsh-compat: no lib/index.js.map — skipping bundle provenance check (run pnpm build:client to enable it)')
+} else if (provenance.versions.size === 0) {
+  console.log('check-dsh-compat: bundle provenance not resolvable from the source map — skipped')
+} else {
+  const inlined = [...provenance.versions].sort().join(', ')
+  console.log('check-dsh-compat: lib/index.js inlined DSH ' + inlined + ' (from ' + provenance.roots.size + ' checkout(s) / registry entries)')
+  if (dshVersion !== '(unknown)' && !(provenance.versions.size === 1 && provenance.versions.has(dshVersion))) {
+    fail('the built lib/index.js inlines DSH ' + inlined + ' but the installed harness is ' + dshVersion
+      + ' — rebuild the bundle against the running harness (a stale checkout type-checks green while shipping old DSH code).')
+  }
+}

package/src/core.ts

@@ -64,11 +64,19 @@ export interface BridgeFindItem {
 
 /**
  * 兼容读取不同 dsh-session 版本上的会话事件：
- * - 旧版 `Session` 暴露 `get events(): readonly SessionEvent[]`；
- * - 新版（如宿主实际运行的 0.1.2-rc.x）将 `get events` 改为
- *   `snapshotEvents(fromSeq?, toSeqExclusive?)` 方法——`.events` 直接读取会
- *   得到 `undefined`，对 for...of 迭代即抛 `events is not iterable`。
+ * - 旧版 \`Session\` 暴露 \`get events(): readonly SessionEvent[]\`；
+ * - 新版将 \`get events\` 改为 \`snapshotEvents(fromSeq?, toSeqExclusive?)\` 方法——
+ *   \`.events\` 直接读取会得到 \`undefined\`，对 for...of 迭代即抛
+ *   \`events is not iterable\`。
  * 两者都读不到（或 session 不存在）时回退为空数组，绝不抛迭代错误。
+ *
+ * 注意：dsh 0.1.6-alpha.1 起 \`snapshotEvents()\`（连同 \`eventAt()\` /
+ * \`ownEvents()\`）已标记 @deprecated —— 官方策略是"现有逻辑可暂不迁移，但禁止
+ * 新增调用"；其替代不是同步读，而是（a）恢复后读取 Session 投影/派生状态，或
+ * （b）按需异步分页读取历史窗口（见 dsh 决策
+ * 2026-09-09-deprecate-synchronous-session-event-reads）。本函数的调用方
+ * （foldMessages / segmentsSince / wait 基线）仍依赖完整同步快照，故按该决定暂缓
+ * 迁移；将来官方补齐分页读后，只需改造这一个入口。
  */
 export function sessionEvents(session: unknown): readonly SessionEvent[] {
   const s = session as {

package/src/tools.ts

@@ -194,8 +194,16 @@ function registerCreate(env: BridgeEnv): void {
           ...(model !== '' ? { model } : {}),
           ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
         },
-        setup: (agentCtx: Context) => {
-          if (caller !== undefined) {
+        setup: async (agentCtx: Context) => {
+          const requestedPreset = typeof args.agentPreset === 'string' && args.agentPreset.trim() !== '' ? args.agentPreset.trim() : undefined
+          if (requestedPreset !== undefined) {
+            // An explicit agentPreset composes THAT preset. Falling through to the
+            // caller-join below would silently ignore the request: the id would
+            // still reach the session header, while the agent kept running on the
+            // caller's standing composition and its tools.
+            const presets = env.ctx.agentPresets as unknown as { mount(agentCtx: Context, id: string): Promise<unknown> }
+            await presets.mount(agentCtx, requestedPreset)
+          } else if (caller !== undefined) {
             const presets = env.ctx.agentPresets as unknown as { composeFrom(agentCtx: Context, parentCtx: Context): string | undefined }
             presets.composeFrom(agentCtx, caller.ctx)
           }