@mono-agent/agent-app 0.11.3 → 0.11.4

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

@@ -7,9 +7,9 @@ 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` |
-| Backup models on retryable provider failure | config | `runtime.fallbackModels` | `runtime.fallback-models` |
+| 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>`; unsupported for direct OpenCode SDK 1.x), `runtime.maxTurns`, `runtime.workspace` | `runtime.execution-modes`, `runtime.effort`, `runtime.max-turns`, `runtime.workspace` |
+| 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` |
 | 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` |
@@ -36,9 +36,9 @@ Every framework capability and how a composed agent reaches it. This table is th
 | 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` |
 | 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}` (default `0 */2 * * *`); env `MONO_AGENT_MEMORY_CONSOLIDATION_CRON`, `MONO_AGENT_MEMORY_CONSOLIDATION_ENABLED` | `memory.bujo-consolidation` |
+| 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 out-of-band maintenance CLI (rebuild/recall/index/legacy reflect/migrate) | cli | `memory-bujo <subcommand> <root>`; opt-in `MONO_AGENT_MEMORY_EMBEDDINGS_PROVIDER` (`ollama`/`lmstudio`/`openai`), `_MODEL`, and `_DIM` for semantic recall; advanced `migrate` remains Ollama-only, outside guided init, and requires `MONO_AGENT_MEMORY_LLM_MODEL` (optional `_ENDPOINT`) | — |
-| Config-aware memory preview CLI (stats/today/show/search/top plus metadata-only audit; 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]` | — |
+| 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` |
@@ -52,8 +52,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Built-in tool allow/deny lists (deny wins, even under allow-all; pi doesn't deny external MCP tools) | config | `tools.allowedTools`, `tools.disallowedTools`; built-ins are Read/Write/Edit/Glob/Grep/Bash/WebFetch/WebSearch | `tool-policy.allowlist`, `tool-policy.denylist`, `runtime.builtin-tools` |
 | 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 | `agent-app.adapter-send-tools` |
-| Human-in-the-loop interaction bridge for 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 when `AskUser` or `TelegramAskButtons` 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. | `interaction.bridge` |
+| 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, 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` or `TelegramAskButtons` 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. | `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` |
 | 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` |
@@ -64,8 +64,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 
 | Capability | Coverage | Where | Registry config ids |
 | --- | --- | --- | --- |
-| Webhook (sync/async HTTP invoke + status polling) | config | `webhook` section; endpoint overrides at `webhook.endpoints[].{model,effort}`; `webhook.maxRunMs` bounds each run | `webhook.http-invoke`, `webhook.run-watchdog` |
-| OpenAI-compatible API (/v1/models, /v1/chat/completions, SSE, bearer) | config | `openaiApi` section | `openai-api.chat-completions` |
+| Webhook (sync/async HTTP invoke + status polling + optional bearer) | config | `webhook` section; `apiKey` protects invoke/status and is required with non-loopback opt-in; endpoint overrides at `webhook.endpoints[].{model,effort,maxRunMs}`; endpoint `maxRunMs` wins over the `webhook.maxRunMs` fallback and `0` disables that endpoint watchdog | `webhook.http-invoke`, `webhook.run-watchdog` |
+| OpenAI-compatible API (/v1/models, /v1/chat/completions, SSE, bearer) | config | `openaiApi` section; sampling fields remain request metadata, while non-default values are ignored with a `runtime_warning` and runtime config stays authoritative | `openai-api.chat-completions` |
 | Telegram long polling and chat allowlist | config | `telegram` section | `telegram.long-polling` |
 | Telegram command/reaction/button/file interactivity | config | `telegram.commands[]`, `telegram.reactions`, `telegram.quietHours`; `TelegramAskButtons` / `TelegramSendFile` through `tools.allowedTools` | `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` |
@@ -78,10 +78,10 @@ Every framework capability and how a composed agent reaches it. This table is th
 | 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 | `tui.stream-endpoint` |
 | Live event relay (read-only run-event SSE for web) | config | `live.{enabled,host,port,basePath,allowNonLoopback,apiKey}`; default on, loopback | `live.event-relay` |
-| Cron jobs (five-field expressions, timezones, overlap skip) | config | `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.scheduled-prompts` |
+| 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/`); 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-trigger runtime model and effort overrides | config + code | `cron.jobs[].{model,effort}`; `webhook.endpoints[].{model,effort}` plus request body `{model,effort}` (request wins) | `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. Cron model-exhaustion notices require an explicit `notifyConversationId` and never infer; `notifyFailureCooldownHours` rate-limits them. | `channel.native-notify` |
+| 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` |
 | 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` |
 
@@ -89,17 +89,17 @@ Every framework capability and how a composed agent reaches it. This table is th
 
 | Capability | Coverage | Where | Registry config ids |
 | --- | --- | --- | --- |
-| JSONL run artifacts (events + summaries, secrets redacted) | config | `artifacts.dir`, `artifacts.retention`, `artifacts.memoryRetention` | `observability.jsonl-artifacts` |
+| JSONL run artifacts (events + summaries; strings capped; non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; free text is not content-scanned) | config | `artifacts.dir`, `artifacts.retention`, `artifacts.memoryRetention` | `observability.jsonl-artifacts` |
 | Trace-source registry (heartbeat manifests `mono-agent status` reads) | config | `traceability.{registryDir,sourceId,sourceLabel,heartbeatMs,staleAfterMs,globalDiscovery}` | `observability.trace-registry` |
-| Phoenix trace viewer (OTLP exporter; local JSONL artifacts are the fallback) | config | `observability.exporters` (phoenix entry) | `observability.phoenix-exporter` |
+| 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) | cli | `mono-agent tui [--agent <label>]`; agents serve the `tui` stream endpoint by default (`tui.enabled`, loopback) | — |
 | Managed proposal-only configuration conversation | cli + tool | macOS `mono-agent tui --configure` attaches to the authoritative background agent; `/configure`; separate configuration/ordinary conversation ids; host-gated `ProposeAgentConfiguration`; approval restarts and waits for readiness, failed start rolls files/agent back. `--local` is ordinary chat only; off macOS configuration is manual | — |
 | Session Recorder web PWA (read-only run browser) | cli | `mono-agent web [--host <addr>] [--port <n>] [--no-open] [--allow-non-loopback] [--show-auth-url] [--include-memory] [--max-runs <n>] [--config <path>] [--env-file <path>]`; package `@mono-agent/session-web`; non-loopback/non-interactive auth uses `MONO_AGENT_WEB_AUTH_TOKEN` | — |
