@kbediako/codex-orchestrator 0.1.0

package/dist/packages/orchestrator/src/notifications/index.js

@@ -0,0 +1,74 @@
+export function createNotificationSink(options = {}) {
+    const targets = resolveTargets(options.targets, options.envTargets, options.configTargets);
+    if (targets.length === 0) {
+        return new NoopNotificationSink();
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const dispatcher = options.dispatcher ?? createHttpDispatcher(fetchImpl);
+    return new HttpNotificationSink(targets, dispatcher, options.logger ?? console);
+}
+class NoopNotificationSink {
+    targets;
+    constructor(targets = []) {
+        this.targets = targets;
+    }
+    async notify() {
+        return { delivered: [], failures: [] };
+    }
+    async shutdown() {
+        // no-op
+    }
+}
+class HttpNotificationSink {
+    targets;
+    dispatcher;
+    logger;
+    constructor(targets, dispatcher, logger) {
+        this.targets = targets;
+        this.dispatcher = dispatcher;
+        this.logger = logger;
+    }
+    async notify(summary) {
+        const delivered = [];
+        const failures = [];
+        await Promise.all(this.targets.map(async (target) => {
+            try {
+                await this.dispatcher(target, summary);
+                delivered.push(target);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                failures.push({ target, error: message });
+                this.logger.warn(`Notification delivery failed for ${target}: ${message}`);
+            }
+        }));
+        return { delivered, failures };
+    }
+    async shutdown() {
+        // nothing to clean up yet
+    }
+}
+function resolveTargets(cliTargets, envTargets, configTargets) {
+    const source = cliTargets?.length ? cliTargets : envTargets?.length ? envTargets : configTargets ?? [];
+    const normalized = source.map((target) => target.trim()).filter(Boolean);
+    return Array.from(new Set(normalized));
+}
+function createHttpDispatcher(fetchImpl) {
+    if (!fetchImpl) {
+        return async () => {
+            throw new Error('Notifications disabled: fetch API unavailable');
+        };
+    }
+    return async (target, summary) => {
+        const response = await fetchImpl(target, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify(summary)
+        });
+        if (!response.ok) {
+            throw new Error(`Notification endpoint responded with status ${response.status}`);
+        }
+    };
+}

package/dist/packages/orchestrator/src/telemetry/otel-exporter.js

