mercury-agent 0.5.2 → 0.5.6

package/package.json

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

package/docs/ARCHITECTURE.md

@@ -1,34 +0,0 @@
-# {Project Name} — Architecture Reference
-
-> On-demand reference. Do not auto-load. Read when a task is cross-cutting or you need to understand inter-package data flow.
-
-## Packages
-
-| Package | Purpose | Stack | Runs On |
-|---------|---------|-------|---------|
-| `{package}/` | {purpose} | {stack} | {where it runs} |
-
-## Deployment Topology
-
-```
-{ASCII diagram of your deployment — servers, services, databases, CDNs, etc.}
-```
-
-## Data Flow
-
-> How data moves between packages, services, and external systems. Include request paths, event flows, and storage interactions.
-
-## Key Invariants
-
-> Rules that must always hold true across the system. Breaking these causes cascading failures.
-
-- {Invariant 1}
-- {Invariant 2}
-
-## 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/DESIGN.md

@@ -1,42 +0,0 @@
-# {Project Name} — Design System
-
-> Fill this in if your project has a UI. Skip if it's a backend-only project.
-
-## 1. Visual Theme
-
-> Design principles — what the UI should feel like.
-
-## 2. Color Roles
-
-> CSS variable inventory. All colors must be defined as variables — never hardcode hex in component files.
-
-| Token | Dark Value | Light Value | Role |
-|-------|-----------|-------------|------|
-| `--bg` | {hex} | {hex} | Page background |
-| `--surface` | {hex} | {hex} | Card/panel background |
-| `--text` | {hex} | {hex} | Primary text |
-| `--muted` | {hex} | {hex} | Secondary text |
-| `--accent` | {hex} | {hex} | Interactive elements |
-| `--border` | {hex} | {hex} | Borders and dividers |
-| `--color-success` | {hex} | {hex} | Success states |
-| `--color-error` | {hex} | {hex} | Error states |
-| `--color-warning` | {hex} | {hex} | Warning states |
-
-## 3. Typography
-
-> Font families, sizes, weights. Which fonts for which contexts.
-
-## 4. Layout & Spacing
-
-> Grid system, breakpoints, spacing scale. Include RTL/logical property conventions if applicable.
-
-## 5. Components
-
-> Component conventions — buttons, inputs, cards, modals, status indicators, etc.
-
-## 6. Hard Rules
-
-> Violations block merge. Examples:
-> - No hardcoded hex colors in component files — use CSS variables
-> - No physical CSS properties (`left`/`right`) — use logical properties
-> - All interactive elements must have visible focus rings

package/docs/ROADMAP.md

@@ -1,43 +0,0 @@
-# {Project Name} — Roadmap
-
-Single source of truth for priority. Rule: ≤15 min/week to maintain.
-
----
-
-## Inbox
-
-> Uncategorized ideas. Triage into Now / Next / Later or drop.
-
-| Item | Doc | Notes |
-|------|-----|-------|
-| — | — | — |
-
-## Now
-
-> Max 2 items. What you're actively working on.
-
-| Item | Doc | Started | Notes |
-|------|-----|---------|-------|
-| — | — | — | — |
-
-## Next
-
-| # | Item | Doc | Depends on | Why now |
-|---|------|-----|-----------|---------|
-| 1 | **autonomous-planning-tier** | [doc](backlog/autonomous-planning-tier.md) | — | Let agents decompose ideas, keep human gate |
-
-## Later
-
-| Item | Doc | Notes |
-|------|-----|-------|
-| — | — | — |
-
----
-
-## Shipped
-
-| Item | Shipped | What |
-|------|---------|------|
-| **applicative-profiles** | 2026-07-01 | Generic profile layer: manifest schema, exhaustive member scoping, host-side capability broker |
-| **caller-bound-capability-token** | 2026-07-01 | Per-turn unspoofable caller token for host API auth; also hardens TradeStation |
-| **dm-auto-space** | 2026-07-01 | Auto-create space per customer DM with rate limits and dashboard controls |

