dsh-interconnect 0.13.0 → 0.15.0

package/README.md

@@ -44,7 +44,7 @@
 - `interconnect_peers()`（不接受参数；返回本实例配置的全部对端及其链路状态）
 - `interconnect_reply(text=...)`（只需文本；回信 session 是本 agent 自己的，目标从记录的 sender 解析）
 
-`instanceId` 是 `interconnect` 行 `peers` 映射里的键；真正用来拨号的 origin 由该映射的值给出（例如隧道端点 `http://127.0.0.1:13080`），**instanceId 本身从不出现在线上**，也不参与路由——origin 才是唯一的拨号依据。
+`instanceId` 是 `interconnect` 行 `peers` 映射里的键；真正用来拨号的 origin 由该映射的值给出（例如隧道端点 `http://127.0.0.1:13080`），**instanceId 本身从不出现在线上**，也不参与路由——origin 才是唯一的拨号依据。值也可以是字面量 `self`，表示拨向本实例自己的宿主 webserver（见「同一实例内两个会话互通」）。
 
 对端没配在这里时，`send`/`reply` 返回 `peer-not-configured`，`ping`/`list` 则在返回
 `reachable: false` 的同时带上 `configured: false`——这一支**重试永远不会成功**，只能去补
@@ -88,6 +88,32 @@ session-b07326da-…                          [running]
 （`100 of possibly more live sessions`）——满页**可能**被截断，缺失的目标仍可能 live。
 ping 与 list 的答复还会按调用方问的 kind 校验形状，形状不符按「无答复」处理（对应 `unreachable`）。
 
+### 同一实例内两个会话互通（`self`）
+
+同一台 DSH 上两个 session 互相投递时，把 peer 的值写成字面量 `self`，不要写死端口：
+
+```yaml
+- id: interconnect
+  config:
+    instanceId: desktop
+    peers:
+      desktop: self   # 键必须等于本实例的 instanceId
+```
+
+`self` 不是 origin。拨号时插件用宿主 webserver **当前监听**的端口拼出
+`http://127.0.0.1:<port>`（绑定 `0.0.0.0` 时回环同样可达），所以宿主以 `--port 0`
+启动、每次重启换端口（DSH Desktop 的默认行为）时不需要改配置，也不需要重启后手工同步。
+
+- **键必须等于 `instanceId`**：自指链路拨到本实例自己的入站 socket，对端在 `hello` 里自报的
+  就是这个 id；键不同会被当成另一个 peer，回信寻址和事件去重都对不上。配置加载时直接报错，
+  而不是留下一条半可用的链路。
+- **端口在每次拨号时重新读取**：webserver 比本插件晚激活、或还没开始监听时，链路保持 `down`
+  并按退避重试，端口就绪后自动连上。`interconnect_peers` 在解析前把 origin 列显示为 `self`，
+  解析后显示实际的 `http://127.0.0.1:<port>`。
+- **没有 webserver 的部署**（headless profile）里这条链路保持 `down`，日志说明它是 self 路由
+  且当前没有监听中的 webserver；`ping`/`send` 按「已配置但不可达」处理，不会得到
+  `peer-not-configured`。
+
 ### 回复（`reply`）
 
 `send` 的线负载带一个 `sender` 身份（**无地址**：`instanceId` + `sessionId`），收到消息的
@@ -164,10 +190,11 @@ interconnect_reply(text="reply")
 `interconnect_send` 不会往 subagent 拥有的 session 里投递，`interconnect_list` 也不会把它们
 列出来。那类 session 的投递权属于它的父 agent，从这里 splice 进 inbox 会和父 agent 抢。判定
 逻辑镜像 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 两条封栏分支。
+0.2.1-rc.3 起 Host 把 live runtime ownership 移出了 agent registry，通用 Session 路由只保留
+header 里 `origin: 'subagent'` 的身份；普通 fork 即使记了 `parentSession` 也按普通 Session
+处理。谓词在插件内保留一份镜像（`isSessionOwnedBySubagent`，见 `src/interconnect/index.ts`），
+因为已安装的 host 可能解析到早于该导出的 root。这是安全规则，Host 改动时必须同步此副本；
+tests 覆盖 origin=subagent 封栏与 parent-owned 普通 fork 可投递两条分支。
 
 已实测：起一个真实 subagent 后，`interconnect_list` 不包含它；直接 `send` 到它的 id 返回
 `session-owned-by-subagent`，消息**没有**进入 inbox。
@@ -242,7 +269,7 @@ Host 自己的 resume 路径对同一个 session 报 `SessionFormatUnsupportedEr
 |---|---|---|
 | `instanceId` | `'dsh'` | 本实例自报的 id，出现在 `ping`/`send`/`list` 的回包里。也作为「对端如何寻址到我」的身份 |
 | `requestTimeoutMs` | `10000` | 出站请求超时，上限 60000 |
-| `peers` | `{}` | **对端路由映射**：`{ [对端 instanceId]: 我拨向它的 origin }`，例如隧道端点 `http://127.0.0.1:13080`。激活时对每个对端自动建持久 WS 链；`send`/`reply`/`ping`/`list` 都按 instanceId 走对应链接。改这一行不需要重启：profile patch 层的改动会重建 fiber 并按新映射建链 |
+| `peers` | `{}` | **对端路由映射**：`{ [对端 instanceId]: 我拨向它的 origin }`，例如隧道端点 `http://127.0.0.1:13080`；值也可以是字面量 `self`，表示拨向本实例自己的宿主 webserver，端口在拨号时从 `webServer.port` 读取（键必须等于 `instanceId`，见「同一实例内两个会话互通」）。激活时对每个对端自动建持久 WS 链；`send`/`reply`/`ping`/`list` 都按 instanceId 走对应链接。改这一行不需要重启：profile patch 层的改动会重建 fiber 并按新映射建链 |
 | `delivery` | `'followup'` | 入站消息未带 `delivery` 时的默认投递模式 |
 | `allowResume` | `true` | 是否允许发送方用 `resume` 唤醒本机的离线 session |
 
@@ -365,6 +392,7 @@ config）：
 
 改完不用重启：patch 层的改动会重建 fiber 并按新映射建链。key 建议与对端自报的 `instanceId`
 一致，否则 B 拨入的那条链路在 A 侧认不出是同一个 peer，事件会重复一份（服务会 warn 一次）。
+同一台机器上的自指场景不走这一节：把值写成 `self`，见「同一实例内两个会话互通」，不需要隧道。
 
 ### 5. 按顺序验证
 
@@ -399,14 +427,15 @@ pnpm run build    # esbuild → lib/
   的 isolate realm 会导致工具/技能行无法 inject 到该服务。
 - 服务只 inject `agents` 与 `credentials`；**宿主 webserver 是可选的**。有 webserver 时入站
   升级路由注册在它上面（`webServer` 经等待式 inject fiber 接入，与组合顺序无关）；没有
-  webserver 的 profile（例如 headless）里服务仍会拨号已配置对端并经这些出站链接投递，即
-  仅出站模式。`dsh.plugin.json` 的 `inject` 与之一致，只有 `agents`、`credentials`。
+  webserver 的 profile（例如 headless）里服务仍会拨号已配置的固定 origin 对端并经这些出站链接
+  投递，即仅出站模式；`self` 路由没有 origin 可拨，会保持 `down` 并记录原因。
+  `dsh.plugin.json` 的 `inject` 与之一致，只有 `agents`、`credentials`。
 - `ws` 是运行依赖，由宿主的 node_modules 提供（构建时 external）。
 
 ## 验证
 
