feat: SSH Tunnel Support for Remote Incus & Integration Tests

[sebyx07]

Summary

This PR adds comprehensive support for SSH tunneling to remote Incus sockets, enabling AI Army to manage Incus containers on remote workers just as it does with Docker. This is part of the larger Incus/LXC backend integration (PR Group 4 of 5).

Changes

1. SSHTunnelManager Incus Support (Task 15)

   • Add SOCKET_TYPES enum (docker, incus) and DEFAULT_INCUS_SOCKET_PATH constant
   • Accept config.socketType parameter in createTunnel() to determine which remote socket to forward
   • Add _getRemoteSocketPath() helper to resolve socket path based on type
   • Return { dockerHost, incusHost, socketType } in tunnel results
   • Add getIncusHost() and getHost() accessor methods
   • Include socketType/incusHost in healthCheck() and listTunnels() responses
   • Backward compatible: default socketType is 'docker'

2. WorkerAssigner Incus Integration (Task 16)

   • Update worker assignment to include both dockerHost and incusHost in results
   • Pass incusHost through to ContainerPool.initializeContainer() for remote Incus containers

3. Integration Tests (Task 17)

   • Add full Incus container lifecycle integration test in test/integration/execution/IncusBackend.test.js
   • Tests: create, start, exec, install packages, health check, stop, delete
   • Graceful skip if Incus not available ({ skip: !INCUS_AVAILABLE })

4. Comprehensive Unit Tests (Task 18)

   • 30+ new unit tests for Incus-specific behavior in SSHTunnelManager.test.js
   • Test default socket type is 'docker' (backward compatibility)
   • Test Incus socket path selection and custom paths
   • Test socketType in tunnel creation, health checks, and listing
   • Test validation and error handling for invalid socket types

Test Results

✓ All 89 SSHTunnelManager unit tests pass
✓ Integration tests pass (with graceful skip if Incus unavailable)
✓ Lint clean (eslint + prettier)

Backward Compatibility

✅ Default behavior unchanged - socketType defaults to 'docker'
✅ All existing Docker tunnels continue to work
✅ No breaking changes to existing APIs

Test plan

• Unit tests pass (npm run test:unit)
• Integration tests pass (npm run test:integration)
• Lint clean (npm run lint)
• Validated on feature branch

Related

Part of Incus/LXC backend integration epic:

• PR 1-3: Container backend abstraction (merged)
• PR 4: SSH tunnel support ← This PR
• PR 5: Documentation & polish (next)

🤖 Generated with Claude Code

Greptile Overview

Greptile Summary

Extended SSH tunnel infrastructure to support both Docker and Incus socket forwarding, enabling remote Incus container management through SSH tunnels. The implementation adds a socketType parameter (defaulting to 'docker') to SSHTunnelManager.createTunnel(), which determines whether to forward the Docker socket or Incus socket. WorkerAssigner now resolves and provides both dockerHost and incusHost in assignment results, which are passed through to ContainerPool.initializeContainer() to configure remote Incus backends.

• Added SOCKET_TYPES enum with DOCKER and INCUS constants to src/worker/ssh-tunnel.js
• Implemented _getRemoteSocketPath() helper to select socket path based on type (Docker: /var/run/docker.sock, Incus: /var/lib/incus/unix.socket)
• Added getIncusHost() and getHost() accessor methods to retrieve tunnel URLs
• Extended tunnel results to include both dockerHost and incusHost (one is always null based on type)
• Updated WorkerAssigner with _resolveIncusHost() method and added incusHost to all assignment results
• Comprehensive test coverage with 30+ new unit tests and full lifecycle integration tests
• All changes are backward compatible (default socketType is 'docker')

Confidence Score: 5/5

• Safe to merge with no concerns - implementation is well-tested, backward compatible, and follows existing patterns
• The PR demonstrates excellent engineering quality with comprehensive test coverage (30+ unit tests, full integration tests), proper error handling, backward compatibility (default socketType maintains existing behavior), and clean separation of concerns. The implementation correctly extends both SSHTunnelManager and WorkerAssigner to support Incus alongside Docker, with proper validation and null handling throughout the stack.
• No files require special attention

Important Files Changed

Filename	Overview
src/worker/ssh-tunnel.js	Added SOCKET_TYPES enum and Incus socket support with backward-compatible default to Docker, includes proper validation and tunneling logic
src/core/worker-assigner.js	Added _resolveIncusHost() method and included incusHost in assignment results with proper null handling and backward compatibility
test/integration/execution/IncusBackend.test.js	Comprehensive integration tests for Incus container lifecycle with graceful skip when Incus unavailable, covers all critical operations
test/unit/core/WorkerAssigner.test.js	Added comprehensive tests for incusHost resolution covering local workers, remote workers, dual tunnels, and failover scenarios
test/unit/worker/SSHTunnelManager.test.js	Added 30+ unit tests for Incus socket type covering tunnel creation, validation, socket path selection, and backward compatibility

Sequence Diagram

sequenceDiagram
    participant BM as BotManager
    participant WA as WorkerAssigner
    participant STM as SSHTunnelManager
    participant CP as ContainerPool
    participant IB as IncusBackend
    participant Remote as Remote Worker

    BM->>WA: assignBot(botId)
    WA->>WA: _resolveDockerHost(worker)
    WA->>STM: getDockerHost(workerId)
    STM-->>WA: dockerHost or null
    
    WA->>WA: _resolveIncusHost(worker)
    WA->>STM: getIncusHost(workerId)
    STM-->>WA: incusHost or null
    
    WA-->>BM: { workerId, dockerHost, incusHost }
    
    BM->>CP: initializeContainer(botId, config, workspace, { incusHost })
    CP->>CP: _getBackend(botId, config, { incusHost })
    
    alt incusHost provided
        CP->>IB: new IncusBackend({ socketPath: incusHost })
        IB-->>CP: backend instance
    else no incusHost
        CP->>IB: use default IncusBackend()
        IB-->>CP: default backend
    end
    
    CP->>IB: createContainer(botConfig, workspace)
    IB->>Remote: forward via SSH tunnel (tcp://127.0.0.1:port)
    Remote-->>IB: container created
    IB-->>CP: container
    CP-->>BM: container

Loading

_{Last reviewed commit: d29db35}