dsh-interconnect 0.5.0 → 0.6.1

package/README.md

@@ -7,17 +7,19 @@
 
 **`interconnect`** —— host 服务（`ctx.interconnect`）：
 
-- `send` / `ping` HTTP 端点（`/interconnect/*`）：跨实例、跨机器投递消息、探测活性
+- `send` / `list` / `ping` HTTP 端点（`/interconnect/*`）：跨实例、跨机器投递消息、枚举 live session、探测活性
 - `/interconnect/link` WebSocket 端点：双向实时事件推流，含心跳与指数退避重连
 - 事件 fan-out（HTTP + WebSocket），入站事件以 `interconnect/event` 发出
 - 共享密钥鉴权（`DSH_INTERCONNECT_TOKEN`，bearer，fail-closed，timing-safe 比较）
 
 **`tool-interconnect`** —— 模型可见工具：
 
-- `interconnect_send`：向对端实例的指定 session 投递消息，可选 `delivery` 指定投递模式
+- `interconnect_send`：向对端实例的指定 session 投递消息；可选 `delivery` 选投递模式、`resume` 唤醒离线 session
 - `interconnect_list`：列出对端实例的 live session（id + 标题 + 状态），用于在不预先知道 session id 时寻址
 - `interconnect_ping`：探测对端实例活性与身份
 
+## 用法
+
 ### 寻址
 
 `interconnect_send` 需要一个 session id，而调用方通常并不知道。`interconnect_list` 返回对端
@@ -35,22 +37,59 @@ session-b07326da-…                          [running]
 只列 live session 是有意的：`send` 能到达的正好是这些。对端存在但没有运行 agent 的 session
 不会出现在列表里，也收不到消息。
 
-### 投递失败的两种原因
+### 投递失败的原因
 
-`delivered: false` 单独一个布尔值无法据以行动，因为两种失败需要相反的应对，所以
+`delivered: false` 单独一个布尔值无法据以行动，因为不同失败需要不同应对，所以
 `SendResult.reason` 会指明是哪一种：
 
 | `reason` | 含义 | 应对 |
 |---|---|---|
-| `session-not-live` | 对端**答复了**，但那个 session 没有运行中的 agent | 重试同一个 id 无用；用 `interconnect_list` 换一个目标 |
+| `session-not-live` | 对端**答复了**，但那个 session 没有运行中的 agent | 重试同一个 id 无用；用 `interconnect_list` 换目标，或带 `resume` |
 | `unreachable` | 没拿到可用答复（传输失败，或鉴权被拒） | 目标 session 可能完好，重试可能成功 |
+| `resume-refused` | 请求了唤醒，但对端不允许（`allowResume: false`） | 再带 `resume` 也没用 |
+| `resume-failed` | 允许唤醒且尝试了，但没得到 live agent（无此持久化 session，或被别的 owner 持有） | 换目标 |
 
 `reason` 恰好在 `delivered` 为 false 时出现。
 
