@kbediako/codex-orchestrator 0.1.11 → 0.1.12

package/README.md

@@ -1,5 +1,7 @@
 # Codex Orchestrator
 
+![Setup demo](docs/assets/setup.gif)
+
 Codex Orchestrator is the CLI + runtime that coordinates Codex-driven runs, pipelines, and delegation MCP tooling. The npm release focuses on running pipelines locally, emitting auditable manifests, and hosting the delegation server.
 
 ## Install
@@ -45,33 +47,57 @@ codex-orchestrator delegate-server --repo /path/to/repo
 ```
 Optional: add `--mode question_only` to disable `delegate.spawn/pause/cancel`, keeping only `delegate.question.*` + `delegate.status` in the delegate namespace. GitHub tools remain available when GitHub integration is enabled.
 
-Register it with Codex once, then enable per run:
+Register it with Codex once. Delegation MCP is enabled by default (the only MCP enabled by default). To override the default or re-enable after disabling:
 ```bash
 codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
 codex -c 'mcp_servers.delegation.enabled=true' ...
 ```
 `delegate-server` is the canonical name; `delegation-server` is supported as an alias (older docs may use it).
 
-## Delegation flow
+## 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.
 
+### Delegation flow
 ```mermaid
-flowchart LR
-  A["Parent Codex run\n(MCP disabled by default)"]
-  B["Background Codex run\n(delegation enabled)"]
+flowchart TB
+  A["Parent run<br/>(delegation MCP enabled)"]
   C["Delegation MCP server"]
   D["delegate.spawn"]
