@mono-agent/agent-runtime 0.15.0 → 0.15.1

package/MIGRATION.md

@@ -13,7 +13,88 @@ primary route.
 
 ---
 
-## Pre-1.0 public-surface cleanup
+## 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.
@@ -24,7 +105,7 @@ instead. Runtime behavior and the canonical bridge descriptors are unchanged.
 
 ---
 
-## 1. Pi is now native-only (`pi-sdk.js` → `pi-native.js`)
+### 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
@@ -43,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.
 
@@ -54,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
@@ -76,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
@@ -91,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
@@ -103,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).
@@ -119,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
@@ -147,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,
@@ -177,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:
 
@@ -193,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
@@ -208,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
@@ -257,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
@@ -143,11 +145,14 @@ disposeAllProviderSessions
 disposeProviderSession
 executionModeIncompatibilityReason
 generatePiNativeResponse
+getPiBuiltinModel
 inferAllowlistMode
 invalidateProviderSession
 isLikelyContextTermination
 isModelCompatibleWithExecutionMode
+listPiBuiltinModels
 listRuntimeBridges
+loginPiOAuth
 normalizeAllowlistMode
 normalizeClaudeSdkCatalog
 normalizeClaudeSdkModelId
@@ -158,12 +163,14 @@ parseStoredAllowlist
 piNativeRuntimeBridge
 readRuntimeBrand
 readToolRuntime
+reasoningLevelsForPiModel
 refreshProviderSession
 renderResumeSnapshot
 resetToolRuntime
 resolveAgentCompactionPolicy
 resolveAllowlist
 resolveAllowlistMap
+resolvePiOAuthApiKey
 resolveRuntimeBrand
 resolveRuntimeBridge
 runtimeCapabilities
@@ -310,15 +317,20 @@ disposeAllProviderSessions
 disposeProviderSession
 executionModeIncompatibilityReason
 generatePiNativeResponse
+getPiBuiltinModel
 invalidateProviderSession
 isModelCompatibleWithExecutionMode
+listPiBuiltinModels
 listRuntimeBridges
+loginPiOAuth
 normalizeClaudeSdkCatalog
 normalizeClaudeSdkModelId
 normalizeRuntimeModelReference
 parseRuntimeModelReference
 piNativeRuntimeBridge
+reasoningLevelsForPiModel
 refreshProviderSession
+resolvePiOAuthApiKey
 resolveRuntimeBridge
 runtimeCapabilities
 sdkFromModelReference
