dsh-agent-message 1.4.0 → 1.5.1

package/README.en.md

@@ -12,8 +12,8 @@ English | [中文](./README.md)
 
 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;
+- Before sending, first **list every sendable independent session** (non-archived, excluding actual subagents, including offline sessions that have not been reopened), and find the target by its title;
+- Once found, **deliver the message to the target session** — ordinary messages always enter a new independent turn; if the target is offline (not loaded since the last process restart), the plugin resumes it through Harness's public API, delivers the message, and keeps the handle loaded for later communication until plugin teardown;
 - 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.
@@ -22,47 +22,29 @@ Typical scenarios: an orchestrator Agent dispatching work to a developer Agent,
 
 | 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 |
+| `list_peer_agents` | List all **sendable independent sessions**: non-archived, excluding actual subagents while retaining ordinary forks; returns id, title, working directory, and runtime status |
+| `send_agent_message` | Send a message to a session id; `followup` creates an independent turn by default and offline targets are resumed automatically; explicit modes are `followup`, `inject`, and `steer` |
+| `check_delivery` | Query receipts on demand (pending/claimed/discarded/unknown); a successful send first returns accepted, while pre-admission failure is a tool error; explicit message ids remain queryable after restart |
+| `@` session locator | Type `@` at the beginning of the composer and choose a target; candidates show only the session title and `Running`/`Idle`, excluding blank placeholders and subagents. The user sees a readable title while the current Agent receives the stable session id; `@` only locates the session, and the full-sentence intent determines whether to send, read, or analyze |
+| Visible Agent message card | Relay keeps its true plugin provenance while the Client presents it as a left-aligned Agent message card; `From Session · <name>:` opens the sender 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.
+Current relay messages are displayed as visible Agent message cards; clicking the header opens the sender session. The persisted source remains plugin `relay` provenance rather than impersonating human input. The full session id remains in typed source metadata and in a Host-generated model-visible protocol header, so the receiving Agent never has to guess the sender.
 
 ### 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 |
+| (default, omitted) | `followup`: create an independent turn; an offline target is resumed automatically before delivery |
+| `followup` | Same as the default; queue directly when online, or resume and queue when offline |
+| `steer` | Intervene in the target's current work immediately (`running` sessions only) |
+| `inject` | Add next-step context without interrupting the current goal (`running` sessions only) |
 
-**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
-```
+**Archived sessions and actual subagents are always rejected**; ordinary forks remain independent and sendable. Sending to yourself is also rejected.
 
 ## Installation
 
@@ -95,11 +77,12 @@ The plugin ships a `cordis.patch.yml` (pointed to by `dsh.bundle.patch` in `pack
 
 ## 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`.
+1. Type `@` at the beginning of session A's composer and choose the target from the native candidate menu; each candidate shows its title and `Running`/`Idle` activity;
+2. `@` only tells A where the relevant session is; it does not mean send. A calls `send_agent_message` only when the current request or an orchestration responsibility already granted by the user requires cross-session communication. For example, `@B tell it to stop after opening the draft PR` sends, while `@B analyze its latest conversation result` must not send a message to B;
+3. For an explicit forwarding request, A only delivers and reports whether the message was accepted or failed. It must not execute the forwarded task itself or ask B for an extra acknowledgement. B sends a message to `senderSessionId` only when the body explicitly asks it to return business content;
+4. You can still ask the Agent to call `list_peer_agents` and send directly with a full session id;
+5. Session B receives a native `UserMessage` with a typed relay source plus a minimal Host-generated source header on the first body line, so B does not have to guess the sender. The Client presents it as a visible Agent message card whose header opens the sender session;
+6. (Supervision) Say "check the status of my messages to `<session id>`" — it calls `check_delivery`.
 
 ## How it works
 
@@ -110,13 +93,21 @@ Each Agent has an inbox `Inbox` containing two FIFO queues:
 
 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.
+- **Ordinary online message**: find the target Agent through the `agents` registry and call `followup()` so it enters an independent `next-turn`;
+- **Running-mode semantics**: users do not need to name a mode. The Agent selects `steer()` when the full request clearly asks for immediate intervention, or `inject()` when it clearly asks to add context without interrupting the current task. The target must actually be `running`; when intent is unclear, the Agent keeps the default `followup()`;
+- **Ordinary offline message**: first read and validate one logical-session snapshot through `sessionQuery.readSession()`, then restore it through the public `agents.resume()` API and call `followup()`. The plugin retains and reuses the returned handle, keeps the target loaded after it becomes idle, and releases the handle only when the plugin unloads. Resume failures are returned directly; the plugin does not forge core Inbox events as a fallback note.
+
+Session enumeration, batched titles, and offline log reads use Harness's `sessionQuery.listSessions()`, `readTitleSnapshots()`, and `readSession()` respectively. `SessionId` is the only address; `parentSession` records fork lineage only, and only `origin: subagent` identifies an actual subagent. The plugin does not scan `sessionPersistence` directly to rebuild a parallel session directory.
+
+After `send_agent_message` submits the native message to the target Inbox, it immediately returns `accepted` with the native `messageId`; the model receives only a terse “delivered” projection while the complete result stays in tool presentation metadata. `check_delivery` then derives `pending` (still queued), `claimed` (claimed by a turn), `discarded` (cancelled), or `unknown` from Inbox events on demand. `claimed` is transport evidence only: it does not prove that the message was read, answered, or completed. Pre-admission failure remains a Harness tool error and writes nothing to the target Inbox. Runtime state is reported separately as `targetRuntimeStatus`, so unrelated Agent activity never changes the message state. A known `messageId` remains queryable from the target Inbox log after a process restart.
+
+Every cross-session message is created by Harness `createUserMessage()`, and `UserMessage.id` is its only message identity. Its source always uses `kind: dsh-agent-message` and `form: relay`, plus the protocol version, sender/target Session ids, and display title. Because current Harness model requests do not expand custom source fields, the Host also writes a minimal `<dsh-agent-message>` header containing only `senderSessionId` on the first body line. The typed source is the durable/UI truth; the header is only the model-visible projection needed for reply addressing. The plugin registers no global system prompt; send admission lives only in the `send_agent_message` tool contract. The Client only projects relay as a visible Agent message card and never rewrites an Agent message as human `user` provenance.
+
+Relay only means “a message addressed by another session”; it neither requires nor forbids a reply. When the body explicitly requests business content in return, the receiving Agent may send a message to `senderSessionId` with the same tool. Otherwise it must not send a transport acknowledgement or a bare “received.” The plugin does not automatically correlate requests and replies or forward ordinary Agent answers.
 
-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.
+The composer-side `@` session locator reuses Harness's native `inputTriggers` command marker. The visible selected title is capped at 40 Unicode characters with an ellipsis; submission replaces it with the full stable `@session-...` id for the current Agent. The sent bubble still projects that id with a chat icon and the live session title, so renaming a session does not change the locator target.
 
-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.
+See [`docs/architecture-v2.md`](./docs/architecture-v2.md) for the current architecture contract.
 
 ## Directory structure
 
