@mono-agent/agent-runtime 0.13.0 → 0.14.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,15 @@
 # `@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 `0.13.x` 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.
 
 ---
 
@@ -23,13 +23,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 +38,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 +67,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 +155,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
@@ -241,18 +239,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.
 
 ---
 

package/README.md

@@ -1,15 +1,104 @@
 # @mono-agent/agent-runtime
 
+Use this package when you need direct, capability-aware access to mono-agent's
+five built-in model runtime bridges.
+
 ## Category
 
+<!-- package-metadata:start -->
+<!-- Generated by scripts/generate-package-docs.mjs. Do not edit by hand. -->
+
 Category: `runtime`
+Tier: `core`
+Catalog responsibility: Provides five runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, OpenCode app-server, Pi SDK); direct OpenCode requires stable CLI >=1.15.0 on PATH.
+
+<!-- package-metadata:end -->
 
 ## Responsibility
 
 Provides five runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, OpenCode app-server, Pi SDK), with capabilities declared per bridge. This is the runtime layer that `@mono-agent/runtime-adapter` wraps behind runtime contracts. Pi enforces optional mono-agent sandbox policy for runtime-owned tools through an injectable `RuntimeSandbox` seam (a fail-closed passthrough by default; `@mono-agent/runtime-adapter` injects the real implementation). The router supports a compatibility-preserving uniform contract or explicit isolated per-route-native contracts; no provider route silently drops required capabilities.
 
+## Install / Usage
+
+```bash
+pnpm add @mono-agent/agent-runtime
+```
+
+Node.js 22.19 or newer is required. The Claude Code, Codex, and direct
+OpenCode bridges also require their matching CLI on `PATH`; direct OpenCode
+requires stable OpenCode 1.15.0 or newer. SDK-only Claude and Pi runs do not
+spawn those CLIs.
+
+Create one runtime for a host, parse a model reference, and run a turn:
+
+```js
+import {
+  createRuntime,
+  parseRuntimeModelReference,
+} from "@mono-agent/agent-runtime";
+
+const runtime = createRuntime({ workspace: process.cwd() });
+const result = await runtime.run("You are a concise repository assistant.", {
+  model: parseRuntimeModelReference("claude:claude-sonnet-4-6"),
+  executionMode: "sdk",
+  messages: [{ role: "user", content: "Summarize README.md." }],
+  cwd: process.cwd(),
+  allowedTools: ["Read"],
+});
+
+if (result.error) throw new Error(result.error);
+console.log(result.text);
+```
+
+`Glob` and `Grep` prefer the packaged `@vscode/ripgrep` binary on supported
+platforms. An explicit `ripgrepPath` wins, with `PATH` as the final fallback.
+
+## Architecture
+
+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:
+
+### Data flow
+
+1. `createRuntime()` binds host callbacks and creates an isolated tool context.
+2. `resolveRuntimeBridge()` checks the five static bridge descriptors in order.
+3. The selected descriptor lazily imports its provider implementation.
+4. The bridge prepares the runtime inputs it supports, including managed or MCP
+   tools only where that bridge can represent them, streams normalized events,
+   and returns a provider-neutral `RuntimeResult`.
+5. The host validates any domain-specific result and owns persistence or UI
+   effects.
+
+### Package structure
+
+| Source area | Responsibility |
+| --- | --- |
+| `src/runtime.js` | Host binding, per-instance tool context, bridge dispatch, and observer flushing |
+| `src/ai/runtime/` | Model-reference parsing, the lazy bridge registry, capabilities, sessions, and fallback routing |
+| `src/ai/providers/` | Claude SDK/CLI, Codex app-server, OpenCode app-server, and Pi SDK integrations |
+| `src/agent/tools/` | Managed tools, MCP adaptation, output limits, and the injectable sandbox seam |
+| `src/agent/` | Approvals, allowlists, transcript snapshots, and compaction policy helpers |
+
+The detailed lifecycle, provider-session differences, and host boundary are in
+the [architecture guide](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/ARCHITECTURE.md).
+
 ## Public API
 
+### Start here
+
+| API | Use it for |
+| --- | --- |
+| `createRuntime()` | Run one model bridge with host-owned credentials, observers, tools, and lifecycle callbacks |
+| `createRouterRuntime()` | Retry an ordered model chain while preserving explicit route-safety contracts |
+| `parseRuntimeModelReference()` | Convert a canonical `claude:`, `codex:`, `opencode:`, or `pi:` string into the object required by `run()` |
+| `listRuntimeBridges()` / `runtimeCapabilities()` | Inspect the five built-in bridge descriptors without loading provider implementations |
+| `createPiOAuthApiKeyResolver()` | Bind a host-owned Pi auth file with refresh-safe writes |
+| `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
+runtime surfaces. The exhaustive inventory below is generated from the package
+export map.
+
 <!-- public-api-inventory:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
 
@@ -403,78 +492,7 @@ normalizeCodexItemType
 
 <!-- public-api-inventory:end -->
 
-## Dependency Boundary
-
-Depends on external provider SDKs only (`@anthropic-ai/claude-agent-sdk`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, `@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `zod`) — **zero `@mono-agent/*` workspace-package dependencies**. Sandbox enforcement for runtime-owned command preparation and network/path policy checks is an injectable `RuntimeSandbox` seam; `@mono-agent/runtime-adapter` wires in the real sandbox implementation automatically for mono-agent hosts.
-
-## What This Package Does Not Own
-
-- runtime contracts and backend descriptors (`@mono-agent/runtime-adapter`)
-- Conversation history, context building, or host-side session TTL policy (`@mono-agent/agent-harness`)
-- Host configuration (`@mono-agent/config`, `@mono-agent/agent-app`)
-
-## Verification
-
-```bash
-pnpm --filter @mono-agent/agent-runtime run test
-```
-
-## Overview
-
-Generic agent runtime that supports five bridges out of the box:
-
-- **Claude SDK** (`@anthropic-ai/claude-agent-sdk` 0.3.206)
-- **Claude Code CLI** (the `claude` binary)
-- **Pi SDK** (`@earendil-works/pi-agent-core`, used for OpenAI / Codex / Gemini / OpenRouter / Ollama / etc. via Pi providers)
-- **Codex CLI** (the `codex` app-server)
-- **OpenCode CLI** (an isolated `opencode` app-server driven through `@opencode-ai/sdk/v2`)
-
-Hosts wire in their own pricing, persistence, and credential callbacks (plus an `onCompactionRecorded` hook that fires on every automatic compaction — proactive or reactive — the pi bridge drives; see "Context compaction"). The runtime returns raw text + raw structured output; hosts that want a domain-specific contract parse it on their end.
-
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for the package boundary, runtime
-selection flow, lifecycle diagrams, and host responsibilities. Upgrading from
-`0.3.x`? See [MIGRATION.md](./MIGRATION.md) for the Pi-native bridge, removed run
-options, durable-session resume semantics, and fallback-router changes.
-
-## Install / Usage
-
-```bash
-npm install @mono-agent/agent-runtime
-```
-
-Peer requirements:
-
-- Node.js ≥ 22.19.0
-- `claude` CLI on PATH (only for `executionMode: "cli"` with `claude` SDK)
-- `codex` CLI on PATH (only for `executionMode: "cli"` with `codex` SDK; override via the `codexAppServerCommand` option)
-- stable `opencode` CLI >= 1.15.0 on PATH (only for direct `opencode:<provider>:<model>` refs)
-- `Glob` and `Grep` use the packaged `@vscode/ripgrep` binary on supported platforms. An explicit `ripgrepPath` is authoritative and PATH remains a fallback; provide one of those when optional dependencies are omitted or the platform is unsupported.
-
-## Quick start
-
-```js
-import { createRuntime } from "@mono-agent/agent-runtime";
-
-const runtime = createRuntime({
-  // Host integration (all optional)
-  workspace: "/path/to/repo",
-  ripgrepPath: "/usr/bin/rg",
-});
-
-const result = await runtime.run("You are a helpful assistant.", {
-  model: { sdk: "claude", model: "claude-sonnet-4-6" },
-  executionMode: "sdk",
-  messages: [{ role: "user", content: "Read README.md and summarize it." }],
-  cwd: "/path/to/repo",
-  allowedTools: ["Read", "Bash"],
-  maxTurns: 10,
-  onEvent: (event) => console.log(event.type),
-});
-
-console.log(result.text);
-```
-
-## When to reach for this vs. other JS agent runtimes
+### When to reach for this vs. other JS agent runtimes
 
 `@mono-agent/agent-runtime` is purpose-built for **autonomous, long-running agent work** with provider portability and operational resilience as first-class concerns. It is *not* a streaming-chat UI kit. Where each peer fits:
 
