feat(rlm): RLM orchestration with MCP tools

.beads/last-touched

@@ -0,0 +1 @@
+bd-2z0

.docs/ADAPTER_PLAN_SUMMARY.md

@@ -0,0 +1,119 @@
+# fcctl-core Adapter Implementation Plan Summary
+
+## Status: READY FOR IMPLEMENTATION
+
+Both Phase 1 (Research) and Phase 2 (Design) have passed quality evaluation.
+
+---
+
+## Documents Created
+
+| Document | Type | Quality Score | Status |
+|----------|------|---------------|--------|
+| research-fcctl-adapter.md | Phase 1 Research | 4.3/5.0 | ✅ APPROVED |
+| design-fcctl-adapter.md | Phase 2 Design | 4.6/5.0 | ✅ APPROVED |
+| quality-evaluation-fcctl-research.md | Quality Gate | N/A | ✅ PASSED |
+| quality-evaluation-fcctl-design.md | Quality Gate | N/A | ✅ PASSED |
+
+---
+
+## Problem Summary
+
+Bridge fcctl-core's concrete `VmManager` struct with terraphim_firecracker's `VmManager` trait to enable full VM pool functionality.
+
+**Type Mismatch:**
+- fcctl-core provides: Concrete `VmManager` struct
+- terraphim_firecracker expects: `Arc<dyn VmManager>` trait object
+
+**Solution:** Adapter pattern - thin wrapper implementing the trait using fcctl-core's struct
+
+---
+
+## Key Design Decisions
+
+### Architecture
+```
+FirecrackerExecutor -> VmPoolManager -> FcctlVmManagerAdapter -> fcctl-core VmManager -> Firecracker VM
+```
+
+### Value of Pool Architecture (Preserved)
+- Pre-warmed VMs (20-30x faster burst handling)
+- Sub-500ms allocation guarantee
+- VM reuse without boot overhead
+- Background maintenance
+
+### Implementation Plan
+
+**Phase 1: Adapter Structure** (3 steps)
+- Create adapter.rs with struct definition
+- Implement trait scaffolding
+- Configuration translation
+
+**Phase 2: Method Implementation** (5 steps)
+- Implement create_vm(), start_vm(), stop_vm(), delete_vm()
+- Implement remaining trait methods
+
+**Phase 3: Integration** (3 steps)
+- Update executor/mod.rs
+- Replace TODO stub in firecracker.rs
+- Verify compilation
+
+**Phase 4: Testing** (3 steps)
+- Unit tests for adapter
+- Integration test
+- Performance benchmark
+
+**Phase 5: Verification** (2 steps)
+- Full test suite
+- End-to-end test with Firecracker
+
+**Total: 16 steps across 5 phases**
+
+---
+
+## Critical Invariants
+
+- ✅ Adapter implements VmManager trait fully
+- ✅ All operations delegate to fcctl-core
+- ✅ Error propagation preserves context
+- ✅ Configuration translation is lossless
+- ✅ Adapter overhead < 1ms per operation
+- ✅ Sub-500ms allocation guarantee maintained
+
+---
+
+## Open Questions for You
+
+1. **VM ID Format**: fcctl-core uses string IDs. Enforce ULID or pass through?
+
+2. **Configuration Mapping**: VmRequirements may have extra fields. Options:
+   - A) Extend fcctl-core's VmConfig
+   - B) Store extra fields separately
+   - C) Only support common subset
+
+3. **Error Strategy**: 
+   - A) Create unified error type
+   - B) Map to closest trait error variant
+   - C) Preserve fcctl-core errors as source
+
+4. **Pool Configuration**: What PoolConfig values? (pool size, min/max VMs)
+
+---
+
+## Files to Create/Modify
+
+| File | Action | Lines |
+|------|--------|-------|
+| `src/executor/fcctl_adapter.rs` | Create | ~300 |
+| `src/executor/mod.rs` | Modify | +5 |
+| `src/executor/firecracker.rs` | Modify | Replace TODO |
+
+---
+
+## Next Step: Implementation
+
+Ready to proceed with Phase 3 (Implementation) on bigbox.
+
+**Estimated time**: 4-6 hours for all 16 steps
+
+Shall I proceed with implementation?

