mio-agent-runtime 0.2.6 → 0.3.0

package/README.md

@@ -1,27 +1,29 @@
-# 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 --json status           Machine-readable status
-mio --json agents           Machine-readable agents
-```
-
+# 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
@@ -32,25 +34,40 @@ mio --json agents           Machine-readable agents
 - 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/WORKBUDDY.md` (user-level memory rules, auto-loaded by
-  WorkBuddy into every session) plus `<workspace>/AGENTS.md` (project-level).
+  `~/.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.
-
-## MIO_HOME
-
-默认 `~/.mio-intelligence`，可通过环境变量 `MIO_HOME` 覆盖。
-
-## Package layout
-
-```text
-packages/mio-cli
-├── bin/mio.js
-├── adapters/
-│   ├── codex.js
-│   ├── opencode.js
-│   └── workbuddy.js
-├── server/
-│   └── mio-intelligence-mcp/index.js
-└── package.json
+  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/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
 ```

package/adapters/workbuddy.js

@@ -25,15 +25,16 @@ function approvalsPath() {
   return path.join(configDir(), 'mcp-approvals.json')
 }
 
-// User-level memory rules file. WorkBuddy's codebuddy CLI auto-loads
-// WORKBUDDY.md (or WORKBUDDY.mdc) from the config dir into every session
-// (MemoryLoader user scope -> system-reminder-md / prompt context).
+// User-level memory rules file. WorkBuddy's codebuddy CLI (a CodeBuddy fork)
+// auto-loads CODEBUDDY.md (or CODEBUDDY.mdc) from the config dir into every
+// session (MemoryLoader user scope -> system-reminder-md / prompt context).
+// Note: PRODUCT_UPPERCASE_NAME in the CLI bundle is "CODEBUDDY", not "WORKBUDDY".
 function memoryRulesPath() {
-  return path.join(configDir(), 'WORKBUDDY.md')
+  return path.join(configDir(), 'CODEBUDDY.md')
 }
 
 // Project-level memory rules. WorkBuddy walks up from the workspace dir and
-// auto-loads WORKBUDDY.md / AGENTS.md (project scope) into every session.
+// auto-loads CODEBUDDY.md / AGENTS.md (project scope) into every session.
 function projectInstructionsPath(workspace) {
   return path.join(workspace || process.cwd(), 'AGENTS.md')
 }
@@ -188,7 +189,7 @@ function install({ node, serverScript, home, workspace, project }) {
     userRulesChanged: userRules.changed,
     projectRulesChanged: projectRules ? projectRules.changed : false,
     backup,
-    message: 'WorkBuddy Mio MCP installed, approved, and Mio rules injected into WORKBUDDY.md (auto-loaded user memory) and the workspace AGENTS.md. Restart WorkBuddy to load them.',
+    message: 'WorkBuddy Mio MCP installed, approved, and Mio rules injected into CODEBUDDY.md (auto-loaded user memory) and the workspace AGENTS.md. Restart WorkBuddy to load them.',
   }
 }
 

package/bin/mio.js

@@ -14,6 +14,7 @@ const adapters = {
   opencode: require('../adapters/opencode.js'),
   workbuddy: require('../adapters/workbuddy.js'),
 }
+const observer = require('../observe/observer.js')
 
 function ensureHome() {
   fs.mkdirSync(MIO_HOME, { recursive: true })
@@ -51,33 +52,36 @@ function initCommand() {
   console.log(`MIO_HOME ready: ${MIO_HOME}`)
 }
 
-function statusCommand(useJson) {
-  const config = readConfig()
-  const installed = {
-    codex: adapters.codex.isInstalled(),
-    opencode: adapters.opencode.isInstalled(),
-    workbuddy: adapters.workbuddy.isInstalled(),
-  }
-  const payload = {
-    version: config.version,
-    home: MIO_HOME,
-    serverScript: SERVER_SCRIPT,
-    serverScriptExists: fs.existsSync(SERVER_SCRIPT),
-    agents: config.agents || {},
-    codexInstalled: installed.codex,
-    opencodeInstalled: installed.opencode,
-    workbuddyInstalled: installed.workbuddy,
-  }
+function statusCommand(useJson) {
+  const config = readConfig()
+  const installed = {
+    codex: adapters.codex.isInstalled(),
+    opencode: adapters.opencode.isInstalled(),
+    workbuddy: adapters.workbuddy.isInstalled(),
+  }
+  const payload = {
+    version: config.version,
+    home: MIO_HOME,
+    serverScript: SERVER_SCRIPT,
+    serverScriptExists: fs.existsSync(SERVER_SCRIPT),
+    agents: config.agents || {},
+    codexInstalled: installed.codex,
+    opencodeInstalled: installed.opencode,
+    workbuddyInstalled: installed.workbuddy,
+    observerRunning: observer.isRunning(MIO_HOME),
+    observerPid: observer.isRunning(MIO_HOME) ? observer.readPid(MIO_HOME) : null,
+  }
   if (useJson) {
     jsonOrText(payload, true)
     return
   }
-  console.log(`MIO_HOME: ${MIO_HOME}`)
-  console.log(`MCP Server: ${SERVER_SCRIPT}`)
-  console.log(`Codex MCP: ${installed.codex ? 'installed' : 'not installed'}`)
-  console.log(`OpenCode MCP: ${installed.opencode ? 'installed' : 'not installed'}`)
-  console.log(`WorkBuddy MCP: ${installed.workbuddy ? 'installed' : 'not installed'}`)
-}
+  console.log(`MIO_HOME: ${MIO_HOME}`)
+  console.log(`MCP Server: ${SERVER_SCRIPT}`)
+  console.log(`Codex MCP: ${installed.codex ? 'installed' : 'not installed'}`)
+  console.log(`OpenCode MCP: ${installed.opencode ? 'installed' : 'not installed'}`)
+  console.log(`WorkBuddy MCP: ${installed.workbuddy ? 'installed' : 'not installed'}`)
+  console.log(`Observer: ${observer.isRunning(MIO_HOME) ? 'running (pid ' + observer.readPid(MIO_HOME) + ')' : 'not running'}`)
+}
 
 function agentsCommand(useJson) {
   const config = readConfig()
@@ -131,17 +135,69 @@ function installCommand(host, useJson) {
     }
     writeConfig(config)
   }
+  try {
+    observer.runCycle(MIO_HOME, observer.loadState(MIO_HOME), observer.createSinks(MIO_HOME))
+  } catch (_) {}
+  let observerStarted = false
+  try {
+    observerStarted = observer.startBackground(MIO_HOME).started
+  } catch (_) {}
   if (useJson) {
+    result.observer = {
+      running: observer.isRunning(MIO_HOME),
+      started: observerStarted,
+    }
     jsonOrText(result, true)
     return
   }
   console.log(result.message || `${host} adapter completed.`)
+  console.log(
+    observer.isRunning(MIO_HOME)
+      ? 'Observer daemon running.'
+      : 'Observer daemon not running. Run `mio observe --start`.'
+  )
 }
 
 function mcpCommand() {
   require(SERVER_SCRIPT)
 }
 
+function observeCommand(args) {
+  const flags = args.slice(1)
+  const useJson = flags.includes('--json')
+  if (flags.includes('--start')) {
+    const result = observer.startBackground(MIO_HOME)
+    if (useJson) return jsonOrText(result, true)
+    console.log(result.started ? 'Observer started.' : 'Observer already running.')
+    return
+  }
+  if (flags.includes('--stop')) {
+    const result = observer.stopBackground(MIO_HOME)
+    if (useJson) return jsonOrText(result, true)
+    console.log(result.stopped ? 'Observer stopped.' : 'Observer was not running.')
+    return
+  }
+  if (flags.includes('--status')) {
+    const running = observer.isRunning(MIO_HOME)
+    const pid = observer.readPid(MIO_HOME)
+    if (useJson) return jsonOrText({ running, pid }, true)
+    console.log(running ? 'Observer: running (pid ' + pid + ')' : 'Observer: not running')
+    return
+  }
+  if (flags.includes('--once')) {
+    const res = observer.runCycle(
+      MIO_HOME,
+      observer.loadState(MIO_HOME),
+      observer.createSinks(MIO_HOME)
+    )
+    if (useJson) return jsonOrText(res, true)
+    console.log('Observed files=' + res.files + ' lines=' + res.lines + ' outcomes=' + res.outcomes)
+    return
+  }
+  console.log('Observing WorkBuddy transcripts into ' + MIO_HOME + ' (Ctrl+C to stop)...')
+  observer.startForeground(MIO_HOME)
+}
+
 function help() {
   console.log(`Mio Agent Runtime CLI
 
