Implement Jupyter kernel for Zed Agent Client Protocol (ACP)

.gitignore

@@ -1,21 +1,47 @@
-# Generated by Cargo
-# will have compiled files and executables
-debug
-target
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.manifest
+*.spec
 
-# These are backup files generated by rustfmt
-**/*.rs.bk
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
 
-# MSVC Windows builds of rustc generate these, which store debugging information
-*.pdb
+# Jupyter
+.ipynb_checkpoints
+*.ipynb
 
-# Generated by cargo mutants
-# Contains mutation testing data
-**/mutants.out*/
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
 
-# RustRover
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+# OS
+.DS_Store
+Thumbs.db

ARCHITECTURE.md

@@ -0,0 +1,215 @@
+# Architecture
+
+This document describes the architecture of the Agent Client Kernel.
+
+## Overview
+
+The Agent Client Kernel is a Jupyter kernel that implements a client for the Agent Client Protocol (ACP). It allows users to interact with AI coding agents directly from Jupyter notebooks, using notebook cells as a chat interface.
+
+## Components
+
+### 1. Kernel (`agent_client_kernel/kernel.py`)
+
+The `AgentClientKernel` class extends `ipykernel.kernelbase.Kernel` and provides:
+
+- **Kernel Interface**: Implements the Jupyter kernel protocol for executing code
+- **Process Management**: Starts and manages ACP agent processes
+- **JSON-RPC Communication**: Sends and receives JSON-RPC messages via stdin/stdout
+- **Response Handling**: Queues and processes agent responses
+- **Output Display**: Sends agent output to the notebook
+
+Key methods:
+- `start_agent(agent_command)`: Launches the agent process
+- `send_to_agent(message)`: Sends JSON-RPC messages to the agent
+- `do_execute(code, ...)`: Main execution method called by Jupyter
+- `_read_agent_output()`: Background thread for reading agent responses
+
+### 2. Installation (`agent_client_kernel/install.py`)
+
+Provides functionality to install the kernel specification into Jupyter:
+
+- Uses `jupyter_client.kernelspec.KernelSpecManager`
+- Supports user-level and system-level installation
+- Command-line interface for easy installation
+
+### 3. Kernel Specification (`agent_client_kernel/kernelspec/kernel.json`)
+
+Defines the kernel metadata for Jupyter:
+
+```json
+{
+  "argv": ["python", "-m", "agent_client_kernel", "-f", "{connection_file}"],
+  "display_name": "Agent Client Protocol",
+  "language": "agent-chat"
+}
+```
+
+## Communication Flow
+
+### Starting an Agent
+
+```
+User Cell: !start-agent python agent.py
+    ↓
+Kernel.do_execute()
+    ↓
+Kernel.start_agent()
+    ↓
+subprocess.Popen() → Agent Process
+    ↓
+Start reader thread (_read_agent_output)
+    ↓
+Output: "Agent started successfully."
+```
+
+### Sending a Chat Message
+
+```
+User Cell: "Hello, agent!"
+    ↓
+Kernel.do_execute()
+    ↓
+Create JSON-RPC request:
+{
+  "jsonrpc": "2.0",
+  "id": N,
+  "method": "chat/send",
+  "params": {"message": "Hello, agent!"}
+}
+    ↓
+Kernel.send_to_agent()
+    ↓
+Write to agent.stdin
+    ↓
+Reader thread reads from agent.stdout
+    ↓
+Response queued in response_queue
+    ↓
+Parse JSON-RPC response
+    ↓
+Display in notebook output
+```
+
+## JSON-RPC Protocol
+
+The kernel communicates with agents using JSON-RPC 2.0 over stdin/stdout:
+
+### Request Format
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "chat/send",
+  "params": {
+    "message": "User's chat message"
+  }
+}
+```
+
+### Response Format
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "text": "Agent's response text"
+  }
+}
+```
+
+### Error Format
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32601,
+    "message": "Method not found"
+  }
+}
+```
+
+## Threading Model
+
+The kernel uses a multi-threaded approach:
+
+1. **Main Thread**: Handles Jupyter kernel protocol and executes user code
+2. **Reader Thread**: Continuously reads output from the agent's stdout
+3. **Queue**: Thread-safe queue for passing responses between threads
+
+```
+┌─────────────────────┐
+│  Jupyter Notebook   │
+└──────────┬──────────┘
+           │ Kernel Protocol
+           ↓
+┌─────────────────────┐
+│   Main Thread       │
+│  (Kernel.do_execute)│
+├─────────────────────┤
+│  • Parse user input │
+│  • Send to agent    │
+│  • Format output    │
+└──────────┬──────────┘
+           │
+           ↓
+    ┌─────────────┐
+    │   Queue     │
+    └─────┬───────┘
+          ↑
+          │
+┌─────────┴─────────┐
+│  Reader Thread    │
+│(_read_agent_output)│
+├───────────────────┤
+│  • Read stdout    │
+│  • Queue responses│
+└─────────┬─────────┘
+          │
+          ↓
+    ┌─────────────┐
+    │Agent Process│
+    │  (stdin/out)│
+    └─────────────┘
+```
+
+## Special Commands
+
+The kernel recognizes special commands prefixed with `!`:
+
+- `!start-agent <command> [args...]`: Start an agent process
+- `!stop-agent`: Terminate the current agent process
+
+These commands are intercepted in `do_execute()` before being sent to the agent.
+
+## Extension Points
+
+The kernel can be extended to support:
+
+1. **Additional ACP Methods**: Add new method handlers in `send_to_agent()`
+2. **Rich Output**: Support for images, HTML, and other MIME types
+3. **Tool Integration**: Handle tool requests from agents
+4. **File System Operations**: Support for file read/write notifications
+5. **Multiple Agents**: Manage multiple concurrent agent connections
+
+## Security Considerations
+
+1. **Process Isolation**: Agents run as separate processes
+2. **User-Initiated**: Agents must be explicitly started by users
+3. **Input Validation**: JSON-RPC messages are validated before sending
+4. **Error Handling**: Exceptions are caught and displayed as errors
+5. **Resource Limits**: Subprocess timeouts prevent hanging
+
+## Future Enhancements
+
+Potential improvements:
+
+- [ ] Support for agent initialization handshake
+- [ ] Better error messages and diagnostics
+- [ ] Progress indicators for long-running operations
+- [ ] Interrupt handling for canceling operations
+- [ ] Session persistence across notebook restarts
+- [ ] Multi-agent support (chat with multiple agents)
+- [ ] Rich media support (images, diagrams, etc.)
+- [ ] Tool approval UI for file system operations
+- [ ] Agent discovery and auto-configuration

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-10-19
+
+### Added
+- Initial release of Agent Client Kernel
+- Jupyter kernel implementation for Agent Client Protocol (ACP)
+- JSON-RPC communication over stdin/stdout with agents
+- Support for starting and stopping agent processes from notebook cells
+- Chat interface for interacting with agents
+- Special commands: `!start-agent` and `!stop-agent`
+- Mock agent for testing and development
+- Basic test suite
+- Documentation and examples
+- Setup script and kernel installation tool
+
+### Features
+- Execute user messages as chat input to the agent
+- Display agent responses in notebook output
+- Thread-safe message queuing for agent responses
+- Error handling and user feedback
+- Support for any ACP-compliant agent
+
+### Documentation
+- README with installation and usage instructions
+- ARCHITECTURE document explaining the design
+- CONTRIBUTING guide for developers
+- Example usage documentation
+- Inline code documentation
+
+[0.1.0]: https://github.com/jimwhite/agent-client-kernel/releases/tag/v0.1.0