@@ -124,10 +115,10 @@ For `user` messages, the raw body header contains the sender title and full sess
 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
+│   └── client.js       # client half: @session references, 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
+├── docs/               # current architecture and README example screenshot
 ├── README.md           # Chinese documentation
 └── README.en.md        # English documentation
 ```
@@ -135,7 +126,9 @@ dsh-agent-message/
 ## 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).
+- These tools are only for communication between independent sessions; actual subagents are neither listed as targets nor allowed to call them.
+- One Session pair, regardless of direction, may receive at most 10 deliveries in a rolling 60-second window. The 11th is rejected before the target Inbox is changed. This window belongs to the current Harness process and resets on restart.
+- Automatically resuming an offline session uses the **default model** (it does not inherit a model manually selected earlier in that session); if resume fails, the message is not written to the target Inbox.
 - 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.
 

package/README.md

@@ -12,8 +12,8 @@
 
 在 DeepSeek Harness 里，一个进程会同时挂着多个 Agent 会话。本插件给每个会话装上三个工具，让它们能互相"发消息"：
 
-- 发消息前，先**列出所有可发送的会话**（未归档的都在列，含离线未打开的），按标题找到目标；
-- 找到后，**把消息投递到目标会话**——目标在线就立即引导它当前的工作；目标离线（进程重启后还没打开）就**自动把它激活**再投递，激活失败则自动转为**留言**（下次打开可见）；
+- 发消息前，先**列出所有可发送的独立会话**（未归档、排除真实子代理，含离线未打开的），按标题找到目标；
+- 找到后，**把消息投递到目标会话**——普通消息统一进入独立的新 turn；目标离线（进程重启后还没打开）时，插件通过 Harness 公开接口恢复会话、投递，并保持加载供后续通信，插件卸载时再释放 handle；
 - 需要时，可以**按需查询**某条消息的送达状态（排队中/已认领/被丢弃/未知），并单独查看目标是否正在运行，供监督场景使用。
 
 典型场景：编排者 Agent 给开发 Agent 派活、两个 Agent 协作接力、主会话给测试会话发指令、监督者 Agent 盯梢多个 worker。
@@ -22,47 +22,29 @@
 
 | 能力 | 说明 |
 |---|---|
-| `list_peer_agents` | 列出所有**可发送（未归档）**的会话：id、标题、工作目录、状态（在线/离线）、类型（平级/子代理） |
-| `send_agent_message` | 给指定会话 ID 发消息；默认**立即送达**（在线引导 / 离线激活，失败兜底留言），支持五种显式模式 |
-| `check_delivery` | 按需查询消息回执（delivered/claimed/discarded/unknown）；指定消息 ID 时支持重启后恢复查询，并单独返回目标运行状态，默认零播报 |
-| 可导航的发送者消息头 | `user` 气泡的整行 `From Session · <名称>:` 和 relay 的 `From session @<ID>` 来源行均可点击或通过键盘打开发送方会话 |
+| `list_peer_agents` | 列出所有**可发送**的独立会话：未归档、排除真实子代理；普通 fork 保留。返回 id、标题、工作目录和运行状态 |
+| `send_agent_message` | 给指定会话 ID 发消息；默认使用 `followup` 创建独立的新 turn，离线时自动恢复后投递；显式支持 `followup`、`inject`、`steer` |
+| `check_delivery` | 按需查询消息回执（pending/claimed/discarded/unknown）；发送成功时先返回 accepted，接纳前失败由工具错误表示；指定消息 ID 时支持重启后恢复查询 |
+| `@` 会话定位 | 在输入框开头键入 `@` 选择目标；候选只显示会话标题和“运行中/空闲”，空白占位和子代理不混入。选择后用户看到可读标题，当前 Agent 收到稳定 session ID；`@` 只定位，发送、读取或分析由整句意图决定 |
+| 可见的 Agent 消息卡片 | relay 仍保留真实的插件来源，但 Client 将它显示为左侧 Agent 消息卡片；`From Session · <名称>:` 可点击或通过键盘打开发送方会话 |
 | 复制会话 ID | 会话头部新增「复制ID」按钮，一键复制当前会话 ID |
 
-### 消息头跳转示例
+### 发送方导航示例
 
 ![可点击的发送者消息头示例](./docs/assets/message-header-navigation.jpg)
 
-用户只看到发送 Agent 的名称；点击整行即可打开发送方会话。完整会话 ID 仍保留在原始消息和元数据中，供接收 Agent 准确识别与回复。
+当前 relay 消息显示为可见的 Agent 消息卡片；点击消息头即可跳转到发送方会话。持久化来源仍是插件 `relay`，不会伪装成人类输入。完整会话 ID 同时保留在 typed source 和 Host 生成的模型可见协议头中，避免接收 Agent 猜测发送方。
 
 ### 投递模式（`send_agent_message` 的 `mode` 参数）
 
 | mode | 含义 |
 |---|---|
-| （默认，不传） | **立即送达**：在线 → `steer`；离线 → `wake`（激活失败自动转 `leave`） |
-| `steer` | 引导对方当前的工作（仅在线） |
-| `followup` | 给对方排一条新的独立轮次（仅在线） |
-| `inject` | 静默注入下一步，但不唤醒（仅在线） |
-| `leave` | 留言：写进对方收件箱但不唤醒；离线会话就是"留言板" |
-| `wake` | 激活：离线会话先 `resume` 再投递；在线等价于 `followup` |
+| （默认，不传） | `followup`：给目标创建独立的新 turn；离线时自动 `resume` 后投递 |
+| `followup` | 与默认相同；在线直接排队，离线自动恢复后排队 |
+| `steer` | 立即介入对方当前工作（仅 `running` 会话） |
+| `inject` | 不打断当前目标，静默补充下一步上下文（仅 `running` 会话） |
 
-**归档的会话一律拒绝发送**（提示先取消归档）；发给自己也会被拒绝。
-
-### 配置：消息渲染形态（`form`）
-
-两种形态不只是视觉差异，**承载的意图也不同**：
-
-| form | 渲染 | 意图 |
-|---|---|---|
-| `user`（默认） | 普通消息气泡 | **对话式**：像人发消息一样，期待代理回复 |
-| `relay` | 折叠的上下文块 | **引导式**：作为上下文注入，静默影响代理的后续行为，适合指令类消息，不期待回复 |
-
-在你的 profile 的 `cordis.patch.yml` 里覆盖插件条目即可（热更新即时生效，无需重启）：
-
-```yaml
-- id: agent-message
-  config:
-    form: relay
-```
+**归档会话和真实子代理一律拒绝发送**；普通 fork 仍是独立会话，可以发送。发给自己也会被拒绝。
 
 ## 安装
 
@@ -96,11 +78,12 @@ Agent 会用 bash 执行这条命令，装完自动挂载、所有会话立即
 
 ## 使用
 
-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`。
+1. 在会话 A 的输入框开头键入 `@`，从原生候选菜单中选择目标会话；候选会显示标题和“运行中/空闲”；
+2. `@` 只告诉 A 信息或操作的目标在哪里，不代表发送。当前请求或用户已授予的编排职责要求跨会话传递信息时，A 才调用 `send_agent_message`。例如 `@B 告诉他最后提交 PR draft 就停止` 会发送，`@B 帮我分析他最新的对话结果` 则不应向 B 发消息；
+3. 显式要求转告时，A 只负责投递并报告“已接受”或失败，不代为执行被转发的任务，也不要求 B 额外回复“收到”；如果正文明确要求 B 把业务内容返回 A，B 才向 `senderSessionId` 发送消息；
+4. 也可以让 Agent 调 `list_peer_agents`，再用完整会话 ID 直接发送；
+5. 会话 B 收到的是带 typed relay source 的原生 `UserMessage`；正文首行还有 Host 生成的最小来源协议，B 不需要猜测发送方；Client 将其显示为可见 Agent 消息卡片，并可从消息头打开发送方会话；
+6. （监督场景）说「查一下我发给 `<会话ID>` 的消息状态」——它会调 `check_delivery`。
 
 ## 原理
 
