@mono-agent/agent-runtime 0.14.0 → 0.15.1

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,7 +13,99 @@ primary route.
 
 ---
 
-## 1. Pi is now native-only (`pi-sdk.js` → `pi-native.js`)
+## 0.15.1
+
+- **Runtime-owned Pi interoperability:** consumers that directly import
+  `@earendil-works/pi-ai` only for catalog, reasoning, or OAuth behavior should
+  switch to `listPiBuiltinModels`, `getPiBuiltinModel`,
+  `reasoningLevelsForPiModel`, `resolvePiOAuthApiKey`, and `loginPiOAuth` from
+  `@mono-agent/agent-runtime/ai`. The runtime keeps Pi AI and Pi Agent Core
+  exact-pinned at `0.80.6`; the façade returns cloned model and credential
+  snapshots rather than exposing mutable upstream registries.
+- **Claude test seam:** downstream tests should pass
+  `RuntimeRunOptions.claudeAgentQuery` instead of mocking
+  `@anthropic-ai/claude-agent-sdk` by package name. Normal runs omit this option
+  and use the runtime-owned SDK. Pi AI's `@anthropic-ai/sdk@0.91.1` pin and the
+  Claude Agent SDK's `@anthropic-ai/sdk>=0.93.0` requirement intentionally
+  remain as two isolated SDK versions.
+- **Compaction policy cleanup:** the inert
+  `toolPayloadCompactionTriggerChars` and `toolPruneTriggerTokens` properties
+  were removed from `AgentCompactionPolicy`, policy resolution, defaults, and
+  declarations. They had no supported typed/config path and did not activate
+  runtime pruning, so no replacement is required.
+- **Codex live-input teardown:** a Codex app-server transport death now also
+  terminates a pending live-input read. Runs settle with the existing
+  `provider_unavailable` / `codex_app_server_closed` classification instead of
+  waiting forever for the input iterator. If a host `acknowledge` or `reject`
+  callback throws, the already-decided native steering result remains
+  authoritative and the runtime emits a bounded
+  `live_input_callback_failed` warning.
+
+## 0.15.x baseline
+
+This is the current published baseline for the detailed pre-1.0 reference
+below. It includes the explicit exports map, the five-bridge lazy registry,
+typed runtime policies, runtime-owned provider dependencies, and the
+public-surface cleanup described in this guide.
+
+## 0.12.x
+
+- Persistent provider context overflow is classified as `context_limit`, which
+  lets a fallback router try its next model without conflating context capacity
+  with quota, output, or max-turn `usage_limit` failures.
+- Omitted Pi compaction values resolve from effective context window `W`:
+  trigger ratio `0.70`, retained context `10%`, summary output `4%`, and minimum
+  proactive savings `10%`, subject to the documented scalar clamps. Numeric
+  provider limits and generic overflow evidence may lower a learned
+  process-local ceiling; `contextWindowOverride` remains the persistent
+  correction.
+
+## 0.10.x
+
+- `ReadSkill` returns complete skill instructions by default, including content
+  beyond the former 12,000-character boundary. Programmatic callers of
+  `formatSkillBodyWithPathNote()` opt into truncation by passing a positive
+  `maxChars`; omitting it means no helper-level cap. The standard 256 KiB
+  tool-payload guard remains in effect.
+
+## 0.7.x
+
+- Omitting Claude SDK effort now preserves the provider default instead of
+  deriving a `thinking` option. Supported effort values are forwarded exactly;
+  explicit `none` is unsupported (`skipped_capability_mismatch` through the
+  bridge, while direct `claudeEffortOptions("none")` calls throw).
+- Cancellation uses a private abort controller and closes the active Claude SDK
+  `Query` with `Query.close()`. Test doubles must honor both boundaries rather
+  than implementing only iterator `return()`.
+- `Glob` and `Grep` prefer an explicit `ripgrepPath`, then the packaged
+  `@vscode/ripgrep` binary on supported platforms, and finally `PATH`.
+
+## 0.6.2
+
+- Codex file edits use a flat top-level `file_change` event instead of synthetic
+  assistant/user `file_edit` tool-use/tool-result pairs.
+- The synthetic `createClaudeFileEditHooks`,
+  `createFileEditToolUseEvent`, and `createFileEditToolResultEvent` exports were
+  removed. Consumers should observe normalized runtime events or use the
+  remaining file-change statistics helpers rather than recreating provider hook
+  behavior.
+
+---
+
+## Detailed pre-1.0 reference
+
+### 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
 bridge built on `@earendil-works/pi-agent-core`'s high-level `AgentHarness`. The
