@kbediako/codex-orchestrator 0.1.0

package/dist/orchestrator/src/learning/harvester.js

@@ -0,0 +1,146 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { isoTimestamp } from '../cli/utils/time.js';
+import { logger } from '../logger.js';
+import { sanitizeRunId } from '../persistence/sanitizeRunId.js';
+import { sanitizeTaskId } from '../persistence/sanitizeTaskId.js';
+import { appendLearningAlert, ensureLearningSection, updateLearningValidation } from './manifest.js';
+const execFileAsync = promisify(execFile);
+export async function runLearningHarvester(manifest, options) {
+    const { repoRoot, runsRoot, manifestPath, taskId, runId, diffPath = null, promptPath = null, executionHistoryPath = null, maxAttempts = 3, backoffMs = [500, 1_000], storageDir, alertTargets, uploader } = options;
+    const learning = ensureLearningSection(manifest);
+    const safeTaskId = sanitizeTaskId(taskId);
+    const safeRunId = sanitizeRunId(runId);
+    const learningDir = join(runsRoot, safeTaskId, 'cli', safeRunId, 'learning');
+    const storageRoot = storageDir ?? join(runsRoot, 'learning-snapshots');
+    await mkdir(learningDir, { recursive: true });
+    let snapshotPath = null;
+    let queuePayloadPath = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const snapshot = await createSnapshot({ repoRoot, learningDir, runId });
+            snapshotPath = snapshot.tarballPath;
+            const storagePath = await persistSnapshot({
+                uploader,
+                storageRoot,
+                taskId: safeTaskId,
+                runId: safeRunId,
+                tarballPath: snapshot.tarballPath,
+                retentionDays: 30
+            });
+            const queuePayload = {
+                snapshot_id: snapshot.tag,
+                snapshot_commit: snapshot.commitSha,
+                diff_path: diffPath,
+                prompt_path: promptPath,
+                execution_history_path: executionHistoryPath,
+                manifest_path: manifestPath
+            };
+            queuePayloadPath = join(learningDir, 'queue-payload.json');
+            await writeFile(queuePayloadPath, JSON.stringify(queuePayload, null, 2), 'utf8');
+            learning.snapshot = {
+                tag: snapshot.tag,
+                commit_sha: snapshot.commitSha,
+                tarball_path: relative(repoRoot, snapshot.tarballPath),
+                tarball_digest: snapshot.tarballDigest,
+                storage_path: relative(repoRoot, storagePath),
+                retention_days: 30,
+                status: 'captured',
+                attempts: attempt,
+                created_at: isoTimestamp(),
+                last_error: null
+            };
+            learning.queue = {
+                snapshot_id: snapshot.tag,
+                diff_path: diffPath,
+                prompt_path: promptPath,
+                execution_history_path: executionHistoryPath,
+                manifest_path: relative(repoRoot, manifestPath),
+                enqueued_at: isoTimestamp(),
+                payload_path: relative(repoRoot, queuePayloadPath),
+                status: 'queued'
+            };
+            if (learning.validation?.status === 'snapshot_failed') {
+                updateLearningValidation(manifest, 'pending');
+            }
+            return { manifest, snapshotPath, queuePayloadPath };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(`[learning] snapshot attempt ${attempt} failed: ${message}`);
+            learning.snapshot = {
+                tag: learning.snapshot?.tag ?? `learning-snapshot-${randomUUID()}`,
+                commit_sha: learning.snapshot?.commit_sha ?? 'unknown',
+                tarball_path: learning.snapshot?.tarball_path ?? 'unavailable',
+                tarball_digest: learning.snapshot?.tarball_digest ?? 'unavailable',
+                storage_path: learning.snapshot?.storage_path ??
+                    relative(repoRoot, join(storageRoot, safeTaskId, `${safeRunId}.tar.gz`)),
+                retention_days: 30,
+                status: 'snapshot_failed',
+                attempts: attempt,
+                created_at: learning.snapshot?.created_at ?? isoTimestamp(),
+                last_error: message
+            };
+            appendLearningAlert(manifest, {
+                type: 'snapshot_failed',
+                channel: 'slack',
+                target: alertTargets?.slack ?? '#learning-alerts',
+                message: `Snapshot attempt ${attempt} failed: ${message}`
+            });
+            appendLearningAlert(manifest, {
+                type: 'snapshot_failed',
+                channel: 'pagerduty',
+                target: alertTargets?.pagerduty ?? 'learning-pipeline',
+                message: `Snapshot attempt ${attempt} failed for ${taskId}/${runId}`
+            });
+            if (attempt >= maxAttempts) {
+                updateLearningValidation(manifest, 'snapshot_failed');
+                break;
+            }
+            const delayMs = backoffMs[Math.min(attempt - 1, backoffMs.length - 1)] ?? 500;
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    return { manifest, snapshotPath, queuePayloadPath };
+}
+async function createSnapshot(params) {
+    const { repoRoot, learningDir, runId } = params;
+    const commitSha = (await safeGit(['rev-parse', 'HEAD'], repoRoot)).trim();
+    const tag = `learning-snapshot-${randomUUID()}`;
+    await safeGit(['tag', tag, commitSha], repoRoot);
+    await mkdir(learningDir, { recursive: true });
+    const tarballPath = join(learningDir, `${runId}.tar.gz`);
+    const fileListPath = join(learningDir, 'snapshot-files.txt');
+    const { stdout: fileListRaw } = await execFileAsync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
+        cwd: repoRoot
+    });
+    const files = fileListRaw.split('\0').filter(Boolean);
+    await writeFile(fileListPath, files.join('\n'), 'utf8');
+    await execFileAsync('tar', ['-czf', tarballPath, '-C', repoRoot, '-T', fileListPath]);
+    const digest = await hashFile(tarballPath);
+    return { tag, commitSha, tarballPath, tarballDigest: digest };
+}
+async function hashFile(path) {
+    const raw = await readFile(path);
+    return createHash('sha256').update(raw).digest('hex');
+}
+async function persistSnapshot(params) {
+    const { uploader, storageRoot, taskId, runId, tarballPath, retentionDays } = params;
+    const key = join(taskId, `${runId}.tar.gz`);
+    const upload = uploader ?? filesystemUploader;
+    return upload({ storageRoot, key, file: tarballPath, retentionDays });
+}
+async function filesystemUploader(params) {
+    const { storageRoot, key, file } = params;
+    const destination = join(storageRoot, key);
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(file, destination);
+    return destination;
+}
+async function safeGit(args, cwd) {
+    const { stdout } = await execFileAsync('git', args, { cwd });
+    return stdout;
+}

