@mono-agent/agent-app 0.20.11 → 0.21.0

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

@@ -35,32 +35,19 @@
         "model": {
           "description": "Configures model for the runtime section.",
           "examples": [
-            "codex:gpt-5.6-terra"
+            "openai-codex:gpt-5.6-terra"
           ],
           "type": "string"
         },
-        "fallbackModels": {
-          "description": "Legacy fallback list whose routes inherit runtime.effort. Prefer runtime.fallbacks for new configs.",
-          "examples": [
-            [
-              "pi:ollama:gemma4:31b"
-            ]
-          ],
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "default": []
-        },
         "fallbacks": {
           "description": "Canonical ordered fallback routes. Omitted per-route effort means that provider's default.",
           "examples": [
             [
               {
-                "model": "codex:gpt-5.6-sol"
+                "model": "openai-codex:gpt-5.6-sol"
               },
               {
-                "model": "pi:openai-codex:gpt-5.6-terra",
+                "model": "anthropic:claude-sonnet-4-6",
                 "effort": "high"
               }
             ]
@@ -135,28 +122,8 @@
             }
           }
         },
-        "routeSafety": {
-          "description": "Uniform preserves one shared safety contract; per-route-native uses and reports each provider's explicit contract.",
-          "examples": [
-            "per-route-native"
-          ],
-          "type": "string",
-          "default": "uniform",
-          "enum": [
-            "uniform",
-            "per-route-native"
-          ]
-        },
-        "executionMode": {
-          "description": "Configures executionMode for the runtime section.",
-          "examples": [
-            "inferred"
-          ],
-          "type": "string",
-          "default": "inferred"
-        },
         "effort": {
-          "description": "Route-specific effort. 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.",
+          "description": "Route-specific effort forwarded through Pi to the selected provider. Doctor warns when a configured value falls outside the model's advertised ladder but keeps turn-time handling permissive. Ranking above max only prevents keyword downgrade.",
           "examples": [
             "medium"
           ],
@@ -321,7 +288,7 @@
       ]
     },
     "subagents": {
-      "description": "Subagent profiles the Agent tool can deploy, plus its caps. Disabled unless enabled is true, in which case Agent must also appear in tools.allowedTools. Each definition needs exactly one of prompt or promptPath; omitted allowedTools means a read-only default set, and the \"*\" wildcard is rejected. The agent may also author a specialized subagent at call time unless inline.enabled is false; inline.allowedTools caps what an authored subagent may request, defaulting to the parent agent's own built-ins.",
+      "description": "Subagent profiles the Agent tool can deploy, plus its caps. Disabled unless enabled is true, in which case Agent must also appear in tools.allowedTools. Each definition needs exactly one of prompt or promptPath; omitted allowedTools means a read-only default set, and the \"*\" wildcard is rejected. The agent may also author a specialized subagent at call time unless inline.enabled is false; inline.allowedTools caps what an authored subagent may request, defaulting to the parent agent's own built-ins. maxConcurrent is a ceiling, not a scheduling guarantee: Pi 0.85 serializes all tool calls when any stateful/mutating or MCP tool is offered.",
       "examples": [
         {
           "enabled": true,
@@ -751,14 +718,7 @@
             "model": {
               "description": "Configures llm.model for the memory section.",
               "examples": [
-                "pi:openai-codex:gpt-5.6-terra"
-              ],
-              "type": "string"
-            },
-            "executionMode": {
-              "description": "Configures llm.executionMode for the memory section.",
-              "examples": [
-                "example"
+                "openai-codex:gpt-5.6-terra"
               ],
               "type": "string"
             },
@@ -788,6 +748,20 @@
           }
         },
         "recallTool": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "description": "Enables explicit memory reads: targeted MemoryRecall for every backend and chronological MemoryJournal when a local store supports it. Automatic recall is unchanged.",
+              "examples": [
+                true
+              ],
+              "type": "boolean",
+              "default": true
+            }
+          }
+        },
+        "rememberTool": {
           "type": "object",
           "additionalProperties": false,
           "properties": {
@@ -1042,6 +1016,36 @@
           },
           "default": []
         },
+        "filesystem": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "readableRoots": {
+              "description": "Extra roots for managed Read, Glob, and Grep while sandbox.mode is off. Access requires lexical and realpath containment; native sandbox roots remain authoritative when sandboxing is enabled.",
+              "examples": [
+                [
+                  "/srv/shared/reference"
+                ]
+              ],
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "writableRoots": {
+              "description": "Extra roots for managed Write and Edit while sandbox.mode is off; writable roots are also readable. Access requires lexical and realpath containment; native sandbox roots remain authoritative when sandboxing is enabled.",
+              "examples": [
+                [
+                  "/srv/shared/output"
+                ]
+              ],
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
         "mcpConfigPath": {
           "description": "Configures mcpConfigPath for the tools section.",
           "examples": [
@@ -1096,12 +1100,24 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
+            "coordination": {
+              "description": "Host mode shares web request budgets and cooldowns across participating local mono-agent processes; process preserves isolated coordination.",
+              "examples": [
+                "process"
+              ],
+              "type": "string",
+              "default": "process",
+              "enum": [
+                "process",
+                "host"
+              ]
+            },
             "search": {
               "type": "object",
               "additionalProperties": false,
               "properties": {
                 "backend": {
-                  "description": "WebSearch backend: auto tries configured local SearXNG, then ChatGPT-subscription Codex search, then keyless fallbacks; searxng, codex, and keyless are strict.",
+                  "description": "WebSearch backend: auto uses explicitly configured Ollama, configured local SearXNG, ChatGPT-subscription Codex search, then keyless fallbacks. searxng, ollama, codex, and keyless are strict.",
                   "examples": [
                     "auto"
                   ],
@@ -1110,17 +1126,70 @@
                   "enum": [
                     "auto",
                     "searxng",
+                    "ollama",
                     "codex",
                     "keyless"
                   ]
                 },
+                "maxRequestsPerRun": {
+                  "description": "Hard ceiling from 1 to 20 on actual provider search requests in one logical runtime run; cache hits, coalesced followers, cooldown skips, and quota skips consume no request. Default 4.",
+                  "examples": [
+                    4
+                  ],
+                  "type": "integer",
+                  "default": 4,
+                  "minimum": 1,
+                  "maximum": 20
+                },
                 "endpoint": {
-                  "description": "Optional unauthenticated loopback HTTP SearXNG base URL. Remote HTTPS, credentials, query strings, and fragments are rejected.",
+                  "description": "Compatibility alias for tools.web.search.searxng.endpoint and MONO_AGENT_WEB_SEARCH_SEARXNG_ENDPOINT. Existing configurations remain valid; new configurations should use the provider-specific block.",
                   "examples": [
-                    "http://127.0.0.1:8088"
+                    "example"
                   ],
                   "type": "string"
                 },
+                "searxng": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "endpoint": {
+                      "description": "Optional unauthenticated loopback HTTP SearXNG base URL. Remote HTTPS, credentials, query strings, and fragments are rejected.",
+                      "examples": [
+                        "http://127.0.0.1:8088"
+                      ],
+                      "type": "string"
+                    }
+                  }
+                },
+                "ollama": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "baseUrl": {
+                      "description": "Ollama origin. Defaults to local http://127.0.0.1:11434 in strict Ollama mode. Hosted search is exactly https://ollama.com; custom public origins require HTTPS and trustPublicUrl=true.",
+                      "examples": [
+                        "https://ollama.com"
+                      ],
+                      "type": "string",
+                      "default": "http://127.0.0.1:11434"
+                    },
+                    "apiKeyEnv": {
+                      "description": "Environment variable containing the hosted Ollama API key. Required only for exact https://ollama.com and rejected for every other origin; the key value is never stored in JSON.",
+                      "examples": [
+                        "OLLAMA_API_KEY"
+                      ],
+                      "type": "string"
+                    },
+                    "trustPublicUrl": {
+                      "description": "Explicit acknowledgement for an HTTPS custom public Ollama origin. It never permits sending hosted credentials to that origin.",
+                      "examples": [
+                        true
+                      ],
+                      "type": "boolean",
+                      "default": false
+                    }
+                  }
+                },
                 "codex": {
                   "type": "object",
                   "additionalProperties": false,
@@ -1443,7 +1512,75 @@
     },
     "providers": {
       "type": "object",
-      "additionalProperties": false,
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "type": {
+            "enum": [
+              "ollama",
+              "lmstudio",
+              "openai_compat"
+            ]
+          },
+          "baseUrl": {
+            "type": "string"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "trustPublicUrl": {
+            "type": "boolean"
+          },
+          "apiKey": {
+            "type": "string"
+          },
+          "apiKeyEnv": {
+            "type": "string"
+          },
+          "maxAdvertisedModels": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 200,
+            "default": 100
+          },
+          "models": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "name"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "alias": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "displayName": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "enabled": {
+                  "type": "boolean"
+                },
+                "capabilities": {
+                  "type": "object",
+                  "additionalProperties": true
+                },
+                "pricing": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          }
+        }
+      },
       "properties": {
         "piAuthPath": {
           "description": "Configures piAuthPath for the providers section.",
@@ -1470,6 +1607,14 @@
                 "websocket-cached"
               ]
             },
