@mono-agent/agent-runtime 0.20.14 → 0.21.1

package/ARCHITECTURE.md

@@ -106,6 +106,34 @@ Legacy aliases are canonicalized at host ingress when needed. The strict parser
 keeps the package boundary honest by rejecting reserved runtime IDs such as
 `openai:*`, `vercel:*`, and `claude-code:*`.
 
+## Host prompt assembly and replay
+
+The harness's complete `prompt` and typed `sections` describe inspection context.
+Dispatch uses its separate `systemPrompt`: core/SOUL → identity → stable skill
+index/guidance → selected skill bodies → fixed host-envelope instruction. The
+runtime adds its structured-output instruction without moving it into host
+history. Session facts and the conditional warm-skill paragraph live in the
+leading `<host_turn_context>` envelope on every current user message. That
+latest envelope supersedes older copies; quoted surface labels, user/history,
+memory and tool output remain untrusted. Tool enforcement and delivery routes
+do not derive authority from envelope text.
+
+Every harness-prepared cold run and stale-session retry supplies chronological canonical
+messages with deterministic speaker/timestamp labels, then the bounded untrusted
+tool-history projection, then one current user message (envelope, existing
+speaker/preceding-message/user/attachment text, recall suffix). Legacy system/tool
+history is labeled untrusted text, not system authority or native tool calls.
+Inspection, canonical history and provider transcripts remain distinct: the host
+never persists the envelope into canonical user text or memory capture and does
+not use it as a recall query. Configured last-64 retention is unchanged.
+
+Only the primary's first router attempt may retain a provider session. A retry or
+backup after a warm primary failure has the current message and bounded
+failed-attempt snapshot, without the earlier conversation. Its answer retires the
+coordinated durable epoch; the next turn reseeds from canonical history. Fresh
+stateless Pi calls use a private in-memory repository so their stable attribution
+id cannot collide with or delete the primary's transcript.
+
 ## Run Lifecycle
 
 **Diagram summary:** The host calls `run()`, the runtime lazily loads one bridge,
@@ -298,25 +326,36 @@ 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 through a one-shot `session_before_compact` hook: before
+pi-ai-managed retry. `AgentHarness` supports native checkpoint and overflow compaction; mono-agent
+disables that path and drives its own guarded policy through a one-shot `session_before_compact` hook: before
 each turn it compares the full request estimate with an adaptive trigger, and if
 a turn still overflows it retries exactly once only after a preview verifies a
 positive reduction. Runs report `context_compaction_applied` as `true` (a
 compaction fired), `false` (enabled but not needed), or `null` (disabled via
 `runtime.compaction.enabled: false`).
 
-| Provider | Warm session | Resume across turns | Survives process restart |
+`ai/providers/pi-native/compaction-summary.js` prepares copies for Pi's public
+`compact()`: bounded tool-result heads/tails, confirmed built-in file operations,
+and supplemental summary focus. Its model facade changes only summary context;
+model, options, request context and other model methods are forwarded. Each
+completion is accounted once at return or rejection. The driver attaches these
+rows to terminal compaction events, preserving spend even when a preview rejects
+persistence. File metadata and generated prose are measured separately. Native
+cut rules and reserve math remain Pi-owned. Payload diagnostics correlate
+assistant usage independently of these operation-scoped summary requests.
+
+| Active bridge | Warm session | Resume across turns | Survives process restart |
 |---|---|---|---|
 | **pi** | Yes (pi `AgentHarness` + JSONL session repo) | session repo | Yes only with `piSessionsRoot` and the durable history/session transaction contract |
-| **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 |
-| **opencode-app** | No — every run uses an isolated server and private database | Unsupported | No |
-
-Claude CLI and Codex only *approximate* a warm session (resume/replay), so do
-not assume warm-session latency wins there. Direct OpenCode is intentionally
-stateless across runs.
+
+The current registry contains only Pi. A confirmed warm session omits host replay.
+An unconfirmed durable reopen refreshes the handle and supplies canonical history:
+true native resume skips seeding; missing JSONL creates an empty session and seeds
+once. Native resume preserves assistant blocks, tool ids/arguments/results and
+reasoning signatures. Cold reconstruction has only canonical text, so byte identity
+with the original native transcript is not promised. Compaction replaces an older
+prefix and keeps a tail; it may remove loaded skill bodies. Fallback routes remain
+isolated and stateless, with the same cancellation/reset/failed-commit barriers.
 
 ## Essential Takeaway
 

package/MIGRATION.md

@@ -25,7 +25,7 @@ before restarting one.
 
 ### Pi 0.85 dependency migration
 
