@mono-agent/agent-app 0.12.0 → 0.14.0

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

@@ -158,7 +158,7 @@ new agent.
   // NodeRepl shares state only inside one run and uses the same sandbox policy
   // as Bash.
 
-  // Human-in-the-loop bridge: blocking AskUser / TelegramAskButtons plus
+  // 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
   // interaction.progress.enabled resolves true while
@@ -174,7 +174,7 @@ new agent.
   // this block (pi:opencode-go:* remains a Pi route).
   "sandbox": {
     "mode": "native",                      // native (srt-wrapped) | off
-    "network": { "mode": "none", "allowlist": [] }, // none|localhost|allowlist|all; *.suffix wildcards
+    "network": { "mode": "none", "allowlist": [] }, // none|localhost|allowlist|all; *.suffix wildcards; all = open egress with filesystem still enforced (managed/explicit node+cli SRT launch only)
     "readableRoots": ["."],                // relative entries resolve against the workspace
     "writableRoots": ["."],
     "denyWrite": [".env", ".env.*", ".git/config", ".git/hooks/**"], // these are the defaults
@@ -220,12 +220,12 @@ new agent.
     "enabled": true,                       // default-on loopback operator console endpoint
     "host": "127.0.0.1",
     "port": 0,
-    "basePath": "/tui",
+    "basePath": "/gui",
     "allowNonLoopback": false              // set MONO_AGENT_TUI_API_KEY in .env when needed
   },
 
   "live": {
-    "enabled": true,                       // default-on read-only SSE relay for mono-agent sessions
+    "enabled": true,                       // default-on read-only SSE relay (run-event operator surface)
     "host": "127.0.0.1",
     "port": 0,
     "basePath": "/live",
@@ -272,10 +272,14 @@ new agent.
 
   // Telegram & Slack do not stream ANSWER tokens by default. They first show a
   // working indicator; inbound tool starts then edit one temporary, redacted
-  // activity ledger that the final answer replaces. Proactive turns suppress
-  // the ledger. This is built-in behavior (not a JSON field); a custom channel
+  // activity ledger. Both post the final separately and then best-effort delete
+  // their ledger. Proactive turns suppress the ledger. This is built-in behavior
+  // (not a JSON field); a custom channel
   // driver can set stream.showHints=false or stream.finalOnly=false. The
   // OpenAI-compatible endpoint still streams tokens.
+  // Telegram also exposes built-in per-chat /model and /effort menus over the
+  // configured runtime primary + fallbacks. This has no telegram JSON field;
+  // selections reset with the matching `default` command or process restart.
   "telegram": {
     "enabled": true,                       // opt-in; defaults to false (off → "disabled")
     // Put MONO_AGENT_TELEGRAM_BOT_TOKEN in .env; do not inline botToken here.
@@ -285,10 +289,14 @@ new agent.
 
   "slack": {
     "enabled": true,                       // opt-in; defaults to false (off → "disabled")
+    // Built-in @agent /model and /effort Block Kit controls use the same runtime
+    // primary + fallbacks and stay thread-local in shared channels. Register
+    // /<bot-username>-model and /<bot-username>-effort in Slack for channel-wide
+    // picker commands; the adapter derives those names from auth.test.user.
     // Put MONO_AGENT_SLACK_BOT_TOKEN and MONO_AGENT_SLACK_APP_TOKEN in .env.
     "allowedChannelIds": ["C0123"],        // or "allowAllChannels": true
     "allowAllChannels": false,
-    "botUserIds": ["U0BOT"],               // mention detection
+    "botUserIds": ["U0BOT"],               // optional supplemental ID; own ID is auto-discovered
     "mentionTextAliases": ["@agent"],
     "stripMentionText": true,
     "shortcuts": [                         // slack.shortcuts: JSON-only; callbackId matches the Slack app
@@ -401,14 +409,14 @@ mono-agent config       # resolved config field-by-field, each value tagged env/
 mono-agent validate [--preset <id>] [--consumer <path>]     # per-section report; --preset also checks the preset's capabilities
 mono-agent start        # traceability + every configured channel
 mono-agent restart      # apply config edits (config is JSON-first; restart to re-apply)
-mono-agent restart --force  # restart AND purge persisted pi sessions (fresh start; durable memory kept)
+mono-agent restart --clear-sessions  # restart AND purge persisted pi sessions (fresh start; durable memory kept)
 ```
 
 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`. The standalone `memory-bujo migrate` command remains Ollama-only; other maintenance commands use the configured embeddings provider. `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 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 operator views, run `mono-agent tui`, `mono-agent web`, or `mono-agent sessions` from any directory once the agent is started. All 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. The legacy Session Recorder reads artifacts and live updates from the default-on `live` relay (`"live": {"enabled": false}` opts out); run `mono-agent sessions --include-memory` to inspect memory-maintenance runs. 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); 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. The `mono-agent sessions` Session Recorder command was removed; use `mono-agent tui` (recorded-run replay) or `mono-agent web` (live console). Its `@mono-agent/session-web` package still ships and reads artifacts plus live updates from the default-on `live` relay (`"live": {"enabled": false}` opts out), but has no CLI launcher. 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

@@ -172,8 +172,9 @@ setup needed.
 
 The embeddings service and capture LLM are independent. Choosing LM Studio embeddings does
 not move capture there; guided config keeps an explicit `agent-host` LLM, while an authored
-Ollama `memory.llm` remains valid. Standalone advanced `memory-bujo migrate` is still
-Ollama-only and outside guided init.
+Ollama `memory.llm` remains valid. The in-app scheduler handles routine BuJo consolidation;
+the standalone `memory-bujo` maintenance CLI was removed (run `mono-agent memory <subcommand>`
+from the agent folder instead).
 
 Write (embeddings + chat model):
 
@@ -220,8 +221,9 @@ Before running mono-agent validate, pull the required models:
 
 Then run `mono-agent validate` — the Memory section confirms the root is writable,
 provider-specific liveness, and the consolidation cadence.
-See `docs/memory/index.md` for the full tier table, config shapes, and CLI subcommands
-(`memory-bujo rebuild|recall|index|reflect|migrate`).
+See `docs/memory/index.md` for the full tier table and config shapes. Memory maintenance
+runs via `mono-agent memory <subcommand>` from the agent folder; the standalone `memory-bujo`
+CLI was removed.
 
 ## 7. Sandbox
 
@@ -233,7 +235,8 @@ Should Pi-owned runtime commands run inside the native mono-agent sandbox? Direc
 1. No sandbox for the first pass
 2. Native sandbox, no network (fail closed)
 3. Native sandbox with localhost or an explicit network allowlist
-4. Native sandbox with custom filesystem scopes (extra readable/writable roots)
+4. Native sandbox with open network (`all`: filesystem containment only — for agents whose tools need broad egress)
+5. Native sandbox with custom filesystem scopes (extra readable/writable roots)
 ```
 
 Fills: the `sandbox` section — `mode`, `network.mode` (`none`/`localhost`/`allowlist`/`all`), `network.allowlist`, `readableRoots`/`writableRoots` (relative entries resolve against the workspace; default: workspace only), `denyWrite` glob patterns (defaults already deny `.env*`, `.git/config`, `.git/hooks/**`), `fallback` (`fail-closed` recommended; `unsafe-host-process` only with explicit consent plus `unsafeAllowHostProcess: true`).

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

@@ -29,6 +29,7 @@ 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` |
+| 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` |
@@ -37,7 +38,7 @@ Every framework capability and how a composed agent reaches it. This table is th
 | 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}` (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`) | — |
+| 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 was removed — its bin now prints a redirect and exits non-zero; 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` |
@@ -53,7 +54,7 @@ Every framework capability and how a composed agent reaches it. This table is th
 | MCP servers (stdio/sse/http) from a JSON file | config | `tools.mcpConfigPath` | `tool-policy.mcp-servers` |
 | Durable origin-bound continuations for trusted stdio/loopback-HTTP MCP services | config + auto | `tools.continuationServers` + `continuations.*`; interactive claims pin a bounded immutable origin snapshot before commit, exact rollover buckets are preserved, v3 state is restart-safe, and unavailable/legacy snapshots use a fixed zero-model fallback | `agent-app.durable-continuations` |
 | Adapter-derived send tools for enabled Slack/Telegram adapters | config | auto-available under allow-all once the channel is enabled; a **specific** `tools.allowedTools` must include `SlackSendMessage` / `TelegramSendMessage`; valid `slack.*` / `telegram.*` config and existing adapter allowlists provide credentials and destination bounds; confirmed message posts are idempotently recorded in destination history | `agent-app.adapter-send-tools` |
-| 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` |
+| 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` |
 | 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` |
@@ -67,9 +68,9 @@ Every framework capability and how a composed agent reaches it. This table is th
 | 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 runtime/command/reaction/button/file interactivity | config + code | built-in per-chat `/model` and `/effort` use configured primary/fallback models (no Telegram config key); `telegram.commands[]`, `telegram.reactions`, `telegram.quietHours`; `AskUser`, non-blocking `TelegramSendMessage.reply_options`, and `TelegramSendFile` | `telegram.interactive` |
 | Telegram inbound audio transcription | config | `telegram.transcription.{endpoint,model,language,timeoutMs}`; opt-in OpenAI-compatible transcription endpoint for voice notes, audio files, and round-video attachments | `telegram.transcription` |
-| Slack (Socket Mode, channel allowlist, mention handling) | config | `slack` section | `slack.socket-mode` |
+| Slack (Socket Mode, channel allowlist, mention handling, native runtime controls) | config + code | `slack` section; built-in Block Kit controls use configured primary/fallback choices through DM-wide/thread-local `@agent /model` and `@agent /effort`, plus channel-wide workspace commands `/<bot>-model` and `/<bot>-effort` derived from `auth.test.user` (Slack app registration + `commands` scope; no mono-agent config key) | `slack.socket-mode` |
 | Slack 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` |
@@ -80,7 +81,7 @@ Every framework capability and how a composed agent reaches it. This table is th
 | 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, 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` |
+| 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` |
 | 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` |
@@ -93,14 +94,14 @@ 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) | cli | `mono-agent tui [--agent <label>]`; agents serve the `tui` stream endpoint by default (`tui.enabled`, loopback) | — |
-| Always-on multi-agent web console (persistent conversations, attachments, model/effort selection, reasoning/tools, hidden telemetry-backed cumulative context usage, cancellation) | cli | `mono-agent web start\|stop\|restart\|status\|logs\|run`; 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 | — |
+| Always-on multi-agent web console (persistent conversations and same-thread quotes, fixed compact/expanded rail, offline-agent filtering that always preserves pinned/selected agents, alive-page/PWA response notifications, attachments, model/effort selection, reasoning/tools, hidden telemetry-backed cumulative context usage, cancellation) | cli | `mono-agent web start\|stop\|restart\|status\|logs\|run`; bare `mono-agent web` is read-only status/help; default `0.0.0.0:5050`, `--loopback` narrows to `127.0.0.1`; notifications require explicit per-origin browser permission plus a secure context and do not use Web Push; 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 | — |
-| Session Recorder web PWA (read-only run browser) | cli | `mono-agent sessions [--host <addr>] [--port <n>] [--no-open] [--allow-non-loopback] [--show-auth-url] [--include-memory] [--max-runs <n>] [--config <path>] [--env-file <path>]`; default `127.0.0.1:4599`; package `@mono-agent/session-web`; non-loopback/non-interactive auth uses legacy `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 removed in v2.0.0) | — |
+| Session Recorder web PWA (read-only run browser) | cli | Command removed — use `mono-agent tui` (recorded-run replay) or `mono-agent web` (live console); the `@mono-agent/session-web` package still ships without a CLI launcher, and `MONO_AGENT_WEB_AUTH_TOKEN` is no longer read by any code (its only reader, the removed `sessions` command, is gone) | — |
+| 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 | — |
 | 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`; legacy CLI `--fallback-models <csv>` is removed in v2.0.0 | — |
+| 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) | — |
 | 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

