@mono-agent/agent-runtime 0.14.0 → 0.15.0

package/MIGRATION.md

@@ -1,7 +1,7 @@
 # `@mono-agent/agent-runtime` — Migration Guide
 
 Breaking and behavioral changes for consumers upgrading from `0.3.x` to the
-current `0.13.x` contract. `createRuntime()` remains the package entry point;
+current pre-1.0 contract. `createRuntime()` remains the package entry point;
 `createMonoRuntime()` remains the typed facade in
 `@mono-agent/runtime-adapter`. Provider-session input/output uses
 `providerSessionId`, with `disposeSession()` and `disposeAllSessions()` retained.
@@ -13,6 +13,17 @@ primary route.
 
 ---
 
+## Pre-1.0 public-surface cleanup
+
+The compatibility entrypoints `./ai/backend.js` and `./ai/registry.js` were
+removed after repository-wide reachability checks found no supported caller.
+The old `findProviderForModel` / `listProviders` aliases and provider/backend
+constant objects were removed at the same time. Import `resolveRuntimeBridge`
+or `listRuntimeBridges` from `@mono-agent/agent-runtime` (or its `./ai` barrel)
+instead. Runtime behavior and the canonical bridge descriptors are unchanged.
+
+---
+
 ## 1. Pi is now native-only (`pi-sdk.js` → `pi-native.js`)
 
 The hand-rolled Pi bridge that drove the low-level `Agent` was replaced by a
@@ -209,7 +220,7 @@ now a loud failure (guarded by `scripts/verify-deep-imports.mjs`).
 <!-- public-api-js-subpaths:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
 
-The package exposes **22 named deep `.js` subpaths**:
+The package exposes **21 named deep `.js` subpaths**:
 
 ```text
 @mono-agent/agent-runtime/agent/allowlists.js
@@ -219,7 +230,6 @@ The package exposes **22 named deep `.js` subpaths**:
 @mono-agent/agent-runtime/agent/tools/shared/ripgrep.js
 @mono-agent/agent-runtime/agent/tools/shared/runtime-context.js
 @mono-agent/agent-runtime/agent/transcript.js
-@mono-agent/agent-runtime/ai/backend.js
 @mono-agent/agent-runtime/ai/cost.js
 @mono-agent/agent-runtime/ai/failure.js
 @mono-agent/agent-runtime/ai/file-change-stats.js

package/README.md

@@ -142,13 +142,11 @@ discoverClaudeSdkModels
 disposeAllProviderSessions
 disposeProviderSession
 executionModeIncompatibilityReason
-findProviderForModel
 generatePiNativeResponse
 inferAllowlistMode
 invalidateProviderSession
 isLikelyContextTermination
 isModelCompatibleWithExecutionMode
-listProviders
 listRuntimeBridges
 normalizeAllowlistMode
 normalizeClaudeSdkCatalog
@@ -311,11 +309,9 @@ discoverClaudeSdkModels
 disposeAllProviderSessions
 disposeProviderSession
 executionModeIncompatibilityReason
-findProviderForModel
 generatePiNativeResponse
 invalidateProviderSession
 isModelCompatibleWithExecutionMode
-listProviders
 listRuntimeBridges
 normalizeClaudeSdkCatalog
 normalizeClaudeSdkModelId
@@ -330,15 +326,6 @@ syncProviderSession
 toolCompactionAppliedFromWarnings
 ```
 
-**`@mono-agent/agent-runtime/ai/backend.js`**
-
-```text
-BACKEND_CAPABILITIES
-backendCapabilities
-backendSupportsSessionResume
-backendUsesExecenvConfig
-```
-
 **`@mono-agent/agent-runtime/ai/cost.js`**
 
 ```text
@@ -388,9 +375,7 @@ formatLiveInputGuidance
 
 ```text
 buildCliCommand
-claudeCodeBackend
 claudeCodeRuntimeBridge
-codexCliBackend
 createThinkingBuffer
 generateCliResponse
 normalizeCliEvent
@@ -414,7 +399,6 @@ normalizeClaudeSdkModelId
 ```text
 claudeEffortOptions
 claudeRuntimeBridge
-claudeSdkBackend
 claudeSdkModelForQuery
 generateClaudeResponse
 toolPayloadLimit
@@ -423,7 +407,6 @@ toolPayloadLimit
 **`@mono-agent/agent-runtime/ai/providers/codex-app.js`**
 
 ```text