@@ -510,7 +528,7 @@ console.log(result.text);
 
 Honest summary: if the agent runs **without a human watching the screen** for minutes-to-hours and **must survive provider blips**, this is the right tool. If a human is watching a streaming chat, Vercel's SDK is the right tool. Both can coexist in the same app.
 
-## Picking a backend
+### Picking a backend
 
 The runtime picks a backend from `options.model` + `options.executionMode`:
 
@@ -518,13 +536,15 @@ The runtime picks a backend from `options.model` + `options.executionMode`:
 |---|---|---|
 | `"claude"` | `"sdk"` (or omitted) | Claude SDK |
 | `"claude"` | `"cli"` | `claude` CLI |
-| `"pi"` | any | Pi SDK |
+| `"pi"` | `"sdk"` (or omitted) | Pi SDK |
 | `"codex"` | `"cli"` | Codex app-server CLI |
 | `"opencode"` | `"cli"` | Isolated OpenCode app-server CLI |
 
-A `model` reference can be the parsed shape `{ sdk, model, provider? }` or a string (`"pi:openai:gpt-5.5"`, `"claude:claude-sonnet-4-6"`, etc.) that you parse with the package's `parseRuntimeModelReference` helper.
+A `model` is a parsed `{ sdk, model, provider? }` object. Convert canonical
+strings such as `"pi:openai:gpt-5.5"` with
+`parseRuntimeModelReference()` before calling `run()`.
 
-## `createRuntime(host)`
+### `createRuntime(host)`
 
 Pass host-level integration once at boot. All keys are optional.
 
@@ -608,13 +628,13 @@ Returns:
 - `retireDurableSession(id, sessionsRoot)` — delete and verify every exact-id durable Pi transcript, including cold duplicates.
 - `disposeSession(id)` / `invalidateSession(id)` / `disposeAllSessions()` — ordinary best-effort eviction, destructive live invalidation, and shutdown cleanup.
 
-### `runtime.run(systemPrompt, options)`
+#### `runtime.run(systemPrompt, options)`
 
 Per-call options (a non-exhaustive selection):
 
 | Option | Type | Notes |
 |---|---|---|
-| `model` | `object \| string` | **Required.** See "Picking a backend". |
+| `model` | `RuntimeModelRef` | **Required.** Pass the object returned by `parseRuntimeModelReference()`; `run()` does not parse strings. |
 | `executionMode` | `"sdk" \| "cli"` | Default `"sdk"`. |
 | `messages` | `Message[]` | Conversation history. |
 | `cwd` | `string` | Working directory for the agent's tools. |
@@ -623,9 +643,9 @@ Per-call options (a non-exhaustive selection):
 | `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. |
 | `maxTurns` | `number` | Hard cap on agent turns. |
-| `outputSchema` | `JSONSchema` | If set, the agent is asked to produce structured JSON matching this schema. The result lands in `result.structuredResult`. |
+| `outputSchema` | `JSONSchema` | Requests structured JSON on capable bridges; see “Structured output” below for bridge-specific return behavior. |
 | `abortSignal` | `AbortSignal` | Cancel the run. |
-| `liveInput` | `LiveInputQueue` | Stream of in-flight user messages (for human-in-the-loop steering). |
+| `liveInput` | `AsyncIterable<{ body: string; id?: string }>` | Stream of in-flight user messages for steering on capable bridges. |
 | `onEvent` | `(event) => void` | Fired for every event the provider emits (assistant text, tool calls/results, runtime warnings, structured output). |
 | `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
 | `providerSessionId` | `string` | Resume a prior provider session. |