+            "promptCacheDiagnostics": {
+              "description": "Emit metadata-only prompt-cache request fingerprints into run artifacts; never prompt text, tool arguments, cache keys, endpoints or credentials.",
+              "examples": [
+                true
+              ],
+              "type": "boolean",
+              "default": false
+            },
             "piMaxRetries": {
               "description": "Configures piNative.piMaxRetries for the providers section.",
               "examples": [
@@ -1531,6 +1676,12 @@
               "apiKeyEnv": {
                 "type": "string"
               },
+              "maxAdvertisedModels": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 200,
+                "default": 100
+              },
               "models": {
                 "type": "array",
                 "items": {
@@ -1633,7 +1784,7 @@
         "maxChainDepth": {
           "type": "integer",
           "minimum": 1,
-          "maximum": 8,
+          "maximum": 64,
           "default": 4
         },
         "retention": {
@@ -1662,6 +1813,100 @@
         }
       }
     },
+    "monitors": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "maxActive": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32,
+          "default": 8
+        },
+        "maxActivePerConversation": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8,
+          "default": 2
+        },
+        "maxRuntimeMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3600000,
+          "default": 3600000
+        },
+        "persistentMaxRuntimeMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400000,
+          "default": 86400000
+        },
+        "coalesceMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5000,
+          "default": 200
+        },
+        "maxBatchLines": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 2000,
+          "default": 200
+        },
+        "maxBatchBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1048576,
+          "default": 65536
+        },
+        "maxLineBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65536,
+          "default": 4096
+        },
+        "maxWakeIntervalMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 300000,
+          "default": 300000
+        },
+        "maxChainDepth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 64,
+          "default": 4
+        },
+        "rateLimit": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "windowMs": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 60000,
+              "default": 1000
+            },
+            "maxLinesPerWindow": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 20000,
+              "default": 200
+            },
+            "sustainedWindows": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 60,
+              "default": 5
+            }
+          }
+        }
+      }
+    },
     "interaction": {
       "type": "object",
       "additionalProperties": false,
@@ -1693,11 +1938,14 @@
           "additionalProperties": false,
           "properties": {
             "timeoutMs": {
-              "description": "Maximum wait for one AskUser interaction (one to five questions).",
+              "description": "Maximum wait for one AskUser interaction (one to five questions); set null to disable automatic expiry.",
               "examples": [
                 600000
               ],
-              "type": "integer",
+              "type": [
+                "integer",
+                "null"
+              ],
               "default": 600000
             }
           }

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

@@ -38,7 +38,7 @@ Do **not** read or grep the `@mono-agent` TypeScript/package source — `package
 - Ask one question at a time; skip anything the user already answered.
 - Respect existing knowledge: if the folder has `AGENTS.md`, `CLAUDE.md`, `README.md`, or `SOUL.md`, reference it from the identity instead of copying it. `IDENTITY.md` → `## Role` is the single canonical guided-init Role location. Never overwrite an existing identity; say explicitly that a newly entered Role was not written and tell the user to add or edit that heading manually.
 - Fail closed: no allowed tools, no memory writes, loopback-only network until the user opts in.
-- Do not fake runtime success, silently broaden tool access, or hide provider/MCP failures. Backup models are configured failover (`runtime.fallbacks[]`), never silent substitution. Legacy `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` remain compatibility inputs with no removal deadline, but do not emit them for a new agent.
+- Do not fake runtime success, silently broaden tool access, or hide provider/MCP failures. Backup models are configured failover (`runtime.fallbacks[]`), never silent substitution. `runtime.fallbackModels` and `MONO_AGENT_FALLBACK_MODELS` were retired in 0.21.0 and are rejected at load, but do not emit them for a new agent.
 - Secrets stay in `.env` or exported environment variables. An ignored or untracked config file is not permission to inline them; never commit tokens or `.env*` files.
 
 ## Prerequisites
@@ -54,7 +54,7 @@ The install command pairs every available Codex/Claude target by default and
 prints an exact later command for a missing target. Use `--no-docs-mcp` only
 when a file-only skill install is intentional.
 
-To run an unreleased build instead, use a clone of the mono-agent workspace with Node 22.19.0+ and pnpm 10 or newer already installed:
+To run an unreleased build instead, use a clone of the mono-agent workspace with Node 24.15.0+ and pnpm 10 or newer already installed:
 
 ```bash
 git clone <mono-agent-repo> ~/mono-agent && cd ~/mono-agent
@@ -75,8 +75,8 @@ Everything below runs in the user's agent folder, not the workspace.
    mono-agent init --model <ref> [--fallback <ref> [--fallback-effort <provider-default|level>]]... [--effort <level>] [--auth] [--memory lite|journal|bujo]   # bare scaffold
    ```
 
-   Either writes a `mono-agent.config.json` (with `tools.allowedTools` pre-filled from the selected capabilities' recommended tools), an `IDENTITY.md` whose `## Role` body is the one Role destination and which references any knowledge files already present, the managed project-local `mono-agent-configure` and `mono-agent-memory` skills, and `.mono-agent/` working directories (presets also emit a `.env.example` and any extra files). `--effort` writes `runtime.effort` on supporting providers (do not use it with direct `opencode:*` SDK 1.x); `--auth` opts in to provider setup before writing files; `--dry-run` previews without writing or launching auth/preflight commands. Existing scaffold/config files are never overwritten; reviewed secret setup is the deliberate exception that can transactionally replace `.env` and update `.gitignore`.
-3. **Configure.** Edit `mono-agent.config.json` to match the discovery answers. For a newly created identity, put the agreed text under `IDENTITY.md` → `## Role`; if it existed before init, preserve it and report that the new answer was not stored. Preserve the generated `mono-agent-configure` and `mono-agent-memory` selections when appending other skills, and do not auto-select this full authoring-oriented composer inside the generated agent. Read `references/config-blueprint.md` for the full annotated config shape: every channel section, skills, MCP, memory, sandbox, and fallback models. Run `mono-agent config` to see the resolved configuration field-by-field with each value tagged `env` / `json` / `default` — the fastest way to confirm a value came from where you intended.
+   Either writes a `mono-agent.config.json` (with `tools.allowedTools` pre-filled from the selected capabilities' recommended tools), an `IDENTITY.md` whose `## Role` body is the one Role destination and which references any knowledge files already present, the managed project-local `mono-agent-memory` skill, and `.mono-agent/` working directories (presets also emit a `.env.example` and any extra files). `--effort` writes `runtime.effort`, which is narrowed per model for display and still accepted at turn time; `--auth` opts in to provider setup before writing files; `--dry-run` previews without writing or launching auth/preflight commands. Existing scaffold/config files are never overwritten; reviewed secret setup is the deliberate exception that can transactionally replace `.env` and update `.gitignore`.
+3. **Configure.** Edit `mono-agent.config.json` to match the discovery answers. For a newly created identity, put the agreed text under `IDENTITY.md` → `## Role`; if it existed before init, preserve it and report that the new answer was not stored. Preserve the generated `mono-agent-memory` selection when appending other skills, and do not auto-select this full authoring-oriented composer inside the generated agent. Read `references/config-blueprint.md` for the full annotated config shape: every channel section, skills, MCP, memory, sandbox, and fallback models. Run `mono-agent config` to see the resolved configuration field-by-field with each value tagged `env` / `json` / `default` — the fastest way to confirm a value came from where you intended.
 4. **Validate.**
 
    ```bash
@@ -90,7 +90,7 @@ Everything below runs in the user's agent folder, not the workspace.
    mono-agent start
    ```
 
-   Then run the acceptance smoke test matching the chosen channel (see `references/validation.md`). To change anything, edit `mono-agent.config.json` or `IDENTITY.md` directly and run `mono-agent restart`; there is no live browser re-apply. On macOS, `mono-agent tui --configure` opens a persistent, visibly marked proposal-only SELF-CONFIG conversation against the already-running background agent. It maps the available capabilities, helps build a workflow conversationally, never accepts secrets, requires an out-of-band approval, and restarts or rolls back through the managed lifecycle. Approval, rejection, and no-change turns continue SELF-CONFIG; only quitting exits. Off macOS, use manual edits plus `validate`, foreground `start`, and ordinary `tui`; conversational configuration is unavailable.
+   Then run the acceptance smoke test matching the chosen channel (see `references/validation.md`). To change anything, edit `mono-agent.config.json` or `IDENTITY.md` directly, run `mono-agent validate`, and run `mono-agent restart`; there is no live browser or conversational re-apply. Open ordinary `mono-agent tui` after the restarted agent is ready.
 
 ## When Config Is Not Enough