openvisio-agent 0.1.0 → 0.3.0

package/README.md

@@ -20,6 +20,31 @@ That's it. Your agent now has the team's tools (channels, tickets, docs, search)
 
 Options: `--name "<agent>"` (label), `--mcp-url <url>` (override the MCP endpoint).
 
+### `connect --backend <url> --key <api-key> --id <identifier>`
+
+For an agent created against the **org backend** (OpenVisio → Agents → Connect your agent). Verifies the credentials against the backend, then saves `~/.openvisio/<agent>.json` plus a sourceable `~/.openvisio/<agent>.env`:
+
+```
+npx -y openvisio-agent@latest connect --backend https://api.your-org.example/dev \
+  --key 660e8400-… --id 550e8400-… --name "Ada"
+```
+
+The api-key is shown **once**, when the agent is created — if it's lost, remove the agent in OpenVisio and connect it again. The backend dispatches board tasks to the agent; every request authenticates with the `x-agent-api-key` + `x-agent-identifier` headers. Options: `--name "<agent>"` (label / file names).
+
+**Real-time autonomy (optional).** Add `--ws` and `--mcp-url` to let the agent react to assignments and @mentions the moment the backend pushes them:
+
+```
+npx -y openvisio-agent@latest connect --backend https://api.your-org.example/dev \
+  --key 660e8400-… --id 550e8400-… --name "Ada" \
+  --ws wss://abc123.execute-api.us-east-1.amazonaws.com/dev \
+  --mcp-url https://api.your-org.example/dev/agent/mcp
+```
+
+- `--ws <wss-url>` — the org's API-Gateway WebSocket base (the same value the frontend uses as `NEXT_PUBLIC_BACKEND_WS_URL`).
+- `--mcp-url <url>` — registers the `openvisio-team` MCP (authed with the agent header pair) so the agent has tools to **act** on the events.
+
+Then `watch --name ada` auto-detects the backend agent and runs a WebSocket loop instead of polling: it connects with `?api_key=&identifier=`, keeps the connection warm with keepalives, reconnects with backoff, and pokes **one** Claude cycle per `task:assigned` / `agent:mention` (a burst of mentions coalesces into a single follow-up). Needs **Node ≥ 21** for the built-in WebSocket (Node 20: run with `--experimental-websocket`).
+
 ### `watch --name <agent>`
 
 Runs the **autonomy loop** — the agent replies to @mentions and picks up tickets on its own. It cheaply polls an inbox endpoint (no model spend when idle) and pokes a single warm Claude Code session only when something new arrives.

package/bin/cli.mjs

@@ -10,10 +10,10 @@
 // config for `watch`. Nothing is fetched-and-eval'd; the whole source is on npm.
 
 import { spawnSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
-import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, writeJson, mcpConfigPath, configPath, fail, ok, info } from '../src/lib.mjs'
+import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, writeJson, mcpConfigPath, configPath, chmodSafe, OV_DIR, fail, ok, info } from '../src/lib.mjs'
 import { runWatch } from '../src/watch.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
@@ -25,6 +25,7 @@ Connect your coding agent to an OpenVisio team.
 
 Usage:
   openvisio-agent connect <ovs_code> --host <url> [--name "<agent>"] [--mcp-url <url>]
+  openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>]
   openvisio-agent watch   --name <agent> [--install] [--workdir <repo>]
   openvisio-agent --help | --version
 
@@ -32,6 +33,17 @@ connect
   Redeems the setup code, adds the "openvisio-team" MCP server to Claude Code, and
   saves a config for the autonomy watcher.
 
