🤖 Add basic support for SSH runtime

[ammar-agent]

Overview

Implements pluggable runtime abstraction layer with both LocalRuntime and SSHRuntime implementations. Includes comprehensive integration testing for file editing tools across both runtimes.

Changes

Runtime Abstraction

• Runtime interface with core methods: exec(), readFile(), writeFile(), stat(), workspace lifecycle
• LocalRuntime implementation using Node.js APIs (spawn, fs/promises)
• SSHRuntime implementation using SSH connections with:
  • Remote command execution via SSH
  • File operations over SSH with proper shell escaping
  • Git clone-based workspace creation with rsync/scp fallback
  • Remote init hook execution
• RuntimeError class for consistent error handling

File Tools Integration

• Refactored file_read.ts, file_edit_replace.ts, file_edit_insert.ts to use runtime
• Updated bash.ts to support both local and SSH execution
• All file operations now work transparently across local and remote environments

SSH Runtime Bug Fixes

• Fixed shell escaping in SSHRuntime (was using JSON.stringify causing nested quote issues)
• Added escapeShellArg() helper using single-quote escaping for reliable shell argument handling
• Fixed quoting issues in file operations (cat, mkdir, mv commands)

Integration Testing

• New test suite: runtimeFileEditing.test.ts (6 tests, ~42s)
  • Matrix testing across LocalRuntime and SSHRuntime
  • Tests file_read, file_edit_replace_string, file_edit_insert via AI
  • All file operations driven through AI (no direct filesystem access)
  • Uses Haiku 4.5 for speed, toolPolicy to isolate file tools
• Updated: workspaceInitHook.test.ts to expect workspace creation logs
  • Init events now emitted for all workspaces (with or without .cmux/init hook)
  • Tests verify workspace creation steps are logged properly

Workspace Init Events

• Workspace creation now emits init events (git worktree creation, rsync progress, etc.)
• Provides visibility into workspace setup even without init hooks
• LocalRuntime logs: "Creating git worktree...", "Worktree created successfully"
• SSHRuntime logs: "Preparing remote workspace...", "Syncing project files...", etc.

Architecture Benefits

Easy to test: Runtime implementations isolated, matrix testing verifies both paths work identically.

Easy to extend: Adding new runtime = implement interface. Tools automatically work.

Battle-tested: SSH runtime validated with real AI file operations, not just unit tests.

Testing

✅ 6 runtime file editing tests pass (LocalRuntime + SSHRuntime)
✅ 5 workspace init hook tests pass
✅ All 40+ integration tests pass
✅ Type checking passes
✅ Static checks pass

Next Steps

Foundation ready for:

• UI for configuring runtime per workspace
• Additional runtime implementations (Docker, etc.)
• Extended test coverage for edge cases

Generated with cmux

[ammar-agent]

✅ Runtime Integration Tests Added

Added comprehensive integration tests for both LocalRuntime and SSHRuntime with real SSH testing using Docker.

Test Infrastructure

Docker SSH Server:

• Alpine Linux + OpenSSH in container
• Dynamic port allocation (-p 0:22) for concurrent test runs
• Ephemeral SSH key generation per test run
• Container reused across test suite (~2s startup, ~25s total)

Test Matrix Pattern:

• All 52 tests run against both local and ssh runtimes
• Ensures interface compliance and behavior consistency
• Isolated temp directories per test (local or remote)

Test Coverage

Core Operations: (26 tests)

• exec(): stdout/stderr separation, stdin, exit codes, env vars, cwd
• readFile(): text, binary, empty files, error handling
• writeFile(): atomic writes, overwrites, parent dir creation
• stat(): file/dir metadata, error handling

Edge Cases: (26 tests)

• Non-existent paths → RuntimeError
• Directory operations (stat works, read fails)
• Binary data (non-UTF8)
• Large files (1MB+)
• Concurrent operations
• Special characters (quotes, spaces, newlines)
• Nested/long file paths

Results

✅ All 52 tests passing (26 local + 26 SSH)
✅ Existing integration tests still pass
✅ Types checked
✅ Formatted

Test run:

TEST_INTEGRATION=1 bun x jest tests/runtime/runtime.test.ts
# ~25 seconds for all 52 tests

Implementation Notes

LocalRuntime fixes:

• Added type annotations for ReadableStream/WritableStream handlers
• Already creates parent dirs (via write-file-atomic)

SSHRuntime enhancements:

• Added identityFile config option for key path
• Added port config option for non-standard ports
• Fixed writeFile() to create parent directories: mkdir -p $(dirname ...)
• Suppress SSH warnings with -o LogLevel=ERROR

Key design decisions:

• Test real SSH behavior (no mocking) for production confidence
• Dynamic ports prevent conflicts between parallel test runs
• Disposable workspaces ensure test isolation
• Container reuse for speed vs isolation trade-off

Files Added

tests/runtime/
├── runtime.test.ts              # 409 lines, 52 tests
├── ssh-fixture.ts               # Docker lifecycle (278 lines)
├── test-helpers.ts              # Workspace management (176 lines)
├── ssh-server/
│   ├── Dockerfile               # Alpine + OpenSSH
│   ├── entrypoint.sh            # SSH server startup
│   └── sshd_config              # SSH config
└── README.md                    # Test documentation

Ready for review! 🚀

[ammar-agent]

Added macOS runtime integration tests to CI. The main integration suite covers Linux, but runtime code is particularly prone to system incompatibilities (process spawning, streams, file ops) so we run these tests on macOS as well. Full suite on matrix would be wasteful - this targets just the platform-sensitive code.

[ammar-agent]

Updated macOS runtime test job:

• Now runs all of tests/runtime/ for future-proofing
• Removed API keys (runtime tests don't use AI APIs)