@@ -51,6 +51,7 @@ Use this path when the agent needs identity, selected skills, history, and optio
 | Memory substrate (schema, migrations, FTS+vector db, RRF) | `@mono-agent/memory/store` | SQLite storage, BM25 FTS, optional vector index, hybrid recall; re-exports `MemoryStore`/`MemoryBlock`/`MemoryWriteResult` from `@mono-agent/agent-contracts` |
 | Memory engine (all tiers: lite/journal/bujo) | `@mono-agent/memory/bujo` | `BujoMemoryStore` — tier-aware: FTS recall (lite), hybrid recall + static salience (journal), LLM capture/reconcile + entity graph + projection-only scheduled consolidation (bujo) |
 | Embedding providers | `@mono-agent/memory/search` | Exclusive Ollama/LM Studio/OpenAI embedding providers used by the store subpath for vector recall; `agent-app` owns guided typed discovery and the real readiness probe |
+| Composer documentation search + guided reading | `@mono-agent/docs-mcp` (optional plugin) | Exact-version offline hybrid semantic/BM25 `mono_agent_docs` search plus anchored reads, cross-link resolution, and continuation windows over canonical docs and composer references; paired by `mono-agent install-skill`, outside the composed agent's own `mcp.json` |
 | External Supermemory backend | `@mono-agent/memory-supermemory` (optional plugin) | Explicitly installed lockstep package selected by `memory.backend: "supermemory"`; proxies the shared `MemoryStore` / `MemoryRecall` contracts to local or hosted Supermemory for server-side extraction, consolidation, and hybrid recall |
 | Recall tool surface | `@mono-agent/agent-app` (bundled) | Auto-provisions read-only `MemoryRecall` for every configured tier and direct configured responder; automatic/tool recall share the same store and per-turn query cache |
 
