@fusionkit/tool-codex 0.1.6

package/dist/harness.d.ts

@@ -0,0 +1,70 @@
+import type { HarnessAdapter } from "@fusionkit/ensemble";
+export type CodexSandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export type CodexApprovalPolicy = "untrusted" | "on-failure" | "on-request" | "never";
+export type CodexAmbientProvider = {
+    kind: "ambient";
+    credentialEnvNames?: readonly string[];
+};
+export type CodexResponsesProvider = {
+    kind: "responses";
+    baseUrl: string;
+    apiKey?: string;
+    apiKeyEnvName?: string;
+    requiresOpenAiAuth?: boolean;
+    providerId?: string;
+    name?: string;
+};
+export type CodexOpenAiCompatibleProvider = {
+    kind: "openai-compatible";
+    baseUrl: string;
+    apiKey?: string;
+    apiKeyEnvName?: string;
+    defaultModel?: string;
+    providerId?: string;
+    name?: string;
+};
+export type CodexProvider = CodexAmbientProvider | CodexResponsesProvider | CodexOpenAiCompatibleProvider;
+export type CodexExecInput = {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    timeoutMs?: number;
+};
+export type CodexExecResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut?: boolean;
+};
+export type CodexExecRunner = (input: CodexExecInput) => Promise<CodexExecResult> | CodexExecResult;
+export type CodexHarnessOptions = {
+    id?: string;
+    command?: string;
+    cwd?: string;
+    timeoutMs?: number;
+    env?: Record<string, string | undefined>;
+    provider?: CodexProvider;
+    runner?: CodexExecRunner;
+    sandboxMode?: CodexSandboxMode;
+    approvalPolicy?: CodexApprovalPolicy;
+    keepCodexHome?: boolean;
+};
+export type CodexHarnessEnv = Record<string, string | undefined>;
+export type CodexConfigTomlInput = {
+    model: string;
+    sandboxMode: CodexSandboxMode;
+    approvalPolicy: CodexApprovalPolicy;
+    provider?: {
+        providerId?: string;
+        name?: string;
+        baseUrl: string;
+        apiKeyEnvName?: string;
+        requiresOpenAiAuth: boolean;
+    };
+};
+export declare function codexHarnessCredentialSkipReason(env?: CodexHarnessEnv, options?: Pick<CodexHarnessOptions, "provider">): string | undefined;
+export declare function codexConfigToml(input: CodexConfigTomlInput): string;
+export declare function defaultCodexRunner(input: CodexExecInput): Promise<CodexExecResult>;
+export declare function createCodexHarness(options?: CodexHarnessOptions): HarnessAdapter;
+export declare const codexHarness: typeof createCodexHarness;

package/dist/harness.js

