openvisio-agent 0.3.1 → 0.3.3

package/bin/cli.mjs

@@ -13,8 +13,8 @@ import { spawnSync } from 'node:child_process'
 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, chmodSafe, OV_DIR, fail, ok, info } from '../src/lib.mjs'
-import { runWatch } from '../src/watch.mjs'
+import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, writeJson, mcpConfigPath, configPath, chmodSafe, onPath, OV_DIR, fail, ok, info } from '../src/lib.mjs'
+import { runWatch, installService } from '../src/watch.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const VERSION = (() => { try { return JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version } catch { return '0.0.0' } })()
@@ -26,7 +26,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 watch   --name <agent> [--install] [--workdir <repo>] [--debug]
   openvisio-agent --help | --version
 
 connect
@@ -35,14 +35,19 @@ connect
 
 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.
+  verifies the api-key + identifier against the org backend, saves the credentials
+  (~/.openvisio/<agent>.json + a sourceable <agent>.env), and — when --ws is given —
+  installs openvisio-agent globally and sets up an ALWAYS-ON background listener
+  (launchd/systemd) that auto-starts on login, so @mentions/assignments are caught
+  even with no terminal open. 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.
+    --workdir <repo> the always-on listener may do real coding on a branch there.
+    --no-service     skip the background service — just save config + print the
+                     watch commands to run yourself.
 
 watch
   Runs the event-driven autonomy loop (reply to mentions, pick up tickets). Add
@@ -64,6 +69,15 @@ function mcpReplace(claude, addArgs) {
   spawnSync(claude, ['mcp', 'add', '--scope', 'user', ...addArgs], { stdio: 'ignore' })
 }
 
+// The persistent `openvisio-agent` command must exist for `watch` (and the
+// background service) to work — an `npx` connect leaves nothing installed. Make
+// the global install part of setup.
+function ensureAgentInstalled() {
+  if (onPath('openvisio-agent')) return
+  info('Installing openvisio-agent globally (so `watch` and the always-on service have a stable command)…')
+  spawnSync('npm', ['i', '-g', 'openvisio-agent@latest'], { stdio: 'inherit', shell: process.platform === 'win32' })
+}
+
 async function runConnect({ positional, flags }) {
   if (flags.backend) return runConnectBackend({ positional, flags })
   const token = positional[0] || flags.token
@@ -164,18 +178,31 @@ async function runConnectBackend({ flags }) {
   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) {
+  if (!wsUrl) {
+    info()
+    info('Tip: pass --ws <wss-url> and --mcp-url <url> to enable real-time autonomy —')
+    info('     the agent then reacts to task:assigned / agent:mention, always-on.')
+    return
+  }
+
+  // Real-time autonomy IS the point of a backend agent: install the command and a
+  // background service that auto-starts on login, so a mention is always caught —
+  // no terminal left open, survives reboot. Opt out with --no-service.
+  const workdir = flags.workdir === true ? process.cwd() : (flags.workdir ? String(flags.workdir) : '')
+  if (flags['no-service'] || process.platform === 'win32') {
+    ensureAgentInstalled()
     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.)')
+    if (process.platform === 'win32') info('Background auto-start isn\'t supported on Windows yet — run the listener yourself:')
+    else info('Real-time autonomy is ready. Start the always-on listener:')
+    info(`  openvisio-agent watch --name ${slug}             # run now, in this terminal`)
+    info(`  openvisio-agent watch --name ${slug} --install   # background, auto-start on login`)
   } 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).')
+    info('Setting up the always-on autonomy listener (auto-starts on login, survives reboot)…')
+    installService({ slug, workdir })
+    ok('Your agent is now live — it will catch @mentions and assignments even with no terminal open.')
   }
+  if (!mcpUrl) info('Note: no --mcp-url was given, so the agent hears events but has no tools to reply. Reconnect with --mcp-url to fix.')
 }
 
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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

@@ -24,6 +24,10 @@ const SLOW = 6000
 const IDLE_AFTER = 60000
 const MAX_TURNS = 15
 const SESSION_IDLE_MS = 1200000
+// A single cycle must finish within this or it's abandoned — otherwise a hung
+// cycle (e.g. an MCP tool stalling on a down bridge) would leave `busy` stuck
+// true forever and silently queue every later mention.
+const MAX_CYCLE_MS = 240000
 
 export async function runWatch({ flags }) {
   const slug = flags.name ? slugify(String(flags.name)) : null
@@ -43,7 +47,7 @@ export async function runWatch({ flags }) {
     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 })
+    return loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir, debug: !!flags.debug })
   }
 
   const host = stripSlash(flags.host || (saved && saved.host) || '')
@@ -52,19 +56,36 @@ export async function runWatch({ flags }) {
 
   if (flags.install) return installService({ slug: slug || 'openvisio', claude, mcpConfig, workdir })
 
-  return loop({ host, key, claude, mcpConfig, workdir })
+  return loop({ host, key, claude, mcpConfig, workdir, debug: !!flags.debug })
 }
 
 // ── 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 }) {
+function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
   const canCode = !!workdir
   let child = null
   let turnsThisSession = 0
   let sessionStartedAt = 0
   let resolveTurn = null
-  const settleTurn = (o) => { const r = resolveTurn; resolveTurn = null; if (r) r(o) }
+  let cycleTimer = null
+  const clearCycleTimer = () => { if (cycleTimer) { clearTimeout(cycleTimer); cycleTimer = null } }
+  const settleTurn = (o) => { clearCycleTimer(); const r = resolveTurn; resolveTurn = null; if (r) r(o) }
+
+  // --debug: surface what the cycle actually does (tool calls, tool errors, text)
+  // so a silent/hung cycle is diagnosable.
+  function logEvent(o) {
+    if (o.type === 'assistant' && o.message && Array.isArray(o.message.content)) {
+      for (const b of o.message.content) {
+        if (b.type === 'tool_use') log('  → tool ' + b.name)
+        else if (b.type === 'text' && b.text && b.text.trim()) log('  · ' + b.text.trim().replace(/\s+/g, ' ').slice(0, 140))
+      }
+    } else if (o.type === 'user' && o.message && Array.isArray(o.message.content)) {
+      for (const b of o.message.content) if (b.type === 'tool_result' && b.is_error) log('  ✗ tool error: ' + JSON.stringify(b.content).slice(0, 180))
+    } else if (o.type === 'system' && o.subtype === 'init') {
+      log('  session init — mcp servers: ' + JSON.stringify(o.mcp_servers || []).slice(0, 200))
+    }
+  }
 
   function ensureSession() {
     if (child && !child.killed) return
@@ -84,7 +105,8 @@ function createCycleRunner({ claude, mcpConfig, workdir, log }) {
         const line = localBuf.slice(0, i); localBuf = localBuf.slice(i + 1)
         if (!line.trim()) continue
         let o; try { o = JSON.parse(line) } catch { continue }
-        if (o.type === 'result') { log('cycle done (' + (o.subtype || 'ok') + ')'); settleTurn(o) }
+        if (debug) logEvent(o)
+        if (o.type === 'result') { log('cycle done (' + (o.subtype || 'ok') + (o.is_error ? ' · ERROR' : '') + ')'); settleTurn(o) }
       }
     })
     c.on('exit', (code) => { if (c !== child) { log('old session exited ' + code); return } log('session exited ' + code); child = null; settleTurn({ type: 'result', subtype: 'exit' }) })
@@ -102,6 +124,15 @@ function createCycleRunner({ claude, mcpConfig, workdir, log }) {
       ensureSession()
       turnsThisSession++
       resolveTurn = resolve
+      // Backstop: abandon a cycle that never returns a result so `busy` is released
+      // and queued mentions can proceed.
+      clearCycleTimer()
+      cycleTimer = setTimeout(() => {
+        log('cycle TIMED OUT after ' + Math.round(MAX_CYCLE_MS / 1000) + 's — killing the session so the queue can proceed')
+        try { child && child.kill() } catch { /* already gone */ }
+        child = null
+        settleTurn({ type: 'result', subtype: 'timeout' })
+      }, MAX_CYCLE_MS)
       try { child.stdin.write(JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } }) + '\n') }
       catch { settleTurn({ type: 'result', subtype: 'write-failed' }) }
     })
@@ -115,9 +146,9 @@ function createCycleRunner({ claude, mcpConfig, workdir, log }) {
 // 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 }) {
+function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir, debug }) {
   const log = (m) => process.stdout.write('[ws ' + new Date().toISOString() + '] ' + m + '\n')
-  const { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log })
+  const { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log, debug })
   const fullPrompt = canCode ? CODE_FULL : CYCLE
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
 
@@ -125,8 +156,9 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir }
   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 }
+    if (busy) { queued = (queued === 'full' || kind === 'full') ? 'full' : 'fast'; log('busy — queued a ' + kind + ' follow-up cycle'); return }
     busy = true
+    log('running ' + kind + ' cycle…')
     try {
       await runCycle(kind === 'full' ? fullPrompt : fastPrompt)
     } finally {
@@ -161,10 +193,10 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir }
 }
 
 // ── the warm loop ────────────────────────────────────────────────────────────
-function loop({ host, key, claude, mcpConfig, workdir }) {
+function loop({ host, key, claude, mcpConfig, workdir, debug }) {
   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 { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log, debug })
   const fullPrompt = canCode ? CODE_FULL : CYCLE
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
 
@@ -234,7 +266,7 @@ function loop({ host, key, claude, mcpConfig, workdir }) {
 }
 
 // ── background service install (launchd / systemd) ───────────────────────────
-function installService({ slug, workdir }) {
+export function installService({ slug, workdir }) {
   const binPath = onPath('openvisio-agent')
   if (!binPath) {
     info('Installing openvisio-agent globally so the background service has a stable path…')