+connect --backend
+  Registers a BACKEND agent (created in OpenVisio → Agents → Connect your agent):
+  verifies the api-key + identifier against the org backend, then saves the
+  credentials (~/.openvisio/<agent>.json + a sourceable <agent>.env). The backend
+  dispatches board tasks to the agent; requests authenticate with the
+  x-agent-api-key + x-agent-identifier headers.
+    --ws <wss-url>   API-Gateway WebSocket base (same as NEXT_PUBLIC_BACKEND_WS_URL)
+                     — enables real-time autonomy (task:assigned / agent:mention).
+    --mcp-url <url>  registers the openvisio-team MCP so the agent has tools to ACT
+                     on those events. Needs Node >= 21 for the WebSocket.
+
 watch
   Runs the event-driven autonomy loop (reply to mentions, pick up tickets). Add
   --install to run it in the background on login. Add --workdir <repo> to let it do
@@ -40,9 +52,10 @@ watch
 Docs: https://www.npmjs.com/package/openvisio-agent`
 
 async function runConnect({ positional, flags }) {
+  if (flags.backend) return runConnectBackend({ positional, flags })
   const token = positional[0] || flags.token
   const host = flags.host && String(flags.host)
-  if (!token) fail('Missing setup code.\n  Usage: openvisio-agent connect <ovs_code> --host <your OpenVisio URL>')
+  if (!token) fail('Missing setup code.\n  Usage: openvisio-agent connect <ovs_code> --host <your OpenVisio URL>\n  (Backend agent instead? openvisio-agent connect --backend <url> --key <api-key> --id <identifier>)')
   if (!/^ovs_[a-z0-9]+$/i.test(String(token))) fail('That doesn\'t look like a setup code (expected ovs_…).')
   if (!host) fail('Missing --host <your OpenVisio URL>.')
 
@@ -72,6 +85,86 @@ async function runConnect({ positional, flags }) {
   info(`  openvisio-agent watch --name ${slug} --workdir <repo>   # allow real coding on a branch`)
 }
 
+// Backend mode — for agents created against the OpenVisio ORG BACKEND
+// ("Connect your agent" in the Agents tool). No setup-token exchange: the
+// one-time api-key + identifier from the create screen ARE the credentials.
+// We verify them live, then persist a config + a sourceable env file.
+async function runConnectBackend({ flags }) {
+  const backend = stripSlash(String(flags.backend))
+  const apiKey = flags.key && String(flags.key)
+  const identifier = flags.id && String(flags.id)
+  if (!/^https?:\/\//.test(backend)) fail('The --backend value must be a full URL (e.g. https://api.your-org.example/dev).')
+  if (!apiKey || apiKey === true) fail('Missing --key <api-key>.\n  The key is shown ONCE when the agent is created (OpenVisio → Agents → Connect your agent).')
+  if (!identifier) fail('Missing --id <identifier> (shown on the agent\'s create screen and profile).')
+
+  info(`Verifying credentials against ${backend} …`)
+  const headers = { accept: 'application/json', 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier }
+  let res
+  try {
+    res = await fetch(backend + '/projects', { headers })
+  } catch (e) {
+    fail(`Couldn't reach ${backend} — check the URL and your connection.\n  (${e && e.message ? e.message : e})`)
+  }
+  if (res.status === 401 || res.status === 403) {
+    fail('The backend rejected these credentials.\n  Check the api-key and identifier — the key is shown once at creation; if it\'s lost, remove the agent in OpenVisio and connect it again for a fresh one.')
+  }
+  if (!res.ok) fail(`The backend answered HTTP ${res.status} — credentials could not be verified.`)
+
+  const name = (flags.name && String(flags.name)) || 'backend-agent'
+  const slug = slugify(name)
+
+  // Optional real-time autonomy: --ws is the org's API-Gateway WS base (same value
+  // as the frontend's NEXT_PUBLIC_BACKEND_WS_URL). --mcp-url gives the agent a tool
+  // surface so WS events (task:assigned / agent:mention) can drive a Claude cycle.
+  const wsUrl = flags.ws ? stripSlash(String(flags.ws)) : ''
+  const mcpUrl = flags['mcp-url'] ? String(flags['mcp-url']) : ''
+  if (wsUrl && !/^wss?:\/\//.test(wsUrl)) fail('The --ws value must be a WebSocket URL (wss://<id>.execute-api.<region>.amazonaws.com/<stage>).')
+
+  let mcpConfig = ''
+  if (mcpUrl) {
+    const claude = ensureClaude()
+    // Backend agents authenticate with the agent header pair, not a Bearer JWT.
+    const hdr = ['--header', `x-agent-api-key: ${apiKey}`, '--header', `x-agent-identifier: ${identifier}`]
+    spawnSync(claude, ['mcp', 'add', '--transport', 'http', 'openvisio-team', mcpUrl, ...hdr], { stdio: 'ignore' })
+    mcpConfig = mcpConfigPath(slug)
+    writeJson(mcpConfig, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier } } } }, true)
+  }
+
+  writeJson(configPath(slug), { mode: 'backend', backend, apiKey, identifier, name, slug, wsUrl, mcpUrl, mcpConfig }, true)
+  // A sourceable env file, matching the setup snippet OpenVisio shows.
+  const envPath = join(OV_DIR, `${slug}.env`)
+  mkdirSync(OV_DIR, { recursive: true })
+  writeFileSync(envPath, [
+    `OPENVISIO_API_URL=${backend}`,
+    `OPENVISIO_AGENT_API_KEY=${apiKey}`,
+    `OPENVISIO_AGENT_IDENTIFIER=${identifier}`,
+    ...(wsUrl ? [`OPENVISIO_AGENT_WS_URL=${wsUrl}`] : []),
+    '',
+  ].join('\n'))
+  chmodSafe(envPath, 0o600)
+
+  ok(`"${name}" is connected to the org backend — credentials verified.`)
+  info()
+  info(`Saved:  ${configPath(slug)}`)
+  info(`        ${envPath}   (load with:  set -a; source ${envPath}; set +a)`)
+  if (mcpConfig) info(`        ${mcpConfig}   (scoped MCP for the watcher)`)
+  info()
+  info('The backend dispatches board tasks assigned to this agent. Every request it')
+  info('makes authenticates with the x-agent-api-key + x-agent-identifier headers.')
+  if (wsUrl) {
+    info()
+    info('Real-time autonomy is ready. Let it react to assignments + @mentions live:')
+    info(`  openvisio-agent watch --name ${slug}                    # run now, in this terminal`)
+    info(`  openvisio-agent watch --name ${slug} --install          # background, on login`)
+    info(`  openvisio-agent watch --name ${slug} --workdir <repo>   # allow real coding on a branch`)
+    if (!mcpUrl) info('  (add --mcp-url on connect to give the agent tools to ACT on those events.)')
+  } else {
+    info()
+    info('Tip: pass --ws <wss-url> and --mcp-url <url> to enable real-time autonomy')
+    info('     (the agent reacts to task:assigned / agent:mention over a WebSocket).')
+  }
+}
+
 async function main() {
   const argv = process.argv.slice(2)
   if (argv.includes('--version') || argv[0] === 'version') { info(VERSION); return }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Connect your coding agent (Claude Code) to an OpenVisio team — MCP tools + optional autonomy — in one command. No shell scripts.",
   "type": "module",
   "bin": {

package/src/watch.mjs

@@ -9,6 +9,7 @@ import { writeFileSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
 import { OV_DIR, readConfig, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
+import { connectAgentWs, assertWebSocket } from './ws.mjs'
 
 const CYCLE = 'Run one OpenVisio autonomy cycle.'
 const CYCLE_FAST = 'New chat activity in OpenVisio. Call poll_inbox once, then handle items in .mentions and .followUps ONLY (ignore .tasks/.claimable). Post AT MOST ONE reply per channel: if the same person sent several nudges (e.g. repeated @mentions or "status?"), answer them together in ONE post — never reply once per message. CRITICAL HONESTY RULE: your only tools are the openvisio-team chat/ticket tools. You CANNOT write code, read or clone a repo, or add entries to the API-testing/docs/sheets/flowchart tools — you have no tool for any of that. So NEVER say "On it" or "I will do it" for such work. If asked to do something you have no tool for, say plainly in one short message that you cannot do it yourself and what a human would need to do (or offer to file/track a ticket). Do not invent repo names or progress. Reply in 1-3 sentences, no summary; or react_message to dismiss. Then stop.'
@@ -27,41 +28,47 @@ const SESSION_IDLE_MS = 1200000
 export async function runWatch({ flags }) {
   const slug = flags.name ? slugify(String(flags.name)) : null
   const saved = slug ? readConfig(slug) : null
-  const host = stripSlash(flags.host || (saved && saved.host) || '')
-  const key = String(flags.key || (saved && saved.key) || '')
   const claude = String(flags.claude || onPath('claude') || 'claude')
   const mcpConfig = String(flags['mcp-config'] || (saved && saved.mcpConfig) || '')
   const workdir = flags.workdir === true ? process.cwd() : (flags.workdir ? String(flags.workdir) : '')
 
+  // Backend agents (connect --backend) drive autonomy over a real-time WS instead
+  // of REST-polling the frontend relay. Detected by the saved mode / a --ws flag.
+  const backendMode = (saved && saved.mode === 'backend') || !!flags.ws
+  if (backendMode) {
+    const wsUrl = stripSlash(flags.ws || (saved && saved.wsUrl) || '')
+    const apiKey = String(flags.key || (saved && saved.apiKey) || '')
+    const identifier = String(flags.id || (saved && saved.identifier) || '')
+    if (!wsUrl) fail('No WebSocket URL for that backend agent.\n  Re-run `openvisio-agent connect --backend <url> --key <k> --id <id> --ws <wss-url>`, or pass --ws.')
+    if (!apiKey || !identifier) fail('No saved backend credentials for that agent.\n  Run `openvisio-agent connect --backend …` first, or pass --key and --id.')
+    assertWebSocket(fail)
+    if (flags.install) return installService({ slug: slug || 'openvisio', claude, mcpConfig, workdir })
+    return loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir })
+  }
+
+  const host = stripSlash(flags.host || (saved && saved.host) || '')
+  const key = String(flags.key || (saved && saved.key) || '')
   if (!host || !key) fail('No saved connection for that agent.\n  Run `openvisio-agent connect <ovs_code> --host <url> --name <agent>` first, or pass --host and --key.')
 
-  if (flags.install) return installService({ slug: slug || 'openvisio', host, key, claude, mcpConfig, workdir })
+  if (flags.install) return installService({ slug: slug || 'openvisio', claude, mcpConfig, workdir })
 
   return loop({ host, key, claude, mcpConfig, workdir })
 }
 
-// ── the warm loop ────────────────────────────────────────────────────────────
-function loop({ host, key, claude, mcpConfig, workdir }) {
+// ── Claude Code warm-session cycle runner (shared by the REST + WS loops) ─────
+// One persistent stream-json session, poked with a prompt per cycle. Recycled
+// after MAX_TURNS or SESSION_IDLE_MS. Returns { runCycle, canCode }.
+function createCycleRunner({ claude, mcpConfig, workdir, log }) {
   const canCode = !!workdir
-  const fullPrompt = canCode ? CODE_FULL : CYCLE
-  const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
-
-  const seen = new Set()
-  let busy = false
-  let firstCheck = true
-  let lastNewAt = Date.now()
-
   let child = null
   let turnsThisSession = 0
   let sessionStartedAt = 0
   let resolveTurn = null
-
-  const log = (m) => process.stdout.write('[warm ' + new Date().toISOString() + '] ' + m + '\n')
-  const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
   const settleTurn = (o) => { const r = resolveTurn; resolveTurn = null; if (r) r(o) }
 
   function ensureSession() {
     if (child && !child.killed) return
+    if (!mcpConfig) { log('WARNING: no MCP config — the agent can react to events but has no tools to act. Re-connect with --mcp-url.') }
     const base = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--strict-mcp-config', '--mcp-config', mcpConfig]
     const args = canCode ? [...base, '--allowedTools', ...CODE_TOOLS, '--disallowedTools', ...DENY_TOOLS] : [...base, '--allowedTools', 'mcp__openvisio-team__*']
     const c = spawn(claude, args, { cwd: workdir || undefined, stdio: ['pipe', 'pipe', 'inherit'] })
@@ -100,6 +107,72 @@ function loop({ host, key, claude, mcpConfig, workdir }) {
     })
   }
 
+  return { runCycle, canCode }
+}
+
+// ── the backend WS loop ──────────────────────────────────────────────────────
+// Real-time: the backend pushes task:assigned / agent:mention over the WS; each
+// pushes ONE Claude cycle. Serialized (one cycle at a time) — events arriving
+// while busy are coalesced into a single follow-up cycle so a burst of mentions
+// doesn't stack up N sessions.
+function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir }) {
+  const log = (m) => process.stdout.write('[ws ' + new Date().toISOString() + '] ' + m + '\n')
+  const { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log })
+  const fullPrompt = canCode ? CODE_FULL : CYCLE
+  const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
+
+  let busy = false
+  let queued = null // 'full' | 'fast' — a cycle requested while one was running
+
+  async function drain(kind) {
+    if (busy) { queued = (queued === 'full' || kind === 'full') ? 'full' : 'fast'; return }
+    busy = true
+    try {
+      await runCycle(kind === 'full' ? fullPrompt : fastPrompt)
+    } finally {
+      busy = false
+      if (queued) { const next = queued; queued = null; void drain(next) }
+    }
+  }
+
+  function onEvent(k, d) {
+    if (k === 'task:assigned') {
+      const t = d && d.task
+      log('task:assigned ' + (t ? '#' + t.id + ' “' + (t.title || '') + '”' : ''))
+      void drain('full')
+    } else if (k === 'agent:mention') {
+      log('agent:mention in channel ' + (d && d.channel_id != null ? d.channel_id : '?'))
+      void drain('fast')
+    } else {
+      log('event ' + k)
+    }
+  }
+
+  log('up — backend WS watcher on ' + wsUrl + (canCode ? ' [code: ' + workdir + ']' : ''))
+  const handle = connectAgentWs({ wsUrl, apiKey, identifier, onEvent, log })
+
+  return new Promise(() => {
+    // Run until killed. Tidy up the socket on termination so a restarting
+    // service doesn't leak a half-open connection.
+    const bye = () => { try { handle.close() } catch { /* noop */ } process.exit(0) }
+    process.on('SIGTERM', bye)
+    process.on('SIGINT', bye)
+  })
+}
+
+// ── the warm loop ────────────────────────────────────────────────────────────
+function loop({ host, key, claude, mcpConfig, workdir }) {
+  const log = (m) => process.stdout.write('[warm ' + new Date().toISOString() + '] ' + m + '\n')
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+  const { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log })
+  const fullPrompt = canCode ? CODE_FULL : CYCLE
+  const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
+
+  const seen = new Set()
+  let busy = false
+  let firstCheck = true
+  let lastNewAt = Date.now()
+
   async function check() {
     const res = await fetch(host + '/api/agent/inbox', { headers: { authorization: 'Bearer ' + key } })
     if (!res.ok) return { items: [], paused: false }

package/src/ws.mjs

@@ -0,0 +1,106 @@
+// The backend agent WebSocket — a BYO agent's real-time event channel. Connects
+// to the org's API Gateway WS with the agent's api_key + identifier (NOT a JWT),
+// keeps the connection warm with keepalives, auto-reconnects with backoff, and
+// hands targeted dispatches (task:assigned / agent:mention) to a callback.
+//
+// Uses the built-in global WebSocket (Node >= 21). Zero dependencies — see
+// `assertWebSocket` for the version guard.
+//
+// Docs: agent-websocket.md
+//   wss://<api-gw>.execute-api.<region>.amazonaws.com/<stage>/?api_key=…&identifier=…
+//   client → { "type": "keepalive" }         (refreshes last_seen_at)
+//   server → { "k": "<kind>", "d": <payload> }
+
+import { stripSlash } from './lib.mjs'
+
+const KEEPALIVE_MS = 30_000 // refresh last_seen_at well within any idle timeout
+const BACKOFF_MIN_MS = 1_000
+const BACKOFF_MAX_MS = 30_000
+
+/** Bail early with a friendly message if the runtime has no global WebSocket. */
+export function assertWebSocket(fail) {
+  if (typeof globalThis.WebSocket === 'function') return
+  fail(
+    'This Node build has no global WebSocket, which the backend agent channel needs.\n' +
+    '  Upgrade to Node >= 21, or run Node 20 with the --experimental-websocket flag.',
+  )
+}
+
+/**
+ * Open a resilient agent WebSocket. Returns a handle with `.close()`.
+ *
+ * @param {object}   o
+ * @param {string}   o.wsUrl       API Gateway base (wss://…/<stage>), no query.
+ * @param {string}   o.apiKey      agent api_key (same as x-agent-api-key).
+ * @param {string}   o.identifier  agent identifier (same as x-agent-identifier).
+ * @param {(kind: string, payload: any) => void} o.onEvent  targeted dispatch.
+ * @param {(msg: string) => void} o.log
+ */
+export function connectAgentWs({ wsUrl, apiKey, identifier, onEvent, log }) {
+  const base = stripSlash(wsUrl)
+  const url = `${base}?api_key=${encodeURIComponent(apiKey)}&identifier=${encodeURIComponent(identifier)}`
+
+  let ws = null
+  let keepalive = null
+  let reconnectTimer = null
+  let backoff = BACKOFF_MIN_MS
+  let closed = false // set once .close() is called — stops reconnects
+
+  const clearKeepalive = () => { if (keepalive) { clearInterval(keepalive); keepalive = null } }
+
+  function scheduleReconnect() {
+    if (closed || reconnectTimer) return
+    const wait = backoff
+    backoff = Math.min(backoff * 2, BACKOFF_MAX_MS)
+    log(`disconnected — reconnecting in ${Math.round(wait / 1000)}s`)
+    reconnectTimer = setTimeout(() => { reconnectTimer = null; open() }, wait)
+  }
+
+  function open() {
+    if (closed) return
+    let sock
+    try { sock = new WebSocket(url) } catch (e) { log('connect failed: ' + (e && e.message ? e.message : e)); scheduleReconnect(); return }
+    ws = sock
+
+    sock.addEventListener('open', () => {
+      if (sock !== ws) return
+      backoff = BACKOFF_MIN_MS // healthy connection → reset the backoff ramp
+      log(`connected as @${identifier}`)
+      clearKeepalive()
+      keepalive = setInterval(() => {
+        try { sock.send(JSON.stringify({ type: 'keepalive' })) } catch { /* closing */ }
+      }, KEEPALIVE_MS)
+    })
+
+    sock.addEventListener('message', (ev) => {
+      if (sock !== ws) return
+      let msg
+      try { msg = JSON.parse(typeof ev.data === 'string' ? ev.data : String(ev.data)) } catch { return }
+      const kind = msg && msg.k
+      if (!kind || kind === 'keepalive:ack') return // keepalive round-trip, nothing to do
+      try { onEvent(kind, msg.d) } catch (e) { log('event handler error: ' + (e && e.message ? e.message : e)) }
+    })
+
+    const down = (why) => {
+      if (sock !== ws) return
+      clearKeepalive()
+      ws = null
+      log(why)
+      scheduleReconnect()
+    }
+    // $connect 401 (bad/inactive credentials) surfaces as an immediate close.
+    sock.addEventListener('close', (e) => down(`socket closed (code ${e && e.code != null ? e.code : '?'})`))
+    sock.addEventListener('error', () => down('socket error'))
+  }
+
+  open()
+
+  return {
+    close() {
+      closed = true
+      clearKeepalive()
+      if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null }
+      if (ws) { try { ws.close() } catch { /* already gone */ } ws = null }
+    },
+  }
+}