@velum-labs/routekit-tool-codex 0.9.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { ToolIntegration } from "@velum-labs/routekit-tools";
+export declare const codexTool: ToolIntegration;
+export { codexDriverConfigSchema, createCodexDriver } from "./driver.js";
+export type { CodexDriverConfig } from "./driver.js";
+export { codexAgentRoles, codexAgentRoleToml, codexAuthPath, codexCatalogEntries, codexLaunchConfigToml, codexListedStockSlugs, codexModelCatalogJson, codexProfileFiles, codexProfileFileToml, hasCodexLogin, isCodexConfigFailure, launchCodex, readCodexCatalogTemplate, readCodexModelsCache } from "./launch.js";
+export type { CodexAgentRole, CodexModelPreset } from "./launch.js";
+export { codexIntegrationBlock, installCodexIntegration, uninstallCodexIntegration } from "./install.js";
+export type { CodexInstallInput, CodexInstallOwner, CodexInstallProfile, CodexInstallResult } from "./install.js";

package/dist/index.js

@@ -0,0 +1,40 @@
+import { trimTrailingSlashes } from "@velum-labs/routekit-runtime";
+import { codexDriverConfigSchema, createCodexDriver } from "./driver.js";
+import { codexLaunchConfigToml, launchCodex } from "./launch.js";
+const driver = createCodexDriver();
+export const codexTool = {
+    id: "codex",
+    displayName: "Codex",
+    pickerHint: "OpenAI Codex CLI",
+    binary: "codex",
+    packageName: "@velum-labs/routekit-tool-codex",
+    installHint: "install the Codex CLI: https://github.com/openai/codex",
+    authSummary: "Codex uses an ephemeral gateway-backed provider.",
+    setupSnippet: ({ gatewayUrl, model = "gateway-model" }) => codexLaunchConfigToml({
+        gatewayUrl,
+        defaultModel: model
+    }),
+    launch: launchCodex,
+    driver: {
+        kind: driver.kind,
+        driver,
+        configForRoute: (route) => codexDriverConfigSchema.parse({
+            model: route.model,
+            sandboxMode: "danger-full-access",
+            approvalPolicy: "never",
+            provider: {
+                baseUrl: `${trimTrailingSlashes(route.gatewayUrl)}/v1`,
+                ...(route.authToken !== undefined ? { apiKey: route.authToken } : {})
+            }
+        })
+    },
+    capabilities: {
+        streaming: "full",
+        tools: "full",
+        images: "degraded",
+        reasoning_controls: "full"
+    }
+};
+export { codexDriverConfigSchema, createCodexDriver } from "./driver.js";
+export { codexAgentRoles, codexAgentRoleToml, codexAuthPath, codexCatalogEntries, codexLaunchConfigToml, codexListedStockSlugs, codexModelCatalogJson, codexProfileFiles, codexProfileFileToml, hasCodexLogin, isCodexConfigFailure, launchCodex, readCodexCatalogTemplate, readCodexModelsCache } from "./launch.js";
+export { codexIntegrationBlock, installCodexIntegration, uninstallCodexIntegration } from "./install.js";

package/dist/install.d.ts

@@ -0,0 +1,35 @@
+export type CodexInstallProfile = {
+    modelId: string;
+    /** Safe Codex profile selector; defaults to `modelId`. */
+    profileId?: string;
+    description?: string;
+};
+export type CodexInstallOwner = {
+    id: string;
+    displayName: string;
+    providerId: string;
+    installCommand: string;
+    uninstallCommand: string;
+    startCommand: string;
+};
+export type CodexInstallInput = {
+    gatewayUrl: string;
+    profiles: readonly CodexInstallProfile[];
+    owner: CodexInstallOwner;
+    codexHome?: string;
+};
+export type CodexInstallResult = {
+    configPath: string;
+    action: "installed" | "updated";
+    profiles: string[];
+};
+/** Serialize one additive, owner-marked Codex provider block. */
+export declare function codexIntegrationBlock(input: CodexInstallInput): string;
+export declare function installCodexIntegration(input: CodexInstallInput): CodexInstallResult;
+export declare function uninstallCodexIntegration(input: {
+    ownerId: string;
+    codexHome?: string;
+}): {
+    configPath: string;
+    removed: boolean;
+};

