@mono-agent/agent-app 0.19.0 → 0.20.0

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

@@ -1556,6 +1556,93 @@
         }
       }
     },
+    "processJobs": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "stateDir": {
+          "type": "string",
+          "minLength": 1,
+          "default": ".mono-agent/process-jobs"
+        },
+        "maxConcurrent": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32,
+          "default": 4
+        },
+        "maxActivePerConversation": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8,
+          "default": 2
+        },
+        "maxQueued": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 64,
+          "default": 8
+        },
+        "maxRuntimeMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400000,
+          "default": 1800000
+        },
+        "maxQueueAgeMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3600000,
+          "default": 300000
+        },
+        "maxOutputBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8388608,
+          "default": 1048576
+        },
+        "previewChars": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8000,
+          "default": 2000
+        },
+        "maxChainDepth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8,
+          "default": 4
+        },
+        "retention": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "maxRecords": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10000,
+              "default": 1000
+            },
+            "maxAgeMs": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2592000000,
+              "default": 604800000
+            },
+            "artifactMaxBytes": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1073741824,
+              "default": 268435456
+            }
+          }
+        }
+      }
+    },
     "interaction": {
       "type": "object",
       "additionalProperties": false,
@@ -1902,6 +1989,20 @@
             }
           }
         },
+        "operatorActions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "description": "Allows API-key-authenticated, explicitly confirmed run-now and runtime enable/disable actions. Defaults off and never rewrites cron config sources.",
+              "examples": [
+                true
+              ],
+              "type": "boolean",
+              "default": false
+            }
+          }
+        },
         "enabled": {
           "description": "Enables the cron capability.",
           "examples": [
@@ -2318,7 +2419,7 @@
           }
         },
         "stripMentionText": {
-          "description": "When unset, defaults to `true` when `botUserIds` or `mentionTextAliases` is non-empty; otherwise `false`.",
+          "description": "When unset, preserves one readable authenticated self-mention marker; `true` restores legacy full stripping and `false` keeps raw mention forms.",
           "examples": [
             false
           ],

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

@@ -21,6 +21,7 @@ my-agent/
     artifacts/             # JSONL run summaries + events
     workspace/             # runtime working directory (if not ".")
     memory/                # journal memory root (daily notes, graph.jsonl, index/)
+    process-jobs/          # opt-in owner-private Exec/Bash jobs and output
     whatsapp-auth/         # Baileys auth state (WhatsApp channel only)
     trace-sources/         # traceability registry (if kept folder-local)
 ```
@@ -150,7 +151,7 @@ new agent.
 
   // Tool policy (allow-all by default) + MCP servers. Deny wins; overlap is rejected.
   "tools": {
-    "allowedTools": ["*"],                 // omit or include "*" = all tools; ["Read","Bash"] = just those; [] = none (chat-only)
+    "allowedTools": ["*"],                 // omit or include "*" = all tools; name PublishReplyFile in a restrictive list; [] = none (chat-only)
     "disallowedTools": ["Bash"],           // deny wins even under allow-all; the escape hatch to subtract one tool
     "mcpConfigPath": "./mcp.json",         // stdio/sse/http servers; inlined for SDK runtimes
     "web": {
@@ -168,6 +169,28 @@ new agent.
   // Exec is direct argv; use Bash only for shell syntax. NodeRepl shares state
   // only inside one run. All three use the same sandbox policy.
 
+  // Opt-in Pi-native Exec/Bash background jobs. The host owns the inherited
+  // POSIX process group (commands that daemonize into another group are unsupported),
+  // bounded output, exact Slack/Telegram/web wake, cancellation, and restart
+  // interruption. Unsupported on Windows; unknown keys are rejected.
+  "processJobs": {
+    "enabled": true,                       // default false
+    "stateDir": ".mono-agent/process-jobs", // relative child of the agent root
+    "maxConcurrent": 4,                   // cap 32
+    "maxActivePerConversation": 2,        // cap 8
+    "maxQueued": 8,                       // cap 64
+    "maxRuntimeMs": 1800000,              // 30 min; cap 24 h
+    "maxQueueAgeMs": 300000,              // 5 min; cap 1 h
+    "maxOutputBytes": 1048576,            // 1 MiB; cap 8 MiB
+    "previewChars": 2000,                 // cap 8000
+    "maxChainDepth": 4,                   // host-owned; cap 8
+    "retention": {
+      "maxRecords": 1000,                 // cap 10000
+      "maxAgeMs": 604800000,              // 7 d; cap 30 d
+      "artifactMaxBytes": 268435456        // 256 MiB; cap 1 GiB
+    }
+  },
+
   // 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
@@ -378,6 +401,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
     "jobs": [
       {
         "id": "daily",
@@ -421,7 +445,7 @@ A `.env` file in the folder is loaded automatically (exported shell variables wi
 
 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` 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 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); 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).
 
 ## Programmatic Escape Hatch
 

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

