@mono-agent/agent-runtime 0.3.0 → 0.4.0

package/ARCHITECTURE.md

@@ -166,8 +166,12 @@ Key responsibilities by subsystem:
 - `agent/tools/*`: implements built-in tools, path/workdir guards, sandbox
   policy checks, MCP tool adaptation, Playwright artifact routing, and output
   limits.
-- `agent/compaction.js`: estimates context pressure and compacts long agent
-  conversations for providers that support the package's compaction loop.
+- `agent/compaction.js`: two pure helpers consumed by the pi bridge —
+  `resolveAgentCompactionPolicy` (derives the context-window compaction trigger +
+  tool-output payload limits from `agent_compaction_*` settings and the running
+  model) and `isLikelyContextTermination` (classifies a context-pressure error).
+  The bridge drives compaction itself via `AgentHarness.compact()` (proactive +
+  reactive recovery); the legacy in-loop `transformContext` manager was removed.
 - `agent/transcript.js`: builds bounded resume snapshots from prior provider
   events so a fallback or continuation can keep context.
 - `agent/approval.js`: provides host-driven human-in-the-loop tool approval
@@ -204,11 +208,52 @@ The host is responsible for:
 - resolving credentials and custom provider/model rows before provider calls
 - choosing model references, execution mode, effort, fallback chains, and
   runtime settings
-- persisting artifacts, compaction rows, raw logs, run rows, and UI-facing state
+- persisting artifacts, raw logs, run rows, and UI-facing state (the legacy
+  compaction-row hook is inert on the current pi bridge)
 - validating structured output against the host's domain contract
 - converting runtime failures into product workflow behavior
 - deciding when to retry, recover, continue, cancel, or ask for user input
 
