@kbediako/codex-orchestrator 0.1.0

package/dist/orchestrator/src/cli/adapters/CommandPlanner.js

@@ -0,0 +1,164 @@
+import { PLANNER_EXECUTION_MODE_PARSER, resolveRequiresCloudPolicy } from '../../utils/executionMode.js';
+export class CommandPlanner {
+    pipeline;
+    options;
+    cachedPlan = null;
+    constructor(pipeline, options = {}) {
+        this.pipeline = pipeline;
+        this.options = options;
+    }
+    async plan(task) {
+        void task;
+        if (!this.cachedPlan) {
+            const items = this.pipeline.stages.map((stage, index) => this.buildPlanItem(stage, index));
+            const targetId = this.resolveTargetId(items);
+            const normalizedItems = items.map((item) => ({
+                ...item,
+                selected: item.id === targetId
+            }));
+            this.cachedPlan = {
+                items: normalizedItems,
+                notes: this.pipeline.description,
+                targetId: targetId ?? null
+            };
+        }
+        return clonePlanResult(this.cachedPlan);
+    }
+    buildPlanItem(stage, index) {
+        const stagePlanHints = extractStagePlanHints(stage);
+        const requiresCloud = resolveStageRequiresCloud(stage, stagePlanHints);
+        const runnable = resolveStageRunnable(stagePlanHints);
+        const metadata = {
+            pipelineId: this.pipeline.id,
+            stageId: stage.id,
+            stageKind: stage.kind,
+            index
+        };
+        if (stagePlanHints.aliases.length > 0) {
+            metadata.aliases = stagePlanHints.aliases;
+        }
+        if (stagePlanHints.defaultTarget) {
+            metadata.defaultTarget = true;
+        }
+        if (stagePlanHints.executionMode) {
+            metadata.executionMode = stagePlanHints.executionMode;
+        }
+        metadata.requiresCloud = requiresCloud;
+        return {
+            id: `${this.pipeline.id}:${stage.id}`,
+            description: stage.title,
+            requires_cloud: requiresCloud,
+            requiresCloud,
+            runnable,
+            metadata
+        };
+    }
+    resolveTargetId(items) {
+        const explicit = this.normalizeTargetId(this.options.targetStageId ?? null, items);
+        if (explicit) {
+            return explicit;
+        }
+        const flagged = items.find((item) => item.metadata?.defaultTarget === true);
+        if (flagged) {
+            return flagged.id;
+        }
+        const runnableItems = items.filter((item) => item.runnable !== false);
+        if (runnableItems.length > 0) {
+            return runnableItems[0].id;
+        }
+        return items[0]?.id ?? null;
+    }
+    normalizeTargetId(candidate, items) {
+        if (!candidate) {
+            return null;
+        }
+        const exact = items.find((item) => item.id === candidate);
+        if (exact) {
+            return exact.id;
+        }
+        const normalized = candidate.includes(':') ? candidate.split(':').pop() ?? candidate : candidate;
+        const lowerNormalized = normalized.toLowerCase();
+        for (const item of items) {
+            const stageId = item.metadata?.stageId?.toLowerCase();
+            if (stageId && stageId === lowerNormalized) {
+                return item.id;
+            }
+            const aliases = Array.isArray(item.metadata?.aliases)
+                ? item.metadata?.aliases
+                : [];
+            if (aliases.some((alias) => alias.toLowerCase() === lowerNormalized)) {
+                return item.id;
+            }
+        }
+        return null;
+    }
+}
+function extractStagePlanHints(stage) {
+    const stageRecord = stage;
+    const planConfig = stageRecord.plan ?? {};
+    const aliases = Array.isArray(planConfig.aliases)
+        ? planConfig.aliases.map((alias) => String(alias))
+        : [];
+    const defaultTarget = Boolean(planConfig.defaultTarget ?? planConfig.default ?? planConfig.primary);
+    const requiresCloud = typeof planConfig.requiresCloud === 'boolean'
+        ? planConfig.requiresCloud
+        : typeof planConfig.requires_cloud === 'boolean'
+            ? planConfig.requires_cloud
+            : undefined;
+    const rawExecutionMode = typeof planConfig.executionMode === 'string'
+        ? planConfig.executionMode
+        : typeof stageRecord.executionMode === 'string'
+            ? stageRecord.executionMode
+            : typeof stageRecord.execution_mode === 'string'
+                ? stageRecord.execution_mode
+                : typeof stageRecord.mode === 'string'
+                    ? stageRecord.mode
+                    : undefined;
+    const executionMode = typeof rawExecutionMode === 'string'
+        ? rawExecutionMode.trim().toLowerCase() || null
+        : null;
+    return {
+        runnable: planConfig.runnable,
+        defaultTarget,
+        aliases,
+        requiresCloud,
+        executionMode
+    };
+}
+function resolveStageRequiresCloud(stage, hints) {
+    const stageRecord = stage;
+    const requiresCloud = resolveRequiresCloudPolicy({
+        boolFlags: [
+            hints.requiresCloud,
+            typeof stageRecord.requires_cloud === 'boolean'
+                ? stageRecord.requires_cloud
+                : undefined,
+            typeof stageRecord.requiresCloud === 'boolean'
+                ? stageRecord.requiresCloud
+                : undefined
+        ],
+        metadata: {
+            executionMode: hints.executionMode ?? null,
+            mode: null
+        },
+        metadataOrder: ['executionMode'],
+        parseMode: PLANNER_EXECUTION_MODE_PARSER
+    });
+    return requiresCloud ?? false;
+}
+function resolveStageRunnable(hints) {
+    if (typeof hints.runnable === 'boolean') {
+        return hints.runnable;
+    }
+    return true;
+}
+function clonePlanResult(plan) {
+    return {
+        items: plan.items.map((item) => ({
+            ...item,
+            metadata: item.metadata ? { ...item.metadata } : undefined
+        })),
+        notes: plan.notes,
+        targetId: plan.targetId ?? null
+    };
+}

