@mono-agent/agent-runtime 0.20.11 → 0.21.0

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

@@ -6,10 +6,9 @@ current pre-1.0 contract. `createRuntime()` remains the package entry point;
 `@mono-agent/runtime-adapter`. Provider-session input/output uses
 `providerSessionId`, with `disposeSession()` and `disposeAllSessions()` retained.
 
-Review every section that matches your usage. The package now has an explicit
-exports map, a five-bridge lazy registry, typed policy objects, stricter sandbox
-behavior, and revised provider-session semantics even when Pi is not your
-primary route.
+Review every section that matches your usage. As of `0.21.0` the package runs
+exactly one runtime — Pi — behind an explicit exports map, with typed policy
+objects, stricter sandbox behavior, and revised provider-session semantics.
 
 Migration policy: every newly introduced fail-closed validation belongs in the
 first affected version section, even when it tightens behavior without changing
@@ -17,6 +16,278 @@ the configuration schema.
 
 ---
 
+## 0.21.0
+
+**This is the largest breaking change since `0.3.x`.** mono-agent shipped six
+runtime bridges behind a dispatch table; it now runs only its Pi implementation.
+Read the whole section before upgrading a live agent, and migrate its config
+before restarting one.
+
+### Pi 0.85 dependency migration
+
+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
+change in its Pi compatibility adapter; hosts do not need a config migration.
+
+Pi's JSONL store now writes v4 transcripts. Existing v3 transcripts are
+upgraded by Pi when opened and retain their conversation context. An unfinished
+durable operation is aborted before mono-agent accepts a new prompt because
+mono-agent tools do not yet use Pi's replay-memo contract; this prevents an
+interrupted side-effecting tool from being executed twice.
+
+### Deleted runtime bridges
+
+`claude-sdk`, `claude-code-cli`, `codex-app-cli`, `opencode-app-cli` and
+`acp-stdio` are gone. `pi-sdk` remains and is no longer *a* backend — it is the
+runtime. The backend descriptor table, the selection table and
+`MonoRuntimeBackendId` are removed with them.
+
+### What is NOT deleted
+
+Four surfaces share names with the deleted bridges and are unaffected. If you
+use any of them, nothing changes:
+
+- **The ACP *server* bridge** (`mono-agent bridge acp`) — mono-agent still
+  serves ACP to clients. Only the ACP *client* backend was removed.
+- **`install-skill --target claude|codex`** — writes skills into those tools'
+  directories.
+- **`docs-mcp-pairing`** — pairs the docs MCP with Claude Code and Codex.
+- **The Codex web-search backend** (`tools.web.search.backend: "codex"`) — it
+  drives a real Codex app-server through an extracted client.
+
+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
+first colon only.
+
+| before | after |
+| --- | --- |
+| `pi:openai-codex:gpt-5.6-sol` | `openai-codex:gpt-5.6-sol` |
+| `pi:anthropic:claude-opus-5` | `anthropic:claude-opus-5` |
+| `ollama:llama3.1:8b` | unchanged — only the first colon splits |
+| `codex:gpt-5.6-terra` | **rejected**; no mechanical replacement |
+
+A leading `pi:` is canonicalized away automatically, so those refs keep working
+and stripping the prefix is optional tidying rather than a migration step.
+`codex:`, `claude:`, `claude-code:`, `codex-cli:`, `acp:` and `vercel:` are
+rejected at load with the replacement named in the message `doctor`,
+`mono-agent validate`, `mono-agent config` and the startup error all print. They
+are **not** migrated automatically: `codex:gpt-5.6-terra` →
+`openai-codex:gpt-5.6-terra` looks mechanical but changes which auth store the
+agent reads, and refs paired with `executionMode: "cli"` have no Pi equivalent
+at all. A human has to choose.
+
+### Retired configuration keys
+
+Each has an environment twin, and both now fail at load with the repair for the
+surface they were set on, instead of a generic unknown-key error. A single load
+is exhaustive *within one class*: every retired key present is named in one
+message, and every retired variable set is named in one message — not one per
+run. It is not exhaustive *across* classes. A config carrying both a retired key
+and a retired variable stops at the key, and names the variable only on the next
+run; see [Migrating a config](#migrating-a-config) for the order the classes are
+checked in. An empty assignment (`KEY=`) is treated as unset and does not fail.
+
+| key | environment twin | replacement |
+| --- | --- | --- |
+| `runtime.executionMode` | `MONO_AGENT_EXECUTION_MODE` | delete it — only the Pi runtime remains |
+| `memory.llm.executionMode` | `MONO_AGENT_MEMORY_LLM_EXECUTION_MODE` | delete it, same reason |
+| `runtime.routeSafety` | `MONO_AGENT_ROUTE_SAFETY` | delete it — every route is Pi-native, so `per-route-native` has no meaning |
+| `runtime.fallbackModels` | `MONO_AGENT_FALLBACK_MODELS` | `runtime.fallbacks: [{ "model": "..." }]` for the key, `MONO_AGENT_FALLBACKS_JSON` for the variable |
+
+`runtime.fallbacks` stays uncapped: `runtime.model` plus its fallbacks are the
+default route and its backups, nothing more.
+
+### New: `providers`
+
+`providers` declares which providers the agent supports, and widens what is
+*selectable* to those providers' full catalogs — previously you could only pick
+`runtime.model` or a declared fallback, so trying a new model meant editing
+config and restarting. `ollama` and `lmstudio` are zero-config autodiscovered on
+`localhost:11434` and `localhost:1234`; an explicit entry only overrides
+endpoint or credentials. `providers.local[]` migrates on load.
+
+Agents advertise the catalog additively: a slim `providers` array on `/v1/info`
+plus a lazy `GET /v1/models`. `TUI_WIRE_SCHEMA` is **not** bumped, so existing
+consoles keep working.
+
+### Removed deep exports
+
+Subpath exports went from 26 to 17. The removed subpaths all belonged to deleted
+bridges; import the Pi equivalents from the package root.
+
+### Removed host options
+
+Three `createRuntime()` host options went with the ACP *client* backend that was
+their only consumer: `resolveAcpProfile`, `onAcpInteractionRequest` and
+`acpSessionTokenKey`. The `0.18.0` and `0.18.1` sections below still describe
+them as required — that is a correct record of what those releases needed, and
+those sections are deliberately unchanged. As of `0.21.0` the runtime no longer
+binds them, and passing them is inert.
+
+This does **not** affect the ACP *server* bridge (`mono-agent bridge acp`),
+which never used them; see [What is NOT deleted](#what-is-not-deleted).
+
+### Web console store
+
+Schema v10 → v12, in two guarded steps: v11 adds per-thread `run_model` /
+`run_effort`, and v12 adds `agents.providers_json`, the persisted summary of the
+providers an agent advertises. Each step is guarded on `PRAGMA table_info` and
+re-runnable, and adds columns only — no rows are rewritten. Per-conversation
+model and effort overrides now persist server-side, so they roam between devices
+instead of living in one browser's localStorage.
+
+### Migrating a config
+
+There is no codemod. `mono-agent migrate-config` was written for this release and
+then removed before it shipped: it rewrote a live agent's config while the agent
+itself could be writing the same file, and that race could not be closed — only
+narrowed. Migrating by hand is a few minutes per agent and cannot lose data.
+
+The loader does the finding for you. Every retired key, retired environment
+variable and rejected model reference fails at load naming its own repair, so an
+unmigrated agent refuses to start and tells you what to change:
+
+```text
+MonoAgentConfigError: invalid_json
+`runtime.executionMode` was removed; mono-agent runs only the Pi runtime (SDK).
+Delete the key.
+
+MonoAgentConfigError: invalid_env
+`MONO_AGENT_FALLBACK_MODELS` was replaced by `MONO_AGENT_FALLBACKS_JSON`, a JSON
+array of `{ "model": "..." }` objects. Remove the variable and re-express the
+chain there, or drop it into `runtime.fallbacks` in mono-agent.config.json.
+
+MonoAgentConfigError: invalid_model_reference
+runtime.model `codex:gpt-5.6-terra` is not a valid runtime model reference:
+codex is no longer a runtime backend; use openai-codex:gpt-5.6-terra
+```
+
+A model supplied through the environment is attributed to the variable
+(`MONO_AGENT_MODEL ...`) rather than the JSON path, so the message always names
+the place you edit to fix it.
+
+What it does *not* do is report everything at once. Within a class it is
+exhaustive — all retired JSON keys in one message, all retired environment
+variables in one message, all unknown keys in one message — but the load stops at
+the first failing class, in this order: retired JSON keys, unknown JSON keys,
+retired environment variables, model references, then the remaining shape checks.
+Expect to run `mono-agent validate` a few times per agent, not once.
+
+#### Required — the load fails until each of these is done
+
+In `mono-agent.config.json`:
+
+1. Delete `runtime.executionMode`, `memory.llm.executionMode` and
+   `runtime.routeSafety`.
+2. Convert `runtime.fallbackModels: ["a", "b"]` to
+   `runtime.fallbacks: [{ "model": "a" }, { "model": "b" }]`.
+3. Replace every `codex:`, `claude:`, `claude-code:`, `codex-cli:`, `acp:`,
+   `vercel:<provider>:<model>` and nested `opencode:<provider>:<model>` reference
+   — in `runtime.model`, every `runtime.fallbacks[].model`, every
+   `subagents.definitions[].model`, an `agent-host` `memory.llm.model`, and every
+   per-trigger `model` override. The `vercel:`/`opencode:` wrappers unwrap to the
+   inner pair; the rest do not — `codex:gpt-5.6-terra` becomes
+   `openai-codex:gpt-5.6-terra`, which is a different auth store, so that
+   substitution is a decision, not a rename. The load error names the exact
+   replacement for each form.
+
+In the environment — the shell, the `.env` the agent is started with, and any
+`EnvironmentVariables` block in its launchd plist:
+
+4. Remove `MONO_AGENT_EXECUTION_MODE`, `MONO_AGENT_ROUTE_SAFETY` and
+   `MONO_AGENT_MEMORY_LLM_EXECUTION_MODE`. There is no replacement variable.
+5. Remove `MONO_AGENT_FALLBACK_MODELS` and re-express the chain as
+   `MONO_AGENT_FALLBACKS_JSON` (a JSON array of `{ "model": "..." }` objects), or
+   move it into `runtime.fallbacks` in the config file. Pointing this one at the
+   JSON key alone is not a repair: an operator whose chain lives only in `.env`
+   has no `runtime.fallbackModels` key to rewrite.
+6. Apply step 3 to any model reference carried in `MONO_AGENT_MODEL`,
+   `MONO_AGENT_FALLBACKS_JSON`, `MONO_AGENT_SUBAGENTS_JSON` or
+   `MONO_AGENT_MEMORY_LLM_MODEL`.
+
+And in trigger frontmatter:
+
+7. The same step-3 fix to `model:` in every `*.md` under the cron and webhook
+   trigger folders (`cron.dir` / `webhook.dir` if renamed, resolved from the
+   agent root).
+
+An empty assignment (`KEY=`) is *not* a migration item: every reader here treats
+an empty environment value as unset, so an inert leftover line in a deployed
+`.env` neither configured anything before nor fails the load now.
+
+#### Optional — accepted either way
+
+8. A leading `pi:` on a runtime reference is canonicalized away at load, so
+   `pi:openai-codex:gpt-5.6-terra` loads today and resolves to
+   `openai-codex:gpt-5.6-terra`. Stripping it from `runtime.model` and
+   `runtime.fallbacks[].model` is cosmetic — do it if you want the file to match
+   what `mono-agent config` prints. `pi:codex:...` is still rejected: the inner
+   pair is checked after the wrapper comes off.
+9. Strip `pi:` from `memory.llm.model` **only** when `memory.llm.provider` is
+   `agent-host`. Under the default `ollama` provider that field is a raw service
+   model string, where the colon in `qwen3:8b` is a tag separator — rewriting it
+   would repoint memory at a model that does not exist.
+
+#### `configVersion: 1` files are not covered by this checklist
+
+`configVersion` belonged to an experimental schema (`runtimes`, `routing`,
+`policy`, `state`, `$use` dependency injection) that the shipped loader has never
+accepted. None of steps 1–9 apply, because none of those keys exist in such a
+file; it is rejected whole, as unknown keys:
+
+```text
+mono-agent.config.json contains unknown keys: agent.id, agent.instructions,
+agent.workspace, channels.operator, configVersion, context.skills, policy,
+routing, runtimes, session, state. Remove or correct them; unknown keys are not
+ignored.
+```
+
+Re-author such a config against the current schema (or `mono-agent init` a fresh
+one and port the values across); there is no `configVersion: 1` upgrade path.
+
+### Deployment order
+
+```text
+merge → release 0.21.0 → per agent: stop it, edit the config, mono-agent validate
+      → mono-agent start
+```
+
+Edit with the agent stopped. `mono-agent validate` runs the same load as startup
+without starting a turn or spending a model call, so it finds these problems for
+free — but it reports one failing class per run (see above), so re-run it after
+each edit until it comes back clean.
+
+---
+
 ## 0.19.0
 
 - **Oversized `Read` images:** raster image results with an edge above 8,000
@@ -422,17 +693,16 @@ key-resolution contract is unchanged**: an `apiKeys` map entry wins, else the ho
 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` is now `0.84.3`; `@earendil-works/pi-agent-core` remains `0.83.0`**
-(the initial Pi 0.80 migration landed at `0.80.5`, from `^0.79.1`, ran at
-`0.80.6` until the 0.83 upgrade, and then at `0.83.0`). Agent Core 0.84.3 is
-held back because its replacement durable harness does not yet implement the
-prompt, subscription, compaction, or abort paths used here. Compaction is driven
-natively (section 3), and model-native `max` reasoning plus Pi's request-wide
+Current dependency pins: **`@earendil-works/pi-ai` and
+`@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 consequently retain Agent Core's nested Pi AI 0.83.0
-compatibility copy beside the runtime-owned Pi AI 0.84.3 catalog/provider copy.
-The release guard resolves and verifies both exact paths independently.
+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
 so hosts need no action:
@@ -458,7 +728,7 @@ now a loud failure (guarded by `scripts/verify-deep-imports.mjs`).
 <!-- public-api-js-subpaths:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
 
-The package exposes **22 named deep `.js` subpaths**:
+The package exposes **14 named deep `.js` subpaths**:
 
 ```text
 @mono-agent/agent-runtime/agent/allowlists.js
@@ -472,17 +742,9 @@ The package exposes **22 named deep `.js` subpaths**:
 @mono-agent/agent-runtime/ai/failure.js
 @mono-agent/agent-runtime/ai/file-change-stats.js
 @mono-agent/agent-runtime/ai/live-input-prompt.js
-@mono-agent/agent-runtime/ai/providers/acp.js
-@mono-agent/agent-runtime/ai/providers/claude-cli.js
-@mono-agent/agent-runtime/ai/providers/claude-sdk-discovery.js
-@mono-agent/agent-runtime/ai/providers/claude-sdk.js
-@mono-agent/agent-runtime/ai/providers/codex-app.js
-@mono-agent/agent-runtime/ai/providers/opencode-discovery.js
-@mono-agent/agent-runtime/ai/runtime/context-windows.js
-@mono-agent/agent-runtime/ai/runtime/fast-mode.js
+@mono-agent/agent-runtime/ai/providers/codex/app-server-client.js
 @mono-agent/agent-runtime/ai/runtime/model-refs.js
 @mono-agent/agent-runtime/ai/runtime/registry.js
-@mono-agent/agent-runtime/ai/streaming/codex-events.js
 ```
 <!-- public-api-js-subpaths:end -->
 
@@ -496,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.
@@ -517,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.84.3` and Pi Agent Core `0.83.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
@@ -525,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.84.3` and Pi Agent Core `0.83.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