openvisio-agent 0.4.0 → 0.5.0

package/package.json

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

@@ -5,7 +5,7 @@
 // than written to disk from a pasted heredoc.
 
 import { spawn, spawnSync } from 'node:child_process'
-import { writeFileSync, mkdirSync } from 'node:fs'
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
 import { OV_DIR, DEFAULT_WORKSPACE, readConfig, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
@@ -48,6 +48,7 @@ const CODE_CHARTER = [
 
 const CODE_FULL = CODE_CHARTER + '\n\n' + [
   'THIS CYCLE: call get_marching_orders and poll_inbox to see assigned tickets + mentions, then act on them.',
+  'ACKNOWLEDGE FIRST: for a task assigned to you, post a one-line comment_ticket ("On it — picking this up now") BEFORE you start, so the team sees you have it. Then do the work and report when done.',
   'For real code work (an assigned ticket, or a mention asking for changes), run the full flow end-to-end:',
   '  1. GET THE CODE: locate the target repo under your workspace root. If it\'s already a subfolder, cd in and `git pull`; if it isn\'t cloned yet, clone it into the workspace (gh repo clone <org>/<repo>, or git clone <url>) and cd in. Do this yourself — never ask the user for a path.',
   '  2. BRANCH: git checkout -B agent/<short-task-slug>. NEVER work on, commit to, or push main/master.',
@@ -65,6 +66,23 @@ const CODE_FAST = CODE_CHARTER + '\n\n' + [
   'Do NOT promise and stop — finish and report in THIS cycle. Reply 1-3 sentences, no summary. Then stop.',
 ].join('\n')
 
+// ── Workspace-ethics cycles (both chat-only + code agents) ───────────────────
+// INTRO: a one-time hello when the agent first joins a workspace. SWEEP: a daily
+// (and on-startup) catch-up so nothing assigned while the agent was offline is
+// missed — TASKS especially.
+const INTRO = [
+  'You have just JOINED this OpenVisio workspace (your first connection). Workspace etiquette: introduce yourself so the team knows you are here and reachable.',
+  'Find the most general channel — call poll_inbox (or list channels) and pick the "general"/main one — then post_message there ONCE: give your name, say you are an AI teammate who picks up tasks assigned to you and answers @mentions, and invite people to mention you. 1-2 sentences, warm and professional.',
+  'Post it EXACTLY ONCE, then stop. Do NOT do any other work this cycle.',
+].join('\n')
+const SWEEP = [
+  'DAILY CATCH-UP — you may have missed items while offline. Prioritize TASKS.',
+  'Call get_marching_orders AND poll_inbox, then:',
+  '  1. For every task assigned to you that you have NOT started: post a brief comment_ticket acknowledgement first ("Catching up — picking this up now"), then do the work end-to-end and report (branch/PR + a short channel note).',
+  '  2. Answer any @mentions or thread follow-ups you missed — at most one reply per channel.',
+  'If there is genuinely nothing outstanding, STOP silently — do NOT post a "nothing to do" message.',
+].join('\n')
+
 // Bash covers git/gh/clone/tests; the deny list is where the guardrails live.
 const CODE_TOOLS = ['Read', 'Grep', 'Glob', 'Edit', 'Write', 'MultiEdit', 'TodoWrite', 'Bash', 'mcp__openvisio-team__*']
 // Push + PR creation ARE allowed (agents raise PRs), but main/master, force-pushes,
@@ -130,7 +148,7 @@ export async function runWatch({ flags }) {
 
   if (flags.install) return installService({ slug: slug || 'openvisio', claude, mcpConfig, workdir })
 
-  return loop({ host, key, claude, mcpConfig, workdir, debug: !!flags.debug })
+  return loop({ host, key, slug: slug || 'openvisio', claude, mcpConfig, workdir, debug: !!flags.debug })
 }
 
 // ── Claude Code warm-session cycle runner (shared by the REST + WS loops) ─────
@@ -219,10 +237,10 @@ function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
 }
 
 // ── 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.
+// Real-time: the backend pushes task:created/task:updated (assignments) + 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 doesn't
+// stack up N sessions. Plus a one-time intro on first connect and a daily catch-up sweep.
 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, debug })
