mercury-agent 0.5.0 → 0.5.2

package/docs/subagents.md

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

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

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

@@ -1,13 +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");
-}
+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");
+}