openvisio-agent 0.18.0 → 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.
@@ -69,7 +71,16 @@ openvisio-agent watch --name ada --workdir ~/repo  # allow REAL work on a git br
 openvisio-agent stop --name ada                  # stop service + every ada watcher
 ```
 
-With `--workdir`, the agent gets file + Bash tools scoped to that repo and works on a branch. Guardrails are built in: it never pushes or merges, and destructive shell (`git push`, `rm`, `sudo`, `curl`, publish, PR-merge, …) is denied.
+With `--workdir`, the agent gets file + shell tools scoped to the workspace and works on an `agent/*` branch. For a codebase linked to OpenVisio, Codex first uses the authenticated MCP branch, commit, and pull-request tools. That creates the PR through the existing integration and avoids a local `git push`.
+
+When those linked-codebase tools are unavailable, a pull request still requires exporting the local branch to the private Git remote. The constrained fallback uses an explicit, one-time authorization per repository:
+
+```bash
+cd /path/to/private-repo
+openvisio-agent authorize-pr-push
+```
+
+That command installs a narrow Codex rule for `openvisio-agent push-pr-branch` and records the repository's exact root and `origin`. The helper accepts no arguments and can only push `HEAD` to the same `agent/*` branch on that authorized origin. It disables repository hooks and rejects main/master, other branch namespaces, changed remotes, force pushes, local/file remotes, and credential-bearing URLs. Revoke it from the repository with `openvisio-agent revoke-pr-push`.
 
 `--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).
 
@@ -79,7 +90,7 @@ Do not chase auto-changing watcher PIDs. `openvisio-agent stop --name <agent>` u
 
 - **No opaque script.** You run a named, versioned npm package you can read here and on [npmjs.com](https://www.npmjs.com/package/openvisio-agent).
 - **Single-use code.** The `ovs_` code is exchanged once for a key; a leaked code is already spent.
-- **Least privilege.** Chat mode exposes only the `openvisio-team` MCP tools. Coding mode is opt-in per repo, branch-only, with a shell denylist.
+- **Least privilege.** Chat mode exposes only the `openvisio-team` MCP tools. Codex private-repository pushes require an explicit per-repository opt-in and go through a no-argument `agent/*`-only helper; merges and protected-branch pushes remain unavailable.
 - **Local secrets.** Your agent key lives in `~/.openvisio/` with `600` permissions — never printed, never committed.
 
 ## Requirements

package/bin/cli.mjs

@@ -15,6 +15,7 @@ import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, ensureCodex, writeJson, mcpConfigPath, configPath, chmodSafe, onPath, OV_DIR, fail, ok, info } from '../src/lib.mjs'
 import { runWatch, installService, stopWatchers } from '../src/watch.mjs'
+import { authorizePrPush, pushPrBranch, revokePrPush } from '../src/pr-push.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const VERSION = (() => { try { return JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version } catch { return '0.0.0' } })()
@@ -28,6 +29,9 @@ Usage:
   openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>] [--agent claude|codex|opencode]
   openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--model <m>] [--chat-model <m>] [--debug]
   openvisio-agent stop    --name <agent>
+  openvisio-agent authorize-pr-push [--repo <dir>]
+  openvisio-agent push-pr-branch
+  openvisio-agent revoke-pr-push [--repo <dir>]
   openvisio-agent --help | --version
 
 connect
@@ -78,6 +82,19 @@ stop
   remaining watcher with that exact --name and clears its stale lock. Use this
   instead of killing changing PIDs: openvisio-agent stop --name Alex
 
+authorize-pr-push
+  One-time, explicit authorization for the current private repository. Installs a
+  narrow Codex command rule and records the exact repository root + origin. The
+  permitted helper can only push the current agent/* branch and cannot force-push,
+  choose another remote/ref, push a protected branch, or merge.
+
+push-pr-branch
+  Pushes HEAD to the same agent/* branch on an origin previously authorized with
+  authorize-pr-push. Intended for Codex work cycles; accepts no arguments.
+
+revoke-pr-push
+  Removes the current repository from the helper's authorization list.
+
 Docs: https://www.npmjs.com/package/openvisio-agent`
 
 // Register the `openvisio-team` MCP at USER (global) scope so it's available in
@@ -291,6 +308,29 @@ async function main() {
     if (!name) fail('Missing agent name.\n  Usage: openvisio-agent stop --name <agent>')
     return stopWatchers({ slug: slugify(name) })
   }
+  if (cmd === 'authorize-pr-push') {
+    const cwd = String(rest.flags.repo || rest.positional[0] || process.cwd())
+    const result = authorizePrPush({ cwd })
+    ok('Authorized constrained PR-branch pushes for this repository.')
+    info(`Repository: ${result.root}`)
+    info(`Origin: ${result.remote}`)
+    info('Codex can now run: openvisio-agent push-pr-branch')
+    info('This does not allow pushes to main/master, force pushes, arbitrary remotes, or merges.')
+    return
+  }
+  if (cmd === 'push-pr-branch') {
+    if (rest.positional.length || Object.keys(rest.flags).length) fail('push-pr-branch accepts no arguments. It uses the current repository, origin, and agent/* branch.')
+    const result = pushPrBranch()
+    ok(`Pushed ${result.branch} to its matching origin branch.`)
+    return
+  }
+  if (cmd === 'revoke-pr-push') {
+    const cwd = String(rest.flags.repo || rest.positional[0] || process.cwd())
+    const result = revokePrPush({ cwd })
+    if (result.revoked) ok(`Revoked constrained PR pushes for ${result.root}.`)
+    else info(`No PR-push authorization was stored for ${result.root}.`)
+    return
+  }
   fail(`Unknown command "${cmd}".\n\n${HELP}`)
 }
 

package/package.json

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

@@ -21,9 +21,16 @@ run('package dry run', 'npm', ['pack', '--dry-run'])
 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 = [
@@ -31,13 +38,19 @@ const assertions = [
   ['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)')],
   ['review handoff releases the task key for future rework', watcher.includes('seenTasks.delete(taskKey)') && watcher.includes('seenTasks.delete(key)')],
-  ['assigned coding completion is posted by the watcher', watcher.includes('announceTaskCompletion') && watcher.includes("callMcpTool('post_message', { project_id: projectId, channel_id: channelId, content: report.content })")],
+  ['assigned coding completion is posted by the watcher', watcher.includes('announceTaskCompletion') && watcher.includes('postMessageOnce({ key: `completion:${report.key}`')],
   ['completion requires review/done state and PR evidence', watcher.includes('buildTaskCompletionReport') && watcher.includes('completion report deferred')],
   ['completion delivery survives reconnect and deduplicates', watcher.includes('pendingCompletionReports: [...pendingCompletionReports]') && watcher.includes('reportedCompletions: [...reportedCompletions]') && watcher.includes('reportedCompletions.has(report.key)')],
   ['verified completion is persisted as one ticket comment', watcher.includes("callMcpTool('comment_ticket', { project_id: projectId, ticket_id: ticketId, text: report.content })") && watcher.includes('reportedTaskComments: [...reportedTaskComments]') && watcher.includes('reportedTaskComments.has(report.key)')],
   ['ticket comments cannot masquerade as channel completion', watcher.includes('didChannelMessage') && watcher.includes("mcpCalls.includes('post_message')")],
   ['single-watcher acquisition is atomic and fails closed', watcher.includes("openSync(lockPath, 'wx')") && watcher.includes('Could not acquire the single-watcher lock')],
   ['websocket and activity mention delivery share a replay guard', watcher.includes('markMentionHandled(activityMessage, activityChannelId)') && watcher.includes('markMentionHandled(msg, cid)') && watcher.includes('recentMentionSignatures')],
+  ['reconciled mentions reuse the guarded websocket delivery path', watcher.includes("onEvent('agent:mention'") && watcher.includes('_mentionAlreadyMarked: true')],
+  ['rendered backend replies are checked before every guarded thread post', watcher.includes("callMcpTool('list_message_thread'") && watcher.includes('renderedAgentMessages(live') && watcher.includes('same-content-rendered')],
+  ['Codex cannot race the watcher with post_message', watcher.includes("disabledMcpTools: ['post_message']") && watcher.includes('disabled_tools = [')],
+  ['reply delivery keys survive reconnects', watcher.includes('deliveredReplies: [...deliveredReplies]') && watcher.includes('deliveredReplies.has(deliveryKey)')],
+  ['guarded replies stay independent while a lane is busy', watcher.includes('lane.deferred.push') && watcher.includes('lane.deferred.shift()')],
+  ['BYO memory uses real ticket and thread identities', watcher.includes('createByoMemoryGraph') && watcher.includes('memory.context(memoryRefs)') && memory.includes('sameRef(r.projectId, refs.projectId)') && memory.includes('sameRef(r.threadId, refs.threadId)')],
   ['two internal lanes exist', watcher.includes('work: createCycleRunner') && watcher.includes('reply: createCycleRunner')],
   ['work and reply activity targets are isolated', watcher.includes("laneStatusTargets = { work: new Set(), reply: new Set() }") && watcher.includes("emitLaneStatus('work', 'typing')") && watcher.includes("emitLaneStatus('reply', 'typing')")],
   ['assigned task activity resolves a project channel', watcher.includes("callMcpTool('list_channels'") && watcher.includes('projectStatusChannel(projectId)')],
@@ -49,13 +62,29 @@ 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'")],
   ['policy-blocked tickets are persisted and paused', watcher.includes('blockedTasks: [...blockedTasks]') && watcher.includes('WORK_CYCLE_BLOCKED')],
+  ['repository push authorization automatically resumes the paused ticket', watcher.includes('blockedTaskRepos: [...blockedTaskRepos]') && watcher.includes('repositoryHasPrPushAuthorization')],
+  ['Codex prefers linked-codebase MCP PR delivery', watcher.includes('CODEX PR DELIVERY') && watcher.includes('create_codebase_branch/create_codebase_commit/create_pull_request') && events.includes('const codebaseMutation')],
+  ['private PR pushes use an explicit constrained helper', cli.includes("cmd === 'authorize-pr-push'") && cli.includes("cmd === 'push-pr-branch'") && prPush.includes("'push', '-u', 'origin', destination")],
+  ['PR push helper rejects protected/alternate/force targets by construction', prPush.includes("/^agent\\/") && prPush.includes('entry?.root === root && entry?.remote === remote') && prPush.includes('accepts no force, remote, or ref args')],
+  ['Codex recognizes helper authorization as a blocker', events.includes('OPENVISIO_PR_PUSH_AUTH_REQUIRED') && watcher.includes("block?.kind === 'pr-push-authorization-required'")],
   ['policy blocker is surfaced to the user', watcher.includes('reportPolicyBlock(prompt, activeTaskRef, result.policyBlock)') && watcher.includes("Action required: I'm blocked")],
   ['blocker routing carries explicit task identity', watcher.includes('taskRefs: []') && watcher.includes('activeTaskRef') && watcher.includes('taskRef: activeTaskRef')],
   ['all runtime blockers have a delivery path', watcher.includes('publishBlocker') && watcher.includes('WORK_CYCLE_BLOCKED') && watcher.includes('COORDINATION_CYCLE_BLOCKED')],

package/src/events.mjs

@@ -89,14 +89,17 @@ 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 ?? '')
 
   const lowerTool = tool.toLowerCase()
   const prefixed = /^(?:mcp__)?openvisio(?:-team|_team)(?:__|[_.:/-])(.+)$/i.exec(tool)
   const bareTool = lowerTool.replace(/[-.]/g, '_')
-  const knownMcp = /^(?:get_ticket|list_tasks|list_task_types|update_ticket|post_message|comment_ticket|react_message|list_projects|list_agents|list_activity)$/
+  const knownMcp = /^(?:get_ticket|list_tasks|list_task_types|update_ticket|post_message|comment_ticket|react_message|list_projects|list_agents|list_activity|list_codebases|create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/
   const mcpTool = (prefixed?.[1] ? prefixed[1].replace(/[-.]/g, '_') : (knownMcp.test(bareTool) ? bareTool : '')).toLowerCase()
+  const codebaseMutation = /^(?:create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/.test(mcpTool)
   const mutationTool = /^(?:edit|write|patch|apply_patch|multiedit|multi_edit)$/i.test(tool)
   const bashTool = /^(?:bash|shell|terminal|exec|command)$/i.test(tool)
   const commandMutation = /\b(?:git\s+(?:commit|push)|gh\s+pr\s+create)\b/i.test(command)
@@ -106,8 +109,9 @@ export function opencodeEventEvidence(event) {
     ...(mcpTool ? { mcpTool } : {}),
     failed,
     completed,
-    didCode: completed && (mutationTool || bashTool),
-    didRepoMutation: completed && (mutationTool || (bashTool && commandMutation)),
+    ...(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),
     didMcpTaskUpdate: completed && mcpTool === 'update_ticket',
     didMessage: completed && /^(?:post_message|comment_ticket)$/.test(mcpTool),
@@ -131,6 +135,16 @@ export function agentStateRequest(backend, channelId, state, apiKey, identifier)
 
 export function codexPolicyBlock(value) {
   const text = String(value || '')
+  if (/OPENVISIO_PR_PUSH_AUTH_REQUIRED/i.test(text)) {
+    const root = /From\s+([^\n,]+),\s*run:\s*openvisio-agent authorize-pr-push/i.exec(text)?.[1]?.trim() || ''
+    return {
+      kind: 'pr-push-authorization-required',
+      command: 'openvisio-agent push-pr-branch',
+      reason: 'The repository has not received the one-time constrained PR-branch authorization.',
+      root,
+      setupCommand: 'openvisio-agent authorize-pr-push',
+    }
+  }
   if (!/rejected due to unacceptable risk|action was rejected due to unacceptable risk|explicitly approves? the action/i.test(text)) return null
   const command = /exec_command failed for [`']([^`']+)[`']/.exec(text)?.[1] || ''
   const reasonTail = text.split(/Reason:\s*/i)[1] || ''
