@velum-labs/routekit-tool-codex 0.16.8 → 0.17.0

package/README.md

@@ -18,3 +18,10 @@ import { codexTool } from "@velum-labs/routekit-tool-codex";
 
 - CLI reference: [../../docs/cli.md](../../docs/cli.md)
 - Maintainer reference: [../../docs/typescript-reference.md](../../docs/typescript-reference.md)
+
+## Native client ownership
+
+The launcher uses the user's normal `CODEX_HOME`, applies gateway routing as
+process-scoped configuration, and keeps credentials in the environment. RouteKit
+does not observe, store, resume, or delete Codex sessions; use Codex's native
+history and commands directly.

package/dist/index.d.ts

@@ -1,8 +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 { codexDriverConfigSchema, createCodexDriver } from "./driver.js";
 export type { CodexInstallInput, CodexInstallOwner, CodexInstallProfile, CodexInstallResult } from "./install.js";
+export { codexIntegrationBlock, codexIntegrationConfigPath, installCodexIntegration, uninstallCodexIntegration } from "./install.js";
+export type { CodexAgentRole, CodexModelPreset } from "./launch.js";
+export { codexAgentRoles, codexAgentRoleToml, codexAuthPath, codexCatalogEntries, codexLaunchConfigToml, codexListedStockSlugs, codexModelCatalogJson, codexPersistentModelCatalogJson, codexProfileFiles, codexProfileFileToml, hasCodexLogin, isCodexConfigFailure, launchCodex, readCodexCatalogTemplate, readCodexHomeModelsCache, readCodexModelsCache } from "./launch.js";

package/dist/index.js

