@mono-agent/agent-app 0.20.11 → 0.21.0

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

@@ -28,29 +28,22 @@ my-agent/
 
 ## Annotated Config
 
-New configs use `runtime.fallbacks[]`, where each route owns its optional exact
-effort. Legacy `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` remain
-supported compatibility inputs with no removal deadline; do not emit them for a
-new agent.
+Configs use `runtime.fallbacks[]`, where each route owns its optional exact
+effort. `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` were retired in
+0.21.0 and are now rejected at load — never emit them.
 
 ```jsonc
 {
   // Runtime: primary model plus ordered backups tried on retryable provider
   // failures (failover is reported in run results, never silent).
   "runtime": {
-    "model": "claude:claude-sonnet-4-6",   // claude:* | codex:* | pi:<provider>:<model>
-    "fallbacks": [{ "model": "pi:ollama:gemma4:31b" }],
-    "routeSafety": "uniform",              // uniform | per-route-native
-    "executionMode": "sdk",                // sdk | cli (default inferred from model)
-    "effort": "medium",                    // none|minimal|low|medium|high|xhigh|max|ultra; omit for direct opencode:*
-                                           // 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.
+    "model": "anthropic:claude-sonnet-4-6", // canonical <provider>:<model>, split at the first colon only
+    "fallbacks": [{ "model": "ollama:gemma4:31b" }],
+    "effort": "medium",                    // none|minimal|low|medium|high|xhigh|max|ultra
+                                           // Narrowed per model for display; still accepted at turn time.
+                                           // A model advertising no ultra rung simply does not offer it in pickers.
                                            // Ranking above max only prevents keyword downgrade.
-    "permissionMode": "default",           // default|plan|acceptEdits|bypassPermissions (CLI backends)
+    "permissionMode": "default",           // default|plan|acceptEdits|bypassPermissions
     "maxTurns": 0,                         // 0 or omitted means unlimited; 1-100 caps turns
     "compaction": {
       "enabled": true,                     // default true
@@ -72,29 +65,37 @@ new agent.
     "maxPendingRuns": 100
   },
 
-  // Local/self-hosted providers for pi:<provider>:<model> references.
+  // Providers the agent supports, keyed by canonical provider id. This map
+  // gates what is selectable: a route naming a provider that is neither a Pi
+  // builtin, nor `ollama`/`lmstudio` (zero-config autodiscovered), nor declared
+  // here with a "baseUrl", fails config load. `piAuthPath`, `piNative`, and
+  // `local` are reserved keys, never provider ids.
   "providers": {
     "piAuthPath": "~/.pi/agent/auth.json", // Pi OAuth credentials (openai-codex, ...)
     // Pi-native bridge tuning (all optional).
     "piNative": {
       "transport": "auto",                // auto | sse | websocket | websocket-cached
+      "promptCacheDiagnostics": false,     // metadata-only request fingerprints in run artifacts
       "piMaxRetries": 2,                   // 0-8; transient provider-transport retries
       "maxRetryDelayMs": 60000,            // backoff cap between retries (ms)
       "piSessionsRoot": ".mono-agent/sessions" // durable JSONL sessions → resume across restarts (unset = in-memory)
     },
-    "local": [
-      {
-        "id": "ollama",
-        "type": "ollama",                  // ollama | lmstudio | openai_compat
-        "baseUrl": "http://localhost:11434",
-        "enabled": true,
-        "trustPublicUrl": false,           // explicit opt-in for non-private URLs
-        // Keep the key in .env; config stores only its variable name.
-        // Inline "apiKey" remains schema-compatible for existing consumers.
-        "apiKeyEnv": "MY_PROVIDER_KEY",
-        "models": [{ "name": "gemma4:31b", "capabilities": { "context_window": 32768 } }]
-      }
-    ]
+    // One entry per provider id; every field below is optional. Declare an
+    // ollama/lmstudio entry only to override its endpoint or credential.
+    "ollama": {
+      "type": "ollama",                    // ollama | lmstudio | openai_compat; required with a
+                                           // baseUrl unless the id is ollama or lmstudio
+      "baseUrl": "http://localhost:11434",
+      "enabled": true,                     // false keeps the route loadable but unselectable
+      "trustPublicUrl": false,             // explicit opt-in for non-private URLs
+      // Keep the key in .env; config stores only its variable name.
+      // Inline "apiKey" remains schema-compatible for existing consumers.
+      "apiKeyEnv": "MY_PROVIDER_KEY",
+      "maxAdvertisedModels": 100,          // 1-200 catalog cap; default 100
+      "models": [{ "name": "gemma4:31b", "capabilities": { "context_window": 32768 } }]
+    }
+    // Legacy shape, still accepted and migrated on load — do not emit it for a
+    // new agent: "local": [{ "id": "ollama", "type": "ollama", ... }]
   },
 
   // Identity, optional soul, and selected skills.
@@ -128,11 +129,14 @@ new agent.
       "dim": 768                           // nomic-embed-text:v1.5 output dimension
     },
     "llm": {                               // enables bujo capture and the effective bujo tier; omit for lite/journal
-      // Env: MONO_AGENT_MEMORY_LLM_PROVIDER / _MODEL / _EXECUTION_MODE / _ENDPOINT.
+      // Env: MONO_AGENT_MEMORY_LLM_PROVIDER / _MODEL / _ENDPOINT / _TRACE / _TIMEOUT_MS.
+      // `memory.llm.executionMode` and MONO_AGENT_MEMORY_LLM_EXECUTION_MODE were
+      // retired in 0.21.0 and are rejected at load — never emit them.
       "provider": "ollama",                // ollama | agent-host
-      "model": "qwen3.6:latest",           // ollama: model string; agent-host: runtime ref, e.g. pi:openai-codex:gpt-5.5
+      "model": "qwen3.6:latest",           // ollama: model string; agent-host: canonical <provider>:<model>
       "endpoint": "http://localhost:11434" // ollama only; invalid for agent-host
-      // For agent-host, use: "model": "pi:openai-codex:gpt-5.5", "executionMode": "sdk"; omit endpoint.
+      // For agent-host, use: "model": "openai-codex:gpt-5.6-sol"; omit endpoint.
+      // agent-host also accepts "trace" (default true) and "timeoutMs" (default 60000).
     },
     // Bujo auto-scheduler — override the default or disable it.
     // Consolidation runs in-app; no external cron or launchd needed.
@@ -156,12 +160,13 @@ new agent.
     "mcpConfigPath": "./mcp.json",         // stdio/sse/http servers; inlined for SDK runtimes
     "web": {
       "search": {
-        "backend": "auto",                 // auto | searxng | codex | keyless
+        "backend": "auto",                 // auto | searxng | ollama | codex | keyless
         "codex": { "model": "gpt-5.6-luna" },
-        "endpoint": "http://127.0.0.1:8088" // optional unauthenticated loopback HTTP SearXNG base URL
+        "searxng": { "endpoint": "http://127.0.0.1:8088" }, // optional unauthenticated loopback HTTP
+        "ollama": { "baseUrl": "http://127.0.0.1:11434" }   // used only when backend is ollama
       },
       "fetch": {
-        "render": "never",                 // never disables browser capability; auto is static-first
+        "render": "never",                 // never disables browser capability; auto is static-first; always permits browser-first calls
         "browserCommand": "agent-browser"  // direct executable name/path
       }
     }
@@ -185,7 +190,7 @@ new agent.
     "maxQueueAgeMs": 300000,              // 5 min; cap 1 h
     "maxOutputBytes": 1048576,            // 1 MiB; cap 8 MiB
     "previewChars": 2000,                 // cap 8000
-    "maxChainDepth": 4,                   // host-owned; cap 8
+    "maxChainDepth": 4,                   // host-owned; cap 64
     "retention": {
       "maxRecords": 1000,                 // cap 10000
       "maxAgeMs": 604800000,              // 7 d; cap 30 d
@@ -193,6 +198,15 @@ new agent.
     }
   },
 
+  // Monitor watches reuse processJobs state and require processJobs.enabled.
+  // Tool policy defaults: wake_on batch, dedupe none, min_wake_interval_ms 0.
+  // Exit-only rejects nondefault dedupe/interval; terminal wakes always bypass both.
+  "monitors": {
+    "enabled": false,
+    "maxWakeIntervalMs": 300000,           // host interval ceiling; cap 300000
+    "maxChainDepth": 4                    // host-owned; cap 64
+  },
+
   // Human-in-the-loop bridge: structured blocking AskUser plus
   // run-scoped project-MCP progress. It auto-starts when either ask tool is
   // allowed, this block or an interaction env override is configured, or
@@ -200,13 +214,13 @@ new agent.
   // tools.mcpRequestContextServers names at least one opted project MCP server.
   "interaction": {
     "bridge": { "host": "127.0.0.1", "port": 0 },
-    "askUser": { "timeoutMs": 600000 },
+    "askUser": { "timeoutMs": 600000 }, // set null to disable automatic expiry
     "progress": { "enabled": true }
   },
 
-  // Sandbox for Pi-owned runtime commands. Direct Codex uses its own sandbox;
-  // Claude/direct OpenCode cannot enforce these exact srt scopes. All reject
-  // this block (pi:opencode-go:* remains a Pi route).
+  // Sandbox for Pi-owned runtime commands. Every route is Pi-native, so this
+  // block applies uniformly across the primary, every fallback, and every
+  // per-trigger override — no route family rejects it any more.
   "sandbox": {
     "mode": "native",                      // native (srt-wrapped) | off
     "network": { "mode": "none", "allowlist": [] }, // none|localhost|allowlist|all; *.suffix wildcards; all = open egress with filesystem still enforced (managed/explicit node+cli SRT launch only)
@@ -275,7 +289,7 @@ new agent.
         "path": "/webhook/invoke",
         "mode": "sync",
         "prompt": "Respond to this request:",
-        "model": "claude:claude-sonnet-4-6", // optional per-trigger override
+        "model": "anthropic:claude-sonnet-4-6", // optional per-trigger override
         "effort": "high",                  // same eight-level effort enum as runtime
         "maxRunMs": 3600000,               // endpoint override; 0 disables only this watchdog
         "notify": true,                     // deliver the successful final answer verbatim
@@ -405,7 +419,7 @@ new agent.
 
   "cron": {
     "dir": "cron",                         // optional: folder of *.md jobs (frontmatter + prompt body), default "cron"
-    "operatorActions": { "enabled": false }, // opt-in web run-now/runtime enable controls; requires tui.apiKey
+    "operatorActions": { "enabled": false }, // opt-in operator API run-now/runtime enable controls; requires tui.apiKey
     "jobs": [
       {
         "id": "daily",
@@ -414,7 +428,7 @@ new agent.
         "timezone": "UTC",                 // IANA timezone
         "prompt": "Post the morning summary.",
         "conversationId": "cron-daily",    // optional: share memory/history across ticks
-        "model": "claude:claude-sonnet-4-6", // optional per-trigger override
+        "model": "anthropic:claude-sonnet-4-6", // optional per-trigger override
         "effort": "high",
         "notify": true,                     // successful non-empty final answer is delivered verbatim
         // Explicit destination; if omitted, infer only with exactly one candidate.
@@ -437,7 +451,7 @@ new agent.
 mono-agent presets list                 # saved answer-sets (id, risk, description)
 mono-agent presets show <id>            # generated config + .env.example + follow-up checklist
 mono-agent init --preset <id> --yes [--with slack,cron] [--dry-run]   # scaffold from a preset (non-interactive)
-mono-agent init --model claude:claude-sonnet-4-6 --fallback pi:ollama:gemma4:31b [--memory lite|journal|bujo]
+mono-agent init --model anthropic:claude-sonnet-4-6 --fallback ollama:gemma4:31b [--memory lite|journal|bujo]
 mono-agent config       # resolved config field-by-field, each value tagged env/json/default
 mono-agent validate [--preset <id>] [--consumer <path>]     # per-section report; --preset also checks the preset's capabilities
 mono-agent start        # traceability + every configured channel
@@ -447,9 +461,9 @@ mono-agent restart --clear-sessions  # restart AND purge persisted pi sessions (
 
 A `.env` file in the folder is loaded automatically (exported shell variables win); use `--env-file <path>` for an alternate file. `validate --consumer <path>` loads the consumer folder's `.env` by default and resolves relative `--config` / `--env-file` paths there. `start` prints the traceability source (Phoenix when an `observability.exporters` Phoenix entry is configured, otherwise the local JSONL artifacts) and one status line per channel: `running` with its endpoint facts, `waiting_for_config` with the exact missing setting, `disabled`, or `failed` with the reason. Config is JSON-first: edit `mono-agent.config.json` directly (agents can edit it) and run `mono-agent restart` to apply — there is no live browser re-apply.
 
-For BuJo capture and the effective `bujo` tier that runs scheduled consolidation, configure `memory.llm`. Use `provider: "ollama"` with a local Ollama chat model string and optional `endpoint`, or `provider: "agent-host"` with `model` as a normal SDK runtime model reference such as `pi:openai-codex:gpt-5.5` and `executionMode: "sdk"`. `endpoint` is Ollama-only, and CLI-backed refs such as `codex:gpt-5.5` are rejected for memory LLMs until runtimes can enforce no external actions. The same values can be supplied via `MONO_AGENT_MEMORY_LLM_PROVIDER`, `MONO_AGENT_MEMORY_LLM_MODEL`, `MONO_AGENT_MEMORY_LLM_EXECUTION_MODE`, and `MONO_AGENT_MEMORY_LLM_ENDPOINT`. Routine BuJo consolidation runs via the in-app scheduler; the standalone `memory-bujo` maintenance CLI was removed (use `mono-agent memory <subcommand>` from the agent folder). `agent-host` LLM capture is an in-app composition path that injects the `LlmComplete` implementation into the BuJo store.
+For BuJo capture and the effective `bujo` tier that runs scheduled consolidation, configure `memory.llm`. Use `provider: "ollama"` with a local Ollama chat model string and optional `endpoint`, or `provider: "agent-host"` with `model` as a canonical `<provider>:<model>` runtime reference such as `openai-codex:gpt-5.6-sol`. Every route is Pi-native, so there is no SDK-versus-CLI distinction and no reference family is singled out for rejection: any reference the runtime accepts is valid here, including `openai-codex:*`. `endpoint` is Ollama-only and invalid for `agent-host`; `agent-host` additionally accepts `trace` (record each `complete()` as a `mem-*` run; default `true`) and `timeoutMs` (per-`complete()` abort, default 60000, range 1000-600000). The same values can be supplied via `MONO_AGENT_MEMORY_LLM_PROVIDER`, `MONO_AGENT_MEMORY_LLM_MODEL`, `MONO_AGENT_MEMORY_LLM_ENDPOINT`, `MONO_AGENT_MEMORY_LLM_TRACE`, and `MONO_AGENT_MEMORY_LLM_TIMEOUT_MS`. `memory.llm.executionMode` and `MONO_AGENT_MEMORY_LLM_EXECUTION_MODE` were retired in 0.21.0 and now fail config load — delete them, never emit them. Routine BuJo consolidation runs via the in-app scheduler; the standalone `memory-bujo` maintenance CLI was removed (use `mono-agent memory <subcommand>` from the agent folder). `agent-host` LLM capture is an in-app composition path that injects the `LlmComplete` implementation into the BuJo store.
 
-For operator views, run `mono-agent tui` or `mono-agent web` from any directory once the agent is started. Both discover running agents via the trace-source registry. The TUI and assistant-ui web console chat over the default-on `tui` stream endpoint (`"tui": {"enabled": false}` opts out); on macOS, `mono-agent tui --configure` opens a persistent, visibly marked proposal-only SELF-CONFIG conversation against the managed background agent and must not be combined with `--local`. Approval, rejection, and no-change turns continue that session; only quitting exits it. `mono-agent web` is an always-on service namespace, binds `0.0.0.0:5050` by default, and has no app login; use `--loopback` to narrow it. Capable agents expose stable read-only cron channels there. Run-now and runtime enable controls remain hidden unless `tui.apiKey` is configured and `cron.operatorActions.enabled` is explicitly true; every mutation still requires confirmation, is agent-audited, and does not rewrite job config. The former read-only recorder command, package, and relay were removed; use `mono-agent tui` (recorded-run replay) or `mono-agent web` (live console). The low-level `mono-agent-tui` bin also supports `--responder <file>` (embedded, an ESM module default-exporting an `AgentResponderLike` or exporting `createResponder(env, cwd, configJson)`) and `--url <baseUrl>` (direct connect).
+For operator views, run `mono-agent tui` or `mono-agent web` from any directory once the agent is started. Both discover running agents via the trace-source registry. The TUI and assistant-ui web console chat over the default-on `tui` stream endpoint (`"tui": {"enabled": false}` opts out). Edit `mono-agent.config.json` or `IDENTITY.md`, validate, and restart to apply configuration changes. `mono-agent web` is an always-on service namespace, binds `0.0.0.0:5050` by default, and has no app login; use `--loopback` to narrow it. On `web start`, `restart`, or `run`, `--theme` selects the shell and `--name <label>` replaces the hostname-derived PWA, browser-tab, and rail label; `--name -` restores the hostname default; managed starts persist both selections. Capable agents expose stable read-only cron channels there. Their quiet headers show only cadence and agent-authored next run (viewer-local absolute time), or disabled/removed/unavailable state. Retained web proxy and operator API run-now/runtime enable controls require `tui.apiKey` and explicit `cron.operatorActions.enabled`; every mutation still requires confirmation, is agent-audited, and does not rewrite job config. The former read-only recorder command, package, and relay were removed; use `mono-agent tui` (recorded-run replay) or `mono-agent web` (live console). The low-level `mono-agent-tui` bin also supports `--responder <file>` (embedded, an ESM module default-exporting an `AgentResponderLike` or exporting `createResponder(env, cwd, configJson)`) and `--url <baseUrl>` (direct connect).
 
 ## Programmatic Escape Hatch
 

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

@@ -9,16 +9,14 @@ Question:
 ```text
 Which model should drive the agent, and should any backups take over when the provider fails?
 
