@mono-agent/agent-runtime 0.3.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,8 +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`: estimates context pressure and compacts long agent
-  conversations for providers that support the package's compaction loop.
+- `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), `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
@@ -204,11 +225,56 @@ 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, compaction rows, raw logs, run rows, and UI-facing state
+- 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
 
+## Sessions, Follow-ups & Concurrency
+
+When `runtime.session.mode = "continuous"`, the harness keeps a conversation's
+provider session warm and serializes its turns through a per-conversation queue
+(`@mono-agent/agent-harness` `LiveSessionManager`). A message that arrives while
+a turn is in flight is **queued and answered on the warm session after the
+current turn finishes** (queue-after-turn) rather than rejected — this is what
+powers follow-up messages in chat channels. Different conversations run
+concurrently; an optional `concurrency.maxConcurrentRuns` bounds simultaneous
+model runs via admission control around the provider call (queued follow-ups
+hold no slot, so the bound never deadlocks against the queue). Note this bound is
+**per harness instance** — the app builds one harness per channel, so the limiter
+is per-channel, not a single global cap; with N enabled channels the effective
+ceiling is N× the configured value. Channels surface
+a user cancel through `responder.cancel(conversationId)`, which aborts the
+in-flight turn and clears that conversation's queue.
+
+**Honest per-provider session behavior** — parity is *behavioral* (every
+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. `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 |
+|---|---|---|---|
+| **pi** | Yes (pi `AgentHarness` + JSONL session repo) | session repo | **Yes** (only one) |
+| **claude-sdk** | No persistent process (stream closes at turn end) | `queryOptions.resume` | No (Anthropic-side id) |
+| **claude-cli** | No — respawns `claude --resume` per turn (re-inits MCP) | `--resume` replay | No |
+| **codex-app** | Live subprocess thread (dies with the subprocess) | next turn on the thread, else replay | No |
+
+claude-cli and codex only *approximate* a warm session (resume/replay), so do
+not assume warm-session latency wins there. Recall (memory embeddings) is bounded
+by a timeout + circuit breaker and degrades to empty (with a `memory_degraded`
+warning) rather than blocking or failing a turn; selected skills are mtime-cached
+across turns.
+
 ## Essential Takeaway
 
 Think of `@mono-agent/agent-runtime` as the portable agent process engine

package/MIGRATION.md