-The runtime exact-pins Pi AI and Pi Agent Core at `0.85.0`; the TUI pins Pi TUI
+The runtime exact-pins Pi AI and Pi Agent Core at `0.85.1`; the TUI pins Pi TUI
 at the same version. Pi's harness is now created asynchronously and exposes
 prompt, navigation, compaction, abort, event, and transcript operations through
 its `main` lane with an explicit operation context. mono-agent absorbs that API
@@ -60,6 +60,29 @@ use any of them, nothing changes:
 Note also that `openai-codex` and `opencode-go` are **Pi provider ids**, not
 references to the deleted bridges. Routes naming them keep working.
 
+### Web research configuration
+
+SearXNG remains supported in strict mode and as the first configured `auto`
+route. Its canonical JSON setting is now provider-scoped:
+
+```json
+{ "tools": { "web": { "search": {
+  "backend": "searxng",
+  "searxng": { "endpoint": "http://127.0.0.1:8088" }
+} } } }
+```
+
+The former `tools.web.search.endpoint` and
+`MONO_AGENT_WEB_SEARCH_ENDPOINT` spellings remain compatibility aliases; no
+immediate migration is required. Prefer `tools.web.search.searxng.endpoint` or
+`MONO_AGENT_WEB_SEARCH_SEARXNG_ENDPOINT` when editing config. If both spellings
+are present they must normalize to the same URL.
+
+Ollama Web Search is additive and explicit-only: select `backend: "ollama"`.
+It never joins `auto`. Local mode defaults to `http://127.0.0.1:11434`; hosted
+`https://ollama.com` additionally requires `ollama.apiKeyEnv`. A hosted key is
+never sent to a local or custom origin.
+
 ### Model reference grammar
 
 Old: `<sdk>:[<provider>:]<model>`. New: **`<provider>:<model>`**, split at the
@@ -671,14 +694,14 @@ falls back to its own env vars, exactly as returning `undefined` from the old ho
 did). **No host action needed** — `resolvePiApiKey` behaves as before.
 
 Current dependency pins: **`@earendil-works/pi-ai` and