@@ -230,8 +248,12 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
 
   let busy = false
-  let queued = null // 'full' | 'fast' — a cycle requested while one was running
+  let queued = null // 'full' | 'fast' | 'sweep' | 'intro' — a cycle requested while one was running
   let handle = null
+  // Tasks we've already reacted to (keyed task-id:agent — so a REASSIGNMENT to a
+  // different agent re-triggers), so a noisy stream of task:updated events doesn't
+  // re-acknowledge the same assignment.
+  const seenTasks = new Set()
   // 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
@@ -243,13 +265,16 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
   // Hand them to the model up front so it never shells around hunting for them.
   const credNote = `AUTH: the openvisio-team (mcp__openvisio-team__*) tools REQUIRE two arguments on EVERY call — agent_identifier: "${identifier}" and agent_api_key: "${apiKey}". Include BOTH on every openvisio-team tool call (post_message, poll_inbox, react_message, comment_ticket, …). They are given to you right here — do NOT hunt for them (no Bash/grep/cat/find to locate credentials, no reading memory); just call the tools with these exact values. (Bash/git/gh ARE for your code work — this rule is only about not searching for these keys.)`
 
+  // Higher rank wins when coalescing cycles requested while one is running.
+  const RANK = { fast: 0, intro: 1, sweep: 2, full: 3 }
+  const baseFor = (kind) => kind === 'intro' ? INTRO : (kind === 'full' || kind === 'sweep') ? fullPrompt : fastPrompt
+
   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 }
+    if (busy) { queued = (RANK[kind] ?? 0) >= (RANK[queued] ?? 0) ? kind : queued; 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 = credNote + '\n\n' + (ctx.length ? ctx.join('\n') + '\n\n' : '') + base
+    const prompt = credNote + '\n\n' + (ctx.length ? ctx.join('\n') + '\n\n' : '') + baseFor(kind)
     log('running ' + kind + ' cycle…' + (ctx.length ? ' (' + ctx.length + ' event' + (ctx.length === 1 ? '' : 's') + ')' : ''))
     try {
       await runCycle(prompt)
@@ -269,11 +294,25 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
 
   function onEvent(k, d) {
     const raw = d && typeof d === 'object' ? d : {}
-    if (k === 'task:assigned') {
-      const t = raw.task || {}
-      log('task:assigned ' + (t.id != null ? '#' + t.id + ' “' + (t.title || '') + '”' : ''))
+    // The backend has NO `task:assigned` event — a task assigned to an agent arrives
+    // as `task:created` (assigned on create) or `task:updated` (assignee changed),
+    // 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)
+      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}`
+      if (t.id != null && seenTasks.has(key)) return
+      if (t.id != null) { seenTasks.add(key); if (seenTasks.size > 500) seenTasks.clear() }
+      log('task ' + k.slice(5) + ' #' + (t.id != null ? t.id : '?') + ' (agent ' + agentId + ') “' + (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)
+      void drain('full', `A task was just ${k === 'task:created' ? 'created and assigned' : 'assigned'} to an agent in this workspace — task #${t.id != null ? t.id : '?'}: "${t.title || ''}"${desc} (agent_id ${agentId}). Call get_marching_orders to confirm it is assigned to YOU. If it IS yours: FIRST post a brief comment_ticket acknowledgement ("On it — picking this up now, will update shortly"), THEN do the work end-to-end and report back (branch/PR + a channel note). If it is NOT yours, do nothing and stop.`)
     } else if (k === 'agent:mention') {
       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 : {}
@@ -297,25 +336,48 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
     }
   }
 
-  // NO polling — the WebSocket is the only trigger (task:assigned / agent:mention).
-  // A thread reply that @mentions the agent fires agent:mention and is handled
-  // in-thread above; genuinely un-mentioned thread activity has no WS event, so
-  // it's a backend concern (dispatch a thread event to participant agents), not a
-  // reason to poll.
+  // The WebSocket drives real-time reactions (task:created/updated assigned to us,
+  // agent:mention). A thread reply that @mentions the agent fires agent:mention and
+  // is handled in-thread above. In addition we run a DAILY (and on-startup) sweep
+  // 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 })
 
+  const DAY_MS = 24 * 60 * 60 * 1000
+  let introTimer = null, sweepStartTimer = null, sweepTimer = null
+  if (mcpConfig) {
+    // Workspace ethics: a one-time hello the FIRST time this agent ever connects.
+    const introMarker = join(OV_DIR, 'intro-' + slugify(identifier) + '.done')
+    if (!existsSync(introMarker)) {
+      try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(introMarker, new Date().toISOString() + '\n') } catch { /* best-effort */ }
+      log('first connection — introducing self to the workspace')
+      introTimer = setTimeout(() => void drain('intro'), 5000) // let the socket subscribe first
+    }
+    // Catch-up sweep: shortly after startup (covers downtime) + once every day.
+    sweepStartTimer = setTimeout(() => { log('startup catch-up sweep'); void drain('sweep', SWEEP) }, 30_000)
+    sweepTimer = setInterval(() => { log('daily catch-up sweep'); void drain('sweep', SWEEP) }, DAY_MS)
+  } else {
+    log('no MCP config — skipping intro + daily sweep (agent has no tools to post/act)')
+  }
+
   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 && handle.close() } catch { /* noop */ } process.exit(0) }
