@kbediako/codex-orchestrator 0.1.0

package/dist/orchestrator/src/sync/CloudRunsHttpClient.js

@@ -0,0 +1,82 @@
+export class CloudRunsHttpError extends Error {
+    status;
+    statusText;
+    body;
+    constructor(message, status, statusText, body) {
+        super(message);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.name = 'CloudRunsHttpError';
+    }
+}
+export class CloudRunsHttpClient {
+    broker;
+    baseUrl;
+    workspaceId;
+    bucket;
+    vaultPath;
+    scope;
+    fetchImpl;
+    constructor(options) {
+        this.broker = options.broker;
+        this.baseUrl = options.baseUrl ?? process.env.CODEX_CLOUD_BASE_URL ?? 'https://api.codex.cloud';
+        this.workspaceId = options.workspaceId ?? process.env.CODEX_CLOUD_WORKSPACE_ID ?? '';
+        this.bucket = options.bucket ?? process.env.CLOUD_SYNC_BUCKET ?? undefined;
+        this.vaultPath = options.vaultPath ?? process.env.CLOUD_SYNC_VAULT_PATH ?? undefined;
+        this.scope = options.scope ?? 'runs:write';
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        if (!this.workspaceId) {
+            throw new Error('CloudRunsHttpClient requires a workspace id (set CODEX_CLOUD_WORKSPACE_ID)');
+        }
+        if (!this.fetchImpl) {
+            throw new Error('CloudRunsHttpClient requires a fetch implementation');
+        }
+    }
+    async uploadManifest(payload) {
+        const token = await this.fetchToken();
+        const response = await this.fetchImpl(`${this.baseUrl}/workspaces/${this.workspaceId}/runs/import`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${token}`,
+                'x-idempotency-key': payload.idempotencyKey
+            },
+            body: JSON.stringify({
+                summary: payload.summary,
+                manifest: payload.manifest,
+                bucket: this.bucket,
+                idempotencyKey: payload.idempotencyKey
+            })
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new CloudRunsHttpError(`CloudRuns upload failed with status ${response.status}`, response.status, response.statusText, text);
+        }
+        let remoteId;
+        try {
+            const data = (await response.json());
+            remoteId = data.id ?? data.runId;
+        }
+        catch (error) {
+            // Ignore JSON parse errors; remote id stays undefined.
+            remoteId = undefined;
+        }
+        return {
+            status: 'success',
+            runId: payload.summary.runId,
+            remoteId
+        };
+    }
+    async fetchToken() {
+        const { token } = await this.broker.getToken({
+            service: 'codex-cloud',
+            scope: this.scope,
+            vaultPath: this.vaultPath
+        });
+        if (!token) {
+            throw new Error('Credential broker returned an empty token for codex-cloud');
+        }
+        return token;
+    }
+}

package/dist/orchestrator/src/sync/CloudSyncWorker.js

@@ -0,0 +1,206 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { CloudRunsHttpError } from './CloudRunsHttpClient.js';
+import { sanitizeTaskId } from '../persistence/sanitizeTaskId.js';
+import { sanitizeRunId } from '../persistence/sanitizeRunId.js';
+export class CloudSyncWorker {
+    bus;
+    client;
+    options;
+    runsDir;
+    outDir;
+    enabled;
+    maxRetries;
+    backoffMs;
+    unsubscribe;
+    manifestReadRetries;
+    manifestInitialDelayMs;
+    constructor(bus, client, options = {}) {
+        this.bus = bus;
+        this.client = client;
+        this.options = options;
+        this.runsDir = options.runsDir ?? join(process.cwd(), '.runs');
+        this.outDir = options.outDir ?? join(process.cwd(), 'out');
+        this.enabled = options.enabled ?? true;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.backoffMs = options.backoffMs ?? 250;
+        this.manifestReadRetries = options.manifestReadRetries ?? 5;
+        this.manifestInitialDelayMs = options.manifestInitialDelayMs ?? 50;
+    }
+    start() {
+        if (!this.enabled || this.unsubscribe) {
+            return;
+        }
+        this.unsubscribe = this.bus.on('run:completed', (event) => {
+            void this.handleRunCompleted(event.payload);
+        });
+    }
+    stop() {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = undefined;
+        }
+    }
+    async handleRunCompleted(summary) {
+        if (!this.enabled) {
+            return;
+        }
+        let manifest;
+        try {
+            manifest = await this.readManifestWithRetry(summary);
+        }
+        catch (error) {
+            this.options.onError?.(error, summary, 0);
+            await this.appendAuditLog({
+                level: 'error',
+                message: 'Failed to read manifest before sync',
+                summary,
+                details: serializeError(error)
+            });
+            return;
+        }
+        const idempotencyKey = createHash('sha256')
+            .update(`${summary.taskId}:${summary.runId}`)
+            .digest('hex');
+        let attempt = 0;
+        let delay = this.backoffMs;
+        while (attempt < this.maxRetries) {
+            attempt += 1;
+            try {
+                const result = await this.client.uploadManifest({
+                    summary,
+                    manifest,
+                    idempotencyKey
+                });
+                this.options.onSuccess?.(result, summary);
+                await this.appendAuditLog({
+                    level: 'info',
+                    message: 'Cloud sync completed',
+                    summary,
+                    details: { remoteId: result.remoteId, attempt }
+                });
+                return;
+            }
+            catch (error) {
+                this.options.onError?.(error, summary, attempt);
+                await this.appendAuditLog({
+                    level: 'error',
+                    message: 'Cloud sync attempt failed',
+                    summary,
+                    details: { attempt, error: serializeError(error) }
+                });
+                const shouldRetry = this.shouldRetry(error);
+                if (attempt >= this.maxRetries || !shouldRetry) {
+                    return;
+                }
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                delay *= 2;
+            }
+        }
+    }
+    buildManifestPath(summary) {
+        const safeTaskId = sanitizeTaskId(summary.taskId);
+        const safeRunId = sanitizeRunId(summary.runId);
+        const runDir = join(this.runsDir, safeTaskId, safeRunId);
+        return join(runDir, 'manifest.json');
+    }
+    async appendAuditLog(entry) {
+        const safeTaskId = sanitizeTaskId(entry.summary.taskId);
+        const logDir = join(this.outDir, safeTaskId, 'cloud-sync');
+        await mkdir(logDir, { recursive: true });
+        const logPath = join(logDir, 'audit.log');
+        const line = JSON.stringify({
+            timestamp: new Date().toISOString(),
+            taskId: entry.summary.taskId,
+            runId: entry.summary.runId,
+            level: entry.level,
+            message: entry.message,
+            details: entry.details
+        });
+        await appendFile(logPath, `${line}\n`, 'utf-8');
+    }
+    shouldRetry(error) {
+        if (this.options.retryDecider) {
+            return this.options.retryDecider(error);
+        }
+        if (error instanceof CloudRunsHttpError) {
+            if (error.status === 429) {
+                return true;
+            }
+            return error.status >= 500;
+        }
+        return true;
+    }
+    async readManifestWithRetry(summary) {
+        const manifestPath = this.buildManifestPath(summary);
+        let attempt = 0;
+        let delay = this.manifestInitialDelayMs;
+        let lastError;
+        let lastContents = null;
+        while (attempt < this.manifestReadRetries) {
+            attempt += 1;
+            try {
+                const contents = await readFile(manifestPath, 'utf-8');
+                lastContents = contents;
+                return JSON.parse(contents);
+            }
+            catch (error) {
+                lastError = error;
+                if (shouldRetryManifestRead(error) && attempt < this.manifestReadRetries) {
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    delay *= 2;
+                    continue;
+                }
+                break;
+            }
+        }
+        if (lastContents && lastError instanceof SyntaxError) {
+            const repaired = attemptJsonRecovery(lastContents);
+            if (repaired) {
+                try {
+                    const parsed = JSON.parse(repaired);
+                    await this.appendAuditLog({
+                        level: 'info',
+                        message: 'Recovered manifest from partial JSON',
+                        summary,
+                        details: { strategy: 'trim-trailing', attempts: attempt }
+                    });
+                    return parsed;
+                }
+                catch (parseError) {
+                    lastError = parseError;
+                }
+            }
+        }
+        throw lastError ?? new Error(`Manifest not available after ${this.manifestReadRetries} attempts`);
+    }
+}
+function shouldRetryManifestRead(error) {
+    if (error instanceof SyntaxError) {
+        return true;
+    }
+    const code = error?.code;
+    return code === 'ENOENT' || code === 'EBUSY' || code === 'EMFILE';
+}
+function attemptJsonRecovery(contents) {
+    const lastBrace = contents.lastIndexOf('}');
+    if (lastBrace === -1) {
+        return null;
+    }
+    const candidate = contents.slice(0, lastBrace + 1);
+    return candidate.trim().length > 0 ? candidate : null;
+}
+function serializeError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack
+        };
+    }
+    if (typeof error === 'object' && error !== null) {
+        return error;
+    }
+    return { message: String(error) };
+}

package/dist/orchestrator/src/sync/createCloudSyncWorker.js

@@ -0,0 +1,15 @@
+import { CloudRunsHttpClient } from './CloudRunsHttpClient.js';
+import { CloudSyncWorker } from './CloudSyncWorker.js';
+/**
+ * Convenience factory that wires the CloudRuns HTTP client to the CloudSync worker using
+ * the credential broker defined in the architecture spec. Callers can override client or
+ * worker options as needed.
+ */
+export function createCloudSyncWorker(params) {
+    const client = new CloudRunsHttpClient({
+        broker: params.broker,
+        ...(params.client ?? {})
+    });
+    const worker = new CloudSyncWorker(params.bus, client, params.worker);
+    return { worker, client };
+}

package/dist/orchestrator/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/orchestrator/src/utils/atomicWrite.js

@@ -0,0 +1,15 @@
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+let atomicWriteCounter = 0;
+export function buildAtomicTempPath(destination, now = Date.now, pid = process.pid) {
+    atomicWriteCounter = (atomicWriteCounter + 1) % Number.MAX_SAFE_INTEGER;
+    return `${destination}.tmp-${pid}-${now()}-${atomicWriteCounter}`;
+}
+export async function writeAtomicFile(destination, contents, options = {}) {
+    const tmpPath = buildAtomicTempPath(destination, options.now ?? Date.now, options.pid ?? process.pid);
+    if (options.ensureDir) {
+        await mkdir(dirname(destination), { recursive: true });
+    }
+    await writeFile(tmpPath, contents, options.encoding ?? 'utf8');
+    await rename(tmpPath, destination);
+}

package/dist/orchestrator/src/utils/errorMessage.js

@@ -0,0 +1,14 @@
+export function normalizeErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}

package/dist/orchestrator/src/utils/executionMode.js

@@ -0,0 +1,69 @@
+export function createExecutionModeParser(options) {
+    const trim = options.trim ?? false;
+    const lowercase = options.lowercase ?? true;
+    const truthy = new Set(options.truthyValues);
+    const falsy = new Set(options.falsyValues);
+    return (value) => {
+        const normalizedInput = trim ? value.trim() : value;
+        if (!normalizedInput) {
+            return null;
+        }
+        const normalized = lowercase ? normalizedInput.toLowerCase() : normalizedInput;
+        if (truthy.has(normalized)) {
+            return true;
+        }
+        if (falsy.has(normalized)) {
+            return false;
+        }
+        return null;
+    };
+}
+export const CLI_EXECUTION_MODE_PARSER = createExecutionModeParser({
+    trim: false,
+    lowercase: true,
+    truthyValues: ['cloud'],
+    falsyValues: ['mcp']
+});
+export const MANAGER_EXECUTION_MODE_PARSER = createExecutionModeParser({
+    trim: true,
+    lowercase: true,
+    truthyValues: ['cloud', 'true', '1', 'yes'],
+    falsyValues: ['mcp', 'false', '0', 'no']
+});
+export const PLANNER_EXECUTION_MODE_PARSER = createExecutionModeParser({
+    trim: false,
+    lowercase: true,
+    truthyValues: ['cloud'],
+    falsyValues: ['mcp']
+});
+export function resolveRequiresCloudFlag(options) {
+    for (const flag of options.boolFlags) {
+        if (flag === true) {
+            return true;
+        }
+        if (flag === false) {
+            return false;
+        }
+    }
+    for (const candidate of options.metadataModes) {
+        if (typeof candidate !== 'string') {
+            continue;
+        }
+        const parsed = options.parseMode(candidate);
+        if (parsed !== null) {
+            return parsed;
+        }
+    }
+    return null;
+}
+export function resolveRequiresCloudPolicy(options) {
+    const metadataModes = options.metadataOrder.map((key) => {
+        const value = options.metadata[key];
+        return typeof value === 'string' ? value : null;
+    });
+    return resolveRequiresCloudFlag({
+        boolFlags: options.boolFlags,
+        metadataModes,
+        parseMode: options.parseMode
+    });
+}

package/dist/packages/control-plane-schemas/src/index.js

@@ -0,0 +1 @@
+export { CONTROL_PLANE_RUN_REQUEST_SCHEMA, CONTROL_PLANE_RUN_REQUEST_VERSION, validateRunRequestV2 } from './run-request.js';