feat: Runner abstraction layer — pluggable agent backend interface (#3263)

* feat: Runner abstraction layer — pluggable agent backend interface (#3263)

Define AgentRunner interface that abstracts agent lifecycle operations
(start, sendInput, readOutput, kill, isAlive). This decouples session
management from the Claude Code-specific AcpBackend, enabling future
support for Codex, Gemini CLI, and other agent backends.

New modules:
- src/runners/types.ts — AgentRunner interface, ProcessHandle, config/result types
- src/runners/registry.ts — InMemoryRunnerRegistry for runner lookup
- src/runners/stubs/codex-runner.ts — Codex CLI stub (interface-only)
- src/runners/stubs/gemini-runner.ts — Gemini CLI stub (interface-only)
- src/__tests__/fix-3263-runner-abstraction.test.ts — 14 test cases

No existing code modified — pure additive change. Zero test regressions.

Unblocks: #3180 (multi-agent), #3049 (ACP agent mode)
Refs: #3003, #3004

* fix: extract shared NotImplementedError, add async generator semantics comment (#3268 review)

Argus review feedback:
- Extract duplicated NotImplementedError to runners/stubs/shared.ts (DRY)
- Add comment explaining async generator throw semantics on stub readOutput
- Rebase on develop

Author: OneStepAt4time

src/__tests__/fix-3263-runner-abstraction.test.ts

@@ -0,0 +1,197 @@
+/**
+ * fix-3263-runner-abstraction.test.ts — Tests for the Runner abstraction layer.
+ *
+ * Issue #3263: AgentRunner interface, RunnerRegistry, and stub runners.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type {
+  AgentRunner,
+  ProcessHandle,
+  RunnerStartConfig,
+  RunnerStartResult,
+  RunnerSendResult,
+  OutputChunk,
+  RunnerKillResult,
+} from '../runners/types.js';
+import { InMemoryRunnerRegistry } from '../runners/registry.js';
+import { CodexRunner } from '../runners/stubs/codex-runner.js';
+import { GeminiCliRunner } from '../runners/stubs/gemini-runner.js';
+
+// ── Test helpers ─────────────────────────────────────────────────
+
+/** A minimal mock runner for testing the registry. */
+class MockRunner implements AgentRunner {
+  readonly name: string;
+  private readonly handles = new Map<string, ProcessHandle>();
+  private alive = new Set<ProcessHandle>();
+
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  async start(sessionId: string, _config: RunnerStartConfig): Promise<RunnerStartResult> {
+    const handle = `${this.name}-${sessionId}`;
+    this.handles.set(sessionId, handle);
+    this.alive.add(handle);
+    return { handle, capabilities: { mock: true }, agentInfo: { name: this.name } };
+  }
+
+  async sendInput(handle: ProcessHandle, _input: string): Promise<RunnerSendResult> {
+    if (!this.alive.has(handle)) return { delivered: false, attempts: 1, error: 'not alive' };
+    return { delivered: true, attempts: 1 };
+  }
+
+  async *readOutput(_handle: ProcessHandle): AsyncIterable<OutputChunk> {
+    yield { text: 'mock output', source: 'stdout', timestamp: new Date().toISOString() };
+  }
+
+  async kill(handle: ProcessHandle): Promise<RunnerKillResult> {
+    this.alive.delete(handle);
+    return { exitCode: 0, clean: true };
+  }
+
+  isAlive(handle: ProcessHandle): boolean {
+    return this.alive.has(handle);
+  }
+
+  getHandle(sessionId: string): ProcessHandle | undefined {
+    return this.handles.get(sessionId);
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────
+
+describe('Issue #3263 — Runner abstraction layer', () => {
+  describe('AgentRunner interface', () => {
+    it('MockRunner satisfies the interface contract', async () => {
+      const runner = new MockRunner('test-runner');
+      expect(runner.name).toBe('test-runner');
+
+      const result = await runner.start('session-1', { cwd: '/tmp' });
+      expect(result.handle).toBe('test-runner-session-1');
+      expect(result.capabilities).toEqual({ mock: true });
+
+      expect(runner.isAlive(result.handle)).toBe(true);
+      expect(runner.getHandle('session-1')).toBe(result.handle);
+
+      const sendResult = await runner.sendInput(result.handle, 'hello');
+      expect(sendResult.delivered).toBe(true);
+
+      const killResult = await runner.kill(result.handle);
+      expect(killResult.clean).toBe(true);
+      expect(runner.isAlive(result.handle)).toBe(false);
+    });
+
+    it('runner swap does not break session lifecycle', async () => {
+      const runnerA = new MockRunner('runner-a');
+      const runnerB = new MockRunner('runner-b');
+
+      const resultA = await runnerA.start('swap-session', { cwd: '/tmp' });
+      expect(runnerA.isAlive(resultA.handle)).toBe(true);
+
+      await runnerA.kill(resultA.handle);
+      expect(runnerA.isAlive(resultA.handle)).toBe(false);
+
+      const resultB = await runnerB.start('swap-session', { cwd: '/tmp' });
+      expect(runnerB.isAlive(resultB.handle)).toBe(true);
+      expect(resultB.handle).not.toBe(resultA.handle);
+    });
+  });
+
+  describe('RunnerRegistry', () => {
+    it('registers and retrieves runners', () => {
+      const registry = new InMemoryRunnerRegistry();
+      const runner = new MockRunner('claude-code');
+      registry.register(runner);
+
+      expect(registry.get('claude-code')).toBe(runner);
+      expect(registry.listNames()).toEqual(['claude-code']);
+    });
+
+    it('first registered runner becomes default', () => {
+      const registry = new InMemoryRunnerRegistry();
+      const first = new MockRunner('first');
+      const second = new MockRunner('second');
+
+      registry.register(first);
+      registry.register(second);
+
+      expect(registry.getDefault()).toBe(first);
+      expect(registry.listNames()).toEqual(['first', 'second']);
+    });
+
+    it('throws when no runners registered and getDefault is called', () => {
+      const registry = new InMemoryRunnerRegistry();
+      expect(() => registry.getDefault()).toThrow('No runners registered');
+    });
+
+    it('returns undefined for unknown runner name', () => {
+      const registry = new InMemoryRunnerRegistry();
+      expect(registry.get('nonexistent')).toBeUndefined();
+    });
+
+    it('supports multiple runners', () => {
+      const registry = new InMemoryRunnerRegistry();
+      registry.register(new MockRunner('claude-code'));
+      registry.register(new MockRunner('codex'));
+      registry.register(new MockRunner('gemini-cli'));
+
+      expect(registry.listNames()).toHaveLength(3);
+      expect(registry.listNames()).toContain('claude-code');
+      expect(registry.listNames()).toContain('codex');
+      expect(registry.listNames()).toContain('gemini-cli');
+    });
+  });
+
+  describe('CodexRunner stub', () => {
+    it('implements AgentRunner interface', () => {
+      const runner = new CodexRunner();
+      expect(runner.name).toBe('codex');
+      expect(runner.isAlive('any')).toBe(false);
+      expect(runner.getHandle('any')).toBeUndefined();
+    });
+
+    it('throws on start', async () => {
+      const runner = new CodexRunner();
+      await expect(runner.start('s1', { cwd: '/tmp' })).rejects.toThrow('not implemented');
+    });
+
+    it('throws on sendInput', async () => {
+      const runner = new CodexRunner();
+      await expect(runner.sendInput('h1', 'test')).rejects.toThrow('not implemented');
+    });
+
+    it('throws on kill', async () => {
+      const runner = new CodexRunner();
+      await expect(runner.kill('h1')).rejects.toThrow('not implemented');
+    });
+  });
+
+  describe('GeminiCliRunner stub', () => {
+    it('implements AgentRunner interface', () => {
+      const runner = new GeminiCliRunner();
+      expect(runner.name).toBe('gemini-cli');
+      expect(runner.isAlive('any')).toBe(false);
+      expect(runner.getHandle('any')).toBeUndefined();
+    });
+
+    it('throws on start', async () => {
+      const runner = new GeminiCliRunner();
+      await expect(runner.start('s1', { cwd: '/tmp' })).rejects.toThrow('not implemented');
+    });
+  });
+
+  describe('Integration: registry with stubs', () => {
+    it('all stub runners compile and register', () => {
+      const registry = new InMemoryRunnerRegistry();
+      registry.register(new CodexRunner());
+      registry.register(new GeminiCliRunner());
+
+      expect(registry.listNames()).toEqual(['codex', 'gemini-cli']);
+      expect(registry.get('codex')).toBeInstanceOf(CodexRunner);
+      expect(registry.get('gemini-cli')).toBeInstanceOf(GeminiCliRunner);
+    });
+  });
+});

src/runners/index.ts

@@ -0,0 +1,19 @@
+/**
+ * runners/index.ts — Barrel export for the runner abstraction.
+ *
+ * Issue #3263: Pluggable agent backend interface.
+ */
+
+export type {
+  AgentRunner,
+  RunnerRegistry,
+  ProcessHandle,
+  OutputChunk,
+  RunnerStartConfig,
+  RunnerStartResult,
+  RunnerSendResult,
+  RunnerKillOptions,
+  RunnerKillResult,
+} from './types.js';
+
+export { InMemoryRunnerRegistry } from './registry.js';

src/runners/registry.ts

@@ -0,0 +1,35 @@
+/**
+ * runners/registry.ts — In-memory RunnerRegistry implementation.
+ *
+ * Issue #3263: Manages registered agent runners and resolves them by name.
+ */
+
+import type { AgentRunner, RunnerRegistry } from './types.js';
+
+export class InMemoryRunnerRegistry implements RunnerRegistry {
+  private readonly runners = new Map<string, AgentRunner>();
+  private defaultRunner: AgentRunner | undefined;
+
+  register(runner: AgentRunner): void {
+    this.runners.set(runner.name, runner);
+    // First registered runner becomes the default
+    if (!this.defaultRunner) {
+      this.defaultRunner = runner;
+    }
+  }
+
+  get(name: string): AgentRunner | undefined {
+    return this.runners.get(name);
+  }
+
+  listNames(): string[] {
+    return [...this.runners.keys()];
+  }
+
+  getDefault(): AgentRunner {
+    if (!this.defaultRunner) {
+      throw new Error('No runners registered. Register at least one AgentRunner.');
+    }
+    return this.defaultRunner;
+  }
+}

src/runners/stubs/codex-runner.ts

@@ -0,0 +1,55 @@
+/**
+ * runners/stubs/codex-runner.ts — Stub Codex runner (interface only).
+ *
+ * Issue #3263: Placeholder for OpenAI Codex CLI integration.
+ * Will be implemented when Codex CLI gains ACP/stdio support.
+ */
+
+import type {
+  AgentRunner,
+  ProcessHandle,
+  RunnerStartConfig,
+  RunnerStartResult,
+  RunnerSendResult,
+  OutputChunk,
+  RunnerKillOptions,
+  RunnerKillResult,
+} from '../types.js';
+import { NotImplementedError } from './shared.js';
+
+/**
+ * CodexRunner — stub implementation for OpenAI Codex CLI.
+ *
+ * All methods throw to indicate this runner is not yet implemented.
+ * Registered in the runner registry to prove interface compatibility
+ * and allow configuration references.
+ */
+export class CodexRunner implements AgentRunner {
+  readonly name = 'codex';
+
+  async start(_sessionId: string, _config: RunnerStartConfig): Promise<RunnerStartResult> {
+    throw new NotImplementedError('CodexRunner.start');
+  }
+
+  async sendInput(_handle: ProcessHandle, _input: string): Promise<RunnerSendResult> {
+    throw new NotImplementedError('CodexRunner.sendInput');
+  }
+
+  // Note: the throw occurs before any yield, so the caller gets a rejected
+  // promise rather than an error during iteration.
+  async *readOutput(_handle: ProcessHandle): AsyncIterable<OutputChunk> {
+    throw new NotImplementedError('CodexRunner.readOutput');
+  }
+
+  async kill(_handle: ProcessHandle, _options?: RunnerKillOptions): Promise<RunnerKillResult> {
+    throw new NotImplementedError('CodexRunner.kill');
+  }
+
+  isAlive(_handle: ProcessHandle): boolean {
+    return false;
+  }
+
+  getHandle(_sessionId: string): ProcessHandle | undefined {
+    return undefined;
+  }
+}

src/runners/stubs/gemini-runner.ts

@@ -0,0 +1,55 @@
+/**
+ * runners/stubs/gemini-runner.ts — Stub Gemini CLI runner (interface only).
+ *
+ * Issue #3263: Placeholder for Google Gemini CLI integration.
+ * Will be implemented when Gemini CLI gains ACP/stdio support.
+ */
+
+import type {
+  AgentRunner,
+  ProcessHandle,
+  RunnerStartConfig,
+  RunnerStartResult,
+  RunnerSendResult,
+  OutputChunk,
+  RunnerKillOptions,
+  RunnerKillResult,
+} from '../types.js';
+import { NotImplementedError } from './shared.js';
+
+/**
+ * GeminiCliRunner — stub implementation for Google Gemini CLI.
+ *
+ * All methods throw to indicate this runner is not yet implemented.
+ * Registered in the runner registry to prove interface compatibility
+ * and allow configuration references.
+ */
+export class GeminiCliRunner implements AgentRunner {
+  readonly name = 'gemini-cli';
+
+  async start(_sessionId: string, _config: RunnerStartConfig): Promise<RunnerStartResult> {
+    throw new NotImplementedError('GeminiCliRunner.start');
+  }
+
+  async sendInput(_handle: ProcessHandle, _input: string): Promise<RunnerSendResult> {
+    throw new NotImplementedError('GeminiCliRunner.sendInput');
+  }
+
+  // Note: the throw occurs before any yield, so the caller gets a rejected
+  // promise rather than an error during iteration.
+  async *readOutput(_handle: ProcessHandle): AsyncIterable<OutputChunk> {
+    throw new NotImplementedError('GeminiCliRunner.readOutput');
+  }
+
+  async kill(_handle: ProcessHandle, _options?: RunnerKillOptions): Promise<RunnerKillResult> {
+    throw new NotImplementedError('GeminiCliRunner.kill');
+  }
+
+  isAlive(_handle: ProcessHandle): boolean {
+    return false;
+  }
+
+  getHandle(_sessionId: string): ProcessHandle | undefined {
+    return undefined;
+  }
+}

src/runners/stubs/shared.ts

@@ -0,0 +1,18 @@
+/**
+ * runners/stubs/shared.ts — Shared utilities for stub runners.
+ *
+ * Issue #3263: Common error types for placeholder runner implementations.
+ */
+
+/**
+ * Error thrown by stub runner methods that are not yet implemented.
+ *
+ * Stubs compile and register successfully but throw on any lifecycle operation,
+ * allowing the interface contract to be validated without a real agent binary.
+ */
+export class NotImplementedError extends Error {
+  constructor(method: string) {
+    super(`${method} is not implemented. This runner is a stub for future agent integration.`);
+    this.name = 'NotImplementedError';
+  }
+}