feat(server): add ACP support

examples/acp-server/README.md

@@ -0,0 +1,118 @@
+# DeepAgents ACP Server Example
+
+This example demonstrates how to run DeepAgents as an ACP (Agent Client Protocol) server for integration with IDEs like Zed, JetBrains, and other ACP-compatible clients.
+
+## Prerequisites
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+2. Build the packages:
+   ```bash
+   pnpm build
+   ```
+
+## Running the Server
+
+### Direct Execution
+
+```bash
+npx tsx examples/acp-server/server.ts
+```
+
+### With Debug Logging
+
+```bash
+DEBUG=true npx tsx examples/acp-server/server.ts
+```
+
+### With Custom Workspace
+
+```bash
+WORKSPACE_ROOT=/path/to/your/project npx tsx examples/acp-server/server.ts
+```
+
+## IDE Configuration
+
+### Zed
+
+Add to your Zed settings (`~/.config/zed/settings.json` on Linux, `~/Library/Application Support/Zed/settings.json` on macOS):
+
+```json
+{
+  "agent": {
+    "profiles": {
+      "deepagents": {
+        "name": "DeepAgents",
+        "command": "npx",
+        "args": ["tsx", "examples/acp-server/server.ts"],
+        "cwd": "/path/to/deepagentsjs",
+        "env": {
+          "WORKSPACE_ROOT": "${workspaceFolder}"
+        }
+      }
+    }
+  }
+}
+```
+
+### JetBrains IDEs
+
+JetBrains ACP support is coming soon. Check the [ACP documentation](https://agentclientprotocol.com/get-started/clients) for updates.
+
+## Features
+
+The DeepAgents ACP server provides:
+
+- **Full Filesystem Access**: Read, write, edit files in the workspace
+- **Code Search**: Grep and glob patterns for finding code
+- **Task Management**: Todo list tracking for complex tasks
+- **Subagent Delegation**: Spawn specialized subagents for specific tasks
+- **Session Persistence**: Maintain conversation context across interactions
+- **Multiple Modes**: Switch between Agent, Plan, and Ask modes
+
+## Customization
+
+Edit `server.ts` to customize:
+
+- Model selection
+- System prompt
+- Skills and memory paths
+- Custom tools
+- Middleware configuration
+
+## Protocol Details
+
+The server implements the [Agent Client Protocol](https://agentclientprotocol.com):
+
+- Communication: JSON-RPC 2.0 over stdio
+- Session management with persistent state
+- Streaming responses via session updates
+- Tool call tracking and status updates
+- Plan/todo list synchronization
+
+## Troubleshooting
+
+### Server not starting
+
+- Check that all dependencies are installed: `pnpm install`
+- Ensure packages are built: `pnpm build`
+- Check for TypeScript errors: `pnpm typecheck`
+
+### Debug logging
+
+Enable debug mode to see detailed logs:
+
+```bash
+DEBUG=true npx tsx examples/acp-server/server.ts
+```
+
+Logs are written to stderr to avoid interfering with the ACP protocol on stdout.
+
+### Connection issues
+
+- Verify the command path in your IDE configuration
+- Check that the workspace path exists
+- Ensure the LLM API key is set (e.g., `ANTHROPIC_API_KEY`)

examples/acp-server/server.ts

@@ -0,0 +1,94 @@
+/**
+ * DeepAgents ACP Server Example
+ *
+ * This example demonstrates how to start a DeepAgents ACP server
+ * that can be used with IDEs like Zed, JetBrains, and other ACP clients.
+ *
+ * Usage:
+ *   npx tsx examples/acp-server/server.ts
+ *
+ * Then configure your IDE to use this agent. For Zed, add to settings.json:
+ *
+ * {
+ *   "agent": {
+ *     "profiles": {
+ *       "deepagents": {
+ *         "name": "DeepAgents",
+ *         "command": "npx",
+ *         "args": ["tsx", "examples/acp-server/server.ts"],
+ *         "cwd": "/path/to/deepagentsjs"
+ *       }
+ *     }
+ *   }
+ * }
+ */
+
+import { DeepAgentsServer } from "deepagents-acp";
+import { FilesystemBackend } from "deepagents";
+import path from "node:path";
+
+// Get workspace root from environment or use current directory
+const workspaceRoot = process.env.WORKSPACE_ROOT ?? process.cwd();
+
+// Create the ACP server with a coding assistant agent
+const server = new DeepAgentsServer({
+  // Agent configuration
+  agents: [
+    {
+      name: "coding-assistant",
+      description:
+        "AI coding assistant powered by DeepAgents with full filesystem access, " +
+        "code search, task management, and subagent delegation capabilities.",
+
+      // Use Claude Sonnet as the default model
+      model: "claude-sonnet-4-5-20250929",
+
+      // Use filesystem backend rooted at the workspace
+      backend: new FilesystemBackend({
+        rootDir: workspaceRoot,
+      }),
+
+      // Load skills from the workspace if available
+      skills: [
+        path.join(workspaceRoot, ".deepagents", "skills"),
+        path.join(workspaceRoot, "skills"),
+      ],
+
+      // Load memory/context from AGENTS.md files
+      memory: [
+        path.join(workspaceRoot, ".deepagents", "AGENTS.md"),
+        path.join(workspaceRoot, "AGENTS.md"),
+      ],
+
+      // Custom system prompt (optional)
+      systemPrompt: `You are an AI coding assistant integrated with an IDE through the Agent Client Protocol (ACP).
+
+You have access to the workspace at: ${workspaceRoot}
+
+When working on tasks:
+1. First understand the codebase structure
+2. Make a plan before making changes
+3. Test your changes when possible
+4. Explain your reasoning
+
+Always be helpful, concise, and focused on the user's coding tasks.`,
+    },
+  ],
+
+  // Server configuration
+  serverName: "deepagents-acp-server",
+  serverVersion: "0.0.1",
+  workspaceRoot,
+
+  // Enable debug logging (set to true to see debug output on stderr)
+  debug: process.env.DEBUG === "true",
+});
+
+// Start the server
+console.error("[deepagents] Starting ACP server...");
+console.error(`[deepagents] Workspace: ${workspaceRoot}`);
+
+server.start().catch((error) => {
+  console.error("[deepagents] Server error:", error);
+  process.exit(1);
+});

examples/package.json

@@ -7,6 +7,7 @@
   },
   "dependencies": {
     "deepagents": "workspace:*",
+    "deepagents-acp": "workspace:*",
     "@langchain/anthropic": "^1.3.7",
     "@langchain/core": "^1.1.12",
     "@langchain/langgraph-checkpoint": "^1.0.0",
@@ -24,4 +25,4 @@
     "dotenv": "^17.2.3",
     "typescript": "^5.9.2"
   }
-}
+}