-| Setup presets (saved answer-sets: generate config + `.env.example` + checklist) | cli | `mono-agent presets list\|show <id>`, `mono-agent init --preset <id> --yes` (`recipes`/`--recipe` deprecated aliases) | — |
+| Setup presets (saved answer-sets: generate config + `.env.example` + checklist) | cli | `mono-agent presets list\|show <id>`, `mono-agent init --preset <id> --yes` (`recipes`/`--recipe` deprecated aliases removed in v2.0.0) | — |
 | 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 temporary configuration) | 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-models <csv>] [--effort <level>] [--auth]\|validate [--consumer <path>]\|config\|presets\|start\|install-skill` | — |
+| 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`; legacy CLI `--fallback-models <csv>` is removed in v2.0.0 | — |
 | Preset capability check (selected preset live?) | cli | `mono-agent validate --preset <id>` | — |
 | `.env` auto-loading | cli | automatic; `--env-file <path>` | — |
 | Explicit failure objects (no fake success) | auto | harness | — |

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

@@ -101,7 +101,7 @@ Communication adapters are edge packages. They accept an `AgentResponder` and ow
 | OpenAI-compatible API | `@mono-agent/openai-api-adapter` | `curl /v1/models` and `/v1/chat/completions` |
 | Operator endpoints | `@mono-agent/operator-adapter` | `mono-agent tui` connects; `mono-agent web` observes live runs |
 | A2A provider/consumer | `@mono-agent/a2a-adapter` (external channel plugin) | Send text to the Agent Card URL |
