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

package/dist/install.d.ts

@@ -1,7 +1,10 @@
 import type { ModelReasoningCapabilities } from "@velum-labs/routekit-contracts";
 export type CodexInstallProfile = {
     modelId: string;
-    /** Safe Codex profile selector; defaults to `modelId`. */
+    /**
+     * Legacy selector for the one persistent profile. New callers should use
+     * `CodexInstallInput.profileId`; when both are absent it is `routekit`.
+     */
     profileId?: string;
     description?: string;
     reasoning?: ModelReasoningCapabilities;
@@ -16,7 +19,16 @@ export type CodexInstallOwner = {
 };
 export type CodexInstallInput = {
     gatewayUrl: string;
+    /**
+     * The RouteKit models made available through Codex's model picker.  This
+     * remains named `profiles` for API compatibility, although persistent
+     * installs now write one RouteKit profile rather than one file per model.
+     */
     profiles: readonly CodexInstallProfile[];
+    /** Model selected when the single RouteKit profile is first opened. */
+    defaultModel?: string;
+    /** Safe selector for the one persistent RouteKit profile. */
+    profileId?: string;
     owner: CodexInstallOwner;
     codexHome?: string;
 };

package/dist/install.js

@@ -26,11 +26,7 @@ function catalogFileName(ownerId) {
     }
     return `.${ownerId}-model-catalog.json`;
 }