@@ -36,7 +36,7 @@ Where should people (or other agents) reach this agent? Pick every channel that
 7. Cron (scheduled prompts, no inbound channel)
 ```
 
-Fills one config section per choice: built-in channels use `webhook`, `openaiApi`, `telegram`, `slack`, and `cron`; WhatsApp and A2A are external channel plugins under `channels.plugins[]` with package names `@mono-agent/whatsapp-adapter` and `@mono-agent/a2a-adapter`. Channels are independent: an unconfigured channel reports `waiting_for_config` and never blocks the others. For chat channels collect tokens and allowlists (chat IDs, channel IDs, JIDs). For HTTP channels collect host/port/path and whether non-loopback binding is allowed (default: loopback only); for webhook, offer an optional bearer key on loopback and require it whenever non-loopback is selected, storing it in `MONO_AGENT_WEBHOOK_API_KEY`. For paid or otherwise non-repeatable A2A dispatches, also collect a reviewed stable `provider.idempotency.namespace` (the authenticated-principal boundary), retention horizon, and lifetime unique-key capacity; callers must supply an existing stable logical key rather than a fresh key per attempt.
+Fills one config section per choice: built-in channels use `webhook`, `openaiApi`, `telegram`, `slack`, and `cron`; WhatsApp and A2A are external channel plugins under `channels.plugins[]` with package names `@mono-agent/whatsapp-adapter` and `@mono-agent/a2a-adapter`. Channels are independent: an unconfigured channel reports `waiting_for_config` and never blocks the others. For chat channels collect tokens and allowlists (chat IDs, channel IDs, JIDs). For HTTP channels collect host/port/path and whether non-loopback binding is allowed (default: loopback only); for webhook, offer an optional bearer key on loopback and require it whenever non-loopback is selected, storing it in `MONO_AGENT_WEBHOOK_API_KEY`. For cron, collect the expression, timezone, prompt, and notification destination; ask separately whether the operator may run or runtime-disable jobs from the web console, keeping `cron.operatorActions.enabled` false unless explicitly requested and requiring `tui.apiKey` when enabled. For paid or otherwise non-repeatable A2A dispatches, also collect a reviewed stable `provider.idempotency.namespace` (the authenticated-principal boundary), retention horizon, and lifetime unique-key capacity; callers must supply an existing stable logical key rather than a fresh key per attempt.
 
 ## 3. Identity And Existing Knowledge
 
@@ -77,7 +77,7 @@ What tools does the agent need?
 Plus, independently: MCP servers from an mcp.json config file?
 ```
 
-Fills: `tools.allowedTools`, `tools.disallowedTools` (denylist wins, even under allow-all), `tools.mcpConfigPath`. The default is allow-all (`["*"]`) — write that unless the user asks to narrow. Under allow-all the adapter-derived send tools (`SlackSendMessage` / `TelegramSendMessage` / …) are auto-available once the channel is enabled; only a **specific** allowlist needs their exact names added. Valid enabled Slack/Telegram adapter config and destination allowlists are required either way. On the pi-native runtime `disallowedTools` does not filter external MCP-server tools — to withhold one, don't declare its server.
+Fills: `tools.allowedTools`, `tools.disallowedTools` (denylist wins, even under allow-all), `tools.mcpConfigPath`. The default is allow-all (`["*"]`) — write that unless the user asks to narrow. Under allow-all the adapter-derived send tools (`SlackSendMessage` / `TelegramSendMessage` / …) and `PublishReplyFile` are auto-available once their host requirements are met; only a **specific** allowlist needs their exact names added. Valid enabled Slack/Telegram adapter config and destination allowlists are required either way. If the user needs MCP Apps, select a Pi-native primary and only Pi-native fallbacks: the host suppresses App registration and advertising when any possible route cannot carry the bridge. On the pi-native runtime `disallowedTools` does not filter external MCP-server tools — to withhold one, don't declare its server.
 
 For Pi process work, prefer the `Exec` built-in for one executable plus literal
 argv and offer `Bash` only when shell syntax is required. Offer `NodeRepl` when

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

