dsh-interconnect 0.6.3 → 0.7.0

package/README.md

@@ -17,6 +17,7 @@
 - `interconnect_send`：向对端实例的指定 session 投递消息；可选 `delivery` 选投递模式、`resume` 唤醒离线 session
 - `interconnect_list`：列出对端实例的 live session（id + 标题 + 状态），用于在不预先知道 session id 时寻址
 - `interconnect_ping`：探测对端实例活性与身份
+- `interconnect_reply`：向记录过的发送方回传消息，只需本机 session id + 文本，无需再次寻址
 
 ## 用法
 
@@ -37,6 +38,29 @@ session-b07326da-…                          [running]
 只列 live session 是有意的：`send` 能到达的正好是这些。对端存在但没有运行 agent 的 session
 不会出现在列表里，也收不到消息。
 
+### 回复（`reply`）
+
+`send` 的线负载带一个可选的 `sender` 身份（`baseUrl` + `instanceId` + `sessionId`），收到
+消息的 instance 会按「本地 session id → 该 sender」记下这份身份。之后那个 session 可以只凭
+**自己的 session id + 文本**把消息回传给发送方，不用再次给出对端 origin 或远程 session id。
+
+```text
+# 源实例 A 指定目标 B 的 session，并带上自己的身份
+interconnect_send(baseUrl=B, sessionId=B-sess, text="…", sender={baseUrl:A, instanceId:A, sessionId:A-sess})
+
+# B 回传：只给本地 session id + 文本，目标从记录的 sender 解析
+interconnect_reply(sessionId=B-sess, text="reply")
+```
+
+- `sender` 是**自报**的，只用于 reply 归因与寻址，**不是**路由或鉴权依据——连接本身仍由
+  共享密钥在每个 origin 上独立鉴权。
+- 回复的消息也带 `sender`（当本机配置了 `selfBaseUrl`），所以对话可双向多轮延续。
+- 只有当入站 send **带了 `sender`** 时 reply 才有目标；对端版本没带、或本 session 从未收过
+  互联消息时，`reply` 返回 `delivered: false, reason: "no-sender-known"`。
+- `sender` **不进模型上下文**（和 `source` 一样只落到持久化日志与 UI 归因）——这条消息的
+  内容字面就是 wire 上传来的 `text`，模型看到的仍是普通 user 文本，只是不带任何结构化的
+  发送方标记。
+
 ### 投递失败的原因
 
 `delivered: false` 单独一个布尔值无法据以行动，因为不同失败需要不同应对，所以
@@ -49,6 +73,7 @@ session-b07326da-…                          [running]
 | `resume-refused` | 请求了唤醒，但对端不允许（`allowResume: false`） | 再带 `resume` 也没用 |
 | `resume-failed` | 允许唤醒且尝试了，但没得到 live agent（无此持久化 session，或被别的 owner 持有） | 换目标 |
 | `session-owned-by-subagent` | 该 session 属于 subagent 路由，投递权在它的父 agent | 通过父 agent 触达，别直接投 |
+| `no-sender-known` | `reply` 指向的本地 session 从未记录过发送方（它没收到过带 `sender` 的消息，或对端版本过旧没带 `sender`） | 先用 `interconnect_send` 主动建立联系，或确认对端配置了 `selfBaseUrl` |
 
 `reason` 恰好在 `delivered` 为 false 时出现。
 
@@ -127,6 +152,7 @@ Host 自己的 resume 路径对同一个 session 报 `SessionFormatUnsupportedEr
 | 字段 | 默认 | 说明 |
 |---|---|---|
 | `instanceId` | `'dsh'` | 本实例自报的 id，出现在 `ping`/`send`/`list` 的回包里。仅诊断用，**不作为路由依据** |
+| `selfBaseUrl` | 无 | 本实例对外可达的 origin（如 `http://my-box:3080`）。设置后，出站 `send`/`reply` 会带上本实例的 `sender` 身份，使对端能回信；不设置则不归因、对端 `reply` 报 `no-sender-known` |
 | `requestTimeoutMs` | `10000` | 出站请求超时，上限 60000 |
 | `peers` | `[]` | 启动时的事件 fan-out 目标；运行时可用 `subscribe()` 增补 |
 | `delivery` | `'followup'` | 入站消息未带 `delivery` 时的默认投递模式 |
