mio-agent-runtime 0.3.4 → 0.3.6

package/README.md

@@ -1,79 +1,102 @@
-# mio-agent-runtime
-
-Mio Agent Runtime 的可发布 CLI 包。
-
-安装一次，所有 Agent 自动接入 Mio。
-
-## Install
-
-```bash
-npm install -g mio-agent-runtime
-```
-
-## 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)
-mio status                  Show runtime and adapter status
-mio agents                  List installed agents
-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
-```
-
-## 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.
-- 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 内更新的会话，避免把历史记录灌入记忆库。
-
-## MIO_HOME
-
-默认 `~/.mio-intelligence`，可通过环境变量 `MIO_HOME` 覆盖。
-
-## Package layout
-
-```text
-packages/mio-cli
-├── bin/mio.js
-├── adapters/
-│   ├── codex.js
-│   ├── opencode.js
-│   └── workbuddy.js
-├── observe/
-│   └── observer.js
-├── server/
-│   └── mio-intelligence-mcp/index.js
-└── package.json
-```
+# 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)
+mio status                  Show runtime and adapter status
+mio agents                  List installed agents
+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
+```
+
+## 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
+│   ├── opencode.js
+│   └── workbuddy.js
+├── observe/
+│   └── observer.js
+├── server/
+│   └── mio-intelligence-mcp/index.js
+└── package.json
+```

package/adapters/hermes.js

@@ -0,0 +1,90 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { spawnSync } = require('child_process')
+
+const SERVER_NAME = 'mio-intelligence'
+
+function hermesBin() {
+  if (process.env.HERMES_BIN && fs.existsSync(process.env.HERMES_BIN)) return process.env.HERMES_BIN
+  const candidates = [
+    path.join(os.homedir(), 'AppData', 'Local', 'hermes', 'hermes-agent', 'bin', 'hermes.exe'),
+    path.join(os.homedir(), '.hermes', 'bin', 'hermes.exe'),
+  ]
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c
+  }
+  return null
+}
+
+function runHermes(args) {
+  const bin = hermesBin()
+  // `hermes mcp add` asks to confirm tool enablement interactively; pre-answer
+  // it so the install is non-interactive.
+  const input = args[0] === 'mcp' && args[1] === 'add' ? 'Y\n' : undefined
+  let res
+  try {
+    res = bin
+      ? spawnSync(bin, args, { encoding: 'utf8', timeout: 60000, windowsHide: true, input: input })
+      : spawnSync('hermes', args, { encoding: 'utf8', timeout: 60000, shell: true, windowsHide: true, input: input })
+  } catch (_) {
+    return null
+  }
+  if (res.error || res.status !== 0) return null
+  return (res.stdout || '') + (res.stderr || '')
+}
+
+function isInstalled() {
+  const out = runHermes(['mcp', 'list'])
+  return Boolean(out && out.indexOf(SERVER_NAME) !== -1)
+}
+
+function install({ node, serverScript, home, workspace, project }) {
+  if (!hermesBin() && !isHermesOnPath()) {
+    return {
+      changed: false,
+      message: 'Hermes binary not found. Install hermes-agent first.',
+      configPath: null,
+    }
+  }
+  if (isInstalled()) {
+    return { changed: false, message: 'Hermes Mio MCP already installed.', configPath: null }
+  }
+
+  const context = JSON.stringify({
+    agentId: 'hermes',
+    project: project || path.basename(workspace || process.cwd()),
+    workspace: workspace || process.cwd(),
+    sessionId: 'hermes-session',
+  })
+
+  const args = [
+    'mcp', 'add', SERVER_NAME,
+    '--command', node,
+    '--args', serverScript,
+    '--env', 'MIO_DATA_DIR=' + home, 'MIO_CONTEXT=' + context,
+  ]
+  const out = runHermes(args)
+  const installed = isInstalled()
+
+  let message
+  if (installed) {
+    message = 'Hermes Mio MCP installed (config: <LocalAppData>/hermes/config.yaml). Start a new Hermes session to load it.'
+  } else {
+    message = 'Hermes mcp add returned but Mio was not detected. Run `hermes mcp add ' + SERVER_NAME + ' --command ' + node + ' --args ' + serverScript + '` manually and answer Y to the prompt.'
+  }
+  return { changed: installed, configPath: null, message }
+}
+
+function isHermesOnPath() {
+  try {
+    const res = spawnSync('where', ['hermes'], { encoding: 'utf8', shell: true })
+    return res.status === 0 && /hermes/.test(res.stdout || '')
+  } catch (_) {
+    return false
+  }
+}
+
+module.exports = { hermesBin, isInstalled, install }