package/docs/TODOS.md

@@ -1,147 +0,0 @@
-# Mercury — Remaining TODOs
-
-This document tracks gaps identified in the comprehensive code review that are not yet addressed. Items are ordered by priority (security first, then reliability, then polish).
-
----
-
-## Security
-
-### TODO-1: Protect dashboard root routes
-
-**Status:** Open  
-**Priority:** Medium  
-**Files:** `src/server.ts`
-
-**Issue:** `GET /` and `GET /dashboard` serve the dashboard HTML without authentication. Only `/dashboard/*` (htmx partials, API, SSE) is protected. Users can load the HTML shell without a token.
-
-**Fix:** Apply the same auth middleware to `/` and `/dashboard`, or redirect unauthenticated requests to a login page. When `MERCURY_API_SECRET` is set, require Bearer token or `mercury_token` cookie for these routes.
-
----
-
-### TODO-2: Harden permission guard
-
-**Status:** Open  
-**Priority:** Medium  
-**Files:** `src/extensions/permission-guard.ts`
-
-**Issue:** The permission guard blocks CLI names via regex on bash commands. It can be bypassed by:
-- `env napkin search "query"`
-- `` `which napkin` search "query" ``
-- `python3 -c "import subprocess; subprocess.run(['napkin', ...])"`
-- Path-based execution: `/root/.bun/bin/napkin`
-
-**Fix options:**
-1. Run denied CLIs through an allowlist/blocklist at the pi tool-call layer (if the pi API supports it)
-2. Use a wrapper script that validates the command before execution
-3. Document that this is defense-in-depth only; rely on extension trust model
-4. Consider seccomp or additional bwrap restrictions to limit subprocess execution
-
-**Note:** Bubblewrap limits filesystem access but does not prevent the agent from invoking allowed binaries. The permission guard remains the primary control for which CLIs run.
-
----
-
-### TODO-3: Sanitize extension install commands
-
-**Status:** Open  
-**Priority:** Low  
-**Files:** `src/extensions/image-builder.ts`
-
-**Issue:** Extension `install` commands are interpolated directly into Dockerfile `RUN` statements. A malicious extension could inject shell commands that exfiltrate secrets or modify the image.
-
-**Fix options:**
-1. Validate install commands against an allowlist (e.g. `bun add -g X`, `npm install -g X`)
-2. Run install commands in a sandboxed build step
-3. Document that extensions are trusted by design (operator installs them); recommend auditing before `mercury add`
-
----
-
-## Reliability
-
-### TODO-4: Database migration system
-
-**Status:** Open  
-**Priority:** Medium  
-**Files:** `src/storage/db.ts`, new `src/storage/migrations/`
-
-**Issue:** Schema evolution uses `CREATE TABLE IF NOT EXISTS` only. Adding columns, changing types, or renaming tables has no migration path.
-
-**Fix:** Implement a simple migration system:
-1. Create `migrations/` directory with sequential SQL files (`001_initial.sql`, `002_add_mutes.sql`, …)
-2. Add `schema_migrations` table to track applied migrations
-3. On startup, run any migrations not yet applied
-4. Document migration authoring in `docs/`
-
----
-
-### TODO-5: Outbox scan race condition
-
-**Status:** Open  
-**Priority:** Low  
-**Files:** `src/core/outbox.ts`, `src/agent/container-runner.ts`
-
-**Issue:** Outbox scanning uses mtime comparison against `startTime`. Files written at exactly `startTime` or during clock skew could be missed or incorrectly included.
-
-**Fix:** Use a more robust approach (e.g. track written files explicitly, or use a small time buffer). Document the current behavior and edge cases.
-
----
-
-## Operations
-
-### TODO-6: Run containers as non-root
-
-**Status:** Open  
-**Priority:** Low  
-**Files:** `container/Dockerfile`, `container/Dockerfile.minimal`, `src/agent/container-runner.ts`
-
-**Issue:** Containers run as root. Chromium uses `--no-sandbox` because it runs as root. This increases blast radius if the container is compromised.
-
-**Fix:**
-1. Create a non-root user in the Dockerfile
-2. Run the entrypoint as that user (`USER mercury` or similar)
-3. Ensure Chromium can run without `--no-sandbox` (may require `--user-data-dir` and other flags, or use a different approach)
-4. Update `container-runner.ts` if `docker run` needs `--user` override
-
-**Note:** Bubblewrap runs as the same user as the parent process. Moving the container to non-root would also make bwrap run as non-root, reducing privilege further.
-
----
-
-### TODO-7: CORS configuration
-
-**Status:** Open  
-**Priority:** Low  
-**Files:** `src/server.ts`
-
-**Issue:** No CORS headers are set. When Mercury is behind a reverse proxy or accessed from a browser on another origin, cross-origin requests may fail or behave unexpectedly.
-
-**Fix:** Add configurable CORS middleware (e.g. `MERCURY_CORS_ORIGINS`). Default to restrictive (same-origin or empty) for security.
-
----
-
-## In-Memory State (Deferred)
-
-### TODO-8: Crash-safe rate limiter and queue
-
-**Status:** Deferred  
-**Priority:** Low  
-**Files:** `src/core/rate-limiter.ts`, `src/core/space-queue.ts`
-
-**Issue:** Rate limiter and queue are in-memory. On crash, rate limit windows reset (allowing burst abuse) and queued work is lost.
-
-**Fix:** Persist rate limit state and queue to SQLite or Redis. Adds complexity; may be acceptable for single-node deployments. Revisit if multi-instance or high-availability is required.
-
----
-
-## Bubblewrap — What It Mitigates
-
-Bubblewrap adds **defense-in-depth** inside the container:
-
-| Risk | Mitigated by bubblewrap? |
-|------|--------------------------|
-| **Cross-space data access** | Partially — with per-space mount, `/spaces` only has one space. Bwrap further restricts the pi process to a minimal mount set. |
-| **Arbitrary filesystem access** | Yes — pi only sees `/usr`, `/app`, `/etc`, `/docs`, `/spaces`, `/root`, `/proc`, `/dev`, `/tmp`. Cannot access other paths. |
-| **Process isolation** | Yes — `--unshare-pid`, `--new-session`, `--die-with-parent` limit process visibility and lifecycle. |
-| **Permission guard bypass** | No — bwrap limits *what* the agent can access, not *which commands* it runs. A bypassed guard could still invoke allowed binaries. |
-| **Extension install injection** | No — that happens at image build time, before bwrap runs. |
-| **Container non-root** | No — bwrap runs as the same user (root) as the container. Moving to non-root would improve both. |
-
-**Summary:** Bubblewrap reduces blast radius if the agent is compromised. It does not replace the permission guard, API auth, or other controls. It is a valuable additional layer.

package/docs/VISION.md

@@ -1,32 +0,0 @@
-# {Project Name} — Product Vision
-
-## What {Project Name} Is
-
-> One-sentence pitch.
-
-## Target User
-
-> Who is this for? Be specific — role, context, what they're trying to accomplish.
-
-## What Makes {Project Name} Different
-
-| Differentiator | Why it matters |
-|---------------|----------------|
-| {differentiator} | {why} |
-
-## Non-Goals
-
-> Explicit list of what this project does NOT try to be. Helps filter feature requests.
-
-- {Non-goal 1}
-- {Non-goal 2}
-
-## Guiding Questions for New Ideas
-
-> Use these to evaluate whether a feature idea fits the product:
-
-1. Does this serve the target user directly?
-2. Does this align with the differentiators above?
-3. Does this conflict with any non-goal?
-4. Can the user benefit from this without configuration or documentation?
-5. Would removing this make the product worse for the target user?

package/docs/archive/applicative-profiles/2026-07-01-applicative-profiles.md

@@ -1,270 +0,0 @@
-# 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