mercury-agent 0.4.28 → 0.5.1

package/docs/auth/whatsapp.md

@@ -1,173 +1,173 @@
-# WhatsApp Authentication
-
-Mercury connects to WhatsApp using the [Baileys](https://github.com/WhiskeySockets/Baileys) library, which implements the WhatsApp Web protocol. This means you need to link your WhatsApp account just like you would link WhatsApp Web.
-
-## Initial Setup
-
-### QR Code Mode (Recommended)
-
-The simplest way to authenticate:
-
-```bash
-mercury auth whatsapp
-```
-
-This will:
-1. Display a QR code in your terminal
-2. Wait for you to scan it with WhatsApp
-3. Save credentials to `.mercury/whatsapp-auth/`
-4. Exit when authentication is complete
-
-**To scan:**
-1. Open WhatsApp on your phone
-2. Tap **Settings → Linked Devices → Link a Device**
-3. Point your camera at the QR code
-
-### Pairing Code Mode
-
-If you can't scan QR codes (e.g., running on a remote server), use pairing code mode:
-
-```bash
-mercury auth whatsapp --pairing-code --phone 14155551234
-```
-
-Replace `14155551234` with your phone number (country code + number, no `+` or spaces).
-
-This will:
-1. Request a pairing code from WhatsApp
-2. Display an 8-character code
-3. Wait for you to enter it on your phone
-
-**To pair:**
-1. Open WhatsApp on your phone
-2. Tap **Settings → Linked Devices → Link a Device**
-3. Tap **"Link with phone number instead"**
-4. Enter the code shown in your terminal
-
-## Session Lifecycle
-
-### Session Duration
-
-WhatsApp linked device sessions typically last **~14-20 days** before requiring re-authentication. This is controlled by WhatsApp, not Mercury.
-
-Signs your session has expired:
-- WhatsApp stops receiving messages
-- Logs show `connection closed` with `loggedOut` reason
-- Status file shows `failed:logged_out`
-
-### Re-authentication
-
-If your session expires:
-
-1. **Stop Mercury** (if running):
-   ```bash
-   # Ctrl+C in the terminal running mercury, or
-   pkill -f "bun.*chat-sdk"
-   ```
-
-2. **Delete old credentials**:
-   ```bash
-   rm -rf .mercury/whatsapp-auth/
-   ```
-
-3. **Re-authenticate**:
-   ```bash
-   mercury auth whatsapp
-   ```
-
-4. **Restart Mercury**:
-   ```bash
-   mercury run
-   ```
-
-## Status Files
-
-The auth script writes status files for external monitoring (useful for headless deployments):
-
-| File | Description |
-|------|-------------|
-| `.mercury/whatsapp-status.txt` | Current status (`authenticated`, `waiting_qr`, `pairing_code:XXXX`, `failed:reason`) |
-| `.mercury/whatsapp-qr.txt` | Raw QR data for external rendering (deleted after successful auth) |
-
-### Status Values
-
-- `authenticated` — Successfully connected
-- `already_authenticated` — Existing valid session found
-- `waiting_qr` — Waiting for QR code scan
-- `pairing_code:XXXXXXXX` — Waiting for pairing code entry
-- `failed:logged_out` — Session was logged out by WhatsApp
-- `failed:qr_timeout` — QR code expired before scan
-- `failed:515` — Stream error (usually recovers automatically)
-- `failed:unknown` — Other connection failure
-
-## Auth Status API Endpoint
-
-When Mercury is running, you can check auth status via the API:
-
-```bash
-curl http://localhost:8787/auth/whatsapp
-```
-
-**Responses:**
-
-```json
-// Authenticated and connected
-{ "status": "authenticated" }
-
-// Waiting for QR scan (includes raw QR data)
-{ "status": "waiting", "qr": "2@AbCdEf123..." }
-
-// Disconnected or not yet connected
-{ "status": "disconnected" }
-```
-
-This endpoint requires no authentication, making it suitable for headless monitoring dashboards.
-
-## Troubleshooting
-
-### "Already authenticated"
-
-If you see this but WhatsApp isn't working:
-```bash
-rm -rf .mercury/whatsapp-auth/
-mercury auth whatsapp
-```
-
-### QR code times out too quickly
-
-WhatsApp QR codes expire after ~20 seconds. If you're having trouble:
-1. Have your phone ready before running the command
-2. Use `--pairing-code` mode instead
-
-### "Stream error (515)"
-
-This is usually transient and the auth script will automatically reconnect. If it persists:
-```bash
-rm -rf .mercury/whatsapp-auth/
-mercury auth whatsapp
-```
-
-### WhatsApp shows "Linked Device" but Mercury doesn't receive messages
-
-1. Check that `MERCURY_ENABLE_WHATSAPP=true` is set in `.env`
-2. Check logs for connection errors
-3. Try re-authenticating
-
-### Messages from before startup appear
-
-Mercury ignores messages that were sent before it connected to prevent processing old backlog. This is intentional.
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MERCURY_ENABLE_WHATSAPP` | `false` | Enable WhatsApp adapter |
-| `MERCURY_WHATSAPP_AUTH_DIR` | `.mercury/whatsapp-auth` | Directory for auth credentials |
-| `MERCURY_DATA_DIR` | `.mercury` | Base data directory (auth dir is relative to this) |
-
-## Security Notes
-
-- Auth credentials in `.mercury/whatsapp-auth/` are sensitive — treat them like passwords
-- Anyone with access to these files can impersonate your WhatsApp account
-- The `/auth/whatsapp` endpoint is unauthenticated — only expose your API port to trusted networks
-- Consider using a dedicated WhatsApp number for your bot
+# WhatsApp Authentication
+
+Mercury connects to WhatsApp using the [Baileys](https://github.com/WhiskeySockets/Baileys) library, which implements the WhatsApp Web protocol. This means you need to link your WhatsApp account just like you would link WhatsApp Web.
+
+## Initial Setup
+
+### QR Code Mode (Recommended)
+
+The simplest way to authenticate:
+
+```bash
+mercury auth whatsapp
+```
+
+This will:
+1. Display a QR code in your terminal
+2. Wait for you to scan it with WhatsApp
+3. Save credentials to `.mercury/whatsapp-auth/`
+4. Exit when authentication is complete
+
+**To scan:**
+1. Open WhatsApp on your phone
+2. Tap **Settings → Linked Devices → Link a Device**
+3. Point your camera at the QR code
+
+### Pairing Code Mode
+
+If you can't scan QR codes (e.g., running on a remote server), use pairing code mode:
+
+```bash
+mercury auth whatsapp --pairing-code --phone 14155551234
+```
+
+Replace `14155551234` with your phone number (country code + number, no `+` or spaces).
+
+This will:
+1. Request a pairing code from WhatsApp
+2. Display an 8-character code
+3. Wait for you to enter it on your phone
+
+**To pair:**
+1. Open WhatsApp on your phone
+2. Tap **Settings → Linked Devices → Link a Device**
+3. Tap **"Link with phone number instead"**
+4. Enter the code shown in your terminal
+
+## Session Lifecycle
+
+### Session Duration
+
+WhatsApp linked device sessions typically last **~14-20 days** before requiring re-authentication. This is controlled by WhatsApp, not Mercury.
+
+Signs your session has expired:
+- WhatsApp stops receiving messages
+- Logs show `connection closed` with `loggedOut` reason
+- Status file shows `failed:logged_out`
+
+### Re-authentication
+
+If your session expires:
+
+1. **Stop Mercury** (if running):
+   ```bash
+   # Ctrl+C in the terminal running mercury, or
+   pkill -f "bun.*chat-sdk"
+   ```
+
+2. **Delete old credentials**:
+   ```bash
+   rm -rf .mercury/whatsapp-auth/
+   ```
+
+3. **Re-authenticate**:
+   ```bash
+   mercury auth whatsapp
+   ```
+
+4. **Restart Mercury**:
+   ```bash
+   mercury run
+   ```
+
+## Status Files
+
+The auth script writes status files for external monitoring (useful for headless deployments):
+
+| File | Description |
+|------|-------------|
+| `.mercury/whatsapp-status.txt` | Current status (`authenticated`, `waiting_qr`, `pairing_code:XXXX`, `failed:reason`) |
+| `.mercury/whatsapp-qr.txt` | Raw QR data for external rendering (deleted after successful auth) |
+
+### Status Values
+
+- `authenticated` — Successfully connected
+- `already_authenticated` — Existing valid session found
+- `waiting_qr` — Waiting for QR code scan
+- `pairing_code:XXXXXXXX` — Waiting for pairing code entry
+- `failed:logged_out` — Session was logged out by WhatsApp
+- `failed:qr_timeout` — QR code expired before scan
+- `failed:515` — Stream error (usually recovers automatically)
+- `failed:unknown` — Other connection failure
+
+## Auth Status API Endpoint
+
+When Mercury is running, you can check auth status via the API:
+
+```bash
+curl http://localhost:8787/auth/whatsapp
+```
+
+**Responses:**
+
+```json
+// Authenticated and connected
+{ "status": "authenticated" }
+
+// Waiting for QR scan (includes raw QR data)
+{ "status": "waiting", "qr": "2@AbCdEf123..." }
+
+// Disconnected or not yet connected
+{ "status": "disconnected" }
+```
+
+This endpoint requires no authentication, making it suitable for headless monitoring dashboards.
+
+## Troubleshooting
+
+### "Already authenticated"
+
+If you see this but WhatsApp isn't working:
+```bash
+rm -rf .mercury/whatsapp-auth/
+mercury auth whatsapp
+```
+
+### QR code times out too quickly
+
+WhatsApp QR codes expire after ~20 seconds. If you're having trouble:
+1. Have your phone ready before running the command
+2. Use `--pairing-code` mode instead
+
+### "Stream error (515)"
+
+This is usually transient and the auth script will automatically reconnect. If it persists:
+```bash
+rm -rf .mercury/whatsapp-auth/
+mercury auth whatsapp
+```
+
+### WhatsApp shows "Linked Device" but Mercury doesn't receive messages
+
+1. Check that `MERCURY_ENABLE_WHATSAPP=true` is set in `.env`
+2. Check logs for connection errors
+3. Try re-authenticating
+
+### Messages from before startup appear
+
+Mercury ignores messages that were sent before it connected to prevent processing old backlog. This is intentional.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MERCURY_ENABLE_WHATSAPP` | `false` | Enable WhatsApp adapter |
+| `MERCURY_WHATSAPP_AUTH_DIR` | `.mercury/whatsapp-auth` | Directory for auth credentials |
+| `MERCURY_DATA_DIR` | `.mercury` | Base data directory (auth dir is relative to this) |
+
+## Security Notes
+
+- Auth credentials in `.mercury/whatsapp-auth/` are sensitive — treat them like passwords
+- Anyone with access to these files can impersonate your WhatsApp account
+- The `/auth/whatsapp` endpoint is unauthenticated — only expose your API port to trusted networks
+- Consider using a dedicated WhatsApp number for your bot

package/docs/authoring-profiles.md

@@ -0,0 +1,174 @@
+# Authoring Applicative Profiles
+
+The contract for building a **profile** — a package of deterministic business
+logic that wraps raw capabilities (Calendar, email, …) and scopes what members
+can do. Mercury (this repo) provides the schema, loader, permission scoping, and
+the host-side capability broker; **profiles live in a separate repo** and depend
+only on this contract.
+
+> Layers: **Mercury** = platform (messaging, spaces, permissions, tokens,
+> broker). **Capability extensions** = raw API access (e.g. `gws`), admin-only.
+> **Profiles** = deterministic domain logic wrapping capabilities, member-facing.
+
+## 1. Profile manifest — `mercury-profile.yaml`
+
+```yaml
+name: barber-appointments            # lowercase-kebab; required
+description: Appointment booking for a barber shop
+version: 0.1.0
+
+agents_md: ./AGENTS.md               # optional; copied to the global AGENTS.md
+
+# Raw capability extensions this profile requires to be installed. Validated at
+# apply time — activation fails loudly if any are missing.
+capabilities:
+  - gws
+
+# Extensions this profile ships (copied into .mercury/extensions).
+extensions:
+  - name: barber
+    source: ./extensions/barber
+
+# EXHAUSTIVE member permission set while active. When present it REPLACES the
+# default member permissions — nothing is merged in — so raw capabilities stay
+# admin-only unless listed here. Omit entirely to keep built-in defaults.
+member_permissions:
+  - prompt
+  - prefs.get
+  - barber                           # the profile's own capability, NOT gws
+
+# Optional env the profile needs (host-side credentials for capabilities).
+env:
+  - key: MERCURY_BARBER_BUSINESS_HOURS
+    description: "Business hours"
+    default: "09:00-18:00"
+
+# Project-wide agent persona, injected into every container's system prompt.
+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
+```
+
+Apply it with `mercury profile apply <name|path|git-url>`. That validates
+capabilities, copies extensions/AGENTS.md, and persists activation to
+`.mercury/active-profile.json`, which Mercury loads at startup.
+
+## 2. The capability broker (where the business logic runs)
+
+A profile's privileged work runs **on the host**, so credentials never enter the
+customer-controlled agent container. The profile's extension registers a
+handler; the agent invokes it through a thin CLI.
+
+### Register a handler (in the extension's `index.ts`)
+
+```ts
+import type { ExtensionSetupFn } from "mercury-agent"; // types from this repo
+
+const setup: ExtensionSetupFn = (mercury) => {
+  // Make the capability gate-able. Members get it via member_permissions.
+  mercury.permission({ defaultRoles: [] });
+
+  // Host-side credentials for the wrapped capability (never sent to the container).
+  mercury.env({ from: "MERCURY_BARBER_GOOGLE_CREDENTIALS" });
+
+  mercury.capability("barber", async (req, ctx) => {
+    // req.callerId is the TOKEN-DERIVED, unspoofable caller — safe for ownership.
+    switch (req.action) {
+      case "availability":
+        return { data: await listOpenSlots(req.body, ctx) };
+      case "book":
+        return { data: await book(req.callerId, req.body, ctx) };
+      case "cancel":
+        return { data: await cancelOwn(req.callerId, req.body, ctx) };
+      case "my-appointments":
+        return { data: await listOwn(req.callerId, ctx) };
+      default:
+        return { status: 400, data: { error: `unknown action: ${req.action}` } };
+    }
+  });
+};
+
+export default setup;
+```
+
+### The contract types (exported from this repo)
+
+```ts
+type CapabilityHandler = (
+  req: CapabilityRequest,
+  ctx: MercuryExtensionContext,
+) => Promise<CapabilityResult>;
+
+interface CapabilityRequest {
+  name: string;      // capability name
+  action: string;    // sub-action (book, cancel, …)
+  callerId: string;  // token-derived, TRUSTWORTHY — use for ownership checks
+  spaceId: string;
+  body: unknown;     // parsed JSON request body (or null)
+}
+
+interface CapabilityResult {
+  status?: number;   // default 200
+  data: unknown;     // JSON-serializable response
+}
+```
+
+`ctx` (`MercuryExtensionContext`) gives you `db`, `config`, `log`, and
+`hasCallerPermission(spaceId, callerId, permission)`. Store per-profile state via
+`mercury.store` (namespaced KV) or your own tables through `ctx.db`.
+
+### How the agent invokes it
+
+Inside the container the agent runs:
+
+```
+mrctl capability barber book '{"slot":"2026-07-02T15:00"}'
+```
+
+→ `POST /api/capability/barber/book`. Document these commands for the agent in
+the extension's `SKILL.md` or the profile's `AGENTS.md`.
+
+## 3. Permission & security model (non-negotiable)
+
+- **`member_permissions` is exhaustive.** List every permission a member may
+  hold, including the capability name (e.g. `barber`). Anything not listed —
+  including raw capabilities like `gws` — is unavailable to members.
+- **Authorization = permission named after the capability.** The broker route
+  requires the caller to hold the `<name>` permission; the same grant gates both
+  the `mrctl capability <name> …` CLI and the route. Keep capability name ==
+  permission name == the entry in `member_permissions`.
+- **Credentials stay on the host.** Put capability credentials in host env
+  (`mercury.env`) / `mercury.store` and use them only inside the handler. Never
+  expose a raw capability CLI (e.g. `gws`) to members — its secret would be
+  readable inside the container.
+- **Enforce ownership with `req.callerId`.** It is token-derived and cannot be
+  spoofed by the container. Never trust an id passed in `req.body`.
+- **`callerId === "system"`** for scheduled/system runs — handle it explicitly
+  (e.g. skip per-customer ownership).
+
+## 4. Suggested profile repo layout
+
+```
+<profile-repo>/
+  barber/                      # one folder per profile
+    mercury-profile.yaml
+    AGENTS.md
+    extensions/
+      barber/
+        index.ts               # registers permission + capability
+        package.json
+```
+
+Depend on this repo (`mercury-agent`) for the types
+(`ExtensionSetupFn`, `CapabilityRequest`, `CapabilityResult`,
+`MercuryExtensionContext`). See `src/extensions/types.ts` for the full surface.
+
+## 5. Local test loop
+
+1. `mercury profile apply ./barber`
+2. `mercury service install` (builds the derived image with the extension CLI)
+3. DM the bot as a non-admin number; confirm you can `book`/`cancel` only your
+   own appointments and cannot reach `gws`/Gmail.

package/docs/configuration.md

@@ -1,54 +1,54 @@
-# Configuration
-
-Mercury reads settings from **environment variables** (`MERCURY_*`) and, optionally, a project **`mercury.yaml`** file in the current working directory.
-
-**Product / design spec:** [prd-config-load.md](prd-config-load.md) (config load: YAML + env precedence, security, non-goals).
-
-## Precedence
-
-1. If a `MERCURY_*` variable is **set** in the environment (the key exists, including empty string), its value wins.
-2. Otherwise, if **`mercury.yaml`** (or **`mercury.yml`**) exists in `cwd`, values from that file apply.
-3. Otherwise, built-in defaults from `config.ts` apply.
-
-Set **`MERCURY_CONFIG_FILE`** to an explicit path to load a different file. Set it to **`""`** (empty) or **`none`** to **disable** loading any file (useful for tests or when you want env/defaults only).
-
-Relative paths in `MERCURY_CONFIG_FILE` are resolved against `cwd`.
-
-## Secrets (never use `mercury.yaml` for these)
-
-These must be supplied via environment variables only; they are **not** read from YAML:
-
-- `MERCURY_API_SECRET`
-- `MERCURY_CHAT_API_KEY`
-- `MERCURY_DISCORD_GATEWAY_SECRET`
-
-Platform tokens, provider API keys, and extension keys (e.g. `MERCURY_TELEGRAM_BOT_TOKEN`, `MERCURY_BRAVE_API_KEY`) are also **env-only** today—they are not part of the YAML schema.
-
-## YAML layout
-
-See [`resources/templates/mercury.example.yaml`](../resources/templates/mercury.example.yaml) for a commented template. Supported sections include `server`, `model`, `ingress`, `runtime`, `trigger`, `context`, `conditional_context`, `compaction`, `agent`, `discord`, `telegram`, `media`, and `permissions`.
-
-The `context:` block seeds default conversation-context behavior into the `main` space on first boot:
-
-```yaml
-context:
-  mode: context              # clear | context (default: context)
-  window_size: 10            # 1-50 (default: 10). Sliding-window turns when mode=context.
-  reply_chain_depth: 10      # 1-50 (default: 10). Reply chain depth when mode=clear.
-```
-
-Per-space overrides via `mrctl config set context.<key> <value>` always win over YAML defaults; YAML re-reads on restart do not overwrite an existing space row.
-
-You may also set a top-level **`model_chain`** array as an alias for `model.chain`.
-
-## Model chain
-
-In YAML, use a list of `{ provider, model }` objects under `model.chain` (max 4 legs). The same rules apply as for `MERCURY_MODEL_CHAIN` JSON.
-
-Optional **`model.capabilities`** may be a mapping; it is applied like `MERCURY_MODEL_CAPABILITIES` JSON.
-
-### Removed: `provider: cursor`
-
-The **Cursor Agent CLI** integration has been removed. All model legs use **pi** with standard providers (`anthropic`, `openai`, `google`, `mistral`, `groq`, `openrouter`, etc.).
-
-If your chain still has `provider: cursor`, the agent run **fails fast** with an error that points here. Switch to the **native provider** for the model you want (for example `anthropic` for Claude, `openai` for GPT) and set the matching **`MERCURY_*_API_KEY`**.
+# Configuration
+
+Mercury reads settings from **environment variables** (`MERCURY_*`) and, optionally, a project **`mercury.yaml`** file in the current working directory.
+
+**Product / design spec:** [prd-config-load.md](prd-config-load.md) (config load: YAML + env precedence, security, non-goals).
+
+## Precedence
+
+1. If a `MERCURY_*` variable is **set** in the environment (the key exists, including empty string), its value wins.
+2. Otherwise, if **`mercury.yaml`** (or **`mercury.yml`**) exists in `cwd`, values from that file apply.
+3. Otherwise, built-in defaults from `config.ts` apply.
+
+Set **`MERCURY_CONFIG_FILE`** to an explicit path to load a different file. Set it to **`""`** (empty) or **`none`** to **disable** loading any file (useful for tests or when you want env/defaults only).
+
+Relative paths in `MERCURY_CONFIG_FILE` are resolved against `cwd`.
+
+## Secrets (never use `mercury.yaml` for these)
+
+These must be supplied via environment variables only; they are **not** read from YAML:
+
+- `MERCURY_API_SECRET`
+- `MERCURY_CHAT_API_KEY`
+- `MERCURY_DISCORD_GATEWAY_SECRET`
+
+Platform tokens, provider API keys, and extension keys (e.g. `MERCURY_TELEGRAM_BOT_TOKEN`, `MERCURY_BRAVE_API_KEY`) are also **env-only** today—they are not part of the YAML schema.
+
+## YAML layout
+
+See [`resources/templates/mercury.example.yaml`](../resources/templates/mercury.example.yaml) for a commented template. Supported sections include `server`, `model`, `ingress`, `runtime`, `trigger`, `context`, `conditional_context`, `compaction`, `agent`, `discord`, `telegram`, `media`, and `permissions`.
+
+The `context:` block seeds default conversation-context behavior into the `main` space on first boot:
+
+```yaml
+context:
+  mode: context              # clear | context (default: context)
+  window_size: 10            # 1-50 (default: 10). Sliding-window turns when mode=context.
+  reply_chain_depth: 10      # 1-50 (default: 10). Reply chain depth when mode=clear.
+```
+
+Per-space overrides via `mrctl config set context.<key> <value>` always win over YAML defaults; YAML re-reads on restart do not overwrite an existing space row.
+
+You may also set a top-level **`model_chain`** array as an alias for `model.chain`.
+
+## Model chain
+
+In YAML, use a list of `{ provider, model }` objects under `model.chain` (max 4 legs). The same rules apply as for `MERCURY_MODEL_CHAIN` JSON.
+
+Optional **`model.capabilities`** may be a mapping; it is applied like `MERCURY_MODEL_CAPABILITIES` JSON.
+
+### Removed: `provider: cursor`
+
+The **Cursor Agent CLI** integration has been removed. All model legs use **pi** with standard providers (`anthropic`, `openai`, `google`, `mistral`, `groq`, `openrouter`, etc.).
+
+If your chain still has `provider: cursor`, the agent run **fails fast** with an error that points here. Switch to the **native provider** for the model you want (for example `anthropic` for Claude, `openai` for GPT) and set the matching **`MERCURY_*_API_KEY`**.