@@ -172,6 +186,54 @@ export function mentionDedupeKeys(message, channelId) {
   }
 }
 
+export function normalizeRenderedMessageText(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim().toLowerCase()
+}
+
+// Extract only messages visibly authored by this agent from the backend's live
+// thread response. REST and WebSocket payloads use several sender shapes, so this
+// mirrors the frontend normalizer instead of trusting one field name.
+export function renderedAgentMessages(value, identity = {}) {
+  const rows = []
+  const seen = new Set()
+  const visit = (node, depth = 0) => {
+    if (depth > 6 || node == null) return
+    if (Array.isArray(node)) { for (const item of node) visit(item, depth + 1); return }
+    if (typeof node !== 'object') return
+    const row = node
+    const content = row.content ?? row.body ?? row.text ?? (typeof row.message === 'string' ? row.message : undefined)
+    const rowId = row.id ?? row.message_id ?? row.messageId
+    if (content != null && rowId != null) {
+      const sender = [row.sender, row.user, row.author, row.member].find((item) => item && typeof item === 'object') || {}
+      const expanded = [row.senderAgent, row.sender_agent, row.agent, sender.agent].find((item) => item && typeof item === 'object')
+      const senderKind = String(sender.type ?? sender.kind ?? sender.sender_type ?? row.sender_type ?? row.author_type ?? '').toLowerCase()
+      const senderLooksLikeAgent = /agent|bot/.test(senderKind) || sender.agent_id != null || sender.identifier != null || (sender.slug != null && !sender.email)
+      const agent = expanded || (senderLooksLikeAgent ? sender : {})
+      const agentId = Number(agent.id ?? agent.agent_id ?? row.agent_id ?? row.sender_agent_id ?? row.senderAgentId ?? NaN)
+      const identifier = String(agent.identifier ?? agent.slug ?? row.agent_identifier ?? row.sender_identifier ?? '')
+      const name = String(agent.name ?? agent.display_name ?? (senderLooksLikeAgent ? sender.name : '') ?? '')
+      const aliases = new Set([identity.identifier, identity.slug, identity.name].map((item) => String(item || '').toLowerCase()).filter(Boolean))
+      const isSelf = (Number.isFinite(Number(identity.id)) && agentId === Number(identity.id)) || aliases.has(identifier.toLowerCase()) || (!!expanded && aliases.has(name.toLowerCase()))
+      if (isSelf) {
+        const key = String(rowId)
+        if (!seen.has(key)) {
+          seen.add(key)
+          rows.push({
+            id: rowId,
+            parentId: row.parent_id ?? row.parentId ?? row.thread_id ?? null,
+            content: String(content),
+          })
+        }
+      }
+    }
+    for (const key of ['messages', 'replies', 'items', 'data', 'result', 'thread', 'message']) {
+      if (row[key] && typeof row[key] === 'object') visit(row[key], depth + 1)
+    }
+  }
+  visit(value)
+  return rows
+}
+
 // A mention event means this agent's name appeared somewhere, not necessarily
 // that the request was addressed to it. Reject a later-agent hand-off before a
 // model starts, while keeping explicitly shared requests addressed to both.

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/memory.mjs

@@ -0,0 +1,82 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const clean = (value, max = 320) => String(value || '').replace(/\s+/g, ' ').trim().slice(0, max)
+const sameRef = (a, b) => a != null && b != null && String(a) === String(b)
+
+// Small, deterministic memory graph for BYO watchers. Nodes are real events,
+// tickets and deliveries; edges record what a reply answered or where a task was
+// reported. It is intentionally not an LLM transcript or vector store: stable
+// backend ids make exact recall cheaper and prevent old work from being replayed.
+export function createByoMemoryGraph({ path, maxNodes = 1000, now = () => Date.now() }) {
+  let raw = {}
+  try { raw = JSON.parse(readFileSync(path, 'utf8')) } catch { /* first run */ }
+  const nodes = new Map((Array.isArray(raw.nodes) ? raw.nodes : []).filter((node) => node?.key).map((node) => [String(node.key), node]))
+  const edges = new Map((Array.isArray(raw.edges) ? raw.edges : []).filter((edge) => edge?.from && edge?.to && edge?.relation).map((edge) => [`${edge.from}|${edge.relation}|${edge.to}`, edge]))
+
+  const persist = () => {
+    try {
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(path, JSON.stringify({ version: 1, nodes: [...nodes.values()], edges: [...edges.values()] }, null, 2) + '\n', { mode: 0o600 })
+    } catch { /* memory is best-effort; live backend checks remain authoritative */ }
+  }
+  const trim = () => {
+    if (nodes.size <= maxNodes) return
+    const oldest = [...nodes.values()].sort((a, b) => Number(a.updatedAt || 0) - Number(b.updatedAt || 0)).slice(0, nodes.size - maxNodes)
+    const removed = new Set(oldest.map((node) => String(node.key)))
+    for (const key of removed) nodes.delete(key)
+    for (const [key, edge] of edges) if (removed.has(String(edge.from)) || removed.has(String(edge.to))) edges.delete(key)
+  }
+
+  const remember = ({ key, kind, state, summary, refs = {}, meta = {} }) => {
+    const id = String(key || '')
+    if (!id) return null
+    const previous = nodes.get(id)
+    const stamp = now()
+    const node = {
+      ...(previous || { key: id, createdAt: stamp }),
+      kind: clean(kind, 40) || previous?.kind || 'event',
+      state: clean(state, 40) || previous?.state || 'observed',
+      summary: clean(summary) || previous?.summary || '',
+      refs: { ...(previous?.refs || {}), ...refs },
+      meta: { ...(previous?.meta || {}), ...meta },
+      updatedAt: stamp,
+    }
+    nodes.set(id, node); trim(); persist()
+    return node
+  }
+
+  const connect = (from, to, relation) => {
+    const edge = { from: String(from || ''), to: String(to || ''), relation: clean(relation, 50), updatedAt: now() }
+    if (!edge.from || !edge.to || !edge.relation) return null
+    edges.set(`${edge.from}|${edge.relation}|${edge.to}`, edge); persist()
+    return edge
+  }
+
+  const recall = (refs = {}, limit = 8) => {
+    const direct = [...nodes.values()].filter((node) => {
+      const r = node.refs || {}
+      return sameRef(r.channelId, refs.channelId) && (refs.threadId == null || sameRef(r.threadId, refs.threadId)) ||
+        sameRef(r.projectId, refs.projectId) && sameRef(r.ticketId, refs.ticketId)
+    })
+    const keys = new Set(direct.map((node) => String(node.key)))
+    for (const edge of edges.values()) {
+      if (keys.has(String(edge.from))) keys.add(String(edge.to))
+      if (keys.has(String(edge.to))) keys.add(String(edge.from))
+    }
+    return [...nodes.values()].filter((node) => keys.has(String(node.key))).sort((a, b) => Number(b.updatedAt || 0) - Number(a.updatedAt || 0)).slice(0, limit)
+  }
+
+  const context = (refs = {}, limit = 8) => {
+    const items = recall(refs, limit)
+    if (!items.length) return ''
+    return ['RELEVANT VERIFIED MEMORY (do not repeat completed/delivered actions):', ...items.map((node) => `- ${node.kind} ${node.state}: ${node.summary || node.key}`)].join('\n')
+  }
+
+  const has = (key, state) => {
+    const node = nodes.get(String(key || ''))
+    return !!node && (state == null || node.state === state)
+  }
+
+  return { remember, connect, recall, context, has, persist }
+}

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/pr-push.mjs