@@ -136,6 +162,7 @@ Host 自己的 resume 路径对同一个 session 报 `SessionFormatUnsupportedEr
 - id: interconnect
   config:
     instanceId: my-box
+    selfBaseUrl: http://my-box:3080   # 让对端能 reply 回本机
     peers: ['http://peer-host:3080']
     delivery: followup
     allowResume: false   # 拒绝一切唤醒请求
@@ -187,7 +214,7 @@ pnpm run build    # esbuild → lib/
 
 ## 验证
 
-- 50/50 单测通过（服务 + 工具）；类型检查、构建均干净。
+- 67/67 单测通过（服务 + 工具）；类型检查、构建均干净。
 - 已在两台机器之间实测双向互通：消息投递、WebSocket 事件推流、以及 agent 经
   `interconnect_send` 工具反向回发，均验证通过。
 - CI（GitHub Actions）：clone 公开 DSH 仓库作为 sibling，跑 `pnpm run check`。
@@ -198,9 +225,12 @@ pnpm run build    # esbuild → lib/
   `{ kind: 'user' }`。负例：把该 source 改回 `kind: 'user'`，对应断言转红。
   **注意 `source` 不进模型上下文**——只有 `role` 和 `content` 会，而 `role` 是 `user`。
   所以这个字段的价值在持久化日志与 UI 归因，接收方的**模型本身分辨不出**消息来自插件。
+  同理，reply 的记录与寻址依赖 `sender`，它同样不进模型上下文。
+- reply 双向多轮延续在**同一测试进程内用真实 HTTP 双向回环**验证（A→B→A→B），不是 mockout。
 - 每个行为改动都配负例对照（删掉实现使对应断言转红），而不只是「测试通过」。
   例如：去掉请求处理器的 `await` 会让 25 个测试转红；去掉 `resume` 的发送方 opt-in
-  门或接收方否决门，各让 1 个转红。
+  门或接收方否决门，各让 1 个转红；去掉入站 send 的 sender 记录（`senders.set`），
+  两条 reply 回环测试转红。
 
 ## 许可
 

package/lib/index.js

@@ -847,6 +847,17 @@ var linkFrameSchema = Schema.union([
   Schema.object({ type: Schema.const("event"), notification: notificationSchema })
 ]);
 var sendPayloadSchema = Schema.object({
+  sessionId: Schema.string(),
+  text: Schema.string(),
+  sender: Schema.object({
+    baseUrl: Schema.string(),
+    instanceId: Schema.string(),
+    sessionId: Schema.string()
+  }),
+  delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]),
+  resume: Schema.boolean()
+});
+var replyPayloadSchema = Schema.object({
   sessionId: Schema.string(),
   text: Schema.string(),
   delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]),
@@ -860,12 +871,14 @@ var InterconnectService = class extends Service {
   static inject = ["webServer", "agents", "credentials"];
   static Config = Schema.object({
     instanceId: Schema.string().default("dsh"),
+    selfBaseUrl: Schema.string(),
     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"),
     allowResume: Schema.boolean().default(true)
   });
   instanceId;
+  selfBaseUrl;
   requestTimeoutMs;
   delivery;
   allowResume;
@@ -877,9 +890,12 @@ var InterconnectService = class extends Service {
   heartbeatTimer;
   /** Peer identity each live socket announced via its `hello` frame, if any. */
   peerOf = /* @__PURE__ */ new WeakMap();
+  /** Sender each local session last received a send from, keyed by local session id. */
+  senders = /* @__PURE__ */ new Map();
   constructor(ctx, config) {
     super(ctx, "interconnect");
     this.instanceId = config.instanceId;
+    this.selfBaseUrl = config.selfBaseUrl;
     this.requestTimeoutMs = config.requestTimeoutMs;
     this.delivery = config.delivery ?? "followup";
     this.allowResume = config.allowResume ?? true;
@@ -950,16 +966,49 @@ var InterconnectService = class extends Service {
       this.server.close();
     }, "interconnect: websocket teardown");
   }
+  /**
+   * This instance's identity to attach to outbound messages, when configured.
+   * Absent (`selfBaseUrl` unset) outbound sends are not attributable and the
+   * peer cannot reply to them.
+   * @param sessionId - the local session that is sending, used as the reply target.
+   */
+  selfSender(sessionId) {
+    return this.selfBaseUrl === void 0 ? void 0 : { baseUrl: this.selfBaseUrl, instanceId: this.instanceId, sessionId };
+  }
   async send(request) {
     const payload = {
       sessionId: request.sessionId,
       text: request.text,
+      ...request.sender === void 0 ? {} : { sender: request.sender },
       ...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" };
   }
+  /**
+   * Deliver one text message back to the peer that a local session last
+   * received a send from. `sessionId` names the LOCAL replying session; the
+   * outbound target is the `sender` that session recorded, resolved to a
+   * `send` against the recalled baseUrl and remote session id.
+   */
+  async reply(request) {
+    const sender = this.senders.get(request.sessionId);
+    if (sender === void 0) {
+      return { delivered: false, instance: this.instanceId, reason: "no-sender-known" };
+    }
+    const payload = {
+      sessionId: sender.sessionId,
+      text: request.text,
+      ...request.delivery === void 0 ? {} : { delivery: request.delivery },
+      ...request.resume === void 0 ? {} : { resume: request.resume },
+      // Attribute the reply to this instance so the peer, in turn, can reply
+      // back — chaining the conversation. Absent when we have no self origin.
+      ...this.selfBaseUrl === void 0 ? {} : { sender: this.selfSender(request.sessionId) }
+    };
+    const result = await this.post(sender.baseUrl, "send", payload);
+    return result ?? { delivered: false, instance: this.instanceId, reason: "unreachable" };
+  }
   async ping(baseUrl) {
     return this.post(baseUrl, "ping", {});
   }
@@ -1134,6 +1183,15 @@ var InterconnectService = class extends Service {
       }
       return this.deliver(parsed);
     }
+    if (endpoint === "reply") {
+      let parsed;
+      try {
+        parsed = Schema.resolve(payload, replyPayloadSchema, {})[0];
+      } catch (error) {
+        throw new InvalidPayloadError(`reply payload invalid: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      return this.replyForSession(parsed);
+    }
     if (endpoint === "list") {
       return this.listSessions();
     }
