openvisio-agent 0.11.1 → 0.13.0

package/README.md

@@ -56,18 +56,23 @@ Then `watch --name ada` auto-detects the backend agent and runs a WebSocket loop
 
 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.
 
+Backend/BYO watchers reconcile immediately whenever the process starts or the WebSocket connects. A direct MCP session checks both `poll_inbox` and `get_marching_orders`, covering unanswered mentions, follow-ups, and assigned tasks missed while offline. The same zero-model check runs every five minutes as a safety net; a model starts only when pending work exists.
+
 Routine messages, triage, introductions, catch-up checks, and ticket movement use a lightweight model by default. Claude uses Haiku and Codex uses `gpt-5.6-luna`. Requests that clearly require repository work route to the coding model: Sonnet for Claude and `gpt-5.6-sol` for Codex. Override either lane with `--chat-model` and `--model`.
 
 ```bash
 openvisio-agent watch --name ada                 # run in this terminal
 openvisio-agent watch --name ada --install       # run in the background, start at login
 openvisio-agent watch --name ada --workdir ~/repo  # allow REAL work on a git branch
+openvisio-agent stop --name ada                  # stop service + every ada watcher
 ```
 
 With `--workdir`, the agent gets file + Bash tools scoped to that repo and works on a branch. Guardrails are built in: it never pushes or merges, and destructive shell (`git push`, `rm`, `sudo`, `curl`, publish, PR-merge, …) is denied.
 
 `--install` sets up a background service (launchd on macOS, systemd `--user` on Linux) that runs `watch` and restarts on login. Logs go to `~/.openvisio/<agent>.log` (macOS) or `journalctl --user -u openvisio-<agent>` (Linux).
 
+Do not chase auto-changing watcher PIDs. `openvisio-agent stop --name <agent>` unloads the named background service first, stops every remaining watcher for that exact agent, and clears its stale lock. Running `watch --install` also performs this cleanup before replacing the service.
+
 ## Security
 
 - **No opaque script.** You run a named, versioned npm package you can read here and on [npmjs.com](https://www.npmjs.com/package/openvisio-agent).

package/bin/cli.mjs

@@ -14,7 +14,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, ensureCodex, writeJson, mcpConfigPath, configPath, chmodSafe, onPath, OV_DIR, fail, ok, info } from '../src/lib.mjs'
-import { runWatch, installService } from '../src/watch.mjs'
+import { runWatch, installService, stopWatchers } 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' } })()
@@ -27,6 +27,7 @@ Usage:
   openvisio-agent connect <ovs_code> --host <url> [--name "<agent>"] [--mcp-url <url>] [--agent claude|codex|opencode]
   openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>] [--agent claude|codex|opencode]
   openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--model <m>] [--chat-model <m>] [--debug]
+  openvisio-agent stop    --name <agent>
   openvisio-agent --help | --version
 
 connect
@@ -72,6 +73,11 @@ watch
   setup needed. Use --workspace <dir> to relocate it (e.g. an existing clones folder),
   --chat-only to disable code work, and --install to run in the background on login.
 
+stop
+  Stops the named agent's launchd/systemd service first, then terminates every
+  remaining watcher with that exact --name and clears its stale lock. Use this
+  instead of killing changing PIDs: openvisio-agent stop --name Alex
+
 Docs: https://www.npmjs.com/package/openvisio-agent`
 
 // Register the `openvisio-team` MCP at USER (global) scope so it's available in