-**不会自动 resume 已持久化但未打开的 session**，这是有意的：`agents.resume()` 返回的
-handle 由调用方 context 拥有，实测确认插件 fiber 被 dispose 时会把 resume 出来的 agent 和
-session 一起拆掉（用根 ctx 调用则不会——ownership 跟随调用时用的那个 context）。让本插件的
-卸载连带杀掉用户正在用的会话是不可接受的，所以这里只报告 `session-not-live`。
+### 唤醒离线 session（`resume`，默认关）
+
+`SendPayload.resume: true` 让对端唤醒一个已持久化但没有运行 agent 的 session。
+
+**默认关闭是有意的。** 实测确认：消息投递到 session 后会触发一次**完整的 agent 回合**——
+`wakeDriver()` → `kick()` → `turn()` → `llm.stream()`，即一次计费的模型调用，且 assembly
+里带着该 session 的完整工具集。在一个用户没打开、看不到、也无法中断的会话里启动这些，和
+「推一下已经开着的会话」不是一个量级，所以必须由发送方显式请求。
+
+两侧都有控制权：
+
+- **发送方**按消息决定 `resume`（默认不唤醒）
+- **接收方**用 `Config.allowResume`（默认 `true`）一票否决——因为花钱和跑工具的是它那台机器；
+  拒绝时在跑 lookup 之前就短路，回 `resume-refused`
+
+唤醒**不是**调本插件的 `ctx.agents.resume()`，而是走 Host 已配置的 `agent` lookup
+（`typert.lookups.get('agent')`）。这一点是关键：`resume()` 返回的 handle 由**调用方
+context** 拥有，实测确认插件 fiber 被 dispose 时会把 resume 出来的 agent 和 session 一起
+拆掉（同一调用改用根 ctx 则两者都存活）。交给 Host 的 resolver 之后 owner 是 api-proxy，
+而且它会按 session 日志里记录的 preset 重建工具集——不是空壳。
+
+没有 Host lookup 的部署（headless、无 api-proxy 的 profile）会降级为 `session-not-live`，
+不会报错。
+
+唤醒**只把消息放进 inbox**，是否真的开始处理取决于 `delivery`：
+
+```text
+# 唤醒并让对方实际处理（会起一个计费回合）
+interconnect_send(baseUrl, sessionId, text, resume=true, delivery="followup")
+
+# 唤醒但不起回合：只写入上下文，等对方下次被唤醒时一起读
+interconnect_send(baseUrl, sessionId, text, resume=true, delivery="inject")
+```
+
+已实测：`resume=true` + `inject` 之后目标从非 live 变 live（`interconnect_list` 计数 +1），
+且该 session 日志里只多一条 `agent/inbox/spliced`、**后面没有 `turn/start`**。
+
+**已知限制**：磁盘格式过旧的 session 无法唤醒，返回 `resume-failed`。这不是本插件的限制——
+Host 自己的 resume 路径对同一个 session 报 `SessionFormatUnsupportedError`，同样失败。
 
 ### 投递模式
 
@@ -66,6 +105,30 @@ session 一起拆掉（用根 ctx 调用则不会——ownership 跟随调用时
 该字段时沿用接收方 `Config.delivery` 的配置。`SendResult.delivery` 回报实际生效的
 模式，发送方据此判断覆盖是否被采纳。
 
+## 配置
+
+`interconnect` 行的 `config`（全部可选，下表为默认值）：
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `instanceId` | `'dsh'` | 本实例自报的 id，出现在 `ping`/`send`/`list` 的回包里。仅诊断用，**不作为路由依据** |
+| `requestTimeoutMs` | `10000` | 出站请求超时，上限 60000 |
+| `peers` | `[]` | 启动时的事件 fan-out 目标；运行时可用 `subscribe()` 增补 |
+| `delivery` | `'followup'` | 入站消息未带 `delivery` 时的默认投递模式 |
+| `allowResume` | `true` | 是否允许发送方用 `resume` 唤醒本机的离线 session |
+
+```yaml
+- id: interconnect
+  config:
+    instanceId: my-box
+    peers: ['http://peer-host:3080']
+    delivery: followup
+    allowResume: false   # 拒绝一切唤醒请求
+```
+
+鉴权用的共享密钥不在这里，而是取自 credentials 的 `DSH_INTERCONNECT_TOKEN`（fail-closed：
+没有 token 时端点返回 403）。
+
 ## 安装
 
 本包已发布到 npm：[`dsh-interconnect`](https://www.npmjs.com/package/dsh-interconnect)。
@@ -109,16 +172,20 @@ pnpm run build    # esbuild → lib/
 
 ## 验证
 
-- 22/22 单测通过（服务 17 + 工具 5）；类型检查、构建均干净。
+- 50/50 单测通过（服务 + 工具）；类型检查、构建均干净。
 - 已在两台机器之间实测双向互通：消息投递、WebSocket 事件推流、以及 agent 经
   `interconnect_send` 工具反向回发，均验证通过。
 - CI（GitHub Actions）：clone 公开 DSH 仓库作为 sibling，跑 `pnpm run check`。
 - 已发布版本：从 registry 下载的 tarball 与本地构建 shasum 一致；干净消费端
   解析 `.`、`./tool-interconnect` 两个入口的类型均通过，负例（把 `string` 赋给
   `number`）如期报 `TS2322`。
-- 投递消息的 `source` 为 `{ kind: 'plugin', plugin: 'dsh-interconnect' }`，不是
-  `{ kind: 'user' }`——接收方 agent 据此区分跨实例投递与本地用户输入。负例：把
-  该 source 改回 `kind: 'user'`，对应断言转红。
+- 投递消息以 `source: { kind: 'plugin', plugin: 'dsh-interconnect' }` 落库，而不是
+  `{ kind: 'user' }`。负例：把该 source 改回 `kind: 'user'`，对应断言转红。
+  **注意 `source` 不进模型上下文**——只有 `role` 和 `content` 会，而 `role` 是 `user`。
+  所以这个字段的价值在持久化日志与 UI 归因，接收方的**模型本身分辨不出**消息来自插件。
+- 每个行为改动都配负例对照（删掉实现使对应断言转红），而不只是「测试通过」。
+  例如：去掉请求处理器的 `await` 会让 25 个测试转红；去掉 `resume` 的发送方 opt-in
+  门或接收方否决门，各让 1 个转红。
 
 ## 许可
 

package/lib/index.js

@@ -7,6 +7,7 @@ import {
 } from "@deepseek-ai/dsh-host-apiproxy/api";
 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) {
@@ -848,7 +849,8 @@ var linkFrameSchema = Schema.union([
 var sendPayloadSchema = Schema.object({
   sessionId: Schema.string(),
   text: Schema.string(),
-  delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")])
+  delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]),
+  resume: Schema.boolean()
 });
 var eventPayloadSchema = Schema.object({
   sender: Schema.string(),
@@ -860,11 +862,13 @@ var InterconnectService = class extends Service {
     instanceId: Schema.string().default("dsh"),
     requestTimeoutMs: Schema.natural().max(6e4).default(1e4),
     peers: Schema.array(Schema.string()).default([]),
-    delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]).default("followup")
+    delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]).default("followup"),
+    allowResume: Schema.boolean().default(true)
   });
   instanceId;
   requestTimeoutMs;
   delivery;