@@ -75,6 +76,11 @@ Use `@mono-agent/agent-harness` directly when a host needs custom prompt/runtime
 
 Use `@mono-agent/agent-harness` for tool/MCP policy normalization. The **config** default is allow-all (`["*"]`); `createToolPolicy` itself does no defaulting, and the harness's no-policy safety net is `failClosedToolPolicy()` (an empty, fail-closed policy):
 
+The `mono-agent-docs` MCP server paired with this authoring skill is a harness
+companion, not an MCP server injected into every composed agent. Add project
+MCP servers to the agent's own `mcp.json`; do not copy the documentation server
+there unless the resulting agent itself must answer mono-agent framework questions.
+
 ```ts
 import { createToolPolicy, toolPolicyToRuntimeOptions } from "@mono-agent/agent-harness";
 
@@ -99,7 +105,7 @@ Communication adapters are edge packages. They accept an `AgentResponder` and ow
 | Slack | `@mono-agent/slack-adapter` | Allowed channel or DM gets the final reply |
 | WhatsApp | `@mono-agent/whatsapp-adapter` (external channel plugin) | Allowed sender/group trigger produces a reply |
 | OpenAI-compatible API | `@mono-agent/openai-api-adapter` | `curl /v1/models` and `/v1/chat/completions` |
-| Operator endpoints | `@mono-agent/operator-adapter` | `mono-agent tui` and `mono-agent web` connect for chat; `mono-agent sessions` observes live runs |
+| Operator endpoints | `@mono-agent/operator-adapter` | `mono-agent tui` and `mono-agent web` connect for chat; the read-only `live` relay feeds operator tooling such as the `@mono-agent/session-web` PWA |
 | 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 (with `Authorization: Bearer ...` when `apiKey` is set) |
 | Cron | `@mono-agent/cron-adapter` | One scheduled or manually triggered invocation |
@@ -111,9 +117,9 @@ 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 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/web` for the assistant-ui always-on browser console (`mono-agent web`): persistent multi-agent conversations, device-local file picking, streamed reasoning/tools, internal telemetry-backed cumulative context usage, cancellation, LAN-default HTTP on port 5050, and conflict-safe optional Tailscale Serve HTTPS. It has no app login; network reachability is the access boundary.
-- `@mono-agent/session-web` for the legacy read-only Session Recorder PWA served by `mono-agent sessions`, including local artifact paging and live relay aggregation on its existing port 4599 surface.
-- `@mono-agent/operator-adapter` for the loopback NDJSON stream endpoint the TUI and web chat console connect to (`tui` config section, on by default) and the live SSE endpoint `mono-agent sessions` observes (`live` config section, on by default).
+- `@mono-agent/web` for the assistant-ui always-on browser console (`mono-agent web`): persistent multi-agent conversations and same-thread quotes, fixed compact/expanded agent navigation with offline filtering, explicit alive-page/PWA response notifications, device-local file picking, streamed reasoning/tools, internal telemetry-backed cumulative context usage, cancellation, LAN-default HTTP on port 5050, and conflict-safe optional Tailscale Serve HTTPS. It has no app login; network reachability is the access boundary.
+- `@mono-agent/session-web` for the read-only Session Recorder PWA. Its `sessions` launcher command was removed (use `mono-agent tui` for recorded-run replay or `mono-agent web` for the live console); the package still ships without a CLI command and full retirement is pending. Local artifact paging and live relay aggregation stay on its port 4599 surface.
+- `@mono-agent/operator-adapter` for the loopback NDJSON stream endpoint the TUI and web chat console connect to (`tui` config section, on by default) and the read-only live SSE endpoint operator tooling 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; 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.

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

