@mono-agent/agent-runtime 0.13.0 → 0.15.0

package/ARCHITECTURE.md

@@ -24,6 +24,11 @@ a plain-data/plain-function seam the host wires up, not an import.
 
 ## Package Boundary
 
+**Diagram summary:** A host constructs `createRuntime()` or `createRouterRuntime()`.
+The runtime selects one of five provider bridges while sharing observability,
+failure normalization, and capability-specific agent-kernel services. It returns
+a provider-neutral result for the host to interpret.
+
 ```mermaid
 flowchart TB
   HostApp["Host app<br/>API / coordinator / worker / UI / DB"] --> CoreAI["host runtime composition"]
@@ -39,6 +44,7 @@ flowchart TB
   Registry --> ClaudeCLI["Claude Code CLI bridge"]
   Registry --> PiSDK["Pi SDK bridge<br/>OpenAI, Codex, Gemini, OpenRouter,<br/>Ollama, custom providers"]
   Registry --> CodexApp["Codex app-server CLI bridge"]
+  Registry --> OpenCodeApp["OpenCode app-server CLI bridge"]
 
   AgentKernel --> Builtins["Read / Write / Edit / Glob / Grep / Bash<br/>NodeRepl / WebFetch / WebSearch"]
   AgentKernel --> MCP["MCP stdio / SSE / HTTP tools"]
@@ -49,6 +55,7 @@ flowchart TB
   ClaudeCLI --> Providers
   PiSDK --> Providers
   CodexApp --> Providers
+  OpenCodeApp --> Providers
 
   Runtime --> Result["RuntimeResult<br/>text, structuredResult, events,<br/>usage, diagnostics, failureKind"]
   Result --> CoreAI
@@ -61,16 +68,24 @@ and pre-resolved settings into the runtime instead.
 
 ## Runtime Selection
 
+**Diagram summary:** Hosts may use `parseRuntimeModelReference()` to turn a
+canonical string into the object required by `run()`. The static registry then
+matches that object plus execution mode and lazily imports Claude SDK, Claude
+Code CLI, Pi SDK, Codex app-server, or OpenCode app-server code. Capability
+descriptors are available without loading those provider implementations.
+
 ```mermaid
 flowchart LR
-  ModelRef["options.model<br/>claude:* / pi:*:* / codex:*"] --> Parse["parseRuntimeModelReference()"]
-  Parse --> Mode["options.executionMode<br/>sdk or cli"]
+  AuthoredRef["authored model string"] --> Parse["parseRuntimeModelReference()"]
+  Parse --> ModelRef["options.model<br/>parsed RuntimeModelRef"]
+  ModelRef --> Mode["options.executionMode<br/>sdk or cli"]
   Mode --> Resolve["resolveRuntimeBridge()"]
 
   Resolve -->|sdk=claude + sdk mode| ClaudeSDK["claude bridge<br/>@anthropic-ai/claude-agent-sdk"]
   Resolve -->|sdk=claude + cli mode| ClaudeCLI["claude-code bridge<br/>claude binary"]
   Resolve -->|sdk=pi| PiSDK["pi bridge<br/>@earendil-works/pi-agent-core"]
   Resolve -->|sdk=codex + cli mode| CodexApp["codex-app bridge<br/>codex app-server"]
+  Resolve -->|sdk=opencode + cli mode| OpenCodeApp["opencode-app bridge<br/>isolated OpenCode server"]
 
   Resolve --> Caps["runtimeCapabilities()<br/>static backend features"]
   Caps --> Used["capabilitiesUsed<br/>per-call observed features"]
@@ -82,6 +97,10 @@ Canonical active model references are:
   `executionMode`
 - `pi:<providerId>:<modelName>` for Pi SDK providers
 - `codex:<modelId>` for Codex app-server CLI
+- `opencode:<providerId>:<modelName>` for the isolated OpenCode app-server CLI
+
+`createRuntime().run()` expects this already-parsed object; it does not parse a
+string implicitly.
 
 Legacy aliases are canonicalized at host ingress when needed. The strict parser
 keeps the package boundary honest by rejecting reserved runtime IDs such as
@@ -89,6 +108,11 @@ keeps the package boundary honest by rejecting reserved runtime IDs such as
 
 ## Run Lifecycle
 
