dsh-interconnect 0.11.24 → 0.15.0

package/lib/tool-interconnect/index.js

@@ -8,7 +8,7 @@ import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { remoteErrorOf } from "@deepseek-ai/dsh-typert-protocol";
 import { boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
 
-// ../.dsh/source/staging-20260807T143236Z/vendor/cosmokit/src/misc.ts
+// ../dsh-wt-ic-merge/vendor/cosmokit/src/misc.ts
 function isNullable(value) {
   return value === null || value === void 0;
 }
@@ -30,7 +30,7 @@ function pick(source, keys, forced) {
   return result;
 }
 
-// ../.dsh/source/staging-20260807T143236Z/vendor/cosmokit/src/types.ts
+// ../dsh-wt-ic-merge/vendor/cosmokit/src/types.ts
 function is(type, value) {
   if (arguments.length === 1) return (value2) => is(type, value2);
   return type in globalThis && value instanceof globalThis[type] || Object.prototype.toString.call(value).slice(8, -1) === type;
@@ -139,7 +139,7 @@ function deepEqual(a, b, strict) {
   }) ?? Object.keys({ ...a, ...b }).every((key) => deepEqual(a[key], b[key], strict));
 }
 
-// ../.dsh/source/staging-20260807T143236Z/vendor/cosmokit/src/time.ts
+// ../dsh-wt-ic-merge/vendor/cosmokit/src/time.ts
 var Time;
 ((Time2) => {
   Time2.millisecond = 1;
@@ -219,7 +219,7 @@ var Time;
   Time2.template = template;
 })(Time || (Time = {}));
 
-// ../.dsh/source/staging-20260807T143236Z/vendor/schemastery/lib/index.mjs
+// ../dsh-wt-ic-merge/vendor/schemastery/lib/index.mjs
 var kSchema = Symbol.for("schemastery");
 var kValidationError = Symbol.for("ValidationError");
 globalThis.__schemastery_index__ ??= 0;
