@mono-agent/agent-runtime 0.4.0 → 0.4.1

package/ARCHITECTURE.md

@@ -9,13 +9,18 @@ agent turn:
 
 - pick the right backend from a model reference and execution mode
 - expose built-in tools, MCP tools, approvals, structured output, and live input
-- enforce optional sandbox policy for built-in tool execution and stdio MCP startup
+- enforce an optional sandbox policy for built-in tool execution and stdio MCP
+  startup, through an injectable seam (see `agent/sandbox-seam.js`) rather than
+  a bundled sandboxing implementation
 - normalize provider events into one runtime event stream
 - classify runtime failures and retryable provider errors
 - collect usage, cost, cache, capability, and warning telemetry
 - return raw text plus raw structured output to the host
 
-Hosts consume the package through `src/runtime.js`.
+Hosts consume the package through `src/runtime.js`. The package has **zero
+workspace-package dependencies**: everything a host-side integration would
+otherwise need to inject (sandboxing, in this package's case) is expressed as
+a plain-data/plain-function seam the host wires up, not an import.
 
 ## Package Boundary
 
@@ -135,11 +140,12 @@ flowchart TB
 
   Providers --> Claude["claude-sdk.js"]
   Providers --> ClaudeCode["claude-cli.js"]
-  Providers --> Pi["pi-sdk.js<br/>pi-models/messages/events"]
+  Providers --> Pi["pi-native.js<br/>pi-models/messages/events"]
   Providers --> Codex["codex-app.js"]
 
   AgentExports --> Tools["agent/tools/*"]
-  Tools --> ToolRuntime["shared/runtime-context.js<br/>workspace, repoRoot, rg, brand"]
+  Tools --> ToolContext["shared/tool-context.js<br/>per-instance ToolContext<br/>workspace, repoRoot, rg, sandbox, brand"]
+  ToolContext --> ToolRuntime["shared/runtime-context.js<br/>back-compat DEFAULT context<br/>(module-level singleton wrapping tool-context.js)"]
   Tools --> PiBridge["tools/pi-bridge.js<br/>built-ins + MCP adaptation"]
 
   AgentExports --> Compaction["agent/compaction.js"]
@@ -155,8 +161,9 @@ flowchart TB
 
 Key responsibilities by subsystem:
 
-- `runtime.js`: binds host callbacks once, configures tool runtime context, and
-  routes each call to the resolved bridge.
+- `runtime.js`: binds host callbacks once, builds a per-instance `ToolContext`
+  (`agent/tools/shared/tool-context.js`) threaded to every bridge call via
+  `options.toolContext`, and routes each call to the resolved bridge.
 - `ai/runtime/registry.js`: maps model reference plus execution mode to one of
   the built-in provider bridges.
 - `ai/runtime/router.js`: retries across an ordered fallback chain on retryable
@@ -166,12 +173,22 @@ Key responsibilities by subsystem:
 - `agent/tools/*`: implements built-in tools, path/workdir guards, sandbox
   policy checks, MCP tool adaptation, Playwright artifact routing, and output
   limits.
-- `agent/compaction.js`: two pure helpers consumed by the pi bridge —
+- `agent/sandbox-seam.js`: the injectable `RuntimeSandbox` interface (policy
+  merge, command preparation, network-allow checks) and its zero-dependency
+  `passthroughSandbox` default (no policy configured → unsandboxed, exactly as
+  before; a policy configured with no implementation injected → fails closed).
+  Real hosts inject `@mono-agent/runtime-adapter`'s sandbox implementation.
+- `agent/compaction.js`: pure helpers consumed by the pi bridge —
   `resolveAgentCompactionPolicy` (derives the context-window compaction trigger +
   tool-output payload limits from `agent_compaction_*` settings and the running
-  model) and `isLikelyContextTermination` (classifies a context-pressure error).
-  The bridge drives compaction itself via `AgentHarness.compact()` (proactive +
-  reactive recovery); the legacy in-loop `transformContext` manager was removed.
+  model), `estimateFixedOverheadTokens` (the proactive fixed-overhead correction:
+  system prompt + tool schemas + per-turn message), `isLikelyContextTermination`
+  (classifies a context-pressure error), and the typed-policy/`settings`-bag shim
+  helpers (`resolveRuntimePolicyInputs`, `deprecatedSettingsWarning`) that let a
+  present `toolLimits`/`compaction` object win wholesale per-group over the
+  deprecated flat `settings` bag (MIGRATION.md §8). The bridge drives compaction
+  itself via `AgentHarness.compact()` (proactive + reactive recovery); the legacy
+  in-loop `transformContext` manager was removed.
 - `agent/transcript.js`: builds bounded resume snapshots from prior provider
   events so a fallback or continuation can keep context.
 - `agent/approval.js`: provides host-driven human-in-the-loop tool approval
