mercury-agent 0.4.27 → 0.5.0

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/ARCHITECTURE.md

@@ -28,3 +28,7 @@
 ## Extension Points
 
 > Where the system is designed to be extended — plugin interfaces, hook points, configuration surfaces.
+
+- **Applicative profiles** (`src/core/profiles.ts`) — a `mercury-profile.yaml` declares `capabilities`, an exhaustive `member_permissions` set, and a `system_prompt`. `applyProfile` validates capabilities and persists `.mercury/active-profile.json`; `main.ts` activates it at startup (project-wide). Member permission scoping is in `getRolePermissions` (`src/core/permissions.ts`). Authoring contract: `docs/authoring-profiles.md`.
+- **Host-side capability broker** — extensions register `mercury.capability(name, handler)` (`src/extensions/types.ts`, `api.ts`); the agent invokes them from the container via `mrctl capability <name> <action>` → `POST /api/capability/:name/:action` (`src/core/routes/capability.ts`). Handlers run on the host with credentials that never enter the container; identity is the token-derived caller.
+- **Caller-bound capability token** (`src/core/caller-token.ts`) — per-turn HMAC token minted at container spawn, made authoritative over spoofable identity headers in the control-plane API auth middleware (`src/core/api.ts`).

package/docs/ROADMAP.md

@@ -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/archive/2026-07-01-applicative-profiles.md

