@mono-agent/agent-runtime 0.1.0

package/src/ai/file-change-stats.js

@@ -0,0 +1,234 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+const FILE_CHANGE_SNAPSHOT_LIMIT_BYTES = 300_000;
+const FILE_CHANGE_DIFF_LINE_LIMIT = 4000;
+const FILE_CHANGE_HUNK_LINE_LIMIT = 2000;
+
+function splitFileLines(text) {
+  if (!text) return [];
+  const lines = String(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+export function readFileChangeSnapshot(path) {
+  try {
+    if (!path || !existsSync(path)) return { exists: false, line_count: 0 };
+    const stat = statSync(path);
+    if (!stat.isFile()) return { exists: false, line_count: 0, unavailable_reason: "not_file" };
+    if (stat.size > FILE_CHANGE_SNAPSHOT_LIMIT_BYTES) {
+      return { exists: true, size: stat.size, unavailable_reason: "too_large" };
+    }
+    const content = readFileSync(path, "utf8");
+    return {
+      exists: true,
+      size: stat.size,
+      content,
+      line_count: splitFileLines(content).length,
+    };
+  } catch (err) {
+    return { exists: false, line_count: 0, unavailable_reason: err?.code || "read_failed" };
+  }
+}
+
+function rollingLcsCount(beforeLines, afterLines) {
+  let previous = new Array(afterLines.length + 1).fill(0);
+  let current = new Array(afterLines.length + 1).fill(0);
+  for (let i = 1; i <= beforeLines.length; i += 1) {
+    for (let j = 1; j <= afterLines.length; j += 1) {
+      current[j] = beforeLines[i - 1] === afterLines[j - 1]
+        ? previous[j - 1] + 1
+        : Math.max(previous[j], current[j - 1]);
+    }
+    [previous, current] = [current, previous.fill(0)];
+  }
+  return previous[afterLines.length];
+}
+
+function fullLcsTableWithHunks(beforeLines, afterLines) {
+  const m = beforeLines.length;
+  const n = afterLines.length;
+  const stride = n + 1;
+  const dp = new Uint16Array((m + 1) * stride);
+  for (let i = 1; i <= m; i += 1) {
+    const row = i * stride;
+    const prev = (i - 1) * stride;
+    for (let j = 1; j <= n; j += 1) {
+      dp[row + j] = beforeLines[i - 1] === afterLines[j - 1]
+        ? dp[prev + (j - 1)] + 1
+        : Math.max(dp[prev + j], dp[row + (j - 1)]);
+    }
+  }
+  const common = dp[m * stride + n];
+  const changedAfter = [];
+  let i = m;
+  let j = n;
+  while (i > 0 && j > 0) {
+    if (beforeLines[i - 1] === afterLines[j - 1]) {
+      i -= 1; j -= 1;
+    } else if (dp[(i - 1) * stride + j] >= dp[i * stride + (j - 1)]) {
+      i -= 1;
+    } else {
+      changedAfter.push(j);
+      j -= 1;
+    }
+  }
+  while (j > 0) {
+    changedAfter.push(j);
+    j -= 1;
+  }
+  changedAfter.reverse();
+  return { common, hunks: positionsToRanges(changedAfter) };
+}
+
+function positionsToRanges(positions) {
+  if (!positions.length) return [];
+  const ranges = [];
+  let start = positions[0];
+  let end = positions[0];
+  for (let i = 1; i < positions.length; i += 1) {
+    if (positions[i] === end + 1) {
+      end = positions[i];
+    } else {
+      ranges.push({ start, end });
+      start = positions[i];
+      end = positions[i];
+    }
+  }
+  ranges.push({ start, end });
+  return ranges;
+}
+
+function lineDiffCounts(beforeContent, afterContent) {
+  const beforeLines = splitFileLines(beforeContent);
+  const afterLines = splitFileLines(afterContent);
+  const before = beforeLines.length;
+  const after = afterLines.length;
+  if (before > FILE_CHANGE_DIFF_LINE_LIMIT || after > FILE_CHANGE_DIFF_LINE_LIMIT) {
+    return {
+      before_lines: before,
+      after_lines: after,
+      unavailable_reason: "too_many_lines",
+    };
+  }
+
+  if (before <= FILE_CHANGE_HUNK_LINE_LIMIT && after <= FILE_CHANGE_HUNK_LINE_LIMIT) {
+    const { common, hunks } = fullLcsTableWithHunks(beforeLines, afterLines);
+    const added = after - common;
+    const removed = before - common;
+    return {
+      before_lines: before,
+      after_lines: after,
+      added_lines: added,
+      removed_lines: removed,
+      changed_lines: added + removed,
+      hunks,
+    };
+  }
+
+  const common = rollingLcsCount(beforeLines, afterLines);
+  const added = after - common;
+  const removed = before - common;
+  return {
+    before_lines: before,
+    after_lines: after,
+    added_lines: added,
+    removed_lines: removed,
+    changed_lines: added + removed,
+  };
+}
+
+export function statsForCompletedChange(change, before, after) {
+  const kind = change?.kind || "change";
+  if (before?.unavailable_reason || after?.unavailable_reason) {
+    return {
+      before_lines: before?.line_count,
+      after_lines: after?.line_count,
+      unavailable_reason: before?.unavailable_reason || after?.unavailable_reason,
+    };
+  }
+  if (kind === "add" && !before?.exists && after?.exists && typeof after.content === "string") {
+    const afterLines = splitFileLines(after.content).length;
+    const stats = { before_lines: 0, after_lines: afterLines, added_lines: afterLines, removed_lines: 0, changed_lines: afterLines };
+    if (afterLines > 0) stats.hunks = [{ start: 1, end: afterLines }];
+    return stats;
+  }
+  if (kind === "delete" && before?.exists && !after?.exists && typeof before.content === "string") {
+    const beforeLines = splitFileLines(before.content).length;
+    return { before_lines: beforeLines, after_lines: 0, added_lines: 0, removed_lines: beforeLines, changed_lines: beforeLines };
+  }
+  if (typeof before?.content === "string" && typeof after?.content === "string") {
+    return lineDiffCounts(before.content, after.content);
+  }
+  if (before?.exists || after?.exists) {
+    return {
+      before_lines: before?.line_count,
+      after_lines: after?.line_count,
+      unavailable_reason: "missing_snapshot",
+    };
+  }
+  return null;
+}
+
+export function fileChangeSummary(changes) {
+  const stats = changes.map((change) => change?.line_stats).filter(Boolean);
+  if (!stats.length) return null;
+  return {
+    files: changes.length,
+    added_lines: stats.reduce((sum, item) => sum + (Number(item.added_lines) || 0), 0),
+    removed_lines: stats.reduce((sum, item) => sum + (Number(item.removed_lines) || 0), 0),
+    changed_lines: stats.reduce((sum, item) => sum + (Number(item.changed_lines) || 0), 0),
+    unavailable_count: stats.filter((item) => item.unavailable_reason).length,
+  };
+}
+
+function snapshotKey(id, path) {
+  return `${id}:${path}`;
+}
+
+export function createFileChangePayload(raw, { cwd = process.cwd(), snapshots = new Map() } = {}) {
+  const item = raw?.item || {};
+  const id = item.id || "file_change";
+  const changes = (Array.isArray(item.changes) ? item.changes : []).map((change) => {
+    const resolvedPath = change?.path ? resolve(cwd, change.path) : "";
+    if (!resolvedPath) return change;
+    if (raw.type === "item.started") {
+      const before = readFileChangeSnapshot(resolvedPath);
+      snapshots.set(snapshotKey(id, resolvedPath), before);
+      return change;
+    }
+    const before = snapshots.get(snapshotKey(id, resolvedPath)) || null;
+    const after = readFileChangeSnapshot(resolvedPath);
+    snapshots.delete(snapshotKey(id, resolvedPath));
+    const lineStats = statsForCompletedChange(change, before, after);
+    return lineStats ? { ...change, line_stats: lineStats } : change;
+  });
+  const summary = fileChangeSummary(changes) || item.summary;
+  return {
+    changes,
+    status: item.status || (raw.type === "item.completed" ? "completed" : "in_progress"),
+    ...(summary ? { summary } : {}),
+  };
+}
+
+export function createFileEditToolUseEvent(id, payload) {
+  return {
+    type: "assistant",
+    message: { content: [{ type: "tool_use", id, name: "file_edit", input: payload }] },
+  };
+}
+
+export function createFileEditToolResultEvent(id, payload, { isError = false } = {}) {
+  return {
+    type: "user",
+    message: {
+      content: [{
+        type: "tool_result",
+        tool_use_id: id,
+        content: payload,
+        is_error: isError,
+      }],
+    },
+  };
+}

package/src/ai/index.js

@@ -0,0 +1,16 @@
+// Public surface of the provider layer.
+
+export * from "./registry.js";
+export * from "./runtime/model-refs.js";
+export * from "./runtime/registry.js";
+export {
+  createSessionRegistry,
+  disposeAllProviderSessions,
+  disposeProviderSession,
+} from "./runtime/sessions.js";
+export { createMetricsObserver, createObserverHub } from "./observer.js";
+export {
+  buildCapabilitiesUsed,
+  toolCompactionAppliedFromWarnings,
+  UNKNOWN_CAPABILITY,
+} from "./runtime/capabilities-used.js";

package/src/ai/live-input-prompt.js

@@ -0,0 +1,15 @@
+// Live-input prompt fragment used by AI providers when injecting human
+// guidance mid-run. Lives in src/ai/ because providers are the only
+// consumers; the queue/normalize/supports helpers stay in core/live-input.js
+// for the API + coordinator + worker callers that don't need this string.
+
+export function formatLiveInputGuidance(text) {
+  return [
+    "Live guidance from the user:",
+    String(text || ""),
+    "",
+    "Apply this guidance before continuing. It may correct, narrow, or override your current approach.",
+    "Keep satisfying the original task and existing comments except where this live guidance conflicts with them.",
+    "When there is a conflict, the newest human live guidance wins. Do not discard the broader task unless the user explicitly asks to replace it.",
+  ].join("\n");
+}

package/src/ai/observer.js

@@ -0,0 +1,233 @@
+// Observer registry + streaming telemetry.
+//
+// The runtime supports multiple observers per call. An observer is anything
+// with a `recordEvent(event)` (and optionally `recordMetric(metric)` and
+// `flush()`) method. Observers register at runtime construction time via
+// `host.observers`, or per-call via `options.observers`. The existing
+// `options.onEvent` callback is still respected — internally it becomes a
+// thin observer so the rest of the kernel can keep emitting events through
+// one channel.
+//
+// A built-in `createMetricsObserver()` aggregates cumulative cost, cache
+// hit rate, token totals, tool-call counts, error counts, and turn-latency
+// percentiles. Hosts that want their own aggregation implement the same
+// interface and register alongside (or instead of) the built-in one.
+//
+// All observers receive events synchronously on the hot path; if an
+// observer needs to do I/O it must buffer internally (zeroclaw uses the
+// same contract — fan-out is sync, batching is the observer's problem).
+
+/**
+ * @typedef Observer
+ * @property {string=} name
+ * @property {(event: object) => void} recordEvent
+ * @property {(metric: object) => void=} recordMetric
+ * @property {() => (void | Promise<void>)=} flush
+ */
+
+export function createObserverHub({ observers = [], onEvent = null } = {}) {
+  const list = [];
+  for (const observer of observers || []) addObserver(list, observer);
+  if (typeof onEvent === "function") {
+    list.push({
+      name: "host.onEvent",
+      recordEvent: (event) => { try { onEvent(event); } catch { /* host emit errors don't escape */ } },
+    });
+  }
+
+  function emit(event) {
+    if (!event) return;
+    for (const obs of list) {
+      try { obs.recordEvent(event); } catch { /* swallow */ }
+    }
+  }
+
+  function recordMetric(metric) {
+    if (!metric) return;
+    for (const obs of list) {
+      if (typeof obs.recordMetric === "function") {
+        try { obs.recordMetric(metric); } catch { /* swallow */ }
+      }
+    }
+  }
+
+  async function flush() {
+    for (const obs of list) {
+      if (typeof obs.flush === "function") {
+        try { await obs.flush(); } catch { /* swallow */ }
+      }
+    }
+  }
+
+  return {
+    emit,
+    recordMetric,
+    flush,
+    observers: () => list.slice(),
+  };
+}
+
+function addObserver(list, observer) {
+  if (!observer || typeof observer.recordEvent !== "function") return;
+  list.push(observer);
+}
+
+// Built-in aggregator. Pure in-memory; never throws.
+//
+// Snapshot shape:
+// {
+//   events: { total, byType: { "tool_use": 12, ... } },
+//   tokens: { input, output, cacheReadTokens, cacheCreationTokens },
+//   cost: { cumulativeUsd },
+//   cache: { hits, misses, hitRatio },          // hitRatio in [0,1]; null if no signal
+//   tools: { callsByName: { ... }, errorsByName: { ... } },
+//   errors: { total, byKind: { ... } },
+//   turns: { count, latencyMsP50, latencyMsP95 },
+//   approvals: { pending, granted, denied },
+// }
+export function createMetricsObserver({ name = "metrics" } = {}) {
+  const state = {
+    eventsTotal: 0,
+    eventsByType: new Map(),
+    tokens: { input: 0, output: 0, cacheReadTokens: 0, cacheCreationTokens: 0 },
+    cumulativeCostUsd: 0,
+    cacheHits: 0,
+    cacheMisses: 0,
+    cacheReadTokensFromEvents: 0,
+    toolCallsByName: new Map(),
+    toolErrorsByName: new Map(),
+    errorTotal: 0,
+    errorsByKind: new Map(),
+    turnLatencies: [],
+    turnStartByModel: new Map(),
+    approvalPending: 0,
+    approvalGranted: 0,
+    approvalDenied: 0,
+  };
+
+  function tally(map, key, by = 1) {
+    if (!key) return;
+    map.set(key, (map.get(key) || 0) + by);
+  }
+
+  function recordEvent(event) {
+    if (!event || typeof event !== "object") return;
+    state.eventsTotal += 1;
+    const type = String(event.type || "unknown");
+    tally(state.eventsByType, type, 1);
+
+    if (type === "tool_use" || (type === "assistant" && Array.isArray(event.message?.content))) {
+      // Walk assistant content blocks for tool_use entries.
+      const blocks = type === "tool_use" ? [event] : (event.message?.content || []);
+      for (const block of blocks) {
+        if (block && block.type === "tool_use" && block.name) tally(state.toolCallsByName, block.name, 1);
+      }
+    }
+
+    if (type === "user" && Array.isArray(event.message?.content)) {
+      for (const block of event.message.content) {
+        if (block && block.type === "tool_result" && block.is_error) {
+          // tool_use_id alone doesn't carry the tool name; bridges set
+          // event.toolName when known. Fallback to "unknown".
+          tally(state.toolErrorsByName, event.toolName || "unknown", 1);
+        }
+      }
+    }
+
+    if (type === "runtime_warning" && event.warning_kind) {
+      // warnings are not errors but worth counting in `errorsByKind` only
+      // when they indicate a failure mode.
+    }
+
+    if (type === "error" || type === "cancelled") {
+      state.errorTotal += 1;
+      tally(state.errorsByKind, event.failureKind || event.reason || type, 1);
+    }
+
+    if (type === "cache_hit") {
+      state.cacheHits += 1;
+      if (Number.isFinite(Number(event.tokens))) state.cacheReadTokensFromEvents += Number(event.tokens);
+    }
+    if (type === "cache_miss") {
+      state.cacheMisses += 1;
+    }
+
+    if (type === "cost_accumulated") {
+      // bridges send the running total, not the delta, so use it as the
+      // current value rather than adding.
+      if (Number.isFinite(Number(event.cumulativeUsd))) {
+        state.cumulativeCostUsd = Number(event.cumulativeUsd);
+      }
+      if (event.tokens && typeof event.tokens === "object") {
+        if (Number.isFinite(Number(event.tokens.input))) state.tokens.input = Number(event.tokens.input);
+        if (Number.isFinite(Number(event.tokens.output))) state.tokens.output = Number(event.tokens.output);
+        if (Number.isFinite(Number(event.tokens.cacheReadTokens))) state.tokens.cacheReadTokens = Number(event.tokens.cacheReadTokens);
+        if (Number.isFinite(Number(event.tokens.cacheCreationTokens))) state.tokens.cacheCreationTokens = Number(event.tokens.cacheCreationTokens);
+      }
+    }
+
+    if (type === "provider_request_started" && event.model) {
+      state.turnStartByModel.set(event.model, (Number.isFinite(event.timestamp) ? event.timestamp : Date.now()));
+    }
+    if (type === "provider_request_completed" && event.model) {
+      const started = state.turnStartByModel.get(event.model);
+      if (started !== undefined) {
+        state.turnLatencies.push(Math.max(0, ((Number.isFinite(event.timestamp) ? event.timestamp : Date.now())) - started));
+        state.turnStartByModel.delete(event.model);
+      }
+    }
+    if (type === "turn_latency" && Number.isFinite(Number(event.durationMs))) {
+      state.turnLatencies.push(Number(event.durationMs));
+    }
+
+    if (type === "tool_approval_pending") state.approvalPending += 1;
+    if (type === "tool_approval_granted") state.approvalGranted += 1;
+    if (type === "tool_approval_denied") state.approvalDenied += 1;
+  }
+
+  function recordMetric() { /* future hook */ }
+
+  function snapshot() {
+    const cacheTotal = state.cacheHits + state.cacheMisses;
+    const hitRatio = cacheTotal > 0 ? state.cacheHits / cacheTotal : null;
+    return {
+      events: { total: state.eventsTotal, byType: Object.fromEntries(state.eventsByType) },
+      tokens: { ...state.tokens },
+      cost: { cumulativeUsd: state.cumulativeCostUsd },
+      cache: {
+        hits: state.cacheHits,
+        misses: state.cacheMisses,
+        hitRatio,
+        readTokensFromEvents: state.cacheReadTokensFromEvents,
+      },
+      tools: {
+        callsByName: Object.fromEntries(state.toolCallsByName),
+        errorsByName: Object.fromEntries(state.toolErrorsByName),
+      },
+      errors: { total: state.errorTotal, byKind: Object.fromEntries(state.errorsByKind) },
+      turns: percentilesFor(state.turnLatencies),
+      approvals: { pending: state.approvalPending, granted: state.approvalGranted, denied: state.approvalDenied },
+    };
+  }
+
+  return { name, recordEvent, recordMetric, snapshot };
+}
+
+function percentilesFor(samples) {
+  const arr = Array.isArray(samples) ? samples.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b) : [];
+  if (!arr.length) return { count: 0, latencyMsP50: null, latencyMsP95: null };
+  return {
+    count: arr.length,
+    latencyMsP50: percentile(arr, 0.5),
+    latencyMsP95: percentile(arr, 0.95),
+  };
+}
+
+function percentile(sortedArr, q) {
+  if (!sortedArr.length) return null;
+  const rank = q * (sortedArr.length - 1);
+  const lo = Math.floor(rank);
+  const hi = Math.ceil(rank);
+  if (lo === hi) return sortedArr[lo];
+  return sortedArr[lo] + (sortedArr[hi] - sortedArr[lo]) * (rank - lo);
+}