-function profileSelector(profile) {
-    return profile.profileId ?? profile.modelId;
-}
-function profileFileName(profile) {
-    const selector = profileSelector(profile);
+function profileFileName(selector) {
     if (selector.length === 0 ||
         selector.includes("/") ||
         selector.includes("\\") ||
@@ -39,6 +35,24 @@ function profileFileName(profile) {
     }
     return `${selector}.config.toml`;
 }
+function selectedProfileId(input) {
+    return input.profileId ?? input.profiles[0]?.profileId ?? "routekit";
+}
+function selectedDefaultModel(input) {
+    const model = input.defaultModel ?? input.profiles[0]?.modelId;
+    if (model === undefined)
+        throw new Error("at least one Codex catalog model is required");
+    if (!input.profiles.some((profile) => profile.modelId === model)) {
+        throw new Error(`the Codex default model ${JSON.stringify(model)} is not in the RouteKit catalog`);
+    }
+    return model;
+}
+function orderedCatalogProfiles(profiles, defaultModel) {
+    return [
+        ...profiles.filter((profile) => profile.modelId === defaultModel),
+        ...profiles.filter((profile) => profile.modelId !== defaultModel)
+    ];
+}
 /** Serialize one additive, owner-marked Codex provider block. */
 export function codexIntegrationBlock(input) {
     const base = trimTrailingSlashes(input.gatewayUrl);
@@ -47,6 +61,7 @@ export function codexIntegrationBlock(input) {
     const filesComment = profileFilesComment(input.owner.id);
     const catalogComment = catalogFileComment(input.owner.id);
     const catalogFile = catalogFileName(input.owner.id);
+    const profileId = selectedProfileId(input);
     const body = tomlStringify({
         model_providers: {
             [input.owner.providerId]: {
@@ -63,9 +78,10 @@ export function codexIntegrationBlock(input) {
         `# 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(" ")}`,
+        `# Then launch: codex --profile ${profileId}`,
+        "# That one profile keeps the RouteKit provider selected while Codex's model picker",
+        "# reads the catalog below. It does not change your normal Codex default model.",
+        `${filesComment} ${profileFileName(profileId)}`,
         `${catalogComment} ${catalogFile}`,
         "",
         body.trimEnd(),
@@ -134,14 +150,6 @@ function assertNoConflicts(outside, input) {
         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+$/, "");
@@ -159,9 +167,19 @@ function removeOwnedProfileFile(path, ownerId) {
         // Best-effort cleanup; an orphaned profile does not alter the main config.
     }
 }
+function assertProfileFileCanBeManaged(path, ownerId) {
+    if (!existsSync(path))
+        return;
+    if (readFileSync(path, "utf8").includes(`Managed by ${ownerId}`))
+        return;
+    throw new Error(`refusing to overwrite an existing Codex profile: ${path}; ` +
+        `rename it, then rerun the RouteKit install`);
+}
 export function installCodexIntegration(input) {
     if (input.profiles.length === 0)
-        throw new Error("at least one Codex profile is required");
+        throw new Error("at least one Codex catalog model is required");
+    const defaultModel = selectedDefaultModel(input);
+    const profileId = selectedProfileId(input);
     const configPath = codexIntegrationConfigPath(input.codexHome);
     const codexHome = dirname(configPath);
     const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
@@ -182,25 +200,28 @@ export function installCodexIntegration(input) {
     if (!isRecord(providers) || providers[input.owner.providerId] === undefined) {
         throw new Error("internal error: the assembled Codex config lost its managed provider block");
     }
+    const persistentProfilePath = join(codexHome, profileFileName(profileId));
+    assertProfileFileCanBeManaged(persistentProfilePath, input.owner.id);
     mkdirSync(codexHome, { recursive: true });
-    writeFileSync(catalogPath, codexPersistentModelCatalogJson(input.profiles.map((profile) => ({
+    writeFileSync(catalogPath, codexPersistentModelCatalogJson(orderedCatalogProfiles(input.profiles, defaultModel).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))));
+    writeFileSync(persistentProfilePath, `# Managed by ${input.owner.id}\n${codexProfileFileToml(defaultModel, input.owner.providerId, catalogPath)}`, { mode: 0o600 });
+    // Write the new profile before replacing the managed block, then clean up
+    // legacy per-model files last. An interrupted migration therefore leaves a
+    // working old or new profile, never a config that points at a missing file.
+    writeFileSync(configPath, next);
+    const nextFiles = new Set([persistentProfilePath]);
     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, catalogPath)}`, { mode: 0o600 });
-    }
     return {
         configPath,
         catalogPath,
         action: managed !== undefined ? "updated" : "installed",
-        profiles: input.profiles.map(profileSelector)
+        profiles: [profileId]
     };
 }
 export function uninstallCodexIntegration(input) {

package/dist/test/install.test.js

@@ -12,7 +12,7 @@ const OWNER = {
     uninstallCommand: "example uninstall codex",
     startCommand: "example serve"
 };
-test("Codex managed install updates and removes only owner-marked config", () => {
+test("Codex managed install adds one picker-backed profile and removes only owner-marked config", () => {
     const home = mkdtempSync(join(tmpdir(), "routekit-codex-install-"));
     const configPath = join(home, "config.toml");
     writeFileSync(configPath, 'model = "user-default"\n');
@@ -24,33 +24,41 @@ test("Codex managed install updates and removes only owner-marked config", () =>
                 { modelId: "opaque-primary" },
                 { modelId: "opaque-secondary", description: "Secondary route" }
             ],
+            defaultModel: "opaque-secondary",
             codexHome: home
         });
         assert.equal(installed.action, "installed");
+        assert.deepEqual(installed.profiles, ["routekit"]);
         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.match(readFileSync(configPath, "utf8"), /codex --profile routekit/);
+        assert.equal(existsSync(join(home, "routekit.config.toml")), true);
+        assert.equal(existsSync(join(home, "opaque-primary.config.toml")), false);
+        assert.equal(existsSync(join(home, "opaque-secondary.config.toml")), false);
         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"]);
+        assert.match(readFileSync(join(home, "routekit.config.toml"), "utf8"), /model = "opaque-secondary"/);
+        assert.match(readFileSync(join(home, "routekit.config.toml"), "utf8"), /model_catalog_json/);
+        assert.deepEqual(JSON.parse(readFileSync(installed.catalogPath, "utf8")).models.map((model) => model.slug), ["opaque-secondary", "opaque-primary"]);
         const updated = installCodexIntegration({
             gatewayUrl: "http://127.0.0.1:8888",
             owner: OWNER,
             profiles: [{ modelId: "opaque-primary" }],
+            defaultModel: "opaque-primary",
             codexHome: home
         });
         assert.equal(updated.action, "updated");
-        assert.equal(existsSync(join(home, "opaque-secondary.config.toml")), false);
+        assert.deepEqual(updated.profiles, ["routekit"]);
+        assert.match(readFileSync(join(home, "routekit.config.toml"), "utf8"), /model = "opaque-primary"/);
         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(join(home, "routekit.config.toml")), false);
         assert.equal(existsSync(installed.catalogPath), false);
     }
     finally {
         rmSync(home, { recursive: true, force: true });
     }
 });
-test("Codex profiles can preserve an opaque model id behind a safe selector", () => {
+test("Codex's single persistent profile can use a safe custom selector", () => {
     const home = mkdtempSync(join(tmpdir(), "routekit-codex-opaque-"));
     try {
         const result = installCodexIntegration({
@@ -67,3 +75,65 @@ test("Codex profiles can preserve an opaque model id behind a safe selector", ()
         rmSync(home, { recursive: true, force: true });
     }
 });
+test("Codex reinstall migrates a legacy per-model installation to one RouteKit profile", () => {
+    const home = mkdtempSync(join(tmpdir(), "routekit-codex-migrate-"));
+    const configPath = join(home, "config.toml");
+    const legacyProfiles = ["routekit-model-1.config.toml", "routekit-model-2.config.toml"];
+    writeFileSync(configPath, [
+        'model = "user-default"',
+        "",
+        "# >>> example-host integration >>>",
+        "# example-host-profile-files: routekit-model-1.config.toml routekit-model-2.config.toml",
+        "# example-host-catalog-file: .example-host-model-catalog.json",
+        "",
+        "[model_providers.example_route]",
+        'name = "Example Host gateway"',
+        'base_url = "http://127.0.0.1:9999/v1"',
+        'wire_api = "responses"',
+        "requires_openai_auth = false",
+        'env_key = "ROUTEKIT_GATEWAY_TOKEN"',
+        "",
+        "# <<< example-host integration <<<",
+        ""
+    ].join("\n"));
+    for (const profile of legacyProfiles) {
+        writeFileSync(join(home, profile), "# Managed by example-host\nmodel = \"opaque-primary\"\n");
+    }
+    writeFileSync(join(home, ".example-host-model-catalog.json"), "{\"models\":[]}\n");
+    try {
+        const result = installCodexIntegration({
+            gatewayUrl: "http://127.0.0.1:8888",
+            owner: OWNER,
+            profiles: [{ modelId: "opaque-primary" }, { modelId: "opaque-secondary" }],
+            defaultModel: "opaque-secondary",
+            codexHome: home
+        });
+        assert.equal(result.action, "updated");
+        assert.deepEqual(result.profiles, ["routekit"]);
+        assert.equal(existsSync(join(home, "routekit.config.toml")), true);
+        for (const profile of legacyProfiles)
+            assert.equal(existsSync(join(home, profile)), false);
+        assert.match(readFileSync(configPath, "utf8"), /example-host-profile-files: routekit\.config\.toml/);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test("Codex install refuses to overwrite a user-owned routekit profile", () => {
+    const home = mkdtempSync(join(tmpdir(), "routekit-codex-profile-conflict-"));
+    const configPath = join(home, "config.toml");
+    writeFileSync(join(home, "routekit.config.toml"), 'model = "user-profile"\n');
+    try {
+        assert.throws(() => installCodexIntegration({
+            gatewayUrl: "http://127.0.0.1:9999",
+            owner: OWNER,
+            profiles: [{ modelId: "opaque-primary" }],
+            codexHome: home
+        }), /refusing to overwrite an existing Codex profile/);
+        assert.equal(existsSync(configPath), false);
+        assert.equal(existsSync(join(home, ".example-host-model-catalog.json")), false);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-tool-codex",
   "private": false,
-  "version": "0.17.0",
+  "version": "0.17.2",
   "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.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"
+    "@velum-labs/routekit-contracts": "0.17.2",
+    "@velum-labs/routekit-harness-core": "0.17.2",
+    "@velum-labs/routekit-runtime": "0.17.2",
+    "@velum-labs/routekit-tools": "0.17.2",
+    "@velum-labs/routekit-registry": "0.17.2"
   },
   "keywords": [
     "llm",