@@ -0,0 +1,270 @@
+# Applicative Profiles
+
+**Status**: Done
+**Slug**: applicative-profiles
+**Created**: 2026-07-01
+**Last updated**: 2026-07-01
+
+---
+
+## 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. 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 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 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 (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 — 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):**
+- 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 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
+
+- `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
+
+### 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 repo** `tagula-agents/tagula-agent-profiles` | Availability, 2 barbers, per-number limits, ownership rules — the moat |
+
+### Part 1 — Schema + permission scoping
+
+Extend `profileSchema` in `src/core/profiles.ts` (all new fields optional → backward compatible):
+
+```typescript
+const profileSchema = z.object({
+  // ... 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
+});
+```
+
+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`).
+
+**`system_prompt` precedence** (highest wins): per-space `system_prompt` override → profile `system_prompt` → global AGENTS.md.
+
+### Part 2 — Host-side capability broker (the core security mechanism)
+
+This is the crux, and it reuses an existing, production-proven pattern rather than inventing one.
+
+**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**
+
+**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
+
+**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.
+
+### Part 3 — Trustworthy caller identity (dependency)
+
+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 the private monorepo `Avishai-tsabari/tagula-agents` (`c:/code/agentic/tagula-agents`), under `tagula-agent-profiles/` (the repo also holds the cloud console). Checked out as a sibling of `mercury-public`. 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
+name: barber-appointments
+description: Appointment booking for a barber shop
+version: 0.1.0
+agents_md: ./AGENTS.md
+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 each customer book, view, and cancel
+  ONLY their own appointments. Never reveal other customers' schedules.
+defaults:
+  trigger_patterns: always
+```
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `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` (optional).
+   - Read first: `src/core/profiles.ts`
+   - 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: apply throws on missing capability; passes when present
+   - Blocker: Step 1
+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: `space_config` reflects active profile
+   - Blocker: Step 1
+4. **Profile-aware permissions** — `getRolePermissions()` uses `profile.member_permissions` as the exhaustive member set.
+   - Read first: `src/core/permissions.ts`
+   - Verify: member gets only profile perms; admin unchanged; `gws` CLI denied + env withheld for members
+   - Blocker: Step 3
+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`
+   - 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** — 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.
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| 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
+- [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
+- [x] Step 1 — Extend profile schema (`capabilities`, `member_permissions`, `system_prompt`); swapped hand-rolled `parseSimpleYaml` for the `yaml` lib (multiline `system_prompt` support, less fragility)
+- [x] Step 2 — Capability validation (`validateProfileCapabilities`, called in `applyProfile`); tests in `tests/applicative-profiles.test.ts`
+- [x] Step 3 — Activation + config: `profile` config key; `applyProfile` persists `.mercury/active-profile.json`; `main.ts` reads it at startup (after extensions load) and calls `setActiveProfileMemberPermissions`
+- [x] Step 4 — Profile-aware permissions: `getRolePermissions` uses the active profile's member set as exhaustive; precedence = explicit per-space override > profile > defaults; admin/system unaffected
+- [x] Step 5 — Caller token dependency ([[caller-bound-capability-token]]) — implemented and committed
+- [x] Step 5b — Inject `system_prompt` at container spawn (appended to `MERCURY_EXT_SYSTEM_PROMPT` in `runtime.ts`, ahead of per-space prompt)
+- [x] Step 6 — Host-side capability broker: `mercury.capability(name, handler)` extension API; `POST /api/capability/:name/:action` route (auth = token-derived caller, authz = permission named after the capability); `registry.getCapability`; `mrctl capability <name> <action> [json]`
+- [x] Step 7 — Tests: `tests/api.test.ts` capability broker (dispatch with token-derived caller; permission-denied → 403) + schema/scoping tests in `tests/applicative-profiles.test.ts`
+- [x] Step 8 — Example config: profile + `mrctl capability` + `MERCURY_CALLER_TOKEN_KEY` notes in `mercury.example.yaml`
+- [ ] `bun run check` passes
+- [ ] No secrets or `.env` files committed
+- [ ] No unrelated files modified
+- [ ] All user stories verifiably met
+
+---
+
+## Open Questions
+
+- [ ] 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
+
+**Residual risks / follow-ups:**
+- Barber business logic (availability, 2-barber, per-number limits) lives in the private `tagula-agents` repo — out of this repo's scope — accepted
+- Ephemeral caller-token key breaks `mrctl` if the API and container-runner ever run in separate processes without `MERCURY_CALLER_TOKEN_KEY` set; documented in config + `docs/authoring-profiles.md` — accepted
+- `mrctl capability <name>/<action>` are not URL-encoded (path traversal only reaches other RBAC-guarded routes, no escalation) — accepted
+- Duplicate capability-name registration across two extensions silently first-wins in `registry.getCapability` — accepted
+- Empty `member_permissions: []` in a manifest gives members zero permissions (author's explicit exhaustive choice) — accepted
+
+**What changed from the plan:**
+- Signing key is NOT derived from `API_SECRET` (the plan's fallback) — `API_SECRET` is readable in the container, so an ephemeral host-only random key is used instead (config `callerTokenKey` for multi-process).
+- Caller token split into its own delivered dependency (`caller-bound-capability-token`) — also hardened TradeStation, which reads identity from the same auth context (no code change needed there).
+- Replaced the hand-rolled `parseSimpleYaml` in `profiles.ts` with the `yaml` lib (multiline `system_prompt` support + less fragility); built-in profiles still parse.
+- Profile activation is project-wide via a module-level registry + persisted `.mercury/active-profile.json`, not per-space `space_config` writes (simpler, works for later-created dm-auto-space spaces).
+- Broker registration model chosen with the user: generic `mercury.capability(name, handler)` + `POST /api/capability/:name/:action` + `mrctl capability`, authorized by the permission named after the capability.
+- Added `docs/authoring-profiles.md` as the contract for the external profiles repo.
+
+**Key decisions made during implementation:**
+- Token = HMAC-SHA256 over `base64url(payload).base64url(sig)`, constant-time compare with length guard; TTL = container timeout + 60s.
+- `getRolePermissions` uses `Array.isArray` (not `!== null`) on the active-profile member set so a malformed `active-profile.json` falls back to defaults instead of throwing in the hot path (found in session review).
+- Profile schema uses plain `z.object` (no `.strict()`), so unknown manifest keys are stripped, honoring the `2026-07-01-strict-yaml-schema-crash` post-mortem (warn/ignore unknown keys, fail only on invalid values); startup `loadActiveProfile` is try/catch → null.
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [x] New package/module added — `src/core/caller-token.ts`, `src/core/routes/capability.ts`
+- [ ] New data model or schema change (uses existing `space_config`; adds a local `.mercury/active-profile.json` file, no DB schema change)
+- [x] New inter-package interaction — extension host-side capability handlers invoked via the control-plane API
+- [ ] Deployment topology changed

package/docs/archive/2026-07-01-caller-bound-capability-token.md

@@ -0,0 +1,184 @@
+# Caller-Bound Capability Token
+
+**Status**: Done
+**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
+- [x] Step 1 — Token helpers (`src/core/caller-token.ts`)
+- [x] Step 2 — Mint at spawn (`container-runner.ts`; key added to `BLOCKED_ENV_VARS`)
+- [x] Step 3 — Forward in mrctl (`x-mercury-token` header)
+- [x] Step 4 — Verify host-side (`api.ts` middleware; token identity wins)
+- [x] Step 5 — TradeStation guard: **no change needed** — it reads `c.get("auth")`, which now derives from the token
+- [x] Step 6 — Tests (`tests/caller-token.test.ts` unit; `tests/api.test.ts` integration: token overrides spoofed header, invalid token → 401)
+- [x] `bun run check` passes (one unrelated discord-adapter timeout flake under full parallel run; passes in isolation)
+- [x] 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:**
+- **Signing key is NOT derived from `API_SECRET`.** The plan suggested deriving it when unset, but `API_SECRET` is injected into containers — the agent could recompute the key and forge tokens. Instead: an optional host-only `callerTokenKey` (env `MERCURY_CALLER_TOKEN_KEY`, in `BLOCKED_ENV_VARS`), falling back to an **ephemeral random key** generated once per host process. Zero required config; nothing forgeable from inside the container.
+- **TradeStation guard needed no code change** — it already reads identity from `c.get("auth")`, which the middleware now sets from the token.
+- Token injected as container env `CALLER_TOKEN` (unprefixed, like `CALLER_ID`/`API_SECRET`), forwarded as `x-mercury-token`.
+
+**Key decisions made during implementation:**
+- HMAC-SHA256 over `base64url(payload).base64url(sig)`, payload `{c,s,exp}`; constant-time compare; no new dependency (`node:crypto`).
+- TTL = container timeout + 60s buffer, so a token never expires mid-turn but stays short-lived vs the permanent shared secret.
+- Header path retained as fallback → fully backward compatible; existing header-based tests and old container images keep working.
+
+**Architecture impact:**
+- [ ] New package/module added
+- [ ] New data model or schema change
+- [ ] New inter-package interaction
+- [ ] Deployment topology changed