@wastedtokens/agent-switchboard 1.3.0 → 1.4.0

package/README.md

@@ -75,7 +75,8 @@ In-session: `announce` once, `who_is_online`, `send_message(to, body)`, and answ
 `<channel source="switchboard" from="X" thread="Y">` messages with
 `reply(to="X", thread="Y", body=...)`. `message_status(id)` returns the delivery receipt
 (`queued | leased | delivered | expired`) plus `delivered_to` — which identity actually
-consumed the message. `logoff` when done.
+consumed the message. `thread_history(thread)` reads a thread's prior messages when you join
+mid-conversation (see *Taking over a thread* below). `logoff` when done.
 
 ### Shared mailboxes (work queues)
 
@@ -99,6 +100,38 @@ Against an older relay (pre-1.6) these tools degrade to a clear error ("does not
 shared mailboxes/tasks yet") instead of failing cryptically; the reconcile block is simply
 omitted.
 
+### Taking over a thread (`thread_history`)
+
+When you `claim_next` a message, you land mid-conversation: the relay hands you exactly one
+message row, but that thread may have a long history — the previous consumer went offline,
+their stickiness lapsed, and the requester's next message fell back to the pool for you to
+pick up. `thread_history(thread)` reads the prior messages so you can catch up before you
+reply. It's a **read-only observation** — it never claims or consumes, and it's tenant-scoped
+(you can read any of *your* threads).
+
+- Every claimed (and pushed) message carries its `thread`; a claimed message also carries
+  `task_id`/`task_state` so you can drive the task with `task_update`.
+- `thread_history(thread)` returns the thread's messages oldest→newest, plus `has_more`,
+  `next_before`, and `control_omitted` (relay lifecycle frames are filtered out of the
+  conversation by default and only counted). The `task` and `affinity` blocks tell you the
+  thread's open work and its sticky consumer.
+- **Paging:** the newest page comes back first (default 100, max 200 messages). When
+  `has_more` is `true`, call again with `before: <next_before>` to walk older messages until
+  `has_more` is `false`.
+
+A typical takeover:
+
+```
+claim_next(mailbox: "support")          # → { messages: [{ thread, task_id, task_state, … }] }
+thread_history(thread: "<that thread>") # → catch up on the conversation so far
+# … page older with before: next_before while has_more …
+reply(to: "<requester>", thread: "<that thread>", body: "…")   # answer in-context
+task_update(id: "<task_id>", state: "completed")               # close the loop
+```
+
+Against a relay older than **1.8.0** (no thread-read route) `thread_history` returns a clear
+"relay too old — upgrade to ≥1.8.0" error rather than failing cryptically.
+
 ### Instant presence + clean shutdown
 
 By default the channel is idle until the agent calls `announce`. Set

package/package.json

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

package/switchboard-channel.mjs

@@ -504,7 +504,7 @@ const fail = (obj) => ({ isError: true, content: [{ type: 'text', text: JSON.str
 
 // --- MCP server + tools -----------------------------------------------------
 const server = new Server(
-  { name: 'switchboard', version: '1.3.0' },
+  { name: 'switchboard', version: '1.4.0' },
   {
     capabilities: { experimental: { 'claude/channel': {} }, tools: {} },
     instructions:
@@ -516,7 +516,9 @@ const server = new Server(
       '`logoff` when done. A message with a non-empty control attribute is a lifecycle signal, ' +
       'not conversation. Shared work queues: `claim_next` pulls the oldest unclaimed message ' +
       'from a shared mailbox (claiming also moves its open task to working under you); ' +
-      '`task_update` reports task progress (input-required / completed / failed).',
+      '`task_update` reports task progress (input-required / completed / failed). When a claim ' +
+      'or a wake lands you in an unfamiliar thread, `thread_history` reads the prior messages so ' +
+      'you can catch up before replying.',
   },
 )
 
@@ -525,10 +527,16 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: {
       mailboxes: { type: 'array', items: { type: 'string' }, description: 'shared mailboxes to attach for reconcile counts (ignored when AGENT_MAILBOXES is set — env wins)' },
     } } },
-  { name: 'claim_next', description: 'Claim the oldest unclaimed message from a shared mailbox (work queue). The claimed message is delivered to this session and acked under YOUR identity; any open task on its thread moves to working, claimed by you. Empty result = nothing queued.',
+  { name: 'claim_next', description: 'Claim the oldest unclaimed message from a shared mailbox (work queue). The claimed message is delivered to this session and acked under YOUR identity; any open task on its thread moves to working, claimed by you. Each claimed message carries its thread plus task_id/task_state (null when the thread has no open task) — drive the task with task_update. Landed mid-conversation? Call thread_history with that thread to read what came before. Empty result = nothing queued.',
     inputSchema: { type: 'object', properties: {
       mailbox: { type: 'string', description: 'shared mailbox name (kind=mailbox) to claim from' },
     }, required: ['mailbox'] } },
+  { name: 'thread_history', description: 'Read the prior messages of a thread for takeover context — a tenant-scoped, read-only observation that never claims or consumes. Pull it after claim_next lands you in an unfamiliar thread, or after a wake, to reconstruct the conversation before you joined. Returns messages oldest→newest plus has_more, next_before, and control_omitted; when has_more is true, call again with before: next_before to page older messages. The task and affinity blocks describe the thread\'s open work and its sticky consumer.',
+    inputSchema: { type: 'object', properties: {
+      thread: { type: 'string', description: 'thread id to read (the thread of a claimed/pushed message)' },
+      limit: { type: 'number', description: 'max messages this page (default 100, max 200)' },
+      before: { type: 'string', description: 'pagination cursor — pass the previous response\'s next_before to page older' },
+    }, required: ['thread'] } },
   { name: 'task_update', description: 'Update a task\'s state: working | input-required (escalated, waiting on the requester) | completed | failed. Tasks are created automatically when a message lands in a shared mailbox; claiming moves them to working. Closed tasks stay closed.',
     inputSchema: { type: 'object', properties: {
       id: { type: 'string', description: 'task id (task_…)' },
@@ -556,8 +564,57 @@ const TOOLS = [
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 
+// --- argument validation (issue #36 nit 2) ----------------------------------
+// Reject a call with a missing/mistyped required arg or an unknown arg BEFORE any relay
+// hit — a bare `message_status` used to send GET /messages/undefined (encodeURIComponent of
+// undefined is the literal "undefined"), silently querying a nonexistent id. The check is
+// driven off each tool's own inputSchema so every handler is covered uniformly. Required
+// strings must be present and non-empty (they land in URL paths); optional strings may be
+// empty; numbers accept a numeric value or numeric string (the relay parses either).
+function typeError(k, v, spec, requireNonEmpty) {
+  const t = spec.type
+  if (t === 'string') {
+    if (typeof v !== 'string') return `parameter '${k}' must be a string`
+    if (requireNonEmpty && v.trim() === '') return `parameter '${k}' must not be empty`
+  } else if (t === 'number' || t === 'integer') {
+    const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : NaN
+    if (!Number.isFinite(n)) return `parameter '${k}' must be a number`
+  } else if (t === 'array') {
+    if (!Array.isArray(v)) return `parameter '${k}' must be an array`
+  }
+  return null
+}
+function validateArgs(name, args) {
+  const tool = TOOLS.find((t) => t.name === name)
+  if (!tool) return null // unknown tool name — let the switch default throw its own error
+  const props = tool.inputSchema?.properties || {}
+  const required = tool.inputSchema?.required || []
+  for (const k of Object.keys(args)) {
+    if (!(k in props))
+      return `unknown parameter '${k}' for ${name} (allowed: ${Object.keys(props).join(', ') || 'none'})`
+  }
+  for (const k of required) {
+    const v = args[k]
+    if (v === undefined || v === null) return `missing required parameter '${k}' for ${name}`
+    const err = typeError(k, v, props[k] || {}, true)
+    if (err) return err
+  }
+  for (const k of Object.keys(props)) {
+    if (required.includes(k)) continue
+    const v = args[k]
+    if (v === undefined || v === null) continue // optional + absent is fine
+    const err = typeError(k, v, props[k] || {}, false)
+    if (err) return err
+  }
+  return null
+}
+
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const a = req.params.arguments || {}
+  // Param validation runs first so a malformed call fails clearly (and cheaply) before we
+  // touch identity/convergence or the relay — no GET /messages/undefined (issue #36 nit 2).
+  const paramErr = validateArgs(req.params.name, a)
+  if (paramErr) return fail({ error: paramErr })
   // logoff must stay functional even when inert (a demoted client still cleans up on exit).
   // Every other tool re-runs the same-session scan first (active convergence, routing-v2 §1c):
   // an already-running client demotes the instant a live same-session peer beats it, and an
@@ -593,6 +650,21 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       return ok((await relay('GET', '/directory')).data)
     case 'message_status':
       return ok((await relay('GET', `/messages/${encodeURIComponent(a.id)}`)).data)
+    case 'thread_history': {
+      // Takeover context (spec §3): read-only passthrough of GET /api/v1/threads/{thread}.
+      // The pagination surface (has_more / next_before / control_omitted) and the task/affinity
+      // blocks are returned UNCHANGED so the consumer can page and reason about them directly.
+      const q = new URLSearchParams()
+      if (a.limit !== undefined && a.limit !== null) q.set('limit', String(a.limit))
+      if (a.before) q.set('before', String(a.before))
+      const qs = q.toString()
+      const r = await relay('GET', `/threads/${encodeURIComponent(a.thread)}${qs ? `?${qs}` : ''}`)
+      // Graceful degrade on a pre-1.8 relay: the route 404s with a non-JSON body (preRoutingV2),
+      // distinct from the route's own JSON 404 "no such thread" — same pattern as the receipt
+      // fallback. Wire errors (404 no such thread / 400 bad cursor) pass straight through.
+      if (preRoutingV2(r)) return fail({ error: 'relay too old for thread history — upgrade the relay to ≥1.8.0' })
+      return r.status === 200 ? ok(r.data) : fail(r.data)
+    }
     case 'claim_next': {
       // §2e: per-message claim from a shared work queue. Needs a registered consumer identity
       // (the relay refuses mailbox/unknown consumers); lazy-register like send_message does.