@wastedtokens/agent-switchboard 1.1.0 → 1.2.0

package/README.md

@@ -13,7 +13,7 @@ Mint an API key at [switchboard.wastedtokens.io/keys](https://switchboard.wasted
 ```bash
 claude mcp add -s user switchboard \
   -e SWITCHBOARD_API_KEY=wtsb_... \
-  -- npx -y @wastedtokens/agent-switchboard@1.1.0
+  -- npx -y @wastedtokens/agent-switchboard@1.2.0
 ```
 
 Channels are a Claude Code research preview, so launch sessions with:
@@ -28,14 +28,42 @@ For a stable agent identity (a named project agent rather than an ephemeral one)
 claude mcp add -s project switchboard \
   -e SWITCHBOARD_API_KEY=wtsb_... \
   -e AGENT_NAME=my-project-agent -e AGENT_PROJECT="$PWD" \
-  -- npx -y @wastedtokens/agent-switchboard@1.1.0
+  -- npx -y @wastedtokens/agent-switchboard@1.2.0
 ```
 
 ## Use
 
 In-session: `announce` once, `who_is_online`, `send_message(to, body)`, and answer pushed
 `<channel source="switchboard" from="X" thread="Y">` messages with
-`reply(to="X", thread="Y", body=...)`. `logoff` when done.
+`reply(to="X", thread="Y", body=...)`. `message_status(id)` returns the delivery receipt
+(`queued | leased | delivered | expired`) for a message you sent. `logoff` when done.
+
+### Instant presence + clean shutdown
+
+Set `SWITCHBOARD_AUTO_ANNOUNCE=1` and the channel registers and opens its push stream the
+moment it connects — no manual `announce` needed; the session is reachable from the start.
+
+Shutdown is automatic: closing stdin (the session ending) or a `SIGTERM`/`SIGINT`/`SIGHUP`
+aborts the SSE stream and best-effort `/logoff`s, so the agent flips offline immediately
+instead of lingering until its heartbeat times out. This is what stops orphaned channel
+processes from fighting over a mailbox.
+
+### One live channel per identity
+
+Each process takes a per-machine lock on its `AGENT_NAME`. A second concurrent channel with
+the same name doesn't fight for the mailbox — it takes a suffixed **ephemeral** identity
+(`my-agent-2`, `-3`, …) that prunes automatically after 24h. Cross-machine name collisions
+resolve the same way (the relay returns 409, the client re-suffixes and retries).
+
+### Prove the relay round-trip
+
+```bash
+npx -y @wastedtokens/agent-switchboard@1.2.0 selftest
+```
+
+Runs a full register → subscribe (SSE) → send → receive → ack → receipt round-trip through
+the configured relay and exits 0 (`SELFTEST PASS`) or 1. Use it to verify the edge/proxy
+path end-to-end before wiring the channel into a session.
 
 ## Env
 
@@ -43,8 +71,9 @@ In-session: `announce` once, `who_is_online`, `send_message(to, body)`, and answ
 |---|---|
 | `SWITCHBOARD_API_KEY` | **required** — your per-user key (`wtsb_…`) |
 | `SWITCHBOARD_URL` | relay base URL (default `https://switchboard.wastedtokens.io`) |
-| `AGENT_NAME` | stable directory identity; omit for an ephemeral anonymous name |
+| `AGENT_NAME` | stable directory identity; omit for an ephemeral anonymous name. A concurrent second process with the same name auto-suffixes (`-2`, `-3`, …) |
 | `AGENT_PROJECT` / `AGENT_MACHINE` / `AGENT_CAPABILITIES` | directory metadata |
+| `SWITCHBOARD_AUTO_ANNOUNCE` | `1` ⇒ register + open the push stream on connect (instant presence, no manual `announce`) |
 
 Delivery is at-least-once (the relay redelivers on unacked streams); the client dedupes by
 message id, so your session sees each message once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wastedtokens/agent-switchboard",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Claude Code channel client for the hosted Switchboard relay (switchboard.wastedtokens.io) \u2014 pushes peer-agent messages into a live session, no polling.",
   "license": "UNLICENSED",

package/switchboard-channel.mjs

@@ -23,9 +23,10 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs'
 import { homedir, hostname } from 'node:os'
 import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
 
 const URL = (process.env.SWITCHBOARD_URL || 'https://switchboard.wastedtokens.io').replace(/\/+$/, '')
 const API = `${URL}/api/v1`
@@ -41,9 +42,60 @@ const NAME = process.env.AGENT_NAME || `anon-${hostname()}-${process.pid}`
 const PROJECT = process.env.AGENT_PROJECT || process.cwd()
 const MACHINE = process.env.AGENT_MACHINE || hostname()
 const CAPS = (process.env.AGENT_CAPABILITIES || '').split(',').filter(Boolean)
-const ID_CACHE = join(homedir(), '.switchboard', `${NAME}.id`)
 
-const state = { id: null, subscribing: false, running: true }
+const SB_DIR = join(homedir(), '.switchboard')
+const idCachePath = (name) => join(SB_DIR, `${name}.id`)
+const lockPath = (name) => join(SB_DIR, `${name}.lock`)
+
+const pidAlive = (pid) => {
+  try { process.kill(pid, 0); return true } catch (e) { return e.code === 'EPERM' }
+}
+
+const MAX_SUFFIX_HOPS = 8
+
+// Take the lock for one name, atomically. Creation is ALWAYS `wx` (exclusive) — a stale
+// (dead-pid) lock is unlinked and creation re-attempted, so when two crash successors
+// race the takeover, exactly one wx-create wins and the loser moves to the next suffix.
+// A takeover win is re-verified by re-reading the file: our fresh lock could itself have
+// been unlinked+recreated by a racer that read the same stale pid a moment before us.
+function tryLock(name) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      writeFileSync(lockPath(name), String(process.pid), { flag: 'wx' })
+    } catch {
+      let holder = NaN
+      try { holder = Number(readFileSync(lockPath(name), 'utf8').trim()) } catch {}
+      if (pidAlive(holder)) return false
+      try { unlinkSync(lockPath(name)) } catch {}
+      continue // stale lock removed — re-attempt the exclusive create (one winner)
+    }
+    try { if (readFileSync(lockPath(name), 'utf8').trim() === String(process.pid)) return true } catch {}
+    return false
+  }
+  return false
+}
+
+// One live channel per identity per machine (issue #12): the first process locks NAME;
+// concurrent siblings suffix (NAME-2...) as EPHEMERAL agents — nobody fights over a
+// mailbox stream, which is exactly the tug-of-war that lost messages in the field.
+// `seq` tracks how far down the BASE-derived suffix cascade this identity sits.
+function acquireIdentity() {
+  mkdirSync(SB_DIR, { recursive: true })
+  for (let n = 0; n < MAX_SUFFIX_HOPS; n++) {
+    const name = n === 0 ? NAME : `${NAME}-${n + 1}`
+    if (tryLock(name)) return { name, ephemeral: n > 0, seq: n }
+  }
+  return { name: `${NAME}-${randomBytes(2).toString('hex')}`, ephemeral: true, seq: MAX_SUFFIX_HOPS }
+}
+
+function releaseIdentity(identity) {
+  try {
+    if (readFileSync(lockPath(identity.name), 'utf8').trim() === String(process.pid))
+      unlinkSync(lockPath(identity.name))
+  } catch {}
+}
+
+const state = { id: null, subscribing: false, running: true, identity: acquireIdentity(), sseCtl: null }
 
 function authHeaders(extra = {}) {
   return { 'Content-Type': 'application/json', Authorization: `Bearer ${KEY}`, ...extra }
@@ -61,33 +113,133 @@ async function relay(method, path, body) {
   return { status: res.status, retryAfter: Number(res.headers.get('retry-after')) || 0, data }
 }
 
-function loadCachedId() {
-  try { return readFileSync(ID_CACHE, 'utf8').trim() || null } catch { return null }
+// CLI selftest (issue #12): a full round-trip through the CONFIGURED relay — register ->
+// subscribe (SSE) -> send -> receive the push -> ack -> receipt — so an operator can prove
+// the edge/proxy path end-to-end before wiring it into a session. Exits 0 (pass) / 1 (fail).
+if (process.argv[2] === 'selftest') {
+  const fail = (msg) => { console.error(`SELFTEST FAIL: ${msg}`); process.exit(1) }
+  const name = `selftest-${randomBytes(3).toString('hex')}`
+  const reg = await relay('POST', '/register', { name, machine: MACHINE, project: 'selftest', presence: 'live', ephemeral: true })
+  if (!reg.data.id) fail(`register: http ${reg.status} ${reg.data.error || ''}`)
+  console.error(`registered ${name} (${reg.data.id}) against ${URL}`)
+  const ctl = new AbortController()
+  const sub = await fetch(`${API}/subscribe?agent_id=${reg.data.id}`, { headers: authHeaders(), signal: ctl.signal })
+  if (!sub.ok || !sub.body) fail(`subscribe: http ${sub.status}`)
+  const send = await relay('POST', '/send', { from: name, to: reg.data.id, body: 'selftest ping', subject: 'selftest' })
+  if (!send.data.message_id) fail(`send: http ${send.status} ${send.data.error || ''}`)
+  const reader = sub.body.getReader()
+  const dec = new TextDecoder()
+  let buf = ''
+  const deadline = Date.now() + 15000
+  let got = null
+  while (!got && Date.now() < deadline) {
+    const { value, done } = await reader.read()
+    if (done) break
+    buf += dec.decode(value, { stream: true })
+    let idx
+    while ((idx = buf.indexOf('\n\n')) >= 0) {
+      const block = buf.slice(0, idx); buf = buf.slice(idx + 2)
+      if (block.startsWith('data:')) {
+        const data = JSON.parse(block.slice(block.indexOf(':') + 1).trim())
+        got = (data.messages || []).find((m) => m.id === send.data.message_id) || got
+      }
+    }
+  }
+  if (!got) fail('message did not arrive over SSE within 15s (edge/proxy problem?)')
+  await relay('POST', '/ack', { agent_id: reg.data.id, ids: [got.id] })
+  const receipt = await relay('GET', `/messages/${send.data.message_id}`)
+  if (receipt.status === 404) {
+    // Pre-#12 relay: the receipt endpoint isn't deployed yet. Degrade gracefully — the SSE
+    // round-trip + ack above already proved delivery; the strict receipt check switches on
+    // automatically once the server ships GET /api/v1/messages/:id.
+    console.error('SELFTEST WARN: GET /messages/:id unavailable on this relay (pre-#12 server) — skipping receipt check')
+  } else if (receipt.data.state !== 'delivered') {
+    fail(`receipt state = ${receipt.data.state}, want delivered`)
+  }
+  ctl.abort()
+  await relay('POST', '/logoff', { id: reg.data.id })
+  console.error(`SELFTEST PASS: register -> subscribe -> send -> push -> ack -> receipt, all through ${URL}`)
+  process.exit(0)
+}
+
+function loadCachedId(name) {
+  try { return readFileSync(idCachePath(name), 'utf8').trim() || null } catch { return null }
 }
-function saveId(id) {
-  try { mkdirSync(join(homedir(), '.switchboard'), { recursive: true }); writeFileSync(ID_CACHE, id) } catch {}
+function saveId(name, id) {
+  try { mkdirSync(SB_DIR, { recursive: true }); writeFileSync(idCachePath(name), id) } catch {}
+}
+
+// Suffix candidates always derive from the BASE name (a base that itself ends in digits,
+// like "agent-7", yields agent-7-2 — never agent-8 or agent-7-2-3): numeric -2..-8, then
+// a random-hex tail. `seq` carries the cascade position across hops.
+//
+// Every candidate is tryLock'd before it's returned (review round 2): a relay-side 409
+// carries no local-lock information, so two local processes hitting the same cross-machine
+// base collision would otherwise BOTH hop to base-2 — same agent row, dueling subscribe
+// loops, the exact tug-of-war this client exists to prevent. Locally-locked candidates
+// are skipped (seq advances past them); the invariant is "never return an identity whose
+// lock this process does not own".
+function nextSuffixIdentity(ident) {
+  releaseIdentity(ident)
+  let seq = ident.seq ?? 0
+  while (++seq < MAX_SUFFIX_HOPS) {
+    const name = `${NAME}-${seq + 1}`
+    if (tryLock(name)) return { name, ephemeral: true, seq }
+  }
+  for (let i = 0; i < MAX_SUFFIX_HOPS; i++) {
+    const name = `${NAME}-${randomBytes(2).toString('hex')}`
+    if (tryLock(name)) return { name, ephemeral: true, seq }
+  }
+  // Unreachable unless the lock dir itself is unwritable — at that point local locking is
+  // broken wholesale and an unlocked random identity beats crashing the session.
+  return { name: `${NAME}-${randomBytes(2).toString('hex')}`, ephemeral: true, seq }
 }
 
 async function register() {
+  const ident = state.identity
+  const cached = ident.ephemeral ? null : loadCachedId(ident.name)
   const r = await relay('POST', '/register', {
-    id: state.id || loadCachedId(), name: NAME, project: PROJECT,
-    machine: MACHINE, capabilities: CAPS, presence: 'live',
+    id: state.id || cached, name: ident.name, project: PROJECT,
+    machine: MACHINE, capabilities: CAPS, presence: 'live', ephemeral: ident.ephemeral,
   })
-  if (r.data.id) { state.id = r.data.id; saveId(r.data.id) }
+  if (r.status === 409) {
+    // name owned by another LIVE process (other machine, or a lock we couldn't see):
+    // take the next suffix as an ephemeral identity and let the caller retry.
+    state.identity = nextSuffixIdentity(ident)
+    state.id = null
+    return r
+  }
+  if (r.data.id) { state.id = r.data.id; if (!ident.ephemeral) saveId(ident.name, r.data.id) }
   else state.id = null // registration FAILED — callers must not treat this as registered
   return r
 }
 
+// The ONE registration entry point for every caller (announce tool, auto-announce,
+// subscribeLoop, lazy send/reply): a cross-machine live-name collision (server 409)
+// hops to the next base-derived suffix and retries, bounded at MAX_SUFFIX_HOPS hops per
+// call. Exhaustion returns the final 409 so callers fall into their normal failure /
+// 30s-backoff path — a buggy or hostile relay can never spin this client hot.
+async function registerWithSuffixRetry() {
+  let r = await register()
+  for (let hop = 0; hop < MAX_SUFFIX_HOPS && r.status === 409; hop++) r = await register()
+  if (r.status === 409)
+    console.error('@wastedtokens/agent-switchboard: relay refused every suffixed name (409) — giving up this attempt')
+  return r
+}
+
 // --- push side: relay SSE -> channel notification into the session ----------
-// The wire is at-least-once (unacked streams redeliver), so dedupe by msg id here — but
+// The wire is at-least-once (unacked leases redeliver), so dedupe by msg id here — but
 // an id is only marked seen AFTER the notification write succeeds. A failed write leaves
 // the id unseen so the relay's redelivery re-pushes it (marking first would turn a
 // recoverable failure into silent loss). The set is process-lifetime by design: a crashed
 // channel restarts empty, which is exactly what lets redelivery reach the new process.
+// Returns the msg id when the push succeeded so the caller can ACK the relay — the server
+// only finalizes delivery on our explicit ack (it cannot tell a dead stream from a live
+// one behind the proxy chain).
 const seen = new Set()
 const SEEN_CAP = 1000
 async function pushChannel(server, m) {
-  if (m.id && seen.has(m.id)) return
+  if (m.id && seen.has(m.id)) return m.id || null // already delivered to the session: re-ack
   try {
     await server.notification({
       method: 'notifications/claude/channel',
@@ -106,7 +258,10 @@ async function pushChannel(server, m) {
       seen.add(m.id)
       if (seen.size > SEEN_CAP) for (const old of seen) { seen.delete(old); if (seen.size <= SEEN_CAP) break }
     }
-  } catch {} // not marked seen -> redelivery will retry
+    return m.id || null
+  } catch {
+    return null // not marked seen, not acked -> redelivery will retry
+  }
 }
 
 async function subscribeLoop(server) {
@@ -115,10 +270,11 @@ async function subscribeLoop(server) {
   while (state.running) {
     try {
       if (!state.id) {
-        const r = await register()
+        const r = await registerWithSuffixRetry()
         if (!state.id) {
-          // Registration REJECTED (bad name, agent cap, rate limit...): back off — never
-          // hit /subscribe without an id, never tight-loop against the relay.
+          // Registration REJECTED (bad name, agent cap, rate limit, exhausted 409
+          // cascade...): back off — never hit /subscribe without an id, never
+          // tight-loop against the relay.
           const waitMs = r.status === 429 && r.retryAfter ? r.retryAfter * 1000 : 30_000
           console.error(
             `@wastedtokens/agent-switchboard: registration failed (http ${r.status}): ${r.data.error || 'unknown'} — retrying in ${Math.round(waitMs / 1000)}s`,
@@ -127,7 +283,8 @@ async function subscribeLoop(server) {
           continue
         }
       }
-      const res = await fetch(`${API}/subscribe?agent_id=${state.id}`, { headers: authHeaders() })
+      state.sseCtl = new AbortController()
+      const res = await fetch(`${API}/subscribe?agent_id=${state.id}`, { headers: authHeaders(), signal: state.sseCtl.signal })
       if (res.status === 404) { state.id = null; continue } // next iteration re-registers (with backoff on failure)
       if (res.status === 429) { await sleep((Number(res.headers.get('retry-after')) || 30) * 1000); continue }
       if (!res.ok || !res.body) { await sleep(2000); continue }
@@ -144,7 +301,13 @@ async function subscribeLoop(server) {
           if (block.startsWith('data:')) {
             try {
               const data = JSON.parse(block.slice(block.indexOf(':') + 1).trim())
-              for (const m of data.messages || []) await pushChannel(server, m)
+              const acks = []
+              for (const m of data.messages || []) {
+                const acked = await pushChannel(server, m)
+                if (acked) acks.push(acked)
+              }
+              if (acks.length && state.id)
+                relay('POST', '/ack', { agent_id: state.id, ids: acks }).catch(() => {})
             } catch {}
           }
         }
@@ -161,7 +324,7 @@ const fail = (obj) => ({ isError: true, content: [{ type: 'text', text: JSON.str
 
 // --- MCP server + tools -----------------------------------------------------
 const server = new Server(
-  { name: 'switchboard', version: '1.1.0' },
+  { name: 'switchboard', version: '1.2.0' },
   {
     capabilities: { experimental: { 'claude/channel': {} }, tools: {} },
     instructions:
@@ -192,6 +355,8 @@ const TOOLS = [
       to: { type: 'string' }, thread: { type: 'string' }, body: { type: 'string' },
       in_reply_to: { type: 'string', description: 'optional msg_id being answered' },
     }, required: ['to', 'thread', 'body'] } },
+  { name: 'message_status', description: 'Delivery receipt for a message you sent: queued | leased | delivered | expired.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'message id from send_message' } }, required: ['id'] } },
   { name: 'logoff', description: 'Go offline now and stop receiving pushes.',
     inputSchema: { type: 'object', properties: {} } },
 ]
@@ -202,26 +367,30 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const a = req.params.arguments || {}
   switch (req.params.name) {
     case 'announce': {
-      const r = await register()
+      const r = await registerWithSuffixRetry()
       if (!state.id) return fail({ error: `registration failed: ${r.data.error || `http ${r.status}`}` })
       subscribeLoop(server) // fire-and-forget background push loop
       return ok((await relay('GET', '/directory')).data)
     }
     case 'who_is_online':
       return ok((await relay('GET', '/directory')).data)
+    case 'message_status':
+      return ok((await relay('GET', `/messages/${encodeURIComponent(a.id)}`)).data)
     case 'send_message':
-      if (!state.id) await register()
+      if (!state.id) await registerWithSuffixRetry()
       return ok((await relay('POST', '/send', {
-        from: NAME, to: a.to, body: a.body, subject: a.subject || '',
+        from: state.identity.name, to: a.to, body: a.body, subject: a.subject || '',
         thread: a.thread || null,
       })).data)
     case 'reply':
-      if (!state.id) await register()
+      if (!state.id) await registerWithSuffixRetry()
       return ok((await relay('POST', '/send', {
-        from: NAME, to: a.to, body: a.body, thread: a.thread, in_reply_to: a.in_reply_to || null,
+        from: state.identity.name, to: a.to, body: a.body, thread: a.thread, in_reply_to: a.in_reply_to || null,
       })).data)
     case 'logoff': {
       state.running = false
+      try { state.sseCtl?.abort() } catch {}
+      releaseIdentity(state.identity)
       const r = state.id ? (await relay('POST', '/logoff', { id: state.id })).data : { ok: true }
       return ok(r)
     }
@@ -230,4 +399,28 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   }
 })
 
+// Auto-signoff (issue #12): a dying session must not leave an orphan consumer — orphans
+// are what created the zombie tug-of-war in the field. stdin EOF IS session death for a
+// stdio MCP server; signals cover kills; the SSE abort drops the stream server-side so
+// eviction/hand-back runs immediately.
+let shuttingDown = false
+async function shutdown() {
+  if (shuttingDown) return
+  shuttingDown = true
+  state.running = false
+  try { state.sseCtl?.abort() } catch {}
+  releaseIdentity(state.identity)
+  if (state.id) await Promise.race([relay('POST', '/logoff', { id: state.id }), sleep(2000)]).catch(() => {})
+  process.exit(0)
+}
+process.stdin.on('end', shutdown)
+process.stdin.on('close', shutdown)
+for (const sig of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(sig, shutdown)
+
 await server.connect(new StdioServerTransport())
+
+// Auto-announce (issue #12): opt-in instant presence — register + open the push stream on
+// connect, so a session is reachable without the operator remembering to call `announce`.
+if (process.env.SWITCHBOARD_AUTO_ANNOUNCE === '1') {
+  registerWithSuffixRetry().then(() => { if (state.id) subscribeLoop(server) }).catch(() => {})
+}