@mono-agent/agent-app 0.15.3 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-app",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "Config-first mono-agent host: builds a responder and starts every configured communication channel and traceability from one mono-agent.config.json.",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -35,22 +35,22 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@earendil-works/pi-ai": "0.80.6",
+    "@earendil-works/pi-ai": "0.83.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@mono-agent/agent-contracts": "0.15.3",
-    "@mono-agent/agent-harness": "0.15.3",
-    "@mono-agent/config": "0.15.3",
-    "@mono-agent/cron-adapter": "0.15.3",
-    "@mono-agent/operator-adapter": "0.15.3",
-    "@mono-agent/memory": "0.15.3",
-    "@mono-agent/observability": "0.15.3",
-    "@mono-agent/openai-api-adapter": "0.15.3",
-    "@mono-agent/runtime-adapter": "0.15.3",
-    "@mono-agent/slack-adapter": "0.15.3",
-    "@mono-agent/telegram-adapter": "0.15.3",
-    "@mono-agent/tui": "0.15.3",
-    "@mono-agent/web": "0.15.3",
-    "@mono-agent/webhook-adapter": "0.15.3",
+    "@mono-agent/agent-contracts": "0.16.0",
+    "@mono-agent/agent-harness": "0.16.0",
+    "@mono-agent/config": "0.16.0",
+    "@mono-agent/cron-adapter": "0.16.0",
+    "@mono-agent/operator-adapter": "0.16.0",
+    "@mono-agent/memory": "0.16.0",
+    "@mono-agent/observability": "0.16.0",
+    "@mono-agent/openai-api-adapter": "0.16.0",
+    "@mono-agent/runtime-adapter": "0.16.0",
+    "@mono-agent/slack-adapter": "0.16.0",
+    "@mono-agent/telegram-adapter": "0.16.0",
+    "@mono-agent/tui": "0.16.0",
+    "@mono-agent/web": "0.16.0",
+    "@mono-agent/webhook-adapter": "0.16.0",
     "undici": "8.7.0",
     "zod": "^4.4.3"
   },

package/schema/mono-agent.config.schema.json

@@ -89,11 +89,52 @@
                   "max",
                   "ultra"
                 ]
+              },
+              "attempts": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 10
               }
             }
           },
           "default": []
         },
+        "retry": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "primaryAttempts": {
+              "description": "Total attempts on runtime.model including the first, before the chain advances. Retries fire only for transient provider failures (overloaded, rate-limited, timeout, network, 5xx); context overflow and bad credentials advance immediately. Set 1 to disable.",
+              "examples": [
+                3
+              ],
+              "type": "integer",
+              "default": 2,
+              "minimum": 1,
+              "maximum": 10
+            },
+            "backoffMs": {
+              "description": "Delay before the first same-model retry. Doubles on each further retry, capped by runtime.retry.maxBackoffMs.",
+              "examples": [
+                2000
+              ],
+              "type": "integer",
+              "default": 1000,
+              "minimum": 0,
+              "maximum": 60000
+            },
+            "maxBackoffMs": {
+              "description": "Ceiling for the doubling same-model retry delay.",
+              "examples": [
+                30000
+              ],
+              "type": "integer",
+              "default": 15000,
+              "minimum": 0,
+              "maximum": 300000
+            }
+          }
+        },
         "routeSafety": {
           "description": "Uniform preserves one shared safety contract; per-route-native uses and reports each provider's explicit contract.",
           "examples": [
@@ -279,6 +320,150 @@
         "model"
       ]
     },