+    // Run until killed. Tidy up the socket + timers on termination so a restarting
+    // service doesn't leak a half-open connection or a dangling interval.
+    const bye = () => {
+      if (introTimer) clearTimeout(introTimer)
+      if (sweepStartTimer) clearTimeout(sweepStartTimer)
+      if (sweepTimer) clearInterval(sweepTimer)
+      try { handle && 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, debug }) {
+function loop({ host, key, slug, 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, debug })
@@ -326,6 +388,22 @@ function loop({ host, key, claude, mcpConfig, workdir, debug }) {
   let busy = false
   let firstCheck = true
   let lastNewAt = Date.now()
+  // A one-off prompt (intro / daily sweep) the main loop runs the next time it's
+  // free — keeps everything on the single runCycle so nothing overlaps.
+  let queuedSpecial = null
+  if (mcpConfig) {
+    const introMarker = join(OV_DIR, 'intro-' + (slug || 'openvisio') + '.done')
+    if (!existsSync(introMarker)) {
+      try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(introMarker, new Date().toISOString() + '\n') } catch { /* best-effort */ }
+      log('first run — introducing self to the workspace')
+      setTimeout(() => { queuedSpecial = INTRO }, 5000)
+    }
+    // The startup poll marks pre-existing tasks as "seen" (so it won't re-handle old
+    // ones) — which would also skip tasks assigned while offline. A startup + daily
+    // sweep re-checks get_marching_orders so those are still picked up.
+    setTimeout(() => { log('startup catch-up sweep'); queuedSpecial = SWEEP + '\n\n' + fullPrompt }, 30_000)
+    setInterval(() => { log('daily catch-up sweep'); queuedSpecial = SWEEP + '\n\n' + fullPrompt }, 24 * 60 * 60 * 1000)
+  }
 
   async function check() {
     const res = await fetch(host + '/api/agent/inbox', { headers: { authorization: 'Bearer ' + key } })
@@ -345,6 +423,15 @@ function loop({ host, key, claude, mcpConfig, workdir, debug }) {
     for (;;) {
       let delay = FAST
       try {
+        // Run a queued one-off (intro / daily sweep) first when free, on the same
+        // runCycle so it never overlaps a normal cycle.
+        if (!busy && queuedSpecial) {
+          const p = queuedSpecial; queuedSpecial = null
+          busy = true
+          try { await runCycle(p) } finally { busy = false; lastNewAt = Date.now() }
+          await sleep(FAST)
+          continue
+        }
         const res = busy ? { items: [], paused: false } : await check()
         const items = Array.isArray(res.items) ? res.items : []
         if (firstCheck && Array.isArray(res.items)) {