@@ -208,8 +225,9 @@ The host is responsible for:
 - resolving credentials and custom provider/model rows before provider calls
 - choosing model references, execution mode, effort, fallback chains, and
   runtime settings
-- persisting artifacts, raw logs, run rows, and UI-facing state (the legacy
-  compaction-row hook is inert on the current pi bridge)
+- persisting artifacts, raw logs, run rows, and UI-facing state (via the
+  `onCompactionRecorded` hook, which fires on every automatic compaction —
+  proactive or reactive — the pi bridge drives)
 - validating structured output against the host's domain contract
 - converting runtime failures into product workflow behavior
 - deciding when to retry, recover, continue, cancel, or ask for user input
@@ -236,10 +254,13 @@ provider exposes queue-after-turn), not durability/cost:
 
 The pi runtime is built on pi-agent-core's native `AgentHarness` (the hand-rolled
 bridge was removed once native reached parity); it owns the session and
-pi-ai-managed retry, and context/window handling is delegated to the harness.
-There is **no** automatic in-loop summarization pass driven by this package, so
-runs report `context_compaction_applied: null` (unknown/unsupported) rather than
-asserting compaction ran.
+pi-ai-managed retry. `AgentHarness` itself has **no** automatic compaction, so
+the pi bridge drives it directly: before each turn it estimates the running
+model's context usage and calls `AgentHarness.compact()` when near the window
+(proactive), and if a turn still overflows it compacts once and re-prompts
+(reactive recovery). Runs report `context_compaction_applied` as `true` (a
+compaction fired), `false` (enabled but not needed), or `null` (disabled via
+`agent_compaction_enabled: false`).
 
 | Provider | Warm session | Resume across turns | Survives process restart |
 |---|---|---|---|

package/MIGRATION.md

@@ -22,13 +22,14 @@ registry resolves `pi` → the native bridge unconditionally; there is no
 
 - **Public runtime API** (`createRuntime`, model reference `"pi:<provider>:<model>"`)
   is unchanged — `pi:openai:gpt-5.5` etc. still work.
-- **Deep imports** of `@mono-agent/agent-runtime/ai/providers/pi-sdk.js` still
-  resolve via a **deprecated compatibility shim** that re-exports the native
-  equivalents (`generatePiResponse` → `generatePiNativeResponse`,
-  `piRuntimeBridge` → `piNativeRuntimeBridge`, `isContextLimitError`,
-  `normalizePiErrorMessage`, and the `pi*Backend` symbols). **Action:** migrate
-  deep imports to `./ai/providers/pi-native.js`; the shim may be removed in a
-  future major.
+- **Deep imports** of `@mono-agent/agent-runtime/ai/providers/pi-sdk.js` **no
+  longer resolve**: the deprecated compatibility shim was removed and, with the
+  Phase-6 explicit `exports` map (no `./ai/*` / `./agent/*` wildcards), that
+  subpath is not exported. **Action:** import `generatePiNativeResponse` /
+  `piNativeRuntimeBridge` from `./ai`, and
+  `isContextLimitError` / `normalizePiErrorMessage` from `./ai/providers/pi-errors.js`
+  (or reach for the public runtime registry). The `pi*Backend` aliases are gone —
+  all Pi routes through the one native bridge.
 
 ## 2. Removed run options: `piReasoningSummary`, `piCodexTransport`
 
