mercury-agent 0.14.0 → 0.16.0

package/README.md

@@ -279,8 +279,17 @@ mercury service install
 mercury service uninstall
 mercury service status
 mercury service logs [-f]
+
+# upgrade (stops the service, installs globally, restarts)
+mercury upgrade             # latest
+mercury upgrade 0.14.0      # a specific version
 ```
 
+> **Windows:** stop Mercury before upgrading. Windows locks the native
+> `libvips` DLL that a running Mercury has mapped, so a global install fails
+> with `EBUSY`. `mercury upgrade` detects the lock and stops before npm leaves a
+> rolled-back install behind — see [docs/deployment.md](docs/deployment.md#windows-stop-mercury-before-upgrading).
+
 ### `mrctl` (in-container API CLI)
 
 ```bash

package/container/Dockerfile

@@ -60,45 +60,38 @@ RUN echo '{"args":["--no-sandbox"]}' > /home/mercury/.puppeteerrc.json
 ENV CHROMIUM_FLAGS="--no-sandbox"
 
 # Install CLIs
-RUN bun add -g @earendil-works/pi-coding-agent@~0.79.6
+RUN bun add -g @earendil-works/pi-coding-agent@~0.84.1
 
 WORKDIR /app
 
 COPY container/agent-package.json /app/package.json
 RUN bun install --production
 
-# Patch pi: skip thinkingConfig for Gemma models (Google API rejects thinkingBudget for them,
-# but pi marks gemma-4 as reasoning:true and sends thinkingBudget:0 to disable it)
-RUN node <<'EOF'
-const fs = require('fs'), path = require('path');
-function patch(dir) {
-  try {
-    for (const f of fs.readdirSync(dir)) {
-      const p = path.join(dir, f);
-      try {
-        if (fs.statSync(p).isDirectory()) patch(p);
-        else if (f === 'google.js' && p.includes('@earendil-works/pi-ai')) {
-          let c = fs.readFileSync(p, 'utf8');
-          const noThinking = '&& !model.id.startsWith("gemma")';
-          const p1 = 'if (options.thinking?.enabled && model.reasoning) {';
-          const p2 = 'else if (model.reasoning && options.thinking && !options.thinking.enabled) {';
-          if (!c.includes(noThinking)) {
-            c = c.replace(p1, 'if (options.thinking?.enabled && model.reasoning ' + noThinking + ') {');
-            c = c.replace(p2, 'else if (model.reasoning && options.thinking && !options.thinking.enabled ' + noThinking + ') {');
-            fs.writeFileSync(p, c);
-            console.log('Patched:', p);
-          }
-        }
-      } catch(e) {}
-    }
-  } catch(e) {}
-}
-patch('/home/mercury/.bun');
-patch('/app/node_modules');
-EOF
+# pi >= 0.84 handles Gemma 4's thinking config itself, so the patch that used to
+# live here is gone. It string-replaced two exact lines in pi-ai's
+# dist/providers/google.js to stop `thinkingBudget: 0` being sent to Gemma
+# models, which the Google API rejects. In 0.84 that file moved to
+# dist/api/google-generative-ai.js and gained `isGemma4Model()`, whose
+# `getDisabledThinkingConfig()` returns `{ thinkingLevel: "MINIMAL" }` instead.
+# Neither string the patch matched still exists.
+#
+# Narrower than what it replaces, deliberately and worth knowing: the patch
+# gated on `model.id.startsWith("gemma")` — every Gemma — while `isGemma4Model`
+# is `/gemma-?4/`, so anything else still falls through to `thinkingBudget: 0`.
+# pi's built-in Google catalog only ships gemma-4 ids, so reaching the gap needs
+# a hand-authored models.json entry for e.g. gemma-3 marked `reasoning: true`.
+# If that turns up, fix it upstream rather than reinstating a source patch.
+#
+# Deleted rather than updated for a second reason: the patch swallowed every
+# error (`catch(e) {}`) and only wrote when its marker was absent, so once pi
+# moved the file it silently did nothing while still reading as protection. A
+# no-op that looks like a safeguard is worse than no safeguard. If a future pi
+# regresses here, reinstate it as a build step that FAILS when its pattern does
+# not match.
 
 # Fix ownership of all mercury home dir artifacts before switching user.
-# Placed here — after the last step that writes to /home/mercury (the pi patch),
+# Placed here — after the last step that writes to /home/mercury (the global
+# `bun add -g` above),
 # but before the volatile /app source COPYs below — so this expensive `chown -R`
 # (it walks the whole Chromium + .bun tree) lands in a stable cached layer.
 # Editing source files no longer invalidates it or forces the huge layer re-export.

package/container/Dockerfile.base

@@ -42,42 +42,34 @@ RUN echo '{"args":["--no-sandbox"]}' > /home/mercury/.puppeteerrc.json
 ENV CHROMIUM_FLAGS="--no-sandbox"
 
 # Install CLIs
-RUN bun add -g @earendil-works/pi-coding-agent@~0.79.6
+RUN bun add -g @earendil-works/pi-coding-agent@~0.84.1
 
 WORKDIR /app
 
 COPY container/agent-package.json /app/package.json
 RUN bun install --production
 
-# Patch pi: skip thinkingConfig for Gemma models (Google API rejects thinkingBudget for them,
-# but pi marks gemma-4 as reasoning:true and sends thinkingBudget:0 to disable it)
-RUN node <<'EOF'
-const fs = require('fs'), path = require('path');
-function patch(dir) {
-  try {
-    for (const f of fs.readdirSync(dir)) {
-      const p = path.join(dir, f);
-      try {
-        if (fs.statSync(p).isDirectory()) patch(p);
-        else if (f === 'google.js' && p.includes('@earendil-works/pi-ai')) {
-          let c = fs.readFileSync(p, 'utf8');
-          const noThinking = '&& !model.id.startsWith("gemma")';
-          const p1 = 'if (options.thinking?.enabled && model.reasoning) {';
-          const p2 = 'else if (model.reasoning && options.thinking && !options.thinking.enabled) {';
-          if (!c.includes(noThinking)) {
-            c = c.replace(p1, 'if (options.thinking?.enabled && model.reasoning ' + noThinking + ') {');
-            c = c.replace(p2, 'else if (model.reasoning && options.thinking && !options.thinking.enabled ' + noThinking + ') {');
-            fs.writeFileSync(p, c);
-            console.log('Patched:', p);
-          }
-        }
-      } catch(e) {}
-    }
-  } catch(e) {}
-}
-patch('/home/mercury/.bun');
-patch('/app/node_modules');
-EOF
+# pi >= 0.84 handles Gemma 4's thinking config itself, so the patch that used to
+# live here is gone. It string-replaced two exact lines in pi-ai's
+# dist/providers/google.js to stop `thinkingBudget: 0` being sent to Gemma
+# models, which the Google API rejects. In 0.84 that file moved to
+# dist/api/google-generative-ai.js and gained `isGemma4Model()`, whose
+# `getDisabledThinkingConfig()` returns `{ thinkingLevel: "MINIMAL" }` instead.
+# Neither string the patch matched still exists.
+#
+# Narrower than what it replaces, deliberately and worth knowing: the patch
+# gated on `model.id.startsWith("gemma")` — every Gemma — while `isGemma4Model`
+# is `/gemma-?4/`, so anything else still falls through to `thinkingBudget: 0`.
+# pi's built-in Google catalog only ships gemma-4 ids, so reaching the gap needs
+# a hand-authored models.json entry for e.g. gemma-3 marked `reasoning: true`.
+# If that turns up, fix it upstream rather than reinstating a source patch.
+#
+# Deleted rather than updated for a second reason: the patch swallowed every
+# error (`catch(e) {}`) and only wrote when its marker was absent, so once pi
+# moved the file it silently did nothing while still reading as protection. A
+# no-op that looks like a safeguard is worse than no safeguard. If a future pi
+# regresses here, reinstate it as a build step that FAILS when its pattern does
+# not match.
 
 COPY src/agent/container-entry.ts /app/src/agent/container-entry.ts
 COPY src/agent/model-capabilities-core.ts /app/src/agent/model-capabilities-core.ts

