mercury-agent 0.5.0 → 0.5.2

package/docs/ROADMAP.md

@@ -25,9 +25,6 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 | # | Item | Doc | Depends on | Why now |
 |---|------|-----|-----------|---------|
 | 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) | 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
 
@@ -41,4 +38,6 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 
 | 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/archive/summarization/2026-07-02-recent-dev-summary.md

@@ -0,0 +1,71 @@
+# Recent Dev Summary
+
+**Date:** 2026-07-02
+**Covers:** 3 shipped features · 2026-06-30 → 2026-07-01
+
+Three tightly-related features shipped together to lay the groundwork for customer-facing (member) profiles: a per-DM auto-space so each customer gets isolated persistent context, a caller-bound capability token so the host can trust *who* is calling, and applicative profiles that scope member capabilities and route privileged work through a host-side broker. The unifying thread is a **security pivot**: moving from "trust whoever holds a tool" to "keep secrets on the host and bind identity cryptographically" — a prerequisite for exposing capabilities to untrusted members.
+
+## Shipped
+
+| Feature | Slug | Date shipped | Key takeaway |
+|---------|------|-------------|--------------|
+| Auto-Create Space per DM | dm-auto-space | 2026-07-01 | Config-driven per-customer spaces; default-off, idempotent seeding via read-before-write |
+| Caller-Bound Capability Token | caller-bound-capability-token | 2026-07-01 | Per-turn HMAC token binds `{callerId, spaceId}`; host trusts the token, not spoofable headers |
+| Applicative Profiles | applicative-profiles | 2026-07-01 | Profiles scope member permissions + run privileged work host-side; secrets never enter member containers |
+
+## Build patterns
+
+### 1. Security by architecture, not by guardrail
+
+Rather than hardening a bypassable boundary, these features removed the sensitive material from the untrusted zone entirely.
+
+| Feature | Observation |
+|---------|-------------|
+| applicative-profiles | Credentials stay in host storage; member containers get only a self-scoped per-turn token — so `printenv` leaks nothing. Explicitly does *not* rely on the bypassable permission guard (TODO-2). |
+| caller-bound-capability-token | Signing key never enters the container; the container holds only its own turn's token and cannot forge another caller. |
+
+**Rule:** When an untrusted actor shares an execution environment, don't guard the secret — remove it from that environment. Security should come from where the secret lives, not from blocking the paths to it.
+
+### 2. Reuse the proven pattern over inventing one
+
+New capabilities deliberately mirrored an existing production mechanism instead of designing fresh machinery.
+
+| Feature | Observation |
+|---------|-------------|
+| applicative-profiles | The host-side capability broker is the TradeStation pattern generalized (`mrctl`→control-plane API, creds host-side), not a new transport. |
+| caller-bound-capability-token | TradeStation's confirm guard needed *no code change* — it already read identity from `c.get("auth")`, which the new middleware now populates from the token. |
+
+**Rule:** Before building new infrastructure, find the closest production-proven pattern and generalize it. Consumers that read from the right abstraction inherit the upgrade for free.
+
+### 3. Backward-compatible, additive rollout
+
+Every feature shipped default-off or fallback-preserving so existing deployments were unaffected.
+
+| Feature | Observation |
+|---------|-------------|
+| dm-auto-space | `enabled` defaults to `false`; global daily rate limits default to `0` (unlimited). |
+| caller-bound-capability-token | Absent a token, the old shared-secret + header path is unchanged, so old container images keep working during rollout. |
+| applicative-profiles | All new profile schema fields optional; brokers additive; existing profiles still parse. |
+
+**Rule:** Ship member-facing and security-sensitive changes as additive with a safe default; make the new path authoritative only when explicitly present, so rollout never breaks in-flight deployments.
+
+### 4. Plan-vs-reality divergence on the crypto detail
+
+Each retrospective flagged where the plan's shortcut was unsafe and was corrected during implementation.
+
+| Feature | Observation |
+|---------|-------------|
+| caller-bound-capability-token | Plan proposed deriving the signing key from `API_SECRET`; rejected because `API_SECRET` is readable in the container — switched to an ephemeral host-only key. |
+| applicative-profiles | Profile activation moved from per-space `space_config` writes to a module-level registry + persisted `.mercury/active-profile.json`; schema dropped `.strict()` to honor the strict-yaml crash post-mortem. |
+
+**Rule:** Re-examine any "derive the key from the existing secret" shortcut against the threat model — if the base secret is reachable by the attacker, the derived key is too.
+
+## Comparison with previous dev summary
+
+None — this is the first dev summary. Future summaries should watch whether the "security by architecture" and "reuse the proven pattern" themes persist as more member-facing profiles land in the private repo.
+
+## Action items
+
+1. **Land the private barber-appointments profile** against the now-public contract (schema + broker + caller token) to validate the design end-to-end.
+2. **Audit remaining header-trusting routes** to migrate onto token-derived identity now that the mechanism exists.
+3. **Document the host-side broker contract** (`docs/authoring-profiles.md`) as the canonical reference for external profile authors, and keep it in sync as capabilities grow.