@@ -823,12 +823,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)}`);
@@ -839,6 +835,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;
@@ -966,11 +963,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,
@@ -1111,7 +1116,7 @@ var InterconnectService = class extends Service {
    * Returns the peer identity when reachable, or undefined when the link is
    * not up or no answer arrives.
    * @param instanceId - the peer's `instanceId` as configured under {@link Config.peers}.
-   * @returns the peer's identity, or undefined when the link is not up or no answer arrives.
+   * @returns the peer's identity, or undefined when there is no usable answer.
    */
   async ping(instanceId) {
     return this.queryRequest(instanceId, { kind: "ping" });
@@ -1125,16 +1130,33 @@ var InterconnectService = class extends Service {
   async list(instanceId) {
     return this.queryRequest(instanceId, { kind: "list" });
   }
+  /**
+   * The peers this instance configures, each with the current state of the link
+   * it dials, in configuration order. This is how a caller tells an id this
+   * instance cannot reach at all (`peer-not-configured`) from one whose link is
+   * merely down (`unreachable`), which the bare `undefined` of `ping`/`list`
+   * cannot express. A configured peer whose link is `down` is still a valid
+   * target: its reconnect runs on its own backoff, so it may answer later.
+   * @returns one row per configured peer.
+   */
+  peers() {
+    return [...this.linkStates].map(([instanceId, state]) => ({
+      instanceId,
+      origin: state.peer,
+      link: state.writable() ? "up" : "down"
+    }));
+  }
   /**
    * Send a `msg` frame over the live link to a peer and resolve with its
-   * correlated `msg-result`. Undefined when the peer has no live link here
-   * (not configured, or the link is down) — sends can only address configured+
-   * connected peers by design — and a `message-too-large` result when the
-   * encoded frame would not fit the link.
+   * correlated `msg-result`. A `peer-not-configured` result when this instance
+   * configures no route for that id, undefined when the route exists but its
+   * link is down, and a `message-too-large` result when the encoded frame would
+   * not fit the link.
    */
   async msgRequest(instanceId, kind, payload) {
     const state = this.linkStates.get(instanceId);
-    if (state === void 0 || !state.writable()) return void 0;
+    if (state === void 0) return { delivered: false, instance: instanceId, reason: "peer-not-configured" };
+    if (!state.writable()) return void 0;
     const reqId = `m${++this.reqIdCounter}-${randomUUID()}`;
     const frame = {
       type: "msg",
@@ -1196,7 +1218,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(
@@ -1206,11 +1229,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);
@@ -1345,7 +1385,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)) {
@@ -1372,7 +1412,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;
@@ -1430,7 +1471,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 = (() => {
@@ -1639,24 +1680,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) => {
@@ -1788,11 +1845,13 @@ var deliveryOutcome = (result) => ({
   ...result.delivery === void 0 ? {} : { delivery: result.delivery },
   ...result.reason === void 0 ? {} : { reason: result.reason }
 });
+var configures = (interconnect, instanceId) => interconnect.peers().some((peer) => peer.instanceId === instanceId);
+var unansweredText = (instanceId, configured) => configured === false ? `not configured: this instance has no peer "${instanceId}" \u2014 add it to the interconnect peers mapping (interconnect_peers lists what is configured)` : `unreachable: peer "${instanceId}" gave no usable answer (its link is down, or the shared token differs); retrying may succeed`;
 function apply(ctx) {
   const interconnect = ctx.interconnect;
   ctx.tools.register(defineTool({
     name: "interconnect_send",
-    description: 'Deliver one text message to a live session on another DSH instance (same machine, another machine, or another session). Returns whether the peer instance received it and which instance answered. Only a live session receives directly; a persisted one can be woken by setting resume, and when delivery fails the result reports the reason (for example "session-not-live") and interconnect_list shows which sessions are live there. The sending instance and session ids are attached automatically, so the receiver can reply with interconnect_reply; do not pass a sender parameter.',
+    description: 'Deliver one text message to a session on another DSH instance (same machine, another machine, or another session). Returns whether the peer instance received it and which instance answered. A live session receives directly; a persisted session with no live agent is woken by default (resume), and when delivery fails the result reports the reason (for example "session-not-live" or "resume-refused"). The sending instance and session ids are attached automatically, so the receiver can reply with interconnect_reply; do not pass a sender parameter.',
     parameters: {
       instanceId: {
         type: "string",
@@ -1816,7 +1875,7 @@ function apply(ctx) {
       },
       resume: {
         type: "boolean",
-        description: `Wake the target session if it is persisted but not live. Off by default because delivery to a woken session starts a real agent turn \u2014 a billed model call with that session's full toolset \u2014 in a conversation nobody is watching. Prefer interconnect_list and an already-live target; set this only when that specific session must be reached. The receiver may refuse, answering reason "resume-refused".`
+        description: `Wake the target session if it is persisted but not live. Defaults to true: waking starts a real agent turn \u2014 a billed model call with that session's full toolset \u2014 on the receiver, which is what makes an offline target reachable. Set false to leave it asleep and report reason "session-not-live". The receiver may still refuse, answering reason "resume-refused".`
       }
     },
     output: {
@@ -1830,6 +1889,8 @@ function apply(ctx) {
         }
         const text = (() => {
           switch (value.reason) {
+            case "peer-not-configured":
+              return `not delivered: this instance configures no peer "${value.instance}" \u2014 add it to the interconnect peers mapping (interconnect_peers lists what is configured)`;
             case "unreachable":
               return `not delivered: ${value.instance} did not answer (unreachable); retrying may succeed`;
             case "resume-refused":
@@ -1841,7 +1902,7 @@ function apply(ctx) {
             case "message-too-large":
               return "not delivered: the message is too large for the peer link (limit 1 MiB); shorten the text and try again";
             default:
-              return `not delivered: no live session "${_args.sessionId}" on ${value.instance}` + (_args.resume === true ? " \u2014 use interconnect_list to see which sessions are live there" : " \u2014 use interconnect_list to see which sessions are live there, or set resume to wake this one");
+              return `not delivered: no live session "${_args.sessionId}" on ${value.instance}` + (_args.resume === false ? " \u2014 waking was disabled (resume: false); the message was not delivered to any other session" : " \u2014 it could not be woken there (the receiver has no resuming agent lookup); the message was not delivered to any other session");
           }
         })();
         return [{ type: "text", text }];
@@ -1859,7 +1920,9 @@ function apply(ctx) {
         // as a reply target.
         ...sessionId === void 0 ? {} : { sender: interconnect.selfSender(String(sessionId)) },
         ...args.delivery === void 0 ? {} : { delivery: args.delivery },
-        ...args.resume === void 0 ? {} : { resume: args.resume }
+        // Waking is the default: a persisted target with no live agent is
+        // otherwise unreachable, and a caller that wants it left asleep passes false.
+        resume: args.resume ?? true
       }));
       return deliveryOutcome(result);
     }