-- 179/179 单测通过（服务 + 工具 + skill，含 wire 校验、畸形帧、心跳/池清理、结果帧按 kind 绑定与投影、list 的行数与字节双上限及满页提示、peer 状态与「未配置」分支、本机原因不得从线缆上来的负例等回归用例）；
-  类型检查、构建均干净。
+- 185/185 单测通过（服务 + 工具 + skill，含 wire 校验、畸形帧、心跳/池清理、结果帧按 kind 绑定与投影、list 的行数与字节双上限及满页提示、peer 状态与「未配置」分支、subagent 封栏与 parent-owned 普通 fork 可投递、`self` 路由的端口延迟解析/真实 `--port 0` webserver 回环/headless 降级/键约束、本机原因不得从线缆上来的负例等回归用例）；
+  类型检查、构建均干净；对公开 DSH master（0.2.2-rc.1）验证。
 - 已在两台机器之间实测双向互通：消息投递、WebSocket 事件推流、以及 agent 经
   `interconnect_send` 工具反向回发，均验证通过。
 - CI（GitHub Actions）：clone 公开 DSH 仓库作为 sibling，跑 `pnpm run check`。

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-interconnect",
   "description": "Cross-instance message/event handoff for DeepSeek Harness (DSH): WebSocket link, model-facing tools, and companion skill.",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "entry": {
     "name": "dsh-interconnect/interconnect",
     "inject": ["agents", "credentials"]

package/lib/index.js

@@ -820,12 +820,8 @@ defineMethod("transform", [
 
 // src/interconnect/index.ts
 import WebSocket, { WebSocketServer } from "ws";
-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);
+function isSessionOwnedBySubagent(session) {
+  return session.header.origin === "subagent";
 }
 function assertNever(value) {
   throw new Error(`interconnect: unhandled variant ${JSON.stringify(value)}`);
@@ -836,6 +832,7 @@ var DEFAULT_INSTANCE_ID = "dsh";
 var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
 var LINK_HANDSHAKE_TIMEOUT_MS = 1e4;
 var LINK_CHANNEL = "/interconnect/link";
+var SELF_PEER_ORIGIN = "self";
 var MAX_INSTANCE_ID_CHARS = 256;
 var MAX_REQUEST_ID_CHARS = 256;
 var MAX_LISTED_SESSIONS = 100;
@@ -963,11 +960,19 @@ var InterconnectService = class extends Service {
     this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     this.delivery = config.delivery ?? "followup";
     this.allowResume = config.allowResume ?? true;
-    for (const origin of Object.values(config.peers ?? {})) {
+    for (const [peerInstanceId, origin] of Object.entries(config.peers ?? {})) {
+      if (origin === SELF_PEER_ORIGIN) {
+        if (peerInstanceId !== this.instanceId) {
+          throw new Error(
+            `interconnect: peer "${peerInstanceId}" is configured as self, but this instance announces "${this.instanceId}"; key a self peer by the instanceId`
+          );
+        }
+        continue;
+      }
       linkUrl(trimBase(origin));
     }
     for (const [peerInstanceId, origin] of Object.entries(config.peers ?? {})) {
-      this.link(peerInstanceId, origin);
+      this.link(peerInstanceId, origin === SELF_PEER_ORIGIN ? () => this.selfOrigin() : origin);
     }
     const upgrade = {
       path: LINK_CHANNEL,
@@ -1210,7 +1215,8 @@ var InterconnectService = class extends Service {
    * `Config.peers` entry; the resulting state owns reconnection for the life of
    * the service fiber.
    * @param instanceId - the peer's `instanceId`.
-   * @param origin - receiver origin this instance dials, e.g. `http://127.0.0.1:13080`.
+   * @param origin - receiver origin this instance dials (e.g.
+   *   `http://127.0.0.1:13080`), or a resolver for a `self` route.
    */
   link(instanceId, origin) {
     const state = new LinkState(
@@ -1220,11 +1226,28 @@ var InterconnectService = class extends Service {
       this.ctx.logger,
       () => this.resolveToken(),
       instanceId,
-      trimBase(origin)
+      typeof origin === "string" ? trimBase(origin) : origin
     );
     this.linkStates.set(instanceId, state);
     state.dial();
   }
+  /**
+   * The origin of this instance's own host webserver, or undefined while no
+   * listening port exists. Read on every dial rather than cached: the
+   * webserver may activate after this service, its port is assigned only in
+   * its listen callback (`--port 0` picks a fresh one per start), and a
+   * replacement webserver would move it again. Loopback is used regardless of
+   * the bind host: a server bound to `0.0.0.0` also accepts `127.0.0.1`, while
+   * `0.0.0.0` itself is a bind address, not a dialable origin.
+   * @returns `http://127.0.0.1:<port>`, or undefined without a listening server.
+   */
+  selfOrigin() {
+    const server = this.ctx.get("webServer");
+    if (server === void 0) return void 0;
+    const port = server.port;
+    if (typeof port !== "number" || port <= 0) return void 0;
+    return `http://127.0.0.1:${String(port)}`;
+  }
   /** Push one serialized lifecycle fact out to every linked peer over WS. */
   fanout(notification) {
     this.broadcast(notification);
@@ -1359,7 +1382,7 @@ var InterconnectService = class extends Service {
    * @returns the bounded listing.
    */
   listSessions(rowBudgetBytes) {
-    const reachable = this.ctx.agents.list().filter((agent) => !isSessionOwnedBySubagent(this.ctx, agent.session, agent));
+    const reachable = this.ctx.agents.list().filter((agent) => !isSessionOwnedBySubagent(agent.session));
     const sessions = [];
     let used = 0;
     for (const agent of reachable.slice(0, MAX_LISTED_SESSIONS)) {
@@ -1386,7 +1409,8 @@ var InterconnectService = class extends Service {
     let title;
     try {
       const snapshot = this.ctx.get("sessionProjections")?.snapshot(agent.session);
-      const value = snapshot?.values.title;
+      const values = snapshot?.values;
+      const value = values?.title;
       if (typeof value === "string" && value !== "") title = value;
     } catch {
       title = void 0;
@@ -1444,7 +1468,7 @@ var InterconnectService = class extends Service {
       }
       agent = woken.agent;
     }
-    if (isSessionOwnedBySubagent(this.ctx, agent.session, agent)) {
+    if (isSessionOwnedBySubagent(agent.session)) {
       return { delivered: false, instance: this.instanceId, reason: "session-owned-by-subagent" };
     }
     const sender = (() => {
@@ -1653,24 +1677,40 @@ var LinkState = class {
     this.logger = logger;
     this.resolveToken = resolveToken;
     this.instanceId = instanceId;
-    this.peer = origin;
+    this.origin = origin;
   }
   dialed;
   closed = false;
   retry = 0;
   reconnectTimer;
   warnedNoToken = false;
-  /** Receiver origin this link dials. */
-  peer;
+  warnedNoOrigin = false;
   instanceId;
+  origin;
+  /** The origin this link dials now; for an unresolved `self` route, the sentinel is shown. */
+  get peer() {
+    return typeof this.origin === "string" ? this.origin : this.origin() ?? SELF_PEER_ORIGIN;
+  }
   /** Open the socket; reconnect is scheduled by the close handler. */
   dial() {
     if (this.closed) return;
+    const origin = typeof this.origin === "string" ? this.origin : this.origin();
+    if (origin === void 0) {
+      if (this.retry >= 1 && !this.warnedNoOrigin) {
+        this.warnedNoOrigin = true;
+        this.logger.warn(
+          `interconnect: peer ${this.instanceId} is configured as self but this instance has no listening webServer port yet; the link stays down and retries`
+        );
+      }
+      this.scheduleReconnect();
+      return;
+    }
+    this.warnedNoOrigin = false;
     let url;
     try {
-      url = linkUrl(this.peer);
+      url = linkUrl(origin);
     } catch {
-      this.logger.warn(`interconnect: invalid peer origin ${this.peer}; link to ${this.instanceId} stays down`);
+      this.logger.warn(`interconnect: invalid peer origin ${origin}; link to ${this.instanceId} stays down`);
       return;
     }
     void this.resolveToken().then((token) => {

package/lib/interconnect/index.js

@@ -820,12 +820,8 @@ defineMethod("transform", [
 
 // src/interconnect/index.ts
 import WebSocket, { WebSocketServer } from "ws";
-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);
+function isSessionOwnedBySubagent(session) {
+  return session.header.origin === "subagent";
 }
 function assertNever(value) {
   throw new Error(`interconnect: unhandled variant ${JSON.stringify(value)}`);
@@ -836,6 +832,7 @@ var DEFAULT_INSTANCE_ID = "dsh";
 var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
 var LINK_HANDSHAKE_TIMEOUT_MS = 1e4;
 var LINK_CHANNEL = "/interconnect/link";
+var SELF_PEER_ORIGIN = "self";
 var MAX_INSTANCE_ID_CHARS = 256;
 var MAX_REQUEST_ID_CHARS = 256;
 var MAX_LISTED_SESSIONS = 100;
@@ -963,11 +960,19 @@ var InterconnectService = class extends Service {
     this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     this.delivery = config.delivery ?? "followup";
     this.allowResume = config.allowResume ?? true;
-    for (const origin of Object.values(config.peers ?? {})) {
+    for (const [peerInstanceId, origin] of Object.entries(config.peers ?? {})) {
+      if (origin === SELF_PEER_ORIGIN) {
+        if (peerInstanceId !== this.instanceId) {
+          throw new Error(
+            `interconnect: peer "${peerInstanceId}" is configured as self, but this instance announces "${this.instanceId}"; key a self peer by the instanceId`
+          );
+        }
+        continue;
+      }
       linkUrl(trimBase(origin));
     }
     for (const [peerInstanceId, origin] of Object.entries(config.peers ?? {})) {
-      this.link(peerInstanceId, origin);
+      this.link(peerInstanceId, origin === SELF_PEER_ORIGIN ? () => this.selfOrigin() : origin);
     }
     const upgrade = {
       path: LINK_CHANNEL,
@@ -1210,7 +1215,8 @@ var InterconnectService = class extends Service {
    * `Config.peers` entry; the resulting state owns reconnection for the life of
    * the service fiber.
    * @param instanceId - the peer's `instanceId`.
-   * @param origin - receiver origin this instance dials, e.g. `http://127.0.0.1:13080`.
+   * @param origin - receiver origin this instance dials (e.g.
+   *   `http://127.0.0.1:13080`), or a resolver for a `self` route.
    */
   link(instanceId, origin) {
     const state = new LinkState(
@@ -1220,11 +1226,28 @@ var InterconnectService = class extends Service {
       this.ctx.logger,
       () => this.resolveToken(),
       instanceId,
-      trimBase(origin)
+      typeof origin === "string" ? trimBase(origin) : origin
     );
     this.linkStates.set(instanceId, state);
     state.dial();
   }
+  /**
+   * The origin of this instance's own host webserver, or undefined while no
+   * listening port exists. Read on every dial rather than cached: the
+   * webserver may activate after this service, its port is assigned only in
+   * its listen callback (`--port 0` picks a fresh one per start), and a
+   * replacement webserver would move it again. Loopback is used regardless of
+   * the bind host: a server bound to `0.0.0.0` also accepts `127.0.0.1`, while
+   * `0.0.0.0` itself is a bind address, not a dialable origin.
+   * @returns `http://127.0.0.1:<port>`, or undefined without a listening server.
+   */
+  selfOrigin() {
+    const server = this.ctx.get("webServer");
+    if (server === void 0) return void 0;
+    const port = server.port;
+    if (typeof port !== "number" || port <= 0) return void 0;
+    return `http://127.0.0.1:${String(port)}`;
+  }
   /** Push one serialized lifecycle fact out to every linked peer over WS. */
   fanout(notification) {
     this.broadcast(notification);
@@ -1359,7 +1382,7 @@ var InterconnectService = class extends Service {
    * @returns the bounded listing.
    */
   listSessions(rowBudgetBytes) {
-    const reachable = this.ctx.agents.list().filter((agent) => !isSessionOwnedBySubagent(this.ctx, agent.session, agent));
+    const reachable = this.ctx.agents.list().filter((agent) => !isSessionOwnedBySubagent(agent.session));
     const sessions = [];
     let used = 0;
     for (const agent of reachable.slice(0, MAX_LISTED_SESSIONS)) {
@@ -1386,7 +1409,8 @@ var InterconnectService = class extends Service {
     let title;
     try {
       const snapshot = this.ctx.get("sessionProjections")?.snapshot(agent.session);
-      const value = snapshot?.values.title;
+      const values = snapshot?.values;
+      const value = values?.title;
       if (typeof value === "string" && value !== "") title = value;
     } catch {
       title = void 0;
@@ -1444,7 +1468,7 @@ var InterconnectService = class extends Service {
       }
       agent = woken.agent;
     }
-    if (isSessionOwnedBySubagent(this.ctx, agent.session, agent)) {
+    if (isSessionOwnedBySubagent(agent.session)) {
       return { delivered: false, instance: this.instanceId, reason: "session-owned-by-subagent" };
     }
     const sender = (() => {
@@ -1653,24 +1677,40 @@ var LinkState = class {
     this.logger = logger;
     this.resolveToken = resolveToken;
     this.instanceId = instanceId;
-    this.peer = origin;
+    this.origin = origin;
   }
   dialed;
   closed = false;
   retry = 0;
   reconnectTimer;
   warnedNoToken = false;
-  /** Receiver origin this link dials. */
-  peer;
+  warnedNoOrigin = false;
   instanceId;
+  origin;
+  /** The origin this link dials now; for an unresolved `self` route, the sentinel is shown. */
+  get peer() {
+    return typeof this.origin === "string" ? this.origin : this.origin() ?? SELF_PEER_ORIGIN;
+  }
   /** Open the socket; reconnect is scheduled by the close handler. */
   dial() {
     if (this.closed) return;
+    const origin = typeof this.origin === "string" ? this.origin : this.origin();
+    if (origin === void 0) {
+      if (this.retry >= 1 && !this.warnedNoOrigin) {
+        this.warnedNoOrigin = true;
+        this.logger.warn(
+          `interconnect: peer ${this.instanceId} is configured as self but this instance has no listening webServer port yet; the link stays down and retries`
+        );
+      }
+      this.scheduleReconnect();
+      return;
+    }
+    this.warnedNoOrigin = false;
     let url;
     try {
-      url = linkUrl(this.peer);
+      url = linkUrl(origin);
     } catch {
-      this.logger.warn(`interconnect: invalid peer origin ${this.peer}; link to ${this.instanceId} stays down`);
+      this.logger.warn(`interconnect: invalid peer origin ${origin}; link to ${this.instanceId} stays down`);
       return;
     }
     void this.resolveToken().then((token) => {