@mono-agent/agent-runtime 0.15.3 → 0.16.0

package/MIGRATION.md

@@ -42,8 +42,8 @@ the configuration schema.
   switch to `listPiBuiltinModels`, `getPiBuiltinModel`,
   `reasoningLevelsForPiModel`, `resolvePiOAuthApiKey`, and `loginPiOAuth` from
   `@mono-agent/agent-runtime/ai`. The runtime keeps Pi AI and Pi Agent Core
-  exact-pinned at `0.80.6`; the façade returns cloned model and credential
-  snapshots rather than exposing mutable upstream registries.
+  exact-pinned at `0.83.0`; the façade returns cloned model and credential
+  snapshots rather than exposing upstream provider objects.
 - **Claude test seam:** downstream tests should pass
   `RuntimeRunOptions.claudeAgentQuery` instead of mocking
   `@anthropic-ai/claude-agent-sdk` by package name. Normal runs omit this option
@@ -63,12 +63,27 @@ the configuration schema.
   authoritative and the runtime emits a bounded
   `live_input_callback_failed` warning.
 
-## 0.15.x baseline
+## 0.16.x baseline
 
 This is the current published baseline for the detailed pre-1.0 reference
-below. It includes the explicit exports map, the five-bridge lazy registry,
-typed runtime policies, runtime-owned provider dependencies, and the
-public-surface cleanup described in this guide.
+below. It carries the whole 0.15.x contract forward and adds:
+
+- `skills` and `skillsRoot` on the run options. `skills` is the disclosed
+  `{name, description}` set for a run; a non-empty value makes `supports_skills`
+  a routing requirement, so a chain entry lacking it is skipped. `skillsRoot`
+  names the directory holding `<name>/SKILL.md` and is required alongside
+  `skills` for `ReadSkill` to exist. A subagent run now inherits both from its
+  parent unless a host-supplied `run` withholds them, so a child no longer has
+  to rediscover by trial and error what its parent could look up.
+- Provider failover detail reaches whoever is watching the run rather than being
+  flattened at the boundary.
+- Pi SDK 0.83.0.
+
+## 0.15.x
+
+- The explicit exports map, the five-bridge lazy registry, typed runtime
+  policies, runtime-owned provider dependencies, and the public-surface cleanup
+  described in this guide.
 
 ## 0.12.x
 
@@ -313,9 +328,22 @@ falls back to its own env vars, exactly as returning `undefined` from the old ho
 did). **No host action needed** — `resolvePiApiKey` behaves as before.
 
 Dependency bump: **`@earendil-works/pi-ai` and `@earendil-works/pi-agent-core` are
-now `0.80.6`** (the initial Pi 0.80 migration landed at `0.80.5`, from
-`^0.79.1`). Compaction is driven natively (section 3). The `0.80.6` refresh also
-preserves model-native `max` reasoning and Pi's request-wide pricing tiers.
+now `0.83.0`** (the initial Pi 0.80 migration landed at `0.80.5`, from
+`^0.79.1`, and ran at `0.80.6` until the 0.83 upgrade). Compaction is driven
+natively (section 3), and model-native `max` reasoning plus Pi's request-wide
+pricing tiers are preserved.
+
+The 0.83 upgrade carries two upstream removals, both absorbed inside the runtime
+so hosts need no action:
+
+- `@earendil-works/pi-ai/oauth` became a type-only entry point. The generic
+  registry (`getOAuthApiKey`, `getOAuthProvider`, `getOAuthProviders`) is gone,
+  and the per-provider flows are not importable. `src/ai/pi-oauth-compat.js`
+  rebuilds the same contracts over `provider.auth.oauth`, so `resolvePiApiKey`,
+  `resolvePiOAuthApiKey`, and `loginPiOAuth` keep their existing signatures and
+  behaviour, including the refresh-on-expiry trigger.
+- `AgentHarnessOptions.env` was removed in favour of a per-turn `toolContext`.
+  The runtime passes neither: it uses none of Pi's built-in file/shell tools.
 
 ### 11. Exports map: wildcards removed (explicit deep-path map)
 
@@ -366,7 +394,7 @@ a compatibility subpath.
 
 ## Version
 