package/dist/orchestrator/src/learning/manifest.js

@@ -0,0 +1,56 @@
+import { isoTimestamp } from '../cli/utils/time.js';
+const DEFAULT_VALIDATION = {
+    mode: 'per-task',
+    grouping: null,
+    status: 'pending',
+    reason: null,
+    log_path: null,
+    last_error: null,
+    git_status_path: null,
+    git_log_path: null
+};
+function normalizeValidation(validation) {
+    return {
+        ...DEFAULT_VALIDATION,
+        ...validation,
+        mode: validation?.mode ?? 'per-task',
+        grouping: validation?.grouping ?? null,
+        status: validation?.status ?? 'pending'
+    };
+}
+export function ensureLearningSection(manifest) {
+    if (!manifest.learning) {
+        manifest.learning = {
+            validation: { ...DEFAULT_VALIDATION },
+            alerts: [],
+            approvals: []
+        };
+        return manifest.learning;
+    }
+    manifest.learning.validation = normalizeValidation(manifest.learning.validation);
+    if (!Array.isArray(manifest.learning.alerts)) {
+        manifest.learning.alerts = [];
+    }
+    if (!Array.isArray(manifest.learning.approvals)) {
+        manifest.learning.approvals = [];
+    }
+    return manifest.learning;
+}
+export function appendLearningAlert(manifest, alert) {
+    const section = ensureLearningSection(manifest);
+    const next = {
+        ...alert,
+        created_at: alert.created_at ?? isoTimestamp()
+    };
+    section.alerts = [...(section.alerts ?? []), next];
+    return next;
+}
+export function updateLearningValidation(manifest, status, updates = {}) {
+    const section = ensureLearningSection(manifest);
+    section.validation = {
+        ...normalizeValidation(section.validation),
+        ...updates,
+        status
+    };
+    return section;
+}