-`@earendil-works/pi-agent-core` are both `0.85.0`** (the initial Pi 0.80
+`@earendil-works/pi-agent-core` are both `0.85.1`** (the initial Pi 0.80
 migration landed at `0.80.5`, from `^0.79.1`). Pi 0.85's durable lane harness is
 adapted behind the runtime's existing public API. Compaction remains owned by
 mono-agent policy, and model-native `max` reasoning plus Pi's request-wide
 pricing tiers are preserved.
 
-Packed npm consumers resolve the runtime-owned exact Pi AI 0.85.0 copy for both
-the runtime and Agent Core's `^0.85.0` dependency. The release guard verifies
+Packed npm consumers resolve the runtime-owned exact Pi AI 0.85.1 copy for both
+the runtime and Agent Core's `^0.85.1` dependency. The release guard verifies
 both resolution paths independently.
 
 The 0.83 upgrade carries two upstream removals, both absorbed inside the runtime
@@ -735,7 +758,7 @@ a compatibility subpath.
 
 ## Version
 
-This guide describes the published `0.20.x` package contract. Keep
+This guide describes the published `0.21.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.
@@ -756,7 +779,7 @@ Worklab's runtime fork:
    `@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 dependencies
-  to the exact Pi AI `0.85.0` and Pi Agent Core `0.85.0` compatibility pins
+  to the exact Pi AI `0.85.1` and Pi Agent Core `0.85.1` compatibility pins
    rather than floating ranges. Do not restore the
    removed `pi-sdk.js` subpath.
 3. **Use the public Pi surfaces.** Run models through
@@ -764,7 +787,7 @@ Worklab's runtime fork:
    `listPiBuiltinModels`, `getPiBuiltinModel`,
    `reasoningLevelsForPiModel`, `resolvePiOAuthApiKey`, and `loginPiOAuth` for
    catalog and OAuth integration. Those façades keep Pi provider objects and the
-  exact Pi AI `0.85.0` and Pi Agent Core `0.85.0` compatibility pins inside the runtime. OAuth login adapters
+  exact Pi AI `0.85.1` and Pi Agent Core `0.85.1` compatibility pins 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

package/README.md

@@ -27,6 +27,12 @@ pnpm add @mono-agent/agent-runtime
 Node.js 22.19 or newer is required. Pi is the only runtime, and it talks to
 providers over their SDKs, so no provider CLI has to be on `PATH`.
 
+When a host enables background Exec/Bash, `wake_on_completion` defaults to true;
+explicit false retains terminal lifecycle updates without a completion turn.
+Using that field without `background: true` is invalid. Host-provided
+`processJobsAvailability` exposes lineage and exhaustion diagnostics even
+when a request has no start controller.
+
 Create one runtime for a host, parse a model reference, and run a turn:
 
 ```js
@@ -47,6 +53,16 @@ if (result.error) throw new Error(result.error);
 console.log(result.text);
 ```
 
+Requests to Pi providers `opencode` and `opencode-go`, and to custom models whose
+exact URL hostname is `opencode.ai`, carry `x-opencode-client: mono-agent` and an
+`x-opencode-session` continuity value. The value is the raw internal provider
+session id, not a channel conversation id. It remains stable for a continuous
+conversation epoch, rotates on reset or invalidation, and is fresh per call when
+a direct caller supplies no session or attribution identity. Existing
+case-insensitive auth/model/request headers—including explicit `null`
+suppression—and caller header transforms take precedence. Other providers receive
+no `x-opencode-*` headers.
+
 `Glob` and `Grep` prefer the packaged `@vscode/ripgrep` binary on supported
 platforms. An explicit `ripgrepPath` wins, with `PATH` as the final fallback.
 
@@ -63,6 +79,12 @@ See [Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-rep
 
 ## Architecture
 
+The injected Pi-native `Monitor` tool supports `wake_on: "batch" | "exit"`,
+`dedupe: "none" | "batch"`, and `min_wake_interval_ms` (defaults batch/none/0).
+The start receipt reports the host's effective policy, including interval
+clamping. Terminal delivery bypasses batch suppression and timing. A cancelled
+watch is intentionally stopped and must not be automatically recreated.
+
 The package uses a fixed registry of bridge descriptors and loads provider code
 only after a run selects a matching model reference and execution mode:
 
@@ -96,13 +118,23 @@ the [architecture guide](https://github.com/robertsreberski/mono-agent/blob/main
 
 ### Managed-tool lifecycle fidelity
 
+Native event admission precedes queued storage: observers receive `recordEvent`
+and optional `recordToolLifecycle` callbacks synchronously. The latter receives
+the normalized lifecycle event before persistence begins. This lets the harness
+retain work emitted before cancellation while its sidecar is busy. Persistence
+and client delivery remain serialized; later cancellation cannot reclassify an
+already admitted tool result.
+
 `RuntimeRunOptions.toolLifecycleSink` is an awaited host-owned boundary. The
 runtime sends redaction-eligible raw arguments/content plus stable provider call
 id and name; the host returns only record/sequence, persistence/truncation byte
 metadata, and opaque artifact references. That returned metadata is attached to
-the exact normalized `tool_use` / `tool_result` event rendered by clients. Sink
-failure is fail-soft and explicit (`persistence: "failed"` plus an error code),
-never fake success. A callback exception cannot duplicate a client event.
+the exact normalized `tool_use` / `tool_result` event rendered by clients.
+`persistence: "deferred"` preserves a host-accepted write whose foreground
+confirmation window elapsed; `failed` plus an error code is reserved for a
+definitive sink rejection. Both remain fail-soft for the provider outcome and
+neither is converted into fake success. A callback exception cannot duplicate a
+client event.
 
 Provider bridges only claim terminal distinctions their structured protocol
 actually supplies:
@@ -154,6 +186,8 @@ provider-supplied known kind when available and otherwise `runtime_error`.
 | `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 |
+| `describePiProviderAuth()` / `checkPiProviderAuth()` / `loginPiProviderAuth()` | Bridge Pi's provider-owned auth descriptions, detection, prompts, device events, and returned credential without exposing its mutable registry |
+| `runPiProviderCheck()` | Execute one isolated, bounded Pi request for an explicitly selected provider/model and return only a fixed sanitized outcome; only provider-construction options are admitted, never session/history/tool/hook state |
 | `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
@@ -176,11 +210,18 @@ BridgeSpec
 DEFAULT_RUNTIME_BRAND
 DEFAULT_TOOL_BLOAT_CONFIG
 MAX_TOOL_RESULT_BYTES
+PROVIDER_CHECK_PROMPT
 PiBuiltinModelSnapshot
 PiBuiltinProviderSnapshot
 PiOAuthCredentialsSnapshot
 PiOAuthLoginCallbacks
+PiProviderAuthCheck
+PiProviderAuthDescription
+PiProviderAuthInteraction
+PiProviderAuthPrompt
 PiReasoningLevel
+ProviderCheckCode
+ProviderCheckOutcome
 RISK_TIERS
 RUNTIME_CAPABILITIES
 RuntimeBridge
@@ -190,6 +231,8 @@ RuntimeModelRef
 UNKNOWN_CAPABILITY
 buildCapabilitiesUsed
 buildTranscriptTailSnapshot
+checkPiProviderAuth
+classifyProviderCheckFailure
 configureToolRuntime
 createApprovalManager
 createMetricsObserver
@@ -199,6 +242,7 @@ createRouterRuntime
 createRuntime
 createSessionRegistry
 describePiBuiltinProvider
+describePiProviderAuth
 disposeAllProviderSessions
 disposeProviderSession
 generatePiNativeResponse
@@ -210,6 +254,7 @@ listPiBuiltinModels
 listPiBuiltinProviders
 listRuntimeBridges
 loginPiOAuth
+loginPiProviderAuth
 normalizeAllowlistMode
 normalizeList
 normalizeRuntimeModelReference
@@ -228,6 +273,7 @@ resolveAllowlistMap
 resolvePiOAuthApiKey
 resolveRuntimeBrand
 resolveRuntimeBridge
+runPiProviderCheck
 runtimeCapabilities
 storedAllowlistMode
 syncProviderSession
@@ -367,11 +413,18 @@ renderResumeSnapshot
 
 ```text
 BridgeSpec
+PROVIDER_CHECK_PROMPT
 PiBuiltinModelSnapshot
 PiBuiltinProviderSnapshot
 PiOAuthCredentialsSnapshot
 PiOAuthLoginCallbacks
+PiProviderAuthCheck
+PiProviderAuthDescription
+PiProviderAuthInteraction
+PiProviderAuthPrompt
 PiReasoningLevel
+ProviderCheckCode
+ProviderCheckOutcome
 RUNTIME_CAPABILITIES
 RuntimeBridge
 RuntimeBridgeDescriptor
@@ -379,10 +432,13 @@ RuntimeBridgeId
 RuntimeModelRef
 UNKNOWN_CAPABILITY
 buildCapabilitiesUsed
+checkPiProviderAuth
+classifyProviderCheckFailure
 createMetricsObserver
 createObserverHub
 createSessionRegistry
 describePiBuiltinProvider
+describePiProviderAuth
 disposeAllProviderSessions
 disposeProviderSession
 generatePiNativeResponse
@@ -392,6 +448,7 @@ listPiBuiltinModels
 listPiBuiltinProviders
 listRuntimeBridges
 loginPiOAuth
+loginPiProviderAuth
 normalizeRuntimeModelReference
 parseRuntimeModelReference
 piNativeRuntimeBridge
@@ -399,6 +456,7 @@ reasoningLevelsForPiModel
 refreshProviderSession
 resolvePiOAuthApiKey
 resolveRuntimeBridge
+runPiProviderCheck
 runtimeCapabilities
 syncProviderSession
 toolCompactionAppliedFromWarnings
@@ -554,6 +612,8 @@ createRuntime({
   // -- tool runtime context (process-level config for the tool kernel) --
   workspace,               // primary allowed root for path-based tools
   repoRoot,                // secondary allowed root
+  additionalReadRoots,     // extra realpath-contained file-tool read roots
+  additionalWriteRoots,    // extra realpath-contained file-tool write roots
   ripgrepPath,             // explicit path to `rg`; falls back to packaged binary, then PATH
   qaOutputDir,             // fallback dir for Playwright MCP filename routing
   sandboxPolicy,           // optional SandboxPolicy for tools and stdio MCP (enforced
@@ -616,6 +676,10 @@ 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`.
+Pi 0.85.1 exposes GPT-6 Astra through these same catalog APIs as
+`openai:gpt-6-astra` for OpenAI API keys and
+`openai-codex:gpt-6-astra` for Codex subscriptions; no separate model allowlist
+is maintained by mono-agent.
 `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.
@@ -625,13 +689,25 @@ manual-code, and abort callbacks pass through unchanged.
 These functions deliberately do not expose Pi's mutable model collections or
 OAuth-provider registry.
 
+Headless hosts can instead use `describePiProviderAuth()` to enumerate a
+provider's OAuth/API-key methods, `checkPiProviderAuth()` to distinguish stored
+or ambient credential detection without refreshing or making a model request,
+and `loginPiProviderAuth()` to relay Pi's typed prompts and events. The last
+function returns a credential to its caller but does not persist it; the owning
+application must apply its own safe-store transaction and must never serialize
+prompt answers into an operator projection. Abort can close supported Pi flows
+and discard an uncooperative provider's late result, but it cannot undo a
+provider-side grant or a filesystem mutation that already began; the owning app
+must fence pre-mutation persistence and safely drain atomic promotion/cleanup.
+
 Returns:
 
 - `run(systemPrompt, options)` — async, runs one agent turn against the chosen backend.
 - `configureTools(next)` — update the tool runtime context after construction.
 - `syncSession(id)` — fsync provider-owned durable state before canonical history commits.
 - `refreshSession(id)` — guarantee the next resume cannot reuse process-local state; absence succeeds and cleanup uncertainty rejects.
-- `retireDurableSession(id, sessionsRoot)` — delete and verify every exact-id durable Pi transcript, including cold duplicates.
+- `recoverSession(receipt, { appliedInputIds })` — validate and fsync an opted-in, settled durable Pi tail without executing the provider or appending a message. A host-owned `sessionRecovery: { runId, revision }` run option enables receipts; retries/backups strip that option and every returned receipt. Pending recovery blocks native resume. Failed/aborted assistant messages stay on disk and are filtered by Pi; completed tool evidence retains its native bytes. False or uncertain recovery requires host retirement. See [session recovery](../../docs/runtime/sessions-concurrency.md).
+- `retireDurableSession(id, sessionsRoot)` — delete and verify every exact-id durable Pi transcript, including cold duplicates. If the matching live session is still unwinding after cancellation or failure, refresh it out of the registry and unlink and fsync its current JSONL; a post-runtime retry also removes any headerless exact-name file recreated by a late append. Uncoordinated calls retain the legacy rollback behavior; opted-in admitted durable calls can retain a provisional tail for host recovery.
 - `disposeSession(id)` / `invalidateSession(id)` / `disposeAllSessions()` — ordinary best-effort eviction, destructive live invalidation, and shutdown cleanup.
 
 #### `runtime.run(systemPrompt, options)`
@@ -649,14 +725,15 @@ Per-call options (a non-exhaustive selection):
 | `skills` / `skillsRoot` | `{name, description}[]` / `string` | Skills disclosed to the run and the directory holding `<name>/SKILL.md`. |
 | `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http). |
 | `sandboxPolicy` | `SandboxPolicy` | Optional fail-closed sandbox policy for built-in tools and stdio MCP process startup. |
-| `webSearchConfig` | `{ backend?, endpoint?, codex?: { model? } }` | Run-scoped local SearXNG, ChatGPT-subscription Codex, and keyless WebSearch backend selection. |
+| `webSearchConfig` | `{ backend?, maxRequestsPerRun?, searxng?: { endpoint? }, ollama?: { baseUrl?, apiKey?, apiKeyEnv?, trustPublicUrl? }, codex?: { model? } }` | Run-scoped ordered WebSearch selection and a 1–20 actual-provider-request budget (default 4). `auto` uses explicitly configured Ollama, configured SearXNG, Codex, then keyless; named modes are strict. The deprecated top-level `endpoint` remains a SearXNG compatibility alias. |
 | `webFetchConfig` | `{ render?, browserCommand? }` | Run-scoped static extraction and optional isolated browser-render policy. |
 | `piToolExecutionMode` | `"safe-parallel" \| "sequential"` | Pi built-in scheduling. Safe parallelism is the default; read-only tools may overlap only when the offered tool set contains no stateful/mutating or MCP tool. Otherwise Pi 0.85 serializes the whole batch. |
 | `maxTurns` | `number` | Hard cap on agent turns. |
 | `outputSchema` | `JSONSchema` | Requests structured JSON; see “Structured output” below. |
 | `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 the active run. The 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. |
+| `liveInput` | `AsyncIterable<RuntimeLiveInputMessage>` | Stream of in-flight user messages. `accepted` reports native queue acceptance; `acknowledge` reports exact owned-operation transcript consumption; `uncertain` fences ambiguous delivery; proved-safe `reject` permits identified router replay. Stable nonblank IDs are required for cross-attempt replay. |
 | `onEvent` | `(event) => void` | Fired for every runtime event (assistant text, tool calls/results, applied live input, runtime warnings, structured output). |
+| `persistArtifact` | `({ filename, buffer, toolName, toolUseId }) => path \| null` | Synchronous artifact sink for this run. A run value overrides the host default and route-attempt resolvers cannot replace it. |
 | `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
 | `providerSessionId` | `string` | Resume a prior provider session. |
 | `runArtifactDir` | `string` | Used as the Playwright MCP filename target. |
@@ -670,15 +747,21 @@ The `"allow_all_only"` value survives for custom structural bridges that accept
 only an effective unrestricted policy; omission by such a bridge means the
 capability is unknown.
 
-Live input is native on the Pi bridge.
-After the 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
-undo the steer that already reached the harness; it surfaces as a bounded
-`live_input_failed` runtime warning and ends that run's live-input consumer, so
-later guidance for the same run is no longer steered.
+Live input is native on the Pi bridge. Native acceptance is not consumption.
+Consumption requires the exact Pi entry's user `message_end` in the one
+main-lane prompt operation owned by the Mono run, plus the prompt result's
+matching operation ID. This proves transcript incorporation only—not provider
+receipt, answer use, or adherence. `live_input_consumed` records native
+evidence; legacy `live_input_applied` follows only when host acknowledgement
+returns exactly `recorded`. Void, `ignored`, throwing, or thenable callbacks
+produce settlement-unconfirmed diagnostics instead of false success.
+
+The logical-run fence keys stable IDs across retry and failover. The first
+occurrence owns its body and callbacks; later same-ID occurrences are suppressed
+as invalid duplicates. A proved pre-acceptance rejection or native queue removal
+can replay the original owner. Accepted, consumed, and uncertain IDs never
+replay. Missing IDs remain compatible but are exposed only in the first iterator
+generation. Diagnostics contain metadata only, never guidance bodies.
 
 ### Project instructions
 
@@ -699,12 +782,13 @@ by one lazily started Node.js REPL child per run. You select them via
 `allowedTools`. Tool implementations honor:
 
 - `cwd` (required for path-based tools)
-- The runtime context's `workspace` / `repoRoot` allow-list (paths outside both, plus `/tmp` and `process.cwd()`, are rejected)
-- Output truncation with optional artifact persistence (`{toolArtifactDir}/tool-output/{runId}/...` when `toolArtifactDir` is configured)
+- The runtime context's `workspace` / `repoRoot` allow-list (paths outside both, plus `/tmp` and `process.cwd()`, are rejected), with optional `additionalReadRoots` / `additionalWriteRoots` for narrowly scoped managed file-tool access. Additional roots require both the requested path and its realpath to stay inside the configured roots, so a symlink cannot escape them.
+- Output truncation with optional host-provided artifact persistence. The configured app binds this per run under `artifacts.dir/tool-output/<runId>/`.
 
 The Pi-native tool context may structurally receive a host process-job
-controller. Only then do Exec and Bash add optional `background`; with no
-controller their schemas and foreground path are unchanged. A background call
+controller. Only then do Exec and Bash add optional `background` and
+`wake_on_completion`. A host can disclose lineage diagnostics independently
+of that controller; a background request without one is rejected. A background call
 hands the exact prepared command to the controller and stops awaiting it. The
 kernel first creates a command-agnostic detached POSIX group leader; only after
 the host durably records its PID, equal PGID, and process incarnation does the
@@ -715,14 +799,34 @@ contract package for this boundary.
 
 `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 `Exec`/`Bash` and communicates through token-authenticated, length-prefixed JSON frames on ordinary stdin/stdout; 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.
 
-`WebSearch` uses a configured loopback SearXNG endpoint and/or deterministic
-public fallbacks that require no credentials. It canonicalizes and deduplicates
-results, then fuses multiple query rankings. `WebFetch` extracts HTML, JSON,
-feeds, PDFs, and text locally with
-bounded redirects, bodies, headers, and retries. Config can opt into isolated
-`agent-browser` rendering for sparse client-rendered HTML. One ephemeral
-controller per run deduplicates identical calls and closes every browser
-namespace at run end.
+`WebSearch` uses explicit Ollama Web Search, a configured loopback SearXNG
+endpoint, and deterministic public fallbacks. Strict backends do not fall
+through, and `auto` tries explicitly configured Ollama → configured SearXNG →
+Codex → keyless. Hosted Ollama bearer credentials are accepted only for the
+exact official origin. Search canonicalizes and deduplicates results, trying
+supplied alternate queries only if the primary has no relevant results. Codex
+subscription search preserves a 10% allowance reserve. An optional host-injected
+coordinator shares admission and cooldowns across processes. `WebFetch`
+deterministically decodes and extracts HTML, JSON, feeds, PDFs, and text locally
+with bounded redirects, bodies, headers, retries, and structured parser
+failures. Config can opt into isolated `agent-browser` rendering for sparse
+client-rendered HTML; an explicit `render: "always"` call is browser-first.
+One ephemeral controller per run deduplicates identical calls and closes every
+browser namespace at run end. WebFetch `start_line` and `max_lines` reuse a
+bounded run-scoped document cache. Search and fetch use total deadlines of 60
+and 45 seconds respectively, with bounded transport cleanup after cancellation.
+WebSearch also shares a default hard budget of four actual provider requests
+across route retries in one logical run. Cache hits, in-flight followers,
+cooldown skips, and quota skips do not spend it. Rate-limited providers are
+deferred for that run, with retry timing and an explicit next action returned
+to the model; children and later runs receive fresh budgets.
+
+Each normalized WebSearch result caps its title at 500 characters and its
+snippet at 4,000 characters, including a visible truncation marker directing
+the model to `WebFetch`. The ranked result body is capped at 64 KiB UTF-8;
+lower-ranked snippets shrink before whole results are omitted, while the
+control, metadata, filter, and balanced untrusted-result framing always remain.
+Ollama receives the caller's effective 1–10 result limit as `max_results`.
 
 Pi runs with selected skills also expose `ReadSkill`. It returns the complete
 skill instructions by default, including content beyond the former
@@ -747,7 +851,24 @@ JSON as `result.structuredResult`.
 
 ### Provider fallback router
 
-`createRouterRuntime({ host, chain, resolveAttempt })` wraps the standard runtime with an ordered chain of model references. On a retryable provider/auth failure it retries the logical run against the next entry with one bounded transcript-tail snapshot. A chain is stateless across provider sessions. Entry `effort` is tri-state: a string fixes that route, `null` asks for provider default, and omission inherits the legacy per-run effort.
+`createRouterRuntime({ host, chain, resolveAttempt })` wraps the standard runtime with an ordered chain of model references. On a retryable provider/auth failure it retries the logical run against the next entry with one bounded transcript-tail snapshot. Only the primary's first attempt can keep a provider session; retries and backups are stateless and their successful results withhold `providerSessionId`. Entry `effort` is tri-state: a string fixes that route, `null` asks for provider default, and omission inherits the legacy per-run effort.
+
+The primary's first attempt owns the provider session. Retries and failovers run
+stateless with bounded transcript-tail replay. With coordinated durable Pi history,
+any answer from a retry or backup retires the primary epoch. The next turn
+cold-reseeds from canonical history; after a primary first-attempt success,
+subsequent turns resume the new session and are eligible for provider caching.
+
+On a warm turn whose primary attempt fails, the retry or backup attempt runs
+stateless with the current message and a bounded snapshot of the failed attempt,
+without the earlier conversation; the next turn reseeds from canonical history.
+
+Provider attribution remains stable across attempts even when the router withholds
+the resumable result id. Fresh stateless Pi calls use a private in-memory repository
+to avoid colliding with, or deleting, a primary transcript sharing that attribution.
+Lifecycle methods forward to the router's original inner runtime; a custom
+`resolveAttempt().runtime` must not assume those methods target its own independent
+session store.
 
 ```js
 import { createRouterRuntime, parseRuntimeModelReference } from "@mono-agent/agent-runtime";
@@ -889,17 +1010,76 @@ boundary, not approving the call.
 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.
+2. For text-only overflow, substitutes a compact summary plus a UTF-8-safe
+   60/40 head/tail sample inside a new balanced untrusted frame. The explicit
+   notice says the omitted middle may contain content and the retained tail is
+   not the source ending. Image, binary, and mixed payloads stay summary-only.
 3. Emits a `runtime_warning` with `warning_kind: "tool_payload_truncated"` and the saved-paths array.
 
-Hosts that don't supply `persistArtifact` get the truncation summary but no on-disk capture.
+Hosts that don't supply `persistArtifact`, or whose sink fails, get honest
+`persistence unavailable` text and no on-disk capture; the tool call still
+completes. The configured app writes owner-private raw, untrusted files under
+`artifacts.dir/tool-output/<runId>/`. Neither run-artifact retention nor
+tool-history retention cleans them up automatically.
 
 Before that byte cap runs, the builtin `Read` tool normalizes raster images with an edge longer than 8,000 px to fit within an 8,000 × 8,000 px box. Resizing preserves aspect ratio and the source format (resized BMP input becomes PNG), retains GIF/WebP animation, and never modifies the source file. Images already within the limit are embedded byte-for-byte unchanged.
 
+### System instructions and transcript assembly
+
+The host supplies stable system instructions separately from ordered messages.
+`@mono-agent/agent-harness` projects core/SOUL, identity and skill instructions
+by typed section ids; its full inspection prompt is not dispatched as system
+text. The runtime still appends its structured-output instruction here.
+The current user message starts with the host's latest Session/warm-skill
+envelope, followed by user/attachment text and recall. Tool authorization and
+delivery routing remain host-enforced.
+
+On every cold/stateless/retry path, canonical historical text precedes the cold
+untrusted tool-history projection and current turn. Canonical replay preserves
+speaker and stored timestamp labels, but cannot reconstruct native reasoning
+signatures or tool calls. A true Pi resume skips all supplied prior messages and
+keeps its native transcript; a missing durable JSONL seeds prior messages once.
+History retention remains last-64 for the configured host. Compaction can replace
+an older native prefix and remove previously loaded skill bodies, so warm-skill
+guidance only says complete instructions may remain visible.
+
 ### Context compaction
 
-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
+Summary preparation preserves labelled heads and tails of text tool results within
+Pi's 2,000-character serializer allowance. Copies retain tool identities and
+arguments; live results remain unchanged. Confirmed `Read`/`Write`/`Edit` results
+augment file metadata using `file_path`; failed or unmatched writes remain
+unresolved evidence. File metadata and supplemental file-operation evidence each
+have a 4 KiB bound, with omission counts. Record references remain unavailable
+without a proven host resolver.
+
+A versioned focus supplements both Pi summary requests, including split turns:
+intent, approval constraints, open work, decisions, exact symbols, errors, and next
+action, distinguishing current instructions from superseded ones. Pi's prompts,
+cut rules, recent tail and output budgets remain unchanged. Empty, malformed,
+aborted and output-truncated summaries are rejected before persistence.
+
+Each `context_compaction` event includes metadata-only `accounting` (version 1).
+Terminal events retain separately identified summary requests and their status,
+duration, provider tokens and cost, including rejected requests. Missing usage or
+cost stays `null`. Transcript and full-request before/after estimates are comparable
+and explicitly inexact; `afterSource` distinguishes a candidate preview from the
+persisted context. Summary text estimates, appended metadata bytes, tail
+estimate, policy and preparation omission counts are separate. Summary content,
+paths, tool arguments and raw cache keys are excluded from accounting.
+
+With prompt-cache diagnostics enabled, assistant payload diagnostics and usage
+share a request ID and phase. `context_usage.providerCostUsd` preserves unknown
+provider cost as `null` alongside the existing compatibility cost field. Summary requests use operation-scoped IDs in
+compaction accounting; their usage never flows into assistant request totals.
+`scripts/summarize-prompt-cache.mjs` reports boundaries, separate assistant/summary
+cost, and first differing observed message fingerprints for full inputs. Differences
+are evidence of payload changes, not proof of cache misses; delta/unsupported
+prefix comparisons remain unknown. Pi summary requests retain their existing
+`cacheRetention: "none"` behavior.
+
+The sole pi bridge runs on pi-agent-core's native `AgentHarness`. Pi supports native checkpoint and overflow compaction; mono-agent disables that path
+and drives guarded compaction itself: 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 exactly once
 only after a rebuilt-context preview proves positive reduction (reactive recovery).
@@ -955,9 +1135,12 @@ These are stable but treated as advanced API. Most consumers should reach for `c
 
 ## Dependency Boundary
 
-This package has zero `@mono-agent/*` workspace dependencies. Its runtime
-dependencies are `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`,
+This package has zero `@mono-agent/*` workspace dependencies. Its runtime core
+uses `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`,
 `@modelcontextprotocol/sdk`, `@vscode/ripgrep`, `cross-spawn`, and `zod`.
+Managed web extraction owns its direct parser dependencies: Defuddle,
+Readability, linkedom, Turndown, fast-xml-parser, and unpdf. Image inspection
+uses bmp-ts and sharp.
 
 The runtime owns and exact-pins its Pi dependencies; consumers use the runtime's
 Pi façade rather than coordinating a second direct `@earendil-works/pi-ai`
@@ -989,7 +1172,8 @@ runtime fails closed.
 - [Programmatic approvals and structured output](https://mono-agent-docs.vercel.app/programmatic/approval-and-structured-output/)
   shows the code-only host hooks.
 - [Local-first web research](https://mono-agent-docs.vercel.app/tools/web-research/)
-  documents SearXNG, extraction, retry, browser isolation, and sandbox policy.
+  documents Ollama/SearXNG selection, extraction, retry, browser isolation, and
+  sandbox policy.
 - [Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-replies/)
   documents the host bridge, browser sandbox, and lifecycle limits.
 - [Architecture](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/ARCHITECTURE.md)