mirror of
https://github.com/instructkr/claw-code.git
synced 2026-10-18 00:00:11 +08:00
cleanup: remove phase 1a documentation (owned by PR #3329)
This commit is contained in:
clawdbot committed
1 parent
e8c14616c6
commit
46eba21620
4 files changed
-1464
No files matched your search
@@ -1,287 +0,0 @@
|
||||
# Phase 1a Completion Report: GJC Tool Semantics - Line Range Selector
|
||||
|
||||
**Lane**: `lane/gjc-s21`
|
||||
**Issue**: #3323 [Slice 2.1]
|
||||
**Task**: Bring claw-code tools to GJC parity
|
||||
**Phase**: 1a (Read Tool Selector Parser)
|
||||
**Status**: ✅ COMPLETE
|
||||
|
||||
---
|
||||
|
||||
## SUMMARY
|
||||
|
||||
Successfully implemented the foundation for GJC-compatible line range selectors for the read tool. This is the first critical component of Batch 1, enabling the semantic upgrades needed to match GJC's powerful read tool.
|
||||
|
||||
**Deliverable**: Fully tested line range selector parser with support for all GJC selector syntaxes.
|
||||
|
||||
---
|
||||
|
||||
## COMPLETED DELIVERABLES
|
||||
|
||||
### 1. Line Range Selector Module ✅
|
||||
**File**: `rust/crates/runtime/src/line_range_selector.rs` (343 LOC)
|
||||
|
||||
#### Features Implemented
|
||||
- **Selector Parsing**: Full support for GJC selector syntax
|
||||
- `:L` - single line (e.g., `:50`)
|
||||
- `:L-L` - line range (e.g., `:50-200`)
|
||||
- `:L+N` - start+count (e.g., `:50+150`)
|
||||
- `:L,L-L,L+N` - multiple ranges with auto-merging (e.g., `:5-16,960-973`)
|
||||
- `:raw` - full verbatim output
|
||||
- `:conflicts` - git merge conflict extraction only
|
||||
|
||||
- **Type System**
|
||||
```rust
|
||||
pub enum LineRangeSelector {
|
||||
Raw,
|
||||
Conflicts,
|
||||
Lines(Vec<LineRange>),
|
||||
None,
|
||||
}
|
||||
```
|
||||
|
||||
- **Range Merging**: Automatic merging of overlapping/adjacent ranges
|
||||
- Input: `5-16,10-20` → Output: single range `5-20`
|
||||
- Input: `5-16,17-20` → Output: single range `5-20` (adjacent)
|
||||
|
||||
- **Error Handling**: Comprehensive error types
|
||||
- `ParseError::InvalidFormat` - malformed syntax
|
||||
- `ParseError::InvalidNumber` - non-numeric values
|
||||
- `ParseError::InvalidRange` - logical errors (start > end, zero lines)
|
||||
|
||||
#### Public API
|
||||
```rust
|
||||
// Main entry point for selector parsing
|
||||
pub fn parse_selector(selector: &str) -> Result<LineRangeSelector, ParseError>
|
||||
|
||||
// Structured types
|
||||
pub struct LineRange {
|
||||
pub start_line: usize, // 1-indexed
|
||||
pub end_line: usize, // 1-indexed
|
||||
}
|
||||
|
||||
impl LineRange {
|
||||
pub fn zero_indexed(&self) -> (usize, usize)
|
||||
pub fn len(&self) -> usize
|
||||
pub fn is_valid(&self) -> bool
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Comprehensive Test Suite ✅
|
||||
**Tests**: 13 passing tests in `line_range_selector.rs:tests` module
|
||||
|
||||
Coverage:
|
||||
- ✅ `test_parse_raw` - Special mode parsing
|
||||
- ✅ `test_parse_conflicts` - Conflict extraction mode
|
||||
- ✅ `test_parse_single_line` - Simple line selection
|
||||
- ✅ `test_parse_range_start_dash_end` - Dash syntax
|
||||
- ✅ `test_parse_range_start_plus_count` - Plus syntax
|
||||
- ✅ `test_parse_multiple_ranges` - Comma-separated ranges
|
||||
- ✅ `test_merge_overlapping_ranges` - Overlapping merge behavior
|
||||
- ✅ `test_merge_adjacent_ranges` - Adjacent range merge
|
||||
- ✅ `test_invalid_range_start_greater_than_end` - Error handling
|
||||
- ✅ `test_invalid_zero_line` - Error handling
|
||||
- ✅ `test_empty_selector` - Default behavior
|
||||
- ✅ `test_line_range_zero_indexed` - Index conversion
|
||||
- ✅ `test_line_range_len` - Range length calculation
|
||||
|
||||
**Build Status**: ✅ Cargo test passes, zero warnings
|
||||
|
||||
### 3. Module Integration ✅
|
||||
**File**: `rust/crates/runtime/src/lib.rs`
|
||||
|
||||
- Added public module export: `pub mod line_range_selector;`
|
||||
- Module is public and ready for use by tools layer
|
||||
|
||||
### 4. Documentation ✅
|
||||
- **Gap Matrix**: `docs/gjc-compat/gap-matrix.md` (799 LOC)
|
||||
- Comprehensive analysis of GJC vs claw-code tool gaps
|
||||
- Tool-by-tool specifications and semantics
|
||||
- Implementation complexity estimates
|
||||
|
||||
- **Tool Semantics Doc**: `docs/gjc-compat/tool-semantics-phase1.md` (337 LOC)
|
||||
- Detailed GJC tool specifications (read/edit/search/find)
|
||||
- Current claw-code gaps analysis
|
||||
- Batch implementation plan
|
||||
|
||||
- **Implementation Log**: `docs/gjc-compat/slice-2.1-implementation-log.md` (157 LOC)
|
||||
- Phase-by-phase progress tracking
|
||||
- PR planning and risk assessment
|
||||
- Testing strategy
|
||||
|
||||
---
|
||||
|
||||
## GIT HISTORY
|
||||
|
||||
```
|
||||
baa31c75 docs: add Slice 2.1 implementation tracking log
|
||||
6b8bdb2c feat: add GJC-compatible line range selector parser for read tool
|
||||
baa31c75 docs: add Slice 2.1 implementation tracking log
|
||||
1e55fb11 docs: add GJC tool semantics analysis for Batch 1
|
||||
7e6981fb docs: add GJC compatibility gap matrix
|
||||
```
|
||||
|
||||
**Branch**: Clean, linear history on `lane/gjc-s21` with descriptive commits.
|
||||
|
||||
---
|
||||
|
||||
## ARCHITECTURAL DESIGN
|
||||
|
||||
### Design Decisions
|
||||
|
||||
1. **Separate Module**: Selector logic isolated in dedicated module for testability
|
||||
2. **No External Dependencies**: Pure Rust, leverages only stdlib (zero new dependencies)
|
||||
3. **Zero-Index Conversion**: Internal use with automatic 1-indexed ↔ 0-indexed conversion
|
||||
4. **Range Merging**: Automatic to simplify downstream consumption
|
||||
5. **Enum-Based Output**: Type-safe selector representation vs raw strings
|
||||
|
||||
### Integration Points (Next Phase)
|
||||
|
||||
The parsed selector integrates with:
|
||||
- `ReadFileInput` - receives selector string, parses with `line_range_selector::parse_selector()`
|
||||
- `file_ops.rs:read_file_in_workspace()` - applies selected ranges to file content
|
||||
- Output formatter - generates truncation footer with recovery hints
|
||||
|
||||
### Dependencies
|
||||
|
||||
This module depends on:
|
||||
- `std::num::ParseIntError` (stdlib)
|
||||
- Nothing else (no external crates)
|
||||
|
||||
---
|
||||
|
||||
## NEXT PHASES
|
||||
|
||||
### Phase 1b: Tool Integration (🚧 Ready to Start)
|
||||
**Estimated LOC**: 600-800
|
||||
**Complexity**: Medium
|
||||
|
||||
Tasks:
|
||||
1. Extend `ReadFileInput` struct in `tools/lib.rs` to include selector field
|
||||
2. Update tool specification in `mvp_tool_specs()`
|
||||
3. Integrate selector parsing in `run_read_file()`
|
||||
4. Update `file_ops.rs:read_file_in_workspace()` to apply ranges
|
||||
5. Tests for tool-level integration
|
||||
|
||||
### Phase 1c: Truncation Footers & Metadata
|
||||
**Estimated LOC**: 300-400
|
||||
**Complexity**: Low-Medium
|
||||
|
||||
Tasks:
|
||||
1. Extend `TextFilePayload` to include `totalLines`, `totalBytes`
|
||||
2. Generate truncation footers with recovery hints
|
||||
3. Tests for footer formatting
|
||||
|
||||
### Phase 1d: Structural Summarization (Optional)
|
||||
**Estimated LOC**: 400-600
|
||||
**Complexity**: High
|
||||
|
||||
Tasks:
|
||||
1. Code language detection
|
||||
2. Brace pair collapsing to `..`
|
||||
3. Hash line anchor generation
|
||||
4. Tests for summarization logic
|
||||
|
||||
---
|
||||
|
||||
## TESTING & VERIFICATION
|
||||
|
||||
### Current Status
|
||||
- ✅ Selector parser: 13/13 tests passing
|
||||
- ✅ Compilation: Zero errors, zero warnings
|
||||
- ✅ Module exports: Correctly exposed in runtime lib.rs
|
||||
|
||||
### Testing Coverage
|
||||
- **Unit Tests**: Parsing, merging, edge cases (100% of parser logic)
|
||||
- **Integration Tests**: To be added in Phase 1b (tool layer)
|
||||
- **Parity Tests**: Manual comparison with GJC reference (Phase 1b+)
|
||||
|
||||
### Quality Metrics
|
||||
- **Code Coverage**: Parser fully covered by tests
|
||||
- **Error Handling**: All error paths tested
|
||||
- **Edge Cases**: Zero-lines, overlaps, adjacent ranges tested
|
||||
- **Performance**: Linear time complexity O(n) where n = range count
|
||||
|
||||
---
|
||||
|
||||
## DEPENDENCIES & COMPATIBILITY
|
||||
|
||||
### Rust Version
|
||||
- Edition 2021 (consistent with workspace)
|
||||
- No MSRV bump required
|
||||
- No new external dependencies added
|
||||
|
||||
### Workspace Impact
|
||||
- No changes to Cargo.toml
|
||||
- No new dependencies
|
||||
- Additive only (new module, no breaking changes)
|
||||
|
||||
### Backward Compatibility
|
||||
- Existing `ReadFileInput` unchanged (selector field is optional in Phase 1b)
|
||||
- Default behavior when selector absent: `LineRangeSelector::None`
|
||||
- No breaking changes to public APIs
|
||||
|
||||
---
|
||||
|
||||
## KNOWN LIMITATIONS & FUTURE WORK
|
||||
|
||||
### Current Scope
|
||||
- Parser only (not applied to file content yet)
|
||||
- No archive/SQLite support (separate Phase)
|
||||
- No structural summarization (optional)
|
||||
- No context line expansion (for selected ranges)
|
||||
|
||||
### Design Decisions for Future Reference
|
||||
- Ranges stored as 1-indexed for user-facing API consistency with GJC
|
||||
- Merging is automatic (no option to preserve overlaps)
|
||||
- Special modes (`:raw`, `:conflicts`) are mutually exclusive with line ranges
|
||||
|
||||
---
|
||||
|
||||
## HAND-OFF & CONTINUITY
|
||||
|
||||
### For Phase 1b Implementation
|
||||
1. **Context**: This module is ready to integrate
|
||||
2. **Entry Point**: `line_range_selector::parse_selector(&selector_string)?`
|
||||
3. **Type to Use**: `LineRangeSelector` enum
|
||||
4. **Tests**: Run `cargo test -p runtime line_range_selector` to verify
|
||||
|
||||
### Documentation
|
||||
- Tool semantics clearly specified in `tool-semantics-phase1.md`
|
||||
- GJC reference available at `/home/bellman/Workspace/gajae-code/packages/coding-agent/src/tools/read.ts`
|
||||
- Implementation tracking in `slice-2.1-implementation-log.md`
|
||||
|
||||
---
|
||||
|
||||
## METRICS & STATISTICS
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Code Lines (module) | 343 |
|
||||
| Test Lines | 150+ |
|
||||
| Test Count | 13 |
|
||||
| Test Pass Rate | 100% |
|
||||
| External Dependencies | 0 |
|
||||
| Compiler Warnings | 0 |
|
||||
| Coverage | ~100% of parser logic |
|
||||
| Documentation Pages | 3 |
|
||||
| Commits This Phase | 4 |
|
||||
| Branch Health | ✅ Clean, linear history |
|
||||
|
||||
---
|
||||
|
||||
## SIGN-OFF
|
||||
|
||||
**Phase 1a**: ✅ COMPLETE
|
||||
**Ready for Phase 1b**: ✅ YES
|
||||
**Blockers**: None
|
||||
**Risk Level**: Low (isolated module, comprehensive tests)
|
||||
|
||||
**Approved for Merge**: Ready for PR review when needed.
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Created**: 2026-10-13
|
||||
**Author**: Lane CC-GJC-S21
|
||||
**Status**: Final
|
||||
@@ -1,799 +0,0 @@
|
||||
# GJC Compatibility Gap Matrix
|
||||
|
||||
**Document Status**: Phase 1 Analysis (2026-10-13)
|
||||
**Scope**: SDK wire protocol, session lifecycle, tools, skills, settings, hooks, commands, and AGENTS.md rules
|
||||
**Target**: Rust fork-in-spirit of gajae-code (GJC) SDK-compatible and capability-compatible
|
||||
|
||||
---
|
||||
|
||||
## 1. EXECUTIVE SUMMARY
|
||||
|
||||
This matrix maps GJC capabilities (from gajae-code) against claw-code's current Rust implementation, identifying gaps and proposing crate/module ownership for each slice.
|
||||
|
||||
### Key Findings
|
||||
|
||||
| Area | Status | Priority |
|
||||
|------|--------|----------|
|
||||
| **SDK Wire Protocol** | Missing | P0 (Foundation) |
|
||||
| **Session Lifecycle** | Partial (no SDK) | P0 (Foundation) |
|
||||
| **Tool Catalog (55 tools)** | Partial (35/55) | P1 (Core) |
|
||||
| **Skill Discovery** | Partial (basic) | P1 (Core) |
|
||||
| **Settings & Config** | Partial | P2 (Enhancing) |
|
||||
| **Hooks & Plugins** | Existing | P3 (Polish) |
|
||||
| **AGENTS.md Rules** | Existing | P3 (Polish) |
|
||||
| **Slash Commands (120+)** | Partial (40/120+) | P2 (Core) |
|
||||
| **Subagent Delegation** | Existing | P2 (Core) |
|
||||
|
||||
---
|
||||
|
||||
## 2. SDK WIRE PROTOCOL
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/sdk/client/client.ts`, `sdk/host/session-runtime.ts`
|
||||
|
||||
GJC uses a **WebSocket-based JSON-RPC-like protocol** with:
|
||||
- **Transport**: WebSocket over TCP
|
||||
- **Frame Format**: JSON object with typed fields
|
||||
- **Correlation**: Request/response matched by `frame.id` (UUID)
|
||||
- **Operations**: 65+ operation types (Q1-Q32, C01-C06, reverse ops)
|
||||
- **Error Handling**: Typed `SdkErrorCode` with `uncertain_after_send` recovery
|
||||
- **Reconnect**: Exponential backoff with deadline management
|
||||
- **Request Timeout**: 10s default (`DEFAULT_SDK_REQUEST_TIMEOUT_MS`), per-request override
|
||||
- **Handshake**: `client.hello` with capabilities advertised; `server.hello` response
|
||||
|
||||
**Operations** (sample):
|
||||
- **Control**: `turn.create`, `turn.prompt`, `turn.steer`, `turn.abort_and_prompt`
|
||||
- **Queries**: `turn.list`, `turn.get_one`, `turn.message_list`, `skill.source`, `artifact.content`
|
||||
- **Reverse**: `ask.answer`, `tool.dispatch`, `tool.fetch_capability`
|
||||
|
||||
**Event Schema**:
|
||||
```json
|
||||
{
|
||||
"id": "uuid-string",
|
||||
"operation": "turn.create",
|
||||
"input": { ... },
|
||||
"connectionId": "optional",
|
||||
"settings": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Missing entirely. claw-code has no SDK wire protocol or external session API.
|
||||
|
||||
**Files**: None
|
||||
**Lines**: 0
|
||||
|
||||
**Reality**:
|
||||
- claw-code operates as a local CLI only (stdin/stdout/stderr).
|
||||
- Sessions are file-based (`.claw/sessions/`).
|
||||
- No remote access or external SDK clients.
|
||||
- No WebSocket transport.
|
||||
- No frame correlation or reconnect logic.
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| WebSocket Transport | 1500 LOC | — | 100% | High |
|
||||
| Frame Correlation | 800 LOC | — | 100% | Medium |
|
||||
| Operation Registry | 400 LOC | 0 | 100% | Medium |
|
||||
| Error Handling & Recovery | 600 LOC | — | 100% | High |
|
||||
| Handshake & Negotiation | 200 LOC | — | 100% | Low |
|
||||
| **Total** | **3,500 LOC** | **0** | **3,500 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `sdk` (new)
|
||||
|
||||
**Module Structure**:
|
||||
```
|
||||
rust/crates/sdk/
|
||||
├── Cargo.toml
|
||||
└── src/
|
||||
├── lib.rs (exports + top-level API)
|
||||
├── client/
|
||||
│ ├── mod.rs (SdkClient, WebSocket transport)
|
||||
│ ├── correlation.rs (frame ID tracking, reconnect)
|
||||
│ └── errors.rs (SdkErrorCode, recovery)
|
||||
├── protocol/
|
||||
│ ├── mod.rs (Operation registry)
|
||||
│ ├── operations.rs (operation definitions)
|
||||
│ └── schema.rs (JSON schemas, frame validation)
|
||||
├── session/
|
||||
│ ├── mod.rs (session lifecycle over SDK)
|
||||
│ ├── router.rs (session routing, durable state)
|
||||
│ └── reconciliation.rs (uncertain outcome recovery)
|
||||
└── tests/
|
||||
├── mod.rs
|
||||
└── fixtures/ (mock server scenarios)
|
||||
```
|
||||
|
||||
**Size Estimate**: 4,500 LOC (Rust + test fixtures)
|
||||
|
||||
**Dependencies**:
|
||||
- `tokio` (async I/O, WebSocket)
|
||||
- `tungstenite` (WebSocket protocol)
|
||||
- `serde_json` (frame serialization)
|
||||
- `uuid` (correlation IDs)
|
||||
- `runtime` crate (session persistence bridge)
|
||||
|
||||
---
|
||||
|
||||
## 3. SESSION LIFECYCLE
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/sdk/host/session-runtime.ts`, `sdk/client/`, `sdk/lifecycle/`
|
||||
|
||||
GJC sessions have **three entry points**:
|
||||
1. **Native SDK** (via WebSocket): typed `SdkClient` with `session.create`, `session.prompt`, etc.
|
||||
2. **Browser ACP** (via iframe): same protocol, browser sandbox isolate
|
||||
3. **CLI Daemon** (stdio): JSON-RPC over stdio for local CLI access
|
||||
|
||||
**Session Operations**:
|
||||
- **create**: `turn.create(model, input)` → returns `sessionId`, persistent state written to broker DB
|
||||
- **prompt**: `turn.prompt(request, tools, settings)` → streams events: `agent_begin`, `tool_use`, `tool_result`, `agent_end`
|
||||
- **steer**: `turn.steer(overrides)` → mid-flight direction change (model, settings, system prompt)
|
||||
- **abort**: `turn.abort_and_prompt()` → terminal failure + new prompt in one operation
|
||||
- **list**: `turn.list(filters)` → paginated session history
|
||||
- **get_one**: `turn.get_one(sessionId, turnId)` → single turn with full details
|
||||
|
||||
**State Persistence**:
|
||||
- Invocation record (prompt request, outcome, correlation)
|
||||
- Message buffer (system, assistant, tool results, agent events)
|
||||
- Reconciliation store (uncertain → durable mapping)
|
||||
- Terminal scope (last session per correlation key)
|
||||
|
||||
**Lifecycle Events**:
|
||||
1. `turn_accepted` (immediate, transient)
|
||||
2. `agent_begin` (before first model call)
|
||||
3. `tool_use` + `tool_result` (interleaved)
|
||||
4. `agent_end` (final model output)
|
||||
5. `turn_ended` (durable, terminal outcome recorded)
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Partial. Local session lifecycle exists but no SDK transport or remote access.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/runtime/src/session.rs` (1,961 LOC)
|
||||
- `rust/crates/runtime/src/conversation.rs` (1,878 LOC)
|
||||
- `rust/crates/runtime/src/session_control.rs` (file ops, migration)
|
||||
- `rust/crates/runtime/src/lib.rs` (re-exports `Session`, `SessionStore`, `ConversationRuntime`)
|
||||
|
||||
**Lines**: ~3,900 LOC (session + conversation)
|
||||
|
||||
**Reality**:
|
||||
- `Session` struct holds in-memory state (messages, usage, context).
|
||||
- `SessionStore` reads/writes `.claw/sessions/{id}/` directory.
|
||||
- `ConversationRuntime` drives the local agent loop (sync).
|
||||
- No WebSocket or remote access.
|
||||
- No invocation reconciliation or uncertain outcome recovery.
|
||||
- No terminal scope tracking (per-session-per-correlation).
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| Remote Session Router | 2,500 LOC | — | 100% | High |
|
||||
| Invocation Reconciliation | 1,200 LOC | — | 100% | High |
|
||||
| Terminal Scope Tracking | 600 LOC | — | 100% | Medium |
|
||||
| Async Event Streaming | 800 LOC | Partial | 60% | Medium |
|
||||
| Uncertain Outcome Recovery | 1,000 LOC | — | 100% | High |
|
||||
| **Total** | **6,100 LOC** | **3,900** | **2,200 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `sdk` (new, or extend `runtime`)
|
||||
|
||||
**Module Structure** (add to `sdk/session/`):
|
||||
```
|
||||
sdk/session/
|
||||
├── router.rs (session routing, durable lookup)
|
||||
├── reconciliation.rs (uncertain → terminal recovery)
|
||||
├── terminal_scope.rs (per-correlation state retention)
|
||||
└── events.rs (event publishing, reconciliation)
|
||||
```
|
||||
|
||||
**Integration Points**:
|
||||
- Bridge `runtime::Session` into `sdk::Session` wrapper
|
||||
- Add `runtime::SessionStore` extensions for reconciliation data
|
||||
- Extend `ConversationRuntime` with event emission
|
||||
|
||||
**Size Estimate**: 2,500 LOC (Rust, new + modifications)
|
||||
|
||||
---
|
||||
|
||||
## 4. TOOL CATALOG (55 Tools)
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/tools/` (55 tool files + shared harness)
|
||||
|
||||
GJC implements **55 distinct tools** across multiple domains:
|
||||
- **File I/O**: `read`, `write`, `edit`, `search`, `find`
|
||||
- **Shell**: `bash`, `sleep`
|
||||
- **Task Delegation**: `task` (subagent spawning)
|
||||
- **Workflow**: `skill`, `skill_discovery`, `goal`, `ask`
|
||||
- **Search**: `search_tool_bm25` (semantic search discovery)
|
||||
- **Image**: `image_gen` (DALL-E), `image_tag_scan`
|
||||
- **Integration**: `web_fetch`, `web_search`, `custom_tool_fetch`
|
||||
- **Developer**: `notebook_edit`, `command_repl`, `shell_repl`, `powershell`
|
||||
- **Config**: `config_read`, `config_write` (settings, modes)
|
||||
- **Structured**: `model_registry`, `cost_calculator`, `settings_apply`
|
||||
- **Workflow Gates**: `workflow_gate_answer`, `workflow_plan_approve`
|
||||
- **Move**: `move_cwd`, `move_session`
|
||||
|
||||
**Tool Execution Model**:
|
||||
1. Input deserialized from JSON schema
|
||||
2. Permission check (read-only vs. destructive)
|
||||
3. Tool invocation with typed inputs
|
||||
4. Structured output or error
|
||||
5. Result published to agent loop
|
||||
|
||||
**Permission Gating**: Every tool has a `required_permission` (read-only, approve, unsafe).
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Partial. 35 tools implemented, 20 missing or incomplete.
|
||||
|
||||
**Files**: `rust/crates/tools/src/lib.rs` (10,892 LOC, single file with all 55 spec + implementations)
|
||||
|
||||
**Implemented Tools** (~35):
|
||||
- `read`, `write`, `edit`, `search`, `find`
|
||||
- `bash`, `sleep`
|
||||
- `task` (subagent spawning)
|
||||
- `skill`, `skill_discovery` (basic)
|
||||
- `bash_list_*, bash_check_*` (validation helpers)
|
||||
- `web_fetch`, `search_bm25` (basic)
|
||||
- `config_*` (read/write settings)
|
||||
- `notebooks` (edit, execute)
|
||||
- `goal` (basic ledger)
|
||||
- `move_*` (cwd, session)
|
||||
- Various validation and utility tools
|
||||
|
||||
**Missing / Incomplete Tools** (~20):
|
||||
- `image_gen` (DALL-E)
|
||||
- `image_tag_scan`
|
||||
- `custom_tool_fetch`
|
||||
- `command_repl`, `shell_repl`, `powershell`
|
||||
- `model_registry`, `cost_calculator`
|
||||
- `workflow_gate_answer`, `workflow_plan_approve`
|
||||
- `ask` (interactive prompt)
|
||||
- `irc` (live coordination)
|
||||
- Search/discovery integration tools
|
||||
- Advanced structured output handling
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| Tool Registry | 400 LOC | 400 LOC | 0% | — |
|
||||
| Spec Table (55 entries) | 1,800 LOC | 1,800 LOC | 0% | — |
|
||||
| image_gen | 600 LOC | — | 100% | High |
|
||||
| command_repl, shell_repl | 900 LOC | — | 100% | Medium |
|
||||
| workflow_gate_* | 800 LOC | — | 100% | Medium |
|
||||
| custom_tool_fetch | 400 LOC | — | 100% | Low |
|
||||
| ask (interactive) | 1,200 LOC | Stub | 80% | High |
|
||||
| cost_calculator | 300 LOC | — | 100% | Low |
|
||||
| **Total** | **11,500 LOC** | **8,000** | **3,500 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `tools` (expand existing)
|
||||
|
||||
**New Modules**:
|
||||
```
|
||||
rust/crates/tools/src/
|
||||
├── tools/
|
||||
│ ├── image_gen.rs (DALL-E integration)
|
||||
│ ├── ask_interactive.rs (blocking user prompts)
|
||||
│ ├── workflow_gates.rs (plan approval, gate answer)
|
||||
│ ├── repl/*.rs (command_repl, shell_repl, powershell)
|
||||
│ └── cost_calc.rs (pricing lookup)
|
||||
└── vendors/
|
||||
├── dalle.rs (image generation API)
|
||||
└── integrations.rs (custom tool fetch)
|
||||
```
|
||||
|
||||
**Size Estimate**: 3,500 LOC (new tools + vendor integration)
|
||||
|
||||
**Dependencies**:
|
||||
- `reqwest` (image generation API calls)
|
||||
- `api` crate (provider client reuse)
|
||||
- Existing: `runtime`, `commands`, `serde_json`
|
||||
|
||||
---
|
||||
|
||||
## 5. SKILL DISCOVERY & INVOCATION
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/tools/skill-discovery.ts`, `packages/coding-agent/src/tools/skill.ts`, `packages/coding-agent/src/sdk-skills/`
|
||||
|
||||
GJC supports **dynamic skill loading** with:
|
||||
- **Discovery**: `skill_discovery` tool scans `.gjc/skills/`, project `.gjc/skills/`, bundled skills
|
||||
- **Frontmatter Parsing**: YAML headers in `SKILL.md` define metadata (name, description, use conditions)
|
||||
- **Invocation**: `skill` tool loads and executes a named skill (skill name + args)
|
||||
- **Skill Execution**: Skill = subprocess call to `gjc /skill:<name>` with args
|
||||
- **Bundled Skills**: `autoresearch`, `deep-interview`, `ralplan`, `ultragoal`
|
||||
- **Project Skills**: Discoverable from `.gjc/skills/*/SKILL.md`
|
||||
- **User Skills**: Discoverable from `~/.gjc/skills/*/SKILL.md`
|
||||
|
||||
**Skill Metadata**:
|
||||
```yaml
|
||||
# /skill:my-skill
|
||||
# description: What this skill does
|
||||
# scope: project | user | bundled
|
||||
# requires: List of capabilities
|
||||
```
|
||||
|
||||
**Skill Discovery Result**:
|
||||
```json
|
||||
{
|
||||
"name": "skill-name",
|
||||
"description": "...",
|
||||
"path": "...",
|
||||
"bundled": true | false,
|
||||
"scope": "project" | "user" | "bundled"
|
||||
}
|
||||
```
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Basic. Skill discovery exists but limited to filesystem scanning.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/tools/src/lib.rs` (skill_discovery + skill dispatch, ~200 LOC)
|
||||
- `rust/crates/runtime/src/prompt.rs` (skill loading in prompts, ~100 LOC)
|
||||
|
||||
**Implementation**:
|
||||
- Scans `.claw/skills/` directory for `SKILL.md` files
|
||||
- Parses frontmatter (basic YAML)
|
||||
- Returns discovery results as JSON
|
||||
- `skill` tool invokes skill as subprocess
|
||||
|
||||
**Missing**:
|
||||
- Bundled skill registry (autoresearch, deep-interview, ralplan, ultragoal)
|
||||
- Project + user skill discovery hierarchy
|
||||
- Frontmatter validation and standardization
|
||||
- Skill chaining (`skill()` tool to invoke another skill from within a skill)
|
||||
- Skill state persistence (workflow handoff)
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| Bundled Skill Registry | 200 LOC | — | 100% | Low |
|
||||
| Frontmatter Parser | 150 LOC | 100 LOC | 30% | Low |
|
||||
| Project + User Discovery | 300 LOC | Basic | 70% | Low |
|
||||
| Skill Chaining | 250 LOC | — | 100% | Medium |
|
||||
| Workflow State Handoff | 400 LOC | — | 100% | Medium |
|
||||
| Skill Execution Harness | 200 LOC | Partial | 40% | Low |
|
||||
| **Total** | **1,500 LOC** | **100** | **1,400 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `tools` (expand existing) or `skills` (new, lightweight)
|
||||
|
||||
**Module Structure**:
|
||||
```
|
||||
rust/crates/tools/src/
|
||||
├── skill_discovery.rs (enhanced parsing, project/user/bundled hierarchy)
|
||||
├── skill_execution.rs (subprocess dispatch, state handoff)
|
||||
├── bundled_skills.rs (registry of autoresearch, deep-interview, ralplan, ultragoal)
|
||||
└── skill_state.rs (workflow handoff serialization)
|
||||
```
|
||||
|
||||
**Size Estimate**: 1,400 LOC (Rust)
|
||||
|
||||
**Integration**:
|
||||
- Extend `skill_discovery` tool to search three scopes (bundled, project, user)
|
||||
- Add `skill` tool support for chaining (returning another skill invocation)
|
||||
- Store workflow state in durable files for handoff
|
||||
|
||||
---
|
||||
|
||||
## 6. SETTINGS & CONFIGURATION
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/config.ts`, `packages/coding-agent/src/sdk/host/session-runtime.ts`
|
||||
|
||||
GJC supports **settings override** at multiple levels:
|
||||
1. **Global Settings**: `~/.gjc/config.json` (user defaults)
|
||||
2. **Session Settings**: per-session override via `turn.create` or `turn.prompt` input
|
||||
3. **Runtime Override**: `settings` field in SDK request frames
|
||||
4. **Setting Categories**:
|
||||
- **Model**: `modelName`, `modelTemperature`, `modelMaxTokens`
|
||||
- **Behavior**: `allowance`, `permissions.*`, `features.*`
|
||||
- **UX**: `theme`, `shell`, `notification*`
|
||||
- **Advanced**: `memory.context`, `memory.compression`, `cost.*`
|
||||
|
||||
**Config Schema**: Typed with JSON schema validation per setting
|
||||
|
||||
**Permission Modes**:
|
||||
- `read_only` (no execution)
|
||||
- `approve` (interactive approval)
|
||||
- `unsafe` (no gates)
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Partial. Config exists but no session-level override or setting propagation.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/runtime/src/config.rs` (3,894 LOC, largest file in runtime)
|
||||
- `rust/crates/runtime/src/config_validate.rs` (validation helpers)
|
||||
|
||||
**Implementation**:
|
||||
- Reads `.claw/config.json` at startup
|
||||
- Stores global settings (model, permissions, plugins, features)
|
||||
- No session-level override
|
||||
- No setting propagation through tool execution
|
||||
- No typed setting validation against schema
|
||||
|
||||
**Missing**:
|
||||
- Per-session setting override (session-specific model, permissions)
|
||||
- Setting propagation to all tool invocations
|
||||
- Dynamic setting application (e.g., changing model mid-session)
|
||||
- Setting schema validation
|
||||
- Config hotreload (changes without restart)
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap | Complexity |
|
||||
|-----------|-----|-----------|-----|------------|
|
||||
| Setting Schema Definition | 300 LOC | — | 100% | Low |
|
||||
| Session-Level Override | 400 LOC | — | 100% | Medium |
|
||||
| Setting Propagation | 300 LOC | — | 100% | Low |
|
||||
| Dynamic Application | 200 LOC | — | 100% | Medium |
|
||||
| Config Hotreload | 150 LOC | — | 100% | Low |
|
||||
| **Total** | **1,350 LOC** | **3,894** | **-2,544 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `runtime` (enhance existing `config.rs`)
|
||||
|
||||
**Additions to config.rs**:
|
||||
- Setting schema registry
|
||||
- Session setting override struct
|
||||
- Setting applicator (merge global + session + override)
|
||||
- Hotreload support (watch config file, signal on change)
|
||||
|
||||
**Size Estimate**: 500 LOC (new code, mostly schema + applicators)
|
||||
|
||||
---
|
||||
|
||||
## 7. HOOKS & PLUGINS
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/hooks.ts`, `packages/coding-agent/src/plugin_lifecycle.ts`
|
||||
|
||||
GJC provides **5 hook points**:
|
||||
- `on_session_created`: After session starts
|
||||
- `on_prompt_received`: Before agent loop begins
|
||||
- `on_tool_use`: Before tool invocation
|
||||
- `on_tool_result`: After tool completes
|
||||
- `on_session_ended`: Before session cleanup
|
||||
|
||||
**Plugin System**:
|
||||
- Plugins are shell scripts or binaries in `.claw/plugins/`
|
||||
- Each plugin implements hook handlers (exit code + JSON output)
|
||||
- Plugin registry stored in config
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Existing and comprehensive.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/runtime/src/hooks.rs` (L155)
|
||||
- `rust/crates/runtime/src/plugin_lifecycle.rs`
|
||||
- `rust/crates/plugins/src/` (plugin manager)
|
||||
|
||||
**Implementation**: Hooks fully implemented; plugin system working.
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap |
|
||||
|-----------|-----|-----------|-----|
|
||||
| Hook Points | 5 | 5 | 0% |
|
||||
| Plugin Registry | ✓ | ✓ | 0% |
|
||||
| Plugin Execution | ✓ | ✓ | 0% |
|
||||
|
||||
**Status**: **No gaps**. Hooks and plugins are fully compatible.
|
||||
|
||||
---
|
||||
|
||||
## 8. AGENTS.MD RULES & CONTEXT
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: gajae-code root + `docs/` (AGENTS.md files at multiple levels)
|
||||
|
||||
GJC loads **directory-specific rules** from `AGENTS.md` files:
|
||||
- **Root AGENTS.md**: Project-level knowledge base
|
||||
- **Directory AGENTS.md**: Directory-specific rules override parent
|
||||
- **Rules Loaded**: Automatically prepended to system prompt during agent reasoning
|
||||
- **Hierarchy**: Deepest (most specific) rules override higher level
|
||||
|
||||
**Rule Content**:
|
||||
- Code organization and conventions
|
||||
- Tool restrictions (never use X in Y context)
|
||||
- Testing requirements
|
||||
- Deployment/safety gates
|
||||
- Architecture decisions
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Existing and matching GJC.
|
||||
|
||||
**Files**:
|
||||
- Root: `AGENTS.md`
|
||||
- Crate-level: `rust/crates/*/AGENTS.md`
|
||||
- Implementation: `rust/crates/runtime/src/` (loads rules)
|
||||
|
||||
**Implementation**: Rules loaded and applied to prompts.
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap |
|
||||
|-----------|-----|-----------|-----|
|
||||
| Rule Loading | ✓ | ✓ | 0% |
|
||||
| Hierarchy | ✓ | ✓ | 0% |
|
||||
| Prompt Integration | ✓ | ✓ | 0% |
|
||||
|
||||
**Status**: **No gaps**. AGENTS.md system is compatible.
|
||||
|
||||
---
|
||||
|
||||
## 9. SLASH COMMANDS (120+ Commands)
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/commands/lib.ts` (7,200 LOC with 120+ command specs)
|
||||
|
||||
GJC implements **120+ slash commands** for REPL interaction:
|
||||
- **Session**: `/session list`, `/session create`, `/session restore`, `/session delete`
|
||||
- **Model**: `/model set`, `/model list`, `/model info`
|
||||
- **Permissions**: `/permissions set`, `/permissions show`
|
||||
- **Config**: `/config get`, `/config set`, `/config reload`
|
||||
- **Skills**: `/skills list`, `/skills install`, `/skills create`
|
||||
- **Plugins**: `/plugins list`, `/plugins install`
|
||||
- **Workflow**: `/plan`, `/review`, `/approve`, `/ultragoal`
|
||||
- **Debugging**: `/debug`, `/dump`, `/trace`
|
||||
- **Utilities**: `/help`, `/clear`, `/quit`, `/export`
|
||||
|
||||
**Command Format**: `/command [arg1] [arg2] ...` with arg parsing per command
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Partial. ~40 commands implemented out of 120+.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/commands/src/lib.rs` (7,183 LOC)
|
||||
- Command specs in `SLASH_COMMAND_SPECS` static table
|
||||
|
||||
**Implemented Commands** (~40):
|
||||
- Session mgmt (list, create, etc.)
|
||||
- Help, status, version
|
||||
- Config (get, set, reload)
|
||||
- Skills (list, install)
|
||||
- Plugins (list, install)
|
||||
- Workspace/debug (clear, compact, etc.)
|
||||
|
||||
**Missing Commands** (~80):
|
||||
- Advanced workflow (`/plan`, `/review`, `/ultragoal`)
|
||||
- Model selection and info
|
||||
- Cost calculator (`/cost`)
|
||||
- Advanced debugging (`/dump`, `/trace`)
|
||||
- Theme management
|
||||
- Advanced permission controls
|
||||
- Task management (`/tasks list`, `/tasks cancel`)
|
||||
- IRC/coordination (`/irc`)
|
||||
- Many others
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap |
|
||||
|-----------|-----|-----------|-----|
|
||||
| Command Parser | 800 LOC | 800 LOC | 0% |
|
||||
| Spec Table (120+ entries) | 2,000 LOC | 2,000 LOC | 0% |
|
||||
| Handlers (80 missing) | 3,200 LOC | 1,800 LOC | 56% |
|
||||
| Help/suggestion | 600 LOC | 400 LOC | 30% |
|
||||
| **Total** | **7,200 LOC** | **4,000** | **3,200 LOC** | — |
|
||||
|
||||
### Proposed Implementation
|
||||
|
||||
**Owner Crate**: `commands` (expand existing)
|
||||
|
||||
**New Modules**:
|
||||
```
|
||||
rust/crates/commands/src/
|
||||
├── handlers/
|
||||
│ ├── workflow.rs (/plan, /review, /approve, /ultragoal)
|
||||
│ ├── model.rs (/model set, /model list, /model info)
|
||||
│ ├── cost.rs (/cost)
|
||||
│ ├── advanced_debug.rs (/dump, /trace, /debug advanced)
|
||||
│ ├── theme.rs (/theme set, /theme list)
|
||||
│ ├── task.rs (/tasks list, /tasks cancel)
|
||||
│ └── advanced_perms.rs (advanced permission commands)
|
||||
```
|
||||
|
||||
**Size Estimate**: 3,200 LOC (new command handlers)
|
||||
|
||||
**Dependencies**: `runtime`, `tools`, `plugins`
|
||||
|
||||
---
|
||||
|
||||
## 10. SUBAGENT DELEGATION & TASK EXECUTION
|
||||
|
||||
### GJC Behavior (gajae-code Reference)
|
||||
|
||||
**Source**: `packages/coding-agent/src/tools/task.ts`, `packages/coding-agent/src/task/`
|
||||
|
||||
GJC's **subagent system** enables parallel task execution:
|
||||
- **task Tool**: Spawn parallel subtasks with independent context
|
||||
- **Task States**: spawning, running, succeeded, failed
|
||||
- **Task Isolation**: Each task has isolated session, permissions, context
|
||||
- **Task Coordination**: `irc` tool for live inter-task communication
|
||||
- **Task Monitoring**: `task.inspect`, `task.list`, `task.cancel`
|
||||
- **Artifact Sharing**: Tasks share artifact URLs but not direct state
|
||||
|
||||
**Task Spawning**:
|
||||
```json
|
||||
{
|
||||
"agent": "executor|architect|planner",
|
||||
"tasks": [
|
||||
{
|
||||
"id": "task-1",
|
||||
"description": "...",
|
||||
"assignment": "..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### claw-code Status
|
||||
|
||||
**Current**: Existing and working.
|
||||
|
||||
**Files**:
|
||||
- `rust/crates/tools/src/lib.rs` (task tool, ~300 LOC)
|
||||
- `rust/crates/runtime/src/task_*.rs` (task execution, state mgmt)
|
||||
|
||||
**Implementation**: Task tool works; spawning, monitoring, and coordination functional.
|
||||
|
||||
### Gap Assessment
|
||||
|
||||
| Component | GJC | claw-code | Gap |
|
||||
|-----------|-----|-----------|-----|
|
||||
| Task Spawning | ✓ | ✓ | 0% |
|
||||
| Task Isolation | ✓ | ✓ | 0% |
|
||||
| Task Monitoring | ✓ | ✓ | 0% |
|
||||
| IRC Coordination | ✓ | ✓ | 0% |
|
||||
|
||||
**Status**: **No significant gaps**. Task execution is compatible.
|
||||
|
||||
---
|
||||
|
||||
## 11. IMPLEMENTATION ROADMAP
|
||||
|
||||
### Phase 1: Foundation (SDK Wire Protocol)
|
||||
|
||||
**Slice 1.1: WebSocket Transport & Frame Correlation**
|
||||
- Create `sdk` crate structure
|
||||
- Implement `SdkClient` with WebSocket connection
|
||||
- Add frame ID correlation and response matching
|
||||
- Add reconnect logic with exponential backoff
|
||||
- Tests: transport connectivity, frame correlation, reconnect behavior
|
||||
|
||||
**Slice 1.2: Operation Registry & Schema**
|
||||
- Define Operation enum (65+ operation types)
|
||||
- JSON schema validation for requests
|
||||
- Error code definitions and handlers
|
||||
- Uncertain outcome recovery protocol
|
||||
- Tests: operation parsing, schema validation, error scenarios
|
||||
|
||||
**Slice 1.3: Session SDK Integration**
|
||||
- Bridge `runtime::Session` to SDK session model
|
||||
- Implement session router (durable lookup)
|
||||
- Add invocation reconciliation store
|
||||
- Terminal scope tracking per correlation
|
||||
- Tests: session creation, routing, reconciliation
|
||||
|
||||
### Phase 2: Core Capabilities (Tools & Skills)
|
||||
|
||||
**Slice 2.1: Missing Tool Implementation**
|
||||
- `image_gen` (DALL-E integration)
|
||||
- `ask` (interactive blocking prompts)
|
||||
- `workflow_gate_*` (plan approval gates)
|
||||
- `command_repl`, `shell_repl`, `powershell`
|
||||
- `cost_calculator`
|
||||
|
||||
**Slice 2.2: Skill Enhancement**
|
||||
- Bundled skill registry (autoresearch, deep-interview, ralplan, ultragoal)
|
||||
- Enhanced skill discovery (project, user, bundled hierarchy)
|
||||
- Skill chaining support (skill calling skill)
|
||||
- Workflow state handoff
|
||||
|
||||
### Phase 3: Polish (Settings, Commands, Integration)
|
||||
|
||||
**Slice 3.1: Settings & Configuration**
|
||||
- Session-level setting override
|
||||
- Setting schema validation
|
||||
- Setting propagation to tools
|
||||
- Config hotreload
|
||||
|
||||
**Slice 3.2: Slash Commands**
|
||||
- Workflow commands (/plan, /review, /ultragoal)
|
||||
- Model selection (/model set, /model list)
|
||||
- Cost calculator (/cost)
|
||||
- Advanced debugging (/dump, /trace)
|
||||
- Task management (/tasks list, /tasks cancel)
|
||||
- Theme management (/theme)
|
||||
|
||||
---
|
||||
|
||||
## 12. DEPENDENCY & CRATE RELATIONSHIPS
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ cli (rusty-claude-cli: main entry, REPL, TUI) │
|
||||
└────────────┬───────────────────────────────────────────┘
|
||||
│
|
||||
┌────────────▼──────────────────────────────────────────┐
|
||||
│ commands (slash command specs & handlers) │
|
||||
└────────┬────────────────────────────────────────┬──────┘
|
||||
│ │
|
||||
│ ┌───▼────────────────────┐
|
||||
│ │ tools (55 tool impl) │
|
||||
│ └──────┬─────────────────┘
|
||||
│ │
|
||||
┌────────▼─────────────────────────────────────────▼──────────────────┐
|
||||
│ runtime (session, conversation, config, mcp, hooks, permissions) │
|
||||
└────────┬──────────────────────────────┬────────────────────────────┘
|
||||
│ │
|
||||
┌────▼──────────────┐ ┌──────▼─────────────────┐
|
||||
│ api (providers) │ │ plugins (plugin mgmt) │
|
||||
└───────────────────┘ └───────────────────────┘
|
||||
|
||||
NEW: sdk (WebSocket, session routing, reconciliation)
|
||||
│
|
||||
└─→ depends on: runtime, serde_json, tokio, tungstenite
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. RISK & MITIGATION
|
||||
|
||||
| Risk | Probability | Severity | Mitigation |
|
||||
|------|-------------|----------|-----------|
|
||||
| SDK protocol complexity | High | High | Start with mock transport tests, iterate on real scenarios |
|
||||
| Session state inconsistency | Medium | High | Comprehensive reconciliation tests, durable state verification |
|
||||
| Tool compatibility gaps | Medium | Medium | Tool-by-tool comparison with GJC, shadow testing |
|
||||
| Breaking changes to runtime | Medium | High | Version gates, feature flags, phased rollout |
|
||||
| Performance regression | Medium | Medium | Benchmark key paths (session create, tool dispatch), profile |
|
||||
|
||||
---
|
||||
|
||||
## 14. VERIFICATION & SIGN-OFF
|
||||
|
||||
- [ ] SDK transport connects and communicates with mock server
|
||||
- [ ] Session lifecycle operations (create, prompt, steer, abort) work end-to-end
|
||||
- [ ] Tool execution with SDK matches GJC behavior
|
||||
- [ ] Skill discovery finds all three scopes (bundled, project, user)
|
||||
- [ ] Settings override works per-session
|
||||
- [ ] Slash commands parse and dispatch correctly
|
||||
- [ ] All AGENTS.md tests pass
|
||||
- [ ] Hooks fire at correct lifecycle points
|
||||
- [ ] Subagent tasks spawn and communicate via IRC
|
||||
- [ ] Public documentation has no internal paths, hosts, or private infra
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Last Updated**: 2026-10-13
|
||||
**Next Review**: After Slice 1.1 implementation complete
|
||||
@@ -1,157 +0,0 @@
|
||||
# Slice 2.1 Implementation Log: GJC Tool Catalog Semantic Parity
|
||||
|
||||
**Issue**: #3323
|
||||
**Branch**: `lane/gjc-s21`
|
||||
**Target**: Bring read/edit/search/find tools to GJC semantics
|
||||
**Status**: In Progress
|
||||
|
||||
---
|
||||
|
||||
## Completed Work
|
||||
|
||||
### Phase 1a: Read Tool Selector Parser ✅
|
||||
**Commit**: `6b8bdb2c`
|
||||
**Date**: 2026-10-13
|
||||
|
||||
**Components**:
|
||||
- ✅ New module: `rust/crates/runtime/src/line_range_selector.rs` (343 LOC)
|
||||
- ✅ Line range selector parsing (`:L`, `:L-L+N` syntax)
|
||||
- ✅ Special modes (`:raw`, `:conflicts`)
|
||||
- ✅ Range merging logic for multi-range selectors
|
||||
- ✅ 13 unit tests, all passing
|
||||
|
||||
**Details**:
|
||||
- Supports formats: `:50`, `:50-200`, `:50+150`, `:5-16,960-973`
|
||||
- Automatically merges overlapping/adjacent ranges
|
||||
- Type: `LineRangeSelector` enum with variants: `Raw`, `Conflicts`, `Lines(Vec<LineRange>)`, `None`
|
||||
|
||||
---
|
||||
|
||||
## In-Progress Work
|
||||
|
||||
### Phase 1b: Integration into ReadFileOutput (🚧)
|
||||
**Target**: Next commit
|
||||
**Scope**:
|
||||
- [ ] Update `ReadFileInput` struct in `rust/crates/tools/src/lib.rs` to include selector field
|
||||
- [ ] Update `read_file()` function signature to accept selector parameter
|
||||
- [ ] Implement selector application in `read_file_in_workspace()`
|
||||
- [ ] Update output format to include truncation footer
|
||||
- [ ] Add tests for selector integration
|
||||
|
||||
**Estimated LOC**: 600-800
|
||||
**Complexity**: Medium
|
||||
|
||||
---
|
||||
|
||||
## Remaining Work (Planned)
|
||||
|
||||
### Phase 1c: Truncation Footers & Metadata
|
||||
**Target**: After 1b
|
||||
**Scope**:
|
||||
- [ ] Add `totalLines` field to output
|
||||
- [ ] Add `totalBytes` field to output
|
||||
- [ ] Generate truncation footer with recovery hints
|
||||
- [ ] Format footer: `[Showing lines X-Y of Z; re-read path:1-Z for full file]`
|
||||
- [ ] Add tests for footer generation
|
||||
|
||||
**Estimated LOC**: 300-400
|
||||
|
||||
### Phase 1d: Structural Summarization (Optional - Lower Priority)
|
||||
**Target**: Later
|
||||
**Scope**:
|
||||
- [ ] Collapse function bodies to `..` for code files
|
||||
- [ ] Preserve full lines for prose
|
||||
- [ ] Add hash line anchors for structural boundaries
|
||||
- [ ] Support code language detection
|
||||
|
||||
**Estimated LOC**: 400-600
|
||||
**Complexity**: High
|
||||
|
||||
### Batch 2: EDIT Tool Enhancements
|
||||
**Target**: After Batch 1 complete
|
||||
**Scope**:
|
||||
- [ ] Add patch metadata to output (line numbers, context)
|
||||
- [ ] Ensure exact match semantics
|
||||
- [ ] Add comprehensive tests
|
||||
|
||||
**Estimated LOC**: 200-300
|
||||
|
||||
### Batch 3: SEARCH/FIND Tools
|
||||
**Target**: After Batches 1-2
|
||||
**Scope**:
|
||||
- [ ] Enhance grep with structured output
|
||||
- [ ] Enhance find with metadata (file type, modified)
|
||||
- [ ] Add filtering options
|
||||
|
||||
**Estimated LOC**: 400-500
|
||||
|
||||
---
|
||||
|
||||
## PR Plan
|
||||
|
||||
### PR 1: Read Selector Parser (Phase 1a) ✅
|
||||
**Status**: Merged
|
||||
**Scope**: Selector parsing logic
|
||||
**Files**: `line_range_selector.rs` + lib.rs exports
|
||||
**Tests**: 13 unit tests
|
||||
|
||||
### PR 2: Read Selector Integration (Phase 1b-1c)
|
||||
**Status**: Next
|
||||
**Scope**: ReadFileInput/Output update + integration
|
||||
**Files**: `tools/lib.rs`, `file_ops.rs`, tests
|
||||
**Size**: ~1000 LOC
|
||||
|
||||
### PR 3: EDIT Tool Enhancements (Batch 2)
|
||||
**Status**: Planned
|
||||
**Scope**: Output format enhancements
|
||||
**Size**: ~200 LOC
|
||||
|
||||
### PR 4: SEARCH/FIND Tools (Batch 3)
|
||||
**Status**: Planned
|
||||
**Scope**: Output format & filtering
|
||||
**Size**: ~400 LOC
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
Each phase includes:
|
||||
1. **Unit Tests**: Core functions (parsing, selection, formatting)
|
||||
2. **Integration Tests**: End-to-end tool invocation
|
||||
3. **Parity Tests**: Compare outputs against GJC reference (manual)
|
||||
|
||||
### Test Files
|
||||
- `rust/crates/runtime/src/line_range_selector.rs:tests` ✅ (13 tests)
|
||||
- `rust/crates/runtime/src/file_ops.rs:tests` (to be extended)
|
||||
- `rust/crates/tools/src/lib.rs:tests` (to be extended)
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Mitigation | Priority |
|
||||
|------|-----------|----------|
|
||||
| Large refactor breaks existing tests | Keep changes isolated, extend existing structs | High |
|
||||
| GJC semantics unclear | Reference gajae-code/tools/read.ts directly | High |
|
||||
| Performance regression | Benchmark file ops against baseline | Medium |
|
||||
| Windows path handling | Use existing normalize_for_comparison logic | Medium |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **GJC Read Tool**: `/home/bellman/Workspace/gajae-code/packages/coding-agent/src/tools/read.ts`
|
||||
- **Gap Matrix**: `docs/gjc-compat/gap-matrix.md`
|
||||
- **Semantics Doc**: `docs/gjc-compat/tool-semantics-phase1.md`
|
||||
- **Current Implementation**: `rust/crates/runtime/src/file_ops.rs:713`
|
||||
- **Tool Input Schema**: `rust/crates/tools/src/lib.rs:2884`
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Immediate** (this turn): Implement Phase 1b (ReadFileInput/Output integration)
|
||||
2. **Short-term** (next commit): Add Phase 1c (truncation footers)
|
||||
3. **Medium-term**: Batch 2 (EDIT tool) and Batch 3 (SEARCH/FIND)
|
||||
4. **Verification**: Manual parity testing against GJC reference
|
||||
5. **Merge**: Create focused PRs, merge when checks pass
|
||||
Reference in new issue
Block a user