-1. `claude:<model>` through SDK or CLI mode
-2. `codex:<model>` through CLI mode (the default direct Codex path)
-3. `pi:openai-codex:<model>` through SDK mode (a selectable Pi alternative when Pi auth is configured)
-4. `pi:<provider>:<model>` through SDK mode (OpenAI, Copilot, OpenRouter, OpenCode-through-Pi, local Ollama, LM Studio, ...)
-5. A custom MonoRuntimeLike supplied programmatically (escape hatch)
+1. `<provider>:<model>` on any provider the agent declares — `openai-codex`, `anthropic`,
+   `github-copilot`, `openrouter`, `opencode-go`, local `ollama`/`lmstudio`, ...
+2. A custom MonoRuntimeLike supplied programmatically (escape hatch)
 ```
 
-Fills: `runtime.model`, canonical `runtime.fallbacks[]` (ordered backup routes tried on retryable provider failures, each with optional exact effort), `runtime.executionMode` (usually inferred), `runtime.effort`, `runtime.maxTurns`. Legacy `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` remain supported with no removal deadline, but do not emit them for a new agent. Keep a direct `codex:*` chain all-direct. Pi, Claude, and direct OpenCode may mix only with `sandbox` omitted/off; if native mono-agent sandboxing is selected, every primary/fallback/trigger model must stay on Pi (`pi:opencode-go:*` is Pi). Direct `opencode:*` is advanced scaffold/config-only, requires effective allow-all (an omitted or wildcard-containing allowlist with no denied tools) plus an explicit native `permissionMode`, and must omit `runtime.effort` under SDK 1.x.
+Fills: `runtime.model`, `runtime.fallbacks[]` (ordered backup routes tried on retryable provider failures, each with optional exact effort), `runtime.effort`, `runtime.maxTurns`, and `providers` (the map declaring which providers this agent supports — it gates what is selectable). `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` were retired in 0.21.0 and are rejected at load; never emit them. Every route is Pi-native, so a chain may mix providers freely and native mono-agent sandboxing applies uniformly.
 
-The interactive `mono-agent init` wizard discovers Pi OpenAI-Codex auth, OpenCode models, Ollama models, and LM Studio's local server best-effort. It defaults to direct `codex:gpt-5.6-terra` and presents both `pi:openai-codex:gpt-5.6-terra` and `pi:openai-codex:gpt-5.6-sol` as concrete selectable candidates. Direct `codex:gpt-5.6-sol` is also selectable; direct GPT-5.6 routes require Codex CLI 0.144.0 or newer. The wizard maps discovered OpenCode options to `pi:opencode-go:<model>` for setup/preflight, and auto-adds local provider modules when a primary or fallback model uses `pi:ollama:*` or `pi:lmstudio:*`. Recover missing Pi OAuth with `mono-agent auth login <provider>` (and `--pi-auth-path` when required). Direct `opencode:<provider>:<model>` refs are supported only as hand-authored runtime backend config; do not present them as a first-class composer or init wizard selection. For local models also fill `providers.local` (e.g. an Ollama or LM Studio base URL plus model capabilities). Follow-up only if needed: continuous provider session per conversation (`runtime.session.mode: "continuous"`, default) versus stateless per-message.
+The interactive `mono-agent init` wizard discovers Pi OpenAI-Codex auth, OpenCode models, Ollama models, and LM Studio's local server best-effort. It presents `openai-codex:gpt-5.6-terra` and `openai-codex:gpt-5.6-sol` as concrete selectable candidates, maps discovered OpenCode options to `opencode-go:<model>`, and auto-adds local provider modules when a primary or fallback model uses `ollama:*` or `lmstudio:*`. Recover missing Pi OAuth with `mono-agent auth login <provider>` (and `--pi-auth-path` when required). `ollama` and `lmstudio` are zero-config autodiscovered; declare a `providers` entry only to override an endpoint or credential, or to widen selection to a provider no route uses. Follow-up only if needed: continuous provider session per conversation (`runtime.session.mode: "continuous"`, default) versus stateless per-message.
 
 ## 2. Channels Of Communication
 
@@ -85,14 +83,19 @@ 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 automatic
-local SearXNG → ChatGPT-subscription Codex → keyless fallback, strict Codex,
-strict keyless, or strict SearXNG-only discovery. Fill
-`tools.web.search.backend`, optional `tools.web.search.endpoint`, and optional
+local SearXNG → ChatGPT-subscription Codex → keyless fallback, explicit local or
+hosted Ollama, strict Codex, strict keyless, or strict SearXNG-only discovery.
+Fill `tools.web.search.backend`, optional `tools.web.search.searxng.endpoint`,
+optional `tools.web.search.ollama.*`, and optional
 `tools.web.search.codex.model` (default `gpt-5.6-luna`). 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.
+config-level `"auto"` plus the direct `browserCommand`. Explain that the agent
+can request per-call `WebFetch` `render: "always"` when a known page must be
+browser-first; `"always"` is not a config value. Explain that local
+SearXNG/Ollama are infrastructure, not offline indexes, both search and fetch
+still generate public network traffic, hosted Ollama credentials are accepted
+only at the exact official origin, and rendering does not bypass access controls.
 
 ## 6. Memory Strategy
 
@@ -175,9 +178,7 @@ setup needed.
 - Ask: which chat LLM provider/model for LLM pipelines?
   - Ollama: local model string such as `qwen3.6:latest`; pull it first with
     `ollama pull qwen3.6:latest`.
-  - agent-host: SDK runtime model reference such as `pi:openai-codex:gpt-5.6-terra` with
-    `executionMode: "sdk"`. Do not use CLI-backed refs such as `codex:gpt-5.6-terra`; they are
-    rejected for memory LLMs until runtimes can enforce no external actions.
+  - agent-host: a canonical runtime model reference such as `openai-codex:gpt-5.6-terra`.
 - Ask: should per-turn intelligent capture be enabled (`writeMode: "capture"`), or only
   deterministic rapid-log summaries (`append-host-summary`) plus scheduled consolidation?
 - Ask: should we keep the default consolidation schedule (`0 */2 * * *`), customise the
@@ -213,8 +214,7 @@ For an agent-host memory LLM, write the `llm` block as:
 ```jsonc
 "llm": {
   "provider": "agent-host",
-  "model": "pi:openai-codex:gpt-5.6-terra",
-  "executionMode": "sdk"
+  "model": "openai-codex:gpt-5.6-terra"
 }
 ```
 
@@ -243,7 +243,7 @@ CLI was removed.
 Question:
 
 ```text