@@ -0,0 +1,436 @@
+import { spawn } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { artifactHash } from "@fusionkit/protocol";
+import { OpenAiBackend, startGateway } from "@fusionkit/model-gateway";
+import { buildSkippedCandidate, definedEnv, normalizeApiBaseUrl, readEnv } from "@fusionkit/tools";
+const DEFAULT_CODEX_COMMAND = "codex";
+const DEFAULT_PROVIDER_ID = "fusionkit-codex";
+const DEFAULT_PROVIDER_NAME = "FusionKit Codex";
+const DEFAULT_CREDENTIAL_ENV_NAMES = ["CODEX_API_KEY", "OPENAI_API_KEY"];
+const INLINE_PROVIDER_API_KEY_ENV = "FUSIONKIT_CODEX_PROVIDER_API_KEY";
+const CODEX_AUTH_FILE = "auth.json";
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function stripResponsesRoute(baseUrl) {
+    return baseUrl.replace(/\/responses\/?$/, "");
+}
+function isLoopbackUrl(baseUrl) {
+    try {
+        const url = new URL(baseUrl);
+        return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+    }
+    catch {
+        return false;
+    }
+}
+function firstPresentEnv(env, names) {
+    return names.find((name) => env[name] !== undefined && env[name].length > 0);
+}
+function codexHome(env) {
+    return env.CODEX_HOME && env.CODEX_HOME.length > 0
+        ? env.CODEX_HOME
+        : join(homedir(), ".codex");
+}
+function codexAuthFile(env) {
+    const path = join(codexHome(env), CODEX_AUTH_FILE);
+    return existsSync(path) ? path : undefined;
+}
+function providerFromEnv(env) {
+    const responsesBaseUrl = readEnv(env, "FUSIONKIT_CODEX_RESPONSES_BASE_URL") ?? env.CODEX_RESPONSES_BASE_URL;
+    if (responsesBaseUrl !== undefined && responsesBaseUrl.length > 0) {
+        const apiKeyEnvName = firstPresentEnv(env, [
+            "FUSIONKIT_CODEX_API_KEY",
+            "WARRANT_CODEX_API_KEY",
+            "CODEX_API_KEY",
+            "OPENAI_API_KEY"
+        ]);
+        return {
+            kind: "responses",
+            baseUrl: responsesBaseUrl,
+            ...(apiKeyEnvName ? { apiKeyEnvName } : {}),
+            requiresOpenAiAuth: !isLoopbackUrl(responsesBaseUrl)
+        };
+    }
+    const openAiBaseUrl = readEnv(env, "FUSIONKIT_CODEX_OPENAI_BASE_URL") ?? env.OPENAI_BASE_URL;
+    if (openAiBaseUrl !== undefined && openAiBaseUrl.length > 0) {
+        const apiKeyEnvName = firstPresentEnv(env, [
+            "FUSIONKIT_CODEX_OPENAI_API_KEY",
+            "WARRANT_CODEX_OPENAI_API_KEY",
+            "OPENAI_API_KEY"
+        ]);
+        return {
+            kind: "openai-compatible",
+            baseUrl: openAiBaseUrl,
+            ...(apiKeyEnvName ? { apiKeyEnvName } : {})
+        };
+    }
+    return { kind: "ambient" };
+}
+function credentialEnvName(provider, env) {
+    if (provider.apiKey !== undefined)
+        return INLINE_PROVIDER_API_KEY_ENV;
+    if (provider.apiKeyEnvName !== undefined)
+        return provider.apiKeyEnvName;
+    return firstPresentEnv(env, DEFAULT_CREDENTIAL_ENV_NAMES);
+}
+function missingCredentialReason(provider, env) {
+    switch (provider.kind) {
+        case "ambient": {
+            const names = provider.credentialEnvNames ?? DEFAULT_CREDENTIAL_ENV_NAMES;
+            return firstPresentEnv(env, names) === undefined && codexAuthFile(env) === undefined
+                ? `Codex credentials are absent; set ${names.join(" or ")} or configure a Responses/OpenAI-compatible provider.`
+                : undefined;
+        }
+        case "responses": {
+            if (provider.requiresOpenAiAuth === false || provider.apiKey !== undefined)
+                return undefined;
+            const envName = credentialEnvName(provider, env);
+            return envName === undefined || env[envName] === undefined || env[envName].length === 0
+                ? `Codex Responses provider credentials are absent; set ${provider.apiKeyEnvName ?? DEFAULT_CREDENTIAL_ENV_NAMES.join(" or ")} or mark the provider requiresOpenAiAuth=false for local endpoints.`
+                : undefined;
+        }
+        case "openai-compatible":
+            return undefined;
+        default: {
+            const exhausted = provider;
+            throw new Error(`unsupported Codex provider: ${String(exhausted)}`);
+        }
+    }
+}
+export function codexHarnessCredentialSkipReason(env = process.env, options = {}) {
+    const defined = definedEnv(env);
+    return missingCredentialReason(options.provider ?? providerFromEnv(defined), defined);
+}
+function sandboxModeFor(descriptor, override) {
+    if (override !== undefined)
+        return override;
+    switch (descriptor.policy.sideEffects) {
+        case "none":
+        case "read_only":
+            return "read-only";
+        case "writes_workspace":
+        case "network":
+        case "tool_execution":
+        case "unknown":
+            return "workspace-write";
+        default: {
+            const exhausted = descriptor.policy.sideEffects;
+            throw new Error(`unsupported side effects policy: ${String(exhausted)}`);
+        }
+    }
+}
+export function codexConfigToml(input) {
+    const lines = [
+        `model = ${tomlString(input.model)}`,
+        input.provider
+            ? `model_provider = ${tomlString(input.provider.providerId ?? DEFAULT_PROVIDER_ID)}`
+            : `model_provider = "openai"`,
+        `approval_policy = ${tomlString(input.approvalPolicy)}`,
+        `sandbox_mode = ${tomlString(input.sandboxMode)}`,
+        ""
+    ];
+    if (input.provider !== undefined) {
+        const providerId = input.provider.providerId ?? DEFAULT_PROVIDER_ID;
+        lines.push(`[model_providers.${providerId}]`, `name = ${tomlString(input.provider.name ?? DEFAULT_PROVIDER_NAME)}`, `base_url = ${tomlString(normalizeApiBaseUrl(stripResponsesRoute(input.provider.baseUrl)))}`, `wire_api = "responses"`, `requires_openai_auth = ${input.provider.requiresOpenAiAuth ? "true" : "false"}`);
+        if (input.provider.apiKeyEnvName !== undefined) {
+            lines.push(`env_key = ${tomlString(input.provider.apiKeyEnvName)}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function codexArgs(prompt) {
+    return ["exec", "--json", "--skip-git-repo-check", prompt];
+}
+function writeCodexHome(input) {
+    const codexHome = mkdtempSync(join(input.tempRoot, "candidate-"));
+    const providerConfig = input.provider.kind === "ambient"
+        ? undefined
+        : {
+            providerId: input.provider.providerId,
+            name: input.provider.name,
+            baseUrl: input.providerBaseUrl ?? input.provider.baseUrl,
+            apiKeyEnvName: input.provider.kind === "responses"
+                ? credentialEnvName(input.provider, input.env)
+                : undefined,
+            requiresOpenAiAuth: input.provider.kind === "responses"
+                ? input.provider.requiresOpenAiAuth ?? true
+                : false
+        };
+    writeFileSync(join(codexHome, "config.toml"), codexConfigToml({
+        model: input.model.model,
+        sandboxMode: sandboxModeFor(input.descriptor, input.sandboxMode),
+        approvalPolicy: input.approvalPolicy,
+        ...(providerConfig ? { provider: providerConfig } : {})
+    }));
+    if (input.provider.kind === "ambient" &&
+        firstPresentEnv(input.env, input.provider.credentialEnvNames ?? DEFAULT_CREDENTIAL_ENV_NAMES) === undefined) {
+        const authFile = codexAuthFile(input.env);
+        if (authFile !== undefined) {
+            copyFileSync(authFile, join(codexHome, CODEX_AUTH_FILE));
+        }
+    }
+    return codexHome;
+}
+export async function defaultCodexRunner(input) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(input.command, input.args, {
+            cwd: input.cwd,
+            env: input.env,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        const stdout = [];
+        const stderr = [];
+        let timedOut = false;
+        let timer;
+        if (input.timeoutMs !== undefined) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+            }, input.timeoutMs);
+        }
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolve({
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8"),
+                exitCode: timedOut ? 124 : code ?? 0,
+                ...(timedOut ? { timedOut } : {})
+            });
+        });
+    });
+}
+async function runProvider(input) {
+    switch (input.provider.kind) {
+        case "ambient":
+        case "responses":
+            return {
+                provider: input.provider,
+                modelCallRecords: [],
+                close: async () => undefined
+            };
+        case "openai-compatible": {
+            const records = [];
+            const apiKey = input.provider.apiKey ??
+                (input.provider.apiKeyEnvName !== undefined
+                    ? input.env[input.provider.apiKeyEnvName]
+                    : input.env.OPENAI_API_KEY);
+            const gateway = await startGateway({
+                backend: new OpenAiBackend({
+                    baseUrl: normalizeApiBaseUrl(input.provider.baseUrl),
+                    ...(apiKey !== undefined ? { apiKey } : {}),
+                    defaultModel: input.provider.defaultModel ?? input.model.model
+                }),
+                provenance: {
+                    onModelCall(record) {
+                        records.push(record);
+                    }
+                }
+            });
+            return {
+                provider: input.provider,
+                configBaseUrl: gateway.url(),
+                modelCallRecords: records,
+                close: () => gateway.close()
+            };
+        }
+        default: {
+            const exhausted = input.provider;
+            throw new Error(`unsupported Codex provider: ${String(exhausted)}`);
+        }
+    }
+}
+function metadataFor(input) {
+    return {
+        adapter: "codex",
+        command: input.command,
+        args: input.args,
+        provider_kind: input.provider.kind,
+        stdout_bytes: Buffer.byteLength(input.stdout),
+        stderr_bytes: Buffer.byteLength(input.stderr),
+        timed_out: input.timedOut === true,
+        model_call_count: input.modelCallRecords.length
+    };
+}
+function skippedCandidate(input) {
+    return buildSkippedCandidate({
+        descriptor: input.descriptor,
+        model: input.model,
+        ordinal: input.ordinal,
+        reason: input.reason,
+        adapter: "codex",
+        transcript: `Codex adapter skipped: ${input.reason}`,
+        metadata: { provider_kind: input.provider.kind }
+    });
+}
+function failedToSpawnCandidate(input) {
+    const errno = input.error;
+    const reason = errno.code === "ENOENT"
+        ? "Codex CLI binary was not found on PATH."
+        : input.error instanceof Error
+            ? input.error.message
+            : String(input.error);
+    return skippedCandidate({
+        descriptor: input.descriptor,
+        model: input.model,
+        ordinal: input.ordinal,
+        reason,
+        provider: input.provider
+    });
+}
+export function createCodexHarness(options = {}) {
+    const id = options.id ?? "codex";
+    const command = options.command ?? DEFAULT_CODEX_COMMAND;
+    const runner = options.runner ?? defaultCodexRunner;
+    const approvalPolicy = options.approvalPolicy ?? "never";
+    return {
+        id,
+        harnessKind: "codex",
+        prepare: () => {
+            const env = definedEnv(options.env ?? process.env);
+            return {
+                tempRoot: mkdtempSync(join(tmpdir(), "warrant-codex-")),
+                env,
+                provider: options.provider ?? providerFromEnv(env)
+            };
+        },
+        capabilities: () => ({
+            workspace_read: "supported",
+            apply_patch: "supported",
+            shell_command: "degraded",
+            artifact_capture: "supported",
+            model_gateway_responses: "supported",
+            openai_compatible_gateway: "supported",
+            verification: "supported"
+        }),
+        verificationProfile: () => ({
+            id: `${id}-verification`,
+            requiredEvidence: ["codex transcript", "exit code", "optional model-call record"]
+        }),
+        run: async ({ descriptor, model, ordinal, prepared, worktree }) => {
+            const state = prepared;
+            const missing = missingCredentialReason(state.provider, state.env);
+            if (missing !== undefined) {
+                return skippedCandidate({ descriptor, model, ordinal, reason: missing, provider: state.provider });
+            }
+            const provider = await runProvider({
+                provider: state.provider,
+                env: state.env,
+                model
+            });
+            try {
+                const env = { ...state.env };
+                if (provider.provider.kind === "responses" && provider.provider.apiKey !== undefined) {
+                    env[INLINE_PROVIDER_API_KEY_ENV] = provider.provider.apiKey;
+                }
+                const codexHome = writeCodexHome({
+                    tempRoot: state.tempRoot,
+                    model,
+                    providerBaseUrl: provider.configBaseUrl,
+                    provider: provider.provider,
+                    env,
+                    descriptor,
+                    sandboxMode: options.sandboxMode,
+                    approvalPolicy
+                });
+                env.CODEX_HOME = codexHome;
+                const args = codexArgs(descriptor.prompt);
+                const cwd = worktree?.path ?? options.cwd ?? descriptor.workspace ?? process.cwd();
+                const timeoutMs = options.timeoutMs ?? descriptor.policy.timeoutMs;
+                let result;
+                try {
+                    result = await runner({ command, args, cwd, env, timeoutMs });
+                }
+                catch (error) {
+                    return failedToSpawnCandidate({
+                        descriptor,
+                        model,
+                        ordinal,
+                        error,
+                        provider: provider.provider
+                    });
+                }
+                const transcript = [result.stdout, result.stderr].filter(Boolean).join("\n");
+                const status = result.exitCode === 0 && result.timedOut !== true ? "succeeded" : "failed";
+                const outputHash = artifactHash(transcript);
+                const modelCallRecord = provider.modelCallRecords.at(-1);
+                return {
+                    candidateId: `${descriptor.id}_${model.id}_${ordinal}`,
+                    model,
+                    status,
+                    ...(modelCallRecord ? { modelCallId: modelCallRecord.call_id, modelCallRecord } : {}),
+                    ...(worktree ? { branchName: worktree.branchName, worktreePath: worktree.path } : {}),
+                    transcript,
+                    log: transcript,
+                    artifacts: [
+                        {
+                            artifact_id: `artifact_${descriptor.id}_${model.id}_codex_output`,
+                            kind: "log",
+                            hash: outputHash,
+                            redaction_status: "synthetic"
+                        }
+                    ],
+                    toolRecords: [
+                        {
+                            execution_id: `exec_${descriptor.id}_${model.id}_${ordinal}_codex`,
+                            plan_id: `plan_${descriptor.id}_${model.id}_${ordinal}_codex`,
+                            status,
+                            output_hash: outputHash,
+                            ...(status === "failed"
+                                ? {
+                                    error: {
+                                        kind: result.timedOut === true ? "timeout" : "provider_error",
+                                        message: result.timedOut === true ? "Codex CLI timed out." : result.stderr.slice(0, 500),
+                                        retryable: result.timedOut === true
+                                    }
+                                }
+                                : {})
+                        }
+                    ],
+                    verification: {
+                        status,
+                        evidence: [`exit_code=${result.exitCode}`, outputHash],
+                        exitCode: result.exitCode
+                    },
+                    ...(status === "failed"
+                        ? {
+                            error: {
+                                kind: result.timedOut === true ? "timeout" : "provider_error",
+                                message: result.timedOut === true ? "Codex CLI timed out." : result.stderr.slice(0, 500),
+                                retryable: result.timedOut === true
+                            }
+                        }
+                        : {}),
+                    metadata: metadataFor({
+                        command,
+                        args,
+                        provider: provider.provider,
+                        stdout: result.stdout,
+                        stderr: result.stderr,
+                        ...(result.timedOut !== undefined ? { timedOut: result.timedOut } : {}),
+                        modelCallRecords: provider.modelCallRecords
+                    })
+                };
+            }
+            finally {
+                await provider.close();
+            }
+        },
+        collectArtifacts: () => [],
+        cleanup: ({ prepared }) => {
+            if (options.keepCodexHome === true)
+                return;
+            const state = prepared;
+            if (state !== undefined)
+                rmSync(state.tempRoot, { recursive: true, force: true });
+        }
+    };
+}
+export const codexHarness = createCodexHarness;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { ToolIntegration } from "@fusionkit/tools";
+export declare const codexTool: ToolIntegration;
+export { codexConfigToml, codexHarness, codexHarnessCredentialSkipReason, createCodexHarness, defaultCodexRunner } from "./harness.js";
+export type { CodexAmbientProvider, CodexApprovalPolicy, CodexConfigTomlInput, CodexExecInput, CodexExecResult, CodexExecRunner, CodexHarnessEnv, CodexHarnessOptions, CodexOpenAiCompatibleProvider, CodexProvider, CodexResponsesProvider, CodexSandboxMode } from "./harness.js";
+export { codexLaunchConfigToml, launchCodex } from "./launch.js";

package/dist/index.js

@@ -0,0 +1,61 @@
+import { codexHarness, codexHarnessCredentialSkipReason, createCodexHarness } from "./harness.js";
+import { launchCodex } from "./launch.js";
+const LIVE_SMOKE_PROMPT = "Read README.md if present, then reply exactly CODEX_LIVE_SMOKE_OK. Do not modify files.";
+export const codexTool = {
+    id: "codex",
+    displayName: "Codex",
+    pickerHint: "OpenAI Codex CLI",
+    binary: "codex",
+    modes: ["fusion", "local"],
+    harnessKinds: ["codex"],
+    launch: launchCodex,
+    createHarness: (_kind, options) => createCodexHarness({
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        provider: {
+            kind: "openai-compatible",
+            baseUrl: options.fusionBackendUrl,
+            ...(options.fusionApiKey !== undefined ? { apiKey: options.fusionApiKey } : {})
+        }
+    }),
+    harness: {
+        harnessKind: "codex",
+        sideEffects: "writes_workspace",
+        responseShape: "Return a Codex-style result summary with patch and verification evidence."
+    },
+    dashboard: {
+        id: "codex",
+        harnessKind: "codex",
+        displayName: "Codex",
+        availability: "credential_gated",
+        capabilities: {
+            model_override: "supported",
+            transcript_capture: "supported",
+            diff_capture: "supported",
+            tool_loop_capture: "degraded",
+            patch_apply_visibility: "supported",
+            route_model_observation: "supported",
+            verification_hint: "supported",
+            replay_support: "degraded"
+        },
+        notes: ["Credential-gated; dashboard smoke uses an empty env skip path."],
+        makeMatrixHarness: (env) => codexHarness({ env, provider: { kind: "ambient" } }),
+        credentialSkipReason: (env) => codexHarnessCredentialSkipReason(env),
+        smoke: {
+            taskId: "codex-skipped",
+            model: { id: "codex", model: "gpt-5.5-codex" },
+            sideEffects: "writes_workspace",
+            allowedTools: ["read_file", "apply_patch"],
+            makeHarness: () => codexHarness({ env: {}, provider: { kind: "ambient" } })
+        },
+        liveSmoke: {
+            taskId: "codex-live",
+            envName: "FUSIONKIT_CODEX_SMOKE",
+            prompt: LIVE_SMOKE_PROMPT,
+            modelEnvName: "FUSIONKIT_CODEX_SMOKE_MODEL",
+            defaultModel: "gpt-5.5-codex",
+            makeHarness: (env) => codexHarness({ env })
+        }
+    }
+};
+export { codexConfigToml, codexHarness, codexHarnessCredentialSkipReason, createCodexHarness, defaultCodexRunner } from "./harness.js";
+export { codexLaunchConfigToml, launchCodex } from "./launch.js";

package/dist/launch.d.ts

@@ -0,0 +1,9 @@
+import type { ToolLaunchContext } from "@fusionkit/tools";
+/**
+ * Codex config.toml fragment defining the gateway as a Responses provider.
+ * Written into an ephemeral CODEX_HOME so the user's own config is untouched.
+ * (This is the launcher shim; the harness has its own richer config builder.)
+ */
+export declare function codexLaunchConfigToml(gatewayUrl: string, model: string): string;
+/** Boot the Codex CLI against the gateway via an ephemeral CODEX_HOME. */
+export declare function launchCodex(ctx: ToolLaunchContext): Promise<number>;

package/dist/launch.js

@@ -0,0 +1,33 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LOCAL_MODEL_LABEL, spawnTool } from "@fusionkit/tools";
+/**
+ * Codex config.toml fragment defining the gateway as a Responses provider.
+ * Written into an ephemeral CODEX_HOME so the user's own config is untouched.
+ * (This is the launcher shim; the harness has its own richer config builder.)
+ */
+export function codexLaunchConfigToml(gatewayUrl, model) {
+    return [
+        `model = "${model}"`,
+        `model_provider = "${LOCAL_MODEL_LABEL}"`,
+        "",
+        `[model_providers.${LOCAL_MODEL_LABEL}]`,
+        `name = "FusionKit local"`,
+        `base_url = "${gatewayUrl}/v1"`,
+        `wire_api = "responses"`,
+        `requires_openai_auth = false`,
+        ""
+    ].join("\n");
+}
+/** Boot the Codex CLI against the gateway via an ephemeral CODEX_HOME. */
+export async function launchCodex(ctx) {
+    const home = mkdtempSync(join(tmpdir(), "fusionkit-codex-"));
+    ctx.registerDisposer(() => rmSync(home, { recursive: true, force: true }));
+    writeFileSync(join(home, "config.toml"), codexLaunchConfigToml(ctx.gatewayUrl, ctx.modelLabel));
+    ctx.prepareForPassthrough();
+    if (ctx.mode === "fusion") {
+        ctx.log("fusion: launching codex (each prompt is a coding task fused across the panel)...");
+    }
+    return await spawnTool("codex", ctx.toolArgs, { CODEX_HOME: home }, ctx.repo);
+}

package/dist/test/codex.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/codex.test.js

@@ -0,0 +1,277 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { createMockHarness, ensemble } from "@fusionkit/ensemble";
+import { codexConfigToml, codexHarness, defaultCodexRunner } from "../index.js";
+function tempOutputRoot() {
+    const outputRoot = mkdtempSync(join(tmpdir(), "ensemble-codex-out-"));
+    return {
+        outputRoot,
+        cleanup: () => rmSync(outputRoot, { recursive: true, force: true })
+    };
+}
+function descriptor(outputRoot, overrides = {}) {
+    return {
+        id: "codex_ensemble_test",
+        harness: createMockHarness(),
+        models: [{ id: "codex", model: "gpt-5.1-codex-max" }],
+        runtime: { id: "local" },
+        judge: { id: "judge", model: "fake-judge" },
+        policy: {
+            id: "policy",
+            allowedTools: ["read_file", "apply_patch"],
+            sideEffects: "writes_workspace",
+            timeoutMs: 1_000
+        },
+        prompt: "Summarize Codex harness evidence.",
+        sourceRepo: "handoffkit",
+        baseGitSha: "b".repeat(40),
+        outputRoot,
+        ...overrides
+    };
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+async function closeServer(server) {
+    await new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+    });
+}
+async function startOpenAiCompatibleServer() {
+    const requests = [];
+    const server = createServer((req, res) => {
+        void (async () => {
+            const path = new URL(req.url ?? "/", "http://localhost").pathname;
+            if (req.method === "GET" && path === "/v1/models") {
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ data: [{ id: "local-model" }] }));
+                return;
+            }
+            if (req.method === "POST" && path === "/v1/chat/completions") {
+                const body = JSON.parse((await readBody(req)).toString("utf8"));
+                requests.push(body);
+                const model = typeof body.model === "string" ? body.model : "local-model";
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({
+                    id: "chatcmpl_test",
+                    model,
+                    choices: [{ message: { role: "assistant", content: "gateway-ok" } }],
+                    usage: { prompt_tokens: 3, completion_tokens: 2, total_tokens: 5 }
+                }));
+                return;
+            }
+            res.writeHead(404, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: { message: "not found" } }));
+        })().catch((error) => {
+            res.writeHead(500, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: { message: String(error) } }));
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    assert.ok(typeof address === "object" && address !== null);
+    return {
+        url: `http://127.0.0.1:${address.port}`,
+        requests,
+        close: () => closeServer(server)
+    };
+}
+test("codexConfigToml declares a Responses provider without requiring auth", () => {
+    const toml = codexConfigToml({
+        model: "local-model",
+        sandboxMode: "workspace-write",
+        approvalPolicy: "never",
+        provider: {
+            baseUrl: "http://127.0.0.1:9000",
+            requiresOpenAiAuth: false
+        }
+    });
+    assert.ok(toml.includes('model = "local-model"'));
+    assert.ok(toml.includes('model_provider = "fusionkit-codex"'));
+    assert.ok(toml.includes("[model_providers.fusionkit-codex]"));
+    assert.ok(toml.includes('base_url = "http://127.0.0.1:9000/v1"'));
+    assert.ok(toml.includes('wire_api = "responses"'));
+    assert.ok(toml.includes("requires_openai_auth = false"));
+});
+test("codex adapter skips clearly when credentials are absent", async () => {
+    const { outputRoot, cleanup } = tempOutputRoot();
+    const emptyCodexHome = mkdtempSync(join(tmpdir(), "ensemble-codex-empty-home-"));
+    let invoked = false;
+    const runner = () => {
+        invoked = true;
+        return { stdout: "", stderr: "", exitCode: 0 };
+    };
+    try {
+        const result = await ensemble.run(descriptor(outputRoot, {
+            harness: codexHarness({ env: { CODEX_HOME: emptyCodexHome }, runner })
+        }));
+        assert.equal(invoked, false);
+        assert.equal(result.harnessRunResult.status, "skipped");
+        assert.equal(result.candidates[0]?.status, "skipped");
+        assert.equal(result.candidates[0]?.error?.kind, "capability_missing");
+        assert.match(result.candidates[0]?.error?.message ?? "", /CODEX_API_KEY|OPENAI_API_KEY/);
+    }
+    finally {
+        cleanup();
+        rmSync(emptyCodexHome, { recursive: true, force: true });
+    }
+});
+test("codex adapter accepts local CLI auth without exported API keys", async () => {
+    const { outputRoot, cleanup } = tempOutputRoot();
+    const sourceHome = mkdtempSync(join(tmpdir(), "ensemble-codex-source-home-"));
+    writeFileSync(join(sourceHome, "auth.json"), "{\"auth\":\"redacted-test-token\"}\n");
+    let seenAuthFile = false;
+    const runner = (input) => {
+        const codexHome = input.env.CODEX_HOME;
+        assert.ok(codexHome);
+        assert.notEqual(codexHome, sourceHome);
+        assert.equal(input.env.CODEX_API_KEY, undefined);
+        assert.equal(input.env.OPENAI_API_KEY, undefined);
+        seenAuthFile = existsSync(join(codexHome, "auth.json"));
+        return { stdout: "codex local auth ok", stderr: "", exitCode: 0 };
+    };
+    try {
+        const result = await ensemble.run(descriptor(outputRoot, {
+            harness: codexHarness({ env: { CODEX_HOME: sourceHome }, runner })
+        }));
+        assert.equal(seenAuthFile, true);
+        assert.equal(result.harnessRunResult.status, "succeeded");
+        assert.equal(result.candidates[0]?.metadata?.provider_kind, "ambient");
+    }
+    finally {
+        cleanup();
+        rmSync(sourceHome, { recursive: true, force: true });
+    }
+});
+test("generic ensemble descriptor swaps mock harness for Codex harness", async () => {
+    const { outputRoot, cleanup } = tempOutputRoot();
+    let seenArgs;
+    let seenConfig = "";
+    const runner = (input) => {
+        seenArgs = input.args;
+        const codexHome = input.env.CODEX_HOME;
+        assert.ok(codexHome);
+        seenConfig = readFileSync(join(codexHome, "config.toml"), "utf8");
+        assert.equal(input.env.CODEX_API_KEY, "test-key");
+        return { stdout: '{"type":"message","message":"codex-ok"}\n', stderr: "", exitCode: 0 };
+    };
+    try {
+        const base = descriptor(outputRoot);
+        const mock = await ensemble.run(base);
+        const codex = await ensemble.run({
+            ...base,
+            harness: codexHarness({ env: { CODEX_API_KEY: "test-key" }, runner })
+        });
+        assert.equal(mock.harnessRunResult.status, "succeeded");
+        assert.equal(codex.harnessRunResult.status, "succeeded");
+        assert.deepEqual(seenArgs?.slice(0, 3), ["exec", "--json", "--skip-git-repo-check"]);
+        assert.equal(seenArgs?.at(-1), base.prompt);
+        assert.ok(seenConfig.includes('model = "gpt-5.1-codex-max"'));
+        assert.equal(codex.candidates[0]?.metadata?.provider_kind, "ambient");
+    }
+    finally {
+        cleanup();
+    }
+});
+test("defaultCodexRunner captures stdout/stderr and exit code from a real process", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "codex-runner-"));
+    const stubCli = join(workdir, "codex-stub");
+    writeFileSync(stubCli, '#!/bin/sh\necho "codex-stdout-ok"\necho "codex-stderr-ok" 1>&2\nexit 0\n');
+    chmodSync(stubCli, 0o755);
+    try {
+        const result = await defaultCodexRunner({
+            command: stubCli,
+            args: ["exec", "hello"],
+            cwd: workdir,
+            env: { PATH: process.env.PATH ?? "" },
+            timeoutMs: 10_000
+        });
+        assert.equal(result.exitCode, 0);
+        assert.match(result.stdout, /codex-stdout-ok/);
+        assert.match(result.stderr, /codex-stderr-ok/);
+        assert.notEqual(result.timedOut, true);
+    }
+    finally {
+        rmSync(workdir, { recursive: true, force: true });
+    }
+});
+test("defaultCodexRunner reports a non-zero exit code from the process", async () => {
+    const workdir = mkdtempSync(join(tmpdir(), "codex-runner-fail-"));
+    const stubCli = join(workdir, "codex-stub");
+    writeFileSync(stubCli, '#!/bin/sh\necho "boom" 1>&2\nexit 3\n');
+    chmodSync(stubCli, 0o755);
+    try {
+        const result = await defaultCodexRunner({
+            command: stubCli,
+            args: ["exec"],
+            cwd: workdir,
+            env: { PATH: process.env.PATH ?? "" }
+        });
+        assert.equal(result.exitCode, 3);
+        assert.match(result.stderr, /boom/);
+    }
+    finally {
+        rmSync(workdir, { recursive: true, force: true });
+    }
+});
+test("Codex OpenAI-compatible provider goes through Responses gateway records", async () => {
+    const { outputRoot, cleanup } = tempOutputRoot();
+    const upstream = await startOpenAiCompatibleServer();
+    let gatewayBaseUrl;
+    const runner = async (input) => {
+        const codexHome = input.env.CODEX_HOME;
+        assert.ok(codexHome);
+        const config = readFileSync(join(codexHome, "config.toml"), "utf8");
+        const match = /base_url = "([^"]+)"/.exec(config);
+        assert.ok(match);
+        gatewayBaseUrl = match[1];
+        assert.ok(gatewayBaseUrl);
+        const response = await fetch(`${gatewayBaseUrl}/responses`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                input: "hello from fake codex",
+                stream: false
+            })
+        });
+        assert.equal(response.status, 200);
+        return { stdout: "codex gateway ok", stderr: "", exitCode: 0 };
+    };
+    try {
+        const result = await ensemble.run(descriptor(outputRoot, {
+            harness: codexHarness({
+                env: {},
+                provider: {
+                    kind: "openai-compatible",
+                    baseUrl: `${upstream.url}/v1`,
+                    defaultModel: "local-model"
+                },
+                runner
+            })
+        }));
+        assert.match(gatewayBaseUrl ?? "", /^http:\/\/127\.0\.0\.1:\d+\/v1$/);
+        assert.equal(upstream.requests.length, 1);
+        assert.equal(result.harnessRunResult.status, "succeeded");
+        assert.equal(result.modelCallRecords.length, 1);
+        assert.equal(result.modelCallRecords[0]?.metadata?.dialect, "openai-responses");
+        assert.equal(result.modelCallRecords[0]?.model, "local-model");
+        assert.equal(result.candidates[0]?.metadata?.model_call_count, 1);
+    }
+    finally {
+        await upstream.close();
+        cleanup();
+    }
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@fusionkit/tool-codex",
+  "private": false,
+  "version": "0.1.6",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/tool-codex"
+  },
+  "description": "Codex CLI tool integration for fusionkit: launcher config shim plus the ensemble Codex harness adapter.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@fusionkit/ensemble": "0.1.6",
+    "@fusionkit/protocol": "0.1.6",
+    "@fusionkit/tools": "0.1.6",
+    "@fusionkit/model-gateway": "0.1.6"
+  }
+}