package/container/agent-package.json

@@ -3,6 +3,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "~0.79.6"
+    "@earendil-works/pi-coding-agent": "~0.84.1"
   }
 }

package/docs/configuration.md

@@ -39,6 +39,41 @@ context:
 
 Per-space overrides via `mrctl config set context.<key> <value>` always win over YAML defaults; YAML re-reads on restart do not overwrite an existing space row.
 
+## Operator alerts (`alerts:`)
+
+When a provider OAuth credential can no longer be refreshed, every space stops
+answering until someone re-authenticates on the host. Mercury DMs the configured
+operators so the outage does not wait for a human to read the logs.
+
+```yaml
+alerts:
+  enabled: true              # default: true
+  cooldown_ms: 21600000      # 60000 – 604800000 (default: 6h)
+```
+
+Env equivalents: **`MERCURY_ALERTS_ENABLED`**, **`MERCURY_ALERTS_COOLDOWN_MS`**.
+
+- **Recipients** are the ids already listed in `permissions.admins` (`MERCURY_ADMINS`)
+  and `dm_auto_space.admin_ids` (`MERCURY_DM_AUTO_SPACE_ADMIN_IDS`)
+  — there is no separate alert-recipient key. An id is alerted only when it
+  resolves to an existing space **with a linked conversation**, i.e. a chat
+  Mercury can actually send into; an alert never creates a space. With no
+  configured admin, or none that has ever messaged the bot, the alert has
+  nowhere to go — Mercury logs that fact at ERROR and leaves the cooldown
+  unclaimed, so the next failure tries again.
+- **Channel** is the ordinary adapter outbox, the same path scheduled-task
+  failures use. It carries no agent run and no LLM, so it still works when the
+  agent's own credential is what died.
+- **`cooldown_ms`** is the minimum gap between identical alerts, per credential
+  and per reason. It is deliberately long: the alert names a manual recovery
+  step, and repeating it while an operator performs it adds nothing. The state is
+  stored in the database, so a crash-looping service does not re-alert on every
+  restart. A successful credential load clears it — if the credential dies again
+  later, that is news and alerts immediately.
+- **Transient failures** (HTTP 408/429/5xx from the token endpoint) alert only
+  after three in a row; a single blip heals itself. A rejected refresh token, or
+  a cause that could not be classified, alerts on the first occurrence.
+
 ## Ambient group context
 
 In linked group chats, messages that don't trigger the bot are stored as **ambient context** (author-attributed) so it can answer questions about conversation it overheard. Every message in a linked group becomes a row, bounded on both ends:
@@ -74,6 +109,57 @@ Container env passthrough: all — these vars reach every space's container and
 
 For secrets that only host-side hooks and jobs need, prefer `mercury.env({ from: "…", hostOnly: true })`, which keeps them out of containers in either mode. For credentials the agent should never hold at all, use a host-side capability handler (`mercury.capability()`), which runs the privileged call on the host and returns only the result.
 