@@ -638,7 +658,7 @@ Returns:
 ```ts
 {
   text: string,                     // raw assistant text
-  structuredResult?: any,           // JSON returned via outputSchema (if any)
+  structuredResult?: any,           // captured JSON on supported bridges
   structuredResultSource?: string,  // where structuredResult came from
   events: RuntimeEvent[],           // full event stream (for host-side parsing)
   usage: {
@@ -650,7 +670,7 @@ Returns:
   numTurns: number,
   model: string,
   effort: string,
-  sdk: "claude" | "pi" | "codex",
+  sdk: "claude" | "pi" | "codex" | "opencode",
   cancelled: boolean,
   error: string | null,
   errorDetails: object | null,
@@ -673,7 +693,7 @@ Returns:
 
 `capabilitiesUsed` is the per-call complement to `runtimeCapabilities()`. Tristate fields use `null` to mean "this provider can't tell" — distinct from `false` ("definitely off"). It's also emitted as a `capabilities_resolved` event near the end of the run, so observers can capture it without inspecting the result object.
 
-## Built-in tools
+### Built-in tools
 
 The agent kernel's managed tools are `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `NodeRepl`, `WebFetch`, and `WebSearch`. `NodeRepl({ code })` is backed by one lazily started Node.js REPL child per run. You select them via `allowedTools`. Tool implementations honor:
 
@@ -685,13 +705,19 @@ The agent kernel's managed tools are `Read`, `Write`, `Edit`, `Glob`, `Grep`, `B
 
 Override or extend the tool surface by passing `mcpServers` for MCP-backed tools.
 
-## Structured output
+### Structured output
 
-Pass `options.outputSchema` (a JSON Schema). On Claude SDK / Codex app-server / Pi SDK, the runtime wires the schema into the provider's structured-output API. The matched JSON lands in `result.structuredResult`.
+Pass `options.outputSchema` (a JSON Schema). Claude SDK, Claude CLI, and Pi SDK
+surface captured JSON as `result.structuredResult`. Codex app-server receives
+the schema and reports that structured output was enforced, but its bridge
+returns provider text rather than parsing `structuredResult`; hosts must parse
+and validate `result.text`. Direct OpenCode rejects `outputSchema` with a typed
+capability mismatch.
 
-The package does **not** validate `structuredResult` against your schema — it only forwards what the provider produced. Hosts run their own validation (Zod, AJV, etc.).
+The package does **not** validate captured output against your schema. Hosts run
+their own validation (Zod, AJV, and similar) before applying domain effects.
 