@@ -105,6 +106,126 @@ 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)
+
+`@mono-agent/agent-runtime` does not depend on `@mono-agent/runtime-adapter`. Sandbox
+enforcement (command sandboxing, network-policy checks, and monotonic policy
+merging) is now driven through an injectable `RuntimeSandbox` seam
+(`agent/sandbox-seam.js`): `createRuntime({sandbox})` / `createRouterRuntime({host: {sandbox}})`
+accept an implementation. `@mono-agent/runtime-adapter` injects the real
+sandbox implementation automatically for every
+`createMonoRuntime(...)` call, so behavior is **byte-identical** for existing
+mono-agent hosts — no action needed if you build your runtime through
+`@mono-agent/runtime-adapter`.
+
+- **No sandbox policy configured, no implementation injected:** unchanged —
+  every tool runs unsandboxed, exactly as before.
+- **A sandbox policy IS configured, but no `RuntimeSandbox` implementation is
+  injected** (only possible if you call `@mono-agent/agent-runtime`'s
+  `createRuntime` directly, bypassing `@mono-agent/runtime-adapter`): **this
+  now fails closed** with a `sandbox_unavailable` error instead of silently
+  running the command unsandboxed. Previously `@mono-agent/agent-runtime`
+  always bundled the real sandbox implementation and always enforced the policy; a
+  host that built on `createRuntime` directly and relied on that implicit
+  availability must now also inject a `RuntimeSandbox` implementation (the
+  real one from `@mono-agent/runtime-adapter`, or a custom one) to keep policies
+  enforced. **Action:** if you configure `sandboxPolicy` and call
+  `createRuntime`/`createRouterRuntime` directly instead of going 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`)
+
+The flat `options.settings` bag is **deprecated** as the way to configure
+tool-output clamps and context compaction. The supported replacements are typed,
+per-run objects on `RuntimeRunOptions`:
+
+- **`options.toolLimits`** (`RuntimeToolLimits`) — `toolTextLimitChars`,
+  `bashOutputLimitChars`, `mcpTextLimitChars`, `searchResultLimit`,
+  `imageInlineMaxBytes`, `toolPayloadMaxBytes`, `mcpCallTimeoutMs`,
+  `mcpCallMaxTotalTimeoutMs`, `bashTimeoutMs`.
+- **`options.compaction`** (`RuntimeCompactionPolicy`) — `enabled`,
+  `triggerRatio`, `keepRecentTokens`, `summaryMaxTokens`, `minSavingsTokens`,
+  `fixedOverheadEnabled`, `contextWindowOverride`.
+
+Precedence is **per-group**: a present typed object wins wholesale for its group
+and that group's legacy `settings` keys are ignored; an absent typed object lets
+its group's `settings` keys through as a fallback. Consuming **any** legacy
+`settings` key emits exactly one `runtime_warning` with
+**`warning_kind: "deprecated_settings_option"`** per run (listing the consumed
+keys). Passing no `settings` — or an empty/irrelevant bag — never warns, so a host
+that never passed `settings` is byte-for-byte unchanged (mono-agent hosts do not
+pass it, so this is a no-op there).
+
+`resolveAgentCompactionPolicy(settings, model)` stays exported (the canonical
+clamp/mapper both paths route through), and `@mono-agent/runtime-adapter` exposes
+`resolveRuntimePolicies(settings)` to map a legacy bag to the typed objects.
+**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`
+
+Beyond `toolLimits` / `compaction`, `RuntimeRunOptions` gained:
+
+- **`sandbox`** — a per-run `RuntimeSandbox` implementation override. Precedence
+  is run > host > passthrough; it overrides only the *enforcing code*, while the
+  policy **data** still merges monotonically (I13, section 7).
+- **`sandboxPolicy`** — per-run policy data, merged monotonically with the host
+  policy (it can **tighten**, never weaken or disable).
+- **`prompts`** (`RuntimePromptOverrides`) — per-run overrides of the kernel's
+  built-in prompt fragments: `structuredOutputInstruction(systemPrompt)`,
+  `structuredOutputFinalization()`, `liveInputGuidance(body)`. Run wins over the
+  host-level `prompts` default; an absent field keeps the built-in string
+  (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)
+
+Pi 0.80 removed the harness `getApiKeyAndHeaders` hook; request auth now resolves
+through a `Models` collection's `CredentialStore`. The bridge's **per-run
+key-resolution contract is unchanged**: an `apiKeys` map entry wins, else the host
+`resolvePiApiKey(provider)` callback is consulted; a callback failure emits a
+`pi_auth_failed` runtime warning and proceeds keyless (a builtin provider then
+falls back to its own env vars, exactly as returning `undefined` from the old hook
+did). **No host action needed** — `resolvePiApiKey` behaves as before.
+
+Dependency bump: **`@earendil-works/pi-ai` and `@earendil-works/pi-agent-core` are
+now `^0.80.x`** (were `^0.79.1`). Compaction is driven natively (section 3).
+
+## 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 **21 named deep
+`.js` subpaths**, each carrying its own generated `types` condition. A deep import
+that is not on the map **no longer resolves** — a wildcard used to silently
+resolve anything under `src/`, so a moved/renamed/mistyped subpath is now a loud
+failure (guarded by `scripts/verify-deep-imports.mjs`).
+
+The 21 supported deep paths:
+
+```
+./ai/failure.js                         ./agent/tools/index.js
+./ai/cost.js                            ./agent/tools/shared/runtime-context.js
+./ai/backend.js                         ./agent/tools/shared/ripgrep.js
+./ai/runtime/model-refs.js              ./agent/prompt/skill-index.js
+./ai/runtime/registry.js                ./agent/allowlists.js
+./ai/runtime/context-windows.js         ./agent/transcript.js
+./ai/runtime/fast-mode.js               ./agent/compaction.js
+./ai/streaming/codex-events.js
+./ai/live-input-prompt.js
+./ai/file-change-stats.js
+./ai/providers/claude-sdk.js
+./ai/providers/claude-cli.js
+./ai/providers/codex-app.js
+./ai/providers/opencode-discovery.js
+```
+
+**Action:** if you deep-import a subpath not in this list, switch to the closest
+supported one, a barrel (`./ai` / `./agent`), or the public runtime registry.
+`pi-sdk.js` is gone and remains intentionally unexported (section 1). Worklab
+ports should import `generatePiNativeResponse` from `@mono-agent/agent-runtime/ai`
+instead of adding a `pi-sdk.js` compatibility subpath.
+
 ---
 
 ## Version