-  E["Child run"]
-  F["delegate.question.enqueue / poll\n(optional back to parent)"]
-  G["Artifacts\n.runs/<task-id>/cli/<run-id>/manifest.json"]
+  E["Child run<br/>(pipeline resolved)"]
+  N{Pipeline = rlm?}
+  P["Standard pipeline<br/>(plan/build/test/review)"]
+  RLM["RLM pipeline<br/>(see next chart)"]
+
+  A --> C --> D --> E --> N
+  N -- yes --> RLM
+  N -- no --> P
+  E -. optional .-> Q["delegate.question.enqueue/poll"] -.-> A
+```
 
-  A --> B --> C --> D --> E
-  E -. optional .-> F -.-> A
-  E --> G
+### RLM loop
+```mermaid
+flowchart TB
+  F["Resolve mode<br/>(auto -> iterative/symbolic)"]
+  G{Symbolic?}
+  H["Context store<br/>(chunk + search)"]
+  I["Planner JSON<br/>(select subcalls)"]
+  J["Subcalls<br/>(tool + edits)"]
+  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"]
+
+  F --> G
+  G -- yes --> H --> I --> J --> K
+  G -- no --> J
+  J --> K
+  K --> L --> M
+  K -- fail & budget left --> F
 ```
 
 ## Skills (bundled)
 
-The release ships skills under `skills/`. Install them into `$CODEX_HOME/skills`:
+The release ships skills under `skills/` for downstream packaging. If you already have global skills installed, treat those as the primary reference and use bundled skills as the shipped fallback. Install bundled skills into `$CODEX_HOME/skills`:
 ```bash
 codex-orchestrator skills install
 ```
@@ -82,6 +108,8 @@ Options:
 
 Bundled skills (may vary by release):
 - `delegation-usage`
+- `standalone-review`
+- `docs-first`
 
 ## DevTools readiness
 
@@ -100,6 +128,7 @@ codex-orchestrator devtools setup
 - `codex-orchestrator start <pipeline>` — run a pipeline.
 - `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 self-check --format json` — JSON health payload.
 - `codex-orchestrator mcp serve` — Codex MCP stdio server.
 
@@ -114,3 +143,4 @@ codex-orchestrator devtools setup
 
 Repo internals, development workflows, and deeper architecture notes live in the GitHub repository:
 - `docs/README.md`
+- `docs/diagnostics-prompt-guide.md` (first-run diagnostics prompt + expected outputs)

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

@@ -1306,10 +1306,7 @@ function assertRunManifestPath(pathname, label) {
     }
     const taskDir = dirname(cliDir);
     const runsDir = dirname(taskDir);
-    if (basename(runsDir) !== '.runs') {
-        throw new Error(`${label} invalid`);
-    }
-    if (!basename(runDir) || !basename(taskDir)) {
+    if (!basename(runDir) || !basename(taskDir) || !basename(runsDir)) {
         throw new Error(`${label} invalid`);
     }
 }

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

@@ -1,8 +1,8 @@
 import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { realpathSync } from 'node:fs';
-import { chmod, readFile } from 'node:fs/promises';
-import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { access, chmod, readFile, readdir, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import process from 'node:process';
 import { loadDelegationConfigFiles, computeEffectiveDelegationConfig, parseDelegationConfigOverride, splitDelegationConfigOverrides } from './config/delegationConfig.js';
 import { logger } from '../logger.js';
@@ -11,6 +11,8 @@ const PROTOCOL_VERSION = '2024-11-05';
 const QUESTION_POLL_INTERVAL_MS = 500;
 const MAX_QUESTION_POLL_WAIT_MS = 10_000;
 const DEFAULT_SPAWN_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_SPAWN_START_TIMEOUT_MS = 10_000;
+const DEFAULT_SPAWN_START_POLL_INTERVAL_MS = 200;
 const DEFAULT_GH_TIMEOUT_MS = 60_000;
 const DEFAULT_DELEGATION_TOKEN_RETRY_MS = 2000;
 const DEFAULT_DELEGATION_TOKEN_RETRY_INTERVAL_MS = 200;
@@ -94,7 +96,8 @@ function buildToolList(options) {
                 parent_run_id: { type: 'string' },
                 parent_manifest_path: { type: 'string' },
                 env: { type: 'object', additionalProperties: { type: 'string' } },
-                delegate_mode: { type: 'string', enum: ['full', 'question_only'] }
+                delegate_mode: { type: 'string', enum: ['full', 'question_only'] },
+                start_only: { type: 'boolean' }
             },
             required: ['pipeline', 'repo']
         }));
@@ -322,10 +325,16 @@ async function handleDelegateSpawn(input, repoRoot, allowNested, allowedRoots, a
     const pipeline = requireString(readStringValue(input, 'pipeline'), 'pipeline');
     const repo = readStringValue(input, 'repo') ?? repoRoot ?? process.cwd();
     const resolvedRepo = resolve(repo);
+    const resolvedRepoRoot = realpathSafe(resolvedRepo);
     if (!isPathWithinRoots(resolvedRepo, allowedRoots)) {
         throw new Error('repo_not_permitted');
     }
     const taskId = readStringValue(input, 'task_id', 'taskId');
+    const startOnly = readBooleanValue(input, 'start_only', 'startOnly');
+    const resolvedStartOnly = startOnly ?? true;
+    if (resolvedStartOnly && !taskId) {
+        throw new Error('task_id is required when start_only=true');
+    }
     const args = ['start', pipeline, '--format', 'json', '--no-interactive'];
     if (taskId) {
         args.push('--task', taskId);
@@ -347,19 +356,120 @@ async function handleDelegateSpawn(input, repoRoot, allowNested, allowedRoots, a
         ...(parentManifestPath ? { CODEX_DELEGATION_PARENT_MANIFEST_PATH: parentManifestPath } : {}),
         ...(mcpOverrides.length > 0 ? { CODEX_MCP_CONFIG_OVERRIDES: mcpOverrides.join(';') } : {})
     };
-    const child = spawn('codex-orchestrator', args, { cwd: resolvedRepo, env: childEnv });
-    const output = await collectOutput(child, DEFAULT_SPAWN_TIMEOUT_MS);
-    const parsedRecord = parseSpawnOutput(output.stdout);
-    const manifestPath = readStringValue(parsedRecord, 'manifest');
-    if (!manifestPath) {
-        return { status: 'spawn_failed', stdout: output.stdout.trim(), stderr: output.stderr.trim() };
-    }
-    const runId = readStringValue(parsedRecord, 'run_id', 'runId');
-    const logPath = readStringValue(parsedRecord, 'log_path', 'logPath');
-    const resolvedManifestPath = resolveSpawnManifestPath(manifestPath, resolvedRepo, allowedRoots);
+    if (!envOverrides || !Object.prototype.hasOwnProperty.call(envOverrides, 'CODEX_ORCHESTRATOR_ROOT')) {
+        childEnv.CODEX_ORCHESTRATOR_ROOT = resolvedRepoRoot;
+    }
+    if (!resolvedStartOnly) {
+        const child = spawn('codex-orchestrator', args, { cwd: resolvedRepo, env: childEnv });
+        const output = await collectOutput(child, DEFAULT_SPAWN_TIMEOUT_MS);
+        const parsedRecord = parseSpawnOutput(output.stdout);
+        const manifestPath = readStringValue(parsedRecord, 'manifest');
+        if (!manifestPath) {
+            return { status: 'spawn_failed', stdout: output.stdout.trim(), stderr: output.stderr.trim() };
+        }
+        const runId = readStringValue(parsedRecord, 'run_id', 'runId');
+        const logPath = readStringValue(parsedRecord, 'log_path', 'logPath');
+        const resolvedManifestPath = resolveSpawnManifestPath(manifestPath, resolvedRepo, allowedRoots);
+        if (!resolvedManifestPath) {
+            return { status: 'spawn_failed', stdout: output.stdout.trim(), stderr: output.stderr.trim() };
+        }
+        const eventsPath = `${dirname(resolvedManifestPath)}/events.jsonl`;
+        await persistDelegationToken(resolvedManifestPath, delegationToken, {
+            parentRunId: parentRunId ?? null,
+            childRunId: runId ?? null
+        });
+        if (parentManifestPath && parentRunId && runId) {
+            try {
+                await callControlEndpoint(parentManifestPath, '/delegation/register', {
+                    token: delegationToken,
+                    parent_run_id: parentRunId,
+                    child_run_id: runId
+                }, undefined, { allowedHosts });
+            }
+            catch (error) {
+                logger.warn(`Failed to register delegation token: ${error?.message ?? error}`);
+            }
+        }
+        return {
+            run_id: runId,
+            manifest_path: resolvedManifestPath,
+            log_path: logPath,
+            events_path: eventsPath
+        };
+    }
+    const runsRepoRoot = resolveRepoRootForRuns(resolvedRepo, childEnv);
+    const runsRoot = resolveRunsRoot(runsRepoRoot, childEnv);
+    if (!isPathWithinRoots(runsRoot, allowedRoots)) {
+        throw new Error('runs_root not permitted');
+    }
+    const taskRunsRoot = join(runsRoot, taskId, 'cli');
+    const baselineRuns = await snapshotRunManifests(taskRunsRoot);
+    const spawnStart = Date.now();
+    const child = spawn('codex-orchestrator', args, {
+        cwd: resolvedRepo,
+        env: childEnv,
+        detached: true,
+        stdio: ['ignore', 'ignore', 'ignore']
+    });
+    let spawnError = null;
+    const recordSpawnError = (message) => {
+        if (!spawnError) {
+            spawnError = new Error(message);
+        }
+    };
+    child.once('error', (error) => {
+        spawnError = error instanceof Error ? error : new Error(String(error));
+    });
+    child.once('exit', (code, signal) => {
+        if (code === 0 && !signal) {
+            return;
+        }
+        recordSpawnError(`delegate.spawn child exited with code ${code ?? 'null'} (${signal ?? 'no signal'})`);
+    });
+    child.once('close', (code, signal) => {
+        if (code === 0 && !signal) {
+            return;
+        }
+        recordSpawnError(`delegate.spawn child closed with code ${code ?? 'null'} (${signal ?? 'no signal'})`);
+    });
+    child.unref();
+    const timeoutMs = resolveSpawnStartTimeoutMs(childEnv);
+    const manifestInfo = await pollForSpawnManifest({
+        taskId: taskId,
+        taskRunsRoot,
+        baselineRuns,
+        spawnStart,
+        timeoutMs,
+        intervalMs: DEFAULT_SPAWN_START_POLL_INTERVAL_MS,
+        getSpawnError: () => spawnError
+    });
+    if (!manifestInfo) {
+        const candidates = await collectSpawnCandidates(taskRunsRoot, taskId);
+        return {
+            status: 'spawn_failed',
+            task_id: taskId,
+            runs_root: runsRoot,
+            expected_manifest_glob: join(taskRunsRoot, '*', 'manifest.json'),
+            candidates,
+            error: spawnError?.message ?? null
+        };
+    }
+    const resolvedManifestPath = resolveSpawnManifestPath(manifestInfo.manifestPath, resolvedRepo, allowedRoots);
     if (!resolvedManifestPath) {
-        return { status: 'spawn_failed', stdout: output.stdout.trim(), stderr: output.stderr.trim() };
+        return {
+            status: 'spawn_failed',
+            task_id: taskId,
+            runs_root: runsRoot,
+            expected_manifest_glob: join(taskRunsRoot, '*', 'manifest.json'),
+            candidates: [
+                {
+                    path: manifestInfo.manifestPath,
+                    reason: 'manifest_path not permitted'
+                }
+            ]
+        };
     }
+    const runId = manifestInfo.runId;
     const eventsPath = `${dirname(resolvedManifestPath)}/events.jsonl`;
     await persistDelegationToken(resolvedManifestPath, delegationToken, {
         parentRunId: parentRunId ?? null,
@@ -380,7 +490,7 @@ async function handleDelegateSpawn(input, repoRoot, allowNested, allowedRoots, a
     return {
         run_id: runId,
         manifest_path: resolvedManifestPath,
-        log_path: logPath,
+        log_path: manifestInfo.logPath ?? null,
         events_path: eventsPath
     };
 }
@@ -1035,6 +1145,174 @@ function clampQuestionPollWaitMs(value) {
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function resolveRepoRootForRuns(repoRoot, env) {
+    const configured = env.CODEX_ORCHESTRATOR_ROOT?.trim();
+    if (!configured) {
+        return repoRoot;
+    }
+    return isAbsolute(configured) ? configured : resolve(repoRoot, configured);
+}
+function resolveRunsRoot(repoRoot, env) {
+    const configured = env.CODEX_ORCHESTRATOR_RUNS_DIR?.trim();
+    if (!configured) {
+        return resolve(repoRoot, '.runs');
+    }
+    return isAbsolute(configured) ? configured : resolve(repoRoot, configured);
+}
+function resolveSpawnStartTimeoutMs(env) {
+    const raw = env.CODEX_DELEGATION_SPAWN_START_TIMEOUT_MS ?? env.DELEGATION_SPAWN_START_TIMEOUT_MS;
+    if (!raw) {
+        return DEFAULT_SPAWN_START_TIMEOUT_MS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return DEFAULT_SPAWN_START_TIMEOUT_MS;
+    }
+    return parsed;
+}
+async function snapshotRunManifests(taskRunsRoot) {
+    const snapshot = new Map();
+    let entries;
+    try {
+        entries = await readdir(taskRunsRoot, { withFileTypes: true });
+    }
+    catch {
+        return snapshot;
+    }
+    await Promise.all(entries.map(async (entry) => {
+        if (!entry.isDirectory()) {
+            return;
+        }
+        const runId = entry.name;
+        const manifestPath = join(taskRunsRoot, runId, 'manifest.json');
+        let exists = false;
+        try {
+            await access(manifestPath);
+            exists = true;
+        }
+        catch {
+            exists = false;
+        }
+        snapshot.set(runId, { manifestExists: exists });
+    }));
+    return snapshot;
+}
+async function findSpawnManifest(params) {
+    let entries;
+    try {
+        entries = await readdir(params.taskRunsRoot, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const runId = entry.name;
+        const manifestPath = join(params.taskRunsRoot, runId, 'manifest.json');
+        let stats;
+        try {
+            stats = await stat(manifestPath);
+        }
+        catch {
+            continue;
+        }
+        const baseline = params.baselineRuns.get(runId);
+        if (baseline?.manifestExists) {
+            continue;
+        }
+        if (stats.mtimeMs < params.spawnStart) {
+            continue;
+        }
+        candidates.push({ runId, manifestPath, mtimeMs: stats.mtimeMs });
+    }
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const candidate of candidates) {
+        try {
+            const raw = await readFile(candidate.manifestPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed.task_id && parsed.task_id !== params.taskId) {
+                continue;
+            }
+            const runId = typeof parsed.run_id === 'string' && parsed.run_id.trim()
+                ? parsed.run_id.trim()
+                : candidate.runId;
+            if (!runId) {
+                continue;
+            }
+            const logPath = typeof parsed.log_path === 'string' && parsed.log_path.trim().length > 0
+                ? parsed.log_path.trim()
+                : null;
+            return { runId, manifestPath: candidate.manifestPath, logPath };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function pollForSpawnManifest(params) {
+    const deadline = Date.now() + params.timeoutMs;
+    while (Date.now() <= deadline) {
+        if (params.getSpawnError()) {
+            return null;
+        }
+        const manifest = await findSpawnManifest(params);
+        if (manifest) {
+            return manifest;
+        }
+        await delay(params.intervalMs);
+    }
+    return null;
+}
+async function collectSpawnCandidates(taskRunsRoot, taskId) {
+    let entries;
+    try {
+        entries = await readdir(taskRunsRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const manifestPath = join(taskRunsRoot, entry.name, 'manifest.json');
+        try {
+            await access(manifestPath);
+        }
+        catch {
+            candidates.push({ path: manifestPath, reason: 'manifest.json missing' });
+            if (candidates.length >= 3) {
+                return candidates;
+            }
+            continue;
+        }
+        try {
+            const raw = await readFile(manifestPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed.task_id && parsed.task_id !== taskId) {
+                candidates.push({ path: manifestPath, reason: 'task_id mismatch' });
+            }
+            else if (!parsed.run_id) {
+                candidates.push({ path: manifestPath, reason: 'run_id missing' });
+            }
+            else {
+                candidates.push({ path: manifestPath, reason: 'manifest present but not selected' });
+            }
+        }
+        catch {
+            candidates.push({ path: manifestPath, reason: 'manifest unreadable' });
+        }
+        if (candidates.length >= 3) {
+            return candidates;
+        }
+    }
+    return candidates;
+}
 async function collectOutput(child, timeoutMs) {
     let stdout = '';
     let stderr = '';
@@ -1315,10 +1593,7 @@ function assertRunManifestPath(pathname, label) {
     }
     const taskDir = dirname(cliDir);
     const runsDir = dirname(taskDir);
-    if (basename(runsDir) !== '.runs') {
-        throw new Error(`${label} invalid`);
-    }
-    if (!basename(runDir) || !basename(taskDir)) {
+    if (!basename(runDir) || !basename(taskDir) || !basename(runsDir)) {
         throw new Error(`${label} invalid`);
     }
 }