@mono-agent/agent-runtime 0.13.0 → 0.15.0

package/README.md

@@ -1,15 +1,104 @@
 # @mono-agent/agent-runtime
 
+Use this package when you need direct, capability-aware access to mono-agent's
+five built-in model runtime bridges.
+
 ## Category
 
+<!-- package-metadata:start -->
+<!-- Generated by scripts/generate-package-docs.mjs. Do not edit by hand. -->
+
 Category: `runtime`
+Tier: `core`
+Catalog responsibility: Provides five runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, OpenCode app-server, Pi SDK); direct OpenCode requires stable CLI >=1.15.0 on PATH.
+
+<!-- package-metadata:end -->
 
 ## Responsibility
 
 Provides five runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, OpenCode app-server, Pi SDK), with capabilities declared per bridge. This is the runtime layer that `@mono-agent/runtime-adapter` wraps behind runtime contracts. Pi enforces optional mono-agent sandbox policy for runtime-owned tools through an injectable `RuntimeSandbox` seam (a fail-closed passthrough by default; `@mono-agent/runtime-adapter` injects the real implementation). The router supports a compatibility-preserving uniform contract or explicit isolated per-route-native contracts; no provider route silently drops required capabilities.
 
+## Install / Usage
+
+```bash
+pnpm add @mono-agent/agent-runtime
+```
+
+Node.js 22.19 or newer is required. The Claude Code, Codex, and direct
+OpenCode bridges also require their matching CLI on `PATH`; direct OpenCode
+requires stable OpenCode 1.15.0 or newer. SDK-only Claude and Pi runs do not
+spawn those CLIs.
+
+Create one runtime for a host, parse a model reference, and run a turn:
+
+```js
+import {
+  createRuntime,
+  parseRuntimeModelReference,
+} from "@mono-agent/agent-runtime";
+
+const runtime = createRuntime({ workspace: process.cwd() });
+const result = await runtime.run("You are a concise repository assistant.", {
+  model: parseRuntimeModelReference("claude:claude-sonnet-4-6"),
+  executionMode: "sdk",
+  messages: [{ role: "user", content: "Summarize README.md." }],
+  cwd: process.cwd(),
+  allowedTools: ["Read"],
+});
+
+if (result.error) throw new Error(result.error);
+console.log(result.text);
+```
+
+`Glob` and `Grep` prefer the packaged `@vscode/ripgrep` binary on supported
+platforms. An explicit `ripgrepPath` wins, with `PATH` as the final fallback.
+
+## Architecture
+
+The package uses a fixed registry of bridge descriptors and loads provider code
+only after a run selects a matching model reference and execution mode:
+
+### Data flow
+
+1. `createRuntime()` binds host callbacks and creates an isolated tool context.
+2. `resolveRuntimeBridge()` checks the five static bridge descriptors in order.
+3. The selected descriptor lazily imports its provider implementation.
+4. The bridge prepares the runtime inputs it supports, including managed or MCP
+   tools only where that bridge can represent them, streams normalized events,
+   and returns a provider-neutral `RuntimeResult`.
+5. The host validates any domain-specific result and owns persistence or UI
+   effects.
+
+### Package structure
+
+| Source area | Responsibility |
+| --- | --- |
+| `src/runtime.js` | Host binding, per-instance tool context, bridge dispatch, and observer flushing |
+| `src/ai/runtime/` | Model-reference parsing, the lazy bridge registry, capabilities, sessions, and fallback routing |
+| `src/ai/providers/` | Claude SDK/CLI, Codex app-server, OpenCode app-server, and Pi SDK integrations |
+| `src/agent/tools/` | Managed tools, MCP adaptation, output limits, and the injectable sandbox seam |
+| `src/agent/` | Approvals, allowlists, transcript snapshots, and compaction policy helpers |
+
+The detailed lifecycle, provider-session differences, and host boundary are in
+the [architecture guide](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/ARCHITECTURE.md).
+
 ## Public API
 