@@ -1226,12 +1284,21 @@ var InterconnectService = class extends Service {
     if (hasApiRemoteSubagentOwner(this.ctx, agent.session, agent)) {
       return { delivered: false, instance: this.instanceId, reason: "session-owned-by-subagent" };
     }
+    const sender = (() => {
+      const candidate = payload.sender;
+      return candidate === void 0 || typeof candidate.baseUrl !== "string" ? void 0 : candidate;
+    })();
+    if (sender !== void 0) {
+      this.senders.set(payload.sessionId, sender);
+    }
     const message = createUserMessage({
       source: {
         kind: "plugin",
         plugin: PLUGIN_SOURCE,
         form: "notice",
-        summary: boundContextSummary(`interconnect handoff delivered on instance ${this.instanceId}`)
+        summary: boundContextSummary(
+          sender === void 0 ? `interconnect handoff delivered on instance ${this.instanceId}` : `interconnect handoff from ${sender.instanceId} (session ${sender.sessionId}) delivered on instance ${this.instanceId}`
+        )
       },
       content: [{ type: "text", text: payload.text }]
     });
@@ -1249,7 +1316,19 @@ var InterconnectService = class extends Service {
     }
     return { delivered: true, instance: this.instanceId, delivery: mode };
   }
-  /** POST one business call to a peer instance; undefined on transport/auth failure. */
+  /**
+   * Inbound `reply` dispatch: forward a request to {link reply}, resolving the
+   * outbound sender for the named local session. Kept separate from {link
+   * deliver} so the two wire endpoints stay distinct in the request pipeline.
+   */
+  async replyForSession(payload) {
+    return this.reply({
+      sessionId: payload.sessionId,
+      text: payload.text,
+      ...payload.delivery === void 0 ? {} : { delivery: payload.delivery },
+      ...payload.resume === void 0 ? {} : { resume: payload.resume }
+    });
+  }
   async post(baseUrl, endpoint, payload) {
     const token = await this.resolveToken();
     if (token === void 0) return void 0;

package/lib/interconnect/index.js

@@ -847,6 +847,17 @@ var linkFrameSchema = Schema.union([
   Schema.object({ type: Schema.const("event"), notification: notificationSchema })
 ]);
 var sendPayloadSchema = Schema.object({
+  sessionId: Schema.string(),
+  text: Schema.string(),
+  sender: Schema.object({
+    baseUrl: Schema.string(),
+    instanceId: Schema.string(),
+    sessionId: Schema.string()
+  }),
+  delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]),
+  resume: Schema.boolean()
+});
+var replyPayloadSchema = Schema.object({
   sessionId: Schema.string(),
   text: Schema.string(),
   delivery: Schema.union([Schema.const("followup"), Schema.const("steer"), Schema.const("inject")]),
@@ -860,12 +871,14 @@ var InterconnectService = class extends Service {
   static inject = ["webServer", "agents", "credentials"];
   static Config = Schema.object({
     instanceId: Schema.string().default("dsh"),
+    selfBaseUrl: Schema.string(),
     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"),
     allowResume: Schema.boolean().default(true)
   });
   instanceId;
+  selfBaseUrl;
   requestTimeoutMs;
   delivery;
   allowResume;
@@ -877,9 +890,12 @@ var InterconnectService = class extends Service {
   heartbeatTimer;
   /** Peer identity each live socket announced via its `hello` frame, if any. */
   peerOf = /* @__PURE__ */ new WeakMap();
+  /** Sender each local session last received a send from, keyed by local session id. */
+  senders = /* @__PURE__ */ new Map();
   constructor(ctx, config) {
     super(ctx, "interconnect");
     this.instanceId = config.instanceId;
+    this.selfBaseUrl = config.selfBaseUrl;
     this.requestTimeoutMs = config.requestTimeoutMs;
     this.delivery = config.delivery ?? "followup";
     this.allowResume = config.allowResume ?? true;
@@ -950,16 +966,49 @@ var InterconnectService = class extends Service {
       this.server.close();
     }, "interconnect: websocket teardown");
   }
+  /**
+   * This instance's identity to attach to outbound messages, when configured.
+   * Absent (`selfBaseUrl` unset) outbound sends are not attributable and the
+   * peer cannot reply to them.
+   * @param sessionId - the local session that is sending, used as the reply target.
+   */
+  selfSender(sessionId) {
+    return this.selfBaseUrl === void 0 ? void 0 : { baseUrl: this.selfBaseUrl, instanceId: this.instanceId, sessionId };
+  }
   async send(request) {
     const payload = {
       sessionId: request.sessionId,
       text: request.text,
+      ...request.sender === void 0 ? {} : { sender: request.sender },
       ...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" };
   }
+  /**
+   * Deliver one text message back to the peer that a local session last
+   * received a send from. `sessionId` names the LOCAL replying session; the
+   * outbound target is the `sender` that session recorded, resolved to a
+   * `send` against the recalled baseUrl and remote session id.
+   */
+  async reply(request) {
+    const sender = this.senders.get(request.sessionId);
+    if (sender === void 0) {
+      return { delivered: false, instance: this.instanceId, reason: "no-sender-known" };
+    }
+    const payload = {
+      sessionId: sender.sessionId,
+      text: request.text,
+      ...request.delivery === void 0 ? {} : { delivery: request.delivery },
+      ...request.resume === void 0 ? {} : { resume: request.resume },
+      // Attribute the reply to this instance so the peer, in turn, can reply
+      // back — chaining the conversation. Absent when we have no self origin.
+      ...this.selfBaseUrl === void 0 ? {} : { sender: this.selfSender(request.sessionId) }
+    };
+    const result = await this.post(sender.baseUrl, "send", payload);
+    return result ?? { delivered: false, instance: this.instanceId, reason: "unreachable" };
+  }
   async ping(baseUrl) {
     return this.post(baseUrl, "ping", {});
   }
@@ -1134,6 +1183,15 @@ var InterconnectService = class extends Service {
       }
       return this.deliver(parsed);
     }
+    if (endpoint === "reply") {
+      let parsed;
+      try {
+        parsed = Schema.resolve(payload, replyPayloadSchema, {})[0];
+      } catch (error) {
+        throw new InvalidPayloadError(`reply payload invalid: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      return this.replyForSession(parsed);
+    }
     if (endpoint === "list") {
       return this.listSessions();
     }
@@ -1226,12 +1284,21 @@ var InterconnectService = class extends Service {
     if (hasApiRemoteSubagentOwner(this.ctx, agent.session, agent)) {
       return { delivered: false, instance: this.instanceId, reason: "session-owned-by-subagent" };
     }
+    const sender = (() => {
+      const candidate = payload.sender;
+      return candidate === void 0 || typeof candidate.baseUrl !== "string" ? void 0 : candidate;
+    })();
+    if (sender !== void 0) {
+      this.senders.set(payload.sessionId, sender);
+    }
     const message = createUserMessage({
       source: {
         kind: "plugin",
         plugin: PLUGIN_SOURCE,
         form: "notice",
-        summary: boundContextSummary(`interconnect handoff delivered on instance ${this.instanceId}`)
+        summary: boundContextSummary(
+          sender === void 0 ? `interconnect handoff delivered on instance ${this.instanceId}` : `interconnect handoff from ${sender.instanceId} (session ${sender.sessionId}) delivered on instance ${this.instanceId}`
+        )
       },
       content: [{ type: "text", text: payload.text }]
     });
@@ -1249,7 +1316,19 @@ var InterconnectService = class extends Service {
     }
     return { delivered: true, instance: this.instanceId, delivery: mode };
   }
-  /** POST one business call to a peer instance; undefined on transport/auth failure. */
+  /**
+   * Inbound `reply` dispatch: forward a request to {link reply}, resolving the
+   * outbound sender for the named local session. Kept separate from {link
+   * deliver} so the two wire endpoints stay distinct in the request pipeline.
+   */
+  async replyForSession(payload) {
+    return this.reply({
+      sessionId: payload.sessionId,
+      text: payload.text,
+      ...payload.delivery === void 0 ? {} : { delivery: payload.delivery },
+      ...payload.resume === void 0 ? {} : { resume: payload.resume }
+    });
+  }
   async post(baseUrl, endpoint, payload) {
     const token = await this.resolveToken();
     if (token === void 0) return void 0;