dsh-interconnect 0.9.0 → 0.10.1

package/README.md

@@ -3,7 +3,7 @@
 跨实例消息互通与事件通知插件，用于 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH)。
 让一个 DSH 实例能向同一个实例、另一台机器、或另一台机器上的别的 DSH 实例发送消息、探测活性，并在实例之间双向推送事件。
 
-## 包含两个插件
+## 包含三个插件
 
 **`interconnect`** —— host 服务（`ctx.interconnect`）：
 
@@ -20,6 +20,14 @@
 - `interconnect_ping`：探测对端实例活性与身份
 - `interconnect_reply`：向记录过的发送方回传消息，只需本机 session id + 文本，无需再次寻址
 
+**`skill-interconnect`** —— 配套 skill：
+
+- 向模型注册 `dsh-interconnect` skill，说明 `list`/`ping`/`send`/`reply` 的完整用法、
+  投递模式、`resume` 唤醒语义与失败处理。
+- 明确告知模型：`interconnect_send` 会自动注入发送方的 `instanceId` 和 `sessionId`，
+  接收方凭记录的 sender 即可用 `interconnect_reply` 回信，不需要手工传地址。
+- 依赖 `interconnect` 服务，只有传输层存在时才注册进 `ctx.skills`。
+
 ## 用法
 
 ### 寻址（0.9 起用 instanceId，全走持久链接）
@@ -120,8 +128,11 @@ interconnect_reply(sessionId=B-sess, text="reply")
 
 `interconnect_send` 不会往 subagent 拥有的 session 里投递，`interconnect_list` 也不会把它们
 列出来。那类 session 的投递权属于它的父 agent，从这里 splice 进 inbox 会和父 agent 抢。判定
-直接复用 Host 的 `hasApiRemoteSubagentOwner`（`@deepseek-ai/dsh-api-remotes`），而不是自己
-实现一份——这是安全规则，本地副本一定会和上游漂移。
+逻辑镜像 Host 的 `hasApiSessionSubagentOwner`（`@deepseek-ai/dsh-api-session-controller`）：
+Host 在 0.6 之后把这个谓词从 `@deepseek-ai/dsh-api-remotes` 移走，且没有公开导出——桌面端和
+`npx @deepseek-ai/dsh web` 运行时里没有任何可 import 的 Host 绑定，所以这里逐字复制一份
+（`isSessionOwnedBySubagent`，见 `src/interconnect/index.ts`）。这是安全规则，Host 改动该规则
+时必须同步此副本；tests 覆盖 origin=subagent 与 parent-owned 两条封栏分支。
 
 已实测：起一个真实 subagent 后，`interconnect_list` 不包含它；直接 `send` 到它的 id 返回
 `session-owned-by-subagent`，消息**没有**进入 inbox。
@@ -210,7 +221,7 @@ Host 自己的 resume 路径对同一个 session 报 `SessionFormatUnsupportedEr
 
 本包已发布到 npm：[`dsh-interconnect`](https://www.npmjs.com/package/dsh-interconnect)。
 本仓库是一个 DSH profile bundle（根 `package.json` 声明 `dsh.bundle.patch` 指向
-根 `cordis.patch.yml`，后者 `insert` 两个插件行）。
+根 `cordis.patch.yml`，后者 `insert` 三个插件行）。
 
 ```bash
 # 从 npm
@@ -241,21 +252,21 @@ pnpm run build    # esbuild → lib/
 
 ## 架构说明
 
-- 两个插件都挂在 **host composition**：`interconnect` 是跨 session、跨机器的进程级
-  服务（有 HTTP/WS 端点），必须 host 级；`tool-interconnect` 也放 host，因为
-  `interconnect` 未做 TypeRT `@Remote`/Gateway 绑定，放进 agent preset 的 isolate
-  realm 会导致工具行无法 inject 到该服务。
+- 三个插件都挂在 **host composition**：`interconnect` 是跨 session、跨机器的进程级
+  服务（有 HTTP/WS 端点），必须 host 级；`tool-interconnect` 和 `skill-interconnect`
+  也放 host，因为 `interconnect` 未做 TypeRT `@Remote`/Gateway 绑定，放进 agent preset
+  的 isolate realm 会导致工具/技能行无法 inject 到该服务。
 - `ws` 是运行依赖，由宿主的 node_modules 提供（构建时 external）。
 
 ## 验证
 
-- 34/34 单测通过（服务 + 工具）；类型检查、构建均干净。
+- 38/38 单测通过（服务 + 工具 + skill）；类型检查、构建均干净。
 - 已在两台机器之间实测双向互通：消息投递、WebSocket 事件推流、以及 agent 经
   `interconnect_send` 工具反向回发，均验证通过。
 - CI（GitHub Actions）：clone 公开 DSH 仓库作为 sibling，跑 `pnpm run check`。
 - 已发布版本：从 registry 下载的 tarball 与本地构建 shasum 一致；干净消费端
