@ai-sdlc/orchestrator 0.1.0

package/dist/runners/cursor.js

@@ -0,0 +1,140 @@
+/**
+ * Cursor CLI runner — invokes `cursor-agent` in --print mode with
+ * stream-json output and collects the result via git diff.
+ */
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_CURSOR_MODEL, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
+import { buildPrompt } from './claude-code.js';
+export { buildPrompt };
+const execFileAsync = promisify(execFile);
+async function gitExec(workDir, args) {
+    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
+    return stdout.trim();
+}
+/**
+ * Parse NDJSON stream output from cursor-agent --output-format=stream-json.
+ * Extracts the final assistant message content for use as a summary.
+ */
+export function parseStreamJson(stdout) {
+    const lines = stdout.split('\n').filter(Boolean);
+    let lastAssistantContent = '';
+    for (const line of lines) {
+        try {
+            const obj = JSON.parse(line);
+            if (obj.role === 'assistant' && typeof obj.content === 'string') {
+                lastAssistantContent = obj.content;
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return lastAssistantContent || stdout.slice(0, 2000);
+}
+/**
+ * Parse token usage from Cursor CLI stderr output.
+ */
+export function parseTokenUsage(stderr, model) {
+    const inputMatch = stderr.match(/input[\s_-]*tokens?[:\s]+(\d[\d,]*)/i);
+    const outputMatch = stderr.match(/output[\s_-]*tokens?[:\s]+(\d[\d,]*)/i);
+    if (inputMatch || outputMatch) {
+        return {
+            inputTokens: inputMatch ? parseInt(inputMatch[1].replace(/,/g, ''), 10) : 0,
+            outputTokens: outputMatch ? parseInt(outputMatch[1].replace(/,/g, ''), 10) : 0,
+            model,
+        };
+    }
+    const totalMatch = stderr.match(/total[\s_-]*tokens?[:\s]+(\d[\d,]*)/i);
+    if (totalMatch) {
+        const total = parseInt(totalMatch[1].replace(/,/g, ''), 10);
+        return {
+            inputTokens: Math.round(total * 0.7),
+            outputTokens: Math.round(total * 0.3),
+            model,
+        };
+    }
+    return undefined;
+}
+export class CursorRunner {
+    async run(ctx) {
+        const prompt = buildPrompt(ctx);
+        const timeoutMs = ctx.timeoutMs ?? DEFAULT_RUNNER_TIMEOUT_MS;
+        const model = DEFAULT_CURSOR_MODEL ?? 'cursor-default';
+        try {
+            const args = ['--print', prompt, '--force', '--output-format=stream-json'];
+            if (DEFAULT_CURSOR_MODEL) {
+                args.push('-m', DEFAULT_CURSOR_MODEL);
+            }
+            const { stdout, stderr } = await new Promise((resolve, reject) => {
+                const child = spawn('cursor-agent', args, {
+                    cwd: ctx.workDir,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    env: { ...process.env },
+                    timeout: timeoutMs,
+                });
+                const chunks = [];
+                const errChunks = [];
+                child.stdout.on('data', (data) => chunks.push(data));
+                child.stderr.on('data', (data) => errChunks.push(data));
+                child.on('close', (code) => {
+                    const out = Buffer.concat(chunks).toString('utf-8');
+                    const err = Buffer.concat(errChunks).toString('utf-8');
+                    if (code === 0) {
+                        resolve({ stdout: out, stderr: err });
+                    }
+                    else {
+                        reject(new Error(`cursor-agent exited with code ${code}: ${err || out}`));
+                    }
+                });
+                child.on('error', reject);
+            });
+            const tokenUsage = parseTokenUsage(stderr, model);
+            const summary = parseStreamJson(stdout);
+            // Collect changed files
+            const diffOutput = await gitExec(ctx.workDir, ['diff', '--name-only']);
+            const untrackedOutput = await gitExec(ctx.workDir, [
+                'ls-files',
+                '--others',
+                '--exclude-standard',
+            ]);
+            const filesChanged = [
+                ...diffOutput.split('\n').filter(Boolean),
+                ...untrackedOutput.split('\n').filter(Boolean),
+            ];
+            if (filesChanged.length === 0) {
+                return {
+                    success: false,
+                    filesChanged: [],
+                    summary: 'Agent made no changes',
+                    error: 'No files were modified',
+                    tokenUsage,
+                };
+            }
+            // Stage and commit
+            await gitExec(ctx.workDir, ['add', '-A']);
+            const tmpl = ctx.commitMessageTemplate ?? DEFAULT_COMMIT_MESSAGE_TEMPLATE;
+            const coAuthor = ctx.commitCoAuthor ?? DEFAULT_COMMIT_CO_AUTHOR;
+            const commitMsg = tmpl
+                .replace(/\{issueNumber\}/g, String(ctx.issueNumber))
+                .replace(/\{issueTitle\}/g, ctx.issueTitle);
+            await gitExec(ctx.workDir, ['commit', '-m', `${commitMsg}\n\nCo-Authored-By: ${coAuthor}`]);
+            return {
+                success: true,
+                filesChanged,
+                summary: summary.slice(0, 2000),
+                tokenUsage,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                success: false,
+                filesChanged: [],
+                summary: 'Agent execution failed',
+                error: message,
+            };
+        }
+    }
+}
+//# sourceMappingURL=cursor.js.map

package/dist/runners/devin-stub.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stub runner for Devin — placeholder for future implementation.
+ */
+import type { AgentRunner, AgentContext, AgentResult } from './types.js';
+export declare class DevinStubRunner implements AgentRunner {
+    readonly name = "devin";
+    run(_ctx: AgentContext): Promise<AgentResult>;
+}
+//# sourceMappingURL=devin-stub.d.ts.map

package/dist/runners/devin-stub.js

@@ -0,0 +1,15 @@
+/**
+ * Stub runner for Devin — placeholder for future implementation.
+ */
+export class DevinStubRunner {
+    name = 'devin';
+    async run(_ctx) {
+        return {
+            success: false,
+            filesChanged: [],
+            summary: 'Devin runner not yet implemented',
+            error: 'STUB: Devin integration requires Devin API access',
+        };
+    }
+}
+//# sourceMappingURL=devin-stub.js.map

package/dist/runners/generic-llm.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Generic LLM runner — HTTP-based, OpenAI-compatible API runner.
+ *
+ * Design decision D4: Calls LLM APIs directly via HTTP (not CLI subprocess).
+ * Accepts apiUrl, apiKey, model config. Enables non-Claude agents.
+ */
+import type { AgentRunner, AgentContext, AgentResult } from './types.js';
+export interface GenericLLMConfig {
+    /** API endpoint URL (e.g., https://api.openai.com/v1/chat/completions). */
+    apiUrl: string;
+    /** API key for authentication. */
+    apiKey: string;
+    /** Model identifier (e.g., gpt-4, claude-3-opus, etc.). */
+    model: string;
+    /** Maximum tokens to generate. Defaults to 4096. */
+    maxTokens?: number;
+    /** Request timeout in milliseconds. Defaults to 120000. */
+    timeoutMs?: number;
+    /** System prompt prefix. */
+    systemPrompt?: string;
+}
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface ChatCompletionResponse {
+    id: string;
+    choices: Array<{
+        message: {
+            role: string;
+            content: string;
+        };
+        finish_reason: string;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    model?: string;
+}
+export declare class GenericLLMRunner implements AgentRunner {
+    private config;
+    constructor(config: GenericLLMConfig);
+    run(ctx: AgentContext): Promise<AgentResult>;
+    private buildMessages;
+    private callAPI;
+    private parseTokenUsage;
+    private extractFilesFromResponse;
+}
+//# sourceMappingURL=generic-llm.d.ts.map

package/dist/runners/generic-llm.js

@@ -0,0 +1,125 @@
+/**
+ * Generic LLM runner — HTTP-based, OpenAI-compatible API runner.
+ *
+ * Design decision D4: Calls LLM APIs directly via HTTP (not CLI subprocess).
+ * Accepts apiUrl, apiKey, model config. Enables non-Claude agents.
+ */
+import { DEFAULT_LLM_TIMEOUT_MS, DEFAULT_LLM_MAX_TOKENS, DEFAULT_LLM_SYSTEM_PROMPT, } from '../defaults.js';
+export class GenericLLMRunner {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async run(ctx) {
+        const messages = this.buildMessages(ctx);
+        try {
+            const response = await this.callAPI(messages);
+            if (!response.choices?.[0]?.message?.content) {
+                return {
+                    success: false,
+                    filesChanged: [],
+                    summary: 'LLM returned empty response',
+                    error: 'No content in response',
+                };
+            }
+            const content = response.choices[0].message.content;
+            const tokenUsage = this.parseTokenUsage(response);
+            return {
+                success: true,
+                filesChanged: this.extractFilesFromResponse(content),
+                summary: content.slice(0, 2000),
+                tokenUsage,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                filesChanged: [],
+                summary: 'LLM API call failed',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    buildMessages(ctx) {
+        const messages = [];
+        if (this.config.systemPrompt) {
+            messages.push({ role: 'system', content: this.config.systemPrompt });
+        }
+        else {
+            messages.push({
+                role: 'system',
+                content: DEFAULT_LLM_SYSTEM_PROMPT,
+            });
+        }
+        const userContent = [
+            `Issue #${ctx.issueNumber}: ${ctx.issueTitle}`,
+            '',
+            ctx.issueBody,
+            '',
+            `Working directory: ${ctx.workDir}`,
+            `Branch: ${ctx.branch}`,
+            `Max files: ${ctx.constraints.maxFilesPerChange}`,
+            `Require tests: ${ctx.constraints.requireTests}`,
+        ];
+        if (ctx.codebaseContext) {
+            userContent.push('', `Codebase: ${JSON.stringify(ctx.codebaseContext)}`);
+        }
+        messages.push({ role: 'user', content: userContent.join('\n') });
+        return messages;
+    }
+    async callAPI(messages) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs ?? DEFAULT_LLM_TIMEOUT_MS);
+        try {
+            const res = await fetch(this.config.apiUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    model: this.config.model,
+                    messages,
+                    max_tokens: this.config.maxTokens ?? DEFAULT_LLM_MAX_TOKENS,
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`API error ${res.status}: ${text.slice(0, 200)}`);
+            }
+            return (await res.json());
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    parseTokenUsage(response) {
+        if (!response.usage)
+            return undefined;
+        return {
+            inputTokens: response.usage.prompt_tokens,
+            outputTokens: response.usage.completion_tokens,
+            model: response.model ?? this.config.model,
+        };
+    }
+    extractFilesFromResponse(content) {
+        // Extract file paths from common patterns in LLM responses
+        const patterns = [
+            /(?:modified|created|updated|changed|edited)\s+[`"]?([^\s`"]+\.[a-z]+)/gi,
+            /```[\w]*\s*\/\/\s*(\S+\.[a-z]+)/g,
+        ];
+        const files = new Set();
+        for (const pattern of patterns) {
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+                const file = match[1].replace(/[`'"]/g, '');
+                if (file.includes('/') || file.includes('.')) {
+                    files.add(file);
+                }
+            }
+        }
+        return [...files];
+    }
+}
+//# sourceMappingURL=generic-llm.js.map

package/dist/runners/index.d.ts

@@ -0,0 +1,8 @@
+export type { AgentRunner, AgentContext, AgentResult, TokenUsage } from './types.js';
+export { ClaudeCodeRunner, GitHubActionsRunner } from './claude-code.js';
+export { GenericLLMRunner, type GenericLLMConfig, type ChatCompletionResponse, } from './generic-llm.js';
+export { CopilotRunner } from './copilot.js';
+export { CursorRunner } from './cursor.js';
+export { CodexRunner } from './codex.js';
+export { RunnerRegistry, createRunnerRegistry, type RegisteredRunner } from './runner-registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runners/index.js

@@ -0,0 +1,7 @@
+export { ClaudeCodeRunner, GitHubActionsRunner } from './claude-code.js';
+export { GenericLLMRunner, } from './generic-llm.js';
+export { CopilotRunner } from './copilot.js';
+export { CursorRunner } from './cursor.js';
+export { CodexRunner } from './codex.js';
+export { RunnerRegistry, createRunnerRegistry } from './runner-registry.js';
+//# sourceMappingURL=index.js.map

package/dist/runners/runner-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Runner registry — manages available agent runners with auto-discovery.
+ *
+ * Design decision D4: Registry auto-discovers available runners from environment.
+ */
+import type { AgentRunner } from './types.js';
+export interface RegisteredRunner {
+    name: string;
+    runner: AgentRunner;
+    /** Whether this runner is available (has required config). */
+    available: boolean;
+    /** Source of the runner (built-in, env, manual). */
+    source: 'built-in' | 'env' | 'manual';
+}
+export declare class RunnerRegistry {
+    private runners;
+    /**
+     * Register a runner manually.
+     */
+    register(name: string, runner: AgentRunner): void;
+    /**
+     * Get a runner by name.
+     */
+    get(name: string): AgentRunner | undefined;
+    /**
+     * Get the default runner. Returns the first available runner.
+     */
+    getDefault(): AgentRunner | undefined;
+    /**
+     * List all registered runners.
+     */
+    list(): RegisteredRunner[];
+    /**
+     * List only available runners.
+     */
+    listAvailable(): RegisteredRunner[];
+    /**
+     * Check if a runner is registered and available.
+     */
+    has(name: string): boolean;
+    /**
+     * Auto-discover runners from environment variables and register them.
+     */
+    discoverFromEnv(env?: Record<string, string | undefined>): void;
+}
+/**
+ * Create a runner registry with auto-discovery.
+ */
+export declare function createRunnerRegistry(env?: Record<string, string | undefined>): RunnerRegistry;
+//# sourceMappingURL=runner-registry.d.ts.map

package/dist/runners/runner-registry.js

@@ -0,0 +1,156 @@
+/**
+ * Runner registry — manages available agent runners with auto-discovery.
+ *
+ * Design decision D4: Registry auto-discovers available runners from environment.
+ */
+import { ClaudeCodeRunner } from './claude-code.js';
+import { GenericLLMRunner } from './generic-llm.js';
+import { CopilotRunner } from './copilot.js';
+import { CursorRunner } from './cursor.js';
+import { CodexRunner } from './codex.js';
+import { DEFAULT_OPENAI_API_URL, DEFAULT_OPENAI_MODEL, DEFAULT_ANTHROPIC_API_URL, DEFAULT_ANTHROPIC_MODEL, DEFAULT_GENERIC_LLM_MODEL, } from '../defaults.js';
+export class RunnerRegistry {
+    runners = new Map();
+    /**
+     * Register a runner manually.
+     */
+    register(name, runner) {
+        this.runners.set(name, {
+            name,
+            runner,
+            available: true,
+            source: 'manual',
+        });
+    }
+    /**
+     * Get a runner by name.
+     */
+    get(name) {
+        return this.runners.get(name)?.runner;
+    }
+    /**
+     * Get the default runner. Returns the first available runner.
+     */
+    getDefault() {
+        for (const entry of this.runners.values()) {
+            if (entry.available)
+                return entry.runner;
+        }
+        return undefined;
+    }
+    /**
+     * List all registered runners.
+     */
+    list() {
+        return [...this.runners.values()];
+    }
+    /**
+     * List only available runners.
+     */
+    listAvailable() {
+        return [...this.runners.values()].filter((r) => r.available);
+    }
+    /**
+     * Check if a runner is registered and available.
+     */
+    has(name) {
+        const entry = this.runners.get(name);
+        return entry?.available ?? false;
+    }
+    /**
+     * Auto-discover runners from environment variables and register them.
+     */
+    discoverFromEnv(env = process.env) {
+        // Claude Code is always available as CLI runner
+        if (!this.runners.has('claude-code')) {
+            this.runners.set('claude-code', {
+                name: 'claude-code',
+                runner: new ClaudeCodeRunner(),
+                available: true,
+                source: 'built-in',
+            });
+        }
+        // OpenAI-compatible runner from env
+        const openaiKey = env.OPENAI_API_KEY;
+        if (openaiKey && !this.runners.has('openai')) {
+            this.runners.set('openai', {
+                name: 'openai',
+                runner: new GenericLLMRunner({
+                    apiUrl: env.OPENAI_API_URL ?? DEFAULT_OPENAI_API_URL,
+                    apiKey: openaiKey,
+                    model: env.OPENAI_MODEL ?? DEFAULT_OPENAI_MODEL,
+                }),
+                available: true,
+                source: 'env',
+            });
+        }
+        // Anthropic API runner from env
+        const anthropicKey = env.ANTHROPIC_API_KEY;
+        if (anthropicKey && !this.runners.has('anthropic')) {
+            this.runners.set('anthropic', {
+                name: 'anthropic',
+                runner: new GenericLLMRunner({
+                    apiUrl: env.ANTHROPIC_API_URL ?? DEFAULT_ANTHROPIC_API_URL,
+                    apiKey: anthropicKey,
+                    model: env.ANTHROPIC_MODEL ?? DEFAULT_ANTHROPIC_MODEL,
+                }),
+                available: true,
+                source: 'env',
+            });
+        }
+        // Generic LLM runner from env
+        const genericUrl = env.LLM_API_URL;
+        const genericKey = env.LLM_API_KEY;
+        if (genericUrl && genericKey && !this.runners.has('generic-llm')) {
+            this.runners.set('generic-llm', {
+                name: 'generic-llm',
+                runner: new GenericLLMRunner({
+                    apiUrl: genericUrl,
+                    apiKey: genericKey,
+                    model: env.LLM_MODEL ?? DEFAULT_GENERIC_LLM_MODEL,
+                }),
+                available: true,
+                source: 'env',
+            });
+        }
+        // GitHub Copilot CLI runner — available when GH_TOKEN or GITHUB_TOKEN is set
+        const ghToken = env.GH_TOKEN ?? env.GITHUB_TOKEN;
+        if (ghToken && !this.runners.has('copilot')) {
+            this.runners.set('copilot', {
+                name: 'copilot',
+                runner: new CopilotRunner(),
+                available: true,
+                source: 'env',
+            });
+        }
+        // Cursor CLI runner — available when CURSOR_API_KEY is set
+        const cursorKey = env.CURSOR_API_KEY;
+        if (cursorKey && !this.runners.has('cursor')) {
+            this.runners.set('cursor', {
+                name: 'cursor',
+                runner: new CursorRunner(),
+                available: true,
+                source: 'env',
+            });
+        }
+        // Codex CLI runner — available when CODEX_API_KEY is set
+        const codexKey = env.CODEX_API_KEY;
+        if (codexKey && !this.runners.has('codex')) {
+            this.runners.set('codex', {
+                name: 'codex',
+                runner: new CodexRunner(),
+                available: true,
+                source: 'env',
+            });
+        }
+    }
+}
+/**
+ * Create a runner registry with auto-discovery.
+ */
+export function createRunnerRegistry(env) {
+    const registry = new RunnerRegistry();
+    registry.discoverFromEnv(env);
+    return registry;
+}
+//# sourceMappingURL=runner-registry.js.map

package/dist/runners/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * AgentRunner abstraction — decouples agent invocation from execution environment.
+ * The ClaudeCodeRunner is the initial implementation; swap to
+ * Codespaces / devcontainers by implementing this interface.
+ */
+import type { AgentMemory } from '@ai-sdlc/reference';
+import type { CodebaseContext } from '../analysis/types.js';
+export interface AgentContext {
+    issueNumber: number;
+    issueTitle: string;
+    issueBody: string;
+    workDir: string;
+    branch: string;
+    constraints: {
+        maxFilesPerChange: number;
+        requireTests: boolean;
+        blockedPaths: string[];
+    };
+    /** CI failure logs, populated only during fix-CI retries. */
+    ciErrors?: string;
+    /** Agent memory for long-term/episodic recall. */
+    memory?: AgentMemory;
+    /** Override the default tool allowlist for the agent subprocess. */
+    allowedTools?: string[];
+    /** Timeout in milliseconds for the agent subprocess (default 300000). */
+    timeoutMs?: number;
+    /** Override the default model for this agent invocation. */
+    model?: string;
+    /** Codebase context for intelligent agent prompting. */
+    codebaseContext?: CodebaseContext;
+    /** Enriched episodic context from prior runs. */
+    episodicContext?: string;
+    /** Lint command for agent prompt (e.g., `npm run lint`). */
+    lintCommand?: string;
+    /** Format command for agent prompt (e.g., `npm run format`). */
+    formatCommand?: string;
+    /** Commit message template with `{issueNumber}` and `{issueTitle}` placeholders. */
+    commitMessageTemplate?: string;
+    /** Co-author line for commits. */
+    commitCoAuthor?: string;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    model: string;
+}
+export interface AgentResult {
+    success: boolean;
+    filesChanged: string[];
+    summary: string;
+    error?: string;
+    /** Token usage parsed from the agent subprocess. */
+    tokenUsage?: TokenUsage;
+}
+export interface AgentRunner {
+    run(context: AgentContext): Promise<AgentResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runners/types.js

@@ -0,0 +1,7 @@
+/**
+ * AgentRunner abstraction — decouples agent invocation from execution environment.
+ * The ClaudeCodeRunner is the initial implementation; swap to
+ * Codespaces / devcontainers by implementing this interface.
+ */
+export {};
+//# sourceMappingURL=types.js.map