Merge pull request #99 from nikomatsakis/main

Simplify the setup

Author: nikomatsakis

Cargo.lock

@@ -3,7 +3,6 @@ members = [
     "setup",
     "md-rfd-preprocessor",
     "ci",
-    "src/symposium-acp-proxy",
     "src/symposium-acp-agent",
     "src/symposium-ferris",
     "src/symposium-math",

Cargo.toml

@@ -24,13 +24,14 @@
     - [Ferris](./using/ferris.md)
     - [Cargo](./using/cargo.md)
 
-# Contributing
+# Development guide
 
 - [How to contribute](./contribute.md)
 - [Overview](./design/implementation-overview.md)
 - [Common Issues](./design/common-issues.md)
 - [Distribution](./design/distribution.md)
 - [Components](./design/components.md)
+- [Act-as-Configured Mode](./design/act-as-configured.md)
 - [Rust Crate Sources](./design/rust-crate-sources.md)
 - [VSCode Extension](./design/vscode-extension/architecture.md)
     - [Message Protocol](./design/vscode-extension/message-protocol.md)

md/SUMMARY.md

@@ -0,0 +1,119 @@
+# Act-as-Configured Mode
+
+The `act-as-configured` subcommand simplifies editor integration by reading agent configuration from a file rather than requiring command-line arguments.
+
+## Motivation
+
+Without this mode, editor extensions must either:
+- Hardcode specific agent commands, requiring extension updates to add new agents
+- Expose complex configuration UI for specifying agent commands and proxy options
+
+With `act-as-configured`, the extension simply runs:
+
+```bash
+symposium-acp-agent act-as-configured
+```
+
+The agent reads its configuration from `~/.symposium/config.jsonc`, and if no configuration exists, runs an interactive setup wizard.
+
+## Configuration File
+
+**Location:** `~/.symposium/config.jsonc`
+
+The file uses JSONC (JSON with comments) format:
+
+```jsonc
+{
+  // Downstream agent command (parsed as shell words)
+  "agent": "npx -y @zed-industries/claude-code-acp",
+  
+  // Proxy extensions to enable
+  "proxies": [
+    { "name": "sparkle", "enabled": true },
+    { "name": "ferris", "enabled": true },
+    { "name": "cargo", "enabled": true }
+  ]
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agent` | string | Shell command to spawn the downstream agent. Parsed using shell word splitting. |
+| `proxies` | array | List of proxy extensions with `name` and `enabled` fields. |
+
+The `agent` string is parsed as shell words, so commands like `npx -y @zed-industries/claude-code-acp` work correctly.
+
+## Runtime Behavior
+
+```
+┌─────────────────────────────────────────┐
+│         act-as-configured               │
+└─────────────────┬───────────────────────┘
+                  │
+                  ▼
+        ┌─────────────────┐
+        │ Config exists?  │
+        └────────┬────────┘
+                 │
+         ┌───────┴───────┐
+         │               │
+         ▼               ▼
+   ┌──────────┐   ┌──────────────┐
+   │  Yes     │   │     No       │
+   └────┬─────┘   └──────┬───────┘
+        │                │
+        ▼                ▼
+   Load config     Run configuration
+   Run agent       agent (setup wizard)
+```
+
+When a configuration file exists, `act-as-configured` behaves equivalently to:
+
+```bash
+symposium-acp-agent act-as-agent \
+    --proxy sparkle --proxy ferris --proxy cargo \
+    -- npx -y @zed-industries/claude-code-acp
+```
+
+## Configuration Agent
+
+When no configuration file exists, Symposium runs a built-in configuration agent instead of a downstream AI agent. This agent:
+
+1. Presents a numbered list of known agents (Claude Code, Gemini, Codex, Kiro CLI)
+2. Waits for the user to type a number (1-N)
+3. Saves the configuration file with all proxies enabled
+4. Instructs the user to restart their editor
+
+The configuration agent is a simple state machine that expects numeric input. Invalid input causes the prompt to repeat.
+
+### Known Agents
+
+The configuration wizard offers these pre-configured agents:
+
+| Name | Command |
+|------|---------|
+| Claude Code | `npx -y @zed-industries/claude-code-acp` |
+| Gemini CLI | `npx -y -- @google/gemini-cli@latest --experimental-acp` |
+| Codex | `npx -y @zed-industries/codex-acp` |
+| Kiro CLI | `kiro-cli-chat acp` |
+
+Users can manually edit `~/.symposium/config.jsonc` to use other agents or modify proxy settings.
+
+## Implementation
+
+The implementation consists of:
+
+- **Config types:** `SymposiumUserConfig` and `ProxyEntry` structs in `src/symposium-acp-agent/src/config.rs`
+- **Config loading:** `load()` reads from `~/.symposium/config.jsonc`, `save()` writes it
+- **Configuration agent:** `ConfigurationAgent` implements the ACP `Component` trait
+- **CLI integration:** `ActAsConfigured` variant in the `Command` enum
+
+### Dependencies
+
+| Crate | Purpose |
+|-------|---------|
+| `serde_jsonc` | Parse JSON with comments |
+| `shell-words` | Parse agent command string into arguments |
+| `dirs` | Cross-platform home directory resolution |

md/artwork/logos/acp.png

@@ -4,35 +4,54 @@ Symposium uses a **conductor** to orchestrate a dynamic chain of component proxi
 
 ## Two Deployment Modes
 
-Symposium provides two binaries for different deployment scenarios:
+The `symposium-acp-agent` binary supports two deployment modes via subcommands:
 
-### Proxy Mode (`symposium-acp-proxy`)
+### Agent Mode (`act-as-agent`)
 
-Sits between an editor and an existing agent, enriching the connection:
+Acts as a complete agent that wraps a downstream agent:
 
 ```mermaid
 flowchart LR
-    Editor --> Proxy[symposium-acp-proxy] --> Agent
+    Editor --> Agent[symposium-acp-agent] --> DownstreamAgent[claude-code, etc.]
 ```
 
-Use this when the editor spawns agents separately and you want to insert Symposium's capabilities in between.
+Use this when you want a single binary that editors can spawn directly. This is ideal for Zed extensions and similar scenarios where the editor expects to spawn a single agent binary.
 
-### Agent Mode (`symposium-acp-agent`)
+Example:
+```bash
+symposium-acp-agent act-as-agent --proxy defaults -- npx -y @anthropic-ai/claude-code-acp
+```
 
-Acts as a complete agent that wraps a downstream agent:
+### Proxy Mode (`act-as-proxy`)
+
+Sits between an editor and an existing agent, enriching the connection:
 
 ```mermaid
 flowchart LR
-    Editor --> Agent[symposium-acp-agent] --> DownstreamAgent[claude-code, etc.]
+    Editor --> Proxy[symposium-acp-agent] --> Agent
 ```
 
-Use this when you want a single binary that editors can spawn directly. This is ideal for Zed extensions and similar scenarios where the editor expects to spawn a single agent binary.
+Use this when the editor spawns agents separately and you want to insert Symposium's capabilities in between.
 
 Example:
 ```bash
-symposium-acp-agent -- npx -y @zed-industries/claude-code-acp
+symposium-acp-agent act-as-proxy --proxy sparkle --proxy ferris
+```
+
+## Proxy Configuration
+
+Use `--proxy <name>` to specify which extensions to include. Order matters - proxies are chained in the order specified.
+
+Known proxies: `sparkle`, `ferris`, `cargo`
+
+The special value `defaults` expands to all known proxies:
+```bash
+--proxy defaults           # equivalent to: --proxy sparkle --proxy ferris --proxy cargo
+--proxy foo --proxy defaults --proxy bar  # foo, then all defaults, then bar
 ```
 
+If no `--proxy` flags are given, no proxies are included (pure passthrough).
+
 ## Internal Structure
 
 Both modes use a [conductor](https://symposium-dev.github.io/symposium-acp/) to orchestrate multiple component proxies:

md/artwork/logos/emacs.png

@@ -250,12 +250,10 @@ Each `rust_crate_query` call creates exactly one research session and expects ex
 
 ## Integration with Symposium
 
-The component is registered with the conductor in `symposium-acp-proxy/src/lib.rs`:
+The component is registered with the conductor in `symposium-acp-agent/src/symposium.rs`:
 
 ```rust
-components.push(sacp::DynComponent::new(
-    symposium_crate_sources_proxy::CrateSourcesProxy {},
-));
+proxies.push(DynComponent::new(symposium_ferris::FerrisComponent::new(ferris_config)));
 ```
 
 The component implements `Component::serve()` to: