openvisio-agent 0.3.2 → 0.3.4

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.4",
   "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,34 +146,61 @@ 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
 
   let busy = false
   let queued = null // 'full' | 'fast' — a cycle requested while one was running
+  // Context lines from the events themselves (the WS payload already carries the
+  // channel + message / task), so the agent acts on THEM directly instead of
+  // hoping poll_inbox re-surfaces the same item. Accumulated across coalesced
+  // events and drained into the next cycle's prompt.
+  const pending = []
 
-  async function drain(kind) {
-    if (busy) { queued = (queued === 'full' || kind === 'full') ? 'full' : 'fast'; return }
+  async function drain(kind, context) {
+    if (context) pending.push(context)
+    if (busy) { queued = (queued === 'full' || kind === 'full') ? 'full' : 'fast'; log('busy — queued a ' + kind + ' follow-up cycle'); return }
     busy = true
+    const ctx = pending.splice(0) // take everything accumulated so far
+    const base = kind === 'full' ? fullPrompt : fastPrompt
+    const prompt = ctx.length ? ctx.join('\n') + '\n\n' + base : base
+    log('running ' + kind + ' cycle…' + (ctx.length ? ' (' + ctx.length + ' event' + (ctx.length === 1 ? '' : 's') + ')' : ''))
     try {
-      await runCycle(kind === 'full' ? fullPrompt : fastPrompt)
+      await runCycle(prompt)
     } finally {
       busy = false
-      if (queued) { const next = queued; queued = null; void drain(next) }
+      if (queued || pending.length) { const next = queued || 'fast'; queued = null; void drain(next) }
     }
   }
 
+  // Distill an event's WS payload into a directive the model can act on without
+  // any extra lookup.
+  const senderName = (m) => {
+    const s = m && (m.sender || m.user || m.author)
+    if (!s) return ''
+    return (`${s.first_name || ''} ${s.last_name || ''}`.trim() || s.name || s.email || '')
+  }
+
   function onEvent(k, d) {
+    const raw = d && typeof d === 'object' ? d : {}
     if (k === 'task:assigned') {
-      const t = d && d.task
-      log('task:assigned ' + (t ? '#' + t.id + ' “' + (t.title || '') + '”' : ''))
-      void drain('full')
+      const t = raw.task || {}
+      log('task:assigned ' + (t.id != null ? '#' + t.id + ' “' + (t.title || '') + '”' : ''))
+      const desc = t.description ? ' — ' + String(t.description).replace(/\s+/g, ' ').slice(0, 400) : ''
+      void drain('full', t.id != null ? `You were ASSIGNED task #${t.id}: "${t.title || ''}"${desc}. Handle it, then comment_ticket with a short summary.` : undefined)
     } else if (k === 'agent:mention') {
-      log('agent:mention in channel ' + (d && d.channel_id != null ? d.channel_id : '?'))
-      void drain('fast')
+      const cid = raw.channel_id != null ? raw.channel_id : (raw.channelId != null ? raw.channelId : null)
+      const msg = raw.message && typeof raw.message === 'object' ? raw.message : {}
+      const text = String(msg.content || msg.body || msg.text || '').replace(/\s+/g, ' ').slice(0, 600)
+      const who = senderName(msg)
+      log('agent:mention in channel ' + (cid != null ? cid : '?'))
+      const ctx = cid != null
+        ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by ${who}` : ''}: "${text}". Reply DIRECTLY in that channel now with post_message (channel_id ${cid}), 1-3 sentences addressing it. Do NOT depend on poll_inbox to find it — you already have it here. You MAY still call poll_inbox to catch OTHER pending items, but you MUST answer this one.`
+        : undefined
+      void drain('fast', ctx)
     } else {
       log('event ' + k)
     }
@@ -161,10 +219,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