@@ -113,3 +234,60 @@ These changes ship in the first `agent-runtime` release after `0.3.0` on the
 `feat/runtime-live-sessions` line (a minor/major bump; see the release tag). The
 paired `@mono-agent/runtime-adapter` drops the `piReasoningSummary` field from its
 run-options type in lockstep.
+
+---
+
+## 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.x`), `@modelcontextprotocol/sdk`,
+   `@opencode-ai/sdk`, `@anthropic-ai/claude-agent-sdk`, `zod`.
+3. **Pi bump `^0.74.0` → `^0.80.x` 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)*.

package/README.md

@@ -6,7 +6,7 @@ Category: `runtime`
 
 ## Responsibility
 
-Provides the multi-backend agent runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, Pi SDK) with provider session support. This is the runtime layer that `@mono-agent/runtime-adapter` wraps behind runtime contracts, and it enforces optional `@mono-agent/sandbox` policy for runtime-owned tools.
+Provides the multi-backend agent runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, Pi SDK) with provider session support. This is the runtime layer that `@mono-agent/runtime-adapter` wraps behind runtime contracts, and it enforces an optional sandbox policy for runtime-owned tools through an injectable `RuntimeSandbox` seam (a fail-closed passthrough by default; `@mono-agent/runtime-adapter` injects the real sandbox implementation for mono-agent hosts).
 
 ## Public API
 