package/dist/orchestrator/src/cli/adapters/CommandReviewer.js

@@ -0,0 +1,32 @@
+export class CommandReviewer {
+    getResult;
+    constructor(getResult) {
+        this.getResult = getResult;
+    }
+    async review(input) {
+        void input;
+        const result = this.requireResult();
+        const summaryLines = [
+            result.success
+                ? 'Diagnostics pipeline succeeded.'
+                : 'Diagnostics pipeline failed — inspect manifest for details.',
+            `Manifest: ${result.manifestPath}`,
+            `Runner log: ${result.logPath}`
+        ];
+        const summary = summaryLines.join('\n');
+        return {
+            summary,
+            decision: {
+                approved: result.success,
+                feedback: result.notes.join('\n') || undefined
+            }
+        };
+    }
+    requireResult() {
+        const result = this.getResult();
+        if (!result) {
+            throw new Error('Pipeline result unavailable during reviewer stage.');
+        }
+        return result;
+    }
+}

package/dist/orchestrator/src/cli/adapters/CommandTester.js

@@ -0,0 +1,33 @@
+import { ensureGuardrailStatus } from '../run/manifest.js';
+export class CommandTester {
+    getResult;
+    constructor(getResult) {
+        this.getResult = getResult;
+    }
+    async test(input) {
+        const result = this.requireResult();
+        const guardrailStatus = ensureGuardrailStatus(result.manifest);
+        const reports = [
+            {
+                name: 'guardrails',
+                status: guardrailStatus.present ? 'passed' : 'failed',
+                details: guardrailStatus.present
+                    ? guardrailStatus.summary
+                    : guardrailStatus.recommendation ?? guardrailStatus.summary
+            }
+        ];
+        return {
+            subtaskId: input.build.subtaskId,
+            success: guardrailStatus.present && result.success,
+            reports,
+            runId: input.runId
+        };
+    }
+    requireResult() {
+        const result = this.getResult();
+        if (!result) {
+            throw new Error('Pipeline result unavailable during tester stage.');
+        }
+        return result;
+    }
+}

