@staix/agent-hub 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.2
+
+- The channel plugin no longer fights a second session attached as the same peer: the replaced one stays detached and its tools say so, instead of taking the peer back every second (#16).
+- The plugin MCP server exits when its host goes away, and stops retrying a hub that refused it (wire version, token, peer id), reporting the hub's reason (#17).
+- After upgrading, run `ahub setup` to refresh the Claude plugin and restart agent sessions; stale `server.js` processes from earlier versions have to be ended by hand once.
+
 ## 0.3.1
 
 - Hub task, review and budget events are distinguished from reference-only presence/recall in agent instructions and rendered message kinds, including mixed Claude digests.

package/README.md

@@ -4,7 +4,7 @@ Native multi-agent hub for one developer's machine: Claude Code, Codex, Kimi Cod
 hub-owned local-LLM worker collaborate as peers in one project directory, with
 task-aware model routing (Switchyard) in front of a self-hosted gateway (OmniRoute).
 
-Status: 0.3.1. All six milestones of the design spec are implemented; the [smoke checklist](docs/smoke.md)
+Status: 0.3.2. All six milestones of the design spec are implemented; the [smoke checklist](docs/smoke.md)
 says what has and has not been verified against real agents.
 
 ## Start here
@@ -22,7 +22,7 @@ cd <your project> && ahub init && ahub up && ahub tail
 Or install the same version from GitHub:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.3.1 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.3.2 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code and a local worker as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -15566,12 +15566,12 @@ class ControlClient {
       const ws = new WebSocket(control.url);
       const client = new ControlClient(ws);
       ws.onerror = () => reject(new Error(`cannot reach hub at ${control.url}`));
-      ws.onclose = () => {
-        reject(new Error("hub closed the connection (stale token?)"));
+      ws.onclose = (ev) => {
+        reject(Object.assign(new Error(`hub closed the connection: ${ev.reason || "stale token?"}`), { code: ev.code }));
         for (const done of client.pending.values())
           done({ ok: false, error: "hub connection closed" });
         client.pending.clear();
-        client.onClose();
+        client.onClose(ev.code, ev.reason);
       };
       ws.onmessage = (ev) => {
         const msg = JSON.parse(String(ev.data));
@@ -15602,7 +15602,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.3.1",
+  version: "0.3.2",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code and a local worker as peers in one project",
   license: "MIT",
   type: "module",
@@ -15713,6 +15713,13 @@ function roles() {
   }
 }
 var MAX_RECONNECT_DELAY_MS = 30000;
+var TERMINAL_CLOSES = {
+  4000: `another session attached to the hub as "${peerId}"; this one is detached (restart it to take the peer back)`,
+  4401: "the hub refused the control token",
+  4403: `the hub refused the peer id "${peerId}" (reserved or malformed)`,
+  4409: `the peer id "${peerId}" is taken by a hub-managed adapter`,
+  4426: "wire version mismatch with the running hub: update the agent-hub plugin (ahub setup) and restart this session"
+};
 var INBOX_CAP = 200;
 var INSTRUCTIONS = [
   "agent-hub connects you to other coding agents working in this project (for example codex, kimi, local) and to the hub console user.",
@@ -15734,6 +15741,8 @@ var text = (s) => ({ content: [{ type: "text", text: s }] });
 var server = new Server({ name: "agent-hub", version: VERSION }, toolsOnly ? { capabilities: { tools: {} }, instructions: TOOLS_INSTRUCTIONS } : { capabilities: { experimental: { "claude/channel": {} }, tools: {} }, instructions: INSTRUCTIONS });
 var inbox = [];
 var hub;
+var detached;
+var offline = () => detached ?? "hub is not running for this project (start it with: ahub up).";
 async function push(envs) {
   const parent = replyParent(envs);
   const single = envs.length === 1;
@@ -15761,19 +15770,25 @@ ${sanitize(e.body)}`).join(`
 }
 async function connectLoop() {
   for (let attempt = 0;; attempt++) {
+    let code;
     try {
       const client = await ControlClient.connect(stateDir, { role: toolsOnly ? "tools" : "peer", peer: peerId });
       client.onPush = (msg) => msg.t === "deliver" && void push(msg.envs ?? [msg.env]);
       hub = client;
       attempt = -1;
       log(`connected to hub as "${peerId}"`);
-      await new Promise((r) => client.onClose = r);
+      code = await new Promise((r) => client.onClose = r);
       hub = undefined;
       log("hub connection lost");
     } catch (e) {
+      code = e.code;
       if (attempt === 0)
         log(e.message);
     }
+    if (code !== undefined && TERMINAL_CLOSES[code]) {
+      detached = TERMINAL_CLOSES[code];
+      return log(`stopped reconnecting: ${detached}`);
+    }
     await new Promise((r) => setTimeout(r, Math.min(1000 * 2 ** Math.max(attempt, 0), MAX_RECONNECT_DELAY_MS)));
   }
 }
@@ -15814,7 +15829,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   if (name === "hub_send") {
     const { text: body, to, reply_to } = args ?? {};
     if (!hub)
-      return text("hub is not running for this project (start it with: ahub up). Message not sent.");
+      return text(`${offline()} Message not sent.`);
     const res = await hub.request({ t: "send", body, to, reply_to });
     if (!res.ok)
       return text(`not sent: ${res.error}`);
@@ -15824,11 +15839,13 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   }
   if (TASK_TOOL_NAMES.has(name)) {
     if (!hub)
-      return text("hub is not running for this project (start it with: ahub up).");
+      return text(offline());
     const res = await hub.request({ t: "task", op: name, args: args ?? {} });
     return text(res.ok ? res.text : `error: ${res.error}`);
   }
   return text(`unknown tool ${name}`);
 });
 await server.connect(new StdioServerTransport);
+process.stdin.on("end", () => process.exit(0));
+process.stdin.on("close", () => process.exit(0));
 connectLoop();

package/src/adapters/claude-channel.ts

@@ -24,6 +24,14 @@ function roles(): Record<string, string[]> {
   }
 }
 const MAX_RECONNECT_DELAY_MS = 30_000;
+/** Close codes a retry cannot fix: another session took this peer id (4000), bad token, reserved or taken id, wire version. */
+const TERMINAL_CLOSES: Record<number, string> = {
+  4000: `another session attached to the hub as "${peerId}"; this one is detached (restart it to take the peer back)`,
+  4401: "the hub refused the control token",
+  4403: `the hub refused the peer id "${peerId}" (reserved or malformed)`,
+  4409: `the peer id "${peerId}" is taken by a hub-managed adapter`,
+  4426: "wire version mismatch with the running hub: update the agent-hub plugin (ahub setup) and restart this session",
+};
 const INBOX_CAP = 200;
 
 const INSTRUCTIONS = [
@@ -50,6 +58,8 @@ const server = new Server(
 
 const inbox: string[] = []; // pushes that failed; drained by hub_inbox
 let hub: ControlClient | undefined;
+let detached: string | undefined; // why this server stopped reconnecting; tool calls report it
+const offline = () => detached ?? "hub is not running for this project (start it with: ahub up).";
 
 /** One delivery = one notification, because every notification can cost Claude a turn. */
 async function push(envs: Envelope[]): Promise<void> {
@@ -75,18 +85,25 @@ async function push(envs: Envelope[]): Promise<void> {
 
 async function connectLoop(): Promise<void> {
   for (let attempt = 0; ; attempt++) {
+    let code: number | undefined;
     try {
       const client = await ControlClient.connect(stateDir, { role: toolsOnly ? "tools" : "peer", peer: peerId });
       client.onPush = (msg) => msg.t === "deliver" && void push(msg.envs ?? [msg.env]); // `env`: a daemon older than wire version 2
       hub = client;
       attempt = -1;
       log(`connected to hub as "${peerId}"`);
-      await new Promise<void>((r) => (client.onClose = r));
+      code = await new Promise<number>((r) => (client.onClose = r));
       hub = undefined;
       log("hub connection lost");
     } catch (e) {
+      code = (e as { code?: number }).code;
       if (attempt === 0) log((e as Error).message);
     }
+    // Retrying these only fights another session or hammers a hub that will refuse again.
+    if (code !== undefined && TERMINAL_CLOSES[code]) {
+      detached = TERMINAL_CLOSES[code];
+      return log(`stopped reconnecting: ${detached}`);
+    }
     await new Promise((r) => setTimeout(r, Math.min(1000 * 2 ** Math.max(attempt, 0), MAX_RECONNECT_DELAY_MS)));
   }
 }
@@ -129,14 +146,14 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   }
   if (name === "hub_send") {
     const { text: body, to, reply_to } = (args ?? {}) as { text?: string; to?: string[]; reply_to?: string };
-    if (!hub) return text("hub is not running for this project (start it with: ahub up). Message not sent.");
+    if (!hub) return text(`${offline()} Message not sent.`);
     const res = await hub.request({ t: "send", body, to, reply_to });
     if (!res.ok) return text(`not sent: ${res.error}`);
     if (res.recorded) return text("recorded only ([FYI]): it is on the hub console and log, and no peer spent a turn on it");
     return text(`sent to: ${res.targets.join(", ") || "(no other peers attached)"}`);
   }
   if (TASK_TOOL_NAMES.has(name)) {
-    if (!hub) return text("hub is not running for this project (start it with: ahub up).");
+    if (!hub) return text(offline());
     const res = await hub.request({ t: "task", op: name, args: args ?? {} });
     return text(res.ok ? res.text : `error: ${res.error}`);
   }
@@ -144,4 +161,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 
 await server.connect(new StdioServerTransport());
+// The host (Claude Code, Codex, Kimi) talks over stdin; once it is gone nothing can use this server, and a leftover would keep reconnecting.
+process.stdin.on("end", () => process.exit(0));
+process.stdin.on("close", () => process.exit(0));
 void connectLoop();

package/src/cli/main.ts

@@ -388,7 +388,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const hub = await connect().catch(() => undefined);
     if (hub) {
       hub.send({ t: "kill" });
-      await new Promise<void>((r) => (hub.onClose = r));
+      await new Promise<void>((r) => (hub.onClose = () => r()));
       return console.log("hub stopped");
     }
     const pidFile = join(stateDir, "hub.pid");

package/src/hub/control-client.ts

@@ -30,7 +30,8 @@ export class ControlClient {
   private nextRid = 1;
   private readonly pending = new Map<number, (msg: any) => void>();
   onPush: (msg: any) => void = () => {};
-  onClose: () => void = () => {};
+  /** `code`/`reason`: what the hub closed with, e.g. 4000 when another client attached as the same peer. */
+  onClose: (code: number, reason: string) => void = () => {};
 
   private constructor(private readonly ws: WebSocket) {}
 
@@ -41,11 +42,12 @@ export class ControlClient {
       const ws = new WebSocket(control.url);
       const client = new ControlClient(ws);
       ws.onerror = () => reject(new Error(`cannot reach hub at ${control.url}`));
-      ws.onclose = () => {
-        reject(new Error("hub closed the connection (stale token?)"));
+      ws.onclose = (ev) => {
+        // A refused hello carries its reason (bad token, wire version, peer id); say that, not a guess.
+        reject(Object.assign(new Error(`hub closed the connection: ${ev.reason || "stale token?"}`), { code: ev.code }));
         for (const done of client.pending.values()) done({ ok: false, error: "hub connection closed" });
         client.pending.clear();
-        client.onClose();
+        client.onClose(ev.code, ev.reason);
       };
       ws.onmessage = (ev) => {
         const msg = JSON.parse(String(ev.data));

package/src/hub/daemon.ts

@@ -107,7 +107,13 @@ type Sock = ServerWebSocket<Client>;
 /** A peer that lives in another process and attaches over the control WS (the Claude channel plugin). */
 class WsPeer extends BasePeer {
   private sock: Sock | undefined;
+  private claimed: Sock | undefined;
+  /** Called at hello, before the async preface: the newest hello wins even if an older one's recall finishes last. */
+  claim(sock: Sock): void {
+    this.claimed = sock;
+  }
   attach(sock: Sock): void {
+    if (sock !== this.claimed) return void sock.close(4000, "replaced"); // a newer session said hello meanwhile
     this.sock?.close(4000, "replaced");
     this.sock = sock;
     this.setState("idle");
@@ -584,6 +590,7 @@ export async function startDaemon(opts: DaemonOptions) {
         if (!peer) bus.add((peer = new WsPeer(c.peer)));
         if (!(peer instanceof WsPeer)) return sock.close(4409, "peer id is taken by a hub-managed adapter");
         const ws = peer;
+        ws.claim(sock);
         void ensurePreface(c.peer).finally(() => {
           if (sock.readyState === WebSocket.OPEN) ws.attach(sock);
         });