-| Webhook | `@mono-agent/webhook-adapter` | `curl` the configured invocation path |
+| Webhook | `@mono-agent/webhook-adapter` | `curl` the configured invocation path (with `Authorization: Bearer ...` when `apiKey` is set) |
 | Cron | `@mono-agent/cron-adapter` | One scheduled or manually triggered invocation |
 
 Adapters must not import the harness, runtime adapter, memory package (`@mono-agent/memory` subpaths), or other adapters. `@mono-agent/agent-app` composes them from config; custom hosts and demos may compose them directly.
@@ -110,12 +110,12 @@ Adapters must not import the harness, runtime adapter, memory package (`@mono-ag
 
 Use:
 
-- `@mono-agent/tui` for the pi-tui operator console (`mono-agent tui`): live chat with full stream-event insight, recorded-run replay, config view.
+- `@mono-agent/tui` for the pi-tui operator console (`mono-agent tui`): live chat with structured stream-event insight, recorded-run replay, and config view. Remote event frames have a strict 256 KiB UTF-8 NDJSON cap: assistant-thought/tool-call payload fields are reduced and remeasured, while another oversized variant or a reducible event whose minimal form still does not fit becomes a bounded `oversized_event` marker. Other frame kinds are unaffected, and replay contains only key-redacted, capped events that reached terminal JSONL persistence.
 - `@mono-agent/session-web` for the read-only Session Recorder web PWA served by `mono-agent web`, including local artifact paging and live relay aggregation.
 - `@mono-agent/operator-adapter` for the loopback NDJSON stream endpoint the console connects to (`tui` config section, on by default) and the live SSE endpoint `mono-agent web` observes (`live` config section, on by default).
 - `@mono-agent/observability` for JSONL event artifacts, summaries, trace-source registration, and the `@mono-agent/observability/otel` Phoenix OTLP exporter configured via `observability.exporters`.
 
-Traceability is local-first. A running host registers a source manifest; `mono-agent status` reads the trace-source registry to report live sources, and artifacts are keyed by `(sourceId, runId)` so duplicate run ids do not collide. Phoenix is the recommended trace viewer when an `observability.exporters` (phoenix) entry is configured; local JSONL artifacts are the fallback otherwise.
+Traceability is local-first. A running host registers a source manifest; `mono-agent status` reads the trace-source registry to report live sources, and artifacts are keyed by `(sourceId, runId)` so duplicate run ids do not collide. Phoenix is the recommended trace viewer when an `observability.exporters` (phoenix) entry is configured; its terminal-batched export is best-effort. Independently, the local recorder writes empty events plus a `running` summary at start and a key-redacted, capped snapshot at finish/fail. Events stay in RAM between those boundaries, so a crash can lose them. Without Phoenix, those bounded terminal JSONL snapshots are the only local run record.
 
 ## Multi-Agent Join
 

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

@@ -16,10 +16,12 @@ Flow, check whether one of these fits and adapt it. Verify every key against
 **Goal:** a Telegram bot (long polling) that captures every turn into BuJo memory with scheduled consolidation and recalls past notes semantically.
 **Features:** `telegram.long-polling`, `channel.final-only-delivery`, `memory.bujo`, `memory.per-turn-capture`, `memory.bujo-consolidation`, `memory.recall-tool`, `memory.embeddings`.
 
+Put `MONO_AGENT_TELEGRAM_BOT_TOKEN=...` in `.env`; the source config omits the credential.
+
 ```json
 {
   "runtime": { "model": "pi:openai-codex:gpt-5.6-terra" },
-  "telegram": { "enabled": true, "botToken": "...", "allowedChatIds": ["123456789"] },
+  "telegram": { "enabled": true, "allowedChatIds": ["123456789"] },
   "memory": {
     "mode": "bujo", "path": "./.mono-agent/memory", "writeMode": "capture",
     "embeddings": { "provider": "ollama", "model": "nomic-embed-text:v1.5", "endpoint": "http://localhost:11434", "dim": 768 },
@@ -36,10 +38,12 @@ Flow, check whether one of these fits and adapt it. Verify every key against
 **Goal:** a mention-triggered Slack Socket Mode bot with a custom MCP tool, Read/Grep, and `SlackSendMessage` for proactive posts.
 **Features:** `slack.socket-mode`, `tool-policy.allowlist`, `tool-policy.mcp-servers`, `agent-app.adapter-send-tools`, `runtime.concurrency`.
 
+Put `MONO_AGENT_SLACK_BOT_TOKEN` and `MONO_AGENT_SLACK_APP_TOKEN` in `.env`; the source config omits credentials.
+
 ```json
 {
   "runtime": { "model": "pi:openai-codex:gpt-5.6-terra" },
-  "slack": { "enabled": true, "botToken": "xoxb-...", "appToken": "xapp-...", "allowedChannelIds": ["C012345"], "botUserIds": ["U012345"], "mentionTextAliases": ["@agent"] },
+  "slack": { "enabled": true, "allowedChannelIds": ["C012345"], "botUserIds": ["U012345"], "mentionTextAliases": ["@agent"] },
   "tools": { "allowedTools": ["Read", "Grep", "SlackSendMessage", "deployTool"], "mcpConfigPath": "./mcp.json" },
   "concurrency": { "maxConcurrentRuns": 4, "maxPendingRuns": 8 }
 }
@@ -103,12 +107,14 @@ Flow, check whether one of these fits and adapt it. Verify every key against
 **Goal:** a timezone-aware cron job that builds a daily digest with shared history and delivers its final answer verbatim through native notification.
 **Features:** `cron.scheduled-prompts`, `channel.native-notify`, `slack.socket-mode`, `memory.journal`.
 
-**Destination resolution:** an explicit `notifyConversationId` wins; otherwise mono-agent infers only when exactly one notify-capable Telegram/Slack candidate exists. With 0 or 2+ candidates delivery is skipped with a warning. Cron model-exhaustion notices require an explicit `notifyConversationId` and never infer a destination.
+**Destination resolution:** an explicit `notifyConversationId` wins; otherwise mono-agent infers only when exactly one notify-capable Telegram/Slack candidate exists. With 0 or 2+ candidates delivery is skipped with a warning. Artifact-derived candidates are cached for 30 seconds after each scan completes. An artifact committed under a Telegram/Slack conversation id invalidates the cache immediately; runs using the default synthetic `cron:`/`webhook:` ids do not. Other artifact changes are picked up after cache expiry and the next scan completes. Cron model-exhaustion notices require an explicit `notifyConversationId` and never infer a destination.
+
+Put `MONO_AGENT_SLACK_BOT_TOKEN` and `MONO_AGENT_SLACK_APP_TOKEN` in `.env`; the source config omits credentials.
 
 ```json
 {
   "runtime": { "model": "claude:claude-sonnet-4-6" },
-  "slack": { "enabled": true, "botToken": "xoxb-...", "appToken": "xapp-...", "allowedChannelIds": ["C012345"] },
+  "slack": { "enabled": true, "allowedChannelIds": ["C012345"] },
   "cron": { "jobs": [{ "id": "morning-digest", "enabled": true, "expression": "0 9 * * *", "timezone": "America/New_York", "prompt": "Build the morning digest. Your final answer is the digest to notify.", "conversationId": "daily-digest", "notify": true, "notifyConversationId": "slack:C012345" }] }
 }
 ```
@@ -128,16 +134,17 @@ Flow, check whether one of these fits and adapt it. Verify every key against
       "id": "a2a",
       "config": {
         "enabled": true,
-        "provider": { "host": "127.0.0.1", "port": 4201, "requireBearer": true, "bearerToken": "...", "idempotency": { "namespace": "research-production", "retentionMs": 2592000000, "maxRecords": 10000 } },
+        "provider": { "host": "127.0.0.1", "port": 4201, "requireBearer": true, "idempotency": { "namespace": "research-production", "retentionMs": 2592000000, "maxRecords": 10000 } },
         "agent": { "name": "Research Agent", "description": "Does research.", "version": "0.1.0" },
         "skill": { "id": "research", "name": "Research", "description": "Web research", "tags": ["research"] },
-        "consumer": { "remoteAgentUrls": ["http://127.0.0.1:4201"], "defaultRemoteAgentUrl": "http://127.0.0.1:4201", "bearerToken": "...", "timeoutMs": 30000 }
+        "consumer": { "remoteAgentUrls": ["http://127.0.0.1:4201"], "defaultRemoteAgentUrl": "http://127.0.0.1:4201", "timeoutMs": 30000 }
       }
     }]
   }
 }
 ```
-**Steps:** provider — `init`, add the `@mono-agent/a2a-adapter` plugin entry with `provider`/`agent`/`skill` + bearer; for paid/non-repeatable calls choose a reviewed stable `provider.idempotency.namespace`; `validate`, `start`, confirm the Agent Card is reachable. Consumer — set plugin `config.consumer` (or compose `createA2AConsumerResponder`), then pass the existing logical dispatch id through `idempotencyKey` / `idempotencyKeyForRequest` rather than generating one per attempt.
+**Credentials:** put `MONO_AGENT_A2A_BEARER_TOKEN` in the provider's `.env` and `MONO_AGENT_A2A_CONSUMER_BEARER_TOKEN` in the consumer's `.env`; source config omits both tokens.
+**Steps:** provider — `init`, add the `@mono-agent/a2a-adapter` plugin entry with `provider`/`agent`/`skill` + env-backed bearer; for paid/non-repeatable calls choose a reviewed stable `provider.idempotency.namespace`; `validate`, `start`, confirm the Agent Card is reachable. Consumer — set plugin `config.consumer` (or compose `createA2AConsumerResponder`), then pass the existing logical dispatch id through `idempotencyKey` / `idempotencyKeyForRequest` rather than generating one per attempt.
 **Smoke:** repeat one keyed message to the provider's Agent Card URL with the bearer; confirm the same task/result is returned and the responder runs once.
 
 ## 8. Multi-agent orchestration (`AskCollaborator`) — code
@@ -146,15 +153,23 @@ Flow, check whether one of these fits and adapt it. Verify every key against
 **Features:** `orchestrator.ask-collaborator`, `harness.request-runtime-options`, `runtime.custom`.
 
 ```ts
-const ext = createCollaboratorToolRuntimeExtension({
-  collaborators: [
-    { id: "researcher", label: "Research", responder: researcher },
-    { id: "writer", label: "Writer", responder: writer },
-  ],
-  conversationId, maxCalls: 10,
+const orchestrator = await createConfiguredAgentResponder({
+  config,
+  runtimeOptionsForRequest: async (input) => {
+    const extension = await createCollaboratorToolRuntimeExtension({
+      collaborators: [
+        { id: "researcher", label: "Research", responder: researcher },
+        { id: "writer", label: "Writer", responder: writer },
+      ],
+      conversationId: input.request.conversationId,
+      originalUserMessage: input.request.userMessage,
+      abortSignal: input.request.abortSignal,
+      maxCalls: 10,
+    });
+    // The harness invokes cleanup after success, failure, or request abort.
+    return { runtimeOptions: extension.runtimeOptions, cleanup: extension.cleanup };
+  },
 });
-// pass ext.runtimeOptions via createConfiguredAgentResponder({ runtimeOptionsForRequest })
-// call ext.cleanup() on disposal to close the ephemeral MCP server
 ```
 **Smoke:** give a compound task ("research X then write a summary"); confirm the artifact shows `AskCollaborator` delegating to both, and `cleanup()` closes the MCP port.
 
@@ -175,7 +190,7 @@ const ext = createCollaboratorToolRuntimeExtension({
 
 ## 10. Phoenix-observed agent with the TUI
 **For:** an agent builder evaluating runs in a tracing dashboard.
-**Goal:** run locally with the TUI and stream every run to Phoenix as OpenInference spans; local JSONL is the fallback.
+**Goal:** run locally with the TUI, attempt a best-effort terminal-batched Phoenix export, and retain a key-redacted, capped local JSONL snapshot after terminal persistence. A pre-terminal crash can omit the Phoenix batch and lose RAM-buffered JSONL events.
 **Features:** `observability.phoenix-exporter`, `observability.jsonl-artifacts`, `observability.trace-registry`, `tui.chat`.
 
 ```json
@@ -183,11 +198,11 @@ const ext = createCollaboratorToolRuntimeExtension({
   "runtime": { "model": "claude:claude-sonnet-4-6" },
   "artifacts": { "dir": ".mono-agent/artifacts" },
   "traceability": { "registryDir": ".mono-agent/trace-sources", "sourceId": "my-agent", "heartbeatMs": 10000 },
-  "observability": { "exporters": [{ "type": "phoenix", "endpoint": "http://127.0.0.1:6006/v1/traces", "projectName": "my-project", "includeSensitiveData": false, "timeoutMs": 5000 }] }
+  "observability": { "exporters": [{ "type": "phoenix", "endpoint": "http://127.0.0.1:6006/v1/traces", "projectName": "my-project", "includeSensitiveData": false, "contentPatternRedaction": false, "timeoutMs": 5000 }] }
 }
 ```
 **Steps:** start Phoenix (6006) → `init` → add artifacts/traceability/exporter → `validate` (POSTs an empty protobuf) → `start` (prints the Phoenix endpoint) → `mono-agent tui`.
-**Smoke:** complete a TUI prompt; confirm a redacted JSONL artifact AND a Phoenix trace with merged tool spans under the project.
+**Smoke:** complete a TUI prompt; confirm a JSONL artifact AND a Phoenix trace with merged tool spans under the project. Artifact/export strings are capped; non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; free text is not content-scanned or scrubbed.
 
 ## 11. Backfill historical runs to Phoenix
 **For:** an ops engineer onboarding observability after the fact.
@@ -208,11 +223,14 @@ const ext = createCollaboratorToolRuntimeExtension({
 
 ```json
 {
-  "runtime": { "model": "claude:claude-sonnet-4-6", "fallbackModels": ["pi:openai-codex:gpt-5.5", "pi:ollama:gemma4:31b"], "session": { "mode": "continuous" } },
+  "runtime": { "model": "claude:claude-sonnet-4-6", "fallbacks": [{ "model": "pi:openai-codex:gpt-5.5" }, { "model": "pi:ollama:gemma4:31b" }], "session": { "mode": "continuous" } },
   "providers": { "local": [{ "id": "ollama", "type": "ollama", "baseUrl": "http://localhost:11434", "enabled": true }], "piNative": { "transport": "auto", "piMaxRetries": 2, "maxRetryDelayMs": 60000, "piSessionsRoot": ".mono-agent/sessions" } }
 }
 ```
-**Steps:** `ollama pull gemma4:31b` → `mono-agent init --model claude:claude-sonnet-4-6 --fallback-models pi:openai-codex:gpt-5.5,pi:ollama:gemma4:31b` → add `providers.local` + `piNative.piSessionsRoot` → `validate` → `start`.
+Legacy `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` remain supported
+with no removal deadline, but this playbook intentionally emits the canonical
+per-route form for a new agent.
+**Steps:** `ollama pull gemma4:31b` → `mono-agent init --model claude:claude-sonnet-4-6 --fallback pi:openai-codex:gpt-5.5 --fallback pi:ollama:gemma4:31b` → add `providers.local` + `piNative.piSessionsRoot` → `validate` → `start`.
 **Boundary:** this mixed Pi/Claude chain intentionally omits the native mono-agent sandbox. Keep direct Codex chains all-direct; keep every route on Pi (including `pi:opencode-go:*`, not direct `opencode:*`) when `sandbox.mode` is `native`.
 **Smoke:** force a retryable primary failure; confirm the run result reports failover to the next model (not silent) and the conversation resumes from the transcript tail.
 

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

@@ -10,7 +10,20 @@ In the user's agent folder:
 mono-agent validate
 ```
 
-The report covers core config, runtime support for the primary and every fallback model, identity/skills/memory/MCP paths, the sandbox policy, the observability section (artifacts, traceability, and any configured exporters), and every channel (`ok` / `waiting` / `off` / `error`). Exit 0 means the folder is ready to start. Fix every `[error]`; `[waiting]` channels are simply unconfigured.
+The report covers core config, runtime support for the primary and every
+fallback model, identity/skills/memory/MCP paths, the sandbox policy,
+observability (artifacts, traceability, and configured exporters), runs health,
+managed launchd logs, secret placement, and every channel (`ok` / `waiting` /
+`disabled` / `error`). Its Runtime provenance section identifies the CLI
+producing the report by a full managed closure id only after validating its
+private marker, freshly recomputed installed closure, and coherent current
+closure manifest, or reports `dev (unmanaged)`; under `--consumer`, that is
+still the validator CLI rather than a separately running daemon. The launchd-log
+section reports active, retained, and total bytes for safely inspected streams,
+marks unsafe or unreadable byte inventory unavailable, and never rotates or
+changes permissions. Exit 0 means the folder is structurally valid; fix every
+`[error]`, and treat `[waiting]` as an unresolved selected dependency rather
+than a readiness claim.
 
 From a separate orchestration folder, validate a downstream consumer without changing cwd:
 
@@ -83,13 +96,13 @@ pnpm run test:demo
 | TUI | Start the host, connect with ordinary `mono-agent tui`, and complete one real prompt against the running responder. |
 | Telegram | Send one allowed chat message and verify the reply. |
 | Slack | Send one allowed DM or channel message and verify formatting. |
-| Adapter send tools | When `SlackSendMessage` / `TelegramSendMessage` are available (allow-all, or an explicit `tools.allowedTools` entry) with the channel enabled, call them from a non-Slack/Telegram surface such as TUI, cron, or OpenAI API to an allowed destination and verify delivery. |
+| Adapter send tools | When `SlackSendMessage` / `TelegramSendMessage` are available (allow-all, or an explicit `tools.allowedTools` entry) with the channel enabled, call them from a non-Slack/Telegram surface such as TUI, cron, or OpenAI API to an allowed destination; verify delivery, then reply at the destination and verify the exact sent text appears in replayed history. |
 | WhatsApp | Send one allowed sender/group trigger and verify the reply. |
 | OpenAI API | `curl /v1/models` and `/v1/chat/completions`. |
 | A2A | Send text to the Agent Card URL with `sendA2AMessage()`. |
 | Webhook | `curl` the invocation path and inspect the response body/status. |
 | Cron | Run a one-off scheduled invocation or wait for one tick. |
-| Observability | Confirm a run writes a redacted JSONL artifact; if an `observability.exporters` Phoenix entry is set, confirm the trace appears in Phoenix. |
+| 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; free text is not content-scanned. 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. |
 | 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. |