@mono-agent/agent-app 0.11.2 → 0.11.4

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

@@ -5,7 +5,7 @@
 > <https://mono-agent-docs.vercel.app/config/>. This annotated JSON
 > stays the offline canonical shape.
 
-One `mono-agent.config.json` declares the whole agent. Paths are relative to the folder; every field also has a `MONO_AGENT_*` env var that overrides it (env > JSON > defaults). Omit a section to leave that capability off — every section except `runtime.model` and `context.identityPath` is optional. `references/feature-coverage.md` maps every framework feature to its config key; if a capability is not listed there, it needs the programmatic escape hatch.
+One `mono-agent.config.json` declares the whole agent. Paths are relative to the folder; config fields may be JSON-only. Environment-variable overrides are optional: only fields with a documented `MONO_AGENT_*` mapping accept one (env > JSON > defaults), so consult the generated config reference's `Env override` column (`--` means none, as for `channels.plugins`) instead of inferring one. Omit a section to leave that capability off — every section except `runtime.model` and `context.identityPath` is optional. `references/feature-coverage.md` maps every framework feature to its config key; if a capability is not listed there, it needs the programmatic escape hatch.
 
 ## Folder Layout
 
@@ -27,26 +27,46 @@ my-agent/
 
 ## Annotated Config
 
