Agent Runners

The orchestrator invokes AI coding agents through the AgentRunner interface. Runners are auto-discovered from environment variables via the RunnerRegistry.

AgentRunner Interface

Every runner implements:

interface AgentRunner {
  run(ctx: AgentContext): Promise<AgentResult>;
}

The orchestrator provides context (issue details, codebase profile, constraints) and the runner spawns the agent, collects output, and commits changes.

Available Runners

ClaudeCodeRunner

Invokes Claude Code CLI in --print mode.

import { ClaudeCodeRunner } from '@ai-sdlc/orchestrator';

CopilotRunner

Invokes GitHub Copilot CLI in --yolo autonomous mode.

import { CopilotRunner } from '@ai-sdlc/orchestrator';

CursorRunner

Invokes Cursor CLI agent with NDJSON stream output.

The runner parses NDJSON output to extract the final assistant message for use as the PR summary.

import { CursorRunner, parseStreamJson } from '@ai-sdlc/orchestrator';

CodexRunner

Invokes OpenAI Codex CLI in --full-auto --json mode.

The runner includes an enhanced token usage parser that first tries NDJSON usage/token_usage events from stderr (accumulating across multiple events), then falls back to regex.

import { CodexRunner, parseTokenUsage } from '@ai-sdlc/orchestrator';

GenericLLMRunner

Invokes any OpenAI-compatible chat completions API over HTTP.

import { GenericLLMRunner } from '@ai-sdlc/orchestrator';

Runner Registry

The RunnerRegistry manages discovery and selection of runners:

import { createRunnerRegistry } from '@ai-sdlc/orchestrator';

const registry = createRunnerRegistry();

// List all available runners
const available = registry.listAvailable();
console.log(available.map(r => r.name));
// ['claude-code', 'copilot', 'cursor', ...]

// Get a specific runner
const runner = registry.get('copilot');

// Get the default runner (first available)
const defaultRunner = registry.getDefault();

Auto-Discovery

discoverFromEnv() registers runners based on environment variables:

Manual Registration

You can register custom runners:

import { RunnerRegistry } from '@ai-sdlc/orchestrator';

class MyCustomRunner implements AgentRunner {
  async run(ctx: AgentContext): Promise<AgentResult> {
    // Custom agent invocation logic
  }
}

const registry = new RunnerRegistry();
registry.register('my-agent', new MyCustomRunner());

Common Pattern

All CLI-based runners (Claude Code, Copilot, Cursor, Codex) follow the same subprocess pattern:

1. Build prompt — buildPrompt(ctx) constructs a prompt from issue details, constraints, codebase context, and episodic memory
2. Spawn CLI — Run the agent CLI as a child process with appropriate flags
3. Collect output — Buffer stdout and stderr
4. Parse token usage — Extract input/output token counts from stderr for cost tracking
5. Git diff — Run git diff --name-only and git ls-files --others to find changed files
6. Commit — git add -A and git commit with the configured message template and co-author

Environment Variables