Multi-Adapter Architecture Design

Archived design document. Preserved for historical context; not part of the current normative reference/ contract.

Overview

Extend agent-mux to support multiple adapter types beyond subprocess-based execution. This enables integration with sophisticated tools that provide HTTP APIs, WebSocket interfaces, or direct SDK access.

Current Architecture (Subprocess-Only)

interface AgentAdapter {
  buildSpawnArgs(options: RunOptions): SpawnArgs;
  parseEvent(line: string, context: ParseContext): AgentEvent | AgentEvent[] | null;
  // ... session, auth, config methods
}

**Limitations:**

• Forces all tools into subprocess model
• Cannot leverage HTTP APIs, WebSocket streaming, or native SDKs
• Suboptimal for TUI-first tools (OpenCode), server-based tools (Codex app-server)

Proposed Architecture

1. Adapter Type Hierarchy

// Base interface (shared across all adapter types)
interface BaseAgentAdapter {
  // Identity
  readonly agent: AgentName;
  readonly displayName: string;
  readonly adapterType: 'subprocess' | 'remote' | 'programmatic';
  
  // Capabilities (unchanged)
  readonly capabilities: AgentCapabilities;
  readonly models: ModelCapabilities[];
  
  // Common functionality
  detectAuth(): Promise<AuthState>;
  getAuthGuidance(): AuthSetupGuidance;
  sessionDir(cwd?: string): string;
  parseSessionFile(filePath: string): Promise<Session>;
  // ... other common methods
}

// Subprocess adapters (current model)
interface SubprocessAdapter extends BaseAgentAdapter {
  readonly adapterType: 'subprocess';
  readonly cliCommand: string;
  buildSpawnArgs(options: RunOptions): SpawnArgs;
  parseEvent(line: string, context: ParseContext): AgentEvent | AgentEvent[] | null;
}

// Remote adapters (HTTP, WebSocket, Unix sockets)
interface RemoteAdapter extends BaseAgentAdapter {
  readonly adapterType: 'remote';
  readonly connectionType: 'http' | 'websocket' | 'unix';
  
  connect(options: RunOptions): Promise<RemoteConnection>;
  disconnect(connection: RemoteConnection): Promise<void>;
  
  // Optional: start/stop server if adapter manages it
  startServer?(): Promise<ServerInfo>;
  stopServer?(serverInfo: ServerInfo): Promise<void>;
}

// Programmatic adapters (direct SDK integration)
interface ProgrammaticAdapter extends BaseAgentAdapter {
  readonly adapterType: 'programmatic';
  
  execute(options: RunOptions): AsyncIterableIterator<AgentEvent>;
}

2. Connection Abstractions

// Remote connection interface
interface RemoteConnection {
  readonly connectionId: string;
  readonly connectionType: 'http' | 'websocket' | 'unix';
  
  send(data: unknown): Promise<void>;
  receive(): AsyncIterableIterator<AgentEvent>;
  close(): Promise<void>;
}

// HTTP-specific connection
interface HttpConnection extends RemoteConnection {
  readonly connectionType: 'http';
  readonly baseUrl: string;
  
  get(path: string, params?: Record<string, unknown>): Promise<unknown>;
  post(path: string, data?: unknown): Promise<unknown>;
  stream(path: string, data?: unknown): AsyncIterableIterator<AgentEvent>;
}

// WebSocket-specific connection  
interface WebSocketConnection extends RemoteConnection {
  readonly connectionType: 'websocket';
  readonly websocketUrl: string;
  
  subscribe(channel: string): AsyncIterableIterator<AgentEvent>;
  unsubscribe(channel: string): Promise<void>;
}

3. Server Management

interface ServerInfo {
  readonly serverId: string;
  readonly serverType: string;
  readonly endpoint: string;
  readonly pid?: number;
  readonly health?: 'starting' | 'healthy' | 'unhealthy';
}

interface ServerManager {
  start(adapter: RemoteAdapter, options?: ServerOptions): Promise<ServerInfo>;
  stop(serverId: string): Promise<void>;
  health(serverId: string): Promise<ServerInfo>;
  list(): Promise<ServerInfo[]>;
}

Implementation Plan

Phase 1: Core Architecture

1. **Create new interface hierarchy** in packages/core/src/adapter-types.ts 2. **Extend AgentAdapter** to be union type: SubprocessAdapter | RemoteAdapter | ProgrammaticAdapter 3. **Update BaseAgentAdapter** in adapters package to implement SubprocessAdapter 4. **Maintain backward compatibility** - all existing adapters continue working

Phase 2: Execution Engine Updates

1. **Update RunHandleImpl** to route based on adapter.adapterType 2. **Create RemoteRunner** for HTTP/WebSocket execution 3. **Create ProgrammaticRunner** for direct SDK execution 4. **Add ServerManager** for lifecycle management 5. **Update event streaming** to handle different execution models

Phase 3: New Adapter Implementations

1. **opencode-http**: HTTP server + REST API + SSE streaming 2. **codex-sdk**: Direct SDK integration 3. **codex-websocket**: WebSocket app-server integration 4. **claude-agent-sdk**: Programmatic Claude interface 5. **pi-sdk**: Enhanced programmatic Pi interface