+    "subagents": {
+      "description": "Subagent profiles the Agent tool can deploy, plus its caps. Disabled unless enabled is true, in which case Agent must also appear in tools.allowedTools. Each definition needs exactly one of prompt or promptPath; omitted allowedTools means a read-only default set, and the \"*\" wildcard is rejected. The agent may also author a specialized subagent at call time unless inline.enabled is false; inline.allowedTools caps what an authored subagent may request, defaulting to the parent agent's own built-ins.",
+      "examples": [
+        {
+          "enabled": true,
+          "maxConcurrent": 5,
+          "definitions": [
+            {
+              "name": "researcher",
+              "description": "Reads code and docs to answer a factual question about the codebase. Read-only.",
+              "prompt": "You are a codebase researcher. Answer with file:line citations. Never modify files.",
+              "allowedTools": [
+                "Read",
+                "Glob",
+                "Grep"
+              ]
+            }
+          ]
+        }
+      ],
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "maxConcurrent": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        },
+        "maxPerTurn": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 200
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 3600000
+        },
+        "maxTurns": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 200
+        },
+        "definitions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "name",
+              "description"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              },
+              "description": {
+                "type": "string",
+                "minLength": 1
+              },
+              "prompt": {
+                "type": "string",
+                "minLength": 1
+              },
+              "promptPath": {
+                "type": "string",
+                "minLength": 1
+              },
+              "model": {
+                "type": "string",
+                "minLength": 1
+              },
+              "effort": {
+                "type": "string",
+                "enum": [
+                  "none",
+                  "minimal",
+                  "low",
+                  "medium",
+                  "high",
+                  "xhigh",
+                  "max",
+                  "ultra"
+                ]
+              },
+              "allowedTools": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "disallowedTools": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "mcpServers": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "maxTurns": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 200
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "minimum": 1000,
+                "maximum": 3600000
+              }
+            }
+          }
+        },
+        "inline": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "allowedTools": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      },
+      "default": {
+        "enabled": false
+      }
+    },
     "concurrency": {
       "type": "object",
       "additionalProperties": false,
@@ -906,6 +1091,64 @@
           ],
           "type": "integer",
           "default": 2700000
+        },
+        "web": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "search": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "backend": {
+                  "description": "WebSearch backend: auto tries a configured local SearXNG endpoint then keyless fallbacks; searxng is strict; keyless skips SearXNG.",
+                  "examples": [
+                    "auto"
+                  ],
+                  "type": "string",
+                  "default": "auto",
+                  "enum": [
+                    "auto",
+                    "searxng",
+                    "keyless"
+                  ]
+                },
+                "endpoint": {
+                  "description": "Optional unauthenticated loopback HTTP SearXNG base URL. Remote HTTPS, credentials, query strings, and fragments are rejected.",
+                  "examples": [
+                    "http://127.0.0.1:8088"
+                  ],
+                  "type": "string"
+                }
+              }
+            },
+            "fetch": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "render": {
+                  "description": "Browser-render capability for sparse JavaScript pages. never forces every call to static extraction; auto permits an isolated agent-browser session when needed.",
+                  "examples": [
+                    "never"
+                  ],
+                  "type": "string",
+                  "default": "never",
+                  "enum": [
+                    "never",
+                    "auto"
+                  ]
+                },
+                "browserCommand": {
+                  "description": "Direct executable name or path for agent-browser; shell fragments are not evaluated.",
+                  "examples": [
+                    "agent-browser"
+                  ],
+                  "type": "string",
+                  "default": "agent-browser"
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -2081,6 +2324,60 @@
           ],
           "type": "boolean"
         },
