Add WebSocket server module design document #43
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Comprehensive plan for adding codey-server, a WebSocket server that exposes the full agent interaction for automation and external client integration. Key design decisions: - Workspace restructure: codey (core), codey-tools, codey-cli, codey-server - Server-side tool execution with approval promotion over WebSocket - Reuse existing types with Serialize derives where possible - ToolEventMessage as serializable mirror of ToolEvent (channels can't serialize) - Session event loop mirrors app.rs structure
Adds Serialize/Deserialize derives to core types to enable WebSocket and other wire protocol integrations: - AgentStep, Usage, RequestMode in agent.rs - ToolCall, ToolDecision in exec.rs - Effect in pipeline.rs - Edit, ToolPreview in ide/mod.rs Adds ToolEventMessage enum as a serializable version of ToolEvent. The internal ToolEvent contains oneshot::Sender channels for the approval flow which cannot be serialized. ToolEventMessage mirrors the structure but omits these channels, with a to_message() conversion. Exports new types from lib.rs public API: - ToolEventMessage, ToolDecision, Effect
Major refactor to support WebSocket server as a separate binary: Workspace structure: - crates/codey: Core library + CLI binary (with cli feature) - crates/codey-server: WebSocket server binary Changes: - Move src/ to crates/codey/src/ - Create workspace Cargo.toml with shared dependencies - Add codey crate with cli feature for optional TUI/tool deps - Add codey-server crate with WebSocket protocol and session management codey-server implements: - protocol.rs: ClientMessage/ServerMessage JSON protocol - session.rs: Per-connection agent session with event loop - server.rs: WebSocket listener and connection handling - main.rs: CLI entry point with configuration The server currently streams AgentStep events over WebSocket and promotes tool approvals to the client. Full ToolExecutor integration is planned for follow-up. Makefile updated with workspace-aware targets: - make build: Build all workspace members - make build-cli: Build just the CLI - make build-server: Build just the server - make run / make run-server: Run respective binaries
- Export CLI-gated types (Config, ToolFilters, ToolEvent, ToolExecutor) from lib.rs - Load config from ~/.config/codey/config.toml in server main.rs - Compile ToolFilters from config for auto-approve/deny behavior - Session uses Arc<ToolFilters> shared across connections - ToolExecutor handles server-side tool execution - Tools matching filters auto-approved/denied, others bubble to WebSocket - Add toml dependency to codey-server for config parsing
- clients/python/codey_client/schemas.py: Pydantic models for all protocol types - clients/python/codey_client/client.py: Async WebSocket client with high-level API - clients/python/examples/basic_chat.py: Interactive chat example - clients/INTEGRATION.md: Protocol documentation for implementing clients The Python client provides: - Full type safety with Pydantic models matching Rust protocol types - Async context manager for easy connection lifecycle - High-level chat() and stream_text() methods - Configurable tool approval (auto-approve, callback, or default deny)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Comprehensive plan for adding codey-server, a WebSocket server that exposes
the full agent interaction for automation and external client integration.
Key design decisions: