mio-agent-runtime 0.11.0 → 0.12.0

package/server/memory-store.js

@@ -29,9 +29,63 @@ function readJsonl(file) {
     .filter(Boolean)
 }
 
+// --- cross-call read cache ------------------------------------------------
+// The MCP server is long-lived and re-reads the same append-only logs on every
+// tool call. On a 1094-record store that is ~7 ms to read+parse memory.jsonl
+// and ~13 ms more to rebuild every record's tokenized haystack -- about 20 ms
+// per query, against ~0.4 ms when both are warm.
+//
+// Validity: (size, mtimeMs) is checked on every call, and every write that goes
+// through appendJsonl/writeJsonl drops the entry explicitly. The one window
+// left is an outside process rewriting a file in the same millisecond to the
+// exact same byte count; the consequence is a single stale query, not corrupt
+// data. `mio prune` (retention.js) now writes through this module's writeJsonl
+// (or calls dropCache directly), so its prunes invalidate the cache explicitly
+// instead of relying on the size check.
+const readCache = new Map()
+
+// Haystacks are memoized against the record objects the cache hands out, so a
+// fresh parse produces fresh objects and rebuilds them. Reassigned (not just
+// cleared) on every write because mergeMemory() mutates `survivor.tags` in
+// place, and tags are part of the haystack -- a WeakMap cannot be cleared, so
+// it is replaced.
+let haystackCache = new WeakMap()
+
+function dropCache(file) {
+  readCache.delete(file)
+  haystackCache = new WeakMap()
+}
+
+function readJsonlCached(file) {
+  let st
+  try {
+    st = fs.statSync(file)
+  } catch (_) {
+    dropCache(file)
+    return []
+  }
+  const hit = readCache.get(file)
+  if (hit !== undefined && hit.size === st.size && hit.mtimeMs === st.mtimeMs) {
+    return hit.records
+  }
+  const records = readJsonl(file)
+  readCache.set(file, { size: st.size, mtimeMs: st.mtimeMs, records })
+  return records
+}
+
+function haystackFor(record) {
+  let hay = haystackCache.get(record)
+  if (hay === undefined) {
+    hay = splitHaystack(`${record.content || ''} ${(record.tags || []).join(' ')} ${record.kind || ''}`)
+    haystackCache.set(record, hay)
+  }
+  return hay
+}
+
 function appendJsonl(file, value) {
   fs.mkdirSync(path.dirname(file), { recursive: true })
   fs.appendFileSync(file, `${JSON.stringify(value)}\n`, 'utf8')
+  dropCache(file)
 }
 
 function writeJsonl(file, values) {
@@ -41,6 +95,7 @@ function writeJsonl(file, values) {
     values.length > 0 ? values.map((value) => JSON.stringify(value)).join('\n') + '\n' : '',
     'utf8'
   )
+  dropCache(file)
 }
 
 // --- Duplicate / quality analysis (mio.memory.analyze) ---------------------
@@ -165,27 +220,60 @@ function cjkBigrams(text) {
   return bigrams
 }
 