@@ -0,0 +1,142 @@
+const DEFAULT_BACKOFF_MS = 500;
+const DEFAULT_MAX_BACKOFF_MS = 5_000;
+const DEFAULT_MAX_FAILURES = 3;
+export function createTelemetrySink(options = {}) {
+    const endpoint = options.endpoint ?? null;
+    const explicitlyDisabled = options.enabled === false;
+    if (!endpoint || explicitlyDisabled) {
+        return new NoopTelemetrySink();
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        return new NoopTelemetrySink();
+    }
+    return new OtelTelemetrySink({
+        endpoint,
+        headers: options.headers ?? {},
+        maxFailures: options.maxFailures ?? DEFAULT_MAX_FAILURES,
+        backoffMs: options.backoffMs ?? DEFAULT_BACKOFF_MS,
+        maxBackoffMs: options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS,
+        fetch: fetchImpl,
+        logger: options.logger ?? console
+    });
+}
+class NoopTelemetrySink {
+    async record() {
+        // no-op
+    }
+    async recordSummary() {
+        // no-op
+    }
+    async flush() {
+        // no-op
+    }
+    async shutdown() {
+        // no-op
+    }
+}
+class OtelTelemetrySink {
+    endpoint;
+    headers;
+    fetchImpl;
+    logger;
+    maxFailures;
+    backoffMs;
+    maxBackoffMs;
+    queue = [];
+    disabled = false;
+    consecutiveFailures = 0;
+    constructor(config) {
+        this.endpoint = config.endpoint;
+        this.headers = { 'content-type': 'application/json', ...config.headers };
+        this.fetchImpl = config.fetch;
+        this.logger = config.logger;
+        this.maxFailures = config.maxFailures;
+        this.backoffMs = config.backoffMs;
+        this.maxBackoffMs = config.maxBackoffMs;
+    }
+    async record(event) {
+        if (this.disabled) {
+            return;
+        }
+        this.queue.push(event);
+    }
+    async recordSummary(summary) {
+        if (this.disabled) {
+            return;
+        }
+        await this.flush();
+        try {
+            const dimensions = buildSummaryDimensions(summary.payload.metrics);
+            const payload = dimensions ? { kind: 'summary', summary, dimensions } : { kind: 'summary', summary };
+            await this.sendPayload(payload);
+        }
+        catch (error) {
+            this.handleFailure(error);
+        }
+    }
+    async flush() {
+        if (this.disabled || this.queue.length === 0) {
+            return;
+        }
+        const batch = this.queue.splice(0, this.queue.length);
+        try {
+            await this.sendPayload({ kind: 'events', events: batch });
+            this.consecutiveFailures = 0;
+        }
+        catch (error) {
+            this.queue.unshift(...batch);
+            this.handleFailure(error);
+        }
+    }
+    async shutdown() {
+        await this.flush();
+    }
+    async sendPayload(payload) {
+        if (this.consecutiveFailures > 0) {
+            const delay = Math.min(this.backoffMs * 2 ** (this.consecutiveFailures - 1), this.maxBackoffMs);
+            await wait(delay);
+        }
+        const response = await this.fetchImpl(this.endpoint, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(payload)
+        });
+        if (!response.ok) {
+            throw new Error(`Telemetry request failed with status ${response.status}`);
+        }
+    }
+    handleFailure(error) {
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= this.maxFailures) {
+            this.disabled = true;
+            this.logger.warn(`Telemetry disabled after ${this.consecutiveFailures} consecutive failures: ${String(error)}`);
+        }
+    }
+}
+function buildSummaryDimensions(metrics) {
+    if (!metrics) {
+        return undefined;
+    }
+    const dimensions = {
+        tool_cost_usd: metrics.costUsd,
+        latency_ms: metrics.latencyMs
+    };
+    if (metrics.tfgrpo) {
+        dimensions.tfgrpo_epoch = metrics.tfgrpo.epoch;
+        dimensions.tfgrpo_group_size = metrics.tfgrpo.groupSize;
+        dimensions.tfgrpo_group_id = metrics.tfgrpo.groupId;
+    }
+    if (metrics.perTool.length > 0) {
+        dimensions.tool_costs = Object.fromEntries(metrics.perTool.map((entry) => [entry.tool, entry.costUsd]));
+    }
+    return dimensions;
+}
+async function wait(ms) {
+    if (ms <= 0) {
+        return;
+    }
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/packages/orchestrator/src/tool-orchestrator.js

@@ -0,0 +1,161 @@
+export class SandboxRetryableError extends Error {
+    nextState;
+    constructor(message, nextState = undefined) {
+        super(message);
+        this.nextState = nextState;
+        this.name = 'SandboxRetryableError';
+    }
+}
+export class ApprovalRequiredError extends Error {
+    context;
+    policy;
+    constructor(message, context, policy) {
+        super(message);
+        this.context = context;
+        this.policy = policy;
+        this.name = 'ApprovalRequiredError';
+    }
+}
+export class ApprovalDeniedError extends Error {
+    context;
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'ApprovalDeniedError';
+    }
+}
+export class ToolInvocationFailedError extends Error {
+    record;
+    cause;
+    constructor(message, record, cause) {
+        super(message);
+        this.record = record;
+        this.cause = cause;
+        this.name = 'ToolInvocationFailedError';
+    }
+}
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BACKOFF_MS = 250;
+export class ToolOrchestrator {
+    approvalPolicy;
+    approvalCache;
+    approvalPrompter;
+    maxAttempts;
+    initialBackoffMs;
+    wait;
+    now;
+    constructor(options = {}) {
+        this.approvalPolicy = options.approvalPolicy ?? 'on-request';
+        this.approvalCache = options.approvalCache;
+        this.approvalPrompter = options.approvalPrompter;
+        this.maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+        this.initialBackoffMs = Math.max(0, options.initialBackoffMs ?? DEFAULT_BACKOFF_MS);
+        this.wait =
+            options.wait ??
+                ((ms) => new Promise((resolve) => {
+                    setTimeout(resolve, ms);
+                }));
+        this.now = options.now ?? (() => new Date());
+    }
+    async invoke(invocation) {
+        if (!invocation.id) {
+            throw new Error('Tool invocation id is required.');
+        }
+        if (!invocation.tool) {
+            throw new Error('Tool invocation tool name is required.');
+        }
+        const approvalSource = await this.resolveApproval(invocation);
+        let sandboxState = invocation.sandbox?.initialState ?? 'sandboxed';
+        const startedAt = this.now().toISOString();
+        let attempt = 1;
+        let lastError = null;
+        while (attempt <= this.maxAttempts) {
+            try {
+                const output = await invocation.run({ attempt, sandboxState });
+                const completedAt = this.now().toISOString();
+                const record = this.createRecord(invocation, approvalSource, sandboxState, attempt, completedAt, startedAt, 'succeeded');
+                return { output, record };
+            }
+            catch (error) {
+                lastError = error;
+                const decision = this.classifySandboxDecision(invocation.sandbox, error);
+                const reachedMaxAttempts = attempt >= this.maxAttempts;
+                if (!decision.retry || reachedMaxAttempts) {
+                    const completedAt = this.now().toISOString();
+                    const record = this.createRecord(invocation, approvalSource, decision.nextState ?? sandboxState, attempt, completedAt, startedAt, 'failed');
+                    throw new ToolInvocationFailedError(`Tool invocation ${invocation.id} failed after ${attempt} attempt${attempt === 1 ? '' : 's'}.`, record, error);
+                }
+                const delay = this.initialBackoffMs * 2 ** (attempt - 1);
+                await invocation.sandbox?.onRetry?.({
+                    attempt,
+                    delayMs: delay,
+                    sandboxState,
+                    error
+                });
+                await this.wait(delay);
+                sandboxState = decision.nextState ?? sandboxState;
+                attempt += 1;
+            }
+        }
+        // This branch is defensive; the loop should always return or throw earlier.
+        throw lastError instanceof Error ? lastError : new Error('Tool invocation aborted unexpectedly.');
+    }
+    async resolveApproval(invocation) {
+        if (!invocation.approvalRequired) {
+            return 'not-required';
+        }
+        if (!invocation.approvalKey) {
+            throw new Error(`Tool invocation ${invocation.id} requires an approvalKey when approvalRequired is true.`);
+        }
+        const context = {
+            toolId: invocation.tool,
+            description: invocation.description
+        };
+        const cached = this.approvalCache?.get(invocation.approvalKey);
+        if (cached?.granted) {
+            return 'cache';
+        }
+        if (this.approvalPolicy === 'never') {
+            throw new ApprovalRequiredError(`Approval required for ${invocation.tool} but approval policy forbids new prompts.`, context, this.approvalPolicy);
+        }
+        if (!this.approvalPrompter) {
+            throw new ApprovalRequiredError(`Approval required for ${invocation.tool} but no approval prompter is available.`, context, this.approvalPolicy);
+        }
+        const grant = await this.approvalPrompter.requestApproval(invocation.approvalKey, context);
+        if (!grant.granted) {
+            throw new ApprovalDeniedError(`Approval denied for ${invocation.tool}.`, context);
+        }
+        const stampedGrant = {
+            ...grant,
+            granted: true,
+            timestamp: grant.timestamp ?? this.now().toISOString()
+        };
+        this.approvalCache?.set(invocation.approvalKey, stampedGrant);
+        return 'prompt';
+    }
+    classifySandboxDecision(sandbox, error) {
+        const decision = sandbox?.classifyError?.(error);
+        if (decision) {
+            return decision;
+        }
+        if (error instanceof SandboxRetryableError) {
+            return { retry: true, nextState: error.nextState };
+        }
+        return { retry: false };
+    }
+    createRecord(invocation, approvalSource, sandboxState, attemptCount, completedAt, startedAt, status) {
+        const metadata = invocation.metadata ? { ...invocation.metadata } : undefined;
+        return {
+            id: invocation.id,
+            tool: invocation.tool,
+            approvalSource,
+            retryCount: Math.max(0, attemptCount - 1),
+            sandboxState,
+            status,
+            startedAt,
+            completedAt,
+            attemptCount,
+            ...(metadata ? { metadata } : {})
+        };
+    }
+}

