@mono-agent/agent-runtime 0.15.2 → 0.15.4

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
@@ -650,8 +657,11 @@ Per-call options (a non-exhaustive selection):
 | `cwd` | `string` | Working directory for the agent's tools. |
 | `allowedTools` | `string[]` | Built-in tool allowlist. Default: all. |
 | `disallowedTools` | `string[]` | Block list. |
-| `mcpServers` | `Record<string, McpServerConfig>` | Configured MCP servers (stdio / sse / http). |
+| `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
@@ -760,6 +786,17 @@ truncation is explicitly desired; omitting it is not a separate hidden limit.
 The standard 256 KiB tool-payload guard still applies to oversized tool results.
 
 Override or extend the tool surface by passing `mcpServers` for MCP-backed tools.
+On direct Codex normal runs, each valid server that survives translation into
+the app-server config is the authorization boundary for the tools it exposes.
+The bridge accepts Codex's synthesized `mcp_tool_call` elicitation for that exact
+server without persisting an approval. Inherited or otherwise unconfigured
+server names, genuine downstream MCP elicitations, and other app-server requests
+remain fail-closed.
+
+This also applies under direct Codex `permissionMode: "plan"`: the read-only
+sandbox constrains Codex-owned filesystem and command execution, but a declared
+MCP tool can still change state managed by its server. Do not declare a server
+whose complete tool surface is not authorized for the run.
 
 ### Structured output
 
@@ -783,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 },
   ],
@@ -797,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.
@@ -814,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"`).
 
@@ -1004,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.2",
+  "version": "0.15.4",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, and Pi SDK bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -136,9 +136,13 @@
     "@earendil-works/pi-agent-core": "0.80.6",
     "@earendil-works/pi-ai": "0.80.6",
     "@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": {