+// Split a record's searchable text once. The scorer below used to run four
+// regex passes per record -- [a-z0-9]+ twice (tokenize + latinTokens) and
+// [\u4e00-\u9fff] twice (tokenize + cjkBigrams) -- and materialised a `cjk:`
+// string for every single CJK character, ~1200 allocations for a 600-character
+// record, on every query. One pass that keeps latin words and CJK characters
+// apart is exact: the two token kinds come from disjoint character classes, so
+// looking each up in its own collection scores identically.
+//
+// Measured on the real 1094-record store: 22.05 ms -> 18.16 ms for a full
+// scoring pass (1.21x), with 5470 (record, query) pairs scoring bit-identical.
+const HAYSTACK_PART_RE = /[a-z0-9]+|[\u4e00-\u9fff]/g
+
+function splitHaystack(content) {
+  const parts = String(content || '').toLowerCase().match(HAYSTACK_PART_RE) || []
+  const latin = []
+  const cjkChars = []
+  for (let i = 0; i < parts.length; i += 1) {
+    const part = parts[i]
+    // CJK ideographs are all above U+2000; latin words and digits are not.
+    if (part.charCodeAt(0) > 0x2000) cjkChars.push(part)
+    else latin.push(part)
+  }
+  const cjkSet = new Set(cjkChars)
+  const bigrams = new Set()
+  for (let i = 0; i + 1 < cjkChars.length; i += 1) {
+    bigrams.add(cjkChars[i] + cjkChars[i + 1])
+  }
+  return { latin, cjkSet, bigrams }
+}
+
 function scoreRecord(record, queryText, project, evidence) {
   if (project && record.project && record.project !== project) return 0
-  const content = `${record.content || ''} ${(record.tags || []).join(' ')} ${record.kind || ''}`
-  const haystackTokens = tokenize(content)
-  const haystackLatin = latinTokens(content)
+  // Memoized against the record object itself: see haystackFor above.
+  const hay = haystackFor(record)
   const queryTokens = tokenize(queryText)
   let score = 0
   for (const token of queryTokens) {
-    if (haystackTokens.includes(token)) score += 2
+    if (token.startsWith('cjk:')) {
+      if (hay.cjkSet.has(token.slice(4))) score += 2
+    } else if (hay.latin.includes(token)) {
+      score += 2
+    }
   }
   const queryLatin = queryTokens.filter((token) => !token.startsWith('cjk:'))
   for (const token of queryLatin) {
     if (
       token.length >= 3 &&
-      haystackLatin.some((item) => item.startsWith(token) || token.startsWith(item))
+      hay.latin.some((item) => item.startsWith(token) || token.startsWith(item))
     ) {
       score += 1
     }
   }
   const queryBigrams = cjkBigrams(queryText)
-  const haystackBigrams = cjkBigrams(content)
+  const haystackBigrams = hay.bigrams
   if (queryBigrams.size > 0 && haystackBigrams.size > 0) {
     let matched = 0
     for (const bigram of queryBigrams) {
@@ -255,7 +343,7 @@ function createMemoryStore(options = {}) {
 
   function loadEvidenceWeights() {
     const weights = new Map()
-    for (const record of readJsonl(experienceReusePath)) {
+    for (const record of readJsonlCached(experienceReusePath)) {
       if (!verifiedFilter(record)) continue
       const id = record.experienceId
       if (!id) continue
@@ -286,16 +374,24 @@ function createMemoryStore(options = {}) {
     const scoreFor = (record) =>
       scoreRecord(record, query, project, evidence) +
       (scope === 'all' && isGlobalRecord(record) ? 0.5 : 0)
-    const results = readJsonl(memoryPath)
-      .filter((record) => record.archived !== true)
-      .filter((record) => matchesMemoryFilters(record, kind, tags))
-      .filter((record) => matchesProjectScope(record, project, scope))
-      .filter((record) => scoreFor(record) > 0)
-      .sort((a, b) => {
-        return scoreFor(b) - scoreFor(a)
-      })
+    // Score every candidate exactly once, then sort the scored pairs. Calling
+    // scoreFor() inside the comparator re-ran the whole tokenizer + CJK bigram
+    // scan O(n log n) times instead of O(n): measured on the real 1094-record
+    // store, one query invoked the scorer 6214 times (5.7x) and spent 84 ms of
+    // its 111 ms there. Sorting precomputed pairs is behaviour-identical --
+    // Array#sort is stable, so ties keep their original file order either way.
+    const scored = []
+    for (const record of readJsonlCached(memoryPath)) {
+      if (record.archived === true) continue
+      if (!matchesMemoryFilters(record, kind, tags)) continue
+      if (!matchesProjectScope(record, project, scope)) continue
+      const score = scoreFor(record)
+      if (score > 0) scored.push({ record, score })
+    }
+    const results = scored
+      .sort((a, b) => b.score - a.score)
       .slice(0, limit)
-      .map((record) => {
+      .map(({ record }) => {
         const ev = evidence.get(record.id)
         if (!ev) return record
         return {
@@ -361,7 +457,7 @@ function createMemoryStore(options = {}) {
     const limit = Math.min(Math.max(Number(args.limit) || 20, 1), 200)
     const includePayload = args.include_payload !== false
 
-    const all = readJsonl(tracePath)
+    const all = readJsonlCached(tracePath)
     const matched = all.filter((trace) => {
       if (!trace || typeof trace !== 'object') return false
       if (project && trace.project !== project) return false
@@ -442,7 +538,7 @@ function createMemoryStore(options = {}) {
   function analyzeMemory(args = {}) {
     const project = args.project || projectName()
     const limit = Math.min(Math.max(Number(args.limit) || 5, 1), 20)
-    const records = readJsonl(memoryPath).filter(
+    const records = readJsonlCached(memoryPath).filter(
       (record) => !project || record.project === project || !record.project
     )
     const archived = records.filter((record) => record.archived === true).length
@@ -536,7 +632,7 @@ function createMemoryStore(options = {}) {
     const project = args.project || projectName()
     const reason = args.reason ? String(args.reason).trim().slice(0, 200) : null
 
-    const records = readJsonl(memoryPath)
+    const records = readJsonlCached(memoryPath)
     const idSet = new Set(ids)
     const updated = []
     const unchanged = []
@@ -593,7 +689,7 @@ function createMemoryStore(options = {}) {
     // because "which divergence wins" is then undefined.
     const allowDivergent = args.allowDivergent === true || args.allowDivergent === 'true'
 
-    const records = readJsonl(memoryPath)
+    const records = readJsonlCached(memoryPath)
     const idSet = new Set(ids)
     // The project filter must be applied once, up front. Applying it only in the
     // archive loop let a mismatched project still rewrite the survivor's
@@ -736,7 +832,7 @@ function createMemoryStore(options = {}) {
     const restore = args.restore === true || args.restore === 'true'
     const reason = args.reason ? String(args.reason).trim().slice(0, 200) : null
 
-    const records = readJsonl(memoryPath)
+    const records = readJsonlCached(memoryPath)
     const idSet = new Set(ids)
     const archived = []
     // Ids that exist but are already in the requested state. Reported separately
@@ -795,7 +891,7 @@ function createMemoryStore(options = {}) {
     const reason = args.reason ? String(args.reason).trim().slice(0, 200) : null
     const by = args.by ? String(args.by).trim().slice(0, 80) : null
 
-    const records = readJsonl(memoryPath)
+    const records = readJsonlCached(memoryPath)
     const idSet = new Set(ids)
     const forgotten = []
     const notFound = [...ids]
@@ -875,4 +971,4 @@ function createMemoryStore(options = {}) {
 
 // Module-level exports let sibling stores (e.g. experience-store.js) reuse the
 // same JSONL primitives instead of duplicating them and drifting apart.
-module.exports = { createMemoryStore, createId, readJsonl, appendJsonl, writeJsonl }
+module.exports = { createMemoryStore, createId, readJsonl, readJsonlCached, appendJsonl, writeJsonl }

package/server/mio-intelligence-mcp/index.js

@@ -13,6 +13,7 @@ const { createMemoryStore } = require('../memory-store.js')
 const { createExperienceStore, REUSE_STATUS_FILTERS } = require('../experience-store.js')
 const { createPolicyStore } = require('../policy-store.js')
 const { createAgentStore } = require('../agent-store.js')
+const { createEvaluationStore } = require('../evaluation-store.js')
 const { createTaskStore } = require('../task-store.js')
 const { createQueryLog } = require('../query-log.js')
 const { createSubscriptionStore } = require('../subscription-store.js')
@@ -216,6 +217,10 @@ const { policyCheck } = policyStore
 const agentStore = createAgentStore({ dataDir, projectName })
 const { listAgents, reportAgent, registerAgent } = agentStore
 
+// ADR-017 evaluation metrics, same store the CLI uses (`mio agents evaluation`).
+const evaluationStore = createEvaluationStore({ dataDir, projectName })
+const evaluateAgents = (args) => evaluationStore.evaluate(args)
+
 // task.route delegates to the shared store so the CLI (`mio task route`) and
 // this MCP tool route identically. The MCP keeps feeding the query log
 // (auto-claim depends on it); the CLI passes persistQuery: false.
@@ -541,6 +546,18 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'mio.agent.evaluation',
+    description:
+      'ADR-017 evaluation-period metrics: route adoption rate, behaviour change rate, recall quality, and data hygiene (pending auto-claim ratio). Each metric reports its own denominator, so a null rate means "no samples" rather than "zero".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project name filter. Defaults to current repository.' },
+        since: { type: 'string', description: 'ISO timestamp; only count records at or after it.' },
+      },
+    },
+  },
   {
     name: 'mio.evolution.report',
     description: 'Generate cross-agent evolution report: ecosystem summary, agent performance comparison, cross-agent patterns, memory health, and optimization suggestions (ADR-017 Evolution plane).',
@@ -976,6 +993,8 @@ async function callTool(name, args = {}) {
       return listAgents(args)
     case 'mio.agent.report':
       return reportAgent(args)
+    case 'mio.agent.evaluation':
+      return evaluateAgents(args)
     case 'mio.evolution.report':
       return evolutionReport(args)
     case 'mio.evolution.status':

package/server/mio-intelligence-mcp/phase0.js

@@ -1,7 +1,7 @@
 'use strict'
 
-const fs = require('fs')
 const path = require('path')
+const { readJsonlCached } = require('../memory-store.js')
 
 const PHASE0_THRESHOLDS = Object.freeze({
   minHosts: 2,
@@ -55,22 +55,6 @@ function normalizeEventType(value) {
   return eventType || null
 }
 
-function readJsonl(filePath) {
-  if (!fs.existsSync(filePath)) return []
-  return fs
-    .readFileSync(filePath, 'utf8')
-    .split(/\r?\n/)
-    .filter(Boolean)
-    .map((line) => {
-      try {
-        return JSON.parse(line)
-      } catch (_) {
-        return null
-      }
-    })
-    .filter(Boolean)
-}
-
 function filterByProject(records, project) {
   if (!project) return records
   return records.filter((record) => readString(record, 'project') === project)
@@ -279,9 +263,9 @@ function analyzePhase0(dataset) {
 
 function loadPhase0(dataDir, project) {
   const normalizedProject = project && project.trim() ? project.trim() : undefined
-  const memories = readJsonl(path.join(dataDir, 'memory.jsonl')).map(asRecord).filter(Boolean)
-  const traces = readJsonl(path.join(dataDir, 'traces.jsonl')).map(asRecord).filter(Boolean)
-  const reuseRecords = readJsonl(path.join(dataDir, 'experience_reuse.jsonl'))
+  const memories = readJsonlCached(path.join(dataDir, 'memory.jsonl')).map(asRecord).filter(Boolean)
+  const traces = readJsonlCached(path.join(dataDir, 'traces.jsonl')).map(asRecord).filter(Boolean)
+  const reuseRecords = readJsonlCached(path.join(dataDir, 'experience_reuse.jsonl'))
     .map(asRecord)
     .filter(Boolean)
 

package/server/policy-store.js

@@ -12,7 +12,7 @@
 
 const path = require('path')
 
-const { readJsonl } = require('./memory-store.js')
+const { readJsonlCached } = require('./memory-store.js')
 
 // Outcomes that count against an action. `retry` is included because a retried
 // action is evidence the first attempt did not simply work.
@@ -139,7 +139,7 @@ function createPolicyStore(options = {}) {
     if (!action) throw new Error('policy.check requires action')
     const project = args.project || projectName()
     const actionTokens = tokenize(action)
-    const allTraces = readJsonl(tracePath)
+    const allTraces = readJsonlCached(tracePath)
     const scopedTraces = allTraces.filter(
       (event) => !(project && event.project && event.project !== project)
     )
@@ -186,7 +186,7 @@ function createPolicyStore(options = {}) {
       suggestion = 'Low historical risk. Proceed with normal checks.'
     }
     const evidence = loadEvidenceWeights()
-    const relatedMemories = readJsonl(memoryPath)
+    const relatedMemories = readJsonlCached(memoryPath)
       .filter((record) => scoreRecord(record, action, project, evidence) > 0)
       .sort(
         (a, b) => scoreRecord(b, action, project, evidence) - scoreRecord(a, action, project, evidence)

package/server/query-log.js

@@ -12,9 +12,8 @@
 // mio-intelligence-mcp/index.js, one in task-store.js -- which had to be kept
 // equivalent by hand.
 
-const fs = require('fs')
 const path = require('path')
-const { readJsonl } = require('./memory-store.js')
+const { readJsonlCached, writeJsonl } = require('./memory-store.js')
 
 const MAX_RECENT_QUERIES = 200
 
@@ -31,7 +30,7 @@ function createQueryLog(options = {}) {
 
   function load() {
     const now = Date.now()
-    return readJsonl(queryPath)
+    return readJsonlCached(queryPath)
       .filter(
         (entry) =>
           entry &&
@@ -45,12 +44,7 @@ function createQueryLog(options = {}) {
 
   function persist(entries) {
     const limited = entries.slice(-MAX_RECENT_QUERIES)
-    fs.mkdirSync(dataDir, { recursive: true })
-    fs.writeFileSync(
-      queryPath,
-      limited.length > 0 ? limited.map((entry) => JSON.stringify(entry)).join('\n') + '\n' : '',
-      'utf8'
-    )
+    writeJsonl(queryPath, limited)
     return limited
   }
 

package/server/retention.js

@@ -8,6 +8,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const { writeJsonl } = require('./memory-store.js')
 
 // Age-based JSONL stores (records carry an ISO `timestamp` field).
 const AGE_BASED_FILES = ['traces.jsonl', 'experience_reuse.jsonl']
@@ -41,15 +42,6 @@ function createRetention(options = {}) {
     return backup
   }
 
-  function writeJsonl(file, values) {
-    fs.mkdirSync(path.dirname(file), { recursive: true })
-    fs.writeFileSync(
-      file,
-      values.length > 0 ? values.map((value) => JSON.stringify(value)).join('\n') + '\n' : '',
-      'utf8'
-    )
-  }
-
   function planAgeBased(name, cutoff) {
     const file = path.join(home, name)
     const records = readJsonl(file)

package/server/subscription-store.js

@@ -9,10 +9,56 @@
 // would mean one store with two different notions of "where the data lives".
 //
 // The digest is cursor-based: digest_state.json records, per subscription, the
-// timestamp of the newest event already delivered. Running it again therefore
+// position of the newest event already delivered. Running it again therefore
 // returns only what is new -- which is the point, but also why a digest is not
 // idempotent and the cursor must be written even when nothing matched (otherwise
 // a subscription created just now would replay the whole trace history).
+//
+// A cursor is `{ time, id }` and is an *exclusive* bound: an event is delivered
+// iff it sorts strictly after it, with `id` breaking ties inside a millisecond.
+// The tie-break is not cosmetic. Both timestamps in play come from the same wall
+// clock -- task-store.js stamps the event, digest() stamps the cursor -- and the
+// gap between them is one small writeFileSync, so comparing time alone silently
+// swallowed every event that shared a millisecond with the cursor, permanently,
+// because the cursor only moves forward. Measured 2026-09-22: that gap is ~2ms
+// on a Defender-scanned Windows box but sub-millisecond on a CI runner, which is
+// why `digest respects topic filter` passed 30/30 locally and flaked about half
+// the time on CI. See __tests__/observer-digest-cursor.test.js.
+//
+// The `id` field has three states, and the difference matters:
+//   ''     a wall-clock cursor: digest() found nothing to deliver, so nothing at
+//          that instant has been consumed. The empty string sorts below every
+//          real id, so same-millisecond events are still delivered.
+//   null   a legacy cursor, written before the tie-break existed as a bare ISO
+//          string. `null` sorts above every real id, reproducing the old
+//          inclusive time comparison exactly -- so an upgrade never re-delivers.
+//   '<id>' an event cursor: the event with that id has been delivered.
+const WALL_CURSOR_ID = ''
+
+function readCursor(raw) {
+  if (typeof raw === 'string') {
+    const time = Date.parse(raw)
+    return Number.isFinite(time) ? { time, id: null } : null
+  }
+  if (raw && typeof raw === 'object' && typeof raw.time === 'string') {
+    const time = Date.parse(raw.time)
+    if (!Number.isFinite(time)) return null
+    return { time, id: typeof raw.id === 'string' ? raw.id : null }
+  }
+  return null
+}
+
+// Exclusive: true when `event` sorts strictly after `cursor`.
+function isNewEvent(eventTime, eventId, cursor) {
+  if (!cursor || cursor.time === null || eventTime === null) return true
+  if (eventTime !== cursor.time) return eventTime > cursor.time
+  // Same millisecond -- fall back to the id. Ids are `trace_<ms>_<hex>`, so the
+  // order inside a millisecond is by the random suffix: arbitrary, but stable,
+  // which is all "do not deliver twice" needs.
+  if (cursor.id === null) return false
+  if (typeof eventId !== 'string' || eventId === '') return true
+  return eventId > cursor.id
+}
 
 const fs = require('fs')
 const path = require('path')
@@ -148,10 +194,10 @@ function createSubscriptionStore(options = {}) {
     const matchedSubscriptionIds = new Set()
 
     for (const subscription of subscriptions) {
-      const cursor = state[subscription.id] || null
-      const cursorTime = cursor ? Date.parse(cursor) : null
+      const cursor = readCursor(state[subscription.id])
       const subscriptionEventTypes = subscription.eventTypes || []
       let lastEventTime = null
+      let lastEventId = WALL_CURSOR_ID
       for (const event of traces) {
         if (subscription.project && event.project && event.project !== subscription.project) {
           continue
@@ -168,9 +214,17 @@ function createSubscriptionStore(options = {}) {
           if (!haystack.includes(subscription.topic.toLowerCase())) continue
         }
         const eventTime = event.timestamp ? Date.parse(event.timestamp) : null
-        if (cursorTime !== null && eventTime !== null && eventTime <= cursorTime) continue
-        if (eventTime !== null && (lastEventTime === null || eventTime > lastEventTime)) {
-          lastEventTime = eventTime
+        if (!isNewEvent(eventTime, event.id, cursor)) continue
+        if (eventTime !== null) {
+          if (lastEventTime === null || eventTime > lastEventTime) {
+            lastEventTime = eventTime
+            lastEventId = typeof event.id === 'string' ? event.id : WALL_CURSOR_ID
+          } else if (eventTime === lastEventTime && typeof event.id === 'string' && event.id > lastEventId) {
+            // Several delivered events share the newest millisecond. The cursor
+            // has to sit on the highest id among them, otherwise the next digest
+            // would hand the lower ones out again.
+            lastEventId = event.id
+          }
         }
         if (seenIds.has(event.id)) continue
         seenIds.add(event.id)
@@ -189,9 +243,9 @@ function createSubscriptionStore(options = {}) {
       // Advance the cursor even when nothing matched: a brand-new subscription
       // has no cursor, and without this it would replay the entire history.
       if (lastEventTime !== null) {
-        state[subscription.id] = new Date(lastEventTime).toISOString()
+        state[subscription.id] = { time: new Date(lastEventTime).toISOString(), id: lastEventId }
       } else if (cursor === null) {
-        state[subscription.id] = digestTime
+        state[subscription.id] = { time: digestTime, id: WALL_CURSOR_ID }
       }
       if (events.length >= limit) break
     }