+  allowResume;
   peers = /* @__PURE__ */ new Set();
   subscriptions = [];
   server = new WebSocketServer({ noServer: true });
@@ -878,6 +882,7 @@ var InterconnectService = class extends Service {
     this.instanceId = config.instanceId;
     this.requestTimeoutMs = config.requestTimeoutMs;
     this.delivery = config.delivery ?? "followup";
+    this.allowResume = config.allowResume ?? true;
     for (const peer of config.peers ?? []) this.peers.add(trimBase(peer));
     const route = {
       kind: "prefix",
@@ -949,7 +954,8 @@ var InterconnectService = class extends Service {
     const payload = {
       sessionId: request.sessionId,
       text: request.text,
-      ...request.delivery === void 0 ? {} : { delivery: request.delivery }
+      ...request.delivery === void 0 ? {} : { delivery: request.delivery },
+      ...request.resume === void 0 ? {} : { resume: request.resume }
     };
     const result = await this.post(request.baseUrl, "send", payload);
     return result ?? { delivered: false, instance: this.instanceId, reason: "unreachable" };
@@ -1088,7 +1094,7 @@ var InterconnectService = class extends Service {
       return;
     }
     try {
-      const value = this.runEndpoint(endpoint, parsed.data.payload);
+      const value = await this.runEndpoint(endpoint, parsed.data.payload);
       writeFull(res, rpcId, { ok: true, value });
     } catch (error) {
       if (error instanceof UnknownEndpointError) {
@@ -1113,7 +1119,7 @@ var InterconnectService = class extends Service {
     }
   }
   /** Dispatch one authenticated business call. */
-  runEndpoint(endpoint, payload) {
+  async runEndpoint(endpoint, payload) {
     if (endpoint === "ping") {
       return { pong: true, instance: this.instanceId };
     }
@@ -1157,7 +1163,8 @@ var InterconnectService = class extends Service {
    * matches how the Host's own session listing treats its projection column.
    */
   listSessions() {
-    const sessions = this.ctx.agents.list().map((agent) => {
+    const reachable = this.ctx.agents.list().filter((agent) => !hasApiRemoteSubagentOwner(this.ctx, agent.session, agent));
+    const sessions = reachable.map((agent) => {
       let title;
       try {
         const snapshot = this.ctx.get("sessionProjections")?.snapshot(agent.session);
@@ -1174,11 +1181,48 @@ var InterconnectService = class extends Service {
     });
     return { sessions, instance: this.instanceId };
   }
-  /** Deliver one message to a live local session, if it exists. */
-  deliver(payload) {
-    const agent = this.ctx.agents.get(payload.sessionId);
+  /**
+   * Resolve a session that is not currently live, when the sender asked to wake
+   * it. Returns the agent, or the reason it stays undelivered.
+   *
+   * The resume is delegated to the Host's configured `agent` lookup rather than
+   * calling `ctx.agents.resume()` here, and that is the whole point: a handle
+   * from `resume()` is owned by the CALLING context, so resuming on this
+   * plugin's fiber would tear the session down again the moment the plugin
+   * unloads (measured: the same call through the root context leaves it alive).
+   * The Host's resolver owns it instead, and it also composes the preset the
+   * session recorded — so a woken agent comes back with the toolset its history
+   * was produced under, not an empty one.
+   */
+  async wake(payload) {
+    if (payload.resume !== true) return { reason: "session-not-live" };
+    if (!this.allowResume) return { reason: "resume-refused" };
+    const lookup = this.ctx.get("typert")?.lookups.get("agent");
+    if (lookup === void 0) return { reason: "session-not-live" };
+    try {
+      const resolved = await lookup.resolve(payload.sessionId);
+      if (resolved === void 0 || resolved === null) return { reason: "session-not-live" };
+      return { agent: resolved };
+    } catch (error) {
+      this.ctx.logger.info(`interconnect: resume refused for ${payload.sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+      return { reason: "resume-failed" };
+    }
+  }
+  /**
+   * Deliver one message to a live local session, waking a persisted one only
+   * when the sender asked and this receiver allows it.
+   */
+  async deliver(payload) {
+    let agent = this.ctx.agents.get(payload.sessionId);
     if (agent === void 0) {
-      return { delivered: false, instance: this.instanceId, reason: "session-not-live" };
+      const woken = await this.wake(payload);
+      if ("reason" in woken) {
+        return { delivered: false, instance: this.instanceId, reason: woken.reason };
+      }
+      agent = woken.agent;
+    }
+    if (hasApiRemoteSubagentOwner(this.ctx, agent.session, agent)) {
+      return { delivered: false, instance: this.instanceId, reason: "session-owned-by-subagent" };
     }
     const message = createUserMessage({
       source: {

package/lib/interconnect/index.js

@@ -7,6 +7,7 @@ import {
 } from "@deepseek-ai/dsh-host-apiproxy/api";
 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) {
@@ -848,7 +849,8 @@ var linkFrameSchema = Schema.union([
 var sendPayloadSchema = Schema.object({
   sessionId: Schema.string(),
   text: Schema.string(),
-  delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")])
+  delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]),
+  resume: Schema.boolean()
 });
 var eventPayloadSchema = Schema.object({
   sender: Schema.string(),
@@ -860,11 +862,13 @@ var InterconnectService = class extends Service {
     instanceId: Schema.string().default("dsh"),
     requestTimeoutMs: Schema.natural().max(6e4).default(1e4),
     peers: Schema.array(Schema.string()).default([]),
-    delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]).default("followup")
+    delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]).default("followup"),
+    allowResume: Schema.boolean().default(true)
   });
   instanceId;
   requestTimeoutMs;
   delivery;
+  allowResume;
   peers = /* @__PURE__ */ new Set();
   subscriptions = [];
   server = new WebSocketServer({ noServer: true });
@@ -878,6 +882,7 @@ var InterconnectService = class extends Service {
     this.instanceId = config.instanceId;
     this.requestTimeoutMs = config.requestTimeoutMs;
     this.delivery = config.delivery ?? "followup";
+    this.allowResume = config.allowResume ?? true;
     for (const peer of config.peers ?? []) this.peers.add(trimBase(peer));
     const route = {
       kind: "prefix",
@@ -949,7 +954,8 @@ var InterconnectService = class extends Service {
     const payload = {
       sessionId: request.sessionId,
       text: request.text,
-      ...request.delivery === void 0 ? {} : { delivery: request.delivery }
+      ...request.delivery === void 0 ? {} : { delivery: request.delivery },
+      ...request.resume === void 0 ? {} : { resume: request.resume }
     };
     const result = await this.post(request.baseUrl, "send", payload);
     return result ?? { delivered: false, instance: this.instanceId, reason: "unreachable" };
@@ -1088,7 +1094,7 @@ var InterconnectService = class extends Service {
       return;
     }
     try {
-      const value = this.runEndpoint(endpoint, parsed.data.payload);
+      const value = await this.runEndpoint(endpoint, parsed.data.payload);
       writeFull(res, rpcId, { ok: true, value });
     } catch (error) {
       if (error instanceof UnknownEndpointError) {
@@ -1113,7 +1119,7 @@ var InterconnectService = class extends Service {
     }
   }
   /** Dispatch one authenticated business call. */
-  runEndpoint(endpoint, payload) {
+  async runEndpoint(endpoint, payload) {
     if (endpoint === "ping") {
       return { pong: true, instance: this.instanceId };
     }
@@ -1157,7 +1163,8 @@ var InterconnectService = class extends Service {
    * matches how the Host's own session listing treats its projection column.
    */
   listSessions() {
-    const sessions = this.ctx.agents.list().map((agent) => {
+    const reachable = this.ctx.agents.list().filter((agent) => !hasApiRemoteSubagentOwner(this.ctx, agent.session, agent));
+    const sessions = reachable.map((agent) => {
       let title;
       try {
         const snapshot = this.ctx.get("sessionProjections")?.snapshot(agent.session);
@@ -1174,11 +1181,48 @@ var InterconnectService = class extends Service {
     });
     return { sessions, instance: this.instanceId };
   }
-  /** Deliver one message to a live local session, if it exists. */
-  deliver(payload) {
-    const agent = this.ctx.agents.get(payload.sessionId);
+  /**
+   * Resolve a session that is not currently live, when the sender asked to wake
+   * it. Returns the agent, or the reason it stays undelivered.
+   *
+   * The resume is delegated to the Host's configured `agent` lookup rather than
+   * calling `ctx.agents.resume()` here, and that is the whole point: a handle
+   * from `resume()` is owned by the CALLING context, so resuming on this
+   * plugin's fiber would tear the session down again the moment the plugin
+   * unloads (measured: the same call through the root context leaves it alive).
+   * The Host's resolver owns it instead, and it also composes the preset the
+   * session recorded — so a woken agent comes back with the toolset its history
+   * was produced under, not an empty one.
+   */
+  async wake(payload) {
+    if (payload.resume !== true) return { reason: "session-not-live" };
+    if (!this.allowResume) return { reason: "resume-refused" };
+    const lookup = this.ctx.get("typert")?.lookups.get("agent");
+    if (lookup === void 0) return { reason: "session-not-live" };
+    try {
+      const resolved = await lookup.resolve(payload.sessionId);
+      if (resolved === void 0 || resolved === null) return { reason: "session-not-live" };
+      return { agent: resolved };
+    } catch (error) {
+      this.ctx.logger.info(`interconnect: resume refused for ${payload.sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+      return { reason: "resume-failed" };
+    }
+  }
+  /**
+   * Deliver one message to a live local session, waking a persisted one only
+   * when the sender asked and this receiver allows it.
+   */
+  async deliver(payload) {
+    let agent = this.ctx.agents.get(payload.sessionId);
     if (agent === void 0) {
-      return { delivered: false, instance: this.instanceId, reason: "session-not-live" };
+      const woken = await this.wake(payload);
+      if ("reason" in woken) {
+        return { delivered: false, instance: this.instanceId, reason: woken.reason };
+      }
+      agent = woken.agent;
+    }
+    if (hasApiRemoteSubagentOwner(this.ctx, agent.session, agent)) {
+      return { delivered: false, instance: this.instanceId, reason: "session-owned-by-subagent" };
     }
     const message = createUserMessage({
       source: {