dsh-session-messaging 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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
+
+- A client-side sidebar panel, “Session Messaging”, with:
+  - a cross-directory toggle persisted through the dsh settings form
+    (`sameDirectoryOnly` is now a volatile config field);
+  - an npm update check against the published package;
+  - links to npm, GitHub, and the author's blog.
+
+### Changed
+
+- The `sameDirectoryOnly` config field is volatile, so the panel can edit it
+  at runtime without editing the profile patch by hand.
+
 ## [0.2.0] - 2026-10-18
 
 ### Changed

package/README.md

@@ -40,16 +40,24 @@ Two user-launched sessions used the plugin to coordinate a real fix. One session
 
 See [CHANGELOG.md](CHANGELOG.md) for the `0.1.2` entry.
 
+### Settings panel
+
+![Session Messaging settings panel](docs/assets/panel.webp)
+
+The sidebar entry opens a small panel: toggle cross-directory messaging (persisted through the dsh settings form), check the latest npm version, and open npm, GitHub, or the author's blog. After installing or upgrading the bundle, refresh the Web UI once so the client half joins the module graph.
+
 ## Features
 
 - `session_peers` — list live, same-directory, top-level sessions and their reception state.
 - `session_send` — relay a coordination message, optionally declaring `writeScopes` and replying to a message.
 - `session_reception` — pause/resume receiving peer messages for the current session and declare its write scopes.
+- **Sidebar panel** — a “Session Messaging” entry in the left sidebar with a cross-directory toggle, update check, and author links.
 - Messages appear inline in the target conversation, attributed to the sending session — no separate inbox UI.
 - 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
 
@@ -80,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.2.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
 
@@ -96,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.
@@ -141,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

@@ -36,16 +36,24 @@ macOS 桌面客户端（`0.2.1-rc.2`）真实运行：另一个用户启动的
 
 `0.1.2` 的变更见 [CHANGELOG.md](CHANGELOG.md)。
 
+### 设置面板
+
+![跨会话消息设置面板](docs/assets/panel.webp)
+
+侧边栏入口打开一个设置面板：切换跨目录消息（通过 dsh 设置表单持久化）、检查 npm 最新版本，并打开 npm / GitHub / 作者博客。安装或升级 bundle 后刷新一次 Web UI，客户端模块才会进入模块图。
+
 ## 功能
 
 - `session_peers`：列出同目录、live 的顶层会话及其接收状态。
 - `session_send`：发送协调消息，可附带 `writeScopes` 与 `replyTo`。
 - `session_reception`：暂停/恢复本会话接收对等消息，并声明写范围。
