openvisio-agent 0.25.6 → 0.25.7

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## [0.25.7] — 2026-09-21
+
+- Restore recovery for addressed messages that the backend omits from the watcher WebSocket stream.
+- Cache projects during connection recovery, then check only `list_activity` every 30 seconds while idle. The lightweight check does not rescan projects, tasks, boards, or task types and starts no model provider unless it finds a new addressed message.
+- Add a behavioral regression test proving a missed mention is handled once without idle project or task scans.
+
 ## [0.25.6] — 2026-09-21
 
 - Keep healthy backend watchers event-driven after their connection recovery pass instead of polling every project for tasks and activity every 30 seconds.

package/README.md

@@ -81,7 +81,7 @@ The integration follows Mastra's [semantic memory](https://mastra.ai/docs/memory
 
 Model selections are stable. Exact IDs (including reasoning effort) are preserved. An unsuffixed ACP model may resolve once to the same model with `medium` effort; the watcher saves that exact selection. Unavailable selections produce an explicit error rather than switching generations or families. Claude versioned IDs are preserved, with automatic family fallbacks disabled. Codex uses the configured chat model for replies.
 
-Backend/BYO watchers reconcile once whenever the WebSocket starts or reconnects. A direct MCP session discovers and caches the backend's actual `tools/list` response, then uses available tools such as `list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity` to recover assigned tasks and recent mention activity missed while offline. Team discovery is shared by every runtime provider: structured MCP results and compact Markdown list envelopes are normalized once before the watcher resolves its project, identity, boards, tickets, or dedicated channel. Adding another model provider therefore reuses the same saved team connection and setup path instead of adding provider-specific project discovery. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. After the recovery pass, the healthy event connection waits without polling MCP tools and starts a model only when work arrives.
+Backend/BYO watchers reconcile assignments whenever the WebSocket starts or reconnects. A direct MCP session discovers and caches the backend's actual `tools/list` response, then uses available tools such as `list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity` to recover work missed while offline. Because the backend can omit an addressed message from the watcher stream, the watcher retains the recovered project IDs and checks only recent `list_activity` every 30 seconds; it does not repeat project, board, task-type, or task scans while idle. Team discovery is shared by every runtime provider: structured MCP results and compact Markdown list envelopes are normalized once before the watcher resolves its project, identity, boards, tickets, or dedicated channel. Adding another model provider therefore reuses the same saved team connection and setup path instead of adding provider-specific project discovery. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. The activity check starts a model only when it finds a new addressed message.
 
 The backend MCP may be stateful or stateless. A successful initialize response without `Mcp-Session-Id` is accepted as stateless, so OpenCode agents do not stop with “MCP initialize returned no session id.” Each OpenCode lane keeps its MCP identity in a private per-agent config directory while the repository is supplied separately with `--dir`; stale workspace configuration therefore cannot swap one agent's credentials for another's. The generated remote configuration sends the agent headers directly, disables OAuth probing, and backend cycles never request relay-only inbox calls or MCP resource-discovery tools in place of team actions.
 
@@ -114,7 +114,7 @@ Authorization recovery checks paused repositories locally every two seconds and
 
 Fresh top-level messages belong in the agent’s dedicated channel; responses to existing requests stay in their source thread. The watcher resolves a unique exact identity/name match (including `agent-alex` and `alex-agent`) and never falls back to general. Use `connect ... --channel <id>` for a differently named dedicated channel. If it is missing or ambiguous, ticket results remain recorded and channel delivery stays pending; the watcher does not invent a channel-creation tool.
 
