mercury-agent 0.5.0 → 0.5.2

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

@@ -1,98 +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
+---
+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

@@ -1,52 +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.
+# 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/skill/SKILL.md

@@ -1,57 +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.
+---
+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

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