openvisio-agent 0.18.1 → 0.18.2

package/README.md

@@ -58,6 +58,8 @@ Runs the **autonomy loop** — the agent replies to @mentions and picks up ticke
 
 Backend/BYO watchers reconcile immediately whenever the process starts or the WebSocket connects. A direct MCP session uses the backend's actual tools (`list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity`) to recover assigned tasks and recent mention activity missed while offline. 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 `get_marching_orders`, `poll_inbox`, or `get_resource` tools.
+
 Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent Sol reply/work lanes, authoritative `get_ticket` verification for assignments, REST-backed in-app activity, persistent replay suppression, and runtime evidence gates before completion. Maintainers must run `npm run certify` before publishing.
 
 Claude uses Haiku for routine coordination and Sonnet for repository work. Codex uses `gpt-5.6-sol` for every cycle, including messages, mentions, triage, board movement, MCP calls, and coding. This intentionally favors reliability and consistent tool use over the cheaper Codex tiers.

package/package.json

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

package/scripts/certify.mjs

@@ -23,11 +23,14 @@ run('diff whitespace check', 'git', ['diff', '--check'], repo)
 const watcher = readFileSync(join(root, 'src', 'watch.mjs'), 'utf8')
 const events = readFileSync(join(root, 'src', 'events.mjs'), 'utf8')
 const memory = readFileSync(join(root, 'src', 'memory.mjs'), 'utf8')
+const mcpHttp = readFileSync(join(root, 'src', 'mcp-http.mjs'), 'utf8')
+const opencodeConfig = readFileSync(join(root, 'src', 'opencode-config.mjs'), 'utf8')
 const prPush = readFileSync(join(root, 'src', 'pr-push.mjs'), 'utf8')
 const cli = readFileSync(join(root, 'bin', 'cli.mjs'), 'utf8')
 const websocket = readFileSync(join(root, 'src', 'ws.mjs'), 'utf8')
 const activityHook = readFileSync(join(repo, 'frontend', 'hooks', 'useAgentActivity.ts'), 'utf8')
 const taskHook = readFileSync(join(repo, 'frontend', 'hooks', 'useBackendTasks.ts'), 'utf8')