package/dist/packages/sdk-node/src/orchestrator.js

@@ -0,0 +1,195 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream, mkdtempSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { EventEmitter } from 'node:events';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { PassThrough } from 'node:stream';
+import { tmpdir } from 'node:os';
+export class ExecClient {
+    cliPath;
+    cwd;
+    baseEnv;
+    constructor(options = {}) {
+        this.cliPath = options.cliPath ?? 'codex-orchestrator';
+        this.cwd = options.cwd ?? process.cwd();
+        this.baseEnv = { ...process.env, ...options.env };
+    }
+    run(options) {
+        if (!options.command) {
+            throw new Error('Exec command requires a command to run.');
+        }
+        const internal = this.normalizeOptions(options);
+        const child = spawn(internal.cliPath, buildCliArgs(internal), {
+            cwd: internal.spawnCwd,
+            env: internal.inheritedEnv,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        return new ExecRunHandle(this, internal, child);
+    }
+    normalizeOptions(options) {
+        const spawnCwd = this.cwd;
+        const mergedEnv = { ...this.baseEnv, ...options.env };
+        return {
+            ...options,
+            cliPath: this.cliPath,
+            spawnCwd,
+            inheritedEnv: mergedEnv
+        };
+    }
+}
+export class ExecRunHandle extends EventEmitter {
+    client;
+    baseOptions;
+    child;
+    eventsList = [];
+    stderrLines = [];
+    eventsStream;
+    stderrStream;
+    eventsFilePath;
+    stderrFilePath;
+    artifactRoot;
+    maxEventBuffer = 200;
+    maxStderrBuffer = 200;
+    streamsClosed = false;
+    summaryEvent = null;
+    resultPromise;
+    resolveResult;
+    rejectResult;
+    constructor(client, baseOptions, child) {
+        super();
+        this.client = client;
+        this.baseOptions = baseOptions;
+        this.child = child;
+        this.artifactRoot = mkdtempSync(join(tmpdir(), 'codex-exec-'));
+        this.eventsFilePath = join(this.artifactRoot, 'events.ndjson');
+        this.stderrFilePath = join(this.artifactRoot, 'stderr.log');
+        this.eventsStream = createWriteStream(this.eventsFilePath, { flags: 'a' });
+        this.stderrStream = createWriteStream(this.stderrFilePath, { flags: 'a' });
+        this.resultPromise = new Promise((resolve, reject) => {
+            this.resolveResult = resolve;
+            this.rejectResult = reject;
+        });
+        const stdout = child.stdout ?? new PassThrough();
+        const stderr = child.stderr ?? new PassThrough();
+        const rl = createInterface({ input: stdout, crlfDelay: Infinity });
+        rl.on('line', (line) => {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch (error) {
+                this.emit('warning', new Error(`Failed to parse JSONL line: ${trimmed}`));
+                return;
+            }
+            this.eventsStream.write(`${JSON.stringify(parsed)}\n`);
+            this.eventsList.push(parsed);
+            if (this.eventsList.length > this.maxEventBuffer) {
+                this.eventsList.shift();
+            }
+            this.emit('event', parsed);
+            if (parsed.type === 'run:summary') {
+                this.summaryEvent = parsed;
+                this.resolveResult(this.buildResult());
+                this.emit('summary', this.summaryEvent);
+            }
+        });
+        stderr.on('data', (chunk) => {
+            const text = chunk.toString();
+            this.stderrStream.write(text);
+            if (this.stderrLines.length >= this.maxStderrBuffer) {
+                this.stderrLines.shift();
+            }
+            this.stderrLines.push(text.trim());
+            this.emit('stderr', text);
+        });
+        child.once('error', (error) => {
+            this.closeStreams();
+            this.emit('error', error);
+            this.rejectResult(error);
+        });
+        child.once('close', (code, signal) => {
+            this.closeStreams();
+            this.emit('exit', { code, signal });
+            if (!this.summaryEvent) {
+                const error = new Error('Exec command exited without emitting a summary event.');
+                error.exitCode = code ?? null;
+                error.signal = signal ?? null;
+                this.rejectResult(error);
+            }
+        });
+    }
+    get events() {
+        return this.eventsList;
+    }
+    get summary() {
+        return this.summaryEvent;
+    }
+    get result() {
+        return this.resultPromise;
+    }
+    cancel(signal = 'SIGTERM') {
+        if (!this.child.killed) {
+            this.child.kill(signal);
+        }
+    }
+    retry(overrides = {}) {
+        const merged = {
+            ...this.baseOptions,
+            ...overrides
+        };
+        delete merged.cliPath;
+        delete merged.spawnCwd;
+        delete merged.inheritedEnv;
+        return this.client.run(merged);
+    }
+    buildResult() {
+        if (!this.summaryEvent) {
+            throw new Error('Summary not available');
+        }
+        const payload = this.summaryEvent.payload;
+        return {
+            summary: this.summaryEvent,
+            events: [...this.eventsList],
+            eventsPath: this.eventsFilePath,
+            exitCode: payload.result.exitCode ?? null,
+            status: payload.status,
+            manifestPath: payload.run.manifest,
+            rawStderr: [...this.stderrLines],
+            stderrPath: this.stderrFilePath
+        };
+    }
+    closeStreams() {
+        if (this.streamsClosed) {
+            return;
+        }
+        this.streamsClosed = true;
+        this.eventsStream.end();
+        this.stderrStream.end();
+        void rm(this.artifactRoot, { recursive: true, force: true }).catch(() => { });
+    }
+}
+function buildCliArgs(options) {
+    const args = ['exec', '--jsonl'];
+    if (options.taskId) {
+        args.push('--task', options.taskId);
+    }
+    if (options.cwd) {
+        args.push('--cwd', options.cwd);
+    }
+    if (options.otelEndpoint) {
+        args.push('--otel-endpoint', options.otelEndpoint);
+    }
+    if (options.notify) {
+        for (const target of options.notify) {
+            args.push('--notify', target);
+        }
+    }
+    args.push('--');
+    args.push(options.command, ...(options.args ?? []));
+    return args;
+}