+## Sessions, Follow-ups & Concurrency
+
+When `runtime.session.mode = "continuous"`, the harness keeps a conversation's
+provider session warm and serializes its turns through a per-conversation queue
+(`@mono-agent/agent-harness` `LiveSessionManager`). A message that arrives while
+a turn is in flight is **queued and answered on the warm session after the
+current turn finishes** (queue-after-turn) rather than rejected — this is what
+powers follow-up messages in chat channels. Different conversations run
+concurrently; an optional `concurrency.maxConcurrentRuns` bounds simultaneous
+model runs via admission control around the provider call (queued follow-ups
+hold no slot, so the bound never deadlocks against the queue). Note this bound is
+**per harness instance** — the app builds one harness per channel, so the limiter
+is per-channel, not a single global cap; with N enabled channels the effective
+ceiling is N× the configured value. Channels surface
+a user cancel through `responder.cancel(conversationId)`, which aborts the
+in-flight turn and clears that conversation's queue.
+
+**Honest per-provider session behavior** — parity is *behavioral* (every
+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, and context/window handling is delegated to the harness.
+There is **no** automatic in-loop summarization pass driven by this package, so
+runs report `context_compaction_applied: null` (unknown/unsupported) rather than
+asserting compaction ran.
+
+| Provider | Warm session | Resume across turns | Survives process restart |
+|---|---|---|---|
+| **pi** | Yes (pi `AgentHarness` + JSONL session repo) | session repo | **Yes** (only one) |
+| **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 |
+
+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.
+
 ## Essential Takeaway
 
 Think of `@mono-agent/agent-runtime` as the portable agent process engine

package/MIGRATION.md

@@ -0,0 +1,115 @@
+# `@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**.
+
+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.
+
+---
+
+## 1. Pi is now native-only (`pi-sdk.js` → `pi-native.js`)
+
+The hand-rolled Pi bridge that drove the low-level `Agent` was replaced by a
+bridge built on `@earendil-works/pi-agent-core`'s high-level `AgentHarness`. The
+registry resolves `pi` → the native bridge unconditionally; there is no
+`piEngine` flag.
+
+- **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` still
+  resolve via a **deprecated compatibility shim** that re-exports the native
+  equivalents (`generatePiResponse` → `generatePiNativeResponse`,
+  `piRuntimeBridge` → `piNativeRuntimeBridge`, `isContextLimitError`,
+  `normalizePiErrorMessage`, and the `pi*Backend` symbols). **Action:** migrate
+  deep imports to `./ai/providers/pi-native.js`; the shim may be removed in a
+  future major.
+
+## 2. Removed run options: `piReasoningSummary`, `piCodexTransport`
+
+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.)
+- `piCodexTransport` was doc-only and is removed. No replacement is needed.
+
+## 3. Pi context compaction: bridge-driven via AgentHarness.compact()
+
+`AgentHarness` has no automatic compaction, so the pi bridge drives it directly
+(the legacy low-level `transformContext` / `afterToolCall` hooks and
+`createAgentCompactionManager` were removed):
+
+- Before each turn the bridge estimates the running model's context usage and
+  calls `AgentHarness.compact()` when near the window (proactive). If a turn still
+  overflows the bridge compacts once and re-prompts (reactive recovery).
+- Runs report **`capabilitiesUsed.context_compaction_applied`** as `true` (a
+  compaction fired), `false` (enabled but not needed), or `null` (disabled via
+  `agent_compaction_enabled: false`). If you assert on this value, expect this
+  tristate on the Pi path.
+- The host **`onCompactionRecorded`** callback now **fires on each automatic
+  compaction** on the Pi path (previously inert).
+- The trigger window auto-tracks the model actually serving the request
+  (`harness.getModel()`) and self-corrects from any real ceiling stated in an
+  overflow error, so a wrong/default `context_window` no longer defeats it.
+  `resolveAgentCompactionPolicy` (`agent_compaction_*` settings) remains exported.
+
+## 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
+`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
+`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.
+
+## 5. Fallback router enforces requested native-subagent capability
+
+Pi advertises `supports_native_subagents: false`. The fallback router now infers
+a `supports_native_subagents` requirement when a run passes
+`options.nativeSubagents.teammates` (non-empty), the same way it already infers
+`structured_output` from `outputSchema`. A chain entry that cannot satisfy it
+(e.g. a Pi fallback behind a Claude primary that was handed native teammates) is
+**skipped** (`skipped_capability_mismatch`) rather than silently succeeding with
+`nativeSubagentsUsed: []`. **Action:** if you configure fallback chains for
+native-subagent runs, ensure at least one entry supports native subagents, or the
+run reports exhausted instead of degrading silently.
+
+## 6. Diagnostics & internal behavior changes (no API change)
+
+- **Pi multimodal**: image inputs are delivered to the model as image content
+  blocks (internal fix; affects behavior, not the call shape).
+- **Tool-output limits**: settings-driven clamps (`agent_tool_text_limit_chars`,
+  `agent_search_result_limit`, `toolPayloadMaxBytes`, …) are honored again on the
+  Pi path (built-ins + MCP). The 256 KB tool-payload ceiling is unchanged.
+- **WebFetch** retries transient network errors (timeout / ECONNRESET / 5xx)
+  in-tool with backoff before returning an error.
+- **Claude CLI**: the temporary `mcp.json` written for a CLI run is now created
+  with `0600` (owner-only) permissions.
+- Pi session lifecycle is hardened: aborts during setup are honored before the
+  provider call, fresh durable sessions are deleted on setup/abort failure, and
+  resumed sessions roll back to their pre-turn leaf on host-side (outer-catch)
+  failures. These are correctness fixes with no API surface change.
+
+---
+
+## 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.

package/README.md

@@ -42,10 +42,12 @@ Generic agent runtime that supports four backends out of the box:
 - **Pi SDK** (`@earendil-works/pi-agent-core`, used for OpenAI / Codex / Gemini / OpenRouter / Ollama / etc. via Pi providers)
 - **Codex CLI** (the `codex` app-server)
 
-Hosts wire in their own pricing, persistence, credential, and compaction-recording callbacks. The runtime returns raw text + raw structured output; hosts that want a domain-specific contract parse it on their end.
+Hosts wire in their own pricing, persistence, and credential callbacks (plus a legacy compaction-recording hook that is inert on the current pi bridge — 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.
+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
 
@@ -89,7 +91,7 @@ console.log(result.text);
 `@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:
 
 - **Vercel AI SDK** — best when you're building a chat / generative-UI experience inside a React or Next.js app. `useChat`, `useCompletion`, streaming server components, and edge-runtime compatibility are their strengths. Their provider list is curated (Anthropic, OpenAI, Google, etc., via `@ai-sdk/*` packages); there's no Pi gateway, no Claude Code CLI, no Codex CLI app-server, and no per-call provider fallback. If you're rendering a streaming chat into a browser, use them. If you're orchestrating multi-turn autonomous work that must survive a rate-limited primary provider, use us.
-- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We *wrap* it as one of our four backends and add context compaction, transcript-resume across provider drops, a 22-kind failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
+- **Claude Agent SDK** (`@anthropic-ai/claude-agent-sdk`) — first-party Anthropic SDK. Tight integration with Claude features (canUseTool, sub-agents, hooks, MCP). We *wrap* it as one of our four backends and add transcript-resume across provider drops, a 22-kind failure taxonomy, a tool-bloat guard with artifact persistence, and a provider fallback router. Context/window handling stays with the provider — the runtime does not run its own in-loop summarization pass. Reach for the bare Anthropic SDK when you only ever talk to Claude and don't need cross-provider portability or resume.
 - **Mastra** — a workflow engine + memory + RAG stack. Different category: it's the layer *above* a runtime. You can layer Mastra workflows on top of `@mono-agent/agent-runtime` if you want both.
 - **OpenAI Agents SDK** — first-party OpenAI SDK. Same trade-off as the Claude Agent SDK: tight integration with OpenAI, no other providers. Pi providers in our runtime cover OpenAI plus a dozen others through a single API.
 - **LangChain.js** — kitchen sink with deep abstraction stacks. We're deliberately lean; if you want chains, agents, vector stores, and parsers under one umbrella, LangChain is built for that. If you want a focused runtime kernel, use us.
@@ -109,7 +111,7 @@ console.log(result.text);
 | Multi-provider portability | ✓ (4 backends, 15+ providers) | partial | ✗ |
 | CLI providers (claude/codex binaries) | ✓ | ✗ | ✗ |
 | Provider fallback on rate limit / overload | ✓ (`createRouterRuntime`) | ✗ | ✗ |
-| Aggressive context compaction with summarization | ✓ | ✗ | partial |
+| Context handling delegated to the provider (no host auto-summarization) | ✓ | ✓ | ✓ |
 | Transcript-tail resume after provider drops | ✓ | ✗ | ✗ |
 | Tool-output bloat guard + artifact persistence | ✓ | ✗ | ✗ |
 | MCP transports out of the box (stdio/SSE/HTTP) | ✓ | partial | ✓ |
@@ -142,7 +144,9 @@ createRuntime({
   resolveCustomPricing,    // (parsed) => NormalizedPricing | null
   resolvePiApiKey,         // async (provider) => string | undefined
   persistArtifact,         // ({ filename, buffer, toolName, toolUseId }) => path | null
-  onCompactionRecorded,    // (compactionRow) => void
+  onCompactionRecorded,    // (compactionRow) => void — fired when the pi bridge
+                           // runs an automatic compaction (proactive or reactive
+                           // recovery) via AgentHarness.compact()
 
   // -- tool runtime context (process-level config for the tool kernel) --
   workspace,               // primary allowed root for path-based tools
@@ -228,7 +232,6 @@ Per-call options (a non-exhaustive selection):
 | `runId` | `string` | Tag this run for downstream callbacks (e.g. `onCompactionRecorded`). |
 | `providerSessionId` | `string` | Resume a prior provider session. |
 | `runArtifactDir` | `string` | Used by some providers as the Playwright MCP filename target. |
-| `piCodexTransport` | `string` | Forwarded to Pi when running OpenAI Codex models. |
 | `codexAppServerCommand` | `string` | Override the Codex CLI binary. |
 | `codexAppServerArgs` | `string[]` | Override the Codex CLI arguments. |
 
@@ -405,7 +408,20 @@ Hosts that don't supply `persistArtifact` get the truncation summary but no on-d
 
 ## Context compaction
 
-`@mono-agent/agent-runtime/agent/compaction.js` provides `createAgentCompactionManager(...)` which the Pi SDK provider invokes automatically. Configure via the agent's settings (`agent_compaction_*` keys). When a compaction completes, the kernel hands a structured row to your `onCompactionRecorded(record)` callback so the host can persist it however it likes.
+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
+running model's context usage and calls `AgentHarness.compact()` when near the window
+(proactive), and if a turn still overflows it compacts once and re-prompts (reactive
+recovery). The context window auto-tracks the model actually serving the request
+(`harness.getModel()`), self-correcting from any real ceiling stated in an overflow error.
+Runs report `context_compaction_applied: true` (fired), `false` (enabled but not needed),
+or `null` (disabled). The other backends manage their windows per their own behavior.
+(`docs/feature-registry.md` is the source of truth for this row.)
+
+`resolveAgentCompactionPolicy(...)` (the `agent_compaction_*` settings: trigger ratio,
+keep-recent, enable/disable) and the `onCompactionRecorded(record)` host callback (fired
+on each automatic compaction) are exported from
+`@mono-agent/agent-runtime/agent/compaction.js` and consumed by the pi bridge.
 
 ## Advanced exports
 
@@ -414,7 +430,7 @@ The package exposes its inner pieces via subpath imports:
 ```js
 import { resolveRuntimeBridge, listRuntimeBridges, runtimeCapabilities } from "@mono-agent/agent-runtime/ai/runtime/registry.js";
 import { generateClaudeResponse } from "@mono-agent/agent-runtime/ai/providers/claude-sdk.js";
-import { createAgentCompactionManager, estimateFirstTurnInput } from "@mono-agent/agent-runtime/agent/compaction.js";
+import { resolveAgentCompactionPolicy, isLikelyContextTermination } from "@mono-agent/agent-runtime/agent/compaction.js";
 import { configureToolRuntime, readToolRuntime } from "@mono-agent/agent-runtime/agent/tools/shared/runtime-context.js";
 // ...
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agent runtime supporting Claude SDK, Claude CLI, Codex CLI, and PI SDK out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -25,6 +25,7 @@
     "src/**/*.js",
     "!src/__tests__/**",
     "ARCHITECTURE.md",
+    "MIGRATION.md",
     "README.md",
     "LICENSE"
   ],
@@ -35,7 +36,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.1.0",
     "@earendil-works/pi-agent-core": "^0.79.1",
     "@earendil-works/pi-ai": "^0.79.1",
-    "@mono-agent/sandbox": "0.3.0",
+    "@mono-agent/sandbox": "0.4.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@opencode-ai/sdk": "^1.15.13",
     "zod": "^4.3.6"