-This guide describes the published `0.15.x` package contract. Keep
+This guide describes the published `0.16.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.
@@ -387,14 +415,14 @@ 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 Pi
-   dependency to exact `0.80.6` rather than a floating range. Do not restore the
+   dependency to exact `0.83.0` rather than a floating range. Do not restore the
    removed `pi-sdk.js` subpath.
 3. **Use the public Pi surfaces.** Run models through
    `generatePiNativeResponse` or the runtime registry. Use
    `listPiBuiltinModels`, `getPiBuiltinModel`,
    `reasoningLevelsForPiModel`, `resolvePiOAuthApiKey`, and `loginPiOAuth` for
-   catalog and OAuth integration. Those façades keep Pi mutable state and the
-   exact `0.80.6` compatibility pin inside the runtime. OAuth login adapters
+   catalog and OAuth integration. Those façades keep Pi provider objects and the
+   exact `0.83.0` compatibility pin 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

package/README.md

@@ -246,12 +246,19 @@ inferSkillsRoot
 
 ```text
 bashToolImpl
+bashToolRun
+createWebToolController
 editToolImpl
+execToolImpl
+execToolRun
 globToolImpl
 grepToolImpl
 isPathAllowed
 isWorkdirAllowed
 normalizeBashTimeoutMs
+normalizeProcessTimeoutMs
+performWebFetch
+performWebSearch
 readToolImpl
 resolveRgPath
 webFetchToolImpl
