@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/orchestrator/src/cli/utils/devtools.js

@@ -5,6 +5,7 @@ import { EnvUtils } from '../../../../packages/shared/config/env.js';
 import { resolveCodexCliBin } from './codexCli.js';
 import { resolveCodexHome } from './codexPaths.js';
 import { buildCommandPreview } from './commandPreview.js';
+import { hasMcpServerEntry } from './mcpServerEntry.js';
 export const DEVTOOLS_SKILL_NAME = 'chrome-devtools';
 export const DEVTOOLS_CONFIG_OVERRIDE = 'mcp_servers.chrome-devtools.enabled=true';
 const CONFIG_OVERRIDE_ENV_KEYS = ['CODEX_MCP_CONFIG_OVERRIDES', 'CODEX_CONFIG_OVERRIDES'];
@@ -132,7 +133,7 @@ function inspectDevtoolsConfig(env = process.env) {
             error: error instanceof Error ? error.message : String(error)
         };
     }
-    const hasEntry = hasDevtoolsConfigEntry(raw);
+    const hasEntry = hasMcpServerEntry(raw, DEVTOOLS_SKILL_NAME);
     if (hasEntry) {
         return { status: 'ok', path: configPath };
     }
@@ -142,52 +143,6 @@ function inspectDevtoolsConfig(env = process.env) {
         detail: 'chrome-devtools entry not found'
     };
 }