@@ -54,8 +54,10 @@ 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. 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}` selects strict/first-choice loopback SearXNG or public no-credentials fallbacks; `tools.web.fetch.{render,browserCommand}` keeps static extraction as the default and optionally enables isolated agent-browser rendering; transient-fetch retry behavior is automatic rather than config-bearing | `runtime.web-research` |
 | MCP servers (stdio/sse/http) from a JSON file | config | `tools.mcpConfigPath` | `tool-policy.mcp-servers` |
+| 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` |
@@ -84,8 +86,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 | 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` |
 | 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 | `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/`); queue/replace controls are programmatic-only `startCronAdapter` options | `cron.scheduled-prompts` |
+| 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` |
@@ -99,8 +101,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 | JSONL run artifacts (events + summaries; strings capped; non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; retained free text is scanned for a closed set of high-confidence credential shapes) | 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 (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 and same-thread quotes, live active-agent skill discovery with canonical `$skill-name` insertion, 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`; 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`; 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 | — |
+| 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, 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 | — |
 | 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 | — |

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

@@ -82,6 +82,22 @@ 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.
 
+`RunHistory` and `SessionHistory` are app-owned request-scoped read tools, not
+entries for `mcp.json`. `SessionHistory` searches the current logical session's
+retained managed-tool calls/results and needs no config key. Allow-all exposes
+it on compatible routes; a specific allowlist must name `SessionHistory`.
+Direct OpenCode/ACP retain and cold-project lifecycle evidence but cannot expose
+that request-scoped tool.
+`@mono-agent/agent-app` also owns rich reply composition. `PublishReplyFile`
+copies a confined generated file into owner-private integrity storage and is
+available under allow-all (or by exact name in a restrictive policy). Supported
+Pi-native MCP tool results can register their declared MCP App UI resource for
+the web console. An all-Pi route chain is required for Apps; direct or fallback
+routes that cannot carry the bridge do not advertise it. Adapters consume the
+shared reply-part contract: Slack and Telegram confirm native uploads, the web
+serves authorized downloads and sandboxed Apps, and machine/verbatim adapters
+preserve answer text when they cannot represent a part.
+
 ```ts
 import { createToolPolicy, toolPolicyToRuntimeOptions } from "@mono-agent/agent-harness";
 
@@ -102,8 +118,8 @@ Communication adapters are edge packages. They accept an `AgentResponder` and ow
 
 | Surface | Package | First smoke |
 | --- | --- | --- |
-| Telegram | `@mono-agent/telegram-adapter` | Allowed chat sends a message |
-| Slack | `@mono-agent/slack-adapter` | Allowed channel or DM gets the final reply |
+| Telegram | `@mono-agent/telegram-adapter` | Allowed chat receives text and a generated reply file through `sendDocument` |
+| Slack | `@mono-agent/slack-adapter` | Allowed channel or DM receives text and a generated reply file through the external upload flow |
 | 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 endpoint | `@mono-agent/operator-adapter` | `mono-agent tui` and `mono-agent web` connect for chat |
@@ -118,7 +134,7 @@ 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 sensitive-key-redacted, credential-scanned, 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 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/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, integrity-checked reply downloads, confirmation-gated MCP Apps in a double-frame sandbox, 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/operator-adapter` for the loopback NDJSON stream endpoint the TUI and web chat console connect to (`tui` 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`.
 

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

@@ -273,20 +273,20 @@ per-route form for a new agent.
 ## 15. Interactive agent with long jobs and large media
 **For:** a builder whose Telegram agent needs to ask before acting, run multi-minute tools, and exchange large files.
 **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`.
+**Features:** `telegram.long-polling`, `agent-app.adapter-send-tools`, `agent-app.rich-replies`, `interaction.ask-user`, `interaction.progress`, `tool-policy.mcp-servers`.
 
 **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
 {
   "runtime": { "model": "pi:openai-codex:gpt-5.5", "executionMode": "sdk" },
-  "tools": { "allowedTools": ["Read", "AskUser", "TelegramSendFile"], "mcpConfigPath": "./.mcp.json", "mcpCallMaxTotalTimeoutMs": 2700000 },
+  "tools": { "allowedTools": ["Read", "AskUser", "TelegramSendFile", "PublishReplyFile"], "mcpConfigPath": "./.mcp.json", "mcpCallMaxTotalTimeoutMs": 2700000 },
   "interaction": { "bridge": { "host": "127.0.0.1", "port": 4471 }, "askUser": { "timeoutMs": 600000 }, "progress": { "enabled": true } },
   "telegram": { "enabled": true, "allowedChatIds": ["123456789"], "apiRoot": "http://127.0.0.1:8081", "attachments": { "maxBytes": 268435456, "maxUploadBytes": 268435456 } }
 }
 ```
 **Steps:** run a loopback self-hosted Bot API server if files exceed 20 MB, wire a long-running MCP tool in `.mcp.json`, `validate`, `start`.
-**Smoke:** send media with no caption, answer the `AskUser` question, watch progress update during the long job, and receive the generated file via `TelegramSendFile`.
+**Smoke:** send media with no caption, answer the `AskUser` question, watch progress update during the long job, and receive both an explicit `TelegramSendFile` send and a final generated reply file published with `PublishReplyFile` as native documents.
 
 ## 16. Local-first web research agent
 **For:** a researcher wanting operator-owned search infrastructure and bounded public-page extraction.

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

@@ -116,8 +116,9 @@ 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 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. |
+| 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. When generated reply files are required, call `PublishReplyFile` and verify one native document arrives at the exact reply target. |
+| 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. When generated reply files are required, call `PublishReplyFile` and verify the external upload completes in the exact channel/thread. Open `@agent /model`, choose a configured option, and verify DM-wide or shared-channel-thread-local scope as appropriate. |
+| Web rich replies | In the web console, download one generated reply file and verify its name, size, and content. For an MCP App on an all-Pi route chain, verify the App appears connected, a tool call shows the bounded/redacted confirmation preview, keyboard focus stays in the modal, and a denied action leaves the App isolated. |
 | 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`. |
@@ -126,6 +127,7 @@ pnpm run test:demo
 | Cron | Run a one-off scheduled invocation or wait for one tick. |
 | Observability | Confirm a run writes a JSONL artifact with strings capped: non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; retained free text is scanned for a closed set of high-confidence credential shapes. If an `observability.exporters` Phoenix entry is set, confirm the trace appears in Phoenix. |
 | Memory recall tool | With any memory tier configured (`memory.recallTool.enabled` defaults on), ask the agent to recall an old note and confirm `MemoryRecall` appears separately from action-tool allowlists and returns it. |
+| Session tool history | Complete a managed tool call, start a later cold turn in the same logical conversation, and confirm its bounded path-opaque call/result projection is available. After compaction, use `SessionHistory.search` then `get`; verify another conversation and the current run remain unavailable. A crash-dangling call must recover once as `interrupted` without rerun, while a clean writer shutdown must not be reported as crash recovery. |
 | Web research | Run `mono-agent validate` and require the Web search & fetch section to prove configured loopback SearXNG plus `agent-browser >=0.33.1` when rendering is enabled. Then ask for two query variants and one official-page fetch; require canonical ranked URLs, untrusted-content boundaries, and bounded timing metadata without query/URL leakage. |
 | Semantic memory search | With `memory.embeddings` set, first prove the configured provider only: Ollama model advertises `embedding` through `/api/show` and answers `/api/embed`, or LM Studio model has exact `type: "embedding"` in `/api/v1/models` and answers `/v1/embeddings`. Verify the finite vector dimension matches config, then ask a paraphrased question about an old note and confirm `MemoryRecall` returns it. Never accept a cross-provider fallback as proof. |