@@ -111,13 +94,21 @@ Agent 会用 bash 执行这条命令，装完自动挂载、所有会话立即
 
 `send_agent_message` 的投递路径：
 
-- **在线**：通过 `agents` 注册表找到目标 Agent，调 `steer()` / `followup()` / `inject()` 写入其收件箱；
-- **离线留言（leave）**：把 `agent/inbox/spliced` 事件**持久化追加**进目标会话的日志——目标下次被打开（resume）时，收件箱会重放该事件，消息就在那里；
-- **离线激活（wake）**：`agents.resume()` 恢复该会话（连同它记录的 agent preset），再 `followup()`，会话被唤醒并立即处理。
+- **在线普通消息**：通过 `agents` 注册表找到目标 Agent，调用 `followup()` 进入独立的 `next-turn`；
+- **运行中高级语义**：用户无需说出模式名；Agent 根据整句话判断，明确要求立即介入时使用 `steer()`，明确要求不打断当前任务、只补充上下文时使用 `inject()`；目标必须确实为 `running`，判断不清时仍使用默认 `followup()`；
+- **离线普通消息**：先由 `sessionQuery.readSession()` 读取同一份逻辑会话快照并校验目标，再通过公开 `agents.resume()` 恢复、调用 `followup()`；插件持有并复用恢复得到的 handle，目标回到 idle 后仍保持加载，只在插件卸载时释放。恢复失败直接返回失败，不伪造核心 Inbox 事件作为留言。
+
+会话枚举、批量标题和离线日志读取分别使用 Harness 的 `sessionQuery.listSessions()`、`readTitleSnapshots()` 与 `readSession()`。`SessionId` 是唯一地址；`parentSession` 只记录分叉血缘，只有 `origin: subagent` 才会被识别为真实子代理。插件不直接扫描 `sessionPersistence` 重建另一份会话目录。
+
+`send_agent_message` 成功把原生消息提交给目标 Inbox 后立即返回 `accepted` 和该消息的原生 `messageId`；模型只接收简短的“已投递”，完整结果保留在工具呈现元数据中。`check_delivery` 根据 Inbox 事件按需返回 `pending`（仍在排队）、`claimed`（已被某轮认领）、`discarded`（被取消）或 `unknown`。`claimed` 只是传输证据，不表示已读、回复或任务完成。接纳前失败由 Harness 工具错误表示，不写入目标 Inbox。目标是否正在运行通过独立的 `targetRuntimeStatus` 返回，不把 Agent 的整体运行状态误当成某条消息正在处理。指定 `messageId` 时可从目标现有 Inbox 日志恢复状态，因此进程重启后仍可查询。
+
+所有跨会话消息都由 Harness `createUserMessage()` 创建，`UserMessage.id` 是唯一消息身份。`source.kind` 固定为 `dsh-agent-message`，`form` 固定为 `relay`，并携带协议版本、发送/目标 Session 和显示标题。由于当前 Harness 不会把自定义 source 字段展开给模型，Host 还会在正文首行写入只含 `senderSessionId` 的最小 `<dsh-agent-message>` 协议头；source 是持久化/UI 真相，协议头只是回复寻址所需的模型可见投影。插件不注册全局系统提示词，发送准入只存在于 `send_agent_message` 的工具合同中。Client 只把 relay 投影为可见的 Agent 消息卡片，不会反向把 Agent 消息伪装成人类 `user` 来源。
+
+relay 只表达“另一会话发来的消息”，本身不等于必须回复或禁止回复。正文明确要求返回业务内容时，接收 Agent 可用同一工具向 `senderSessionId` 发送消息；没有明确要求时不回传 transport ack 或单纯的“收到”。插件不自动关联请求与回复，也不自动转发 Agent 的普通回答。
 
-回执状态来自收件箱事件：消息还在队列里是 `delivered`，被对方某轮认领是 `claimed`，被取消是 `discarded`；目标是否正在运行通过独立的 `targetStatus` 返回，不把 Agent 的整体运行状态误当成某条消息正在处理。指定 `messageId` 时，`check_delivery` 会直接从目标现有 Inbox 日志恢复状态，因此进程重启后仍可查询。
+输入框的 `@` 会话定位复用 Harness 原生 `inputTriggers` 命令标记：选择后的可见标题最多 40 个 Unicode 字符，超出用省略号；提交给当前 Agent 时换成完整 `@session-...` 稳定 ID。发送后的气泡依然用聊天图标和实时会话标题投影该 ID，显示名称变化不会改变定位目标。
 
-`user` 消息的原始正文头包含发送者标题和完整会话 ID，界面只显示可导航的 `From Session · <名称>:` 消息头。`relay` 的正文不重复消息头，Harness 原生来源行显示为可导航的 `From session @<ID>`；两种形态的 `source` 元数据都保留发送者标题和纯 `session-...` ID。
+完整的现役架构合同见 [`docs/architecture-v2.md`](./docs/architecture-v2.md)。
 
 ## 目录结构
 
@@ -125,10 +116,10 @@ Agent 会用 bash 执行这条命令，装完自动挂载、所有会话立即
 dsh-agent-message/
 ├── lib/
 │   ├── index.js        # host 半区：list_peer_agents / send_agent_message / check_delivery
-│   └── client.js       # client 半区：发送方会话导航与复制会话ID按钮
+│   └── client.js       # client 半区：@会话引用、会话导航与复制会话ID按钮
 ├── cordis.patch.yml    # 自注册补丁（dsh.bundle.patch 指向它）
 ├── package.json        # DSH 插件清单（dsh.bundle / dsh.client / dshx.contributes）