-function hasDevtoolsConfigEntry(raw) {
-    const lines = raw.split('\n');
-    let currentTable = null;
-    for (const line of lines) {
-        const trimmed = stripTomlComment(line).trim();
-        if (!trimmed) {
-            continue;
-        }
-        const tableMatch = trimmed.match(/^\[(.+)\]$/);
-        if (tableMatch) {
-            currentTable = tableMatch[1]?.trim() ?? null;
-            if (currentTable === 'mcp_servers.chrome-devtools' ||
-                currentTable === 'mcp_servers."chrome-devtools"' ||
-                currentTable === "mcp_servers.'chrome-devtools'") {
-                return true;
-            }
-            continue;
-        }
-        if (trimmed.startsWith('mcp_servers.')) {
-            if (trimmed.startsWith('mcp_servers."chrome-devtools".')) {
-                return true;
-            }
-            if (trimmed.startsWith("mcp_servers.'chrome-devtools'.")) {
-                return true;
-            }
-            if (trimmed.startsWith('mcp_servers.chrome-devtools.')) {
-                return true;
-            }
-            if (trimmed.startsWith('mcp_servers."chrome-devtools"=')) {
-                return true;
-            }
-            if (trimmed.startsWith("mcp_servers.'chrome-devtools'=")) {
-                return true;
-            }
-            if (trimmed.startsWith('mcp_servers.chrome-devtools=')) {
-                return true;
-            }
-        }
-        if (currentTable === 'mcp_servers') {
-            if (/^"?chrome-devtools"?\s*=/.test(trimmed)) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
 function parseConfigOverrides(env) {
     const overrides = [];
     for (const key of CONFIG_OVERRIDE_ENV_KEYS) {
@@ -216,10 +171,3 @@ function applyConfigOverrides(overrides, args) {
 function dedupeOverrides(overrides) {
     return Array.from(new Set(overrides.filter((override) => override.trim().length > 0)));
 }
-function stripTomlComment(line) {
-    const index = line.indexOf('#');
-    if (index === -1) {
-        return line;
-    }
-    return line.slice(0, index);
-}

package/dist/orchestrator/src/cli/utils/mcpServerEntry.js

@@ -0,0 +1,53 @@
+export function hasMcpServerEntry(raw, serverName) {
+    const lines = raw.split('\n');
+    let currentTable = null;
+    const escapedServerName = escapeRegExp(serverName);
+    for (const line of lines) {
+        const trimmed = stripTomlComment(line).trim();
+        if (!trimmed) {
+            continue;
+        }
+        const tableMatch = trimmed.match(/^\[(.+)\]$/u);
+        if (tableMatch) {
+            currentTable = tableMatch[1]?.trim() ?? null;
+            if (currentTable === `mcp_servers.${serverName}` ||
+                currentTable === `mcp_servers."${serverName}"` ||
+                currentTable === `mcp_servers.'${serverName}'`) {
+                return true;
+            }
+            continue;
+        }
+        if (trimmed.startsWith('mcp_servers.')) {
+            if (trimmed.startsWith(`mcp_servers."${serverName}".`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.'${serverName}'.`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.${serverName}.`)) {
+                return true;
+            }
+            const dottedEntryPattern = new RegExp(`^mcp_servers\\.(?:"${escapedServerName}"|'${escapedServerName}'|${escapedServerName})\\s*=`, 'u');
+            if (dottedEntryPattern.test(trimmed)) {
+                return true;
+            }
+        }
+        if (currentTable === 'mcp_servers') {
+            const entryPattern = new RegExp(`^(?:"${escapedServerName}"|'${escapedServerName}'|${escapedServerName})\\s*=`, 'u');
+            if (entryPattern.test(trimmed)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function stripTomlComment(line) {
+    const index = line.indexOf('#');
+    if (index === -1) {
+        return line;
+    }
+    return line.slice(0, index);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/orchestrator/src/cli/utils/packageProgramResolver.js

@@ -0,0 +1,151 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { extname, join, normalize } from 'node:path';
+import process from 'node:process';
+import { findPackageRoot } from './packageInfo.js';
+const DEFAULT_SOURCE_EXTENSIONS = ['.ts', '.mts', '.js', '.mjs', '.tsx'];
+const BOOTSTRAP_SOURCE_EXTENSIONS = ['.js', '.ts', '.mjs', '.mts', '.tsx'];
+const ALLOWED_RESOLVED_ENV_OVERRIDE_KEYS = ['TS_NODE_PROJECT'];
+export function resolvePackageProgramInvocation(options) {
+    const fileExists = options.fileExists ?? existsSync;
+    const packageRoot = resolvePackageRoot(options);
+    const distRelativePath = stripLeadingSeparators(options.distRelativePath);
+    const distPath = join(packageRoot, 'dist', distRelativePath);
+    const sourcePath = resolveSourcePath({
+        packageRoot,
+        distRelativePath,
+        fileExists,
+        sourcePreference: options.sourcePreference ?? 'default'
+    });
+    const execPath = options.execPath ?? process.execPath;
+    if (sourcePath) {
+        const sourceExtension = extname(sourcePath).toLowerCase();
+        if (!requiresTsNodeLoader(sourceExtension)) {
+            return {
+                command: execPath,
+                args: [sourcePath],
+                packageRoot,
+                distPath,
+                sourcePath,
+                mode: 'source',
+                warning: null
+            };
+        }
+        const loaderPath = resolveTsNodeLoaderPath(packageRoot, options.resolveModulePath);
+        if (loaderPath) {
+            return {
+                command: execPath,
+                args: ['--no-warnings', '--loader', loaderPath, sourcePath],
+                packageRoot,
+                distPath,
+                sourcePath,
+                mode: 'source',
+                warning: null,
+                envOverrides: filterResolvedProgramInvocationEnvOverrides({
+                    TS_NODE_PROJECT: join(packageRoot, 'tsconfig.json')
+                })
+            };
+        }
+    }
+    if (fileExists(distPath)) {
+        return {
+            command: execPath,
+            args: [distPath],
+            packageRoot,
+            distPath,
+            sourcePath,
+            mode: 'dist',
+            warning: sourcePath ? buildSourceFallbackWarning(sourcePath, distPath) : null
+        };
+    }
+    if (sourcePath) {
+        throw new Error(`Unable to run ${sourcePath} because ts-node/esm is unavailable, and fallback dist artifact ${distPath} is missing.`);
+    }
+    throw new Error(`Unable to locate packaged program. Expected ${distPath}.`);
+}
+export function resolveCodexOrchestratorBootstrapInvocation(options = {}) {
+    return resolvePackageProgramInvocation({
+        ...options,
+        distRelativePath: 'bin/codex-orchestrator.js',
+        sourcePreference: 'bootstrap'
+    });
+}
+export function resolveProviderLinearWorkerProgramInvocation(options = {}) {
+    return resolvePackageProgramInvocation({
+        ...options,
+        distRelativePath: 'orchestrator/src/cli/providerLinearWorkerRunner.js'
+    });
+}
+export function filterResolvedProgramInvocationEnvOverrides(envOverrides) {
+    if (!envOverrides) {
+        return undefined;
+    }
+    const filtered = {};
+    for (const key of ALLOWED_RESOLVED_ENV_OVERRIDE_KEYS) {
+        const value = envOverrides[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            filtered[key] = value;
+        }
+    }
+    return Object.keys(filtered).length > 0 ? filtered : undefined;
+}
+export function applyResolvedProgramInvocationEnvOverrides(targetEnv, envOverrides) {
+    const filtered = filterResolvedProgramInvocationEnvOverrides(envOverrides);
+    if (filtered) {
+        Object.assign(targetEnv, filtered);
+    }
+}
+function resolvePackageRoot(options) {
+    const defaultPackageRoot = normalize(options.packageRoot ?? findPackageRoot(import.meta.url));
+    const configured = normalizeOptionalString(options.env?.CODEX_ORCHESTRATOR_PACKAGE_ROOT);
+    if (configured &&
+        (options.allowConfiguredForeignPackageRoot === true || pathsEqual(configured, defaultPackageRoot))) {
+        return normalize(configured);
+    }
+    return defaultPackageRoot;
+}
+function resolveSourcePath(input) {
+    const relativeWithoutExtension = input.distRelativePath.replace(/\.js$/u, '');
+    const extensions = input.sourcePreference === 'bootstrap' ? BOOTSTRAP_SOURCE_EXTENSIONS : DEFAULT_SOURCE_EXTENSIONS;
+    for (const extension of extensions) {
+        const candidate = join(input.packageRoot, `${relativeWithoutExtension}${extension}`);
+        if (input.fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function resolveTsNodeLoaderPath(packageRoot, resolveModulePath) {
+    try {
+        const resolver = resolveModulePath ??
+            ((specifier, fromPath) => createRequire(fromPath).resolve(specifier));
+        return resolver('ts-node/esm', join(packageRoot, 'package.json'));
+    }
+    catch {
+        return null;
+    }
+}
+function requiresTsNodeLoader(extension) {
+    return extension === '.ts' || extension === '.mts' || extension === '.tsx';
+}
+function buildSourceFallbackWarning(sourcePath, distPath) {
+    return [
+        'Source checkout fallback: ts-node/esm is unavailable, so execution is using the built dist artifact instead of the live source entrypoint.',
+        `source=${sourcePath}`,
+        `dist=${distPath}`,
+        'Fresh merged TypeScript changes may remain stale until dist is rebuilt.'
+    ].join(' ');
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function pathsEqual(leftPath, rightPath) {
+    return normalize(leftPath) === normalize(rightPath);
+}
+function stripLeadingSeparators(value) {
+    return value.replace(/^[/\\]+/u, '');
+}

package/dist/orchestrator/src/cli/utils/providerOverrideEnv.js

@@ -0,0 +1,71 @@
+import { join } from 'node:path';
+import { readProviderControlHostLocatorFromEnv } from '../../../../scripts/lib/provider-run-contract.js';
+import { REPO_CONFIG_REQUIRED_ENV_KEY } from '../config/repoConfigPolicy.js';
+import { REPO_CONFIG_PATH_ENV_KEY } from '../config/userConfig.js';
+const PROVIDER_REPO_CONFIG_PATH_ENV_KEY = 'CODEX_ORCHESTRATOR_PROVIDER_REPO_CONFIG_PATH';
+const PROVIDER_PACKAGE_ROOT_ENV_KEY = 'CODEX_ORCHESTRATOR_PROVIDER_PACKAGE_ROOT';
+const PROVIDER_OVERRIDE_ENV_KEYS = [
+    REPO_CONFIG_PATH_ENV_KEY,
+    'CODEX_ORCHESTRATOR_PACKAGE_ROOT'
+];
+const PROVIDER_OVERRIDE_MARKER_ENV_KEYS = [
+    PROVIDER_REPO_CONFIG_PATH_ENV_KEY,
+    PROVIDER_PACKAGE_ROOT_ENV_KEY
+];
+const PROVIDER_WORKSPACE_ARTIFACT_ENV_KEYS = [
+    'CODEX_ORCHESTRATOR_ROOT',
+    'CODEX_ORCHESTRATOR_RUNS_DIR',
+    'CODEX_ORCHESTRATOR_OUT_DIR'
+];
+export { PROVIDER_OVERRIDE_ENV_KEYS, PROVIDER_OVERRIDE_MARKER_ENV_KEYS, PROVIDER_PACKAGE_ROOT_ENV_KEY, PROVIDER_REPO_CONFIG_PATH_ENV_KEY };
+export function sanitizeProviderOverrideEnv(env = process.env, options = {}) {
+    const sanitized = { ...env };
+    if (options.stripWorkspaceArtifactEnv) {
+        for (const key of PROVIDER_WORKSPACE_ARTIFACT_ENV_KEYS) {
+            delete sanitized[key];
+        }
+    }
+    const controlHostLocator = readProviderControlHostLocatorFromEnv(sanitized);
+    if (!controlHostLocator) {
+        return sanitized;
+    }
+    const currentRepoConfigPath = normalizeEnvString(sanitized[REPO_CONFIG_PATH_ENV_KEY]);
+    const currentPackageRoot = normalizeEnvString(sanitized.CODEX_ORCHESTRATOR_PACKAGE_ROOT);
+    const providerPackageRootMarker = normalizeEnvString(sanitized[PROVIDER_PACKAGE_ROOT_ENV_KEY]);
+    const providerRepoConfigPath = normalizeEnvString(sanitized[PROVIDER_REPO_CONFIG_PATH_ENV_KEY]) ??
+        deriveProviderRepoConfigPath(providerPackageRootMarker ?? currentPackageRoot, controlHostLocator.taskId, controlHostLocator.runId);
+    const providerPackageRoot = providerPackageRootMarker ??
+        (currentRepoConfigPath && providerRepoConfigPath && currentRepoConfigPath === providerRepoConfigPath
+            ? currentPackageRoot
+            : null);
+    const shouldStripRepoConfig = currentRepoConfigPath !== null &&
+        providerRepoConfigPath !== null &&
+        currentRepoConfigPath === providerRepoConfigPath;
+    const shouldStripPackageRoot = currentPackageRoot !== null &&
+        providerPackageRoot !== null &&
+        currentPackageRoot === providerPackageRoot;
+    if (shouldStripRepoConfig) {
+        delete sanitized[REPO_CONFIG_PATH_ENV_KEY];
+        delete sanitized[REPO_CONFIG_REQUIRED_ENV_KEY];
+    }
+    if (shouldStripPackageRoot) {
+        delete sanitized.CODEX_ORCHESTRATOR_PACKAGE_ROOT;
+    }
+    for (const key of PROVIDER_OVERRIDE_MARKER_ENV_KEYS) {
+        delete sanitized[key];
+    }
+    return sanitized;
+}
+function deriveProviderRepoConfigPath(packageRoot, controlHostTaskId, controlHostRunId) {
+    if (!packageRoot) {
+        return null;
+    }
+    return join(packageRoot, '.runs', controlHostTaskId, 'cli', controlHostRunId, 'provider-workflow.last-known-good.json');
+}
+function normalizeEnvString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}

package/dist/orchestrator/src/cli/utils/trailingJsonObject.js

@@ -0,0 +1,59 @@
+export function parseTrailingJsonObject(raw, options = {}) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const direct = safeJsonObjectParse(trimmed);
+    if (direct) {
+        return direct;
+    }
+    if (options.allowTrailingTextAfterJson) {
+        return parseJsonObjectBeforeTrailingText(trimmed);
+    }
+    return parseStrictTrailingJsonObject(trimmed);
+}
+function parseStrictTrailingJsonObject(trimmed) {
+    if (!trimmed.endsWith('}')) {
+        return null;
+    }
+    const lines = trimmed.split(/\r?\n/u);
+    for (let start = 0; start < lines.length; start += 1) {
+        if (!lines[start]?.trimStart().startsWith('{')) {
+            continue;
+        }
+        const parsed = safeJsonObjectParse(lines.slice(start).join('\n'));
+        if (parsed) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function parseJsonObjectBeforeTrailingText(trimmed) {
+    const lines = trimmed.split(/\r?\n/u);
+    for (let start = lines.length - 1; start >= 0; start -= 1) {
+        if (!lines[start]?.trimStart().startsWith('{')) {
+            continue;
+        }
+        for (let end = lines.length - 1; end >= start; end -= 1) {
+            if (!lines[end]?.includes('}')) {
+                continue;
+            }
+            const parsed = safeJsonObjectParse(lines.slice(start, end + 1).join('\n'));
+            if (parsed) {
+                return parsed;
+            }
+        }
+    }
+    return null;
+}
+function safeJsonObjectParse(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/orchestrator/src/learning/crystalizer.js

@@ -7,7 +7,7 @@ import { isoTimestamp } from '../cli/utils/time.js';
 import { resolveCodexCliBin } from '../cli/utils/codexCli.js';
 import { slugify } from '../cli/utils/strings.js';
 import { appendLearningAlert, ensureLearningSection } from './manifest.js';
-import { computePromptPackStamp, loadPromptPacks } from '../../../packages/orchestrator/src/instructions/promptPacks.js';
+import { loadPromptPacks } from '../../../packages/orchestrator/src/instructions/promptPacks.js';
 const DEFAULT_PROMPT_PACK = 'crystalizer-v1';
 const DEFAULT_OUTPUT_DIR = '.agent/patterns/candidates';
 const DEFAULT_MODEL = process.env.CRYSTALIZER_MODEL || 'gpt-5.1-codex-max';
@@ -23,7 +23,7 @@ export async function runCrystalizer(options) {
     if (!pack) {
         throw new Error(`Prompt pack ${promptPackId} not found`);
     }
-    const packStamp = computePromptPackStamp(pack.sources);
+    const packStamp = pack.stamp;
     const promptSources = pack.sources.map((source) => source.content).join('\n\n');
     const prompt = composePrompt(promptSources, packStamp, problemStatement, validatedPatch, scenarioSummary ?? '');
     const response = await client.generate(prompt, { model });

package/dist/orchestrator/src/manager.js

@@ -160,7 +160,7 @@ export class TaskManager {
         const build = await this.executeBuilder(task, plan, target, mode, runId);
         if (!build.success) {
             const skippedTest = this.createSkippedTestResult(build, runId);
-            const skippedReview = this.createSkippedReviewResult('build-failed');
+            const skippedReview = this.createSkippedReviewResult('build-failed', build);
             const summary = this.createRunSummary(task, mode, plan, build, skippedTest, skippedReview, runId);
             return { target, mode, build, test: skippedTest, review: skippedReview, summary };
         }
@@ -239,13 +239,27 @@ export class TaskManager {
             runId
         };
     }
-    createSkippedReviewResult(reason) {
+    createSkippedReviewResult(reason, build) {
         if (reason === 'build-failed') {
+            const prerequisiteStage = this.extractFailedPrerequisiteStage(build);
+            if (prerequisiteStage) {
+                const artifactPath = this.findFailedStageArtifactPath(build);
+                const artifactFeedback = artifactPath ? ` Error artifact: ${artifactPath}.` : '';
+                return {
+                    summary: `Review skipped: prerequisite stage \`${prerequisiteStage}\` failed.`,
+                    decision: {
+                        approved: false,
+                        feedback: `Prerequisite stage \`${prerequisiteStage}\` failed; review skipped.${artifactFeedback}`
+                    }
+                };
+            }
+            const artifactPath = this.findFailedStageArtifactPath(build);
+            const artifactFeedback = artifactPath ? ` Error artifact: ${artifactPath}.` : '';
             return {
                 summary: 'Review skipped: build stage failed.',
                 decision: {
                     approved: false,
-                    feedback: 'Build stage failed; review skipped.'
+                    feedback: `Build stage failed; review skipped.${artifactFeedback}`
                 }
             };
         }
@@ -257,6 +271,62 @@ export class TaskManager {
             }
         };
     }
+    extractFailedPrerequisiteStage(build) {
+        const stage = build?.failureStage?.trim();
+        const canonicalStage = stage?.toLowerCase();
+        if (!stage || (canonicalStage != null && ['build', 'test', 'review'].includes(canonicalStage))) {
+            return null;
+        }
+        return stage;
+    }
+    findFailedStageArtifactPath(build) {
+        if (build?.failureArtifactPath) {
+            return build.failureArtifactPath;
+        }
+        const failureStage = build?.failureStage?.trim().toLowerCase();
+        if (!failureStage) {
+            return null;
+        }
+        if (['build', 'test', 'review'].includes(failureStage)) {
+            return null;
+        }
+        const stagePathToken = failureStage.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+        const stageArtifact = build?.artifacts.find((candidate) => {
+            const normalizedPath = candidate.path.replace(/\\/g, '/').toLowerCase();
+            const isErrorArtifact = normalizedPath.startsWith('errors/') ||
+                normalizedPath.includes('/errors/') ||
+                /\berror\b/i.test(candidate.description);
+            if (!isErrorArtifact) {
+                return false;
+            }
+            return this.artifactMatchesFailedStage(candidate, failureStage, stagePathToken);
+        });
+        return stageArtifact?.path ?? null;
+    }
+    artifactMatchesFailedStage(candidate, failureStage, stagePathToken) {
+        const normalizedDescription = candidate.description.toLowerCase();
+        const parentheticalStages = [...normalizedDescription.matchAll(/\(([^)]+)\)/g)]
+            .map((match) => match[1]?.trim() ?? '')
+            .filter(Boolean);
+        if (parentheticalStages.some((stage) => this.stageTokenMatches(stage, failureStage, stagePathToken))) {
+            return true;
+        }
+        const normalizedPath = candidate.path.replace(/\\/g, '/').toLowerCase();
+        return normalizedPath
+            .split('/')
+            .map((segment) => segment.replace(/\.[^.]+$/, '').replace(/^\d+-/, ''))
+            .some((segment) => this.stageTokenMatches(segment, failureStage, stagePathToken));
+    }
+    stageTokenMatches(candidate, failureStage, stagePathToken) {
+        if (candidate === failureStage) {
+            return true;
+        }
+        if (!stagePathToken) {
+            return false;
+        }
+        const candidatePathToken = candidate.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+        return candidatePathToken === stagePathToken;
+    }
     async executePlanner(task, runId) {
         try {
             const plan = await this.options.planner.plan(task);
@@ -335,7 +405,7 @@ export class TaskManager {
         const cause = error ?? new Error('Planner stage failed without an error payload');
         const build = this.createBuilderErrorResult('planner-unavailable', mode, runId, cause);
         const skippedTest = this.createSkippedTestResult(build, runId);
-        const skippedReview = this.createSkippedReviewResult('build-failed');
+        const skippedReview = this.createSkippedReviewResult('build-failed', build);
         const summary = this.createRunSummary(task, mode, plan, build, skippedTest, skippedReview, runId);
         this.eventBus.emit({ type: 'run:completed', payload: summary });
         return summary;