+const liveTasks = readFileSync(join(repo, 'frontend', 'lib', 'collab', 'liveTasks.ts'), 'utf8')
 const spec = readFileSync(join(repo, 'docs', 'CODEX_BYO_AGENT_SPEC.md'), 'utf8')
 
 const assertions = [
@@ -59,9 +62,20 @@ const assertions = [
   ['frontend consumes typing event', activityHook.includes("'channel:agent:typing'")],
   ['frontend activity TTL distinguishes work from typing', activityHook.includes('thinking: 6_000') && activityHook.includes('typing: 5_000') && activityHook.includes('working: 30_000')],
   ['frontend consumes documented task comment events', taskHook.includes("'task:comment':") && taskHook.includes("'task:comment_updated':") && taskHook.includes("'task:comment_deleted':") && taskHook.includes("'task:comment_reacted':")],
+  ['ticket comments load only on demand', !taskHook.includes('for (const task of tasks)') && taskHook.includes('loadedCommentIds.current.has(taskId)')],
+  ['concurrent ticket comment loads share one request', taskHook.includes('commentRequests.current.get(requestKey)') && taskHook.includes('commentRequests.current.set(requestKey, request)')],
+  ['backend ticket slugs render uppercase', liveTasks.includes("t.slug?.trim().toUpperCase()")],
   ['completion has an evidence failure gate', watcher.includes('WORK_CYCLE_FAILED')],
   ['OpenCode emits structured events for runtime evidence', watcher.includes("'--format', 'json'") && watcher.includes('opencodeEventEvidence(event)')],
+  ['OpenCode API-key MCP disables OAuth probing', opencodeConfig.includes("oauth: false") && opencodeConfig.includes('timeout: 15_000')],
+  ['OpenCode identities use isolated configs outside the code workspace', watcher.includes('opencodeRuntimeLayout({ cfgKey, workdir })') && watcher.includes("'--dir', workspace") && watcher.includes('OPENCODE_CONFIG: opencodeConfigPath') && watcher.includes('OPENCODE_CONFIG_CONTENT: JSON.stringify(opencodeConfig)')],
+  ['OpenCode backend prompts forbid relay-only tools', watcher.includes('BACKEND MCP RULE') && watcher.includes('get_marching_orders, poll_inbox, and get_resource are relay-only')],
+  ['OpenCode tool failures retain sanitized diagnostics', events.includes('toolError: toolError.replace') && watcher.includes("opencode tool '") && watcher.includes("split(redactKey).join('[redacted]')")],
   ['OpenCode acknowledgements cannot satisfy coding completion', watcher.includes("agent === 'codex' || agent === 'opencode'") && watcher.includes('releaseTaskForRetry(activeTaskRef, prompt)')],
+  ['backend MCP accepts stateless initialize responses', mcpHttp.includes("mode = () => !initialized ? 'uninitialized' : sessionId ? 'stateful' : 'stateless'") && !watcher.includes('MCP initialize returned no session id')],
+  ['MCP initialize is shared across concurrent startup probes', mcpHttp.includes('if (initializePromise) return initializePromise')],
+  ['stateless tool errors do not cause initialize loops', mcpHttp.includes('if (hadSession && !retried')],
+  ['backend introduction is watcher-owned for every runtime', watcher.includes('void announceIntroduction().then((delivered)')],
   ['Codex policy rejection is captured from stderr', watcher.includes("stdio: ['ignore', 'pipe', 'pipe']") && watcher.includes('forwardDiagnostic(d)') && watcher.includes('inspectDiagnostic(incoming)')],
   ['Codex recoverable subprocess diagnostics are not surfaced as activity', watcher.includes('shouldSuppressCodexDiagnostic(line)') && watcher.includes("forwardDiagnostic('', true)") && watcher.includes('RECOVER DEAD COMMAND SESSIONS')],
   ['policy rejection cannot be logged as successful', watcher.includes("subtype = policyBlock ? 'blocked'")],

package/src/events.mjs

@@ -89,6 +89,8 @@ export function opencodeEventEvidence(event) {
   const status = String(state.status ?? part.status ?? '').toLowerCase()
   const failed = /error|failed|denied|rejected/.test(status) || state.error != null || part.error != null
   const completed = !failed && (!status || /completed|success|succeeded|ok/.test(status))
+  const rawToolError = state.error ?? part.error
+  const toolError = rawToolError == null ? '' : (typeof rawToolError === 'string' ? rawToolError : JSON.stringify(rawToolError))
   const input = state.input && typeof state.input === 'object' ? state.input : (part.input && typeof part.input === 'object' ? part.input : {})
   const command = String(input.command ?? input.cmd ?? '')
 
@@ -107,6 +109,7 @@ export function opencodeEventEvidence(event) {
     ...(mcpTool ? { mcpTool } : {}),
     failed,
     completed,
+    ...(failed && toolError ? { toolError: toolError.replace(/\s+/g, ' ').slice(0, 500) } : {}),
     didCode: completed && (mutationTool || bashTool || codebaseMutation),
     didRepoMutation: completed && (mutationTool || codebaseMutation || (bashTool && commandMutation)),
     didMcpTaskRead: completed && /^(?:get_ticket|list_tasks|list_task_types)$/.test(mcpTool),

package/src/mcp-http.mjs

@@ -0,0 +1,85 @@
+const parsePayload = 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()
+  try { return JSON.parse(data || body || '{}') }
+  catch { throw new Error('MCP returned a non-JSON response') }
+}
+
+// Streamable HTTP permits both stateful servers (initialize returns
+// Mcp-Session-Id) and stateless servers (no session header). The backend agent
+// MCP is deployed in both forms, so absence of a session id is a transport mode,
+// not an initialization failure.
+export function createMcpHttpClient({ url, apiKey, identifier, clientVersion, fetchImpl = fetch, log = () => {} }) {
+  let initialized = false
+  let sessionId = ''
+  let rpcId = 0
+  let initializePromise = null
+
+  const post = (message, withSession = true) => fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      'x-agent-api-key': apiKey,
+      'x-agent-identifier': identifier,
+      ...(withSession && sessionId ? { 'mcp-session-id': sessionId } : {}),
+    },
+    body: JSON.stringify(message),
+  })
+
+  const reset = () => { initialized = false; sessionId = '' }
+
+  const initialize = () => {
+    if (initialized) return Promise.resolve()
+    if (initializePromise) return initializePromise
+    initializePromise = (async () => {
+      const res = await post({
+        jsonrpc: '2.0',
+        id: ++rpcId,
+        method: 'initialize',
+        params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'openvisio-agent', version: clientVersion } },
+      }, false)
+      if (!res.ok) throw new Error('MCP initialize HTTP ' + res.status)
+      const payload = await parsePayload(res)
+      if (payload.error) throw new Error(`MCP initialize: ${payload.error.message || 'protocol error'}`)
+      sessionId = res.headers.get('mcp-session-id') || ''
+
+      const ready = await post({ jsonrpc: '2.0', method: 'notifications/initialized' })
+      if (!ready.ok) { reset(); throw new Error('MCP initialized HTTP ' + ready.status) }
+      initialized = true
+      if (!sessionId) log('MCP initialized in stateless mode (no session id required)')
+    })().finally(() => { initializePromise = null })
+    return initializePromise
+  }
+
+  const callTool = async (name, args = {}, retried = false) => {
+    await initialize()
+    const hadSession = !!sessionId
+    const res = await post({
+      jsonrpc: '2.0',
+      id: ++rpcId,
+      method: 'tools/call',
+      params: { name, arguments: { ...args, agent_api_key: apiKey, agent_identifier: identifier } },
+    })
+    if (!res.ok) {
+      // Only a stateful transport can have an expired session. A stateless 4xx
+      // belongs to the tool request itself and must not trigger an initialize loop.
+      if (hadSession && !retried && [400, 404, 409, 410].includes(res.status)) {
+        reset()
+        return callTool(name, args, true)
+      }
+      throw new Error(`MCP ${name} HTTP ${res.status}`)
+    }
+    const payload = await parsePayload(res)
+    if (payload.error) throw new Error(`MCP ${name}: ${payload.error.message || 'tool error'}`)
+    const result = payload.result ?? payload
+    if (result?.isError) {
+      const detail = String(result.content?.find?.((item) => item?.type === 'text')?.text || 'tool error').split(apiKey).join('[redacted]')
+      throw new Error(`MCP ${name}: ${detail}`)
+    }
+    return result
+  }
+
+  const mode = () => !initialized ? 'uninitialized' : sessionId ? 'stateful' : 'stateless'
+  return { callTool, initialize, reset, mode }
+}

