@kbediako/codex-orchestrator 0.1.3 → 0.1.4

package/README.md

@@ -130,6 +130,11 @@ Notes:
 - `MCP_RUNNER_TASK_ID` is no longer coerced or lowercased silently. The CLI calls the shared `sanitizeTaskId` helper and fails fast when the value contains control characters, traversal attempts, or Windows-reserved characters (`<`, `>`, `:`, `"`, `/`, `\`, `|`, `?`, `*`). Set the correct task ID in your environment *before* invoking the CLI.
 - Run IDs used for manifest or artifact storage must come from the CLI (or pass the shared `sanitizeRunId` helper). Strings with colons, control characters, or `../` are rejected to ensure every run directory lives under `.runs/<task-id>/cli/<run-id>` (and legacy `mcp` mirrors) without risking traversal.
 
+### Delegation Guardrails
+- `delegate.question.poll` clamps `wait_ms` to `MAX_QUESTION_POLL_WAIT_MS` (10s); each poll timeout is bounded by the remaining `wait_ms`.
+- Confirm-to-act fallback only triggers on confirmation-specific errors (`error.code`), not generic tool failures.
+- Tool profile entries used for MCP overrides are sanitized; only alphanumeric + `_`/`-` names are allowed (rejects `;`, `/`, `\n`, `=` and similar).
+
 ## Pipelines & Execution Plans
 - Default pipelines live in `codex.orchestrator.json` (repository-specific) and `orchestrator/src/cli/pipelines/` (built-in defaults). Each stage is either a command (shell execution) or a nested pipeline.
 - The `CommandPlanner` inspects the selected pipeline and target stage; you can pass `--target <stage-id>` (alias: `--target-stage`) or set `CODEX_ORCHESTRATOR_TARGET_STAGE` to focus on a specific step (e.g., rerun tests only).
@@ -149,7 +154,7 @@ Notes:
 - `TaskStateStore` writes per-task snapshots with bounded lock retries; failures degrade gracefully while still writing the main manifest.
 - `RunManifestWriter` generates the canonical manifest JSON for each run (mirrored under `.runs/`), while metrics appenders and summary writers keep `out/` up to date.
 - Heartbeat files and timestamps guard against stalled runs. `orchestrator/src/cli/metrics/metricsRecorder.ts` aggregates command durations, exit codes, and guardrail stats for later review.
-- Optional caps: `CODEX_ORCHESTRATOR_EXEC_EVENT_MAX_CHUNKS` limits captured exec chunk events per command (0 = no cap), and `CODEX_METRICS_PRIVACY_EVENTS_MAX` limits privacy decision events stored in `metrics.json` (-1 = no cap; `privacy_event_count` still reflects total).
+- Optional caps: `CODEX_ORCHESTRATOR_EXEC_EVENT_MAX_CHUNKS` limits captured exec chunk events per command (defaults to 500; set 0 for no cap), `CODEX_ORCHESTRATOR_TELEMETRY_MAX_EVENTS` caps in-memory telemetry events queued before flush (defaults to 1000; set 0 for no cap), and `CODEX_METRICS_PRIVACY_EVENTS_MAX` limits privacy decision events stored in `metrics.json` (-1 = no cap; `privacy_event_count` still reflects total).
 
 ## Customizing for New Projects
 - Duplicate the templates under `/tasks`, `docs/`, and `.agent/` for your task ID and keep checklist status mirrored (`[ ]` → `[x]`) with links to the manifest that proves each outcome.

package/dist/bin/codex-orchestrator.js

@@ -16,6 +16,8 @@ import { formatDevtoolsSetupSummary, runDevtoolsSetup } from '../orchestrator/sr
 import { loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
 import { slugify } from '../orchestrator/src/cli/utils/strings.js';
 import { serveMcp } from '../orchestrator/src/cli/mcp.js';
+import { startDelegationServer } from '../orchestrator/src/cli/delegationServer.js';
+import { splitDelegationConfigOverrides } from '../orchestrator/src/cli/config/delegationConfig.js';
 async function main() {
     const args = process.argv.slice(2);
     const command = args.shift();
@@ -66,6 +68,10 @@ async function main() {
             case 'mcp':
                 await handleMcp(args);
                 break;
+            case 'delegate-server':
+            case 'delegation-server':
+                await handleDelegationServer(args);
+                break;
             case 'version':
                 printVersion();
                 break;
@@ -506,6 +512,34 @@ async function handleMcp(rawArgs) {
     const dryRun = Boolean(flags['dry-run']);
     await serveMcp({ repoRoot, dryRun, extraArgs: positionals });
 }
+async function handleDelegationServer(rawArgs) {
+    const { flags } = parseArgs(rawArgs);
+    const repoRoot = typeof flags['repo'] === 'string' ? flags['repo'] : process.cwd();
+    const modeFlag = typeof flags['mode'] === 'string' ? flags['mode'] : undefined;
+    const overrideFlag = typeof flags['config'] === 'string'
+        ? flags['config']
+        : typeof flags['config-override'] === 'string'
+            ? flags['config-override']
+            : undefined;
+    const envMode = process.env.CODEX_DELEGATE_MODE?.trim();
+    const resolvedMode = modeFlag ?? envMode;
+    let mode;
+    if (resolvedMode) {
+        if (resolvedMode === 'full' || resolvedMode === 'question_only') {
+            mode = resolvedMode;
+        }
+        else {
+            console.warn(`Invalid delegate mode "${resolvedMode}". Falling back to config default.`);
+        }
+    }
+    const configOverrides = overrideFlag
+        ? splitDelegationConfigOverrides(overrideFlag).map((value) => ({
+            source: 'cli',
+            value
+        }))
+        : [];
+    await startDelegationServer({ repoRoot, mode, configOverrides });
+}
 function parseExecArgs(rawArgs) {
     const notifyTargets = [];
     let otelEndpoint = null;
@@ -687,6 +721,10 @@ Commands:
     --yes                 Apply setup by running "codex mcp add ...".
     --format json         Emit machine-readable output (dry-run only).
   mcp serve [--repo <path>] [--dry-run] [-- <extra args>]
+  delegate-server         Run the delegation MCP server (stdio).
+    --repo <path>         Repo root for config + manifests (default cwd).
+    --mode <full|question_only>  Limit tool surface for child runs.
+    --config "<key>=<value>[;...]"  Apply config overrides (repeat via separators).
   version | --version
 
   help                      Show this message.

package/dist/orchestrator/src/cli/config/delegationConfig.js

@@ -0,0 +1,485 @@
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { logger } from '../../logger.js';
+const require = createRequire(import.meta.url);
+const toml = require('@iarna/toml');
+const DEFAULT_ALLOWED_RUN_ROOTS = [];
+const DEFAULT_CONFIG = {
+    delegate: {
+        allowNested: false,
+        toolProfile: [],
+        allowedToolServers: [],
+        mode: 'question_only',
+        expiryFallback: 'pause'
+    },
+    rlm: {
+        policy: 'always',
+        environment: 'docker',
+        allowedEnvironments: ['docker'],
+        maxIterations: 50,
+        maxSubcalls: 200,
+        maxSubcallDepth: 1,
+        wallClockTimeoutMs: 30 * 60 * 1000,
+        budgetUsd: 0,
+        budgetTokens: 0,
+        rootModel: '',
+        subModel: ''
+    },
+    runner: {
+        mode: 'prod',
+        allowedModes: ['prod']
+    },
+    ui: {
+        controlEnabled: false,
+        bindHost: '127.0.0.1',
+        allowedBindHosts: ['127.0.0.1'],
+        allowedRunRoots: DEFAULT_ALLOWED_RUN_ROOTS
+    },
+    github: {
+        enabled: false,
+        operations: []
+    },
+    paths: {
+        allowedRoots: []
+    },
+    confirm: {
+        autoPause: true,
+        maxPending: 3,
+        expiresInMs: 15 * 60 * 1000
+    },
+    sandbox: {
+        network: false
+    }
+};
+const SOURCE_PRIORITY = {
+    global: 1,
+    repo: 2,
+    env: 3,
+    cli: 4
+};
+export async function loadDelegationConfigFiles(options) {
+    const env = options.env ?? process.env;
+    const codexHome = options.codexHome ?? resolveCodexHome(env);
+    const globalPath = join(codexHome, 'config.toml');
+    const repoPath = join(options.repoRoot, '.codex', 'orchestrator.toml');
+    const globalRaw = await readTomlFile(globalPath);
+    const repoRaw = await readTomlFile(repoPath);
+    return {
+        global: globalRaw ? normalizeLayer(globalRaw, 'global') : null,
+        repo: repoRaw ? normalizeLayer(repoRaw, 'repo') : null
+    };
+}
+export function computeEffectiveDelegationConfig(options) {
+    const sorted = [...options.layers].sort((a, b) => SOURCE_PRIORITY[a.source] - SOURCE_PRIORITY[b.source]);
+    const merged = sorted.reduce((acc, layer) => mergeLayer(acc, layer), {
+        source: 'global'
+    });
+    const repoLayer = sorted.find((layer) => layer.source === 'repo');
+    const defaults = structuredClone(DEFAULT_CONFIG);
+    const effective = {
+        delegate: {
+            ...defaults.delegate,
+            ...(merged.delegate ?? {})
+        },
+        rlm: {
+            ...defaults.rlm,
+            ...(merged.rlm ?? {})
+        },
+        runner: {
+            ...defaults.runner,
+            ...(merged.runner ?? {})
+        },
+        ui: {
+            ...defaults.ui,
+            ...(merged.ui ?? {})
+        },
+        github: {
+            ...defaults.github
+        },
+        paths: {
+            ...defaults.paths,
+            ...(merged.paths ?? {})
+        },
+        confirm: {
+            ...defaults.confirm,
+            ...(merged.confirm ?? {})
+        },
+        sandbox: {
+            ...defaults.sandbox,
+            ...(merged.sandbox ?? {})
+        }
+    };
+    if (effective.delegate.mode !== 'full' && effective.delegate.mode !== 'question_only') {
+        effective.delegate.mode = defaults.delegate.mode;
+    }
+    const repoAllowedRoots = typeof repoLayer?.paths?.allowedRoots !== 'undefined' ? repoLayer.paths.allowedRoots : [options.repoRoot];
+    const repoCapRoots = normalizeRoots(repoAllowedRoots);
+    const requestedRoots = typeof merged.paths?.allowedRoots !== 'undefined' ? merged.paths.allowedRoots : repoCapRoots;
+    const candidateRoots = normalizeRoots(requestedRoots);
+    effective.paths.allowedRoots = intersectRoots(repoCapRoots, candidateRoots);
+    const repoToolCap = repoLayer?.delegate?.allowedToolServers ?? [];
+    const requestedToolProfile = merged.delegate?.toolProfile ?? repoToolCap;
+    effective.delegate.allowedToolServers = [...repoToolCap];
+    effective.delegate.toolProfile = intersectExact(repoToolCap, requestedToolProfile);
+    const repoAllowedModes = repoLayer?.runner?.allowedModes ?? defaults.runner.allowedModes;
+    effective.runner.allowedModes = repoAllowedModes;
+    const requestedMode = merged.runner?.mode ?? defaults.runner.mode;
+    effective.runner.mode = repoAllowedModes.includes(requestedMode) ? requestedMode : repoAllowedModes[0] ?? defaults.runner.mode;
+    const repoAllowedEnvs = repoLayer?.rlm?.allowedEnvironments ?? defaults.rlm.allowedEnvironments;
+    effective.rlm.allowedEnvironments = repoAllowedEnvs;
+    const requestedEnv = merged.rlm?.environment ?? defaults.rlm.environment;
+    effective.rlm.environment = repoAllowedEnvs.includes(requestedEnv) ? requestedEnv : repoAllowedEnvs[0] ?? defaults.rlm.environment;
+    const repoAllowedBindHosts = repoLayer?.ui?.allowedBindHosts ?? defaults.ui.allowedBindHosts;
+    effective.ui.allowedBindHosts = repoAllowedBindHosts;
+    const requestedBindHost = merged.ui?.bindHost ?? defaults.ui.bindHost;
+    effective.ui.bindHost = repoAllowedBindHosts.includes(requestedBindHost)
+        ? requestedBindHost
+        : repoAllowedBindHosts[0] ?? defaults.ui.bindHost;
+    const repoAllowedRunRoots = typeof repoLayer?.ui?.allowedRunRoots !== 'undefined' ? repoLayer.ui.allowedRunRoots : [options.repoRoot];
+    const repoCapRunRoots = normalizeRoots(repoAllowedRunRoots);
+    const hasRunRootsOverride = typeof repoLayer?.ui?.allowedRunRoots !== 'undefined' || typeof merged.ui?.allowedRunRoots !== 'undefined';
+    const requestedRunRoots = typeof merged.ui?.allowedRunRoots !== 'undefined' ? merged.ui.allowedRunRoots : repoCapRunRoots;
+    const candidateRunRoots = normalizeRoots(requestedRunRoots);
+    effective.ui.allowedRunRoots = intersectRoots(repoCapRunRoots, candidateRunRoots);
+    if (hasRunRootsOverride && effective.ui.allowedRunRoots.length === 0 && repoCapRunRoots.length > 0) {
+        logger.warn('ui.allowedRunRoots override produced empty intersection with repo cap; UI run access disabled.');
+    }
+    const repoAllowNetwork = Boolean(repoLayer?.sandbox?.network ?? defaults.sandbox.network);
+    effective.sandbox.network = repoAllowNetwork && Boolean(merged.sandbox?.network ?? defaults.sandbox.network);
+    const githubEnabled = Boolean(repoLayer?.github?.enabled ?? false);
+    effective.github.enabled = githubEnabled;
+    effective.github.operations = githubEnabled ? [...(repoLayer?.github?.operations ?? [])] : [];
+    if (!hasRunRootsOverride && effective.ui.allowedRunRoots.length === 0) {
+        effective.ui.allowedRunRoots = [options.repoRoot];
+    }
+    return effective;
+}
+function mergeLayer(base, update) {
+    const merged = {
+        ...base,
+        source: update.source
+    };
+    merged.delegate = mergeSection(base.delegate, update.delegate);
+    merged.rlm = mergeSection(base.rlm, update.rlm);
+    merged.runner = mergeSection(base.runner, update.runner);
+    merged.ui = mergeSection(base.ui, update.ui);
+    merged.github = mergeSection(base.github, update.github);
+    merged.paths = mergeSection(base.paths, update.paths);
+    merged.confirm = mergeSection(base.confirm, update.confirm);
+    merged.sandbox = mergeSection(base.sandbox, update.sandbox);
+    return merged;
+}
+function mergeSection(base, update) {
+    if (!update) {
+        return base;
+    }
+    if (!base) {
+        const cleaned = {};
+        for (const [key, value] of Object.entries(update)) {
+            if (typeof value === 'undefined') {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                cleaned[key] = [...value];
+                continue;
+            }
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                cleaned[key] = { ...value };
+                continue;
+            }
+            cleaned[key] = value;
+        }
+        return cleaned;
+    }
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(update)) {
+        if (typeof value === 'undefined') {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            merged[key] = [...value];
+            continue;
+        }
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            merged[key] = { ...merged[key], ...value };
+            continue;
+        }
+        merged[key] = value;
+    }
+    return merged;
+}
+async function readTomlFile(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        const parsed = toml.parse(raw);
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+function normalizeLayer(raw, source) {
+    return {
+        source,
+        delegate: normalizeDelegate(raw.delegate),
+        rlm: normalizeRlm(raw.rlm),
+        runner: normalizeRunner(raw.runner),
+        ui: normalizeUi(raw.ui),
+        github: normalizeGithub(raw.github),
+        paths: normalizePaths(raw.paths),
+        confirm: normalizeConfirm(raw.confirm),
+        sandbox: normalizeSandbox(raw.sandbox)
+    };
+}
+function normalizeDelegate(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return {
+        allowNested: asBoolean(record.allow_nested ?? record.allowNested),
+        toolProfile: asStringArray(record.tool_profile ?? record.toolProfile),
+        allowedToolServers: asStringArray(record.allowed_tool_servers ?? record.allowedToolServers),
+        mode: asString(record.mode),
+        expiryFallback: asString(record.question_expiry_fallback ?? record.expiryFallback)
+    };
+}
+function normalizeRlm(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return {
+        policy: asString(record.policy),
+        environment: asString(record.environment) ?? asString(record.env),
+        allowedEnvironments: asStringArray(record.allowed_environments ?? record.allowedEnvironments),
+        maxIterations: asNumber(record.max_iterations ?? record.maxIterations),
+        maxSubcalls: asNumber(record.max_subcalls ?? record.maxSubcalls),
+        maxSubcallDepth: asNumber(record.max_subcall_depth ?? record.maxSubcallDepth),
+        wallClockTimeoutMs: asNumber(record.wall_clock_timeout_ms ?? record.wallClockTimeoutMs),
+        budgetUsd: asNumber(record.budget_usd ?? record.budgetUsd),
+        budgetTokens: asNumber(record.budget_tokens ?? record.budgetTokens),
+        rootModel: asString(record.root_model ?? record.rootModel),
+        subModel: asString(record.sub_model ?? record.subModel)
+    };
+}
+function normalizeRunner(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return {
+        mode: asString(record.mode),
+        allowedModes: asStringArray(record.allowed_modes ?? record.allowedModes)
+    };
+}
+function normalizeUi(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return {
+        controlEnabled: asBoolean(record.control_enabled ?? record.controlEnabled),
+        bindHost: asString(record.bind_host ?? record.bindHost),
+        allowedBindHosts: asStringArray(record.allowed_bind_hosts ?? record.allowedBindHosts),
+        allowedRunRoots: asStringArray(record.allowed_run_roots ?? record.allowedRunRoots)
+    };
+}
+function normalizeGithub(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return {
+        enabled: asBoolean(record.enabled),
+        operations: asStringArray(record.operations)
+    };
+}
+function normalizePaths(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return {
+        allowedRoots: asStringArray(record.allowed_roots ?? record.allowedRoots)
+    };
+}
+function normalizeConfirm(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return {
+        autoPause: asBoolean(record.auto_pause ?? record.autoPause),
+        maxPending: asNumber(record.max_pending ?? record.maxPending),
+        expiresInMs: asNumber(record.expires_in_ms ?? record.expiresInMs)
+    };
+}
+function normalizeSandbox(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return {
+        network: asBoolean(record.network)
+    };
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function asBoolean(value) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    return undefined;
+}
+function asString(value) {
+    if (typeof value === 'string' && value.trim().length > 0) {
+        return value.trim();
+    }
+    return undefined;
+}
+function asStringArray(value) {
+    if (value === null || typeof value === 'undefined')
+        return undefined;
+    if (Array.isArray(value)) {
+        return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0).map((entry) => entry.trim());
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? [trimmed] : [];
+    }
+    return undefined;
+}
+function asNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    return undefined;
+}
+function resolveCodexHome(env) {
+    const override = env.CODEX_HOME?.trim();
+    if (override) {
+        return isAbsolute(override) ? override : resolve(process.cwd(), override);
+    }
+    return join(homedir(), '.codex');
+}
+function normalizeRoots(roots) {
+    const normalized = roots
+        .filter((root) => typeof root === 'string')
+        .map((root) => realpathSafe(resolve(root)))
+        .filter((root) => root.length > 0);
+    return Array.from(new Set(normalized));
+}
+function intersectExact(cap, requested) {
+    if (cap.length === 0 || requested.length === 0) {
+        return [];
+    }
+    const set = new Set(cap);
+    return requested.filter((entry) => set.has(entry));
+}
+function intersectRoots(cap, requested) {
+    if (cap.length === 0 || requested.length === 0) {
+        return [];
+    }
+    const resolvedCap = cap.map((root) => realpathSafe(resolve(root)));
+    return requested
+        .map((root) => realpathSafe(resolve(root)))
+        .filter((candidate) => resolvedCap.some((allowed) => isWithinRoot(allowed, candidate)));
+}
+function isWithinRoot(root, candidate) {
+    const normalizedRoot = normalizePath(realpathSafe(resolve(root)));
+    const normalizedCandidate = normalizePath(realpathSafe(resolve(candidate)));
+    if (normalizedRoot === normalizedCandidate) {
+        return true;
+    }
+    const relativePath = relative(normalizedRoot, normalizedCandidate);
+    if (!relativePath) {
+        return true;
+    }
+    if (isAbsolute(relativePath)) {
+        return false;
+    }
+    return !relativePath.startsWith(`..${sep}`) && relativePath !== '..';
+}
+function realpathSafe(pathname) {
+    try {
+        return realpathSync(pathname);
+    }
+    catch {
+        return pathname;
+    }
+}
+function normalizePath(pathname) {
+    return process.platform === 'win32' ? pathname.toLowerCase() : pathname;
+}
+export function resolveConfigDir(pathname) {
+    return dirname(pathname);
+}
+export function splitDelegationConfigOverrides(raw) {
+    if (!raw) {
+        return [];
+    }
+    const entries = [];
+    let current = '';
+    let bracketDepth = 0;
+    let inSingle = false;
+    let inDouble = false;
+    let escaping = false;
+    const flush = () => {
+        const trimmed = current.trim();
+        if (trimmed) {
+            entries.push(trimmed);
+        }
+        current = '';
+    };
+    for (const char of raw) {
+        if (escaping) {
+            current += char;
+            escaping = false;
+            continue;
+        }
+        if ((inSingle || inDouble) && char === '\\') {
+            current += char;
+            escaping = true;
+            continue;
+        }
+        if (!inDouble && char === '\'') {
+            inSingle = !inSingle;
+            current += char;
+            continue;
+        }
+        if (!inSingle && char === '"') {
+            inDouble = !inDouble;
+            current += char;
+            continue;
+        }
+        if (!inSingle && !inDouble) {
+            if (char === '[') {
+                bracketDepth += 1;
+            }
+            else if (char === ']') {
+                bracketDepth = Math.max(0, bracketDepth - 1);
+            }
+            if (bracketDepth === 0 && (char === ',' || char === ';' || char === '\n')) {
+                flush();
+                continue;
+            }
+        }
+        current += char;
+    }
+    flush();
+    return entries;
+}
+export function parseDelegationConfigOverride(value, source) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const parsed = toml.parse(trimmed);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    return normalizeLayer(parsed, source);
+}