mercury-agent 0.10.0 → 0.12.0

package/README.md

@@ -361,8 +361,8 @@ Optional project file **`mercury.yaml`** (or **`mercury.yml`**) supplies non-sec
 
 | Variable | Description |
 |----------|-------------|
-| `MERCURY_API_SECRET` | Shared secret for `/api/*` routes. When set, requires `Authorization: Bearer <secret>`. Auto-generated by `mercury setup`. |
-| `MERCURY_CHAT_API_KEY` | Optional API key for `/chat` endpoint. When set, requires Bearer token. When unset, `/chat` is open (for local use). |
+| `MERCURY_API_SECRET` | Shared secret for `/api/*`, `/dashboard/*` and `/chat`. Requires `Authorization: Bearer <secret>`; when unset those routes refuse to serve (503). Auto-generated by `mercury setup`. |
+| `MERCURY_CHAT_API_KEY` | Optional dedicated key for the `/chat` endpoint. Falls back to `MERCURY_API_SECRET` when unset; with neither configured, `/chat` returns 503. |
 
 **Auth:**
 

package/docs/configuration.md

@@ -95,6 +95,104 @@ In YAML, use a list of `{ provider, model }` objects under `model.chain` (max 4
 
 Optional **`model.capabilities`** may be a mapping; it is applied like `MERCURY_MODEL_CAPABILITIES` JSON.
 
+### Custom endpoints (`models.json`)
+
+A model leg is `{ provider, model }` and carries no host, so it cannot on its own
+reach an endpoint pi does not already know about — a metering gateway, a local
+model server (Ollama, LM Studio, vLLM), or a private/regional deployment.
+
+pi solves this with its own config file, and Mercury mounts it. Drop a
+`models.json` into the **global dir** (`<dataDir>/global/`, alongside
+`AGENTS.md`); it is bind-mounted read-only at `PI_CODING_AGENT_DIR` and pi reads
+it natively. No Mercury config key is involved, and the model-chain schema is
+unchanged.
+
+**Repoint an existing provider** — keeps pi's model metadata, costs and
+capabilities, and every `provider: openai` leg goes to the new host:
+
+```json
+{ "providers": { "openai": { "baseUrl": "https://gateway.example.com/v1" } } }
+```
+
+**Define custom models** — here pi requires `baseUrl`, and `api` is effectively
+mandatory too: pi silently skips any model whose wire format it cannot resolve,
+so omitting it makes the model vanish without an error.
+
+```json
+{
+  "providers": {
+    "mygateway": {
+      "baseUrl": "https://gateway.example.com/v1",
+      "api": "openai-completions",
+      "apiKey": "$MYGATEWAY_API_KEY",
+      "models": [{ "id": "openai/gpt-4o-mini", "contextWindow": 128000 }]
+    }
+  }
+}
+```
+
+### Credentials in `models.json`
+
+Which credential path applies depends on which shape you used:
+
+- **Repointing a built-in provider** (`openai`, `anthropic`, …) changes nothing:
+  the key keeps travelling as `MERCURY_<PROVIDER>_API_KEY`, exactly as before.
+- **A provider that exists only in `models.json`** is unknown to pi's env-var
+  map, so no `*_API_KEY` variable is read for it. Its key must come from the
+  provider entry — written as a **reference**, never a literal:
+  `"apiKey": "$MYGATEWAY_API_KEY"` (`${VAR}` and `!some-command` also work).
+  Pass the secret itself as `MERCURY_MYGATEWAY_API_KEY` and it reaches the
+  container through the usual passthrough. This assumes the default
+  `agent.env_passthrough: all`; under `claimed`, only the provider variables
+  Mercury knows about are forwarded, and a custom provider's key is not among
+  them, so pi fails to resolve it.
+
+> ⚠️ **Never store a credential literally.** Mercury refuses to mount a
+> `models.json` that has a literal value in `apiKey`, in a credential-shaped
+> field or header (`Authorization`, `x-api-key`, anything containing
+> key/token/secret/auth/cookie/credential/passw), or as userinfo or a
+> credential-shaped query parameter in a `baseUrl` — provider-level and
+> per-model alike — and logs an error naming the fields. Every other entry
+> mounted into the agent container is a resource kind that cannot hold a secret
+> (`auth.json` is excluded precisely so the OAuth refresh token never reaches
+> the least-trusted part of the system), and `models.json` is held to the same
+> rule.
+>
+> **References are fine**, and so is a value that merely *contains* one:
+> `"Bearer $GW_KEY"` is the ordinary spelling of a bearer header, because pi
+> interpolates rather than matching whole values. What is left over once the
+> references are removed still has to look like configuration — stapling an
+> unused `$VAR` onto a pasted key does not buy passage.
+>
+> This is a guardrail against accident, not a control against a hostile writer:
+> the bind source is live, so anyone able to write the global dir could change
+> the file after the check. Anyone who can do that can already do worse.
+>
+> A file that cannot be read or parsed is refused for the same reason — its
+> contents are unverifiable. The check parses exactly what pi parses: `//` line
+> comments and trailing commas are fine, **`/* … */` block comments are not** —
+> pi cannot read those either, so a file containing one is refused rather than
+> mounted and then silently ignored by pi.
+>
+> **What refusal costs depends on the shape.** A repointed built-in provider
+> falls back to its default endpoint, so traffic quietly leaves your gateway; a
+> provider defined only in `models.json` stops resolving altogether. Either way,
+> grep the logs for `Ignoring models.json`.
+
+**Capabilities for a custom provider.** Capability detection is host-side and
+registry-based, so a provider that exists only in `models.json` is invisible to
+it and the leg resolves to `DEFAULT_CAPABILITIES` (`tools: true`, everything
+else false). This degrades gracefully: tool use — the one that matters — stays
+on, and a `false` from an unresolved model is treated as *unknown* rather than
+*unsupported*, so capability-gated extensions and skills still install. To state
+capabilities explicitly, add the model to `<dataDir>/model-capabilities.yaml`,
+which is consulted before the registry.
+
+The **override-only** shape mostly avoids the question, since the provider stays
+a known one — but only for model ids that are themselves in pi's registry.
+Repointing `openai`'s `baseUrl` and then naming a model pi has never heard of
+lands back in `default`.
+
 ### Removed: `provider: cursor`
 
 The **Cursor Agent CLI** integration has been removed. All model legs use **pi** with standard providers (`anthropic`, `openai`, `google`, `mistral`, `groq`, `openrouter`, etc.).

package/docs/scheduler.md

@@ -61,27 +61,31 @@ TaskScheduler.start()
         │
         ├─► Query DB for due tasks (active=1, next_run_at <= now)
         │
-        ├─► For each due task:
+        ├─► For each due task (skipped if a run is already in flight):
         │     │
-        │     ├─► [Cron task]
-        │     │     ├─► Compute next run time from cron expression
-        │     │     ├─► Update next_run_at in DB
-        │     │     └─► Execute handler
+        │     ├─► Execute handler
+        │     ├─► Record the outcome on the task row
         │     │
-        │     └─► [At task]
-        │           ├─► Execute handler
-        │           └─► Delete task from DB
+        │     ├─► [Failed, retries left]
+        │     │     └─► Set next_run_at to the retry time — schedule untouched
+        │     │
+        │     └─► [Succeeded, or out of retries]
+        │           ├─► Report the failure to the space (failures only)
+        │           ├─► [Cron task] Compute and store the next run time
+        │           └─► [At task]   Delete task from DB
         │
         └─► Schedule next poll
 ```
 
 Tasks are processed sequentially within a poll cycle. Each task runs as if the `createdBy` user sent the prompt.
 
+The schedule is consumed **after** the attempt, not before. A task therefore stays "due" for the whole time it is running; the in-flight guard is what stops the poll starting a second run, and it is also why a long run shows as `now` in the dashboard's Next Run column until it finishes.
+
 **At-task lifecycle:**
 1. Created with a future timestamp
 2. Waits until scheduled time
-3. Executes once
-4. Auto-deletes (regardless of success/failure)
+3. Executes once, plus any retries
+4. Auto-deletes once it succeeds or runs out of retries
 
 ## Creating Tasks
 
@@ -185,6 +189,9 @@ CREATE TABLE tasks (
   silent INTEGER NOT NULL DEFAULT 0,
   next_run_at INTEGER NOT NULL,
   created_by TEXT NOT NULL,
+  last_run_at INTEGER,                -- Epoch ms of the last completed attempt
+  last_status TEXT,                   -- 'ok' | 'error'
+  last_error TEXT,                    -- Failure message, capped at 500 chars
   created_at INTEGER NOT NULL,
   updated_at INTEGER NOT NULL
 );
@@ -197,6 +204,11 @@ CREATE INDEX idx_tasks_next ON tasks(active, next_run_at);
 | `cron` | Cron expression for recurring tasks (null for at-tasks) |
 | `at` | ISO 8601 timestamp for one-shot tasks (null for cron-tasks) |
 | `silent` | If 1, task runs but doesn't post results to chat |
+| `last_run_at` | When the last attempt finished. Null until the task has run |
+| `last_status` | `ok` or `error`. Written for every attempt, retries included |
+| `last_error` | Why the last attempt failed; null after a success |
+
+The last-run columns are shown in the dashboard's task table (**Last Run**), with the error text as the cell's tooltip. Existing rows are not backfilled — a task that has never run since the upgrade reads as `never`.
 
 ## Permissions
 
@@ -241,13 +253,29 @@ The scheduler stops cleanly on shutdown — no orphaned timers.
 ### `TaskScheduler`
 
 ```typescript
-const scheduler = new TaskScheduler(db, pollIntervalMs);
+const scheduler = new TaskScheduler(db, pollIntervalMs, {
+  retryAttempts,  // extra attempts after the first failure
+  retryDelayMs,   // how long to wait before one
+});
 
-scheduler.start(handler);    // Begin polling
-scheduler.stop();            // Stop polling
+scheduler.start(handler, onFailure);   // Begin polling
+scheduler.stop();                      // Stop polling
 scheduler.computeNextRun(cron, from);  // Get next run time for cron tasks
 ```
 
+`onFailure` is optional and is called **once per due cycle**, only after the retries are spent — never once per attempt.
+
+```typescript
+type TaskFailure = {
+  id: number;
+  spaceId: string;
+  name: string | null;
+  silent: boolean;   // the task's flag; the reporter decides whether to honour it
+  error: string;     // capped at 500 chars
+  attempts: number;  // attempts made this cycle, including the first
+};
+```
+
 ### Handler Signature
 
 ```typescript
@@ -276,13 +304,47 @@ db.setTaskActive(id, active); // Pause/resume
 db.deleteTask(id, spaceId);   // Delete task (with space check)
 db.deleteTaskById(id);        // Delete task (no space check, for scheduler)
 db.updateTaskNextRun(id, nextRunAt);  // Update next execution time
+db.recordTaskRun(id, status, error?); // Record one attempt's outcome
 ```
 
 ## Error Handling
 
-If a task handler fails:
-- Error is logged
-- Task is not retried in the same cycle
-- **Cron tasks:** `next_run_at` is already updated, so it will run again at the next scheduled time
-- **At tasks:** Still deleted after execution (one-shot behavior preserved)
-- Other tasks in the cycle continue to execute
+A task that fails is retried, then reported. Nothing about a failure is silent.
+
+When a handler throws:
+
+1. The error is logged and written to the task row (`last_status = 'error'`, `last_error`).
+2. If attempts remain, `next_run_at` is set to the retry time and the poll picks the task up again. Nothing is posted to the space — a pending retry is not news yet.
+3. Once the attempts are spent, the space is told (see below) and only **then** is the schedule consumed: a cron task advances to its next occurrence, a one-shot task is deleted.
+4. Other tasks in the cycle are unaffected.
+
+The retry time is `now + retry_delay_ms`, **clamped to the task's own next occurrence** — a 5-minute delay on an every-minute task must not swallow four scheduled runs.
+
+### The failure notice
+
+On a final failure Mercury posts one message into the task's space:
+
+> ⚠️ Scheduled task "Daily football" failed and produced nothing (attempts: 2). Reason: Container timed out for group 19
+
+`silent` is **not** honoured here. It suppresses a task's routine output, and a silent task that fails is exactly the one whose failure nobody would otherwise discover. Set `scheduling.notify_on_failure: false` to turn the notices off entirely.
+
+The message is locale-aware (`messages.locale`, `en` and `he`), like every other host-generated system message.
+
+### Configuration
+
+| YAML | Env | Default | What |
+|------|-----|---------|------|
+| `scheduling.retry_attempts` | `MERCURY_TASK_RETRY_ATTEMPTS` | `1` | Extra attempts after the first failure. `0` disables retrying |
+| `scheduling.retry_delay_ms` | `MERCURY_TASK_RETRY_DELAY_MS` | `300000` (5 min) | Wait before a retry. Minimum 60 000 — an agent run costs tokens and a container slot, so retrying a systematic failure fast is worse than not retrying |
+| `scheduling.notify_on_failure` | `MERCURY_TASK_NOTIFY_ON_FAILURE` | `true` | Post the notice above |
+
+```yaml
+scheduling:
+  retry_attempts: 1
+  retry_delay_ms: 300000
+  notify_on_failure: true
+```
+
+### Unparseable cron expressions
+
+A task whose cron cannot be parsed has no next occurrence to advance to. Rather than leave `next_run_at` in the past — which would make the poll re-run it, and spend a full agent turn, every few seconds — the scheduler **pauses the task** and logs why. Fix the expression and resume it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",
@@ -84,13 +84,13 @@
     "@chat-adapter/slack": "^4.14.0",
     "@chat-adapter/teams": "^4.17.0",
     "@chat-adapter/telegram": "^4.26.0",
-    "@earendil-works/pi-agent-core": "~0.79.6",
-    "@earendil-works/pi-ai": "~0.79.10",
-    "@earendil-works/pi-coding-agent": "~0.79.6",
+    "@earendil-works/pi-agent-core": "~0.83.0",
+    "@earendil-works/pi-ai": "~0.83.0",
+    "@earendil-works/pi-coding-agent": "~0.83.0",
     "@whiskeysockets/baileys": "^7.0.0-rc.9",
     "axios": "^1.15.1",
     "chat": "^4.14.0",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "cron-parser": "^5.5.0",
     "discord.js": "^14.26.3",
     "hono": "^4.12.34",
@@ -100,10 +100,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.12",
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.1.2",
     "@types/qrcode-terminal": "^0.12.2",
     "bun-types": "^1.3.5",
-    "typescript": "^5.8.0"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "bun": ">=1.2.0"

package/src/agent/container-entry.ts

@@ -1058,6 +1058,14 @@ function invokePiOnce(
         return;
       }
       const parsed = parsePiPrintJsonlOutput(stdout);
+      if (parsed.droppedNarrationBlocks) {
+        // Counts only — never the text. This is the one signal that survives
+        // the --rm container, and it is what lets a live run confirm the
+        // narration filter is doing its job.
+        logTiming("container.pi.narration_dropped", {
+          blocks: parsed.droppedNarrationBlocks,
+        });
+      }
       if (parsed.piFailureMessage) {
         reject(new Error(parsed.piFailureMessage));
         return;

package/src/agent/container-runner.ts

@@ -52,10 +52,17 @@ const INNER_PI_AGENT_DIR = "/home/mercury/.pi/agent";
  * A superset of what Mercury itself writes (`.pi/`, `AGENTS.md`, `skills/`) —
  * the remaining entries are pi resource kinds a user may drop in by hand, none
  * of which can hold a credential.
+ *
+ * `models.json` is the one entry where that last clause is a *rule* rather than
+ * an observation: pi's `ProviderConfig` accepts an `apiKey` and arbitrary
+ * `headers`, so the file is checked for literal credentials before it is
+ * mounted (see `modelsJsonIsCredentialFree`). Env references are allowed —
+ * they are how a custom provider is meant to be keyed.
  */
 const PI_AGENT_RESOURCE_ENTRIES = [
   ".pi",
   "AGENTS.md",
+  "models.json",
   "skills",
   "agents",
   "commands",
@@ -63,6 +70,286 @@ const PI_AGENT_RESOURCE_ENTRIES = [
   "extensions",
 ] as const;
 
+/**
+ * Names whose value is a credential rather than configuration. Applied both to
+ * header names and to the config fields beside them: pi's schema ignores an
+ * unknown field, but Typebox still lets it through, so a provider that spells
+ * `apiKey` as `api_key` gets no complaint from pi and the secret rides into the
+ * mounted file anyway.
+ */
+const CREDENTIAL_FIELD_RE =
+  /(^authorization$|^cookie$|key|token|secret|auth|credential|passw)/i;
+
+/** Env var names pi will resolve in a `$VAR` / `${VAR}` reference. */
+const ENV_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_VAR_NAME_PREFIX_RE = /^[A-Za-z_][A-Za-z0-9_]*/;
+
+/**
+ * A run long enough to be a pasted secret. Only ever applied to the *literal*
+ * remainder of a value that already carries an env reference, which is what
+ * separates `"Bearer $GW_KEY"` (a template, fine) from
+ * `"sk-live-abc…$GW_KEY"` (a secret with a reference stapled on). Blind to `/`
+ * and `.` so a URL-shaped literal cannot trip it.
+ */
+const SECRET_SHAPED_RUN = /[A-Za-z0-9_-]{20,}/;
+
+/**
+ * Split a config value the way pi's `parseConfigValueTemplate` does
+ * (`pi-coding-agent@0.79.10/dist/core/resolve-config-value.js`), reporting
+ * whether any part resolves from the environment and what literal text is left
+ * over once the references are removed.
+ *
+ * The parse has to be pi's, not an approximation of it: pi *interpolates*, so a
+ * reference may sit inside a longer string, and `$$` / `$!` escape a literal
+ * `$` / `!` rather than starting one.
+ */
+function scanConfigValueTemplate(config: string): {
+  hasEnvRef: boolean;
+  literal: string;
+} {
+  let literal = "";
+  let hasEnvRef = false;
+  let index = 0;
+  while (index < config.length) {
+    const dollar = config.indexOf("$", index);
+    if (dollar < 0) {
+      literal += config.slice(index);
+      break;
+    }
+    literal += config.slice(index, dollar);
+    const next = config[dollar + 1];
+    if (next === "$" || next === "!") {
+      literal += next;
+      index = dollar + 2;
+      continue;
+    }
+    if (next === "{") {
+      const end = config.indexOf("}", dollar + 2);
+      if (end < 0) {
+        literal += "$";
+        index = dollar + 1;
+        continue;
+      }
+      const name = config.slice(dollar + 2, end);
+      if (ENV_VAR_NAME_RE.test(name)) hasEnvRef = true;
+      else literal += config.slice(dollar, end + 1);
+      index = end + 1;
+      continue;
+    }
+    const name = config.slice(dollar + 1).match(ENV_VAR_NAME_PREFIX_RE)?.[0];
+    if (name) {
+      hasEnvRef = true;
+      index = dollar + 1 + name.length;
+      continue;
+    }
+    literal += "$";
+    index = dollar + 1;
+  }
+  return { hasEnvRef, literal };
+}
+
+/**
+ * True when pi resolves this value at run time instead of reading it from the
+ * file: `!cmd` (shell command), or a template carrying at least one `$VAR` /
+ * `${VAR}` reference.
+ *
+ * This distinction is the whole point of the check. `"apiKey": "$GATEWAY_KEY"`
+ * is a *reference* and is exactly how a custom provider is supposed to be
+ * keyed; `"apiKey": "sk-…"` is a secret sitting at rest in a mounted file.
+ *
+ * A template only has to *contain* a reference, because that is pi's rule:
+ * `"Authorization": "Bearer $GW_KEY"` is the ordinary spelling of a bearer
+ * header and holds no secret. What is left over after the references are
+ * removed still has to look like configuration rather than a key, so stapling
+ * an unused `$VAR` onto a pasted secret does not buy passage.
+ */
+function isCredentialReference(value: string): boolean {
+  if (!value.trim()) return true; // nothing there to leak
+  // pi tests the raw value, so a leading space means this is not a command.
+  if (value.startsWith("!")) return true;
+  const { hasEnvRef, literal } = scanConfigValueTemplate(value);
+  if (!hasEnvRef) return false;
+  return !SECRET_SHAPED_RUN.test(literal);
+}
+
+/**
+ * JSONC → JSON, character-for-character as pi does it
+ * (`pi-coding-agent@0.79.10/dist/utils/json.js`): `//` line comments and
+ * trailing commas go, string literals are left alone. Block comments stay,
+ * because pi does not strip them either.
+ *
+ * Matching pi exactly is the requirement, not tolerance for its own sake. Strip
+ * *more* than pi and a file this check passed is one pi then fails to parse —
+ * pi keeps its built-in models and stashes the error, so a repointed provider
+ * quietly goes back to its default endpoint, which is the silent drift the
+ * mount was added to prevent. Strip *less* and a file pi reads happily is
+ * refused as unparseable.
+ */
+function stripJsonComments(input: string): string {
+  return input
+    .replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*/g, (m) => (m[0] === '"' ? m : ""))
+    .replace(/"(?:\\.|[^"\\])*"|,(\s*[}\]])/g, (m, tail) =>
+      tail !== undefined ? tail : m[0] === '"' ? m : "",
+    );
+}
+
+/** Every literal credential in a parsed models.json, as `provider.field` paths. */
+function findLiteralCredentials(parsed: unknown): string[] {
+  const providers = (parsed as { providers?: Record<string, unknown> })
+    ?.providers;
+  if (!providers || typeof providers !== "object") return [];
+
+  const offenders: string[] = [];
+
+  /**
+   * Every string field whose *name* says it holds a credential. Serves both the
+   * `headers` record and the config object around it, which are the same
+   * question asked of a different bag of strings.
+   */
+  const checkFields = (obj: unknown, where: string) => {
+    if (!obj || typeof obj !== "object") return;
+    for (const [name, value] of Object.entries(
+      obj as Record<string, unknown>,
+    )) {
+      if (typeof value !== "string") continue;
+      if (!CREDENTIAL_FIELD_RE.test(name)) continue;
+      if (!isCredentialReference(value)) offenders.push(`${where}.${name}`);
+    }
+  };
+
+  /** Userinfo or a credential-shaped query parameter is a credential however it got into the URL. */
+  const checkUrl = (value: unknown, where: string) => {
+    if (typeof value !== "string") return;
+    let url: URL;
+    try {
+      url = new URL(value);
+    } catch {
+      return; // Not a URL — pi will complain about it; not this function's business.
+    }
+    if (url.username || url.password) {
+      offenders.push(where);
+      return;
+    }
+    for (const [name, param] of url.searchParams) {
+      if (CREDENTIAL_FIELD_RE.test(name) && !isCredentialReference(param)) {
+        offenders.push(`${where}?${name}`);
+        return;
+      }
+    }
+  };
+
+  for (const [name, raw] of Object.entries(providers)) {
+    const p = raw as Record<string, unknown> | null;
+    if (!p || typeof p !== "object") continue;
+
+    checkFields(p, name);
+    checkFields(p.headers, `${name}.headers`);
+    checkUrl(p.baseUrl, `${name}.baseUrl`);
+    if (Array.isArray(p.models)) {
+      for (const m of p.models as Array<Record<string, unknown> | null>) {
+        if (!m || typeof m !== "object") continue;
+        const at = `${name}.models[${String(m.id)}]`;
+        checkFields(m, at);
+        checkFields(m.headers, `${at}.headers`);
+        // pi takes a per-model baseUrl over the provider's, so it needs the
+        // same look: `modelDef.baseUrl ?? providerConfig.baseUrl`.
+        checkUrl(m.baseUrl, `${at}.baseUrl`);
+      }
+    }
+    if (p.modelOverrides && typeof p.modelOverrides === "object") {
+      for (const [id, ov] of Object.entries(
+        p.modelOverrides as Record<string, Record<string, unknown> | null>,
+      )) {
+        if (!ov || typeof ov !== "object") continue;
+        const at = `${name}.modelOverrides[${id}]`;
+        checkFields(ov, at);
+        checkFields(ov.headers, `${at}.headers`);
+      }
+    }
+  }
+  return offenders;
+}
+
+/** Cached verdict per file, keyed on the stat that would change if it changed. */
+const modelsJsonVerdicts = new Map<
+  string,
+  { mtimeMs: number; size: number; ok: boolean }
+>();
+
+/**
+ * Refuse a `models.json` that stores a credential *literally*, so the
+ * allowlist's "none of which can hold a credential" note stays true for the one
+ * entry where pi's schema would otherwise permit a secret.
+ *
+ * References are fine and are the supported spelling: `"apiKey": "$GATEWAY_KEY"`
+ * resolves inside the container from the env Mercury already passes through.
+ * A literal is not, because the file is mounted into the least-trusted part of
+ * the system — the same reasoning that keeps `auth.json` off the allowlist.
+ *
+ * **A guardrail against accident, not a boundary against a hostile writer.**
+ * The bind source is live, so anyone who can write the global dir can change
+ * the file after this check and before `docker create`. Anyone who can do that
+ * can already do worse.
+ *
+ * Fails closed on a file it cannot read or parse: an unverifiable file is one
+ * whose invariant is unknown. Never fatal — a typo in an optional config file
+ * should not take the bot down — so it logs at error level instead, and the
+ * verdict is cached per (mtime, size) to keep that to one line per edit rather
+ * than one per turn.
+ */
+function modelsJsonIsCredentialFree(file: string): boolean {
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    return false;
+  }
+  const cached = modelsJsonVerdicts.get(file);
+  if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+    return cached.ok;
+  }
+
+  const remember = (ok: boolean) => {
+    modelsJsonVerdicts.set(file, {
+      mtimeMs: stat.mtimeMs,
+      size: stat.size,
+      ok,
+    });
+    return ok;
+  };
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    logger.error("Ignoring models.json: it could not be read.", {
+      file,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return remember(false);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stripJsonComments(raw));
+  } catch (error) {
+    logger.error("Ignoring models.json: it is not valid JSON.", {
+      file,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return remember(false);
+  }
+
+  const offenders = findLiteralCredentials(parsed);
+  if (offenders.length === 0) return remember(true);
+
+  logger.error(
+    'Ignoring models.json: it stores a credential literally. Replace the value with an env reference such as "$MY_GATEWAY_KEY" and pass the secret as MERCURY_MY_GATEWAY_KEY. Until this is fixed, a repointed provider falls back to its default endpoint and a provider defined only in this file stops resolving.',
+    { file, fields: offenders.join(", ") },
+  );
+  return remember(false);
+}
+
 /**
  * Docker `-v` args exposing the global dir's resource entries at
  * `INNER_PI_AGENT_DIR`, one mount per entry rather than one mount of the
@@ -84,7 +371,11 @@ export function buildPiAgentMountArgs(
 ): string[] {
   const args: string[] = [];
   for (const entry of PI_AGENT_RESOURCE_ENTRIES) {
-    if (!fs.existsSync(path.join(hostGlobalDir, entry))) continue;
+    const hostPath = path.join(hostGlobalDir, entry);
+    if (!fs.existsSync(hostPath)) continue;
+    if (entry === "models.json" && !modelsJsonIsCredentialFree(hostPath)) {
+      continue;
+    }
     args.push(
       "-v",
       `${path.join(innerGlobalDir, entry)}:${INNER_PI_AGENT_DIR}/${entry}:ro`,

package/src/agent/model-capabilities.ts

@@ -4,7 +4,10 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { getModels, type KnownProvider } from "@earendil-works/pi-ai";
+import {
+  type BuiltinProvider,
+  getBuiltinModels,
+} from "@earendil-works/pi-ai/providers/all";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 import type { ModelLeg } from "../config.js";
@@ -96,8 +99,8 @@ function matchBuiltinCapabilities(
   provider: string,
   modelId: string,
 ): ModelCapabilities | null {
-  // Cast to KnownProvider — getModels returns [] for unrecognised providers at runtime
-  const model = getModels(provider as KnownProvider).find(
+  // Cast to BuiltinProvider — getBuiltinModels returns [] for unrecognised providers at runtime
+  const model = getBuiltinModels(provider as BuiltinProvider).find(
     (m) => m.id === modelId,
   );
   if (!model) return null;