mercury-agent 0.4.27 → 0.5.0

package/docs/authoring-profiles.md

@@ -0,0 +1,174 @@
+# Authoring Applicative Profiles
+
+The contract for building a **profile** — a package of deterministic business
+logic that wraps raw capabilities (Calendar, email, …) and scopes what members
+can do. Mercury (this repo) provides the schema, loader, permission scoping, and
+the host-side capability broker; **profiles live in a separate repo** and depend
+only on this contract.
+
+> Layers: **Mercury** = platform (messaging, spaces, permissions, tokens,
+> broker). **Capability extensions** = raw API access (e.g. `gws`), admin-only.
+> **Profiles** = deterministic domain logic wrapping capabilities, member-facing.
+
+## 1. Profile manifest — `mercury-profile.yaml`
+
+```yaml
+name: barber-appointments            # lowercase-kebab; required
+description: Appointment booking for a barber shop
+version: 0.1.0
+
+agents_md: ./AGENTS.md               # optional; copied to the global AGENTS.md
+
+# Raw capability extensions this profile requires to be installed. Validated at
+# apply time — activation fails loudly if any are missing.
+capabilities:
+  - gws
+
+# Extensions this profile ships (copied into .mercury/extensions).
+extensions:
+  - name: barber
+    source: ./extensions/barber
+
+# EXHAUSTIVE member permission set while active. When present it REPLACES the
+# default member permissions — nothing is merged in — so raw capabilities stay
+# admin-only unless listed here. Omit entirely to keep built-in defaults.
+member_permissions:
+  - prompt
+  - prefs.get
+  - barber                           # the profile's own capability, NOT gws
+
+# Optional env the profile needs (host-side credentials for capabilities).
+env:
+  - key: MERCURY_BARBER_BUSINESS_HOURS
+    description: "Business hours"
+    default: "09:00-18:00"
+
+# Project-wide agent persona, injected into every container's system prompt.
+system_prompt: |
+  You are a barber shop assistant. Help each customer book, view, and cancel
+  ONLY their own appointments. Never reveal other customers' schedules.
+
+defaults:
+  trigger_patterns: always
+```
+
+Apply it with `mercury profile apply <name|path|git-url>`. That validates
+capabilities, copies extensions/AGENTS.md, and persists activation to
+`.mercury/active-profile.json`, which Mercury loads at startup.
+
+## 2. The capability broker (where the business logic runs)
+
+A profile's privileged work runs **on the host**, so credentials never enter the
+customer-controlled agent container. The profile's extension registers a
+handler; the agent invokes it through a thin CLI.
+
+### Register a handler (in the extension's `index.ts`)
+
+```ts
+import type { ExtensionSetupFn } from "mercury-agent"; // types from this repo
+
+const setup: ExtensionSetupFn = (mercury) => {
+  // Make the capability gate-able. Members get it via member_permissions.
+  mercury.permission({ defaultRoles: [] });
+
+  // Host-side credentials for the wrapped capability (never sent to the container).
+  mercury.env({ from: "MERCURY_BARBER_GOOGLE_CREDENTIALS" });
+
+  mercury.capability("barber", async (req, ctx) => {
+    // req.callerId is the TOKEN-DERIVED, unspoofable caller — safe for ownership.
+    switch (req.action) {
+      case "availability":
+        return { data: await listOpenSlots(req.body, ctx) };
+      case "book":
+        return { data: await book(req.callerId, req.body, ctx) };
+      case "cancel":
+        return { data: await cancelOwn(req.callerId, req.body, ctx) };
+      case "my-appointments":
+        return { data: await listOwn(req.callerId, ctx) };
+      default:
+        return { status: 400, data: { error: `unknown action: ${req.action}` } };
+    }
+  });
+};
+
+export default setup;
+```
+
+### The contract types (exported from this repo)
+
+```ts
+type CapabilityHandler = (
+  req: CapabilityRequest,
+  ctx: MercuryExtensionContext,
+) => Promise<CapabilityResult>;
+
+interface CapabilityRequest {
+  name: string;      // capability name
+  action: string;    // sub-action (book, cancel, …)
+  callerId: string;  // token-derived, TRUSTWORTHY — use for ownership checks
+  spaceId: string;
+  body: unknown;     // parsed JSON request body (or null)
+}
+
+interface CapabilityResult {
+  status?: number;   // default 200
+  data: unknown;     // JSON-serializable response
+}
+```
+
+`ctx` (`MercuryExtensionContext`) gives you `db`, `config`, `log`, and
+`hasCallerPermission(spaceId, callerId, permission)`. Store per-profile state via
+`mercury.store` (namespaced KV) or your own tables through `ctx.db`.
+
+### How the agent invokes it
+
+Inside the container the agent runs:
+
+```
+mrctl capability barber book '{"slot":"2026-07-02T15:00"}'
+```
+
+→ `POST /api/capability/barber/book`. Document these commands for the agent in
+the extension's `SKILL.md` or the profile's `AGENTS.md`.
+
+## 3. Permission & security model (non-negotiable)
+
+- **`member_permissions` is exhaustive.** List every permission a member may
+  hold, including the capability name (e.g. `barber`). Anything not listed —
+  including raw capabilities like `gws` — is unavailable to members.
+- **Authorization = permission named after the capability.** The broker route
+  requires the caller to hold the `<name>` permission; the same grant gates both
+  the `mrctl capability <name> …` CLI and the route. Keep capability name ==
+  permission name == the entry in `member_permissions`.
+- **Credentials stay on the host.** Put capability credentials in host env
+  (`mercury.env`) / `mercury.store` and use them only inside the handler. Never
+  expose a raw capability CLI (e.g. `gws`) to members — its secret would be
+  readable inside the container.
+- **Enforce ownership with `req.callerId`.** It is token-derived and cannot be
+  spoofed by the container. Never trust an id passed in `req.body`.
+- **`callerId === "system"`** for scheduled/system runs — handle it explicitly
+  (e.g. skip per-customer ownership).
+
+## 4. Suggested profile repo layout
+
+```
+<profile-repo>/
+  barber/                      # one folder per profile
+    mercury-profile.yaml
+    AGENTS.md
+    extensions/
+      barber/
+        index.ts               # registers permission + capability
+        package.json
+```
+
+Depend on this repo (`mercury-agent`) for the types
+(`ExtensionSetupFn`, `CapabilityRequest`, `CapabilityResult`,
+`MercuryExtensionContext`). See `src/extensions/types.ts` for the full surface.
+
+## 5. Local test loop
+
+1. `mercury profile apply ./barber`
+2. `mercury service install` (builds the derived image with the extension CLI)
+3. DM the bot as a non-admin number; confirm you can `book`/`cancel` only your
+   own appointments and cannot reach `gws`/Gmail.

package/docs/debug/major/2026-07-01-strict-yaml-schema-crash.md

@@ -0,0 +1,85 @@
+# Bug: Strict YAML schema crashes Mercury on unknown config keys
+
+**Status**: Fixed
+**Severity**: major
+**Slug**: strict-yaml-schema-crash
+**Reported**: 2026-07-01
+**Last updated**: 2026-07-01
+
+---
+
+## Summary
+`mercuryFileSchema` uses `.strict()` on all Zod objects, causing Mercury to crash on startup when `mercury.yaml` contains any unrecognized key — a typo, a key from a newer version, or a renamed field. Combined with PM2's default unlimited restarts and Baileys' session-based auth, this creates a cascade: config error → crash loop → WhatsApp session revoked → extended downtime requiring manual QR re-scan.
+
+## Steps to Reproduce
+1. Add any unrecognized key to `mercury.yaml`, e.g. `dm_auto_space: { admin_numbers: ["123"] }` (renamed to `admin_ids` in 0.4.27)
+2. Start Mercury (`mercury run` or `mercury service install`)
+3. Mercury crashes with `Invalid mercury.yaml: dm_auto_space: Unrecognized key: "admin_numbers"`
+4. PM2 restarts Mercury in a crash loop, each restart fails identically
+5. Crash loop causes WhatsApp session to expire (reason=401), requiring re-authentication
+
+## Expected Behavior
+Mercury should log a warning about the unknown key and continue starting normally. Invalid *values* (wrong type, out of range) should still crash — the distinction is between "unknown key" (safe to ignore) and "invalid value" (can't run correctly).
+
+## Actual Behavior
+Mercury throws an unhandled error and exits. PM2 restart loop compounds the damage by expiring the WhatsApp session.
+
+## Impact
+- **Service downtime** — entire Mercury instance goes down, no messages processed
+- **WhatsApp session loss** — crash loop causes Baileys auth to expire, requiring manual QR re-scan
+- **Version upgrade risk** — any field rename between versions (like `admin_numbers` → `admin_ids`) crashes deployments that haven't updated their yaml
+- **Typo intolerance** — a single typo in mercury.yaml takes down the whole service
+
+## Root Cause Analysis
+
+Two separate concerns are conflated by `.strict()`:
+
+1. **Unknown keys** (typo, version mismatch, renamed field) — should warn, not crash. The config isn't invalid, it's just unrecognized. Even with WABA, crashing because of a typo is wrong.
+2. **Invalid values** (wrong type, out of range) — should crash. If `port: "abc"`, the service can't run correctly. Fail fast is correct.
+
+The Baileys crash-loop cascade is a separate but compounding problem — on the unofficial WhatsApp protocol, rapid reconnect attempts trigger session revocation by Meta. This makes *any* crash loop catastrophic, not just config-related ones.
+
+## Suspected Location
+- `src/config-file.ts` — `mercuryFileSchema` (line 25) and all nested objects use `.strict()`, which rejects unknown keys
+- `src/config-file.ts` — `mergeRawMercuryConfig()` (line 352) calls `safeParse` but throws on failure instead of warning
+
+## Fix Plan
+
+### Phase 1 — Short term (now)
+
+**Config resilience:** Remove `.strict()` from `mercuryFileSchema` and all nested objects (Zod default behavior strips unknown keys silently). Add a post-parse diff that logs warnings for any stripped keys so operators notice typos without crashing.
+
+**PM2 restart limit:** Configure `max_restarts` and `min_uptime` in the PM2 ecosystem config so a crash loop stops after N attempts instead of running forever. Send an alert when the limit is hit.
+
+### Phase 2 — Medium term
+
+**Circuit breaker for container errors:** Container failures (model API errors, malformed responses) should not crash the host process. The host should log the error, reply to the user with a friendly message, and continue.
+
+### Phase 3 — Long term (WABA)
+
+With WABA, auth is a permanent API token — crash loops no longer revoke auth. At that point, strict validation on values remains correct (fail fast on truly invalid config), while unknown keys should still warn-not-crash regardless of the WhatsApp transport.
+
+## Notes
+- Industry standard (Kubernetes, OpenCode/SST) is to warn on unknown keys, not crash. Zod's default behavior is `.strip()` (silently remove unknown keys) — Mercury explicitly opted into `.strict()` which is the most aggressive mode.
+- OpenCode hit the same bug and fixed it by switching to passthrough + warnings (github.com/sst/opencode/issues/6145).
+- The Baileys session loss is a known risk of the unofficial protocol — Meta actively discourages bot usage on consumer WhatsApp. WABA eliminates this class of risk entirely.
+
+---
+
+## Post-Mortem
+
+### Investigation
+Read `src/config-file.ts` — `mercuryFileSchema` and all 13 nested Zod object schemas used `.strict()`. The `mergeRawMercuryConfig()` function called `safeParse()` correctly but threw unconditionally on any parse failure, including unknown keys. The Zod `.strict()` mode treats unknown keys the same as type errors — both produce parse failures.
+
+### Root Cause
+`.strict()` on Zod object schemas rejects unknown keys with the same error severity as invalid values. There was no distinction between "unrecognized key" (safe to ignore) and "invalid value" (can't run). A renamed field (`admin_numbers` → `admin_ids`) caused Mercury to crash on startup, PM2's unlimited restarts amplified this into a crash loop, and the rapid reconnection pattern caused WhatsApp/Baileys to revoke the session.
+
+### Fix
+- **`src/config-file.ts`**: Replaced all 13 `.strict()` calls with `.strip()` (Zod default — silently removes unknown keys). Added `KNOWN_TOP_KEYS` and `KNOWN_SECTION_KEYS` static key sets, and a `warnUnknownKeys()` function that runs before parsing to log `[WARN]` messages for any unrecognized keys. Invalid values (wrong types, out-of-range numbers) still throw — only unknown keys are tolerated.
+- **`mergeRawMercuryConfig()`**: Added an optional `log` parameter (defaults to `console.warn`) so the warning function is testable. Called `warnUnknownKeys()` before `safeParse()`.
+- **`tests/config.test.ts`**: Added 4 tests: unknown top-level key warns but doesn't crash, unknown nested key warns, invalid value type still throws, valid config produces no warnings.
+
+### Lessons
+- Separate "unknown key" from "invalid value" in config validation — they have different severity and different correct responses.
+- Any feature that adds config fields must consider version mismatch — a user on version N with a yaml from version N+1 should not crash.
+- On Baileys, any crash loop is catastrophic — PM2 restart limits should be configured.

package/docs/ideas/business-extensions.md

@@ -0,0 +1,48 @@
+---
+name: business-extensions
+description: Dedicated business extensions that wrap raw capabilities (GWS, etc.) with deterministic domain logic — e.g. a barber-appointments extension
+metadata:
+  type: idea
+---
+
+# Business Extensions
+
+**Status**: Idea
+**Created**: 2026-07-01
+
+## Problem
+
+Raw capability extensions (GWS Calendar, Gmail, web search) expose generic APIs. Business workflows (appointment booking, customer management) require deterministic logic — availability checks, double-booking prevention, confirmation flows — that can't be reliably delegated to the LLM via prompting alone.
+
+Today the only options are: (1) let the LLM orchestrate raw APIs via system prompt instructions (not deterministic enough), or (2) build a full standalone application outside Mercury. Neither is ideal.
+
+## Idea
+
+A pattern for **business extensions** that wrap raw capabilities with domain-specific, deterministic logic and expose simplified CLIs to the agent.
+
+Example: `barber-appointments` extension
+- Wraps GWS Calendar internally
+- Exposes: `book-appointment`, `list-availability`, `cancel-appointment`
+- Enforces business rules in code: no double-booking, business hours only, minimum slot duration, confirmation required
+- Registers as a single Mercury permission (`barber-appointments`)
+- The LLM calls the simplified CLI; the extension handles the hard logic deterministically
+
+This separates concerns:
+- **Mercury** = platform (messaging, spaces, permissions, rate limits)
+- **Capability extensions** = raw API access (GWS, web search, etc.) — admin-only or building blocks
+- **Business extensions** = deterministic domain logic wrapping capabilities — customer-facing
+
+## Why not just prompt engineering?
+
+LLMs are non-deterministic. For a barber shop, a double-booked appointment or a cancelled-without-confirmation is a real-world problem. Business rules must be enforced in code, not hoped for via prompts.
+
+## Open questions
+
+- Should business extensions be a separate category in the extension system, or just a convention?
+- How do business extensions declare their dependency on capability extensions (e.g., `barber-appointments` needs `gws`)?
+- Should there be a template/scaffold for creating business extensions?
+- How does this relate to "profiles" — is a profile = business extension + config preset?
+
+## First candidate
+
+`barber-appointments` — Calendar-based appointment booking for a barber shop. Quick win for first customer impression. Gmail integration deferred.

package/docs/pending-updates/applicative-profiles.md

@@ -0,0 +1,15 @@
+---
+slug: applicative-profiles
+shipped: 2026-07-01
+---
+
+## ROADMAP changes
+
+**Remove from:** Next (table row where Item = applicative-profiles)
+
+**Also pull:** none
+
+**Add to Shipped table** (insert at top, after header row):
+| **applicative-profiles** | 2026-07-01 | Generic profile layer: manifest schema, exhaustive member scoping, host-side capability broker |
+
+**Milestone Map:** none

package/docs/pending-updates/caller-bound-capability-token.md

@@ -0,0 +1,15 @@
+---
+slug: caller-bound-capability-token
+shipped: 2026-07-01
+---
+
+## ROADMAP changes
+
+**Remove from:** Next (table row where Item = caller-bound-capability-token)
+
+**Also pull:** none
+
+**Add to Shipped table** (insert at top, after header row):
+| **caller-bound-capability-token** | 2026-07-01 | Per-turn unspoofable caller token for host API auth; also hardens TradeStation |
+
+**Milestone Map:** none

package/docs/runbooks/gws-oauth-setup.md

@@ -0,0 +1,211 @@
+# GWS OAuth Setup Runbook
+
+How to connect Google Calendar to a customer's Mercury assistant.
+
+## Prerequisites
+
+- Access to the Tagula GCP project (console.cloud.google.com, project "Tagula")
+- SSH access to the customer's VPS
+- The customer's `MERCURY_API_SECRET` (from their `.env`)
+- The customer's Google account email
+
+## Option A: Auth Gateway (preferred — works on mobile + desktop)
+
+Use this when `auth.tagula.ai` is set up. Customer just clicks a link.
+
+### One-time gateway setup
+
+> Skip if the gateway is already running at `auth.tagula.ai`.
+
+1. **DNS**: Add an A record for `auth.tagula.ai` → gateway server IP (GoDaddy DNS panel)
+
+2. **Server**: SSH into the gateway server and install nginx + certbot:
+   ```bash
+   apt-get update && apt-get install -y nginx certbot python3-certbot-nginx
+   ```
+
+3. **Nginx config** (`/etc/nginx/sites-available/auth-tagula`):
+   ```nginx
+   server {
+       listen 80;
+       server_name auth.tagula.ai;
+       location / {
+           proxy_pass http://127.0.0.1:3456;
+           proxy_set_header Host $host;
+           proxy_set_header X-Forwarded-For $remote_addr;
+       }
+   }
+   ```
+   ```bash
+   ln -s /etc/nginx/sites-available/auth-tagula /etc/nginx/sites-enabled/
+   nginx -t && systemctl reload nginx
+   ```
+
+4. **SSL**:
+   ```bash
+   certbot --nginx -d auth.tagula.ai
+   ```
+
+5. **Gateway config**: Copy `gateway-config.example.json` → `gateway-config.json`, fill in:
+   - `google.clientId` and `google.clientSecret` from the Tagula GCP project
+   - `google.redirectUri` = `https://auth.tagula.ai/oauth/callback`
+
+6. **GCP redirect URI**: In GCP Console → APIs & Services → Credentials → Web client → add `https://auth.tagula.ai/oauth/callback` to Authorized redirect URIs
+
+7. **Start gateway**:
+   ```bash
+   npm install -g pm2  # if not installed
+   pm2 start auth-gateway.js --name auth-gateway
+   pm2 save
+   ```
+
+### Per-customer setup
+
+1. **Add customer to gateway config** (`gateway-config.json`):
+   ```json
+   "assistants": {
+     "customer-name": {
+       "apiUrl": "http://<VPS_IP>:8787",
+       "apiSecret": "<MERCURY_API_SECRET from customer's .env>",
+       "envVar": "MERCURY_GWS_CREDENTIALS_JSON"
+     }
+   }
+   ```
+   Restart gateway: `pm2 restart auth-gateway`
+
+2. **Add test user in GCP**: GCP Console → Google Auth Platform → Audience → Add users → add customer's Gmail
+
+3. **Install gws extension on customer VPS** (if not already):
+   ```bash
+   ssh root@<VPS_IP>
+   # Via dashboard: go to http://<VPS_IP>:8787/dashboard/page/features → Install gws
+   # Or via API:
+   curl -X POST http://localhost:8787/api/console/extensions/install \
+     -H "Authorization: Bearer <API_SECRET>" \
+     -H "Content-Type: application/json" \
+     -d '{"catalogName": "gws"}'
+   ```
+
+4. **Send the link to customer**:
+   ```
+   https://auth.tagula.ai/connect/gws?assistant=customer-name
+   ```
+   Customer clicks → signs in with Google → sees "Connected!" → done.
+
+5. **Verify**: Check Mercury logs on the VPS:
+   ```bash
+   pm2 logs 'mercury run' --lines 20 --nostream | grep -i gws
+   ```
+   Should show: `Loaded extension: gws` and `Installed skill: gws`
+
+---
+
+## Option B: Manual (ngrok — no gateway needed)
+
+Use this before the gateway is set up, or as a one-off.
+
+### Setup
+
+1. **Install ngrok on customer VPS**:
+   ```bash
+   ssh root@<VPS_IP>
+   curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
+     | tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
+   echo 'deb https://ngrok-agent.s3.amazonaws.com buster main' \
+     | tee /etc/apt/sources.list.d/ngrok.list
+   apt-get update && apt-get install -y ngrok
+   ngrok config add-authtoken <YOUR_NGROK_TOKEN>
+   ```
+
+2. **Write callback script** (`/tmp/oauth-callback.js`):
+   ```bash
+   # Copy from tagula-agents-cloud-console/oauth-callback-standalone.js
+   # Update CLIENT_ID and CLIENT_SECRET from GCP
+   scp oauth-callback-standalone.js root@<VPS_IP>:/tmp/oauth-callback.js
+   ```
+
+3. **Start callback + ngrok**:
+   ```bash
+   ssh root@<VPS_IP>
+   nohup node /tmp/oauth-callback.js > /tmp/oauth-callback.log 2>&1 &
+   ngrok http 9999
+   ```
+   Note the ngrok URL (e.g., `https://abc123.ngrok-free.dev`)
+
+4. **Configure redirect URI**:
+   - Set redirect URI in the callback script:
+     ```bash
+     curl "http://localhost:9999/set-redirect?uri=https://<NGROK_URL>/oauth/callback"
+     ```
+   - Add same URL to GCP: APIs & Services → Credentials → Web client → Authorized redirect URIs
+
+5. **Add test user**: GCP → Google Auth Platform → Audience → Add customer's Gmail
+
+6. **Send OAuth link to customer**:
+   ```
+   https://accounts.google.com/o/oauth2/v2/auth?client_id=<CLIENT_ID>&redirect_uri=https://<NGROK_URL>/oauth/callback&response_type=code&scope=https://www.googleapis.com/auth/calendar.events&access_type=offline&prompt=consent
+   ```
+
+7. **After customer authorizes**:
+   - ngrok free tier shows an interstitial — customer clicks "Visit Site"
+   - Check logs: `cat /tmp/oauth-callback.log`
+   - Should show `SUCCESS - credentials saved`
+
+8. **Move credentials to correct .env** (the callback script writes to `.mercury/.env` but Mercury reads from project root `.env`):
+   ```bash
+   grep MERCURY_GWS /opt/path/to/assistant/.mercury/.env >> /opt/path/to/assistant/.env
+   sed -i '/MERCURY_GWS/d' /opt/path/to/assistant/.mercury/.env
+   ```
+
+9. **Restart Mercury and clean up**:
+   ```bash
+   pm2 restart 'mercury run'
+   # Kill callback server and ngrok
+   kill $(lsof -ti:9999) 2>/dev/null
+   pkill ngrok
+   rm /tmp/oauth-callback.js /tmp/oauth-callback.log
+   ```
+
+10. **Verify**:
+    ```bash
+    pm2 logs 'mercury run' --lines 20 --nostream | grep -i gws
+    ```
+
+---
+
+## Option C: Copy-paste URL (desktop only)
+
+Simplest, no infrastructure needed. Customer must be on a computer (not mobile).
+
+1. **Create Desktop-type OAuth client** in GCP (not Web) — allows `http://localhost` redirect
+2. **Generate OAuth URL** with `redirect_uri=http://localhost:1`
+3. **Send link to customer** — they click, authorize, Google redirects to localhost (fails)
+4. **Customer copies the full URL** from their browser bar and sends it back
+5. **Extract code and exchange**:
+   ```bash
+   # Extract code from the URL the customer sent
+   CODE="the_code_from_url"
+   curl -s -X POST https://oauth2.googleapis.com/token \
+     -d "code=$CODE&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&redirect_uri=http://localhost:1&grant_type=authorization_code"
+   ```
+6. **Set env var and restart** — copy the tokens JSON into `.env` as `MERCURY_GWS_CREDENTIALS_JSON='...'`
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `invalid_client` on Google consent | Client not propagated yet, or created in new Auth Platform UI | Wait 10 min, or recreate from legacy APIs & Services → Credentials |
+| Extension installs but doesn't load | `MERCURY_GWS_CREDENTIALS_JSON` not set or in wrong `.env` | Check `grep MERCURY_GWS .env` in project root |
+| `Removed stale skill: gws` in logs | Extension skipped by credential gate | Same as above — credential missing |
+| `Failed to build derived image` | `docker-buildx` not installed | `apt-get install docker-buildx` |
+| Customer's wrong Google account used | Browser auto-selects default account | Add all their accounts as test users, or use incognito |
+| ngrok "Visit Site" interstitial | Free tier warning | Customer clicks "Visit Site" — shows once |
+| `refresh_token_expires_in: 604799` | Token expires in 7 days (testing mode) | Publish the OAuth app in GCP to get non-expiring refresh tokens |
+
+## Important notes
+
+- **Test mode tokens expire in 7 days.** While the GCP app is in "Testing" status, refresh tokens expire after 7 days. To get permanent tokens, publish the app (requires Google verification for sensitive scopes). For now, re-run the OAuth flow when tokens expire.
+- **docker-buildx** is required on Linux servers for Mercury to build derived images with extension CLIs. Install with `apt-get install docker-buildx`.
+- **Rotate credentials** after sharing them in chat. Go to GCP → Credentials → Web client → rotate client secret. Update `gateway-config.json` and any callback scripts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.4.27",
+  "version": "0.5.0",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",