-## Provider fallback router
+### Provider fallback router
 
 `createRouterRuntime({ host, chain, routeSafety, 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.
 
@@ -736,7 +762,7 @@ Behaviour:
 
 Chain entries can require backend capabilities via `requires: { structured_output: true, supports_mcp: true, ... }`; entries that don't satisfy the requirements are skipped (logged in `failoverHistory` as `failureKind: "skipped_capability_mismatch"`).
 
-## Observers & metrics
+### Observers & metrics
 
 The runtime emits structured events for everything that happens during a run — assistant messages, tool calls, runtime warnings, cache hits/misses, cost updates, provider request start/end, approval lifecycle. Hosts can subscribe via `host.observers[]` (any number) or the simpler `options.onEvent` callback (one subscriber). Both work simultaneously.
 
@@ -771,7 +797,7 @@ Notable new events emitted by the bridges:
 - `cache_hit` / `cache_miss` — when the provider reports cached / cache-creation input tokens.
 - `cost_accumulated` — running cost in USD with cumulative token breakdown.
 
-## Approval gates (human-in-the-loop)
+### Approval gates (human-in-the-loop)
 
 Pass `onToolApprovalRequest` to gate tool calls behind a runtime approval. The runtime calls your callback once per tool invocation whose risk tier requires it, and pauses the agent until you respond.
 
@@ -812,7 +838,7 @@ Approval lifecycle is observable via `onEvent`:
 - `tool_approval_granted` — host approved.
 - `tool_approval_denied` — host denied, timed out, threw, or no callback for a high-risk tool.
 
-## Tool-result bloat handling
+### Tool-result bloat handling
 
 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:
 
@@ -822,7 +848,7 @@ The kernel's tool-bloat guard (`agent/tool-bloat.js`, internal) enforces a 256 K
 
 Hosts that don't supply `persistArtifact` get the truncation summary but no on-disk capture.
 
-## Context compaction
+### 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
@@ -856,7 +882,7 @@ summary output `clamp(floor(W × 0.04), 2000, 12000)`. Explicit values retain th
 scalar validation bounds. `onCompactionRecorded(record)` fires only for accepted,
 persisted automatic compactions.
 
-## Advanced exports
+### Advanced exports
 
 The package exposes a fixed set of inner pieces via subpath imports. The
 `exports` map is explicit (no `./ai/*` / `./agent/*` wildcards): only the mapped
@@ -875,10 +901,43 @@ import { configureToolRuntime, readToolRuntime } from "@mono-agent/agent-runtime
 
 These are stable but treated as advanced API. Most consumers should reach for `createRuntime` first.
 
-## Example consumer
+## Dependency Boundary
+
+This package has zero `@mono-agent/*` workspace dependencies. Its runtime
+dependencies are `@anthropic-ai/claude-agent-sdk`, `@anthropic-ai/sdk`,
+`@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`,
+`@modelcontextprotocol/sdk`, `@opencode-ai/sdk`, `@vscode/ripgrep`,
+`cross-spawn`, and `zod`.
 
-See [`examples/echo-agent/`](../../examples/echo-agent/) for a runnable consumer that imports `@mono-agent/agent-runtime`, runs a single Claude SDK turn with the Bash tool, and prints the result.
+Sandbox enforcement is an injectable `RuntimeSandbox` seam.
+`@mono-agent/runtime-adapter` supplies the mono-agent implementation; a direct
+consumer that configures a sandbox policy must inject an implementation or the
+runtime fails closed.
 
-## License
+## What This Package Does Not Own
 
-GPL-3.0-only.
+- Typed host-facing runtime contracts and SRT process wrapping, owned by
+  `@mono-agent/runtime-adapter`.
+- Conversation history, context assembly, memory coordination, or host-side
+  session policy, owned by `@mono-agent/agent-harness`.
+- Configuration loading, communication channels, domain result validation, UI,
+  and host persistence.
+
+## Related Documentation
+
+- [Runtime and providers](https://mono-agent-docs.vercel.app/runtime/) explains the
+  config-first model and backend choices.
+- [Backends and model references](https://mono-agent-docs.vercel.app/runtime/backends/)
+  documents all five bridges and their execution modes.
+- [Programmatic approvals and structured output](https://mono-agent-docs.vercel.app/programmatic/approval-and-structured-output/)
+  shows the code-only host hooks.
+- [Architecture](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/ARCHITECTURE.md)
+  and [migration guide](https://github.com/robertsreberski/mono-agent/blob/main/packages/agent-runtime/MIGRATION.md)
+  cover internal flow and upgrades from `0.3.x`.
+
+## Verification
+
+```bash
+pnpm --filter @mono-agent/agent-runtime run build
+pnpm --filter @mono-agent/agent-runtime run test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, and Pi SDK bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",

package/src/agent/approval.js

@@ -2,8 +2,10 @@
 // callback that can approve, deny, or "always approve" (session-scoped
 // allowlist). Adapted from zeroclaw's ApprovalManager pattern.
 //
-// Hosts opt in by passing `onToolApprovalRequest` to createRuntime. When the
-// callback is not supplied, the gate falls back to per-tier defaults:
+// Runtime bridges opt in by passing `onToolApprovalRequest`; the Claude SDK and
+// Pi bridges do not install this manager when that callback is absent. A host
+// that calls `createApprovalManager` directly without a callback gets these
+// low-level per-tier defaults:
 //   low risk    → auto-approve
 //   medium risk → auto-approve (no host means "don't pause")
 //   high risk   → deny (fail closed)

package/src/ai/runtime/model-refs.js

@@ -123,7 +123,7 @@ export const RESERVED_RUNTIME_KINDS = [...RESERVED_RUNTIME_IDS];
 //   sdk='claude'   → CLI (claude binary) or SDK (Anthropic)
 //   sdk='codex'    → CLI only (codex app-server)
 //   sdk='opencode' → CLI only (opencode server via @opencode-ai/sdk)
-//   sdk='pi'       → SDK only (pi-sdk handles openai-codex and other providers)
+//   sdk='pi'       → SDK only (the pi-native bridge handles openai-codex and other providers)
 
 // Returns null when the combo is fine; otherwise a short reason string the
 // UI / API can show.

package/src/ai/types.js

@@ -133,7 +133,7 @@
  * @property {string} [providerSessionId]                 Provider-owned resume id for resumable bridges.
  * @property {boolean} [sessionKeepAlive]                 Keep resumable provider state alive after the turn.
  * @property {number} [sessionIdleTimeoutMs]              Idle TTL for resumable provider state.
- * @property {boolean} [liveInput]                        Whether this run expects a live/streaming input channel.
+ * @property {AsyncIterable<{body: string, id?: string}>} [liveInput] Stream of in-flight user messages for steering an active run.
  * @property {ReadonlyArray<*>} [observers]               Per-call observers (see RuntimeObserver) merged with host-level (createRuntime) observers.
  * @property {(event: RuntimeEvent) => void} [onEvent]
  * @property {ReadonlyArray<Object>} [messages]

package/src/runtime.js

@@ -8,10 +8,10 @@
 // method that resolves the right provider bridge based on `options.model` +
 // `options.executionMode`.
 //
-// The built-in bridges (claude-sdk, claude-cli, pi-native, codex-app,
-// opencode-app) register themselves on import via the runtime registry. Hosts
-// that need
-// finer control can keep using the named exports (resolveRuntimeBridge,
+// The runtime registry contains a static table for the five built-in bridges
+// (claude-sdk, claude-cli, pi-native, codex-app, opencode-app) and lazily imports
+// the matching implementation only when a run selects it. Hosts that need finer
+// control can keep using the named exports (resolveRuntimeBridge,
 // generateClaudeResponse, etc.) directly.
 //
 // Return shape from `.run()`:

package/types/ai/types.d.ts

@@ -104,7 +104,7 @@
  * @property {string} [providerSessionId]                 Provider-owned resume id for resumable bridges.
  * @property {boolean} [sessionKeepAlive]                 Keep resumable provider state alive after the turn.
  * @property {number} [sessionIdleTimeoutMs]              Idle TTL for resumable provider state.
- * @property {boolean} [liveInput]                        Whether this run expects a live/streaming input channel.
+ * @property {AsyncIterable<{body: string, id?: string}>} [liveInput] Stream of in-flight user messages for steering an active run.
  * @property {ReadonlyArray<*>} [observers]               Per-call observers (see RuntimeObserver) merged with host-level (createRuntime) observers.
  * @property {(event: RuntimeEvent) => void} [onEvent]
  * @property {ReadonlyArray<Object>} [messages]
@@ -490,9 +490,12 @@ export type RuntimeRunOptions = {
      */
     sessionIdleTimeoutMs?: number;
     /**
-     * Whether this run expects a live/streaming input channel.
+     * Stream of in-flight user messages for steering an active run.
      */
-    liveInput?: boolean;
+    liveInput?: AsyncIterable<{
+        body: string;
+        id?: string;
+    }>;
     /**
      * Per-call observers (see RuntimeObserver) merged with host-level (createRuntime) observers.
      */