@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/orchestrator/src/cli/control/questionChildResolutionAdapter.js

@@ -0,0 +1,361 @@
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { logger } from '../../logger.js';
+const CHILD_CONTROL_TIMEOUT_MS = 15_000;
+const CSRF_HEADER = 'x-csrf-token';
+const DELEGATION_TOKEN_HEADER = 'x-codex-delegation-token';
+const DELEGATION_RUN_HEADER = 'x-codex-delegation-run-id';
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+export function createQuestionChildResolutionAdapter(input) {
+    const adapter = {
+        readDelegationHeaders: (req) => readDelegationHeaders(req),
+        validateDelegation: (auth) => input.validateDelegationToken(auth.token, input.readParentRunId(), auth.childRunId),
+        resolveManifestPath: (rawPath) => resolveRunManifestPath(rawPath, input.allowedRunRoots, 'from_manifest_path'),
+        readManifest: (path) => readJsonFile(path),
+        resolveChildQuestion: async (record, outcome) => {
+            const resolution = resolveChildQuestionAction(record, outcome, input.expiryFallback);
+            if (!resolution) {
+                return;
+            }
+            const manifestPath = record.from_manifest_path ?? null;
+            if (!manifestPath) {
+                return;
+            }
+            const shouldResolve = await isChildAwaitingQuestion(manifestPath, input.allowedRunRoots);
+            if (!shouldResolve) {
+                return;
+            }
+            try {
+                await callChildControlEndpoint({
+                    manifestPath,
+                    payload: {
+                        action: resolution.action,
+                        requested_by: 'parent',
+                        reason: resolution.reason
+                    },
+                    allowedRunRoots: input.allowedRunRoots,
+                    allowedBindHosts: input.allowedBindHosts
+                });
+            }
+            catch (error) {
+                const message = error?.message ?? String(error);
+                logger.warn(`Failed to resolve child question: ${message}`);
+                await input.emitResolutionFallback({
+                    question_id: record.question_id,
+                    outcome,
+                    action: resolution.action,
+                    reason: resolution.reason,
+                    non_fatal: true,
+                    error: message
+                });
+            }
+        },
+        queueQuestionResolutions: (records) => {
+            for (const record of records) {
+                if (record.status === 'queued') {
+                    continue;
+                }
+                void adapter.resolveChildQuestion(record, record.status).catch((error) => {
+                    const message = error?.message ?? String(error);
+                    logger.warn(`Failed to resolve child question: ${message}`);
+                    void input.emitResolutionFallback({
+                        question_id: record.question_id,
+                        outcome: record.status,
+                        action: 'unknown',
+                        reason: 'resolution_enqueue_failed',
+                        non_fatal: true,
+                        error: message
+                    });
+                });
+            }
+        }
+    };
+    return adapter;
+}
+export function readDelegationHeaders(req) {
+    const token = readHeaderValue(req.headers[DELEGATION_TOKEN_HEADER]);
+    const childRunId = readHeaderValue(req.headers[DELEGATION_RUN_HEADER]);
+    if (!token || !childRunId) {
+        return null;
+    }
+    return { token, childRunId };
+}
+export async function callChildControlEndpoint(input) {
+    input.assertCurrent?.();
+    const { baseUrl, token } = await loadControlEndpoint({
+        manifestPath: input.manifestPath,
+        allowedRunRoots: input.allowedRunRoots,
+        allowedBindHosts: input.allowedBindHosts
+    });
+    input.assertCurrent?.();
+    const url = new URL('/control/action', baseUrl);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), CHILD_CONTROL_TIMEOUT_MS);
+    let staleAssertionError = null;
+    const currentCheckTimer = input.assertCurrent === undefined
+        ? null
+        : setInterval(() => {
+            try {
+                input.assertCurrent?.();
+            }
+            catch (error) {
+                staleAssertionError = error;
+                controller.abort();
+            }
+        }, 50);
+    let res;
+    try {
+        input.assertCurrent?.();
+        res = await fetch(url.toString(), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+                [CSRF_HEADER]: token
+            },
+            body: JSON.stringify(input.payload),
+            signal: controller.signal
+        });
+        input.assertCurrent?.();
+    }
+    catch (error) {
+        if (staleAssertionError) {
+            throw staleAssertionError;
+        }
+        if (error?.name === 'AbortError') {
+            throw new Error('child control request timeout');
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        if (currentCheckTimer !== null) {
+            clearInterval(currentCheckTimer);
+        }
+    }
+    input.assertCurrent?.();
+    if (!res.ok) {
+        const message = await res.text();
+        input.assertCurrent?.();
+        throw new Error(`child control error: ${res.status} ${message}`);
+    }
+}
+function resolveChildQuestionAction(record, outcome, defaultExpiryFallback) {
+    const autoPause = record.auto_pause ?? true;
+    if (!autoPause || !record.from_manifest_path) {
+        return null;
+    }
+    if (outcome === 'expired') {
+        const fallback = record.expiry_fallback ?? defaultExpiryFallback ?? 'pause';
+        if (fallback === 'pause') {
+            return { action: 'pause', reason: 'question_expired' };
+        }
+        return {
+            action: fallback === 'resume' ? 'resume' : 'fail',
+            reason: 'question_expired'
+        };
+    }
+    if (outcome === 'answered') {
+        return { action: 'resume', reason: 'question_answered' };
+    }
+    if (outcome === 'dismissed') {
+        return { action: 'resume', reason: 'question_dismissed' };
+    }
+    return null;
+}
+async function isChildAwaitingQuestion(manifestPath, allowedRunRoots) {
+    if (!manifestPath) {
+        return false;
+    }
+    try {
+        const resolvedManifest = resolveRunManifestPath(manifestPath, allowedRunRoots, 'from_manifest_path');
+        const controlPath = resolve(dirname(resolvedManifest), 'control.json');
+        const snapshot = await readJsonFile(controlPath);
+        const latest = snapshot?.latest_action;
+        if (!latest || latest.action !== 'pause') {
+            return false;
+        }
+        return latest.reason === 'awaiting_question_answer';
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT') {
+            logger.warn(`Failed to inspect child question state: ${error?.message ?? error}`);
+        }
+        return false;
+    }
+}
+async function loadControlEndpoint(input) {
+    const resolvedManifest = resolveRunManifestPath(input.manifestPath, input.allowedRunRoots, 'from_manifest_path');
+    const runDir = dirname(resolvedManifest);
+    const endpointPath = resolve(runDir, 'control_endpoint.json');
+    const raw = await readFile(endpointPath, 'utf8');
+    const endpointInfo = JSON.parse(raw);
+    const baseUrl = validateControlBaseUrl(endpointInfo.base_url, input.allowedBindHosts);
+    const tokenPath = resolveControlTokenPath(endpointInfo.token_path, runDir);
+    const token = await readControlToken(tokenPath);
+    return { baseUrl, token };
+}
+function validateControlBaseUrl(raw, allowedHosts) {
+    if (typeof raw !== 'string' || raw.trim().length === 0) {
+        throw new Error('control base_url missing');
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error('control base_url invalid');
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error('control base_url invalid');
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error('control base_url invalid');
+    }
+    const allowed = normalizeAllowedHosts(allowedHosts);
+    if (allowed.size > 0 && !allowed.has(parsed.hostname.toLowerCase())) {
+        throw new Error('control base_url not permitted');
+    }
+    return parsed;
+}
+function normalizeAllowedHosts(allowedHosts) {
+    const values = allowedHosts && allowedHosts.length > 0 ? allowedHosts : Array.from(LOOPBACK_HOSTS);
+    return new Set(values.map((entry) => entry.toLowerCase()));
+}
+function resolveControlTokenPath(tokenPath, runDir) {
+    const fallback = resolve(runDir, 'control_auth.json');
+    const raw = typeof tokenPath === 'string' ? tokenPath.trim() : '';
+    const resolved = raw ? resolve(runDir, raw) : fallback;
+    if (!isPathWithinRoots(resolved, [runDir])) {
+        throw new Error('control auth path invalid');
+    }
+    return resolved;
+}
+async function readControlToken(tokenPath) {
+    const tokenRaw = await readFile(tokenPath, 'utf8');
+    const parsedToken = safeJsonParse(tokenRaw);
+    const tokenValue = parsedToken && typeof parsedToken === 'object' && !Array.isArray(parsedToken)
+        ? parsedToken.token
+        : null;
+    const token = typeof tokenValue === 'string' && tokenValue.trim().length > 0
+        ? tokenValue.trim()
+        : tokenRaw.trim();
+    if (!token) {
+        throw new Error('control auth token missing');
+    }
+    return token;
+}
+function resolveRunManifestPath(rawPath, allowedRoots, label) {
+    const resolved = resolve(rawPath);
+    const canonicalPath = realpathSafe(resolved);
+    assertRunManifestPath(canonicalPath, label);
+    if (!isPathWithinRoots(canonicalPath, allowedRoots)) {
+        throw new Error(`${label} not permitted`);
+    }
+    return canonicalPath;
+}
+function assertRunManifestPath(pathname, label) {
+    const resolvedPath = resolve(pathname);
+    if (basename(resolvedPath) !== 'manifest.json') {
+        throw new Error(`${label} invalid`);
+    }
+    const runDir = dirname(resolvedPath);
+    const cliDir = dirname(runDir);
+    if (basename(cliDir) !== 'cli') {
+        throw new Error(`${label} invalid`);
+    }
+    const taskDir = dirname(cliDir);
+    if (!basename(runDir) || !basename(taskDir)) {
+        throw new Error(`${label} invalid`);
+    }
+}
+function isPathWithinRoots(pathname, roots) {
+    const resolved = normalizePath(realpathSafe(pathname));
+    return roots.some((root) => {
+        const resolvedRoot = normalizePath(realpathSafe(root));
+        if (resolvedRoot === resolved) {
+            return true;
+        }
+        const relativePath = relative(resolvedRoot, resolved);
+        if (!relativePath) {
+            return true;
+        }
+        if (isAbsolute(relativePath)) {
+            return false;
+        }
+        return !relativePath.startsWith(`..${sep}`) && relativePath !== '..';
+    });
+}
+function realpathSafe(pathname) {
+    try {
+        return realpathSync(pathname);
+    }
+    catch {
+        return resolve(pathname);
+    }
+}
+function normalizePath(pathname) {
+    return process.platform === 'win32' ? pathname.toLowerCase() : pathname;
+}
+async function readJsonFile(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        logger.warn(`Failed to read JSON file ${path}: ${error?.message ?? error}`);
+        return null;
+    }
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function readHeaderValue(value) {
+    if (Array.isArray(value)) {
+        const values = [];
+        for (const entry of value) {
+            if (typeof entry !== 'string') {
+                continue;
+            }
+            const parts = entry.split(',');
+            for (const part of parts) {
+                const trimmed = part.trim();
+                if (trimmed) {
+                    values.push(trimmed);
+                }
+            }
+        }
+        return readUniqueHeaderValue(values);
+    }
+    if (typeof value === 'string') {
+        const parts = value.split(',');
+        const values = [];
+        for (const part of parts) {
+            const trimmed = part.trim();
+            if (trimmed) {
+                values.push(trimmed);
+            }
+        }
+        return readUniqueHeaderValue(values);
+    }
+    return null;
+}
+function readUniqueHeaderValue(values) {
+    if (values.length === 0) {
+        return null;
+    }
+    const unique = new Set(values);
+    if (unique.size > 1) {
+        return null;
+    }
+    return values[0];
+}