+**Diagram summary:** The host calls `run()`, the runtime lazily loads one bridge,
+and that bridge talks to its SDK or subprocess. Supported tool calls pass through
+the shared kernel, provider events are normalized, and the host receives a result
+that it must validate for its domain.
+
 ```mermaid
 sequenceDiagram
   participant Host as Host app
@@ -105,15 +129,19 @@ sequenceDiagram
   Runtime->>Observer: create hub from host + call observers
   Runtime->>Bridge: execute(systemPrompt, normalized options)
 
-  Bridge->>Kernel: prepare tools, MCP, approvals, limits
-  Kernel-->>Bridge: provider-specific tool surface
+  opt bridge supports managed or MCP tool dispatch
+    Bridge->>Kernel: prepare tools, MCP, approvals, limits
+    Kernel-->>Bridge: provider-specific tool surface
+  end
   Bridge->>Provider: send prompt, messages, tools, schema, settings
 
   loop streaming events
     Provider-->>Bridge: assistant/tool/result/provider events
     Bridge->>Observer: normalized runtime events
-    Bridge->>Kernel: execute built-in/MCP tools as needed
-    Kernel-->>Bridge: tool results or tool errors
+    opt provider requests host-dispatched tools
+      Bridge->>Kernel: execute built-in/MCP tools
+      Kernel-->>Bridge: tool results or tool errors
+    end
   end
 
   Bridge-->>Runtime: RuntimeResult
@@ -122,12 +150,20 @@ sequenceDiagram
   Host->>Host: validate/parse host-specific contract
 ```
 
-The package forwards provider structured output as `structuredResult`, but it
-does not validate that output against a host domain schema. Hosts own that
-validation and any state-machine side effects.
+Claude SDK, Claude CLI, and Pi SDK can return provider-captured output as
+`structuredResult`. Codex app-server receives the schema but returns its output
+as text for the host to parse; direct OpenCode rejects the option. The package
+does not validate any captured output against a host domain schema. Hosts own
+that validation and all state-machine side effects.
 
 ## Main Subsystems
 