+## Agent run traces (`agent.trace_runs`)
+
+Captures pi's raw output from inside each agent container, with arrival timestamps, and copies it to `<dataDir>/traces/` before the container is reaped:
+
+```yaml
+agent:
+  trace_runs: false          # false (default) | true
+```
+
+Env: `MERCURY_CONTAINER_TRACE_RUNS`.
+
+Agent containers run with `--rm`, so pi's session logs die with the container. That is fine until a run misbehaves — a turn that hits `container_timeout_ms` is killed and leaves **nothing** to show where its time went. Tracing exists for exactly that question.
+
+Each harvested file is `<dataDir>/traces/<container-name>.jsonl`, one JSON object per line:
+
+```json
+{"atMs":0,"stream":"meta","data":"{\"piSpawnedAtIso\":\"2026-08-13T09:15:02.104Z\"}"}
+{"atMs":812,"stream":"stdout","data":"{\"type\":\"message_start\"…"}
+{"atMs":47310,"stream":"stdout","data":"{\"type\":\"tool_call\"…"}
+```
+
+- `atMs` — milliseconds since pi was spawned. **A long gap between consecutive lines is the finding**: it says which call the run was sitting inside.
+- `stream` — `stdout`, `stderr`, or `meta`.
+- A trace with no closing `meta` line carrying `exitCode` means the container was **killed** rather than exiting — itself a diagnosis. A `meta` line carrying `spawnError` instead means pi never started, which looks similar but is a different fault.
+
+> **One file can hold several segments.** A run with a model chain, or one that retries a retryable failure, invokes pi more than once, and every invocation appends to the same file. Each one opens with its own `piSpawnedAtIso` `meta` line and **restarts `atMs` from zero**.
+>
+> So: split the file on `meta` lines carrying `piSpawnedAtIso`, and treat each segment separately. Comparing `atMs` across a boundary yields a negative gap and hides however long the earlier leg took — which matters, because a retry fires on exactly the misbehaving runs a trace is opened for. Concatenating `stdout` reconstructs pi's raw output byte for byte **within a segment**; glued across segments it parses as neither.
+
+Writes go through `appendFileSync` rather than a buffered stream, deliberately: a buffered write loses whatever is in userspace when the process is SIGKILLed, which is the case the trace is for.
+
+To find where a slow run actually spent its time — the largest gap between consecutive lines, and what the run was doing when it stalled:
+
+```bash
+bun -e 'const ls=require("fs").readFileSync(process.argv[1],"utf8").trim().split("\n").map(l=>JSON.parse(l));
+let prev=0,seg=0,w={gapMs:0};for(const l of ls){
+if(l.stream==="meta"&&String(l.data).includes("piSpawnedAtIso")){seg++;prev=0;continue}
+const g=l.atMs-prev;if(g>w.gapMs)w={gapMs:g,seg,atMs:l.atMs,after:String(l.data).slice(0,160)};prev=l.atMs}
+console.log(w)' .mercury/traces/<container-name>.jsonl
+```
+
+The `prev=0` reset at each `meta` line is what keeps a multi-leg run honest — without it the boundary produces a negative gap and the earlier leg's stall never wins.
+
+`after` is the output that arrived *when the gap ended*, so the call that hung is the one immediately before it.
+
+> ⚠️ **A trace contains the full prompt and the full reply in clear text** — real conversation content, including anything group members said. Treat it like `log_level: debug`: switch it on for a bounded window, capture the run you need, and switch it back.
+
+`<dataDir>/traces/` is swept by the storage cleanup: a trace file is deleted once it is older than **`MERCURY_TRACE_TTL_DAYS`** (default `7`). The sweep runs whether or not `agent.trace_runs` is currently on — otherwise switching tracing off would strand that window's traces on disk permanently, which is the case the retention exists for. Shorten it if traces are being captured on a host where the conversation content is sensitive; deleting files by hand is still fine at any time.
+
+> ⚠️ **Changing this setting needs an agent image rebuild, not just a restart.** The capture half lives in `src/agent/container-entry.ts`, which is baked into the image (`container/Dockerfile`). A restart alone deploys the host-side half and leaves tracing silently doing nothing.
+
 ## Extension config defaults (`extensions:`)
 
 Deployment-wide defaults for extension config keys, applied to **every space** (including auto-created DM spaces) at read time:

package/docs/context-architecture.md