@@ -280,6 +286,11 @@ async function main() {
   const rest = parseFlags(argv.slice(1))
   if (cmd === 'connect') return runConnect(rest)
   if (cmd === 'watch') return runWatch(rest)
+  if (cmd === 'stop') {
+    const name = String(rest.flags.name || rest.positional[0] || '')
+    if (!name) fail('Missing agent name.\n  Usage: openvisio-agent stop --name <agent>')
+    return stopWatchers({ slug: slugify(name) })
+  }
   fail(`Unknown command "${cmd}".\n\n${HELP}`)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team — MCP tools + optional autonomy — in one command.",
   "type": "module",
   "bin": {

package/src/watch.mjs

@@ -229,18 +229,13 @@ export async function runWatch({ flags }) {
     const lock = acquireSingleInstance(slug || 'openvisio')
     if (lock.conflict) {
       const watcherName = slug || 'openvisio'
-      const stop = process.platform === 'darwin'
-        ? `launchctl unload ~/Library/LaunchAgents/io.openvisio.${watcherName}.plist`
-        : process.platform === 'win32'
-          ? 'Stop the existing openvisio-agent process in Task Manager.'
-          : `systemctl --user stop openvisio-${watcherName}.service`
       const logs = process.platform === 'darwin'
         ? `tail -f ~/.openvisio/${watcherName}.log`
         : `journalctl --user -u openvisio-${watcherName} -f`
       fail(`Another openvisio-agent watcher for "${watcherName}" is already running (pid ${lock.conflict}).\n` +
         `  Two watchers for the same agent BOTH reply to every mention — that is what causes duplicate/contradicting messages.\n` +
         `  This is usually the auto-restarting background service; killing its PID only makes it restart.\n` +
-        `  To run in this terminal instead, stop the service first:\n    ${stop}\n` +
+        `  Stop the service and every watcher for this agent with:\n    openvisio-agent stop --name ${watcherName}\n` +
         `  Or keep the service and inspect its log:\n    ${logs}\n` +
         `  Refusing to start a second watcher.`)
     }
@@ -555,6 +550,85 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   // hoping poll_inbox re-surfaces the same item. Accumulated across coalesced
   // events and drained into the next cycle's prompt.
   const pending = []
+  let backlogProbeBusy = false
+  let lastTaskSignature = ''
+  let lastTaskTriggeredAt = 0
+  let mcpSessionId = ''
+  let mcpRpcId = 0
+
+  const mcpPayload = async (res) => {
+    const body = await res.text()
+    const data = body.split(/\r?\n/).filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trim()).pop()
+    return JSON.parse(data || body || '{}')
+  }
+  const mcpPost = async (message, withSession = true) => {
+    const res = await fetch(mcpUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+        'x-agent-api-key': apiKey,
+        'x-agent-identifier': identifier,
+        ...(withSession && mcpSessionId ? { 'mcp-session-id': mcpSessionId } : {}),
+      },
+      body: JSON.stringify(message),
+    })
+    return res
+  }
+  const ensureMcpSession = async () => {
+    if (mcpSessionId) return
+    const res = await mcpPost({ jsonrpc: '2.0', id: ++mcpRpcId, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'openvisio-agent', version: '0.13.0' } } }, false)
+    if (!res.ok) throw new Error('MCP initialize HTTP ' + res.status)
+    await mcpPayload(res)
+    mcpSessionId = res.headers.get('mcp-session-id') || ''
+    if (!mcpSessionId) throw new Error('MCP initialize returned no session id')
+    const ready = await mcpPost({ jsonrpc: '2.0', method: 'notifications/initialized' })
+    if (!ready.ok) throw new Error('MCP initialized HTTP ' + ready.status)
+  }
+  const callMcpTool = async (name, args = {}, retried = false) => {
+    await ensureMcpSession()
+    const res = await mcpPost({ jsonrpc: '2.0', id: ++mcpRpcId, method: 'tools/call', params: { name, arguments: { ...args, agent_api_key: apiKey, agent_identifier: identifier } } })
+    if (!res.ok) {
+      if (!retried && (res.status === 400 || res.status === 404)) { mcpSessionId = ''; return callMcpTool(name, args, true) }
+      throw new Error(`MCP ${name} HTTP ${res.status}`)
+    }
+    const payload = await mcpPayload(res)
+    if (payload.error) throw new Error(`MCP ${name}: ${payload.error.message || 'tool error'}`)
+    return JSON.stringify(payload.result ?? payload)
+  }
+
+  // Reconcile everything that may have arrived while disconnected. This spends no
+  // model tokens unless the tools actually report pending work.
+  const reconcileBacklog = async () => {
+    if (!mcpUrl || backlogProbeBusy || busy) return
+    backlogProbeBusy = true
+    try {
+      const orders = await callMcpTool('get_marching_orders')
+      const inbox = await callMcpTool('poll_inbox')
+      const normalized = String(orders).replace(/\\"/g, '"').replace(/\s+/g, ' ').trim()
+      const empty = !normalized || /\b(?:no|zero)\s+(?:open\s+|assigned\s+|pending\s+)?tasks?\b/i.test(normalized) || /"(?:tasks|assigned|marching_orders)"\s*:\s*\[\s*\]/i.test(normalized)
+      if (empty) lastTaskSignature = ''
+      else if (/\b(?:task|ticket|title|status|assigned)\b/i.test(normalized)) {
+        const signature = normalized.slice(0, 1200)
+        const retryDue = Date.now() - lastTaskTriggeredAt > 30 * 60 * 1000
+        if (signature !== lastTaskSignature || retryDue) {
+          lastTaskSignature = signature
+          lastTaskTriggeredAt = Date.now()
+          log('backlog reconciliation found pending tasks -> coding cycle')
+          void drain('full', 'Backlog reconciliation found one or more tasks in get_marching_orders. Call get_marching_orders now, select every open task assigned to YOU, and execute the oldest/highest-priority one immediately. Do not merely acknowledge it. Move it to the active column, complete the repository work, verify it, open the PR, move the ticket to done when appropriate, and report evidence. Ignore tasks assigned to anyone else.')
+        }
+      }
+      const inboxText = String(inbox).replace(/\\"/g, '"').replace(/\s+/g, ' ').trim()
+      const hasInbox = /"(?:mentions|messages|follow_?ups|items)"\s*:\s*\[\s*\{/i.test(inboxText) || /\b(?:pending|unanswered|new)\s+(?:mention|message|follow.?up)/i.test(inboxText)
+      if (hasInbox) {
+        log('backlog reconciliation found inbox activity -> reply cycle')
+        void drain('fast', 'Backlog reconciliation found pending inbox activity. Call poll_inbox now and handle every unanswered mention or follow-up directed to YOU. Do not respond to other agents\' messages and do not duplicate a reply already present.')
+      }
+    } catch (e) {
+      mcpSessionId = ''
+      log('backlog reconciliation failed: ' + (e && e.message ? e.message : e))
+    } finally { backlogProbeBusy = false }
+  }
 
   // Higher rank wins when coalescing cycles requested while one is running.
   const RANK = { fast: 0, intro: 1, coord: 2, sweep: 2, full: 3 }
@@ -644,12 +718,13 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
     // fanned out org-wide. Catch both, keep only agent-assigned tasks, and let the
     // cycle confirm ownership via get_marching_orders before acting.
     if (k === 'task:created' || k === 'task:updated') {
-      const t = raw.task && typeof raw.task === 'object' ? raw.task : {}
-      const agentId = t.agent_id != null ? t.agent_id : (t.agentId != null ? t.agentId : null)
+      const envelope = raw.data && typeof raw.data === 'object' ? raw.data : raw
+      const t = envelope.task && typeof envelope.task === 'object' ? envelope.task : envelope
+      const ag = (t.agent && typeof t.agent === 'object') ? t.agent : (t.assigned_agent && typeof t.assigned_agent === 'object') ? t.assigned_agent : null
+      const agentId = t.agent_id ?? t.agentId ?? t.assigned_agent_id ?? t.assignedAgentId ?? t.assignee_agent_id ?? t.assigneeAgentId ?? ag?.id ?? ag?.agent_id ?? null
       if (agentId == null) return // not assigned to an agent — ignore
       // If the payload carries the agent's identifier, filter precisely to US and skip
       // other agents' tasks entirely; otherwise let get_marching_orders confirm.
-      const ag = (t.agent && typeof t.agent === 'object') ? t.agent : null
       const agIdent = ag && (ag.identifier || ag.slug) ? String(ag.identifier || ag.slug) : null
       if (agIdent != null && agIdent !== identifier) return
       const key = `${t.id}:${agentId}`
@@ -724,10 +799,10 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   // so anything assigned while the agent was offline — tasks especially — is still
   // picked up even though we don't hot-poll.
   log('up — backend WS watcher on ' + wsUrl + (canCode ? ' [code: ' + workdir + ']' : ''))
-  handle = connectAgentWs({ wsUrl, apiKey, identifier, onEvent, log })
+  handle = connectAgentWs({ wsUrl, apiKey, identifier, onEvent, onConnect: () => { setTimeout(() => void reconcileBacklog(), 250) }, log })
 
   const DAY_MS = 24 * 60 * 60 * 1000
-  let introTimer = null, sweepStartTimer = null, sweepTimer = null
+  let introTimer = null, sweepStartTimer = null, sweepTimer = null, taskProbeStartTimer = null, taskProbeTimer = null
   if (mcpConfig || mcpUrl) {
     // Workspace ethics: a one-time hello the FIRST time this agent ever connects.
     const introMarker = join(OV_DIR, 'intro-' + slugify(identifier) + '.done')
@@ -745,6 +820,10 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
       log('startup catch-up sweep skipped (ran within the last 6h)')
     }
     sweepTimer = setInterval(() => { log('daily catch-up sweep'); void drain('sweep', SWEEP) }, DAY_MS)
+    // Cheap reliability net: no model runs unless the MCP result actually contains
+    // assigned work. This also catches assignments created while the socket was down.
+    taskProbeStartTimer = setTimeout(() => void reconcileBacklog(), 3_000)
+    taskProbeTimer = setInterval(() => void reconcileBacklog(), 5 * 60 * 1000)
   } else {
     log('no MCP config — skipping intro + daily sweep (agent has no tools to post/act)')
   }
@@ -756,6 +835,8 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
       if (introTimer) clearTimeout(introTimer)
       if (sweepStartTimer) clearTimeout(sweepStartTimer)
       if (sweepTimer) clearInterval(sweepTimer)
+      if (taskProbeStartTimer) clearTimeout(taskProbeStartTimer)
+      if (taskProbeTimer) clearInterval(taskProbeTimer)
       try { handle && handle.close() } catch { /* noop */ }
       process.exit(0)
     }
@@ -871,7 +952,57 @@ function loop({ host, key, slug, claude, agent, mcpConfig, mcpUrl, workdir, mode
 }
 
 // ── background service install (launchd / systemd) ───────────────────────────
+/** Stop the auto-restarting service first, then every orphaned watcher whose
+ *  --name resolves to this exact slug. Never use a broad pkill pattern. */
+export function stopWatchers({ slug, quiet = false }) {
+  const key = slugify(slug || 'openvisio')
+  let serviceStopped = false
+
+  if (process.platform === 'darwin') {
+    const plist = join(homedir(), 'Library', 'LaunchAgents', `io.openvisio.${key}.plist`)
+    if (existsSync(plist)) {
+      const r = spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' })
+      serviceStopped = r.status === 0
+    }
+  } else if (process.platform !== 'win32') {
+    const r = spawnSync('systemctl', ['--user', 'stop', `openvisio-${key}.service`], { stdio: 'ignore' })
+    serviceStopped = r.status === 0
+  }
+
+  const watcherPids = () => {
+    if (process.platform === 'win32') return []
+    const r = spawnSync('ps', ['-axo', 'pid=,command='], { encoding: 'utf8' })
+    if (r.status !== 0) return []
+    const out = []
+    for (const line of String(r.stdout || '').split(/\r?\n/)) {
+      const m = /^\s*(\d+)\s+(.+)$/.exec(line)
+      if (!m) continue
+      const pid = Number(m[1]); const command = m[2]
+      if (pid === process.pid || !/\bopenvisio-agent\b/.test(command) || !/\bwatch\b/.test(command)) continue
+      const name = /(?:^|\s)--name(?:=|\s+)["']?([^"'\s]+)/.exec(command)?.[1]
+      if (name && slugify(name) === key) out.push(pid)
+    }
+    return out
+  }
+
+  const found = watcherPids()
+  for (const pid of found) { try { process.kill(pid, 'SIGTERM') } catch { /* already stopped */ } }
+  if (found.length) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 600)
+  const stubborn = watcherPids()
+  for (const pid of stubborn) { try { process.kill(pid, 'SIGKILL') } catch { /* already stopped */ } }
+  if (stubborn.length) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 150)
+
+  const remaining = watcherPids()
+  if (remaining.length) fail(`Could not stop watcher${remaining.length === 1 ? '' : 's'} for "${key}": ${remaining.join(', ')}`)
+  try { unlinkSync(join(OV_DIR, `watch-${key}.lock`)) } catch { /* absent */ }
+  if (!quiet) ok(`Stopped ${found.length} watcher process${found.length === 1 ? '' : 'es'} for "${key}"${serviceStopped ? ' and disabled its background service' : ''}.`)
+  return { stopped: found.length, serviceStopped }
+}
+
 export function installService({ slug, workdir }) {
+  // Replacing a service must also remove manually-started watchers. Otherwise the
+  // new KeepAlive process repeatedly spawns, sees their lock, exits, and respawns.
+  stopWatchers({ slug, quiet: true })
   const binPath = onPath('openvisio-agent')
   if (!binPath || binPath.includes('/_npx/')) {
     info('Installing openvisio-agent globally so the background service has a stable path…')

package/src/ws.mjs

@@ -36,7 +36,7 @@ export function assertWebSocket(fail) {
  * @param {(kind: string, payload: any) => void} o.onEvent  targeted dispatch.
  * @param {(msg: string) => void} o.log
  */
-export function connectAgentWs({ wsUrl, apiKey, identifier, onEvent, log }) {
+export function connectAgentWs({ wsUrl, apiKey, identifier, onEvent, onConnect, log }) {
   const base = stripSlash(wsUrl)
   const url = `${base}?api_key=${encodeURIComponent(apiKey)}&identifier=${encodeURIComponent(identifier)}`
 
@@ -66,6 +66,7 @@ export function connectAgentWs({ wsUrl, apiKey, identifier, onEvent, log }) {
       if (sock !== ws) return
       backoff = BACKOFF_MIN_MS // healthy connection → reset the backoff ramp
       log(`connected as @${identifier}`)
+      try { onConnect && onConnect() } catch { /* reconciliation is best-effort */ }
       clearKeepalive()
       keepalive = setInterval(() => {
         try { sock.send(JSON.stringify({ type: 'keepalive' })) } catch { /* closing */ }