mercury-agent 0.4.27 → 0.4.28

package/README.md

@@ -19,7 +19,7 @@ Mercury is a personal AI assistant that lives where you chat. It connects to Wha
 
 - **[Node.js](https://nodejs.org/)** >= 18 — Required for `npm install -g mercury-agent`
 - **[Bun](https://bun.sh)** >= 1.0 — JavaScript runtime used by Mercury
-- **[Docker](https://docs.docker.com/get-docker/)** — Required for running agent containers
+- **[Docker](https://docs.docker.com/get-docker/)** — Required for running agent containers. On Linux, also install `docker-buildx` (`apt-get install docker-buildx`) — Docker Desktop includes it, but Docker Engine on Linux does not.
 - **Windows users:** Mercury runs best under [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). Install WSL2 with `wsl --install`, then install Bun and Docker inside it.
 
 ## Quick Start

package/docs/ROADMAP.md

@@ -10,7 +10,7 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 
 | Item | Doc | Notes |
 |------|-----|-------|
-| — | — | — |
+| **business-extensions** | [doc](ideas/business-extensions.md) | Dedicated business extensions wrapping raw capabilities with deterministic logic |
 
 ## Now
 
@@ -26,7 +26,8 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 |---|------|-----|-----------|---------|
 | 1 | **autonomous-planning-tier** | [doc](backlog/autonomous-planning-tier.md) | — | Let agents decompose ideas, keep human gate |
 | 2 | **dm-auto-space** | [doc](backlog/dm-auto-space.md) | — | Auto-create space per customer DM |
-| 3 | **applicative-profiles** | [doc](backlog/applicative-profiles.md) | — | Generic profile layer for business logic scoping |
+| 3 | **applicative-profiles** | [doc](backlog/applicative-profiles.md) | caller-bound-capability-token | Generic profile layer; host-side broker keeps secrets off customer containers |
+| 4 | **caller-bound-capability-token** | [doc](backlog/caller-bound-capability-token.md) | — | Per-turn token so brokers can trust callerId; also hardens TradeStation |
 
 ## Later
 

package/docs/backlog/applicative-profiles.md

@@ -9,199 +9,184 @@
 
 ## Goal
 
-Mercury's existing profile system (`src/core/profiles.ts`) is a static provisioning mechanism — it bundles extensions, AGENTS.md, env vars, and config defaults into a deployable template. But it has no runtime behavior: it can't scope which capabilities members access, enforce data isolation (ownership), or declare capability dependencies. Business workflows (appointment booking, customer management) require deterministic logic that can't be reliably delegated to the LLM.
+Mercury's existing profile system (`src/core/profiles.ts`) is a static provisioning mechanism — it bundles extensions, AGENTS.md, env vars, and config defaults into a deployable template. It has no runtime behavior: it can't scope which capabilities members access, keep secrets out of an untrusted member's container, or enforce per-user ownership. Business workflows (appointment booking, customer management) require deterministic logic that the LLM cannot be trusted to enforce.
 
-Applicative Profiles extend the existing profile system with a **runtime contract** — a profile declares what capabilities it wraps, what commands it exposes to members, and what isolation rules it enforces. Mercury provides the schema, loader, and runtime enforcement; profiles live in external repos. The barber-appointments profile is the first implementation to validate the design.
+Applicative Profiles extend the profile system with a **runtime contract**: a profile declares the capabilities it wraps, the commands it exposes to members, and its member permission set — and its privileged work runs **host-side**, behind an authenticated broker, so credentials never enter a customer-controlled container. Mercury (public repo) provides the schema, permission scoping, and broker mechanism; the actual business profiles live in a **separate private repo**. The barber-appointments profile is the first implementation and the design driver.
+
+### Security framing (why the naive design fails)
+
+Mercury's security model today **trusts whoever it hands a tool to** — appropriate because tool-callers have historically been admins. Two facts make a naive "wrap GWS in an extension" approach unsafe for customer-facing profiles:
+
+1. **The permission guard is bypassable.** It's a regex denylist on CLI names (`src/extensions/permission-guard.ts`) that the project documents as defense-in-depth only (`docs/TODOS.md` TODO-2). It cannot stop `printenv`, `cat /proc/self/environ`, `curl`, `python -c`, etc.
+2. **Member role does not remove bash.** Role only controls which CLIs are denied and which env vars are injected (`src/core/runtime.ts:1343-1376`); whether bash exists is decided by *model capability*, not role. So a member on a tool-capable model can read any env var in their container.
+
+Therefore **any credential injected into a customer's container is readable by that customer.** The only safe design keeps the credential on the host — which Mercury already does for TradeStation (see Architecture).
 
 ## User Stories
 
-- As a Mercury operator, I want to install a profile package from an external repo so my bot gains domain-specific business logic without modifying Mercury core.
-- As a barber shop owner, I want my customers (DM members) to book and cancel only their own appointments through the bot, without seeing other customers' schedules.
-- As a barber shop owner, I want my customers to have zero access to my Gmail, even though the profile uses my GWS credentials for calendar access internally.
-- As a profile developer, I want a clear schema/contract for defining profiles so I know what to implement (commands, permissions, capability dependencies, data isolation rules).
-- As a Mercury admin, I want raw capability extensions (GWS, web search) to remain admin-only while the profile's scoped commands are member-facing.
+- As a Mercury operator, I want to install a profile from an external repo so my bot gains domain-specific business logic without modifying Mercury core.
+- As a barber shop owner, I want customers (DM members) to book and cancel only their **own** appointments, never seeing others' schedules.
+- As a barber shop owner, I want customers to have **zero** access to my Gmail/Google account, even though the profile uses my Google credentials for Calendar internally.
+- As a profile developer, I want a clear schema + a host-side broker pattern so I can enforce ownership on the host where the real `callerId` is trustworthy.
+- As a Mercury admin, I want raw capability extensions (GWS, web search) to stay admin-only while the profile's scoped commands are member-facing.
 
 ## MVP Scope
 
-**In scope:**
-- Extend `mercury-profile.yaml` schema with runtime fields: `capabilities` (required extensions), `member_permissions` (exhaustive permission list for members), and `system_prompt` (profile-specific agent persona)
+**In scope (all in `mercury-public`):**
+- Extend `mercury-profile.yaml` schema with runtime fields: `capabilities` (required host-side extensions), `member_permissions` (exhaustive member permission set), `system_prompt` (agent persona)
 - Profile-aware permission resolution — when a profile is active, member permissions come from the profile, not from extension defaults
-- Capability dependency validation — profile apply fails if required extensions aren't installed
-- Profile activation per space — a space can have an active profile that governs its runtime behavior
-- `CALLER_ID` injection — profile extensions receive the caller's identity so they can enforce ownership in their CLI code
-- Barber-appointments profile (separate repo) as the first implementation to validate the design
+- Capability-dependency validation — activation fails if a required capability isn't installed
+- A **host-side capability broker** convention: profile capabilities execute on the host (credentials in host storage), invoked from the container via the existing `mrctl`→control-plane-API channel — following the proven TradeStation pattern
+- Depends on [[caller-bound-capability-token]] so the broker can trust `callerId` for ownership checks
 
 **Out of scope (deferred):**
-- Profile marketplace/registry — profiles are installed manually (npm/bun add or git clone) for now
-- Profile versioning/migration — no schema version negotiation yet
-- Multi-profile per space — one profile per space for MVP
+- The actual barber business logic (availability rules, 2-barber support, per-number appointment limits) — lives in the **private profiles repo**, not here
+- Profile marketplace/registry — profiles are installed manually (git clone / package) for now
+- Profile versioning/migration — no schema-version negotiation yet
+- Multi-profile per space — one active profile per deployment for MVP
 - Profile UI in dashboard — managed via config/YAML only
-- Declarative data isolation rules — ownership enforcement is in profile extension code, not a schema declaration (too domain-specific for a generic schema in v1)
+- Declarative ownership rules — ownership is enforced in the profile's host-side route code using the trusted `callerId`, not a generic schema (too domain-specific for v1)
 
 ---
 
 ## Context for Claude
 
-> Key files to read before touching anything.
-
-- `src/core/profiles.ts` — Existing profile system: `profileSchema`, `loadProfileFromDir()`, `applyProfile()`, `resolveProfileSource()`. Bundles extensions + AGENTS.md + env + defaults into `.mercury/`
-- `src/extensions/types.ts` — Extension type system: `MercuryExtensionAPI`, `ExtensionMeta`, `PermissionDef`, `CliDef`, `EnvDef`. The API surface extensions use during setup
-- `src/core/permissions.ts` — Permission resolution: `getRolePermissions()`, `registerPermission()`, `resolveRole()`. Role-based (admin/member) per space with extension-registered defaults
-- `src/extensions/permission-guard.ts` — Container-side enforcement: reads `MERCURY_DENIED_CLIS` env var and blocks unauthorized CLI calls
-- `src/extensions/loader.ts` — `ExtensionRegistry` class: scans `.mercury/extensions/`, validates, runs setup functions, collects `ExtensionMeta`
+- `src/core/profiles.ts` — Existing profile system: `profileSchema`, `loadProfileFromDir()`, `applyProfile()` (project-level, no DB/space). Extended here
+- `src/core/permissions.ts` — `getRolePermissions()`, `registerPermission()`, `resolveRole()`. Role-based (admin/member) per space
+- `src/core/runtime.ts` — Container spawn: denied-CLI computation + per-permission env injection at 1343-1376
+- `src/extensions/permission-guard.ts` — Bypassable CLI-name denylist (see `docs/TODOS.md` TODO-2)
+- `src/core/routes/tradestation.ts` + `src/tradestation/host-api.ts` — **The reference broker.** Container calls `mrctl tradestation order` → host route executes with a token from `db.getExtState(...)`, never exposing it to the container ("keeps order placement off the agent container"). Includes a caller-bound confirm guard (153-158, 245-254)
+- `src/core/api.ts` — Control-plane API + auth middleware (35-75) that broker routes mount onto
+- `src/cli/mrctl.ts` — In-container CLI that calls the host API (the container→host transport)
 
 ---
 
 ## Architecture & Data
 
-### Data Models
+### The four parts (and where each lives)
+
+| Part | Repo | What |
+|------|------|------|
+| 1. Profile schema + permission scoping | `mercury-public` | New `mercury-profile.yaml` fields; profile-aware member permissions |
+| 2. Host-side capability broker | `mercury-public` | Profile capabilities run host-side via `mrctl`→API, à la TradeStation; secrets stay on host |
+| 3. Per-turn caller token | `mercury-public` | [[caller-bound-capability-token]] — trustworthy `callerId` on the host (dependency) |
+| 4. Barber business logic | **private profiles repo** | Availability, 2 barbers, per-number limits, ownership rules — the moat |
 
-Extend the existing `profileSchema` in `src/core/profiles.ts`:
+### Part 1 — Schema + permission scoping
+
+Extend `profileSchema` in `src/core/profiles.ts` (all new fields optional → backward compatible):
 
 ```typescript
-// New fields added to profileSchema
 const profileSchema = z.object({
-  // ... existing fields ...
-  name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
-  description: z.string().optional(),
-  version: z.string().default("0.1.0"),
-  agents_md: z.string().optional(),
-  extensions: z.array(profileExtensionSchema).default([]),
-  env: z.array(profileEnvVarSchema).default([]),
-  defaults: profileDefaultsSchema.optional(),
-
-  // NEW — runtime applicative fields
-  capabilities: z.array(z.string()).default([]),          // required raw extensions (e.g. ["gws"])
-  member_permissions: z.array(z.string()).optional(),     // exhaustive member permission list when profile is active
-  system_prompt: z.string().optional(),                   // profile-specific agent persona
+  // ... existing: name, description, version, agents_md, extensions, env, defaults ...
+  capabilities: z.array(z.string()).default([]),        // required host-side capability extensions, e.g. ["gws"]
+  member_permissions: z.array(z.string()).optional(),   // EXHAUSTIVE member permission set when active
+  system_prompt: z.string().optional(),                 // profile persona
 });
 ```
 
-New DB storage — per-space active profile tracking via existing `space_config`:
-- Key: `profile.active` — value: profile name (e.g. `"barber-appointments"`)
-- Key: `profile.member_permissions` — value: comma-separated permission list from the profile manifest
+Activation is **project-wide** (a deployment runs one profile — the "app"), stored in `space_config` on `main` / applied to member-facing spaces:
+- `profile.active` — profile name
+- `profile.member_permissions` — comma-separated list from the manifest
+
+Permission resolution (`getRolePermissions()`): when `profile.member_permissions` is set, that is the **complete** member set — no extension defaults merged in. Admin/system unchanged (all). Consequence: raw `gws` is absent from the member set, so its CLI is denied **and** its env vars are withheld from member containers (`runtime.ts:1360`).
 
-No new tables or migrations needed.
+**`system_prompt` precedence** (highest wins): per-space `system_prompt` override → profile `system_prompt` → global AGENTS.md.
 
-### How it works at runtime
+### Part 2 — Host-side capability broker (the core security mechanism)
 
-1. **Profile apply** (`applyProfile()` extended): copies extensions + AGENTS.md (existing behavior), then validates that all `capabilities` are installed as extensions, and stores the profile's `member_permissions` in a resolvable location.
+This is the crux, and it reuses an existing, production-proven pattern rather than inventing one.
 
-2. **Permission resolution** (`getRolePermissions()` extended): when a space has `profile.active` set, member permissions come from `profile.member_permissions` instead of the default `prompt + prefs.get + extension defaults`. Admin permissions are unchanged (all). This means raw capabilities (e.g., `gws`) stay admin-only unless the profile explicitly lists them in `member_permissions`.
+**How TradeStation already does it (the template):**
+- Container runs `mrctl tradestation order …` → `POST /api/tradestation/orders`
+- The route runs **on the host** (`src/core/routes/tradestation.ts`) using an OAuth token read from host storage (`db.getExtState(...)`, `src/tradestation/host-api.ts:27`) — the token **never enters the container**
 
-3. **Capability scoping**: the profile's own extensions call `mercury.permission({ defaultRoles: ["member"] })` to make their commands member-accessible. Raw capability extensions (e.g., `gws`) are NOT in `member_permissions`, so their CLIs are denied by `permission-guard.ts`. The profile extension uses the raw capability internally (server-side hooks, or by passing credentials via env vars that only the extension code — not the container — can access).
+**The barber broker is the same shape, Calendar-flavored:**
+- New host routes (e.g. `POST /api/barber/availability|book|cancel`, `GET /api/barber/my-appointments`) mounted on the existing API (`src/core/api.ts`)
+- New `mrctl` (or thin profile-CLI) subcommands the member agent invokes
+- Host route calls Google Calendar using credentials in **host storage** (`extension_state` / host env) — never injected into the customer container
+- Ownership enforced host-side: the route filters/authorizes by the **token-derived** `callerId` (Part 3), so a customer can only see/cancel their own appointments
 
-4. **Data isolation / ownership**: handled in the profile extension's CLI code. The container already receives `CALLER_ID` (the platform user ID). The profile's CLI checks the caller against the data before acting (e.g., "does this appointment belong to this caller?"). This is intentionally not a generic schema — it's too domain-specific.
+**Why Gmail is safe:** the customer container gets neither the `gws` CLI nor any Google credential. Even if the customer reads every env var in their container, there is no secret there — only a per-turn token scoped to themselves. Calendar access happens on the host; Gmail is never wired into the broker at all.
 
-5. **Gmail protection**: the `gws` extension exposes both Calendar and Gmail CLIs. When the barber profile is active, `member_permissions` does NOT include `gws`, so the permission guard blocks all `gws` CLI calls for members. The barber extension accesses Calendar server-side (via hooks or its own env vars) — members never touch GWS directly.
+### Part 3 — Trustworthy caller identity (dependency)
 
-### Example: barber-appointments profile
+The broker's ownership checks require a `callerId` the customer cannot forge. Today `callerId` arrives as a spoofable header gated only by a shared `API_SECRET` (`api.ts:50-72`). [[caller-bound-capability-token]] mints a per-turn token bound to `{callerId, spaceId}` at spawn and makes it authoritative host-side. **This feature depends on that one landing** (or shipping together).
+
+### Part 4 — Barber business logic (private repo)
+
+Lives in `tagula-agent-profiles` (or similar). Contains the `mercury-profile.yaml`, the agent persona, and the host-side route implementations' business rules (availability windows, 2-barber scheduling, per-number booking limits, double-booking prevention). Consumes Parts 1-3 as the public contract; never touches `mercury-public`.
+
+### Example manifest (in the private repo)
 
 ```yaml
-# mercury-profile.yaml (in separate repo)
 name: barber-appointments
 description: Appointment booking for a barber shop
 version: 0.1.0
-
 agents_md: ./AGENTS.md
-
-capabilities:
-  - gws                    # requires GWS extension installed (for Calendar)
-
-extensions:
-  - name: barber
-    source: ./extensions/barber
-
-member_permissions:
-  - prompt
-  - prefs.get
-  - barber                 # only the barber extension — NOT gws
-
-env:
-  - key: MERCURY_BARBER_BUSINESS_HOURS
-    description: "Business hours (e.g. 09:00-18:00)"
-    default: "09:00-18:00"
-  - key: MERCURY_BARBER_SLOT_DURATION
-    description: "Appointment slot duration in minutes"
-    default: "30"
-
+capabilities: [gws]                 # Calendar via host-side broker
+member_permissions: [prompt, prefs.get, barber]   # barber only — NOT gws
 system_prompt: |
-  You are a barber shop assistant. Help customers book, view, and cancel
-  their appointments. You can only help each customer with their own
-  appointments — never reveal other customers' schedules.
-
+  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"
+  trigger_patterns: always
 ```
 
-The barber extension (`./extensions/barber/index.ts`):
-- Calls `mercury.cli({ name: "barber", ... })` — installs a CLI with subcommands: `barber book`, `barber availability`, `barber cancel`, `barber my-appointments`
-- Calls `mercury.permission({ defaultRoles: ["member"] })` — members can use the `barber` CLI
-- The CLI internally uses GWS Calendar API (via env var credentials) but filters results by `CALLER_ID`
-- Members NEVER see the `gws` CLI — it's blocked by the permission guard
-
-### API Contracts
-
-No new HTTP API endpoints. Profile activation is done via:
-1. `mercury.yaml` — `profile: barber-appointments` (static config)
-2. `space_config` — `profile.active: barber-appointments` (per-space override)
-
 ### File & Folder Structure
 
 | Path | New / Modified | Purpose |
 |------|---------------|---------|
-| `src/core/profiles.ts` | Modified | Extend `profileSchema` with `capabilities`, `member_permissions`, `system_prompt`. Add validation in `applyProfile()` |
-| `src/core/permissions.ts` | Modified | Profile-aware `getRolePermissions()` — check `profile.member_permissions` for the space |
-| `src/config.ts` | Modified | Add `profile` config key for static profile activation |
-| `src/config-file.ts` | Modified | Add `profile` to YAML schema and env mapping |
-| `tests/applicative-profiles.test.ts` | New | Tests for profile permission scoping and capability validation |
+| `src/core/profiles.ts` | Modified | Extend `profileSchema`; validate `capabilities`; write `profile.*` to `space_config` |
+| `src/core/permissions.ts` | Modified | Profile-aware `getRolePermissions()` |
+| `src/config.ts` / `src/config-file.ts` | Modified | `profile` config key for activation |
+| `src/core/api.ts` | Modified | Mount profile broker routes (generic mounting point) |
+| `src/core/routes/` | New (per profile capability) | Host-side broker routes — pattern mirrors `tradestation.ts` |
+| `tests/applicative-profiles.test.ts` | New | Permission scoping + capability validation tests |
 
 ### Implementation Sequence
 
-1. **Extend profile schema** — Add `capabilities`, `member_permissions`, `system_prompt` to `profileSchema` in `profiles.ts`. These are optional fields so existing profiles remain valid.
+1. **Extend profile schema** — add `capabilities`, `member_permissions`, `system_prompt` (optional).
    - Read first: `src/core/profiles.ts`
-   - Verify: `bun run typecheck` passes
-
-2. **Add capability validation** — In `applyProfile()`, after copying extensions, check that every entry in `capabilities` has a matching directory in `.mercury/extensions/`. Throw a clear error if a required capability is missing.
+   - Verify: `bun run typecheck`; existing profiles still parse
+2. **Capability validation** — in `applyProfile()`, fail loudly if any `capabilities` entry has no matching extension.
    - Read first: `src/core/profiles.ts`, `src/extensions/loader.ts`
-   - Verify: `bun run typecheck` passes
+   - Verify: apply throws on missing capability; passes when present
    - Blocker: Step 1
-
-3. **Store profile activation in space_config** — When `applyProfile()` runs for a space, write `profile.active` and `profile.member_permissions` to `space_config`. Add `profile` config key to `config.ts` / `config-file.ts` for static activation.
+3. **Activation + config** — write `profile.active` / `profile.member_permissions` to `space_config`; add `profile` config key.
    - Read first: `src/config.ts`, `src/config-file.ts`, `src/storage/db.ts`
-   - Verify: `bun run typecheck` passes
+   - Verify: `space_config` reflects active profile
    - Blocker: Step 1
-
-4. **Profile-aware permission resolution** — In `getRolePermissions()`, when the space has `profile.member_permissions` set, use that as the member permission set instead of the default. Admin/system roles unchanged.
+4. **Profile-aware permissions** — `getRolePermissions()` uses `profile.member_permissions` as the exhaustive member set.
    - Read first: `src/core/permissions.ts`
-   - Verify: `bun run typecheck` passes
-   - Blocker: Step 3
-
-5. **System prompt injection** — When a profile has `system_prompt`, inject it via the existing `before_container` hook mechanism or config seeding (same pattern as `dm-auto-space`'s `default_system_prompt`).
-   - Read first: `src/core/runtime.ts`, `src/extensions/hooks.ts`
-   - Verify: `bun run typecheck` passes
+   - Verify: member gets only profile perms; admin unchanged; `gws` CLI denied + env withheld for members
    - Blocker: Step 3
-
-6. **Write tests** — Profile permission scoping: member gets only profile-declared permissions; admin gets all; raw capability blocked for members. Capability validation: apply fails when required extension missing. Profile activation: space_config correctly set.
+5. **Caller token dependency** — land [[caller-bound-capability-token]] (or ship together) so brokers can trust `callerId`.
+   - Verify: broker route reads token-derived caller; spoofed header ignored
+   - Blocker: separate doc
+6. **Broker route pattern** — document + provide the mounting point and a reference so a profile's host-side routes follow `tradestation.ts` (host-held creds, caller-bound authorization).
+   - Read first: `src/core/routes/tradestation.ts`, `src/tradestation/host-api.ts`, `src/core/api.ts`
+   - Verify: a sample broker route executes host-side, credential never injected into the container
+   - Blocker: Steps 4, 5
+7. **Tests** — scoping (member/admin/raw-capability), capability validation, activation.
    - Read first: `tests/permissions.test.ts`
-   - Verify: `bun test` passes
-   - Blocker: Steps 1-5
-
-7. **Update example config** — Add commented `profile` section to `mercury.example.yaml`.
-   - Read first: `resources/templates/mercury.example.yaml`
-   - Verify: file contains the new section
+   - Verify: `bun test`
+   - Blocker: Steps 1-6
+8. **Example config** — commented `profile` section in `mercury.example.yaml`.
+   - Verify: file contains the section
 
 ---
 
 ## Non-Negotiable Rules
 
-- **Profiles are external** — Mercury core provides the schema, loader, and runtime. No specific profile (barber, etc.) lives in this repo.
-- **Member permissions are exhaustive** — When a profile declares `member_permissions`, that is the COMPLETE set. No extension defaults are merged in. This prevents capability leakage.
-- **Admin permissions unchanged** — Admins always get all permissions regardless of profile. Profiles scope members only.
-- **Capability validation is strict** — `applyProfile()` must fail loudly if a required capability extension is not installed. Silent degradation is not acceptable.
-- **Data isolation is code, not config** — Ownership enforcement happens in the profile extension's CLI code, not in a declarative schema. The extension checks `CALLER_ID` before acting.
-- **Backward compatible** — Existing profiles without the new fields continue to work exactly as before. All new fields are optional.
-- **No Gmail exposure** — When a profile wraps GWS for Calendar access, the raw `gws` CLI (which includes Gmail) must be blocked for members via permission scoping.
+- **Profiles are external** — no specific business profile (barber, etc.) lives in `mercury-public`. Only schema, scoping, and broker mechanism.
+- **Credentials never enter a member container** — capability credentials live in host storage and are used only by host-side broker routes. This is the whole point; violating it re-opens the Gmail leak.
+- **Member permissions are exhaustive** — a profile's `member_permissions` is the COMPLETE set; no extension defaults merged. Prevents capability leakage.
+- **Ownership is enforced host-side with the trusted `callerId`** — never with a container-supplied argument, never by prompting the LLM.
+- **Admin permissions unchanged** — admins always get all permissions; profiles scope members only.
+- **Capability validation is strict** — activation fails loudly if a required capability extension is missing.
+- **Backward compatible** — existing profiles and existing brokers keep working; all new fields optional; token path is additive.
+- **Do not rely on the permission guard as a security boundary** — it is bypassable (TODO-2). Security comes from *not putting secrets in the container*, not from blocking CLIs.
 
 ---
 
@@ -209,36 +194,37 @@ No new HTTP API endpoints. Profile activation is done via:
 
 | Scenario | Handling |
 |----------|---------|
-| Profile declares `member_permissions: ["nonexistent"]` | `isValidPermission()` filters invalid names. Log a warning but don't crash — the invalid permission is silently dropped. |
-| Profile requires capability `gws` but it's not installed | `applyProfile()` throws with a clear error listing missing capabilities. |
-| Admin manually overrides `role.member.permissions` per space | Per-space override in `space_config` takes precedence over profile defaults (existing behavior). Profile sets the baseline; admin can further restrict or expand. |
-| Profile is removed/changed but space_config still references it | `profile.active` becomes stale. Permission resolution still works from the stored `profile.member_permissions`. On next `applyProfile()` the values are updated. |
-| Two extensions declare the same CLI name | Existing loader behavior: second registration throws. No change needed. |
-| Profile extension tries to call raw capability CLI in container | Allowed only if the extension is running as admin (hooks run on host, not in container). Container CLI calls go through permission guard. |
-| Caller ID not available (e.g., system-triggered task) | `CALLER_ID` is already `"system"` for scheduled tasks. Profile extension should handle this gracefully (e.g., skip ownership check for system callers). |
-| Existing deployment upgrades Mercury with profiles feature | No behavioral change. `member_permissions` is optional; when absent, existing permission resolution applies. |
+| Customer asks the agent to `printenv` / read files | Allowed — but the container holds no capability secret, only a self-scoped per-turn token. Nothing sensitive to leak. |
+| Customer tries to `curl` the broker spoofing another `callerId` | Rejected — broker authorizes by the token-derived caller ([[caller-bound-capability-token]]), not the header. |
+| Profile requires `gws` but it isn't installed | `applyProfile()` throws listing missing capabilities. |
+| `member_permissions` lists an invalid permission | Filtered by `isValidPermission()`; warn, don't crash. |
+| Admin overrides `role.member.permissions` per space | Per-space override still wins (existing behavior); profile sets the baseline. |
+| Broker route needs Calendar but customer has no appointment yet | Ownership filter returns empty; booking creates a record keyed to `callerId`. |
+| System-triggered task (`callerId = "system"`) hits a broker | Broker skips per-customer ownership for system caller (or per Part 3's system-token decision). |
+| Existing deployment upgrades to this version | No behavior change: `member_permissions` optional; brokers additive. |
 
 ---
 
 ## Implementation Checklist
 
-### Phase 1 — Goal (fill before asking for approval)
+### Phase 1 — Goal
 - [x] Goal, User Stories, and MVP Scope written and reviewed
 
-### Phase 2 — Architecture (fill after Goal approved)
+### 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 (tick off as you go)
+### Implementation
 - [ ] Step 1 — Extend profile schema
-- [ ] Step 2 — Add capability validation
-- [ ] Step 3 — Store profile activation in space_config
-- [ ] Step 4 — Profile-aware permission resolution
-- [ ] Step 5 — System prompt injection
-- [ ] Step 6 — Write tests
-- [ ] Step 7 — Update example config
+- [ ] Step 2 — Capability validation
+- [ ] Step 3 — Activation + config
+- [ ] Step 4 — Profile-aware permissions
+- [ ] Step 5 — Caller token dependency ([[caller-bound-capability-token]])
+- [ ] Step 6 — Broker route pattern (mirror `tradestation.ts`)
+- [ ] Step 7 — Tests
+- [ ] Step 8 — Example config
 - [ ] `bun run check` passes
 - [ ] No secrets or `.env` files committed
 - [ ] No unrelated files modified
@@ -248,17 +234,17 @@ No new HTTP API endpoints. Profile activation is done via:
 
 ## Open Questions
 
-- [ ] Should `dm_auto_space` auto-activate a profile for new customer spaces? (Likely yes — `dm_auto_space.profile: barber-appointments` config key) — owner: TBD
-- [ ] How does `CALLER_ID` map to appointment ownership? Phone number? Display name? A registration step? — owner: profile developer (barber repo)
+- [ ] Should `dm_auto_space` auto-activate the profile for new customer spaces (`dm_auto_space.profile: barber-appointments`)? — owner: TBD
+- [ ] How does `callerId` map to appointment ownership — phone number as-is, or a registration/name step? — owner: profile developer (private repo)
+- [ ] Broker routes: generic `POST /api/profile/:capability/:action` mounting vs per-profile route files? — owner: TBD
 
 ---
 
 ## Retrospective
 
-> Fill this section when archiving.
-
 **Residual risks / follow-ups:**
-- none
+- Per-turn caller token is a hard dependency for safe ownership → backlog/caller-bound-capability-token.md
+- Barber business logic tracked in the private profiles repo (out of this repo's scope) — accepted
 
 **What changed from the plan:**
 - ...

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

package/src/config-file.ts

@@ -29,7 +29,7 @@ const mercuryFileSchema = z
         port: z.number().int().min(1).max(65535).optional(),
         bot_username: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     model: z
@@ -48,7 +48,7 @@ const mercuryFileSchema = z
           .optional(),
         capabilities: z.record(z.string(), z.unknown()).optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     /** Top-level alias for `model.chain` */
@@ -65,7 +65,7 @@ const mercuryFileSchema = z
         whatsapp: z.boolean().optional(),
         telegram: z.boolean().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     runtime: z
@@ -88,14 +88,14 @@ const mercuryFileSchema = z
         rate_limit_daily_member: z.number().int().min(0).max(10000).optional(),
         rate_limit_daily_admin: z.number().int().min(0).max(10000).optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     scheduling: z
       .object({
         default_timezone: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     trigger: z
@@ -103,7 +103,7 @@ const mercuryFileSchema = z
         patterns: z.string().optional(),
         match: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     context: z
@@ -112,7 +112,7 @@ const mercuryFileSchema = z
         window_size: z.number().int().min(1).max(50).optional(),
         reply_chain_depth: z.number().int().min(1).max(50).optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     agent: z
@@ -127,7 +127,7 @@ const mercuryFileSchema = z
         container_bwrap_docker_compat: z.boolean().optional(),
         override_pi_system_prompt: z.boolean().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     discord: z
@@ -139,14 +139,14 @@ const mercuryFileSchema = z
           .max(60 * 60 * 1000)
           .optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     telegram: z
       .object({
         format_enabled: z.boolean().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     media: z
@@ -154,14 +154,14 @@ const mercuryFileSchema = z
         enabled: z.boolean().optional(),
         max_size_mb: z.number().min(1).max(100).optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     permissions: z
       .object({
         admins: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
 
     dm_auto_space: z
@@ -171,15 +171,109 @@ const mercuryFileSchema = z
         default_system_prompt: z.string().optional(),
         default_member_permissions: z.string().optional(),
       })
-      .strict()
+      .strip()
       .optional(),
   })
-  .strict();
+  .strip();
 
 type MercuryFile = z.infer<typeof mercuryFileSchema>;
 
 export type RawMercuryConfigInput = Record<string, unknown>;
 
+const KNOWN_TOP_KEYS = new Set([
+  "server",
+  "model",
+  "model_chain",
+  "ingress",
+  "runtime",
+  "scheduling",
+  "trigger",
+  "context",
+  "agent",
+  "discord",
+  "telegram",
+  "media",
+  "permissions",
+  "dm_auto_space",
+]);
+
+const KNOWN_SECTION_KEYS: Record<string, Set<string>> = {
+  server: new Set(["port", "bot_username"]),
+  model: new Set([
+    "chain",
+    "provider",
+    "model",
+    "fallback_provider",
+    "fallback",
+    "max_retries_per_leg",
+    "chain_budget_ms",
+    "capabilities",
+  ]),
+  ingress: new Set(["discord", "slack", "teams", "whatsapp", "telegram"]),
+  runtime: new Set([
+    "data_dir",
+    "auth_path",
+    "whatsapp_auth_dir",
+    "max_concurrency",
+    "log_level",
+    "log_format",
+    "rate_limit_per_user",
+    "rate_limit_window_ms",
+    "rate_limit_daily_member",
+    "rate_limit_daily_admin",
+  ]),
+  scheduling: new Set(["default_timezone"]),
+  trigger: new Set(["patterns", "match"]),
+  context: new Set(["mode", "window_size", "reply_chain_depth"]),
+  agent: new Set([
+    "image",
+    "container_timeout_ms",
+    "container_bwrap_docker_compat",
+    "override_pi_system_prompt",
+  ]),
+  discord: new Set(["gateway_duration_ms"]),
+  telegram: new Set(["format_enabled"]),
+  media: new Set(["enabled", "max_size_mb"]),
+  permissions: new Set(["admins"]),
+  dm_auto_space: new Set([
+    "enabled",
+    "admin_ids",
+    "default_system_prompt",
+    "default_member_permissions",
+  ]),
+};
+
+function warnUnknownKeys(
+  rawYaml: Record<string, unknown>,
+  configPath: string,
+  log: (msg: string) => void,
+): void {
+  for (const key of Object.keys(rawYaml)) {
+    if (!KNOWN_TOP_KEYS.has(key)) {
+      log(
+        `[WARN] Unknown key "${key}" in ${configPath} — ignored. Check spelling or update mercury-agent.`,
+      );
+      continue;
+    }
+    const section = rawYaml[key];
+    const knownKeys = KNOWN_SECTION_KEYS[key];
+    if (
+      knownKeys &&
+      section != null &&
+      typeof section === "object" &&
+      !Array.isArray(section)
+    ) {
+      for (const subKey of Object.keys(section)) {
+        if (!knownKeys.has(subKey)) {
+          log(
+            `[WARN] Unknown key "${key}.${subKey}" in ${configPath} — ignored. Check spelling or update mercury-agent.`,
+          );
+        }
+      }
+    }
+  }
+}
+
 function resolveConfigPath(cwd: string): string | null {
   const explicit = process.env.MERCURY_CONFIG_FILE;
   if (explicit !== undefined) {
@@ -391,6 +485,7 @@ function envValueForSchema(
 export function mergeRawMercuryConfig(
   env: NodeJS.ProcessEnv = process.env,
   cwd: string = process.cwd(),
+  log: (msg: string) => void = console.warn,
 ): RawMercuryConfigInput {
   const configPath = resolveConfigPath(cwd);
   let fromFile: RawMercuryConfigInput = {};
@@ -404,6 +499,11 @@ export function mergeRawMercuryConfig(
       throw new Error(`Failed to read mercury config ${configPath}: ${msg}`);
     }
     if (rawYaml == null) rawYaml = {};
+
+    if (typeof rawYaml === "object" && !Array.isArray(rawYaml)) {
+      warnUnknownKeys(rawYaml as Record<string, unknown>, configPath, log);
+    }
+
     const parsed = mercuryFileSchema.safeParse(rawYaml);
     if (!parsed.success) {
       const issues = parsed.error.issues

package/src/core/routes/console.ts

@@ -275,6 +275,38 @@ export function createConsoleApp(opts: {
     return c.json({ connections });
   });
 
+  /* ── Credential injection ────────────────────────────────────── */
+
+  app.post("/credentials", async (c) => {
+    const body = (await c.req.json().catch(() => ({}))) as {
+      envVar?: string;
+      value?: string;
+      restart?: boolean;
+    };
+
+    const envVar = typeof body.envVar === "string" ? body.envVar.trim() : "";
+    const value = typeof body.value === "string" ? body.value : "";
+    const shouldRestart = body.restart !== false;
+
+    if (!envVar || !/^[A-Z_][A-Z0-9_]*$/.test(envVar)) {
+      return c.json(
+        { error: "envVar must be a valid SCREAMING_SNAKE_CASE name" },
+        400,
+      );
+    }
+
+    const envPath = path.join(opts.projectRoot, ".env");
+    updateDotEnv(envPath, { [envVar]: value || null });
+    logger.info(`Console: credential written`, { envVar, removed: !value });
+
+    if (shouldRestart && value) {
+      setTimeout(() => process.kill(process.pid, "SIGTERM"), 500);
+      return c.json({ ok: true, envVar, restarting: true });
+    }
+
+    return c.json({ ok: true, envVar, restarting: false });
+  });
+
   /* ── Adapter management ──────────────────────────────────────── */
 
   /** Return current adapter enable/disable state and credential presence. */