mio-agent-runtime 0.5.22 → 0.6.0

package/server/evolution-report.js

@@ -0,0 +1,311 @@
+'use strict'
+
+// Cross-agent evolution report (ADR-017 Evolution plane).
+//
+// Shared by the MCP tool `mio.evolution.report` and the CLI `mio evolution report`
+// so the two cannot drift. Dependencies are injected -- the MCP server resolves
+// its data directory from MIO_DATA_DIR while the CLI uses MIO_HOME, and each has
+// its own projectName() -- so this module owns no path or environment policy.
+
+const fs = require('fs')
+const path = require('path')
+
+const REPORT_FILES = {
+  memory: 'memory.jsonl',
+  trace: 'traces.jsonl',
+  reuse: 'experience_reuse.jsonl',
+  agent: 'agents.jsonl',
+}
+
+function readJsonl(file) {
+  if (!fs.existsSync(file)) return []
+  return fs
+    .readFileSync(file, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line)
+      } catch (_) {
+        return null
+      }
+    })
+    .filter(Boolean)
+}
+
+const PERIOD_MS = {
+  '24h': 86400000,
+  '7d': 604800000,
+  '30d': 2592000000,
+}
+
+// `high` maps to 0, so the rank must be looked up with hasOwnProperty -- an
+// `|| default` fallback would turn high (0, falsy) into the lowest priority and
+// sort the most urgent suggestion last.
+const SUGGESTION_RANK = { high: 0, medium: 1, low: 2 }
+
+function suggestionRank(priority) {
+  return Object.prototype.hasOwnProperty.call(SUGGESTION_RANK, priority)
+    ? SUGGESTION_RANK[priority]
+    : SUGGESTION_RANK.low
+}
+
+function createEvolutionReport({ dataDir, projectName }) {
+  const files = {
+    memory: path.join(dataDir, REPORT_FILES.memory),
+    trace: path.join(dataDir, REPORT_FILES.trace),
+    reuse: path.join(dataDir, REPORT_FILES.reuse),
+    agent: path.join(dataDir, REPORT_FILES.agent),
+  }
+
+  function report(args = {}) {
+    const project = args.project || projectName()
+    const period = String(args.period || 'all').trim()
+    const now = Date.now()
+    const periodMs = PERIOD_MS[period] === undefined ? Infinity : PERIOD_MS[period]
+    const cutoff = periodMs === Infinity ? 0 : now - periodMs
+
+    const memories = readJsonl(files.memory).filter((m) => !project || m.project === project || !m.project)
+    const traces = readJsonl(files.trace).filter((t) => !project || t.project === project)
+    const reuses = readJsonl(files.reuse).filter((r) => !project || r.project === project)
+    const agents = readJsonl(files.agent).filter((a) => !project || a.project === project)
+
+    const filteredTraces = cutoff ? traces.filter((t) => new Date(t.timestamp).getTime() >= cutoff) : traces
+    const filteredMemories = cutoff ? memories.filter((m) => new Date(m.timestamp).getTime() >= cutoff) : memories
+
+    // Ecosystem summary
+    const agentIds = new Set()
+    filteredTraces.forEach((t) => { if (t.agent) agentIds.add(t.agent) })
+    agents.forEach((a) => agentIds.add(a.agentId))
+    const outcomes = filteredTraces.filter((t) => t.event_type === 'task_outcome')
+    const successes = outcomes.filter((t) => t.outcome === 'success').length
+    const failures = outcomes.filter((t) => t.outcome === 'failure').length
+    const verifiedReuses = reuses.filter((r) => r.confirmed && r.reuse && r.behaviorChanged && r.outcomeImproved)
+    const pendingReuses = reuses.filter((r) => r.source === 'auto_claim' && !r.confirmed)
+
+    const ecosystem = {
+      agents: agentIds.size,
+      totalTasks: outcomes.length,
+      successRate: outcomes.length > 0 ? Math.round((successes / outcomes.length) * 100) : 0,
+      totalMemories: filteredMemories.length,
+      totalReuses: reuses.length,
+      verifiedReuses: verifiedReuses.length,
+      pendingReuses: pendingReuses.length,
+    }
+
+    // Agent performance comparison
+    const agentPerf = []
+    for (const agentId of agentIds) {
+      const agentTraces = filteredTraces.filter((t) => t.agent === agentId)
+      const agentOutcomes = agentTraces.filter((t) => t.event_type === 'task_outcome')
+      const agentSuccesses = agentOutcomes.filter((t) => t.outcome === 'success').length
+      const agentFailures = agentOutcomes.filter((t) => t.outcome === 'failure').length
+      const agentMemories = filteredMemories.filter((m) => m.source === agentId)
+      const agentVerified = reuses.filter((r) =>
+        (r.sourceAgent === agentId || r.targetAgent === agentId) && r.confirmed && r.reuse && r.behaviorChanged && r.outcomeImproved
+      )
+      const reg = agents.find((a) => a.agentId === agentId)
+      agentPerf.push({
+        agentId,
+        tasks: {
+          total: agentOutcomes.length,
+          success: agentSuccesses,
+          failure: agentFailures,
+          successRate: agentOutcomes.length > 0 ? Math.round((agentSuccesses / agentOutcomes.length) * 100) : 0,
+        },
+        memories: agentMemories.length,
+        verifiedReuses: agentVerified.length,
+        registered: !!reg,
+        lastActive: reg ? reg.lastSeenAt : (agentTraces.length > 0 ? agentTraces[agentTraces.length - 1].timestamp : null),
+      })
+    }
+    agentPerf.sort((a, b) => b.tasks.successRate - a.tasks.successRate || b.tasks.total - a.tasks.total)
+
+    // Cross-agent patterns
+    const crossPatterns = []
+    const reuseByPair = {}
+    for (const r of reuses) {
+      const key = r.sourceAgent + '->' + r.targetAgent
+      if (!reuseByPair[key]) reuseByPair[key] = { source: r.sourceAgent, target: r.targetAgent, total: 0, verified: 0, improved: 0 }
+      reuseByPair[key].total++
+      if (r.confirmed) reuseByPair[key].verified++
+      if (r.outcomeImproved) reuseByPair[key].improved++
+    }
+    for (const [key, pair] of Object.entries(reuseByPair)) {
+      if (pair.source !== pair.target) {
+        crossPatterns.push({
+          type: 'reuse_path',
+          from: pair.source,
+          to: pair.target,
+          total: pair.total,
+          verified: pair.verified,
+          improved: pair.improved,
+        })
+      }
+    }
+    crossPatterns.sort((a, b) => b.verified - a.verified || b.total - a.total)
+
+    // Memory health
+    const byKind = {}
+    let shortContent = 0
+    let missingKind = 0
+    for (const m of filteredMemories) {
+      const kind = m.kind || 'unknown'
+      byKind[kind] = (byKind[kind] || 0) + 1
+      const content = String(m.content || '').trim()
+      if (content.length < 20) shortContent++
+      if (!m.kind) missingKind++
+    }
+    const memoryHealth = {
+      total: filteredMemories.length,
+      byKind,
+      shortContent,
+      missingKind,
+      qualityScore: filteredMemories.length > 0
+        ? Math.round(((filteredMemories.length - shortContent - missingKind) / filteredMemories.length) * 100)
+        : 100,
+    }
+
+    // Suggestions engine
+    const suggestions = []
+
+    // Routing suggestion: compare agent success rates
+    if (agentPerf.length >= 2) {
+      const best = agentPerf[0]
+      const worst = agentPerf[agentPerf.length - 1]
+      if (best.tasks.total >= 5 && worst.tasks.total >= 5 && best.tasks.successRate - worst.tasks.successRate >= 15) {
+        suggestions.push({
+          category: 'routing',
+          priority: 'high',
+          description: best.agentId + ' has ' + best.tasks.successRate + '% success rate vs ' + worst.agentId + ' at ' + worst.tasks.successRate + '%; prefer routing to ' + best.agentId,
+          basedOn: 'task_outcome comparison',
+        })
+      }
+    }
+
+    // Pending auto-claim suggestion
+    if (pendingReuses.length >= 10) {
+      suggestions.push({
+        category: 'evidence',
+        priority: 'medium',
+        description: pendingReuses.length + ' pending auto-claims awaiting confirmation; review cross-agent claims to increase verified reuse count',
+        basedOn: 'experience_reuse.jsonl',
+      })
+    }
+
+    // Memory quality suggestion
+    if (memoryHealth.qualityScore < 80 && filteredMemories.length > 10) {
+      suggestions.push({
+        category: 'memory',
+        priority: 'medium',
+        description: 'Memory quality score is ' + memoryHealth.qualityScore + '%; ' + shortContent + ' short records and ' + missingKind + ' missing kind fields found',
+        basedOn: 'memory.jsonl quality analysis',
+      })
+    }
+
+    // Cross-agent value suggestion
+    if (crossPatterns.length === 0 && agentIds.size >= 2) {
+      suggestions.push({
+        category: 'interop',
+        priority: 'high',
+        description: 'Multiple agents registered but no cross-agent reuse patterns detected; ensure agents query shared memory',
+        basedOn: 'experience_reuse.jsonl',
+      })
+    }
+
+    // Active agent suggestion
+    const inactiveAgents = agentPerf.filter((a) => {
+      if (!a.lastActive) return false
+      return (now - new Date(a.lastActive).getTime()) > 7 * 86400000
+    })
+    if (inactiveAgents.length > 0) {
+      suggestions.push({
+        category: 'coverage',
+        priority: 'low',
+        description: inactiveAgents.map((a) => a.agentId).join(', ') + ' inactive for >7 days; consider removal or reactivation',
+        basedOn: 'agent registry lastSeenAt',
+      })
+    }
+
+    suggestions.sort((a, b) => suggestionRank(a.priority) - suggestionRank(b.priority))
+
+    return {
+      project,
+      generatedAt: new Date().toISOString(),
+      period,
+      ecosystem,
+      agentPerformance: agentPerf,
+      crossAgentPatterns: crossPatterns,
+      memoryHealth,
+      suggestions,
+    }
+  }
+
+  return { report }
+}
+
+function formatEvolutionReportText(result) {
+  const lines = []
+  lines.push(`Evolution report -- project ${result.project || '(all)'}, period ${result.period}`)
+  lines.push(`Generated ${result.generatedAt}`)
+
+  const eco = result.ecosystem
+  lines.push('')
+  lines.push('Ecosystem')
+  lines.push(`  agents           ${eco.agents}`)
+  lines.push(`  tasks            ${eco.totalTasks}${eco.totalTasks > 0 ? ` (success rate ${eco.successRate}%)` : ''}`)
+  lines.push(`  memories         ${eco.totalMemories}`)
+  lines.push(`  reuses           ${eco.totalReuses} (verified ${eco.verifiedReuses}, pending ${eco.pendingReuses})`)
+
+  lines.push('')
+  lines.push('Agent performance')
+  if (result.agentPerformance.length === 0) {
+    lines.push('  (no agents seen in this window)')
+  } else {
+    for (const a of result.agentPerformance) {
+      const reg = a.registered ? 'registered' : 'unregistered'
+      lines.push(
+        `  ${a.agentId.padEnd(12)} tasks ${String(a.tasks.total).padStart(3)}` +
+        `  success ${String(a.tasks.successRate).padStart(3)}%` +
+        `  memories ${String(a.memories).padStart(3)}` +
+        `  verified reuses ${a.verifiedReuses}  (${reg})`
+      )
+    }
+  }
+
+  lines.push('')
+  lines.push('Cross-agent patterns')
+  if (result.crossAgentPatterns.length === 0) {
+    lines.push('  (none)')
+  } else {
+    for (const p of result.crossAgentPatterns) {
+      lines.push(`  ${p.from} -> ${p.to}   total ${p.total}  verified ${p.verified}  improved ${p.improved}`)
+    }
+  }
+
+  const mh = result.memoryHealth
+  lines.push('')
+  lines.push('Memory health')
+  lines.push(`  quality ${mh.qualityScore}%   total ${mh.total}   short ${mh.shortContent}   missing kind ${mh.missingKind}`)
+  const kinds = Object.entries(mh.byKind)
+  if (kinds.length > 0) {
+    lines.push(`  by kind: ${kinds.map(([k, n]) => `${k} ${n}`).join(', ')}`)
+  }
+
+  lines.push('')
+  lines.push('Suggestions')
+  if (result.suggestions.length === 0) {
+    lines.push('  (none)')
+  } else {
+    for (const s of result.suggestions) {
+      lines.push(`  [${s.priority}] ${s.category}: ${s.description}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+module.exports = {
+  createEvolutionReport,
+  formatEvolutionReportText,
+}

package/server/experience-store.js

@@ -0,0 +1,214 @@
+'use strict'
+
+// Shared experience-reuse store: the single implementation behind
+// mio.experience.list / confirm / reuse, consumed by both the MCP server and
+// the CLI (`mio experience`). Kept separate from memory-store.js because it
+// owns a different file (experience_reuse.jsonl) and a different concern —
+// whether a past experience actually helped when reused, not recall ranking.
+//
+// The status vocabulary here is load-bearing: `verified` is the only status
+// that feeds memory ranking and task routing, and an unconfirmed `auto_claim`
+// never qualifies. That is why the CLI exposes pending claims explicitly —
+// unconfirmed auto-claims are otherwise invisible dead weight.
+
+const path = require('path')
+const { createId, readJsonl, appendJsonl, writeJsonl } = require('./memory-store.js')
+
+const REUSE_STATUS_FILTERS = Object.freeze({
+  pending: (record) => record.source === 'auto_claim' && record.confirmed !== true,
+  confirmed: (record) => record.confirmed === true,
+  verified: (record) =>
+    (record.reuse === true || record.reuse === 'true') &&
+    (record.behaviorChanged === true || record.behaviorChanged === 'true') &&
+    (record.outcomeImproved === true || record.outcomeImproved === 'true'),
+  auto_claim: (record) => record.source === 'auto_claim',
+  agent_report: (record) => record.source !== 'auto_claim',
+})
+
+const REUSE_STATUSES = Object.freeze(Object.keys(REUSE_STATUS_FILTERS))
+
+function toBool(value) {
+  return value === true || value === 'true'
+}
+
+function visibleRecord(record) {
+  return {
+    id: record.id,
+    source: record.source,
+    sourceAgent: record.sourceAgent,
+    targetAgent: record.targetAgent,
+    experienceId: record.experienceId,
+    reuse: toBool(record.reuse),
+    behaviorChanged: toBool(record.behaviorChanged),
+    outcomeImproved: toBool(record.outcomeImproved),
+    confirmed: record.confirmed === true,
+    confirmedBy: record.confirmedBy || null,
+    traceId: record.traceId || null,
+    timestamp: record.timestamp,
+    project: record.project,
+    notes: typeof record.notes === 'string' && record.notes ? record.notes.slice(0, 300) : null,
+  }
+}
+
+function createExperienceStore(options = {}) {
+  const dataDir = options.dataDir
+  const projectName = options.projectName || (() => null)
+  // Optional hook returning a phase-0 summary for the affected project. The MCP
+  // server wires it so its response shape stays unchanged; the CLI may omit it.
+  const phase0Summary = options.phase0Summary || null
+  const experiencePath = path.join(dataDir, 'experience_reuse.jsonl')
+
+  function listReuse(args = {}) {
+    const project = args.project || projectName()
+    const status = String(args.status || 'all').trim().toLowerCase()
+    const targetAgent = String(args.targetAgent || '').trim().toLowerCase()
+    const limit = Math.min(Math.max(Number(args.limit) || 20, 1), 100)
+
+    let records = readJsonl(experiencePath)
+    if (project) records = records.filter((record) => record.project === project)
+    if (targetAgent) {
+      records = records.filter(
+        (record) => String(record.targetAgent || '').toLowerCase() === targetAgent
+      )
+    }
+    const matcher = REUSE_STATUS_FILTERS[status]
+    if (matcher) records = records.filter(matcher)
+    records.sort((a, b) => {
+      const at = new Date(a.timestamp || 0).getTime()
+      const bt = new Date(b.timestamp || 0).getTime()
+      return bt - at
+    })
+
+    const visible = records.slice(0, limit).map(visibleRecord)
+
+    return {
+      project: project || null,
+      status,
+      count: visible.length,
+      total: records.length,
+      records: visible,
+    }
+  }
+
+  // Confirms one record (legacy `id`) or many (`ids`).
+  //
+  // Single-id calls keep strict semantics: an unknown id or a non-auto_claim
+  // record throws, so a caller that named one record always learns when it was
+  // wrong. Bulk calls are best-effort — with dozens of pending auto-claims a
+  // single bad id must not abort the whole batch — and report `notFound` /
+  // `rejected` instead.
+  function confirmReuse(args = {}) {
+    const bulk = Array.isArray(args.ids)
+    const ids = (
+      bulk ? args.ids : args.id ? [args.id] : []
+    )
+      .map((value) => String(value).trim())
+      .filter(Boolean)
+
+    if (ids.length === 0) {
+      throw new Error('experience.confirm requires id of an auto-claimed reuse record')
+    }
+
+    const outcomeImprovedArg =
+      args.outcomeImproved === undefined || args.outcomeImproved === null
+        ? null
+        : toBool(args.outcomeImproved)
+    const confirmedBy = String(args.confirmedBy || 'agent').trim() || 'agent'
+    const notes = args.notes ? String(args.notes).trim() : null
+
+    const records = readJsonl(experiencePath)
+    const confirmedIds = []
+    const confirmedRecords = []
+    const notFound = []
+    const rejected = []
+    const alreadyConfirmed = []
+    const confirmedAt = new Date().toISOString()
+
+    for (const id of ids) {
+      const index = records.findIndex((record) => record && record.id === id)
+      if (index < 0) {
+        if (!bulk) throw new Error(`No experience reuse record found with id ${id}`)
+        notFound.push(id)
+        continue
+      }
+      const record = records[index]
+      if (record.source !== 'auto_claim') {
+        if (!bulk) throw new Error('experience.confirm only applies to source=auto_claim reuse records')
+        rejected.push(id)
+        continue
+      }
+      if (record.confirmed === true && !args.force) {
+        alreadyConfirmed.push(id)
+        continue
+      }
+      const updated = {
+        ...record,
+        behaviorChanged: true,
+        outcomeImproved: outcomeImprovedArg === null ? record.outcomeImproved === true : outcomeImprovedArg,
+        confirmed: true,
+        confirmedAt,
+        confirmedBy,
+        notes: notes || record.notes || null,
+      }
+      records[index] = updated
+      confirmedIds.push(id)
+      confirmedRecords.push(updated)
+    }
+
+    if (confirmedRecords.length > 0) writeJsonl(experiencePath, records)
+
+    const result = {
+      confirmed: confirmedRecords.length > 0,
+      // `evidence` stays a single record for back-compat with single-id callers
+      // (including the MCP tests); bulk callers should use confirmedIds.
+      evidence: confirmedRecords.length === 1 ? confirmedRecords[0] : confirmedRecords[0] || null,
+      confirmedCount: confirmedRecords.length,
+      confirmedIds,
+      notFound,
+      rejected,
+      alreadyConfirmed,
+    }
+    if (phase0Summary && confirmedRecords.length > 0) {
+      result.phase0 = phase0Summary(confirmedRecords[0].project)
+    }
+    return result
+  }
+
+  function recordReuse(args = {}) {
+    const sourceAgent = String(args.sourceAgent || '').trim()
+    const targetAgent = String(args.targetAgent || '').trim()
+    const experienceId = String(args.experienceId || '').trim()
+    if (!sourceAgent) throw new Error('experience.reuse requires sourceAgent')
+    if (!targetAgent) throw new Error('experience.reuse requires targetAgent')
+    if (!experienceId) throw new Error('experience.reuse requires experienceId')
+
+    const project = args.project || projectName()
+    const evidence = {
+      id: createId('xfer'),
+      timestamp: new Date().toISOString(),
+      sourceAgent,
+      targetAgent,
+      experienceId,
+      reuse: toBool(args.reuse),
+      behaviorChanged: toBool(args.behaviorChanged),
+      outcomeImproved: toBool(args.outcomeImproved),
+      project,
+      source: args.source || 'agent_report',
+      notes: args.notes || null,
+    }
+    appendJsonl(experiencePath, evidence)
+
+    const result = { recorded: true, evidence }
+    if (phase0Summary) result.phase0 = phase0Summary(project)
+    return result
+  }
+
+  return { experiencePath, listReuse, confirmReuse, recordReuse }
+}
+
+module.exports = {
+  createExperienceStore,
+  REUSE_STATUS_FILTERS,
+  REUSE_STATUSES,
+  visibleRecord,
+}

package/server/insight-store.js

@@ -0,0 +1,118 @@
+'use strict'
+
+// Shared insight self-observation store: the single implementation behind the
+// mio.insight.* MCP tools and the `mio insight` CLI command. Same rationale as
+// memory-store.js / experience-store.js / policy-store.js -- one implementation,
+// two entry points, so CLI and MCP cannot drift.
+//
+// @akemi-mio/insight is an *optional* dependency: every entry point throws the
+// same "not installed" error, and isInsightAvailable() lets the MCP server gate
+// tool registration on it.
+
+const path = require('path')
+
+let InsightStore = null
+let InsightGenerator = null
+try {
+  const insight = require('@akemi-mio/insight')
+  InsightStore = insight.InsightStore
+  InsightGenerator = insight.InsightGenerator
+} catch {}
+
+function isInsightAvailable() {
+  return Boolean(InsightStore)
+}
+
+// Score at or above which an unreported insight is counted as high-value in the
+// status summary.
+const INSIGHT_HIGH_VALUE_SCORE = 0.7
+const INSIGHT_HIGH_VALUE_LIMIT = 50
+
+function createInsightStore(options = {}) {
+  const dataDir = options.dataDir
+  const chatJson = options.chatJson
+  const storePath =
+    options.storePath || (dataDir ? path.join(dataDir, 'insights', 'insights.json') : null)
+
+  // Built on first use rather than at construction: the MCP server used to
+  // build it eagerly at module load, which touched the filesystem even when no
+  // insight tool was ever called.
+  let store = null
+  function requireStore() {
+    if (!InsightStore) throw new Error('@akemi-mio/insight not installed')
+    if (!storePath) throw new Error('insight store requires dataDir or storePath')
+    if (!store) store = new InsightStore(storePath)
+    return store
+  }
+
+  function status() {
+    const s = requireStore()
+    const all = s.getAll()
+    const unreported = s.getUnreported()
+    return {
+      total: all.length,
+      unreported: unreported.length,
+      reported: all.length - unreported.length,
+      highValue: s.getHighValueUnreported(INSIGHT_HIGH_VALUE_LIMIT, INSIGHT_HIGH_VALUE_SCORE).length,
+    }
+  }
+
+  function list(args = {}) {
+    const s = requireStore()
+    let insights = s.getAll()
+    if (args.unreported) insights = s.getUnreported()
+    if (args.minScore) insights = insights.filter((i) => i.score >= args.minScore)
+    if (args.detector) insights = insights.filter((i) => i.detector === args.detector)
+    if (args.limit) insights = insights.slice(-args.limit)
+    return insights
+  }
+
+  function markReported(args = {}) {
+    const s = requireStore()
+    if (!args.ids || !Array.isArray(args.ids)) throw new Error('ids array required')
+    for (const id of args.ids) s.markReported(id)
+    return { marked: args.ids.length }
+  }
+
+  async function generate(args = {}) {
+    if (!InsightGenerator) throw new Error('@akemi-mio/insight not installed')
+    const generator = new InsightGenerator({ chatJson })
+    const ctx = {
+      memoryEntries: (args.memories || []).map((m) => ({
+        type: m.kind || m.type || 'note',
+        content: m.content || '',
+        createdAt: m.createdAt || m.timestamp || Date.now(),
+      })),
+      summaries: args.summaries || [],
+      interactionCount: 0,
+      plans: (args.plans || []).map((p) => ({
+        title: p.title || p.name || '',
+        status: p.status || 'unknown',
+        updatedAt: p.updatedAt || Date.now(),
+        steps: p.steps || [],
+        createdAt: p.createdAt || Date.now(),
+      })),
+      eventCount: 0,
+    }
+    const insights = await generator.generate(ctx)
+    if (InsightStore && storePath) {
+      requireStore().addMany(insights)
+    }
+    return { generated: insights.length, insights }
+  }
+
+  return {
+    storePath,
+    status,
+    list,
+    markReported,
+    generate,
+  }
+}
+
+module.exports = {
+  createInsightStore,
+  isInsightAvailable,
+  INSIGHT_HIGH_VALUE_SCORE,
+  INSIGHT_HIGH_VALUE_LIMIT,
+}