+        "resolveUserNames": {
+          "description": "Resolves the speaker's display name and handle via `users.info` so the agent knows who is talking. Requires the `users:read` scope; a missing scope degrades to an unnamed speaker rather than failing turns.",
+          "examples": [
+            true
+          ],
+          "type": "boolean",
+          "default": true
+        },
+        "threadContext": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "description": "Sends what was said in the conversation before the agent was triggered as untrusted background context. Reads the thread for an in-thread trigger and recent channel history otherwise; needs a `*:history` scope.",
+              "examples": [
+                true
+              ],
+              "type": "boolean",
+              "default": true
+            },
+            "maxMessages": {
+              "description": "Messages of context sent per turn, newest kept. `0` disables the read. Capped at the harness's own 30-message bound.",
+              "examples": [
+                15
+              ],
+              "type": "integer",
+              "default": 15
+            },
+            "requestLimit": {
+              "description": "Objects requested from Slack per read. Slack caps this at 15 for non-Marketplace apps; internal apps can raise it.",
+              "examples": [
+                15
+              ],
+              "type": "integer",
+              "default": 15
+            },
+            "timeoutMs": {
+              "description": "Budget for the whole context phase, including name resolution. Exceeding it submits the turn with less context rather than delaying it. `0` bounds the phase only by the turn itself.",
+              "examples": [
+                4000
+              ],
+              "type": "integer",
+              "default": 4000
+            },
+            "includeBotMessages": {
+              "description": "Include other apps' messages (a CI or alert bot) labelled as bots. The agent's own posts are always excluded.",
+              "examples": [
+                true
+              ],
+              "type": "boolean",
+              "default": true
+            }
+          }
+        },
         "heartbeatIntervalMs": {
           "description": "Configures heartbeatIntervalMs for the slack section.",
           "examples": [

package/skills/mono-agent-composer/references/config-blueprint.md

@@ -152,11 +152,21 @@ new agent.
   "tools": {
     "allowedTools": ["*"],                 // omit or include "*" = all tools; ["Read","Bash"] = just those; [] = none (chat-only)
     "disallowedTools": ["Bash"],           // deny wins even under allow-all; the escape hatch to subtract one tool
-    "mcpConfigPath": "./mcp.json"          // stdio/sse/http servers; inlined for SDK runtimes
+    "mcpConfigPath": "./mcp.json",         // stdio/sse/http servers; inlined for SDK runtimes
+    "web": {
+      "search": {
+        "backend": "auto",                 // auto | searxng (strict) | keyless
+        "endpoint": "http://127.0.0.1:8088" // optional unauthenticated loopback HTTP SearXNG base URL
+      },
+      "fetch": {
+        "render": "never",                 // never disables browser capability; auto is static-first
+        "browserCommand": "agent-browser"  // direct executable name/path
+      }
+    }
   },
 
-  // NodeRepl shares state only inside one run and uses the same sandbox policy
-  // as Bash.
+  // Exec is direct argv; use Bash only for shell syntax. NodeRepl shares state
+  // only inside one run. All three use the same sandbox policy.
 
   // Human-in-the-loop bridge: structured blocking AskUser plus
   // run-scoped project-MCP progress. It auto-starts when either ask tool is

package/skills/mono-agent-composer/references/discovery-questions.md

@@ -79,7 +79,18 @@ Plus, independently: MCP servers from an mcp.json config file?
 
 Fills: `tools.allowedTools`, `tools.disallowedTools` (denylist wins, even under allow-all), `tools.mcpConfigPath`. The default is allow-all (`["*"]`) — write that unless the user asks to narrow. Under allow-all the adapter-derived send tools (`SlackSendMessage` / `TelegramSendMessage` / …) are auto-available once the channel is enabled; only a **specific** allowlist needs their exact names added. Valid enabled Slack/Telegram adapter config and destination allowlists are required either way. On the pi-native runtime `disallowedTools` does not filter external MCP-server tools — to withhold one, don't declare its server.
 
-Offer the `NodeRepl` built-in when the user wants run-scoped JavaScript evaluation. It executes with the same sandbox authority as `Bash`.
+For Pi process work, prefer the `Exec` built-in for one executable plus literal
+argv and offer `Bash` only when shell syntax is required. Offer `NodeRepl` when
+the user wants run-scoped JavaScript evaluation. All three execute with the same
+sandbox authority.
+
+If the agent needs public-web research, ask whether it should use the keyless
+default, a loopback SearXNG companion, or strict SearXNG-only discovery. Fill
+`tools.web.search.backend` and optional `tools.web.search.endpoint`. Keep
+`tools.web.fetch.render: "never"` unless the user explicitly needs
+JavaScript-heavy pages and has `agent-browser` 0.33.1 or newer; then select
+`"auto"` plus the direct `browserCommand`. Explain that SearXNG is local
+infrastructure but both search and fetch still generate public network traffic.
 
 ## 6. Memory Strategy
 

package/skills/mono-agent-composer/references/feature-coverage.md

@@ -7,6 +7,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Capability | Coverage | Where | Registry config ids |
 | --- | --- | --- | --- |
 | Model backends: claude (sdk/cli), codex (cli direct fallback), pi sdk providers (OpenAI, OpenAI-Codex preferred when Pi auth exists, Copilot, OpenRouter, OpenCode-through-Pi, Ollama, LM Studio, ...), plus hand-authored opencode runtime refs (cli, `opencode:<provider>:<model>` via the OpenCode server) | config | `runtime.model` | `runtime.multi-backend` |
+| Subagent delegation via the Agent tool | config | pi runtime only. Requires BOTH `subagents.enabled: true` and `Agent` in `tools.allowedTools`. Each definition needs exactly one of `prompt` or `promptPath`; omitted `allowedTools` means a read-only default set and `"*"` is rejected. Subagents are capped by `maxConcurrent` (5) and `maxPerTurn` (20), never receive Agent/AskUser/channel-send tools, and cannot spawn subagents | `runtime.subagents` |
+| Same-model retries before failover | config | `runtime.retry.primaryAttempts` (default 2) gives the primary a second attempt before the chain advances; per-route `runtime.fallbacks[].attempts` opts a backup in. Only transient provider failures retry — context overflow and bad credentials still advance. Set `primaryAttempts` to 1 to disable | `runtime.retry` |
 | Backup models on retryable provider failure | config | New configs use `runtime.fallbacks[]` with optional per-route effort. Legacy `runtime.fallbackModels` / `MONO_AGENT_FALLBACK_MODELS` remain compatibility inputs with no removal deadline; do not emit them for new agents | `runtime.fallback-models` |
 | Route-safety contract for primary and fallback models | config | `runtime.routeSafety`: `uniform` (default) or `per-route-native` | `runtime.route-safety` |
 | Execution mode (sdk/cli), effort, max turns, workspace | config + cli | `runtime.executionMode`, `runtime.effort` (`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max` / `ultra`; `mono-agent init --effort <level>`). Reasoning-capable `pi:*` maps `ultra` to LOW; Pi without reasoning uses OFF. Direct `codex:*` forwards `ultra` unchanged. Mono-agent rejects `ultra` on its Claude SDK route because the pinned SDK public contract ends at `max` (the SDK JavaScript itself forwards the value). The Claude CLI route passes `--effort ultra`, but both tested Claude Code binaries (SDK-bundled 2.1.206 and local 2.1.210) warn that it is unknown, ignore it, and use default effort. Direct OpenCode rejects explicit effort. Ranking above `max` only prevents keyword downgrade. `runtime.maxTurns`, `runtime.workspace` | `runtime.execution-modes`, `runtime.effort`, `runtime.max-turns`, `runtime.workspace` |
@@ -51,7 +53,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Capability | Coverage | Where | Registry config ids |
 | --- | --- | --- | --- |
 | Allow-all tool policy (omitted / `["*"]` = all tools; `[]` = none) | config | default `tools.allowedTools`; the harness no-policy safety net is `failClosedToolPolicy()` | `tool-policy.allow-all` |
-| Built-in tool allow/deny lists (deny wins, even under allow-all; pi doesn't deny external MCP tools) | config | `tools.allowedTools`, `tools.disallowedTools`; managed built-ins are Read/Write/Edit/Glob/Grep/Bash/NodeRepl/WebFetch/WebSearch | `tool-policy.allowlist`, `tool-policy.denylist`, `runtime.builtin-tools` |
+| Built-in tool allow/deny lists (deny wins, even under allow-all; pi doesn't deny external MCP tools) | config | `tools.allowedTools`, `tools.disallowedTools`; managed built-ins are Read/Write/Edit/Glob/Grep/Exec/Bash/NodeRepl/WebFetch/WebSearch | `tool-policy.allowlist`, `tool-policy.denylist`, `runtime.builtin-tools` |
+| Local-first public-web research | config + auto | `tools.web.search.{backend,endpoint}` selects strict/first-choice loopback SearXNG or public no-credentials fallbacks; `tools.web.fetch.{render,browserCommand}` keeps static extraction as the default and optionally enables isolated agent-browser rendering; transient-fetch retry behavior is automatic rather than config-bearing | `runtime.web-research` |
 | MCP servers (stdio/sse/http) from a JSON file | config | `tools.mcpConfigPath` | `tool-policy.mcp-servers` |
 | Durable origin-bound continuations for trusted stdio/loopback-HTTP MCP services | config + auto | `tools.continuationServers` + `continuations.*`; interactive claims pin a bounded immutable origin snapshot before commit, exact rollover buckets are preserved, v3 state is restart-safe, and unavailable/legacy snapshots use a fixed zero-model fallback | `agent-app.durable-continuations` |
 | Adapter-derived send tools for enabled Slack/Telegram adapters | config | auto-available under allow-all once the channel is enabled; a **specific** `tools.allowedTools` must include `SlackSendMessage` / `TelegramSendMessage`; valid `slack.*` / `telegram.*` config and existing adapter allowlists provide credentials and destination bounds; confirmed message posts are idempotently recorded in destination history | `agent-app.adapter-send-tools` |
@@ -72,6 +75,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Telegram runtime/command/reaction/button/file interactivity | config + code | built-in per-chat `/model` and `/effort` use configured primary/fallback models (no Telegram config key); `telegram.commands[]`, `telegram.reactions`, `telegram.quietHours`; `AskUser`, non-blocking `TelegramSendMessage.reply_options`, and `TelegramSendFile` | `telegram.interactive` |
 | Telegram inbound audio transcription | config | `telegram.transcription.{endpoint,model,language,timeoutMs}`; opt-in OpenAI-compatible transcription endpoint for voice notes, audio files, and round-video attachments | `telegram.transcription` |
 | Slack (Socket Mode, channel allowlist, mention handling, native runtime controls) | config + code | `slack` section; built-in Block Kit controls use configured primary/fallback choices through DM-wide/thread-local `@agent /model` and `@agent /effort`, plus channel-wide workspace commands `/<bot>-model` and `/<bot>-effort` derived from `auth.test.user` (Slack app registration + `commands` scope; no mono-agent config key) | `slack.socket-mode` |
+| Slack speaker names (who sent each turn) | config | `slack.resolveUserNames` (default `true`) resolves the sender's display name and handle via `users.info`; requires the `users:read` bot scope; best-effort, so a missing scope leaves turns unnamed instead of failing them; the resolved name is durable (stored turn + memory label) | `slack.speaker-names` |
+| Slack thread/channel turn context (what was said before the agent was triggered) | config | `slack.threadContext.{enabled,maxMessages,requestLimit,timeoutMs,includeBotMessages}`, defaults `true`/`15`/`15`/`4000`/`true`; reads `conversations.replies` in a thread and `conversations.history` otherwise; requires `channels:history` / `groups:history` / `im:history` / `mpim:history`; one request per turn with a per-channel rate-limit breaker; best-effort, so a missing scope or rate limit sends no transcript instead of failing the turn | `slack.thread-context` |
 | Slack global/message shortcuts | config | `slack.shortcuts[]: {callbackId, prompt, channelId?, ackText?, threadReply?}`; JSON-only | `slack.shortcuts` |
 | Slack App Home actions | config | `slack.homeTab: {enabled?, headerText?, buttons?:[{actionId, label, prompt, channelId?, ackText?, threadReply?}]}`; `enabled` defaults to `false`, `buttons` defaults to `[]`; JSON-only | `slack.app-home` |
 | External channel plugins | config | `channels.plugins[]: { package, id?, label?, config? }`; package must export `createChannelDriver(options)` or a default driver factory | `channel.plugins` |

package/skills/mono-agent-composer/references/playbooks.md

@@ -175,7 +175,7 @@ const orchestrator = await createConfiguredAgentResponder({
 
 ## 9. Sandboxed code agent (loopback only, deny .env)
 **For:** a security team deploying an internal code assistant.
-**Goal:** read repos + run Bash or run-scoped NodeRepl inside the native srt sandbox with loopback-only network access and protected secrets.
+**Goal:** read repos + run direct Exec, shell-syntax Bash, or run-scoped NodeRepl inside the native srt sandbox with loopback-only network access and protected secrets.
 **Features:** `sandbox.mode`, `sandbox.network-policy`, `sandbox.filesystem-scopes`, `sandbox.fallback`, `tool-policy.allow-all`, `memory.journal`.
 
 ```json
@@ -186,7 +186,7 @@ const orchestrator = await createConfiguredAgentResponder({
 }
 ```
 **Steps:** `mono-agent init --memory journal` → leave tools at the allow-all default (`["*"]`); the **sandbox**, not an allowlist, is what constrains the code tools → `sandbox.mode native` + `network localhost` + deny-write defaults → keep `fallback: fail-closed` (do NOT set `unsafe-host-process`) → `validate` → `start`.
-**Smoke:** ask it to read a file, run Bash, then use NodeRepl twice to retain a variable and produce `42` (all work); next fetch an external URL or write `.env` (both blocked in the artifact). Keep every primary/fallback/trigger model on Pi; direct Codex, Claude, and direct OpenCode reject this mono-agent sandbox policy.
+**Smoke:** ask it to read a file, use Exec for one argv-safe command, run one Bash pipeline, then use NodeRepl twice to retain a variable and produce `42` (all work); next fetch an external URL or write `.env` (both blocked in the artifact). Keep every primary/fallback/trigger model on Pi; direct Codex, Claude, and direct OpenCode reject this mono-agent sandbox policy.
 
 ## 10. Phoenix-observed agent with the TUI
 **For:** an agent builder evaluating runs in a tracing dashboard.
@@ -287,3 +287,26 @@ per-route form for a new agent.
 ```
 **Steps:** run a loopback self-hosted Bot API server if files exceed 20 MB, wire a long-running MCP tool in `.mcp.json`, `validate`, `start`.
 **Smoke:** send media with no caption, answer the `AskUser` question, watch progress update during the long job, and receive the generated file via `TelegramSendFile`.
+
+## 16. Local-first web research agent
+**For:** a researcher wanting operator-owned search infrastructure and bounded public-page extraction.
+**Goal:** discover through loopback SearXNG, extract pages locally, and optionally render sparse JavaScript HTML in an isolated anonymous browser.
+**Features:** `runtime.web-research`, `runtime.webfetch-retry`, `runtime.builtin-tools`, `sandbox.network-policy`.
+
+```json
+{
+  "runtime": { "model": "pi:openai-codex:gpt-5.5" },
+  "tools": {
+    "allowedTools": ["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
+    "web": {
+      "search": { "backend": "searxng", "endpoint": "http://127.0.0.1:8088" },
+      "fetch": { "render": "never", "browserCommand": "agent-browser" }
+    }
+  },
+  "sandbox": { "mode": "native", "network": { "mode": "all" }, "fallback": "fail-closed" }
+}
+```
+
+**Steps:** start the pinned loopback companion from `demos/searxng` → keep strict `searxng` or choose `auto` for keyless fallback → keep render `never`, or install `agent-browser >=0.33.1` and opt into `auto` for SPA pages → `validate` → `start`.
+**Boundary:** local SearXNG is private infrastructure, not an offline index; it contacts public engines and WebFetch contacts result sites. `localhost` permits the companion but blocks public fetches.
+**Smoke:** ask for two query variants and one official-page fetch; require canonical ranked URLs, untrusted-content boundaries, bounded timing metadata without query/URL leakage, and no duplicate network work for an identical call in the run.

package/skills/mono-agent-composer/references/validation.md

@@ -126,6 +126,7 @@ pnpm run test:demo
 | Cron | Run a one-off scheduled invocation or wait for one tick. |
 | Observability | Confirm a run writes a JSONL artifact with strings capped: non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; retained free text is scanned for a closed set of high-confidence credential shapes. If an `observability.exporters` Phoenix entry is set, confirm the trace appears in Phoenix. |
 | Memory recall tool | With any memory tier configured (`memory.recallTool.enabled` defaults on), ask the agent to recall an old note and confirm `MemoryRecall` appears separately from action-tool allowlists and returns it. |
+| Web research | Run `mono-agent validate` and require the Web search & fetch section to prove configured loopback SearXNG plus `agent-browser >=0.33.1` when rendering is enabled. Then ask for two query variants and one official-page fetch; require canonical ranked URLs, untrusted-content boundaries, and bounded timing metadata without query/URL leakage. |
 | Semantic memory search | With `memory.embeddings` set, first prove the configured provider only: Ollama model advertises `embedding` through `/api/show` and answers `/api/embed`, or LM Studio model has exact `type: "embedding"` in `/api/v1/models` and answers `/v1/embeddings`. Verify the finite vector dimension matches config, then ask a paraphrased question about an old note and confirm `MemoryRecall` returns it. Never accept a cross-provider fallback as proof. |
 
 ## Failure Handling

package/dist/broadcast-recorder.d.ts

@@ -1,27 +0,0 @@
-import type { RunEventSink } from "@mono-agent/agent-contracts";
-import type { RunRecorder } from "@mono-agent/observability";
-/** Stable run context stamped onto every broadcast frame. */
-export interface BroadcastRunContext {
-    readonly runId: string;
-    readonly conversationId: string;
-    /** Producing instance's trace-source id (empty when the host has none). */
-    readonly sourceId: string;
-    readonly sourceLabel?: string;
-    /** Trigger channel, e.g. "cron" | "webhook" | "chat" | "memory". */
-    readonly source?: string;
-    /** Trigger detail (cron job id / webhook endpoint name). */
-    readonly sourceDetail?: string;
-}
-/**
- * Wrap a {@link RunRecorder} so every run start/event/finish is ALSO published to
- * a {@link RunEventSink} (the in-process live bus), giving operator surfaces
- * sub-run visibility the on-disk recorder can't (it flushes only at start/finish).
- *
- * Broadcast is best-effort and additive, exactly like the Phoenix exporter path:
- * the inner recorder is the source of truth for the returned summary, and a
- * publish failure never changes the run outcome (publish is wrapped and the bus's
- * own `publish` is contracted never to throw). `seq` is left 0 here — the bus
- * stamps a process-wide monotonic value on publish.
- */
-export declare function createBroadcastRunRecorder(inner: RunRecorder, sink: RunEventSink, ctx: BroadcastRunContext): RunRecorder;
-//# sourceMappingURL=broadcast-recorder.d.ts.map

package/dist/broadcast-recorder.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"broadcast-recorder.d.ts","sourceRoot":"","sources":["../src/broadcast-recorder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAmD,MAAM,2BAA2B,CAAC;AAE9G,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,mBAAmB,GACvB,WAAW,CAyFb"}

package/dist/broadcast-recorder.js

@@ -1,104 +0,0 @@
-import { LIVE_EVENT_SCHEMA } from "@mono-agent/agent-contracts";
-import { redactJsonValue } from "@mono-agent/observability";
-/**
- * Wrap a {@link RunRecorder} so every run start/event/finish is ALSO published to
- * a {@link RunEventSink} (the in-process live bus), giving operator surfaces
- * sub-run visibility the on-disk recorder can't (it flushes only at start/finish).
- *
- * Broadcast is best-effort and additive, exactly like the Phoenix exporter path:
- * the inner recorder is the source of truth for the returned summary, and a
- * publish failure never changes the run outcome (publish is wrapped and the bus's
- * own `publish` is contracted never to throw). `seq` is left 0 here — the bus
- * stamps a process-wide monotonic value on publish.
- */
-export function createBroadcastRunRecorder(inner, sink, ctx) {
-    let eventIndex = 0;
-    let terminalStarted = false;
-    let terminalPromise;
-    const publish = (frame) => {
-        try {
-            sink.publish(frame);
-        }
-        catch {
-            // Broadcast is best-effort; a sink failure must never break the run.
-        }
-    };
-    const finished = async (summary) => {
-        const redactedSummary = redactJsonValue(summary);
-        publish({
-            t: "run_finished",
-            schema: LIVE_EVENT_SCHEMA,
-            sourceId: ctx.sourceId,
-            runId: ctx.runId,
-            status: redactedSummary.status,
-            summary: redactedSummary,
-            seq: 0,
-        });
-        return summary;
-    };
-    const recorder = {
-        onEvent(event) {
-            // Terminal is a hard boundary in the live protocol. Events accepted after
-            // commit starts could otherwise appear after `run_finished` or be absent
-            // from the authoritative summary/export.
-            if (terminalStarted)
-                return;
-            inner.onEvent(event);
-            const redactedEvent = redactJsonValue(event);
-            publish({
-                t: "event",
-                schema: LIVE_EVENT_SCHEMA,
-                sourceId: ctx.sourceId,
-                runId: ctx.runId,
-                eventIndex: eventIndex++,
-                event: redactedEvent,
-                seq: 0,
-            });
-        },
-        async prepareFinish(result) {
-            await inner.prepareFinish?.(result);
-        },
-        async commitFinish(result) {
-            if (terminalPromise === undefined) {
-                terminalStarted = true;
-                terminalPromise = (async () => await finished(inner.commitFinish === undefined ? await inner.finish(result) : await inner.commitFinish(result)))();
-            }
-            return await terminalPromise;
-        },
-        async finish(result) {
-            await recorder.prepareFinish?.(result);
-            return await recorder.commitFinish(result);
-        },
-        async fail(error) {
-            if (terminalPromise === undefined) {
-                terminalStarted = true;
-                terminalPromise = (async () => await finished(await inner.fail(error)))();
-            }
-            return await terminalPromise;
-        },
-    };
-    // `start` is optional on RunRecorder — only expose (and emit run_started) when
-    // the inner recorder has one, so callers that probe `recorder.start?.()` behave
-    // identically to the unwrapped recorder.
-    if (inner.start !== undefined) {
-        const innerStart = inner.start.bind(inner);
-        recorder.start = async () => {
-            const summary = await innerStart();
-            publish({
-                t: "run_started",
-                schema: LIVE_EVENT_SCHEMA,
-                sourceId: ctx.sourceId,
-                ...(ctx.sourceLabel === undefined ? {} : { sourceLabel: ctx.sourceLabel }),
-                runId: ctx.runId,
-                conversationId: ctx.conversationId,
-                ...(ctx.source === undefined ? {} : { source: ctx.source }),
-                ...(ctx.sourceDetail === undefined ? {} : { sourceDetail: ctx.sourceDetail }),
-                startedAt: summary.startedAt ?? new Date().toISOString(),
-                seq: 0,
-            });
-            return summary;
-        };
-    }
-    return recorder;
-}
-//# sourceMappingURL=broadcast-recorder.js.map