mercury-agent 0.4.5

package/docs/subagents.md

@@ -0,0 +1,166 @@
+# Subagents
+
+Mercury supports delegating tasks to specialized sub-agents using pi's subagent extension. Each sub-agent runs in its own isolated context window, keeping the main conversation clean.
+
+## How It Works
+
+When the agent invokes the `subagent` tool, it spawns a separate `pi` process with:
+- Its own context window (isolated from main conversation)
+- A specific system prompt (from the agent definition)
+- Optionally a different model (e.g., Haiku for fast recon)
+
+```
+Main Agent
+  │
+  └─► subagent tool
+        │
+        ├─► Spawn pi process
+        │     • --mode json
+        │     • --model <agent-model>
+        │     • --tools <agent-tools>
+        │     • --append-system-prompt <agent.md>
+        │
+        ├─► Stream messages back
+        │
+        └─► Return final output to main agent
+```
+
+## Built-in Agents
+
+| Agent | Purpose | Model | Tools |
+|-------|---------|-------|-------|
+| `explore` | Fast codebase reconnaissance | Haiku | read, grep, find, ls, bash |
+| `worker` | General-purpose tasks | Sonnet | all |
+
+### explore
+
+Quickly investigates a codebase and returns structured findings. Outputs:
+- Files retrieved with line ranges
+- Key code snippets (types, interfaces, functions)
+- Architecture overview
+- Where to start
+
+### worker
+
+General-purpose agent with full capabilities. Works autonomously and reports:
+- What was done
+- Files changed
+- Notes for handoff
+
+## Execution Modes
+
+### Single Agent
+
+Delegate one task to one agent:
+
+```
+"Use explore to find all rate limiting code"
+```
+
+### Parallel Execution
+
+Run multiple agents concurrently (max 8 tasks, 4 concurrent):
+
+```
+"Run 2 workers in parallel: one to refactor the router, one to update tests"
+```
+
+### Chained Workflow
+
+Sequential execution where each agent receives the previous output via `{previous}`:
+
+```
+"Use a chain: first have explore find the auth code, then have worker add rate limiting"
+```
+
+## File Locations
+
+After `mercury init`, subagent files are scaffolded to:
+
+```
+.mercury/global/
+├── extensions/subagent/
+│   ├── index.ts      # Subagent tool implementation
+│   └── agents.ts     # Agent discovery logic
+└── agents/
+    ├── explore.md    # Explorer agent definition
+    └── worker.md     # Worker agent definition
+```
+
+## Adding Custom Agents
+
+Create a new `.md` file in `.mercury/global/agents/`:
+
+```markdown
+---
+name: researcher
+description: Deep research specialist for complex questions
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-5
+---
+
+You are a research specialist. Thoroughly investigate questions and provide comprehensive answers.
+
+## Strategy
+1. Break down the question
+2. Search for relevant information
+3. Synthesize findings
+
+## Output Format
+- Summary
+- Key findings
+- Sources
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Agent identifier (used in subagent calls) |
+| `description` | Yes | Brief description of the agent's purpose |
+| `tools` | No | Comma-separated list of allowed tools |
+| `model` | No | Model to use (defaults to current model) |
+
+The body after the frontmatter becomes the agent's system prompt.
+
+## Agent Discovery
+
+Agents are discovered from:
+1. **User agents**: `~/.pi/agent/agents/` (default scope)
+2. **Project agents**: `.mercury/global/agents/` (requires `agentScope: "both"`)
+
+Project agents require user confirmation before running (security measure for repo-controlled code).
+
+## Configuration
+
+The subagent tool accepts these parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `agent` | string | Agent name (single mode) |
+| `task` | string | Task description (single mode) |
+| `tasks` | array | Array of `{agent, task}` (parallel mode) |
+| `chain` | array | Array of `{agent, task}` (chain mode) |
+| `agentScope` | string | `"user"`, `"project"`, or `"both"` |
+| `cwd` | string | Working directory for the agent |
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Max parallel tasks | 8 |
+| Max concurrency | 4 |
+
+## Example Usage
+
+In the chat, users can request subagent work naturally:
+
+```
+@Mercury Use explore to find how authentication works in this codebase
+
+@Mercury Run a chain: explore finds the database models, then worker adds a new "status" field to the User model
+
+@Mercury Run 2 workers in parallel: one fixes the bug in router.ts, one adds a test for it
+```
+
+The main agent interprets these requests and invokes the subagent tool accordingly.

package/docs/web-search.md

@@ -0,0 +1,62 @@
+# Web Search
+
+Web search is **extension-based** in Mercury.
+
+Mercury core does not ship a built-in browser/search CLI. Instead, install a web automation extension (for example, `pinchtab`) and let the agent use that tool directly.
+
+---
+
+## Recommended Setup
+
+Use the real example extension at:
+
+- `examples/extensions/pinchtab/`
+
+It demonstrates:
+
+- installing browser tooling in the derived image
+- `before_container` hook for runtime env injection
+- system-prompt guidance for consistent search behavior
+
+---
+
+## Typical Flow
+
+1. Start browser automation tool (`pinchtab`)
+2. Navigate to search engine URL (e.g. Brave Search)
+3. Extract text/snapshot content
+4. Summarize and cite key findings
+
+Example command pattern used by agents (see `examples/extensions/pinchtab/` for `pinchtab_ensure` — wait until the bridge listens on `:9867` before calling the CLI; otherwise you get `connection refused`):
+
+```bash
+pinchtab_ensure || exit 1
+pinchtab nav "https://search.brave.com/search?q=your+query"
+sleep 3
+pinchtab text
+```
+
+---
+
+## Why Extension-Based
+
+- keeps Mercury core lean
+- lets each deployment pick its own browser/search stack
+- allows per-space RBAC for web tooling (`pinchtab` permission)
+- avoids locking users into one provider/tool
+
+---
+
+## Security & RBAC
+
+Extension CLIs are called directly in bash, with RBAC enforced by Mercury's in-container permission guard.
+
+If a caller lacks permission for a web extension CLI, execution is blocked.
+
+---
+
+## Related Docs
+
+- [extensions.md](./extensions.md)
+- [pipeline.md](./pipeline.md)
+- [container-lifecycle.md](./container-lifecycle.md)

package/examples/extensions/README.md

@@ -0,0 +1,12 @@
+# Extension Examples
+
+Real-world Mercury extensions. Copy any of these into `.mercury/extensions/` to use.
+
+| Extension | What it does | Features used |
+|-----------|-------------|---------------|
+| **charts** | Chart generation via `charts-cli` | cli, skill, permission |
+| **pdf** | PDF processing (OCR, form filling, conversion) | cli, skill, permission |
+| **gws** | Google Workspace (Drive/Gmail/Calendar/etc.) | cli, skill, permission (admin-only default) |
+| **pinchtab** | Browser automation via Playwright | cli, skill, permission, `before_container` hook (env + system prompt) |
+| **napkin** | Obsidian vault management + KB distillation | cli, skill, permission, `workspace_init` hook, `before_container` hook, job, config, widget, store |
+

package/examples/extensions/charts/index.ts

@@ -0,0 +1,13 @@
+export default function (mercury: {
+  cli(opts: { name: string; install: string }): void;
+  permission(opts: { defaultRoles: string[] }): void;
+  skill(relativePath: string): void;
+}) {
+  mercury.cli({
+    name: "charts",
+    install: "npm install -g charts-cli",
+  });
+
+  mercury.permission({ defaultRoles: ["admin", "member"] });
+  mercury.skill("./skill");
+}

package/examples/extensions/charts/skill/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: charts
+description: Generate SVG/PNG charts (bar, line, pie, scatter, radar, heatmap, funnel, gauge, sankey, etc.) from ECharts JSON configs
+---
+
+# Charts CLI
+
+Generate charts from the command line using ECharts. No browser needed.
+
+## Usage
+
+### List available chart types
+
+```bash
+charts schema --list
+```
+
+### Get schema for a chart type
+
+```bash
+charts schema bar
+charts schema pie
+charts schema xAxis
+```
+
+### Render a chart
+
+```bash
+# Pipe JSON config
+cat option.json | charts render -o outbox/chart.png
+
+# Or render from file
+charts render --config option.json -o outbox/chart.png
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Output path (`.svg` or `.png`) |
+| `-W, --width <n>` | Width in pixels (default: 800) |
+| `-H, --height <n>` | Height in pixels (default: 400) |
+| `--theme <name>` | `dark`, `vintage`, or path to JSON |
+| `--format <type>` | `svg` or `png` (auto-detected from extension) |
+
+### Supported chart types
+
+bar, line, pie, scatter, radar, funnel, gauge, treemap, boxplot, heatmap, candlestick, sankey
+
+## Visual style rules
+
+Always apply these defaults unless the user asks for something else.
+
+### Global defaults
+
+- `backgroundColor: "#ffffff"`
+- Title: centered, top 14, fontSize 16, fontWeight bold, color `#111827`
+- Grid: `{ left: 60, right: 32, top: 60, bottom: 48 }`
+- Color palette: `#4f46e5`, `#0d9488`, `#d97706`, `#dc2626`, `#7c3aed`, `#0891b2`
+
+### Axis styling
+
+- xAxis: hide ticks, axis line `#d1d5db`, label color `#4b5563`, fontSize 13
+- yAxis: hide line + ticks, label color `#9ca3af`, dashed split lines `#e5e7eb`
+
+### Bar
+
+- `barWidth: "50%"`
+- Rounded top corners: `borderRadius: [5,5,0,0]`
+- Labels on top
+
+### Line
+
+- `smooth: true`
+- `symbol: "circle"`, `symbolSize: 7`, line width 3
+- Single-series line charts should usually use light area fill
+
+### Pie / donut
+
+- No axes
+- Use white segment borders
+- Prefer `-W 800 -H 500`
+
+### Scatter
+
+- Both axes `type: "value"`
+- `symbolSize: 8`, opacity `0.7`
+
+### Radar / Funnel / Gauge / Heatmap / Sankey / Treemap / Boxplot / Candlestick
+
+Use the same conventions as documented by `charts schema` and keep styling clean and modern.
+
+## Workflow
+
+1. Use `charts schema <type>` to inspect the config shape
+2. Build the ECharts JSON option
+3. Render to a file in `outbox/`
+4. Reply briefly describing the chart so Mercury sends the file back to the user