@@ -652,6 +659,9 @@ Per-call options (a non-exhaustive selection):
 | `disallowedTools` | `string[]` | Block list. |
 | `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http); on direct Codex, each forwarded server authorizes its own tool calls. |
 | `sandboxPolicy` | `SandboxPolicy` | Optional fail-closed sandbox policy for built-in tools and stdio MCP process startup. |
+| `webSearchConfig` | `{ backend?, endpoint? }` | Run-scoped local SearXNG/keyless WebSearch backend selection. |
+| `webFetchConfig` | `{ render?, browserCommand? }` | Run-scoped static extraction and optional isolated browser-render policy. |
+| `piToolExecutionMode` | `"safe-parallel" \| "sequential"` | Pi built-in scheduling. Safe parallelism is the default; stateful/mutating and MCP tools stay sequential. |
 | `maxTurns` | `number` | Hard cap on agent turns. |
 | `outputSchema` | `JSONSchema` | Requests structured JSON on capable bridges; see “Structured output” below for bridge-specific return behavior. |
 | `abortSignal` | `AbortSignal` | Cancel the run. |
@@ -744,13 +754,29 @@ Successful provider requests may also emit exact context telemetry through
 
 ### 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:
+The agent kernel's managed tools are `Read`, `Write`, `Edit`, `Glob`, `Grep`,
+`Exec`, `Bash`, `NodeRepl`, `WebFetch`, and `WebSearch`.
+`Exec({ executable, args })` invokes one executable directly; `Bash` is the
+clean non-interactive shell surface for pipelines, redirection, and other shell
+syntax. Both preserve bounded partial stdout/stderr and structured exit,
+timeout, abort, signal, and truncation metadata. `NodeRepl({ code })` is backed
+by one lazily started Node.js REPL child per run. You select them via
+`allowedTools`. Tool implementations honor:
 
 - `cwd` (required for path-based tools)
 - The runtime context's `workspace` / `repoRoot` allow-list (paths outside both, plus `/tmp` and `process.cwd()`, are rejected)
 - Output truncation with optional artifact persistence (`{toolArtifactDir}/tool-output/{runId}/...` when `toolArtifactDir` is configured)
 
-`NodeRepl` uses Node's default `node:repl` evaluator, so variables, `_`, `_error`, and loaded modules persist across calls in the same run. It supports multiline input and top-level `await`, resolves workspace-installed packages, and is closed with the run. Its child is prepared through the same sandbox seam as `Bash`; abort, the fixed 120-second timeout, child exit, or hard output overflow resets the session. It deliberately has no session ids, persistent history, terminal commands, or package-install surface.
+`NodeRepl` uses Node's default `node:repl` evaluator, so variables, `_`, `_error`, and loaded modules persist across calls in the same run. It supports multiline input and top-level `await`, resolves workspace-installed packages, and is closed with the run. Its child is prepared through the same sandbox seam as `Exec`/`Bash` and communicates through token-authenticated, length-prefixed JSON frames on ordinary stdin/stdout; abort, the fixed 120-second timeout, child exit, or hard output overflow resets the session. It deliberately has no session ids, persistent history, terminal commands, or package-install surface.
+
+`WebSearch` uses a configured loopback SearXNG endpoint and/or deterministic
+public fallbacks that require no credentials. It canonicalizes and deduplicates
+results, then fuses multiple query rankings. `WebFetch` extracts HTML, JSON,
+feeds, PDFs, and text locally with
+bounded redirects, bodies, headers, and retries. Config can opt into isolated
+`agent-browser` rendering for sparse client-rendered HTML. One ephemeral
+controller per run deduplicates identical calls and closes every browser
+namespace at run end.
 
 Pi runs with selected skills also expose `ReadSkill`. It returns the complete
 skill instructions by default, including content beyond the former
@@ -794,8 +820,10 @@ import { createRouterRuntime } from "@mono-agent/agent-runtime";
 const router = createRouterRuntime({
   host: { /* same shape as createRuntime */ },
   routeSafety: "per-route-native",
+  // Backoff shape for same-model retries; per-route counts live on `attempts`.
+  retry: { backoffMs: 1000, maxBackoffMs: 15000 },
   chain: [
-    { model: { sdk: "claude", model: "claude-sonnet-5" }, effort: "high" },
+    { model: { sdk: "claude", model: "claude-sonnet-5" }, effort: "high", attempts: 2 },
     { model: { sdk: "codex", model: "gpt-5.6-sol" }, effort: "xhigh" },
     { model: { sdk: "pi", provider: "ollama", model: "gemma4:31b" }, effort: null },
   ],
@@ -808,8 +836,11 @@ console.log(result.failoverHistory, result.routeSafetyHistory);
 Behaviour:
 
 - Successful run on entry N → returns the result with `failoverHistory` set to attempts 0..N-1.
-- Retryable provider failure → emits `provider_failover_started`, builds a transcript snapshot, and retries on the next entry.
-- Context-window failure after bridge compaction recovery → preserves `failureKind: "context_limit"` in `failoverHistory` and tries the next entry; quota/output/max-turn `usage_limit` remains terminal.
+- Retryable provider failure → retries the SAME entry while it has `attempts` left (emitting `provider_retry_started` after a doubling backoff), then emits `provider_failover_started`, builds a transcript snapshot, and advances to the next entry. `attempts` defaults to `1` per entry, so the kernel is single-shot unless a host opts in — `@mono-agent/config` supplies the product default of 2 on the primary.
+- Same-model retries fire only for transient subkinds (`overloaded`, `rate_limited`, `timeout`, `network`, `server_error`, `retryable_request`, terminated streams). A retry drops the route's provider session, since the failed attempt already appended to it, and appends its own `failoverHistory` entry carrying `retryIndex`.
+- A retry is *not* a failover: `provider_route_safety` and `provider_failover_started` are emitted once per entry, and `provider_failover_completed` only fires when a genuinely different model answered.
+- This is a whole-logical-turn retry sitting strictly outside the provider bridges' own transport retries. On a `pi` route, `attempts: 2` combined with pi's default `maxRetries: 2` means up to six provider stream starts.
+- Context-window failure after bridge compaction recovery → never retries the same entry (a second identical request against the same window is a guaranteed second failure); preserves `failureKind: "context_limit"` in `failoverHistory` and tries the next entry; quota/output/max-turn `usage_limit` remains terminal.
 - Provider auth failure → retries the next chain entry and preserves `failureKind: "provider_auth"` in `failoverHistory` for the failed attempt.
 - Malformed request/config/billing-type non-retryable failure → returns immediately with `failoverHistory` containing the one attempt.
 - Cancellation → returns immediately.
@@ -825,7 +856,11 @@ Behaviour:
   inputs, while request-scoped overrides remain on that exact run. A runtime
   that cannot accept this projection fails closed as `safety_unavailable`.
 - Attempt-resolver failures are sanitized to `safety_unavailable`; resolver
-  credentials/options never enter result telemetry.
+  credentials/options never enter result telemetry, and they advance to the next
+  entry rather than consuming the route's remaining `attempts`.
+- `resolveAttempt` runs once per attempt — including every same-model retry — and
+  receives `{ attemptIndex, retryIndex }`, where `attemptIndex` stays the chain
+  index. Its `cleanup` runs after each attempt.
 
 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"`).
 
@@ -1015,6 +1050,8 @@ runtime fails closed.
   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.
+- [Local-first web research](https://mono-agent-docs.vercel.app/tools/web-research/)
+  documents SearXNG, extraction, retry, browser isolation, and sandbox policy.
 - [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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.15.3",
+  "version": "0.16.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",
@@ -133,12 +133,16 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.206",
     "@anthropic-ai/sdk": "^0.110.0",
-    "@earendil-works/pi-agent-core": "0.80.6",
-    "@earendil-works/pi-ai": "0.80.6",
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mozilla/readability": "0.6.0",
     "@opencode-ai/sdk": "^1.15.13",
     "@vscode/ripgrep": "1.18.0",
     "cross-spawn": "^7.0.6",
+    "defuddle": "0.19.2",
+    "linkedom": "0.18.13",
+    "unpdf": "1.8.0",
     "zod": "^4.3.6"
   },
   "scripts": {