@@ -68,6 +68,12 @@ The session boundary (`chat_state.min_message_id`) excludes messages older than
 
 ```
 <caller id="…" name="…" role="…" space="…" />
+<run_budget>                            ← wall-clock window for this run
+  <started_at>…</started_at>
+  <killed_at>…</killed_at>              ← host kills the container here
+  <begin_final_answer_by>…</begin_final_answer_by>
+  <total_budget>…</total_budget>
+</run_budget>
 <episodic_memory>…</episodic_memory>   ← MEMORY.md (if present)
 <active_episodes>…</active_episodes>   ← relevance-scored episode snippets
 <history>                               ← sliding window from DB
@@ -85,6 +91,20 @@ The session boundary (`chat_state.min_message_id`) excludes messages older than
 [user prompt text]
 ```
 
+`<run_budget>` carries the wall clock the host enforces. `containerTimeoutMs`
+kills the container at `killed_at`, and before this block existed the agent had
+no way to learn that — the first and only signal was SIGKILL, too late to pace
+the work or save partial findings. `begin_final_answer_by` reserves a
+proportional slice of the budget (20%, floored at 30s, capped at 5min) for
+composing and sending the answer. The block is omitted entirely when the host
+supplies no window, or an incoherent one — a missing budget beats one claiming
+the run is already over.
+
+The matching `## Run budget` instructions live in the system prompt. They are
+gated more tightly than the block itself: a toolless model gets the block (the
+kill time is useful context regardless) but not the instructions, which all
+assume a shell to run `date` in and a file tool to save findings with.
+
 ---
 
 ## Why Not a Pi Session File?

package/docs/deployment.md

