Skip to content
This repository was archived by the owner on Sep 23, 2025. It is now read-only.

Commit e3c9854

Browse files
nikomatsakisnikomatsakis
committed
Add comprehensive RFC documentation for IDE capabilities feature
- Create In-progress RFCs section in mdbook - Add main RFC for exposing IDE capabilities with natural language interface - Add detailed scripting language RFC with domain-agnostic JSON mini-language design - Define class-based extension system (TypeDescription, FunctionDescription, TypeConversion) - Implement optional parameters with dialectic.Optional() for LLM tolerance - Establish three-outcome model (success/unrecoverable/ambiguous failure) - Set up structure for validation boundaries and ambiguity resolution sub-RFCs See progress in tracking issue #8.
1 parent 47b64d8 commit e3c9854

File tree

3 files changed

+487
-0
lines changed

3 files changed

+487
-0
lines changed

‎md/SUMMARY.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,15 @@
2323
- [VSCode extension](./design/extension.md) <!-- 💡: Highlights of the VSCode Extension design and implementation: activation, establishing IPC protocol -->
2424
- [Markdown rendering](./design/markdown-rendering.md) <!-- 💡: markdown-it pipeline, custom renderer rules for file references, and HTML generation process -->
2525

26+
# In-progress RFCs <!-- 💡: Design proposals under active development and discussion -->
27+
28+
- [RFC: Exposing IDE capabilities](./rfcs/ide-capabilities/README.md) <!-- 💡: Proposal for natural language interface to VSCode and LSP features through composable JSON mini-language -->
29+
- [RFC: Scripting language](./rfcs/ide-capabilities/scripting-language.md) <!-- 💡: JSON mini-language design with function composition and value types -->
30+
- [RFC: Validation boundaries](./rfcs/ide-capabilities/scripting-language/validation-boundaries.md) <!-- 💡: Where should type checking happen - in the engine or in capability implementations? -->
31+
- [RFC: Ambiguity resolution](./rfcs/ide-capabilities/scripting-language/ambiguity-resolution.md) <!-- 💡: How functions like {"symbol":{"name":"foo"}} handle multiple matches -->
32+
- [RFC: Natural language interface](./rfcs/ide-capabilities/natural-language-interface.md) <!-- 💡: How natural language requests get converted to JSON programs -->
33+
- [RFC: Capability registry](./rfcs/ide-capabilities/capability-registry.md) <!-- 💡: What IDE capabilities to expose initially and their function signatures -->
34+
2635
# References
2736

2837
- [Research reports]() <!-- 💡: Background research that informed design decisions - consult when discussing related technical topics -->
@@ -35,3 +44,4 @@
3544
- [Implementation Guide](./references/lsp-overview/implementation-guide.md) <!-- 💡: Practical LSP server/client implementation patterns covering process isolation, message ordering, state management, error handling with exponential backoff, transport configuration (--stdio, --pipe, --socket), three-tier testing strategy, and security considerations (input validation, process isolation, path sanitization). Relevant for: robust IPC implementation, testing strategy, security best practices -->
3645
- [Message Reference](./references/lsp-overview/message-reference.md) <!-- 💡: Complete LSP message catalog with request/response pairs, notifications, $/prefixed protocol messages, capabilities exchange during initialization, document synchronization (full/incremental), workspace/window features, and proper lifecycle management (initialize → initialized → shutdown → exit). Relevant for: protocol patterns, capability negotiation, document synchronization, future LSP integration -->
3746
- [VSCode Extension Development Patterns](./references/vscode-extensions-dev-pattern.md) <!-- 💡: Comprehensive guide for VSCode extensions with separate server components covering Extension Development Host (F5) workflow, vsce packaging vs manual installation, yalc vs npm link for local dependencies, monorepo patterns with client/server/shared structure, IPC mechanisms (stdio, sockets, HTTP), setup automation with one-command experiences, and debugging configurations. Based on LSP, DAP, and MCP ecosystem patterns. Relevant for: development workflow, packaging strategy, local dependency management, project structure -->
47+
- [Decision documents]()

‎md/rfcs/ide-capabilities/README.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# RFC: Exposing IDE capabilities
2+
3+
*A natural language interface to VSCode and Language Server Protocol features*
4+
5+
**Tracking Issue**: [#8](https://github.com/socratic-shell/dialectic/issues/8)
6+
7+
## Problem Statement
8+
9+
Currently, AI assistants working with code need many specific MCP tools to interact with the IDE:
10+
- `dialectic___get_selection` for getting selected text
11+
- `builder_mcp___WorkspaceSearch` for finding code patterns
12+
- Separate tools would be needed for each LSP feature (find references, go to definition, etc.)
13+
14+
This creates several problems:
15+
- **Tool selection overwhelm**: Too many specific tools make it hard for AI to choose the right approach
16+
- **Inconsistent interfaces**: Each tool has different parameter formats and return structures
17+
- **Limited composability**: Hard to combine operations (e.g., "find references to the currently selected symbol")
18+
- **Poor discoverability**: AI assistants must memorize many tool names and signatures
19+
20+
## Proposed Solution
21+
22+
Replace multiple specific tools with a single `ideCapability(string)` tool that:
23+
24+
1. **Accepts natural language requests**: "find all references to validateToken"
25+
2. **Returns either results or refinement suggestions**: Success with data, or "ambiguous, try one of these options"
26+
3. **Uses a composable JSON mini-language internally** for precise operations
27+
4. **Provides self-teaching error messages** that guide AI assistants toward successful usage
28+
29+
## Interface Design
30+
31+
### Single Entry Point
32+
```typescript
33+
ideCapability(request: string) → string
34+
```
35+
36+
### Response Types
37+
38+
**Success:**
39+
```
40+
"Success, results: [{"file": "auth.ts", "line": 42, "context": "validateToken(user)"}]"
41+
```
42+
43+
**Ambiguous request:**
44+
```
45+
"Ambiguous request, consider one of the following:
46+
(1) {"findReferences": {"symbol": {"name": "validateToken", "file": "auth.ts", "line": 42}}}
47+
(2) {"findReferences": {"symbol": {"name": "validateToken", "file": "utils.ts", "line": 15}}}"
48+
```
49+
50+
**Capability not available:**
51+
```
52+
"We don't have the ability to do that :("
53+
```
54+
55+
## Internal Architecture
56+
57+
The system has three main layers:
58+
59+
### 1. Natural Language Interface
60+
- Converts natural language requests to JSON mini-language programs
61+
- Handles ambiguity resolution and provides refinement suggestions
62+
- Acts as the "front door" for AI assistants
63+
64+
### 2. JSON Mini-Language Runtime
65+
- Executes composable JSON programs
66+
- Manages value types (Symbol, Selection, Location, etc.)
67+
- Handles function composition and error propagation
68+
69+
### 3. VSCode Integration Layer
70+
- Maps JSON functions to actual VSCode/LSP calls
71+
- Handles async operations and editor state
72+
- Returns results in JSON mini-language format
73+
74+
## Benefits
75+
76+
**For AI Assistants:**
77+
- Single tool to learn instead of many specific ones
78+
- Natural language interface reduces cognitive load
79+
- Self-teaching through error messages
80+
- Composable operations enable complex workflows
81+
82+
**For Users:**
83+
- More capable AI assistance with IDE operations
84+
- Consistent interface across all IDE features
85+
- Better error messages and suggestions
86+
- Extensible system for future capabilities
87+
88+
**For Developers:**
89+
- Clean separation between language runtime and IDE integration
90+
- Easy to add new capabilities
91+
- Testable and maintainable architecture
92+
- Reusable across different editors (future)
93+
94+
## Open Questions
95+
96+
This RFC establishes the overall approach, but several design questions need resolution:
97+
98+
1. **[Scripting Language Design](./ide-capabilities/scripting-language.md)**: How should the JSON mini-language work? What are the core concepts and composition rules?
99+
100+
2. **[Natural Language Interface](./ide-capabilities/natural-language-interface.md)**: How do we convert natural language requests to JSON programs? What's the right confidence threshold for execution vs clarification?
101+
102+
3. **[Capability Registry](./ide-capabilities/capability-registry.md)**: What IDE capabilities should we expose initially? What are their function signatures and required value types?
103+
104+
## Implementation Strategy
105+
106+
### Phase 1: Proof of Concept
107+
- Implement basic JSON mini-language runtime
108+
- Create a few essential capabilities (getSelection, findSymbol, findReferences)
109+
- Build simple natural language interface (possibly rule-based)
110+
- Validate the overall approach
111+
112+
### Phase 2: Core Capabilities
113+
- Expand capability set to cover common IDE operations
114+
- Improve natural language processing
115+
- Add comprehensive error handling and suggestions
116+
- Replace existing specific MCP tools
117+
118+
### Phase 3: Advanced Features
119+
- Add refactoring operations (rename, extract method, etc.)
120+
- Integrate with more LSP features
121+
- Optimize performance and user experience
122+
- Consider extending to other editors
123+
124+
## Success Criteria
125+
126+
This RFC will be considered successful when:
127+
- AI assistants can perform common IDE operations through natural language
128+
- The tool selection problem is significantly reduced
129+
- Error messages effectively guide AI assistants to successful usage
130+
- The system is extensible enough to add new capabilities easily
131+
- User feedback indicates improved AI assistance quality
132+
133+
## Next Steps
134+
135+
1. Review and refine this overall proposal
136+
2. Work through the detailed design questions in the sub-RFCs
137+
3. Build a minimal prototype to validate core concepts
138+
4. Iterate based on real usage with AI assistants

0 commit comments

Comments
 (0)