@mono-agent/agent-runtime 0.15.0 → 0.15.2

package/MIGRATION.md

@@ -11,9 +11,118 @@ exports map, a five-bridge lazy registry, typed policy objects, stricter sandbox
 behavior, and revised provider-session semantics even when Pi is not your
 primary route.
 
+Migration policy: every newly introduced fail-closed validation belongs in the
+first affected version section, even when it tightens behavior without changing
+the configuration schema.
+
 ---
 
-## Pre-1.0 public-surface cleanup
+## 0.15.2
+
+- **Tool-policy capability discovery:** built-in bridge capabilities now report
+  `tool_policy: "projected" | "allow_all_only"`. Pi, Claude SDK, and Claude Code
+  report `projected`; direct Codex and direct OpenCode report
+  `allow_all_only`. Custom structural bridges that omit the field have unknown
+  capability.
+- **Wildcard normalization:** any `allowedTools` list containing `"*"` is
+  semantically allow-all. Direct Codex, direct OpenCode, and the public legacy
+  Codex CLI export now accept forms such as `["*", "Read"]` when
+  `disallowedTools` is empty. Named-only lists, `[]`, and every non-empty
+  denylist still fail closed on those non-projecting routes. The guided Codex
+  readiness probe retains its exact no-tool contract.
+- **Telemetry compatibility:** the route-safety value
+  `tools: "exact-allow-all"` is unchanged. It now explicitly denotes the
+  effective unrestricted contract rather than requiring a literal one-element
+  `["*"]` array.
+
+## 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
+
+- Direct Codex normal runs introduced a fail-closed tool-policy gate: omitted
+  `allowedTools` or the explicit `["*"]` sentinel was accepted with no denied
+  tools, while named-only allowlists, `[]`, and deny lists were rejected before
+  provider startup. Version 0.15.2 preserves that safety boundary while
+  normalizing every wildcard-containing allowlist to the same effective
+  allow-all meaning.
+- `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 +133,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 +152,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 +163,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 +185,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 +200,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 +212,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 +228,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 +256,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 +286,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 +302,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 +317,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 +366,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,17 +655,35 @@ 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. |
 | `codexAppServerCommand` | `string` | Override the Codex CLI binary. |
 | `codexAppServerArgs` | `string[]` | Override the Codex CLI arguments. |
 
+`runtimeCapabilities()` and each descriptor returned by
+`listRuntimeBridges()` expose `tool_policy`. `"projected"` means the bridge can
+project restrictive `allowedTools` / `disallowedTools`; `"allow_all_only"`
+means it accepts only an effective unrestricted policy—`allowedTools` omitted
+or containing `"*"`, with no denied tools. A wildcard dominates named entries,
+so `["*", "Read"]` is allow-all. Named-only lists, `[]`, and any denylist remain
+unsupported on the direct Codex and direct OpenCode bridges and fail before
+provider startup. Built-in bridges always report this field; omission by a
+custom structural bridge means the capability is unknown.
+
 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 +752,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 +969,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.2",
   "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,