package/dist/orchestrator/src/cli/control/questionQueueController.js

@@ -0,0 +1,181 @@
+import { runQuestionReadSequence } from './questionReadSequence.js';
+export async function handleQuestionQueueRequest(context) {
+    const method = context.req.method ?? 'GET';
+    const pathname = new URL(context.req.url ?? '/', 'http://localhost').pathname;
+    if (pathname === '/questions' && method === 'GET') {
+        const result = await runQuestionReadSequence({
+            listQuestions: () => context.questionQueue.list(),
+            expireQuestions: () => context.expireQuestions()
+        });
+        context.queueQuestionResolutions(result.retryCandidates);
+        writeQuestionResponse(context.res, 200, { questions: result.questions });
+        return true;
+    }
+    if (pathname === '/questions/enqueue' && method === 'POST') {
+        const delegationAuth = context.readDelegationHeaders();
+        if (!delegationAuth || !context.validateDelegation(delegationAuth)) {
+            writeQuestionResponse(context.res, 403, { error: 'delegation_token_invalid' });
+            return true;
+        }
+        const body = await context.readRequestBody();
+        const prompt = readStringValue(body, 'prompt');
+        if (!prompt) {
+            writeQuestionResponse(context.res, 400, { error: 'missing_prompt' });
+            return true;
+        }
+        const autoPause = readBooleanValue(body, 'auto_pause', 'autoPause') ?? true;
+        const expiryFallback = parseExpiryFallback(readStringValue(body, 'expiry_fallback', 'expiryFallback'));
+        const rawFromManifest = readStringValue(body, 'from_manifest_path', 'fromManifestPath');
+        let resolvedFromManifest = null;
+        if (rawFromManifest) {
+            try {
+                resolvedFromManifest = context.resolveManifestPath(rawFromManifest);
+            }
+            catch {
+                writeQuestionResponse(context.res, 400, { error: 'invalid_manifest_path' });
+                return true;
+            }
+            const manifest = await context.readManifest(resolvedFromManifest);
+            if (!manifest || manifest.run_id !== delegationAuth.childRunId) {
+                writeQuestionResponse(context.res, 403, { error: 'delegation_run_mismatch' });
+                return true;
+            }
+        }
+        const record = context.questionQueue.enqueue({
+            parentRunId: context.getParentRunId(),
+            fromRunId: delegationAuth.childRunId,
+            fromManifestPath: resolvedFromManifest ?? null,
+            prompt,
+            urgency: parseUrgency(readStringValue(body, 'urgency')),
+            expiresInMs: readNumberValue(body, 'expires_in_ms', 'expiresInMs'),
+            autoPause,
+            expiryFallback
+        });
+        await context.persistQuestions();
+        await context.emitQuestionQueued(record);
+        context.publishRuntime('questions.enqueue');
+        writeQuestionResponse(context.res, 200, record);
+        return true;
+    }
+    if (pathname === '/questions/answer' && method === 'POST') {
+        const body = await context.readRequestBody();
+        const questionId = readStringValue(body, 'question_id', 'questionId');
+        const answer = readStringValue(body, 'answer');
+        if (!questionId || !answer) {
+            writeQuestionResponse(context.res, 400, { error: 'missing_question_or_answer' });
+            return true;
+        }
+        try {
+            context.questionQueue.answer(questionId, answer, readStringValue(body, 'answered_by', 'answeredBy') ?? 'user');
+        }
+        catch (error) {
+            const message = error?.message ?? 'question_invalid';
+            writeQuestionResponse(context.res, message === 'question_not_found' ? 404 : 409, { error: message });
+            return true;
+        }
+        await context.persistQuestions();
+        const record = context.questionQueue.get(questionId);
+        if (record) {
+            await context.emitQuestionAnswered(record);
+            await context.resolveChildQuestion(record, record.status);
+        }
+        context.publishRuntime('questions.answer');
+        writeQuestionResponse(context.res, 200, { status: 'answered' });
+        return true;
+    }
+    if (pathname === '/questions/dismiss' && method === 'POST') {
+        const body = await context.readRequestBody();
+        const questionId = readStringValue(body, 'question_id', 'questionId');
+        if (!questionId) {
+            writeQuestionResponse(context.res, 400, { error: 'missing_question_id' });
+            return true;
+        }
+        try {
+            context.questionQueue.dismiss(questionId, readStringValue(body, 'dismissed_by', 'dismissedBy') ?? 'user');
+        }
+        catch (error) {
+            const message = error?.message ?? 'question_invalid';
+            writeQuestionResponse(context.res, message === 'question_not_found' ? 404 : 409, { error: message });
+            return true;
+        }
+        await context.persistQuestions();
+        const record = context.questionQueue.get(questionId);
+        if (record) {
+            await context.emitQuestionDismissed(record);
+            await context.resolveChildQuestion(record, record.status);
+        }
+        context.publishRuntime('questions.dismiss');
+        writeQuestionResponse(context.res, 200, { status: 'dismissed' });
+        return true;
+    }
+    if (pathname.startsWith('/questions/') && method === 'GET') {
+        await context.expireQuestions();
+        const delegationAuth = context.readDelegationHeaders();
+        if (delegationAuth && !context.validateDelegation(delegationAuth)) {
+            writeQuestionResponse(context.res, 403, { error: 'delegation_token_invalid' });
+            return true;
+        }
+        const questionId = pathname.split('/').pop();
+        const record = questionId ? context.questionQueue.get(questionId) : null;
+        if (!record) {
+            writeQuestionResponse(context.res, 404, { error: 'not_found' });
+            return true;
+        }
+        if (delegationAuth && record.from_run_id !== delegationAuth.childRunId) {
+            writeQuestionResponse(context.res, 403, { error: 'delegation_scope_mismatch' });
+            return true;
+        }
+        writeQuestionResponse(context.res, 200, record);
+        return true;
+    }
+    return false;
+}
+function writeQuestionResponse(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function readStringValue(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function readNumberValue(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            return value;
+        }
+        if (typeof value === 'string' && value.trim().length > 0) {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed)) {
+                return parsed;
+            }
+        }
+    }
+    return undefined;
+}
+function readBooleanValue(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'boolean') {
+            return value;
+        }
+    }
+    return undefined;
+}
+function parseUrgency(value) {
+    if (value === 'low' || value === 'med' || value === 'high') {
+        return value;
+    }
+    return 'med';
+}
+function parseExpiryFallback(value) {
+    if (value === 'pause' || value === 'resume' || value === 'fail') {
+        return value;
+    }
+    return undefined;
+}