@@ -99,6 +99,42 @@ Not currently supported via `mercury service`. Options:
 2. **NSSM**: Use [NSSM](https://nssm.cc/) to wrap Mercury as a Windows service
 3. **PM2**: Use `pm2 start "mercury run" --name mercury`
 
+## Upgrading
+
+```bash
+mercury upgrade            # to the latest published version
+mercury upgrade 0.14.0     # to a specific version
+```
+
+On macOS and Linux this stops the managed service, installs the new version
+globally, and restarts the service.
+
+### Windows: stop Mercury before upgrading
+
+Windows will not let a file be replaced while a running process has it mapped.
+Mercury reaches `sharp` transitively (via `@whiskeysockets/baileys`, which loads
+it on demand to build image thumbnails), and importing sharp maps
+`libvips-*.dll` out of the global install tree. Once a running Mercury has
+handled a single image, a plain `npm install -g mercury-agent@latest` fails:
+
+```
+npm error code EBUSY
+npm error EBUSY: resource busy or locked
+npm error path ...\node_modules\@img\sharp-win32-x64\lib\libvips-42.dll
+```
+
+`mercury upgrade` detects this before npm does and stops with the list of locked
+files instead of leaving a rolled-back install behind. The fix is to stop Mercury
+first:
+
+1. Stop every running Mercury — `Ctrl+C` in the `mercury run` terminal, or stop
+   the NSSM / Task Scheduler / PM2 entry wrapping it.
+2. `mercury upgrade`
+3. Start Mercury again.
+
+Mercury's own CLI does not load the WhatsApp stack at startup, so running
+`mercury upgrade` never locks the tree it is replacing.
+
 ## Auto-Restart Behavior
 
 Both systemd and launchd are configured to automatically restart Mercury if it crashes:

package/examples/extensions/README.md

@@ -9,4 +9,5 @@ Real-world Mercury extensions. Copy any of these into `.mercury/extensions/` to
 | **gws** | Google Workspace (Drive/Gmail/Calendar/etc.) | cli, skill, permission (admin-only default) |
 | **pinchtab** | Browser automation via Playwright | cli, skill, permission, `before_container` hook (env + system prompt) |
 | **napkin** | Obsidian vault management + KB distillation | cli, skill, permission, `workspace_init` hook, `before_container` hook, job, config, widget, store |
+| **poster** | Styled posters with correct Hebrew/RTL text — AI background art + deterministic HTML typography | cli, skill, permission, env, config, `requires`, `before_container` hook (config → env) |
 

package/examples/extensions/gws/index.ts

@@ -56,9 +56,42 @@ const gwsEnv = {
 const CREDENTIALS_FILE = "/tmp/gws-credentials.json";
 
 export default function (mercury: MercuryExt) {
+  // The gws CLI can only take refresh-token credentials from a file, so someone
+  // has to materialize GWS_CREDENTIALS_JSON before the first command runs. The
+  // before_container hook can't (see the comment on that hook below), and asking
+  // the skill to do it makes credential delivery depend on the model remembering
+  // a prose instruction. Instead, /usr/local/bin/gws is a wrapper that does it on
+  // every invocation and execs the real binary.
+  //
+  // Ordering note: parseInstallCommand() keeps a command that mixes a package
+  // manager with shell parts intact as a single shell step, which is what makes
+  // the `mv` reliably run after the npm install. Do NOT split this into separate
+  // mercury.cli() declarations — mergeInstalls() would then reorder npm ahead of
+  // shell only by coincidence of grouping, and the wrapper would be clobbered.
   mercury.cli({
     name: "gws",
-    install: "npm install -g @googleworkspace/cli",
+    install: [
+      "npm install -g @googleworkspace/cli",
+      'mv "$(command -v gws)" /usr/local/bin/gws-real',
+      // Written line-by-line via printf so the credentials never reach a traced
+      // shell; $GWS_CREDENTIALS_JSON is single-quoted here and expanded only at
+      // runtime, inside the wrapper.
+      "printf '%s\\n' " +
+        "'#!/bin/sh' " +
+        "'if [ -n \"$GWS_CREDENTIALS_JSON\" ]; then' " +
+        `'  c="\${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-${CREDENTIALS_FILE}}"' ` +
+        "'  t=\"$c.$$\"' " +
+        "'  (umask 077; printf %s \"$GWS_CREDENTIALS_JSON\" > \"$t\")' " +
+        // Credentials changed (rotation, or a different caller in a reused
+        // container) invalidates the cached access token alongside them.
+        "'  cmp -s \"$t\" \"$c\" 2>/dev/null || rm -f \"${GOOGLE_WORKSPACE_CLI_CONFIG_DIR:-$HOME/.config/gws}/token_cache.json\"' " +
+        "'  mv -f \"$t\" \"$c\"' " +
+        "'  GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=\"$c\"; export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE' " +
+        "'fi' " +
+        "'exec /usr/local/bin/gws-real \"$@\"' " +
+        "> /usr/local/bin/gws",
+      "chmod 755 /usr/local/bin/gws",
+    ].join(" && "),
   });
 
   mercury.permission({ defaultRoles: ["admin"] });

package/examples/extensions/gws/skill/SKILL.md

@@ -23,16 +23,20 @@ Use the `gws` CLI via Bash for all Google Workspace operations.
 | JSON objects or arrays | Summarise in prose |
 | Email `labelIds`, `threadId`, `messageId` | Never shown |
 
-## Credentials setup (run once per session before any gws command)
+## Credentials
 
-`GWS_CREDENTIALS_JSON` contains the credentials as a JSON string. Materialize it to the path gws expects, then verify auth:
+Credentials are set up automatically — there is **no** setup step to run. Never
+write a credentials file yourself and never set
+`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`; the `gws` command does both on every
+invocation.
 
-```bash
-[ -n "$GWS_CREDENTIALS_JSON" ] && echo "$GWS_CREDENTIALS_JSON" > "${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-/tmp/gws-credentials.json}" && export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-/tmp/gws-credentials.json}"
-gws auth status
-```
+If a command fails on authentication, run `gws auth status` and report the cause
+accurately:
 
-If `auth_method` is not `none`, credentials are ready. Skip this step on subsequent calls in the same session (the file persists in /tmp for the container lifetime).
+| `gws auth status` says | What it actually means — report this |
+|---|---|
+| `"auth_method": "none"` | The caller does not have the `gws` permission, or no Google Workspace connection has been set up for this deployment. Say that — do **not** say Google Workspace is broken or misconfigured. |
+| `"auth_method": "oauth2"` but the command still fails | Credentials are present and delivered. The failure is API-side (revoked token, missing scope, or a per-service permission), not a Mercury configuration problem. Report the API's own error message. |
 
 ## Dispatch table
 

package/examples/extensions/longview/index.ts

@@ -20,6 +20,7 @@ import { join, resolve } from "node:path";
 import {
   getPiAuthCredential,
   parseOAuthTokenEnv,
+  providerCredentialEnvVar,
 } from "mercury-agent/storage/pi-auth";
 import {
   DEFAULT_THRESHOLD,
@@ -130,12 +131,23 @@ export default function (mercury: {
     const authPath = resolve(
       config.authPath ?? join(config.globalDir, "auth.json"),
     );
+    // Name the credential the way pi reads it for this provider — the same
+    // shared table container-runner injects from, so the two spawn paths can't
+    // drift apart again. Asked *before* resolving, in that same order: a
+    // provider pi reads no env var for (openai-codex) can never be served, and
+    // resolving would spend a single-use refresh token to learn that. Only
+    // non-anthropic providers can land here, so the fail-fast below is
+    // unaffected — anthropic always has an env var.
+    const credEnvVar = providerCredentialEnvVar(config.modelProvider);
+    if (!credEnvVar) {
+      return { ok: true, env };
+    }
     const cred = await getPiAuthCredential({
       provider: config.modelProvider,
       authPath,
     });
     if (cred.status === "ok") {
-      env.ANTHROPIC_API_KEY = cred.apiKey;
+      env[credEnvVar] = cred.apiKey;
       return { ok: true, env };
     }
 

package/examples/extensions/napkin/index.ts

@@ -14,6 +14,7 @@ import { delimiter, dirname, join, resolve } from "node:path";
 import {
   getPiAuthCredential,
   parseOAuthTokenEnv,
+  providerCredentialEnvVar,
 } from "mercury-agent/storage/pi-auth";
 
 const KNOWLEDGE_DIR = "knowledge";
@@ -458,12 +459,23 @@ export default function (mercury: {
     const authPath = resolve(
       config.authPath ?? join(config.globalDir, "auth.json"),
     );
+    // Name the credential the way pi reads it for this provider — the same
+    // shared table container-runner injects from, so the two spawn paths can't
+    // drift apart again. Asked *before* resolving, in that same order: a
+    // provider pi reads no env var for (openai-codex) can never be served, and
+    // resolving would spend a single-use refresh token to learn that. Only
+    // non-anthropic providers can land here, so the fail-fast below is
+    // unaffected — anthropic always has an env var.
+    const credEnvVar = providerCredentialEnvVar(config.modelProvider);
+    if (!credEnvVar) {
+      return { ok: true, env };
+    }
     const cred = await getPiAuthCredential({
       provider: config.modelProvider,
       authPath,
     });
     if (cred.status === "ok") {
-      env.ANTHROPIC_API_KEY = cred.apiKey;
+      env[credEnvVar] = cred.apiKey;
       return { ok: true, env };
     }
 

package/examples/extensions/poster/index.ts

@@ -0,0 +1,92 @@
+/**
+ * poster — styled poster generation with correct Hebrew (and other RTL) text.
+ *
+ * Two layers, deliberately separated:
+ *
+ *   1. art   — an image model paints the background (photographic scene, textures,
+ *              product plates). Prompted to render NO text at all.
+ *   2. render — Chromium composites the copy from an HTML template using a real
+ *              embedded Hebrew font.
+ *
+ * The split exists because no image model renders Hebrew reliably. Nano Banana Pro
+ * is the best available (Gemini 3 backbone plans layout before rendering) but
+ * accuracy is length-dependent — ~100% on headlines, ~80% at 15-30 words, ~60%
+ * beyond — and Arabic, the closest published RTL analogue to Hebrew, sits at ~75%
+ * per short line. A poster with twenty text runs is never fully clean. Layer 2
+ * makes the typography deterministic: fonts, RTL, kerning and safe-area geometry
+ * are code, not a prompt.
+ *
+ * No CLI install step is needed. The container base image is the Microsoft
+ * Playwright image and already provides `/usr/local/bin/chromium` plus Bun, so
+ * `mercury.cli()` only drops a shim onto the read-only skill mount.
+ */
+
+import type { MercuryExtensionAPI } from "mercury-agent/extensions/types";
+
+const EXT = "poster";
+
+/** Skill dir as mounted inside the container (read-only). */
+const SKILL_DIR = `/home/mercury/.pi/agent/skills/${EXT}`;
+
+export default function setup(mercury: MercuryExtensionAPI) {
+  // A shim rather than an npm package: the implementation ships in the skill
+  // directory, so there is nothing to publish and nothing to version separately.
+  mercury.cli({
+    name: EXT,
+    install: [
+      `printf '#!/bin/sh\\nexec bun ${SKILL_DIR}/scripts/poster.mjs "$@"\\n'`,
+      `> /usr/local/bin/${EXT}`,
+      `&& chmod +x /usr/local/bin/${EXT}`,
+    ].join(" "),
+  });
+
+  mercury.permission({ defaultRoles: ["admin", "member"] });
+
+  // Layer 2 is free; layer 1 needs whichever provider is configured. Keys are
+  // only injected for callers who hold the `poster` permission.
+  mercury.env({ from: "MERCURY_POSTER_GEMINI_KEY", as: "POSTER_GEMINI_KEY" });
+  mercury.env({ from: "MERCURY_POSTER_OPENAI_KEY", as: "POSTER_OPENAI_KEY" });
+
+  mercury.config("provider", {
+    description:
+      "Art-layer image provider: gemini (Nano Banana Pro), openai (GPT Image 2), or local (self-hosted HTTP endpoint).",
+    default: "gemini",
+    validate: (v) => v === "gemini" || v === "openai" || v === "local",
+  });
+
+  mercury.config("local_endpoint", {
+    description:
+      "HTTP endpoint for provider=local, e.g. http://host.docker.internal:8188/mercury-poster. POSTed {prompt,width,height}; must return {image_b64} or a raw PNG.",
+    default: "",
+  });
+
+  mercury.config("size", {
+    description:
+      "Default art-layer resolution: 1K, 2K or 4K. Gemini bills 2K and 1K identically, so 2K is the sensible floor.",
+    default: "2K",
+    validate: (v) => v === "1K" || v === "2K" || v === "4K",
+  });
+
+  // The CLI runs inside the container and cannot read space config directly, so
+  // resolve it host-side and hand it over as env.
+  mercury.on("before_container", async (event, ctx) => {
+    return {
+      env: {
+        POSTER_PROVIDER:
+          ctx.getConfig(event.spaceId, `${EXT}.provider`) ?? "gemini",
+        POSTER_LOCAL_ENDPOINT:
+          ctx.getConfig(event.spaceId, `${EXT}.local_endpoint`) ?? "",
+        POSTER_SIZE: ctx.getConfig(event.spaceId, `${EXT}.size`) ?? "2K",
+        POSTER_SKILL_DIR: SKILL_DIR,
+      },
+    };
+  });
+
+  // Both layers are driven from bash; without tool use the skill is inert.
+  // Note that `requires` gates the *skill* install, not the `cli()` install: on a
+  // chain leg with no tool use the `poster` shim still exists but points at a skill
+  // directory that was never copied. Harmless, but the failure reads as a bun
+  // stack trace rather than "command not found".
+  mercury.requires(["tools"]);
+  mercury.skill("./skill");
+}