@kbediako/codex-orchestrator 0.1.38 → 0.2.1

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

@@ -5,11 +5,13 @@ export class CommandBuilder {
     }
     async build(input) {
         const result = await this.executePipeline(input);
+        const failure = resolveManifestFailure(result.manifest);
         return {
             subtaskId: input.target.id,
             artifacts: [
                 { path: result.manifestPath, description: 'CLI run manifest' },
                 { path: result.logPath, description: 'Runner log (ndjson)' },
+                ...collectCommandErrorArtifacts(result.manifest.commands),
                 ...(result.manifest.cloud_execution?.diff_path
                     ? [{ path: result.manifest.cloud_execution.diff_path, description: 'Cloud diff artifact' }]
                     : [])
@@ -18,6 +20,8 @@ export class CommandBuilder {
             runId: input.runId,
             success: result.success,
             notes: result.notes.join('\n') || undefined,
+            failureStage: failure.stage,
+            failureArtifactPath: failure.artifactPath,
             cloudExecution: result.manifest.cloud_execution
                 ? {
                     taskId: result.manifest.cloud_execution.task_id,
@@ -42,3 +46,49 @@ export class CommandBuilder {
         };
     }
 }
+function resolveManifestFailure(manifest) {
+    const statusDetailStage = extractStageFromStatusDetail(manifest.status_detail);
+    const cloudStage = extractCloudStageFromStatusDetail(manifest.status_detail);
+    const fallbackFailedCommand = statusDetailStage || hasStatusDetail(manifest.status_detail) ? null : firstFailedCommand(manifest.commands);
+    const cloudFailedStage = cloudStage && hasFailedCommand(manifest.commands, cloudStage) ? cloudStage : null;
+    const stage = statusDetailStage ?? cloudFailedStage ?? fallbackFailedCommand?.id ?? null;
+    const artifactPath = stage ? findFailedCommandErrorArtifact(manifest.commands, stage) : null;
+    return { stage, artifactPath };
+}
+function hasStatusDetail(statusDetail) {
+    return statusDetail != null && statusDetail.trim().length > 0;
+}
+function extractStageFromStatusDetail(statusDetail) {
+    const match = /^(?:stage|subpipeline):(.+):(?:failed|error)$/.exec(statusDetail ?? '');
+    return match?.[1] ?? null;
+}
+function extractCloudStageFromStatusDetail(statusDetail) {
+    const match = /^cloud:(.+):(?:failed|error)$/.exec(statusDetail ?? '');
+    return match?.[1] ?? null;
+}
+function firstFailedCommand(commands) {
+    return commands.find((command) => command.status === 'failed') ?? null;
+}
+function hasFailedCommand(commands, stage) {
+    return commands.some((command) => command.status === 'failed' && command.id === stage);
+}
+function findFailedCommandErrorArtifact(commands, stage) {
+    const matching = commands.find((command) => command.status === 'failed' && command.id === stage && command.error_file);
+    return matching?.error_file ?? null;
+}
+function collectCommandErrorArtifacts(commands) {
+    const seen = new Set();
+    const artifacts = [];
+    for (const command of commands) {
+        const errorFile = command.error_file;
+        if (!errorFile || seen.has(errorFile)) {
+            continue;
+        }
+        seen.add(errorFile);
+        artifacts.push({
+            path: errorFile,
+            description: `Command error artifact (${command.id})`
+        });
+    }
+    return artifacts;
+}

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

@@ -1,16 +1,18 @@
 import { PLANNER_EXECUTION_MODE_PARSER, resolveRequiresCloudPolicy } from '../../utils/executionMode.js';
+import { selectTaskMemoryRefs } from '../services/plannerMemory.js';
 export class CommandPlanner {
     pipeline;
     options;
     cachedPlan = null;
+    cachedPlanKey = 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 planKey = buildPlanCacheKey(task);
+        if (!this.cachedPlan || this.cachedPlanKey !== planKey) {
+            const items = this.pipeline.stages.map((stage, index) => this.buildPlanItem(stage, index, task));
             const targetId = this.resolveTargetId(items);
             const normalizedItems = items.map((item) => ({
                 ...item,
@@ -21,10 +23,11 @@ export class CommandPlanner {
                 notes: this.pipeline.description,
                 targetId: targetId ?? null
             };
+            this.cachedPlanKey = planKey;
         }
         return clonePlanResult(this.cachedPlan);
     }
-    buildPlanItem(stage, index) {
+    buildPlanItem(stage, index, task) {
         const stagePlanHints = extractStagePlanHints(stage);
         const requiresCloud = resolveStageRequiresCloud(stage, stagePlanHints);
         const runnable = resolveStageRunnable(stagePlanHints);
@@ -47,6 +50,18 @@ export class CommandPlanner {
             metadata.cloudEnvId = stagePlanHints.cloudEnvId;
         }
         metadata.requiresCloud = requiresCloud;
+        const selectedMemoryRefs = selectTaskMemoryRefs({
+            task,
+            pipeline: this.pipeline,
+            target: {
+                id: `${this.pipeline.id}:${stage.id}`,
+                description: stage.title
+            },
+            stage
+        });
+        if (selectedMemoryRefs.length > 0) {
+            metadata.selectedMemoryRefs = selectedMemoryRefs;
+        }
         return {
             id: `${this.pipeline.id}:${stage.id}`,
             description: stage.title,
@@ -178,3 +193,6 @@ function clonePlanResult(plan) {
         targetId: plan.targetId ?? null
     };
 }
+function buildPlanCacheKey(task) {
+    return JSON.stringify(task.memory?.refs ?? null);
+}

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

@@ -1,4 +1,4 @@
-import { diagnoseCloudFailure } from './cloudFailureDiagnostics.js';
+import { diagnoseCloudFailure, formatCloudFailureClass } from './cloudFailureDiagnostics.js';
 export class CommandReviewer {
     getResult;
     constructor(getResult) {
@@ -41,12 +41,12 @@ export class CommandReviewer {
                 ...(cloudExecution?.status_url ? [`Cloud status URL: ${cloudExecution.status_url}`] : [])
             ];
             if (!approved) {
-                summaryLines.push(`Failure class: ${diagnosis.category}`);
+                summaryLines.push(`Failure class: ${formatCloudFailureClass(diagnosis)}`);
                 summaryLines.push(`Guidance: ${diagnosis.guidance}`);
             }
             const feedbackLines = [cloudExecution?.error ?? (result.notes.join('\n') || undefined)].filter((line) => Boolean(line && line.trim().length > 0));
             if (!approved) {
-                feedbackLines.push(`Failure class: ${diagnosis.category}`);
+                feedbackLines.push(`Failure class: ${formatCloudFailureClass(diagnosis)}`);
                 feedbackLines.push(`Guidance: ${diagnosis.guidance}`);
             }
             return {

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

@@ -1,5 +1,5 @@
 import { ensureGuardrailStatus } from '../run/manifest.js';
-import { diagnoseCloudFailure } from './cloudFailureDiagnostics.js';
+import { diagnoseCloudFailure, formatCloudFailureClass } from './cloudFailureDiagnostics.js';
 export class CommandTester {
     getResult;
     constructor(getResult) {
@@ -49,7 +49,7 @@ export class CommandTester {
                     status: passed ? 'passed' : 'failed',
                     details: passed
                         ? failureDetails
-                        : `${failureDetails}\nFailure class: ${diagnosis.category}. ${diagnosis.guidance}`
+                        : `${failureDetails}\nFailure class: ${formatCloudFailureClass(diagnosis)}. ${diagnosis.guidance}`
                 }
             ];
             return {

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

@@ -1,44 +1,328 @@
+export function formatCloudFailureClass(diagnosis) {
+    return `${diagnosis.category} (${diagnosis.diagnostic_category})`;
+}
 const CLOUD_FAILURE_RULES = [
+    {
+        category: 'execution',
+        diagnostic_category: 'guardian_timeout',
+        patterns: [
+            'guardian timeout',
+            'guardian-timeout',
+            'guardian_timeout',
+            'guardian timed out',
+            'guardian review timeout',
+            'guardian review timed out'
+        ],
+        guidance: 'Guardian review timed out; retry or inspect timeout-specific Guardian guidance before treating it as a policy denial.'
+    },
+    {
+        category: 'execution',
+        diagnostic_category: 'guardian_policy_denial',
+        patterns: [
+            'guardian policy denial',
+            'guardian-policy-denial',
+            'guardian_policy_denial',
+            'guardian policy denied',
+            'guardian denied',
+            'guardian blocked'
+        ],
+        guidance: 'Guardian policy denied the request; inspect policy-denial guidance instead of retrying as a timeout.'
+    },
+    {
+        category: 'credentials',
+        diagnostic_category: 'cloud_connector_auth_drift',
+        patterns: [
+            'cloud connector auth drift',
+            'cloud-connector-auth-drift',
+            'cloud_connector_auth_drift',
+            'missing_github_connector_link',
+            'missing github connector link',
+            'github connection not found for user',
+            'github connection not found',
+            'github connector not found',
+            'github connector link missing',
+            'missing github connection',
+            'missing github connector'
+        ],
+        guidance: 'Repair or relink the GitHub connector for the current ChatGPT/Codex cloud account/environment, or record an explicit waiver before re-running cloud-canary gates.'
+    },
+    {
+        category: 'credentials',
+        diagnostic_category: 'cloud_denial',
+        patterns: [
+            'cloud denial',
+            'cloud-denial',
+            'cloud_denial',
+            'cloud denied',
+            'not allowed in cloud',
+            'cloud access denied',
+            'cloud execution denied'
+        ],
+        guidance: 'Codex Cloud rejected this run; verify the configured cloud environment, branch, and account permission for cloud execution.'
+    },
+    {
+        category: 'configuration',
+        diagnostic_category: 'environment_not_found',
+        patterns: ['environment_not_found', 'environment not found', 'is not visible to codex cloud'],
+        guidance: 'CODEX_CLOUD_ENV_ID is configured, but Codex Cloud could not resolve it. Fix the env id or choose an environment visible to this account.'
+    },
+    {
+        category: 'configuration',
+        diagnostic_category: 'environment_unavailable',
+        patterns: ['environment_unavailable', 'could not be verified by codex cloud'],
+        guidance: 'CODEX_CLOUD_ENV_ID is configured, but this account cannot use that environment right now. Verify visibility/permissions and retry.'
+    },
     {
         category: 'configuration',
-        patterns: ['cloud-env-missing', 'codex_cloud_env_id', 'no environment id is configured', '--env'],
+        diagnostic_category: 'env_config',
+        patterns: [
+            'env config',
+            'env-config',
+            'env_config',
+            'cloud-env-missing',
+            'codex_cloud_env_id',
+            'no_environment_id',
+            'no environment id is configured',
+            '--env'
+        ],
         guidance: 'Set CODEX_CLOUD_ENV_ID (or metadata.cloudEnvId) to a valid cloud environment id before re-running.'
     },
     {
         category: 'credentials',
-        patterns: ['unauthorized', 'forbidden', 'not logged in', 'login', 'api key', 'credential', 'token'],
-        guidance: 'Ensure Codex Cloud credentials are available to the runner and have access to the configured environment.'
+        diagnostic_category: 'auth_mismatch',
+        patterns: [
+            'auth mismatch',
+            'auth-mismatch',
+            'auth_mismatch',
+            'auth profile',
+            'profile mismatch',
+            'account mismatch',
+            'active account',
+            'active profile',
+            'unauthorized',
+            'forbidden',
+            'not logged in',
+            'login',
+            'api key',
+            'credential',
+            'auth token',
+            'access token',
+            'refresh token',
+            'bearer token',
+            'invalid token',
+            'expired token',
+            'token expired',
+            'missing token',
+            'token missing'
+        ],
+        guidance: 'Ensure the active Codex account/auth profile matches the cloud environment and has access to the configured environment.'
+    },
+    {
+        category: 'execution',
+        diagnostic_category: 'quota_rate_limit',
+        patterns: [
+            'quota_rate_limit',
+            'rate limit',
+            'rate-limit',
+            'rate_limited',
+            'rate_limit_exceeded',
+            'quota',
+            'too many requests',
+            'usage limit',
+            'usage_limit_reached'
+        ],
+        guidance: 'Codex account quota or rate-limit state is implicated; inspect account plan/rate-limit evidence and retry after limits reset.'
     },
     {
         category: 'connectivity',
+        diagnostic_category: 'network_connectivity',
         patterns: ['enotfound', 'econn', 'timed out', 'timeout', 'network', '502', '503', '504'],
         guidance: 'Cloud endpoint connectivity looks unstable; retry and inspect network/endpoint health.'
     }
 ];
 const TERMINAL_FAILURE_STATUSES = new Set(['failed', 'error', 'cancelled']);
+const MACHINE_READABLE_CLOUD_DETAILS = new Set([
+    'auth_mismatch',
+    'cloud_access_denied',
+    'cloud_denial',
+    'cloud_denied',
+    'cloud_env_missing',
+    'environment_not_found',
+    'environment_unavailable',
+    'cloud_execution_denied',
+    'cloud_connector_auth_drift',
+    'codex_cloud_env_id',
+    'env_config',
+    'guardian_policy_denial',
+    'guardian_timeout',
+    'github_connection_not_found',
+    'github_connector_not_found',
+    'missing_github_connector_link',
+    'no_environment_id',
+    'not_allowed_in_cloud',
+    'quota_rate_limit',
+    'rate_limit',
+    'rate_limit_exceeded',
+    'rate_limited',
+    'usage_limit_reached'
+]);
+function isEnvironmentNotFoundSignal(signal) {
+    const lowercase = signal.toLowerCase();
+    if (/\benvironment_not_found\b/u.test(lowercase)) {
+        return true;
+    }
+    if (!/\benvironment\s+(?:['"][^'"]+['"]|[^\s'"]+)\s+not\s+found\b/u.test(lowercase)) {
+        return false;
+    }
+    return (lowercase.includes('codex_cloud_env_id') ||
+        lowercase.includes('codex cloud env id') ||
+        lowercase.includes('is not visible to codex cloud') ||
+        lowercase.includes('could not be verified by codex cloud'));
+}
+function matchesCloudFailureRule(rule, lowercase, normalized) {
+    return rule.patterns.some((pattern) => {
+        const normalizedPattern = normalizeCloudFailureSignal(pattern);
+        return lowercase.includes(pattern) ||
+            (normalizedPattern.length >= 4 && normalized.includes(normalizedPattern));
+    });
+}
+function findCloudFailureRule(diagnosticCategory) {
+    return CLOUD_FAILURE_RULES.find((rule) => rule.diagnostic_category === diagnosticCategory) ?? null;
+}
+function findMatchedCloudFailureRule(diagnosticCategory, signal) {
+    const rule = findCloudFailureRule(diagnosticCategory);
+    if (!rule) {
+        return null;
+    }
+    const lowercase = signal.toLowerCase();
+    const normalized = normalizeCloudFailureSignal(signal);
+    return matchesCloudFailureRule(rule, lowercase, normalized) ? rule : null;
+}
+function maskEnvConfigIdentifierValues(normalizedSignal) {
+    return normalizedSignal
+        .replace(/\bcodex_cloud_env_id\s+(?:['"][^'"]+['"]|[^\s'"]+)/gu, 'codex_cloud_env_id <env-id>')
+        .replace(/\bcodex cloud env id\s+(?:['"][^'"]+['"]|[^\s'"]+)/gu, 'codex cloud env id <env-id>')
+        .replace(/\benvironment\s+(?:['"][^'"]+['"]|[^\s'"]+)\s+not\s+found\b/gu, 'environment <env-id> not found');
+}
+function hasStrongConnectivityContext(signal) {
+    const normalized = maskEnvConfigIdentifierValues(signal.toLowerCase());
+    return (normalized.includes('enotfound') ||
+        normalized.includes('econn') ||
+        normalized.includes('bad gateway') ||
+        normalized.includes('service unavailable') ||
+        normalized.includes('gateway timeout') ||
+        /\bnetwork\W{0,24}(?:error|failure|unreachable|unavailable|timeout|timed out|connection|connectivity)\b/u.test(normalized) ||
+        /\b(?:request|connection|endpoint|gateway|upstream|service)\W{0,24}(?:timed out|timeout)\b/u.test(normalized) ||
+        /\b(?:timed out|timeout)\W{0,24}(?:(?:while\s+)?(?:contacting|connecting|reaching|calling|waiting)|request|connection|endpoint|gateway|upstream|service|after)\b/u.test(normalized) ||
+        /\b(?:http(?:\s+(?:status|response))?|status|response|upstream|gateway|error|failed|returned)\D{0,16}(?:502|503|504)\b/u.test(normalized) ||
+        /\b(?:502|503|504)\D{0,16}(?:bad gateway|service unavailable|gateway timeout)\b/u.test(normalized));
+}
+function matchCloudFailureRule(signal) {
+    const lowercase = signal.toLowerCase();
+    const normalized = normalizeCloudFailureSignal(signal);
+    const envConfigRule = findCloudFailureRule('env_config');
+    if (isEnvironmentNotFoundSignal(signal)) {
+        const specificRule = matchSpecificWrappedFailureRule(signal, lowercase, normalized);
+        if (specificRule) {
+            return specificRule;
+        }
+        return findCloudFailureRule('environment_not_found');
+    }
+    if (envConfigRule && matchesCloudFailureRule(envConfigRule, lowercase, normalized)) {
+        const specificRule = matchSpecificWrappedFailureRule(signal, lowercase, normalized);
+        if (specificRule) {
+            return specificRule;
+        }
+        const envUnavailableRule = findCloudFailureRule('environment_unavailable');
+        if (envUnavailableRule && matchesCloudFailureRule(envUnavailableRule, lowercase, normalized)) {
+            return envUnavailableRule;
+        }
+    }
+    return CLOUD_FAILURE_RULES.find((rule) => matchesCloudFailureRule(rule, lowercase, normalized)) ?? null;
+}
+function matchSpecificWrappedFailureRule(signal, lowercase, normalized) {
+    const maskedSignal = maskEnvConfigIdentifierValues(lowercase);
+    for (const diagnosticCategory of [
+        'cloud_connector_auth_drift',
+        'cloud_denial',
+        'auth_mismatch',
+        'quota_rate_limit'
+    ]) {
+        const rule = findMatchedCloudFailureRule(diagnosticCategory, maskedSignal);
+        if (rule) {
+            return rule;
+        }
+    }
+    const connectivityRule = findCloudFailureRule('network_connectivity');
+    if (connectivityRule &&
+        matchesCloudFailureRule(connectivityRule, lowercase, normalized) &&
+        hasStrongConnectivityContext(signal)) {
+        return connectivityRule;
+    }
+    return null;
+}
+function normalizeCloudFailureSignal(signal) {
+    return signal
+        .replace(/([a-z0-9])([A-Z])/gu, '$1 $2')
+        .toLowerCase()
+        .replace(/[_-]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+function normalizeMachineReadableCloudDetail(signal) {
+    return normalizeCloudFailureSignal(signal).replace(/\s+/gu, '_');
+}
+function isMachineReadableCloudDetail(signal) {
+    return MACHINE_READABLE_CLOUD_DETAILS.has(normalizeMachineReadableCloudDetail(signal));
+}
+function buildCloudFailureDiagnosis(rule, signal) {
+    return {
+        category: rule.category,
+        diagnostic_category: rule.diagnostic_category,
+        guidance: rule.guidance,
+        signal
+    };
+}
 export function diagnoseCloudFailure(options) {
     const signal = [options.status ?? null, options.statusDetail ?? null, options.error ?? null]
         .filter((value) => typeof value === 'string' && value.trim().length > 0)
         .join('\n');
-    const normalized = signal.toLowerCase();
-    for (const rule of CLOUD_FAILURE_RULES) {
-        if (rule.patterns.some((pattern) => normalized.includes(pattern))) {
-            return {
-                category: rule.category,
-                guidance: rule.guidance,
-                signal
-            };
+    if (options.statusDetail && isMachineReadableCloudDetail(options.statusDetail)) {
+        const statusDetailRule = matchCloudFailureRule(options.statusDetail);
+        if (statusDetailRule) {
+            if (normalizeMachineReadableCloudDetail(options.statusDetail) === 'environment_unavailable' &&
+                options.error) {
+                const errorRule = matchCloudFailureRule(options.error);
+                if (errorRule &&
+                    errorRule.diagnostic_category !== 'environment_unavailable' &&
+                    errorRule.diagnostic_category !== 'env_config') {
+                    return buildCloudFailureDiagnosis(errorRule, signal);
+                }
+            }
+            return buildCloudFailureDiagnosis(statusDetailRule, signal);
         }
     }
+    if (options.error) {
+        const errorRule = matchCloudFailureRule(options.error);
+        if (errorRule) {
+            return buildCloudFailureDiagnosis(errorRule, signal);
+        }
+    }
+    const signalRule = matchCloudFailureRule(signal);
+    if (signalRule) {
+        return buildCloudFailureDiagnosis(signalRule, signal);
+    }
     if (options.status && TERMINAL_FAILURE_STATUSES.has(options.status.toLowerCase())) {
         return {
             category: 'execution',
+            diagnostic_category: 'provider_runtime',
             guidance: 'Inspect manifest cloud_execution.error and cloud command logs for the terminal cloud failure.',
             signal
         };
     }
     return {
         category: 'unknown',
+        diagnostic_category: 'unknown',
         guidance: 'Inspect manifest status_detail plus cloud command logs to classify this failure.',
         signal
     };