+**Diagram summary:** The public barrels lead to the runtime factory, fallback
+router, AI registry, and agent-kernel helpers. The registry owns five lazy
+provider loaders. Shared agent modules own tools, context, approvals,
+compaction, transcript snapshots, and result-size guards; shared AI modules own
+failure, cost, observation, and capability metadata.
+
 ```mermaid
 flowchart TB
   Public["Public API<br/>src/index.js"] --> RuntimeFactory["runtime.js<br/>createRuntime()"]
@@ -142,6 +178,7 @@ flowchart TB
   Providers --> ClaudeCode["claude-cli.js"]
   Providers --> Pi["pi-native.js<br/>pi-models/messages/events"]
   Providers --> Codex["codex-app.js"]
+  Providers --> OpenCode["opencode-app.js<br/>opencode-server.js"]
 
   AgentExports --> Tools["agent/tools/*"]
   Tools --> ToolContext["shared/tool-context.js<br/>per-instance ToolContext<br/>workspace, repoRoot, rg, sandbox, brand"]
@@ -164,8 +201,9 @@ Key responsibilities by subsystem:
 - `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/registry.js`: keeps the five static bridge descriptors, exposes
+  their metadata for introspection, and lazily imports the one whose model
+  reference plus execution mode matches a run.
 - `ai/runtime/router.js`: retries across an ordered fallback chain on retryable
   provider failures, carrying a transcript-tail resume snapshot forward.
 - `ai/providers/*`: owns provider-specific request shapes, event conversion,
@@ -199,6 +237,11 @@ Key responsibilities by subsystem:
 
 ## Host Responsibilities
 
+**Diagram summary:** The host injects pricing, Pi credentials, artifact and
+compaction persistence, tool-approval decisions, runtime branding, and allowed
+filesystem roots. The runtime returns raw normalized data; the host owns domain
+validation, durable state, and UI effects.
+
 ```mermaid
 flowchart LR
   Host["Host app"] --> Pricing["resolveCustomPricing"]
@@ -265,22 +308,21 @@ compaction fired), `false` (enabled but not needed), or `null` (disabled via
 
 | Provider | Warm session | Resume across turns | Survives process restart |
 |---|---|---|---|
-| **pi** | Yes (pi `AgentHarness` + JSONL session repo) | session repo | **Yes** (only one) |
+| **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. 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.
+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.
 
 ## Essential Takeaway
 
 Think of `@mono-agent/agent-runtime` as the portable agent process engine
 underneath a host app. The host decides what a task means, which agent should
 run, how state changes, and how results are persisted. The runtime decides how
-to talk to Claude, Pi, and Codex execution surfaces; how tools are exposed; how
-provider failures are normalized; and how enough telemetry is returned for a
-host to make reliable orchestration decisions.
+to talk to Claude, Pi, Codex, and OpenCode execution surfaces; how tools are
+exposed; how provider failures are normalized; and how enough telemetry is
+returned for a host to make reliable orchestration decisions.

package/MIGRATION.md

@@ -1,15 +1,26 @@
 # `@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**.
+Breaking and behavioral changes for consumers upgrading from `0.3.x` to the
+current pre-1.0 contract. `createRuntime()` remains the package entry point;
+`createMonoRuntime()` remains the typed facade in
+`@mono-agent/runtime-adapter`. Provider-session input/output uses
+`providerSessionId`, with `disposeSession()` and `disposeAllSessions()` retained.
 
-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.
+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.
+
+---
+
+## Pre-1.0 public-surface cleanup
+
+The compatibility entrypoints `./ai/backend.js` and `./ai/registry.js` were
+removed after repository-wide reachability checks found no supported caller.
+The old `findProviderForModel` / `listProviders` aliases and provider/backend
+constant objects were removed at the same time. Import `resolveRuntimeBridge`
+or `listRuntimeBridges` from `@mono-agent/agent-runtime` (or its `./ai` barrel)
+instead. Runtime behavior and the canonical bridge descriptors are unchanged.
 
 ---
 
@@ -23,13 +34,14 @@ registry resolves `pi` → the native bridge unconditionally; there is no
 - **Public runtime API** (`createRuntime`, model reference `"pi:<provider>:<model>"`)
   is unchanged — `pi:openai:gpt-5.5` etc. still work.
 - **Deep imports** of `@mono-agent/agent-runtime/ai/providers/pi-sdk.js` **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.
+  longer resolve**: the compatibility shim was removed and the explicit exports
+  map has no provider wildcard. **Action:** import
+  `generatePiNativeResponse` / `piNativeRuntimeBridge` from
+  `@mono-agent/agent-runtime/ai`, or select Pi through the public runtime
+  registry. `pi-errors.js` is internal and is not an exported replacement; use
+  the normalized `RuntimeResult.failureKind` or the public failure helpers at
+  `@mono-agent/agent-runtime/ai/failure.js`. The `pi*Backend` aliases are gone —
+  all Pi routes through the native bridge.
 
 ## 2. Removed run options: `piReasoningSummary`, `piCodexTransport`
 
@@ -37,10 +49,9 @@ 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.)
+  Codex and Claude CLI bridges emit their own reasoning events. **Action:**
+  remove `piReasoningSummary` from call sites. The former
+  `runtime.reasoningSummary` config field has also been removed.
 - `piCodexTransport` was doc-only and is removed. No replacement is needed.
 
 ## 3. Pi context compaction: bridge-driven via AgentHarness.compact()
@@ -67,15 +78,15 @@ These were Pi-bridge knobs the native path does not consume.
 
 ## 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
+When a run supplies a `providerSessionId` (or the legacy `sessionId` alias) **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
+passed an arbitrary `providerSessionId` 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.
@@ -155,9 +166,7 @@ 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).
+keys). Passing no `settings` — or an empty/irrelevant bag — never warns.
 
 `resolveAgentCompactionPolicy(settings, model)` stays exported (the canonical
 clamp/mapper both paths route through), and `@mono-agent/runtime-adapter` exposes
@@ -211,7 +220,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 **21 named deep `.js` subpaths**:
 
 ```text
 @mono-agent/agent-runtime/agent/allowlists.js
@@ -221,7 +230,6 @@ The package exposes **22 named deep `.js` subpaths**:
 @mono-agent/agent-runtime/agent/tools/shared/ripgrep.js
 @mono-agent/agent-runtime/agent/tools/shared/runtime-context.js
 @mono-agent/agent-runtime/agent/transcript.js
-@mono-agent/agent-runtime/ai/backend.js
 @mono-agent/agent-runtime/ai/cost.js
 @mono-agent/agent-runtime/ai/failure.js
 @mono-agent/agent-runtime/ai/file-change-stats.js
@@ -241,18 +249,18 @@ The package exposes **22 named deep `.js` subpaths**:
 
 **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.
+`pi-sdk.js` is gone and remains intentionally unexported (section 1). Import
+`generatePiNativeResponse` from `@mono-agent/agent-runtime/ai` instead of adding
+a 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.
+This guide describes the published `0.13.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.
 
 ---