Phase 4: Mock Infrastructure

1. **MockHttpServer**: Simulate HTTP endpoints + SSE 2. **MockWebSocketServer**: Simulate real-time connections 3. **MockSDK**: Simulate direct SDK calls 4. **Enhanced scenarios**: Support all adapter types

Adapter Naming Convention

**Pattern**: {tool}-{type} where type indicates the integration method:

• opencode (subprocess, default)
• opencode-http (HTTP server)
• codex (subprocess, current)
• codex-sdk (programmatic SDK)
• codex-websocket (WebSocket app-server)
• claude-agent-sdk (programmatic)

Example Adapter Implementations

HTTP Adapter (OpenCode)

class OpenCodeHttpAdapter implements RemoteAdapter {
  readonly adapterType = 'remote';
  readonly connectionType = 'http';
  readonly agent = 'opencode-http';
  
  async connect(options: RunOptions): Promise<HttpConnection> {
    // Start 'opencode serve' if needed
    const serverInfo = await this.ensureServer();
    
    // Create HTTP connection
    return new OpenCodeHttpConnection({
      baseUrl: serverInfo.endpoint,
      sessionId: options.sessionId,
      model: options.model,
    });
  }
  
  private async ensureServer(): Promise<ServerInfo> {
    // Check if server already running
    // If not, start via 'opencode serve --port 0'
    // Return connection details
  }
}

class OpenCodeHttpConnection implements HttpConnection {
  async *stream(path: string, data: unknown): AsyncIterableIterator<AgentEvent> {
    // POST to /api/chat/stream with SSE
    const response = await fetch(`${this.baseUrl}${path}`, {
      method: 'POST',
      body: JSON.stringify(data),
      headers: { 'Accept': 'text/event-stream' }
    });
    
    for await (const chunk of response.body) {
      yield this.parseServerSentEvent(chunk);
    }
  }
}

SDK Adapter (Codex)

class CodexSdkAdapter implements ProgrammaticAdapter {
  readonly adapterType = 'programmatic';
  readonly agent = 'codex-sdk';
  
  async *execute(options: RunOptions): AsyncIterableIterator<AgentEvent> {
    const sdk = new CodexSDK({
      apiKey: process.env.OPENAI_API_KEY,
      model: options.model || this.defaultModelId,
    });
    
    const stream = await sdk.chat.completions.create({
      messages: [{ role: 'user', content: options.prompt }],
      stream: true,
    });
    
    for await (const chunk of stream) {
      yield this.parseCodexChunk(chunk);
    }
  }
}

Migration Strategy

1. **Backward Compatible**: All existing adapters continue working unchanged 2. **Gradual Adoption**: Add new adapter types without breaking existing functionality 3. **Clear Documentation**: Document when to use each adapter type 4. **Mock Support**: Ensure all adapter types have full mock coverage

Benefits

1. **Native Performance**: Direct SDK integration eliminates subprocess overhead 2. **Real-time Streaming**: WebSocket connections enable bidirectional communication 3. **Full Capabilities**: HTTP APIs provide access to complete tool feature sets 4. **Flexible Integration**: Choose the best integration method per tool 5. **Future-Proof**: Support emerging tools with non-CLI interfaces

Claude-Specific Transport Note

Claude now spans multiple distinct integration surfaces that should not be collapsed into a single "server mode" mental model:

• claude CLI can provide a **persistent structured subprocess transport** through --print --input-format stream-json --output-format stream-json, with stdin carrying later user turns and stdout carrying structured events.
• claude-agent-sdk is a **programmatic persistent transport** with direct callback integration.
• claude-remote-control is the **server-managed Claude surface for Claude.ai / Claude app clients**. Agent-mux can launch and observe the bridge honestly, but it does not advertise local stdin-driven chat semantics for it.
• Claude channels are **MCP-mediated push/reply integrations into a running Claude host session**, not a standalone replacement for the CLI or SDK transports.

Agent-mux should model these surfaces honestly and only advertise the transport semantics each one actually supports.

Trade-offs

1. **Complexity**: Multiple execution paths increase code complexity 2. **Resource Management**: HTTP servers and connections need lifecycle management 3. **Testing**: More sophisticated mocking required 4. **Dependencies**: Programmatic adapters may require additional npm dependencies

Files to Create/Modify

New Files

• packages/core/src/adapter-types.ts - New interface hierarchy
• packages/core/src/remote-runner.ts - HTTP/WebSocket execution
• packages/core/src/programmatic-runner.ts - SDK execution
• packages/core/src/server-manager.ts - Server lifecycle management
• packages/adapters/src/remote-adapter-base.ts - Base class for remote adapters
• packages/adapters/src/programmatic-adapter-base.ts - Base class for SDK adapters

Modified Files

• packages/core/src/adapter.ts - Update AgentAdapter union type
• packages/core/src/run-handle-impl.ts - Route by adapter type
• packages/adapters/src/base-adapter.ts - Implement SubprocessAdapter
• packages/harness-mock/src/index.ts - Add mock infrastructure

This architecture enables agent-mux to evolve beyond subprocess-only integration while maintaining full backward compatibility and providing a clear path for supporting sophisticated AI tools with diverse integration requirements.