@vela-science/canopus 0.4.0-rc.1

package/dist/src/engines/codex-events.d.ts

@@ -0,0 +1,25 @@
+import type { EngineUsage } from "./engine.js";
+export interface CodexEventSummary {
+    usage: EngineUsage;
+    eventTypes: string[];
+    actionTypes: string[];
+}
+export interface CodexStructuralSummary {
+    lines: number;
+    parsed_lines: number;
+    invalid_lines: number;
+    event_types: Record<string, number>;
+    item_types: Record<string, number>;
+}
+/**
+ * Describe only the shape of a Codex JSONL stream. Values that could contain
+ * prompts, paths, commands, host data, or credentials are never returned.
+ */
+export declare function summarizeCodexStructure(value: string): CodexStructuralSummary;
+/**
+ * Extract a bounded diagnostic from Codex's documented JSONL failure events.
+ * Raw stderr and unstructured stdout are intentionally excluded because they
+ * can contain credential, host, or prompt material.
+ */
+export declare function summarizeCodexFailure(value: string): string;
+export declare function parseCodexEvents(value: string): CodexEventSummary;

package/dist/src/engines/codex-events.js

@@ -0,0 +1,219 @@
+import { objectAt } from "../contracts/validation.js";
+const EVENT_TYPES = new Set([
+    "thread.started",
+    "turn.started",
+    "item.started",
+    "item.updated",
+    "item.completed",
+    "turn.completed",
+]);
+const PASSIVE_ITEMS = new Set(["agent_message", "reasoning", "todo_list"]);
+const ACTION_ITEMS = new Set(["command_execution", "file_change"]);
+const FORBIDDEN_COMMAND = /(?:^|[\s;&|])(?:vela\s+sign|git\s+push|gh\s+|curl\s+|wget\s+|ssh\s+)/iu;
+const SECRET_ASSIGNMENT = /\b(?:api[_-]?key|access[_-]?token|authorization|password|secret)\b\s*[:=]\s*[^\s,;]+/giu;
+const SECRET_TOKEN = /\b(?:sk|sess|key)-[A-Za-z0-9_-]{8,}\b/gu;
+const BEARER_TOKEN = /\bBearer\s+[A-Za-z0-9._~+\/-]+=*/giu;
+const URL_WITH_QUERY = /https?:\/\/[^\s?#]+[?#][^\s]*/giu;
+const MAX_FAILURE_LINES = 256;
+const MAX_FAILURE_MESSAGE_CHARS = 512;
+function safeEventLabel(value) {
+    return typeof value === "string" &&
+        (EVENT_TYPES.has(value) || value === "error" || value === "turn.failed")
+        ? value
+        : "other";
+}
+function safeItemLabel(value) {
+    return typeof value === "string" &&
+        (PASSIVE_ITEMS.has(value) || ACTION_ITEMS.has(value) || value === "error")
+        ? value
+        : "other";
+}
+function increment(counts, label) {
+    counts[label] = (counts[label] ?? 0) + 1;
+}
+/**
+ * Describe only the shape of a Codex JSONL stream. Values that could contain
+ * prompts, paths, commands, host data, or credentials are never returned.
+ */
+export function summarizeCodexStructure(value) {
+    const summary = {
+        lines: 0,
+        parsed_lines: 0,
+        invalid_lines: 0,
+        event_types: {},
+        item_types: {},
+    };
+    for (const line of value.split("\n")) {
+        if (line.length === 0)
+            continue;
+        summary.lines += 1;
+        if (Buffer.byteLength(line) > 1_048_576) {
+            summary.invalid_lines += 1;
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            summary.invalid_lines += 1;
+            continue;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            summary.invalid_lines += 1;
+            continue;
+        }
+        const event = parsed;
+        summary.parsed_lines += 1;
+        increment(summary.event_types, safeEventLabel(event.type));
+        if (typeof event.item === "object" && event.item !== null && !Array.isArray(event.item)) {
+            increment(summary.item_types, safeItemLabel(event.item.type));
+        }
+    }
+    summary.event_types = Object.fromEntries(Object.entries(summary.event_types).sort());
+    summary.item_types = Object.fromEntries(Object.entries(summary.item_types).sort());
+    return summary;
+}
+function safeDiagnostic(value) {
+    const normalized = value
+        .replace(/[\u0000-\u001f\u007f]+/gu, " ")
+        .replace(URL_WITH_QUERY, "[url-with-query-redacted]")
+        .replace(BEARER_TOKEN, "Bearer [redacted]")
+        .replace(SECRET_TOKEN, "[secret-redacted]")
+        .replace(SECRET_ASSIGNMENT, "[secret-assignment-redacted]")
+        .replace(/\s+/gu, " ")
+        .trim();
+    return [...normalized].slice(0, MAX_FAILURE_MESSAGE_CHARS).join("");
+}
+/**
+ * Extract a bounded diagnostic from Codex's documented JSONL failure events.
+ * Raw stderr and unstructured stdout are intentionally excluded because they
+ * can contain credential, host, or prompt material.
+ */
+export function summarizeCodexFailure(value) {
+    const diagnostics = [];
+    const lines = value.split("\n").filter((line) => line.length > 0).slice(0, MAX_FAILURE_LINES);
+    for (const line of lines) {
+        if (Buffer.byteLength(line) > 1_048_576)
+            continue;
+        let event;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+                continue;
+            event = parsed;
+        }
+        catch {
+            continue;
+        }
+        let message;
+        if (event.type === "error") {
+            message = event.message;
+        }
+        else if (event.type === "turn.failed") {
+            const error = event.error;
+            if (typeof error === "object" && error !== null && !Array.isArray(error)) {
+                message = error.message;
+            }
+        }
+        else if ((event.type === "item.started" ||
+            event.type === "item.updated" ||
+            event.type === "item.completed") &&
+            typeof event.item === "object" &&
+            event.item !== null &&
+            !Array.isArray(event.item)) {
+            const item = event.item;
+            if (item.type === "error")
+                message = item.message;
+        }
+        if (typeof message !== "string" || message.length === 0)
+            continue;
+        const diagnostic = safeDiagnostic(message);
+        if (diagnostic.length > 0 && !diagnostics.includes(diagnostic))
+            diagnostics.push(diagnostic);
+        if (diagnostics.length === 3)
+            break;
+    }
+    return diagnostics.length === 0
+        ? "no structured Codex failure event"
+        : diagnostics.join("; ");
+}
+function usageInteger(value, at) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${at} must be a nonnegative integer`);
+    }
+    return value;
+}
+export function parseCodexEvents(value) {
+    const eventTypes = new Set();
+    const actionTypes = new Set();
+    const itemKinds = new Map();
+    let usage;
+    const lines = value.split("\n").filter((line) => line.length > 0);
+    if (lines.length === 0)
+        throw new Error("Codex returned no JSONL events");
+    for (const [index, line] of lines.entries()) {
+        if (Buffer.byteLength(line) > 1_048_576)
+            throw new Error(`Codex event ${index} is oversized`);
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`Codex event ${index} is invalid JSON`);
+        }
+        const event = objectAt(parsed, `codex_event[${index}]`);
+        const type = event.type;
+        if (typeof type !== "string" || !EVENT_TYPES.has(type)) {
+            throw new Error(`Codex event ${index} has unknown type ${String(type)}`);
+        }
+        eventTypes.add(type);
+        if (type === "thread.started" && (typeof event.thread_id !== "string" || event.thread_id === "")) {
+            throw new Error("Codex thread.started event has no thread_id");
+        }
+        if (type === "turn.completed") {
+            const rawUsage = objectAt(event.usage, "codex turn.completed.usage");
+            usage = {
+                input_tokens: usageInteger(rawUsage.input_tokens, "usage.input_tokens"),
+                cached_input_tokens: usageInteger(rawUsage.cached_input_tokens, "usage.cached_input_tokens"),
+                output_tokens: usageInteger(rawUsage.output_tokens, "usage.output_tokens"),
+                reasoning_output_tokens: usageInteger(rawUsage.reasoning_output_tokens, "usage.reasoning_output_tokens"),
+            };
+        }
+        if (type === "item.started" || type === "item.updated" || type === "item.completed") {
+            const item = objectAt(event.item, `codex ${type}.item`);
+            if (typeof item.id !== "string" || item.id === "" || typeof item.type !== "string") {
+                throw new Error(`Codex ${type} has a malformed item`);
+            }
+            const previous = itemKinds.get(item.id);
+            if (previous !== undefined && previous !== item.type) {
+                throw new Error(`Codex item ${item.id} changed type`);
+            }
+            itemKinds.set(item.id, item.type);
+            if (!PASSIVE_ITEMS.has(item.type) && !ACTION_ITEMS.has(item.type)) {
+                throw new Error(`Codex emitted unsupported action type ${item.type}`);
+            }
+            if (ACTION_ITEMS.has(item.type))
+                actionTypes.add(item.type);
+            if (type === "item.completed" && item.type === "command_execution") {
+                if (typeof item.command !== "string" || item.command === "") {
+                    throw new Error("Codex completed command has no command text");
+                }
+                if (FORBIDDEN_COMMAND.test(item.command)) {
+                    throw new Error(`Codex attempted a forbidden external or custody action: ${item.command}`);
+                }
+            }
+        }
+    }
+    for (const required of ["thread.started", "turn.started", "turn.completed"]) {
+        if (!eventTypes.has(required))
+            throw new Error(`Codex event stream is missing ${required}`);
+    }
+    if (usage === undefined)
+        throw new Error("Codex event stream has no usage record");
+    return {
+        usage,
+        eventTypes: [...eventTypes].sort(),
+        actionTypes: [...actionTypes].sort(),
+    };
+}

package/dist/src/engines/codex-exec.d.ts

@@ -0,0 +1,17 @@
+import { type CommandRunner } from "../util/command.js";
+import type { Engine, EngineContext, EngineResult } from "./engine.js";
+export interface CodexEngineOptions {
+    binary: string;
+    expectedSha256: string;
+    expectedVersion: string;
+    model: string;
+    authHome: string;
+    outputSchema: string;
+    runner?: CommandRunner;
+}
+export declare class CodexExecEngine implements Engine {
+    #private;
+    readonly name = "codex-exec";
+    constructor(options: CodexEngineOptions);
+    run(context: EngineContext): Promise<EngineResult>;
+}

package/dist/src/engines/codex-exec.js

@@ -0,0 +1,136 @@
+import path from "node:path";
+import { parseCandidateDraft, assertDraftArtifactsAllowed } from "../candidate/validate.js";
+import { roleInstruction } from "../roles.js";
+import { canonicalJson, contentDigest, sha256Bytes } from "../util/canonical.js";
+import { isolatedEnvironment, runCommand, } from "../util/command.js";
+import { MAX_EXECUTABLE_BYTES, readBoundedRegularFile, sha256RegularFile } from "../util/files.js";
+import { parseCodexEvents, summarizeCodexFailure } from "./codex-events.js";
+import { prepareIsolatedCodexHome, removeIsolatedCodexHome } from "./codex-home.js";
+import { CODEX_TOOL_FEATURES, sandboxedToolFreeCodexExecArgv, } from "./codex-tool-free.js";
+function prompt(mission, briefing) {
+    return [
+        "Execute one bounded Canopus research mission.",
+        roleInstruction(mission.role),
+        "This is a tool-free synthesis stage. You cannot inspect the host or run commands.",
+        "Use only the mission and the exact Vela work briefing supplied below.",
+        "Return artifact bytes inline as UTF-8 content. The trusted harness materializes and verifies them later.",
+        "Do not request tools, network access, external messages, Vela signing, human keys, or accepted-state writes.",
+        "Worker status reports producer completion, not verifier or scientific standing. Return status success when you produced all artifact bytes required by the output contract, while stating that separate verification remains pending.",
+        "Return null only when the bounded work produced no candidate, and failed only when you could not produce a contract-complete candidate or observed disqualifying evidence. Do not turn verifier failure into a success claim.",
+        "Return only the supplied engine-output JSON shape.",
+        "Mission:",
+        canonicalJson(mission),
+        "Vela work briefing:",
+        canonicalJson(briefing),
+    ].join("\n");
+}
+export class CodexExecEngine {
+    name = "codex-exec";
+    #options;
+    #runner;
+    constructor(options) {
+        this.#options = options;
+        this.#runner = options.runner ?? runCommand;
+    }
+    async #version(cwd, home, timeoutMs) {
+        const result = await this.#runner({
+            argv: [this.#options.binary, "--version"],
+            cwd,
+            env: isolatedEnvironment(home),
+            timeoutMs,
+            maxOutputBytes: 4096,
+        });
+        const version = result.stdout.toString("utf8").trim();
+        if (result.exitCode !== 0 || result.stderr.length !== 0 || version !== this.#options.expectedVersion) {
+            throw new Error(`expected Codex ${this.#options.expectedVersion}, observed ${JSON.stringify(version)}`);
+        }
+        return version;
+    }
+    async run(context) {
+        context.budget.beginAttempt();
+        const binaryDigest = await sha256RegularFile(this.#options.binary, MAX_EXECUTABLE_BYTES);
+        if (binaryDigest !== this.#options.expectedSha256) {
+            throw new Error(`Codex binary digest mismatch: expected ${this.#options.expectedSha256}, observed ${binaryDigest}`);
+        }
+        context.budget.beginProcess();
+        const finalPath = path.join(context.paths.work, ".canopus-final.json");
+        const version = await this.#version(context.paths.work, context.paths.home, context.budget.remainingTimeMs());
+        context.budget.beginProcess();
+        const runtimeCodexHome = await prepareIsolatedCodexHome(this.#options.authHome, context.paths.home);
+        try {
+            const environment = {
+                ...isolatedEnvironment(context.paths.home),
+                CODEX_HOME: runtimeCodexHome,
+                NO_COLOR: "1",
+            };
+            const argv = await sandboxedToolFreeCodexExecArgv({
+                binary: this.#options.binary,
+                model: this.#options.model,
+                outputSchema: this.#options.outputSchema,
+                finalPath,
+                cwd: context.paths.work,
+                authHome: runtimeCodexHome,
+            });
+            const started = performance.now();
+            const workerPrompt = prompt(context.mission, context.briefing);
+            context.budget.addPrompt(Buffer.byteLength(workerPrompt));
+            const result = await this.#runner({
+                argv,
+                cwd: context.paths.work,
+                env: environment,
+                timeoutMs: context.budget.remainingTimeMs(),
+                maxOutputBytes: context.budget.remainingOutputBytes(),
+                stdin: workerPrompt,
+            });
+            context.budget.addOutput(result.stdout.length + result.stderr.length);
+            if (result.exitCode !== 0) {
+                throw new Error(`codex exec exited ${result.exitCode}: ` +
+                    `${summarizeCodexFailure(result.stdout.toString("utf8"))}; ` +
+                    `stdout_sha256=${sha256Bytes(result.stdout)}; stderr_sha256=${sha256Bytes(result.stderr)}`);
+            }
+            const events = parseCodexEvents(result.stdout.toString("utf8"));
+            if (events.actionTypes.length !== 0) {
+                throw new Error(`tool-free Codex worker emitted actions: ${events.actionTypes.join(",")}`);
+            }
+            context.budget.addTokens(events.usage.input_tokens + events.usage.output_tokens);
+            const finalBytes = await readBoundedRegularFile(finalPath, 1_048_576);
+            context.budget.addOutput(finalBytes.length);
+            let raw;
+            try {
+                raw = JSON.parse(finalBytes.toString("utf8"));
+            }
+            catch (error) {
+                throw new Error(`Codex final response is not JSON: ${String(error)}`);
+            }
+            const draft = parseCandidateDraft(raw);
+            assertDraftArtifactsAllowed(draft, context.mission.allowed_paths);
+            return {
+                draft,
+                engine: {
+                    name: this.name,
+                    version,
+                    binary_sha256: binaryDigest,
+                    model: this.#options.model,
+                    configuration_sha256: contentDigest({
+                        binary_sha256: binaryDigest,
+                        codex_version: version,
+                        disabled_features: CODEX_TOOL_FEATURES,
+                        model: this.#options.model,
+                        output_schema_sha256: sha256Bytes(await readBoundedRegularFile(this.#options.outputSchema, 1_048_576)),
+                        outer_sandbox: "macos_seatbelt_bounded_reads",
+                        product_sandbox: "read-only",
+                    }),
+                },
+                usage: events.usage,
+                wallTimeMs: Math.max(0, Math.round(performance.now() - started)),
+                eventTypes: events.eventTypes,
+                actionTypes: events.actionTypes,
+                eventsDigest: sha256Bytes(result.stdout),
+                stderrDigest: sha256Bytes(result.stderr),
+            };
+        }
+        finally {
+            await removeIsolatedCodexHome(runtimeCodexHome);
+        }
+    }
+}

package/dist/src/engines/codex-home.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stage only the credential and optional model catalog needed by Codex into a
+ * fresh, disposable home. Native Codex writes installation_id during startup;
+ * it must never receive write access to the user's real credential directory.
+ */
+export declare function prepareIsolatedCodexHome(sourceHome: string, runtimeRoot: string, config?: Uint8Array): Promise<string>;
+export declare function removeIsolatedCodexHome(codexHome: string): Promise<void>;

package/dist/src/engines/codex-home.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { readBoundedRegularFile } from "../util/files.js";
+const AUTH_MAX_BYTES = 2 * 1024 * 1024;
+const MODEL_CATALOG_MAX_BYTES = 32 * 1024 * 1024;
+async function optionalBoundedFile(file, maxBytes) {
+    try {
+        return await readBoundedRegularFile(file, maxBytes);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Stage only the credential and optional model catalog needed by Codex into a
+ * fresh, disposable home. Native Codex writes installation_id during startup;
+ * it must never receive write access to the user's real credential directory.
+ */
+export async function prepareIsolatedCodexHome(sourceHome, runtimeRoot, config) {
+    const source = path.resolve(sourceHome);
+    const destination = path.join(path.resolve(runtimeRoot), "codex-runtime");
+    await mkdir(destination, { mode: 0o700 });
+    try {
+        const auth = await readBoundedRegularFile(path.join(source, "auth.json"), AUTH_MAX_BYTES);
+        const modelCatalog = await optionalBoundedFile(path.join(source, "models_cache.json"), MODEL_CATALOG_MAX_BYTES);
+        await writeFile(path.join(destination, "auth.json"), auth, { flag: "wx", mode: 0o600 });
+        if (modelCatalog !== undefined) {
+            await writeFile(path.join(destination, "models_cache.json"), modelCatalog, {
+                flag: "wx",
+                mode: 0o600,
+            });
+        }
+        if (config !== undefined) {
+            await writeFile(path.join(destination, "config.toml"), config, {
+                flag: "wx",
+                mode: 0o600,
+            });
+        }
+        return destination;
+    }
+    catch (error) {
+        await rm(destination, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function removeIsolatedCodexHome(codexHome) {
+    await rm(codexHome, { recursive: true, force: true });
+}

package/dist/src/engines/codex-tool-free.d.ts

@@ -0,0 +1,26 @@
+export declare const CODEX_TOOL_FEATURES: readonly ["apply_patch_freeform", "apply_patch_streaming_events", "apps", "artifact", "browser_use", "browser_use_external", "computer_use", "enable_mcp_apps", "goals", "hooks", "image_generation", "in_app_browser", "memories", "multi_agent", "plugin_sharing", "remote_plugin", "shell_snapshot", "shell_tool", "tool_suggest", "unified_exec", "workspace_dependencies"];
+export interface ToolFreeCodexArgs {
+    binary: string;
+    model: string;
+    outputSchema: string;
+    finalPath: string;
+    cwd: string;
+    reasoningEffort?: string;
+}
+export interface SandboxedToolFreeCodexArgs extends ToolFreeCodexArgs {
+    authHome: string;
+}
+/**
+ * Wrap Codex itself in a host read boundary. Codex 0.139 always registers
+ * view_image even when every feature-backed tool is disabled, so this outer
+ * sandbox is the control that makes an arbitrary host image unreadable.
+ */
+export declare function sandboxedToolFreeCodexExecArgv(options: SandboxedToolFreeCodexArgs): Promise<string[]>;
+/**
+ * Build the complete, pinned Codex lane used for untrusted synthesis.
+ *
+ * Read-only sandboxing alone still permits host reads. This lane registers no
+ * shell, patch, browser, app, MCP, memory, or computer-use surface at all.
+ * The only accepted product is the final response constrained by outputSchema.
+ */
+export declare function toolFreeCodexExecArgv(options: ToolFreeCodexArgs): string[];