-Codex, OpenCode, Gemini CLI, and Qwen Code use Mastra ACP directly. OpenCode starts only for an accepted cycle and exits as soon as that cycle releases it, so the idle watcher does not retain an OpenCode child process. Other runtimes retain work sessions per ticket in a six-entry pool and reply sessions in an eight-entry pool; their idle sessions expire after five minutes, and active sessions cannot be evicted. Git snapshots are asynchronous, lightweight commands lazily load the watcher, and logs separate queue wait, preflight, first-event, and total runtime time. Studio reads watcher liveness from the local PID lock instead of requiring journal heartbeats, and model changes arrive through filesystem notifications. Projects reconcile with concurrency three and enqueue tickets before reading optional activity history. Coordination sessions can update the board without gaining repository access.
+Codex, OpenCode, Gemini CLI, and Qwen Code use Mastra ACP directly. OpenCode starts only for an accepted cycle and exits as soon as that cycle releases it, so the idle watcher does not retain an OpenCode child process. Other runtimes retain work sessions per ticket in a six-entry pool and reply sessions in an eight-entry pool; their idle sessions expire after five minutes, and active sessions cannot be evicted. Git snapshots are asynchronous, lightweight commands lazily load the watcher, and logs separate queue wait, preflight, first-event, and total runtime time. Studio reads watcher liveness from the local PID lock instead of requiring journal heartbeats, and model changes arrive through filesystem notifications. Projects reconcile with concurrency three and enqueue tickets before reading optional activity history; later idle recovery reads activity only. Coordination sessions can update the board without gaining repository access.
 
 Assignments use independent FIFO entries with stable-key duplicate suppression and bounded, worktree-aware concurrency. Backlog recovery uses the same ticket verification path as WebSocket events, and each queued ticket is checked again before a model starts. MCP calls have a 20-second deadline including response bodies; tool discovery is cached and paginated. Codex MCP failures retain a bounded, credential-redacted reason in the watcher log. Cancellation targets only its ACP session. Credentials and replay state use atomic file replacement; Mastra persists contextual memory in libSQL.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.25.6",
+  "version": "0.25.7",
   "description": "Connect Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code to an OpenVisio team \u2014 MCP tools + optional autonomy \u2014 in one command.",
   "type": "module",
   "bin": {

package/scenarios/workspace.scenarios.mjs

@@ -16,7 +16,7 @@ async function eventually(predicate, description) {
   assert.fail(`Watcher did not reach: ${description}`)
 }
 
-export function fixture({ agent = 'codex', name, task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket, listChannels, transportRecoveryDelays, activityReporter } = {}) {
+export function fixture({ agent = 'codex', name, task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket, listChannels, listActivity, transportRecoveryDelays, activityReporter } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'byo-workspace-'))
   const posts = [], runs = [], calls = [], logs = [], messages = [], subscriptions = []
   const ticket = { id: 77, project_id: 1, slug: 'OPEN-77', title: 'Repair the component', agent_id: 7, status: 'In Progress', type_id: 1, updated_at: 'revision-1' }
@@ -36,7 +36,7 @@ export function fixture({ agent = 'codex', name, task = true, run, threadError =
       if (name === 'update_ticket') { Object.assign(ticket, args); return { ticket: { ...ticket } } }
       if (name === 'list_channels' && listChannels) return { channels: await listChannels() }
       if (name === 'list_channels') return { channels: [{ id: 2, name: 'alex', agent_id: 7 }, { id: 9, name: 'general' }] }
-      if (name === 'list_activity') return { activities: [] }
+      if (name === 'list_activity') return listActivity ? await listActivity(args) : { activities: [] }
       if (name === 'list_message_thread') {
         if (typeof threadError === 'function') await threadError()
         else if (threadError) throw new Error('Thread service unavailable')

package/scripts/certify.mjs

@@ -52,9 +52,9 @@ const assertions = [
   ['new follow-ups only deduplicate later replies', watcher.includes('repliesAfterSource(renderedAgentMessages') && watcher.includes('sourceMessageId: mid')],
   ['Mastra snapshots do not block the event loop', mastraHarness.includes('await execFileAsync') && !mastraHarness.includes('spawnSync')],
   ['OpenCode exits after work while the event watcher stays idle', runtimeProviders.includes("id: 'opencode'") && runtimeProviders.includes('idleSessionMs: 0') && watcher.includes('idleMs: runtimeIdleMs')],
-  ['healthy backend watchers do not poll projects while idle', watcher.includes('onConnect: () =>') && watcher.includes('void reconcileBacklog()') && !watcher.includes('taskProbeTimer') && !watcher.includes('taskProbeStartTimer')],
+  ['healthy backend watchers recover missed messages without polling projects or tasks while idle', watcher.includes('onConnect: () =>') && watcher.includes('void reconcileBacklog()') && watcher.includes('activityRecoveryTimer') && watcher.includes('replayRecentActivity(knownProjects)') && !watcher.includes('taskProbeTimer') && !watcher.includes('taskProbeStartTimer')],
   ['idle watchers use event notifications without journal or settings polling', watcher.includes('watchFs(stateDir') && !watcher.includes('modelSettingsTimer') && !journal.includes("emit('runtime.heartbeat'")],
-  ['ticket pickup precedes optional activity reads', watcher.indexOf("await handleTaskSignal('task:assigned'", watcher.indexOf('const reconcileBacklog')) < watcher.indexOf("const activityData = await callMcpTool", watcher.indexOf('const reconcileBacklog'))],
+  ['ticket pickup precedes optional activity reads', watcher.indexOf("await handleTaskSignal('task:assigned'", watcher.indexOf('const reconcileBacklog')) < watcher.indexOf('await replayRecentActivity(projects)', watcher.indexOf('const reconcileBacklog'))],
   ['task:assigned is handled', watcher.includes("k === 'task:assigned'")],
   ['task signals are verified with get_ticket', watcher.includes("callMcpTool('get_ticket'")],
   ['review and testing handoffs do not restart work', watcher.includes('taskIsAwaitingReview(task, reviewIds)') && watcher.includes('taskIsAwaitingReview(ticket, typeSets.review)')],

package/src/watch.mjs

@@ -898,6 +898,8 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   // hoping poll_inbox re-surfaces the same item. Each queue entry retains that
   // source independently through work, continuation, and delivery.
   let backlogProbeBusy = false
+  let activityProbeBusy = false
+  let knownProjects = []
   let selfAgentId = null
   let selfOrganizationId = null
   let identityContext = memory.get?.(`identity:${identifier}`)?.meta?.context || agentProfileContext({}, identifier)
@@ -1424,6 +1426,87 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     return publishBlocker({ prompt, taskRef, delivery, notice, ticketNotice, pause: true })
   }
 
+  const replayRecentActivity = async (projects) => {
+    const mentionActivity = []
+    let activityReplayTouched = false
+    await ensureSelfAgent()
+    const mentionNeedles = [...selfAliases].map((alias) => '@' + alias)
+    await mapConcurrent(projects, 3, async (project) => {
+      const activityData = await callMcpTool('list_activity', { project_id: project.id }).then(toolData).catch((error) => {
+        log('activity reconciliation unavailable: ' + (error?.message || error))
+        return {}
+      })
+      const activities = Array.isArray(activityData.activities) ? activityData.activities : Array.isArray(activityData.activity) ? activityData.activity : []
+      for (const item of activities) {
+        const text = JSON.stringify(item)
+        const activityKey = String(project.id) + ':' + String(item.id ?? item.message_id ?? item.messageId ?? text.slice(0, 500))
+        const data = item?.data && typeof item.data === 'object' ? item.data : null
+        const activityMessage = item?.message && typeof item.message === 'object'
+          ? item.message
+          : data?.message && typeof data.message === 'object' ? data.message : item
+        const activityText = String(activityMessage?.content ?? activityMessage?.body ?? activityMessage?.text ?? '').toLowerCase()
+        const activityChannelId = item?.channel_id ?? item?.channelId ?? data?.channel_id ?? data?.channelId
+        const activityMessageId = activityMessage?.id ?? activityMessage?.message_id ?? activityMessage?.messageId
+        const activityParentId = messageParentId(activityMessage)
+        const activityThreadRoot = activityParentId != null ? activityParentId : activityMessageId
+        const activityControlKey = threadControlKey(activityChannelId, activityThreadRoot)
+        const ownedActivity = !!activityControlKey && memory.has(activityControlKey, 'active')
+        // Search only the source message, never the whole activity envelope: an
+        // old tagged thread root can otherwise make another agent's new reply
+        // look addressed to this watcher. Explicit mentions and human follow-ups
+        // in a persistently owned thread both enter the guarded per-message path.
+        const addressedActivity = mentionNeedles.some((needle) => activityText.includes(needle)) || ownedActivity || activityParentId != null
+        if (!seenActivities.has(activityKey) && addressedActivity && /message|mention|channel/i.test(text)) {
+          seenActivities.add(activityKey); trimSeen(seenActivities); activityReplayTouched = true
+          // The same logical mention may already have arrived over WebSocket.
+          // Share the id/signature guard instead of starting a second model turn.
+          // Recover the former pre-routing acknowledgement bug exactly once
+          // when an owned-thread source has no received ledger entry.
+          if (markMentionHandled(activityMessage, activityChannelId)) {
+            const activityMentionKeys = mentionDedupeKeys(activityMessage, activityChannelId)
+            const activitySourceKey = `mention:${activityChannelId ?? '?'}:${activityMentionKeys.idKey || activityMentionKeys.signatureKey || activityThreadRoot}`
+            if (memory.has(activitySourceKey, 'received')) continue
+          }
+          mentionActivity.push({
+            projectId: project.id,
+            project: project.name,
+            channelId: activityChannelId,
+            message: activityMessage,
+            activity: item, activityKey,
+          })
+        }
+      }
+    })
+    if (activityReplayTouched) persistReplay()
+    if (!mentionActivity.length) return
+    log('activity recovery found ' + mentionActivity.length + ' mention(s) -> guarded reply cycle(s)')
+    // Replay each real message through the exact same delivery path as a live
+    // WebSocket mention. This preserves thread ids and lets postMessageOnce
+    // consult the rendered thread before any reply is emitted.
+    for (const mention of mentionActivity) {
+      void onEvent('agent:mention', {
+        project_id: mention.projectId,
+        channel_id: mention.channelId,
+        message: mention.message,
+        _mentionAlreadyMarked: true,
+      })?.then((result) => {
+        if (result?.status === 'retry') { seenActivities.delete(mention.activityKey); persistReplay() }
+      })
+    }
+  }
+
+  // The backend can occasionally omit a targeted WebSocket message. Keep a
+  // cached project list from connection recovery and check only recent activity
+  // while idle. This does not scan projects, boards, task types, or tickets and
+  // does not start a provider process unless a new addressed message is found.
+  const reconcileActivity = async () => {
+    if (stopping || !mcpUrl || backlogProbeBusy || activityProbeBusy || !knownProjects.length) return
+    activityProbeBusy = true
+    try { await replayRecentActivity(knownProjects) }
+    catch (e) { log('activity recovery failed: ' + (e?.message || e)) }
+    finally { activityProbeBusy = false }
+  }
+
   // Reconcile everything that may have arrived while disconnected. This spends no
   // model tokens unless the tools actually report pending work.
   const reconcileBacklog = async () => {
@@ -1433,8 +1516,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     try {
       const projectsData = toolData(await callMcpTool('list_projects'), 'list_projects')
       const projects = Array.isArray(projectsData.projects) ? projectsData.projects : []
-      const mentionActivity = []
-      let activityReplayTouched = false
+      knownProjects = projects.map((project) => ({ id: project.id, name: project.name }))
       await mapConcurrent(projects, 3, async (project) => {
         try {
           const assigned = []
@@ -1484,71 +1566,9 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
             seenTasks.delete(key)
             await handleTaskSignal('task:assigned', { task: { id: next.id, project_id: next.projectId } })
           }
-          const activityData = await callMcpTool('list_activity', { project_id: project.id }).then(toolData).catch((error) => {
-            log('activity reconciliation unavailable: ' + (error?.message || error))
-            return {}
-          })
-          const activities = Array.isArray(activityData.activities) ? activityData.activities : Array.isArray(activityData.activity) ? activityData.activity : []
-          await ensureSelfAgent()
-          const mentionNeedles = [...selfAliases].map((alias) => '@' + alias)
-          for (const item of activities) {
-            const text = JSON.stringify(item)
-            const activityKey = String(project.id) + ':' + String(item.id ?? item.message_id ?? item.messageId ?? text.slice(0, 500))
-            const data = item?.data && typeof item.data === 'object' ? item.data : null
-            const activityMessage = item?.message && typeof item.message === 'object'
-              ? item.message
-              : data?.message && typeof data.message === 'object' ? data.message : item
-            const activityText = String(activityMessage?.content ?? activityMessage?.body ?? activityMessage?.text ?? '').toLowerCase()
-            const activityChannelId = item?.channel_id ?? item?.channelId ?? data?.channel_id ?? data?.channelId
-            const activityMessageId = activityMessage?.id ?? activityMessage?.message_id ?? activityMessage?.messageId
-            const activityParentId = messageParentId(activityMessage)
-            const activityThreadRoot = activityParentId != null ? activityParentId : activityMessageId
-            const activityControlKey = threadControlKey(activityChannelId, activityThreadRoot)
-            const ownedActivity = !!activityControlKey && memory.has(activityControlKey, 'active')
-            // Search only the source message, never the whole activity envelope: an
-            // old tagged thread root can otherwise make another agent's new reply
-            // look addressed to this watcher. Explicit mentions and human follow-ups
-            // in a persistently owned thread both enter the guarded per-message path.
-            const addressedActivity = mentionNeedles.some((needle) => activityText.includes(needle)) || ownedActivity || activityParentId != null
-            if (!seenActivities.has(activityKey) && addressedActivity && /message|mention|channel/i.test(text)) {
-              seenActivities.add(activityKey); trimSeen(seenActivities); activityReplayTouched = true
-              // The same logical mention may already have arrived over WebSocket.
-              // Share the id/signature guard instead of starting a second model turn.
-              // Recover the former pre-routing acknowledgement bug exactly once
-              // when an owned-thread source has no received ledger entry.
-              if (markMentionHandled(activityMessage, activityChannelId)) {
-                const activityMentionKeys = mentionDedupeKeys(activityMessage, activityChannelId)
-                const activitySourceKey = `mention:${activityChannelId ?? '?'}:${activityMentionKeys.idKey || activityMentionKeys.signatureKey || activityThreadRoot}`
-                if (memory.has(activitySourceKey, 'received')) continue
-              }
-              mentionActivity.push({
-                projectId: project.id,
-                project: project.name,
-                channelId: activityChannelId,
-                message: activityMessage,
-                activity: item, activityKey,
-              })
-            }
-          }
         } catch (error) { log('Project reconciliation failed: ' + (error?.message || error)) }
       })
-      if (activityReplayTouched) persistReplay()
-      if (mentionActivity.length) {
-        log('backlog reconciliation found ' + mentionActivity.length + ' mention(s) -> guarded reply cycle(s)')
-        // Replay each real message through the exact same delivery path as a live
-        // WebSocket mention. This preserves thread ids and lets postMessageOnce
-        // consult the rendered thread before any reply is emitted.
-        for (const mention of mentionActivity) {
-          void onEvent('agent:mention', {
-            project_id: mention.projectId,
-            channel_id: mention.channelId,
-            message: mention.message,
-            _mentionAlreadyMarked: true,
-          })?.then((result) => {
-            if (result?.status === 'retry') { seenActivities.delete(mention.activityKey); persistReplay() }
-          })
-        }
-      }
+      await replayRecentActivity(projects)
     } catch (e) {
       log('backlog reconciliation failed: ' + (e && e.message ? e.message : e))
     } finally { backlogProbeBusy = false }
@@ -2189,6 +2209,10 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   }
   const deliveryTimer = autoStart ? setInterval(() => void flushPendingReplies(), 30_000) : null
   deliveryTimer?.unref?.()
+  const activityRecoveryTimer = autoStart ? setInterval(() => {
+    if (!stopping) void trackOperation(reconcileActivity())
+  }, 30_000) : null
+  activityRecoveryTimer?.unref?.()
   const authorizationTimer = autoStart ? setInterval(() => void resumeReadyAuthorizations(), 2_000) : null
   authorizationTimer?.unref?.()
   let modelSettingsWatcher = null
@@ -2228,6 +2252,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     closePromise = (async () => {
       clearInterval(authorizationTimer)
       clearInterval(deliveryTimer)
+      clearInterval(activityRecoveryTimer)
       modelSettingsWatcher?.close()
       if (introTimer) clearTimeout(introTimer)
       try { handle?.close() } catch { /* already disconnected */ }
@@ -2252,6 +2277,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   }
   return {
     done, close, receive: onEvent, reconcile: () => stopping ? Promise.resolve() : trackOperation(reconcileBacklog()),
+    recoverActivity: () => stopping ? Promise.resolve() : trackOperation(reconcileActivity()),
     resumeAuthorizations: resumeReadyAuthorizations, retryDeliveries: flushPendingReplies,
     get pending() { return queues.work.size + queues.reply.size + mentionIntake.size },
   }