@@ -151,6 +207,8 @@ Usage:
   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
+  mio observe --start|--stop|--status|--once   Manage the background observer daemon
   mio --json status           Machine-readable status
   mio --json agents           Machine-readable agents
 `)
@@ -174,6 +232,8 @@ function main() {
       return statusCommand(useJson)
     case 'agents':
       return agentsCommand(useJson)
+    case 'observe':
+      return observeCommand(args)
     case 'help':
     case '--help':
       return help()
@@ -184,4 +244,4 @@ function main() {
   }
 }
 
-main()
+main()

package/observe/observer.js

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const crypto = require('crypto')
+const { spawn } = require('child_process')
+
+const INTERVAL_MS = 3000
+// A WorkBuddy turn is considered finished when its transcript file has not
+// been appended for this long AND an assistant answer is present.
+const IDLE_MS = 15000
+
+function homeDir() {
+  return process.env.MIO_HOME || path.join(os.homedir(), '.mio-intelligence')
+}
+
+function workbuddyConfigDir() {
+  return (
+    process.env.WORKBUDDY_CONFIG_DIR ||
+    process.env.CODEBUDDY_CONFIG_DIR ||
+    path.join(os.homedir(), '.workbuddy')
+  )
+}
+
+function createId(prefix) {
+  return prefix + '_' + Date.now() + '_' + crypto.randomBytes(6).toString('hex')
+}
+
+function cleanText(text) {
+  return String(text || '')
+    .replace(/\r/g, '')
+    .replace(/#{2,}|\*{2,}|`{1,}|_{2,}|~{2,}|-{2,}/g, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim()
+}
+
+function projectFromDirName(dirName) {
+  // WorkBuddy project dirs encode the workspace path with dashes, e.g.
+  // "d-work-code-douyin_store" -> "douyin_store"
+  const parts = String(dirName || '').split('-').filter(Boolean)
+  if (parts.length > 1 && /^\\d+$/.test(parts[parts.length - 1])) {
+    return dirName || 'unknown'
+  }
+  return parts.length > 1 ? parts[parts.length - 1] : dirName || 'unknown'
+}
+
+function log(home, message) {
+  const line = '[' + new Date().toISOString() + '] ' + message + '\n'
+  try {
+    fs.mkdirSync(path.join(home, 'logs'), { recursive: true })
+    fs.appendFileSync(path.join(home, 'logs', 'observe.log'), line, 'utf8')
+  } catch (_) {}
+  if (process.stdout.isTTY || process.env.MIO_OBSERVE_VERBOSE) {
+    process.stdout.write(line)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// state
+// ---------------------------------------------------------------------------
+
+function stateFile(home) {
+  return path.join(home, 'observe-state.json')
+}
+
+function loadState(home) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(stateFile(home), 'utf8'))
+    if (parsed && typeof parsed === 'object') {
+      return {
+        version: 1,
+        files: parsed.files || {},
+        buffers: parsed.buffers || {},
+        openTurns: parsed.openTurns || {},
+      }
+    }
+  } catch (_) {}
+  return { version: 1, files: {}, buffers: {}, openTurns: {} }
+}
+
+function saveState(home, state) {
+  try {
+    fs.mkdirSync(home, { recursive: true })
+    fs.writeFileSync(stateFile(home), JSON.stringify(state) + '\n', 'utf8')
+  } catch (_) {}
+}
+
+function listTranscripts() {
+  const root = path.join(workbuddyConfigDir(), 'projects')
+  const out = []
+  if (!fs.existsSync(root)) return out
+  const walk = (dir) => {
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch (_) {
+      return
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) walk(full)
+      else if (entry.isFile() && entry.name.endsWith('.jsonl')) out.push(full)
+    }
+  }
+  walk(root)
+  return out
+}
+
+function fileMeta(file) {
+  const dirName = path.basename(path.dirname(file))
+  return {
+    sessionId: path.basename(file, '.jsonl'),
+    project: projectFromDirName(dirName),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sinks (write into MIO_HOME with the same schema as the MCP server)
+// ---------------------------------------------------------------------------
+
+function appendJsonl(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.appendFileSync(file, JSON.stringify(value) + '\n', 'utf8')
+}
+
+function createSinks(home) {
+  const tracePath = path.join(home, 'traces.jsonl')
+  const memoryPath = path.join(home, 'memory.jsonl')
+  const seenTraceIds = new Set()
+  const seenMemoryContents = new Set()
+
+  function trace(event) {
+    const record = {
+      id: createId('trace'),
+      timestamp: new Date().toISOString(),
+      trace_id: event.trace_id,
+      event_type: event.event_type,
+      outcome: event.outcome || null,
+      payload: event.payload || {},
+      agent: event.agent || 'workbuddy-observer',
+      host: event.host || 'workbuddy-observer',
+      project: event.project || 'unknown',
+    }
+    if (seenTraceIds.has(record.trace_id)) return
+    seenTraceIds.add(record.trace_id)
+    if (seenTraceIds.size > 20000) seenTraceIds.clear()
+    appendJsonl(tracePath, record)
+  }
+
+  function memory(entry) {
+    const key = entry.project + '|' + entry.content
+    if (seenMemoryContents.has(key)) return
+    seenMemoryContents.add(key)
+    const record = {
+      id: createId('mem'),
+      timestamp: new Date().toISOString(),
+      kind: entry.kind || 'note',
+      content: entry.content,
+      tags: Array.isArray(entry.tags) ? entry.tags : [],
+      project: entry.project || 'unknown',
+      source: entry.source || 'workbuddy-observer',
+    }
+    appendJsonl(memoryPath, record)
+  }
+
+  return { trace, memory }
+}
+
+// ---------------------------------------------------------------------------
+// WorkBuddy transcript turn machine
+// ---------------------------------------------------------------------------
+
+function createTurn(meta) {
+  return {
+    id: null,
+    ts: null,
+    project: meta.project,
+    sessionId: meta.sessionId,
+    toolCount: 0,
+    errors: [],
+    lastAssistant: null,
+  }
+}
+
+function feedWorkbuddyLine(turn, obj) {
+  if (!obj || typeof obj !== 'object') return { finalized: null, next: turn }
+  let finalized = null
+  if (obj.type === 'message') {
+    if (obj.role === 'user') {
+      finalized = turn
+      const next = createTurn(turn)
+      next.id = obj.id
+      next.ts = obj.timestamp
+      return { finalized, next: next }
+    }
+    if (obj.role === 'assistant') {
+      const text = (Array.isArray(obj.content) ? obj.content : [])
+        .map((c) => (c && typeof c.text === 'string' ? c.text : ''))
+        .filter(Boolean)
+        .join('\n')
+      turn.lastAssistant = {
+        status: obj.status,
+        text: text,
+        error: (obj.providerData && obj.providerData.error) || null,
+      }
+    }
+  } else if (obj.type === 'function_call') {
+    turn.toolCount += 1
+  } else if (obj.type === 'function_call_result') {
+    const status = String(obj.status || (obj.is_error ? 'error' : 'completed'))
+    if (status !== 'completed') {
+      turn.errors.push({ callId: obj.callId, name: obj.name, status: status })
+      if (turn.errors.length > 20) turn.errors.shift()
+    }
+  }
+  return { finalized: finalized, next: turn }
+}
+
+function emitWorkbuddyOutcome(turn, sinks) {
+  const la = turn.lastAssistant
+  if (!la) return
+  let outcome
+  if (la.status === 'completed') outcome = 'success'
+  else if (la.error) outcome = 'failure'
+  else outcome = 'aborted'
+
+  const summary = cleanText(la.text)
+  const turnToken = String(turn.id || 'unknown').slice(0, 8)
+  const tsToken = turn.ts ? Math.floor(Number(turn.ts) / 1000) : Math.floor(Date.now() / 1000)
+
+  sinks.trace({
+    trace_id: 'workbuddy:' + turn.sessionId + ':' + turnToken + ':' + tsToken,
+    event_type: 'task_outcome',
+    outcome: outcome,
+    payload: {
+      host: 'workbuddy',
+      project: turn.project,
+      sessionId: turn.sessionId,
+      turnId: turn.id,
+      toolCalls: turn.toolCount,
+      errors: turn.errors.length,
+      summary: summary.slice(0, 300),
+    },
+    agent: 'workbuddy',
+    host: 'workbuddy',
+    project: turn.project,
+  })
+
+  if (outcome === 'success' && summary.length >= 40) {
+    sinks.memory({
+      kind: 'note',
+      content: '[workbuddy] 任务完成: ' + summary.slice(0, 160),
+      tags: ['task-outcome', 'workbuddy', turn.project],
+      project: turn.project,
+      source: 'workbuddy-observer',
+    })
+  }
+
+  for (const err of turn.errors) {
+    sinks.trace({
+      trace_id: 'workbuddy:' + turn.sessionId + ':' + turnToken + ':' + String(err.callId || 'err').slice(0, 12),
+      event_type: 'error',
+      outcome: 'error',
+      payload: {
+        host: 'workbuddy',
+        project: turn.project,
+        sessionId: turn.sessionId,
+        turnId: turn.id,
+        tool: err.name,
+        status: err.status,
+      },
+      agent: 'workbuddy',
+      host: 'workbuddy',
+      project: turn.project,
+    })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// cycle
+// ---------------------------------------------------------------------------
+
+function runCycle(home, state, sinks, opts) {
+  const out = { files: 0, lines: 0, outcomes: 0 }
+  fs.mkdirSync(home, { recursive: true })
+  const files = listTranscripts()
+  const now = Date.now()
+  const maxAgeMs = (opts && opts.maxAgeMs) || 24 * 60 * 60 * 1000
+
+  for (const file of files) {
+    out.files += 1
+    let st
+    try {
+      st = fs.statSync(file)
+    } catch (_) {
+      continue
+    }
+    const info = state.files[file] || { size: 0 }
+    // Do not flood MIO_HOME with ancient history: only backfill files that are
+    // already tracked or that changed within the max age window.
+    if (!state.files[file] && now - st.mtimeMs > maxAgeMs) continue
+    const size = st.size
+    if (size < info.size) {
+      // rotated/truncated -> restart from the beginning
+      info.size = 0
+      state.buffers[file] = ''
+    }
+
+    const meta = fileMeta(file)
+    let turn = state.openTurns[file] || createTurn(meta)
+    turn.project = meta.project
+    turn.sessionId = meta.sessionId
+
+    if (size > info.size) {
+      let chunk = ''
+      try {
+        const fd = fs.openSync(file, 'r')
+        const buf = Buffer.alloc(size - info.size)
+        fs.readSync(fd, buf, 0, buf.length, info.size)
+        fs.closeSync(fd)
+        chunk = buf.toString('utf8')
+      } catch (_) {
+        continue
+      }
+      const pending = (state.buffers[file] || '') + chunk
+      const lines = pending.split(/\r?\n/)
+      state.buffers[file] = lines.pop()
+      for (const line of lines) {
+        if (!line.trim()) continue
+        out.lines += 1
+        let obj
+        try {
+          obj = JSON.parse(line)
+        } catch (_) {
+          continue
+        }
+        const result = feedWorkbuddyLine(turn, obj)
+        if (result.finalized) {
+          emitWorkbuddyOutcome(result.finalized, sinks)
+          out.outcomes += 1
+        }
+        turn = result.next
+      }
+      state.files[file] = { size: size, mtimeMs: st.mtimeMs }
+    }
+
+    if (turn.lastAssistant && now - st.mtimeMs > IDLE_MS) {
+      emitWorkbuddyOutcome(turn, sinks)
+      out.outcomes += 1
+      state.openTurns[file] = null
+    } else if (turn.id) {
+      state.openTurns[file] = turn
+    } else {
+      state.openTurns[file] = null
+    }
+  }
+
+  saveState(home, state)
+  return out
+}
+
+function startForeground(home) {
+  const state = loadState(home)
+  const sinks = createSinks(home)
+  log(home, 'observe started (home=' + home + ', interval=' + INTERVAL_MS + 'ms)')
+  const tick = () => {
+    try {
+      const res = runCycle(home, state, sinks)
+      if (res.lines > 0) {
+        log(home, 'cycle: files=' + res.files + ' lines=' + res.lines + ' outcomes=' + res.outcomes)
+      }
+    } catch (err) {
+      log(home, 'cycle error: ' + (err && err.stack ? err.stack : String(err)))
+    }
+  }
+  tick()
+  setInterval(tick, INTERVAL_MS)
+}
+
+// ---------------------------------------------------------------------------
+// background daemon control
+// ---------------------------------------------------------------------------
+
+function pidFile(home) {
+  return path.join(home, 'observe.pid')
+}
+
+function readPid(home) {
+  try {
+    const pid = Number(fs.readFileSync(pidFile(home), 'utf8').trim())
+    return Number.isInteger(pid) && pid > 0 ? pid : null
+  } catch (_) {
+    return null
+  }
+}
+
+function isRunning(home) {
+  const pid = readPid(home)
+  if (!pid) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (_) {
+    return false
+  }
+}
+
+function startBackground(home) {
+  if (isRunning(home)) {
+    return { running: true, started: false, pid: readPid(home) }
+  }
+  const script = path.join(__dirname, '..', 'bin', 'mio.js')
+  const child = spawn(process.execPath, [script, 'observe'], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  })
+  child.unref()
+  fs.mkdirSync(home, { recursive: true })
+  fs.writeFileSync(pidFile(home), String(child.pid), 'utf8')
+  return { running: true, started: true, pid: child.pid }
+}
+
+function stopBackground(home) {
+  const pid = readPid(home)
+  if (pid) {
+    try {
+      process.kill(pid)
+    } catch (_) {}
+    try {
+      fs.unlinkSync(pidFile(home))
+    } catch (_) {}
+  }
+  return { running: false, stopped: Boolean(pid), pid: pid || null }
+}
+
+module.exports = {
+  INTERVAL_MS,
+  homeDir,
+  workbuddyConfigDir,
+  loadState,
+  saveState,
+  runCycle,
+  createSinks,
+  startForeground,
+  startBackground,
+  stopBackground,
+  isRunning,
+  readPid,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mio-agent-runtime",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Mio Agent Runtime installer and MCP intelligence layer",
   "license": "MIT",
   "type": "commonjs",
@@ -11,10 +11,11 @@
     "bin/",
     "server/",
     "adapters/",
+    "observe/",
     "README.md"
   ],
   "scripts": {
-    "check": "node --check bin/mio.js && node --check adapters/codex.js && node --check adapters/opencode.js && node --check adapters/workbuddy.js && node --check server/mio-intelligence-mcp/index.js",
+    "check": "node --check bin/mio.js && node --check adapters/codex.js && node --check adapters/opencode.js && node --check adapters/workbuddy.js && node --check server/mio-intelligence-mcp/index.js && node --check observe/observer.js",
     "prepack": "npm run check"
   },
   "engines": {