@agent-relay/acp-bridge 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# @agent-relay/acp-bridge
+
+ACP (Agent Client Protocol) bridge for Agent Relay. Exposes relay agents to ACP-compatible editors like [Zed](https://zed.dev).
+
+## What is ACP?
+
+The [Agent Client Protocol (ACP)](https://agentclientprotocol.com) is an open standard that enables AI agents to integrate with code editors. It's like LSP (Language Server Protocol) but for AI coding agents.
+
+## What does this bridge do?
+
+This bridge allows ACP-compatible editors to communicate with Agent Relay agents:
+
+```
+┌─────────────────┐     ACP (stdio)    ┌─────────────────┐
+│   Zed Editor    │ ◄────────────────► │  relay-acp      │
+│   (or other)    │   JSON-RPC 2.0     │  (this bridge)  │
+└─────────────────┘                    └────────┬────────┘
+                                                │
+                                       Relay Protocol
+                                                │
+                                       ┌────────▼────────┐
+                                       │  Relay Daemon   │
+                                       └────────┬────────┘
+                                                │
+                        ┌───────────────────────┼───────────────────────┐
+                        │                       │                       │
+                ┌───────▼───────┐       ┌───────▼───────┐       ┌───────▼───────┐
+                │   Agent 1     │       │   Agent 2     │       │   Agent N     │
+                │ (Claude Code) │       │ (Codex CLI)   │       │ (any CLI)     │
+                └───────────────┘       └───────────────┘       └───────────────┘
+```
+
+## Installation
+
+```bash
+npm install @agent-relay/acp-bridge
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Start the bridge
+relay-acp --name my-agent --debug
+
+# With custom socket path
+relay-acp --socket /tmp/relay/my-workspace/sockets/daemon.sock
+```
+
+### With Zed Editor
+
+1. Start the relay daemon:
+   ```bash
+   relay-daemon start
+   ```
+
+2. Start some relay agents:
+   ```bash
+   relay spawn Worker1 claude "Help with coding tasks"
+   ```
+
+3. Configure Zed to use the bridge. Add to your Zed settings:
+   ```json
+   {
+     "agent": {
+       "custom_agents": [
+         {
+            "name": "Agent Relay",
+            "command": "relay-acp",
+            "args": ["--name", "zed-bridge"]
+         }
+       ]
+     }
+   }
+   ```
+
+4. Open the Agent Panel in Zed (`Cmd+?` on macOS) and select "Agent Relay"
+
+Or let the CLI configure Zed for you (writes `agent_servers` with the correct socket path):
+
+```bash
+agent-relay up --zed
+```
+
+This adds an entry similar to:
+
+```json
+{
+  "agent_servers": {
+    "Agent Relay": {
+      "type": "custom",
+      "command": "relay-acp",
+      "args": ["--name", "zed-bridge", "--socket", "/path/to/project/.agent-relay/relay.sock"]
+    }
+  }
+}
+```
+
+### Programmatic Usage
+
+```typescript
+import { RelayACPAgent } from '@agent-relay/acp-bridge';
+
+const agent = new RelayACPAgent({
+  agentName: 'my-agent',
+  socketPath: '/tmp/relay-daemon.sock',
+  debug: true,
+  capabilities: {
+    supportsSessionLoading: false,
+    modes: [
+      { slug: 'default', name: 'Default', description: 'Standard mode' },
+      { slug: 'review', name: 'Code Review', description: 'Focus on code review' },
+    ],
+  },
+});
+
+await agent.start();
+```
+
+### Relay CLI commands from the Agent Panel
+
+The bridge intercepts basic `agent-relay` commands typed in the Zed Agent Panel, so you can manage agents without a shell:
+
+- `agent-relay spawn Worker claude "Review the current changes"`
+- `agent-relay release Worker`
+- `agent-relay agents` (list connected agents)
+
+Supported commands today: spawn/create-agent, release, agents/who. Others fall back to normal broadcast handling.
+The panel shows a help block on first message; type `agent-relay help` anytime to see it again.
+
+## How it Works
+
+1. **Initialization**: When an editor connects, the bridge advertises its capabilities
+2. **Session Creation**: Each conversation creates a new session
+3. **Prompt Handling**: User prompts are broadcast to all relay agents
+4. **Response Streaming**: Agent responses are streamed back to the editor
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `agentName` | string | `'relay-acp'` | Name used when connecting to relay daemon |
+| `socketPath` | string | auto | Path to relay daemon socket |
+| `debug` | boolean | `false` | Enable debug logging |
+| `capabilities` | object | - | ACP capabilities to advertise |
+
+Connections to the daemon go through `@agent-relay/sdk`, so socket discovery and reconnection match the rest of the Relay tooling. Provide `socketPath` to override detection when needed.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WORKSPACE_ID` | Used to determine default socket path |
+
+## ACP Compatibility
+
+This bridge implements ACP version `2025-03-26` and supports:
+
+- Session management (new sessions)
+- Prompt handling with streaming responses
+- Cancellation
+
+Not yet supported:
+- Session loading/resumption
+- Tool calls
+- File operations via ACP (use relay agents directly)
+
+## License
+
+Apache-2.0

package/dist/acp-agent.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ACP Agent Implementation
+ *
+ * Implements the ACP Agent interface to bridge relay agents to ACP clients.
+ */
+import * as acp from '@agentclientprotocol/sdk';
+import type { ACPBridgeConfig } from './types.js';
+/**
+ * ACP Agent that bridges to Agent Relay
+ */
+export declare class RelayACPAgent implements acp.Agent {
+    private readonly config;
+    private relayClient;
+    private connection;
+    private sessions;
+    private messageBuffer;
+    constructor(config: ACPBridgeConfig);
+    /**
+     * Start the ACP agent with stdio transport
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the agent
+     */
+    stop(): Promise<void>;
+    /**
+     * Initialize the agent connection
+     */
+    initialize(_params: acp.InitializeRequest): Promise<acp.InitializeResponse>;
+    /**
+     * Authenticate with the client (no auth required for relay)
+     */
+    authenticate(_params: acp.AuthenticateRequest): Promise<acp.AuthenticateResponse>;
+    /**
+     * Create a new session
+     */
+    newSession(_params: acp.NewSessionRequest): Promise<acp.NewSessionResponse>;
+    /**
+     * Load an existing session (not supported)
+     */
+    loadSession(_params: acp.LoadSessionRequest): Promise<acp.LoadSessionResponse>;
+    /**
+     * Set session mode (optional)
+     */
+    setSessionMode(_params: acp.SetSessionModeRequest): Promise<acp.SetSessionModeResponse | void>;
+    /**
+     * Handle a prompt from the client
+     */
+    prompt(params: acp.PromptRequest): Promise<acp.PromptResponse>;
+    /**
+     * Cancel the current operation
+     */
+    cancel(params: acp.CancelNotification): Promise<void>;
+    /**
+     * Parse @mentions from a message.
+     * Returns { targets: string[], message: string } where targets are agent names
+     * and message is the text with @mentions removed.
+     *
+     * Examples:
+     *   "@Worker hello" -> { targets: ["Worker"], message: "hello" }
+     *   "@Worker @Reviewer review this" -> { targets: ["Worker", "Reviewer"], message: "review this" }
+     *   "hello everyone" -> { targets: [], message: "hello everyone" }
+     */
+    private parseAtMentions;
+    /**
+     * Bridge a user prompt to relay agents and collect responses
+     */
+    private bridgeToRelay;
+    /**
+     * Handle incoming relay messages
+     */
+    private handleRelayMessage;
+    /**
+     * Handle system messages (crash notifications, etc.)
+     * These are displayed to all sessions regardless of processing state.
+     */
+    private handleSystemMessage;
+    /**
+     * Broadcast a message to all active sessions.
+     */
+    private broadcastToAllSessions;
+    /**
+     * Parse and handle agent-relay CLI-style commands coming from the editor.
+     */
+    private tryHandleCliCommand;
+    private handleSpawnCommand;
+    private handleReleaseCommand;
+    private handleListAgentsCommand;
+    private handleStatusCommand;
+    private sendTextUpdate;
+    private parseCliArgs;
+    private getHelpText;
+    /**
+     * Extract text content from ACP content blocks
+     */
+    private extractTextContent;
+    /**
+     * Convert Node.js readable stream to Web ReadableStream
+     */
+    private nodeToWebReadable;
+    /**
+     * Convert Node.js writable stream to Web WritableStream
+     */
+    private nodeToWebWritable;
+    /**
+     * Sleep utility
+     */
+    private sleep;
+    /**
+     * Debug logging
+     */
+    private debug;
+}
+//# sourceMappingURL=acp-agent.d.ts.map

package/dist/acp-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-agent.d.ts","sourceRoot":"","sources":["../src/acp-agent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,GAAG,MAAM,0BAA0B,CAAC;AAEhD,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,aAAc,YAAW,GAAG,CAAC,KAAK;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,UAAU,CAAwC;IAC1D,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,aAAa,CAAqC;gBAE9C,MAAM,EAAE,eAAe;IAInC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkF5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IASjF;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,mBAAmB,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IAIvF;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAoBjF;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IAIpF;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,qBAAqB,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAKpG;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAiDpE;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3D;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;YACW,aAAa;IAwJ3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;OAEG;YACW,mBAAmB;YAsCnB,kBAAkB;YAoClB,oBAAoB;YA4BpB,uBAAuB;YAqBvB,mBAAmB;YA8BnB,cAAc;IAe5B,OAAO,CAAC,YAAY;IAkDpB,OAAO,CAAC,WAAW;IAmBnB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,OAAO,CAAC,KAAK;CAKd"}