@@ -15,17 +15,17 @@ Provides the multi-backend agent runtime bridges (Claude SDK, Claude Code CLI, C
 - `ai/runtime/registry.js` — `listRuntimeBridges`
 - Provider bridges for `claude` (SDK + CLI), `codex` (app-server), `pi` (Pi SDK), and `opencode`
 - Provider session support: bridges accept `sessionId` in run options and report `provider_session_id`; the runtime exposes `disposeSession` / `disposeAllSessions`
-- Sandbox-aware built-in tools and stdio MCP startup through `@mono-agent/sandbox`
+- Sandbox-aware built-in tools and stdio MCP startup through an injectable `RuntimeSandbox` seam (`agent/sandbox-seam.js`) — no direct dependency on `@mono-agent/runtime-adapter`
 
 ## Dependency Boundary
 
-Depends on external provider SDKs (`@anthropic-ai/claude-agent-sdk`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, `@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `zod`) plus `@mono-agent/sandbox` for runtime-owned command preparation and network/path policy checks.
+Depends on external provider SDKs only (`@anthropic-ai/claude-agent-sdk`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, `@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `zod`) — **zero `@mono-agent/*` workspace-package dependencies**. Sandbox enforcement for runtime-owned command preparation and network/path policy checks is an injectable `RuntimeSandbox` seam; `@mono-agent/runtime-adapter` wires in the real sandbox implementation automatically for mono-agent hosts.
 
 ## What This Package Does Not Own
 
 - runtime contracts and backend descriptors (`@mono-agent/runtime-adapter`)
 - Conversation history, context building, or host-side session TTL policy (`@mono-agent/agent-harness`)
-- Host configuration (`@mono-agent/config`, `@mono-agent/agent-host`)
+- Host configuration (`@mono-agent/config`, `@mono-agent/agent-app`)
 
 ## Verification
 
@@ -42,7 +42,7 @@ Generic agent runtime that supports four backends out of the box:
 - **Pi SDK** (`@earendil-works/pi-agent-core`, used for OpenAI / Codex / Gemini / OpenRouter / Ollama / etc. via Pi providers)
 - **Codex CLI** (the `codex` app-server)
 
-Hosts wire in their own pricing, persistence, and credential callbacks (plus a legacy compaction-recording hook that is inert on the current pi bridge — see "Context compaction"). The runtime returns raw text + raw structured output; hosts that want a domain-specific contract parse it on their end.
+Hosts wire in their own pricing, persistence, and credential callbacks (plus an `onCompactionRecorded` hook that fires on every automatic compaction — proactive or reactive — the pi bridge drives; see "Context compaction"). The runtime returns raw text + raw structured output; hosts that want a domain-specific contract parse it on their end.
 
 See [ARCHITECTURE.md](./ARCHITECTURE.md) for the package boundary, runtime
 selection flow, lifecycle diagrams, and host responsibilities. Upgrading from
@@ -153,7 +153,11 @@ createRuntime({
   repoRoot,                // secondary allowed root
   ripgrepPath,             // explicit path to `rg`; falls back to vendored binary, then PATH
   qaOutputDir,             // fallback dir for Playwright MCP filename routing
-  sandboxPolicy,           // optional @mono-agent/sandbox policy for tools and stdio MCP
+  sandboxPolicy,           // optional SandboxPolicy for tools and stdio MCP (enforced
+                           // through the injectable RuntimeSandbox seam, not a bundled dep)
+  sandbox,                 // optional RuntimeSandbox implementation override (defaults to
+                           // the zero-dependency passthroughSandbox; runtime-adapter injects
+                           // the real runtime-adapter sandbox implementation for mono-agent hosts)
 
   // -- observers (multi-subscriber telemetry) --
   // Optional. Each observer receives every event the runtime emits.
@@ -315,8 +319,9 @@ console.log(result.failoverHistory);
 Behaviour:
 
 - Successful run on entry N → returns the result with `failoverHistory` set to attempts 0..N-1.
-- Retryable failure → emits `provider_failover_started`, builds a transcript snapshot, and retries on the next entry.
-- Non-retryable failure (auth, billing, invalid request) → returns immediately with `failoverHistory` containing the one attempt.
+- Retryable provider failure → emits `provider_failover_started`, builds a transcript snapshot, and retries on the next entry.
+- Provider auth failure → retries the next chain entry and preserves `failureKind: "provider_auth"` in `failoverHistory` for the failed attempt.
+- Malformed request/config/billing-type non-retryable failure → returns immediately with `failoverHistory` containing the one attempt.
 - Cancellation → returns immediately.
 - Chain exhausted → `failureKind: "provider_unavailable_exhausted"`, `failoverHistory` lists every attempt.
 
@@ -398,7 +403,7 @@ Approval lifecycle is observable via `onEvent`:
 
 ## Tool-result bloat handling
 
-`@mono-agent/agent-runtime/agent/tool-bloat.js` enforces a 256 KB default cap per `tool_result`. When a payload exceeds the cap, the kernel:
+The kernel's tool-bloat guard (`agent/tool-bloat.js`, internal) enforces a 256 KB default cap per `tool_result`. When a payload exceeds the cap, the kernel:
 
 1. Calls your `persistArtifact({ filename, buffer, toolName, toolUseId })` callback (if you supplied one).
 2. Substitutes a compact text reference in the agent's transcript.
@@ -416,7 +421,7 @@ recovery). The context window auto-tracks the model actually serving the request
 (`harness.getModel()`), self-correcting from any real ceiling stated in an overflow error.
 Runs report `context_compaction_applied: true` (fired), `false` (enabled but not needed),
 or `null` (disabled). The other backends manage their windows per their own behavior.
-(`docs/feature-registry.md` is the source of truth for this row.)
+(`docs/reference/feature-registry.md` is the source of truth for this row.)
 
 `resolveAgentCompactionPolicy(...)` (the `agent_compaction_*` settings: trigger ratio,
 keep-recent, enable/disable) and the `onCompactionRecorded(record)` host callback (fired
@@ -425,14 +430,19 @@ on each automatic compaction) are exported from
 
 ## Advanced exports
 
-The package exposes its inner pieces via subpath imports:
+The package exposes a fixed set of inner pieces via subpath imports. The
+`exports` map is explicit (no `./ai/*` / `./agent/*` wildcards): only the mapped
+subpaths resolve, each carrying generated `.d.ts` types. `node
+scripts/verify-deep-imports.mjs` asserts every mapped subpath still loads.
 
 ```js
-import { resolveRuntimeBridge, listRuntimeBridges, runtimeCapabilities } from "@mono-agent/agent-runtime/ai/runtime/registry.js";
-import { generateClaudeResponse } from "@mono-agent/agent-runtime/ai/providers/claude-sdk.js";
+import { resolveRuntimeBridge, listRuntimeBridges } from "@mono-agent/agent-runtime/ai/runtime/registry.js";
+import { parseRuntimeModelReference } from "@mono-agent/agent-runtime/ai/runtime/model-refs.js";
+import { classifyFailure, FAILURE_KINDS } from "@mono-agent/agent-runtime/ai/failure.js";
+import { resolvePricing, estimateCost } from "@mono-agent/agent-runtime/ai/cost.js";
 import { resolveAgentCompactionPolicy, isLikelyContextTermination } from "@mono-agent/agent-runtime/agent/compaction.js";
 import { configureToolRuntime, readToolRuntime } from "@mono-agent/agent-runtime/agent/tools/shared/runtime-context.js";
-// ...
+// see package.json "exports" for the full mapped set
 ```
 
 These are stable but treated as advanced API. Most consumers should reach for `createRuntime` first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Agent runtime supporting Claude SDK, Claude CLI, Codex CLI, and PI SDK out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -14,16 +14,109 @@
     "access": "public"
   },
   "exports": {
-    ".": "./src/index.js",
-    "./ai": "./src/ai/index.js",
-    "./agent": "./src/agent/index.js",
-    "./ai/*": "./src/ai/*",
-    "./agent/*": "./src/agent/*"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./ai": {
+      "types": "./types/ai/index.d.ts",
+      "default": "./src/ai/index.js"
+    },
+    "./agent": {
+      "types": "./types/agent/index.d.ts",
+      "default": "./src/agent/index.js"
+    },
+    "./ai/failure.js": {
+      "types": "./types/ai/failure.d.ts",
+      "default": "./src/ai/failure.js"
+    },
+    "./ai/cost.js": {
+      "types": "./types/ai/cost.d.ts",
+      "default": "./src/ai/cost.js"
+    },
+    "./ai/backend.js": {
+      "types": "./types/ai/backend.d.ts",
+      "default": "./src/ai/backend.js"
+    },
+    "./ai/runtime/model-refs.js": {
+      "types": "./types/ai/runtime/model-refs.d.ts",
+      "default": "./src/ai/runtime/model-refs.js"
+    },
+    "./ai/runtime/registry.js": {
+      "types": "./types/ai/runtime/registry.d.ts",
+      "default": "./src/ai/runtime/registry.js"
+    },
+    "./ai/runtime/context-windows.js": {
+      "types": "./types/ai/runtime/context-windows.d.ts",
+      "default": "./src/ai/runtime/context-windows.js"
+    },
+    "./ai/runtime/fast-mode.js": {
+      "types": "./types/ai/runtime/fast-mode.d.ts",
+      "default": "./src/ai/runtime/fast-mode.js"
+    },
+    "./ai/streaming/codex-events.js": {
+      "types": "./types/ai/streaming/codex-events.d.ts",
+      "default": "./src/ai/streaming/codex-events.js"
+    },
+    "./ai/live-input-prompt.js": {
+      "types": "./types/ai/live-input-prompt.d.ts",
+      "default": "./src/ai/live-input-prompt.js"
+    },
+    "./ai/file-change-stats.js": {
+      "types": "./types/ai/file-change-stats.d.ts",
+      "default": "./src/ai/file-change-stats.js"
+    },
+    "./ai/providers/claude-sdk.js": {
+      "types": "./types/ai/providers/claude-sdk.d.ts",
+      "default": "./src/ai/providers/claude-sdk.js"
+    },
+    "./ai/providers/claude-cli.js": {
+      "types": "./types/ai/providers/claude-cli.d.ts",
+      "default": "./src/ai/providers/claude-cli.js"
+    },
+    "./ai/providers/codex-app.js": {
+      "types": "./types/ai/providers/codex-app.d.ts",
+      "default": "./src/ai/providers/codex-app.js"
+    },
+    "./ai/providers/opencode-discovery.js": {
+      "types": "./types/ai/providers/opencode-discovery.d.ts",
+      "default": "./src/ai/providers/opencode-discovery.js"
+    },
+    "./agent/tools/index.js": {
+      "types": "./types/agent/tools/index.d.ts",
+      "default": "./src/agent/tools/index.js"
+    },
+    "./agent/tools/shared/runtime-context.js": {
+      "types": "./types/agent/tools/shared/runtime-context.d.ts",
+      "default": "./src/agent/tools/shared/runtime-context.js"
+    },
+    "./agent/tools/shared/ripgrep.js": {
+      "types": "./types/agent/tools/shared/ripgrep.d.ts",
+      "default": "./src/agent/tools/shared/ripgrep.js"
+    },
+    "./agent/prompt/skill-index.js": {
+      "types": "./types/agent/prompt/skill-index.d.ts",
+      "default": "./src/agent/prompt/skill-index.js"
+    },
+    "./agent/allowlists.js": {
+      "types": "./types/agent/allowlists.d.ts",
+      "default": "./src/agent/allowlists.js"
+    },
+    "./agent/transcript.js": {
+      "types": "./types/agent/transcript.d.ts",
+      "default": "./src/agent/transcript.js"
+    },
+    "./agent/compaction.js": {
+      "types": "./types/agent/compaction.d.ts",
+      "default": "./src/agent/compaction.js"
+    }
   },
   "main": "./src/index.js",
