mio-agent-runtime 0.5.15 → 0.5.16

package/README.md

@@ -1,253 +1,161 @@
-# mio-agent-runtime
-
-> Your AI agents forget everything between sessions. Mio fixes that.
-
-Mio is a drop-in intelligence layer for Codex, OpenCode, Hermes, and WorkBuddy. Install once, and every agent you use starts remembering decisions, learning from mistakes, and sharing experience across tools — without any workflow changes.
-
-```
-  Codex ─┐
-OpenCode ─┤── MCP ──> Mio Intelligence Core
-  Hermes ─┘            ├─ Memory      decisions, context, problems
-                       ├─ Observer    passive session monitoring
-                       ├─ Policy      risk checks before dangerous ops
-                       ├─ Experience  cross-agent knowledge transfer
-                       ├─ Ideas       memory-powered idea generation
-                       └─ Evolution   ecosystem-level optimization
+# mio-agent-runtime
+
+Mio Agent Runtime 的可发布 CLI 包。
+
+安装一次，所有 Agent 自动接入 Mio。
+
+## Install
+
+```bash
+npm install -g mio-agent-runtime
+```
+
+> 新机器 / 升级：请安装 `>=0.3.6`（Codex + OpenCode + Hermes 被动观察）。
+> 旧版本只有主动 MCP 规则注入，没有「无感存/取」。安装后执行一次
+> `mio init && mio install <host>`。
+
+## Commands
+
+```text
+mio init                    Initialize MIO_HOME
+mio mcp                     Start Mio MCP server (stdio)
+mio install <host>          Install Mio into a host (codex|opencode|workbuddy|hermes)
+mio status                  Show runtime and adapter status
+mio agents                  List installed agents
+mio evolution status        Show composed evolution module health
+mio evolution shadow record      Record a shadow comparison sample
+mio evolution dual-write record  Record a dual-write comparison sample
+mio evolution cutover readiness   Assess shadow/dual-write cutover readiness
+mio evolution authority plan      Preview a gated authority switch plan
+mio evolution migration plan      Preview state migration diffs
+mio evolution cutover apply --dry-run   Dry-run a cutover plan without switching authority
+mio observe                 Watch WorkBuddy transcripts and auto-ingest task outcomes (foreground)
+mio observe --start|--stop|--status|--once   Manage the background observer daemon
+mio --json status           Machine-readable status
+mio --json agents           Machine-readable agents
+mio --json evolution status Machine-readable evolution module health
 ```
 
----
+## Release verification
 
-## Install
+Before publishing the runtime packages, run:
 
 ```bash