package/examples/extensions/gws/README.md

@@ -0,0 +1,52 @@
+# gws Extension (Google Workspace CLI)
+
+Admin-gated Mercury extension for Google Workspace APIs via [`@googleworkspace/cli`](https://github.com/googleworkspace/cli).
+
+## What this example shows
+
+- `mercury.cli()` to install `gws`
+- `mercury.permission()` with admin-only default access
+- `mercury.skill()` so the agent knows how to use `gws`
+
+## Install
+
+Copy into your Mercury project:
+
+```bash
+mkdir -p .mercury/extensions/gws
+cp -R examples/extensions/gws/* .mercury/extensions/gws/
+```
+
+Then restart Mercury (or reinstall service).
+
+## Auth setup (host machine)
+
+1. Install and authenticate `gws` on the host:
+
+```bash
+npm i -g @googleworkspace/cli
+gws auth login
+```
+
+2. Export credentials once:
+
+```bash
+gws auth export --unmasked > .mercury/global/gws-credentials.json
+```
+
+3. Add to `.env`:
+
+```bash
+MERCURY_GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/home/mercury/.pi/agent/gws-credentials.json
+```
+
+(You can also use `MERCURY_GOOGLE_WORKSPACE_CLI_TOKEN`, but it expires quickly.)
+
+## Verify
+
+```bash
+mercury chat --space main --caller "<admin-caller-id>" \
+  "run exactly: gws drive files list --params '{\"pageSize\": 3}'"
+```
+
+A non-admin caller should be blocked by RBAC.

package/examples/extensions/gws/index.ts

@@ -0,0 +1,106 @@
+type ConnectionCategory =
+  | "email"
+  | "drive"
+  | "calendar"
+  | "finance"
+  | "messaging"
+  | "docs"
+  | "workspace"
+  | "other";
+
+type ConnectionAuthType =
+  | "oauth2"
+  | "apikey"
+  | "app-password"
+  | "credentials-file"
+  | "custom";
+
+type MercuryExt = {
+  cli(opts: { name: string; install: string }): void;
+  permission(opts: { defaultRoles: string[] }): void;
+  env(def: { from: string; as?: string }): void;
+  skill(relativePath: string): void;
+  connection(def: {
+    displayName: string;
+    iconUrl?: string;
+    category: ConnectionCategory;
+    authType: ConnectionAuthType;
+    credentialEnvVar?: string;
+    scopes?: string[];
+  }): void;
+  on(
+    event: "before_container",
+    handler: (
+      event: { spaceId: string; callerId: string },
+      ctx: {
+        db: { getExtState(e: string, k: string): string | null };
+        hasCallerPermission(
+          spaceId: string,
+          callerId: string,
+          permission: string,
+        ): boolean;
+      },
+    ) => Promise<{ env?: Record<string, string> } | undefined>,
+  ): void;
+};
+
+import manifest from "../../../resources/connection-env-vars.json";
+
+const gwsEnv = manifest.gws;
+
+/** Path where credentials are materialized inside the inner container's own /tmp. */
+const CREDENTIALS_FILE = "/tmp/gws-credentials.json";
+
+export default function (mercury: MercuryExt) {
+  mercury.cli({
+    name: "gws",
+    install: "npm install -g @googleworkspace/cli",
+  });
+
+  mercury.permission({ defaultRoles: ["admin"] });
+
+  mercury.env({ from: gwsEnv.env.credentials });
+  mercury.env({ from: gwsEnv.env.legacyCredentialsFile });
+
+  mercury.connection({
+    displayName: "Google Workspace",
+    category: "workspace",
+    authType: "oauth2",
+    credentialEnvVar: gwsEnv.credentialEnvVar,
+    scopes: [
+      "https://www.googleapis.com/auth/gmail.modify",
+      "https://www.googleapis.com/auth/drive",
+      "https://www.googleapis.com/auth/calendar",
+      "https://www.googleapis.com/auth/documents",
+      "https://www.googleapis.com/auth/spreadsheets",
+      "https://www.googleapis.com/auth/userinfo.email",
+    ],
+  });
+
+  // Inner containers don't share the outer container's volume — they mount host
+  // filesystem paths. So we can't write a credentials file from this hook and
+  // have the inner container see it. Instead, pass the target path via env var
+  // and let the skill materialize the file from GWS_CREDENTIALS_JSON at runtime.
+  mercury.on("before_container", async () => {
+    const raw = process.env[gwsEnv.env.credentials];
+    if (!raw) return undefined;
+
+    try {
+      JSON.parse(raw);
+    } catch {
+      console.error(
+        `[gws.before_container] ${gwsEnv.env.credentials} is not valid JSON — skipping`,
+      );
+      return undefined;
+    }
+
+    return {
+      env: {
+        GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: CREDENTIALS_FILE,
+        GWS_CREDENTIALS_JSON: raw,
+      },
+    };
+  });
+
+  mercury.skill("./skill");
+}

package/examples/extensions/gws/skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: gws
+description: Access Gmail, Google Drive, Google Calendar, Docs, and Sheets via the gws CLI. Use for email (read, send, triage inbox, reply, forward), calendar (today's agenda, add or reschedule events, meeting prep), Drive (list, find, organize files), and Docs/Sheets (read, summarize, append). Triggers on any Google Workspace or Gmail request.
+allowed-tools: Bash
+---
+
+# Google Workspace (gws)
+
+Use the `gws` CLI via Bash for all Google Workspace operations.
+
+## Presentation rules — always enforce
+
+**Never paste raw gws output into a reply.** Translate every result into plain language before responding.
+
+| Raw output field | What to show instead |
+|---|---|
+| `name` or `summary` | The display name only |
+| `mimeType: application/vnd.google-apps.document` | "Google Doc" |
+| `mimeType: application/vnd.google-apps.spreadsheet` | "spreadsheet" |
+| `mimeType: application/vnd.google-apps.folder` | "folder" |
+| `mimeType: application/pdf` | "PDF" |
+| Any `id` field | Never shown; use internally only for follow-up commands |
+| JSON objects or arrays | Summarise in prose |
+| Email `labelIds`, `threadId`, `messageId` | Never shown |
+
+## Credentials setup (run once per session before any gws command)
+
+`GWS_CREDENTIALS_JSON` contains the credentials as a JSON string. Materialize it to the path gws expects, then verify auth:
+
+```bash
+[ -n "$GWS_CREDENTIALS_JSON" ] && echo "$GWS_CREDENTIALS_JSON" > "${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-/tmp/gws-credentials.json}" && export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-/tmp/gws-credentials.json}"
+gws auth status
+```
+
+If `auth_method` is not `none`, credentials are ready. Skip this step on subsequent calls in the same session (the file persists in /tmp for the container lifetime).
+
+## Dispatch table
+
+Match the user's intent to the right category and read the reference file before acting:
+
+| User intent | Category | Reference file |
+|---|---|---|
+| email, inbox, gmail, send message, unread, triage | Gmail | `references/gmail.md` |
+| drive, files, folder, upload, download, share | Drive | `references/drive.md` |
+| calendar, agenda, event, meeting, schedule | Calendar | `references/calendar.md` |
+| doc, document, write, append, summarise | Docs | `references/docs.md` |
+| sheet, spreadsheet, row, data | Sheets | `references/sheets.md` |
+
+**Always read the reference file for the matched category before running a command.**
+
+## Fallback
+
+If no helper covers the case, use the raw API:
+```bash
+gws <service> --help             # list available subcommands
+```
+Still translate the output before replying.

package/examples/extensions/gws/skill/references/calendar.md

@@ -0,0 +1,101 @@
+# Calendar Reference
+
+Use `gws calendar` for all calendar operations.
+
+## Today's agenda
+
+```bash
+gws calendar +agenda --today
+```
+
+## This week's agenda
+
+```bash
+gws calendar +agenda --week
+```
+
+## Next N days
+
+```bash
+gws calendar +agenda --days 3
+```
+
+## Filter to a specific calendar
+
+```bash
+gws calendar +agenda --today --calendar 'Work'
+gws calendar +agenda --week --calendar 'Personal'
+```
+
+## Timezone override
+
+```bash
+gws calendar +agenda --today --timezone America/New_York
+```
+
+## Create an event
+
+```bash
+gws calendar +insert \
+  --summary 'Team Standup' \
+  --start '2026-04-24T09:00:00-05:00' \
+  --end '2026-04-24T09:30:00-05:00'
+
+# With location and attendees
+gws calendar +insert \
+  --summary 'Project Review' \
+  --start '2026-04-24T14:00:00-05:00' \
+  --end '2026-04-24T15:00:00-05:00' \
+  --location 'Conference Room A' \
+  --attendee alice@example.com \
+  --attendee bob@example.com
+
+# With Google Meet link
+gws calendar +insert \
+  --summary 'Remote Sync' \
+  --start '2026-04-24T10:00:00-05:00' \
+  --end '2026-04-24T10:30:00-05:00' \
+  --meet
+```
+
+Use RFC3339 format for times (e.g. `2026-04-24T09:00:00+03:00`). Always confirm date, time, and timezone with the user before creating.
+
+## Reschedule an event
+
+Get the event ID from `+agenda` output (store internally — never show to user):
+
+```bash
+# Get event ID
+gws calendar events list --params '{"calendarId":"primary","q":"Team Standup","maxResults":5}'
+
+# Update start/end times (replace timezone with the user's local timezone)
+gws calendar events update \
+  --params '{"calendarId":"primary","eventId":"<EVENT_ID>"}' \
+  --json '{"start":{"dateTime":"2026-04-25T09:00:00-05:00","timeZone":"America/New_York"},"end":{"dateTime":"2026-04-25T09:30:00-05:00","timeZone":"America/New_York"}}'
+```
+
+## Meeting prep (attendees, agenda for an upcoming event)
+
+```bash
+# Find the event
+gws calendar events list --params '{"calendarId":"primary","q":"<MEETING_NAME>","maxResults":3}'
+
+# Get full event details including attendees
+gws calendar events get --params '{"calendarId":"primary","eventId":"<EVENT_ID>"}'
+```
+
+Present: title, date/time, location (if any), attendee names — never show email addresses or event IDs unless the user asks.
+
+## Raw API fallback
+
+```bash
+gws calendar events list --params '{"calendarId":"primary","timeMin":"<ISO_DATE>","maxResults":10}'
+gws calendar --help   # list all subcommands
+```
+
+## Output format rules
+
+- Agenda: "9:00 AM — Team Standup (30 min)" or "All day — Public Holiday"
+- Event created: "Added 'Team Standup' to your calendar for Friday April 24 at 9:00 AM"
+- Reschedule confirmation: "Moved 'Team Standup' to Saturday April 25 at 9:00 AM"
+- Never show event IDs, calendar IDs, or raw dateTime strings