dsh-agent-message 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GengDaPeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,144 @@
+# dsh-agent-message
+
+English | [中文](./README.md)
+
+> A cross-session Agent communication plugin for DeepSeek Harness: it lets different Agent sessions running in the same process send and receive messages to each other, just like messaging.
+
+![License](https://img.shields.io/badge/License-MIT-blue.svg)
+
+---
+
+## What is this
+
+In DeepSeek Harness, a single process hosts multiple Agent sessions at once. This plugin equips each session with three tools so they can "message" each other:
+
+- Before sending, first **list every sendable session** (all non-archived ones are listed, including offline ones that haven't been reopened), and find the target by its title;
+- Once found, **deliver the message to the target session** — if the target is online, its current work is steered immediately; if it is offline (not loaded since the last process restart), it is **activated automatically** and then messaged, falling back to a **note** (visible when it is next opened) if activation fails;
+- When needed, **query the delivery status of a message on demand** (queued / claimed / discarded / unknown), with the target runtime status reported separately for supervision scenarios.
+
+Typical scenarios: an orchestrator Agent dispatching work to a developer Agent, two Agents collaborating in a relay, a main session sending instructions to a test session, or a supervisor Agent watching over several workers.
+
+## Features
+
+| Capability | Description |
+|---|---|
+| `list_peer_agents` | List all **sendable (non-archived)** sessions: id, title, working directory, status (online/offline), kind (peer/subagent) |
+| `send_agent_message` | Send a message to a session id; **immediate delivery by default** (online → steer; offline → wake, falling back to leave), plus five explicit modes |
+| `check_delivery` | Query receipts on demand (delivered/claimed/discarded/unknown); explicit message ids remain queryable after restart, with target runtime status reported separately; silent by default |
+| Navigable sender header | Both the `From Session · <name>:` line in `user` bubbles and the `From session @<ID>` source line in relay contexts can open the sender session by click or keyboard |
+| Copy session id | A "Copy ID" button is added to the session header for one-click copying of the current session id |
+
+### Sender navigation example
+
+![Clickable sender header example](./docs/assets/message-header-navigation.jpg)
+
+Users see only the sending Agent's name and can open its session by clicking the whole line. The full session id remains available to the receiving Agent in the raw message and metadata for precise identification and replies.
+
+### Delivery modes (the `mode` parameter of `send_agent_message`)
+
+| mode | Meaning |
+|---|---|
+| (default, omitted) | **Immediate delivery**: online → `steer`; offline → `wake` (falls back to `leave` if activation fails) |
+| `steer` | Steer the target's current work (online only) |
+| `followup` | Queue a new independent turn for the target (online only) |
+| `inject` | Silently inject the next step without waking it up (online only) |
+| `leave` | Leave a note: write into the target's inbox without waking it; for offline sessions this is a "mailbox" that appears when the session is next opened |
+| `wake` | Activate: resume an offline session first, then deliver; equivalent to `followup` when online |
+
+**Archived sessions are always rejected** (you are prompted to unarchive first); sending to yourself is also rejected.
+
+### Configuring the message form (`form`)
+
+The two forms differ not only visually — they carry different **intents**:
+
+| form | Rendering | Intent |
+|---|---|---|
+| `user` (default) | Ordinary message bubble | **Conversational**: like a human chat, a reply is expected |
+| `relay` | Collapsible context block | **Directive**: injected as context that quietly shapes the agent's later behavior — for instruction-style messages where no reply is expected |
+
+Override the plugin entry in your profile's `cordis.patch.yml` (takes effect on hot reload, no restart needed):
+
+```yaml
+- id: agent-message
+  config:
+    form: relay
+```
+
+## Installation
+
+### Option 1: One-liner (recommended)
+```sh
+dsh plugin --profile web add dsh-agent-message
+```
+
+It self-registers on install; no extra configuration is needed.
+
+Compatibility: Node.js 24 and DeepSeek Harness `>=0.1.0-rc.6 <0.2.0`; currently verified with Node.js `24.x` and Harness `0.1.0-rc.6`.
+
+### Option 2: Install from GitHub
+
+```sh
+dsh plugin --profile web add github:GengDaPeng/dsh-agent-message
+```
+
+### Option 3: Just tell your Agent
+
+Open any DSH session and send it this message:
+
+> Help me install the cross-session communication plugin by running: `dsh plugin --profile web add dsh-agent-message`
+
+The Agent will run this command via bash; once installed it auto-mounts and is immediately available to all sessions.
+
+### What happens automatically after install
+
+The plugin ships a `cordis.patch.yml` (pointed to by `dsh.bundle.patch` in `package.json`) that mounts itself into the host composition on install — so you do **not** need to manually edit presets or `cordis.patch.yml`. All sessions automatically gain `list_peer_agents`, `send_agent_message` and `check_delivery`.
+
+## Usage
+
+1. Tell session A "list the sendable Agents" — it calls `list_peer_agents`;
+2. Note down the target session's `id` (or have the other side click the "Copy ID" button);
+3. Say "send a message to `<session id>`: ..." — it calls `send_agent_message`; online targets are messaged immediately, offline targets are activated automatically (or left a note on failure);
+4. For `user` messages, click `From Session · <name>:` to open the sender; `relay` keeps Harness's context presentation and exposes the same navigation through its existing `From session @<ID>` source line.
+5. (Supervision) Say "check the status of my messages to `<session id>`" — it calls `check_delivery`.
+
+## How it works
+
+Each Agent has an inbox `Inbox` containing two FIFO queues:
+
+- `next-turn`: messages queued to be processed as an **independent turn**;
+- `next-step`: steering input consumed at the **next step boundary** within the current turn.
+
+Delivery paths of `send_agent_message`:
+
+- **Online**: find the target Agent through the `agents` registry and write into its inbox via `steer()` / `followup()` / `inject()`;
+- **Offline note (`leave`)**: append an `agent/inbox/spliced` event **durably** to the target session's log — when the session is next resumed, its inbox replays the event and the message is there (and the plugin wakes it so the note appears right away);
+- **Offline activation (`wake`)**: `agents.resume()` restores the session (together with its recorded agent preset), then `followup()` — the session is woken and processes the message immediately.
+
+Receipt states come from inbox events: still queued is `delivered`, claimed by one of the target's turns is `claimed`, and cancelled is `discarded`. The target's runtime state is returned separately as `targetStatus`, so an Agent running unrelated work is not presented as processing this message. When `messageId` is specified, `check_delivery` recovers the state directly from the target's existing Inbox log, so the lookup continues to work after a process restart.
+
+For `user` messages, the raw body header contains the sender title and full session id while the UI shows only a navigable `From Session · <name>:` header. `relay` does not repeat that header in the body; its native Harness source line is shown as a navigable `From session @<ID>`. Both forms retain the sender title and plain `session-...` id in `source` metadata.
+
+## Directory structure
+
+```
+dsh-agent-message/
+├── lib/
+│   ├── index.js        # host half: list_peer_agents / send_agent_message / check_delivery
+│   └── client.js       # client half: sender-session navigation and copy-session-id button
+├── cordis.patch.yml    # self-registration patch (pointed to by dsh.bundle.patch)
+├── package.json        # DSH plugin manifest (dsh.bundle / dsh.client / dshx.contributes)
+├── docs/               # design notes and README example screenshot
+├── README.md           # Chinese documentation
+└── README.en.md        # English documentation
+```
+
+## Limitations
+
+- The target session must be **non-archived** and present in local persistence; archived sessions are always rejected.
+- Offline activation (`wake`) resumes the target with the **default model** (it does not inherit a model manually selected earlier in that session).
+- Bulk receipt queries without `messageId` rely on in-memory bookkeeping and cover only the most recent 1000 sends in the current process (FIFO eviction). After a restart, a known `messageId` remains queryable, but the volatile `sentAt` and `mode` fields are no longer returned.
+- Cross-process / cross-machine communication is out of scope.
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -0,0 +1,145 @@
+# dsh-agent-message
+
+[English](./README.en.md) | 中文
+
+> DeepSeek Harness 的**跨会话 Agent 通信**插件：让运行在同一个进程里的不同 Agent 会话，像发消息一样互相收发信息。
+
+![License](https://img.shields.io/badge/License-MIT-blue.svg)
+
+---
+
+## 这是什么
+
+在 DeepSeek Harness 里，一个进程会同时挂着多个 Agent 会话。本插件给每个会话装上三个工具，让它们能互相"发消息"：
+
+- 发消息前，先**列出所有可发送的会话**（未归档的都在列，含离线未打开的），按标题找到目标；
+- 找到后，**把消息投递到目标会话**——目标在线就立即引导它当前的工作；目标离线（进程重启后还没打开）就**自动把它激活**再投递，激活失败则自动转为**留言**（下次打开可见）；
+- 需要时，可以**按需查询**某条消息的送达状态（排队中/已认领/被丢弃/未知），并单独查看目标是否正在运行，供监督场景使用。
+
+典型场景：编排者 Agent 给开发 Agent 派活、两个 Agent 协作接力、主会话给测试会话发指令、监督者 Agent 盯梢多个 worker。
+
+## 功能
+
+| 能力 | 说明 |
+|---|---|
+| `list_peer_agents` | 列出所有**可发送（未归档）**的会话：id、标题、工作目录、状态（在线/离线）、类型（平级/子代理） |
+| `send_agent_message` | 给指定会话 ID 发消息；默认**立即送达**（在线引导 / 离线激活，失败兜底留言），支持五种显式模式 |
+| `check_delivery` | 按需查询消息回执（delivered/claimed/discarded/unknown）；指定消息 ID 时支持重启后恢复查询，并单独返回目标运行状态，默认零播报 |
+| 可导航的发送者消息头 | `user` 气泡的整行 `From Session · <名称>:` 和 relay 的 `From session @<ID>` 来源行均可点击或通过键盘打开发送方会话 |
+| 复制会话 ID | 会话头部新增「复制ID」按钮，一键复制当前会话 ID |
+
+### 消息头跳转示例
+
+![可点击的发送者消息头示例](./docs/assets/message-header-navigation.jpg)
+
+用户只看到发送 Agent 的名称；点击整行即可打开发送方会话。完整会话 ID 仍保留在原始消息和元数据中，供接收 Agent 准确识别与回复。
+
+### 投递模式（`send_agent_message` 的 `mode` 参数）
+
+| mode | 含义 |
+|---|---|
+| （默认，不传） | **立即送达**：在线 → `steer`；离线 → `wake`（激活失败自动转 `leave`） |
+| `steer` | 引导对方当前的工作（仅在线） |
+| `followup` | 给对方排一条新的独立轮次（仅在线） |
+| `inject` | 静默注入下一步，但不唤醒（仅在线） |
+| `leave` | 留言：写进对方收件箱但不唤醒；离线会话就是"留言板" |
+| `wake` | 激活：离线会话先 `resume` 再投递；在线等价于 `followup` |
+
+**归档的会话一律拒绝发送**（提示先取消归档）；发给自己也会被拒绝。
+
+### 配置：消息渲染形态（`form`）
+
+两种形态不只是视觉差异，**承载的意图也不同**：
+
+| form | 渲染 | 意图 |
+|---|---|---|
+| `user`（默认） | 普通消息气泡 | **对话式**：像人发消息一样，期待代理回复 |
+| `relay` | 折叠的上下文块 | **引导式**：作为上下文注入，静默影响代理的后续行为，适合指令类消息，不期待回复 |
+
+在你的 profile 的 `cordis.patch.yml` 里覆盖插件条目即可（热更新即时生效，无需重启）：
+
+```yaml
+- id: agent-message
+  config:
+    form: relay
+```
+
+## 安装
+
+### 方式一：一行命令（推荐）
+
+```sh
+dsh plugin --profile web add dsh-agent-message
+```
+
+装完即自动注册，无需任何额外配置。
+
+兼容范围：Node.js 24、DeepSeek Harness `>=0.1.0-rc.6 <0.2.0`；当前验证版本为 Node.js `24.x`、Harness `0.1.0-rc.6`。
+
+### 方式二：从 GitHub 安装
+
+```sh
+dsh plugin --profile web add github:GengDaPeng/dsh-agent-message
+```
+
+### 方式三：直接发给你的 Agent
+
+打开任意一个 DSH 会话，把下面这句话发给它：
+
+> 帮我安装跨会话通信插件，执行：`dsh plugin --profile web add dsh-agent-message`
+
+Agent 会用 bash 执行这条命令，装完自动挂载、所有会话立即可用。
+
+### 装完自动发生了什么
+
+插件自带 `cordis.patch.yml`（由 `package.json` 的 `dsh.bundle.patch` 指向），安装后自动把自己挂进宿主组合——所以你**不需要**手动改 preset、改 `cordis.patch.yml`。所有会话自动获得 `list_peer_agents`、`send_agent_message` 和 `check_delivery`。
+
+## 使用
+
+1. 对会话 A 说「列出可发送的其它 Agent」——它会调 `list_peer_agents`；
+2. 记下目标会话的 `id`（或让对方点「复制ID」按钮）；
+3. 说「给 `<会话ID>` 发消息：……」——它会调 `send_agent_message`，目标在线立即送达、离线自动激活（失败则留言）；
+4. 会话 B 以 `user` 形态收到消息时可点击 `From Session · <名称>:`；`relay` 保持 Harness 上下文形态，并可通过原有的 `From session @<ID>` 来源行打开发送方会话。
+5. （监督场景）说「查一下我发给 `<会话ID>` 的消息状态」——它会调 `check_delivery`。
+
+## 原理
+
+每个 Agent 都有一个收件箱 `Inbox`，里面是两条 FIFO 队列：
+
+- `next-turn`：排队等待作为**独立一轮**处理的消息；
+- `next-step`：当前轮次内、**下一步边界**消费的引导输入。
+
+`send_agent_message` 的投递路径：
+
+- **在线**：通过 `agents` 注册表找到目标 Agent，调 `steer()` / `followup()` / `inject()` 写入其收件箱；
+- **离线留言（leave）**：把 `agent/inbox/spliced` 事件**持久化追加**进目标会话的日志——目标下次被打开（resume）时，收件箱会重放该事件，消息就在那里；
+- **离线激活（wake）**：`agents.resume()` 恢复该会话（连同它记录的 agent preset），再 `followup()`，会话被唤醒并立即处理。
+
+回执状态来自收件箱事件：消息还在队列里是 `delivered`，被对方某轮认领是 `claimed`，被取消是 `discarded`；目标是否正在运行通过独立的 `targetStatus` 返回，不把 Agent 的整体运行状态误当成某条消息正在处理。指定 `messageId` 时，`check_delivery` 会直接从目标现有 Inbox 日志恢复状态，因此进程重启后仍可查询。
+
+`user` 消息的原始正文头包含发送者标题和完整会话 ID，界面只显示可导航的 `From Session · <名称>:` 消息头。`relay` 的正文不重复消息头，Harness 原生来源行显示为可导航的 `From session @<ID>`；两种形态的 `source` 元数据都保留发送者标题和纯 `session-...` ID。
+
+## 目录结构
+
+```
+dsh-agent-message/
+├── lib/
+│   ├── index.js        # host 半区：list_peer_agents / send_agent_message / check_delivery
+│   └── client.js       # client 半区：发送方会话导航与复制会话ID按钮
+├── cordis.patch.yml    # 自注册补丁（dsh.bundle.patch 指向它）
+├── package.json        # DSH 插件清单（dsh.bundle / dsh.client / dshx.contributes）
+├── docs/               # 设计稿与 README 示例截图
+├── README.md           # 中文文档
+└── README.en.md        # English documentation
+```
+
+## 限制
+
+- 目标会话必须**未归档**且存在于本机持久化里；归档会话一律拒绝发送。
+- 离线激活（wake）会把目标会话以**默认模型**恢复运行（不继承它上次手动切换的模型选择）。
+- 不指定 `messageId` 的批量回执依赖内存记账，只覆盖本进程最近 1000 条发送记录（FIFO 淘汰）；进程重启后仍可凭已知 `messageId` 查询，但不再返回易失的 `sentAt` 和 `mode`。
+- 跨进程/跨机器通信不在本插件范围内。
+
+## License
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# dsh-agent-message bundle patch：把插件挂进 profile 的宿主组合（自注册）。
+# 由 package.json 的 dsh.bundle.patch 指向本文件，安装后自动挂载、全局可用。
+#
+# 可选配置：消息渲染形态 form —— user=对话式气泡、期待回复（默认）；
+# relay=上下文注入、静默影响代理行为、不期待回复。
+# 需要切换时，在你的 profile 的 cordis.patch.yml 里覆盖此条目：
+#
+#   - id: agent-message
+#     config:
+#       form: relay
+- insert:
+    - id: agent-message
+      name: 'dsh-agent-message'

package/lib/client.js

@@ -0,0 +1,170 @@
+window.__ModuleLoader__.load({
+  id: "dsh-agent-message",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+    const React = require("react");
+
+    const name = "dsh-agent-message-client";
+    const inject = ["slots", "timer", "sessions"];
+
+    function apply(ctx) {
+      const senderSelector = '[data-ref-chip="subagent"], [data-context-relay-sender]';
+
+      function senderLink(target) {
+        if (!(target instanceof Element)) return null;
+        const element = target.closest(senderSelector);
+        if (!element) return null;
+        if (element.dataset.agentMsgSessionId) {
+          return { element: element, sessionId: element.dataset.agentMsgSessionId };
+        }
+        const match = String(element.textContent || "").match(/session-[\w-]+/);
+        return match ? { element: element, sessionId: match[0] } : null;
+      }
+
+      function titleFrom(text) {
+        const line = String(text || "").split("\n", 1)[0].trim();
+        const current = line.match(/^From (?:Session|Agent)(?: ·)? (.+?):(?: @session-[\w-]+)?$/);
+        const previous = line.match(/^来自 Agent · (.+)$/);
+        const legacy = line.match(/^来自 Agent「(.+)」\s*[·：:]?$/);
+        return (current || previous || legacy)?.[1]?.trim() || "";
+      }
+
+      function senderTitle(element) {
+        if (element.dataset.agentMsgSenderTitle) return element.dataset.agentMsgSenderTitle;
+        const label = element.previousElementSibling;
+        const title = titleFrom(label?.textContent);
+        if (title && label) {
+          label.textContent = "";
+          label.classList.add("agent-msg-sender-prefix");
+        }
+        return title;
+      }
+
+      function prepareSenderLinks(root) {
+        if (!(root instanceof Element)) return;
+        const elements = root.matches(senderSelector)
+          ? [root].concat(Array.from(root.querySelectorAll(senderSelector)))
+          : Array.from(root.querySelectorAll(senderSelector));
+        elements.forEach(function (element) {
+          const link = senderLink(element);
+          if (!link) return;
+          const relay = element.matches("[data-context-relay-sender]");
+          const title = relay ? "" : senderTitle(element);
+          if (!relay && !title) return;
+          element.dataset.agentMsgSessionId = link.sessionId;
+          if (title) element.dataset.agentMsgSenderTitle = title;
+          element.textContent = relay ? "From session @" + link.sessionId : "From Session · " + title + ":";
+          element.classList.add("agent-msg-session-link");
+          element.setAttribute("role", "link");
+          element.setAttribute("tabindex", "0");
+          element.setAttribute("title", "打开发送方会话");
+          element.setAttribute("aria-label", "打开发送方会话：" + (title || link.sessionId));
+        });
+      }
+
+      function openSender(event) {
+        const element = event.target instanceof Element
+          ? event.target.closest(".agent-msg-session-link")
+          : null;
+        const sessionId = element?.dataset.agentMsgSessionId;
+        if (!sessionId) return;
+        event.preventDefault();
+        event.stopPropagation();
+        ctx.sessions.open(sessionId);
+      }
+
+      function onKeyDown(event) {
+        if (event.key !== "Enter" && event.key !== " ") return;
+        openSender(event);
+      }
+
+      function legacyCopyText(text) {
+        let ta;
+        try {
+          ta = document.createElement("textarea");
+          ta.value = text;
+          ta.setAttribute("readonly", "");
+          ta.style.position = "fixed";
+          ta.style.opacity = "0";
+          document.body.appendChild(ta);
+          ta.focus();
+          ta.select();
+          return document.execCommand("copy");
+        } catch (_) {
+          return false;
+        } finally {
+          ta?.remove();
+        }
+      }
+
+      async function copyText(text) {
+        try {
+          if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+            await navigator.clipboard.writeText(text);
+            return true;
+          }
+        } catch (_) {}
+        return legacyCopyText(text);
+      }
+
+      function CopyButton(props) {
+        const [copyState, setCopyState] = React.useState("idle");
+        async function onClick() {
+          const text = String(props.sessionId || "");
+          if (text === "") return;
+          setCopyState(await copyText(text) ? "copied" : "failed");
+          ctx.timeout(function () { setCopyState("idle"); }, 2000);
+        }
+        function onMouseLeave() { setCopyState("idle"); }
+        return React.createElement("button", {
+          type: "button",
+          onClick: onClick,
+          onMouseLeave: onMouseLeave,
+          title: "复制会话 ID",
+          "aria-label": "复制会话 ID",
+          className: "agent-msg-copy-id"
+        }, copyState === "copied" ? "已复制" : copyState === "failed" ? "复制失败" : "复制ID");
+      }
+
+      ctx.slots.inject("conversation.session.header.actions", () => ctx.slots.register(
+        { name: "conversation.session.header.actions", id: "copy-session-id", order: 30, label: "复制会话ID" },
+        (props) => React.createElement(CopyButton, { sessionId: props.sessionId })
+      ));
+
+      const css =
+        ".agent-msg-copy-id { cursor: pointer; font-size: 12px; line-height: 1; padding: 5px 10px; border: 1px solid rgba(127,127,127,.35); border-radius: 6px; background: transparent; color: inherit; opacity: .85; } " +
+        ".agent-msg-copy-id:hover { opacity: 1; border-color: rgba(127,127,127,.7); } " +
+        ".agent-msg-sender-prefix { display: none !important; } " +
+        ".agent-msg-session-link { cursor: pointer; text-decoration: none; } " +
+        ".agent-msg-session-link[data-ref-chip=\"subagent\"] { display: block; width: fit-content; padding: 0; background: transparent; color: inherit; font-size: 13px; font-weight: 600; line-height: 1.5; } " +
+        ".agent-msg-session-link:hover { text-decoration: underline; text-underline-offset: 3px; } " +
+        ".agent-msg-session-link:focus-visible { outline: 2px solid currentColor; outline-offset: 3px; border-radius: 2px; }";
+      const tag = document.createElement("style");
+      tag.setAttribute("data-plugin", name);
+      tag.textContent = css;
+      document.head.appendChild(tag);
+      prepareSenderLinks(document.body);
+      const observer = new MutationObserver(function (records) {
+        records.forEach(function (record) {
+          record.addedNodes.forEach(prepareSenderLinks);
+        });
+      });
+      observer.observe(document.body, { childList: true, subtree: true });
+      document.addEventListener("click", openSender);
+      document.addEventListener("keydown", onKeyDown);
+      ctx.effect(() => () => {
+        observer.disconnect();
+        document.removeEventListener("click", openSender);
+        document.removeEventListener("keydown", onKeyDown);
+        tag.remove();
+      });
+    }
+
+    exports.name = name;
+    exports.inject = inject;
+    exports.apply = apply;
+    return module.exports;
+  }
+});

package/lib/index.js

@@ -0,0 +1,370 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'dsh-agent-message'
+export const inject = ['agents', 'tools']
+
+export function apply(ctx, config) {
+  const agents = ctx.agents
+  /** 消息渲染形态：'user'=对话式气泡、期待回复（默认）｜'relay'=上下文注入、静默影响代理行为、不期待回复。 */
+  const form = config?.form === 'relay' ? 'relay' : 'user'
+  let seq = 0
+  /** messageId -> { to, at, mode }；发送成功即记账，供批量查询及补充本进程发送信息。 */
+  const sent = new Map()
+  /** 记账表 FIFO 上限：超过则淘汰最老记录，内存恒定。 */
+  const SENT_MAX = 1000
+
+  function rememberSent(messageId, to, mode) {
+    sent.set(messageId, { to, at: Date.now(), mode })
+    if (sent.size > SENT_MAX) sent.delete(sent.keys().next().value)
+  }
+
+  function mintId() {
+    seq += 1
+    return 'agent-msg-' + Date.now().toString(36) + '-' + seq + '-' + Math.random().toString(36).slice(2, 8)
+  }
+
+  function makeMessage(text, source) {
+    return { id: mintId(), role: 'user', content: [{ type: 'text', text }], source }
+  }
+
+  function titleOf(agent) {
+    const service = ctx.get('sessionTitle')
+    if (service !== undefined) {
+      try {
+        const snapshot = service.get(agent.session)
+        if (snapshot && typeof snapshot.title === 'string') return snapshot.title
+      } catch (_) {}
+    }
+    return ''
+  }
+
+  /** 折叠日志里的 agent/inbox/spliced 事件，得到当前 inbox 状态 + 已认领/已丢弃集合。 */
+  function foldInbox(events) {
+    const state = { 'next-turn': [], 'next-step': [], claimed: new Set(), discarded: new Set() }
+    for (const ev of events) {
+      if (ev.type !== 'agent/inbox/spliced') continue
+      const s = ev.data
+      const list = state[s.target] ?? []
+      const removed = list.splice(s.start, s.removedCount ?? 0, ...s.inserted)
+      const bucket = s.outcome === 'canceled' ? state.discarded : state.claimed
+      for (const m of removed) bucket.add(m.id)
+    }
+    return state
+  }
+
+  function archivedIds() {
+    const workspace = ctx.get('workspaceRegistry')
+    return new Set((workspace !== undefined ? workspace.archivedSessionIds : []).map((id) => String(id)))
+  }
+
+  /** 离线留言：把消息持久化写进目标会话的 inbox（next-turn 末尾），不唤醒。
+   *  写入前双检目标仍未上线；若恰好上线，抛 'target went live'，由调用方转在线投递。 */
+  async function leaveOffline(id, message) {
+    const persistence = ctx.get('sessionPersistence')
+    if (persistence === undefined) throw new Error('本部署无会话持久化，无法离线留言')
+    for (let attempt = 0; attempt < 2; attempt++) {
+      if (agents.get(id) !== undefined) throw new Error('target went live')
+      const { meta, events } = await persistence.readFrom(id, 0)
+      if (agents.get(id) !== undefined) throw new Error('target went live')
+      const state = foldInbox(events.slice(meta.seedLength ?? 0))
+      const start = state['next-turn'].length
+      const nextSeq = events.length === 0 ? 0 : events[events.length - 1].seq + 1
+      try {
+        await persistence.append(id, [{
+          seq: nextSeq,
+          type: 'agent/inbox/spliced',
+          time: Date.now(),
+          data: { target: 'next-turn', start, inserted: [message] },
+        }])
+        return
+      } catch (error) {
+        if (attempt === 0 && error instanceof Error && error.message.includes('append seq mismatch')) continue
+        throw error
+      }
+    }
+  }
+
+  /** 留言投递：写入失败时若目标恰好上线，自动转在线投递（模型无感，不报错）。 */
+  async function deliverLeave(id, message) {
+    try {
+      await leaveOffline(id, message)
+      return { usedMode: 'leave', fallback: '' }
+    } catch (error) {
+      const nowLive = agents.get(id)
+      if (nowLive !== undefined) {
+        nowLive.followup(message)
+        return { usedMode: 'followup', fallback: '留言写入时目标恰好上线，已改为在线投递' }
+      }
+      throw error
+    }
+  }
+
+  /** 离线激活：resume 该会话（恢复其记录的 preset + 默认模型）并 followup。 */
+  async function wakeOffline(id, message) {
+    const persistence = ctx.get('sessionPersistence')
+    if (persistence === undefined) throw new Error('本部署无会话持久化，无法激活离线会话')
+    const inspected = await persistence.inspect(id)
+    let presetId = inspected.meta !== undefined ? inspected.meta.agentPreset : undefined
+    const events = inspected.events ?? []
+    for (let i = events.length - 1; i >= 0; i--) {
+      const ev = events[i]
+      if (ev && ev.type === 'agent-preset/selected') {
+        presetId = ev.data.agentPreset
+        break
+      }
+    }
+    const presets = ctx.get('agentPresets')
+    const defaultModel = ctx.get('agentDefaultModel')
+    const selection = defaultModel !== undefined ? defaultModel.currentSelection() : { provider: '', model: '' }
+    const handle = await agents.resume({
+      resumeSessionId: id,
+      agentOptions: { provider: selection.provider ?? '', model: selection.model ?? '' },
+      ...(presets !== undefined && presetId !== undefined
+        ? { setup: async (agentCtx) => { await presets.mount(agentCtx, presetId) } }
+        : {}),
+    })
+    handle.agent.followup(message)
+    return handle.agent
+  }
+
+  /** 一次读取并折叠目标会话，供同一批回执查询复用。 */
+  async function deliverySnapshotOf(to) {
+    const target = agents.get(to)
+    if (target !== undefined) {
+      const state = foldInbox(target.session.events.slice(target.session.header.seedLength ?? 0))
+      return {
+        pending: new Set(target.inbox.nextTurn.concat(target.inbox.nextStep).map((message) => message.id)),
+        claimed: state.claimed,
+        discarded: state.discarded,
+      }
+    }
+    const persistence = ctx.get('sessionPersistence')
+    if (persistence === undefined) return { pending: new Set(), claimed: new Set(), discarded: new Set() }
+    const { meta, events } = await persistence.readFrom(to, 0)
+    const state = foldInbox(events.slice(meta.seedLength ?? 0))
+    return {
+      pending: new Set(state['next-turn'].concat(state['next-step']).map((message) => message.id)),
+      claimed: state.claimed,
+      discarded: state.discarded,
+    }
+  }
+
+  /** 回执状态：delivered 排队中 / claimed 已认领 / discarded 被丢弃 / unknown 查无此消息。 */
+  function deliveryStateOf(messageId, snapshot) {
+    if (snapshot.pending.has(messageId)) return 'delivered'
+    if (snapshot.discarded.has(messageId)) return 'discarded'
+    if (snapshot.claimed.has(messageId)) return 'claimed'
+    return 'unknown'
+  }
+
+  /** 会话恢复（用户打开）时，若有排队中的留言，唤醒它开始处理——留言"打开即达"。 */
+  ctx.on('agent/session-start', ({ agent }) => {
+    if (agent !== undefined && agent.inbox !== undefined
+      && agent.inbox.nextTurn.some((message) => message.source?.plugin === name)) {
+      agent.wakeDriver()
+    }
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'list_peer_agents',
+    description:
+      '列出当前进程里所有可发送（未归档）的 DeepSeek Harness Agent/会话，用于跨会话通信。' +
+      '每条含：id（会话 ID）、标题、工作目录、status（offline=进程里未加载、重启后未打开；其余为在线）、' +
+      'kind（peer=平级会话 / subagent=子代理）。在线在前、按标题排序。' +
+      '找到目标会话后，用它的 id 调用 send_agent_message 发送消息（目标离线也会自动激活或留言）。' +
+      '注意：它不同于 list_agents（后者列的是你的后台子代理）。',
+    parameters: {},
+    output: {
+      schema: { type: 'json' },
+      render(_args, value) {
+        return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+      },
+    },
+    async execute(_args, exec) {
+      const me = exec.agent
+      const archived = archivedIds()
+      const persistence = ctx.get('sessionPersistence')
+      const live = new Map()
+      for (const agent of agents.list()) live.set(String(agent.id), agent)
+
+      const ids = new Set()
+      for (const id of live.keys()) ids.add(id)
+      const headers = persistence !== undefined ? await persistence.list() : []
+      const headerMap = new Map(headers.map((header) => [String(header.id), header]))
+      for (const id of headerMap.keys()) ids.add(id)
+
+      const rows = []
+      for (const id of ids) {
+        if (archived.has(id)) continue
+        const agent = live.get(id)
+        const header = headerMap.get(id)
+        const status = agent !== undefined ? agent.status : 'offline'
+        const cwd = (agent !== undefined && agent.session !== undefined && agent.session.header !== undefined ? agent.session.header.cwd : '')
+          || (header !== undefined ? header.cwd : '') || ''
+        const kind = ((header !== undefined && header.parentSession !== undefined)
+          || (agent !== undefined && agent.session !== undefined && agent.session.header !== undefined && agent.session.header.parentSession !== undefined))
+          ? 'subagent' : 'peer'
+        rows.push({ id, title: '', cwd, status, kind, self: me !== undefined && String(me.id) === id })
+      }
+
+      const query = ctx.get('sessionQuery')
+      if (query !== undefined) {
+        const snapshots = await query.readTitleSnapshots(rows.map((r) => r.id))
+        const titleMap = new Map()
+        for (const t of snapshots) {
+          if (t.status === 'fulfilled' && t.value !== undefined && t.value.title !== undefined && typeof t.value.title.title === 'string') {
+            titleMap.set(String(t.sessionId), t.value.title.title)
+          }
+        }
+        for (const row of rows) row.title = titleMap.get(row.id) ?? ''
+      }
+
+      const rank = (row) => (row.status === 'running' ? 0 : row.status === 'idle' ? 1 : 2)
+      rows.sort((a, b) => {
+        const ra = rank(a)
+        const rb = rank(b)
+        if (ra !== rb) return ra - rb
+        const ta = a.title || '~'
+        const tb = b.title || '~'
+        return ta < tb ? -1 : ta > tb ? 1 : 0
+      })
+      for (const row of rows) if (row.title === '') row.title = '(无标题 · ' + String(row.id).replace(/^session-/, '').slice(0, 8) + ')'
+      return rows
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'send_agent_message',
+    description:
+      '向另一个 Agent/会话发送消息（跨会话通信）。默认立即送达：目标在线则引导其当前工作（steer）；' +
+      '目标离线（进程里未加载）则自动激活该会话并投递（wake），激活失败自动改为留言（leave）。' +
+      'mode 可选：steer/followup/inject（仅在线）、leave（留言不唤醒）、wake（激活）。归档会话一律拒绝。' +
+      '注意：它不同于 send_message（后者是给你的后台子代理续聊）。',
+    parameters: {
+      to: { type: 'string', required: true, description: '目标会话/Agent ID，来自 list_peer_agents 或复制到的会话 ID。' },
+      content: { type: 'string', required: true, description: '要发送的消息文本。' },
+      mode: { type: 'string', enum: ['steer', 'followup', 'inject', 'leave', 'wake'], description: 'steer/followup/inject 仅在线；leave 留言不唤醒；wake 激活。不传则智能默认。' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render(_args, value) {
+        return [{ type: 'text', text: value.text || JSON.stringify(value) }]
+      },
+    },
+    async execute(args, exec) {
+      const me = exec.agent
+      if (me === undefined) throw new Error('no calling agent')
+      const to = args.to
+      if (to === '' || String(to) === String(me.id)) throw new Error('不能给自己发消息')
+
+      const archived = archivedIds()
+      if (archived.has(String(to))) throw new Error('对方会话已归档，无法发送（请先取消归档）')
+
+      const myTitle = titleOf(me) || String(me.id)
+      const source = {
+        kind: form === 'relay' ? 'plugin' : 'user',
+        plugin: name,
+        form,
+        senderSessionId: String(me.id),
+        senderTitle: myTitle,
+      }
+      const message = makeMessage(form === 'relay' ? args.content : 'From Session · ' + myTitle + ': @' + String(me.id) + '\n' + args.content, source)
+
+      const target = agents.get(to)
+      let usedMode = ''
+      let fallback = ''
+
+      if (target !== undefined) {
+        const mode = args.mode ?? 'steer'
+        if (mode === 'followup' || mode === 'wake') { target.followup(message); usedMode = mode }
+        else if (mode === 'leave') { target.inbox.append('next-turn', message); usedMode = 'leave' }
+        else if (mode === 'inject') { target.inject(message); usedMode = 'inject' }
+        else { target.steer(message); usedMode = 'steer' }
+      } else {
+        const persistence = ctx.get('sessionPersistence')
+        const headers = persistence !== undefined ? await persistence.list() : []
+        const header = headers.find((h) => String(h.id) === String(to))
+        if (header === undefined) throw new Error('会话不存在：' + to)
+        const mode = args.mode ?? 'wake'
+        if (mode === 'steer' || mode === 'followup' || mode === 'inject') {
+          throw new Error('目标离线（进程里未加载）：' + mode + ' 仅用于在线会话；不传 mode（自动激活）或用 wake/leave')
+        }
+        if (mode === 'wake') {
+          try {
+            await wakeOffline(to, message)
+            usedMode = 'wake'
+          } catch (error) {
+            try {
+              const result = await deliverLeave(to, message)
+              usedMode = result.usedMode
+              fallback = '激活失败：' + (error instanceof Error ? error.message : String(error))
+                + (result.fallback !== '' ? '；' + result.fallback : '（已改为留言）')
+            } catch (leaveError) {
+              throw new Error('激活失败（' + (error instanceof Error ? error.message : String(error))
+                + '），且留言也失败（' + (leaveError instanceof Error ? leaveError.message : String(leaveError)) + '）')
+            }
+          }
+        } else {
+          const result = await deliverLeave(to, message)
+          usedMode = result.usedMode
+          fallback = result.fallback
+        }
+      }
+
+      rememberSent(message.id, String(to), usedMode)
+      return {
+        ok: true,
+        to: String(to),
+        mode: usedMode,
+        messageId: message.id,
+        ...(fallback !== '' ? { fallback } : {}),
+        text: fallback !== '' ? fallback : '已通过 ' + usedMode + ' 模式向 Agent ' + String(to) + ' 发送消息。',
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'check_delivery',
+    description:
+      '按需查询发给某会话的消息状态（跨会话回执，默认安静——只有监督场景主动调用时才返回，不做任何自动播报）。' +
+      '状态：delivered=已送达·排队中；claimed=已被对方认领；discarded=被丢弃；unknown=查无此消息。' +
+      '传 messageId 时可在进程重启后从目标 Inbox 日志恢复状态；不传则只返回本进程内发给该会话的全部已记账消息。',
+    parameters: {
+      to: { type: 'string', required: true, description: '目标会话 ID。' },
+      messageId: { type: 'string', description: '可选：只查这一条消息（来自 send_agent_message 的返回值）。' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render(_args, value) {
+        return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+      },
+    },
+    async execute(args) {
+      const target = agents.get(args.to)
+      const targetStatus = target !== undefined ? target.status : 'offline'
+      if (args.messageId !== undefined) {
+        const entry = sent.get(args.messageId)
+        if (entry !== undefined && String(entry.to) !== String(args.to)) {
+          return { to: args.to, entries: [{ messageId: args.messageId, state: 'unknown', targetStatus }] }
+        }
+      }
+      const wanted = args.messageId !== undefined
+        ? [args.messageId]
+        : [...sent.entries()].filter(([, e]) => String(e.to) === String(args.to)).map(([id]) => id)
+      const entries = []
+      const snapshot = wanted.length > 0 ? await deliverySnapshotOf(args.to) : undefined
+      for (const messageId of wanted) {
+        const entry = sent.get(messageId)
+        if (entry !== undefined && String(entry.to) !== String(args.to)) continue
+        const state = deliveryStateOf(messageId, snapshot)
+        entries.push({
+          messageId,
+          ...(entry !== undefined ? { sentAt: entry.at, mode: entry.mode } : {}),
+          state,
+          targetStatus,
+        })
+      }
+      return { to: args.to, entries }
+    },
+  }))
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "dsh-agent-message",
+  "version": "1.4.0",
+  "packageManager": "pnpm@11.1.1",
+  "description": "跨会话 Agent 通信：让 DeepSeek Harness 里不同的 Agent 会话互相收发消息。",
+  "keywords": ["deepseek", "deepseek-harness", "agent", "multi-agent", "messaging"],
+  "homepage": "https://github.com/GengDaPeng/dsh-agent-message#readme",
+  "bugs": { "url": "https://github.com/GengDaPeng/dsh-agent-message/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GengDaPeng/dsh-agent-message.git"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "scripts": { "test": "node --test" },
+  "exports": {
+    ".": { "default": "./lib/index.js" },
+    "./client": { "default": "./lib/client.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["lib", "cordis.patch.yml", "docs/assets/message-header-navigation.jpg"],
+  "publishConfig": { "access": "public" },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "dshx": {
+    "contributes": {
+      "tools": ["list_peer_agents", "send_agent_message", "check_delivery"],
+      "skills": []
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6 <0.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6"
+  },
+  "engines": {
+    "node": ">=24 <25",
+    "dsh": ">=0.1.0-rc.6 <0.2.0"
+  },
+  "license": "MIT"
+}