-├── docs/               # 设计稿与 README 示例截图
+├── docs/               # 现役架构与 README 示例截图
 ├── README.md           # 中文文档
 └── README.en.md        # English documentation
 ```
@@ -136,7 +127,9 @@ dsh-agent-message/
 ## 限制
 
 - 目标会话必须**未归档**且存在于本机持久化里；归档会话一律拒绝发送。
-- 离线激活（wake）会把目标会话以**默认模型**恢复运行（不继承它上次手动切换的模型选择）。
+- 工具只用于独立 Session 之间通信；真实子代理既不会出现在目标列表中，也不能作为调用方使用这些工具。
+- 同一对 Session（不分发送方向）在滚动 60 秒内最多投递 10 条消息；第 11 条会在写入目标 Inbox 前被拒绝。该窗口只属于当前 Harness 进程，重启后清空。
+- 自动恢复离线会话时会使用**默认模型**（不继承它上次手动切换的模型选择）；恢复失败时消息不会被写入目标 Inbox。
 - 不指定 `messageId` 的批量回执依赖内存记账，只覆盖本进程最近 1000 条发送记录（FIFO 淘汰）；进程重启后仍可凭已知 `messageId` 查询，但不再返回易失的 `sentAt` 和 `mode`。
 - 跨进程/跨机器通信不在本插件范围内。
 

package/cordis.patch.yml

@@ -1,13 +1,5 @@
 # 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

@@ -5,12 +5,160 @@ window.__ModuleLoader__.load({
     var exports = module.exports;
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
     const React = require("react");
+    const { createRoot } = require("react-dom/client");
+    const { IconQueueOutline14, StateDot } = require("@deepseek-ai/dsh-client-ui-primitives");
 
     const name = "dsh-agent-message-client";
-    const inject = ["slots", "timer", "sessions"];
+    const inject = ["slots", "timer", "sessions", "inputTriggers", "workspaces"];
 
     function apply(ctx) {
       const senderSelector = '[data-ref-chip="subagent"], [data-context-relay-sender]';
+      const referenceSource = "agent-message-session";
+      const reactRootSelector = "[data-agent-msg-react-root]";
+      const candidateRows = new WeakMap();
+      const mountedRoots = new Map();
+      const sessionLinks = new Set();
+      const workspaces = ctx.get("workspaces");
+
+      function uiText(zh, en) {
+        const language = String(document.documentElement.lang || navigator.language || "zh").toLowerCase();
+        return language.startsWith("zh") ? zh : en;
+      }
+
+      function sessionRows(includeArchived) {
+        const snapshot = ctx.sessions.list.getSnapshot();
+        const archived = new Set(workspaces?.list.getSnapshot().archivedSessionIds || []);
+        return snapshot.ids
+          .map(function (id) { return snapshot.byId[id]; })
+          .filter(function (row) {
+            return row && !row.blank && row.origin !== "subagent"
+              && (includeArchived || !archived.has(row.id));
+          });
+      }
+
+      function sessionRow(id) {
+        return ctx.sessions.list.getSnapshot().byId[id];
+      }
+
+      function sessionTitle(row) {
+        return String(row?.displayTitle || row?.title || row?.id || "");
+      }
+
+      function compactSessionTitle(row) {
+        const chars = Array.from(sessionTitle(row));
+        return chars.length > 40 ? chars.slice(0, 39).join("") + "…" : chars.join("");
+      }
+
+      function renderInto(host, content) {
+        let root = mountedRoots.get(host);
+        if (!root) {
+          root = createRoot(host);
+          mountedRoots.set(host, root);
+          host.setAttribute("data-agent-msg-react-root", "true");
+        }
+        root.render(content);
+      }
+
+      function cleanupRoots(node) {
+        if (!(node instanceof Element)) return;
+        const hosts = node.matches(reactRootSelector)
+          ? [node].concat(Array.from(node.querySelectorAll(reactRootSelector)))
+          : Array.from(node.querySelectorAll(reactRootSelector));
+        hosts.forEach(function (host) {
+          const root = mountedRoots.get(host);
+          if (!root) return;
+          root.unmount();
+          mountedRoots.delete(host);
+        });
+        const links = node.matches(".agent-msg-session-link")
+          ? [node].concat(Array.from(node.querySelectorAll(".agent-msg-session-link")))
+          : Array.from(node.querySelectorAll(".agent-msg-session-link"));
+        links.forEach(function (element) { sessionLinks.delete(element); });
+      }
+
+      function SessionActivity(props) {
+        return props.running
+          ? React.createElement(StateDot, { state: "done", size: 10, className: "agent-msg-status-dot" })
+          : React.createElement("span", { className: "agent-msg-status-dot agent-msg-status-dot-idle", "aria-hidden": "true" });
+      }
+
+      function SessionReference(props) {
+        return React.createElement("span", { className: "agent-msg-reference-content" },
+          React.createElement(IconQueueOutline14, { size: 14, className: "agent-msg-session-icon" }),
+          React.createElement("span", { className: "agent-msg-reference-title" }, "@" + sessionTitle(props.row)));
+      }
+
+      function RelaySender(props) {
+        return React.createElement("span", { className: "agent-msg-relay-sender-content" },
+          React.createElement(IconQueueOutline14, { size: 14, className: "agent-msg-session-icon" }),
+          React.createElement("span", null, uiText("来自会话 · ", "From Session · ") + props.title + ":"));
+      }
+
+      function enhanceReferenceHost(element, row) {
+        let host = element.querySelector(":scope > .agent-msg-reference-host");
+        if (!host) {
+          element.textContent = "";
+          host = document.createElement("span");
+          host.className = "agent-msg-reference-host";
+          element.appendChild(host);
+        }
+        renderInto(host, React.createElement(SessionReference, { row: row }));
+      }
+
+      const inputTriggers = ctx.get("inputTriggers");
+      if (inputTriggers !== undefined) {
+        ctx.effect(() => inputTriggers.registerSource({
+          trigger: "@",
+          name: referenceSource,
+          order: 2,
+          async candidates(session, request) {
+            if (request.position !== "leading") return [];
+            const query = String(request.query || "").toLowerCase();
+            return sessionRows(false)
+              .filter(function (row) {
+                return String(row.id) !== String(session.sessionId)
+                  && (query === "" || sessionTitle(row).toLowerCase().includes(query));
+              })
+              .sort(function (a, b) {
+                if (a.running !== b.running) return a.running ? -1 : 1;
+                return sessionTitle(a).localeCompare(sessionTitle(b));
+              })
+              .map(function (row) {
+                const candidate = {
+                  name: sessionTitle(row),
+                  description: row.running ? uiText("运行中", "Running") : uiText("空闲", "Idle"),
+                  icon: "",
+                };
+                candidateRows.set(candidate, row);
+                return candidate;
+              });
+          },
+          onPick({ candidate, session }) {
+            const row = candidateRows.get(candidate);
+            if (!row) return undefined;
+            const label = "@" + compactSessionTitle(row);
+            return {
+              claim: {
+                token: label + " ",
+                hint: uiText("输入要处理的内容", "Describe what to do"),
+                async submit(args) {
+                  const content = String(args || "").trim();
+                  if (content === "") return { kind: "error", text: uiText("请输入要处理的内容", "Describe what to do") };
+                  const binding = ctx.sessions.binding(session.sessionId);
+                  if (!binding) return { kind: "error", text: uiText("当前会话不可用", "Current session is unavailable") };
+                  const result = await binding.session.prompt([{
+                    type: "text",
+                    text: "@" + String(row.id) + " " + content,
+                  }], "queue");
+                  return result.ok
+                    ? { kind: "success" }
+                    : { kind: "error", text: result.error.message };
+                },
+              },
+            };
+          },
+        }), "dsh-agent-message: @ session source");
+      }
 
       function senderLink(target) {
         if (!(target instanceof Element)) return null;
@@ -25,7 +173,7 @@ window.__ModuleLoader__.load({
 
       function titleFrom(text) {
         const line = String(text || "").split("\n", 1)[0].trim();
-        const current = line.match(/^From (?:Session|Agent)(?: ·)? (.+?):(?: @session-[\w-]+)?$/);
+        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() || "";
@@ -36,7 +184,6 @@ window.__ModuleLoader__.load({
         const label = element.previousElementSibling;
         const title = titleFrom(label?.textContent);
         if (title && label) {
-          label.textContent = "";
           label.classList.add("agent-msg-sender-prefix");
         }
         return title;
@@ -51,16 +198,116 @@ window.__ModuleLoader__.load({
           const link = senderLink(element);
           if (!link) return;
           const relay = element.matches("[data-context-relay-sender]");
-          const title = relay ? "" : senderTitle(element);
+          const title = relay ? sessionTitle(sessionRow(link.sessionId)) || "@" + link.sessionId : 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");
+          if (relay) renderInto(element, React.createElement(RelaySender, { title: title }));
+          else element.textContent = uiText("来自会话 · ", "From Session · ") + title + ":";
+          element.classList.add("agent-msg-session-link", "agent-msg-sender-link");
+          sessionLinks.add(element);
+          element.setAttribute("role", "link");
+          element.setAttribute("tabindex", "0");
+          element.setAttribute("title", uiText("打开发送方会话", "Open sender session"));
+          element.setAttribute("aria-label", uiText("打开发送方会话：", "Open sender session: ") + (title || link.sessionId));
+        });
+      }
+
+      function prepareRelayCards(root) {
+        if (!(root instanceof Element)) return;
+        const disclosures = root.matches("[data-disclosure-row]")
+          ? [root].concat(Array.from(root.querySelectorAll("[data-disclosure-row]")))
+          : Array.from(root.querySelectorAll("[data-disclosure-row]"));
+        disclosures.forEach(function (row) {
+          if (!String(row.textContent || "").includes("dsh-agent-message")) return;
+          if (row.getAttribute("aria-expanded") !== "true") row.click();
+        });
+
+        const bodies = root.matches('[data-context-form="relay"]')
+          ? [root].concat(Array.from(root.querySelectorAll('[data-context-form="relay"]')))
+          : Array.from(root.querySelectorAll('[data-context-form="relay"]'));
+        bodies.forEach(function (body) {
+          const text = body.querySelector("[data-context-text]");
+          const raw = String(text?.textContent || "");
+          const end = raw.indexOf("</dsh-agent-message>");
+          if (!raw.startsWith("<dsh-agent-message>") || end < 0) return;
+          const card = body.closest('[data-chat-flow-kind="context"]') || body.parentElement;
+          card?.setAttribute("data-agent-msg-relay-card", "true");
+          if (text.dataset.agentMsgRelayBody !== "true") {
+            text.textContent = raw.slice(end + "</dsh-agent-message>".length).trimStart();
+            text.dataset.agentMsgRelayBody = "true";
+          }
+        });
+      }
+
+      function prepareSessionReferences(root) {
+        if (!(root instanceof Element)) return;
+        const elements = root.matches('[data-ref-chip="subagent"]')
+          ? [root].concat(Array.from(root.querySelectorAll('[data-ref-chip="subagent"]')))
+          : Array.from(root.querySelectorAll('[data-ref-chip="subagent"]'));
+        elements.forEach(function (element) {
+          if (element.classList.contains("agent-msg-sender-link")) return;
+          const id = element.dataset.agentMsgSessionId
+            || String(element.textContent || "").trim().match(/^@(session-[\w-]+)$/)?.[1];
+          const row = id ? sessionRow(id) : undefined;
+          if (!id || !row) return;
+          element.dataset.agentMsgSessionId = id;
+          element.classList.add("agent-msg-session-link", "agent-msg-reference-link");
+          sessionLinks.add(element);
           element.setAttribute("role", "link");
           element.setAttribute("tabindex", "0");
-          element.setAttribute("title", "打开发送方会话");
-          element.setAttribute("aria-label", "打开发送方会话：" + (title || link.sessionId));
+          element.setAttribute("title", uiText("打开引用会话", "Open referenced session"));
+          element.setAttribute("aria-label", uiText("打开引用会话：", "Open referenced session: ") + sessionTitle(row));
+          enhanceReferenceHost(element, row);
+        });
+      }
+
+      function prepareSessionMenu(root) {
+        if (!(root instanceof Element)) return;
+        const menu = root.matches('[role="listbox"]') ? root : root.closest('[role="listbox"]') || root.querySelector('[role="listbox"]');
+        if (!menu) return;
+        const group = menu.querySelector('[data-source="' + referenceSource + '"]');
+        if (!group) return;
+        group.textContent = uiText("会话", "Sessions");
+        let element = group.nextElementSibling;
+        while (element && !element.hasAttribute("data-source")) {
+          if (element.matches('button[role="option"]')) {
+            element.classList.add("agent-msg-session-candidate");
+            const spans = element.querySelectorAll(":scope > span");
+            const icon = spans[0];
+            const description = spans[2];
+            if (icon) {
+              icon.classList.add("agent-msg-candidate-icon");
+              renderInto(icon, React.createElement(IconQueueOutline14, { size: 14 }));
+            }
+            if (description) {
+              const running = /^(运行中|Running)$/.test(String(description.textContent || "").trim())
+                || element.dataset.agentMsgRunning === "true";
+              element.dataset.agentMsgRunning = String(running);
+              renderInto(description, React.createElement("span", { className: "agent-msg-status-label" },
+                React.createElement(SessionActivity, { running: running }),
+                React.createElement("span", null, running ? uiText("运行中", "Running") : uiText("空闲", "Idle"))));
+            }
+          }
+          element = element.nextElementSibling;
+        }
+      }
+
+      function prepare(root) {
+        prepareRelayCards(root);
+        prepareSenderLinks(root);
+        prepareSessionReferences(root);
+        prepareSessionMenu(root);
+      }
+
+      function refreshSessionLinks() {
+        sessionLinks.forEach(function (element) {
+          if (!element.isConnected) {
+            sessionLinks.delete(element);
+            return;
+          }
+          if (element.classList.contains("agent-msg-sender-link")) prepareSenderLinks(element);
+          else prepareSessionReferences(element);
         });
       }
 
@@ -122,14 +369,18 @@ window.__ModuleLoader__.load({
           type: "button",
           onClick: onClick,
           onMouseLeave: onMouseLeave,
-          title: "复制会话 ID",
-          "aria-label": "复制会话 ID",
+          title: uiText("复制会话 ID", "Copy session ID"),
+          "aria-label": uiText("复制会话 ID", "Copy session ID"),
           className: "agent-msg-copy-id"
-        }, copyState === "copied" ? "已复制" : copyState === "failed" ? "复制失败" : "复制ID");
+        }, copyState === "copied"
+          ? uiText("已复制", "Copied")
+          : copyState === "failed"
+            ? uiText("复制失败", "Copy failed")
+            : uiText("复制ID", "Copy ID"));
       }
 
       ctx.slots.inject("conversation.session.header.actions", () => ctx.slots.register(
-        { name: "conversation.session.header.actions", id: "copy-session-id", order: 30, label: "复制会话ID" },
+        { name: "conversation.session.header.actions", id: "copy-session-id", order: 30, label: uiText("复制会话ID", "Copy session ID") },
         (props) => React.createElement(CopyButton, { sessionId: props.sessionId })
       ));
 
@@ -138,26 +389,50 @@ window.__ModuleLoader__.load({
         ".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-sender-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-reference-link { display: inline-flex !important; align-items: center; color: var(--dsw-alias-state-business-primary) !important; } " +
+        ".agent-msg-reference-host, .agent-msg-reference-content { display: inline-flex; min-width: 0; align-items: center; } " +
+        ".agent-msg-reference-content { gap: 5px; max-width: 100%; } " +
+        ".agent-msg-reference-title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } " +
+        ".agent-msg-session-icon, .agent-msg-candidate-icon { display: inline-flex; flex: none; color: var(--dsw-alias-state-business-primary); } " +
+        ".agent-msg-relay-sender-content { display: inline-flex; align-items: center; gap: 5px; } " +
+        "[data-agent-msg-relay-card] [data-disclosure-row] { display: none !important; } " +
+        "[data-agent-msg-relay-card] [data-context-form=\"relay\"] { width: fit-content; max-width: min(78%, 760px); max-height: none; margin: 0; padding: 14px 16px; overflow: visible; border: 1px solid rgba(127,127,127,.24); border-radius: 16px 16px 16px 4px; background: var(--dsw-alias-markdown-code-block); color: var(--dsw-alias-label-primary); font: inherit; } " +
+        "[data-agent-msg-relay-card] [data-context-relay-sender] { display: block; width: fit-content; margin: 0 0 8px; color: var(--dsw-alias-state-business-primary); font-size: 13px; font-weight: 600; line-height: 1.5; } " +
+        "[data-agent-msg-relay-card] [data-context-text] { margin: 0; overflow: visible; white-space: pre-wrap; overflow-wrap: anywhere; color: inherit; font: inherit; } " +
+        ".agent-msg-status-dot { flex: none; } " +
+        ".agent-msg-status-dot-idle { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: var(--dsw-alias-label-tertiary); opacity: .7; } " +
+        ".agent-msg-status-label { display: inline-flex; align-items: center; gap: 6px; } " +
+        ".agent-msg-session-candidate { border-radius: 0 !important; } " +
+        ".agent-msg-session-candidate > span:nth-child(2) { flex: 1; min-width: 0; max-width: none; } " +
+        ".agent-msg-session-candidate > span:nth-child(3) { display: flex; flex: none; justify-content: flex-end; margin-left: auto; } " +
         ".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);
+      prepare(document.body);
       const observer = new MutationObserver(function (records) {
         records.forEach(function (record) {
-          record.addedNodes.forEach(prepareSenderLinks);
+          record.removedNodes.forEach(cleanupRoots);
+          record.addedNodes.forEach(prepare);
         });
       });
       observer.observe(document.body, { childList: true, subtree: true });
+      const unsubscribeSessions = ctx.sessions.list.subscribe(refreshSessionLinks);
+      const unsubscribeWorkspaces = workspaces?.list.subscribe(refreshSessionLinks);
       document.addEventListener("click", openSender);
       document.addEventListener("keydown", onKeyDown);
       ctx.effect(() => () => {
         observer.disconnect();
+        unsubscribeSessions();
+        unsubscribeWorkspaces?.();
         document.removeEventListener("click", openSender);
         document.removeEventListener("keydown", onKeyDown);
+        mountedRoots.forEach(function (root) { root.unmount(); });
+        mountedRoots.clear();
+        sessionLinks.clear();
         tag.remove();
       });
     }

package/lib/index.js

@@ -1,30 +1,73 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createUserMessage, freezeMessage } from '@deepseek-ai/dsh-llm/message'
 
 export const name = 'dsh-agent-message'
-export const inject = ['agents', 'tools']
+export const inject = ['agents', 'tools', 'sessionQuery']
 
-export function apply(ctx, config) {
+export function apply(ctx) {
   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
+  const PAIR_MESSAGE_LIMIT = 10
+  const PAIR_WINDOW_MS = 60_000
+  const receiptMeaning = 'claimed 仅表示目标 turn 已从 Inbox 认领消息；传输回执不表示对方已读、回复或完成。'
+  /** 插件恢复的 Session handle；保留到插件卸载，避免 idle dispose 移除 Harness store 投影。 */
+  const resumedHandles = new Map()
+  /** 无向 Session 对 -> 最近成功或正在进行的投递预留；只保护当前 Harness 进程。 */
+  const pairSends = new Map()
+  let lastPairPruneAt = 0
+
+  ctx.effect(() => async () => {
+    const handles = [...resumedHandles.values()]
+    resumedHandles.clear()
+    const settled = await Promise.allSettled(handles.map(async (pending) => (await pending).dispose()))
+    for (const result of settled) {
+      if (result.status === 'rejected') ctx.logger?.warn?.('释放恢复会话失败：' + String(result.reason))
+    }
+  }, 'dsh-agent-message: resumed agent handles')
+
+  ctx.on('agent/disposed', ({ agent }) => {
+    const key = String(agent.id)
+    const pending = resumedHandles.get(key)
+    if (pending === undefined) return
+    pending.then((handle) => {
+      if (handle.agent === agent && resumedHandles.get(key) === pending) resumedHandles.delete(key)
+    }, () => {})
+  })
 
   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 reservePairSend(from, to) {
+    const now = Date.now()
+    if (now < lastPairPruneAt || now - lastPairPruneAt >= PAIR_WINDOW_MS) {
+      for (const [key, entries] of pairSends) {
+        const active = entries.filter((entry) => now - entry.at < PAIR_WINDOW_MS)
+        if (active.length === 0) pairSends.delete(key)
+        else pairSends.set(key, active)
+      }
+      lastPairPruneAt = now
+    }
+    const key = JSON.stringify([String(from), String(to)].sort())
+    const recent = (pairSends.get(key) ?? []).filter((entry) => now - entry.at < PAIR_WINDOW_MS)
+    if (recent.length >= PAIR_MESSAGE_LIMIT) {
+      pairSends.set(key, recent)
+      throw new Error('同一对会话 60 秒内最多投递 10 条消息，请稍后再试')
+    }
+    const reservation = { at: now }
+    recent.push(reservation)
+    pairSends.set(key, recent)
+    return () => {
+      const current = pairSends.get(key)
+      if (current === undefined) return
+      const index = current.indexOf(reservation)
+      if (index !== -1) current.splice(index, 1)
+      if (current.length === 0) pairSends.delete(key)
+    }
   }
 
   function titleOf(agent) {
@@ -57,72 +100,75 @@ export function apply(ctx, config) {
     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
-      }
+  function isSubagentSession(header) {
+    return header?.origin === 'subagent'
+  }
+
+  function assertPeerCaller(agent) {
+    if (agent !== undefined && isSubagentSession(agent.session.header)) {
+      throw new Error('子代理不能使用独立会话通信工具')
     }
   }
 
-  /** 留言投递：写入失败时若目标恰好上线，自动转在线投递（模型无感，不报错）。 */
-  async function deliverLeave(id, message) {
+  function sessionQuery() {
+    const query = ctx.get('sessionQuery')
+    if (query === undefined) throw new Error('本部署缺少 sessionQuery，无法查询逻辑会话')
+    return query
+  }
+
+  async function readLogicalSession(id) {
     try {
-      await leaveOffline(id, message)
-      return { usedMode: 'leave', fallback: '' }
+      return await sessionQuery().readSession(id)
     } catch (error) {
-      const nowLive = agents.get(id)
-      if (nowLive !== undefined) {
-        nowLive.followup(message)
-        return { usedMode: 'followup', fallback: '留言写入时目标恰好上线，已改为在线投递' }
-      }
+      if (error?.code === 'SESSION_QUERY_SESSION_NOT_FOUND') return undefined
       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
+  /** 冷会话投递：公开 resume + followup；同一 Session 复用 handle，仅在插件卸载时释放。 */
+  async function resumeAndFollowup(id, message, inspected) {
+    const existing = agents.get(id)
+    if (existing !== undefined) {
+      existing.followup(message)
+      return existing
+    }
+    const key = String(id)
+    let pending = resumedHandles.get(key)
+    if (pending === undefined) {
+      let presetId = inspected.session.agentPreset
+      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: '' }
+      pending = agents.resume({
+        resumeSessionId: id,
+        agentOptions: { provider: selection.provider ?? '', model: selection.model ?? '' },
+        ...(presets !== undefined && presetId !== undefined
+          ? { setup: async (agentCtx) => { await presets.mount(agentCtx, presetId) } }
+          : {}),
+      })
+      resumedHandles.set(key, pending)
+      pending.catch(() => {
+        if (resumedHandles.get(key) === pending) resumedHandles.delete(key)
+      })
+    }
+
+    let handle
+    try {
+      handle = await pending
+    } catch (error) {
+      const concurrent = agents.get(id)
+      if (concurrent === undefined) throw error
+      concurrent.followup(message)
+      return concurrent
     }
-    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
   }
@@ -138,10 +184,9 @@ export function apply(ctx, config) {
         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))
+    const inspected = await readLogicalSession(to)
+    if (inspected === undefined) return { pending: new Set(), claimed: new Set(), discarded: new Set() }
+    const state = foldInbox(inspected.events.slice(inspected.session.seedLength ?? 0))
     return {
       pending: new Set(state['next-turn'].concat(state['next-step']).map((message) => message.id)),
       claimed: state.claimed,
@@ -149,29 +194,21 @@ export function apply(ctx, config) {
     }
   }
 
-  /** 回执状态：delivered 排队中 / claimed 已认领 / discarded 被丢弃 / unknown 查无此消息。 */
+  /** 回执状态：pending 排队中 / claimed 已认领 / discarded 被丢弃 / unknown 查无此消息。 */
   function deliveryStateOf(messageId, snapshot) {
-    if (snapshot.pending.has(messageId)) return 'delivered'
+    if (snapshot.pending.has(messageId)) return 'pending'
     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/会话，用于跨会话通信。' +
+      '列出逻辑会话目录中所有可发送（未归档且不是子代理）的 DeepSeek Harness 会话，用于跨会话通信。' +
       '每条含：id（会话 ID）、标题、工作目录、status（offline=进程里未加载、重启后未打开；其余为在线）、' +
-      'kind（peer=平级会话 / subagent=子代理）。在线在前、按标题排序。' +
-      '找到目标会话后，用它的 id 调用 send_agent_message 发送消息（目标离线也会自动激活或留言）。' +
+      'kind（固定为 peer，作为兼容字段）。在线在前、按标题排序。普通 fork 即使有 parentSession 也仍是独立会话。' +
+      '找到目标会话后，用它的 id 调用 send_agent_message 发送消息（目标离线时自动恢复后投递，恢复失败则返回错误）。' +
       '注意：它不同于 list_agents（后者列的是你的后台子代理）。',
     parameters: {},
     output: {
@@ -182,42 +219,32 @@ export function apply(ctx, config) {
     },
     async execute(_args, exec) {
       const me = exec.agent
+      assertPeerCaller(me)
       const archived = archivedIds()
-      const persistence = ctx.get('sessionPersistence')
+      const query = sessionQuery()
       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) {
+      const records = await query.listSessions()
+      for (const record of records) {
+        const header = record.header
+        const id = String(header.id)
         if (archived.has(id)) continue
+        if (isSubagentSession(header)) 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 })
+        rows.push({ id, title: '', cwd: header.cwd ?? '', status, kind: 'peer', 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)
-          }
+      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) ?? ''
       }
+      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) => {
@@ -236,79 +263,102 @@ export function apply(ctx, config) {
   ctx.tools.register(defineTool({
     name: 'send_agent_message',
     description:
-      '向另一个 Agent/会话发送消息（跨会话通信）。默认立即送达：目标在线则引导其当前工作（steer）；' +
-      '目标离线（进程里未加载）则自动激活该会话并投递（wake），激活失败自动改为留言（leave）。' +
-      'mode 可选：steer/followup/inject（仅在线）、leave（留言不唤醒）、wake（激活）。归档会话一律拒绝。' +
+      '向指定 Agent 或 Session 投递消息，用于执行当前请求或用户已授予的编排职责中的跨会话通信。' +
+      '@session 只提供目标，不代表发送。' +
+      '收到 relay 消息时，只有正文明确要求向发送方返回内容时才使用本工具回复 senderSessionId；' +
+      '不要回传单纯的 transport ack 或“收到”。' +
+      '默认使用 followup 创建独立的新 turn；' +
+      '目标离线（进程里未加载）时自动恢复该会话后投递。' +
+      '用户无需说出模式名：目标为 running 且整句明确要求立即介入时用 steer，明确要求不打断当前任务、只补充上下文时用 inject；不确定时使用 followup。' +
+      '同一对 Session 双向合计 60 秒内最多投递 10 条消息，超过时拒绝本次投递。' +
+      '归档会话和子代理一律拒绝。' +
       '注意：它不同于 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 激活。不传则智能默认。' },
+      content: { type: 'string', required: true, description: '只填用户要求转达的消息文本，不要自行追加“收到”、“请确认”或其他 transport ack 要求。' },
+      mode: { type: 'string', enum: ['followup', 'inject', 'steer'], description: '不确定时省略并使用 followup；steer=立即介入 running 任务；inject=不打断地补充 running 任务上下文。' },
     },
     output: {
       schema: { type: 'json' },
-      render(_args, value) {
-        return [{ type: 'text', text: value.text || JSON.stringify(value) }]
+      render() {
+        return [{ type: 'text', text: '已投递。' }]
+      },
+      presentationMeta(_args, value) {
+        return value
       },
     },
+    presentResult(_args, result) {
+      const meta = result.meta
+      if (result.isError || meta === null || typeof meta !== 'object' || Array.isArray(meta)) return
+      return {
+        card: 'generic',
+        title: '消息已投递',
+        content: [{ type: 'text', text: meta.text || JSON.stringify(meta, null, 2) }],
+      }
+    },
     async execute(args, exec) {
       const me = exec.agent
       if (me === undefined) throw new Error('no calling agent')
+      assertPeerCaller(me)
       const to = args.to
       if (to === '' || String(to) === String(me.id)) throw new Error('不能给自己发消息')
+      if (args.content.includes('<dsh-agent-message>') || args.content.includes('</dsh-agent-message>')) {
+        throw new Error('消息正文不能包含保留协议标签 dsh-agent-message')
+      }
 
       const archived = archivedIds()
       if (archived.has(String(to))) throw new Error('对方会话已归档，无法发送（请先取消归档）')
+      const mode = args.mode ?? 'followup'
+      const target = agents.get(to)
+      if (target !== undefined && isSubagentSession(target.session.header)) {
+        throw new Error('目标是子代理，不能通过会话通信插件直接发送')
+      }
+      if (target !== undefined && mode !== 'followup' && target.status !== 'running') {
+        throw new Error(mode + ' 仅用于 running 会话；目标当前状态：' + target.status)
+      }
+
+      let inspected
+      if (target === undefined) {
+        inspected = await readLogicalSession(to)
+        if (inspected === undefined) throw new Error('会话不存在：' + to)
+        if (isSubagentSession(inspected.session)) throw new Error('目标是子代理，不能通过会话通信插件直接发送')
+        if (mode !== 'followup') throw new Error('目标离线（进程里未加载）：' + mode + ' 仅用于 running 会话')
+      }
 
       const myTitle = titleOf(me) || String(me.id)
       const source = {
-        kind: form === 'relay' ? 'plugin' : 'user',
-        plugin: name,
-        form,
+        kind: name,
+        form: 'relay',
+        protocolVersion: 1,
         senderSessionId: String(me.id),
+        targetSessionId: String(to),
         senderTitle: myTitle,
       }
-      const message = makeMessage(form === 'relay' ? args.content : 'From Session · ' + myTitle + ': @' + String(me.id) + '\n' + args.content, source)
+      const identified = createUserMessage({ content: [{ type: 'text', text: args.content }], source })
+      const relayHeader = JSON.stringify({ senderSessionId: source.senderSessionId })
+      const message = freezeMessage({
+        ...identified,
+        content: [{ type: 'text', text: '<dsh-agent-message>' + relayHeader + '</dsh-agent-message>\n\n' + args.content }],
+      })
 
-      const target = agents.get(to)
       let usedMode = ''
-      let fallback = ''
+      let targetRuntimeStatus = 'offline'
 
-      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)) + '）')
-            }
-          }
+      const rollbackPairSend = reservePairSend(me.id, to)
+      try {
+        if (target !== undefined) {
+          if (mode === 'followup') { target.followup(message); usedMode = mode }
+          else if (mode === 'inject') { target.inject(message); usedMode = 'inject' }
+          else { target.steer(message); usedMode = 'steer' }
+          targetRuntimeStatus = target.status
         } else {
-          const result = await deliverLeave(to, message)
-          usedMode = result.usedMode
-          fallback = result.fallback
+          const resumed = await resumeAndFollowup(to, message, inspected)
+          usedMode = 'followup'
+          targetRuntimeStatus = resumed.status
         }
+      } catch (error) {
+        rollbackPairSend()
+        throw error
       }
 
       rememberSent(message.id, String(to), usedMode)
@@ -317,8 +367,9 @@ export function apply(ctx, config) {
         to: String(to),
         mode: usedMode,
         messageId: message.id,
-        ...(fallback !== '' ? { fallback } : {}),
-        text: fallback !== '' ? fallback : '已通过 ' + usedMode + ' 模式向 Agent ' + String(to) + ' 发送消息。',
+        state: 'accepted',
+        targetRuntimeStatus,
+        text: '会话 ' + String(to) + ' 已接受投递（' + usedMode + '）。这不表示对方已读、回复或完成。',
       }
     },
   }))
@@ -327,7 +378,8 @@ export function apply(ctx, config) {
     name: 'check_delivery',
     description:
       '按需查询发给某会话的消息状态（跨会话回执，默认安静——只有监督场景主动调用时才返回，不做任何自动播报）。' +
-      '状态：delivered=已送达·排队中；claimed=已被对方认领；discarded=被丢弃；unknown=查无此消息。' +
+      '状态：pending=仍在目标 Inbox 排队；claimed=已被对方认领；discarded=被丢弃；unknown=查无此消息。' +
+      'claimed 不表示已读、已回复或任务完成。' +
       '传 messageId 时可在进程重启后从目标 Inbox 日志恢复状态；不传则只返回本进程内发给该会话的全部已记账消息。',
     parameters: {
       to: { type: 'string', required: true, description: '目标会话 ID。' },
@@ -339,13 +391,14 @@ export function apply(ctx, config) {
         return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
       },
     },
-    async execute(args) {
+    async execute(args, exec) {
+      assertPeerCaller(exec?.agent)
       const target = agents.get(args.to)
-      const targetStatus = target !== undefined ? target.status : 'offline'
+      const targetRuntimeStatus = 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 }] }
+          return { to: args.to, receiptMeaning, entries: [{ messageId: args.messageId, state: 'unknown', targetRuntimeStatus }] }
         }
       }
       const wanted = args.messageId !== undefined
@@ -361,10 +414,10 @@ export function apply(ctx, config) {
           messageId,
           ...(entry !== undefined ? { sentAt: entry.at, mode: entry.mode } : {}),
           state,
-          targetStatus,
+          targetRuntimeStatus,
         })
       }
-      return { to: args.to, entries }
+      return { to: args.to, receiptMeaning, entries }
     },
   }))
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agent-message",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "packageManager": "pnpm@11.1.1",
   "description": "跨会话 Agent 通信：让 DeepSeek Harness 里不同的 Agent 会话互相收发消息。",
   "keywords": ["deepseek", "deepseek-harness", "agent", "multi-agent", "messaging"],
@@ -27,7 +27,9 @@
       "inject": [
         "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-ui-slots",
-        "@deepseek-ai/dsh-client-ui-conversation"
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-input-trigger",
+        "@deepseek-ai/dsh-client-ui-primitives"
       ]
     }
   },
@@ -39,9 +41,11 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.6 <0.2.0",
     "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6 <0.2.0"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "0.1.0-rc.6"
   },
   "engines": {