@@ -0,0 +1,293 @@
+# `@mono-agent/agent-runtime` — Migration Guide
+
+Breaking and behavioral changes for consumers upgrading **from `0.3.x`** (the
+`feat/runtime-live-sessions` line). The public entry points are unchanged —
+`createRuntime` / `createMonoRuntime`, the run-options contract, and provider
+session support (`sessionId` in, `provider_session_id` out, `disposeSession` /
+`disposeAllSessions`) all keep their shapes. The changes below affect the **Pi
+runtime bridge, a few run options, durable-session semantics, the fallback
+router, and some diagnostics**.
+
+If you only use the Claude SDK / Claude CLI / Codex backends and do not touch Pi
+or durable sessions, this is a no-op upgrade.
+
+---
+
+## 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
+registry resolves `pi` → the native bridge unconditionally; there is no
+`piEngine` flag.
+
+- **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` **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`
+
+These were Pi-bridge knobs the native path does not consume.
+
+- `piReasoningSummary` is **no longer read** and was removed from the run-options
+  type. Pi-native derives reasoning from `effort` (`thinkingLevel`); the
+  codex/claude CLIs emit reasoning summaries on their own. **Action:** stop
+  passing `piReasoningSummary` — it was already a no-op on the native path; remove
+  it from your call sites. (Host config `runtime.reasoningSummary` still validates
+  for back-compat but is not wired to a runtime option.)
+- `piCodexTransport` was doc-only and is removed. No replacement is needed.
+
+## 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
+`createAgentCompactionManager` were removed):
+
+- Before each turn the bridge estimates the running model's context usage and
+  calls `AgentHarness.compact()` when near the window (proactive). If a turn still
+  overflows the bridge compacts once and re-prompts (reactive recovery).
+- Runs report **`capabilitiesUsed.context_compaction_applied`** as `true` (a
+  compaction fired), `false` (enabled but not needed), or `null` (disabled via
+  `agent_compaction_enabled: false`). If you assert on this value, expect this
+  tristate on the Pi path.
+- The host **`onCompactionRecorded`** callback now **fires on each automatic
+  compaction** on the Pi path (previously inert).
+- The trigger window auto-tracks the model actually serving the request
+  (`harness.getModel()`) and self-corrects from any real ceiling stated in an
+  overflow error, so a wrong/default `context_window` no longer defeats it.
+  `resolveAgentCompactionPolicy` (`agent_compaction_*` settings) remains exported.
+
+## 4. Durable Pi session resume: create-on-miss semantics
+
+When a run supplies a `sessionId` **and** durable storage is configured
+(`piSessionsRoot`), Pi-native now **creates the session with that id if no
+on-disk JSONL exists** (create-on-miss), instead of returning
+`session_not_found`. An existing JSONL is reopened and resumed as before.
+
+This makes a **stable, conversation-derived session id resume across process
+restarts** (the on-disk transcript is the durable history; the in-memory
+conversation→session map is no longer required to resume). **Action:** if you
+passed an arbitrary `sessionId` to a durable run expecting a hard
+`session_not_found` on first use, note it now succeeds by creating that session.
+The in-memory (non-durable) resume path still fast-fails `session_not_found` on a
+miss.
+
+## 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
+`options.nativeSubagents.teammates` (non-empty), the same way it already infers
+`structured_output` from `outputSchema`. A chain entry that cannot satisfy it
+(e.g. a Pi fallback behind a Claude primary that was handed native teammates) is
+**skipped** (`skipped_capability_mismatch`) rather than silently succeeding with
+`nativeSubagentsUsed: []`. **Action:** if you configure fallback chains for
+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)
+
+- **Pi multimodal**: image inputs are delivered to the model as image content
+  blocks (internal fix; affects behavior, not the call shape).
+- **Tool-output limits**: settings-driven clamps (`agent_tool_text_limit_chars`,
+  `agent_search_result_limit`, `toolPayloadMaxBytes`, …) are honored again on the
+  Pi path (built-ins + MCP). The 256 KB tool-payload ceiling is unchanged.
+- **WebFetch** retries transient network errors (timeout / ECONNRESET / 5xx)
+  in-tool with backoff before returning an error.
+- **Claude CLI**: the temporary `mcp.json` written for a CLI run is now created
+  with `0600` (owner-only) permissions.
+- Pi session lifecycle is hardened: aborts during setup are honored before the
+  provider call, fresh durable sessions are deleted on setup/abort failure, and
+  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
+
+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,10 +42,12 @@ 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, credential, and compaction-recording callbacks. 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.
+selection flow, lifecycle diagrams, and host responsibilities. Upgrading from
+`0.3.x`? See [MIGRATION.md](./MIGRATION.md) for the Pi-native bridge, removed run
+options, durable-session resume semantics, and fallback-router changes.
 
 ## Install / Usage
 
@@ -89,7 +91,7 @@ console.log(result.text);
 `@mono-agent/agent-runtime` is purpose-built for **autonomous, long-running agent work** with provider portability and operational resilience as first-class concerns. It is *not* a streaming-chat UI kit. Where each peer fits:
 
 - **Vercel AI SDK** — best when you're building a chat / generative-UI experience inside a React or Next.js app. `useChat`, `useCompletion`, streaming server components, and edge-runtime compatibility are their strengths. Their provider list is curated (Anthropic, OpenAI, Google, etc., via `@ai-sdk/*` packages); there's no Pi gateway, no Claude Code CLI, no Codex CLI app-server, and no per-call provider fallback. If you're rendering a streaming chat into a browser, use them. If you're orchestrating multi-turn autonomous work that must survive a rate-limited primary provider, use us.
-- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We *wrap* it as one of our four backends and add context compaction, transcript-resume across provider drops, a 22-kind failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
+- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We *wrap* it as one of our four backends and add transcript-resume across provider drops, a 22-kind failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Context/window handling stays with the provider — the runtime does not run its own in-loop summarization pass. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
 - **Mastra** — a workflow engine + memory + RAG stack. Different category: it's the layer *above* a runtime. You can layer Mastra workflows on top of `@mono-agent/agent-runtime` if you want both.
 - **OpenAI Agents SDK** — first-party OpenAI SDK. Same trade-off as the Claude Agent SDK: tight integration with OpenAI, no other providers. Pi providers in our runtime cover OpenAI plus a dozen others through a single API.
 - **LangChain.js** — kitchen sink with deep abstraction stacks. We're deliberately lean; if you want chains, agents, vector stores, and parsers under one umbrella, LangChain is built for that. If you want a focused runtime kernel, use us.
@@ -109,7 +111,7 @@ console.log(result.text);
 | Multi-provider portability | ✓ (4 backends, 15+ providers) | partial | ✗ |
 | CLI providers (claude/codex binaries) | ✓ | ✗ | ✗ |
 | Provider fallback on rate limit / overload | ✓ (`createRouterRuntime`) | ✗ | ✗ |
-| Aggressive context compaction with summarization | ✓ | ✗ | partial |
+| Context handling delegated to the provider (no host auto-summarization) | ✓ | ✓ | ✓ |
 | Transcript-tail resume after provider drops | ✓ | ✗ | ✗ |
 | Tool-output bloat guard + artifact persistence | ✓ | ✗ | ✗ |
 | MCP transports out of the box (stdio/SSE/HTTP) | ✓ | partial | ✓ |
@@ -142,14 +144,20 @@ createRuntime({
   resolveCustomPricing,    // (parsed) => NormalizedPricing | null
   resolvePiApiKey,         // async (provider) => string | undefined
   persistArtifact,         // ({ filename, buffer, toolName, toolUseId }) => path | null
-  onCompactionRecorded,    // (compactionRow) => void
+  onCompactionRecorded,    // (compactionRow) => void — fired when the pi bridge
+                           // runs an automatic compaction (proactive or reactive
+                           // recovery) via AgentHarness.compact()
 
   // -- tool runtime context (process-level config for the tool kernel) --
   workspace,               // primary allowed root for path-based tools
   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.
@@ -228,7 +236,6 @@ Per-call options (a non-exhaustive selection):
 | `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. |
-| `piCodexTransport` | `string` | Forwarded to Pi when running OpenAI Codex models. |
 | `codexAppServerCommand` | `string` | Override the Codex CLI binary. |
 | `codexAppServerArgs` | `string[]` | Override the Codex CLI arguments. |
 
@@ -312,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.
 
@@ -395,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.
@@ -405,18 +413,36 @@ Hosts that don't supply `persistArtifact` get the truncation summary but no on-d
 
 ## Context compaction
 
-`@mono-agent/agent-runtime/agent/compaction.js` provides `createAgentCompactionManager(...)` which the Pi SDK provider invokes automatically. Configure via the agent's settings (`agent_compaction_*` keys). When a compaction completes, the kernel hands a structured row to your `onCompactionRecorded(record)` callback so the host can persist it however it likes.
+The sole pi bridge runs on pi-agent-core's native `AgentHarness`. pi performs **no**
+automatic in-loop compaction, so the bridge drives it: before each turn it estimates the
+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). 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/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
+on each automatic compaction) are exported from
+`@mono-agent/agent-runtime/agent/compaction.js` and consumed by the pi bridge.
 
 ## 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 { createAgentCompactionManager, estimateFirstTurnInput } from "@mono-agent/agent-runtime/agent/compaction.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.