package/dist/orchestrator/src/cli/adapters/index.js

@@ -0,0 +1,4 @@
+export { CommandPlanner } from './CommandPlanner.js';
+export { CommandBuilder } from './CommandBuilder.js';
+export { CommandTester } from './CommandTester.js';
+export { CommandReviewer } from './CommandReviewer.js';

package/dist/orchestrator/src/cli/config/userConfig.js

@@ -0,0 +1,28 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { logger } from '../../logger.js';
+export async function loadUserConfig(env) {
+    const configPath = join(env.repoRoot, 'codex.orchestrator.json');
+    try {
+        const raw = await readFile(configPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        logger.info(`[codex-config] Loaded user config from ${configPath}`);
+        if (parsed && Array.isArray(parsed.pipelines)) {
+            return parsed;
+        }
+        return parsed ?? null;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            logger.warn(`[codex-config] Missing codex.orchestrator.json at ${configPath}`);
+            return null;
+        }
+        throw error;
+    }
+}
+export function findPipeline(config, id) {
+    if (!config?.pipelines) {
+        return null;
+    }
+    return config.pipelines.find((pipeline) => pipeline.id === id) ?? null;
+}

package/dist/orchestrator/src/cli/doctor.js

@@ -0,0 +1,48 @@
+import process from 'node:process';
+import { resolveOptionalDependency } from './utils/optionalDeps.js';
+const OPTIONAL_DEPENDENCIES = [
+    {
+        name: 'playwright',
+        install: 'npm install --save-dev playwright && npx playwright install'
+    },
+    { name: 'pngjs', install: 'npm install --save-dev pngjs' },
+    { name: 'pixelmatch', install: 'npm install --save-dev pixelmatch' },
+    { name: 'cheerio', install: 'npm install --save-dev cheerio' }
+];
+export function runDoctor(cwd = process.cwd()) {
+    const dependencies = OPTIONAL_DEPENDENCIES.map((entry) => {
+        const resolved = resolveOptionalDependency(entry.name, cwd);
+        if (resolved.path) {
+            return { name: entry.name, status: 'ok', source: resolved.source };
+        }
+        return {
+            name: entry.name,
+            status: 'missing',
+            source: null,
+            install: entry.install
+        };
+    });
+    const missing = dependencies.filter((dep) => dep.status === 'missing').map((dep) => dep.name);
+    return {
+        status: missing.length === 0 ? 'ok' : 'warning',
+        missing,
+        dependencies
+    };
+}
+export function formatDoctorSummary(result) {
+    const lines = [];
+    lines.push(`Status: ${result.status}`);
+    for (const dep of result.dependencies) {
+        if (dep.status === 'ok') {
+            const source = dep.source ? ` (${dep.source})` : '';
+            lines.push(`  - ${dep.name}: ok${source}`);
+        }
+        else {
+            lines.push(`  - ${dep.name}: missing`);
+            if (dep.install) {
+                lines.push(`    install: ${dep.install}`);
+            }
+        }
+    }
+    return lines;
+}

package/dist/orchestrator/src/cli/events/runEvents.js