package/dist/install.js

@@ -0,0 +1,185 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parse as tomlParse, stringify as tomlStringify } from "smol-toml";
+import { SUBSCRIPTIONS } from "@velum-labs/routekit-registry";
+import { trimTrailingSlashes } from "@velum-labs/routekit-runtime";
+import { codexProfileFileToml } from "./launch.js";
+function codexConfigPath(codexHome) {
+    if (codexHome !== undefined)
+        return join(codexHome, "config.toml");
+    const registryPath = SUBSCRIPTIONS.codex.configPath ?? "~/.codex/config.toml";
+    return registryPath.startsWith("~/") ? join(homedir(), registryPath.slice(2)) : registryPath;
+}
+function marker(ownerId, edge) {
+    return `# ${edge === "begin" ? ">>>" : "<<<"} ${ownerId} integration ${edge === "begin" ? ">>>" : "<<<"}`;
+}
+function profileFilesComment(ownerId) {
+    return `# ${ownerId}-profile-files:`;
+}
+function profileSelector(profile) {
+    return profile.profileId ?? profile.modelId;
+}
+function profileFileName(profile) {
+    const selector = profileSelector(profile);
+    if (selector.length === 0 ||
+        selector.includes("/") ||
+        selector.includes("\\") ||
+        selector.startsWith(".")) {
+        throw new Error(`Codex profile id is not a safe file name: ${JSON.stringify(selector)}`);
+    }
+    return `${selector}.config.toml`;
+}
+/** Serialize one additive, owner-marked Codex provider block. */
+export function codexIntegrationBlock(input) {
+    const base = trimTrailingSlashes(input.gatewayUrl);
+    const begin = marker(input.owner.id, "begin");
+    const end = marker(input.owner.id, "end");
+    const filesComment = profileFilesComment(input.owner.id);
+    const body = tomlStringify({
+        model_providers: {
+            [input.owner.providerId]: {
+                name: `${input.owner.displayName} gateway`,
+                base_url: `${base}/v1`,
+                wire_api: "responses",
+                requires_openai_auth: false
+            }
+        }
+    });
+    return [
+        begin,
+        `# Managed by \`${input.owner.installCommand}\`; do not edit between these markers.`,
+        `# Rerun that command to update; use \`${input.owner.uninstallCommand}\` to remove.`,
+        `# Start the gateway first: ${input.owner.startCommand}`,
+        `# Then launch: codex --profile ${input.profiles[0] !== undefined ? profileSelector(input.profiles[0]) : "gateway-model"}`,
+        ...input.profiles.map((profile) => `#   codex --profile ${profileSelector(profile)}${profile.description !== undefined ? `  (${profile.description})` : ""}`),
+        `${filesComment} ${input.profiles.map(profileFileName).join(" ")}`,
+        "",
+        body.trimEnd(),
+        "",
+        end
+    ].join("\n");
+}
+function ownedProfileFiles(managed, codexHome, ownerId) {
+    if (managed === undefined)
+        return [];
+    const prefix = profileFilesComment(ownerId);
+    const line = managed.split("\n").find((entry) => entry.startsWith(prefix));
+    if (line === undefined)
+        return [];
+    return line
+        .slice(prefix.length)
+        .split(/\s+/)
+        .filter((name) => name.endsWith(".config.toml") && !name.includes("/") && !name.includes("\\"))
+        .map((name) => join(codexHome, name));
+}
+function splitManagedBlock(content, ownerId) {
+    const beginMarker = marker(ownerId, "begin");
+    const endMarker = marker(ownerId, "end");
+    const begin = content.indexOf(beginMarker);
+    if (begin === -1)
+        return { before: content, after: "" };
+    const end = content.indexOf(endMarker, begin);
+    if (end === -1) {
+        throw new Error(`found the ${ownerId} begin marker but no end marker in the Codex config; ` +
+            `remove the "${beginMarker}" line and its managed content, then retry`);
+    }
+    return {
+        before: content.slice(0, begin),
+        managed: content.slice(begin, end + endMarker.length),
+        after: content.slice(end + endMarker.length)
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseTomlOrThrow(content, what) {
+    try {
+        return tomlParse(content);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.split("\n")[0] : String(error);
+        throw new Error(`${what} is not valid TOML (${detail}); fix it, then rerun the command`);
+    }
+}
+function assertNoConflicts(outside, input) {
+    const providers = outside.model_providers;
+    if (isRecord(providers) && providers[input.owner.providerId] !== undefined) {
+        throw new Error(`your Codex config already defines [model_providers.${input.owner.providerId}] outside the ` +
+            `${input.owner.id}-managed block; remove or rename it, then rerun \`${input.owner.installCommand}\``);
+    }
+    const legacyProfiles = outside.profiles;
+    for (const profile of input.profiles) {
+        const selector = profileSelector(profile);
+        if (isRecord(legacyProfiles) && legacyProfiles[selector] !== undefined) {
+            throw new Error(`your Codex config already defines [profiles.${selector}] outside the ` +
+                `${input.owner.id}-managed block; remove or rename it, then rerun \`${input.owner.installCommand}\``);
+        }
+    }
+}
+function normalize(content) {
+    const trimmed = content.replace(/\s+$/, "");
+    return trimmed.length === 0 ? "" : `${trimmed}\n`;
+}
+function removeOwnedProfileFile(path, ownerId) {
+    try {
+        if (!existsSync(path))
+            return;
+        if (!readFileSync(path, "utf8").includes(`Managed by ${ownerId}`))
+            return;
+        rmSync(path);
+    }
+    catch {
+        // Best-effort cleanup; an orphaned profile does not alter the main config.
+    }
+}
+export function installCodexIntegration(input) {
+    if (input.profiles.length === 0)
+        throw new Error("at least one Codex profile is required");
+    const configPath = codexConfigPath(input.codexHome);
+    const codexHome = dirname(configPath);
+    const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    const { before, managed, after } = splitManagedBlock(existing, input.owner.id);
+    const outside = parseTomlOrThrow(`${normalize(before)}\n${normalize(after)}`, `your Codex config (${configPath})`);
+    assertNoConflicts(outside, input);
+    const block = codexIntegrationBlock(input);
+    const head = normalize(before);
+    const tail = normalize(after);
+    const next = `${head}${head.length > 0 ? "\n" : ""}${block}\n${tail.length > 0 ? `\n${tail}` : ""}`;
+    const assembled = parseTomlOrThrow(next, "the updated Codex config");
+    const providers = assembled.model_providers;
+    if (!isRecord(providers) || providers[input.owner.providerId] === undefined) {
+        throw new Error("internal error: the assembled Codex config lost its managed provider block");
+    }
+    mkdirSync(codexHome, { recursive: true });
+    const nextFiles = new Set(input.profiles.map((profile) => join(codexHome, profileFileName(profile))));
+    for (const stale of ownedProfileFiles(managed, codexHome, input.owner.id)) {
+        if (!nextFiles.has(stale))
+            removeOwnedProfileFile(stale, input.owner.id);
+    }
+    writeFileSync(configPath, next);
+    for (const profile of input.profiles) {
+        writeFileSync(join(codexHome, profileFileName(profile)), `# Managed by ${input.owner.id}\n${codexProfileFileToml(profile.modelId, input.owner.providerId)}`);
+    }
+    return {
+        configPath,
+        action: managed !== undefined ? "updated" : "installed",
+        profiles: input.profiles.map(profileSelector)
+    };
+}
+export function uninstallCodexIntegration(input) {
+    const configPath = codexConfigPath(input.codexHome);
+    if (!existsSync(configPath))
+        return { configPath, removed: false };
+    const existing = readFileSync(configPath, "utf8");
+    const { before, managed, after } = splitManagedBlock(existing, input.ownerId);
+    if (managed === undefined)
+        return { configPath, removed: false };
+    for (const owned of ownedProfileFiles(managed, dirname(configPath), input.ownerId)) {
+        removeOwnedProfileFile(owned, input.ownerId);
+    }
+    const head = normalize(before);
+    const tail = normalize(after);
+    writeFileSync(configPath, `${head}${head.length > 0 && tail.length > 0 ? "\n" : ""}${tail}`);
+    return { configPath, removed: true };
+}

package/dist/launch.d.ts

@@ -0,0 +1,32 @@
+import type { AgentProfile, ToolLaunchContext, ToolLaunchSpec } from "@velum-labs/routekit-tools";
+export type CodexModelPreset = Record<string, unknown>;
+export declare function isCodexConfigFailure(code: number, stderr: string): boolean;
+export declare function tomlKey(name: string): string;
+export declare function readCodexModelsCache(home?: string): CodexModelPreset[];
+export declare function readCodexCatalogTemplate(home?: string): CodexModelPreset | undefined;
+export declare function codexAuthPath(home?: string): string;
+export declare function hasCodexLogin(home?: string): boolean;
+/**
+ * Create an isolated Codex home outside the operating-system temp directory.
+ *
+ * Recent Codex releases refuse to install their process-scoped PATH helpers
+ * beneath `tmpdir()`. RouteKit still needs an isolated home so a gateway turn
+ * cannot read or mutate the user's real Codex configuration.
+ */
+export declare function createIsolatedCodexHome(prefix: string, env?: Record<string, string | undefined>): string;
+export declare function codexListedStockSlugs(home?: string): string[];
+export declare function codexCatalogEntries(spec: Pick<ToolLaunchSpec, "defaultModel" | "models">, template: CodexModelPreset, stockModels?: readonly CodexModelPreset[], options?: {
+    appendUnlistedStock?: boolean;
+}): Record<string, unknown>[];
+export declare function codexModelCatalogJson(spec: Pick<ToolLaunchSpec, "defaultModel" | "models">, template: CodexModelPreset, stockModels?: readonly CodexModelPreset[], options?: {
+    appendUnlistedStock?: boolean;
+}): string;
+export declare function codexProfileFileToml(model: string, provider?: string): string;
+export declare function codexProfileFiles(home: string, models: readonly string[], provider?: string): string[];
+export type CodexAgentRole = AgentProfile & {
+    configPath: string;
+};
+export declare function codexAgentRoles(home: string, profiles: readonly AgentProfile[]): CodexAgentRole[];
+export declare function codexAgentRoleToml(profile: AgentProfile): string;
+export declare function codexLaunchConfigToml(spec: Pick<ToolLaunchSpec, "gatewayUrl" | "defaultModel" | "reasoning" | "auth">, modelCatalogPath?: string, roles?: readonly CodexAgentRole[]): string;
+export declare function launchCodex(ctx: ToolLaunchContext): Promise<number>;

package/dist/launch.js

@@ -0,0 +1,302 @@
+import { spawn } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { stringify as tomlStringify } from "smol-toml";
+import { trimTrailingSlashes } from "@velum-labs/routekit-runtime";
+const PROVIDER_ID = "routekit";
+const CATALOG_FILE = "model-catalog.json";
+/** Model-agnostic agent prompt, matching the gateway's synthesized entries. */
+const NEUTRAL_INSTRUCTIONS = "You are a coding agent.";
+const PROFILE_DIR = "agent-profiles";
+const CONFIG_FAILURE_PATTERNS = [
+    /config\.toml/i,
+    /model_catalog/i,
+    /duplicate agent role/i,
+    /error (?:reading|parsing|loading) config/i,
+    /invalid config/i,
+    /unknown field/i,
+    /missing field/i,
+    /agent role/i
+];
+export function isCodexConfigFailure(code, stderr) {
+    return code !== 0 && CONFIG_FAILURE_PATTERNS.some((pattern) => pattern.test(stderr));
+}
+export function tomlKey(name) {
+    return /^[A-Za-z0-9_-]+$/.test(name) ? name : JSON.stringify(name);
+}
+function modelsCachePath(home) {
+    return join(home, ".codex", "models_cache.json");
+}
+export function readCodexModelsCache(home = homedir()) {
+    try {
+        const parsed = JSON.parse(readFileSync(modelsCachePath(home), "utf8"));
+        return Array.isArray(parsed.models)
+            ? parsed.models.filter((entry) => entry !== null && typeof entry === "object")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function readCodexCatalogTemplate(home = homedir()) {
+    return readCodexModelsCache(home)[0];
+}
+export function codexAuthPath(home = homedir()) {
+    return join(home, ".codex", "auth.json");
+}
+export function hasCodexLogin(home = homedir()) {
+    return existsSync(codexAuthPath(home));
+}
+/**
+ * Create an isolated Codex home outside the operating-system temp directory.
+ *
+ * Recent Codex releases refuse to install their process-scoped PATH helpers
+ * beneath `tmpdir()`. RouteKit still needs an isolated home so a gateway turn
+ * cannot read or mutate the user's real Codex configuration.
+ */
+export function createIsolatedCodexHome(prefix, env = process.env) {
+    const userHome = env.HOME ?? env.USERPROFILE ?? homedir();
+    const cacheRoot = env.XDG_CACHE_HOME ??
+        (process.platform === "win32" ? env.LOCALAPPDATA : undefined) ??
+        join(userHome, ".cache");
+    const parent = join(cacheRoot, "routekit", "codex");
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    return mkdtempSync(join(parent, prefix));
+}
+function presetSlug(entry) {
+    return typeof entry.slug === "string" && entry.slug.length > 0 ? entry.slug : undefined;
+}
+export function codexListedStockSlugs(home = homedir()) {
+    const seen = new Set();
+    return readCodexModelsCache(home).flatMap((entry) => {
+        const slug = presetSlug(entry);
+        if (slug === undefined || seen.has(slug))
+            return [];
+        seen.add(slug);
+        return [slug];
+    });
+}
+function codexModelId(modelId) {
+    return modelId.startsWith("codex/")
+        ? modelId.slice("codex/".length)
+        : modelId;
+}
+function catalogIds(spec) {
+    return [
+        ...new Set([spec.defaultModel, ...spec.models.flatMap((model) => [
+                model.id,
+                ...(model.aliases ?? [])
+            ])].map(codexModelId))
+    ];
+}
+/** True when a bare catalog id was projected from a `codex/`-namespaced model. */
+function isCodexNativeId(spec, id) {
+    const namespaced = `codex/${id}`;
+    return (spec.defaultModel === namespaced ||
+        spec.models.some((model) => model.id === namespaced || model.aliases?.includes(namespaced) === true));
+}
+export function codexCatalogEntries(spec, template, stockModels = [], options = {}) {
+    const appendUnlistedStock = options.appendUnlistedStock ?? true;
+    const ids = catalogIds({ ...spec, gatewayUrl: "", args: [] });
+    const listed = new Set(ids);
+    const stockBySlug = new Map(stockModels.flatMap((entry) => {
+        const slug = presetSlug(entry);
+        return slug === undefined ? [] : [[slug, entry]];
+    }));
+    // The template (a stock Codex model entry) only exists to satisfy the
+    // catalog schema of the installed Codex version. Fields that change how
+    // Codex talks to the model must not leak from an unrelated stock model into
+    // gateway-routed entries: reasoning tiers are replaced by each model's
+    // discovered capabilities; `tool_mode` (e.g. "code_mode_only") and
+    // `use_responses_lite` alter (or drop entirely) the tool declarations Codex
+    // sends; service tiers are a stock-model billing offer; and
+    // `base_instructions` / `model_messages` become the developer message, so a
+    // stock prompt ("You are Codex, an agent based on GPT-5...") would tell
+    // every routed model it is GPT-5. Fields are reset to neutral values only
+    // when the template carries them, so the output still matches the installed
+    // Codex version's required fields.
+    const { supported_reasoning_levels: _templateLevels, default_reasoning_level: _templateDefault, supports_reasoning_summaries: _templateSummaries, tool_mode: _templateToolMode, default_service_tier: _templateServiceTier, ...neutralTemplate } = template;
+    for (const [field, neutral] of [
+        ["use_responses_lite", false],
+        ["additional_speed_tiers", []],
+        ["service_tiers", []],
+        ["base_instructions", NEUTRAL_INSTRUCTIONS]
+    ]) {
+        if (field in neutralTemplate)
+            neutralTemplate[field] = neutral;
+    }
+    if (typeof neutralTemplate.model_messages === "object" &&
+        neutralTemplate.model_messages !== null) {
+        neutralTemplate.model_messages = {
+            ...neutralTemplate.model_messages,
+            instructions_template: NEUTRAL_INSTRUCTIONS
+        };
+    }
+    const entries = ids.map((id, priority) => {
+        // A Codex-native model whose real ModelInfo is in the stock cache keeps
+        // it verbatim (its tuned prompt, reasoning tiers, tool mode) — through
+        // the gateway it still reaches the real Codex backend, so the stock
+        // behavior is the correct behavior. This mirrors the gateway's own
+        // picker merge. Only the transport hint is pinned to the gateway's HTTP.
+        const stock = stockBySlug.get(id);
+        if (stock !== undefined && isCodexNativeId(spec, id)) {
+            return { ...stock, slug: id, visibility: "list", priority, prefer_websockets: false };
+        }
+        const model = spec.models.find((candidate) => codexModelId(candidate.id) === id ||
+            candidate.aliases?.some((alias) => codexModelId(alias) === id) === true);
+        const levels = (model?.reasoning?.efforts ?? []).map((effort) => ({
+            effort: effort.id,
+            description: effort.description ?? effort.label ?? effort.id
+        }));
+        return {
+            ...neutralTemplate,
+            prefer_websockets: false,
+            slug: id,
+            display_name: model?.label ?? id,
+            description: "Gateway-routed model.",
+            visibility: "list",
+            priority,
+            availability_nux: null,
+            upgrade: null,
+            // Codex requires this field on every catalog entry; an empty list means
+            // "no discovered effort controls" without fabricating tiers.
+            supported_reasoning_levels: levels,
+            ...(model?.reasoning?.defaultEffort !== undefined
+                ? { default_reasoning_level: model.reasoning.defaultEffort }
+                : {}),
+            supports_reasoning_summaries: model?.reasoning?.status === "supported"
+        };
+    });
+    if (appendUnlistedStock) {
+        for (const stock of stockModels) {
+            const slug = presetSlug(stock);
+            if (slug === undefined || listed.has(slug))
+                continue;
+            listed.add(slug);
+            entries.push({ ...stock, priority: entries.length });
+        }
+    }
+    return entries;
+}
+export function codexModelCatalogJson(spec, template, stockModels = [], options = {}) {
+    return JSON.stringify({ models: codexCatalogEntries(spec, template, stockModels, options) }, null, 2);
+}
+export function codexProfileFileToml(model, provider = PROVIDER_ID) {
+    return `${tomlStringify({ model, model_provider: provider }).trimEnd()}\n`;
+}
+export function codexProfileFiles(home, models, provider = PROVIDER_ID) {
+    const written = [];
+    for (const model of models) {
+        if (model.length === 0 ||
+            model.includes("/") ||
+            model.includes("\\") ||
+            model.startsWith(".") ||
+            written.includes(model)) {
+            continue;
+        }
+        writeFileSync(join(home, `${model}.config.toml`), codexProfileFileToml(model, provider));
+        written.push(model);
+    }
+    return written;
+}
+export function codexAgentRoles(home, profiles) {
+    return profiles.map((profile) => ({
+        ...profile,
+        configPath: join(home, PROFILE_DIR, `${profile.id}.toml`)
+    }));
+}
+export function codexAgentRoleToml(profile) {
+    return [
+        `name = ${JSON.stringify(profile.id)}`,
+        `model = ${JSON.stringify(codexModelId(profile.model))}`,
+        `model_provider = ${JSON.stringify(PROVIDER_ID)}`,
+        `developer_instructions = ${JSON.stringify(profile.instructions)}`,
+        ""
+    ].join("\n");
+}
+export function codexLaunchConfigToml(spec, modelCatalogPath, roles = []) {
+    const lines = [
+        `model = ${JSON.stringify(codexModelId(spec.defaultModel))}`,
+        `model_provider = ${JSON.stringify(PROVIDER_ID)}`
+    ];
+    if (spec.reasoning?.mode === "effort") {
+        lines.push(`model_reasoning_effort = ${JSON.stringify(spec.reasoning.effort)}`);
+    }
+    if (modelCatalogPath !== undefined) {
+        lines.push(`model_catalog_json = ${JSON.stringify(modelCatalogPath)}`);
+    }
+    lines.push("", `[model_providers.${PROVIDER_ID}]`, `name = "RouteKit gateway"`, `base_url = ${JSON.stringify(`${trimTrailingSlashes(spec.gatewayUrl)}/v1`)}`, `wire_api = "responses"`, `requires_openai_auth = false`, ...(spec.auth?.token !== undefined
+        ? [`env_key = "ROUTEKIT_GATEWAY_TOKEN"`]
+        : []), "");
+    if (roles.length > 0) {
+        lines.push("[features]", "multi_agent = true", "", "[agents]", "max_depth = 1", "");
+        for (const role of roles) {
+            lines.push(`[agents.${tomlKey(role.id)}]`, `description = ${JSON.stringify(role.description)}`, `config_file = ${JSON.stringify(role.configPath)}`, "");
+        }
+    }
+    return lines.join("\n");
+}
+function spawnCodex(args, home, cwd, token) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("codex", args, {
+            stdio: ["inherit", "inherit", "pipe"],
+            // env-spread-allowed: interactive user tool inherits the user's shell configuration
+            env: {
+                ...process.env,
+                CODEX_HOME: home,
+                ...(token !== undefined ? { ROUTEKIT_GATEWAY_TOKEN: token } : {})
+            },
+            ...(cwd !== undefined ? { cwd } : {})
+        });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+            stderr = (stderr + chunk.toString("utf8")).slice(-8192);
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => resolve({ code: code ?? 0, stderr }));
+    });
+}
+export async function launchCodex(ctx) {
+    const { spec } = ctx;
+    const home = createIsolatedCodexHome("routekit-codex-");
+    ctx.registerDisposer(() => rmSync(home, { recursive: true, force: true }));
+    if (hasCodexLogin() && spec.auth?.token === undefined) {
+        copyFileSync(codexAuthPath(), join(home, "auth.json"));
+    }
+    const ids = [...catalogIds(spec), ...codexListedStockSlugs()];
+    codexProfileFiles(home, ids);
+    const template = readCodexCatalogTemplate();
+    const catalogPath = template === undefined ? undefined : join(home, CATALOG_FILE);
+    if (catalogPath !== undefined && template !== undefined) {
+        // The stock cache supplies verbatim ModelInfo for gateway models that are
+        // Codex-native. Unlisted stock models are not appended: without a codex
+        // route in the gateway catalog they would not resolve.
+        writeFileSync(catalogPath, codexModelCatalogJson(spec, template, readCodexModelsCache(), {
+            appendUnlistedStock: false
+        }));
+    }
+    const roles = codexAgentRoles(home, spec.agentProfiles ?? []);
+    if (roles.length > 0) {
+        mkdirSync(join(home, PROFILE_DIR), { recursive: true });
+        for (const role of roles)
+            writeFileSync(role.configPath, codexAgentRoleToml(role));
+    }
+    const configPath = join(home, "config.toml");
+    const writeConfig = (catalog, activeRoles) => {
+        writeFileSync(configPath, codexLaunchConfigToml(spec, catalog, activeRoles));
+    };
+    writeConfig(catalogPath, roles);
+    ctx.prepareForPassthrough();
+    let result = await spawnCodex(spec.args, home, spec.cwd, spec.auth?.token);
+    if (catalogPath !== undefined && isCodexConfigFailure(result.code, result.stderr)) {
+        writeConfig(undefined, roles);
+        result = await spawnCodex(spec.args, home, spec.cwd, spec.auth?.token);
+    }
+    if (roles.length > 0 && isCodexConfigFailure(result.code, result.stderr)) {
+        writeConfig(undefined, []);
+        result = await spawnCodex(spec.args, home, spec.cwd, spec.auth?.token);
+    }
+    return result.code;
+}

package/dist/test/driver.test.d.ts

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