dsh-session-messaging 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-10-18
+
+### Added
+
+- Cold-session delivery: when a target session is not live, the plugin resumes
+  it through the deployment's `sessionController` before delivering. Enable or
+  disable it with the new `allowColdDelivery` config field (on by default).
+- `session_send` receipts now report `delivery: 'live' | 'resumed'`.
+- New `cold-delivery-failed` error code for a refused or failed resume.
+
+### Changed
+
+- Profiles without a session controller keep the previous `target-not-live`
+  refusal; archived/subagent-owned sessions are refused by the controller.
+
 ## [0.3.0] - 2026-10-18
 
 ### Added

package/README.md

@@ -56,7 +56,8 @@ The sidebar entry opens a small panel: toggle cross-directory messaging (persist
 - Advisory **write-scope conflict detection**: if a peer declared an overlapping path, the receipt and the message envelope carry a `conflict-warning`.
 - No new Session event types and no `SESSION_FORMAT_VERSION` change: the relay is a durable `user/message` with a declared `session-message` source.
 - Bilingual plugin-card metadata and icons (English / 简体中文) for the dsh plugin manager.
-- Bounded: message size, per-sender→target rate limit, top-level-only, live-only, self-send rejected. Cross-directory peers are allowed by default; `sameDirectoryOnly: true` restricts to one working directory.
+- **Cold-session delivery** — a persisted session that is not live is resumed through the Web/Desktop `sessionController` before delivery (`allowColdDelivery`, on by default).
+- Bounded: message size, per-sender→target rate limit, top-level-only, self-send rejected. Cross-directory peers are allowed by default; `sameDirectoryOnly: true` restricts to one working directory.
 
 ## How it works
 
@@ -87,7 +88,7 @@ The envelope always states that the message comes from another session, not the
 dsh plugin --profile <profile> add dsh-session-messaging
 ```
 
-The package is published as [`dsh-session-messaging`](https://www.npmjs.com/package/dsh-session-messaging) (latest `0.3.0`). For library use: `npm install dsh-session-messaging`.
+The package is published as [`dsh-session-messaging`](https://www.npmjs.com/package/dsh-session-messaging) (latest `0.4.0`). For library use: `npm install dsh-session-messaging`.
 
 ### From GitHub
 
@@ -103,6 +104,15 @@ The repository ships the built `lib/` output, so a git install does not run a bu
 dsh plugin --profile <profile> add /absolute/path/to/dsh-session-messaging
 ```
 
+### Troubleshooting: switching from a link install
+
+If a profile previously linked a local checkout and later installed the npm package **while the app was running**, the running Loader can still reference the old checkout path. Removing that checkout's `node_modules` then surfaces `ERR_MODULE_NOT_FOUND` for `@deepseek-ai/*` peers even though the npm package is installed. Remove and reinstall the bundle, then restart the app (a page reload is enough for the client half):
+
+```sh
+dsh plugin --profile <profile> remove dsh-session-messaging
+dsh plugin --profile <profile> add dsh-session-messaging@latest
+```
+
 ### Desktop app
 
 The macOS/Windows desktop app uses its own profiles (for example `desktop`). Install with the bundled CLI or the agent's `plugin_manager` tool, targeting that profile. In dsh `0.2.1-rc.2` the configuration reloads through HMR, so the two plugin rows usually activate without restarting the app.
@@ -148,13 +158,14 @@ The bundle row accepts validated configuration; every field has a default:
     requireTargetOptIn: false   # sessions are open to peers by default
     sameDirectoryOnly: false
     allowSelfSend: false
+    allowColdDelivery: true   # resume a persisted target when it is not live
 ```
 
 ## Security model and limitations
 
 - **Peer content is untrusted input.** It enters the target session as a user message. The envelope labels the sender and warns the model, but dsh has no content-approval point for peer messages; normal tool approvals, `agent/pre-step`, and sandbox policy remain the only hard boundaries.
 - **Top-level sessions only, in both directions.** A subagent session is neither listed nor allowed to send (`caller-not-top-level`), and a top-level session cannot target a subagent (`target-not-top-level`). Subagents keep using the existing parent/child `send_message` channel. The envelope `from` field is the trusted identity; any identity claim in the message body is data only.
-- **Same process only.** Discovery uses `ctx.agents`; a session that is not live cannot receive a message in this version. Cold-session delivery and cross-process/cross-host messaging are not implemented.
+- **Cold sessions are resumed, not queued.** When the target is not live and `allowColdDelivery` is on, the plugin calls the deployment's `sessionController.resolveAgent()`, which resumes that session and may start a model turn (token cost). Profiles without that controller still answer `target-not-live`. Archived or subagent-owned sessions are refused by the controller/session gate. Cross-process/cross-host messaging remains unimplemented.
 - **Advisory scopes, not locks.** dsh has optimistic filesystem version guards (`FS_STALE_VERSION`) but no file locking. `writeScopes` and `conflict-warning` are coordination aids; Bash, formatters, and code generators bypass them.
 - **In-memory state.** Reception pauses and declared scopes live for the plugin's lifetime and reset on reload/restart.
 - **Cross-directory by default.** Sessions in different working directories can message each other. Set `sameDirectoryOnly: true` to restore a path boundary; peer content remains untrusted either way.

package/README.zh-CN.md

@@ -52,7 +52,8 @@ macOS 桌面客户端（`0.2.1-rc.2`）真实运行：另一个用户启动的
 - 建议性**写范围冲突检测**：与 peer 声明重叠时，回执与消息信封带 `conflict-warning`。
 - 不新增 Session 事件类型、不改 `SESSION_FORMAT_VERSION`：消息就是带 `session-message` source 的 `user/message`。
 - 插件管理卡片提供中英双语标题、简介与图标（English / 简体中文）。
-- 有边界：长度上限、每 sender→target 限频、仅顶层、仅 live、拒绝自发送。默认允许跨目录对等会话；`sameDirectoryOnly: true` 可收紧为同工作目录。
+- **冷会话投递**：目标不在 live 列表时，通过 Web/Desktop 的 `sessionController` 恢复持久会话后再投递（`allowColdDelivery`，默认开启）。
+- 有边界：长度上限、每 sender→target 限频、仅顶层、拒绝自发送。默认允许跨目录对等会话；`sameDirectoryOnly: true` 可收紧为同工作目录。
 
 ## 工作原理
 
@@ -83,7 +84,7 @@ macOS 桌面客户端（`0.2.1-rc.2`）真实运行：另一个用户启动的
 dsh plugin --profile <profile> add dsh-session-messaging
 ```
 
-包已发布为 [`dsh-session-messaging`](https://www.npmjs.com/package/dsh-session-messaging)（最新 `0.3.0`）。库用法：`npm install dsh-session-messaging`。
+包已发布为 [`dsh-session-messaging`](https://www.npmjs.com/package/dsh-session-messaging)（最新 `0.4.0`）。库用法：`npm install dsh-session-messaging`。
 
 ### 从 GitHub 安装
 
@@ -99,6 +100,15 @@ dsh plugin --profile <profile> add github:XBXyftx/dsh-session-messaging
 dsh plugin --profile <profile> add /absolute/path/to/dsh-session-messaging
 ```
 
+### 排障：从本地 link 切换到 npm 安装
+
+如果 profile 之前 link 了本地源码，又在**应用运行中**安装了 npm 包，运行中的 Loader 可能仍引用旧源码路径；此时删除源码目录的 `node_modules` 会出现 `@deepseek-ai/*` 的 `ERR_MODULE_NOT_FOUND`，即使 npm 包已经安装。先移除再重装 bundle，然后重启应用（客户端部分刷新页面即可）：
+
+```sh
+dsh plugin --profile <profile> remove dsh-session-messaging
+dsh plugin --profile <profile> add dsh-session-messaging@latest
+```
+
 ### 桌面应用
 
 桌面应用使用自己的 profile（例如 `desktop`），用其内置 CLI 或 agent 的 `plugin_manager` 工具安装到该 profile。dsh `0.2.1-rc.2` 会通过 HMR 重载配置，通常无需重启应用即可激活。
@@ -142,13 +152,14 @@ dsh plugin --profile <profile> add /absolute/path/to/dsh-session-messaging
     requireTargetOptIn: false   # 默认对 peer 开放
     sameDirectoryOnly: false
     allowSelfSend: false
+    allowColdDelivery: true   # 目标不 live 时先恢复持久会话
 ```
 
 ## 安全模型与限制
 
 - **peer 内容是可信边界外的输入**：它以 user 消息进入目标会话，信封会标注来源并警告模型，但 dsh 没有针对 peer 消息的内容审批点；工具审批、`agent/pre-step` 与 sandbox 策略仍是唯一的硬边界。
 - **只允许顶层会话，收发两个方向都对称**：subagent 会话既不会出现在 peers 里，也不允许发送（`caller-not-top-level`）；顶层会话也不能把 subagent 作为目标（`target-not-top-level`）。subagent 继续使用既有的父子 `send_message` 通道。消息信封的 `from` 字段才是可信身份；正文里的任何身份自称都只是数据。
-- **仅同进程**：发现依赖 `ctx.agents`，非 live 会话本版无法接收；冷会话投递与跨进程/跨机器通信未实现。
+- **冷会话是“恢复后投递”，不是排队**：目标不 live 且 `allowColdDelivery` 开启时，插件调用部署的 `sessionController.resolveAgent()` 恢复该会话，可能启动模型 turn（产生 token 成本）。没有该服务的 profile 仍返回 `target-not-live`；归档或 subagent 拥有的会话会被控制器/会话门禁拒绝。跨进程/跨机器通信仍未实现。
 - **写范围只是建议，不是锁**：dsh 只有乐观版本守卫（`FS_STALE_VERSION`），没有文件锁；Bash、格式化器、代码生成器会绕过写范围提示。
 - **状态在内存**：暂停接收与写范围声明随插件生命周期存在，重载/重启后重置。
 - **默认允许跨目录**：不同工作目录的会话也可以互发消息。设置 `sameDirectoryOnly: true` 可恢复路径边界；无论是否限制，peer 内容都不可信。

package/lib/config.d.ts

@@ -21,6 +21,8 @@ export interface SessionMessagingConfig {
     readonly sameDirectoryOnly: boolean;
     /** Allow a session to relay to itself (diagnostics only; off by default). */
     readonly allowSelfSend: boolean;
+    /** Resume a persisted, non-live session through sessionController before delivery. */
+    readonly allowColdDelivery: boolean;
 }
 /** Schemastery schema for the plugin row's `config` block. */
 export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
@@ -29,12 +31,14 @@ export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
     requireTargetOptIn: Schema<boolean, boolean, "defined">;
     sameDirectoryOnly: Schema<boolean, boolean, "volatile-defined">;
     allowSelfSend: Schema<boolean, boolean, "defined">;
+    allowColdDelivery: Schema<boolean, boolean, "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     maxMessageChars: Schema<number, number, "defined">;
     maxMessagesPerMinute: Schema<number, number, "defined">;
     requireTargetOptIn: Schema<boolean, boolean, "defined">;
     sameDirectoryOnly: Schema<boolean, boolean, "volatile-defined">;
     allowSelfSend: Schema<boolean, boolean, "defined">;
+    allowColdDelivery: Schema<boolean, boolean, "defined">;
 }>>, "plain">;
 /** Plugin runtime config: volatile fields arrive as stable references. */
 export interface ResolvedSessionMessagingConfig extends Omit<SessionMessagingConfig, 'sameDirectoryOnly'> {

package/lib/config.js

@@ -13,4 +13,5 @@ export const Config = Schema.object({
     requireTargetOptIn: Schema.boolean().default(false),
     sameDirectoryOnly: Schema.boolean().default(false).volatile(),
     allowSelfSend: Schema.boolean().default(false),
+    allowColdDelivery: Schema.boolean().default(true),
 });

package/lib/protocol.d.ts

@@ -17,7 +17,7 @@ export declare const MAX_WRITE_SCOPES = 32;
 /** Maximum length of one declared write scope. */
 export declare const MAX_WRITE_SCOPE_CHARS = 200;
 /** Stable refusal reasons surfaced to callers and tests. */
-export type MessagingErrorCode = 'invalid-request' | 'caller-not-top-level' | 'self-send' | 'target-not-live' | 'target-not-top-level' | 'target-not-opted-in' | 'target-paused' | 'cross-directory' | 'rate-limited' | 'delivery-rejected';
+export type MessagingErrorCode = 'invalid-request' | 'caller-not-top-level' | 'self-send' | 'target-not-live' | 'target-not-top-level' | 'target-not-opted-in' | 'target-paused' | 'cold-delivery-failed' | 'cross-directory' | 'rate-limited' | 'delivery-rejected';
 /** Typed refusal that a tool call surfaces as an error result. */
 export declare class MessagingError extends Error {
     readonly code: MessagingErrorCode;
@@ -43,6 +43,8 @@ export interface SendReceipt {
     readonly targetStatus: 'idle' | 'running';
     /** Advisory overlaps with peers' declared write scopes; empty means none detected. */
     readonly conflicts: readonly ScopeConflict[];
+    /** Whether delivery used a live Agent or resumed a persisted session first. */
+    readonly delivery: 'live' | 'resumed';
 }
 /** One same-workspace peer as the model sees it. */
 export interface PeerView {

package/lib/service.d.ts

@@ -37,12 +37,14 @@ export declare class SessionMessagingService extends Service {
         requireTargetOptIn: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         sameDirectoryOnly: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
         allowSelfSend: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+        allowColdDelivery: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
         maxMessageChars: import("@deepseek-ai/schemastery").default<number, number, "defined">;
         maxMessagesPerMinute: import("@deepseek-ai/schemastery").default<number, number, "defined">;
         requireTargetOptIn: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         sameDirectoryOnly: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
         allowSelfSend: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+        allowColdDelivery: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
     }>>, "plain">;
     private readonly config;
     private readonly limiter;
@@ -80,7 +82,24 @@ export declare class SessionMessagingService extends Service {
      */
     private assertTopLevelCaller;
     /**
-     * Relay one message to a live peer session.
+     * Enforce per-target consent and the sender→target rate limit once.
+     * @param caller - sending agent.
+     * @param targetId - target session identity.
+     */
+    private checkConsentAndRate;
+    /**
+     * Resume a persisted, non-live session through the deployment's session
+     * controller. Web and Desktop mount one; profiles without it keep the
+     * `target-not-live` refusal.
+     * @param targetId - persisted session identity to resume.
+     * @returns the resumed live Agent.
+     * @throws {MessagingError} with `target-not-live` without a controller, or
+     *   `cold-delivery-failed` when resume refuses.
+     */
+    private resumeColdAgent;
+    /**
+     * Relay one message to a live peer session, resuming a persisted session
+     * first when `allowColdDelivery` is enabled.
      *
      * Success means the target agent accepted the message into its inbox and the
      * session flush acknowledged persistence. It does not mean the target model

package/lib/service.js

@@ -95,7 +95,53 @@ export class SessionMessagingService extends Service {
         throw new MessagingError('caller-not-top-level', `session ${caller.id} is not a user-launched top-level session; subagent sessions use the parent/child channel`);
     }
     /**
-     * Relay one message to a live peer session.
+     * Enforce per-target consent and the sender→target rate limit once.
+     * @param caller - sending agent.
+     * @param targetId - target session identity.
+     */
+    checkConsentAndRate(caller, targetId) {
+        const consent = this.consent.get(targetId);
+        if (this.config.requireTargetOptIn && consent?.enabled !== true) {
+            throw new MessagingError('target-not-opted-in', `session ${targetId} has not opted in to peer messages`);
+        }
+        if (consent?.enabled === false) {
+            throw new MessagingError('target-paused', `session ${targetId} has paused peer messages`);
+        }
+        const pairKey = `${caller.id}->${targetId}`;
+        if (!this.limiter.allow(pairKey, Date.now())) {
+            throw new MessagingError('rate-limited', `more than ${this.config.maxMessagesPerMinute} messages per minute were sent to this session`);
+        }
+    }
+    /**
+     * Resume a persisted, non-live session through the deployment's session
+     * controller. Web and Desktop mount one; profiles without it keep the
+     * `target-not-live` refusal.
+     * @param targetId - persisted session identity to resume.
+     * @returns the resumed live Agent.
+     * @throws {MessagingError} with `target-not-live` without a controller, or
+     *   `cold-delivery-failed` when resume refuses.
+     */
+    async resumeColdAgent(targetId) {
+        const controller = this.ctx.get('sessionController');
+        if (controller === undefined) {
+            throw new MessagingError('target-not-live', `session ${targetId} is not live and this profile has no session controller for cold resume`);
+        }
+        let resolved;
+        try {
+            resolved = await controller.resolveAgent(targetId);
+        }
+        catch (error) {
+            throw new MessagingError('cold-delivery-failed', `cold resume failed for ${targetId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if ('error' in resolved) {
+            const detail = resolved.error.message === undefined ? '' : ` (${resolved.error.message})`;
+            throw new MessagingError('cold-delivery-failed', `cold resume failed for ${targetId}: ${resolved.error.code ?? 'error'}${detail}`);
+        }
+        return resolved.agent;
+    }
+    /**
+     * Relay one message to a live peer session, resuming a persisted session
+     * first when `allowColdDelivery` is enabled.
      *
      * Success means the target agent accepted the message into its inbox and the
      * session flush acknowledged persistence. It does not mean the target model
@@ -130,9 +176,18 @@ export class SessionMessagingService extends Service {
             .filter(([sessionId]) => sessionId !== caller.id)
             .map(([sessionId, entry]) => ({ sessionId, scopes: entry.writeScopes }))
             .filter(peer => peer.scopes.length > 0));
-        const target = this.ctx.agents.get(targetId);
+        let target = this.ctx.agents.get(targetId);
+        let delivery = 'live';
+        let policyChecked = false;
         if (target === undefined) {
-            throw new MessagingError('target-not-live', `session ${targetId} is not live in this Harness process; cold-session delivery is not implemented yet`);
+            if (!this.config.allowColdDelivery) {
+                throw new MessagingError('target-not-live', `session ${targetId} is not live and cold-session delivery is disabled`);
+            }
+            // Check consent and rate limits before paying for a resume/turn.
+            this.checkConsentAndRate(caller, targetId);
+            policyChecked = true;
+            target = await this.resumeColdAgent(targetId);
+            delivery = 'resumed';
         }
         if (!isTopLevelSessionHeader(target.session.header)) {
             throw new MessagingError('target-not-top-level', `session ${targetId} is not a user-launched top-level session`);
@@ -140,17 +195,8 @@ export class SessionMessagingService extends Service {
         if (this.config.sameDirectoryOnly.get() && !sameDirectory(caller.session.header.cwd, target.session.header.cwd)) {
             throw new MessagingError('cross-directory', 'the target session works in a different directory');
         }
-        const consent = this.consent.get(targetId);
-        if (this.config.requireTargetOptIn && consent?.enabled !== true) {
-            throw new MessagingError('target-not-opted-in', `session ${targetId} has not opted in to peer messages`);
-        }
-        if (consent?.enabled === false) {
-            throw new MessagingError('target-paused', `session ${targetId} has paused peer messages`);
-        }
-        const pairKey = `${caller.id}->${targetId}`;
-        if (!this.limiter.allow(pairKey, Date.now())) {
-            throw new MessagingError('rate-limited', `more than ${this.config.maxMessagesPerMinute} messages per minute were sent to this session`);
-        }
+        if (!policyChecked)
+            this.checkConsentAndRate(caller, targetId);
         const messageId = `session-message-${randomUUID()}`;
         const text = buildRelayText({
             senderSessionId: caller.id,
@@ -182,6 +228,7 @@ export class SessionMessagingService extends Service {
             targetSessionId: targetId,
             targetStatus: target.status,
             conflicts,
+            delivery,
         };
     }
 }

package/lib/tools.js

@@ -89,6 +89,7 @@ export function apply(ctx) {
                     messageId: { type: 'string', required: true },
                     targetSessionId: { type: 'string', required: true },
                     targetStatus: { type: 'string', required: true, enum: ['idle', 'running'] },
+                    delivery: { type: 'string', required: true, enum: ['live', 'resumed'] },
                     conflicts: {
                         type: 'array',
                         required: true,
@@ -108,9 +109,10 @@ export function apply(ctx) {
                 const warning = value.conflicts.length === 0
                     ? ''
                     : ` Conflict warning: ${value.conflicts.map(conflict => `${conflict.sessionId} also declared ${conflict.scopes.join(', ')}`).join('; ')}. Coordinate before writing those paths.`;
+                const resumed = value.delivery === 'resumed' ? ' The target was a persisted session and was resumed for delivery.' : '';
                 return [{
                         type: 'text',
-                        text: `Message ${value.messageId} accepted by session ${value.targetSessionId} (${value.targetStatus}). Acceptance means the message is in that session's inbox; it does not confirm the peer processed it.${warning}`,
+                        text: `Message ${value.messageId} accepted by session ${value.targetSessionId} (${value.targetStatus}). Acceptance means the message is in that session's inbox; it does not confirm the peer processed it.${resumed}${warning}`,
                     }];
             },
             presentationMeta: (_args, value) => ({ targetSessionId: value.targetSessionId, messageId: value.messageId }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-messaging",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Peer messaging between user-launched sessions in one workspace: discover peers, relay coordination messages, pause reception, and get advisory write-scope conflict warnings.",
   "license": "MIT",
   "type": "module",
@@ -62,7 +62,8 @@
     "@deepseek-ai/dsh-llm": "^0.2.1-rc.2",
     "@deepseek-ai/dsh-session": "^0.2.1-rc.2",
     "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.5"
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "@deepseek-ai/dsh-api-session-controller": "^0.2.1-rc.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
@@ -73,13 +74,14 @@
     "@deepseek-ai/dsh-tools": "^0.2.1-rc.2",
     "@deepseek-ai/schemastery": "^3.18.5",
     "@types/node": "^24.0.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "@deepseek-ai/dsh-api-session-controller": "^0.2.1-rc.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --experimental-strip-types --test tests/protocol.test.ts",
-    "test:integration": "node --experimental-strip-types tests/integration-smoke.ts && node --experimental-strip-types tests/directory-policy-smoke.ts",
+    "test:integration": "node --experimental-strip-types tests/integration-smoke.ts && node --experimental-strip-types tests/directory-policy-smoke.ts && node --experimental-strip-types tests/cold-delivery-smoke.ts",
     "test:model-e2e": "node --experimental-strip-types tests/model-e2e-smoke.ts"
   },
   "dsh": {