package/src/opencode-config.mjs

@@ -0,0 +1,29 @@
+import { join } from 'node:path'
+import { OV_DIR, slugify } from './lib.mjs'
+
+export function opencodeRuntimeLayout({ cfgKey, workdir, baseDir = OV_DIR }) {
+  const agentKey = slugify(String(cfgKey || 'agent')) || 'agent'
+  const configDir = join(baseDir, 'opencode-' + agentKey)
+  return {
+    configDir,
+    configPath: join(configDir, 'opencode.json'),
+    workspace: workdir || configDir,
+  }
+}
+
+export function buildOpencodeConfig({ mcpUrl, mcpHeaders }) {
+  if (!mcpUrl) return null
+  return {
+    $schema: 'https://opencode.ai/config.json',
+    mcp: {
+      'openvisio-team': {
+        type: 'remote',
+        url: mcpUrl,
+        enabled: true,
+        oauth: false,
+        timeout: 15_000,
+        ...(mcpHeaders && Object.keys(mcpHeaders).length ? { headers: mcpHeaders } : {}),
+      },
+    },
+  }
+}

package/src/watch.mjs

@@ -13,6 +13,8 @@ import { connectAgentWs, assertWebSocket } from './ws.mjs'
 import { agentStateRequest, buildTaskCompletionReport, codexPolicyBlock, mentionDedupeKeys, normalizeRenderedMessageText, opencodeEventEvidence, renderedAgentMessages, requestTargetsLaterAgent, shouldSuppressCodexDiagnostic, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted } from './events.mjs'
 import { createByoMemoryGraph } from './memory.mjs'
 import { repositoryHasPrPushAuthorization } from './pr-push.mjs'
+import { createMcpHttpClient } from './mcp-http.mjs'
+import { buildOpencodeConfig, opencodeRuntimeLayout } from './opencode-config.mjs'
 
 // Behaviour prompts. The openvisio-team MCP bridge requires the agent's
 // credentials as ARGUMENTS on every tool call — those are injected at runtime by
