openvisio-agent 0.3.2 → 0.3.3

package/bin/cli.mjs

@@ -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

package/package.json

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