+New configs use `runtime.fallbacks[]`, where each route owns its optional exact
+effort. Legacy `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` remain
+supported compatibility inputs with no removal deadline; do not emit them for a
+new agent.
+
 ```jsonc
 {
   // Runtime: primary model plus ordered backups tried on retryable provider
   // failures (failover is reported in run results, never silent).
   "runtime": {
     "model": "claude:claude-sonnet-4-6",   // claude:* | codex:* | pi:<provider>:<model>
-    "fallbackModels": ["pi:ollama:gemma4:31b"],
+    "fallbacks": [{ "model": "pi:ollama:gemma4:31b" }],
+    "routeSafety": "uniform",              // uniform | per-route-native
     "executionMode": "sdk",                // sdk | cli (default inferred from model)
-    "effort": "medium",                    // none|low|medium|high|xhigh|max; omit for direct opencode:*
+    "effort": "medium",                    // none|minimal|low|medium|high|xhigh|max|ultra; omit for direct opencode:*
+                                           // Reasoning-capable pi:* maps ultra to LOW; Pi without reasoning uses OFF.
+                                           // Direct codex:* forwards ultra unchanged. Mono-agent rejects ultra on its Claude SDK route
+                                           // because the pinned SDK public contract ends at max (the SDK JavaScript itself forwards the value).
+                                           // The Claude CLI route passes --effort ultra, but both tested Claude Code binaries
+                                           // (SDK-bundled 2.1.206 and local 2.1.210) warn that it is unknown, ignore it, and use default effort.
+                                           // Direct OpenCode rejects explicit effort.
+                                           // Ranking above max only prevents keyword downgrade.
     "permissionMode": "default",           // default|plan|acceptEdits|bypassPermissions (CLI backends)
     "maxTurns": 0,                         // 0 or omitted means unlimited; 1-100 caps turns
     "workspace": ".",
     "session": { "mode": "continuous", "idleTimeoutMs": 1800000 } // or "per-message"
   },
 
+  // Per-channel admission/execution bounds. Each enabled channel owns one limiter.
+  "concurrency": {
+    "maxConcurrentRuns": 4,
+    "maxPendingRuns": 100
+  },
+
   // Local/self-hosted providers for pi:<provider>:<model> references.
   "providers": {
     "piAuthPath": "~/.pi/agent/auth.json", // Pi OAuth credentials (openai-codex, ...)
     // Pi-native bridge tuning (all optional).
     "piNative": {
+      "transport": "auto",                // auto | sse | websocket | websocket-cached
       "piMaxRetries": 2,                   // 0-8; transient provider-transport retries
       "maxRetryDelayMs": 60000,            // backoff cap between retries (ms)
       "piSessionsRoot": ".mono-agent/sessions" // durable JSONL sessions → resume across restarts (unset = in-memory)
@@ -58,7 +78,9 @@ my-agent/
         "baseUrl": "http://localhost:11434",
         "enabled": true,
         "trustPublicUrl": false,           // explicit opt-in for non-private URLs
-        "apiKeyEnv": "MY_PROVIDER_KEY",    // or inline "apiKey" (untracked file only)
+        // Keep the key in .env; config stores only its variable name.
+        // Inline "apiKey" remains schema-compatible for existing consumers.
+        "apiKeyEnv": "MY_PROVIDER_KEY",
         "models": [{ "name": "gemma4:31b", "capabilities": { "context_window": 32768 } }]
       }
     ]
@@ -73,16 +95,19 @@ my-agent/
     "skillMaxBytes": 48000                 // per-skill byte cap (256-1,000,000)
   },
 
-  // Memory strategy. Omit the section for no memory.
+  // Memory strategy. Omit the section for no memory. The built-in "bujo"
+  // backend owns the three local tiers below; "supermemory" selects the
+  // separately installed, lockstep @mono-agent/memory-supermemory plugin.
   // Three tiers over one substrate (@mono-agent/memory store + bujo subpaths):
   //   lite    — FTS keyword recall + rapid-log; no external deps.
-  //   journal — + hybrid recall (BM25+vector) + decay; needs embeddings.
+  //   journal — + hybrid recall (BM25+vector) + static, non-decaying salience; needs embeddings.
   //   bujo    — + LLM capture/reconcile + entity graph + auto-scheduled
   //             lightweight consolidation; needs embeddings + an app-level memory.llm for capture/tier selection.
   "memory": {
+    "backend": "bujo",                    // bujo (default) | supermemory
     "mode": "bujo",                        // lite | journal | bujo
     "path": "./.mono-agent/memory",        // root directory for all tiers
-    "writeMode": "capture",                // disabled | append-host-summary | capture (bujo only)
+    "writeMode": "capture",                // disabled | append-host-summary | capture (bujo tier or external backend)
     "maxBytes": 64000,
     "embeddings": {                        // required for journal and bujo
       "provider": "ollama",                // ollama | lmstudio | openai; exclusive, no fallback
@@ -100,7 +125,17 @@ my-agent/
     },
     // Bujo auto-scheduler — override the default or disable it.
     // Consolidation runs in-app; no external cron or launchd needed.
-    "consolidation": { "enabled": true, "cron": "0 */2 * * *" } // default: every two hours
+    "consolidation": { "enabled": true, "cron": "0 */2 * * *" }, // default: every two hours
+    // For backend: "supermemory", omit path/mode/embeddings/llm/consolidation
+    // and configure the external service instead. Keep API keys in env.
+    // "supermemory": {
+    //   "baseUrl": "http://127.0.0.1:6767",
+    //   Inline "apiKey" remains schema-compatible; source configs use apiKeyEnv.
+    //   "apiKeyEnv": "SUPERMEMORY_API_KEY",
+    //   "container": "my-agent",
+    //   "timeoutMs": 10000,
+    //   "exposeMcpServer": false
+    // }
   },
 
   // Tool policy (allow-all by default) + MCP servers. Deny wins; overlap is rejected.
@@ -110,6 +145,17 @@ my-agent/
     "mcpConfigPath": "./mcp.json"          // stdio/sse/http servers; inlined for SDK runtimes
   },
 
+  // Human-in-the-loop bridge: blocking AskUser / TelegramAskButtons 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
+  // tools.mcpRequestContextServers names at least one opted project MCP server.
+  "interaction": {
+    "bridge": { "host": "127.0.0.1", "port": 0 },
+    "askUser": { "timeoutMs": 600000 },
+    "progress": { "enabled": true }
+  },
+
   // Sandbox for Pi-owned runtime commands. Direct Codex uses its own sandbox;
   // Claude/direct OpenCode cannot enforce these exact srt scopes. All reject
   // this block (pi:opencode-go:* remains a Pi route).
@@ -123,8 +169,10 @@ my-agent/
     "unsafeAllowHostProcess": false        // explicit opt-in required for the unsafe fallback
   },
 
-  // Observability: JSONL artifacts (always written; the local fallback) + the
-  // trace-source registry that `mono-agent status` reads.
+  // Observability: the recorder writes empty events + a running summary at start,
+  // buffers key-redacted/capped events in RAM, then replaces both files at finish/fail.
+  // A pre-terminal crash can lose buffered events. `mono-agent status` reads the
+  // separate trace-source registry.
   "artifacts": {
     "dir": "./.mono-agent/artifacts",
     "retention": { "maxAgeDays": 365, "maxCount": 50000, "dryRun": false },
@@ -142,11 +190,12 @@ my-agent/
     "globalDiscovery": true
   },
 
-  // Optional trace viewer: add a Phoenix (OTLP) exporter to browse traces in
-  // Phoenix. Omit this entry to keep only the local JSONL artifacts.
+  // Optional trace viewer: add a best-effort, terminal-batched Phoenix (OTLP)
+  // exporter. Omit it to keep only bounded local terminal JSONL snapshots; a
+  // pre-terminal crash can lose buffered events.
   "observability": {
     "exporters": [
-      { "type": "phoenix", "endpoint": "http://127.0.0.1:6006/v1/traces" }
+      { "type": "phoenix", "endpoint": "http://127.0.0.1:6006/v1/traces", "contentPatternRedaction": false }
     ]
   },
 
@@ -159,8 +208,7 @@ my-agent/
     "host": "127.0.0.1",
     "port": 0,
     "basePath": "/tui",
-    "allowNonLoopback": false,
-    "apiKey": "optional-bearer"
+    "allowNonLoopback": false              // set MONO_AGENT_TUI_API_KEY in .env when needed
   },
 
   "live": {
@@ -168,19 +216,36 @@ my-agent/
     "host": "127.0.0.1",
     "port": 0,
     "basePath": "/live",
-    "allowNonLoopback": false,
-    "apiKey": "optional-bearer"
+    "allowNonLoopback": false              // set MONO_AGENT_LIVE_API_KEY in .env when needed
   },
 
   "webhook": {
+    // For bearer auth, put MONO_AGENT_WEBHOOK_API_KEY=<strong-random-secret> in
+    // the owner-only .env file; JSON strings are literal and do not interpolate env: values.
     "enabled": true,
     "host": "127.0.0.1",                   // loopback-only unless allowNonLoopback
     "port": 0,                             // 0 picks a free port
     "path": "/webhook/invoke",
-    "allowNonLoopback": false,
+    "allowNonLoopback": false,             // a non-loopback bind also requires the .env key
     "defaultMode": "sync",                 // sync | async (202 + status URL polling)
+    "endpoints": [
+      {
+        "name": "invoke",
+        "path": "/webhook/invoke",
+        "mode": "sync",
+        "prompt": "Respond to this request:",
+        "model": "claude:claude-sonnet-4-6", // optional per-trigger override
+        "effort": "high",                  // same eight-level effort enum as runtime
+        "maxRunMs": 3600000,               // endpoint override; 0 disables only this watchdog
+        "notify": true,                     // deliver the successful final answer verbatim
+        // Explicit destination; if omitted, infer only with exactly one candidate.
+        // Zero or multiple candidates skip with a warning.
+        "notifyConversationId": "slack:C0123"
+      }
+    ],
     "retentionMs": 300000,                 // async status retention
-    "maxStoredRequests": 100
+    "maxStoredRequests": 100,
+    "maxRunMs": 1200000                    // fallback when an endpoint omits maxRunMs
   },
 
   "openaiApi": {
@@ -199,20 +264,40 @@ my-agent/
   // stream.finalOnly=false. The OpenAI-compatible endpoint still streams tokens.
   "telegram": {
     "enabled": true,                       // opt-in; defaults to false (off → "disabled")
-    "botToken": "...",
+    // Put MONO_AGENT_TELEGRAM_BOT_TOKEN in .env; do not inline botToken here.
     "allowedChatIds": ["123456789"],       // or "allowAllChats": true
     "allowAllChats": false
   },
 
   "slack": {
     "enabled": true,                       // opt-in; defaults to false (off → "disabled")
-    "botToken": "xoxb-...",                // Socket Mode app
-    "appToken": "xapp-...",
+    // 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
     "mentionTextAliases": ["@agent"],
-    "stripMentionText": true
+    "stripMentionText": true,
+    "shortcuts": [                         // slack.shortcuts: JSON-only; callbackId matches the Slack app
+      {
+        "callbackId": "triage_request",
+        "prompt": "Prepare the daily support triage checklist.",
+        "channelId": "C0123",
+        "ackText": "Triage started…",
+        "threadReply": true
+      }
+    ],
+    "homeTab": {                           // slack.homeTab: JSON-only; enable App Home + app_home_opened
+      "enabled": true,
+      "headerText": "*Quick actions*",
+      "buttons": [
+        {
+          "actionId": "build_digest",
+          "label": "Build digest",
+          "prompt": "Build today's team digest.",
+          "channelId": "C0123"
+        }
+      ]
+    }
   },
 
   "channels": {
@@ -241,9 +326,9 @@ my-agent/
             "host": "127.0.0.1",
             "port": 4201,
             "publicBaseUrl": "https://agent.example.com",
-            "allowNonLoopback": false,
+            "allowNonLoopback": true,
             "requireBearer": false,
-            "bearerToken": "...",
+            // Put MONO_AGENT_A2A_BEARER_TOKEN in .env when bearer auth is required.
             "idempotency": {              // optional; namespace explicitly enables the v1 extension
               "namespace": "my-agent-production", // stable authenticated-principal boundary
               "stateDir": ".mono-agent/a2a-my-agent", // optional derived owner-only path when omitted
@@ -256,7 +341,7 @@ my-agent/
           "consumer": {                    // settings for calling remote A2A agents
             "remoteAgentUrls": ["http://127.0.0.1:4202"],
             "defaultRemoteAgentUrl": "http://127.0.0.1:4202",
-            "bearerToken": "...",
+            // Put MONO_AGENT_A2A_CONSUMER_BEARER_TOKEN in .env when the remote requires auth.
             "timeoutMs": 30000
           }
         }
@@ -273,11 +358,20 @@ my-agent/
         "expression": "0 9 * * *",         // five-field cron
         "timezone": "UTC",                 // IANA timezone
         "prompt": "Post the morning summary.",
-        "conversationId": "cron-daily"     // optional: share memory/history across ticks
+        "conversationId": "cron-daily",    // optional: share memory/history across ticks
+        "model": "claude:claude-sonnet-4-6", // optional per-trigger override
+        "effort": "high",
+        "notify": true,                     // successful non-empty final answer is delivered verbatim
+        // Explicit destination; if omitted, infer only with exactly one candidate.
+        // Zero or multiple candidates skip with a warning.
+        "notifyConversationId": "slack:C0123",
+        // Model-exhaustion notices require this explicit destination; never infer.
+        "notifyFailureCooldownHours": 6
       }
     ]
     // Jobs here merge with cron/*.md files (duplicate ids error).
-    // Overlapping ticks of the same job are skipped, never queued.
+    // Agent-app pins overlap to skip; config exposes no queue/replace controls.
+    // Overlapping ticks of the same configured job are therefore skipped, never queued.
   }
 }
 ```