-Should Pi-owned runtime commands run inside the native mono-agent sandbox? Direct Codex uses its own native sandbox and rejects this block; Claude and direct OpenCode reject it because their provider-owned tools cannot enforce the exact `srt` scopes.
+Should Pi-owned runtime commands run inside the native mono-agent sandbox? Every route is Pi-native, so one answer covers the primary, every fallback, and every per-trigger override.
 
 1. No sandbox for the first pass
 2. Native sandbox, no network (fail closed)

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

@@ -2,26 +2,34 @@
 
 Every framework capability and how a composed agent reaches it. This table is the **authoritative, exhaustive** answer to "can the config do X?" — answer from it, do not grep the `@mono-agent` package source to confirm. `config` = declarable in `mono-agent.config.json`; config fields may be JSON-only. Environment-variable overrides are optional: only fields with a documented `MONO_AGENT_*` mapping accept one, so consult the generated config reference's `Env override` column (`--` means none, as for `channels.plugins`) instead of inferring one. `cli` = a `mono-agent` CLI flag/command, `auto` = always on when the app runs, `code` = programmatic escape hatch only, `dev` = development/test tooling. A capability that is absent here, or marked `code`, is not reachable through config — that is the answer, not a cue to read source. The final column maps config-bearing rows back to the repo's canonical registry; multiple ids in one row are an intentional aggregation. The repo's `docs/reference/feature-registry.md` (framework checkout only) and the documentation site at <https://mono-agent-docs.vercel.app/> are longer-form human-facing mirrors of this same table.
 