+### Start here
+
+| API | Use it for |
+| --- | --- |
+| `createRuntime()` | Run one model bridge with host-owned credentials, observers, tools, and lifecycle callbacks |
+| `createRouterRuntime()` | Retry an ordered model chain while preserving explicit route-safety contracts |
+| `parseRuntimeModelReference()` | Convert a canonical `claude:`, `codex:`, `opencode:`, or `pi:` string into the object required by `run()` |
+| `listRuntimeBridges()` / `runtimeCapabilities()` | Inspect the five built-in bridge descriptors without loading provider implementations |
+| `createPiOAuthApiKeyResolver()` | Bind a host-owned Pi auth file with refresh-safe writes |
+| `createMetricsObserver()` | Aggregate normalized event, token, cache, cost, tool, error, turn, and approval metrics |
+
+Most hosts should use `@mono-agent/runtime-adapter` instead of importing deep
+runtime surfaces. The exhaustive inventory below is generated from the package
+export map.
+
 <!-- public-api-inventory:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
 
@@ -53,13 +142,11 @@ discoverClaudeSdkModels
 disposeAllProviderSessions
 disposeProviderSession
 executionModeIncompatibilityReason
-findProviderForModel
 generatePiNativeResponse
 inferAllowlistMode
 invalidateProviderSession
 isLikelyContextTermination
 isModelCompatibleWithExecutionMode
-listProviders
 listRuntimeBridges
 normalizeAllowlistMode
 normalizeClaudeSdkCatalog
@@ -222,11 +309,9 @@ discoverClaudeSdkModels
 disposeAllProviderSessions
 disposeProviderSession
 executionModeIncompatibilityReason
-findProviderForModel
 generatePiNativeResponse
 invalidateProviderSession
 isModelCompatibleWithExecutionMode
-listProviders
 listRuntimeBridges
 normalizeClaudeSdkCatalog
 normalizeClaudeSdkModelId
@@ -241,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
@@ -299,9 +375,7 @@ formatLiveInputGuidance
 
 ```text
 buildCliCommand
-claudeCodeBackend
 claudeCodeRuntimeBridge
-codexCliBackend
 createThinkingBuffer
 generateCliResponse
 normalizeCliEvent
@@ -325,7 +399,6 @@ normalizeClaudeSdkModelId
 ```text
 claudeEffortOptions
 claudeRuntimeBridge
-claudeSdkBackend
 claudeSdkModelForQuery
 generateClaudeResponse
 toolPayloadLimit
@@ -334,7 +407,6 @@ toolPayloadLimit
 **`@mono-agent/agent-runtime/ai/providers/codex-app.js`**
 
 ```text
-codexAppBackend
 codexAppRuntimeBridge
 createCodexAppServerClient
 generateCodexAppResponse
@@ -403,78 +475,7 @@ normalizeCodexItemType
 
 <!-- public-api-inventory:end -->
 
-## Dependency Boundary
-
-Depends on external provider SDKs only (`@anthropic-ai/claude-agent-sdk`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, `@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `zod`) — **zero `@mono-agent/*` workspace-package dependencies**. Sandbox enforcement for runtime-owned command preparation and network/path policy checks is an injectable `RuntimeSandbox` seam; `@mono-agent/runtime-adapter` wires in the real sandbox implementation automatically for mono-agent hosts.
-
-## What This Package Does Not Own
-
-- runtime contracts and backend descriptors (`@mono-agent/runtime-adapter`)
-- Conversation history, context building, or host-side session TTL policy (`@mono-agent/agent-harness`)
-- Host configuration (`@mono-agent/config`, `@mono-agent/agent-app`)
-
-## Verification
-
-```bash
-pnpm --filter @mono-agent/agent-runtime run test
-```
-
-## Overview
-
-Generic agent runtime that supports five bridges out of the box:
-
-- **Claude SDK** (`@anthropic-ai/claude-agent-sdk` 0.3.206)
-- **Claude Code CLI** (the `claude` binary)
-- **Pi SDK** (`@earendil-works/pi-agent-core`, used for OpenAI / Codex / Gemini / OpenRouter / Ollama / etc. via Pi providers)
-- **Codex CLI** (the `codex` app-server)
-- **OpenCode CLI** (an isolated `opencode` app-server driven through `@opencode-ai/sdk/v2`)
-
-Hosts wire in their own pricing, persistence, and credential callbacks (plus an `onCompactionRecorded` hook that fires on every automatic compaction — proactive or reactive — the pi bridge drives; see "Context compaction"). The runtime returns raw text + raw structured output; hosts that want a domain-specific contract parse it on their end.
-
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for the package boundary, runtime
-selection flow, lifecycle diagrams, and host responsibilities. Upgrading from
-`0.3.x`? See [MIGRATION.md](./MIGRATION.md) for the Pi-native bridge, removed run
-options, durable-session resume semantics, and fallback-router changes.
-
-## Install / Usage
-
-```bash
-npm install @mono-agent/agent-runtime
-```
-
-Peer requirements:
-
-- Node.js ≥ 22.19.0
-- `claude` CLI on PATH (only for `executionMode: "cli"` with `claude` SDK)
-- `codex` CLI on PATH (only for `executionMode: "cli"` with `codex` SDK; override via the `codexAppServerCommand` option)
-- stable `opencode` CLI >= 1.15.0 on PATH (only for direct `opencode:<provider>:<model>` refs)
-- `Glob` and `Grep` use the packaged `@vscode/ripgrep` binary on supported platforms. An explicit `ripgrepPath` is authoritative and PATH remains a fallback; provide one of those when optional dependencies are omitted or the platform is unsupported.
-
-## Quick start
-
-```js
-import { createRuntime } from "@mono-agent/agent-runtime";
-
-const runtime = createRuntime({
-  // Host integration (all optional)
-  workspace: "/path/to/repo",
-  ripgrepPath: "/usr/bin/rg",
-});
-
-const result = await runtime.run("You are a helpful assistant.", {
-  model: { sdk: "claude", model: "claude-sonnet-4-6" },
-  executionMode: "sdk",
-  messages: [{ role: "user", content: "Read README.md and summarize it." }],
-  cwd: "/path/to/repo",
-  allowedTools: ["Read", "Bash"],
-  maxTurns: 10,
-  onEvent: (event) => console.log(event.type),
-});
-
-console.log(result.text);
-```
-
-## When to reach for this vs. other JS agent runtimes
+### When to reach for this vs. other JS agent runtimes
 
 `@mono-agent/agent-runtime` is purpose-built for **autonomous, long-running agent work** with provider portability and operational resilience as first-class concerns. It is *not* a streaming-chat UI kit. Where each peer fits:
 