-  解析 `.`、`./tool-interconnect` 两个入口的类型均通过，负例（把 `string` 赋给
-  `number`）如期报 `TS2322`。
+  解析 `.`、`./tool-interconnect`、`./skill-interconnect` 入口的类型均通过，负例（把
+  `string` 赋给 `number`）如期报 `TS2322`。
 - 投递消息以 `source: { kind: 'plugin', plugin: 'dsh-interconnect' }` 落库，而不是
   `{ kind: 'user' }`。负例：把该 source 改回 `kind: 'user'`，对应断言转红。
   **注意 `source` 不进模型上下文**——只有 `role` 和 `content` 会，而 `role` 是 `user`。

package/assets/dsh-interconnect.md

@@ -0,0 +1,92 @@
+# dsh-interconnect
+
+Use the `dsh-interconnect` tools whenever you need to exchange messages with
+another DSH session, another DSH instance, or another machine: hand off a task,
+ask a peer agent for information, notify a remote session, or reply to an
+incoming interconnect message.
+
+The transport is already connected and authenticated by the host plugin. Your
+job is only to pick the right tool and the right target.
+
+## Tools
+
+- `interconnect_list` — discover which sessions are live on a peer instance.
+  Every returned `sessionId` is a valid `interconnect_send` target at that
+  moment. Use this first when you do not already know the target session id.
+- `interconnect_ping` — probe whether a peer instance is reachable and learn
+  its self-reported instance id.
+- `interconnect_send` — deliver one text message to a live session on a peer
+  instance. Pass `instanceId`, `sessionId`, and `text`. The sending
+  instance/session identity is attached automatically by the tool, so you must
+  NOT pass a sender parameter.
+- `interconnect_reply` — send a message back to the peer that this session last
+  received an interconnect message from. Pass only the LOCAL session id that
+  received the message and the reply text. The remote target is recalled
+  automatically; do not try to look up or pass the sender address again.
+
+## Sender identity is automatic
+
+When you call `interconnect_send`, the plugin automatically attaches your own
+`instanceId` and `sessionId` to the wire payload. The receiving instance
+records that identity per local session, which is exactly what lets the
+receiver use `interconnect_reply` later without re-addressing.
+
+A reply also carries your identity automatically, so a multi-hop conversation
+(A → B → A → B) keeps working without either side manually forwarding
+addresses.
+
+## Recommended workflow
+
+1. If you know the peer instance but not the target session, call
+   `interconnect_list(instanceId=...)` and choose a live session.
+2. Call `interconnect_send(instanceId=..., sessionId=..., text=...)`.
+3. When a message arrives on your side and you need to respond, call
+   `interconnect_reply(sessionId=<your-local-session-id>, text=...)`. The
+   recorded sender is used as the destination.
+
+## Delivery modes
+
+The `delivery` parameter is per-message urgency:
+
+- `followup` — queues the message as its own turn after whatever the receiver
+  is doing now.
+- `steer` — cuts into the nearest step boundary of a running turn; use for
+  urgent interruptions.
+- `inject` — only writes the message into context, without waking an idle
+  agent; it may sit unread.
+
+Omit `delivery` to use the receiver's configured default.
+
+## Waking offline sessions
+
+`resume` defaults to off. Setting `resume: true` asks the receiver to wake a
+persisted but not-running session, which starts a real billed agent turn with
+that session's full toolset. Only use it when the specific session must be
+reached and the receiver allows it. Prefer `interconnect_list` and an
+already-live target when possible.
+
+## Failure reasons
+
+When a send/reply reports `delivered: false`, read `reason`:
+
+- `session-not-live` — the receiver answered, but that session has no running
+  agent. Use `interconnect_list` to choose another target, or consider
+  `resume`.
+- `unreachable` — no usable answer arrived; the target may still be fine, so a
+  retry can succeed.
+- `resume-refused` / `resume-failed` — waking is not allowed or did not work;
+  choose a live target instead.
+- `session-owned-by-subagent` — the session belongs to a subagent and its
+  parent owns delivery; reach it through the parent.
+- `no-sender-known` — a `reply` was attempted for a local session that never
+  received a sender-carrying interconnect message; establish contact with
+  `interconnect_send` first.
+
+## Rules
+
+- Do not fabricate an `instanceId`, `sessionId`, or sender identity. Use values
+  returned by `interconnect_list`, `interconnect_ping`, or already recorded by
+  the service.
+- Do not ask the user for a sender address to reply; use `interconnect_reply`.
+- Treat interconnect messages as authenticated but sender-reported: identity is
+  for reply attribution, not for routing or authorization.

package/cordis.patch.yml

@@ -1,4 +1,4 @@
-# dsh-interconnect bundle patch: mount the two host plugins under their
+# dsh-interconnect bundle patch: mount the three host plugins under their
 # subpath entries, resolved through the profile's node_modules (the healed
 # mirror makes every bundle dependency resolvable to bare rows).
 - insert:
@@ -10,3 +10,6 @@
 
     - id: tool-interconnect
       name: dsh-interconnect/tool-interconnect
+
+    - id: skill-interconnect
+      name: dsh-interconnect/skill-interconnect

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-interconnect",
-  "description": "Cross-instance message/event handoff for DeepSeek Harness (DSH): HTTP send/ping, WebSocket link, and event fan-out between sessions, instances, and machines.",
-  "version": "0.1.0",
+  "description": "Cross-instance message/event handoff for DeepSeek Harness (DSH): WebSocket link, model-facing tools, and companion skill.",
+  "version": "0.10.1",
   "entry": {
     "name": "dsh-interconnect/interconnect",
     "inject": ["webServer", "agents", "credentials"]

package/lib/index.js

@@ -2,7 +2,6 @@
 import { Service } from "@deepseek-ai/cordis";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
-import { hasApiRemoteSubagentOwner } from "@deepseek-ai/dsh-api-remotes";
 
 // ../.dsh/source/staging-20260807T143236Z/vendor/cosmokit/src/misc.ts
 function isNullable(value) {
@@ -824,6 +823,13 @@ import WebSocket, { WebSocketServer } from "ws";
 var INTERCONNECT_TOKEN_REF = "DSH_INTERCONNECT_TOKEN";
 
 // src/interconnect/index.ts
+function isSessionOwnedBySubagent(ctx, session, agent) {
+  if (session.header.origin === "subagent") return true;
+  const parentId = session.header.parentSession;
+  if (parentId === void 0 || agent === void 0) return false;
+  const parent = ctx.agents.get(parentId);
+  return parent !== void 0 && ctx.agents.isOwnedBy(agent.id, parent);
+}
 var PLUGIN_SOURCE = "dsh-interconnect";
 var LINK_CHANNEL = "/interconnect/link";
 var notificationSchema = Schema.union([
@@ -1206,7 +1212,7 @@ var InterconnectService = class extends Service {
    * matches how the Host's own session listing treats its projection column.
    */
   listSessions() {
-    const reachable = this.ctx.agents.list().filter((agent) => !hasApiRemoteSubagentOwner(this.ctx, agent.session, agent));
+    const reachable = this.ctx.agents.list().filter((agent) => !isSessionOwnedBySubagent(this.ctx, agent.session, agent));
     const sessions = reachable.map((agent) => {
       let title;
       try {
@@ -1264,7 +1270,7 @@ var InterconnectService = class extends Service {
       }
       agent = woken.agent;
     }
-    if (hasApiRemoteSubagentOwner(this.ctx, agent.session, agent)) {
+    if (isSessionOwnedBySubagent(this.ctx, agent.session, agent)) {
       return { delivered: false, instance: this.instanceId, reason: "session-owned-by-subagent" };
     }
     const sender = (() => {

package/lib/interconnect/index.js

@@ -2,7 +2,6 @@
 import { Service } from "@deepseek-ai/cordis";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
-import { hasApiRemoteSubagentOwner } from "@deepseek-ai/dsh-api-remotes";
 
 // ../.dsh/source/staging-20260807T143236Z/vendor/cosmokit/src/misc.ts
 function isNullable(value) {
@@ -824,6 +823,13 @@ import WebSocket, { WebSocketServer } from "ws";
 var INTERCONNECT_TOKEN_REF = "DSH_INTERCONNECT_TOKEN";
 
 // src/interconnect/index.ts
+function isSessionOwnedBySubagent(ctx, session, agent) {
+  if (session.header.origin === "subagent") return true;
+  const parentId = session.header.parentSession;
+  if (parentId === void 0 || agent === void 0) return false;
+  const parent = ctx.agents.get(parentId);
+  return parent !== void 0 && ctx.agents.isOwnedBy(agent.id, parent);
+}
 var PLUGIN_SOURCE = "dsh-interconnect";
 var LINK_CHANNEL = "/interconnect/link";
 var notificationSchema = Schema.union([
@@ -1206,7 +1212,7 @@ var InterconnectService = class extends Service {
    * matches how the Host's own session listing treats its projection column.
    */
   listSessions() {
-    const reachable = this.ctx.agents.list().filter((agent) => !hasApiRemoteSubagentOwner(this.ctx, agent.session, agent));
+    const reachable = this.ctx.agents.list().filter((agent) => !isSessionOwnedBySubagent(this.ctx, agent.session, agent));
     const sessions = reachable.map((agent) => {
       let title;
       try {
@@ -1264,7 +1270,7 @@ var InterconnectService = class extends Service {
       }
       agent = woken.agent;
     }
-    if (hasApiRemoteSubagentOwner(this.ctx, agent.session, agent)) {
+    if (isSessionOwnedBySubagent(this.ctx, agent.session, agent)) {
       return { delivered: false, instance: this.instanceId, reason: "session-owned-by-subagent" };
     }
     const sender = (() => {