@kbediako/codex-orchestrator 0.1.38 → 0.2.0

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

@@ -0,0 +1,402 @@
+/* eslint-disable patterns/prefer-logger-over-console */
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import process from 'node:process';
+import { resolveEnvironmentPaths } from '../../../scripts/lib/run-manifests.js';
+import { loadControlEndpoint, resolveRunManifestPath } from './delegationServer.js';
+import { shouldEnableControlStatusDashboard, startAttachedControlStatusDashboard } from './control/controlStatusDashboard.js';
+import { normalizeEnvironmentPaths, normalizeTaskId } from './run/environment.js';
+import { resolveRunPaths } from './run/runPaths.js';
+const DEFAULT_ATTACH_REFRESH_INTERVAL_MS = 1_000;
+export const DEFAULT_ATTACH_REQUEST_TIMEOUT_MS = 15_000;
+const CSRF_HEADER = 'x-csrf-token';
+export class CoStatusAttachRequestError extends Error {
+    kind;
+    statusCode;
+    constructor(kind, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'CoStatusAttachRequestError';
+        this.kind = kind;
+        this.statusCode = options.statusCode ?? null;
+    }
+}
+export async function runCoStatusAttachCliShell(params) {
+    if (params.flags.help !== undefined) {
+        params.printHelp();
+        return;
+    }
+    const format = readStringFlag(params.flags, 'format') === 'json' ? 'json' : 'text';
+    const refreshIntervalMs = readIntervalFlag(params.flags, 'refresh-interval-ms');
+    const target = await resolveAttachTarget(params.flags);
+    if (format === 'json') {
+        console.log(JSON.stringify({
+            status: 'ready',
+            mode: 'attach',
+            read_only: true,
+            base_url: target.baseUrl.toString(),
+            task_id: target.taskId,
+            run_id: target.runId,
+            run_dir: target.runDir,
+            manifest_path: target.manifestPath,
+            refresh_interval_ms: refreshIntervalMs
+        }, null, 2));
+        return;
+    }
+    if (!shouldEnableControlStatusDashboard({
+        format,
+        stdoutIsTTY: process.stdout.isTTY === true,
+        stderrIsTTY: process.stderr.isTTY === true,
+        term: process.env.TERM ?? null,
+        env: process.env
+    })) {
+        console.log(`CO STATUS attach target: ${target.baseUrl}`);
+        console.log(`Task: ${target.taskId ?? 'n/a'}`);
+        console.log(`Run: ${target.runId ?? 'n/a'}`);
+        console.log(`Run dir: ${target.runDir}`);
+        console.log(`Manifest: ${target.manifestPath}`);
+        return;
+    }
+    let dashboard = null;
+    const attachAbortController = new AbortController();
+    let activeTarget = target;
+    try {
+        dashboard = startAttachedControlStatusDashboard({
+            readDataset: async (signal) => await readUiDatasetWithEndpointRecovery({
+                flags: params.flags,
+                getTarget: () => activeTarget,
+                setTarget: (nextTarget) => {
+                    activeTarget = nextTarget;
+                },
+                signal: AbortSignal.any([attachAbortController.signal, signal])
+            }),
+            baseUrl: target.baseUrl.toString(),
+            taskId: target.taskId ?? 'unknown',
+            runId: target.runId ?? 'unknown',
+            runDir: target.runDir,
+            startPipelineId: 'attach-viewer',
+            refreshIntervalMs
+        });
+        await waitForSignal();
+    }
+    finally {
+        attachAbortController.abort();
+        dashboard?.stop();
+        await dashboard?.flush();
+    }
+}
+export async function resolveAttachTarget(flags) {
+    const manifestFlag = readStringFlag(flags, 'manifest-path');
+    const runDirFlag = readStringFlag(flags, 'run-dir');
+    const requestedTaskId = readStringFlag(flags, 'task');
+    const requestedRunId = readStringFlag(flags, 'run');
+    const locator = resolveAttachLocator({
+        manifestPath: manifestFlag,
+        runDir: runDirFlag,
+        taskId: requestedTaskId,
+        runId: requestedRunId
+    });
+    const resolvedManifestPath = resolveRunManifestPath(locator.manifestPath, undefined, 'manifest_path');
+    const { baseUrl, token } = await loadControlEndpoint(resolvedManifestPath);
+    const runDir = dirname(resolvedManifestPath);
+    const manifest = await readAttachManifest(resolvedManifestPath);
+    return {
+        manifestPath: resolvedManifestPath,
+        taskId: manifest.taskId ?? locator.taskId,
+        runId: manifest.runId ?? locator.runId,
+        runDir,
+        baseUrl,
+        token
+    };
+}
+function resolveAttachLocator(input) {
+    if (input.manifestPath) {
+        const manifestPath = resolve(input.manifestPath);
+        const derived = deriveTaskRunFromManifestPath(manifestPath);
+        return {
+            manifestPath,
+            taskId: input.taskId ?? derived.taskId,
+            runId: input.runId ?? derived.runId
+        };
+    }
+    if (input.runDir) {
+        const runDir = resolve(input.runDir);
+        const derived = deriveTaskRunFromRunDir(runDir);
+        return {
+            manifestPath: resolve(runDir, 'manifest.json'),
+            taskId: input.taskId ?? derived.taskId,
+            runId: input.runId ?? derived.runId
+        };
+    }
+    const baseEnv = normalizeEnvironmentPaths(resolveEnvironmentPaths());
+    const taskId = normalizeTaskId(input.taskId ?? 'local-mcp');
+    const runId = input.runId ?? 'control-host';
+    return {
+        manifestPath: resolveRunPaths({ ...baseEnv, taskId }, runId).manifestPath,
+        taskId,
+        runId
+    };
+}
+async function readAttachManifest(manifestPath) {
+    try {
+        const raw = await readFile(manifestPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return {
+            taskId: normalizeOptionalString(parsed.task_id),
+            runId: normalizeOptionalString(parsed.run_id)
+        };
+    }
+    catch {
+        return { taskId: null, runId: null };
+    }
+}
+export async function fetchUiDataset(baseUrl, token, options = {}) {
+    const url = new URL('/ui/data.json', baseUrl);
+    const controller = new AbortController();
+    const linkedSignal = options.signal;
+    const onAbort = () => controller.abort();
+    if (linkedSignal) {
+        if (linkedSignal.aborted) {
+            controller.abort();
+        }
+        else {
+            linkedSignal.addEventListener('abort', onAbort, { once: true });
+        }
+    }
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_ATTACH_REQUEST_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
+    let response;
+    try {
+        response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                [CSRF_HEADER]: token
+            },
+            signal: controller.signal
+        });
+    }
+    catch (error) {
+        if (error?.name === 'AbortError') {
+            if (linkedSignal?.aborted) {
+                throw new CoStatusAttachRequestError('cancelled', 'control-host ui request cancelled', { cause: error });
+            }
+            throw new CoStatusAttachRequestError('timeout', `control-host ui request timeout after ${requestTimeoutMs}ms`, { cause: error });
+        }
+        throw new CoStatusAttachRequestError('network', `control-host unavailable at ${url.toString()}: ${formatFetchNetworkError(error)}`, { cause: error });
+    }
+    finally {
+        clearTimeout(timer);
+        linkedSignal?.removeEventListener('abort', onAbort);
+    }
+    if (!response.ok) {
+        const statusText = response.statusText.trim() || 'HTTP error';
+        if (response.status === 401 || response.status === 403) {
+            throw new CoStatusAttachRequestError('auth', `control-host ui auth failed: ${response.status} ${statusText}; refresh control_auth.json or restart co-status attach against the current control-host.`, { statusCode: response.status });
+        }
+        throw new CoStatusAttachRequestError('http', `control-host ui request failed: ${response.status} ${statusText}`, { statusCode: response.status });
+    }
+    const payload = (await response.json());
+    if (!isOperatorDashboardDataset(payload)) {
+        throw new Error('control-host ui dataset invalid');
+    }
+    return payload;
+}
+export async function readUiDatasetWithEndpointRecovery(input) {
+    const previousTarget = input.getTarget();
+    try {
+        return await fetchUiDataset(previousTarget.baseUrl, previousTarget.token, {
+            signal: input.signal,
+            requestTimeoutMs: input.requestTimeoutMs
+        });
+    }
+    catch (error) {
+        if (isCancelledAttachRequestError(error)) {
+            throw error;
+        }
+        let resolvedTarget;
+        try {
+            resolvedTarget = await resolveAttachTarget(input.flags);
+        }
+        catch (resolveError) {
+            throw new Error(`${formatAttachRequestFailure(error, previousTarget)} Re-resolving control_endpoint.json failed: ${resolveError?.message ?? String(resolveError)}.`);
+        }
+        if (!isAttachTargetEndpointEquivalent(previousTarget, resolvedTarget)) {
+            input.setTarget(resolvedTarget);
+            try {
+                return await fetchUiDataset(resolvedTarget.baseUrl, resolvedTarget.token, {
+                    signal: input.signal,
+                    requestTimeoutMs: input.requestTimeoutMs
+                });
+            }
+            catch (retryError) {
+                if (isCancelledAttachRequestError(retryError)) {
+                    throw retryError;
+                }
+                throw new Error(`control-host endpoint rotated from ${previousTarget.baseUrl.toString()} to ${resolvedTarget.baseUrl.toString()}, but the refreshed endpoint is not readable. ${formatAttachRequestFailure(retryError, resolvedTarget, { endpointAlreadyRotated: true })}`);
+            }
+        }
+        if (input.recoverSameEndpointTimeout === true && isTimeoutAttachRequestError(error)) {
+            try {
+                return await fetchUiDataset(previousTarget.baseUrl, previousTarget.token, {
+                    signal: input.signal,
+                    requestTimeoutMs: input.requestTimeoutMs
+                });
+            }
+            catch (retryError) {
+                if (isCancelledAttachRequestError(retryError)) {
+                    throw retryError;
+                }
+                if (isTimeoutAttachRequestError(retryError)) {
+                    throw new Error(formatSameEndpointTimeoutFailure(retryError, previousTarget));
+                }
+                throw new Error(formatAttachRequestFailure(retryError, previousTarget));
+            }
+        }
+        throw new Error(formatAttachRequestFailure(error, previousTarget));
+    }
+}
+function isAttachTargetEndpointEquivalent(left, right) {
+    return left.baseUrl.toString() === right.baseUrl.toString() && left.token === right.token;
+}
+function isCancelledAttachRequestError(error) {
+    return error instanceof CoStatusAttachRequestError && error.kind === 'cancelled';
+}
+function isTimeoutAttachRequestError(error) {
+    return error instanceof CoStatusAttachRequestError && error.kind === 'timeout';
+}
+function formatSameEndpointTimeoutFailure(error, target) {
+    return [
+        `${error.message}.`,
+        `The current resolved /ui/data.json endpoint at ${target.baseUrl.toString()} timed out again after endpoint re-resolution returned the same endpoint/token; this is a same-endpoint current-endpoint timeout, not stale/dead endpoint ECONNREFUSED recovery or attach restart/rotation.`,
+        'Inspect local control-host polling.stuck, polling.restart_required, and running claim evidence before treating the host as unhealthy.'
+    ].join(' ');
+}
+function formatAttachRequestFailure(error, target, options = {}) {
+    if (error instanceof CoStatusAttachRequestError) {
+        if (error.kind === 'network') {
+            if (options.endpointAlreadyRotated) {
+                return `${error.message}. The refreshed control-host endpoint is still unreachable; wait for the new host to come up or rerun co-status attach.`;
+            }
+            return `stale endpoint after control-host restart; control-host unavailable; control_endpoint.json has not rotated to a reachable host. ${error.message}. Waiting for ${resolve(target.runDir, 'control_endpoint.json')} to rotate or rerun co-status attach.`;
+        }
+        if (error.kind === 'timeout') {
+            return `${error.message}. The control-host did not answer before the attach timeout; if restart is in progress, wait for endpoint rotation or rerun co-status attach.`;
+        }
+        return error.message;
+    }
+    return `control-host ui request failed: ${error?.message ?? String(error)}`;
+}
+function formatFetchNetworkError(error) {
+    const message = error?.message ?? String(error);
+    const code = extractFetchErrorCode(error);
+    return code ? `${message} (${code})` : message;
+}
+function extractFetchErrorCode(error) {
+    if (!error || typeof error !== 'object') {
+        return null;
+    }
+    const cause = error.cause;
+    if (!cause || typeof cause !== 'object') {
+        return null;
+    }
+    const code = cause.code;
+    return typeof code === 'string' && code.trim().length > 0 ? code : null;
+}
+function readStringFlag(flags, key) {
+    const value = flags[key];
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function readIntervalFlag(flags, key) {
+    const value = flags[key];
+    if (value === undefined) {
+        return DEFAULT_ATTACH_REFRESH_INTERVAL_MS;
+    }
+    if (value === true || typeof value !== 'string') {
+        throw new Error(`Invalid --${key}: expected integer milliseconds >= 250`);
+    }
+    const raw = value.trim();
+    if (raw.length === 0) {
+        throw new Error(`Invalid --${key}: expected integer milliseconds >= 250`);
+    }
+    if (!/^\d+$/u.test(raw)) {
+        throw new Error(`Invalid --${key}: expected integer milliseconds >= 250`);
+    }
+    const parsed = Number(raw);
+    if (!Number.isSafeInteger(parsed) || parsed < 250) {
+        throw new Error(`Invalid --${key}: expected integer milliseconds >= 250`);
+    }
+    return parsed;
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function isOperatorDashboardDataset(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (value.mode !== 'operator_dashboard' || value.read_only !== true) {
+        return false;
+    }
+    if (typeof value.generated_at !== 'string' || typeof value.host !== 'string') {
+        return false;
+    }
+    if (!isRecord(value.counts) ||
+        !isFiniteNumber(value.counts.running) ||
+        !isFiniteNumber(value.counts.retrying) ||
+        !isFiniteNumber(value.counts.issues)) {
+        return false;
+    }
+    if (!isRecord(value.totals) ||
+        !isNumberOrNull(value.totals.input_tokens) ||
+        !isNumberOrNull(value.totals.output_tokens) ||
+        !isNumberOrNull(value.totals.total_tokens) ||
+        !isFiniteNumber(value.totals.seconds_running)) {
+        return false;
+    }
+    return Array.isArray(value.running) && Array.isArray(value.retrying) && Array.isArray(value.issues);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isNumberOrNull(value) {
+    return value === null || isFiniteNumber(value);
+}
+function deriveTaskRunFromManifestPath(manifestPath) {
+    return deriveTaskRunFromRunDir(dirname(resolve(manifestPath)));
+}
+function deriveTaskRunFromRunDir(runDir) {
+    const resolvedRunDir = resolve(runDir);
+    const parts = resolvedRunDir.split(/[\\/]+/u).filter((part) => part.length > 0);
+    if (parts.length < 3) {
+        return { taskId: null, runId: null };
+    }
+    const runId = parts.at(-1) ?? null;
+    const cliSegment = parts.at(-2) ?? null;
+    const taskId = parts.at(-3) ?? null;
+    if (cliSegment !== 'cli') {
+        return { taskId: null, runId: null };
+    }
+    return { taskId, runId };
+}
+async function waitForSignal() {
+    await new Promise((resolve) => {
+        const handle = () => {
+            process.off('SIGINT', handle);
+            process.off('SIGTERM', handle);
+            resolve();
+        };
+        process.on('SIGINT', handle);
+        process.on('SIGTERM', handle);
+    });
+}