@@ -0,0 +1,112 @@
+import { spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const DEFAULT_AUTH_PATH = join(homedir(), '.openvisio', 'pr-push-authorizations.json')
+const DEFAULT_RULE_PATH = join(homedir(), '.codex', 'rules', 'openvisio-agent.rules')
+
+const gitText = (cwd, args, spawn = spawnSync) => {
+  const result = spawn('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || `git ${args.join(' ')} failed`).trim())
+  return String(result.stdout || '').trim()
+}
+
+const safeRemote = (value) => {
+  const remote = String(value || '').trim()
+  if (/^https?:\/\//i.test(remote) || /^ssh:\/\//i.test(remote)) {
+    const parsed = new URL(remote)
+    if (parsed.username || parsed.password) throw new Error('Origin contains credentials in its URL. Move credentials to your Git credential manager before authorizing PR pushes.')
+    return remote
+  }
+  if (/^[^@\s]+@[^:\s]+:[^\s]+$/.test(remote)) return remote
+  throw new Error('Origin must be an HTTPS or SSH repository URL. Local paths and file:// remotes cannot be authorized.')
+}
+
+export function isSafeAgentBranch(value) {
+  const branch = String(value || '')
+  return /^agent\/[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch) &&
+    !branch.includes('..') && !branch.includes('//') && !branch.includes('@{') &&
+    !/[~^:?*\[\\]/.test(branch) && !/[/.]$/.test(branch)
+}
+
+export function codexPrPushRule() {
+  return `# Generated by: openvisio-agent authorize-pr-push
+# The helper enforces an exact pre-authorized repository + origin and only
+# pushes the current agent/* branch. It accepts no force, remote, or ref args.
+prefix_rule(
+    pattern = ["openvisio-agent", "push-pr-branch"],
+    decision = "allow",
+    justification = "The user explicitly authorized OpenVisio's constrained agent-branch PR push helper.",
+    match = ["openvisio-agent push-pr-branch"],
+)
+`
+}
+
+function readAuthorizations(path) {
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'))
+    return Array.isArray(value.authorizations) ? value.authorizations : []
+  } catch { return [] }
+}
+
+function writePrivate(path, value) {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, value, { mode: 0o600 })
+  try { chmodSync(path, 0o600) } catch { /* Windows / best-effort */ }
+}
+
+export function repositoryPushIdentity(cwd = process.cwd(), spawn = spawnSync) {
+  const root = realpathSync(gitText(cwd, ['rev-parse', '--show-toplevel'], spawn))
+  const remote = safeRemote(gitText(root, ['remote', 'get-url', '--push', 'origin'], spawn))
+  const branch = gitText(root, ['branch', '--show-current'], spawn)
+  return { root, remote, branch }
+}
+
+export function validatePrPushAuthorization({ root, remote, branch, authorizations }) {
+  if (!isSafeAgentBranch(branch)) {
+    throw new Error(`Refusing to push branch "${branch || '(detached HEAD)'}". OpenVisio PR pushes require the current branch to match agent/*.`)
+  }
+  const allowed = (Array.isArray(authorizations) ? authorizations : []).some((entry) => entry?.root === root && entry?.remote === remote)
+  if (!allowed) {
+    throw new Error(`OPENVISIO_PR_PUSH_AUTH_REQUIRED: This repository and its exact origin are not authorized. From ${root}, run: openvisio-agent authorize-pr-push`)
+  }
+  return true
+}
+
+export function repositoryHasPrPushAuthorization({ cwd = process.cwd(), authPath = DEFAULT_AUTH_PATH, spawn = spawnSync } = {}) {
+  try {
+    const { root, remote } = repositoryPushIdentity(cwd, spawn)
+    return readAuthorizations(authPath).some((entry) => entry?.root === root && entry?.remote === remote)
+  } catch { return false }
+}
+
+export function authorizePrPush({ cwd = process.cwd(), authPath = DEFAULT_AUTH_PATH, rulePath = DEFAULT_RULE_PATH, spawn = spawnSync, now = () => new Date().toISOString() } = {}) {
+  const { root, remote } = repositoryPushIdentity(cwd, spawn)
+  const authorizations = readAuthorizations(authPath).filter((entry) => entry?.root !== root)
+  authorizations.push({ root, remote, authorizedAt: now() })
+  writePrivate(authPath, JSON.stringify({ version: 1, authorizations }, null, 2) + '\n')
+  writePrivate(rulePath, codexPrPushRule())
+  return { root, remote, authPath, rulePath }
+}
+
+export function revokePrPush({ cwd = process.cwd(), authPath = DEFAULT_AUTH_PATH, spawn = spawnSync } = {}) {
+  const root = realpathSync(gitText(cwd, ['rev-parse', '--show-toplevel'], spawn))
+  const before = readAuthorizations(authPath)
+  const authorizations = before.filter((entry) => entry?.root !== root)
+  if (existsSync(authPath)) writePrivate(authPath, JSON.stringify({ version: 1, authorizations }, null, 2) + '\n')
+  return { root, revoked: authorizations.length !== before.length }
+}
+
+export function pushPrBranch({ cwd = process.cwd(), authPath = DEFAULT_AUTH_PATH, spawn = spawnSync } = {}) {
+  const identity = repositoryPushIdentity(cwd, spawn)
+  validatePrPushAuthorization({ ...identity, authorizations: readAuthorizations(authPath) })
+  const destination = `HEAD:refs/heads/${identity.branch}`
+  // The helper runs outside Codex's workspace sandbox after the user authorizes
+  // it. Disable repository hooks so an edited pre-push hook cannot widen this
+  // one operation into arbitrary host execution.
+  const nullHooks = process.platform === 'win32' ? 'NUL' : '/dev/null'
+  const result = spawn('git', ['-c', `core.hooksPath=${nullHooks}`, 'push', '-u', 'origin', destination], { cwd: identity.root, stdio: 'inherit' })
+  if (result.status !== 0) throw new Error(`git push failed with exit code ${result.status ?? 'unknown'}`)
+  return identity
+}