openvisio-agent 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.24.0] — 2026-09-10
+
+- Acknowledge accepted coding tasks with the agent's short native plan, then deliver its final response separately. Deduplicate plans through reconnects and use guarded source-thread delivery for every BYO runtime.
+- Enable native coding delegation through Codex multi-agent, OpenCode task, and Claude Agent/Task, with scoped child objectives and parent review.
+- Restore working, thinking, and typing presence through the documented REST endpoint, with per-cycle ownership, throttled refresh, and failure backoff.
+- Remove Studio input outlines and retain a subtle keyboard-focus underline.
+- Keep accepted coding work alive across event WebSocket disconnects. Resume confirmed runtime transport interruptions in the same queue with the original workspace, thread, and partial context; verify ownership again before restarting the model.
+- Wait through known event-channel outages without exhausting retries. Use bounded backoff for provider-only transport failures; preserve agent final responses, cancellation, policy blocks, and guarded delivery.
+- Refresh active cycle state in the Studio journal so long tasks remain visible after their start event leaves the bounded activity window.
+
+## [0.23.0] — 2026-09-10
+
+- Add local semantic and keyword search over recorded conversations with source references, bounded retention, edit replacement, and backend/agent isolation.
+- Add live assignment lookup and intent-based discovery of currently advertised tools, including a task-offer cue in every agent cycle.
+- Expose two on-demand Mastra skills for assignment handling and conversation recall through the native runtime MCP bridge.
+- Run local embedding inference outside the agent loop, preserve keyword fallback during model download/failure, and keep live task state authoritative.
+- Known dependency finding: FastEmbed's ONNX installer inherits the `adm-zip` audit findings documented in the README. Local and simulated runtime tests pass; live team/model behavior requires validation in a safe test organization.
+
 ## [0.22.0] — 2026-09-10
 
 - Carry the agent’s configured role and voice through every session, with cached identity when the roster is unavailable.

package/README.md

@@ -62,15 +62,30 @@ Runs the **autonomy loop** — the agent replies to @mentions and picks up ticke
 
 Codex and OpenCode cycles run through Mastra's ACP harness. Codex uses the packaged `codex-acp` adapter and reuses the machine's existing ChatGPT/Codex login; OpenCode uses its native `opencode acp` server. Each accepted ticket gets its own ACP session and worktree. Mastra Memory stores ticket/thread context in local libSQL under `~/.openvisio/`, while a compact JSON ledger retains only exact replay, cancellation, and delivery keys.
 
+Backend watchers also provide four local context tools through the authenticated MCP bridge:
+
+| Tool | Purpose |
+| --- | --- |
+| `openvisio_list_my_tasks` | Read live pending assignments, including when someone says “I have a task for you.” Does not claim or start work. |
+| `openvisio_find_tools` | Search currently advertised tools by intent and return their actual input schemas, plus available skill descriptions. |
+| `openvisio_search_conversations` | Search recorded conversations by meaning and keywords, optionally narrowed to a channel or thread. |
+| `openvisio_load_skill` | Load the `openvisio-work` or `conversation-recall` skill when useful, including after compaction. |
+
+Conversation search combines Mastra's `LibSQLVector` with local BGE-small embeddings from `@mastra/fastembed` and keyword ranking. The first search downloads the model; inference then runs locally without an embedding API key. A worker handles inference independently of the agent loop. Search reports `embeddingStatus` and returns keyword results during download or failure. No conversation text is sent to an embedding provider.
+
+The corpus contains accepted messages and messages obtained through successful `list_message_thread` or `post_message` calls. It does not automatically crawl the whole organization. Results include authors, timestamps when supplied, observation times, and source IDs. Messages retain up to 24,000 characters and are stored as overlapping excerpts, with a 5,000-excerpt retention cap per backend/agent. Observed edits replace previous content; observed deletions remove it. Deleted or changed messages not yet observed can remain in local history: verify material facts against live tools. Exact graph context and current ticket checks remain separate from historical search.
+
+The integration follows Mastra's [semantic memory](https://mastra.ai/docs/memory/semantic-recall), [skills](https://mastra.ai/docs/skills), [harness](https://mastra.ai/docs/harness/overview), and [workflow](https://mastra.ai/docs/workflows/overview) documentation. The two built-in skills use `createSkill()` and are exposed to native coding runtimes through MCP. Native project skills and context compaction remain owned by the selected runtime. Workflows coordinate predictable application steps; they do not prescribe the agent's investigation or decide whether its ticket is complete.
+
 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 immediately whenever the process starts or the WebSocket connects. 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. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. The same zero-model check runs every five minutes as a safety net; a model starts only when pending work exists.
 
 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.
 
-Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent reply/work queues, authoritative `get_ticket` verification for assignments, silent transient activity, persistent replay suppression, and runtime evidence gates before completion. Maintainers must run `npm run certify` before publishing.
+Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent reply/work queues, authoritative `get_ticket` verification for assignments, silent transient activity, persistent replay suppression, and agent-controlled turn completion. Maintainers must run `npm run certify` before publishing.
 
