@mono-agent/agent-runtime 0.20.11 → 0.20.14

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,255 @@ 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.0`; 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.
+
+### 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 +670,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.0`** (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.0 copy for both
+the runtime and Agent Core's `^0.85.0` 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 +705,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 +719,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 -->
 
@@ -517,7 +756,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.0` and Pi Agent Core `0.85.0` 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 +764,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.0` and Pi Agent Core `0.85.0` 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