@@ -0,0 +1,84 @@
+import { EventEmitter } from 'node:events';
+import { isoTimestamp } from '../utils/time.js';
+export class RunEventEmitter {
+    emitter = new EventEmitter({ captureRejections: false });
+    emit(event) {
+        this.emitter.emit(event.type, event);
+        this.emitter.emit('*', event);
+    }
+    on(type, listener) {
+        const wrapped = (payload) => listener(payload);
+        this.emitter.on(type, wrapped);
+        return () => {
+            this.emitter.off(type, wrapped);
+        };
+    }
+    dispose() {
+        this.emitter.removeAllListeners();
+    }
+}
+export class RunEventPublisher {
+    emitter;
+    context;
+    constructor(emitter, context) {
+        this.emitter = emitter;
+        this.context = context;
+    }
+    runStarted(stages, status) {
+        this.emit('run:started', {
+            pipelineId: this.context.pipelineId,
+            pipelineTitle: this.context.pipelineTitle,
+            manifestPath: this.context.manifestPath,
+            logPath: this.context.logPath,
+            status,
+            stages
+        });
+    }
+    stageStarted(payload) {
+        this.emit('stage:started', payload);
+    }
+    stageCompleted(payload) {
+        this.emit('stage:completed', payload);
+    }
+    runCompleted(payload) {
+        this.emit('run:completed', payload);
+    }
+    runError(payload) {
+        this.emit('run:error', payload);
+    }
+    log(payload) {
+        this.emit('log', payload);
+    }
+    toolCall(payload) {
+        this.emit('tool:call', payload);
+    }
+    emit(type, payload) {
+        if (!this.emitter) {
+            return;
+        }
+        const base = {
+            type: type,
+            timestamp: isoTimestamp(),
+            taskId: this.context.taskId,
+            runId: this.context.runId
+        };
+        const event = { ...base, ...payload };
+        this.emitter.emit(event);
+    }
+}
+export function snapshotStages(manifest, pipeline) {
+    return manifest.commands.map((command) => {
+        const stage = pipeline.stages[command.index - 1];
+        return {
+            index: command.index,
+            id: command.id,
+            title: command.title,
+            kind: stage?.kind === 'subpipeline' ? 'subpipeline' : 'command',
+            status: command.status,
+            summary: command.summary,
+            exitCode: command.exit_code,
+            logPath: command.log_path,
+            subRunId: command.sub_run_id
+        };
+    });
+}

package/dist/orchestrator/src/cli/exec/command.js

@@ -0,0 +1,56 @@
+import { serializeRunSummaryEvent } from '../../../../packages/shared/events/serializer.js';
+import { appendMetricsEntry } from '../metrics/metricsRecorder.js';
+import { resolveTfgrpoContext } from './tfgrpo.js';
+import { bootstrapExecContext } from './context.js';
+import { runExecStage } from './stageRunner.js';
+import { finalizeCommandLifecycle } from './finalization.js';
+import { handleTfgrpoArtifacts } from './tfgrpoArtifacts.js';
+import { buildExecRunSummary, createRunSummaryPayload, emitCommandError, persistRunOutputs, renderRunOutput } from './summary.js';
+import { deliverNotifications, flushTelemetry, recordSummaryTelemetry, shutdownSinks } from './telemetry.js';
+import { maybeTriggerLearning } from './learning.js';
+export async function executeExecCommand(context, invocation) {
+    if (!invocation.command) {
+        throw new Error('exec command requires a command to run.');
+    }
+    const runContext = await bootstrapExecContext(context, invocation);
+    const stageResult = await runExecStage(runContext);
+    const finalization = await finalizeCommandLifecycle(runContext, stageResult);
+    const tfgrpoContext = resolveTfgrpoContext();
+    const runMetricSummary = await handleTfgrpoArtifacts(runContext, finalization, tfgrpoContext);
+    const summaryPayload = createRunSummaryPayload({
+        env: runContext.env,
+        paths: runContext.paths,
+        manifest: runContext.manifest,
+        runStatus: finalization.runStatus,
+        shellCommand: runContext.shellCommand,
+        argv: runContext.argv,
+        resultSummary: finalization.summarySnapshot,
+        toolRecord: finalization.toolRecord,
+        execEvents: runContext.execEvents,
+        exitCode: finalization.exitCode,
+        signal: finalization.signal,
+        notificationTargets: runContext.notificationSink.targets,
+        cwd: runContext.stage.cwd ?? null,
+        metrics: runMetricSummary
+    });
+    const summaryEvent = serializeRunSummaryEvent(summaryPayload);
+    await deliverNotifications(runContext, summaryPayload, summaryEvent);
+    recordSummaryTelemetry(runContext, summaryEvent);
+    renderRunOutput(runContext, summaryPayload, summaryEvent);
+    await flushTelemetry(runContext);
+    await persistRunOutputs(runContext, summaryEvent);
+    await appendMetricsEntry(runContext.env, runContext.paths, runContext.manifest, runContext.persister);
+    await maybeTriggerLearning(runContext, finalization.runStatus);
+    await runContext.persister.flush();
+    await shutdownSinks(runContext);
+    emitCommandError(runContext, finalization.commandError);
+    return buildExecRunSummary({
+        manifest: runContext.manifest,
+        summaryPayload,
+        summaryEvent,
+        shellCommand: runContext.shellCommand,
+        argv: runContext.argv,
+        events: runContext.execEvents,
+        toolRecord: finalization.toolRecord
+    });
+}