+- **侧边栏面板**：左侧“跨会话消息”入口，提供跨目录开关、版本更新检查与作者链接。
 - 消息直接内联显示在目标会话中，来源归属于发送会话，不需要独立收件箱。
 - 建议性**写范围冲突检测**：与 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` 可收紧为同工作目录。
 
 ## 工作原理
 
@@ -76,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.2.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 安装
 
@@ -92,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 重载配置，通常无需重启应用即可激活。
@@ -135,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/client/client.js

@@ -0,0 +1,242 @@
+/**
+ * Browser half: a sidebar entry and its panel for session-messaging settings,
+ * update check, and author links. Built as a ModuleLoader factory (see the
+ * dsh plugin UI template); the Host half carries the service and tools.
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-session-messaging',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+    const NS = 'session-messaging'
+    const PANEL_ID = 'session-messaging'
+    const PACKAGE_NAME = 'dsh-session-messaging'
+    const FALLBACK_VERSION = '0.3.0'
+    const NPM_URL = 'https://www.npmjs.com/package/dsh-session-messaging'
+    const GITHUB_URL = 'https://github.com/XBXyftx/dsh-session-messaging'
+    const BLOG_URL = 'https://xbxyftx.top'
+
+    const zh = {
+      'panel.label': '跨会话消息',
+      'page.title': '跨会话消息',
+      'page.subtitle': '让同一 Host 内的多个用户会话互相发消息、协调任务与写入范围。',
+      'setting.title': '允许跨工作目录消息',
+      'setting.desc': '开启后，不同工作目录的顶层会话也能互相发现和发送消息。',
+      'setting.unavailable': '设置服务当前不可用，无法在线修改。',
+      'setting.loading': '正在读取配置…',
+      'setting.saveFailed': '保存失败，请重试。',
+      'update.title': '版本更新',
+      'update.checking': '正在检查更新…',
+      'update.upToDate': '已是最新版本',
+      'update.available': '发现新版本',
+      'update.failed': '更新检查失败',
+      'update.button': '检查更新',
+      'author.title': '作者',
+      'author.desc': '由 XBXyftx 开发，MIT 开源。',
+      'links.npm': 'npm',
+      'links.github': 'GitHub',
+      'links.blog': '作者博客',
+    }
+    const en = {
+      'panel.label': 'Session Messaging',
+      'page.title': 'Session Messaging',
+      'page.subtitle': 'Let user-launched sessions in the same Host message each other, coordinate tasks, and declare write scopes.',
+      'setting.title': 'Allow cross-directory messages',
+      'setting.desc': 'When on, top-level sessions in different working directories can discover and message each other.',
+      'setting.unavailable': 'The settings service is unavailable; this value cannot be edited here.',
+      'setting.loading': 'Reading configuration…',
+      'setting.saveFailed': 'Saving failed. Try again.',
+      'update.title': 'Updates',
+      'update.checking': 'Checking for updates…',
+      'update.upToDate': 'Up to date',
+      'update.available': 'Update available',
+      'update.failed': 'Update check failed',
+      'update.button': 'Check for updates',
+      'author.title': 'Author',
+      'author.desc': 'Built by XBXyftx. MIT licensed.',
+      'links.npm': 'npm',
+      'links.github': 'GitHub',
+      'links.blog': 'Blog',
+    }
+
+    const color = {
+      text: 'var(--dsw-alias-label-primary)',
+      secondary: 'var(--dsw-alias-label-secondary)',
+      border: 'var(--dsw-alias-border-l1)',
+      surface: 'var(--dsw-alias-bg-layer-1)',
+      accent: 'var(--dsw-alias-brand-primary)',
+      error: 'var(--dsw-alias-state-error-primary)',
+    }
+    const pageStyle = {
+      display: 'flex', flexDirection: 'column', gap: 16, width: '100%',
+      maxWidth: 760, margin: '0 auto', padding: '28px 32px', boxSizing: 'border-box',
+      color: color.text, overflowY: 'auto',
+    }
+    const cardStyle = {
+      display: 'flex', flexDirection: 'column', gap: 14,
+      background: color.surface, border: `1px solid ${color.border}`,
+      borderRadius: 12, padding: 18,
+    }
+    const rowStyle = { display: 'flex', alignItems: 'center', gap: 16, justifyContent: 'space-between' }
+    const titleStyle = { fontSize: 15, fontWeight: 600, margin: 0, color: color.text }
+    const descStyle = { fontSize: 13, lineHeight: 1.5, margin: '6px 0 0', color: color.secondary }
+    const linkStyle = { color: color.accent, textDecoration: 'none', fontSize: 13 }
+    const buttonStyle = {
+      appearance: 'none', border: `1px solid ${color.border}`, borderRadius: 8,
+      background: 'transparent', color: color.text, padding: '6px 12px',
+      fontSize: 13, cursor: 'pointer',
+    }
+
+    function Icon({ size = 16 }) {
+      return h('svg', {
+        viewBox: '0 0 24 24', width: size, height: size, fill: 'none',
+        stroke: 'currentColor', strokeWidth: 1.8, strokeLinecap: 'round',
+        strokeLinejoin: 'round', 'aria-hidden': true, style: { display: 'block' },
+      },
+      h('path', { d: 'M4 6a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2H8l-4 3z' }),
+      h('path', { d: 'M9 13h9a2 2 0 0 1 2 2v3a2 2 0 0 1-2 2h-2l-3 2v-2h-4a2 2 0 0 1-2-2z' }))
+    }
+
+    function compareVersions(a, b) {
+      const pa = String(a).split('-')[0].split('.').map(Number)
+      const pb = String(b).split('-')[0].split('.').map(Number)
+      for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+        const x = pa[i] ?? 0
+        const y = pb[i] ?? 0
+        if (x !== y) return x - y
+      }
+      return 0
+    }
+
+    function Panel({ t, form, loadCurrentVersion }) {
+      const snapshot = React.useSyncExternalStore(
+        React.useCallback(listener => form.subscribe(listener), [form]),
+        React.useCallback(() => form.getSnapshot(), [form]),
+        React.useCallback(() => form.getSnapshot(), [form]),
+      )
+      const [saving, setSaving] = React.useState(false)
+      const [saveFailed, setSaveFailed] = React.useState(false)
+      const [currentVersion, setCurrentVersion] = React.useState(FALLBACK_VERSION)
+      const [update, setUpdate] = React.useState({ status: 'checking', latest: undefined })
+      const ready = snapshot.status === 'ready'
+      const enabled = (snapshot.value && snapshot.value.sameDirectoryOnly) === true
+
+      const check = React.useCallback(async () => {
+        setUpdate(previous => ({ ...previous, status: 'checking' }))
+        try {
+          const response = await fetch('https://registry.npmjs.org/dsh-session-messaging/latest')
+          if (!response.ok) throw new Error(String(response.status))
+          const data = await response.json()
+          setUpdate({ status: 'done', latest: typeof data.version === 'string' ? data.version : undefined })
+        } catch (_error) {
+          setUpdate({ status: 'failed', latest: undefined })
+        }
+      }, [])
+
+      React.useEffect(() => {
+        let cancelled = false
+        void loadCurrentVersion().then(version => { if (!cancelled) setCurrentVersion(version) })
+        void check()
+        return () => { cancelled = true }
+      }, [check, loadCurrentVersion])
+
+      const toggle = async () => {
+        if (!ready || saving) return
+        setSaving(true)
+        setSaveFailed(false)
+        try {
+          const accepted = await form.set('sameDirectoryOnly', !enabled)
+          if (!accepted) setSaveFailed(true)
+        } catch (_error) {
+          setSaveFailed(true)
+        } finally {
+          setSaving(false)
+        }
+      }
+
+      const newer = update.status === 'done' && update.latest !== undefined
+        && compareVersions(update.latest, currentVersion) > 0
+
+      const settingHint = snapshot.status === 'loading'
+        ? t('setting.loading')
+        : snapshot.status === 'unavailable'
+          ? t('setting.unavailable')
+          : saveFailed ? t('setting.saveFailed') : t('setting.desc')
+
+      return h('div', { style: pageStyle },
+        h('div', null,
+          h('h1', { style: { fontSize: 22, fontWeight: 650, margin: 0 } }, t('page.title')),
+          h('p', { style: { ...descStyle, fontSize: 14, marginTop: 6 } }, t('page.subtitle')),
+        ),
+        h('section', { style: cardStyle },
+          h('div', { style: rowStyle },
+            h('div', null,
+              h('h2', { style: titleStyle }, t('setting.title')),
+              h('p', { style: { ...descStyle, color: saveFailed ? color.error : color.secondary } }, settingHint),
+            ),
+            h('input', {
+              type: 'checkbox', checked: enabled, disabled: !ready || saving,
+              onChange: () => { void toggle() }, 'aria-label': t('setting.title'),
+              style: { width: 18, height: 18, accentColor: color.accent, cursor: ready ? 'pointer' : 'default' },
+            }),
+          ),
+        ),
+        h('section', { style: cardStyle },
+          h('div', { style: rowStyle },
+            h('div', null,
+              h('h2', { style: titleStyle }, t('update.title')),
+              h('p', { style: descStyle },
+                update.status === 'checking' ? t('update.checking')
+                  : update.status === 'failed' ? t('update.failed')
+                    : newer ? `${t('update.available')} · v${update.latest}`
+                      : `${t('update.upToDate')} · v${currentVersion}`),
+            ),
+            h('button', { type: 'button', style: buttonStyle, onClick: () => { void check() }, disabled: update.status === 'checking' },
+              t('update.button')),
+          ),
+          newer ? h('a', { href: NPM_URL, target: '_blank', rel: 'noreferrer', style: linkStyle }, t('links.npm') + ' · v' + update.latest) : null,
+        ),
+        h('section', { style: cardStyle },
+          h('div', { style: rowStyle },
+            h('div', null,
+              h('h2', { style: titleStyle }, t('author.title')),
+              h('p', { style: descStyle }, t('author.desc')),
+            ),
+            h('div', { style: { display: 'flex', gap: 14 } },
+              h('a', { href: NPM_URL, target: '_blank', rel: 'noreferrer', style: linkStyle }, t('links.npm')),
+              h('a', { href: GITHUB_URL, target: '_blank', rel: 'noreferrer', style: linkStyle }, t('links.github')),
+              h('a', { href: BLOG_URL, target: '_blank', rel: 'noreferrer', style: linkStyle }, t('links.blog')),
+            ),
+          ),
+        ),
+      )
+    }
+
+    return {
+      inject: ['slots', 'locale', 'configForms', 'remote', 'remote.pluginManager'],
+      apply(ctx) {
+        const t = ctx.locale.bind(NS)
+        ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-session-messaging: locale')
+        const form = ctx.configForms.get(PANEL_ID)
+
+        const currentVersion = () => ctx.remote.pluginManager.listBundles()
+          .then(rows => {
+            const rowsArray = Array.isArray(rows) ? rows : []
+            const own = rowsArray.find(row => row && row.name === PACKAGE_NAME)
+            return own && typeof own.version === 'string' ? own.version : FALLBACK_VERSION
+          })
+          .catch(() => FALLBACK_VERSION)
+
+        ctx.slots.inject('main', () => ctx.slots.register({
+          name: 'main', key: PANEL_ID, locale: NS,
+          inject: () => ({ t, form, loadCurrentVersion: currentVersion }),
+        }, Panel))
+
+        ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
+          name: 'sidebar.panellist', id: PANEL_ID, order: 5,
+          label: () => t('panel.label'), locale: NS,
+        }, Icon))
+      },
+    }
+  },
+})

package/lib/config.d.ts

@@ -13,10 +13,36 @@ export interface SessionMessagingConfig {
     readonly maxMessagesPerMinute: number;
     /** Require the target session to opt in before it can receive peer messages. Off by default: sessions are mutually visible and can message each other unless they pause reception. */
     readonly requireTargetOptIn: boolean;
-    /** Restrict peers to the sender's working directory. Off by default: cross-directory peers are allowed. */
+    /**
+     * Restrict peers to the sender's working directory. Off by default:
+     * cross-directory peers are allowed. Declared volatile so the sidebar panel
+     * can edit it through the dsh settings form.
+     */
     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<SessionMessagingConfig>;
+export declare const Config: Schema<Schemastery.ObjectS<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">;
+}>>, 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'> {
+    readonly sameDirectoryOnly: {
+        get(): boolean;
+    };
+}

package/lib/config.js

@@ -11,6 +11,7 @@ export const Config = Schema.object({
     maxMessageChars: Schema.number().min(1).default(DEFAULT_MAX_MESSAGE_CHARS),
     maxMessagesPerMinute: Schema.number().min(1).default(DEFAULT_MAX_MESSAGES_PER_MINUTE),
     requireTargetOptIn: Schema.boolean().default(false),
-    sameDirectoryOnly: 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

@@ -9,7 +9,7 @@
 import { Service, type Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import { Config } from './config.ts';
-import type { SessionMessagingConfig } from './config.ts';
+import type { ResolvedSessionMessagingConfig } from './config.ts';
 import type { PeerView, SendReceipt, SendRequest } from './protocol.ts';
 /** One session's receive consent and advisory write scopes. */
 interface ConsentEntry {
@@ -31,7 +31,21 @@ declare module '@deepseek-ai/cordis' {
 export declare class SessionMessagingService extends Service {
     static inject: string[];
     /** Loader-read configuration schema; defaults apply when the row omits `config`. */
-    static Config: import("@deepseek-ai/schemastery").default<SessionMessagingConfig>;
+    static Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<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">;
+    }>>, 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;
     private readonly consent;
@@ -39,7 +53,7 @@ export declare class SessionMessagingService extends Service {
      * @param ctx - Cordis context with `agents` and `sessions` ready.
      * @param config - validated plugin configuration.
      */
-    constructor(ctx: Context, config: SessionMessagingConfig);
+    constructor(ctx: Context, config: ResolvedSessionMessagingConfig);
     /**
      * List live user-launched peers the caller may address.
      * @param caller - the agent whose tool call is inspecting peers.
@@ -68,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

@@ -47,7 +47,7 @@ export class SessionMessagingService extends Service {
                 continue;
             if (!isTopLevelSessionHeader(candidate.session.header))
                 continue;
-            if (this.config.sameDirectoryOnly && !sameDirectory(callerDirectory, candidate.session.header.cwd)) {
+            if (this.config.sameDirectoryOnly.get() && !sameDirectory(callerDirectory, candidate.session.header.cwd)) {
                 continue;
             }
             const consent = this.consent.get(candidate.id);
@@ -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,27 +176,27 @@ 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`);
         }
-        if (this.config.sameDirectoryOnly && !sameDirectory(caller.session.header.cwd, target.session.header.cwd)) {
+        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.2.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",
@@ -15,6 +15,7 @@
       "types": "./lib/tools.d.ts",
       "default": "./lib/tools.js"
     },
+    "./client": "./client/client.js",
     "./locale/*.json": "./locale/*.json",
     "./tools/locale/*.json": "./tools/locale/*.json",
     "./tools/icon": "./assets/tools-icon.svg",
@@ -23,6 +24,7 @@
   },
   "files": [
     "lib",
+    "client",
     "locale",
     "tools/locale",
     "assets",
@@ -60,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",
@@ -71,18 +74,27 @@
     "@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": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-layout"
+      ]
     }
   },
   "icon": "./assets/icon.svg",