@@ -32,7 +124,7 @@ registry resolves `pi` → the native bridge unconditionally; there is no
   `@mono-agent/agent-runtime/ai/failure.js`. The `pi*Backend` aliases are gone —
   all Pi routes through the native bridge.
 
-## 2. Removed run options: `piReasoningSummary`, `piCodexTransport`
+### 2. Removed run options: `piReasoningSummary`, `piCodexTransport`
 
 These were Pi-bridge knobs the native path does not consume.
 
@@ -43,7 +135,7 @@ These were Pi-bridge knobs the native path does not consume.
   `runtime.reasoningSummary` config field has also been removed.
 - `piCodexTransport` was doc-only and is removed. No replacement is needed.
 
-## 3. Pi context compaction: bridge-driven via AgentHarness.compact()
+### 3. Pi context compaction: bridge-driven via AgentHarness.compact()
 
 `AgentHarness` has no automatic compaction, so the pi bridge drives it directly
 (the legacy low-level `transformContext` / `afterToolCall` hooks and
@@ -65,7 +157,7 @@ These were Pi-bridge knobs the native path does not consume.
   correction. Deprecated programmatic `agent_compaction_*` settings and
   `resolveAgentCompactionPolicy` remain compatibility surfaces.
 
-## 4. Durable Pi session resume: create-on-miss semantics
+### 4. Durable Pi session resume: create-on-miss semantics
 
 When a run supplies a `providerSessionId` (or the legacy `sessionId` alias) **and**
 durable storage is configured (`piSessionsRoot`), Pi-native now **creates the
@@ -80,7 +172,7 @@ passed an arbitrary `providerSessionId` to a durable run expecting a hard
 The in-memory (non-durable) resume path still fast-fails `session_not_found` on a
 miss.
 
-## 5. Fallback router enforces requested native-subagent capability
+### 5. Fallback router enforces requested native-subagent capability
 
 Pi advertises `supports_native_subagents: false`. The fallback router now infers
 a `supports_native_subagents` requirement when a run passes
@@ -92,7 +184,7 @@ a `supports_native_subagents` requirement when a run passes
 native-subagent runs, ensure at least one entry supports native subagents, or the
 run reports exhausted instead of degrading silently.
 
-## 6. Diagnostics & internal behavior changes (no API change)
+### 6. Diagnostics & internal behavior changes (no API change)
 
 - **Pi multimodal**: image inputs are delivered to the model as image content
   blocks (internal fix; affects behavior, not the call shape).
@@ -108,7 +200,7 @@ run reports exhausted instead of degrading silently.
   resumed sessions roll back to their pre-turn leaf on host-side (outer-catch)
   failures. These are correctness fixes with no API surface change.
 
-## 7. Sandbox enforcement is now an injectable seam (agent-runtime has zero workspace-package dependencies)
+### 7. Sandbox enforcement is now an injectable seam (agent-runtime has zero workspace-package dependencies)
 
 `@mono-agent/agent-runtime` does not depend on `@mono-agent/runtime-adapter`. Sandbox
 enforcement (command sandboxing, network-policy checks, and monotonic policy
@@ -136,7 +228,7 @@ mono-agent hosts — no action needed if you build your runtime through
   `@mono-agent/runtime-adapter`, also pass a `sandbox` implementation, or drop
   the policy.
 
-## 8. Typed run options replace the `settings` bag (`toolLimits` / `compaction` / `prompts`)
+### 8. Typed run options replace the `settings` bag (`toolLimits` / `compaction` / `prompts`)
 
 The flat `options.settings` bag is **deprecated** as the way to configure
 tool-output clamps and context compaction. The supported replacements are typed,
@@ -166,7 +258,7 @@ mapper's fallback window.
 **Action:** migrate `settings` → `toolLimits` / `compaction`; until then the shim
 keeps working with one deprecation warning per run.
 
-## 9. New per-run overrides: `sandbox`, `sandboxPolicy`, `prompts`
+### 9. New per-run overrides: `sandbox`, `sandboxPolicy`, `prompts`
 
 Beyond `toolLimits` / `compaction`, `RuntimeRunOptions` gained:
 
@@ -182,7 +274,7 @@ Beyond `toolLimits` / `compaction`, `RuntimeRunOptions` gained:
   (byte-identical default). These are also accepted on `AgentRuntimeHostOptions`
   as the host-level default.
 
-## 10. Pi 0.80 auth: `Models` credential store (`resolvePiApiKey` semantics preserved)
+### 10. Pi 0.80 auth: `Models` credential store (`resolvePiApiKey` semantics preserved)
 
 Pi 0.80 removed the harness `getApiKeyAndHeaders` hook; request auth now resolves
 through a `Models` collection's `CredentialStore`. The bridge's **per-run
@@ -197,7 +289,7 @@ now `0.80.6`** (the initial Pi 0.80 migration landed at `0.80.5`, from
 `^0.79.1`). Compaction is driven natively (section 3). The `0.80.6` refresh also
 preserves model-native `max` reasoning and Pi's request-wide pricing tiers.
 
-## 11. Exports map: wildcards removed (explicit deep-path map)
+### 11. Exports map: wildcards removed (explicit deep-path map)
 
 The package's `./ai/*` and `./agent/*` **wildcard exports were replaced by an
 explicit `exports` map**: 3 barrels (`.`, `./ai`, `./agent`) plus the generated
@@ -209,7 +301,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 +311,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
@@ -247,64 +338,51 @@ a compatibility subpath.
 
 ## Version
 
-This guide describes the published `0.13.x` package contract. Keep
+This guide describes the published `0.15.x` package contract. Keep
 `@mono-agent/agent-runtime`, `@mono-agent/runtime-adapter`, and other
 `@mono-agent/*` packages on the same lockstep version when upgrading. The paired
 runtime adapter no longer exposes `piReasoningSummary` in its run-options type.
 
 ---
 
-## Appendix — Porting this kernel to a new scope/host (worklab port-readiness)
-
-This kernel is designed to be vendored into a differently-scoped host (the
-concrete target is **worklab**, `@worklab-ai/agent-runtime`, GPL-3.0-only, npm
-workspaces, pure-JS no-build, consuming this package's raw `src/`). The port
-itself is a follow-up; this is the executable checklist, with the port-readiness
-dry-run results recorded inline (verified against the worklab tree read-only).
-
-Run these before/at the port:
-
-1. **Scope rename `@mono-agent/` → `@worklab-ai/`.** Touches `package.json`
-   (`name` + the package-name prefix inside each `exports` key's consumer
-   specifier) only — the kernel's own source uses **relative** imports, so no
-   source import references the scope. *(Verified: zero `@mono-agent/*` specifiers
-   in `src/`.)*
-2. **Dependencies.** Post-decoupling the kernel has **zero workspace-package
-   deps**; only the third-party pins need aligning: `@earendil-works/pi-ai` +
-   `@earendil-works/pi-agent-core` (`0.80.6`), `@modelcontextprotocol/sdk`,
-   `@opencode-ai/sdk`, `@anthropic-ai/claude-agent-sdk`, `zod`.
-3. **Pi bump `^0.74.0` → `0.80.6` in lockstep.** worklab tests that use old pi
-   APIs are rewritten at the port. Do not restore the old `pi-sdk.js` deep
-   import; use `generatePiNativeResponse` from `@mono-agent/agent-runtime/ai`.
-4. **Sandbox.** worklab passes **no** `sandbox` implementation → `passthroughSandbox`,
-   and **never sets `sandboxPolicy`** *(verified: zero `sandboxPolicy` /
-   `sandbox:` in worklab `src/`)*, so with no policy every tool runs unsandboxed
-   exactly as today — behavior is byte-identical. (If worklab later adds a policy,
-   it must also inject a `RuntimeSandbox` impl — section 7's fail-closed rule.)
-5. **License / packaging.** GPL-3.0-only stays; `files` includes `types/`
-   (additive — worklab consumes raw `src/`, `.d.ts` generation is optional).
-6. **Deep imports resolve.** `node scripts/verify-deep-imports.mjs` (default +
-   types conditions) is green. Every worklab **non-test** deep import resolves in
-   the explicit exports map *(verified — no gap)*, and the Worklab-test provider
-   bridge imports for `claude-sdk.js`, `claude-cli.js`, and `codex-app.js` are
-   supported as exported subpaths. The only worklab deep import NOT in the map is
-   the removed **test-only** `pi-sdk.js`; those tests are rewritten at the port
-   (step 3), so no export entry is added for it.
-7. **Contract supersets.** `HOST_KEYS` ⊇ worklab's host bag *(verified:
-   worklab passes `resolveCustomPricing`, `onCompactionRecorded`, `persistArtifact`,
-   `resolvePiApiKey`, `observers` — all covered)*; the deep-import
-   `configureToolRuntime` accepts worklab's keys *(verified: `workspace`,
-   `repoRoot`, `runId`, `toolArtifactDir`, `ripgrepPath`, `qaOutputDir` ⊂
-   `TOOL_CONTEXT_KEYS`)*; and every `RuntimeResult` field worklab's
-   `worker/agent-turn.js` reads exists on the result *(verified: `cancelled`,
-   `providerSessionId`, `error`, `failureKind`, `errorDetails`, `diagnostics`,
-   `runtimeWarnings`, plus `text`/`usage`/`model`/`effort`/`numTurns`/
-   `structuredResult`/`capabilitiesUsed`/`durationMs`/`failoverHistory`;
-   `observerSnapshot` is worklab-side, folded from its own metrics observer)*.
-8. **`options.settings` day one.** Works via the deprecated shim (section 8) with
-   one `deprecated_settings_option` warning per run; worklab later maps
-   `settings` → the typed policy objects in its `core/ai.js`.
-9. **Test layout + no-build consumption.** `src/__tests__` + vitest already match;
-   the package is fully consumable from raw `src/` with **no build**
-   *(verified: a smoke import of `createRuntime` / `createRouterRuntime` from
-   `src/index.js` constructs a runtime with no model call)*.
+## Appendix — Worklab shared-kernel adoption
+
+Worklab should consume the published `@mono-agent/agent-runtime` package rather
+than vendor or rename its source. The products remain separate, but provider
+execution has one owner. Apply this downstream checklist when removing
+Worklab's runtime fork:
+
+1. **Install the lockstep runtime package.** Keep the `@mono-agent/*` packages a
+   Worklab release uses on the same published version. Preserve the shared
+   kernel's `GPL-3.0-only` distribution boundary.
+2. **Remove direct provider ownership.** Delete Worklab production imports from
+   `@earendil-works/pi-ai`, its separate Pi version constraint, and local copies
+   of provider bridge code. Move tests off Pi's faux-provider helpers too; until
+   that is complete, isolate the fixture or pin its development-only Pi
+   dependency to exact `0.80.6` rather than a floating range. Do not restore the
+   removed `pi-sdk.js` subpath.
+3. **Use the public Pi surfaces.** Run models through
+   `generatePiNativeResponse` or the runtime registry. Use
+   `listPiBuiltinModels`, `getPiBuiltinModel`,
+   `reasoningLevelsForPiModel`, `resolvePiOAuthApiKey`, and `loginPiOAuth` for
+   catalog and OAuth integration. Those façades keep Pi mutable state and the
+   exact `0.80.6` compatibility pin inside the runtime. OAuth login adapters
+   must supply `onAuth`, `onDeviceCode`, `onPrompt`, and `onSelect`; the façade
+   rejects an incomplete callback contract before starting provider login.
+4. **Inject Claude tests.** Replace package-level mocks of
+   `@anthropic-ai/claude-agent-sdk` with
+   `RuntimeRunOptions.claudeAgentQuery`. Production calls omit the seam. Expect
+   the runtime installation to retain Pi's Anthropic SDK `0.91.1` beside the
+   newer Anthropic SDK required by Claude; do not force-deduplicate them.
+5. **Preserve the sandbox boundary.** A direct runtime consumer that supplies
+   `sandboxPolicy` must also inject a `RuntimeSandbox`; otherwise the runtime
+   intentionally fails closed. With neither a policy nor an implementation,
+   passthrough behavior remains unchanged.
+6. **Use supported contracts.** Keep host callbacks within
+   `AgentRuntimeHostOptions`, tool state within the exported tool-runtime
+   context, and reads within `RuntimeResult`. Replace deprecated
+   `options.settings` with typed `toolLimits` and `compaction` objects.
+7. **Verify the installed package.** Run Worklab's provider and worker tests
+   against the packed or published package, assert that no production import
+   resolves Pi directly, and prove the injected Claude query performs no
+   network call.

package/README.md

@@ -93,6 +93,8 @@ the [architecture guide](https://github.com/robertsreberski/mono-agent/blob/main
 | `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 |
+| `listPiBuiltinModels()` / `getPiBuiltinModel()` | Read cloned snapshots from the runtime-owned, exact-pinned Pi model catalog without importing Pi directly |
+| `resolvePiOAuthApiKey()` / `loginPiOAuth()` | Use the runtime-owned Pi OAuth implementation without importing Pi's mutable provider registry |
 | `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
@@ -142,14 +144,15 @@ discoverClaudeSdkModels
 disposeAllProviderSessions
 disposeProviderSession
 executionModeIncompatibilityReason
-findProviderForModel
 generatePiNativeResponse
+getPiBuiltinModel
 inferAllowlistMode
 invalidateProviderSession
 isLikelyContextTermination
 isModelCompatibleWithExecutionMode
-listProviders
+listPiBuiltinModels
 listRuntimeBridges
+loginPiOAuth
 normalizeAllowlistMode
 normalizeClaudeSdkCatalog
 normalizeClaudeSdkModelId
@@ -160,12 +163,14 @@ parseStoredAllowlist
 piNativeRuntimeBridge
 readRuntimeBrand
 readToolRuntime
+reasoningLevelsForPiModel
 refreshProviderSession
 renderResumeSnapshot
 resetToolRuntime
 resolveAgentCompactionPolicy
 resolveAllowlist
 resolveAllowlistMap
+resolvePiOAuthApiKey
 resolveRuntimeBrand
 resolveRuntimeBridge
 runtimeCapabilities
@@ -311,18 +316,21 @@ discoverClaudeSdkModels
 disposeAllProviderSessions
 disposeProviderSession
 executionModeIncompatibilityReason
-findProviderForModel
 generatePiNativeResponse
+getPiBuiltinModel
 invalidateProviderSession
 isModelCompatibleWithExecutionMode
-listProviders
+listPiBuiltinModels
 listRuntimeBridges
+loginPiOAuth
 normalizeClaudeSdkCatalog
 normalizeClaudeSdkModelId
 normalizeRuntimeModelReference
 parseRuntimeModelReference
 piNativeRuntimeBridge
+reasoningLevelsForPiModel
 refreshProviderSession
+resolvePiOAuthApiKey
 resolveRuntimeBridge
 runtimeCapabilities
 sdkFromModelReference
@@ -330,15 +338,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 +387,7 @@ formatLiveInputGuidance
 
 ```text
 buildCliCommand
-claudeCodeBackend
 claudeCodeRuntimeBridge
-codexCliBackend
 createThinkingBuffer
 generateCliResponse
 normalizeCliEvent
@@ -414,7 +411,6 @@ normalizeClaudeSdkModelId
 ```text
 claudeEffortOptions
 claudeRuntimeBridge
-claudeSdkBackend
 claudeSdkModelForQuery
 generateClaudeResponse
 toolPayloadLimit
@@ -423,7 +419,6 @@ toolPayloadLimit
 **`@mono-agent/agent-runtime/ai/providers/codex-app.js`**
 
 ```text
-codexAppBackend
 codexAppRuntimeBridge
 createCodexAppServerClient
 generateCodexAppResponse
@@ -619,6 +614,21 @@ The resolver reads provider credentials from the configured file, delegates toke
 refresh to `@earendil-works/pi-ai/oauth`, and writes refreshed credentials back
 with `0600` permissions.
 
+Consumers that need lower-level Pi interoperability should still import only
+`@mono-agent/agent-runtime/ai`. `listPiBuiltinModels(providerId)` returns fresh,
+defensively cloned model snapshots; `getPiBuiltinModel(providerId, modelId)`
+returns one cloned snapshot or `undefined`; and
+`reasoningLevelsForPiModel(model)` translates a Pi model into mono-agent's
+reasoning vocabulary, including `none` rather than Pi's `off`.
+`resolvePiOAuthApiKey(providerId, credentials)` refreshes a caller-owned
+credential snapshot and returns `{ apiKey, newCredentials }` or `null`, while
+`loginPiOAuth(providerId, callbacks)` runs the selected supported login flow.
+Login callers must implement Pi's four required interaction callbacks:
+`onAuth`, `onDeviceCode`, `onPrompt`, and `onSelect`; optional progress,
+manual-code, and abort callbacks pass through unchanged.
+These functions deliberately do not expose Pi's mutable model collections or
+OAuth-provider registry.
+
 Returns:
 
 - `run(systemPrompt, options)` — async, runs one agent turn against the chosen backend.
@@ -645,14 +655,26 @@ 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. |
-| `onEvent` | `(event) => void` | Fired for every event the provider emits (assistant text, tool calls/results, runtime warnings, structured output). |
+| `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. Acknowledgement emits metadata-only `live_input_applied` telemetry. |
+| `claudeAgentQuery` | `typeof query` | Advanced programmatic/test seam for the Claude SDK bridge. When omitted, the bridge uses the runtime's pinned Claude Agent SDK. This is not a config field or telemetry value. |
+| `onEvent` | `(event) => void` | Fired for every runtime event (assistant text, tool calls/results, applied live input, runtime warnings, structured output). |
 | `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
 | `providerSessionId` | `string` | Resume a prior provider session. |
 | `runArtifactDir` | `string` | Used by some providers as the Playwright MCP filename target. |
 | `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.
+After a native bridge invokes `acknowledge()`, the runtime emits exactly one
+`{ type: "live_input_applied", inputId, receivedAt? }` event for that logical
+run. It deliberately omits the guidance body. A fallback router reuses the same
+instrumented input stream, so replay or duplicate acknowledgement cannot emit a
+second applied event. A throwing host `acknowledge` or `reject` callback cannot
+change the native steering outcome; the Codex bridge reports it as a bounded
+`live_input_callback_failed` runtime warning.
+
 Returns:
 
 ```ts
@@ -693,6 +715,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:
@@ -703,6 +742,13 @@ The agent kernel's managed tools are `Read`, `Write`, `Edit`, `Glob`, `Grep`, `B
 
 `NodeRepl` uses Node's default `node:repl` evaluator, so variables, `_`, `_error`, and loaded modules persist across calls in the same run. It supports multiline input and top-level `await`, resolves workspace-installed packages, and is closed with the run. Its child is prepared through the same sandbox seam as `Bash`; abort, the fixed 120-second timeout, child exit, or hard output overflow resets the session. It deliberately has no session ids, persistent history, terminal commands, or package-install surface.
 
+Pi runs with selected skills also expose `ReadSkill`. It returns the complete
+skill instructions by default, including content beyond the former
+12,000-character boundary. Programmatic callers of
+`formatSkillBodyWithPathNote()` may pass a positive `maxChars` only when
+truncation is explicitly desired; omitting it is not a separate hidden limit.
+The standard 256 KiB tool-payload guard still applies to oversized tool results.
+
 Override or extend the tool surface by passing `mcpServers` for MCP-backed tools.
 
 ### Structured output
@@ -784,7 +830,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 +914,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.)
@@ -909,6 +959,19 @@ dependencies are `@anthropic-ai/claude-agent-sdk`, `@anthropic-ai/sdk`,
 `@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `@vscode/ripgrep`,
 `cross-spawn`, and `zod`.
 
+The runtime owns and exact-pins the compatible Pi pair at `0.80.6`; consumers
+use the runtime's Pi façade rather than coordinating a second direct
+`@earendil-works/pi-ai` dependency. Do not attempt to flatten the resulting
+Anthropic dependency tree: Pi AI pins `@anthropic-ai/sdk@0.91.1`, while the
+Claude Agent SDK requires `@anthropic-ai/sdk>=0.93.0` and the runtime supplies
+its compatible newer SDK. Two isolated Anthropic SDK versions are therefore
+expected. `RuntimeRunOptions.claudeAgentQuery` provides deterministic Claude
+tests without mocking package resolution or sending real SDK traffic.
+If a downstream test suite still needs Pi's faux-provider helpers, isolate that
+fixture or keep its development-only Pi dependency on the runtime's exact
+`0.80.6` version until the fixture is removed; a broad host range can otherwise
+float Pi Agent Core's own upstream dependency independently of this façade.
+
 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

package/package.json

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

@@ -22,8 +22,6 @@
  * @property {number} summaryMaxTokens
  * @property {boolean} fixedOverheadEnabled
  * @property {number} compactionMinSavingsTokens
- * @property {number} toolPayloadCompactionTriggerChars
- * @property {number} toolPruneTriggerTokens
  * @property {number} toolTextLimitChars
  * @property {number} bashOutputLimitChars
  * @property {number} mcpTextLimitChars
@@ -36,8 +34,6 @@
 
 const DEFAULT_CONTEXT_WINDOW = 128000;
 const DEFAULT_TRIGGER_RATIO = 0.70;
-const DEFAULT_TOOL_PAYLOAD_COMPACTION_TRIGGER_CHARS = 0;
-const DEFAULT_TOOL_PRUNE_TRIGGER_TOKENS = 40000;
 // intelligence-ramp Phase 3: lifted from 16K/20K/12K. Mid-task tool reads
 // (large file edits, long bash output, deep MCP results) were being silently
 // clipped before the agent could reason about them. The 256KB hard ceiling
@@ -134,13 +130,6 @@ export function resolveAgentCompactionPolicy(settings = {}, model = {}) {
       0,
       500000,
     ),
-    toolPayloadCompactionTriggerChars: clampInteger(
-      settings.agent_tool_payload_compaction_trigger_chars,
-      DEFAULT_TOOL_PAYLOAD_COMPACTION_TRIGGER_CHARS,
-      0,
-      10 * 1024 * 1024,
-    ),
-    toolPruneTriggerTokens: clampInteger(settings.agent_tool_prune_trigger_tokens, DEFAULT_TOOL_PRUNE_TRIGGER_TOKENS, 0, 500000),
     toolTextLimitChars: clampInteger(settings.agent_tool_text_limit_chars, DEFAULT_TOOL_TEXT_LIMIT_CHARS, 1000, 200000),
     bashOutputLimitChars: clampInteger(settings.agent_bash_output_limit_chars, DEFAULT_BASH_OUTPUT_LIMIT_CHARS, 1000, 200000),
     mcpTextLimitChars: clampInteger(settings.agent_mcp_text_limit_chars, DEFAULT_MCP_TEXT_LIMIT_CHARS, 1000, 200000),

package/src/agent/prompt/skill-index.js

@@ -35,6 +35,9 @@ export function buildSkillPathNote({ assetsPath, skillsRoot } = {}) {
 }
 
 /**
+ * Render a complete skill body plus its path note. Omitting `maxChars` returns
+ * the full text; pass a positive `maxChars` only when explicit truncation is
+ * required by the caller.
  * @param {{body?: string, assetsPath?: string, skillsRoot?: any, maxChars?: number}} [options]
  */
 export function formatSkillBodyWithPathNote({ body, assetsPath, skillsRoot, maxChars } = {}) {
@@ -42,7 +45,8 @@ export function formatSkillBodyWithPathNote({ body, assetsPath, skillsRoot, maxC
     buildSkillPathNote({ assetsPath, skillsRoot }),
     String(body || "").trim(),
   ].filter(Boolean).join("\n\n");
-  return maxChars ? text.slice(0, maxChars) : text;
+  const limit = Number(maxChars);
+  return Number.isFinite(limit) && limit > 0 ? text.slice(0, Math.floor(limit)) : text;
 }
 
 export function buildSkillIndex(skills) {