+The default configured agent may also advertise the operator-only v1
+`contextImport` capability. It is not a config toggle and must be detected from
+`GET /v1/info`; `historyAppend`/`deliverVerbatim` is a separate legacy surface
+and is not evidence of import support. Import performs no cron or model turn and
+accepts at most 32 KiB of decoded UTF-8 text with a source-qualified 512-byte
+idempotency key and a 4096-byte conversation id.
+
 ## Runtime
 
 | 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` |
+| Model backends: Pi-only `<provider>:<model>` (OpenAI, OpenAI-Codex, Copilot, Anthropic, OpenRouter, OpenCode-through-Pi, Ollama, LM Studio, ...); a legacy `pi:` prefix is canonicalized away | 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` |
-| Tool-permission posture for CLI backends (direct OpenCode asks/rejects unanswered by default; configure explicitly) | config | `runtime.permissionMode` | `runtime.permission-mode` |
+| Backup models on retryable provider failure | config | `runtime.fallbacks[]`, each route owning optional exact effort (omission = provider default) | `runtime.fallback-models` |
+| Effort, max turns, workspace | config + cli | `runtime.effort` (`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max` / `ultra`; `mono-agent init --effort <level>`). Reasoning-capable models map `ultra` to LOW; models without reasoning use OFF. `max` degrades to `xhigh` unless the resolved model advertises it. `mono-agent doctor` validates effort against the model's advertised levels and warns, naming the nearest supported level, when a configured value is outside that set. Ranking above `max` only prevents keyword downgrade. `runtime.maxTurns`, `runtime.workspace` | `runtime.effort`, `runtime.max-turns`, `runtime.workspace` |
+| Tool-permission posture | config | `runtime.permissionMode` (validated and forwarded, not consumed by the Pi runtime) | `runtime.permission-mode` |
 | Continuous provider sessions with idle eviction and optional daily rollover | config | `runtime.session.{mode,idleTimeoutMs,rollover,rolloverTimezone,rolloverNotice}` | `runtime.provider-sessions` |
 | Per-channel run admission/execution bounds | config | `concurrency.maxConcurrentRuns`, `concurrency.maxPendingRuns` | `runtime.concurrency` |