-Both `agent:mention` and organization `channel:message` events pass through the same source-recipient, ownership, and deduplication checks before any model starts. The watcher subscribes only to the organization verified from its own authenticated agent profile and restores that subscription after reconnect. Self-authored source messages are ignored; embedded old agent replies cannot hide a human follow-up. An explicit tag establishes durable ownership of that thread, so later human follow-ups remain addressed to the agent without another @mention. Messages redirected to another agent and unaddressed agent chatter stay silent, while a direct stand-down cancels queued/running work and releases ownership for that thread. Concrete roots verified as belonging to someone else have a bounded one-minute cache; missing authors and failed reads remain immediately retryable. The watcher does not broadcast working, thinking, or typing presence updates. Claude and OpenCode may add one concrete progress update after work begins, but must continue and post a distinct verified result or blocker afterward; Codex keeps cancellation-safe delivery watcher-owned and renders the verified final answer once.
+Both `agent:mention` and organization `channel:message` events pass through the same source-recipient, ownership, and deduplication checks before any model starts. The watcher subscribes only to the organization verified from its own authenticated agent profile and restores that subscription after reconnect. Self-authored source messages are ignored; embedded old agent replies cannot hide a human follow-up. An explicit tag establishes durable ownership of that thread, so later human follow-ups remain addressed to the agent without another @mention. Messages redirected to another agent and unaddressed agent chatter stay silent, while a direct stand-down cancels queued/running work and releases ownership for that thread. Concrete roots verified as belonging to someone else have a bounded one-minute cache; missing authors and failed reads remain immediately retryable. The watcher publishes working, thinking, and typing presence from actual runtime activity using the authenticated REST endpoint. It stops refreshing when work finishes or is cancelled; the app clears the indicator through its expiry timer. Accepted coding tasks publish a short native plan first; the watcher sends one acknowledgement with up to three steps in the source thread or dedicated channel. Every runtime returns a distinct final answer for guarded watcher delivery. Plans and reconnects cannot duplicate or suppress that final answer.
 
 Ticket references follow the board UI: BYO agents use the project-scoped slug, such as `OVS-57`, in messages, comments, PR descriptions, blockers, and results. Numeric `project_id` and `ticket_id` values remain internal MCP arguments and are never used as human-facing ticket names. If an older backend omits the slug, the agent uses the ticket title rather than inventing one.
 
@@ -83,7 +98,7 @@ openvisio-agent watch --name ada --workdir ~/repo  # allow REAL work on a git br
 openvisio-agent stop --name ada                  # stop service + every ada watcher
 ```
 
-Agents choose their tools, investigation steps, context management, and when to end a turn. Each turn receives the agent’s configured identity, role, and voice when supplied by its profile; that context is cached across restarts. Reply sessions can request their configured coding workspace through `openvisio_request_work_session`, carrying their findings, source thread, and permissions into the continuation. They do not ask you to reassign work because of an internal scheduling choice. A successful native final turn ends the cycle; it does not mark a ticket done. The agent decides when to update the board. Research, audits, and already-satisfied requests can finish without code changes, ticket mutations, or a PR. Tool failures stay visible as diagnostics without forcing another model turn or replacing the agent's explanation.
+Agents choose their tools, investigation steps, context management, and when to end a turn. Coding agents can delegate independent subtasks through the runtime’s native sub-agent tools: Codex multi-agent is enabled, OpenCode permits task delegation, and Claude permits Agent/Task. The parent supplies scoped context and file ownership, works alongside children, reviews their results, and reports once. Delegation depends on the tools advertised by the installed runtime; it does not grant additional task or publishing authority. Each turn receives the agent’s configured identity, role, and voice when supplied by its profile; that context is cached across restarts. Reply sessions can request their configured coding workspace through `openvisio_request_work_session`, carrying their findings, source thread, and permissions into the continuation. They do not ask you to reassign work because of an internal scheduling choice. A successful native final turn ends the cycle; it does not mark a ticket done. The agent decides when to update the board. Research, audits, and already-satisfied requests can finish without code changes, ticket mutations, or a PR. Tool failures stay visible as diagnostics without forcing another model turn or replacing the agent's explanation.
 
 The context graph records source-to-continuation relationships and recalls direct neighbors without walking into unrelated conversations. The watcher saves the agent's final response for delivery retry and avoids rerunning an unchanged assignment after restart. Claude, Codex, and OpenCode keep context within a ticket or conversation; native runtimes handle compaction. A stalled-session watchdog resets when activity arrives, so ongoing work is not stopped by a fixed task duration. Ownership, cancellation, delivery deduplication, credential injection, and repository permissions remain enforced.
 
@@ -101,6 +116,8 @@ Codex and OpenCode use Mastra ACP directly. Work sessions are retained per ticke
 
 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.
 
+An event WebSocket disconnect does not cancel accepted coding work. If the native coding runtime also reports a transport interruption, its queue entry retains the source request, workspace, and partial output. It waits for a known event-channel outage to reconnect, then verifies the ticket again and asks the agent to inspect existing work and uncertain remote writes before continuing. Provider-only interruptions use up to four retries (2, 8, 30, and 60 seconds); repeated failure then reports a blocker. Agent final responses, optional tool errors, explicit cancellation, inactivity timeouts, quota errors, and policy denials do not trigger this recovery. Coordination requests are not automatically replayed. Keep the watcher running during an outage; this recovery retains in-flight context in that watcher, not across process termination.
+
 See `docs/BYO_PERFORMANCE_AUDIT_2026-09-08.md` in the repository for the audit results and remaining live-validation limits. Local certification does not certify a deployed agent's behavior.
 
 `--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).
@@ -160,4 +177,8 @@ Watchers running this version record bounded, credential-redacted activity under
 
 `npm test` includes the executable BYO scenario catalogue. `npm run test:scenarios -- --report /tmp/byo-results.json` writes every case, result, category, and duration. Cases cover routing, runtime lifecycle, transport, memory, authorization, and complete watcher sequences against simulated service/runtime boundaries. They do not invoke paid models or mutate a live workspace.
 
+`node scripts/smoke-context-search.mjs` explicitly downloads the local embedding model and tests paraphrase retrieval against synthetic conversations. Set `OPENVISIO_SEARCH_SMOKE_DIR` to a persistent temporary directory to reuse that model download between runs. Ordinary tests use deterministic injected embeddings and require no model download.
+
+Dependency review (2026-09-10): `@mastra/fastembed@1.3.1` pins `onnxruntime-node@1.26.0`, whose installer depends on `adm-zip@0.5.x`. npm reports a [high-severity ZIP allocation issue](https://github.com/advisories/GHSA-xcpc-8h2w-3j85) and a [symlink extraction issue](https://github.com/advisories/GHSA-vwc7-r8mq-g2x9), propagated to the parent dependencies. Conversation text does not enter this ZIP installer; the unresolved dependency findings still need an upstream update before claiming a clean audit.
+
 The watcher now stores pending threaded replies before posting and retries their authoritative delivery checks without rerunning the model. Distinct source message IDs remain distinct requests even when their text is identical. Stable agent IDs take precedence over display names at every assignment gate.

package/USER_GUIDE.md

@@ -4,6 +4,14 @@ Connect your coding agent to your team, let it handle assigned work, and follow
 
 Already connected? Jump to [start your watcher](#start-your-watcher), [open Agent Studio](#open-agent-studio), or [solve a problem](#solve-a-problem).
 
+## Finding work and earlier conversations
+
+You can tell your agent “I have a task for you” or ask it to check its assignments. Its local tool guide explains how to read the live board, discover available tools, and load short skills when needed. Looking up assignments does not itself claim or complete a ticket.
+
+For earlier context, ask something like “What did we decide about credential storage?” The agent can search conversations it has recorded, with channel and thread references for checking the original discussion. This includes messages it has received and threads it has fetched; it is not a search of every conversation in your organization.
+
+The first semantic search downloads a local embedding model. Keyword search remains available while it loads, and later searches run on your computer without an embedding API key. Search history survives watcher restarts. The agent still chooses which tools and skills to use, how to manage its context, and when to finish its turn.
+
 ## Before you begin
 
 You need Node.js **22.13 or newer**, access to your OpenVisio team, and a supported coding agent: Claude Code, Codex, or OpenCode. Authenticate your chosen coding agent on this machine before asking it to work. Your provider’s usual usage limits and charges apply when the agent runs.
@@ -68,6 +76,8 @@ Stopping a watcher interrupts its active work. When you are ready to resume, run
 
 Replies stay in their source thread. New completion messages use the agent’s dedicated channel. Check the ticket and any linked pull request for delivered results. A progress message describes ongoing work; wait for the final result or blocker.
 
+For accepted coding tasks, the agent starts by publishing a short plan. You receive one acknowledgement with up to three steps, followed later by its result. The agent can delegate independent pieces to native sub-agents and remains responsible for checking their work. Thinking, working, and typing indicators follow runtime activity; they expire after work stops. A reconnect does not repeat the plan or cancel healthy work.
+
 ## Open Agent Studio
 
 In the app, choose **Agents → Open Agent Studio**. Updated backend watchers start Studio automatically. Agent chat replies can also show this button and open the relevant agent’s settings directly.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openvisio-agent",
-  "version": "0.22.0",
-  "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team — MCP tools + optional autonomy — in one command.",
+  "version": "0.24.0",
+  "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team \u2014 MCP tools + optional autonomy \u2014 in one command.",
   "type": "module",
   "bin": {
     "openvisio-agent": "bin/cli.mjs"
@@ -43,6 +43,7 @@
     "@agentclientprotocol/codex-acp": "1.10.0",
     "@mastra/acp": "0.4.1",
     "@mastra/core": "1.64.0",
+    "@mastra/fastembed": "1.3.1",
     "@mastra/libsql": "1.22.3",
     "@mastra/memory": "1.28.2"
   }

package/scenarios/runtime.scenarios.mjs

@@ -321,7 +321,7 @@ for (const agent of ['codex', 'opencode']) for (const mode of modes) for (const
       }
       if (agent === 'opencode') {
         const value = JSON.parse(config.env.OPENCODE_CONFIG_CONTENT)
-        if (mode.canCode) assert.equal(value.permission, undefined)
+        if (mode.canCode) assert.deepEqual(value.permission, { task: 'allow' })
         else {
           assert.equal(value.permission.bash, 'deny')
           assert.equal(value.permission['openvisio-team-watcher_*'], 'allow')

package/scenarios/workspace.scenarios.mjs

@@ -16,11 +16,11 @@ async function eventually(predicate, description) {
   assert.fail(`Watcher did not reach: ${description}`)
 }
 
-export function fixture({ agent = 'codex', task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket, listChannels } = {}) {
+export function fixture({ agent = 'codex', task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket, listChannels, 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' }
-  let watcher, messageId = 100, closed = 0
+  let watcher, connection, messageId = 100, closed = 0
   const memory = createByoMemoryGraph({ path: join(dir, 'ledger.json') })
   const mcp = {
     listTools: async () => ['list_agents', 'list_projects', 'list_tasks', 'get_ticket', 'update_ticket', 'post_message', 'list_message_thread', 'list_channels', 'list_task_types', 'list_activity', ...commentTools].map((name) => ({ name })),
@@ -71,7 +71,7 @@ export function fixture({ agent = 'codex', task = true, run, threadError = false
   }
   const start = () => {
     watcher = createBackendWatcher({ wsUrl: 'wss://unused.example.test', mcpUrl: 'https://unused.example.test/mcp', apiKey: 'test-key', identifier: 'alex', slug: 'test-alex', agent, workdir: join(dir, 'workspace'), model: 'test-code', chatModel: 'test-chat' }, {
-      stateDir: dir, memory, mcpClient: mcp, createRunner, connect: () => ({ close() {}, subscribeOrganization(id) { subscriptions.push(id) } }), autoStart: false, log: (value) => logs.push(value),
+      stateDir: dir, memory, mcpClient: mcp, createRunner, transportRecoveryDelays, activityReporter, connect: (callbacks) => { connection = callbacks; return { close() {}, subscribeOrganization(id) { subscriptions.push(id) } } }, autoStart: false, log: (value) => logs.push(value),
     })
     return watcher
   }
@@ -79,6 +79,7 @@ export function fixture({ agent = 'codex', task = true, run, threadError = false
   return {
     dir, ticket, posts, runs, calls, logs, messages, memory, subscriptions,
     get watcher() { return watcher },
+    get connection() { return connection },
     get closed() { return closed },
     set threadError(value) { threadError = value },
     start,

package/scripts/certify.mjs

@@ -91,7 +91,7 @@ const assertions = [
   ['workers serialize shared worktrees while independent worktrees run concurrently', watcher.includes('groupKey: (item) => item.workdir || workdir') && cycleQueue.includes('active.size < concurrency') && cycleQueue.includes('activeGroups.has(candidate[1].group)')],
   ['work and reply cancellation targets are isolated', watcher.includes('item.control.cancelled = true') && watcher.includes('item.control.runner?.cancelCurrent')],
   ['fresh threads resolve the dedicated agent channel', watcher.includes('dedicatedChannel(Array.isArray(channels)') && watcher.includes('No dedicated agent channel available for a new thread')],
-  ['presence notification requests are disabled', watcher.includes('const sendStatus = () => {}') && !watcher.includes('agentStateRequest(') && !watcher.includes("setInterval(() => emitStatusTargets")],
+  ['presence follows runtime activity and stops refreshing with its cycle', watcher.includes('createActivityReporter') && watcher.includes("activity.set(data.cycleId, live.control.statusTargets, 'working')") && watcher.includes('activity.clear(cycleControl.cycleId)')],
   ['websocket client cannot emit legacy agent_status', !websocket.includes('agent_status')],
   ['frontend consumes thinking event', activityHook.includes("'channel:agent:thinking'")],
   ['frontend consumes working event', activityHook.includes("'channel:agent:working'")],

package/scripts/smoke-context-search.mjs

@@ -0,0 +1,33 @@
+// Explicit opt-in integration check: downloads Mastra's local embedding model.
+// Uses synthetic conversations only. Keep OPENVISIO_SEARCH_SMOKE_DIR between
+// runs to reuse the model download; otherwise the temporary cache is removed.
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createContextSearch } from '../src/context-search.mjs'
+
+const directory = process.env.OPENVISIO_SEARCH_SMOKE_DIR || mkdtempSync(join(tmpdir(), 'openvisio-semantic-smoke-'))
+mkdirSync(directory, { recursive: true })
+const search = createContextSearch({ directory, resourceId: 'synthetic-smoke' })
+try {
+  search.remember({ key: 'security', text: 'Keep production credentials in the vault and rotate them monthly.', refs: { channelId: 1, messageId: 1 } })
+  search.remember({ key: 'lunch', text: 'The team is ordering pizza for lunch on Friday.', refs: { channelId: 1, messageId: 2 } })
+  search.remember({ key: 'work', text: 'Alex owns the pending ticket to repair the login form.', refs: { channelId: 1, messageId: 3 } })
+  await search.search({ query: 'How should we protect passwords?', waitMs: 1 })
+  await search.settled()
+  const result = await search.search({ query: 'How should we protect passwords?', limit: 1, waitMs: 10_000 })
+  assert.equal(result.mode, 'hybrid', JSON.stringify(result))
+  assert.equal(result.matches[0]?.key, 'security', JSON.stringify(result))
+  assert.equal(result.matches[0]?.match, 'semantic', 'Paraphrase has no overlapping keywords')
+  const assignments = await search.search({ query: 'Who is fixing the sign-in bug?', limit: 1, waitMs: 10_000 })
+  assert.equal(assignments.matches[0]?.key, 'work', JSON.stringify(assignments))
+  assert.equal(assignments.matches[0]?.match, 'semantic')
+  const vague = await search.search({ query: 'What assignments need attention?', limit: 1, waitMs: 10_000 })
+  assert.equal(vague.matches.length, 0, 'Weak similarity must not invent an answer to a vague request')
+  console.log('Real local embeddings retrieved the security conversation from a paraphrased query.')
+  console.log('Real local embeddings also recovered the pending work discussion by intent.')
+} finally {
+  await search.close()
+  if (!process.env.OPENVISIO_SEARCH_SMOKE_DIR) rmSync(directory, { recursive: true, force: true })
+}

package/src/activity-reporter.mjs

@@ -0,0 +1,47 @@
+import { agentStateRequest } from './events.mjs'
+
+// Presence is ephemeral, independent of task completion and message delivery.
+// The backend supports no "done" event; stopping refresh lets the UI TTL clear it.
+export function createActivityReporter({ backend, apiKey, identifier, fetchImpl = fetch, now = Date.now, log = () => {}, intervalMs = 3_000 }) {
+  const cycles = new Map(), channels = new Map(), pending = new Set()
+  let closed = false
+  const pulse = () => {
+    if (closed || !backend) return
+    const states = new Map()
+    const priority = { thinking: 0, working: 1, typing: 2 }
+    for (const cycle of cycles.values()) for (const channelId of cycle.channels) {
+      if (!states.has(channelId) || priority[cycle.state] > priority[states.get(channelId)]) states.set(channelId, cycle.state)
+    }
+    for (const [channelId, state] of states) {
+      const prior = channels.get(channelId)
+      if (prior?.busy || now() < (prior?.retryAt || 0) || (prior?.state === state && now() - prior.at < (state === 'working' ? 10_000 : 3_000))) continue
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), 5_000)
+      timer.unref?.()
+      const entry = { state, at: now(), busy: true, controller }
+      channels.set(channelId, entry)
+      const request = agentStateRequest(backend, channelId, state, apiKey, identifier)
+      const operation = Promise.resolve().then(() => fetchImpl(request.url, { ...request.init, signal: controller.signal })).then(async response => {
+        await response.body?.cancel?.()
+        if (!response.ok) throw new Error(`HTTP ${response.status}`)
+      }).catch(error => {
+        entry.retryAt = now() + 30_000
+        if (!closed) log('Activity update unavailable; backing off: ' + String(error?.message || 'request failed').slice(0, 100))
+      }).finally(() => { clearTimeout(timer); entry.busy = false; pending.delete(operation) })
+      pending.add(operation)
+    }
+  }
+  const timer = intervalMs > 0 ? setInterval(pulse, intervalMs) : null
+  timer?.unref?.()
+  return {
+    set(cycleId, channelIds, state) {
+      if (closed || !['thinking', 'working', 'typing'].includes(state)) return
+      const valid = [...new Set([...channelIds].map(Number).filter(id => Number.isSafeInteger(id) && id > 0))]
+      cycles.set(cycleId, { channels: valid, state }); pulse()
+    },
+    clear(cycleId) { cycles.delete(cycleId); pulse() },
+    pulse,
+    async settled() { await Promise.allSettled([...pending]) },
+    async close() { closed = true; clearInterval(timer); cycles.clear(); for (const entry of channels.values()) entry.controller.abort(); await Promise.allSettled([...pending]) },
+  }
+}

package/src/codex-mcp-proxy.mjs

@@ -3,6 +3,7 @@ import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { WORK_SESSION_TOOL, runtimeControlTools, requestWorkSession } from './runtime-control.mjs'
 import { createMcpHttpClient } from './mcp-http.mjs'
+import { contextTools, contextToolNames, callContextService, validateContextArguments } from './context-tools.mjs'
 
 export function toolWithoutCredentialInputs(tool) {
   const copy = structuredClone(tool)
@@ -80,9 +81,25 @@ export function runCodexMcpProxy() {
   const apiKey = process.env.OPENVISIO_CODEX_API_KEY
   const identifier = process.env.OPENVISIO_CODEX_IDENTIFIER
   const capabilities = { canCode: process.env.OPENVISIO_CAN_CODE === 'true', workspaceAvailable: process.env.OPENVISIO_WORKSPACE_AVAILABLE === 'true' }
+  const contextEnvironment = { OPENVISIO_CONTEXT_URL: process.env.OPENVISIO_CONTEXT_URL, OPENVISIO_CONTEXT_TOKEN: process.env.OPENVISIO_CONTEXT_TOKEN }
+  const localContext = contextEnvironment.OPENVISIO_CONTEXT_URL && contextEnvironment.OPENVISIO_CONTEXT_TOKEN ? contextTools : []
+  let available = []
   const { disabled, allowed: allowedTools } = proxyToolPolicyFromEnvironment()
   if (!url || !apiKey || !identifier) throw new Error('OpenVisio Codex MCP bridge is missing its watcher environment.')
   const client = createMcpHttpClient({ url, apiKey, identifier, clientVersion: 'openvisio-agent-codex-proxy' })
+  const discoverTools = async () => {
+    const controls = [...runtimeControlTools(capabilities), ...localContext]
+    let remote
+    try { remote = await client.listTools() }
+    catch (error) {
+      if (!controls.length) throw error
+      process.stderr.write('OpenVisio backend discovery is unavailable; local capabilities remain available.\n')
+      remote = []
+    }
+    const tools = [...remote.filter((tool) => tool.name !== WORK_SESSION_TOOL && !contextToolNames.has(tool.name)), ...controls]
+    available = tools.filter((tool) => toolAllowed(tool.name, { disabled, allowed: allowedTools })).map(toolWithoutCredentialInputs)
+    return available
+  }
   const reply = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n')
   const fail = (id, error, request) => {
     const message = String(error?.message || error || 'MCP bridge error').split(apiKey).join('[redacted]')
@@ -111,20 +128,24 @@ export function runCodexMcpProxy() {
       } else if (request.method === 'ping') {
         reply(id, {})
       } else if (request.method === 'tools/list') {
-        const controls = runtimeControlTools(capabilities)
-        let remote
-        try { remote = await client.listTools() }
-        catch (error) {
-          if (!controls.length) throw error
-          process.stderr.write('OpenVisio backend discovery is unavailable; local workspace continuation remains available.\n')
-          remote = []
-        }
-        const tools = [...remote.filter((tool) => tool.name !== WORK_SESSION_TOOL), ...controls]
-        reply(id, { tools: tools.filter((tool) => toolAllowed(tool.name, { disabled, allowed: allowedTools })).map(toolWithoutCredentialInputs) })
+        reply(id, { tools: await discoverTools() })
       } else if (request.method === 'tools/call') {
         const name = String(request.params?.name || '')
         if (!toolAllowed(name, { disabled, allowed: allowedTools })) throw new Error('This tool is disabled for the current delivery lane.')
         if (name === WORK_SESSION_TOOL) { reply(id, requestWorkSession(request.params?.arguments, capabilities)); return }
+        if (contextToolNames.has(name)) {
+          if (!localContext.length) throw new Error('Local context tools are unavailable')
+          const args = validateContextArguments(name, request.params?.arguments)
+          if (name === 'openvisio_find_tools') await discoverTools()
+          const data = await callContextService(contextEnvironment, { name, arguments: args, availableNames: available.map((tool) => tool.name) })
+          if (name === 'openvisio_find_tools') {
+            // The current proxy is the authority on runtime availability and the
+            // sanitized schema, even if the backend catalog changed mid-search.
+            const catalog = new Map(available.map((tool) => [tool.name, tool]))
+            data.matches = (data.matches || []).filter((tool) => catalog.has(tool.name)).map((tool) => ({ ...catalog.get(tool.name), match: tool.match }))
+          }
+          reply(id, { content: [{ type: 'text', text: JSON.stringify(data) }] }); return
+        }
         let result
         try { result = await client.callTool(name, request.params?.arguments || {}) }
         catch (error) {
@@ -133,6 +154,10 @@ export function runCodexMcpProxy() {
           if (!(allowedTools instanceof Set) || !allowedTools.has(name) || !/^(?:list_|get_|codebase_tree$)/.test(name)) throw error
           result = await client.callTool(name, request.params?.arguments || {})
         }
+        if (localContext.length && ['list_message_thread', 'post_message'].includes(name) && !result?.isError) {
+          try { await callContextService(contextEnvironment, { action: 'observe', name, args: request.params?.arguments || {}, result }, 1000) }
+          catch { /* optional indexing cannot fail the successful backend action */ }
+        }
         reply(id, /^(?:list_agents|get_agent|get_agent_details)$/.test(name) ? agentResultWithoutCredentials(result) : result)
       } else if (id != null) {
         process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } }) + '\n')

package/src/context-search.mjs

@@ -0,0 +1,168 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, existsSync, chmodSync } from 'node:fs'
+import { join } from 'node:path'
+import { Worker } from 'node:worker_threads'
+import { LibSQLVector } from '@mastra/libsql'
+import { writeJson } from './lib.mjs'
+
+const hash = (text) => createHash('sha256').update(text).digest('hex')
+const stopWords = new Set('a an and are as at be been by can could did do does for from had has have how i if in is it its me my of on or our should that the their them there these they this to was we were what when where which who will with would you your'.split(' '))
+const words = (text) => new Set((String(text).toLowerCase().match(/[\p{L}\p{N}_-]{2,}/gu) || []).filter((word) => !stopWords.has(word)))
+const waitBriefly = async (promise, ms) => {
+  let timer
+  try { return await Promise.race([promise, new Promise((resolve) => { timer = setTimeout(resolve, ms) })]) }
+  finally { clearTimeout(timer) }
+}
+
+export function createLocalEmbedder({ cacheDir }) {
+  let worker, sequence = 0, closed = false
+  const pending = new Map()
+  const rejectAll = () => {
+    for (const { reject, timer } of pending.values()) { clearTimeout(timer); reject(new Error('Local embedding unavailable')) }
+    pending.clear()
+    const previous = worker; worker = null
+    void previous?.terminate()
+  }
+  return {
+    embed(texts, { query = false } = {}) {
+      if (closed) return Promise.reject(new Error('Local embedding closed'))
+      if (!worker) {
+        worker = new Worker(new URL('./embedding-worker.mjs', import.meta.url), { workerData: { cacheDir } })
+        const current = worker
+        worker.on('error', () => { if (worker === current) rejectAll() })
+        worker.on('exit', () => { if (worker === current) rejectAll() })
+        worker.on('message', ({ id, vectors, error }) => {
+          const job = pending.get(id)
+          if (!job) return
+          pending.delete(id); clearTimeout(job.timer)
+          if (error) job.reject(new Error(error)); else job.resolve(vectors)
+        })
+      }
+      return new Promise((resolve, reject) => {
+        const id = ++sequence
+        pending.set(id, { resolve, reject, timer: setTimeout(rejectAll, 120_000) })
+        worker.postMessage({ id, texts, query })
+      })
+    },
+    async close() { closed = true; const previous = worker; rejectAll(); await previous?.terminate() },
+  }
+}
+
+// Separate from the exact coordination graph: historical messages are searchable
+// evidence, never instructions or the source of live assignment/completion state.
+export function createContextSearch({ directory, resourceId, embedder, vector, maxRecords = 5000, now = Date.now }) {
+  if (!Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 20_000) throw new Error('Invalid conversation retention capacity')
+  const scope = hash(String(resourceId)).slice(0, 24)
+  const file = join(directory, `context-${scope}.json`)
+  const database = join(directory, `context-${scope}.db`)
+  const indexName = 'context_bge_small_en_v15_retrieval'
+  const model = embedder || createLocalEmbedder({ cacheDir: join(directory, `embeddings-${scope}`) })
+  const vectors = vector || new LibSQLVector({ id: `context-${scope}`, url: `file:${database}`, maxRetries: 1 })
+  let raw
+  try { raw = JSON.parse(readFileSync(file, 'utf8')) } catch { /* first run */ }
+  const records = new Map((raw?.version === 1 && raw?.resourceId === resourceId && Array.isArray(raw.records) ? raw.records : [])
+    .filter((entry) => entry?.id && typeof entry.text === 'string').map((entry) => [entry.id, entry]))
+  if (raw?.indexName !== indexName || !vector && !existsSync(database)) for (const entry of records.values()) delete entry.indexedHash
+  let closed = false, indexing = null, initialized = false, retryAfter = 0, flushTimer
+  let state = 'idle'
+  const persist = () => { clearTimeout(flushTimer); writeJson(file, { version: 1, resourceId, indexName, records: [...records.values()] }, true) }
+  const schedulePersist = () => { clearTimeout(flushTimer); flushTimer = setTimeout(() => { try { persist() } catch { /* search still works in memory */ } }, 100); flushTimer.unref() }
+  const forget = (key) => {
+    for (const [id, entry] of records) if (entry.key === key) records.delete(id)
+    // Stale vectors are rejected against canonical records, including in-flight
+    // writes. Remove them on the next indexing pass as well.
+    schedulePersist()
+  }
+  const remember = ({ key, kind = 'conversation', text, refs = {}, author = '', timestamp = '', ...rest }) => {
+    if (closed || !key || typeof text !== 'string' || !text.trim()) return
+    const bounded = text.trim().slice(0, 24_000)
+    const chunks = []
+    for (let offset = 0; offset < bounded.length; offset += 1000) chunks.push(bounded.slice(offset, offset + 1200))
+    const ids = new Set()
+    for (let part = 0; part < chunks.length; part++) {
+      const id = hash(`${scope}:${key}:${part}`)
+      ids.add(id)
+      const textHash = hash(JSON.stringify([chunks[part], kind, refs]))
+      const previous = records.get(id)
+      records.set(id, { id, key, kind, text: chunks[part], refs, author, timestamp, part, textHash,
+        indexedHash: previous?.textHash === textHash ? previous.indexedHash : undefined,
+        updatedAt: now(), truncated: text.length > bounded.length, ...(rest.name ? { name: rest.name } : {}) })
+    }
+    for (const [id, entry] of records) if (entry.key === key && !ids.has(id)) records.delete(id)
+    if (records.size > maxRecords) {
+      const oldest = [...records.values()].sort((a, b) => a.updatedAt - b.updatedAt).slice(0, records.size - maxRecords)
+      for (const entry of oldest) records.delete(entry.id)
+    }
+    schedulePersist()
+    if (state !== 'idle') void startIndexing()
+  }
+  const startIndexing = () => {
+    if (closed || indexing || now() < retryAfter) return indexing || Promise.resolve()
+    indexing = (async () => {
+      state = 'indexing'
+      if (!initialized) {
+        await vectors.createIndex({ indexName, dimension: 384, metric: 'cosine' })
+        if (!vector) chmodSync(database, 0o600)
+        initialized = true
+      }
+      // Bound disk growth to retained canonical records. Metadata never contains
+      // conversation text or arbitrary tool outputs.
+      await vectors.deleteVectors({ indexName, filter: { id: { $nin: [...records.keys()] } } })
+      while (!closed) {
+        const batch = [...records.values()].filter((entry) => entry.indexedHash !== entry.textHash).slice(0, 16)
+        if (!batch.length) break
+        const embeddings = await model.embed(batch.map((entry) => entry.text))
+        if (closed) return
+        if (embeddings.length !== batch.length || embeddings.some((v) => v.length !== 384 || v.some((n) => !Number.isFinite(n)))) throw new Error('Invalid local embeddings')
+        await vectors.upsert({ indexName, ids: batch.map((entry) => entry.id), vectors: embeddings,
+          metadata: batch.map((entry) => ({ id: entry.id, key: entry.key, kind: entry.kind, hash: entry.textHash, ...entry.refs })) })
+        for (const entry of batch) if (records.get(entry.id)?.textHash === entry.textHash) records.get(entry.id).indexedHash = entry.textHash
+        schedulePersist()
+      }
+      state = 'ready'
+    })().catch(() => { state = 'unavailable'; retryAfter = now() + 60_000 }).finally(() => { indexing = null })
+    return indexing
+  }
+  const search = async ({ query, kind = 'conversation', channelId, threadId, keys, limit = 6, waitMs = 1000 }) => {
+    if (typeof query !== 'string' || !query.trim() || query.length > 2000) throw new Error('Search query must contain 1–2000 characters')
+    if (!Number.isInteger(limit) || limit < 1 || limit > 12) throw new Error('Search limit must be between 1 and 12')
+    const eligible = (entry) => entry && entry.kind === kind && (!keys || keys.includes(entry.key)) && (channelId == null || String(entry.refs.channelId) === String(channelId)) && (threadId == null || String(entry.refs.threadId) === String(threadId))
+    const tokens = words(query)
+    const ranked = [...records.values()].filter(eligible).map((entry) => {
+      const terms = words(entry.text)
+      return { entry, lexical: [...tokens].reduce((n, token) => n + (terms.has(token) ? 1 : 0), 0) / Math.max(1, tokens.size) }
+    }).filter((hit) => hit.lexical > 0).sort((a, b) => b.lexical - a.lexical || b.entry.updatedAt - a.entry.updatedAt)
+    const scores = new Map(ranked.map((hit, rank) => [hit.entry.id, { entry: hit.entry, score: 1 / (60 + rank), match: 'keyword' }]))
+    await waitBriefly(startIndexing(), waitMs)
+    let mode = 'keyword'
+    if (state === 'ready') {
+      try {
+        const result = await waitBriefly((async () => {
+          const [queryVector] = await model.embed([query], { query: true })
+          return vectors.query({ indexName, queryVector, topK: Math.min(maxRecords, limit * 8), minScore: 0.45,
+            filter: { kind, ...(keys ? { key: { $in: keys } } : {}), ...(channelId == null ? {} : { channelId }), ...(threadId == null ? {} : { threadId }) } })
+        })(), waitMs)
+        if (result) {
+          mode = 'hybrid'
+          result.forEach((hit, rank) => {
+            const entry = records.get(hit.id)
+            if (!eligible(entry) || entry.textHash !== hit.metadata?.hash) return
+            const previous = scores.get(hit.id)
+            scores.set(hit.id, { entry, score: (previous?.score || 0) + 1 / (60 + rank), match: previous ? 'hybrid' : 'semantic' })
+          })
+        }
+      } catch { state = 'unavailable'; retryAfter = now() + 60_000 }
+    }
+    const seen = new Set()
+    const matches = [...scores.values()].filter(({ entry }) => records.get(entry.id)?.textHash === entry.textHash && eligible(records.get(entry.id)))
+      .map((hit) => ({ ...hit, entry: records.get(hit.entry.id) })).sort((a, b) => b.score - a.score).filter(({ entry }) => {
+      if (seen.has(entry.key)) return false
+      seen.add(entry.key); return true
+    }).slice(0, limit).map(({ entry, match }) => ({ key: entry.key, text: entry.text, refs: entry.refs, author: entry.author,
+      timestamp: entry.timestamp, observedAt: new Date(entry.updatedAt).toISOString(), match, part: entry.part, truncated: entry.truncated, ...(entry.name ? { name: entry.name } : {}) }))
+    return { mode, embeddingStatus: state, coverage: 'Locally recorded messages visible to this agent; not the entire team archive.', matches }
+  }
+  return { remember, forget, search, async settled() { await indexing; persist() }, async close() {
+    closed = true; clearTimeout(flushTimer); await model.close?.(); await indexing; persist(); await vectors.close?.()
+  } }
+}