@@ -602,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.
@@ -628,8 +655,9 @@ 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; 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). |
+| `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. |
@@ -639,6 +667,13 @@ Per-call options (a non-exhaustive selection):
 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:
 
@@ -707,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
@@ -917,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.15.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",

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

package/src/ai/index.js

@@ -12,6 +12,13 @@ export {
 } from "./runtime/sessions.js";
 export { createMetricsObserver, createObserverHub } from "./observer.js";
 export { generatePiNativeResponse, piNativeRuntimeBridge } from "./providers/pi-native.js";
+export {
+  getPiBuiltinModel,
+  listPiBuiltinModels,
+  loginPiOAuth,
+  reasoningLevelsForPiModel,
+  resolvePiOAuthApiKey,
+} from "./pi-interop.js";
 export {
   CLAUDE_SDK_CATALOG_VERSION,
   createClaudeSdkDiscoveryIsolation,

package/src/ai/pi-interop.js

@@ -0,0 +1,156 @@
+// Runtime-owned interoperability facade for Pi's built-in model and OAuth
+// surfaces. Consumers should use these functions instead of importing pi-ai
+// directly so the runtime's known-good Pi version remains authoritative.
+
+import { getBuiltinModel, getBuiltinModels } from "@earendil-works/pi-ai/providers/all";
+import { getOAuthApiKey, getOAuthProvider } from "@earendil-works/pi-ai/oauth";
+import { reasoningLevelsForPiModel as resolveReasoningLevels } from "./providers/pi-models.js";
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   name: string,
+ *   api: string,
+ *   provider: string,
+ *   baseUrl: string,
+ *   reasoning: boolean,
+ *   input: Array<"text"|"image">,
+ *   cost: {
+ *     input: number,
+ *     output: number,
+ *     cacheRead: number,
+ *     cacheWrite: number,
+ *     tiers?: Array<{
+ *       inputTokensAbove: number,
+ *       input: number,
+ *       output: number,
+ *       cacheRead: number,
+ *       cacheWrite: number
+ *     }>
+ *   },
+ *   contextWindow: number,
+ *   maxTokens: number,
+ *   thinkingLevelMap?: Object<string, string|null>,
+ *   compat?: Object<string, *>,
+ *   headers?: Object<string, string>,
+ *   [key: string]: *
+ * }} PiBuiltinModelSnapshot
+ */
+
+/**
+ * @typedef {"none"|"minimal"|"low"|"medium"|"high"|"xhigh"|"max"} PiReasoningLevel
+ */
+
+/**
+ * @typedef {{
+ *   refresh: string,
+ *   access: string,
+ *   expires: number,
+ *   [key: string]: *
+ * }} PiOAuthCredentialsSnapshot
+ */
+
+/**
+ * @typedef {Object} PiOAuthLoginCallbacks
+ * @property {(info: {url: string, instructions?: string}) => void} onAuth
+ * @property {(info: {userCode: string, verificationUri: string, intervalSeconds?: number, expiresInSeconds?: number}) => void} onDeviceCode
+ * @property {(prompt: {message: string, placeholder?: string, allowEmpty?: boolean}) => Promise<string>} onPrompt
+ * @property {(message: string) => void} [onProgress]
+ * @property {() => Promise<string>} [onManualCodeInput]
+ * @property {(prompt: {message: string, options: Array<{id: string, label: string}>}) => Promise<string|undefined>} onSelect
+ * @property {AbortSignal} [signal]
+ */
+
+/**
+ * Clone provider-owned data before it crosses the public runtime boundary.
+ * Pi's built-in models and OAuth credentials are structured data on the
+ * supported version, and the package requires a Node release with
+ * `structuredClone`.
+ *
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+function cloneInteropValue(value) {
+  return structuredClone(value);
+}
+
+/**
+ * List defensive snapshots of Pi's built-in models for one provider.
+ *
+ * @param {string} providerId
+ * @returns {PiBuiltinModelSnapshot[]}
+ */
+export function listPiBuiltinModels(providerId) {
+  const models = getBuiltinModels(/** @type {any} */ (providerId));
+  return /** @type {PiBuiltinModelSnapshot[]} */ (cloneInteropValue(models));
+}
+
+/**
+ * Read a defensive snapshot of one Pi built-in model.
+ *
+ * @param {string} providerId
+ * @param {string} modelId
+ * @returns {PiBuiltinModelSnapshot|undefined}
+ */
+export function getPiBuiltinModel(providerId, modelId) {
+  const model = getBuiltinModel(
+    /** @type {any} */ (providerId),
+    /** @type {any} */ (modelId),
+  );
+  return model === undefined
+    ? undefined
+    : /** @type {PiBuiltinModelSnapshot} */ (cloneInteropValue(model));
+}
+
+/**
+ * Translate Pi's model-native thinking levels to mono-agent effort spelling.
+ *
+ * @param {PiBuiltinModelSnapshot} model
+ * @returns {PiReasoningLevel[]}
+ */
+export function reasoningLevelsForPiModel(model) {
+  return /** @type {PiReasoningLevel[]} */ (resolveReasoningLevels(model));
+}
+
+/**
+ * Resolve an OAuth-backed API key without allowing Pi to mutate the caller's
+ * credential record or returning Pi-owned credential objects.
+ *
+ * @param {string} providerId
+ * @param {Object<string, PiOAuthCredentialsSnapshot>} credentials
+ * @returns {Promise<{apiKey: string, newCredentials: PiOAuthCredentialsSnapshot}|null>}
+ */
+export async function resolvePiOAuthApiKey(providerId, credentials) {
+  const result = await getOAuthApiKey(
+    providerId,
+    /** @type {any} */ (cloneInteropValue(credentials)),
+  );
+  if (!result) return null;
+  return {
+    apiKey: result.apiKey,
+    newCredentials: cloneInteropValue(result.newCredentials),
+  };
+}
+
+/**
+ * Run a supported Pi OAuth login flow without exposing Pi's mutable provider
+ * registry or provider instances.
+ *
+ * @param {string} providerId
+ * @param {PiOAuthLoginCallbacks} callbacks
+ * @returns {Promise<PiOAuthCredentialsSnapshot>}
+ */
+export async function loginPiOAuth(providerId, callbacks) {
+  const provider = getOAuthProvider(providerId);
+  if (!provider || typeof provider.login !== "function") {
+    throw new Error(`Pi OAuth provider is unavailable: ${providerId}`);
+  }
+  for (const callbackName of ["onAuth", "onDeviceCode", "onPrompt", "onSelect"]) {
+    if (typeof callbacks?.[callbackName] !== "function") {
+      throw new TypeError(`loginPiOAuth requires callbacks.${callbackName}()`);
+    }
+  }
+  const credentials = await provider.login(/** @type {any} */ ({ ...callbacks }));
+  return cloneInteropValue(credentials);
+}

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

@@ -748,6 +748,7 @@ export async function generateClaudeResponse(systemPrompt, options) {
   const prompt = options.liveInput
     ? livePromptMessages({ initialPrompt: promptString, liveInput: options.liveInput, sessionId: reusableProviderSessionId || randomUUID(), prompts: options.prompts })
     : promptString;
+  const claudeAgentQuery = options.claudeAgentQuery ?? query;
   const providerRequestStartedAt = Date.now();
   emitEvent({
     type: "provider_request_started",
@@ -805,7 +806,7 @@ export async function generateClaudeResponse(systemPrompt, options) {
   }
 
   try {
-    stream = query({ prompt: /** @type {any} */ (prompt), options: queryOptions });
+    stream = claudeAgentQuery({ prompt: /** @type {any} */ (prompt), options: queryOptions });
     for await (const event of stream) {
       const nextSessionId = sessionIdFromEvent(event);
       if (nextSessionId) providerSessionId = nextSessionId;

package/src/ai/providers/codex-app.js

@@ -1143,7 +1143,9 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
   let serverRequestViolation = null;
   let resolveTurn;
   let resolveTurnReady;
+  let resolveLiveInputStop;
   let turnReadyResolved = false;
+  let liveInputStopped = false;
   const fileChangeSnapshots = new Map();
   const codexItemContext = {
     fileChangePayload: (raw) => createFileChangePayload(raw, {
@@ -1153,6 +1155,13 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
   };
   const turnDone = new Promise((resolve) => { resolveTurn = resolve; });
   const turnReady = new Promise((resolve) => { resolveTurnReady = resolve; });
+  const liveInputStop = new Promise((resolve) => { resolveLiveInputStop = resolve; });
+
+  function stopLiveInput() {
+    if (liveInputStopped) return;
+    liveInputStopped = true;
+    resolveLiveInputStop();
+  }
 
   function setActiveTurnId(turnId, { steerReady = false } = {}) {
     activeTurnId = turnId || activeTurnId;
@@ -1175,6 +1184,21 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
     options.onEvent?.(safeEvent);
   }
 
+  function invokeLiveInputCallback(message, callbackName, ...args) {
+    const callback = message?.[callbackName];
+    if (typeof callback !== "function") return;
+    try {
+      callback.apply(message, args);
+    } catch (err) {
+      const detail = safeDiagnostic(err, 512);
+      emitEvent({
+        type: "runtime_warning",
+        warning_kind: "live_input_callback_failed",
+        message: safeDiagnostic(`Live-input ${callbackName} callback failed: ${detail}`, 1_024),
+      });
+    }
+  }
+
   const compactionTurnKey = (params = {}) => `${params.threadId || threadId || "thread"}:${params.turnId || activeTurnId || "turn"}`;
 
   /**
@@ -1269,6 +1293,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
       client?.request("turn/interrupt", { threadId, turnId: activeTurnId }).catch(() => {});
     }
     turnCompleted = true;
+    stopLiveInput();
     resolveTurn({ id: activeTurnId, status: "interrupted" });
   }
 
@@ -1293,6 +1318,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
       message: errorMessage,
     });
     turnCompleted = true;
+    stopLiveInput();
     resolveTurn({ id: activeTurnId, status: "interrupted" });
   }
 
@@ -1323,6 +1349,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
     if (method === "turn/completed") {
       setActiveTurnId(params.turn?.id);
       turnCompleted = true;
+      stopLiveInput();
       if (params.turn?.status === "failed") {
         errorMessage = safeDiagnostic(params.turn?.error?.message || params.turn?.error || "Codex turn failed");
         failureKind = "provider_unavailable";
@@ -1482,6 +1509,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
 
   const abortHandler = () => {
     abortRequested = true;
+    stopLiveInput();
     if (threadId && activeTurnId && !interruptSent) {
       interruptSent = true;
       client?.request("turn/interrupt", { threadId, turnId: activeTurnId }).catch(() => {});
@@ -1495,20 +1523,19 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
     if (!options.liveInput) return;
     const iterator = options.liveInput[Symbol.asyncIterator]();
     try {
-      while (!turnCompleted) {
+      while (!turnCompleted && !liveInputStopped) {
         const next = await Promise.race([
           iterator.next(),
-          turnDone.then(() => ({ done: true, value: undefined })),
+          liveInputStop.then(() => ({ done: true, value: undefined })),
         ]);
-        if (next.done || turnCompleted) break;
+        if (next.done || turnCompleted || liveInputStopped) break;
         const message = next.value;
         if (!threadId || !activeTurnId || !turnReadyResolved) {
           await Promise.race([
             turnReady,
-            turnDone,
-            client.closed.then((err) => { throw err; }),
+            liveInputStop,
           ]);
-          if (turnCompleted || !turnReadyResolved) break;
+          if (turnCompleted || liveInputStopped || !turnReadyResolved) break;
         }
         const input = userTextInput(formatLiveInputGuidance(message.body, options.prompts));
         try {
@@ -1518,16 +1545,15 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
             input,
           });
           activeTurnId = response?.turnId || activeTurnId;
-          message.acknowledge?.();
+          invokeLiveInputCallback(message, "acknowledge");
         } catch (err) {
           const providerError = err?.responseError;
           if (isNoActiveTurnToSteer(providerError || err)) {
             await Promise.race([
               turnReady,
-              turnDone,
-              client.closed.then((closedErr) => { throw closedErr; }),
+              liveInputStop,
             ]);
-            if (turnCompleted) break;
+            if (turnCompleted || liveInputStopped) break;
             try {
               const response = await client.request("turn/steer", {
                 threadId,
@@ -1535,10 +1561,10 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
                 input,
               });
               activeTurnId = response?.turnId || activeTurnId;
-              message.acknowledge?.();
+              invokeLiveInputCallback(message, "acknowledge");
               continue;
             } catch (retryErr) {
-              message.reject?.(retryErr);
+              invokeLiveInputCallback(message, "reject", retryErr);
               const retryProviderError = retryErr?.responseError
                 ? safeResponseError(retryErr.responseError)
                 : null;
@@ -1552,7 +1578,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
               break;
             }
           }
-          message.reject?.(err);
+          invokeLiveInputCallback(message, "reject", err);
           emitEvent({
             type: "runtime_warning",
             warning_kind: isActiveTurnNotSteerable(providerError) ? "active_turn_not_steerable" : "live_input_rejected",
@@ -1789,6 +1815,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
         closedSignal.then((err) => {
           if (!turnCompleted) {
             prematureClose = true;
+            stopLiveInput();
             throw err || new Error("codex app-server closed");
           }
           return null;
@@ -1803,6 +1830,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
       }
     } finally {
       abortRaceCleanup();
+      stopLiveInput();
     }
     turnCompleted = true;
     await steerTask;
@@ -1923,6 +1951,7 @@ export async function generateCodexAppResponse(systemPrompt, options = {}) {
       }),
     };
   } finally {
+    stopLiveInput();
     if (activeCompactions.size > 0) {
       const cancelled = !!options.abortSignal?.aborted;
       finalizeOpenCompactions(

package/src/ai/runtime/live-input-events.js

@@ -0,0 +1,94 @@
+// Metadata-only live-input acknowledgement instrumentation.
+//
+// Provider bridges already call message.acknowledge() only after their native
+// steering boundary accepts guidance. Wrapping that callback here creates one
+// adapter-neutral `live_input_applied` event without copying the guidance body
+// into runtime telemetry. A wrapper owns one logical-run dedupe set and is
+// intentionally reused by the fallback router across provider attempts.
+
+// @ts-check
+
+const LIVE_INPUT_APPLIED_INSTRUMENTED = Symbol("mono-agent.live-input-applied-instrumented");
+
+/**
+ * @typedef {{body: string, id?: string, receivedAt?: string, acknowledge?: () => void, reject?: (reason?: unknown) => void}} RuntimeLiveInputMessage
+ * @typedef {{type: "live_input_applied", inputId: string, receivedAt?: string}} LiveInputAppliedEvent
+ */
+
+/**
+ * @param {AsyncIterable<RuntimeLiveInputMessage>|undefined} liveInput
+ * @param {(event: LiveInputAppliedEvent) => void} onApplied
+ * @returns {AsyncIterable<RuntimeLiveInputMessage>|undefined}
+ */
+export function instrumentLiveInputAppliedEvents(liveInput, onApplied) {
+  if (liveInput === undefined || isInstrumented(liveInput)) return liveInput;
+
+  const appliedInputIds = new Set();
+  const instrumented = {
+    [LIVE_INPUT_APPLIED_INSTRUMENTED]: true,
+    [Symbol.asyncIterator]() {
+      const iterator = liveInput[Symbol.asyncIterator]();
+      let ordinal = 0;
+      return {
+        async next() {
+          const next = await iterator.next();
+          if (next.done === true) return next;
+          ordinal += 1;
+          const message = next.value;
+          const inputId = stableInputId(message?.id, ordinal);
+          const receivedAt = typeof message?.receivedAt === "string" && message.receivedAt.length > 0
+            ? message.receivedAt
+            : undefined;
+          const acknowledge = typeof message?.acknowledge === "function"
+            ? message.acknowledge.bind(message)
+            : undefined;
+          return {
+            done: false,
+            value: {
+              ...message,
+              acknowledge: () => {
+                acknowledge?.();
+                if (appliedInputIds.has(inputId)) return;
+                appliedInputIds.add(inputId);
+                try {
+                  onApplied({
+                    type: "live_input_applied",
+                    inputId,
+                    ...(receivedAt === undefined ? {} : { receivedAt }),
+                  });
+                } catch {
+                  // Telemetry must never turn accepted guidance into a provider
+                  // failure after the native steering call already succeeded.
+                }
+              },
+            },
+          };
+        },
+        async return(value) {
+          return typeof iterator.return === "function"
+            ? iterator.return(value)
+            : { done: true, value };
+        },
+        async throw(error) {
+          if (typeof iterator.throw === "function") return iterator.throw(error);
+          throw error;
+        },
+      };
+    },
+  };
+  return /** @type {AsyncIterable<RuntimeLiveInputMessage>} */ (instrumented);
+}
+
+/** @param {unknown} value */
+function isInstrumented(value) {
+  return typeof value === "object"
+    && value !== null
+    && value[LIVE_INPUT_APPLIED_INSTRUMENTED] === true;
+}
+
+/** @param {unknown} value @param {number} ordinal */
+function stableInputId(value, ordinal) {
+  return typeof value === "string" && value.trim().length > 0
+    ? value
+    : `anonymous:${ordinal}`;
+}

package/src/ai/runtime/router.js

@@ -41,6 +41,8 @@ import { runtimeCapabilities } from "./capabilities.js";
 import { buildTranscriptTailSnapshot, renderResumeSnapshot } from "../../agent/transcript.js";
 import { passthroughSandbox } from "../../agent/sandbox-seam.js";
 import { resolveRuntimeBrand } from "../../runtime-brand.js";
+import { createObserverHub } from "../observer.js";
+import { instrumentLiveInputAppliedEvents } from "./live-input-events.js";
 
 /**
  * @typedef {import('../types.js').RuntimeModelRef} RuntimeModelRef
@@ -127,6 +129,22 @@ export function createRouterRuntime({ host = {}, chain = [], routeSafety = "unif
      * @returns {Promise<RuntimeResult>}
      */
     async run(systemPrompt, options = {}) {
+      const liveInputHub = options.liveInput === undefined
+        ? undefined
+        : createObserverHub({
+            observers: [
+              ...(Array.isArray(host.observers) ? host.observers : []),
+              ...(Array.isArray(options.observers) ? options.observers : []),
+            ],
+            onEvent: options.onEvent,
+          });
+      if (options.liveInput !== undefined && liveInputHub !== undefined) {
+        options = {
+          ...options,
+          liveInput: instrumentLiveInputAppliedEvents(options.liveInput, liveInputHub.emit),
+        };
+      }
+      try {
       /** @type {Array<{model: RuntimeModelRef, failureKind: (string|null), requestId?: (string|null|undefined), retryableSubkind?: (string|null|undefined), requirements?: (Object<string,*>|null), routeSafety?: import('../types.js').RuntimeRouteSafetyMode, safetyContract?: import('../types.js').RuntimeRouteSafetyContract}>} */
       const failoverHistory = [];
       /** @type {RuntimeResult|null} */
@@ -374,6 +392,9 @@ export function createRouterRuntime({ host = {}, chain = [], routeSafety = "unif
         failoverHistory,
         routeSafetyHistory,
       };
+      } finally {
+        await liveInputHub?.flush();
+      }
     },
     chain: () => entries.slice(),
     configureTools(next = {}) {

package/src/ai/types.js

@@ -131,6 +131,7 @@
  * @property {string} [executionMode]                     "sdk" (default) or "cli"; selects which bridge variant handles the model.
  * @property {string} [sessionId]                         Host conversation/session key for resumable bridges.
  * @property {string} [providerSessionId]                 Provider-owned resume id for resumable bridges.
+ * @property {typeof import("@anthropic-ai/claude-agent-sdk").query} [claudeAgentQuery] Advanced programmatic/test seam for the Claude SDK route; omitted runs use the runtime's pinned SDK query implementation.
  * @property {boolean} [sessionKeepAlive]                 Keep resumable provider state alive after the turn.
  * @property {number} [sessionIdleTimeoutMs]              Idle TTL for resumable provider state.
  * @property {AsyncIterable<{body: string, id?: string, receivedAt?: string, acknowledge?: () => void, reject?: (error?: unknown) => void}>} [liveInput] Stream of in-flight user messages for steering an active run. Providers acknowledge only after accepting a message into the active turn.

package/src/runtime.js

@@ -40,6 +40,7 @@ import {
 import { createToolContext, updateToolContext } from "./agent/tools/shared/tool-context.js";
 import { resolveRuntimeBrand } from "./runtime-brand.js";
 import { retireDurableNativeSession } from "./ai/providers/pi-native/session-lifecycle.js";
+import { instrumentLiveInputAppliedEvents } from "./ai/runtime/live-input-events.js";
 
 /**
  * @typedef {import('./ai/types.js').AgentRuntimeHostOptions} AgentRuntimeHostOptions
@@ -159,6 +160,7 @@ export function createRuntime(host = {}) {
         observers: [...hostObservers, ...callObservers],
         onEvent: options.onEvent,
       });
+      const liveInput = instrumentLiveInputAppliedEvents(options.liveInput, hub.emit);
       const prompts = resolvePrompts(host.prompts, options.prompts);
       const result = await bridge.execute(systemPrompt, {
         ...hostDefaults,
@@ -172,6 +174,7 @@ export function createRuntime(host = {}) {
         toolContext,
         observerHub: hub,
         onEvent: hub.emit,
+        ...(liveInput === undefined ? {} : { liveInput }),
         // Merged AFTER the spreads so the per-field run>host>default precedence
         // wins over either bag's whole-object `prompts`.
         ...(prompts === undefined ? {} : { prompts }),

package/types/agent/compaction.d.ts

@@ -84,8 +84,6 @@ export type AgentCompactionPolicy = {
     summaryMaxTokens: number;
     fixedOverheadEnabled: boolean;
     compactionMinSavingsTokens: number;
-    toolPayloadCompactionTriggerChars: number;
-    toolPruneTriggerTokens: number;
     toolTextLimitChars: number;
     bashOutputLimitChars: number;
     mcpTextLimitChars: number;

package/types/agent/prompt/skill-index.d.ts

@@ -8,6 +8,9 @@ export function buildSkillPathNote({ assetsPath, skillsRoot }?: {
     skillsRoot?: any;
 }): string;
 /**
+ * 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 }?: {

package/types/ai/index.d.ts

@@ -3,5 +3,6 @@ export * from "./runtime/registry.js";
 export { createSessionRegistry, disposeAllProviderSessions, disposeProviderSession, invalidateProviderSession, refreshProviderSession, syncProviderSession } from "./runtime/sessions.js";
 export { createMetricsObserver, createObserverHub } from "./observer.js";
 export { generatePiNativeResponse, piNativeRuntimeBridge } from "./providers/pi-native.js";
+export { getPiBuiltinModel, listPiBuiltinModels, loginPiOAuth, reasoningLevelsForPiModel, resolvePiOAuthApiKey } from "./pi-interop.js";
 export { CLAUDE_SDK_CATALOG_VERSION, createClaudeSdkDiscoveryIsolation, curatedClaudeSdkModels, discoverClaudeSdkModels, normalizeClaudeSdkCatalog, normalizeClaudeSdkModelId } from "./providers/claude-sdk-discovery.js";
 export { buildCapabilitiesUsed, toolCompactionAppliedFromWarnings, UNKNOWN_CAPABILITY } from "./runtime/capabilities-used.js";

package/types/ai/pi-interop.d.ts

@@ -0,0 +1,113 @@
+/**
+ * List defensive snapshots of Pi's built-in models for one provider.
+ *
+ * @param {string} providerId
+ * @returns {PiBuiltinModelSnapshot[]}
+ */
+export function listPiBuiltinModels(providerId: string): PiBuiltinModelSnapshot[];
+/**
+ * Read a defensive snapshot of one Pi built-in model.
+ *
+ * @param {string} providerId
+ * @param {string} modelId
+ * @returns {PiBuiltinModelSnapshot|undefined}
+ */
+export function getPiBuiltinModel(providerId: string, modelId: string): PiBuiltinModelSnapshot | undefined;
+/**
+ * Translate Pi's model-native thinking levels to mono-agent effort spelling.
+ *
+ * @param {PiBuiltinModelSnapshot} model
+ * @returns {PiReasoningLevel[]}
+ */
+export function reasoningLevelsForPiModel(model: PiBuiltinModelSnapshot): PiReasoningLevel[];
+/**
+ * Resolve an OAuth-backed API key without allowing Pi to mutate the caller's
+ * credential record or returning Pi-owned credential objects.
+ *
+ * @param {string} providerId
+ * @param {Object<string, PiOAuthCredentialsSnapshot>} credentials
+ * @returns {Promise<{apiKey: string, newCredentials: PiOAuthCredentialsSnapshot}|null>}
+ */
+export function resolvePiOAuthApiKey(providerId: string, credentials: {
+    [x: string]: PiOAuthCredentialsSnapshot;
+}): Promise<{
+    apiKey: string;
+    newCredentials: PiOAuthCredentialsSnapshot;
+} | null>;
+/**
+ * Run a supported Pi OAuth login flow without exposing Pi's mutable provider
+ * registry or provider instances.
+ *
+ * @param {string} providerId
+ * @param {PiOAuthLoginCallbacks} callbacks
+ * @returns {Promise<PiOAuthCredentialsSnapshot>}
+ */
+export function loginPiOAuth(providerId: string, callbacks: PiOAuthLoginCallbacks): Promise<PiOAuthCredentialsSnapshot>;
+export type PiBuiltinModelSnapshot = {
+    id: string;
+    name: string;
+    api: string;
+    provider: string;
+    baseUrl: string;
+    reasoning: boolean;
+    input: Array<"text" | "image">;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        tiers?: Array<{
+            inputTokensAbove: number;
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+        }>;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    thinkingLevelMap?: {
+        [x: string]: string | null;
+    };
+    compat?: {
+        [x: string]: any;
+    };
+    headers?: {
+        [x: string]: string;
+    };
+    [key: string]: any;
+};
+export type PiReasoningLevel = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type PiOAuthCredentialsSnapshot = {
+    refresh: string;
+    access: string;
+    expires: number;
+    [key: string]: any;
+};
+export type PiOAuthLoginCallbacks = {
+    onAuth: (info: {
+        url: string;
+        instructions?: string;
+    }) => void;
+    onDeviceCode: (info: {
+        userCode: string;
+        verificationUri: string;
+        intervalSeconds?: number;
+        expiresInSeconds?: number;
+    }) => void;
+    onPrompt: (prompt: {
+        message: string;
+        placeholder?: string;
+        allowEmpty?: boolean;
+    }) => Promise<string>;
+    onProgress?: (message: string) => void;
+    onManualCodeInput?: () => Promise<string>;
+    onSelect: (prompt: {
+        message: string;
+        options: Array<{
+            id: string;
+            label: string;
+        }>;
+    }) => Promise<string | undefined>;
+    signal?: AbortSignal;
+};

package/types/ai/runtime/live-input-events.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @typedef {{body: string, id?: string, receivedAt?: string, acknowledge?: () => void, reject?: (reason?: unknown) => void}} RuntimeLiveInputMessage
+ * @typedef {{type: "live_input_applied", inputId: string, receivedAt?: string}} LiveInputAppliedEvent
+ */
+/**
+ * @param {AsyncIterable<RuntimeLiveInputMessage>|undefined} liveInput
+ * @param {(event: LiveInputAppliedEvent) => void} onApplied
+ * @returns {AsyncIterable<RuntimeLiveInputMessage>|undefined}
+ */
+export function instrumentLiveInputAppliedEvents(liveInput: AsyncIterable<RuntimeLiveInputMessage> | undefined, onApplied: (event: LiveInputAppliedEvent) => void): AsyncIterable<RuntimeLiveInputMessage> | undefined;
+export type RuntimeLiveInputMessage = {
+    body: string;
+    id?: string;
+    receivedAt?: string;
+    acknowledge?: () => void;
+    reject?: (reason?: unknown) => void;
+};
+export type LiveInputAppliedEvent = {
+    type: "live_input_applied";
+    inputId: string;
+    receivedAt?: string;
+};

package/types/ai/types.d.ts

@@ -102,6 +102,7 @@
  * @property {string} [executionMode]                     "sdk" (default) or "cli"; selects which bridge variant handles the model.
  * @property {string} [sessionId]                         Host conversation/session key for resumable bridges.
  * @property {string} [providerSessionId]                 Provider-owned resume id for resumable bridges.
+ * @property {typeof import("@anthropic-ai/claude-agent-sdk").query} [claudeAgentQuery] Advanced programmatic/test seam for the Claude SDK route; omitted runs use the runtime's pinned SDK query implementation.
  * @property {boolean} [sessionKeepAlive]                 Keep resumable provider state alive after the turn.
  * @property {number} [sessionIdleTimeoutMs]              Idle TTL for resumable provider state.
  * @property {AsyncIterable<{body: string, id?: string, receivedAt?: string, acknowledge?: () => void, reject?: (error?: unknown) => void}>} [liveInput] Stream of in-flight user messages for steering an active run. Providers acknowledge only after accepting a message into the active turn.
@@ -481,6 +482,10 @@ export type RuntimeRunOptions = {
      * Provider-owned resume id for resumable bridges.
      */
     providerSessionId?: string;
+    /**
+     * Advanced programmatic/test seam for the Claude SDK route; omitted runs use the runtime's pinned SDK query implementation.
+     */
+    claudeAgentQuery?: typeof import("@anthropic-ai/claude-agent-sdk").query;
     /**
      * Keep resumable provider state alive after the turn.
      */

package/types/ai/backend.d.ts

@@ -1,57 +0,0 @@
-export function backendCapabilities(sdkOrModel: any): any;
-export function backendUsesExecenvConfig(sdk: any): boolean;
-export function backendSupportsSessionResume(sdk: any): boolean;
-export const BACKEND_CAPABILITIES: {
-    claude: {
-        supports_session_resume: boolean;
-        streaming: boolean;
-        structured_output: boolean;
-        native_runtime_config: any;
-        supports_mcp: boolean;
-        supports_skills: boolean;
-        supports_builtin_tools: boolean;
-        supports_live_input: boolean;
-        supports_native_subagents: boolean;
-        supports_fast_mode: boolean;
-        runtime: string;
-    };
-    pi: {
-        supports_session_resume: boolean;
-        supports_native_subagents: boolean;
-        streaming: boolean;
-        structured_output: boolean;
-        native_runtime_config: any;
-        supports_mcp: boolean;
-        supports_skills: boolean;
-        supports_builtin_tools: boolean;
-        supports_live_input: boolean;
-        supports_fast_mode: boolean;
-        runtime: string;
-    };
-    codex: {
-        supports_session_resume: boolean;
-        supports_fast_mode: boolean;
-        streaming: boolean;
-        structured_output: boolean;
-        native_runtime_config: any;
-        supports_mcp: boolean;
-        supports_skills: boolean;
-        supports_builtin_tools: boolean;
-        supports_live_input: boolean;
-        supports_native_subagents: boolean;
-        runtime: string;
-    };
-    opencode: {
-        structured_output: boolean;
-        supports_session_resume: boolean;
-        supports_mcp: boolean;
-        supports_skills: boolean;
-        supports_live_input: boolean;
-        supports_native_subagents: boolean;
-        streaming: boolean;
-        native_runtime_config: any;
-        supports_builtin_tools: boolean;
-        supports_fast_mode: boolean;
-        runtime: string;
-    };
-};

package/types/ai/registry.d.ts

@@ -1 +0,0 @@
-export { listRuntimeBridges as listProviders, resolveRuntimeBridge as findProviderForModel, runtimeCapabilities } from "./runtime/registry.js";