@mono-agent/agent-app 0.13.0 → 0.14.0

package/package.json

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

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

@@ -1220,7 +1220,7 @@
           "additionalProperties": false,
           "properties": {
             "host": {
-              "description": "Loopback host for the app-owned AskUser/tool-progress bridge.",
+              "description": "Bind host for the app-owned AskUser/tool-progress bridge. Defaults to loopback; keep it local because non-loopback values are not rejected.",
               "examples": [
                 "127.0.0.1"
               ],
@@ -1242,7 +1242,7 @@
           "additionalProperties": false,
           "properties": {
             "timeoutMs": {
-              "description": "Maximum wait for one AskUser question.",
+              "description": "Maximum wait for one AskUser interaction (one to five questions).",
               "examples": [
                 600000
               ],

package/skills/mono-agent-composer/SKILL.md

@@ -9,7 +9,7 @@ Construct a working mono-agent in the user's current folder — empty or already
 
 ## Authoritative Sources — Search, Then References, Never Package Source
 
-When the `search_mono_agent_docs` MCP tool is available, use it **before** opening files or following website links. Its version-matched offline corpus contains the canonical public documentation plus the `references/*.md` bundled beside this skill. For "can it do X?", "what is the key for Y?", and "how is Z configured?", search with `scope: "composer"`; returned composer chunks have the same authority as the bundled references. Use `scope: "all"` for broader conceptual or troubleshooting questions. Results include complete Markdown excerpts, so links are provenance rather than a required second retrieval step.
+When the `mono_agent_docs` MCP tool is available, use it **before** opening files or following website links. Its version-matched offline corpus contains the canonical public documentation plus the `references/*.md` bundled beside this skill. Start with `{"action":"search","query":"...","scope":"composer"}` for "can it do X?", "what is the key for Y?", and "how is Z configured?"; use `scope: "all"` for broader conceptual or troubleshooting questions. Search excerpts are a map, not the complete answer: call `{"action":"read","target":"<readTarget>"}` on the best result, follow the returned `internalLinks` with `action: "read"`, and use exact `previousTarget` / `nextTarget` actions when a long section continues. Composer-scoped content has the same authority as the bundled references.
 
 The bundled `references/*.md` remain the source of truth and the fallback when the MCP tool is unavailable. They are maintained in lockstep with the framework and are **complete for configuration and capabilities**. If the tool's `docsVersion` differs from the installed `mono-agent` version, use search for general context but verify version-specific config and CLI details against these local references. Reformulate a weak search once before falling back; never compensate by grepping package source.
 
@@ -17,13 +17,13 @@ Do **not** read or grep the `@mono-agent` TypeScript/package source — `package
 
 - `references/feature-coverage.md` is the **exhaustive** map of every feature to a `config` key, `cli` flag, `auto` behavior, or `code`-only escape hatch. If a capability is listed `config`/`cli`, use that key/flag verbatim. If it is **not in the table, or is marked `code`**, it is not reachable through `mono-agent.config.json` — say so plainly and name the escape hatch. Absence from the table means "not configurable," never "go check the source."
 - The real exception: if the user is **modifying the framework itself** (changing `@mono-agent` package code), that is framework development, not composing an agent — outside this skill. Only then is reading `packages/*/src` correct.
-- The published docs site (<https://mono-agent-docs.vercel.app/>) is the human-facing companion. Do not browse it just to discover links: `search_mono_agent_docs` returns the indexed content directly, and the bundled references work offline when the tool is absent.
+- The published docs site (<https://mono-agent-docs.vercel.app/>) is the human-facing companion. Do not browse it just to discover links: `mono_agent_docs` searches, expands, and resolves internal links offline, and the bundled references work when the tool is absent.
 
 **Red flags — STOP, you are about to grep source you should not:**
 
 | Thought | Reality |
 | --- | --- |
-| "Let me browse the docs navigation until I find the right page." | Search `search_mono_agent_docs`; it returns the matching excerpts directly. |
+| "Let me browse the docs navigation until I find the right page." | Search with `mono_agent_docs`, read the best `readTarget`, then follow its structured `internalLinks`. |
 | "Let me verify the key name against the source." | The references give the exact key. Trust them; don't re-derive from source. |
 | "The references might be incomplete — I'll double-check `packages/.../src`." | `feature-coverage.md` is exhaustive for config/CLI. Not in it = not configurable. |
 | "I'll confirm the docs and source agree." | You are composing an agent, not auditing the framework. The references are the contract. |
@@ -31,7 +31,7 @@ Do **not** read or grep the `@mono-agent` TypeScript/package source — `package
 
 ## Operating Rules
 
-- Answer capability/config questions from `search_mono_agent_docs` with `scope: "composer"`, falling back to the bundled `references/*.md` (authoritative and complete) — never grep or read the `@mono-agent` package source to compose an agent. See "Authoritative Sources" above.
+- Answer capability/config questions through `mono_agent_docs`: search with `scope: "composer"`, read the best target, and continue through structured links/windows as needed. Fall back to the bundled `references/*.md` (authoritative and complete) — never grep or read the `@mono-agent` package source to compose an agent. See "Authoritative Sources" above.
 
 - The deliverable is a folder that works: `mono-agent.config.json` + `IDENTITY.md` (+ optional `skills/`, `mcp.json`), validated and started — not a tutorial.
 - Start by discovering the intended agent product, not by naming packages.
@@ -105,7 +105,7 @@ Config-first covers one responder served over any combination of the seven chann
 - `references/package-map.md` — which package owns what, for programmatic composition and troubleshooting.
 - `references/validation.md` — validation commands and per-channel smoke tests; read before claiming the agent works.
 
-`search_mono_agent_docs` is the primary discovery interface when present; its composer-scoped results are built from these same versioned references. The bundled `references/*` files remain authoritative and self-sufficient when the tool is absent or version-mismatched, so use them rather than package source or a remote site. The published documentation site at <https://mono-agent-docs.vercel.app/> is the human-facing companion, not an AI retrieval dependency.
+`mono_agent_docs` is the primary discovery and reading interface when present; its composer-scoped results are built from these same versioned references. Always progress from `action: "search"` to `action: "read"` before concluding from a short hit, and use the response's exact navigation actions rather than inventing chunk or page locations. The bundled `references/*` files remain authoritative and self-sufficient when the tool is absent or version-mismatched, so use them rather than package source or a remote site. The published documentation site at <https://mono-agent-docs.vercel.app/> is the human-facing companion, not an AI retrieval dependency.
 
 ## Done Criteria
 

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
@@ -409,7 +409,7 @@ 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 --clear-sessions  # restart AND purge persisted pi sessions (fresh start; durable memory kept)  [--force is a deprecated alias]
+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.

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

@@ -29,7 +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; tool `search_mono_agent_docs` searches full offline excerpts from `@mono-agent/docs-mcp` | — |
+| 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` |
@@ -54,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` |
@@ -68,7 +68,7 @@ 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 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`; `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, 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` |

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

@@ -51,7 +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 | `@mono-agent/docs-mcp` (optional plugin) | Exact-version offline hybrid semantic/BM25 search over canonical docs and composer references through `search_mono_agent_docs`; paired by `mono-agent install-skill`, outside the composed agent's own `mcp.json` |
+| 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 |
 

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

@@ -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

@@ -43,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