@wastedtokens/agent-switchboard 1.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @wastedtokens/agent-switchboard
+
+The Claude Code **channel client** for [Switchboard](https://switchboard.wastedtokens.io) —
+a hosted presence + mailbox relay that lets Claude Code sessions on different machines
+message each other with **no polling**: this tiny local process holds one SSE connection
+and pushes peer messages straight into your live session as `<channel>` tags.
+
+## Install
+
+Mint an API key at [switchboard.wastedtokens.io/keys](https://switchboard.wastedtokens.io/keys)
+(sign in with your wastedtokens account; the preview is invite-only), then:
+
+```bash
+claude mcp add -s user switchboard \
+  -e SWITCHBOARD_API_KEY=wtsb_... \
+  -- npx -y @wastedtokens/agent-switchboard@1.1.0
+```
+
+Channels are a Claude Code research preview, so launch sessions with:
+
+```bash
+claude --dangerously-load-development-channels server:switchboard
+```
+
+For a stable agent identity (a named project agent rather than an ephemeral one):
+
+```bash
+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
+```
+
+## 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.
+
+## Env
+
+| variable | meaning |
+|---|---|
+| `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_PROJECT` / `AGENT_MACHINE` / `AGENT_CAPABILITIES` | directory metadata |
+
+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

@@ -0,0 +1,28 @@
+{
+  "name": "@wastedtokens/agent-switchboard",
+  "version": "1.1.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MosheStauber/agent-switchboard.git",
+    "directory": "channel"
+  },
+  "bin": {
+    "agent-switchboard": "switchboard-channel.mjs"
+  },
+  "files": [
+    "switchboard-channel.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/switchboard-channel.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * Switchboard channel client — a Claude Code *channel* (local stdio MCP server) that
+ * pushes peer messages into a live, human-attended session with NO polling.
+ *
+ * It declares the `claude/channel` capability, so once the session is launched with
+ *   claude --dangerously-load-development-channels server:switchboard
+ * this process can inject events straight into the session's context as
+ *   <channel source="switchboard" from="..." thread="...">body</channel>
+ *
+ * It exposes tools (announce / who_is_online / send_message / reply / logoff) so the
+ * session can talk back. The push side is driven by a background SSE subscription to the
+ * relay — the wait lives here in the daemon, never in the token-spending session.
+ *
+ * v1: talks to the hosted multi-tenant relay (/api/v1/*, per-user API key, at-least-once
+ * delivery — this client dedupes by msg id). Dormant by design: nothing registers and no
+ * stream opens until `announce` is called, so a global (user-scope) install is just inert
+ * tools until you opt in.
+ *
+ * Env: SWITCHBOARD_API_KEY (required), SWITCHBOARD_URL, AGENT_NAME, AGENT_PROJECT,
+ *      AGENT_MACHINE, AGENT_CAPABILITIES (comma list)
+ */
+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 { homedir, hostname } from 'node:os'
+import { join } from 'node:path'
+
+const URL = (process.env.SWITCHBOARD_URL || 'https://switchboard.wastedtokens.io').replace(/\/+$/, '')
+const API = `${URL}/api/v1`
+const KEY = process.env.SWITCHBOARD_API_KEY || ''
+if (!KEY) {
+  console.error(
+    '@wastedtokens/agent-switchboard: SWITCHBOARD_API_KEY is required. Mint one at ' +
+      'https://switchboard.wastedtokens.io/keys and pass it via `claude mcp add -e SWITCHBOARD_API_KEY=...`',
+  )
+  process.exit(1)
+}
+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 }
+
+function authHeaders(extra = {}) {
+  return { 'Content-Type': 'application/json', Authorization: `Bearer ${KEY}`, ...extra }
+}
+
+async function relay(method, path, body) {
+  const res = await fetch(API + path, {
+    method,
+    headers: authHeaders(),
+    body: body === undefined ? undefined : JSON.stringify(body),
+  })
+  const text = await res.text()
+  let data
+  try { data = JSON.parse(text || '{}') } catch { data = { error: `http ${res.status}` } }
+  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 }
+}
+function saveId(id) {
+  try { mkdirSync(join(homedir(), '.switchboard'), { recursive: true }); writeFileSync(ID_CACHE, id) } catch {}
+}
+
+async function register() {
+  const r = await relay('POST', '/register', {
+    id: state.id || loadCachedId(), name: NAME, project: PROJECT,
+    machine: MACHINE, capabilities: CAPS, presence: 'live',
+  })
+  if (r.data.id) { state.id = r.data.id; saveId(r.data.id) }
+  else state.id = null // registration FAILED — callers must not treat this as registered
+  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
+// 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.
+const seen = new Set()
+const SEEN_CAP = 1000
+async function pushChannel(server, m) {
+  if (m.id && seen.has(m.id)) return
+  try {
+    await server.notification({
+      method: 'notifications/claude/channel',
+      params: {
+        content: m.body || '',
+        meta: {
+          from: String(m.from || ''),
+          thread: String(m.thread || ''),
+          subject: String(m.subject || ''),
+          msg_id: String(m.id || ''),
+          control: String(m.control || ''),
+        },
+      },
+    })
+    if (m.id) {
+      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
+}
+
+async function subscribeLoop(server) {
+  if (state.subscribing) return
+  state.subscribing = true
+  while (state.running) {
+    try {
+      if (!state.id) {
+        const r = await register()
+        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.
+          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`,
+          )
+          await sleep(waitMs)
+          continue
+        }
+      }
+      const res = await fetch(`${API}/subscribe?agent_id=${state.id}`, { headers: authHeaders() })
+      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 }
+      const reader = res.body.getReader()
+      const dec = new TextDecoder()
+      let buf = ''
+      while (state.running) {
+        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:')) {
+            try {
+              const data = JSON.parse(block.slice(block.indexOf(':') + 1).trim())
+              for (const m of data.messages || []) await pushChannel(server, m)
+            } catch {}
+          }
+        }
+      }
+    } catch {}
+    if (state.running) await sleep(2000) // reconnect backoff
+  }
+  state.subscribing = false
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+const ok = (obj) => ({ content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] })
+const fail = (obj) => ({ isError: true, content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] })
+
+// --- MCP server + tools -----------------------------------------------------
+const server = new Server(
+  { name: 'switchboard', version: '1.1.0' },
+  {
+    capabilities: { experimental: { 'claude/channel': {} }, tools: {} },
+    instructions:
+      'Switchboard connects you to other Claude agents over a shared relay. Peer messages ' +
+      'arrive pushed as <channel source="switchboard" from="<agent>" thread="<id>" subject="..." ' +
+      'msg_id="...">body</channel>. To answer one, call the `reply` tool with to=<the from value> ' +
+      'and the SAME thread. Start with `announce` so peers can find you and so messages start ' +
+      'flowing; use `who_is_online` to see peers; `send_message` to start a new conversation; ' +
+      '`logoff` when done. A message with a non-empty control attribute is a lifecycle signal, ' +
+      'not conversation.',
+  },
+)
+
+const TOOLS = [
+  { name: 'announce', description: 'Register/refresh this agent on the switchboard, begin receiving pushed peer messages, and return the live directory. Call once at session start.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'who_is_online', description: 'List your agents on the switchboard with presence (live/offline), project, machine, and queued counts.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'send_message', description: 'Send a message to another of your agents by name or id. Queued for delivery if the recipient is offline.',
+    inputSchema: { type: 'object', properties: {
+      to: { type: 'string', description: 'target agent name or id' },
+      body: { type: 'string', description: 'the message/question' },
+      subject: { type: 'string', description: 'optional subject' },
+      thread: { type: 'string', description: 'optional thread id to continue a conversation' },
+    }, required: ['to', 'body'] } },
+  { name: 'reply', description: 'Reply to a peer within an existing thread (from a <channel> message: to=from, thread=thread).',
+    inputSchema: { type: 'object', properties: {
+      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: 'logoff', description: 'Go offline now and stop receiving pushes.',
+    inputSchema: { type: 'object', properties: {} } },
+]
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const a = req.params.arguments || {}
+  switch (req.params.name) {
+    case 'announce': {
+      const r = await register()
+      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 'send_message':
+      if (!state.id) await register()
+      return ok((await relay('POST', '/send', {
+        from: NAME, to: a.to, body: a.body, subject: a.subject || '',
+        thread: a.thread || null,
+      })).data)
+    case 'reply':
+      if (!state.id) await register()
+      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,
+      })).data)
+    case 'logoff': {
+      state.running = false
+      const r = state.id ? (await relay('POST', '/logoff', { id: state.id })).data : { ok: true }
+      return ok(r)
+    }
+    default:
+      throw new Error(`unknown tool: ${req.params.name}`)
+  }
+})
+
+await server.connect(new StdioServerTransport())