package/dist/orchestrator/src/cli/exec/context.js

@@ -0,0 +1,108 @@
+import process from 'node:process';
+import { bootstrapManifest } from '../run/manifest.js';
+import { generateRunId } from '../utils/runId.js';
+import { JsonlWriter } from '../utils/jsonlWriter.js';
+import { ExperienceStore } from '../../persistence/ExperienceStore.js';
+import { createTelemetrySink } from '../../../../packages/orchestrator/src/telemetry/otel-exporter.js';
+import { createNotificationSink } from '../../../../packages/orchestrator/src/notifications/index.js';
+import { ManifestPersister, persistManifest } from '../run/manifestPersister.js';
+export async function bootstrapExecContext(context, invocation) {
+    const argv = [invocation.command, ...(invocation.args ?? [])];
+    const shellCommand = buildShellCommand(argv);
+    const stdout = context.stdout ?? process.stdout;
+    const stderr = context.stderr ?? process.stderr;
+    const outputMode = invocation.outputMode;
+    if (outputMode === 'interactive') {
+        stdout.write(`$ ${shellCommand}\n`);
+    }
+    const runIdFactory = context.runIdFactory ?? generateRunId;
+    const env = context.env;
+    const experienceStore = new ExperienceStore({
+        outDir: env.outRoot,
+        runsDir: env.runsRoot
+    });
+    const runId = runIdFactory();
+    const pipeline = createPipeline(shellCommand, invocation, env);
+    const stage = pipeline.stages[0];
+    const { manifest, paths } = await bootstrapManifest(runId, {
+        env,
+        pipeline,
+        taskSlug: null,
+        approvalPolicy: null
+    });
+    const persister = new ManifestPersister({
+        manifest,
+        paths,
+        persistIntervalMs: Math.max(1000, manifest.heartbeat_interval_seconds * 1000)
+    });
+    manifest.status = 'in_progress';
+    await persistManifest(paths, manifest, persister, { force: true });
+    const telemetrySink = context.telemetrySink ?? createTelemetrySink({
+        endpoint: invocation.otelEndpoint,
+        enabled: Boolean(invocation.otelEndpoint)
+    });
+    const envNotifications = parseNotificationEnv(process.env.CODEX_ORCHESTRATOR_NOTIFY);
+    const notificationSink = context.notificationSink ??
+        createNotificationSink({
+            targets: invocation.notifyTargets,
+            envTargets: envNotifications
+        });
+    const jsonlWriter = outputMode === 'jsonl' ? new JsonlWriter(stdout) : null;
+    return {
+        env,
+        invocation,
+        argv,
+        shellCommand,
+        outputMode,
+        stdout,
+        stderr,
+        runId,
+        pipeline,
+        stage,
+        manifest,
+        paths,
+        persister,
+        telemetrySink,
+        notificationSink,
+        jsonlWriter,
+        experienceStore,
+        execEvents: [],
+        telemetryTasks: []
+    };
+}
+export function createPipeline(shellCommand, invocation, env) {
+    const stage = {
+        kind: 'command',
+        id: 'exec',
+        title: invocation.description ?? `Execute ${shellCommand}`,
+        command: shellCommand,
+        cwd: invocation.cwd ?? env.repoRoot,
+        env: invocation.env,
+        session: invocation.session
+    };
+    return {
+        id: 'exec',
+        title: 'CLI Exec Command',
+        stages: [stage],
+        guardrailsRequired: false
+    };
+}
+export function buildShellCommand(argv) {
+    return argv.map(shellEscape).join(' ');
+}
+export function parseNotificationEnv(value) {
+    if (!value) {
+        return null;
+    }
+    const tokens = value.split(',').map((entry) => entry.trim()).filter(Boolean);
+    return tokens.length ? tokens : null;
+}
+function shellEscape(value) {
+    if (value === '') {
+        return "''";
+    }
+    if (/^[A-Za-z0-9_/.:=-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/dist/orchestrator/src/cli/exec/experience.js

@@ -0,0 +1,77 @@
+const DEFAULT_POLICY = {
+    maxSummaryWords: 32,
+    rewardFloor: 0
+};
+export function summarizeTrajectory(request) {
+    const reward = request.reward ?? { gtScore: 0, relativeRank: 0 };
+    const summary = buildTrajectorySummary(request.frames, request.baseSummary);
+    const toolStats = request.frames.map(toToolStat);
+    return {
+        runId: request.runId,
+        taskId: request.taskId,
+        epoch: request.epoch,
+        groupId: request.groupId,
+        summary,
+        reward,
+        toolStats,
+        stampSignature: request.stampSignature,
+        domain: request.domain
+    };
+}
+export function optimizeExperience(input, policy = DEFAULT_POLICY) {
+    const limit = Math.max(1, policy.maxSummaryWords);
+    return {
+        ...input,
+        summary: truncateSummary(input.summary, limit),
+        reward: {
+            gtScore: Math.max(input.reward.gtScore, policy.rewardFloor ?? 0),
+            relativeRank: input.reward.relativeRank
+        }
+    };
+}
+export function framesFromToolMetrics(metrics, representativeEvent) {
+    return metrics.map((metric) => ({
+        event: representativeEvent,
+        tool: metric.tool,
+        tokens: metric.tokens,
+        costUsd: metric.costUsd,
+        latencyMs: metric.latencyMs
+    }));
+}
+export function formatExperienceInjections(experiences, slots) {
+    if (slots <= 0) {
+        return [];
+    }
+    return experiences.slice(0, slots).map((experience) => {
+        const rewardScore = (experience.reward.gtScore + experience.reward.relativeRank).toFixed(2);
+        const statText = experience.toolStats
+            .map((stat) => `${stat.tool}: ${stat.tokens}t/${stat.costUsd.toFixed(3)}usd/${Math.round(stat.latencyMs)}ms`)
+            .join('; ');
+        return `[exp ${experience.id} | epoch ${experience.epoch ?? 'n/a'} | reward ${rewardScore}] ${experience.summary32} (stats: ${statText})`;
+    });
+}
+function buildTrajectorySummary(frames, fallback) {
+    const terminal = frames[frames.length - 1];
+    if (terminal?.event.type === 'exec:end') {
+        const stdout = terminal.event.payload.stdout?.trim();
+        if (stdout) {
+            return stdout.split('\n').slice(0, 2).join(' ');
+        }
+    }
+    return fallback ?? 'TF-GRPO trajectory summary unavailable.';
+}
+function toToolStat(frame) {
+    return {
+        tool: frame.tool,
+        tokens: frame.tokens,
+        costUsd: frame.costUsd,
+        latencyMs: frame.latencyMs
+    };
+}
+function truncateSummary(value, maxWords) {
+    const tokens = value.trim().split(/\s+/u).filter(Boolean);
+    if (tokens.length <= maxWords) {
+        return tokens.join(' ');
+    }
+    return tokens.slice(0, maxWords).join(' ');
+}