package/dist/orchestrator/src/learning/runner.js

@@ -0,0 +1,177 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { isoTimestamp } from '../cli/utils/time.js';
+import { logger } from '../logger.js';
+import { sanitizeRunId } from '../persistence/sanitizeRunId.js';
+import { sanitizeTaskId } from '../persistence/sanitizeTaskId.js';
+import { appendLearningAlert, ensureLearningSection, updateLearningValidation } from './manifest.js';
+const DEFAULT_MANUAL_TEMPLATE = '.agent/task/templates/manual-scenario-template.md';
+export async function synthesizeScenario(options) {
+    const { manifest, taskId, runId, runsRoot, prompt = null, diff = null, executionHistory = [], templatePath = DEFAULT_MANUAL_TEMPLATE, maxAttempts = 2, grouping = null, alertTargets, pagerDutySeverity = 'none' } = options;
+    const learning = ensureLearningSection(manifest);
+    if (grouping && grouping.members.length > 0) {
+        learning.validation = {
+            mode: 'grouped',
+            grouping,
+            status: learning.validation?.status ?? 'pending'
+        };
+    }
+    else if (!learning.validation) {
+        learning.validation = { mode: 'per-task', grouping: null, status: 'pending' };
+    }
+    const safeTaskId = sanitizeTaskId(taskId);
+    const runDir = join(runsRoot, safeTaskId, 'cli', sanitizeRunId(runId));
+    const learningDir = join(runDir, 'learning');
+    await mkdir(learningDir, { recursive: true });
+    const attempts = (learning.scenario?.attempts ?? 0) + 1;
+    const inferred = inferEntrypoint(executionHistory, prompt, diff, templatePath);
+    if (inferred.command) {
+        const scenarioPath = join(learningDir, 'scenario.json');
+        const scenarioPayload = buildScenarioPayload(runId, inferred.command, {
+            prompt,
+            diff,
+            executionHistory
+        });
+        await writeFile(scenarioPath, JSON.stringify(scenarioPayload, null, 2), 'utf8');
+        learning.scenario = {
+            path: relative(process.cwd(), scenarioPath),
+            generated_at: isoTimestamp(),
+            source: inferred.source,
+            status: 'synthesized',
+            attempts,
+            partial_path: null,
+            manual_template: null,
+            approver: null,
+            reason: null
+        };
+        if (learning.validation?.status === 'needs_manual_scenario') {
+            updateLearningValidation(manifest, 'pending');
+        }
+        return { manifest, scenarioPath, partialPath: null };
+    }
+    if (attempts < maxAttempts) {
+        learning.scenario = {
+            path: null,
+            generated_at: null,
+            source: inferred.source,
+            status: 'pending',
+            attempts,
+            partial_path: null,
+            manual_template: null,
+            approver: null,
+            reason: 'insufficient signals; retrying heuristics'
+        };
+        logger.warn('[learning] scenario heuristics did not resolve entrypoint; will retry');
+        return { manifest, scenarioPath: null, partialPath: null };
+    }
+    const partialScenario = {
+        id: `learning-${sanitizeRunId(runId)}`,
+        fallback_reason: inferred.reason ?? 'heuristics exhausted',
+        prompt,
+        diff,
+        execution_history: executionHistory
+    };
+    const partialPath = join(learningDir, 'scenario.partial.json');
+    await writeFile(partialPath, JSON.stringify(partialScenario, null, 2), 'utf8');
+    learning.scenario = {
+        path: null,
+        generated_at: null,
+        source: inferred.source,
+        status: 'needs_manual_scenario',
+        attempts,
+        partial_path: relative(process.cwd(), partialPath),
+        manual_template: templatePath,
+        approver: null,
+        reason: inferred.reason ?? 'Heuristic synthesis failed twice'
+    };
+    updateLearningValidation(manifest, 'needs_manual_scenario');
+    appendLearningAlert(manifest, {
+        type: 'needs_manual_scenario',
+        channel: 'slack',
+        target: alertTargets?.slack ?? '#learning-alerts',
+        message: `Scenario synthesis needs manual input for ${taskId}/${runId}`
+    });
+    if (pagerDutySeverity && pagerDutySeverity !== 'none') {
+        appendLearningAlert(manifest, {
+            type: 'needs_manual_scenario',
+            channel: 'pagerduty',
+            target: alertTargets?.pagerduty ?? 'learning-pipeline',
+            message: `Manual scenario required (${pagerDutySeverity}) for ${taskId}/${runId}`
+        });
+    }
+    return { manifest, scenarioPath: null, partialPath: partialScenario ? partialPath : null };
+}
+function inferEntrypoint(executionHistory, prompt, diff, templatePath) {
+    const recentSuccess = [...executionHistory].reverse().find((entry) => entry.exitCode === 0 && entry.command);
+    if (recentSuccess?.command) {
+        return { source: 'execution_history', command: recentSuccess.command };
+    }
+    const promptCommand = extractCommandFromPrompt(prompt);
+    if (promptCommand) {
+        return { source: 'prompt', command: promptCommand };
+    }
+    const diffCommand = extractCommandFromDiff(diff);
+    if (diffCommand) {
+        return { source: 'diff', command: diffCommand };
+    }
+    return {
+        source: 'template',
+        command: null,
+        reason: `No command inferred; manual template (${templatePath}) required`
+    };
+}
+function extractCommandFromPrompt(prompt) {
+    if (!prompt)
+        return null;
+    const fenced = /`{3,}[^`]*\n([^`]+)\n`{3,}/m.exec(prompt);
+    if (fenced?.[1]) {
+        const candidate = fenced[1].trim().split('\n').find((line) => line.trim().length > 0);
+        if (candidate)
+            return candidate.trim();
+    }
+    const inline = /`([^`]+)`/.exec(prompt);
+    if (inline?.[1]) {
+        return inline[1].trim();
+    }
+    const dollar = /^\s*\$ ([^\n]+)/m.exec(prompt);
+    if (dollar?.[1]) {
+        return dollar[1].trim();
+    }
+    return null;
+}
+function extractCommandFromDiff(diff) {
+    if (!diff)
+        return null;
+    const match = /[+-]{3}\s+[ab]\/([^\n\r]+)/.exec(diff);
+    const path = match?.[1];
+    if (!path)
+        return null;
+    const normalized = path.trim();
+    const isTest = normalized.includes('.test.') ||
+        normalized.includes('.spec.') ||
+        normalized.includes('__tests__') ||
+        normalized.endsWith('.snap');
+    if (isTest) {
+        return `npm test ${normalized}`;
+    }
+    if (normalized.endsWith('.ts') || normalized.endsWith('.js')) {
+        return `npm test -- ${normalized}`;
+    }
+    return null;
+}
+function buildScenarioPayload(runId, command, context) {
+    return {
+        id: `learning-${sanitizeRunId(runId)}`,
+        entrypoint: command,
+        commands: [command],
+        validation: {
+            requiresCleanFixture: true
+        },
+        context: {
+            prompt: context.prompt,
+            diff: context.diff,
+            execution_history: context.executionHistory
+        },
+        generated_at: isoTimestamp()
+    };
+}

package/dist/orchestrator/src/learning/validator.js

@@ -0,0 +1,164 @@
+import { createWriteStream } from 'node:fs';
+import { exec, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative } from 'node:path';
+import { saveManifest } from '../cli/run/manifest.js';
+import { ensureLearningSection, updateLearningValidation } from './manifest.js';
+import { sanitizeTaskId } from '../persistence/sanitizeTaskId.js';
+import { sanitizeRunId } from '../persistence/sanitizeRunId.js';
+import { isoTimestamp } from '../cli/utils/time.js';
+import { logger } from '../logger.js';
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+export async function runScenarioValidation(options) {
+    const { manifest, repoRoot, runsRoot, taskId, runId, paths, scenarioPath } = options;
+    const learning = ensureLearningSection(manifest);
+    const scenarioLocation = scenarioPath ?? learning.scenario?.path ?? null;
+    if (!scenarioLocation) {
+        logger.debug('[learning] scenario validation skipped: no scenario path');
+        return { manifest, logPath: null };
+    }
+    const resolvedScenarioPath = isAbsolute(scenarioLocation)
+        ? scenarioLocation
+        : join(repoRoot, scenarioLocation);
+    let scenarioContents;
+    try {
+        scenarioContents = await readFile(resolvedScenarioPath, 'utf8');
+    }
+    catch (error) {
+        logger.warn(`[learning] scenario validation skipped: unable to read scenario ${resolvedScenarioPath}: ${error?.message ?? String(error)}`);
+        return { manifest, logPath: null };
+    }
+    let scenario;
+    try {
+        scenario = JSON.parse(scenarioContents);
+    }
+    catch (error) {
+        const reason = `Invalid scenario JSON: ${error?.message ?? String(error)}`;
+        updateLearningValidation(manifest, 'snapshot_failed', { reason, last_error: reason });
+        await saveManifest(paths, manifest);
+        return { manifest, logPath: null };
+    }
+    const commands = Array.isArray(scenario.commands)
+        ? scenario.commands.filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+        : [];
+    if (commands.length === 0) {
+        const reason = 'Scenario has no commands to validate';
+        updateLearningValidation(manifest, 'snapshot_failed', { reason, last_error: reason });
+        await saveManifest(paths, manifest);
+        return { manifest, logPath: null };
+    }
+    const learningDir = join(runsRoot, sanitizeTaskId(taskId), 'cli', sanitizeRunId(runId), 'learning');
+    await mkdir(learningDir, { recursive: true });
+    const logPath = join(learningDir, 'scenario-validation.log');
+    const relativeLogPath = relative(repoRoot, logPath);
+    const logStream = createWriteStream(logPath, { flags: 'a' });
+    const writeLog = (line) => logStream.write(`[${isoTimestamp()}] ${line}\n`);
+    writeLog(`Scenario: ${resolvedScenarioPath}`);
+    const requiresCleanFixture = Boolean(scenario.validation?.requiresCleanFixture);
+    let gitStatusPath = null;
+    let gitLogPath = null;
+    try {
+        if (requiresCleanFixture) {
+            const gitState = await collectGitState(repoRoot);
+            if (gitState.dirty) {
+                gitStatusPath = join(learningDir, 'validation-git-status.txt');
+                gitLogPath = join(learningDir, 'validation-git-log.txt');
+                await Promise.all([
+                    writeFile(gitStatusPath, gitState.statusOutput, 'utf8'),
+                    writeFile(gitLogPath, gitState.logOutput, 'utf8')
+                ]);
+                const reason = gitState.reason ?? 'Validation requires a clean fixture';
+                writeLog(reason);
+                updateLearningValidation(manifest, 'stalled_snapshot', {
+                    reason,
+                    log_path: relativeLogPath,
+                    last_error: reason,
+                    git_status_path: relative(repoRoot, gitStatusPath),
+                    git_log_path: relative(repoRoot, gitLogPath)
+                });
+                await saveManifest(paths, manifest);
+                return { manifest, logPath: relativeLogPath };
+            }
+        }
+        for (const command of commands) {
+            writeLog(`$ ${command}`);
+            const result = await runCommand(command, repoRoot);
+            if (result.stdout.trim()) {
+                writeLog(result.stdout.trimEnd());
+            }
+            if (result.stderr.trim()) {
+                writeLog(result.stderr.trimEnd());
+            }
+            if (result.exitCode !== 0) {
+                const reason = `Command "${command}" exited with code ${result.exitCode}`;
+                updateLearningValidation(manifest, 'snapshot_failed', {
+                    reason,
+                    log_path: relativeLogPath,
+                    last_error: result.stderr.trim() || reason
+                });
+                await saveManifest(paths, manifest);
+                return { manifest, logPath: relativeLogPath };
+            }
+        }
+        updateLearningValidation(manifest, 'validated', {
+            reason: null,
+            log_path: relativeLogPath,
+            last_error: null,
+            git_status_path: gitStatusPath ? relative(repoRoot, gitStatusPath) : null,
+            git_log_path: gitLogPath ? relative(repoRoot, gitLogPath) : null
+        });
+        await saveManifest(paths, manifest);
+        return { manifest, logPath: relativeLogPath };
+    }
+    finally {
+        logStream.end();
+    }
+}
+async function runCommand(command, cwd) {
+    try {
+        const { stdout, stderr } = await execAsync(command, {
+            cwd,
+            env: { ...process.env },
+            maxBuffer: 10 * 1024 * 1024
+        });
+        return { exitCode: 0, stdout: stdout ?? '', stderr: stderr ?? '' };
+    }
+    catch (error) {
+        const execError = error;
+        const exitCode = normalizeExitCode(execError.code);
+        return { exitCode, stdout: execError.stdout ?? '', stderr: execError.stderr ?? '' };
+    }
+}
+async function collectGitState(repoRoot) {
+    try {
+        const [statusOutput, logOutput] = await Promise.all([
+            execFileAsync('git', ['status', '--short'], { cwd: repoRoot }).then((result) => result.stdout),
+            execFileAsync('git', ['log', '-5', '--oneline'], { cwd: repoRoot }).then((result) => result.stdout)
+        ]);
+        const dirty = statusOutput.trim().length > 0;
+        return { dirty, statusOutput, logOutput };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            dirty: true,
+            statusOutput: `git status failed: ${message}`,
+            logOutput: `git log failed: ${message}`,
+            reason: 'Validation requires git metadata but repository is unavailable'
+        };
+    }
+}
+function normalizeExitCode(code) {
+    if (typeof code === 'number' && Number.isInteger(code)) {
+        return code;
+    }
+    if (typeof code === 'string') {
+        const parsed = Number.parseInt(code, 10);
+        if (Number.isInteger(parsed)) {
+            return parsed;
+        }
+    }
+    return 1;
+}

package/dist/orchestrator/src/logger.js

@@ -0,0 +1,20 @@
+/* eslint-disable patterns/prefer-logger-over-console */
+// Base logger lives at the bottom of the stack, so it writes to console directly to avoid recursive dependencies.
+const prefix = '[Codex-Orchestrator]';
+function format(message) {
+    return `${prefix} ${message}`;
+}
+export const logger = {
+    info(message, ...args) {
+        console.info(format(message), ...args);
+    },
+    warn(message, ...args) {
+        console.warn(format(message), ...args);
+    },
+    error(message, ...args) {
+        console.error(format(message), ...args);
+    },
+    debug(message, ...args) {
+        console.debug(format(message), ...args);
+    }
+};