package/dist/orchestrator/src/cli/control/questionReadRetryDeduplication.js

@@ -0,0 +1,9 @@
+export function createQuestionReadRetrySelector(beforeExpiry) {
+    const statusBeforeRead = new Map(beforeExpiry.map((record) => [record.question_id, record.status]));
+    return (afterExpiry) => afterExpiry.filter((record) => {
+        if (record.status === 'queued') {
+            return false;
+        }
+        return !(statusBeforeRead.get(record.question_id) === 'queued' && record.status === 'expired');
+    });
+}

package/dist/orchestrator/src/cli/control/questionReadSequence.js

@@ -0,0 +1,10 @@
+import { createQuestionReadRetrySelector } from './questionReadRetryDeduplication.js';
+export async function runQuestionReadSequence(context) {
+    const selectRetryCandidates = createQuestionReadRetrySelector(context.listQuestions());
+    await context.expireQuestions();
+    const questions = context.listQuestions();
+    return {
+        questions,
+        retryCandidates: selectRetryCandidates(questions)
+    };
+}

package/dist/orchestrator/src/cli/control/securityViolationController.js

@@ -0,0 +1,27 @@
+export async function handleSecurityViolationRequest(context) {
+    const method = context.req.method ?? 'GET';
+    const pathname = new URL(context.req.url ?? '/', 'http://localhost').pathname;
+    if (pathname !== '/security/violation' || method !== 'POST') {
+        return false;
+    }
+    const body = await context.readRequestBody();
+    await context.emitSecurityViolation({
+        kind: readStringValue(body, 'kind') ?? 'unknown',
+        summary: readStringValue(body, 'summary') ?? 'security_violation',
+        severity: readStringValue(body, 'severity') ?? 'high',
+        related_request_id: readStringValue(body, 'related_request_id', 'relatedRequestId') ?? null,
+        details_redacted: true
+    });
+    context.res.writeHead(200, { 'Content-Type': 'application/json' });
+    context.res.end(JSON.stringify({ status: 'recorded' }));
+    return true;
+}
+function readStringValue(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}