-npm install -g mio-agent-runtime
-mio init
-mio install codex          # or: opencode, hermes, workbuddy
-mio status
-```
-
-Restart your agent after install. That's it.
-
----
-
-## What it actually does
-
-**Without Mio**, every agent starts from zero each session. Your Codex forgets why you chose Postgres over Redis. Your OpenCode re-discovers the same config bug. Your WorkBuddy re-reads the same ADR you already explained.
-
-**With Mio**, the first agent to solve a problem records the solution. The next agent — any agent — finds it automatically.
-
-```
-  Session 1 (Codex)                    Session 2 (OpenCode)
-  ─────────────────                    ──────────────────
-  "Why not Redis?"                     "How should we cache?"
-  → records decision                   → queries memory
-  → Mio saves it                       → finds the Redis answer
-                                       → skips the dead end
-```
-
----
-
-## CLI Reference
-
-| Command | Description |
-|---------|-------------|
-| `mio init` | Create `~/.mio-intelligence` and default config |
-| `mio install <host>` | Wire MCP + rules + observer into a host |
-| `mio uninstall <host>` | Remove Mio MCP, rules, approvals, and observer from a host |
-| `mio upgrade` | Upgrade Mio via npm and re-wire all installed hosts to the new server |
-| `mio doctor` | Diagnose install/runtime issues: hosts, observer, version drift, PATH |
-| `mio dashboard [--start\|--stop\|--status\|--open]` | Start the live dashboard HTTP server (browser view of MIO_HOME data) |
-| `mio mcp` | Start MCP server (stdio, for agent integration) |
-| `mio status` | Show runtime state, adapter status, observer PID |
-| `mio agents` | List installed hosts |
-| `mio observe` | Foreground session monitor (Ctrl+C to stop) |
-| `mio observe --start` | Start background observer daemon |
-| `mio observe --stop` | Stop background daemon |
-| `mio observe --status` | Check daemon state |
-| `mio observe --once` | Run one collection cycle |
-| `mio --json <cmd>` | Any command outputs JSON |
-
-**What `mio install` does under the hood:**
-
-```
-mio install codex
-  |
-  +-- Writes MCP server config to ~/.codex/config.json
-  +-- Injects usage rules into AGENTS.md
-  +-- Backfills last 24h of session history
-  +-- Starts background passive observer
+npm run verify:pack-install --workspace mio-agent-runtime
 ```
 
----
-
-## MCP Tools (22 tools)
-
-### Memory
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.memory.record` | `content` | `kind`, `tags`, `project`, `scope`, `source` | Save a decision, context, problem, or note |
-| `mio.memory.query` | `query` | `project`, `limit`, `kind`, `tags`, `scope` | Search memory by keyword, tag, or type |
-| `mio.memory.analyze` | — | `project`, `limit` | Audit quality: duplicates, low-quality, type distribution |
-| `mio.memory.archive` | `ids` | `project`, `restore`, `reason` | Archive records (recoverable) |
-| `mio.memory.migrate` | `ids`, `scope` | `project`, `reason` | Move between project and global layers |
-
-### Observer
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.observer.ingest` | `trace_id`, `event_type` | `payload`, `outcome`, `agent`, `host`, `project` | Report tool calls, errors, retries, task outcomes |
-| `mio.observer.subscribe` | — | `eventTypes`, `project`, `topic`, `ttlDays` | Subscribe to event stream by type/project |
-| `mio.observer.digest` | — | `project`, `eventTypes`, `limit` | Pull new events since last digest |
-
-### Policy
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.policy.check` | `action` | `project`, `context` | Pre-flight risk check against historical failure data |
-
-### Experience
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.experience.reuse` | `sourceAgent`, `targetAgent`, `experienceId`, `reuse`, `behaviorChanged`, `outcomeImproved` | `notes`, `project` | Record cross-agent experience reuse with evidence |
-| `mio.experience.confirm` | `id` | `confirmedBy`, `notes`, `outcomeImproved` | Human-confirm an auto-claimed reuse record |
-| `mio.experience.list` | — | `status`, `targetAgent`, `limit`, `project` | Query reuse evidence, filter by status |
-
-### Task
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.task.route` | `task` | `project`, `scope`, `limit` | Recommend best agent for a task based on history |
-| `mio.task.record_outcome` | — | (event-based) | Record task success/failure/abort |
+For CI or reproducible release evidence through `npm run`, set deterministic
+directories through environment variables:
 
-### Agent
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.agent.register` | — | (metadata) | Register agent capabilities and host |
-| `mio.agent.list` | — | — | List registered agents |
-| `mio.agent.report` | — | (agent ID) | Query agent behavior summary |
-
-### Ideas
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.idea.generate` | `goal` | `context`, `constraints` | Generate ideas using 5 strategies: SCAMPER, analogy, first-principles, random-stimulus, constraint-inversion |
-| `mio.idea.list` | — | `goal`, `strategy`, `period` | Query saved ideas |
-
-### Evolution
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.evolution.report` | — | `project` | Ecosystem analysis report |
-| `mio.evolution.suggest` | — | `project` | Actionable optimization suggestions with nextAction + impact |
-
-### Validation
-
-| Tool | Required | Optional | Description |
-|------|----------|----------|-------------|
-| `mio.phase0.report` | — | `project`, `format` | Cross-agent value validation report (JSON / Markdown) |
-
----
-
-## Supported Hosts
-
-| Host | Config Location | Observer Method | Write-back |
-|------|----------------|-----------------|------------|
-| **Codex** | `~/.codex/config.json` | Not needed (agent calls MCP directly) | AGENTS.md rules |
-| **OpenCode** | `~/.config/opencode/opencode.json` | `opencode db` incremental read | `MIO_CONTEXT` block in AGENTS.md |
-| **Hermes** | `hermes mcp add` | `state.db` cursor (no CLI needed) | AGENTS.md (git repos only) |
-| **WorkBuddy** | `~/.workbuddy/mcp.json` | Tails `projects/**/*.jsonl` | `CODEBUDDY.md` + workspace AGENTS.md |
-
-### How passive observation works
-
-Most agents don't call memory tools on their own, even when rules are injected. The passive observer solves this by reading session logs directly:
-
-```
-Agent session logs
-      |
-  mio observe (background daemon)
-      |
-  +-- Extracts task_outcome, errors, summaries
-  +-- Writes to MIO_HOME/traces.jsonl + memory.jsonl
-  +-- Writes summary back to agent's native memory file
-      |
-  Next session: agent sees Mio's notes without calling any tool
+```bash
+MIO_PACK_ARTIFACT_DIR=./dist/mio-pack-artifacts \
+MIO_PACK_INSTALL_DIR=./dist/mio-pack-install \
+MIO_PACK_REPORT_PATH=./dist/mio-pack-report.json \
+npm run verify:pack-install --workspace mio-agent-runtime
 ```
 