@@ -288,7 +382,7 @@ my-agent/
 mono-agent presets list                 # saved answer-sets (id, risk, description)
 mono-agent presets show <id>            # generated config + .env.example + follow-up checklist
 mono-agent init --preset <id> --yes [--with slack,cron] [--dry-run]   # scaffold from a preset (non-interactive)
-mono-agent init --model claude:claude-sonnet-4-6 --fallback-models pi:ollama:gemma4:31b [--memory lite|journal|bujo]
+mono-agent init --model claude:claude-sonnet-4-6 --fallback pi:ollama:gemma4:31b [--memory lite|journal|bujo]
 mono-agent config       # resolved config field-by-field, each value tagged env/json/default
 mono-agent validate [--preset <id>] [--consumer <path>]     # per-section report; --preset also checks the preset's capabilities
 mono-agent start        # traceability + every configured channel

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

@@ -16,7 +16,7 @@ Which model should drive the agent, and should any backups take over when the pr
 5. A custom MonoRuntimeLike supplied programmatically (escape hatch)
 ```
 
-Fills: `runtime.model`, `runtime.fallbackModels` (ordered backup references tried on retryable provider failures), `runtime.executionMode` (usually inferred), `runtime.effort`, `runtime.maxTurns`. Keep a direct `codex:*` chain all-direct. Pi, Claude, and direct OpenCode may mix only with `sandbox` omitted/off; if native mono-agent sandboxing is selected, every primary/fallback/trigger model must stay on Pi (`pi:opencode-go:*` is Pi). Direct `opencode:*` is advanced scaffold/config-only, requires exact allow-all plus an explicit native `permissionMode`, and must omit `runtime.effort` under SDK 1.x.
+Fills: `runtime.model`, canonical `runtime.fallbacks[]` (ordered backup routes tried on retryable provider failures, each with optional exact effort), `runtime.executionMode` (usually inferred), `runtime.effort`, `runtime.maxTurns`. Legacy `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` remain supported with no removal deadline, but do not emit them for a new agent. Keep a direct `codex:*` chain all-direct. Pi, Claude, and direct OpenCode may mix only with `sandbox` omitted/off; if native mono-agent sandboxing is selected, every primary/fallback/trigger model must stay on Pi (`pi:opencode-go:*` is Pi). Direct `opencode:*` is advanced scaffold/config-only, requires exact allow-all plus an explicit native `permissionMode`, and must omit `runtime.effort` under SDK 1.x.
 
 The interactive `mono-agent init` wizard discovers Pi OpenAI-Codex auth, OpenCode models, Ollama models, and LM Studio's local server best-effort. It defaults to direct `codex:gpt-5.6-terra` and presents both `pi:openai-codex:gpt-5.6-terra` and `pi:openai-codex:gpt-5.6-sol` as concrete selectable candidates. Direct `codex:gpt-5.6-sol` is also selectable; direct GPT-5.6 routes require Codex CLI 0.144.0 or newer. The wizard maps discovered OpenCode options to `pi:opencode-go:<model>` for setup/preflight, and auto-adds local provider modules when a primary or fallback model uses `pi:ollama:*` or `pi:lmstudio:*`. Recover missing Pi OAuth with `mono-agent auth login <provider>` (and `--pi-auth-path` when required). Direct `opencode:<provider>:<model>` refs are supported only as hand-authored runtime backend config; do not present them as a first-class composer or init wizard selection. For local models also fill `providers.local` (e.g. an Ollama or LM Studio base URL plus model capabilities). Follow-up only if needed: continuous provider session per conversation (`runtime.session.mode: "continuous"`, default) versus stateless per-message.
 
@@ -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 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 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
 
@@ -88,7 +88,7 @@ Should the agent remember anything between conversations?
 
 1. No durable memory yet (recommended for first integration)
 2. Lite memory — FTS keyword recall + rapid-log capture; zero external deps
-3. Journal memory — hybrid recall (BM25+vector) + salience decay; requires embeddings
+3. Journal memory — hybrid recall (BM25+vector) + static salience; requires embeddings
 4. BuJo memory — full tier: journal + LLM capture/reconcile + entity graph + auto-scheduled
    consolidation; requires embeddings AND a chat model
 ```
