mercury-agent 0.4.26 → 0.4.28

package/docs/backlog/caller-bound-capability-token.md

@@ -0,0 +1,180 @@
+# Caller-Bound Capability Token
+
+**Status**: Backlog
+**Slug**: caller-bound-capability-token
+**Created**: 2026-07-01
+**Last updated**: 2026-07-01
+
+---
+
+## Goal
+
+Mercury's in-container CLIs (`mrctl` and extension CLIs) call back to the host control-plane API to perform privileged work. Today that callback authenticates with a **single shared secret** (`API_SECRET`, injected into every container) and the host **trusts the `x-mercury-caller` / `x-mercury-space` request headers verbatim** (`src/core/api.ts:50-72`, `src/cli/mrctl.ts:34-40`). Because `API_SECRET` is readable inside the container, any code running there can call the host API asserting **any** caller or space — i.e. caller identity is spoofable.
+
+This is acceptable today because host-brokered capabilities (TradeStation, TTS) are **admin-only** — everyone who can invoke them is already trusted. It becomes a security hole the moment an **untrusted member** gets a host-brokered capability, which is exactly what [[applicative-profiles]] introduces (e.g. a barber-shop customer who must only touch their own appointments). A spoofed caller header would let one customer act as another.
+
+This feature adds a **per-turn capability token** minted at container spawn, cryptographically bound to `{callerId, spaceId}`, that the host verifies and uses as the authoritative identity for authorization — instead of trusting request headers.
+
+## User Stories
+
+- As a Mercury operator, I want host-brokered capabilities to attribute each request to the real caller so an untrusted member cannot impersonate another member.
+- As a profile developer, I want a trustworthy `callerId` on the host side so I can enforce per-user ownership rules safely.
+- As a Mercury maintainer, I want existing admin-only brokers (TradeStation) to stop relying on spoofable headers, closing an inherited weakness.
+
+## MVP Scope
+
+**In scope:**
+- Mint a per-turn token at container spawn (`src/agent/container-runner.ts`), bound to `{callerId, spaceId}` plus an expiry, injected as an env var (e.g. `MERCURY_CALLER_TOKEN`)
+- Host-side verification in the API auth middleware (`src/core/api.ts`): when the token is present, derive `callerId`/`spaceId` **from the token**, not from `x-mercury-*` headers, for all authorization decisions
+- HMAC signing with a host-only key (no new dependency); token is opaque to the container
+- Migrate the TradeStation caller-bound confirm guard to token-derived identity (`src/core/routes/tradestation.ts:153-158, 245-254`)
+- Backward compatibility: shared-`API_SECRET` path remains for system/admin flows; token is authoritative when present
+
+**Out of scope (deferred):**
+- Full JWT/JWKS or key rotation infrastructure — a single host-held HMAC key is sufficient for v1
+- Multi-turn / session-scoped tokens — one token per container turn is enough
+- Revocation lists — tokens are short-lived (expire with the turn)
+
+---
+
+## Context for Claude
+
+- `src/core/api.ts` — Hono control-plane API; auth middleware at lines 35-75 (`safeCompare`, header identity resolution at 50-72). This is where token verification is added
+- `src/cli/mrctl.ts` — in-container CLI; builds request headers at lines 33-41, reads `API_URL`/`API_SECRET`/`CALLER_ID`/`SPACE_ID` from env
+- `src/agent/container-runner.ts` — container spawn; injects `API_URL`/`API_SECRET`/`CALLER_ID`/`SPACE_ID` at ~810-817. This is where the token is minted and injected
+- `src/core/routes/tradestation.ts` — existing caller-bound guard (lines 153-158, 245-254) that currently trusts header identity; the reference consumer to migrate
+- `src/config.ts` — `apiSecret` config (line 212); add the host-only signing key here
+
+---
+
+## Architecture & Data
+
+### Token shape
+
+Opaque HMAC-signed token (no new dependency — Node `crypto`):
+
+```
+token   = base64url(payload) + "." + base64url(HMAC_SHA256(key, base64url(payload)))
+payload = { c: callerId, s: spaceId, exp: <unix-seconds> }
+```
+
+- `key` — a host-only secret (`MERCURY_CALLER_TOKEN_KEY`, auto-derived from `API_SECRET` if unset so no new required config). Never injected into containers.
+- `exp` — short TTL (e.g. spawn time + container timeout). The token is useless after the turn.
+
+### Flow
+
+1. **Spawn** (`container-runner.ts`): mint token from `{callerId, spaceId, exp}`, inject as `MERCURY_CALLER_TOKEN`. Do **not** inject the signing key.
+2. **Callback** (`mrctl.ts`): forward `MERCURY_CALLER_TOKEN` as an `x-mercury-token` header (in addition to the existing `Authorization: Bearer API_SECRET`).
+3. **Verify** (`api.ts` middleware): if `x-mercury-token` is present, verify the HMAC and expiry; on success, set the request's authoritative `callerId`/`spaceId` from the token payload and **ignore** `x-mercury-caller`/`x-mercury-space` for authorization. If absent, fall back to today's behavior (shared secret + headers) for backward compatibility.
+
+### Why the token can't be forged from inside the container
+
+The signing key never enters the container. The container holds only its **own** turn's token (valid for its own caller/space). It cannot mint a token for a different caller, and the shared `API_SECRET` alone no longer authorizes an identity claim once a route requires the token.
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `src/core/caller-token.ts` | New | `mintCallerToken()` / `verifyCallerToken()` HMAC helpers |
+| `src/agent/container-runner.ts` | Modified | Mint + inject `MERCURY_CALLER_TOKEN` at spawn; keep key host-side |
+| `src/cli/mrctl.ts` | Modified | Forward token as `x-mercury-token` header |
+| `src/core/api.ts` | Modified | Verify token; prefer token identity over headers |
+| `src/core/routes/tradestation.ts` | Modified | Use token-derived caller for the confirm guard |
+| `src/config.ts` | Modified | Add `callerTokenKey` (derives from `apiSecret` when unset) |
+| `tests/caller-token.test.ts` | New | Mint/verify, tamper, expiry, spoof-rejection tests |
+
+### Implementation Sequence
+
+1. **Token helpers** — `mintCallerToken({callerId, spaceId, exp}, key)` and `verifyCallerToken(token, key)` in `caller-token.ts`.
+   - Read first: `src/config.ts`
+   - Verify: unit tests for round-trip + tamper rejection pass
+2. **Mint at spawn** — inject `MERCURY_CALLER_TOKEN` in `container-runner.ts`; ensure the key is NOT injected (add to the env blocklist alongside `MERCURY_API_SECRET`).
+   - Read first: `src/agent/container-runner.ts` (~810-817, blocklist ~684)
+   - Verify: token present in container env; key absent
+   - Blocker: Step 1
+3. **Forward in mrctl** — add `x-mercury-token` header.
+   - Read first: `src/cli/mrctl.ts` (33-41)
+   - Verify: header present on requests
+   - Blocker: Step 2
+4. **Verify host-side** — token-preferred identity in `api.ts` middleware; header fallback retained.
+   - Read first: `src/core/api.ts` (35-75)
+   - Verify: request with valid token uses token identity; spoofed `x-mercury-caller` is ignored
+   - Blocker: Steps 1, 3
+5. **Migrate TradeStation guard** — derive confirm-guard caller from token.
+   - Read first: `src/core/routes/tradestation.ts` (153-158, 245-254)
+   - Verify: existing TradeStation tests pass with token identity
+   - Blocker: Step 4
+6. **Tests** — spoof rejection, tamper, expiry, backward-compat fallback.
+   - Verify: `bun test` passes
+   - Blocker: Steps 1-5
+
+---
+
+## Non-Negotiable Rules
+
+- **Signing key never enters a container** — it stays host-side; only per-turn tokens are injected.
+- **Token identity wins** — when a token is present and valid, `x-mercury-caller`/`x-mercury-space` are ignored for authorization.
+- **Short-lived** — tokens expire with the turn; no long-lived caller tokens.
+- **Backward compatible** — absent a token, existing shared-secret + header behavior is unchanged, so nothing breaks for current admin-only brokers during rollout.
+- **Constant-time verification** — HMAC compare uses `crypto.timingSafeEqual` (mirror `safeCompare` in `api.ts`).
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| Token expired mid-long-turn | Route returns 401; treat as a transient auth failure. TTL should exceed the container timeout to avoid this. |
+| System-triggered task (`callerId = "system"`) | Mint a token for `system` too, or allow the shared-secret path for system callers explicitly. |
+| Rollout with old containers (no token) | Header/shared-secret fallback keeps them working until images are rebuilt. |
+| Signing key unset | Derive deterministically from `API_SECRET` (documented) so no new required config. |
+| Attacker replays a captured token | Bound to `{caller, space, exp}` and only valid for that caller's own actions; replay grants nothing beyond what that caller already had, and expires with the turn. |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal
+- [x] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture
+- [x] Architecture & Data section complete
+- [x] Non-Negotiable Rules defined
+- [x] Edge Cases covered
+- [x] Context for Claude pointers filled in
+
+### Implementation
+- [ ] Step 1 — Token helpers
+- [ ] Step 2 — Mint at spawn
+- [ ] Step 3 — Forward in mrctl
+- [ ] Step 4 — Verify host-side
+- [ ] Step 5 — Migrate TradeStation guard
+- [ ] Step 6 — Tests
+- [ ] `bun run check` passes
+- [ ] No secrets committed
+
+---
+
+## Open Questions
+
+- [ ] Should `system` callers use a token or keep the shared-secret path? — owner: TBD
+- [ ] TTL value — fixed, or derived from the per-turn container timeout? — owner: TBD
+
+---
+
+## Retrospective
+
+**Residual risks / follow-ups:**
+- none
+
+**What changed from the plan:**
+- ...
+
+**Key decisions made during implementation:**
+- ...
+
+**Architecture impact:**
+- [ ] New package/module added
+- [ ] New data model or schema change
+- [ ] New inter-package interaction
+- [ ] Deployment topology changed

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/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.26",
+  "version": "0.4.28",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",