@@ -1880,17 +1943,20 @@ function apply(ctx) {
         additionalProperties: false,
         properties: {
           reachable: { type: "boolean", required: true },
-          instance: { type: "string" }
+          instance: { type: "string" },
+          // Whether this instance configures that peer at all: absent/false means
+          // the id cannot be reached by any retry, true means the link is down.
+          configured: { type: "boolean" }
         }
       },
-      render: (_args, value) => [{
+      render: (args, value) => [{
         type: "text",
-        text: value.reachable ? `reachable: ${value.instance ?? "(unknown instance)"}` : "unreachable"
+        text: value.reachable ? `reachable: ${value.instance ?? "(unknown instance)"}` : unansweredText(args.instanceId, value.configured)
       }]
     },
     async execute(args, exec) {
       const result = await raceSignal(exec.signal, interconnect.ping(args.instanceId));
-      if (result === void 0) return { reachable: false };
+      if (result === void 0) return { reachable: false, configured: configures(interconnect, args.instanceId) };
       return { reachable: true, instance: result.instance };
     }
   }));
@@ -1911,6 +1977,8 @@ function apply(ctx) {
         properties: {
           reachable: { type: "boolean", required: true },
           instance: { type: "string" },
+          // Whether this instance configures that peer at all, as in interconnect_ping.
+          configured: { type: "boolean" },
           sessions: {
             type: "array",
             items: {
@@ -1925,8 +1993,8 @@ function apply(ctx) {
           }
         }
       },
-      render: (_args, value) => {
-        if (!value.reachable) return [{ type: "text", text: "unreachable" }];
+      render: (args, value) => {
+        if (!value.reachable) return [{ type: "text", text: unansweredText(args.instanceId, value.configured) }];
         const sessions = value.sessions ?? [];
         if (sessions.length === 0) {
           return [{ type: "text", text: `no live sessions on ${value.instance ?? "(unknown instance)"}` }];
@@ -1944,7 +2012,7 @@ function apply(ctx) {
     },
     async execute(args, exec) {
       const result = await raceSignal(exec.signal, interconnect.list(args.instanceId));
-      if (result === void 0) return { reachable: false };
+      if (result === void 0) return { reachable: false, configured: configures(interconnect, args.instanceId) };
       return {
         reachable: true,
         instance: result.instance,
@@ -1958,6 +2026,55 @@ function apply(ctx) {
       };
     }
   }));
+  ctx.tools.register(defineTool({
+    name: "interconnect_peers",
+    description: `List the peer DSH instances this instance is configured to reach, with each peer's dialed link state. Call this first when you do not already know the peer ids available here: every listed instanceId is a valid target for interconnect_send, interconnect_ping, and interconnect_list. A peer listed with link "down" is configured but currently cannot carry frames, so it answers nothing until its reconnect succeeds; an id that is not listed at all cannot be reached and reports reason "peer-not-configured". A message that arrives from a peer this instance does not configure can be received but not replied to.`,
+    parameters: {},
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          peers: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                instanceId: { type: "string", required: true },
+                origin: { type: "string", required: true },
+                link: { type: "string", required: true }
+              }
+            }
+          }
+        }
+      },
+      render: (_args, value) => {
+        const peers = value.peers ?? [];
+        if (peers.length === 0) {
+          return [{
+            type: "text",
+            text: "no peers configured: this instance can receive messages but cannot send or reply. Add entries to the interconnect row's peers mapping (a peer id keyed to the origin this instance dials); the change applies when that row's config is re-activated."
+          }];
+        }
+        return [{
+          type: "text",
+          text: peers.map((peer) => `${peer.instanceId}  ${peer.origin}  [${peer.link}]`).join("\n")
+        }];
+      }
+    },
+    execute(_args, _exec) {
+      return Promise.resolve({
+        peers: interconnect.peers().map((peer) => ({
+          instanceId: peer.instanceId,
+          // The origin is this instance's own dial target, read locally: it is
+          // what a caller needs to diagnose a peer whose link will not come up.
+          origin: peer.origin,
+          link: peer.link
+        }))
+      });
+    }
+  }));
   ctx.tools.register(defineTool({
     name: "interconnect_reply",
     description: `Deliver one text message back to the peer that this session last received an interconnect message from. Only the reply text is needed: the replying session is this agent's own, and the outbound target (the sending instance id and session id) is recalled from the message this session received, so you do not ask for an address twice. The recalled target is the most recent sender only: a later message from another peer replaces it, and restarting this instance forgets it until a new message arrives, so name the intended recipient in the reply text when more than one peer may message this session. A session that never received a message through interconnect \u2014 or received one without a sender identity \u2014 reports reason "no-sender-known".`,
@@ -1974,7 +2091,7 @@ function apply(ctx) {
       },
       resume: {
         type: "boolean",
-        description: "Wake the target session if it is persisted but not live, as in interconnect_send. Off by default; the receiver may refuse."
+        description: `Wake the recorded sender's session if it is persisted but not live. Defaults to true: a reply completes an interchange the sender started, so the session is woken by a real billed agent turn on the receiver. Set false to leave it asleep and report reason "session-not-live". The receiver may still refuse, answering "resume-refused".`
       }
     },
     output: {
@@ -1996,6 +2113,9 @@ function apply(ctx) {
           if (value.reason === "session-owned-by-subagent") {
             return "not delivered: the recorded sender's session belongs to a subagent and its parent agent owns delivery";
           }
+          if (value.reason === "peer-not-configured") {
+            return `not delivered: this instance configures no peer "${value.instance}" \u2014 the sender can be messaged, but this instance cannot dial it back until it is added to the interconnect peers mapping`;
+          }
           if (value.reason === "unreachable") {
             return "not delivered: the recorded sender did not answer (unreachable); retrying may succeed";
           }
@@ -2005,7 +2125,7 @@ function apply(ctx) {
           if (value.reason === "resume-failed") {
             return "not delivered: could not wake the recorded sender's session";
           }
-          return "not delivered: the recorded sender's session is not live";
+          return "not delivered: the recorded sender's session is not live" + (_args.resume === false ? " \u2014 waking was disabled (resume: false); the reply was not sent to any other session" : " \u2014 it could not be woken there (the receiver has no resuming agent lookup); the reply was not sent to any other session");
         })();
         return [{ type: "text", text }];
       }
@@ -2021,7 +2141,8 @@ function apply(ctx) {
         sessionId: String(exec.agent.session.id),
         text: args.text,
         ...args.delivery === void 0 ? {} : { delivery: args.delivery },
-        ...args.resume === void 0 ? {} : { resume: args.resume }
+        // Replying to a sender that has gone offline should still reach it.
+        resume: args.resume ?? true
       }));
       return deliveryOutcome(result);
     }