@kbediako/codex-orchestrator 0.1.12 → 0.1.14-alpha.1

package/LICENSE

@@ -1,7 +1,21 @@
+MIT License
+
 Copyright (c) 2025 Kbediako
-All rights reserved.
 
-This software and associated documentation files (the "Software") are proprietary
-and confidential. Unauthorized copying, modification, distribution, or use of the
-Software, via any medium, is strictly prohibited without prior written permission
-from the copyright holder.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -39,6 +39,32 @@ Node.js >= 20 is required.
    > Tip: if you prefer `npx`, replace `codex-orch` with `npx @kbediako/codex-orchestrator`.
    > Tip: for multiple commands, you can also `export MCP_RUNNER_TASK_ID=<task-id>` once.
 
+## Downstream init (recommended)
+
+Use this when you want Codex to drive work inside another repo with the CO defaults.
+
+1. Install templates:
+   ```bash
+   codex-orchestrator init codex --cwd /path/to/repo
+   ```
+   One-shot (templates + CO-managed Codex CLI):
+   ```bash
+   codex-orchestrator init codex --codex-cli --yes
+   ```
+2. Register the delegation MCP server (one-time per machine):
+   ```bash
+   codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
+   ```
+3. Optional (collab JSONL parity): set up a CO-managed Codex CLI:
+   ```bash
+   codex-orchestrator codex setup
+   ```
+4. Optional (fast refresh helper for downstream users):
+   ```bash
+   scripts/codex-cli-refresh.sh --repo /path/to/codex
+   ```
+   Repo-only helper (not included in npm package). Set `CODEX_REPO` or `CODEX_CLI_SOURCE` to avoid passing `--repo` each time.
+
 ## Delegation MCP server
 
 Run the delegation MCP server over stdio:
@@ -57,6 +83,7 @@ codex -c 'mcp_servers.delegation.enabled=true' ...
 ## Delegation + RLM flow
 
 RLM (Recursive Language Model) is the long-horizon loop used by the `rlm` pipeline (`codex-orchestrator rlm "<goal>"` or `codex-orchestrator start rlm --goal "<goal>"`). Delegated runs only enter RLM when the child is launched with the `rlm` pipeline (or the rlm runner directly). In auto mode it resolves to symbolic when delegated, when `RLM_CONTEXT_PATH` is set, or when the context exceeds `RLM_SYMBOLIC_MIN_BYTES`; otherwise it stays iterative. The runner writes state to `.runs/<task-id>/cli/<run-id>/rlm/state.json` and stops when the validator passes or budgets are exhausted.
