mercury-agent 0.18.0-beta.0 → 0.18.1

package/README.md

@@ -167,6 +167,7 @@ Install extensions from the dashboard (**Features** page), the CLI, or during se
 ```bash
 # From the CLI
 mercury add web-browser         # Web browsing & search (uses Brave Search, no API key needed)
+mercury add web-search          # Brave Search API + site search skill (key stays on the host)
 mercury add napkin              # Obsidian-style knowledge vault
 
 # Or pick a profile that bundles what you need

package/docs/configuration.md

@@ -146,7 +146,7 @@ agent:
   env_passthrough: all       # all (default) | claimed
 ```
 
-- **`all`** — every `MERCURY_*` var except a fixed blocklist is passed into the container with the prefix stripped (`MERCURY_BRAVE_API_KEY` → `BRAVE_API_KEY`). Convenient, but blunt: a secret added to `.env` for one purpose reaches **every space's container**, regardless of who triggered the turn or whether that space has anything to do with it.
+- **`all`** — every `MERCURY_*` var except a fixed blocklist is passed into the container with the prefix stripped (`MERCURY_BILLING_API_KEY` → `BILLING_API_KEY`). Convenient, but blunt: a secret added to `.env` for one purpose reaches **every space's container**, regardless of who triggered the turn or whether that space has anything to do with it. Vars an extension declares `hostOnly` are excluded even here — `MERCURY_BRAVE_API_KEY` stays on the host once `web-search` is installed, which brokers Brave queries through `mrctl capability web-search`.
 - **`claimed`** — only variables an extension declared via `mercury.env()` are passed, and only when the triggering caller holds that extension's permission. Undeclared variables stay on the host.
 
 **Model-provider credentials are exempt** and pass in both modes (`MERCURY_ANTHROPIC_API_KEY`, `MERCURY_ANTHROPIC_OAUTH_TOKEN`, `MERCURY_GEMINI_API_KEY`, `MERCURY_GROQ_API_KEY`, and the rest of the provider list). pi reads them inside the container, and no extension declares them — without the exemption, `claimed` would leave the agent unable to reach any model. They remain subject to the blocklist.
@@ -156,7 +156,7 @@ Env: `MERCURY_CONTAINER_ENV_PASSTHROUGH`.
 `claimed` is opt-in because it breaks setups that rely on blind passthrough for anything other than provider keys — API keys consumed by skills (search, TTS, scrapers) and any credential you added by hand. To migrate, declare those in an extension (see [extensions.md](extensions.md)) before switching. At startup with `all`, Mercury logs the vars it is passing that are neither declared nor provider credentials — names only, so a genuine outlier stands out:
 
 ```
-Container env passthrough: all — these vars reach every space's container and are scoped to nothing. […] vars=MERCURY_BRAVE_API_KEY, MERCURY_BILLING_API_KEY
+Container env passthrough: all — these vars reach every space's container and are scoped to nothing. […] vars=MERCURY_SCRAPER_API_KEY, MERCURY_BILLING_API_KEY
 ```
 
 For secrets that only host-side hooks and jobs need, prefer `mercury.env({ from: "…", hostOnly: true })`, which keeps them out of containers in either mode. For credentials the agent should never hold at all, use a host-side capability handler (`mercury.capability()`), which runs the privileged call on the host and returns only the result.

package/docs/extensions.md