+  "types": "./types/index.d.ts",
   "files": [
     "src/**/*.js",
     "!src/__tests__/**",
+    "types/**/*.d.ts",
     "ARCHITECTURE.md",
     "MIGRATION.md",
     "README.md",
@@ -34,14 +127,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.1.0",
-    "@earendil-works/pi-agent-core": "^0.79.1",
-    "@earendil-works/pi-ai": "^0.79.1",
-    "@mono-agent/sandbox": "0.4.0",
+    "@earendil-works/pi-agent-core": "^0.80.3",
+    "@earendil-works/pi-ai": "^0.80.3",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@opencode-ai/sdk": "^1.15.13",
     "zod": "^4.3.6"
   },
   "scripts": {
-    "test": "pnpm --filter @mono-agent/sandbox run build && vitest run --passWithNoTests"
+    "build": "tsc -p tsconfig.types.json",
+    "test": "vitest run --passWithNoTests"
   }
 }

package/src/agent/allowlists.js

@@ -24,6 +24,9 @@ export function parseStoredAllowlist(value) {
   }
 }
 
+/**
+ * @param {{mode?: string, list?: any, fallback?: string}} [options]
+ */
 export function inferAllowlistMode({ mode, list, fallback = ALLOWLIST_MODE_ALL } = {}) {
   if (mode !== undefined) return normalizeAllowlistMode(mode);
   return normalizeList(list).length > 0

package/src/agent/approval.js

@@ -29,6 +29,9 @@ export const RISK_TIERS = Object.freeze(["low", "medium", "high"]);
 
 const DEFAULT_TIMEOUT_MS = 60_000;
 
+/**
+ * @param {{onToolApprovalRequest?: any, defaultRiskTier?: string, timeoutMs?: number, onEvent?: (event: any) => void, riskTiersByTool?: any, alwaysAllowTools?: any}} [options]
+ */
 export function createApprovalManager({
   onToolApprovalRequest = null,
   defaultRiskTier = "medium",