mio-agent-runtime 0.2.7 → 0.3.1

package/README.md

@@ -18,25 +18,46 @@ 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
+## 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` 覆盖。
@@ -50,6 +71,8 @@ packages/mio-cli
 │   ├── codex.js
 │   ├── opencode.js
 │   └── workbuddy.js
+├── observe/
+│   └── observer.js
 ├── server/
 │   └── mio-intelligence-mcp/index.js
 └── package.json

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,481 @@
+#!/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,
+    cwd: meta.cwd || null,
+    toolCount: 0,
+    errors: [],
+    lastAssistant: null,
+  }
+}
+
+function feedWorkbuddyLine(turn, obj) {
+  if (!obj || typeof obj !== 'object') return { finalized: null, next: turn }
+  let finalized = null
+  if (obj.cwd) turn.cwd = obj.cwd
+  if (obj.type === 'message') {
+    if (obj.role === 'user') {
+      finalized = turn
+      const next = createTurn(turn)
+      next.id = obj.id
+      next.ts = obj.timestamp
+      next.cwd = obj.cwd || turn.cwd
+      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 localDateKey(ts) {
+  const d = new Date(Number(ts) || Date.now())
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return y + '-' + m + '-' + day
+}
+
+// Write a compact Mio digest back into WorkBuddy's own memory file
+// (<workspace>/.workbuddy/memory/YYYY-MM-DD.md). WorkBuddy instructs its model
+// to maintain and read these files every session, so the digest is
+// 'retrieved' next session without any Mio tool call by the model.
+function writeWorkbuddyDigest(turn, outcome, summary) {
+  if (!turn.cwd || !summary) return
+  const dir = path.join(turn.cwd, '.workbuddy', 'memory')
+  const file = path.join(dir, localDateKey(turn.ts) + '.md')
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    const time = new Date(Number(turn.ts) || Date.now()).toLocaleString('zh-CN', { hour12: false })
+    const entry =
+      '\n## Mio 自动摘要 (' + time + ')\n' +
+      '- outcome: ' + outcome + ' | tools: ' + turn.toolCount + ' | ' + summary.slice(0, 160) + '\n'
+    fs.appendFileSync(file, entry, 'utf8')
+  } catch (_) {}
+}
+
+function emitWorkbuddyOutcome(turn, sinks) {
+  const la = turn.lastAssistant
+  if (!la) return false
+  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',
+    })
+    writeWorkbuddyDigest(turn, outcome, summary)
+  }
+
+  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,
+    })
+  }
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// 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) {
+          if (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) {
+      if (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,23 +1,24 @@
-{
-  "name": "mio-agent-runtime",
-  "version": "0.2.7",
-  "description": "Mio Agent Runtime installer and MCP intelligence layer",
-  "license": "MIT",
-  "type": "commonjs",
-  "bin": {
-    "mio": "bin/mio.js"
-  },
-  "files": [
-    "bin/",
-    "server/",
-    "adapters/",
-    "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",
-    "prepack": "npm run check"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "mio-agent-runtime",
+  "version": "0.3.1",
+  "description": "Mio Agent Runtime installer and MCP intelligence layer",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "mio": "bin/mio.js"
+  },
+  "files": [
+    "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 && node --check observe/observer.js",
+    "prepack": "npm run check"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}