-| Local providers (Ollama / LM Studio / OpenAI-compatible) | config | `providers.local[]` | `runtime.local-providers` |
-| Pi OAuth credentials | config | `providers.piAuthPath` | `runtime.pi-credentials` |
+| Local providers (Ollama / LM Studio / OpenAI-compatible) | config | `providers.<id>.{type,baseUrl,enabled,trustPublicUrl,apiKeyEnv,models,maxAdvertisedModels}`; the legacy `providers.local[]` array is still accepted and migrated on load | `runtime.local-providers` |
+| Provider catalog (declares supported providers, widening model selection to each provider's full catalog) | config | the `providers` map, keyed by provider id — `providers.piAuthPath`, `providers.piNative`, and `providers.local` are reserved keys, never provider ids, and `providers.entries` is the resolved in-memory shape, not a JSON key. `ollama` and `lmstudio` are zero-config autodiscovered via localhost; a route naming any other provider that is not a Pi builtin fails config load until the map declares it with a `baseUrl` | `runtime.providers` |
+| Pi OAuth/API-key credentials and web-console re-authentication | config + cli + auto | `providers.piAuthPath`; `mono-agent auth login`; Agent settings lists only effective used providers and, when the protected operator capability is present, offers Pi-native GitHub/OpenAI device code, Anthropic redirect/code paste-back, or masked provider prompts through the same owner-only locked/no-clobber Pi-store transaction. Detection and successful live-request verification are separate; no `--device-auth` flag exists and Codex CLI `~/.codex/auth.json` is not covered | `runtime.pi-credentials` |
 | Pi-native transport, retry, and durable provider-session tuning | config | `providers.piNative.{transport,piMaxRetries,maxRetryDelayMs,piSessionsRoot}` | `runtime.pi-native-tuning` |
+| Prompt-cache diagnostics (metadata-only request fingerprints in run artifacts, offline token-weighted cache summary) | config | `providers.piNative.promptCacheDiagnostics` (`MONO_AGENT_PI_PROMPT_CACHE_DIAGNOSTICS`), default `false`; summarize with `scripts/summarize-prompt-cache.mjs` | `runtime.prompt-cache-diagnostics` |
 | Tool-output bloat guard, cost tracking | auto | built into every run | — |
 | Context handling / auto-compaction | config + provider | `runtime.compaction.*` (matching `MONO_AGENT_COMPACTION_*`) controls adaptive Pi compaction. Omitted budgets derive from the active model window; reactive recovery re-prompts exactly once only after a verified reduction, and persistent `context_limit` advances to a configured fallback | `runtime.context-compaction` |
 | Structured output (JSON schema) | code | harness `runtimeOptions.outputSchema` | — |
-| Live input steering | auto + code | built into ordinary Slack, Telegram, and web-console turns, including completed safe-preview `Steered` activity after provider acknowledgement; custom hosts use `runtimeOptions.liveInput` | — |
+| Live input steering | auto + code | built into ordinary Slack and Telegram turns and the web console's single server-authoritative Send path, with exact host-operation ownership, separate native acceptance, exact transcript consumption, uncertainty/no automatic retry, durable UUID receipts, and confirmed safe-preview `Steered` activity; custom hosts use `runtimeOptions.liveInput` | — |
 | Tool approval gates (risk tiers, timeouts, always-allow) | code | `createMonoRuntime({ onToolApprovalRequest, ... })` — needs a host UI | — |
 | Fully custom runtime | code | `startMonoAgentApp({ runtime })` | — |
 
@@ -31,21 +39,23 @@ Every framework capability and how a composed agent reaches it. This table is th
 | --- | --- | --- | --- |
 | Public name plus identity and optional soul documents; wizard Role has one explicit destination and created/preserved outcome | config + cli | `agent.name`, `context.identityPath`, `context.soulPath`; guided Role is `IDENTITY.md` → `## Role`, and an existing identity is never overwritten | `agent.public-name`, `context.identity`, `context.soul` |
 | Selected skills from a skills root | config | `context.skillsRoot`, `context.selectedSkills` | `skills.selected-activation` |
-| Generated project configuration skills with progressive disclosure | config + cli | init selects `mono-agent-configure` + `mono-agent-memory` under `./skills` with `context.skillDisclosure: "index"`; drift: `mono-agent install-skill --project --check\|--update` | `app.managed-project-skills` |
+| Generated project memory skill with progressive disclosure | config + cli | init selects `mono-agent-memory` under `./skills` with `context.skillDisclosure: "index"`; drift and retired-skill migration: `mono-agent install-skill --project --check\|--update` | `app.managed-project-skills` |
 | Version-matched semantic documentation companion for the global composer skill | cli + tool | `mono-agent install-skill` pairs `mono-agent-docs` with every available Codex/Claude target by default; `--no-docs-mcp` opts out; `mono_agent_docs` uses `action: "search"` for ranked 2–3k excerpts and `action: "read"` for anchored windows up to 10k, internal-link targets, and exact continuation actions | — |
 | Per-skill byte cap | config | `context.skillMaxBytes` | `skills.byte-capping` |
 | Conversation history (owner-only durable store) | auto | 64 messages per exact conversation id independent of `runtime.maxTurns`; aggregate defaults 256 MiB / 10,000 conversations / 365 inactive days; staged atomic publication and post-commit pruning; custom store via code | — |
 | Lite memory (FTS keyword recall + rapid-log capture; no external deps) | config | `memory.mode: "lite"`, `path`, `maxBytes`, `writeMode` | `memory.lite` |
 | Semantic embedding provider selection for Journal/BuJo | config + cli | `memory.embeddings.{provider,endpoint,model,dim,apiKeyEnv}`; guided init supports exclusive Ollama or LM Studio discovery and proof | `memory.embeddings-config` |
 | Journal memory (hybrid recall BM25+vector + static canonical salience; needs configured embeddings) | config | `memory.mode: "journal"`, `path`, `memory.embeddings.{provider,endpoint,model,dim,apiKeyEnv}` (`provider: "ollama" \| "lmstudio" \| "openai"`; exclusive, no cross-provider fallback) | `memory.journal` |
-| BuJo memory (journal + LLM capture/reconcile ADD/UPDATE/SUPERSEDE/NOOP + entity graph + auto-scheduled consolidation; needs embeddings + an app-level `memory.llm`) | config | `memory.mode: "bujo"`, `path`; selected Ollama/LM Studio/OpenAI embeddings are independent from explicit `memory.llm` with `provider: "ollama"` (`model`, optional `endpoint`) or `provider: "agent-host"` (`model` is an SDK runtime model ref, optional `executionMode: "sdk"`) — see `docs/memory/index.md` | `memory.bujo` |
+| BuJo memory (journal + LLM capture/reconcile ADD/UPDATE/SUPERSEDE/NOOP + entity graph + auto-scheduled consolidation; needs embeddings + an app-level `memory.llm`) | config | `memory.mode: "bujo"`, `path`; selected Ollama/LM Studio/OpenAI embeddings are independent from explicit `memory.llm` with `provider: "ollama"` (`model`, optional `endpoint`) or `provider: "agent-host"` (`model` is a runtime model ref) — see `docs/memory/index.md` | `memory.bujo` |
 | Supermemory external backend (server-side extraction/consolidation; async ingestion; explicitly installed plugin) | config | `memory.backend: "supermemory"`, `memory.writeMode`, `memory.supermemory.{baseUrl,apiKey,apiKeyEnv,container,timeoutMs,exposeMcpServer}`; install the exact matching `@mono-agent/memory-supermemory` version | `memory.backend-supermemory` |
 | BuJo consolidation auto-scheduler (projection-only `index.md` refresh + empty `future-log.md` stub + duplicate-group reporting; in-app, no external cron needed) | config | `memory.consolidation.{enabled,cron}` (five-field UTC, default `0 */2 * * *`, no hashed `H`); env `MONO_AGENT_MEMORY_CONSOLIDATION_CRON`, `MONO_AGENT_MEMORY_CONSOLIDATION_ENABLED` | `memory.bujo-consolidation` |
 | Memory maintenance CLI | cli | `mono-agent memory <subcommand>` from the agent folder (stats/today/show/search/top/audit/inspect/rebuild/rollback/…). The standalone `memory-bujo <subcommand> <root>` CLI and bin were removed; routine BuJo consolidation runs via the in-app scheduler | — |
 | Config-aware memory preview CLI (stats/today/show/search/top plus metadata-only audit; remains available when the live recall tool is disabled; local search warns and falls back to FTS-only when embeddings are down) | cli | `mono-agent memory stats\|today\|show <date>\|search <query>\|top\|audit [--limit <n>] [--json]` | — |
 | Memory liveness check (managed tier/provider/model/dimension identity; provider-native typed discovery plus real finite-vector/dimension probe for Ollama or LM Studio; declared auth env; BuJo LLM config + consolidation cadence; no cross-provider fallback) | cli | `mono-agent validate` | — |
 | Memory write modes and per-turn BuJo capture | config | `memory.writeMode`: `disabled`, `append-host-summary`, or `capture`; capture requires `memory.mode: "bujo"` | `memory.write-mode`, `memory.per-turn-capture` |
-| Auto-provisioned read-only `MemoryRecall` tool exposed for every configured memory tier; no chat LLM | config | `config.memory.recallTool.enabled` (`MONO_AGENT_MEMORY_RECALL_TOOL_ENABLED`, default on; explicit false opts out) | `memory.recall-tool` |
+| Auto-provisioned targeted read-only `MemoryRecall` tool exposed for every configured memory backend; no chat LLM | config | `config.memory.recallTool.enabled` (`MONO_AGENT_MEMORY_RECALL_TOOL_ENABLED`, default on; explicit false opts out of both explicit memory-read tools) | `memory.recall-tool` |
+| Bounded `MemoryJournal` broad chronological retrieval over curated canonical local memory; Lite/Journal/BuJo only, Supermemory unsupported; no embedding/chat call | config + auto | Shares `memory.recallTool.enabled`; restrictive `tools.allowedTools` must name `MemoryJournal` (or its canonical MCP name/server wildcard), deny wins | `memory.journal-browse` |
+| Agent-callable `Remember` tool that durably stores one explicitly stated fact; deterministic, append-only, no chat LLM; bujo backend and writable stores only; allowlist-gated and rejects credential-bearing text | config | `config.memory.rememberTool.enabled` (`MONO_AGENT_MEMORY_REMEMBER_TOOL_ENABLED`, default on for the bujo backend; explicit false opts out); a restrictive `tools.allowedTools` must name `Remember` | `memory.remember-tool` |
 | In-app memory LLM call timeout | config | `memory.llm.timeoutMs` (`MONO_AGENT_MEMORY_LLM_TIMEOUT_MS`, default 60000) | `memory.llm-timeout` |
 
 ## Tools, MCP, sandbox
@@ -54,14 +64,16 @@ Every framework capability and how a composed agent reaches it. This table is th
 | --- | --- | --- | --- |
 | 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/Exec/Bash/NodeRepl/WebFetch/WebSearch | `tool-policy.allowlist`, `tool-policy.denylist`, `runtime.builtin-tools` |
-| Pi-native Exec/Bash background process jobs with exact-thread wake | config + cli + auto | `processJobs.*` opts in (default off; unsupported on Windows). Only controller-ready exact Slack, Telegram, and web-console turns gain optional `background`; foreground schemas/behavior stay unchanged otherwise. Host-owned queue/runtime/output/depth/retention caps, owner-private records, inherited POSIX process groups, restart interruption, unforgeable-depth normal-tool wakes, Slack/Telegram same-message lifecycle updates, fail-closed live store health, `mono-agent jobs list\|get\|cancel`, and durable web cards are built in. Busy pre-turn wake admission remains pending without consuming its retry budget. JSON-only `unsafeAllowUnprotectedState` is an explicit sandbox-off/all-Pi trusted-host posture: it suppresses ProcessJobs and clear-sessions SRT while retaining registry, lease, private-root, and provider-zero route invariants, and warns that ProcessJobs state plus the operator secret are model-accessible. Commands that daemonize into another group or session are unsupported | `agent-app.process-jobs` |
-| Local-first public-web research | config + auto | `tools.web.search.{backend,endpoint,codex.model}` selects strict/first-choice loopback SearXNG, structured ChatGPT-subscription Codex search, or public no-credentials fallbacks; `auto` uses that order and rejects irrelevant/domain-mismatched results before stopping. `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` |
+| Additional managed file-tool roots while process sandboxing is off | config | `tools.filesystem.readableRoots` adds roots for Read/Glob/Grep; `tools.filesystem.writableRoots` adds roots for Write/Edit and also makes them readable. Lexical and realpath containment reject traversal and symlink escapes. Native sandbox roots remain authoritative when enabled; these fields do not constrain shell command contents | `tool-policy.filesystem-roots` |
+| Pi-native Exec/Bash background process jobs with exact-thread wake | config + cli + auto | `processJobs.*` opts in (default off; unsupported on Windows). Only controller-ready exact Slack, Telegram, and web-console turns gain optional `background`; request lineage diagnostics remain visible at exhaustion (default depth 4, cap 64). Background-only `wake_on_completion` defaults true; explicit false keeps terminal card updates without a wake. Exact sentinel-only replies suppress delivery; narration and rich content stay visible. Ambiguous wake receipts are unknown and never auto-replayed. Host-owned queue/runtime/output/depth/retention caps, owner-private records, inherited POSIX process groups, restart interruption, unforgeable-depth normal-tool wakes, Slack/Telegram same-message lifecycle updates, fail-closed live store health, `mono-agent jobs list\|get\|cancel`, and durable web cards are built in. Busy pre-turn wake admission remains pending without consuming its retry budget. JSON-only `unsafeAllowUnprotectedState` is an explicit sandbox-off/all-Pi trusted-host posture: it suppresses ProcessJobs and clear-sessions SRT while retaining registry, lease, private-root, and provider-zero route invariants, and warns that ProcessJobs state plus the operator secret are model-accessible. Commands that daemonize into another group or session are unsupported | `agent-app.process-jobs` |
+| Pi-native `Monitor`/`MonitorStop` streaming watches with per-batch conversation wakes | config + cli | `monitors.*` opts in (default off; additionally requires `processJobs.enabled`, whose protected private-state root, registration proof and origin binding it reuses; unsupported on Windows). A monitor keeps a command alive after the turn returns, treats each stdout line as one event, coalesces within `coalesceMs`, and wakes the exact originating conversation per batch plus once at the end, steering an in-flight run or queuing its own turn and holding no provider slot. Command preparation, workdir rules, environment cleaning, sandbox seam and output redaction are shared with `Bash`, so there is no separate command allowlist. Tool fields default to `wake_on: batch`, `dedupe: none`, `min_wake_interval_ms: 0`. Opt-in consecutive batch dedupe ignores ANSI redraw controls only; meaningful whitespace and timestamps remain significant. The host clamps the interval to `monitors.maxWakeIntervalMs` (default/cap 300000) and reports the effective policy. Exit-only permits only default dedupe/interval and sends one terminal wake with a bounded tail. First and terminal wakes bypass the interval; cancellation must never automatically recreate a watch. CLI/web expose durable suppression and follow-up/steered/unknown wake counters, not invented model costs. `monitors.maxChainDepth` defaults to4, cap64. Capacity is counted independently of `processJobs.*`; one wake per monitor is in flight at a time, pending batches are bounded in lines and bytes with oldest-drop accounting reported to the model, and a sustained firehose stops the watch with `rate_limited` plus one terminal wake. A pre-dispatch refusal is re-offered with the same batch under a fresh sequence; every other delivery failure is never replayed. Restart marks live monitors `interrupted`, terminates the incarnation-matched group, and owes exactly one recovery wake without re-running a model-authored command. The fenced envelope declares the turn host-raised and its content untrusted, and a `NOTHING_TO_REPORT` reply is suppressed. Availability is Telegram, Slack, and existing user-created web conversations; cron, webhook, web:new, TUI-direct and A2A never receive the tools. `mono-agent monitors list\|get\|cancel` is the operator surface | `agent-app.monitors` |
+| Local-first public-web research | config + auto | `tools.web.coordination: "host"` shares private admission/cooldown/quota state across agents under one OS user (default `process`); `mono-agent web-control status` inspects it. Broad primary queries and WebFetch `start_line`/`max_lines` avoid repeated work; Codex keeps a 10% quota reserve. `tools.web.search.maxRequestsPerRun` defaults to four actual provider requests per logical run, with cache/coalescing/cooldown/quota skips free. `tools.web.search.backend`, provider-scoped `searxng.endpoint` / `ollama.*`, and `codex.model` select strict providers or public no-credentials fallbacks; `auto` tries explicitly configured Ollama → configured SearXNG → Codex → keyless. Cooldowns advance immediately and tell the model not to sleep or retry. `tools.web.fetch.{render,browserCommand}` keeps deterministic static extraction as the default and optionally enables isolated agent-browser rendering; `render: "always"` is an explicit browser-first tool call under an `auto` config ceiling, and 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` |
 | Generated reply files and Pi-native MCP Apps | config + auto | `PublishReplyFile` is included under allow-all or must be named in a restrictive `tools.allowedTools`; it publishes confined files through owner-private integrity storage for native Slack/Telegram upload and web download. MCP Apps appear only when every configured runtime route supports the Pi-owned bridge, and render only in the hardened web console. Files and Apps share a 20-part run cap; retention follows `artifacts.retention.maxAgeDays` | `agent-app.rich-replies` |
 | 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` |
-| Interaction bridge for adapter-send history, structured blocking asks, and MCP progress | config + auto | `interaction.bridge.{host,port}`, `interaction.askUser.timeoutMs`, `interaction.progress.enabled`; env `MONO_AGENT_INTERACTION_BRIDGE_HOST`, `MONO_AGENT_INTERACTION_BRIDGE_PORT`, `MONO_AGENT_ASK_USER_TIMEOUT_MS`, `MONO_AGENT_PROGRESS_ENABLED`. It auto-starts for configured Slack/Telegram send tools, when `AskUser` is allowed, when an `interaction` block or interaction env override is configured, or when `interaction.progress.enabled` resolves true and `tools.mcpRequestContextServers` names at least one opted project stdio MCP server. AskUser presents all questions together on web and sequential native controls on Slack/Telegram. | `interaction.bridge` |
-| Sandbox on/off + srt engine (Pi-owned tools; direct Codex has its own sandbox, Claude/direct OpenCode reject native mono policy) | config | `sandbox.mode` | `sandbox.mode` |
+| Interaction bridge for adapter-send history, structured blocking asks, and MCP progress | config + auto | `interaction.bridge.{host,port}`, `interaction.askUser.timeoutMs` (default 600000; `null` disables automatic expiry), `interaction.progress.enabled`; env `MONO_AGENT_INTERACTION_BRIDGE_HOST`, `MONO_AGENT_INTERACTION_BRIDGE_PORT`, `MONO_AGENT_ASK_USER_TIMEOUT_MS` (`none` disables automatic expiry), `MONO_AGENT_PROGRESS_ENABLED`. It auto-starts for configured Slack/Telegram send tools, when `AskUser` is allowed, when an `interaction` block or interaction env override is configured, or when `interaction.progress.enabled` resolves true and `tools.mcpRequestContextServers` names at least one opted project stdio MCP server. AskUser presents all questions together on web and sequential native controls on Slack/Telegram. | `interaction.bridge` |
+| Sandbox on/off + srt engine (Pi-owned tools) | config | `sandbox.mode` | `sandbox.mode` |
 | Network policy (none/localhost/allowlist/all) | config | `sandbox.network.{mode,allowlist}` | `sandbox.network-policy` |
 | Filesystem scopes (readable/writable roots, deny-write globs) | config | `sandbox.readableRoots`, `sandbox.writableRoots`, `sandbox.denyWrite` | `sandbox.filesystem-scopes` |
 | Fallback behavior when srt is unavailable | config | `sandbox.fallback`, `sandbox.unsafeAllowHostProcess` | `sandbox.fallback` |
@@ -78,19 +90,20 @@ Every framework capability and how a composed agent reaches it. This table is th
 | 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; optional `slack.unfurlLinks` / `slack.unfurlMedia` control native agent message previews while omission preserves Slack defaults; 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` |
-| Surface awareness (which channel/DM the turn is in) | config | Always on for Slack and Telegram: the Session block states the surface kind, its id, and the per-message character budget. `slack.resolveChannelNames` (default `true`) adds the Slack channel NAME via `conversations.info` and requires `channels:read`/`groups:read`; best-effort, so a missing scope leaves the surface named by kind and id. Surface ids are model-visible by design — pair with an explicit `slack.allowedChannelIds` allowlist if `SlackSendMessage` is enabled | `channels.surface-awareness` |
+| Surface awareness (which channel/DM the turn is in) | config | Always on for Slack and Telegram: the Session block states the surface kind, its id, and the per-message character budget. `slack.resolveChannelNames` (default `true`) adds the Slack channel NAME via `conversations.info` and requires `channels:read`/`groups:read`; best-effort, so a missing scope leaves the surface named by kind and id. Surface ids are model-visible by design — pair with an explicit `slack.allowedChannelIds` allowlist if `SlackSendMessage` is enabled. Interactive console turns (web console thread, terminal TUI) are told which console they are on and given the thread's own conversation id verbatim (`web:<threadId>`), so an agent can quote it to host-side tools and operator commands that bind background work (Monitor, process jobs, task records) to that exact thread; cron/webhook/API turns still disclose nothing | `channels.surface-awareness` |
 | 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` |
 | WhatsApp (Baileys, QR login, group mention/any triggers) | config | `channels.plugins[].package: "@mono-agent/whatsapp-adapter"` plus plugin `config.{enabled,allowedChatJids,allowAllChats,groupMode,botJids,mentionTextAliases,stripMentionText}` | `whatsapp.baileys` |
+| Facebook Messenger (signed Meta webhook + Send API, PSID allowlist) | config | `channels.plugins[].package: "@mono-agent/messenger-adapter"` plus plugin `config.{enabled,allowedUserIds,allowAllUsers,host,port,webhookPath,apiVersion,allowNonLoopback,proactiveMessagingType,proactiveTag}`; the three credentials are environment-only and rejected in JSON — `MONO_AGENT_MESSENGER_PAGE_ACCESS_TOKEN`, `MONO_AGENT_MESSENGER_APP_SECRET`, `MONO_AGENT_MESSENGER_VERIFY_TOKEN` | `messenger.graph` |
 | A2A provider (Agent Card, JSON-RPC + REST, streaming, bearer, configurable request-body limit, opt-in durable dispatch identity) | config | `channels.plugins[].package: "@mono-agent/a2a-adapter"` plus plugin `config.provider` (including `maxRequestBytes` and `idempotency.{namespace,stateDir,retentionMs,maxRecords}`), `config.agent`, `config.skill`; `config.enabled` is canonical | `a2a.provider` |
 | A2A consumer settings (remote agent URLs, timeouts) and calls | config + code | same A2A plugin entry's `config.consumer`; calls via `sendA2AMessage({ idempotencyKey })` or `createA2AConsumerResponder({ idempotencyKeyForRequest })` | `a2a.consumer` |
 | TUI stream endpoint (operator console transport) | config | `tui.{enabled,host,port,basePath,allowNonLoopback,apiKey}`; default on, loopback; `/v1/info` capability-gates exact AskUser and agent-owned cron routes without changing wire schema 1 | `tui.stream-endpoint` |
 | Cron jobs (five-field expressions, timezones, stable job-id-seeded `H`; agent-app pins overlap to skip) | config + code | `cron.jobs[]`, including per-job `model` / `effort`; single-job `MONO_AGENT_CRON_*`, or one markdown file per job in `cron.dir` / `MONO_AGENT_CRON_DIR` (default `cron/`); `cron.operatorActions.enabled` / `MONO_AGENT_CRON_OPERATOR_ACTIONS_ENABLED` opt in to authenticated, confirmed, idempotent run-now and runtime enable controls (default off; never rewrites config); queue/replace controls are programmatic-only `startCronAdapter` options | `cron.scheduled-prompts` |
 | Cron per-run watchdog | config + code | `cron.jobs[].maxRunMs` or `maxRunMs` frontmatter; programmatic adapter fallback via `startCronAdapter({ maxRunMs })` | `cron.run-watchdog` |
-| Per-request runtime model and effort overrides | config + code | `cron.jobs[].{model,effort}`; `webhook.endpoints[].{model,effort}` plus request body `{model,effort}` (request wins); Telegram `/model` and `/effort`; Slack Block Kit selectors through thread-local `@agent /model` / `@agent /effort` and channel-wide `/<bot>-model` / `/<bot>-effort`, all over configured primary/fallback models | `runtime.per-trigger-model` |
-| Native final-answer notification for cron/webhook | config | Per job/endpoint `notify`; explicit `notifyConversationId` wins, otherwise inference occurs only with exactly one notify-capable Telegram/Slack candidate. With 0 or 2+ candidates delivery is skipped with a warning. Artifact-derived candidates use a 30-second post-scan cache. Telegram/Slack artifact commits invalidate it immediately; runs using default synthetic `cron:`/`webhook:` ids do not. Other artifact changes appear after expiry and the next scan. Cron model-exhaustion notices require an explicit `notifyConversationId` and never infer; `notifyFailureCooldownHours` rate-limits them. | `channel.native-notify` |
+| Per-request runtime model and effort overrides | config + code | `cron.jobs[].{model,effort}`; `webhook.endpoints[].{model,effort}` plus request body `{model,effort}` (request wins); Telegram `/model` and `/effort`; Slack Block Kit selectors through thread-local `@agent /model` / `@agent /effort` and channel-wide `/<bot>-model` / `/<bot>-effort`, all over configured primary/fallback models. Model-only turns inherit effort per route: primary = `runtime.effort`, configured fallback = its pinned effort or provider default, other advertised model = `runtime.effort` only when admitted | `runtime.per-trigger-model` |
+| Native final-answer notification for cron/webhook | config | Per job/endpoint `notify`; explicit `notifyConversationId` wins, otherwise inference occurs only with exactly one notify-capable Telegram/Slack/Messenger candidate. With 0 or 2+ candidates delivery is skipped with a warning. Artifact-derived candidates use a 30-second post-scan cache. Telegram/Slack/Messenger artifact commits invalidate it immediately; runs using default synthetic `cron:`/`webhook:` ids do not. Other artifact changes appear after expiry and the next scan. Cron model-exhaustion notices require an explicit `notifyConversationId` and never infer; `notifyFailureCooldownHours` rate-limits them. | `channel.native-notify` |
 | Channel message texts / stream tuning (welcome, debounce, ...) | code | channel driver overrides | — |
 | Custom transports | config + code | implement `ChannelDriver` and expose it through `channels.plugins[]`, or pass it via `startMonoAgentApp({ drivers })` | `channel.custom` |
 
@@ -102,10 +115,9 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Trace-source registry (heartbeat manifests `mono-agent status` reads) | config | `traceability.{registryDir,sourceId,sourceLabel,heartbeatMs,staleAfterMs,globalDiscovery}` | `observability.trace-registry` |
 | Phoenix trace viewer (best-effort terminal-batched OTLP exporter; independent local JSONL has bounded terminal snapshots and can lose RAM-buffered events on crash) | config | `observability.exporters` (phoenix entry) | `observability.phoenix-exporter` |
 | Operator console (live chat with thinking/tool/telemetry insight, run replay, config view, and owner-authenticated process-job routes when enabled) | cli | `mono-agent tui [--agent <label>]`; agents serve the `tui` stream endpoint by default (`tui.enabled`, loopback); `mono-agent jobs` uses a separate owner capability | — |
-| Always-on multi-agent web console (persistent conversations and same-thread quotes, agent-maintained semantic titles with permanent manual-rename precedence, durable process-job cards, live active-agent skill discovery with canonical `$skill-name` insertion, fixed compact/expanded rail, offline-agent filtering that always preserves pinned/selected agents, durable Web Push, exact structured AskUser reconciliation, stable read-only per-cron channels with bounded keyset history, attachments, model/effort selection, reasoning/tools, hidden telemetry-backed cumulative context usage, cancellation) | cli | `mono-agent web start\|stop\|restart\|status\|logs\|run`; stable cron routes are `/agents/:sourceId/cron/:jobId`, read next-run only from capable agents, and expose confirmed mutations only when the agent has an operator key and `cron.operatorActions.enabled`; process-job cards are source/thread-bound and update through the owner-authenticated operator proxy without a live browser; skill autocomplete/browse reads the running agent's bounded registry and never sends on selection; bare `mono-agent web` is read-only status/help; default `0.0.0.0:5050`, `--loopback` narrows to `127.0.0.1`; package `@mono-agent/web`; no app authentication, so LAN/Tailnet reachability is the access boundary | — |
-| Managed proposal-only SELF-CONFIG conversation | cli + tool | macOS `mono-agent tui --configure` attaches to the authoritative background agent; persistent marker and capability map; stable configuration conversation with a fresh proposal capability after each checkpoint; host-gated `ProposeAgentConfiguration`; approval restarts and waits for readiness, failed start rolls files/agent back; only quitting exits. `--local` is ordinary chat only; off macOS configuration is manual | — |
+| Always-on multi-agent web console (persistent conversations and same-thread quotes, one server-authoritative UUID-bearing Send path with durable read-only receipt recovery, agent-maintained semantic titles with permanent manual-rename precedence, durable process-job cards, live active-agent skill discovery with canonical `$skill-name` insertion, fixed compact/expanded rail, offline-agent filtering that always preserves pinned/selected agents, durable Web Push, exact structured AskUser reconciliation, stable read-only per-cron channels with bounded keyset history, attachments, per-conversation model/effort selection, SQLite-persisted per-agent defaults for new web conversations with one-click config revert, per-run requested/attempted/executed route and effective-effort attribution including nested subagents, remembered process-job/Monitor revival selection, reasoning/tools, hidden telemetry-backed cumulative context usage, cancellation) | cli | `mono-agent web start\|stop\|restart\|status\|logs\|run`; stable cron routes are `/agents/:sourceId/cron/:jobId`, read next-run only from capable agents, and expose confirmed mutations only when the agent has an operator key and `cron.operatorActions.enabled`; process-job cards are source/thread-bound and update through the owner-authenticated operator proxy without a live browser; standalone process-job/Monitor wake turns re-read the thread snapshot while an active Web Send targets the exact owned run or visibly queues on an older operator; fallback reasons and retries are bounded/sanitized before browser projection; skill autocomplete/browse reads the running agent's bounded registry and never sends on selection; bare `mono-agent web` is read-only status/help; default `0.0.0.0:5050`, `--loopback` narrows to `127.0.0.1`; `--theme` selects the shell and `--name <label>` replaces the hostname-derived PWA/tab/rail label on start/restart/run, `--name -` restores the hostname default, and managed selections are persisted; package `@mono-agent/web`; no app authentication, so LAN/Tailnet reachability is the access boundary | — |
 | Setup presets (saved answer-sets: generate config + `.env.example` + checklist) | cli | `mono-agent presets list\|show <id>`, `mono-agent init --preset <id> --yes` (the `recipes` command and `--recipe` alias were removed) | — |
-| Interactive setup wizard (preset/custom; exact `IDENTITY.md` → `## Role` prompt/outcome; walks model→channels→memory→tools→sandbox→observability; Journal/BuJo explicitly choose Ollama or LM Studio service root/model/dimension/optional auth env using typed discovery and a real probe; macOS starts the background agent before persistent SELF-CONFIG) | cli | `mono-agent init` (no flags, on a TTY; `setup` alias); manual embedding entry still requires readiness probe; flags/non-TTY stay scaffold-only; unsupported platforms use manual configuration/foreground start/ordinary TUI | — |
+| Interactive setup wizard (preset/custom; exact `IDENTITY.md` → `## Role` prompt/outcome; walks model→channels→memory→tools→sandbox→observability; Journal/BuJo explicitly choose Ollama or LM Studio service root/model/dimension/optional auth env using typed discovery and a real probe; macOS starts the background agent and prints manual edit/validate/restart/TUI steps) | cli | `mono-agent init` (no flags, on a TTY; `setup` alias); manual embedding entry still requires readiness probe; flags/non-TTY stay scaffold-only; unsupported platforms use manual configuration/foreground start/ordinary TUI | — |
 | Tools reporting + no-tools guardrail (allow-all → `All tools allowed`; explicit empty `allowedTools: []` → `waiting`; unknown-tool "did you mean"; send-tool/channel cross-checks) | cli | part of `mono-agent validate`/`doctor`; the wizard's tools step | — |
 | Resolved config view (every field tagged env/json/default) | cli | `mono-agent config` | — |
 | Scaffold / validate / start / install-skill | cli | `mono-agent init [--model <ref>] [--fallback <ref> [--fallback-effort <provider-default\|level>]]... [--effort <level>] [--auth]\|validate [--consumer <path>]\|config\|presets\|start\|install-skill [--target claude\|codex\|both] [--force] [--no-docs-mcp]`; the legacy CLI `--fallback-models <csv>` flag was removed (JSON/env compat inputs remain) | — |
@@ -114,3 +126,9 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Explicit failure objects (no fake success) | auto | harness | — |
 | Per-request runtime options, custom memory/history stores | code | `createConfiguredAgentResponder` options | — |
 | Multi-agent delegation (`AskCollaborator` loopback MCP tool) | code | `@mono-agent/agent-orchestrator` | — |
+
+Prompt-cache diagnostics: set `providers.piNative.promptCacheDiagnostics` (default
+`false`) or `MONO_AGENT_PI_PROMPT_CACHE_DIAGNOSTICS` to retain metadata-only request
+fingerprints in existing run artifacts. Use the framework script
+`scripts/summarize-prompt-cache.mjs` for token-weighted cache ratios and fingerprint
+changes; see [measurement](https://mono-agent-docs.vercel.app/runtime/prompt-cache-measurement/).