|
| 1 | +# Agent Extensions |
| 2 | + |
| 3 | +Agent extensions are proxy components that enrich the agent's capabilities. The VS Code extension allows users to configure which extensions are active, their order, and to add custom extensions. |
| 4 | + |
| 5 | +## Built-in Extensions |
| 6 | + |
| 7 | +| ID | Name | Description | |
| 8 | +|----|------|-------------| |
| 9 | +| `sparkle` | Sparkle | AI collaboration identity and embodiment | |
| 10 | +| `ferris` | Ferris | Rust development tools (crate sources, rust researcher) | |
| 11 | +| `cargo` | Cargo | Cargo build and run tools | |
| 12 | + |
| 13 | +## Extension Sources |
| 14 | + |
| 15 | +Extensions can come from three sources: |
| 16 | + |
| 17 | +- **built-in**: Bundled with Symposium (sparkle, ferris, cargo) |
| 18 | +- **registry**: Installed from the shared agent registry |
| 19 | +- **custom**: User-defined via executable, npx, pipx, or URL |
| 20 | + |
| 21 | +## Configuration |
| 22 | + |
| 23 | +Extensions are configured via the `symposium.extensions` VS Code setting: |
| 24 | + |
| 25 | +```json |
| 26 | +"symposium.extensions": [ |
| 27 | + { "id": "sparkle", "_enabled": true, "_source": "built-in" }, |
| 28 | + { "id": "ferris", "_enabled": true, "_source": "built-in" }, |
| 29 | + { "id": "cargo", "_enabled": true, "_source": "built-in" } |
| 30 | +] |
| 31 | +``` |
| 32 | + |
| 33 | +Custom extensions include their distribution: |
| 34 | + |
| 35 | +```json |
| 36 | +{ |
| 37 | + "id": "my-extension", |
| 38 | + "_enabled": true, |
| 39 | + "_source": "custom", |
| 40 | + "name": "My Extension", |
| 41 | + "distribution": { |
| 42 | + "npx": { "package": "@myorg/my-extension" } |
| 43 | + } |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +**Order matters** - extensions are applied in the order listed. The first extension in the list is closest to the editor, and the last is closest to the agent. |
| 48 | + |
| 49 | +**Default behavior** - when no setting exists, all built-in extensions are enabled. If the user returns to the default configuration, the key is removed from settings.json entirely. |
| 50 | + |
| 51 | +## Settings UI |
| 52 | + |
| 53 | +The Settings panel includes an Extensions section where users can: |
| 54 | + |
| 55 | +- **Enable/disable** extensions via checkbox |
| 56 | +- **Reorder** extensions by dragging the handle |
| 57 | +- **Delete** extensions from the list |
| 58 | +- **Add** extensions via the "+ Add extension" link, which opens a QuickPick dialog |
| 59 | + |
| 60 | +### Add Extension Dialog |
| 61 | + |
| 62 | +The QuickPick dialog shows three sections: |
| 63 | + |
| 64 | +1. **Built-in** - sparkle, ferris, cargo (greyed out if already added) |
| 65 | +2. **From Registry** - extensions from the shared registry with `type: "extension"` |
| 66 | +3. **Add Custom Extension**: |
| 67 | + - From executable on your system (local command/path) |
| 68 | + - From npx package |
| 69 | + - From pipx package |
| 70 | + - From URL to extension.json (GitHub URLs auto-converted to raw) |
| 71 | + |
| 72 | +## CLI Interface |
| 73 | + |
| 74 | +The VS Code extension passes extension configuration to `symposium-acp-agent` via `--proxy` arguments: |
| 75 | + |
| 76 | +```bash |
| 77 | +symposium-acp-agent --proxy sparkle --proxy ferris --proxy cargo -- npx @zed-industries/claude-code-acp |
| 78 | +``` |
| 79 | + |
| 80 | +Only enabled extensions are passed, in their configured order. |
| 81 | + |
| 82 | +## Registry Format |
| 83 | + |
| 84 | +The shared registry includes both agents and extensions: |
| 85 | + |
| 86 | +```json |
| 87 | +{ |
| 88 | + "date": "2026-01-07", |
| 89 | + "agents": [...], |
| 90 | + "extensions": [ |
| 91 | + { |
| 92 | + "id": "some-extension", |
| 93 | + "name": "Some Extension", |
| 94 | + "version": "1.0.0", |
| 95 | + "description": "Does something useful", |
| 96 | + "distribution": { |
| 97 | + "npx": { "package": "@example/some-extension" } |
| 98 | + } |
| 99 | + } |
| 100 | + ] |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +## Architecture |
| 105 | + |
| 106 | +``` |
| 107 | +┌─────────────────────────────────────────────────┐ |
| 108 | +│ VS Code Extension │ |
| 109 | +│ - Reads symposium.extensions setting │ |
| 110 | +│ - Fetches registry extensions │ |
| 111 | +│ - Renders UI in Settings panel │ |
| 112 | +│ - Shows QuickPick for adding extensions │ |
| 113 | +│ - Builds --proxy args for agent spawn │ |
| 114 | +└─────────────────┬───────────────────────────────┘ |
| 115 | + │ |
| 116 | +┌─────────────────▼───────────────────────────────┐ |
| 117 | +│ symposium-acp-agent │ |
| 118 | +│ - Parses --proxy arguments │ |
| 119 | +│ - Validates proxy names │ |
| 120 | +│ - Builds proxy chain in specified order │ |
| 121 | +└─────────────────┬───────────────────────────────┘ |
| 122 | + │ |
| 123 | +┌─────────────────▼───────────────────────────────┐ |
| 124 | +│ symposium-acp-proxy (Symposium struct) │ |
| 125 | +│ - from_proxy_names() creates config │ |
| 126 | +│ - build_proxies() instantiates components │ |
| 127 | +│ - Conductor orchestrates the chain │ |
| 128 | +└─────────────────────────────────────────────────┘ |
| 129 | +``` |
| 130 | + |
| 131 | +## Future Work |
| 132 | + |
| 133 | +- **Per-extension configuration**: Add sub-options for extensions (e.g., which Ferris tools to enable) |
| 134 | +- **Extension updates**: Check for and apply updates to registry-sourced extensions |
0 commit comments