|
4 | 4 |
|
5 | 5 | ## Architecture Summary |
6 | 6 |
|
7 | | -Dialectic consists of two main components that communicate via Unix socket IPC: |
| 7 | +Dialectic consists of three main components that communicate via a [daemon message bus](./protocol.md): |
8 | 8 |
|
9 | | -1. **VSCode Extension** - Provides the review panel UI, handles file navigation, and acts as IPC server |
10 | | -2. **MCP Server** - Acts as a bridge between AI assistants and the VSCode extension via IPC client |
11 | | - |
12 | | -The AI assistant generates review content as structured markdown and uses the MCP server's `present-review` tool to display it in the VSCode interface through bidirectional IPC communication. |
| 9 | +1. **VSCode Extension** - Provides the review panel UI, handles file navigation, and manages [terminal registry](./terminal-registry.md) |
| 10 | +2. **Daemon Message Bus** - Routes messages between MCP servers and VSCode extensions across multiple windows; there is one per IDE process |
| 11 | +3. **MCP Server** - Acts as a bridge between AI assistants and the VSCode extension via daemon communication |
13 | 12 |
|
14 | 13 | ## Communication Architecture |
15 | 14 |
|
| 15 | +```mermaid |
| 16 | +graph TD |
| 17 | + AI[AI Assistant] |
| 18 | + |
| 19 | + subgraph IDE[" IDE Process (e.g., VSCode) "] |
| 20 | + subgraph Window[" Window "] |
| 21 | + Ext[Extension] |
| 22 | + Term1[Terminal 1] |
| 23 | + Server1[MCP Server 1] |
| 24 | + Term2[Terminal 2] |
| 25 | + Server2[MCP Server 2] |
| 26 | + end |
| 27 | + subgraph Window2[" Other window "] |
| 28 | + DotDotDot[...] |
| 29 | + end |
| 30 | + end |
| 31 | +
|
| 32 | + Daemon[Daemon Message Bus] |
| 33 | +
|
| 34 | + AI --> Server1 |
| 35 | + AI --> Server2 |
| 36 | + |
| 37 | + Ext <--> Daemon |
| 38 | + Server1 <--> Daemon |
| 39 | + Server2 <--> Daemon |
| 40 | + DotDotDot <--> Daemon |
| 41 | +
|
| 42 | + %% Terminal connections within windows |
| 43 | + Term1 -.-> Server1 |
| 44 | + Term2 -.-> Server2 |
| 45 | +
|
| 46 | + %% Styling |
| 47 | + classDef daemon fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000 |
| 48 | + classDef extension fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000 |
| 49 | + classDef server fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px,color:#000 |
| 50 | + classDef terminal fill:#fff3e0,stroke:#e65100,stroke-width:1px,color:#000 |
| 51 | + classDef window fill:#fafafa,stroke:#424242,stroke-width:1px,stroke-dasharray: 5 5 |
| 52 | + classDef ai fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000 |
| 53 | +
|
| 54 | + class Daemon daemon |
| 55 | + class Ext extension |
| 56 | + class Server1,Server2 server |
| 57 | + class Term1,Term2 terminal |
| 58 | + class Window window |
| 59 | + class AI ai |
16 | 60 | ``` |
17 | | -AI Assistant → MCP Tool → Unix Socket → VSCode Extension → Review Panel → User |
18 | | - ↑ ↓ |
19 | | - └─────────── Response ←─────── IPC Response ←─────── User Interaction ←┘ |
20 | | -``` |
21 | | - |
22 | | -### IPC Communication |
23 | | - |
24 | | -The MCP server and VSCode extension communicate via Unix socket IPC using environment variable discovery. The VSCode extension creates a socket server and sets `DIALECTIC_IPC_PATH` for the MCP server to find and connect to. |
25 | | - |
26 | | -For detailed information about how the IPC connection is established and what messages are exchanged, see the [Communication Protocol](./protocol.md) chapter. |
27 | | - |
28 | | -**Key Design Decisions:** |
29 | | -- **Unix Socket/Named Pipe**: Secure, efficient local IPC following VSCode extension patterns |
30 | | -- **Newline-Delimited JSON**: Simple, debuggable message format with reliable boundaries |
31 | | -- **Promise-Based Tracking**: Supports concurrent operations with unique message IDs |
32 | | -- **Environment Variable Discovery**: Automatic connection without configuration complexity |
33 | | - |
34 | | -## Design Philosophy |
35 | | - |
36 | | -Dialectic embodies the collaborative patterns from the [socratic shell project](https://socratic-shell.github.io/socratic-shell/). The goal is to enable genuine pair programming partnerships with AI assistants, not create another tool for giving commands to a servant. |
37 | 61 |
|
38 | | -**Collaborative Review** - Instead of accepting hunks blindly or micro-managing every change, we work together to understand what was built and why, just like reviewing a colleague's PR. |
| 62 | +## Example flow |
39 | 63 |
|
40 | | -**Thoughtful Interaction** - The review format encourages narrative explanation and reasoning, not just "what changed" but "how it works" and "why these decisions were made." |
| 64 | +Here is a high-level overview of how the flow works when the user requests a review: |
41 | 65 |
|
42 | | -**Preserved Context** - Reviews become part of your git history, retaining the collaborative thinking process for future reference and team members. |
| 66 | +* User requests a walkthrough. LLM invokes the "present review" [MCP tool](./mcp-tool-interface.md). |
| 67 | +* The MCP server sends a message to the [daemon bus](./protocol.md). The daemon bus broadcasts the message to all connected clients. The message includes the PID of the shell in which the MCP server is running. |
| 68 | +* The extension receives the message from the daemon bus. It identifies that the shell PID belongs to one of the terminals in its window, so it processes the request and creates a webview. |
43 | 69 |
|
44 | | -**Iterative Refinement** - Nothing is right the first time. The review process expects and supports ongoing dialogue, suggestions, and improvements rather than assuming the initial implementation is final. |
45 | | - |
46 | | -## Implementation Status |
47 | | - |
48 | | -**✅ MVP Complete** - All core features implemented and tested: |
49 | | -- **Review Display**: Tree-based markdown rendering in VSCode sidebar |
50 | | -- **Code Navigation**: Clickable `file:line` references that jump to code locations |
51 | | -- **Content Export**: Copy button to export review content for commit messages |
52 | | -- **IPC Communication**: Full bidirectional communication between AI and extension |
53 | | - |
54 | | -**Current State**: Ready for end-to-end testing with real AI assistants in VSCode environments. |
55 | | - |
56 | | -**Next Phase**: Package extension for distribution and create installation documentation. |
57 | | - |
58 | | -## Technical Stack |
59 | | - |
60 | | -- **MCP Server**: TypeScript/Node.js with comprehensive unit testing (49/49 tests passing) |
61 | | -- **VSCode Extension**: TypeScript with VSCode Extension API |
62 | | -- **Communication**: Unix domain sockets (macOS/Linux) and named pipes (Windows) |
63 | | -- **Protocol**: JSON messages with unique ID tracking and timeout protection |
64 | | -- **Testing**: Jest for unit tests with test mode for IPC-free testing |
| 70 | +Read more details in the [communication protocol](./protocol.md) section. |
65 | 71 |
|
66 | 72 | ## Component Responsibilities |
67 | 73 |
|
68 | 74 | ### MCP Server (`server/`) |
69 | 75 | - Exposes `present-review` tool to AI assistants |
70 | | -- Validates parameters and handles errors gracefully |
71 | | -- Manages IPC client connection to VSCode extension |
72 | | -- Supports concurrent operations with Promise-based tracking |
73 | | -- See `server/src/index.ts` for main server implementation |
| 76 | +- Discovers terminal shell PID through process tree walking |
| 77 | +- Announces presence to daemon via Marco-Polo protocol |
| 78 | +- Handles graceful disconnection and cleanup |
| 79 | +- See `server/src/main.rs` for main server implementation |
| 80 | + |
| 81 | +### Daemon Message Bus (`server/src/daemon.rs`) |
| 82 | +- Routes messages between MCP servers and VSCode extensions |
| 83 | +- Manages client connections and handles disconnections |
| 84 | +- Broadcasts messages to appropriate VSCode windows |
| 85 | +- Provides process lifecycle management |
| 86 | +- Runs as background process tied to VSCode instance |
74 | 87 |
|
75 | 88 | ### VSCode Extension (`extension/`) |
76 | | -- Creates IPC server and sets environment variables |
77 | | -- Provides tree-based review display in sidebar |
78 | | -- Handles clickable navigation to code locations |
79 | | -- Manages copy-to-clipboard functionality |
80 | | -- See `extension/src/extension.ts` for activation logic |
81 | | - |
82 | | -### Shared Types (`server/src/types.ts`) |
83 | | -- Defines communication protocol interfaces |
84 | | -- Ensures type safety across IPC boundary |
85 | | -- Prevents protocol mismatches during development |
| 89 | +- Creates daemon client connection and manages terminal registry |
| 90 | +- Provides tree-based review display in sidebar with navigation |
| 91 | +- Implements Ask Socratic Shell integration with intelligent terminal routing |
| 92 | +- Manages terminal picker UI with memory and quick access options |
| 93 | +- Handles workspace state persistence for user preferences |
| 94 | +- See `extension/src/extension.ts` for activation and daemon client logic |
| 95 | + |
| 96 | +### Terminal Registry (`extension/src/extension.ts`) |
| 97 | +- Tracks active terminals with MCP servers using shell PIDs |
| 98 | +- Updates registry based on Marco-Polo discovery messages |
| 99 | +- Provides API for Ask Socratic Shell to query AI-enabled terminals |
| 100 | +- Maintains workspace-specific preferences and memory |
86 | 101 |
|
87 | 102 | ## Key Implementation Files |
88 | 103 |
|
89 | | -- `server/src/index.ts` - Main MCP server with tool handlers |
90 | | -- `server/src/ipc.ts` - IPC client communication logic |
91 | | -- `server/src/validation.ts` - Parameter validation and error handling |
92 | | -- `extension/src/extension.ts` - VSCode extension activation and IPC server |
| 104 | +- `server/src/main.rs` - Main MCP server with tool handlers and process discovery |
| 105 | +- `server/src/daemon.rs` - Daemon message bus with client management |
| 106 | +- `server/src/pid_discovery.rs` - Process tree walking for terminal shell PID detection |
| 107 | +- `extension/src/extension.ts` - VSCode extension with daemon client and terminal registry |
93 | 108 | - `extension/src/reviewProvider.ts` - Tree view implementation and markdown parsing |
94 | | -- `server/src/__tests__/` - Comprehensive unit test suite |
| 109 | +- `server/tests/` - Integration tests with real daemon and terminal scenarios |
95 | 110 |
|
96 | | -For detailed implementation specifics, refer to the source code and inline comments marked with `💡` that explain non-obvious design decisions. |
| 111 | +For detailed implementation specifics, refer to the source code and inline comments that explain design decisions and architectural patterns. |
0 commit comments