.docs/IMPLEMENTATION_COMPLETE.md

@@ -0,0 +1,184 @@
+# PR #426 Implementation Complete
+
+## Executive Summary
+
+All phases of PR #426 have been successfully implemented on bigbox. The `terraphim_rlm` crate now has:
+
+- **Security hardening** - Path traversal prevention, input validation, race condition fixes
+- **Resource management** - Memory limits, timeouts, parser constraints
+- **Simplified architecture** - Direct Firecracker integration, removed MockExecutor
+- **Enhanced error handling** - Full error context preservation with `#[source]`
+- **Comprehensive testing** - 74+ tests including integration test framework
+
+---
+
+## Implementation Summary
+
+### Phase A: Security Hardening (COMPLETED)
+
+| Task | Status | Files Modified |
+|------|--------|----------------|
+| Create validation.rs | Done | `src/validation.rs` (+377 lines) |
+| Fix snapshot naming | Done | `src/executor/firecracker.rs` |
+| Fix race condition | Done | `src/executor/firecracker.rs` |
+| Add input validation to MCP | Done | `src/mcp_tools.rs` |
+| Add session validation | Done | `src/mcp_tools.rs` |
+
+**Key Security Fixes:**
+- Path traversal prevention in snapshot names (rejects `..`, `/`, `\`)
+- MAX_CODE_SIZE enforcement (1MB = 1,048,576 bytes)
+- Atomic snapshot counter to prevent race conditions
+- Session existence validation before all MCP operations
+
+### Phase B: Resource Management (COMPLETED)
+
+| Task | Status | Files Modified |
+|------|--------|----------------|
+| Fix MemoryBackend leak | Done | `src/logger.rs` |
+| Add timeout to query loop | Done | `src/query_loop.rs` |
+| Add parser limits | Done | `src/parser.rs` |
+
+**Resource Limits Implemented:**
+- MAX_MEMORY_EVENTS: 10,000 (FIFO eviction)
+- Query timeout: 5 minutes (300 seconds)
+- MAX_INPUT_SIZE: 10MB (10,485,760 bytes)
+- MAX_RECURSION_DEPTH: 100
+
+### Phase C: CI Compatibility - Simplified (COMPLETED)
+
+| Task | Status | Files Modified |
+|------|--------|----------------|
+| Remove MockExecutor | Done | Deleted `src/executor/mock.rs` |
+| Remove trait abstraction | Done | `src/executor/mod.rs` |
+| Simplify firecracker.rs | Done | `src/executor/firecracker.rs` |
+| Update Cargo.toml | Done | `Cargo.toml` |
+
+**Architecture Decision:**
+- Removed MockExecutor entirely (user choice)
+- Using real Firecracker directly via fcctl-core
+- Removed trait abstraction for simplicity
+- CI will use workspace exclusion or self-hosted runners
+
+### Phase D: Error Handling (COMPLETED)
+
+| Task | Status | Files Modified |
+|------|--------|----------------|
+| Add `#[source]` attributes | Done | `src/error.rs` (+9 variants) |
+| Fix unwrap_or_default() | Done | `src/rlm.rs:736` |
+| Update error constructions | Done | 9 files updated |
+
+**Error Improvements:**
+- All error variants now preserve source error context
+- Proper error propagation instead of silent defaults
+- 60+ error construction sites updated
+
+### Phase E: Testing (COMPLETED)
+
+| Task | Status | Files Created/Modified |
+|------|--------|------------------------|
+| Integration test framework | Done | `tests/integration_test.rs` (+657 lines) |
+| Validation unit tests | Done | `src/validation.rs` (+31 tests) |
+| Test configuration | Done | `Cargo.toml` |
+
+**Test Coverage:**
+- **Unit tests**: 74+ tests covering validation, parser, session, budget, logger
+- **Integration tests**: 15 tests (10 gated, 5 unit-style)
+- **Total**: 74+ tests
+
+---
+
+## Files Changed Summary
+
+### Created Files
+1. `crates/terraphim_rlm/src/validation.rs` - Input validation module
+2. `crates/terraphim_rlm/tests/integration_test.rs` - Integration test framework
+
+### Modified Files
+1. `crates/terraphim_rlm/Cargo.toml` - Dependencies and features
+2. `crates/terraphim_rlm/src/lib.rs` - Module exports
+3. `crates/terraphim_rlm/src/error.rs` - Error types with `#[source]`
+4. `crates/terraphim_rlm/src/executor/mod.rs` - Simplified executor module
+5. `crates/terraphim_rlm/src/executor/firecracker.rs` - Security fixes, removed trait
+6. `crates/terraphim_rlm/src/executor/ssh.rs` - Error handling updates
+7. `crates/terraphim_rlm/src/mcp_tools.rs` - Input validation
+8. `crates/terraphim_rlm/src/parser.rs` - Size/depth limits
+9. `crates/terraphim_rlm/src/query_loop.rs` - Timeout handling
+10. `crates/terraphim_rlm/src/logger.rs` - Memory limit, error handling
+11. `crates/terraphim_rlm/src/rlm.rs` - Error handling, removed MockExecutor
+12. `crates/terraphim_rlm/src/validator.rs` - Error handling
+
+### Deleted Files
+1. `crates/terraphim_rlm/src/executor/mock.rs` - MockExecutor (no longer needed)
+
+---
+
+## Running Tests
+
+### Unit Tests (Always Run)
+```bash
+cargo test -p terraphim_rlm --lib
+```
+
+### Integration Tests (Requires Firecracker VM)
+```bash
+# With environment variable
+FIRECRACKER_TESTS=1 cargo test -p terraphim_rlm --test integration_test
+
+# Or run ignored tests
+cargo test -p terraphim_rlm --test integration_test -- --ignored
+```
+
+### Build Verification
+```bash
+cargo check -p terraphim_rlmcargo fmt -p terraphim_rlmcargo clippy -p terraphim_rlm
+```
+
+---
+
+## Configuration Constants
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| MAX_CODE_SIZE | 1,048,576 bytes (1MB) | Maximum code input size |
+| MAX_INPUT_SIZE | 10,485,760 bytes (10MB) | Maximum parser input size |
+| MAX_RECURSION_DEPTH | 100 | Maximum parsing recursion |
+| MAX_MEMORY_EVENTS | 10,000 | Maximum trajectory log events |
+| Query timeout | 300 seconds (5 min) | Query loop timeout |
+| max_snapshots_per_session | 50 | Maximum snapshots per session |
+
+---
+
+## Security Checklist
+
+- [x] Path traversal prevention in snapshot names
+- [x] Input size validation for code/commands
+- [x] Session validation before operations
+- [x] Atomic snapshot counter (race condition fix)
+- [x] Configurable KG validation (not mandatory per user request)
+
+---
+
+## Next Steps
+
+1. **Run full test suite** on bigbox with Firecracker
+2. **Update PR #426** description with changes summary
+3. **Request code review** focusing on security fixes
+4. **Consider CI setup** with self-hosted runner or workspace exclusion
+
+---
+
+## Commit Information
+
+**Branch**: `feat/terraphim-rlm-experimental`  
+**Location**: `/home/alex/terraphim-ai/` on bigbox  
+**Status**: All phases complete, ready for testing
+
+---
+
+## Documentation
+
+- Research: `.docs/research-pr426.md`
+- Design: `.docs/design-pr426.md`
+- Quality Evaluations: `.docs/quality-evaluation-pr426-*.md`
+- Implementation Plan: `.docs/summary-pr426-plan.md`
+- This Summary: `.docs/IMPLEMENTATION_COMPLETE.md`