@@ -288,25 +290,25 @@ export async function runWatch({ flags }) {
 // ── opencode cycle runner ─────────────────────────────────────────────────────
 // opencode (opencode.ai) has no persistent stream-json protocol like Claude Code,
 // so each cycle is a headless `opencode run <prompt> --auto [--model provider/model]`.
-// The openvisio-team MCP is declared in an `opencode.json` written into the run cwd
-// (opencode reads it from there). `--auto` approves tool use non-interactively.
+// The openvisio-team MCP is declared in a private per-agent config. The actual
+// code workspace is passed through --dir, so two agents never overwrite each
+// other's MCP identity even when they work in the same repository.
+// `--auto` approves tool use non-interactively.
 // Same { runCycle, canCode } contract as the Claude runner.
 function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, onTool, systemPrompt }) {
-  // opencode reads opencode.json from its CWD: the code workspace, or a dedicated
-  // per-agent dir for chat-only agents.
-  const cwd = workdir || join(OV_DIR, 'opencode-' + (cfgKey || 'agent'))
+  const { configDir, configPath: opencodeConfigPath, workspace } = opencodeRuntimeLayout({ cfgKey, workdir })
   const bin = onPath('opencode') || 'opencode'
+  const redactKey = String(mcpHeaders?.['x-agent-api-key'] || '')
+  const opencodeConfig = buildOpencodeConfig({ mcpUrl, mcpHeaders })
   let configured = false
   const ensureConfig = () => {
     if (configured) return
     configured = true
     try {
-      mkdirSync(cwd, { recursive: true })
-      if (mcpUrl) {
-        writeJson(join(cwd, 'opencode.json'), {
-          $schema: 'https://opencode.ai/config.json',
-          mcp: { 'openvisio-team': { type: 'remote', url: mcpUrl, enabled: true, ...(mcpHeaders && Object.keys(mcpHeaders).length ? { headers: mcpHeaders } : {}) } },
-        }, true)
+      mkdirSync(configDir, { recursive: true })
+      mkdirSync(workspace, { recursive: true })
+      if (opencodeConfig) {
+        writeJson(opencodeConfigPath, opencodeConfig, true)
       } else {
         log('WARNING: no --mcp-url — opencode has no openvisio-team tools to act with. Re-connect with --mcp-url.')
       }
@@ -322,7 +324,7 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
       const full = systemPrompt ? systemPrompt + '\n\n' + prompt : prompt
       // JSON mode is the evidence boundary. Formatted stdout only tells us that
       // OpenCode exited; raw events tell us which tools actually completed.
-      const args = ['run', full, '--auto', '--format', 'json', ...(m ? ['--model', m] : [])]
+      const args = ['run', full, '--auto', '--format', 'json', '--dir', workspace, ...(m ? ['--model', m] : [])]
       let child = null, done = false, didCode = false, didRepoMutation = false, didMessage = false, didChannelMessage = false, didMcpTaskRead = false, didMcpTaskUpdate = false
       let outputText = '', jsonlBuffer = ''
       const mcpCalls = new Set(), mcpErrors = new Set(), runtimeErrors = new Set()
@@ -350,6 +352,10 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
         if (evidence.runtimeError) runtimeErrors.add(evidence.runtimeError)
         if (!evidence.tool) return
         if (debug) log('  → tool ' + evidence.tool + (evidence.failed ? ' (failed)' : evidence.completed ? ' (completed)' : ''))
+        if (evidence.failed && evidence.toolError) {
+          const safeError = (redactKey ? String(evidence.toolError).split(redactKey).join('[redacted]') : String(evidence.toolError)).replace(/\s+/g, ' ').slice(0, 240)
+          log('  ✗ opencode tool ' + evidence.tool + ': ' + safeError)
+        }
         try { onTool && onTool(evidence.tool) } catch { /* activity is best-effort */ }
         if (evidence.mcpTool) {
           mcpCalls.add(evidence.mcpTool)
@@ -370,7 +376,18 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
       }, maxCycleMs)
       log('running opencode cycle…' + (m ? ' [' + m + ']' : ''))
       try {
-        child = spawn(bin, args, { cwd, stdio: ['ignore', 'pipe', 'inherit'] })
+        child = spawn(bin, args, {
+          cwd: configDir,
+          env: {
+            ...process.env,
+            OPENCODE_CONFIG: opencodeConfigPath,
+            // Inline config has higher precedence than a project opencode.json.
+            // This prevents a stale generated workspace file from replacing this
+            // agent's URL or credentials while keeping normal project settings.
+            ...(opencodeConfig ? { OPENCODE_CONFIG_CONTENT: JSON.stringify(opencodeConfig) } : {}),
+          },
+          stdio: ['ignore', 'pipe', 'inherit'],
+        })
         child.stdout?.on('data', (data) => {
           jsonlBuffer += String(data)
           const lines = jsonlBuffer.split('\n')
@@ -389,7 +406,7 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
     })
   }
 
-  log('opencode runner ready' + (model ? ' [model ' + model + ']' : '') + (canCode ? ' [CODE workspace ' + cwd + ']' : ' [CHAT-ONLY — cfg ' + cwd + ']'))
+  log('opencode runner ready' + (model ? ' [model ' + model + ']' : '') + (canCode ? ' [CODE workspace ' + workspace + '; isolated cfg ' + configDir + ']' : ' [CHAT-ONLY; isolated cfg ' + configDir + ']'))
   return { runCycle, canCode }
 }
 
@@ -670,7 +687,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   const canCode = !!workdir
   // The Mastra bridge authenticates per-CALL: every openvisio-team tool needs
   // agent_identifier + agent_api_key as arguments. Hand them over up front.
-  const credNote = `AUTH: the 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. Use ONLY names shown in the current tool list. On backend MCP, discover and update work with list_agents, list_projects, list_tasks, get_ticket, update_ticket, comment_ticket, and list_activity; get_marching_orders and poll_inbox may be absent. Tools may be namespaced — call whichever names actually appear. The credentials are given here; do NOT hunt for them. Bash/git/gh ARE for code work; this rule only forbids searching for keys.`
+  const credNote = `AUTH: the 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. Use ONLY names shown in the current tool list. On backend MCP, discover and update work with list_agents, list_projects, list_tasks, list_task_types, get_ticket, update_ticket, comment_ticket, list_channels, list_message_thread, and list_activity as applicable. get_marching_orders, poll_inbox, and get_resource are relay-only and are NOT available here; never call them. Tools may be namespaced — call whichever names actually appear. The credentials are given here; do NOT hunt for them. Bash/git/gh ARE for code work; this rule only forbids searching for keys.`
   // The STATIC charter + creds are the session system prompt (cached, billed once),
   // NOT re-sent in every cycle's user message — the big token saving.
   const systemPrompt = (canCode ? CODE_CHARTER : CHAT_CHARTER) + '\n\n' + credNote
@@ -687,8 +704,10 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   const codexPushGuide = agent === 'codex' && canCode
     ? '\n\nCODEX PR DELIVERY: first inspect the OpenVisio MCP tools. When list_codebases, create_codebase_branch, create_codebase_commit (or write_codebase_file), and create_pull_request are available, use that authenticated linked-codebase flow to create the agent/* branch, publish the verified changed files, and open the PR. This is the preferred path and requires no local git push. If those tools are unavailable for the repository, do not run git push directly. From the repository run `openvisio-agent push-pr-branch`. It is a user-authorized constrained fallback that can only push HEAD to the matching agent/* branch on the exact authorized origin. If it reports OPENVISIO_PR_PUSH_AUTH_REQUIRED, do not retry or route around it. Report the one-time command `openvisio-agent authorize-pr-push` as the blocker.'
     : ''
-  const fullPrompt = canCode ? CODE_FULL + codexPushGuide : CYCLE
-  const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
+  const backendToolRule = 'BACKEND MCP RULE: the event and watcher already provide the work source. Never call get_marching_orders, poll_inbox, get_resource, or other relay-only tools; they are not exposed by the backend MCP. Use only names present in the current openvisio-team tool list. For discovery use list_agents, list_projects, list_tasks, list_task_types, list_activity, get_ticket, and list_channels as applicable.'
+  const fullPrompt = (canCode ? CODE_FULL + codexPushGuide : 'Handle the supplied verified backend ticket with the available OpenVisio tools. Update or comment on the ticket as requested, do not claim repository work in chat-only mode, and stop after the verified action.') + '\n\n' + backendToolRule
+  const fastPrompt = (canCode ? CODE_FAST : CYCLE_FAST) + '\n\n' + backendToolRule
+  const coordinatePrompt = COORDINATE + '\n\n' + backendToolRule
   // Live model state — changeable at runtime by the in-chat `/model` command.
   // codeModel drives full/sweep cycles; chatModel (if set) the lighter fast/intro
   // ones, so routine chatter can run cheaper than real code work.
@@ -768,54 +787,8 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   let lastTaskTriggeredAt = 0
   let lastInboxSignature = ''
   let selfAgentId = null
-  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.18.1' } } }, 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'}`)
-    const result = payload.result ?? payload
-    if (result?.isError) {
-      const detail = String(result.content?.find?.((c) => c?.type === 'text')?.text || 'tool error').split(apiKey).join('[redacted]')
-      throw new Error(`MCP ${name}: ${detail}`)
-    }
-    return result
-  }
+  const mcpClient = createMcpHttpClient({ url: mcpUrl, apiKey, identifier, clientVersion: '0.18.2', log })
+  const callMcpTool = (name, args = {}) => mcpClient.callTool(name, args)
   const toolData = (result) => {
     const text = result?.content?.find?.((c) => c?.type === 'text')?.text
     if (typeof text !== 'string') return result?.structuredContent ?? result ?? {}
@@ -1144,14 +1117,14 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         }
       } else if (!mentionActivity.length) lastInboxSignature = ''
     } catch (e) {
-      mcpSessionId = ''
+      mcpClient.reset()
       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 }
-  const baseFor = (kind) => kind === 'intro' ? INTRO : kind === 'full' ? fullPrompt : (kind === 'coord' || kind === 'sweep') ? COORDINATE : fastPrompt
+  const baseFor = (kind) => kind === 'intro' ? INTRO : kind === 'full' ? fullPrompt : (kind === 'coord' || kind === 'sweep') ? coordinatePrompt : fastPrompt
   // Codex and OpenCode expose structured action streams. Require runtime facts
   // from those streams before accepting a full coding cycle. Claude's evidence
   // shape is different and remains on its existing completion path.
@@ -1473,8 +1446,8 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       const replyDelivery = guardedDelivery(codingMention ? 'result' : 'reply', !codingMention)
       const ctx = cid != null
         ? replyDelivery
-          ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU. ${codingMention ? 'Complete the repository work and verification first.' : 'Answer the request.'} Do NOT call post_message; it is intentionally unavailable. Return only the final 1-3 sentence reply as your final answer. The watcher will read the real thread, check its persistent memory graph, and render that answer at most once.${who ? ` To mention the requester, use their exact full name "@${who}".` : ''} Do not poll_inbox.`
-          : `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU. ${codingMention ? 'This is repository work: complete the coding flow first, then send' : 'Send'} EXACTLY ONE reply with post_message: arguments: channel_id ${cid}${threadRoot != null ? `, parent_id ${threadRoot} (reply IN THAT THREAD, do not start a new top-level message)` : ''}, plus agent_identifier + agent_api_key from the AUTH line above, and a 1-3 sentence reply. Compose the whole answer, then post it ONCE. Do not post a first reply and then a revised version. FIRST read the recent messages in this thread: if you already answered this, or another agent was the one addressed, do NOT post at all. Be sure of your answer before sending.${who ? ` To @mention them back, write their EXACT full name "@${who}". A mention only links when the name matches exactly.` : ''} You ALREADY have the message here. Do not poll_inbox, and after your single reply, STOP.`
+          ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU. ${codingMention ? 'Complete the repository work and verification first.' : 'Answer the request.'} Do NOT call post_message; it is intentionally unavailable. Return only the final 1-3 sentence reply as your final answer. The watcher will read the real thread, check its persistent memory graph, and render that answer at most once.${who ? ` To mention the requester, use their exact full name "@${who}".` : ''} The complete message is already here; do not call get_resource, get_marching_orders, or poll_inbox.`
+          : `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU. ${codingMention ? 'This is repository work: complete the coding flow first, then send' : 'Send'} EXACTLY ONE reply with post_message: arguments: channel_id ${cid}${threadRoot != null ? `, parent_id ${threadRoot} (reply IN THAT THREAD, do not start a new top-level message)` : ''}, plus agent_identifier + agent_api_key from the AUTH line above, and a 1-3 sentence reply. Compose the whole answer, then post it ONCE. Do not post a first reply and then a revised version. FIRST read the recent messages in this thread: if you already answered this, or another agent was the one addressed, do NOT post at all. Be sure of your answer before sending.${who ? ` To @mention them back, write their EXACT full name "@${who}". A mention only links when the name matches exactly.` : ''} The complete message is already here. Do not call get_resource, get_marching_orders, or poll_inbox, and after your single reply, STOP.`
         : undefined
       if (codingMention) {
         if (agent === 'codex' && cid != null) {
@@ -1509,12 +1482,8 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     // 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)) {
-      if (agent !== 'codex') {
-        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(() => {
-        if (agent !== 'codex') { void drain('intro'); return }
         void announceIntroduction().then((delivered) => {
           if (!delivered) return
           try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(introMarker, new Date().toISOString() + '\n') } catch { /* best-effort */ }