@@ -149,9 +149,11 @@ stopping the agent and running config-aware `mono-agent memory rebuild --json`.
 **Tier 4 — bujo (embeddings + chat model + consolidation):**
 
 Proactively explain what bujo does: capture → reconcile (ADD/UPDATE/SUPERSEDE/NOOP),
-hybrid BM25+vector recall, entity graph, scheduled consolidation (decay + duplicate
-superseding), living `index.md`, and an empty retired `future-log.md` stub. Consolidation
-is **auto-scheduled in-app** — no external cron or launchd setup needed.
+hybrid BM25+vector recall, entity graph, scheduled projection-only consolidation, living
+`index.md`, and an empty retired `future-log.md` stub. Consolidation refreshes projections
+and reports duplicate groups; it never decays salience or automatically supersedes or
+rewrites canonical memory. It is **auto-scheduled in-app** — no external cron or launchd
+setup needed.
 
 - Ask: which embeddings provider/service-root/model/dimension/auth-env? Use the same
   exclusive choices and real-probe contract as journal.
@@ -242,10 +244,10 @@ Question:
 Do you need a browsable trace viewer or just local artifacts?
 
 1. JSONL artifacts plus Phoenix as the trace viewer (recommended; add an `observability.exporters` Phoenix entry)
-2. JSONL artifacts only (the local fallback; no external viewer)
+2. JSONL artifacts only (bounded terminal snapshots; no external viewer)
 ```
 
-Fills: `artifacts.dir`, `traceability.registryDir` / `sourceId` / `sourceLabel`, and — when Phoenix is wanted — an `observability.exporters` (phoenix) OTLP entry. Local JSONL artifacts are always written and are the fallback when no exporter is configured. Artifacts record runtime/tool/message events and summaries, not private chain-of-thought. For a terminal operator console, mention `mono-agent tui` (run from anywhere once the agent is started; live chat with thinking/tool insight, run replay, config view). Config is JSON-first — edit `mono-agent.config.json` directly and run `mono-agent restart` to apply changes.
+Fills: `artifacts.dir`, `traceability.registryDir` / `sourceId` / `sourceLabel`, and — when Phoenix is wanted — an `observability.exporters` (phoenix) OTLP entry. The local recorder starts with empty events plus a `running` summary, applies key-based redaction and caps event strings at 4,096 bytes by default, buffers events in RAM, and replaces the artifacts at finish/fail; a pre-terminal crash can lose buffered events. Phoenix adds a best-effort terminal batch, not a crash-safe stream. Artifacts record runtime/tool/message events and summaries, not private chain-of-thought. For a terminal operator console, mention `mono-agent tui` (run from anywhere once the agent is started; live chat with thinking/tool insight, run replay, config view). Config is JSON-first — edit `mono-agent.config.json` directly and run `mono-agent restart` to apply changes.
 
 ## 9. Acceptance Smoke Test