+Symbolic subcalls can optionally use collab tools when `RLM_SYMBOLIC_COLLAB=1` (requires a collab-enabled Codex CLI via `codex-orchestrator codex setup`). Collab tool calls parsed from `codex exec --json --enable collab` are stored in `manifest.collab_tool_calls` (bounded by `CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS`, set to `0` to disable).
 
 ### Delegation flow
 ```mermaid
@@ -82,7 +109,7 @@ flowchart TB
   G{Symbolic?}
   H["Context store<br/>(chunk + search)"]
   I["Planner JSON<br/>(select subcalls)"]
-  J["Subcalls<br/>(tool + edits)"]
+  J["Subcalls<br/>(tool + edits, collab optional)"]
   K["Validator<br/>(test command)"]
   L["State + artifacts<br/>.runs/&lt;task-id&gt;/cli/&lt;run-id&gt;/rlm/state.json"]
   M["Exit status"]
@@ -110,6 +137,9 @@ Bundled skills (may vary by release):
 - `delegation-usage`
 - `standalone-review`
 - `docs-first`
+- `collab-evals`
+- `collab-deliberation`
+- `delegate-early`
 
 ## DevTools readiness
 
@@ -129,6 +159,9 @@ codex-orchestrator devtools setup
 - `codex-orchestrator plan <pipeline>` — preview pipeline stages.
 - `codex-orchestrator exec <cmd>` — run a one-off command with the exec runtime.
 - `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`) into a repo.
+- `codex-orchestrator init codex --codex-cli --yes --codex-source <path>` — also provision a CO-managed Codex CLI binary (build-from-source default; set `CODEX_CLI_SOURCE` to avoid passing `--codex-source` every time).
+- `codex-orchestrator init codex --codex-cli --yes --codex-download-url <url> --codex-download-sha256 <sha>` — opt-in to a prebuilt Codex CLI download.
+- `codex-orchestrator codex setup` — plan/apply a CO-managed Codex CLI install (for collab JSONL parity; use `--download-url` + `--download-sha256` for prebuilts).
 - `codex-orchestrator self-check --format json` — JSON health payload.
 - `codex-orchestrator mcp serve` — Codex MCP stdio server.
 
@@ -141,6 +174,18 @@ codex-orchestrator devtools setup
 
 ## Repository + contributor guide
 
-Repo internals, development workflows, and deeper architecture notes live in the GitHub repository:
+Repo internals, development workflows, and deeper architecture notes (contributor/internal) live in the GitHub repository:
 - `docs/README.md`
 - `docs/diagnostics-prompt-guide.md` (first-run diagnostics prompt + expected outputs)
+- `docs/guides/collab-vs-mcp.md` (agent-first decision guide)
+
+## RLM benchmark graphs
+
+Seeded OOLONG accuracy curves (Wilson 95% CI, runs=5). In these runs, the baseline accuracy degrades as context length grows, while RLM stays near the ceiling across the tested lengths.
+
+<table>
+  <tr>
+    <td><img src="docs/assets/oolong-baseline-seeded-wilson95-runs5.png" alt="Baseline OOLONG seeded Wilson 95% CI" width="420"></td>
+    <td><img src="docs/assets/oolong-rlm-seeded-wilson95-runs5.png" alt="RLM OOLONG seeded Wilson 95% CI" width="420"></td>
+  </tr>
+</table>

package/dist/bin/codex-orchestrator.js

@@ -13,6 +13,7 @@ import { buildSelfCheckResult } from '../orchestrator/src/cli/selfCheck.js';
 import { initCodexTemplates, formatInitSummary } from '../orchestrator/src/cli/init.js';
 import { runDoctor, formatDoctorSummary } from '../orchestrator/src/cli/doctor.js';
 import { formatDevtoolsSetupSummary, runDevtoolsSetup } from '../orchestrator/src/cli/devtoolsSetup.js';
+import { formatCodexCliSetupSummary, runCodexCliSetup } from '../orchestrator/src/cli/codexCliSetup.js';
 import { formatSkillsInstallSummary, installSkills } from '../orchestrator/src/cli/skills.js';
 import { loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
 import { slugify } from '../orchestrator/src/cli/utils/strings.js';
@@ -63,6 +64,9 @@ async function main() {
             case 'doctor':
                 await handleDoctor(args);
                 break;
+            case 'codex':
+                await handleCodex(args);
+                break;
             case 'devtools':
                 await handleDevtools(args);
                 break;
@@ -136,6 +140,24 @@ function readStringFlag(flags, key) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+function resolveExecutionModeFlag(flags) {
+    const cloudShortcut = flags['cloud'] === true;
+    const rawMode = readStringFlag(flags, 'execution-mode');
+    if (cloudShortcut) {
+        if (rawMode && rawMode.toLowerCase() !== 'cloud') {
+            throw new Error('Cannot combine --cloud with --execution-mode values other than cloud.');
+        }
+        return 'cloud';
+    }
+    if (!rawMode) {
+        return undefined;
+    }
+    const normalized = rawMode.toLowerCase();
+    if (normalized !== 'mcp' && normalized !== 'cloud') {
+        throw new Error('Invalid --execution-mode value. Expected one of: mcp, cloud.');
+    }
+    return normalized;
+}
 function applyRlmEnvOverrides(flags, goal) {
     if (goal) {
         process.env.RLM_GOAL = goal;
@@ -198,6 +220,7 @@ async function handleStart(orchestrator, rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const pipelineId = positionals[0];
     const format = flags['format'] === 'json' ? 'json' : 'text';
+    const executionMode = resolveExecutionModeFlag(flags);
     if (pipelineId === 'rlm') {
         const goal = readStringFlag(flags, 'goal');
         applyRlmEnvOverrides(flags, goal);
@@ -217,6 +240,7 @@ async function handleStart(orchestrator, rawArgs) {
             parentRunId: typeof flags['parent-run'] === 'string' ? flags['parent-run'] : undefined,
             approvalPolicy: typeof flags['approval-policy'] === 'string' ? flags['approval-policy'] : undefined,
             targetStageId: resolveTargetStageId(flags),
+            executionMode,
             runEvents
         });
         emitRunOutput(result, format, 'Run started');
@@ -465,6 +489,25 @@ async function handleInit(rawArgs) {
     for (const line of summary) {
         console.log(line);
     }
+    if (flags['codex-cli'] === true) {
+        const apply = Boolean(flags['yes']);
+        const source = readStringFlag(flags, 'codex-source');
+        const ref = readStringFlag(flags, 'codex-ref');
+        const downloadUrl = readStringFlag(flags, 'codex-download-url');
+        const downloadSha256 = readStringFlag(flags, 'codex-download-sha256');
+        const cliForce = Boolean(flags['codex-force']);
+        const setupResult = await runCodexCliSetup({
+            apply,
+            force: cliForce,
+            source,
+            ref,
+            downloadUrl,
+            downloadSha256
+        });
+        for (const line of formatCodexCliSetupSummary(setupResult)) {
+            console.log(line);
+        }
+    }
 }
 async function handleDoctor(rawArgs) {
     const { flags } = parseArgs(rawArgs);
@@ -503,6 +546,39 @@ async function handleDevtools(rawArgs) {
         console.log(line);
     }
 }
+async function handleCodex(rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    const subcommand = positionals.shift();
+    if (!subcommand) {
+        throw new Error('codex requires a subcommand (setup).');
+    }
+    if (subcommand !== 'setup') {
+        throw new Error(`Unknown codex subcommand: ${subcommand}`);
+    }
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const apply = Boolean(flags['yes']);
+    const source = readStringFlag(flags, 'source');
+    const ref = readStringFlag(flags, 'ref');
+    const downloadUrl = readStringFlag(flags, 'download-url');
+    const downloadSha256 = readStringFlag(flags, 'download-sha256');
+    const force = Boolean(flags['force']);
+    const result = await runCodexCliSetup({
+        apply,
+        force,
+        source,
+        ref,
+        downloadUrl,
+        downloadSha256
+    });
+    if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const summary = formatCodexCliSetupSummary(result);
+    for (const line of summary) {
+        console.log(line);
+    }
+}
 async function handleSkills(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const subcommand = positionals[0];
@@ -690,6 +766,8 @@ Commands:
     --parent-run <id>       Link run to parent run id.
     --approval-policy <p>   Record approval policy metadata.
     --format json           Emit machine-readable output.
+    --execution-mode <mcp|cloud>  Force execution mode for this run and child subpipelines.
+    --cloud                 Shortcut for --execution-mode cloud.
     --target <stage-id>     Focus plan/build metadata on a specific stage (alias: --target-stage).
     --goal "<goal>"         When pipeline is rlm, set the RLM goal.
     --validator <cmd|none>  When pipeline is rlm, set the validator command.
@@ -746,7 +824,22 @@ Commands:
 
   self-check [--format json]
   init codex [--cwd <path>] [--force]
+    --codex-cli            Also run CO-managed Codex CLI setup (plan unless --yes).
+    --codex-source <path>  Build from local Codex repo (or git URL).
+    --codex-ref <ref>      Git ref (branch/tag/sha) when building from repo.
+    --codex-download-url <url>  Download a prebuilt codex binary.
+    --codex-download-sha256 <sha>  Expected SHA256 for the prebuilt download.
+    --codex-force          Overwrite existing CO-managed codex binary.
+    --yes                  Apply codex CLI setup (otherwise plan only).
   doctor [--format json]
+  codex setup
+    --source <path>        Build from local Codex repo (or git URL).
+    --ref <ref>            Git ref (branch/tag/sha) when building from repo.
+    --download-url <url>   Download a prebuilt codex binary.
+    --download-sha256 <sha>  Expected SHA256 for the prebuilt download.
+    --force                Overwrite existing CO-managed codex binary.
+    --yes                  Apply setup (otherwise plan only).
+    --format json          Emit machine-readable output.
   devtools setup          Print DevTools MCP setup instructions.
     --yes                 Apply setup by running "codex mcp add ...".
     --format json         Emit machine-readable output (dry-run only).

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

@@ -4,17 +4,41 @@ export class CommandBuilder {
         this.executePipeline = executePipeline;
     }
     async build(input) {
-        const result = await this.executePipeline();
+        const result = await this.executePipeline(input);
         return {
             subtaskId: input.target.id,
             artifacts: [
                 { path: result.manifestPath, description: 'CLI run manifest' },
-                { path: result.logPath, description: 'Runner log (ndjson)' }
+                { path: result.logPath, description: 'Runner log (ndjson)' },
+                ...(result.manifest.cloud_execution?.diff_path
+                    ? [{ path: result.manifest.cloud_execution.diff_path, description: 'Cloud diff artifact' }]
+                    : [])
             ],
             mode: input.mode,
             runId: input.runId,
             success: result.success,
-            notes: result.notes.join('\n') || undefined
+            notes: result.notes.join('\n') || undefined,
+            cloudExecution: result.manifest.cloud_execution
+                ? {
+                    taskId: result.manifest.cloud_execution.task_id,
+                    environmentId: result.manifest.cloud_execution.environment_id,
+                    status: result.manifest.cloud_execution.status,
+                    statusUrl: result.manifest.cloud_execution.status_url,
+                    submittedAt: result.manifest.cloud_execution.submitted_at,
+                    completedAt: result.manifest.cloud_execution.completed_at,
+                    lastPolledAt: result.manifest.cloud_execution.last_polled_at,
+                    pollCount: result.manifest.cloud_execution.poll_count,
+                    pollIntervalSeconds: result.manifest.cloud_execution.poll_interval_seconds,
+                    timeoutSeconds: result.manifest.cloud_execution.timeout_seconds,
+                    attempts: result.manifest.cloud_execution.attempts,
+                    diffPath: result.manifest.cloud_execution.diff_path,
+                    diffUrl: result.manifest.cloud_execution.diff_url,
+                    diffStatus: result.manifest.cloud_execution.diff_status,
+                    applyStatus: result.manifest.cloud_execution.apply_status,
+                    logPath: result.manifest.cloud_execution.log_path,
+                    error: result.manifest.cloud_execution.error
+                }
+                : null
         };
     }
 }

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

@@ -43,6 +43,9 @@ export class CommandPlanner {
         if (stagePlanHints.executionMode) {
             metadata.executionMode = stagePlanHints.executionMode;
         }
+        if (stagePlanHints.cloudEnvId) {
+            metadata.cloudEnvId = stagePlanHints.cloudEnvId;
+        }
         metadata.requiresCloud = requiresCloud;
         return {
             id: `${this.pipeline.id}:${stage.id}`,
@@ -117,12 +120,25 @@ function extractStagePlanHints(stage) {
     const executionMode = typeof rawExecutionMode === 'string'
         ? rawExecutionMode.trim().toLowerCase() || null
         : null;
+    const rawCloudEnvId = typeof planConfig.cloudEnvId === 'string'
+        ? planConfig.cloudEnvId
+        : typeof planConfig.cloud_env_id === 'string'
+            ? planConfig.cloud_env_id
+            : typeof stageRecord.cloudEnvId === 'string'
+                ? stageRecord.cloudEnvId
+                : typeof stageRecord.cloud_env_id === 'string'
+                    ? stageRecord.cloud_env_id
+                    : undefined;
+    const cloudEnvId = typeof rawCloudEnvId === 'string'
+        ? rawCloudEnvId.trim() || null
+        : null;
     return {
         runnable: planConfig.runnable,
         defaultTarget,
         aliases,
         requiresCloud,
-        executionMode
+        executionMode,
+        cloudEnvId
     };
 }
 function resolveStageRequiresCloud(stage, hints) {

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

@@ -1,11 +1,46 @@
+import { diagnoseCloudFailure } from './cloudFailureDiagnostics.js';
 export class CommandReviewer {
     getResult;
     constructor(getResult) {
         this.getResult = getResult;
     }
     async review(input) {
-        void input;
         const result = this.requireResult();
+        if (input.mode === 'cloud') {
+            const cloudExecution = result.manifest.cloud_execution;
+            const status = cloudExecution?.status ?? 'unknown';
+            const cloudTask = cloudExecution?.task_id ?? '<unknown>';
+            const approved = status === 'ready' && result.success;
+            const diagnosis = diagnoseCloudFailure({
+                status,
+                statusDetail: result.manifest.status_detail ?? null,
+                error: cloudExecution?.error ?? null
+            });
+            const summaryLines = [
+                approved
+                    ? `Cloud task ${cloudTask} completed successfully.`
+                    : `Cloud task ${cloudTask} did not complete successfully (${status}).`,
+                `Manifest: ${result.manifestPath}`,
+                `Runner log: ${result.logPath}`,
+                ...(cloudExecution?.status_url ? [`Cloud status URL: ${cloudExecution.status_url}`] : [])
+            ];
+            if (!approved) {
+                summaryLines.push(`Failure class: ${diagnosis.category}`);
+                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(`Guidance: ${diagnosis.guidance}`);
+            }
+            return {
+                summary: summaryLines.join('\n'),
+                decision: {
+                    approved,
+                    feedback: feedbackLines.length > 0 ? feedbackLines.join('\n') : undefined
+                }
+            };
+        }
         const summaryLines = [
             result.success
                 ? 'Diagnostics pipeline succeeded.'

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

@@ -1,4 +1,5 @@
 import { ensureGuardrailStatus } from '../run/manifest.js';
+import { diagnoseCloudFailure } from './cloudFailureDiagnostics.js';
 export class CommandTester {
     getResult;
     constructor(getResult) {
@@ -6,6 +7,33 @@ export class CommandTester {
     }
     async test(input) {
         const result = this.requireResult();
+        if (input.mode === 'cloud') {
+            const cloudExecution = result.manifest.cloud_execution;
+            const status = cloudExecution?.status ?? 'unknown';
+            const passed = status === 'ready' && result.success;
+            const diagnosis = diagnoseCloudFailure({
+                status,
+                statusDetail: result.manifest.status_detail ?? null,
+                error: cloudExecution?.error ?? null
+            });
+            const failureDetails = cloudExecution?.error ??
+                `Cloud task status: ${status}${cloudExecution?.task_id ? ` (${cloudExecution.task_id})` : ''}`;
+            const reports = [
+                {
+                    name: 'cloud-task',
+                    status: passed ? 'passed' : 'failed',
+                    details: passed
+                        ? failureDetails
+                        : `${failureDetails}\nFailure class: ${diagnosis.category}. ${diagnosis.guidance}`
+                }
+            ];
+            return {
+                subtaskId: input.build.subtaskId,
+                success: passed,
+                reports,
+                runId: input.runId
+            };
+        }
         const guardrailStatus = ensureGuardrailStatus(result.manifest);
         const reports = [
             {

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

@@ -0,0 +1,45 @@
+const CLOUD_FAILURE_RULES = [
+    {
+        category: 'configuration',
+        patterns: ['cloud-env-missing', 'codex_cloud_env_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.'
+    },
+    {
+        category: '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']);
+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.status && TERMINAL_FAILURE_STATUSES.has(options.status.toLowerCase())) {
+        return {
+            category: 'execution',
+            guidance: 'Inspect manifest cloud_execution.error and cloud command logs for the terminal cloud failure.',
+            signal
+        };
+    }
+    return {
+        category: 'unknown',
+        guidance: 'Inspect manifest status_detail plus cloud command logs to classify this failure.',
+        signal
+    };
+}