@@ -31,25 +31,25 @@ Put `MONO_AGENT_TELEGRAM_BOT_TOKEN=...` in `.env`; the source config omits the c
 }
 ```
 **Steps:** `ollama pull nomic-embed-text:v1.5 && ollama pull qwen3.6:latest` → `mono-agent init --model claude:claude-sonnet-4-6 --memory bujo` → add telegram + fill embeddings/llm + `writeMode: capture` → `mono-agent validate` (confirm memory liveness + consolidation cadence) → `mono-agent start`.
-**Smoke:** send a fact from the allowed chat, then ask a paraphrased question later; confirm the temporary memory-tool activity is replaced by the final answer, `MemoryRecall` appears in the run JSONL, and the answer uses it.
+**Smoke:** send a fact from the allowed chat, then ask a paraphrased question later; confirm the final answer arrives separately and the temporary memory-tool activity disappears, `MemoryRecall` appears in the run JSONL, and the answer uses it.
 
 ## 2. Slack team bot with MCP tools
 **For:** a DevOps engineer running a shared team bot.
 **Goal:** a mention-triggered Slack Socket Mode bot with a custom MCP tool, Read/Grep, and `SlackSendMessage` for proactive posts.
-**Features:** `slack.socket-mode`, `channel.transient-tool-activity`, `tool-policy.allowlist`, `tool-policy.mcp-servers`, `agent-app.adapter-send-tools`, `runtime.concurrency`.
+**Features:** `slack.socket-mode`, `runtime.per-trigger-model`, `channel.transient-tool-activity`, `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, "allowedChannelIds": ["C012345"], "botUserIds": ["U012345"], "mentionTextAliases": ["@agent"] },
+  "slack": { "enabled": true, "allowedChannelIds": ["C012345"], "stripMentionText": true },
   "tools": { "allowedTools": ["Read", "Grep", "SlackSendMessage", "deployTool"], "mcpConfigPath": "./mcp.json" },
   "concurrency": { "maxConcurrentRuns": 4, "maxPendingRuns": 8 }
 }
 ```
-**Steps:** create a Slack app (Socket Mode app token + bot token) → `mono-agent init` (allow-all by default) → write `mcp.json` (the MCP tool becomes available from the server declaration — MCP tools aren't gated by `allowedTools`) → add slack; `SlackSendMessage` is auto-available under allow-all, or name it if you narrow to a specific allowlist → `validate` → `start`.
-**Smoke:** mention the bot in an allowed channel; confirm the 👀/assistant status, the temporary MCP-tool activity message being replaced by the final answer, the tool firing in the artifact, and `SlackSendMessage` posting only to allowed channels.
+**Steps:** create a Slack app (Socket Mode app token + bot token, with Interactivity enabled and the `commands` bot scope) → register `/<bot-username>-model` and `/<bot-username>-effort` without a Request URL → `mono-agent init` (allow-all by default) → write `mcp.json` (the MCP tool becomes available from the server declaration — MCP tools aren't gated by `allowedTools`) → add Slack; the adapter discovers its own bot identity, and `SlackSendMessage` is auto-available under allow-all or named when using a specific allowlist → `validate` → `start`.
+**Smoke:** mention the bot in an allowed channel; confirm the 👀/assistant status, a fresh final reply followed by removal of the temporary MCP-tool activity message, the tool firing in the artifact, and `SlackSendMessage` posting only to allowed channels. Run `/<bot-username>-model`, choose a configured option, and verify two threads inherit it; then use `@agent /model` in one thread and verify only that thread overrides the channel choice. Confirm colon-delimited references are literal rather than emoji-expanded.
 
 ## 3. Fully local Ollama agent (no cloud)
 **For:** a privacy-focused user with no cloud budget.
@@ -275,7 +275,7 @@ per-route form for a new agent.
 **Goal:** one Telegram agent uses `AskUser`, long-running MCP tool progress, a self-hosted Bot API server, and `TelegramSendFile`.
 **Features:** `telegram.long-polling`, `agent-app.adapter-send-tools`, `interaction.ask-user`, `interaction.progress`, `tool-policy.mcp-servers`.
 
-**Bridge startup:** the loopback interaction bridge auto-starts when `AskUser` or `TelegramAskButtons` is allowed, when the `interaction` block or an interaction env override is configured, or when `interaction.progress.enabled` resolves true and `tools.mcpRequestContextServers` names at least one opted project MCP server.
+**Bridge startup:** the interaction bridge defaults to loopback and auto-starts when `AskUser` is allowed, when the `interaction` block or an interaction env override is configured, or when `interaction.progress.enabled` resolves true and `tools.mcpRequestContextServers` names at least one opted project MCP server. Keep `interaction.bridge.host` on loopback because non-loopback values are not rejected. AskUser takes one to five structured questions with two or three described choices each; Telegram presents them sequentially with native buttons, Other/custom reply, and Done for multi-select.
 
 ```json
 {

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

@@ -25,6 +25,8 @@ 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.
 
+All read/status commands accept `--json` for scriptable checks (`validate`, `config`, `presets`, `status`, `sandbox status`, `install-skill --project --check`, `runs report`, `runs audit`, `memory`, `continuations`): each writes exactly one stdout JSON object with a top-level `ok: boolean` — exit `0` when ok, `1` when it ran but failed, `2` for a usage error.
+
 From a separate orchestration folder, validate a downstream consumer without changing cwd:
 
 ```bash
@@ -41,6 +43,26 @@ mono-agent start
 
 Every channel the user asked for must report `running` with its endpoint facts; anything `failed` is a blocker, not a footnote.
 
+On macOS, managed start also installs a no-`KeepAlive` recovery helper that runs
+at login and every five minutes. It safely reconciles an inactive worker, a
+changed keyed snapshot, or a different available controller CLI closure without
+executing mutable source bytes. The existing worker stays live during runtime
+installation; failed recovery preserves the helper and both definitions for the
+next scheduled retry. `mono-agent stop` removes that authority, so an explicitly
+stopped agent is not resurrected.
+
+Confirm the authoritative process boundary with:
+
+```bash
+mono-agent status --json
+```
+
+Treat `ok: true` as proof only because the status command now requires the trace
+PID to be alive and equal launchd's current PID. When launchd has no matching
+live process, cached `running` channels are rendered `stopped`, live endpoint
+facts are omitted, `pid` is `null`, and the command exits 1. Do not interpret an
+old trace manifest by itself as a running consumer.
+
 ## Documentation Validation
 
 To confirm a skills folder is indexable (replace `<skillsRoot>` with the
@@ -94,8 +116,8 @@ pnpm run test:demo
 | Surface | Smoke |
 | --- | --- |
 | 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 that uses a tool; verify one transient activity ledger is replaced by the final reply. |
-| Slack | Send one allowed DM or channel message that uses a tool; verify formatting and one transient activity ledger replaced by the final reply. |
+| Telegram | Send one allowed chat message that uses a tool; verify the final reply arrives as a new message and the transient activity ledger is deleted. |
+| Slack | Send one allowed DM or channel message that uses a tool; verify formatting, a fresh final reply, and deletion of the transient activity ledger. Open `@agent /model`, choose a configured option, and verify DM-wide or shared-channel-thread-local scope as appropriate. |
 | 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`. |