-codexAppBackend
 codexAppRuntimeBridge
 createCodexAppServerClient
 generateCodexAppResponse
@@ -645,7 +628,7 @@ Per-call options (a non-exhaustive selection):
 | `maxTurns` | `number` | Hard cap on agent turns. |
 | `outputSchema` | `JSONSchema` | Requests structured JSON on capable bridges; see “Structured output” below for bridge-specific return behavior. |
 | `abortSignal` | `AbortSignal` | Cancel the run. |
-| `liveInput` | `AsyncIterable<{ body: string; id?: string }>` | Stream of in-flight user messages for steering on capable bridges. |
+| `liveInput` | `AsyncIterable<{ body: string; id?: string; receivedAt?: string; acknowledge?: () => void; reject?: (error?: unknown) => void }>` | Stream of in-flight user messages for steering on capable bridges. A bridge acknowledges only after its native steering boundary accepts the message; per-attempt rejection permits router replay. |
 | `onEvent` | `(event) => void` | Fired for every event the provider emits (assistant text, tool calls/results, runtime warnings, structured output). |
 | `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
 | `providerSessionId` | `string` | Resume a prior provider session. |
@@ -653,6 +636,10 @@ Per-call options (a non-exhaustive selection):
 | `codexAppServerCommand` | `string` | Override the Codex CLI binary. |
 | `codexAppServerArgs` | `string[]` | Override the Codex CLI arguments. |
 
+Live input is native on the Claude SDK, Codex app-server, and Pi bridges. The
+one-shot Claude CLI and direct OpenCode bridges advertise it as unsupported so
+routers skip them when a direct runtime call requires steering.
+
 Returns:
 
 ```ts
@@ -693,6 +680,23 @@ Returns:
 
 `capabilitiesUsed` is the per-call complement to `runtimeCapabilities()`. Tristate fields use `null` to mean "this provider can't tell" — distinct from `false` ("definitely off"). It's also emitted as a `capabilities_resolved` event near the end of the run, so observers can capture it without inspecting the result object.
 
+Successful provider requests may also emit exact context telemetry through
+`onEvent` and `result.events`:
+
+- `context_usage` is one provider-counted request snapshot, never the run's
+  aggregate processed-token total. Pi emits it at each successful assistant
+  `message_end`; Codex uses `thread/tokenUsage/updated.tokenUsage.last`; direct
+  OpenCode requires a completed assistant message with native `tokens.total`.
+  Each event identifies the measured model and includes `contextWindow` only
+  when the provider's own model metadata supplied it. The Claude bridges do not
+  currently emit this event.
+- `context_compaction` is a lifecycle event with a stable `operationId`,
+  `status` (`running`, `succeeded`, `skipped`, or `failed`), `sdk`, `trigger`,
+  `timestamp`, and optional safe reason/model/count fields. Pi drives and emits
+  its own lifecycle; Codex and OpenCode normalize their native notifications and
+  suppress deprecated duplicate notifications. Pi's before/after counts are
+  estimates and explicitly set `tokenCountsExact: false`.
+
 ### Built-in tools
 
 The agent kernel's managed tools are `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `NodeRepl`, `WebFetch`, and `WebSearch`. `NodeRepl({ code })` is backed by one lazily started Node.js REPL child per run. You select them via `allowedTools`. Tool implementations honor:
@@ -784,7 +788,7 @@ console.log(metrics.snapshot());
 //   cache: { hits, misses, hitRatio, readTokensFromEvents },
 //   tools: { callsByName: { Bash: 3, Read: 2 }, errorsByName: { ... } },
 //   errors: { total, byKind: { provider_unavailable: 1 } },