@@ -510,7 +511,7 @@ console.log(result.text);
 
 Honest summary: if the agent runs **without a human watching the screen** for minutes-to-hours and **must survive provider blips**, this is the right tool. If a human is watching a streaming chat, Vercel's SDK is the right tool. Both can coexist in the same app.
 
-## Picking a backend
+### Picking a backend
 
 The runtime picks a backend from `options.model` + `options.executionMode`:
 
@@ -518,13 +519,15 @@ The runtime picks a backend from `options.model` + `options.executionMode`:
 |---|---|---|
 | `"claude"` | `"sdk"` (or omitted) | Claude SDK |
 | `"claude"` | `"cli"` | `claude` CLI |
-| `"pi"` | any | Pi SDK |
+| `"pi"` | `"sdk"` (or omitted) | Pi SDK |
 | `"codex"` | `"cli"` | Codex app-server CLI |
 | `"opencode"` | `"cli"` | Isolated OpenCode app-server CLI |
 
-A `model` reference can be the parsed shape `{ sdk, model, provider? }` or a string (`"pi:openai:gpt-5.5"`, `"claude:claude-sonnet-4-6"`, etc.) that you parse with the package's `parseRuntimeModelReference` helper.
+A `model` is a parsed `{ sdk, model, provider? }` object. Convert canonical
+strings such as `"pi:openai:gpt-5.5"` with
+`parseRuntimeModelReference()` before calling `run()`.
 
-## `createRuntime(host)`
+### `createRuntime(host)`
 
 Pass host-level integration once at boot. All keys are optional.
 
@@ -608,13 +611,13 @@ Returns:
 - `retireDurableSession(id, sessionsRoot)` — delete and verify every exact-id durable Pi transcript, including cold duplicates.
 - `disposeSession(id)` / `invalidateSession(id)` / `disposeAllSessions()` — ordinary best-effort eviction, destructive live invalidation, and shutdown cleanup.
 
-### `runtime.run(systemPrompt, options)`
+#### `runtime.run(systemPrompt, options)`
 
 Per-call options (a non-exhaustive selection):
 
 | Option | Type | Notes |
 |---|---|---|
-| `model` | `object \| string` | **Required.** See "Picking a backend". |
+| `model` | `RuntimeModelRef` | **Required.** Pass the object returned by `parseRuntimeModelReference()`; `run()` does not parse strings. |
 | `executionMode` | `"sdk" \| "cli"` | Default `"sdk"`. |
 | `messages` | `Message[]` | Conversation history. |
 | `cwd` | `string` | Working directory for the agent's tools. |