@@ -160,6 +160,7 @@ mercury.on("workspace_init", async (event, ctx) => {
 | `workspace_init` | Space workspace created/ensured | No |
 | `before_container` | About to spawn container | Yes |
 | `after_container` | Container finished | Yes |
+| `delivery` | Reply stored, attachments final | No |
 
 Both `workspace_init` and `before_container` events include:
 - `workspace` — absolute host path (for file operations on the host)
@@ -198,6 +199,34 @@ mercury.on("after_container", async (event, ctx) => {
 });
 ```
 
+#### `delivery` — what the user actually received
+
+```typescript
+mercury.on("delivery", async (event, ctx) => {
+  // event.files    — exactly what the adapter will attach
+  // event.withheld — what the media gate stripped
+  // event.userMessageId / event.assistantMessageId — both rows exist
+});
+```
+
+Use this, not `after_container`, whenever a hook needs to know **what was
+delivered**. `after_container` fires *before* the media send gate and can still
+rewrite the reply, so its file list is a proposal: a handler reading it cannot
+tell whether the recipient was actually shown those files. `delivery` fires
+after the gate and after the assistant row is written.
+
+It is non-mutating — by the time it runs, the reply has been decided — and it
+does not fire on paths where nothing reaches the user: a suppressed reply, or a
+scheduler no-op. Handler errors are logged and isolated, so a failing handler
+costs a log line and never the reply.
+
+`event.withheld` exists so a handler can tell "withheld" from "never produced".
+Never treat a withheld file as delivered: the gate replaces the file array
+rather than annotating it, so this is the only place that distinction survives.
+
+The `archive` extension is the worked example
+([`examples/extensions/archive/`](../examples/extensions/archive/)).
+
 ### `mercury.job(name, def)`
 
 Register a background job that runs on the host.
@@ -440,6 +469,50 @@ The skill is installed into the management space's own workspace on
 dir mounted into *every* container, which would advertise the capability to
 spaces that cannot use it.
 
+## Morning / Green Invoice invoicing (`morning`)
+
+`examples/extensions/morning/` issues tax documents through the
+[Morning](https://morning.co) API. Second `mercury.capability()` adopter after
+yahoo-mail, and the case that justifies rung 4: these credentials create legally
+binding documents against a real business, so they never enter a container.
+
+```bash
+mercury add ./examples/extensions/morning
+MERCURY_MORNING_CLIENT_ID=...      # hostOnly
+MERCURY_MORNING_CLIENT_SECRET=...  # hostOnly
+mrctl config set morning.environment sandbox   # or production; sandbox is the default
+```
+
+The agent calls it with `mrctl capability morning <action> '<json>'`:
+
+| Action | Body | Returns |
+|--------|------|---------|
+| `client-search` | `{name?, email?, page?, pageSize?}` | paginated clients |
+| `client-create` | `{name, taxId?, emails?, …}` | the new client |
+| `document-types` | `{lang?}` | `[{id, name}]`, localised |
+| `document-preview` | the document body | `{file, issueToken}` — base64 PDF, nothing created |
+| `document-create` | the same body **plus `issueToken`** | `{id, number, url}` |
+| `document-search` | `{fromDate?, toDate?, type?, …}` | paginated documents |
+| `document-links` | `{id}` | `{origin, he, en}` |
+
+Two properties are enforced in the broker rather than requested in the skill:
+
+- **Preview before issue.** `document-create` refuses without a single-use
+  `issueToken` minted by `document-preview` of the *identical* payload. The
+  token is bound to the payload hash, the environment, the space and the caller,
+  so a changed amount, a sandbox-previewed document presented against
+  production, another person's preview, or a retry after a successful create are
+  each refused. A prompt instruction is not a control when the model may be the
+  thing under attack.
+- **`sensitive: true`.** In a group-linked space the runtime then requires
+  `security.sensitive_connections_allowed` plus per-caller confirmation. Set that
+  key or the space refuses every turn — the symptom otherwise reads as a broken
+  extension.
+
+Slice 1 is invoices. Expenses are deferred: `POST /expenses` requires an
+`accountingClassification` whose lookup endpoint is absent from the published
+spec, and an uploaded file becomes a draft with no API to approve it.
+
 ## Examples
 
 See [`examples/extensions/`](../examples/extensions/) for complete, working extensions ranging from minimal (charts — CLI + skill) to full-featured (napkin — hooks, jobs, config, widgets, KB distillation).

package/docs/profile-guide.md

@@ -134,6 +134,7 @@ reads top-down and the first sections frame the rest.
 ## Silence                              when to say nothing and how (NO_UPDATE, "אין חדש")
 ## Integrity about what was done        "I wrote it" only after a successful write; who can change what
 ## Dedupe / memory routine              which file to read before posting and append after
+## Incoming files                        which uploads to keep, and where (see 4.7)
 ## Privacy                              "you may see it, you may not keep it" — never a denial of what is visible
 ## What this space does NOT do          one line each; the reader's expectations, closed explicitly
 ## Overrides of platform text           the explicit sentences (see 4.4)
@@ -248,6 +249,40 @@ is argued from memory. The football profile keeps the dates in
 `decisions.md` instead (every `D-0NN` names the day and its `Revisit if:`),
 which works as long as the file's section names match the decision ids.
 
+### 4.7 Incoming files: say which uploads to keep
+
+`inbox/` is a transit directory. It is swept after `MERCURY_INBOX_TTL_DAYS`
+(7 by default), and the sweep also nulls the attachment reference in
+`state.db` — so a week later the bot cannot produce the file *or* name it. No
+runtime rule can decide which uploads matter, because only the conversation
+knows. That makes it a profile rule, and a profile without one silently loses
+customer material.
+
+The rule that works, in one section:
+
+```
+## Incoming files
+A file sent with no request attached, or with "keep this" / "use this from now
+on", is reference material: move it to `knowledge/assets/<name>`, write a short
+note at `knowledge/references/<slug>.md` saying what it is and when to use it,
+and tell the person where you put it.
+A file sent as part of a request (edit this, summarise this) is working
+material: use it and leave it. It disappears after a week and that is fine.
+Never say you have kept a file unless you moved it.
+```
+
+Two things that rule gets right and the obvious version does not. **Silence
+defaults to keeping**: most uploads arriving with no question are meant to be
+kept, so an unclassified file should be shelved, not discarded. And the last
+line closes the integrity gap — the same one §"Integrity about what was done"
+exists for, applied to storage rather than to writes.
+
+Files the bot **sends** are the mirror problem and are *not* a profile rule:
+`outbox/` is swept after three days, and the `archive` extension is what keeps
+them. Install it and enable `archive.enabled` per space; the agent then has
+`mrctl capability archive list|get`. See
+[`../examples/extensions/archive/README.md`](../examples/extensions/archive/README.md).
+
 ---
 
 ## 5. Accuracy: put the computation in code

package/docs/skills-guide.md

@@ -155,6 +155,37 @@ never be blanket-copied over from the source: the copy reverts the paths to
 placeholders and the agent's commands break at runtime. Copy, substitute,
 then `diff` and confirm the only difference is the placeholder.
 
+### Reference material is not a skill, and does not live in `inbox/`
+
+A logo, a brand guide, a price list, a corpus a customer uploads "so you answer
+better" — none of these is a skill, and none of them survives where they land.
+`inbox/` is swept after `MERCURY_INBOX_TTL_DAYS` (7 by default), and the sweep
+also nulls the attachment reference in `state.db`, so the agent later cannot
+even name the file it was sent.
+
+Put reference material in the space workspace, which is never swept:
+
+| What | Where | Why there |
+|---|---|---|
+| the bytes (logo, PDF, spreadsheet) | `knowledge/assets/<name>` | outside every TTL; mounted every run |
+| a note describing it | `knowledge/references/<slug>.md` | the vault map indexes it, so the agent finds it the same way it finds everything else |
+
+`knowledge/assets/` is a plain directory, deliberately not a skill directory —
+pi scans only the two roots in the table above, and a binary in a skill dir
+would be listed in the system prompt as though it were an instruction. The note
+in `references/` is what makes the asset discoverable; write it the way you
+would write a skill description, naming the situation the file is for.
+
+Deciding *which* uploads become reference material is a **profile rule**, not
+something the runtime can infer — see `profile-guide.md`. The rule that works in
+practice is "a file sent with no request attached, or with 'keep this', is
+reference material": most uploads carrying no question are meant to be kept, so
+silence should default to keeping rather than to discarding.
+
+Files the assistant **sends** are a separate problem with a separate answer: the
+`archive` extension keeps them past the `outbox/` TTL and gives the agent
+`mrctl capability archive list|get`. It does not cover inbox uploads, by design.
+
 ## 7. Checklist before you ship a skill
 
 - [ ] `name` is lowercase-kebab, ≤64 chars; `description` ≤1024 chars, says

package/docs/web-search.md

@@ -10,7 +10,9 @@ mercury add web-browser
 
 Or install from the dashboard's **Features** page (one click).
 
-No API key is required. The extension uses [pinchtab](https://www.npmjs.com/package/pinchtab) to control a local headless Chromium and navigates to the public [Brave Search](https://search.brave.com) website — the same way a human would.
+No API key is required for the browser path. The extension uses [pinchtab](https://www.npmjs.com/package/pinchtab) to control a local headless Chromium and navigates to the public [Brave Search](https://search.brave.com) website — the same way a human would.
+
+The separate `web-search` extension (`mercury add web-search`) adds structured site search (flights, hotels, cars, apartments) on top of pinchtab and, for fast keyword and news lookups, exposes the Brave Search **API** as a host-side capability: set `MERCURY_BRAVE_API_KEY` in `.env` and the agent can run `mrctl capability web-search news '{"q":"..."}'` (or `web`). The key is declared `hostOnly`, so it never enters a container; the host makes the call, applies a per-space hourly cap (`brave_hourly_cap`, default 60), and returns trimmed results.
 
 ## What It Provides
 

package/examples/extensions/archive/README.md

@@ -0,0 +1,146 @@
+# archive
+
+Keeps every file the assistant delivers, after `outbox/` is swept.
+
+## The problem it solves
+
+`outbox/` is a delivery pipe that gets used as a memory. The storage sweep
+removes its files after `MERCURY_OUTBOX_TTL_DAYS` (3 by default), and in a space
+with no repo behind it — every customer space — the deliverable is then gone for
+good. A customer asking for last month's report cannot be answered.
+
+Raising the TTL only postpones that and costs disk on a box that does not have
+it. This extension adds the missing tier instead: a permanent, per-space,
+content-addressed store, with an index the agent can search and a delete path
+for a single item or a whole customer.
+
+## How it decides what to keep
+
+**Attachment is the classification.** The extension listens on `delivery`, which
+fires once the reply is stored and the media gate has run, so it sees what was
+committed for delivery. There is no tag for the agent to remember and no sweep
+racing the TTL cleanup.
+
+The event fires before the adapter's send returns, so a send that fails
+afterwards — a dropped socket — leaves a file archived that never arrived.
+That is deliberate: the alternative is archiving nothing until an
+acknowledgement that some platforms never give, and over-keeping is the
+recoverable direction.
+
+What is therefore *not* archived, by design:
+
+- files the media gate withheld — they were never delivered;
+- files in `inbox/` that no run ever turned into a deliverable. Reference
+  material a customer wants kept (a logo, a brand guide, a price list) belongs
+  in `knowledge/assets/` with a note in `knowledge/references/`, which is a
+  profile rule, not this extension's job. See `docs/skills-guide.md`.
+
+## Install
+
+```bash
+mercury add ./examples/extensions/archive
+```
+
+Then enable it per space — it is **off by default**, so installing it changes
+nothing until you say so:
+
+```bash
+mrctl config set archive.enabled true
+```
+
+To turn it on for every space, set `archive.enabled` in the `@global` scope on
+the dashboard, or in `mercury.yaml` under `extensions:`.
+
+> On a deployment running an applicative profile, an extension is only reachable
+> once its permission is in the profile's `member_permissions` (both the source
+> YAML and the deployed `active-profile.json`). Without that the capability is
+> silently unavailable to members.
+
+## Configuration
+
+All host-side and `hostOnly` — none of it enters a container.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `MERCURY_ARCHIVE_BACKEND` | `local` | `local` or `drive` |
+| `MERCURY_ARCHIVE_LOCAL_DIR` | `<dataDir>/archive/blobs` | Where the local backend stores blobs |
+| `MERCURY_ARCHIVE_DRIVE_FOLDER` | `Mercury Archive` | Root folder name in the connected Google account |
+| `MERCURY_GWS_CREDENTIALS_JSON` | — | Required for `drive`; the same credential `gws` uses |
+
+A backend that cannot be built disables the extension with an error in the log
+and **never** breaks delivery. If you see `[archive] disabled — …` at startup,
+that is this, and the reason is on the same line.
+
+### Which backend
+
+**`local`** works with nothing configured. Point `MERCURY_ARCHIVE_LOCAL_DIR` at
+a mounted Storage Box and the bytes leave the VPS without any further change.
+On a bare VPS disk it does *not* survive that disk — that is the backup
+runbook's job (`docs/runbooks/backup-offbox.md`), and archive and backup are
+deliberately different systems with different retention.
+
+**`drive`** reuses the Google credential the `gws` extension already needs, so a
+deployment with Google connected gains an off-box archive with no new vendor and
+no new account. On a customer's own VPS with their own Google account this also
+settles ownership: the files are in the customer's Drive, so if they leave they
+keep their deliverables.
+
+Two things to check before enabling `drive`:
+
+- **Is the OAuth app published?** An app still in "Testing" issues refresh
+  tokens that expire after 7 days. The archive will keep retrying and logging
+  `invalid_grant`. Publish the app in the GCP console, or expect to re-consent
+  weekly.
+- **Whose Drive is it?** On a shared deployment the credential is the operator's,
+  so every customer's deliverables land in the operator's Drive. That is a
+  contractual question, not a technical one.
+
+## Erasure
+
+One item, by an admin, from chat:
+
+```
+mrctl capability archive forget '{"id":"<id>"}'
+```
+
+Appends a tombstone and deletes the bytes unless another archived entry
+references the same file. Permanent — on Drive this is `files.delete`, not the
+trash.
+
+A whole customer, by an operator, from the host:
+
+```bash
+bun run scripts/archive-erase-space.ts <space-id>          # dry run
+bun run scripts/archive-erase-space.ts <space-id> --yes    # do it
+```
+
+Removes the backend prefix, the spool, the manifest and `ARCHIVE.md`. Dry-run by
+default because it cannot be undone.
+
+**After restoring from a backup**, re-run the drain and reconcile so tombstones
+written after the snapshot are re-applied. Both are idempotent. Without this
+step a restore silently resurrects erased files — the failure the EDPB's 2026
+enforcement report singles out.
+
+## Operational notes
+
+- **Never enable object lock or bucket versioning** on an archive store. They
+  make per-item erasure impossible, which is the one thing this must be able to
+  do.
+- Uploads are queued: the delivery hook only hashes and copies to a host-side
+  spool, and a job every 60s does the upload with retries. A backend outage
+  grows the spool and logs; it never delays or breaks a reply.
+- A weekly reconcile compares the store against the manifest. Orphaned blobs are
+  deleted. A live entry with no bytes is logged at **error** level and cannot be
+  repaired automatically — it means an archived file can no longer be delivered.
+
+## Layout
+
+| File | What it is |
+|---|---|
+| `index.ts` | Wiring: permission, config, `delivery` hook, jobs, capability |
+| `manifest.ts` | The append-only JSONL log and `ARCHIVE.md` rendering |
+| `queue.ts` | The spool and the drain, including the blob-before-manifest rule |
+| `gc.ts` | Erasure and the reconcile job |
+| `backends/` | `local` and `drive`, behind one interface |
+| `capability.ts` | `list` / `get` / `forget`, and the admin gate on `forget` |