package/docs/auth/dashboard.md

@@ -1,28 +1,28 @@
-# Dashboard Authentication
-
-The Mercury dashboard (`/dashboard/*`) is protected by `MERCURY_API_SECRET`. All htmx partial requests and the SSE events stream require a valid `mercury_token` session cookie.
-
-## How it works
-
-### Login route
-
-`GET /dashboard/login?token=<secret>` — the entry point for browser sessions.
-
-- Validates `token` against `MERCURY_API_SECRET` using `timingSafeEqual`
-- On success: sets `mercury_token` HttpOnly cookie and redirects to `/dashboard`
-- On failure: returns `401 Invalid or missing token`
-- Not protected by the dashboard auth middleware (it's the login endpoint itself)
-
-## Auth flow
-
-```
-User navigates to https://<host>:<port>/dashboard/login?token=<MERCURY_API_SECRET>
-  → agent sets mercury_token HttpOnly cookie
-  → 302 /dashboard
-  → dashboard loads, htmx requests include cookie ✅
-```
-
-## Key constraints
-
-- `MERCURY_API_SECRET` should be set to a long random string. `mercury setup` auto-generates one.
-- The cookie is HttpOnly — not accessible from JavaScript.
+# Dashboard Authentication
+
+The Mercury dashboard (`/dashboard/*`) is protected by `MERCURY_API_SECRET`. All htmx partial requests and the SSE events stream require a valid `mercury_token` session cookie.
+
+## How it works
+
+### Login route
+
+`GET /dashboard/login?token=<secret>` — the entry point for browser sessions.
+
+- Validates `token` against `MERCURY_API_SECRET` using `timingSafeEqual`
+- On success: sets `mercury_token` HttpOnly cookie and redirects to `/dashboard`
+- On failure: returns `401 Invalid or missing token`
+- Not protected by the dashboard auth middleware (it's the login endpoint itself)
+
+## Auth flow
+
+```
+User navigates to https://<host>:<port>/dashboard/login?token=<MERCURY_API_SECRET>
+  → agent sets mercury_token HttpOnly cookie
+  → 302 /dashboard
+  → dashboard loads, htmx requests include cookie ✅
+```
+
+## Key constraints
+
+- `MERCURY_API_SECRET` should be set to a long random string. `mercury setup` auto-generates one.
+- The cookie is HttpOnly — not accessible from JavaScript.

package/docs/auth/overview.md

@@ -1,109 +1,109 @@
-# Authentication
-
-Mercury needs credentials for two things:
-
-1. **AI model provider** — to call the LLM (Anthropic, OpenAI, etc.)
-2. **Chat platforms** — to connect to WhatsApp, Discord, Slack, Teams
-
-## Model Provider Auth
-
-### OAuth Login (Recommended)
-
-Mercury reuses [pi](https://github.com/badlogic/pi)'s OAuth providers. No API key needed — just login:
-
-```bash
-mercury auth login              # Interactive provider picker
-mercury auth login anthropic    # Or specify directly
-```
-
-Supported providers:
-
-| Provider | ID | What it gives you |
-|----------|----|-------------------|
-| Anthropic (Claude Pro/Max) | `anthropic` | Claude access via your subscription |
-| GitHub Copilot | `github-copilot` | Models via Copilot subscription |
-| Google Gemini CLI | `google-gemini-cli` | Gemini via Google Cloud |
-| Antigravity | `antigravity` | Gemini 3, Claude, GPT-OSS via Google Cloud |
-| ChatGPT Plus/Pro | `openai-codex` | OpenAI models via ChatGPT subscription |
-
-Credentials are saved to `.mercury/global/auth.json` and auto-refreshed when expired.
-
-### API Key
-
-Alternatively, set an API key in `.env`:
-
-```bash
-MERCURY_ANTHROPIC_API_KEY=sk-ant-...
-# or
-MERCURY_ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-...
-```
-
-### Resolution Order
-
-Mercury resolves credentials in this order:
-
-1. OAuth credentials from `auth.json` (via `mercury auth login`)
-2. `MERCURY_ANTHROPIC_OAUTH_TOKEN` from `.env`
-3. `MERCURY_ANTHROPIC_API_KEY` from `.env`
-
-> **OAuth always takes precedence over API keys.** If a provider has both an OAuth connection (in `auth.json` or `MERCURY_*_OAUTH_TOKEN`) and an API key (`MERCURY_*_API_KEY`), the OAuth token is used and the API key is ignored. This applies both to the CLI and to agents provisioned via the cloud console.
-
-### Managing Credentials
-
-```bash
-mercury auth status             # Show what's configured
-mercury auth logout anthropic   # Remove saved credentials
-mercury auth logout             # List what's logged in
-```
-
-## Chat Platform Auth
-
-### WhatsApp
-
-```bash
-mercury auth whatsapp                              # QR code (recommended)
-mercury auth whatsapp --pairing-code --phone 1234   # Pairing code (headless)
-```
-
-See [whatsapp.md](whatsapp.md) for details.
-
-### Discord
-
-Set in `.env`:
-
-```bash
-MERCURY_ENABLE_DISCORD=true
-MERCURY_DISCORD_BOT_TOKEN=your-bot-token
-```
-
-### Slack
-
-Set in `.env`:
-
-```bash
-MERCURY_ENABLE_SLACK=true
-MERCURY_SLACK_BOT_TOKEN=xoxb-...
-MERCURY_SLACK_SIGNING_SECRET=...
-```
-
-### Teams
-
-Set in `.env`:
-
-```bash
-MERCURY_ENABLE_TEAMS=true
-MERCURY_TEAMS_APP_ID=...
-MERCURY_TEAMS_APP_PASSWORD=...
-MERCURY_TEAMS_APP_TENANT_ID=...
-```
-
-## Dashboard Auth
-
-The web dashboard is protected by `MERCURY_API_SECRET`. Browser sessions are established via a login handshake managed by the cloud console — see [dashboard.md](dashboard.md).
-
-## Security
-
-- `auth.json` has `0600` permissions (owner read/write only)
-- WhatsApp credentials in `.mercury/whatsapp-auth/` are sensitive — treat like passwords
-- All `MERCURY_*` env vars are passed into containers with the prefix stripped
-- Never commit `.env` or `auth.json` to version control
+# Authentication
+
+Mercury needs credentials for two things:
+
+1. **AI model provider** — to call the LLM (Anthropic, OpenAI, etc.)
+2. **Chat platforms** — to connect to WhatsApp, Discord, Slack, Teams
+
+## Model Provider Auth
+
+### OAuth Login (Recommended)
+
+Mercury reuses [pi](https://github.com/badlogic/pi)'s OAuth providers. No API key needed — just login:
+
+```bash
+mercury auth login              # Interactive provider picker
+mercury auth login anthropic    # Or specify directly
+```
+
+Supported providers:
+
+| Provider | ID | What it gives you |
+|----------|----|-------------------|
+| Anthropic (Claude Pro/Max) | `anthropic` | Claude access via your subscription |
+| GitHub Copilot | `github-copilot` | Models via Copilot subscription |
+| Google Gemini CLI | `google-gemini-cli` | Gemini via Google Cloud |
+| Antigravity | `antigravity` | Gemini 3, Claude, GPT-OSS via Google Cloud |
+| ChatGPT Plus/Pro | `openai-codex` | OpenAI models via ChatGPT subscription |
+
+Credentials are saved to `.mercury/global/auth.json` and auto-refreshed when expired.
+
+### API Key
+
+Alternatively, set an API key in `.env`:
+
+```bash
+MERCURY_ANTHROPIC_API_KEY=sk-ant-...
+# or
+MERCURY_ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-...
+```
+
+### Resolution Order
+
+Mercury resolves credentials in this order:
+
+1. OAuth credentials from `auth.json` (via `mercury auth login`)
+2. `MERCURY_ANTHROPIC_OAUTH_TOKEN` from `.env`
+3. `MERCURY_ANTHROPIC_API_KEY` from `.env`
+
+> **OAuth always takes precedence over API keys.** If a provider has both an OAuth connection (in `auth.json` or `MERCURY_*_OAUTH_TOKEN`) and an API key (`MERCURY_*_API_KEY`), the OAuth token is used and the API key is ignored. This applies both to the CLI and to agents provisioned via the cloud console.
+
+### Managing Credentials
+
+```bash
+mercury auth status             # Show what's configured
+mercury auth logout anthropic   # Remove saved credentials
+mercury auth logout             # List what's logged in
+```
+
+## Chat Platform Auth
+
+### WhatsApp
+
+```bash
+mercury auth whatsapp                              # QR code (recommended)
+mercury auth whatsapp --pairing-code --phone 1234   # Pairing code (headless)
+```
+
+See [whatsapp.md](whatsapp.md) for details.
+
+### Discord
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_DISCORD=true
+MERCURY_DISCORD_BOT_TOKEN=your-bot-token
+```
+
+### Slack
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_SLACK=true
+MERCURY_SLACK_BOT_TOKEN=xoxb-...
+MERCURY_SLACK_SIGNING_SECRET=...
+```
+
+### Teams
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_TEAMS=true
+MERCURY_TEAMS_APP_ID=...
+MERCURY_TEAMS_APP_PASSWORD=...
+MERCURY_TEAMS_APP_TENANT_ID=...
+```
+
+## Dashboard Auth
+
+The web dashboard is protected by `MERCURY_API_SECRET`. Browser sessions are established via a login handshake managed by the cloud console — see [dashboard.md](dashboard.md).
+
+## Security
+
+- `auth.json` has `0600` permissions (owner read/write only)
+- WhatsApp credentials in `.mercury/whatsapp-auth/` are sensitive — treat like passwords
+- All `MERCURY_*` env vars are passed into containers with the prefix stripped
+- Never commit `.env` or `auth.json` to version control