🤖 Add pluggable runtime abstraction layer

[ammar-agent]

Overview

Implements Phase 1 of pluggable runtime system with minimal Runtime interface that allows tools to execute in different environments (local, docker, ssh). This is a pure refactoring with zero user-facing changes.

Changes

Runtime Abstraction

• Runtime interface with 5 core methods: exec(), readFile(), writeFile(), stat(), exists()
• LocalRuntime implementation using Node.js APIs (spawn, fs/promises)
• RuntimeError class for consistent error handling

Tool Refactoring

• Refactored file_read.ts to use runtime.readFile() and runtime.stat()
• Refactored file_edit_replace.ts to use runtime for all file operations
• Refactored file_edit_insert.ts to use runtime for all file operations
• Updated fileCommon.ts to work with FileStat interface instead of fs.Stats
• Note: bash.ts kept unchanged (complex overflow handling)

Integration

• Updated ToolConfiguration to include runtime: Runtime field
• Inject LocalRuntime in aiService and ipcMain
• Updated tsconfig to ES2023 for Disposable type support

Testing

• All 90 tool tests pass with zero failures
• Updated tests to inject LocalRuntime
• Updated error message assertions for RuntimeError format

Architecture Benefits

Easy to test: Runtime implementations are isolated (< 250 lines each), no dependencies between runtimes.

Easy to extend: Adding DockerRuntime or SSHRuntime = implement 5-method interface. Tools automatically work with new runtimes.

Backwards compatible: LocalRuntime is default, no config changes = no behavior changes.

Next Steps

Foundation is now in place for:

• Phase 2: DockerRuntime implementation
• Phase 3: SSHRuntime implementation
• Add runtimeConfig to WorkspaceMetadata
• UI for configuring runtime per workspace

Testing

✅ 90 pass, 0 fail (274 expect() calls)
✅ Type checking passes
✅ Build succeeds

Generated with cmux