-- **Incremental**: file offsets tracked in `observe-state.json`, no duplicates
-- **Scoped**: only backfills sessions updated in last 24h
-- **Per-host**: each adapter reads its own format (JSONL / SQLite / DB CLI)
+PowerShell:
 
----
-
-## MIO_HOME
-
-Default: `~/.mio-intelligence` (override with `MIO_HOME` env var).
-
-```
-~/.mio-intelligence/
-    config.json              runtime config + installed hosts
-    memory.jsonl             decisions, context, problems
-    traces.jsonl             agent behavior events
-    experience-reuse.jsonl   cross-agent reuse evidence
-    ideas.jsonl              generated ideas
-    suggestions.jsonl        evolution suggestions
-    observe-state.json       observer increment cursors
-    observe.pid              background daemon PID
-    logs/                    runtime logs
+```powershell
+$env:MIO_PACK_ARTIFACT_DIR = './dist/mio-pack-artifacts'
+$env:MIO_PACK_INSTALL_DIR = './dist/mio-pack-install'
+$env:MIO_PACK_REPORT_PATH = './dist/mio-pack-report.json'
+npm run verify:pack-install --workspace mio-agent-runtime
 ```
 
----
-
-## Architecture
+When invoking the script directly, command-line flags are also supported:
 
+```bash
+node packages/mio-cli/scripts/verify-packed-runtime.js \
+  --artifact-dir ./dist/mio-pack-artifacts \
+  --install-dir ./dist/mio-pack-install \
+  --report-path ./dist/mio-pack-report.json
 ```
-Before Mio:
-
-  Codex ──── (forgets everything)
-  OpenCode ── (starts from zero)
-  Hermes ──── (isolated memory)
-  WorkBuddy ─ (no continuity)
-
-After Mio:
 
-  Codex ─┐
-OpenCode ─┤        Mio Intelligence Core
-  Hermes ─┼────>   + Memory ........... shared knowledge base
-WorkBuddy ─┘       + Observer ......... automatic data collection
-                    + Policy ........... risk management
-                    + Experience ........ cross-agent reuse with evidence
-                    + Ideas ............ memory-powered creativity
-                    + Evolution ........ ecosystem optimization
+This packs all seven `@akemi-mio/*` runtime modules plus `mio-agent-runtime`, installs
+the local tarballs into a clean temporary npm project, and runs installed CLI
+smoke checks for `mio --json evolution status`, shadow sample recording,
+dual-write sample recording, cutover readiness, and dry-run cutover apply. The
+JSON output includes each packed tarball path, size, and SHA-512 digest for
+release evidence. When `MIO_PACK_REPORT_PATH` or `--report-path` is set, the
+same JSON is written to that file; existing report files are not overwritten. It
+fails closed if any runtime module is missing, unloaded, or unhealthy, if
+shadow/dual-write parity fails, or if cutover apply stops behaving as a dry run.
+It does not publish packages or switch authority.
+
+## Host notes
+
+- OpenCode uses `~/.config/opencode/opencode.json` for MCP registration and
+  `~/.config/opencode/AGENTS.md` for global instructions. `mio install opencode`
+  writes both files and injects Mio usage rules into `AGENTS.md` so OpenCode
+  calls Mio memory/observer/policy automatically. If OpenCode is already
+  running, restart it once so it reloads both files. `mio observe` also
+  passively tails the OpenCode session database (`opencode db`) without
+  requiring the model to call Mio tools.
+- Hermes uses `hermes mcp add mio-intelligence --command node --args <server>`
+  to register the Mio MCP server. Hermes has native memory and reads
+  AGENTS.md Context Files, so retrieval works without Mio rule injection.
+- WorkBuddy uses `~/.workbuddy/mcp.json` and requires each custom MCP server to
+  be approved in `~/.workbuddy/mcp-approvals.json`. `mio install workbuddy`
+  writes both files and injects Mio usage rules into
+  `~/.workbuddy/CODEBUDDY.md` (user-level memory rules, auto-loaded by
+  WorkBuddy into every session; the CLI hardcodes the CodeBuddy product name, so the file is CODEBUDDY.md not WORKBUDDY.md) plus `<workspace>/AGENTS.md` (project-level).
+  If WorkBuddy is already running, restart it once so it reloads the approval
+  and memory rule files.
+
+## Passive observer (`mio observe`)
+
+WorkBuddy 的默认模型不一定会主动调用 Mio MCP 工具，即使规则已注入
+(`CODEBUDDY.md` / `AGENTS.md`)。`mio observe` 是一个不依赖模型自觉的
+兜底：它持续监听 `~/.workbuddy/projects/**/*.jsonl` 会话记录，把每个任务的
+结果（`task_outcome`）、工具调用错误（`error`）以及完成任务的摘要自动写入
+`MIO_HOME/traces.jsonl` 和 `MIO_HOME/memory.jsonl`（与 MCP 服务同一套
+schema，`source=workbuddy-observer`）。
+
+- `mio install <host>` 会自动执行一次回填并启动后台观察器。
+
+- 除了写入 `MIO_HOME`，观察器还会把任务摘要**写回 WorkBuddy 自己的记忆文件**
+  (`<workspace>/.workbuddy/memory/YYYY-MM-DD.md`，标为 `## Mio 自动摘要`)。
+  WorkBuddy 的系统提示要求模型每次会话维护并阅读这些文件，所以下一次会话
+  WorkBuddy 会**被动取到** Mio 记录的内容——单 Agent 的「存 + 取」闭环不依赖
+  模型调用 Mio 工具。
+- 已处理的文件偏移记录在 `MIO_HOME/observe-state.json`，不会重复写入。
+- 只回填最近 24h 内更新的会话，避免把历史记录灌入记忆库。
+
+OpenCode 会话不依赖模型自觉：`mio observe` 通过 `opencode db` 增量读取
+`~/.local/share/opencode/opencode.db`（Windows 下该文件被 OpenCode 独占锁定，
+必须经 opencode 自带 CLI 读取），按 `part` 表的 rowid 做增量游标，只传输
+`text`/`tool` 两种 part，把每个用户回合的 `task_outcome` 与工具错误写入
+`MIO_HOME/traces.jsonl` / `memory.jsonl`（`source=opencode-observer`），并同样
+把摘要写回 `<workspace>/AGENTS.md` 的 `MIO_CONTEXT` 块，供 OpenCode 下一会话
+被动取用。首次启动只回填最近 24h 的 part，避免历史会话灌入记忆库。
+
+Hermes（Nous hermes-agent）同理：`mio observe` 以只读方式增量读取
+`<LocalAppData>/hermes/state.db`（`messages.id` 自增游标，无需调用 hermes CLI），
+把每个用户回合的 `task_outcome` 写入 `MIO_HOME`（`source=hermes-observer`）。
+Hermes 本身有原生记忆，Mio 只负责让 Hermes 经验进入跨 Agent 生态；仅当会话
+发生在真实 git 仓库时才写回该仓库的 `AGENTS.md`，避免污染用户主目录。
+
+## MIO_HOME
+
+默认 `~/.mio-intelligence`，可通过环境变量 `MIO_HOME` 覆盖。
+
+## Package layout
+
+```text
+packages/mio-cli
+├── bin/mio.js
+├── adapters/
+│   ├── codex.js
+│   ├── hermes.js
+│   ├── opencode.js
+│   └── workbuddy.js
+├── observe/
+│   └── observer.js
+├── server/
+│   ├── host-capabilities.js
+│   ├── evolution-cutover.js
+│   ├── runtime-modules.js
+│   └── mio-intelligence-mcp/index.js
+└── package.json
 ```