-//   turns: { count, latencyMsP50, latencyMsP95 },
+//   turns: { count, sampleCount, latencyMsP50, latencyMsP95 },
 //   approvals: { pending, granted, denied },
 // }
 ```
@@ -868,6 +872,10 @@ correction, while learned evidence may still lower it.
 Runs report `context_compaction_applied: true` (fired), `false` (enabled but not needed),
 or `null` (disabled), plus request-estimate, fixed-overhead, reactive-attempted,
 tokens-after, and reduced diagnostics.
+Every attempt also emits one `context_compaction` start and exactly one terminal
+lifecycle event. A successful retry then emits a new exact `context_usage`
+snapshot, allowing consumers to discard the pre-compaction value rather than
+guessing the resulting occupancy from the compaction estimate.
 Persistent overflow is classified as `context_limit`, allowing the fallback router to
 try the next configured model. The other backends manage their windows per their own behavior.
 (`docs/reference/feature-registry.md` is the source of truth for this row.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, and Pi SDK bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -39,10 +39,6 @@
       "types": "./types/ai/cost.d.ts",
       "default": "./src/ai/cost.js"
     },
-    "./ai/backend.js": {
-      "types": "./types/ai/backend.d.ts",
-      "default": "./src/ai/backend.js"
-    },
     "./ai/runtime/model-refs.js": {
       "types": "./types/ai/runtime/model-refs.d.ts",
       "default": "./src/ai/runtime/model-refs.js"
@@ -147,6 +143,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.types.json",
-    "test": "vitest run --passWithNoTests"
+    "typecheck": "tsc -p tsconfig.types.json --noEmit",
+    "test": "vitest run"
   }
 }

package/src/ai/index.js

@@ -1,6 +1,5 @@
 // Public surface of the provider layer.
 
-export * from "./registry.js";
 export * from "./runtime/model-refs.js";
 export * from "./runtime/registry.js";
 export {

package/src/ai/observer.js

@@ -82,10 +82,11 @@ function addObserver(list, observer) {
 //   cache: { hits, misses, hitRatio },          // hitRatio in [0,1]; null if no signal
 //   tools: { callsByName: { ... }, errorsByName: { ... } },
 //   errors: { total, byKind: { ... } },
-//   turns: { count, latencyMsP50, latencyMsP95 },
+//   turns: { count, sampleCount, latencyMsP50, latencyMsP95 },
 //   approvals: { pending, granted, denied },
 // }
-export function createMetricsObserver({ name = "metrics" } = {}) {
+export function createMetricsObserver({ name = "metrics", maxLatencySamples = 2_048 } = {}) {
+  const latencySampleLimit = normalizePositiveInteger(maxLatencySamples, 2_048);
   const state = {
     eventsTotal: 0,
     eventsByType: new Map(),
@@ -99,7 +100,8 @@ export function createMetricsObserver({ name = "metrics" } = {}) {
     errorTotal: 0,
     errorsByKind: new Map(),
     turnLatencies: [],
-    turnStartByModel: new Map(),
+    turnLatencyCount: 0,
+    pendingTurnStarts: [],
     approvalPending: 0,
     approvalGranted: 0,
     approvalDenied: 0,
@@ -167,17 +169,24 @@ export function createMetricsObserver({ name = "metrics" } = {}) {
     }
 
     if (type === "provider_request_started" && event.model) {
-      state.turnStartByModel.set(event.model, (Number.isFinite(event.timestamp) ? event.timestamp : Date.now()));
+      state.pendingTurnStarts.push({
+        key: latencyEventKey(event),
+        model: String(event.model),
+        timestamp: Number.isFinite(event.timestamp) ? event.timestamp : Date.now(),
+      });
+      if (state.pendingTurnStarts.length > latencySampleLimit) state.pendingTurnStarts.shift();
     }
     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);
+      const startIndex = matchingStartIndex(state.pendingTurnStarts, event);
+      const started = startIndex === -1 ? undefined : state.pendingTurnStarts.splice(startIndex, 1)[0];
+      const explicitDuration = Number(event.durationMs);
+      if (Number.isFinite(explicitDuration)) recordTurnLatency(Math.max(0, explicitDuration));
+      else if (started !== undefined) {
+        recordTurnLatency(Math.max(0, ((Number.isFinite(event.timestamp) ? event.timestamp : Date.now())) - started.timestamp));
       }
     }
     if (type === "turn_latency" && Number.isFinite(Number(event.durationMs))) {
-      state.turnLatencies.push(Number(event.durationMs));
+      recordTurnLatency(Math.max(0, Number(event.durationMs)));
     }
 
     if (type === "tool_approval_pending") state.approvalPending += 1;
@@ -187,6 +196,12 @@ export function createMetricsObserver({ name = "metrics" } = {}) {
 
   function recordMetric() { /* future hook */ }
 
+  function recordTurnLatency(durationMs) {
+    state.turnLatencyCount += 1;
+    state.turnLatencies.push(durationMs);
+    if (state.turnLatencies.length > latencySampleLimit) state.turnLatencies.shift();
+  }
+
   function snapshot() {
     const cacheTotal = state.cacheHits + state.cacheMisses;
     const hitRatio = cacheTotal > 0 ? state.cacheHits / cacheTotal : null;
@@ -205,7 +220,7 @@ export function createMetricsObserver({ name = "metrics" } = {}) {
         errorsByName: Object.fromEntries(state.toolErrorsByName),
       },
       errors: { total: state.errorTotal, byKind: Object.fromEntries(state.errorsByKind) },
-      turns: percentilesFor(state.turnLatencies),
+      turns: percentilesFor(state.turnLatencies, state.turnLatencyCount),
       approvals: { pending: state.approvalPending, granted: state.approvalGranted, denied: state.approvalDenied },
     };
   }
@@ -213,16 +228,36 @@ export function createMetricsObserver({ name = "metrics" } = {}) {
   return { name, recordEvent, recordMetric, snapshot };
 }
 
-function percentilesFor(samples) {
+function percentilesFor(samples, count = samples.length) {
   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 };
+  if (!arr.length) return { count, sampleCount: 0, latencyMsP50: null, latencyMsP95: null };
   return {
-    count: arr.length,
+    count,
+    sampleCount: arr.length,
     latencyMsP50: percentile(arr, 0.5),
     latencyMsP95: percentile(arr, 0.95),
   };
 }
 
+function latencyEventKey(event) {
+  const requestId = event.requestId ?? event.turnId;
+  return requestId === undefined || requestId === null ? undefined : String(requestId);
+}
+
+function matchingStartIndex(starts, event) {
+  const key = latencyEventKey(event);
+  if (key !== undefined) {
+    const keyedIndex = starts.findIndex((start) => start.key === key);
+    if (keyedIndex !== -1) return keyedIndex;
+  }
+  return starts.findIndex((start) => start.model === String(event.model));
+}
+
+function normalizePositiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isSafeInteger(number) && number > 0 ? number : fallback;
+}
+
 function percentile(sortedArr, q) {
   if (!sortedArr.length) return null;
   const rank = q * (sortedArr.length - 1);

package/src/ai/providers/claude-cli.js

@@ -83,7 +83,8 @@ const DORMANT_CLI_CAPABILITIES = {
   supports_mcp: true,
   supports_skills: true,
   supports_builtin_tools: true,
-  supports_live_input: true,
+  // The one-shot CLI bridge cannot add stdin messages after process launch.
+  supports_live_input: false,
   supports_native_subagents: true,
 };
 
@@ -776,18 +777,6 @@ export async function generateCliResponse(systemPrompt, options = {}) {
   }
 }
 
-export const claudeCodeBackend = {
-  kind: "claude-code",
-  capabilities: { kind: "claude-code", runtime: "cli", ...DORMANT_CLI_CAPABILITIES },
-  execute: generateCliResponse,
-};
-
-export const codexCliBackend = {
-  kind: "codex-cli",
-  capabilities: { kind: "codex-cli", runtime: "cli", ...DORMANT_CLI_CAPABILITIES },
-  execute: generateCliResponse,
-};
-
 // CLI bridge for sdk='claude' agents that opt into execution_mode='cli'.
 // generateCliResponse internally branches on resolved.sdk; the SDK shape
 // from parseModelReference uses 'claude', the CLI builder expects

package/src/ai/providers/claude-sdk.js

@@ -563,7 +563,18 @@ function createClaudeCanUseTool(approvalManager, modelName) {
 async function* livePromptMessages({ initialPrompt, liveInput, sessionId, prompts }) {
   yield makeSdkUserMessage(initialPrompt, sessionId);
   for await (const message of liveInput) {
-    yield makeSdkUserMessage(formatLiveInputGuidance(message.body, prompts), sessionId, message.id || randomUUID());
+    try {
+      const sdkMessage = makeSdkUserMessage(
+        formatLiveInputGuidance(message.body, prompts),
+        sessionId,
+        message.id || randomUUID(),
+      );
+      message.acknowledge?.();
+      yield sdkMessage;
+    } catch (err) {
+      message.reject?.(err);
+      throw err;
+    }
   }
 }
 
@@ -1051,12 +1062,6 @@ export async function generateClaudeResponse(systemPrompt, options) {
   };
 }
 
-export const claudeSdkBackend = {
-  kind: "claude",
-  capabilities: runtimeCapabilities("claude"),
-  execute: generateClaudeResponse,
-};
-
 export const claudeRuntimeBridge = {
   id: "claude",
   kind: "claude",