@@ -9,7 +9,7 @@ export const codexTool = {
     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.",
+    authSummary: "Codex uses RouteKit's OpenAI-compatible gateway provider.",
     setupSnippet: ({ gatewayUrl, model = "gateway-model" }) => codexLaunchConfigToml({
         gatewayUrl,
         defaultModel: model
@@ -36,5 +36,5 @@ export const codexTool = {
     }
 };
 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";
+export { codexIntegrationBlock, codexIntegrationConfigPath, installCodexIntegration, uninstallCodexIntegration } from "./install.js";
+export { codexAgentRoles, codexAgentRoleToml, codexAuthPath, codexCatalogEntries, codexLaunchConfigToml, codexListedStockSlugs, codexModelCatalogJson, codexPersistentModelCatalogJson, codexProfileFiles, codexProfileFileToml, hasCodexLogin, isCodexConfigFailure, launchCodex, readCodexCatalogTemplate, readCodexHomeModelsCache, readCodexModelsCache } from "./launch.js";

package/dist/install.d.ts

@@ -1,8 +1,10 @@
+import type { ModelReasoningCapabilities } from "@velum-labs/routekit-contracts";
 export type CodexInstallProfile = {
     modelId: string;
     /** Safe Codex profile selector; defaults to `modelId`. */
     profileId?: string;
     description?: string;
+    reasoning?: ModelReasoningCapabilities;
 };
 export type CodexInstallOwner = {
     id: string;
@@ -20,9 +22,11 @@ export type CodexInstallInput = {
 };
 export type CodexInstallResult = {
     configPath: string;
+    catalogPath: string;
     action: "installed" | "updated";
     profiles: string[];
 };
+export declare function codexIntegrationConfigPath(codexHome: string | undefined): string;
 /** Serialize one additive, owner-marked Codex provider block. */
 export declare function codexIntegrationBlock(input: CodexInstallInput): string;
 export declare function installCodexIntegration(input: CodexInstallInput): CodexInstallResult;

package/dist/install.js

@@ -4,8 +4,8 @@ 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) {
+import { codexPersistentModelCatalogJson, codexProfileFileToml, readCodexHomeModelsCache } from "./launch.js";
+export function codexIntegrationConfigPath(codexHome) {
     if (codexHome !== undefined)
         return join(codexHome, "config.toml");
     const registryPath = SUBSCRIPTIONS.codex.configPath ?? "~/.codex/config.toml";
@@ -17,6 +17,15 @@ function marker(ownerId, edge) {
 function profileFilesComment(ownerId) {
     return `# ${ownerId}-profile-files:`;
 }
+function catalogFileComment(ownerId) {
+    return `# ${ownerId}-catalog-file:`;
+}
+function catalogFileName(ownerId) {
+    if (!/^[A-Za-z0-9_-]+$/.test(ownerId)) {
+        throw new Error(`Codex integration owner id is not path-safe: ${JSON.stringify(ownerId)}`);
+    }
+    return `.${ownerId}-model-catalog.json`;
+}
 function profileSelector(profile) {
     return profile.profileId ?? profile.modelId;
 }
@@ -36,13 +45,16 @@ export function codexIntegrationBlock(input) {
     const begin = marker(input.owner.id, "begin");
     const end = marker(input.owner.id, "end");
     const filesComment = profileFilesComment(input.owner.id);
+    const catalogComment = catalogFileComment(input.owner.id);
+    const catalogFile = catalogFileName(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
+                requires_openai_auth: false,
+                env_key: "ROUTEKIT_GATEWAY_TOKEN"
             }
         }
     });
@@ -54,6 +66,7 @@ export function codexIntegrationBlock(input) {
         `# 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(" ")}`,
+        `${catalogComment} ${catalogFile}`,
         "",
         body.trimEnd(),
         "",
@@ -73,6 +86,19 @@ function ownedProfileFiles(managed, codexHome, ownerId) {
         .filter((name) => name.endsWith(".config.toml") && !name.includes("/") && !name.includes("\\"))
         .map((name) => join(codexHome, name));
 }
+function ownedCatalogFile(managed, codexHome, ownerId) {
+    if (managed === undefined)
+        return undefined;
+    const prefix = catalogFileComment(ownerId);
+    const line = managed.split("\n").find((entry) => entry.startsWith(prefix));
+    if (line === undefined)
+        return undefined;
+    const file = line.slice(prefix.length).trim();
+    if (file.length === 0 || file.includes("/") || file.includes("\\") || file !== catalogFileName(ownerId)) {
+        return undefined;
+    }
+    return join(codexHome, file);
+}
 function splitManagedBlock(content, ownerId) {
     const beginMarker = marker(ownerId, "begin");
     const endMarker = marker(ownerId, "end");
@@ -136,12 +162,17 @@ function removeOwnedProfileFile(path, ownerId) {
 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 configPath = codexIntegrationConfigPath(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 catalogPath = join(codexHome, catalogFileName(input.owner.id));
+    if (managed === undefined && existsSync(catalogPath)) {
+        throw new Error(`refusing to overwrite an existing RouteKit catalog file: ${catalogPath}; ` +
+            `move it aside, then rerun \`${input.owner.installCommand}\``);
+    }
     const block = codexIntegrationBlock(input);
     const head = normalize(before);
     const tail = normalize(after);
@@ -152,6 +183,10 @@ export function installCodexIntegration(input) {
         throw new Error("internal error: the assembled Codex config lost its managed provider block");
     }
     mkdirSync(codexHome, { recursive: true });
+    writeFileSync(catalogPath, codexPersistentModelCatalogJson(input.profiles.map((profile) => ({
+        id: profile.modelId,
+        ...(profile.reasoning !== undefined ? { reasoning: profile.reasoning } : {})
+    })), readCodexHomeModelsCache(codexHome)[0]), { mode: 0o600 });
     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))
@@ -159,16 +194,17 @@ export function installCodexIntegration(input) {
     }
     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)}`);
+        writeFileSync(join(codexHome, profileFileName(profile)), `# Managed by ${input.owner.id}\n${codexProfileFileToml(profile.modelId, input.owner.providerId, catalogPath)}`, { mode: 0o600 });
     }
     return {
         configPath,
+        catalogPath,
         action: managed !== undefined ? "updated" : "installed",
         profiles: input.profiles.map(profileSelector)
     };
 }
 export function uninstallCodexIntegration(input) {
-    const configPath = codexConfigPath(input.codexHome);
+    const configPath = codexIntegrationConfigPath(input.codexHome);
     if (!existsSync(configPath))
         return { configPath, removed: false };
     const existing = readFileSync(configPath, "utf8");
@@ -178,6 +214,9 @@ export function uninstallCodexIntegration(input) {
     for (const owned of ownedProfileFiles(managed, dirname(configPath), input.ownerId)) {
         removeOwnedProfileFile(owned, input.ownerId);
     }
+    const catalogPath = ownedCatalogFile(managed, dirname(configPath), input.ownerId);
+    if (catalogPath !== undefined)
+        rmSync(catalogPath, { force: true });
     const head = normalize(before);
     const tail = normalize(after);
     writeFileSync(configPath, `${head}${head.length > 0 && tail.length > 0 ? "\n" : ""}${tail}`);

package/dist/launch.d.ts

@@ -1,8 +1,17 @@
+import { spawn } from "node:child_process";
+import { type ModelReasoningCapabilities } from "@velum-labs/routekit-contracts";
 import type { AgentProfile, ToolLaunchContext, ToolLaunchSpec } from "@velum-labs/routekit-tools";
 export type CodexModelPreset = Record<string, unknown>;
+/** Metadata persisted beside a RouteKit-owned Codex profile. */
+export type CodexPersistentCatalogModel = {
+    id: string;
+    label?: string;
+    reasoning?: ModelReasoningCapabilities;
+};
 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 readCodexHomeModelsCache(codexHome: string): CodexModelPreset[];
 export declare function readCodexCatalogTemplate(home?: string): CodexModelPreset | undefined;
 export declare function codexAuthPath(home?: string): string;
 export declare function hasCodexLogin(home?: string): boolean;
@@ -21,7 +30,13 @@ export declare function codexCatalogEntries(spec: Pick<ToolLaunchSpec, "defaultM
 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;
+/**
+ * Serialize a versioned ModelInfo catalog for persistent profiles. It uses a
+ * target Codex home's stock metadata when available, and a complete fallback
+ * for first-run homes that have not downloaded `models_cache.json` yet.
+ */
+export declare function codexPersistentModelCatalogJson(models: readonly CodexPersistentCatalogModel[], template?: CodexModelPreset | undefined): string;
+export declare function codexProfileFileToml(model: string, provider?: string, modelCatalogPath?: string): string;
 export declare function codexProfileFiles(home: string, models: readonly string[], provider?: string): string[];
 export type CodexAgentRole = AgentProfile & {
     configPath: string;
@@ -29,4 +44,10 @@ export type CodexAgentRole = AgentProfile & {
 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>;
+export type CodexLaunchDependencies = {
+    spawnProcess?: typeof spawn;
+    env?: Record<string, string | undefined>;
+};
+export declare function resolveCodexHome(env?: Record<string, string | undefined>): string;
+/** Launch against the user's real Codex home; only generated catalog data is temporary. */
+export declare function launchCodex(ctx: ToolLaunchContext, deps?: CodexLaunchDependencies): Promise<number>;

package/dist/launch.js

@@ -1,10 +1,10 @@
 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 { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
 import { isCodexPickerEligibleModel, reasoningEffortDescriptors } from "@velum-labs/routekit-contracts";
 import { trimTrailingSlashes } from "@velum-labs/routekit-runtime";
+import { stringify as tomlStringify } from "smol-toml";
 const PROVIDER_ID = "routekit";
 const CATALOG_FILE = "model-catalog.json";
 /** Model-agnostic agent prompt, matching the gateway's synthesized entries. */
@@ -29,9 +29,9 @@ export function tomlKey(name) {
 function modelsCachePath(home) {
     return join(home, ".codex", "models_cache.json");
 }
-export function readCodexModelsCache(home = homedir()) {
+function readCodexModelsCachePath(path) {
     try {
-        const parsed = JSON.parse(readFileSync(modelsCachePath(home), "utf8"));
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
         return Array.isArray(parsed.models)
             ? parsed.models.filter((entry) => entry !== null && typeof entry === "object")
             : [];
@@ -40,6 +40,12 @@ export function readCodexModelsCache(home = homedir()) {
         return [];
     }
 }
+export function readCodexModelsCache(home = homedir()) {
+    return readCodexModelsCachePath(modelsCachePath(home));
+}
+export function readCodexHomeModelsCache(codexHome) {
+    return readCodexModelsCachePath(join(codexHome, "models_cache.json"));
+}
 export function readCodexCatalogTemplate(home = homedir()) {
     return readCodexModelsCache(home)[0];
 }
@@ -79,9 +85,7 @@ export function codexListedStockSlugs(home = homedir()) {
     });
 }
 function codexModelId(modelId) {
-    return modelId.startsWith("codex/")
-        ? modelId.slice("codex/".length)
-        : modelId;
+    return modelId.startsWith("codex/") ? modelId.slice("codex/".length) : modelId;
 }
 function catalogModels(spec) {
     return spec.models.filter((model) => model.id === spec.defaultModel ||
@@ -90,10 +94,10 @@ function catalogModels(spec) {
 }
 function catalogIds(spec) {
     return [
-        ...new Set([spec.defaultModel, ...catalogModels(spec).flatMap((model) => [
-                model.id,
-                ...(model.aliases ?? [])
-            ])].map(codexModelId))
+        ...new Set([
+            spec.defaultModel,
+            ...catalogModels(spec).flatMap((model) => [model.id, ...(model.aliases ?? [])])
+        ].map(codexModelId))
     ];
 }
 /** True when a bare catalog id was projected from a `codex/`-namespaced model. */
@@ -189,8 +193,93 @@ export function codexCatalogEntries(spec, template, stockModels = [], options =
 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`;
+/**
+ * Serialize a versioned ModelInfo catalog for persistent profiles. It uses a
+ * target Codex home's stock metadata when available, and a complete fallback
+ * for first-run homes that have not downloaded `models_cache.json` yet.
+ */
+export function codexPersistentModelCatalogJson(models, template = undefined) {
+    const unique = new Set();
+    const catalogModels = models.flatMap((model) => {
+        if (model.id.length === 0 || unique.has(model.id))
+            return [];
+        unique.add(model.id);
+        return [
+            {
+                id: model.id,
+                ...(model.label !== undefined ? { label: model.label } : {}),
+                ...(model.reasoning !== undefined ? { reasoning: model.reasoning } : {})
+            }
+        ];
+    });
+    const defaultModel = catalogModels[0]?.id;
+    if (defaultModel === undefined)
+        throw new Error("at least one Codex catalog model is required");
+    // A normal Codex home has a version-matched stock entry we can use as the
+    // schema template. This fallback has the full required ModelInfo shape for
+    // first-run/empty homes, then codexCatalogEntries neutralizes the fields
+    // that would otherwise leak stock-model behavior into a routed model.
+    const fallbackTemplate = {
+        slug: "routekit-template",
+        display_name: "RouteKit",
+        description: "Gateway-routed model.",
+        default_reasoning_level: "medium",
+        supported_reasoning_levels: [],
+        shell_type: "shell_command",
+        visibility: "list",
+        supported_in_api: true,
+        priority: 0,
+        additional_speed_tiers: [],
+        service_tiers: [],
+        default_service_tier: "",
+        availability_nux: null,
+        upgrade: null,
+        base_instructions: NEUTRAL_INSTRUCTIONS,
+        model_messages: { instructions_template: NEUTRAL_INSTRUCTIONS },
+        include_skills_usage_instructions: false,
+        default_reasoning_summary: "none",
+        support_verbosity: true,
+        default_verbosity: "low",
+        apply_patch_tool_type: "freeform",
+        web_search_tool_type: "text_and_image",
+        truncation_policy: { mode: "tokens", limit: 10_000 },
+        supports_parallel_tool_calls: true,
+        supports_image_detail_original: true,
+        context_window: 272_000,
+        max_context_window: 272_000,
+        comp_hash: "3000",
+        effective_context_window_percent: 95,
+        experimental_supported_tools: [],
+        input_modalities: ["text", "image"],
+        supports_search_tool: true,
+        use_responses_lite: false,
+        tool_mode: "code_mode",
+        multi_agent_version: "v2"
+    };
+    const generated = codexCatalogEntries({ defaultModel, models: catalogModels }, template ?? fallbackTemplate, [], { appendUnlistedStock: false });
+    // The launcher strips the `codex/` namespace because it supplies a runtime
+    // provider override. Persistent profiles deliberately retain the gateway's
+    // public model id, so restore that exact spelling in their metadata too.
+    const entries = catalogModels.map((model, priority) => {
+        const generatedEntry = generated.find((entry) => entry.slug === codexModelId(model.id));
+        if (generatedEntry === undefined) {
+            throw new Error(`persistent Codex catalog omitted model ${JSON.stringify(model.id)}`);
+        }
+        return {
+            ...generatedEntry,
+            slug: model.id,
+            display_name: model.label ?? model.id,
+            priority
+        };
+    });
+    return JSON.stringify({ models: entries }, null, 2);
+}
+export function codexProfileFileToml(model, provider = PROVIDER_ID, modelCatalogPath) {
+    return `${tomlStringify({
+        model,
+        model_provider: provider,
+        ...(modelCatalogPath !== undefined ? { model_catalog_json: modelCatalogPath } : {})
+    }).trimEnd()}\n`;
 }
 export function codexProfileFiles(home, models, provider = PROVIDER_ID) {
     const written = [];
@@ -233,9 +322,7 @@ export function codexLaunchConfigToml(spec, modelCatalogPath, roles = []) {
     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"`]
-        : []), "");
+    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) {
@@ -244,66 +331,78 @@ export function codexLaunchConfigToml(spec, modelCatalogPath, roles = []) {
     }
     return lines.join("\n");
 }
-function spawnCodex(args, home, cwd, token) {
+export function resolveCodexHome(env = process.env) {
+    const configured = env.CODEX_HOME;
+    if (configured !== undefined && configured.length > 0) {
+        if (!isAbsolute(configured))
+            throw new Error("CODEX_HOME must be an absolute path");
+        return configured;
+    }
+    return join(env.HOME ?? env.USERPROFILE ?? homedir(), ".codex");
+}
+function tomlValue(value) {
+    return JSON.stringify(value);
+}
+function codexLaunchOverrides(spec, catalogPath, roles = []) {
+    const values = [
+        ["model", codexModelId(spec.defaultModel)],
+        ["model_provider", PROVIDER_ID],
+        [`model_providers.${PROVIDER_ID}.name`, "RouteKit gateway"],
+        [`model_providers.${PROVIDER_ID}.base_url`, `${trimTrailingSlashes(spec.gatewayUrl)}/v1`],
+        [`model_providers.${PROVIDER_ID}.wire_api`, "responses"],
+        [`model_providers.${PROVIDER_ID}.requires_openai_auth`, false]
+    ];
+    if (spec.auth?.token !== undefined)
+        values.push([`model_providers.${PROVIDER_ID}.env_key`, "ROUTEKIT_GATEWAY_TOKEN"]);
+    if (spec.reasoning?.mode === "effort")
+        values.push(["model_reasoning_effort", spec.reasoning.effort]);
+    if (catalogPath !== undefined)
+        values.push(["model_catalog_json", catalogPath]);
+    if (roles.length > 0) {
+        values.push(["features.multi_agent", true], ["agents.max_depth", 1]);
+        for (const role of roles) {
+            values.push([`agents.${role.id}.description`, role.description], [`agents.${role.id}.config_file`, role.configPath]);
+        }
+    }
+    return values.flatMap(([key, value]) => [
+        "-c",
+        `${key}=${typeof value === "string" ? tomlValue(value) : String(value)}`
+    ]);
+}
+function spawnCodex(args, home, cwd, token, dependencies) {
+    const spawnProcess = dependencies.spawnProcess ?? spawn;
+    const child = spawnProcess("codex", [...args], {
+        stdio: "inherit",
+        env: {
+            ...(dependencies.env ?? process.env),
+            CODEX_HOME: home,
+            ...(token !== undefined ? { ROUTEKIT_GATEWAY_TOKEN: token } : {})
+        },
+        ...(cwd !== undefined ? { cwd } : {})
+    });
     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 }));
+        child.once("error", reject);
+        child.once("exit", (code, signal) => resolve(code ?? (signal === null ? 0 : 1)));
     });
 }
-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);
+/** Launch against the user's real Codex home; only generated catalog data is temporary. */
+export async function launchCodex(ctx, deps = {}) {
+    const home = resolveCodexHome(deps.env ?? process.env);
+    const temp = mkdtempSync(join(tmpdir(), "rk-codex-"));
+    ctx.registerDisposer(() => rmSync(temp, { recursive: true, force: true }));
+    const stockModels = readCodexHomeModelsCache(home);
+    const template = stockModels[0];
+    const catalogPath = template === undefined ? undefined : join(temp, 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
-        }));
+        writeFileSync(catalogPath, codexModelCatalogJson(ctx.spec, template, stockModels, { appendUnlistedStock: false }), { mode: 0o600 });
     }
-    const roles = codexAgentRoles(home, spec.agentProfiles ?? []);
+    const roles = codexAgentRoles(temp, ctx.spec.agentProfiles ?? []);
     if (roles.length > 0) {
-        mkdirSync(join(home, PROFILE_DIR), { recursive: true });
+        mkdirSync(join(temp, PROFILE_DIR), { recursive: true, mode: 0o700 });
         for (const role of roles)
-            writeFileSync(role.configPath, codexAgentRoleToml(role));
+            writeFileSync(role.configPath, codexAgentRoleToml(role), { mode: 0o600 });
     }
-    const configPath = join(home, "config.toml");
-    const writeConfig = (catalog, activeRoles) => {
-        writeFileSync(configPath, codexLaunchConfigToml(spec, catalog, activeRoles));
-    };
-    writeConfig(catalogPath, roles);
+    const overrides = codexLaunchOverrides(ctx.spec, 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;
+    return await spawnCodex([...overrides, ...ctx.spec.args], home, ctx.spec.cwd, ctx.spec.auth?.token, deps);
 }

package/dist/test/install.test.js

@@ -30,6 +30,9 @@ test("Codex managed install updates and removes only owner-marked config", () =>
         assert.match(readFileSync(configPath, "utf8"), /model = "user-default"/);
         assert.match(readFileSync(configPath, "utf8"), /base_url = "http:\/\/127\.0\.0\.1:9999\/v1"/);
         assert.equal(existsSync(join(home, "opaque-secondary.config.toml")), true);
+        assert.equal(existsSync(installed.catalogPath), true);
+        assert.match(readFileSync(join(home, "opaque-primary.config.toml"), "utf8"), /model_catalog_json/);
+        assert.deepEqual(JSON.parse(readFileSync(installed.catalogPath, "utf8")).models.map((model) => model.slug), ["opaque-primary", "opaque-secondary"]);
         const updated = installCodexIntegration({
             gatewayUrl: "http://127.0.0.1:8888",
             owner: OWNER,
@@ -41,6 +44,7 @@ test("Codex managed install updates and removes only owner-marked config", () =>
         assert.equal(uninstallCodexIntegration({ ownerId: OWNER.id, codexHome: home }).removed, true);
         assert.equal(readFileSync(configPath, "utf8"), 'model = "user-default"\n');
         assert.equal(existsSync(join(home, "opaque-primary.config.toml")), false);
+        assert.equal(existsSync(installed.catalogPath), false);
     }
     finally {
         rmSync(home, { recursive: true, force: true });

package/dist/test/launch.test.js

@@ -3,7 +3,7 @@ import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
-import { codexAgentRoleToml, codexCatalogEntries, createIsolatedCodexHome, codexLaunchConfigToml, codexModelCatalogJson } from "../launch.js";
+import { codexAgentRoleToml, codexCatalogEntries, codexLaunchConfigToml, codexModelCatalogJson, codexPersistentModelCatalogJson, createIsolatedCodexHome, resolveCodexHome } from "../launch.js";
 const SPEC = {
     gatewayUrl: "http://127.0.0.1:9999",
     defaultModel: "opaque-primary",
@@ -50,13 +50,7 @@ test("Codex launcher serializes namespaced models without interpreting provider
         { effort: "quick", description: "quick" },
         { effort: "deep", description: "deep" }
     ]);
-    // Codex rejects the whole catalog file when any entry omits this field, so
-    // undiscovered models must serialize an explicit empty list.
     assert.deepEqual(entries[2]?.supported_reasoning_levels, []);
-    assert.equal(entries[2]?.default_reasoning_level, undefined);
-    assert.ok(entries
-        .slice(0, 3)
-        .every((entry) => Array.isArray(entry.supported_reasoning_levels)), "every gateway-routed entry carries supported_reasoning_levels");
     assert.deepEqual(JSON.parse(codexModelCatalogJson(SPEC, template)).models, entries.slice(0, 3));
 });
 test("Codex launcher filters incompatible OpenRouter models and aliases", () => {
@@ -75,190 +69,81 @@ test("Codex launcher filters incompatible OpenRouter models and aliases", () =>
         ],
         args: []
     };
-    const entries = codexCatalogEntries(spec, { slug: "stock" }, [], {
-        appendUnlistedStock: false
-    });
-    assert.deepEqual(entries.map((entry) => entry.slug), ["openai/unknown", "openrouter/reasoning", "reasoning-alias", "openai-alias"]);
-});
-test("Codex launcher retains an incompatible selected default deterministically", () => {
-    const spec = {
-        gatewayUrl: "http://127.0.0.1:9999",
-        defaultModel: "selected-alias",
-        models: [
-            {
-                id: "openrouter/chat-only",
-                provider: "openrouter",
-                aliases: ["selected-alias", "second-alias"]
-            },
-            { id: "openrouter/hidden", provider: "openrouter", aliases: ["hidden-alias"] }
-        ],
-        args: []
-    };
-    assert.deepEqual(codexCatalogEntries(spec, { slug: "stock" }, [], {
-        appendUnlistedStock: false
-    }).map((entry) => entry.slug), ["selected-alias", "openrouter/chat-only", "second-alias"]);
-});
-test("Codex launcher exposes only provider-discovered Claude effort levels", () => {
-    const spec = {
-        gatewayUrl: "http://127.0.0.1:9999",
-        defaultModel: "claude-code/claude-fable-5",
-        models: [
-            {
-                id: "claude-code/claude-fable-5",
-                reasoning: {
-                    status: "supported",
-                    efforts: [{ id: "low" }, { id: "high" }, { id: "max" }],
-                    budget: { minTokens: 1_024 },
-                    adaptive: true,
-                    wireShape: "anthropic",
-                    provenance: "provider"
-                }
-            }
-        ],
-        args: []
-    };
-    const [entry] = codexCatalogEntries(spec, {
-        slug: "stock",
-        visibility: "list",
-        supported_reasoning_levels: [{ effort: "template" }],
-        default_reasoning_level: "template"
-    });
-    assert.deepEqual(entry?.supported_reasoning_levels, [
-        { effort: "low", description: "low" },
-        { effort: "high", description: "high" },
-        { effort: "max", description: "max" }
-    ]);
-    assert.equal(entry?.default_reasoning_level, undefined);
+    assert.deepEqual(codexCatalogEntries(spec, { slug: "stock" }, [], { appendUnlistedStock: false }).map((entry) => entry.slug), ["openai/unknown", "openrouter/reasoning", "reasoning-alias", "openai-alias"]);
 });
-test("Codex launcher neutralizes stock-model behavior fields from the template", () => {
+test("Codex launcher neutralizes stock-model behavior for gateway-routed models", () => {
     const template = {
         slug: "gpt-stock",
-        display_name: "Stock",
-        visibility: "list",
-        supported_reasoning_levels: [{ effort: "medium" }],
-        default_reasoning_level: "medium",
-        // Real stock entries carry fields that change how Codex talks to the
-        // model; none of them may leak into gateway-routed entries.
         tool_mode: "code_mode_only",
         use_responses_lite: true,
         additional_speed_tiers: ["fast"],
-        service_tiers: [{ id: "priority", name: "Fast" }],
+        service_tiers: [{ id: "priority" }],
         default_service_tier: "priority",
         base_instructions: "You are Codex, an agent based on GPT-5.",
-        model_messages: {
-            instructions_template: "You are Codex, an agent based on GPT-5.",
-            instructions_variables: null
-        }
+        model_messages: { instructions_template: "You are Codex, an agent based on GPT-5." }
     };
     const [entry] = codexCatalogEntries(SPEC, template);
     assert.ok(entry);
     assert.equal("tool_mode" in entry, false);
-    assert.equal("default_service_tier" in entry, false);
     assert.equal(entry.use_responses_lite, false);
     assert.deepEqual(entry.additional_speed_tiers, []);
     assert.deepEqual(entry.service_tiers, []);
-    // The developer message must not claim a stock model's identity.
     assert.equal(entry.base_instructions, "You are a coding agent.");
-    assert.deepEqual(entry.model_messages, {
-        instructions_template: "You are a coding agent.",
-        instructions_variables: null
-    });
-    // A minimal template gains no wire-shape fields it never had.
-    const [minimal] = codexCatalogEntries(SPEC, { slug: "s", visibility: "list" });
-    assert.ok(minimal);
-    assert.equal("use_responses_lite" in minimal, false);
-    assert.equal("service_tiers" in minimal, false);
+    assert.deepEqual(entry.model_messages, { instructions_template: "You are a coding agent." });
 });
-test("Codex launcher passes stock ModelInfo through for codex-native models only", () => {
+test("Codex keeps real stock ModelInfo only for Codex-native models", () => {
     const spec = {
         gatewayUrl: "http://127.0.0.1:9999",
         defaultModel: "codex/gpt-5.5",
-        models: [
-            { id: "codex/gpt-5.5" },
-            // A foreign model that happens to collide with a stock slug must NOT
-            // inherit the stock entry: it is not the Codex-native model.
-            { id: "claude-code/gpt-5.4" },
-            { id: "claude-code/claude-sonnet-5" }
-        ],
+        models: [{ id: "codex/gpt-5.5" }, { id: "claude-code/gpt-5.4" }],
         args: []
     };
-    const template = { slug: "stock", display_name: "Stock", visibility: "list" };
-    const stock = [
-        {
-            slug: "gpt-5.5",
-            display_name: "GPT-5.5",
-            description: "Stock Codex model.",
-            base_instructions: "You are Codex, an agent based on GPT-5.",
-            tool_mode: "code_mode_only",
-            use_responses_lite: true,
-            supported_reasoning_levels: [{ effort: "xhigh" }],
-            default_reasoning_level: "xhigh",
-            visibility: "hidden"
-        },
-        { slug: "gpt-5.4", display_name: "GPT-5.4" },
-        { slug: "gpt-unrelated", display_name: "Unrelated" }
-    ];
-    const entries = codexCatalogEntries(spec, template, stock, {
+    const stock = [{ slug: "gpt-5.5", tool_mode: "code_mode_only" }, { slug: "gpt-5.4" }];
+    const [native, foreign] = codexCatalogEntries(spec, { slug: "stock" }, stock, {
         appendUnlistedStock: false
     });
-    assert.deepEqual(entries.map((entry) => entry.slug), ["gpt-5.5", "claude-code/gpt-5.4", "claude-code/claude-sonnet-5"]);
-    const [native, foreignCollision, foreign] = entries;
-    // Native passthrough keeps the tuned stock behavior, pinned to list + HTTP.
-    assert.equal(native?.base_instructions, "You are Codex, an agent based on GPT-5.");
     assert.equal(native?.tool_mode, "code_mode_only");
-    assert.equal(native?.use_responses_lite, true);
-    assert.equal(native?.default_reasoning_level, "xhigh");
-    assert.equal(native?.visibility, "list");
-    assert.equal(native?.prefer_websockets, false);
-    // Foreign models never inherit stock entries, colliding slug or not.
-    assert.equal(foreignCollision?.base_instructions, undefined);
-    assert.equal("tool_mode" in (foreignCollision ?? {}), false);
-    assert.equal("tool_mode" in (foreign ?? {}), false);
-    // Unlisted stock models stay out when appending is disabled.
-    assert.ok(!entries.some((entry) => entry.slug === "gpt-unrelated"));
+    assert.equal(foreign?.tool_mode, undefined);
 });
-test("Codex launcher serializes one gateway provider and generic agent profiles", () => {
+test("Codex launcher serializes a gateway provider and generic agent profiles", () => {
     const role = { ...PROFILE, configPath: "/tmp/reviewer.toml" };
-    const config = codexLaunchConfigToml(SPEC, "/tmp/catalog.json", [role]);
+    const config = codexLaunchConfigToml({ ...SPEC, auth: { token: "test" } }, "/tmp/catalog.json", [
+        role
+    ]);
     assert.match(config, /model = "opaque-primary"/);
     assert.match(config, /base_url = "http:\/\/127\.0\.0\.1:9999\/v1"/);
+    assert.match(config, /env_key = "ROUTEKIT_GATEWAY_TOKEN"/);
     assert.match(config, /config_file = "\/tmp\/reviewer\.toml"/);
-    const profile = codexAgentRoleToml(PROFILE);
-    assert.match(profile, /model = "opaque-secondary"/);
-    assert.match(profile, /developer_instructions = "Return concise findings\."/);
+    assert.match(codexAgentRoleToml(PROFILE), /developer_instructions = "Return concise findings\."/);
 });
-test("Codex launcher projects codex models to native picker ids", () => {
-    const spec = {
-        gatewayUrl: "http://127.0.0.1:9999",
-        defaultModel: "codex/gpt-5.5",
-        models: [
-            { id: "codex/gpt-5.5", label: "GPT-5.5 subscription" },
-            { id: "claude-code/claude-sonnet-4-6" }
-        ],
-        args: []
-    };
-    const template = {
-        slug: "stock",
-        display_name: "Stock",
-        visibility: "list"
-    };
-    assert.deepEqual(codexCatalogEntries(spec, template).map((entry) => [
-        entry.slug,
-        entry.display_name
-    ]), [
-        ["gpt-5.5", "GPT-5.5 subscription"],
-        [
-            "claude-code/claude-sonnet-4-6",
-            "claude-code/claude-sonnet-4-6"
-        ]
+test("persistent Codex profiles carry matching model metadata", () => {
+    const catalog = JSON.parse(codexPersistentModelCatalogJson([
+        {
+            id: "openai/gpt-4o-mini",
+            reasoning: {
+                status: "supported",
+                efforts: [{ id: "low" }, { id: "high" }],
+                defaultEffort: "low",
+                provenance: "provider"
+            }
+        },
+        { id: "codex/gpt-5.6" }
+    ]));
+    assert.deepEqual(catalog.models.map((model) => model.slug), [
+        "openai/gpt-4o-mini",
+        "codex/gpt-5.6"
     ]);
-    assert.match(codexLaunchConfigToml(spec), /model = "gpt-5\.5"/);
-    assert.match(codexAgentRoleToml({
-        ...PROFILE,
-        model: "codex/gpt-5.5"
-    }), /model = "gpt-5\.5"/);
+    assert.deepEqual(catalog.models[0]?.supported_reasoning_levels, [
+        { effort: "low", description: "low" },
+        { effort: "high", description: "high" }
+    ]);
+    assert.equal(catalog.models[0]?.supports_reasoning_summaries, true);
+});
+test("Codex normal home honors absolute CODEX_HOME and rejects relative values", () => {
+    assert.equal(resolveCodexHome({ CODEX_HOME: "/private/codex" }), "/private/codex");
+    assert.throws(() => resolveCodexHome({ CODEX_HOME: "relative" }), /absolute path/);
 });
-test("isolated Codex homes live under the user cache instead of the system temp root", () => {
+test("isolated Codex homes used by the harness live under the user cache", () => {
     const root = mkdtempSync(join(tmpdir(), "routekit-codex-home-test-"));
     const userHome = join(root, "home");
     try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-tool-codex",
   "private": false,
-  "version": "0.16.8",
+  "version": "0.17.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -29,11 +29,11 @@
     "@openai/codex-sdk": "0.145.0",
     "smol-toml": "1.7.0",
     "zod": "4.4.3",
-    "@velum-labs/routekit-contracts": "0.16.8",
-    "@velum-labs/routekit-harness-core": "0.16.8",
-    "@velum-labs/routekit-runtime": "0.16.8",
-    "@velum-labs/routekit-tools": "0.16.8",
-    "@velum-labs/routekit-registry": "0.16.8"
+    "@velum-labs/routekit-contracts": "0.17.0",
+    "@velum-labs/routekit-harness-core": "0.17.0",
+    "@velum-labs/routekit-registry": "0.17.0",
+    "@velum-labs/routekit-runtime": "0.17.0",
+    "@velum-labs/routekit-tools": "0.17.0"
   },
   "keywords": [
     "llm",