-
-| | Standalone Agent Memory | Mio Control Plane |
-|---|---|---|
-| **Scope** | Single agent | Multi-agent ecosystem |
-| **Collection** | Agent must call tools | Passive observation + active calls |
-| **Knowledge flow** | Isolated | Shared with reuse evidence |
-| **Risk management** | None | Unified policy checks |
-| **Optimization** | Per-agent | Ecosystem-wide |
-
----
-
-## Version History
-
-| Version | Milestone |
-|---------|-----------|
-| < 0.3.6 | Active MCP rule injection only |
-| >= 0.3.6 | Passive observation + seamless read/write |
-| >= 0.5.0 | Idea generation + evolution suggestions |
-| >= 0.5.6 | Rewritten documentation |
-| >= 0.5.9 | `mio uninstall <host>` command |
-| >= 0.5.10 | `mio upgrade` and `mio doctor` commands |
-| >= 0.5.11 | Live web dashboard (`mio dashboard` + `mio.dashboard.*`) |
-| >= 0.5.12 | Observer reliability: all outcomes write back (not just success); Hermes cwd hardening; write-back diagnostics |
-
----
-
-## License
-
-MIT

package/adapters/codex.js

@@ -1,134 +1,122 @@
-'use strict'
-
-const fs = require('fs')
-const path = require('path')
-const os = require('os')
-const { restartWarning } = require('./host-utils')
-
-const SERVER_SECTION = '[mcp_servers.mio-intelligence]'
-const ENV_SECTION = '[mcp_servers.mio-intelligence.env]'
-
-function configPath() {
-  return path.join(os.homedir(), '.codex', 'config.toml')
-}
-
-function isInstalled() {
-  const target = configPath()
-  if (!fs.existsSync(target)) return false
-  return fs.readFileSync(target, 'utf8').includes(SERVER_SECTION)
-}
-
-// Legacy installs pointed args at the worktree copy of the server
-// (server/mio-intelligence-mcp/index.js) instead of this package's copy
-// (server/mio-intelligence-mcp/index.js). Detect staleness by comparing the
-// configured args path with the server path this package ships.
-function configNeedsRepair(serverScript) {
-  const target = configPath()
-  if (!fs.existsSync(target)) return false
-  try {
-    const src = fs.readFileSync(target, 'utf8')
-    if (!src.includes(SERVER_SECTION)) return false
-    const needle = serverScript.replace(/\\/g, '/').toLowerCase()
-    return !src.replace(/\\/g, '/').toLowerCase().includes(needle)
-  } catch (_) {
-    return false
-  }
-}
-
-function installMessage(installed, restartHint) {
-  let message = installed
-    ? 'Codex Mio MCP repaired (server path updated). Restart Codex to load it.'
-    : 'Codex Mio MCP installed. Restart Codex to load it.'
-  if (restartHint) message += ' ' + restartHint
-  return message
-}
-
-function restartWarningMessage() {
-  return restartWarning({
-    hostLabel: 'Codex',
-    exeName: 'codex.exe',
-    exePathFragment: 'OpenAI.Codex',
-    configPath: configPath(),
-  })
-}
-
-function stripMioSection(toml) {
-  const lines = toml.replace(/\r\n/g, '\n').split('\n')
-  const out = []
-  let skipping = false
-  for (const line of lines) {
-    const trimmed = line.trim()
-    if (trimmed === SERVER_SECTION || trimmed === ENV_SECTION) {
-      skipping = true
-      continue
-    }
-    if (skipping && /^\[.*\]$/.test(trimmed)) {
-      skipping = false
-    }
-    if (!skipping) out.push(line)
-  }
-  return out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n'
-}
-
-function install({ node, serverScript, home, workspace }) {
-  const target = configPath()
-  const backup = `${target}.bak-mio-${Date.now()}`
-  const installed = isInstalled()
-  if (installed && !configNeedsRepair(serverScript)) {
-    return {
-      changed: false,
-      configPath: target,
-      message: 'Codex Mio MCP already installed.',
-    }
-  }
-
-  if (fs.existsSync(target)) {
-    fs.copyFileSync(target, backup)
-  }
-
-  const context = JSON.stringify({
-    agentId: 'codex',
-    workspace: workspace || process.cwd(),
-    sessionId: 'codex-session',
-  })
-
-  fs.mkdirSync(path.dirname(target), { recursive: true })
-  let toml = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
-  toml = stripMioSection(toml)
-  toml = toml.replace(/\n{3,}/g, '\n\n')
-  if (!toml.endsWith('\n')) toml += '\n'
-  const section = [
-    '',
-    SERVER_SECTION,
-    `command = '${node}'`,
-    `args = ['${serverScript}']`,
-    'startup_timeout_sec = 30',
-    '',
-    ENV_SECTION,
-    `MIO_DATA_DIR = '${home}'`,
-    `MIO_CONTEXT = '${context}'`,
-    '',
-  ].join('\n')
-  fs.writeFileSync(target, `${toml}${section}\n`, 'utf8')
-
-  return {
-    changed: true,
-    configPath: target,
-    backup,
-    message: installMessage(installed, restartWarningMessage()),
-  }
-}
-
-function uninstall({ serverScript }) {
-  const target = configPath()
-  if (!fs.existsSync(target) || !fs.readFileSync(target, 'utf8').includes(SERVER_SECTION)) {
-    return { changed: false, configPath: target, message: 'Codex Mio MCP not installed.' }
-  }
-  const backup = target + '.bak-mio-' + Date.now()
-  fs.copyFileSync(target, backup)
-  const toml = stripMioSection(fs.readFileSync(target, 'utf8'))
-  fs.writeFileSync(target, toml, 'utf8')
-  return { changed: true, configPath: target, backup, message: 'Codex Mio MCP removed. Restart Codex to apply.' }
-}
-
-module.exports = { configPath, isInstalled, install, uninstall, restartWarningMessage }
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { restartWarning } = require('./host-utils')
+
+const SERVER_SECTION = '[mcp_servers.mio-intelligence]'
+const ENV_SECTION = '[mcp_servers.mio-intelligence.env]'
+
+function configPath() {
+  return path.join(os.homedir(), '.codex', 'config.toml')
+}
+
+function isInstalled() {
+  const target = configPath()
+  if (!fs.existsSync(target)) return false
+  return fs.readFileSync(target, 'utf8').includes(SERVER_SECTION)
+}
+
+// Legacy installs pointed args at the worktree copy of the server
+// (server/mio-intelligence-mcp/index.js) instead of this package's copy
+// (server/mio-intelligence-mcp/index.js). Detect staleness by comparing the
+// configured args path with the server path this package ships.
+function configNeedsRepair(serverScript) {
+  const target = configPath()
+  if (!fs.existsSync(target)) return false
+  try {
+    const src = fs.readFileSync(target, 'utf8')
+    if (!src.includes(SERVER_SECTION)) return false
+    const needle = serverScript.replace(/\\/g, '/').toLowerCase()
+    return !src.replace(/\\/g, '/').toLowerCase().includes(needle)
+  } catch (_) {
+    return false
+  }
+}
+
+function installMessage(installed, restartHint) {
+  let message = installed
+    ? 'Codex Mio MCP repaired (server path updated). Restart Codex to load it.'
+    : 'Codex Mio MCP installed. Restart Codex to load it.'
+  if (restartHint) message += ' ' + restartHint
+  return message
+}
+
+function restartWarningMessage() {
+  return restartWarning({
+    hostLabel: 'Codex',
+    exeName: 'codex.exe',
+    exePathFragment: 'OpenAI.Codex',
+    configPath: configPath(),
+  })
+}
+
+function stripMioSection(toml) {
+  const lines = toml.replace(/\r\n/g, '\n').split('\n')
+  const out = []
+  let skipping = false
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === SERVER_SECTION || trimmed === ENV_SECTION) {
+      skipping = true
+      continue
+    }
+    if (skipping && /^\[.*\]$/.test(trimmed)) {
+      skipping = false
+    }
+    if (!skipping) out.push(line)
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n'
+}
+
+function install({ node, serverScript, home, workspace }) {
+  const target = configPath()
+  const backup = `${target}.bak-mio-${Date.now()}`
+  const installed = isInstalled()
+  if (installed && !configNeedsRepair(serverScript)) {
+    return {
+      changed: false,
+      configPath: target,
+      message: 'Codex Mio MCP already installed.',
+    }
+  }
+
+  if (fs.existsSync(target)) {
+    fs.copyFileSync(target, backup)
+  }
+
+  const context = JSON.stringify({
+    agentId: 'codex',
+    workspace: workspace || process.cwd(),
+    sessionId: 'codex-session',
+  })
+
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  let toml = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : ''
+  toml = stripMioSection(toml)
+  toml = toml.replace(/\n{3,}/g, '\n\n')
+  if (!toml.endsWith('\n')) toml += '\n'
+  const section = [
+    '',
+    SERVER_SECTION,
+    `command = '${node}'`,
+    `args = ['${serverScript}']`,
+    'startup_timeout_sec = 30',
+    '',
+    ENV_SECTION,
+    `MIO_DATA_DIR = '${home}'`,
+    `MIO_CONTEXT = '${context}'`,
+    '',
+  ].join('\n')
+  fs.writeFileSync(target, `${toml}${section}\n`, 'utf8')
+
+  return {
+    changed: true,
+    configPath: target,
+    backup,
+    message: installMessage(installed, restartWarningMessage()),
+  }
+}
+
+module.exports = { configPath, isInstalled, install, restartWarningMessage }