@@ -623,9 +626,9 @@ Per-call options (a non-exhaustive selection):
 | `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http). |
 | `sandboxPolicy` | `SandboxPolicy` | Optional fail-closed sandbox policy for built-in tools and stdio MCP process startup. |
 | `maxTurns` | `number` | Hard cap on agent turns. |
-| `outputSchema` | `JSONSchema` | If set, the agent is asked to produce structured JSON matching this schema. The result lands in `result.structuredResult`. |
+| `outputSchema` | `JSONSchema` | Requests structured JSON on capable bridges; see “Structured output” below for bridge-specific return behavior. |
 | `abortSignal` | `AbortSignal` | Cancel the run. |
-| `liveInput` | `LiveInputQueue` | Stream of in-flight user messages (for human-in-the-loop steering). |
+| `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. |
@@ -633,12 +636,16 @@ 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
 {
   text: string,                     // raw assistant text
-  structuredResult?: any,           // JSON returned via outputSchema (if any)
+  structuredResult?: any,           // captured JSON on supported bridges
   structuredResultSource?: string,  // where structuredResult came from
   events: RuntimeEvent[],           // full event stream (for host-side parsing)
   usage: {
@@ -650,7 +657,7 @@ Returns:
   numTurns: number,
   model: string,
   effort: string,
-  sdk: "claude" | "pi" | "codex",
+  sdk: "claude" | "pi" | "codex" | "opencode",
   cancelled: boolean,
   error: string | null,
   errorDetails: object | null,
@@ -673,7 +680,24 @@ 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.
 
-## Built-in tools
+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:
 
@@ -685,13 +709,19 @@ The agent kernel's managed tools are `Read`, `Write`, `Edit`, `Glob`, `Grep`, `B
 
 Override or extend the tool surface by passing `mcpServers` for MCP-backed tools.
 
-## Structured output
+### Structured output
 
-Pass `options.outputSchema` (a JSON Schema). On Claude SDK / Codex app-server / Pi SDK, the runtime wires the schema into the provider's structured-output API. The matched JSON lands in `result.structuredResult`.
+Pass `options.outputSchema` (a JSON Schema). Claude SDK, Claude CLI, and Pi SDK
+surface captured JSON as `result.structuredResult`. Codex app-server receives
+the schema and reports that structured output was enforced, but its bridge
+returns provider text rather than parsing `structuredResult`; hosts must parse
+and validate `result.text`. Direct OpenCode rejects `outputSchema` with a typed
+capability mismatch.
 
-The package does **not** validate `structuredResult` against your schema — it only forwards what the provider produced. Hosts run their own validation (Zod, AJV, etc.).
+The package does **not** validate captured output against your schema. Hosts run
+their own validation (Zod, AJV, and similar) before applying domain effects.
 
-## Provider fallback router
+### Provider fallback router
 
 `createRouterRuntime({ host, chain, routeSafety, resolveAttempt })` wraps the standard runtime with an ordered chain of model references. On a retryable provider/auth failure it retries the logical run against the next entry with one bounded transcript-tail snapshot. A chain is stateless across provider sessions. Entry `effort` is tri-state: a string fixes that route, `null` asks for provider default, and omission inherits the legacy per-run effort.
 
@@ -736,7 +766,7 @@ Behaviour:
 
 Chain entries can require backend capabilities via `requires: { structured_output: true, supports_mcp: true, ... }`; entries that don't satisfy the requirements are skipped (logged in `failoverHistory` as `failureKind: "skipped_capability_mismatch"`).
 
-## Observers & metrics
+### Observers & metrics
 
 The runtime emits structured events for everything that happens during a run — assistant messages, tool calls, runtime warnings, cache hits/misses, cost updates, provider request start/end, approval lifecycle. Hosts can subscribe via `host.observers[]` (any number) or the simpler `options.onEvent` callback (one subscriber). Both work simultaneously.
 
@@ -758,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 },
 // }
 ```
@@ -771,7 +801,7 @@ Notable new events emitted by the bridges:
 - `cache_hit` / `cache_miss` — when the provider reports cached / cache-creation input tokens.
 - `cost_accumulated` — running cost in USD with cumulative token breakdown.
 
-## Approval gates (human-in-the-loop)
+### Approval gates (human-in-the-loop)
 
 Pass `onToolApprovalRequest` to gate tool calls behind a runtime approval. The runtime calls your callback once per tool invocation whose risk tier requires it, and pauses the agent until you respond.
 
@@ -812,7 +842,7 @@ Approval lifecycle is observable via `onEvent`:
 - `tool_approval_granted` — host approved.
 - `tool_approval_denied` — host denied, timed out, threw, or no callback for a high-risk tool.
 
-## Tool-result bloat handling
+### Tool-result bloat handling
 
 The kernel's tool-bloat guard (`agent/tool-bloat.js`, internal) enforces a 256 KB default cap per `tool_result`. When a payload exceeds the cap, the kernel:
 
@@ -822,7 +852,7 @@ The kernel's tool-bloat guard (`agent/tool-bloat.js`, internal) enforces a 256 K
 
 Hosts that don't supply `persistArtifact` get the truncation summary but no on-disk capture.
 
-## Context compaction
+### Context compaction
 
 The sole pi bridge runs on pi-agent-core's native `AgentHarness`. pi performs **no**
 automatic in-loop compaction, so the bridge drives it: before each turn it estimates the
@@ -842,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.)
@@ -856,7 +890,7 @@ summary output `clamp(floor(W × 0.04), 2000, 12000)`. Explicit values retain th
 scalar validation bounds. `onCompactionRecorded(record)` fires only for accepted,
 persisted automatic compactions.
 
-## Advanced exports
+### Advanced exports
 
 The package exposes a fixed set of inner pieces via subpath imports. The
 `exports` map is explicit (no `./ai/*` / `./agent/*` wildcards): only the mapped
@@ -875,10 +909,43 @@ import { configureToolRuntime, readToolRuntime } from "@mono-agent/agent-runtime
 
 These are stable but treated as advanced API. Most consumers should reach for `createRuntime` first.
 
-## Example consumer
+## Dependency Boundary
+
+This package has zero `@mono-agent/*` workspace dependencies. Its runtime
+dependencies are `@anthropic-ai/claude-agent-sdk`, `@anthropic-ai/sdk`,
+`@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`,
+`@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `@vscode/ripgrep`,
+`cross-spawn`, and `zod`.
 
-See [`examples/echo-agent/`](../../examples/echo-agent/) for a runnable consumer that imports `@mono-agent/agent-runtime`, runs a single Claude SDK turn with the Bash tool, and prints the result.
+Sandbox enforcement is an injectable `RuntimeSandbox` seam.
+`@mono-agent/runtime-adapter` supplies the mono-agent implementation; a direct
+consumer that configures a sandbox policy must inject an implementation or the
+runtime fails closed.
 
-## License
+## What This Package Does Not Own
 
-GPL-3.0-only.
+- Typed host-facing runtime contracts and SRT process wrapping, owned by
+  `@mono-agent/runtime-adapter`.
+- Conversation history, context assembly, memory coordination, or host-side
+  session policy, owned by `@mono-agent/agent-harness`.
+- Configuration loading, communication channels, domain result validation, UI,
+  and host persistence.
+
+## Related Documentation
+
+- [Runtime and providers](https://mono-agent-docs.vercel.app/runtime/) explains the
+  config-first model and backend choices.
+- [Backends and model references](https://mono-agent-docs.vercel.app/runtime/backends/)
+  documents all five bridges and their execution modes.
+- [Programmatic approvals and structured output](https://mono-agent-docs.vercel.app/programmatic/approval-and-structured-output/)
+  shows the code-only host hooks.
+- [Architecture](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/ARCHITECTURE.md)
+  and [migration guide](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/MIGRATION.md)
+  cover internal flow and upgrades from `0.3.x`.
+
+## Verification
+
+```bash
+pnpm --filter @mono-agent/agent-runtime run build
+pnpm --filter @mono-agent/agent-runtime run test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.13.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/agent/approval.js

@@ -2,8 +2,10 @@
 // callback that can approve, deny, or "always approve" (session-scoped
 // allowlist). Adapted from zeroclaw's ApprovalManager pattern.
 //
-// Hosts opt in by passing `onToolApprovalRequest` to createRuntime. When the
-// callback is not supplied, the gate falls back to per-tier defaults:
+// Runtime bridges opt in by passing `onToolApprovalRequest`; the Claude SDK and
+// Pi bridges do not install this manager when that callback is absent. A host
+// that calls `createApprovalManager` directly without a callback gets these
+// low-level per-tier defaults:
 //   low risk    → auto-approve
 //   medium risk → auto-approve (no host means "don't pause")
 //   high risk   → deny (fail closed)

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);