@velum-labs/routekit-tool-codex 0.9.0

package/dist/test/driver.test.js

@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { driverContractSuite } from "@velum-labs/routekit-harness-core/testing";
+import { createCodexDriver } from "../driver.js";
+/**
+ * A fake `codex` CLI: honors `--version`, and for `exec --json`
+ * reads the prompt from stdin and emits the JSONL event stream the codex-sdk
+ * parses (thread.started, turn.started, item, turn.completed). `resume <id>`
+ * reuses the given thread id so resume round-trips are observable.
+ */
+const FAKE_CODEX_CLI = `#!/usr/bin/env node
+const args = process.argv.slice(2);
+if (args[0] === "--version") { console.log("codex-cli 0.145.0"); process.exit(0); }
+const resumeIdx = args.indexOf("resume");
+const threadId = resumeIdx >= 0 ? args[resumeIdx + 1] : "thread_fake_1";
+let input = "";
+process.stdin.on("data", (c) => (input += c));
+process.stdin.on("end", () => {
+  const emit = (obj) => process.stdout.write(JSON.stringify(obj) + "\\n");
+  emit({ type: "thread.started", thread_id: threadId });
+  emit({ type: "turn.started" });
+  emit({ type: "item.started", item: { id: "i1", type: "agent_message", text: "" } });
+  emit({ type: "item.completed", item: { id: "i1", type: "agent_message", text: "ARGS: " + args.join(" ") + "\\nOK: " + input.trim() } });
+  emit({ type: "turn.completed", usage: { input_tokens: 3, cached_input_tokens: 0, output_tokens: 2, reasoning_output_tokens: 0 } });
+  process.exit(0);
+});
+`;
+function fakeCodexRepo() {
+    const dir = mkdtempSync(join(tmpdir(), "codex-driver-"));
+    const command = join(dir, "codex-fake.mjs");
+    writeFileSync(command, FAKE_CODEX_CLI);
+    chmodSync(command, 0o755);
+    return { command, cwd: dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+const repo = fakeCodexRepo();
+driverContractSuite({
+    name: "codex driver",
+    createInstance: async () => {
+        const driver = createCodexDriver();
+        const config = driver.configSchema.parse({ command: repo.command });
+        return driver.createInstance(config);
+    },
+    startOptions: () => ({ cwd: repo.cwd, model: "gpt-5.1-codex" }),
+    supportsResume: true,
+    turnTimeoutMs: 15_000
+});
+test("codex driver maps the CLI event stream into canonical events", async () => {
+    const driver = createCodexDriver();
+    const instance = await driver.createInstance(driver.configSchema.parse({ command: repo.command }));
+    try {
+        const session = await instance.startSession({ cwd: repo.cwd });
+        const events = [];
+        for await (const event of session.sendTurn({ prompt: "hello codex" })) {
+            events.push(event);
+        }
+        const types = events.map((event) => event.type);
+        assert.ok(types.includes("session.started"));
+        assert.ok(types.includes("turn.started"));
+        const delta = events.find((event) => event.type === "content.delta");
+        assert.ok(delta && delta.text.includes("hello codex"));
+        const completed = events.find((event) => event.type === "turn.completed");
+        assert.equal(completed?.endReason, "completed");
+        assert.equal(completed?.usage?.outputTokens, 2);
+        // The real thread id from thread.started becomes the resume cursor.
+        const cursor = session.resumeCursor();
+        assert.equal((cursor?.data).threadId, "thread_fake_1");
+        // Every event carries the codex kind and the raw envelope is preserved.
+        assert.ok(events.every((event) => event.kind === "codex"));
+        assert.ok(events.some((event) => event.raw?.source === "codex.exec.json"));
+    }
+    finally {
+        await instance.dispose();
+        repo.cleanup();
+    }
+});
+test("codex driver forwards effort as the SDK CLI config", async () => {
+    const driver = createCodexDriver();
+    const effortRepo = fakeCodexRepo();
+    const instance = await driver.createInstance(driver.configSchema.parse({ command: effortRepo.command }));
+    try {
+        const session = await instance.startSession({
+            cwd: effortRepo.cwd,
+            reasoning: { mode: "effort", effort: "low" }
+        });
+        const events = [];
+        for await (const event of session.sendTurn({ prompt: "reason carefully" })) {
+            events.push(event);
+        }
+        const text = events
+            .flatMap((event) => (event.type === "content.delta" ? [event.text] : []))
+            .join("");
+        assert.match(text, /model_reasoning_effort="low"/);
+    }
+    finally {
+        await instance.dispose();
+        effortRepo.cleanup();
+    }
+});
+test("codex driver probe reports version and installed state", async () => {
+    const driver = createCodexDriver();
+    const repo2 = fakeCodexRepo();
+    try {
+        const status = await driver.probe({ env: { ...process.env } });
+        // The default command "codex" may or may not be installed on the host, so
+        // this only asserts the shape; the fake-command instance path is covered above.
+        assert.equal(status.kind, "codex");
+        assert.ok(typeof status.installed === "boolean");
+    }
+    finally {
+        repo2.cleanup();
+    }
+});

package/dist/test/install.test.d.ts

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

package/dist/test/install.test.js

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { installCodexIntegration, uninstallCodexIntegration } from "../install.js";
+const OWNER = {
+    id: "example-host",
+    displayName: "Example Host",
+    providerId: "example_route",
+    installCommand: "example install codex",
+    uninstallCommand: "example uninstall codex",
+    startCommand: "example serve"
+};
+test("Codex managed install updates 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');
+    try {
+        const installed = installCodexIntegration({
+            gatewayUrl: "http://127.0.0.1:9999/",
+            owner: OWNER,
+            profiles: [
+                { modelId: "opaque-primary" },
+                { modelId: "opaque-secondary", description: "Secondary route" }
+            ],
+            codexHome: home
+        });
+        assert.equal(installed.action, "installed");
+        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);
+        const updated = installCodexIntegration({
+            gatewayUrl: "http://127.0.0.1:8888",
+            owner: OWNER,
+            profiles: [{ modelId: "opaque-primary" }],
+            codexHome: home
+        });
+        assert.equal(updated.action, "updated");
+        assert.equal(existsSync(join(home, "opaque-secondary.config.toml")), false);
+        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);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test("Codex profiles can preserve an opaque model id behind a safe selector", () => {
+    const home = mkdtempSync(join(tmpdir(), "routekit-codex-opaque-"));
+    try {
+        const result = installCodexIntegration({
+            gatewayUrl: "http://127.0.0.1:9999",
+            owner: OWNER,
+            profiles: [{ modelId: "provider/model", profileId: "route-1" }],
+            codexHome: home
+        });
+        assert.deepEqual(result.profiles, ["route-1"]);
+        assert.match(readFileSync(join(home, "route-1.config.toml"), "utf8"), /provider\/model/);
+        assert.equal(existsSync(join(home, "provider", "model.config.toml")), false);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/test/launch.test.d.ts

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

package/dist/test/launch.test.js

@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+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";
+const SPEC = {
+    gatewayUrl: "http://127.0.0.1:9999",
+    defaultModel: "opaque-primary",
+    models: [
+        {
+            id: "opaque-primary",
+            label: "Primary",
+            aliases: ["primary-alias"],
+            reasoning: {
+                status: "supported",
+                efforts: [{ id: "quick" }, { id: "deep" }],
+                defaultEffort: "quick",
+                provenance: "provider"
+            }
+        },
+        {
+            id: "opaque-secondary",
+            reasoning: { status: "unknown", provenance: "unknown" }
+        }
+    ],
+    args: []
+};
+const PROFILE = {
+    id: "reviewer",
+    model: "opaque-secondary",
+    description: "Review changes.",
+    instructions: "Return concise findings."
+};
+test("Codex launcher serializes namespaced models without interpreting provider ids", () => {
+    const template = {
+        slug: "stock",
+        display_name: "Stock",
+        visibility: "list",
+        supported_reasoning_levels: [{ effort: "template" }],
+        default_reasoning_level: "template"
+    };
+    const entries = codexCatalogEntries(SPEC, template, [
+        template,
+        { slug: "opaque-secondary", display_name: "duplicate" }
+    ]);
+    assert.deepEqual(entries.map((entry) => entry.slug), ["opaque-primary", "primary-alias", "opaque-secondary", "stock"]);
+    assert.equal(entries[0]?.display_name, "Primary");
+    assert.deepEqual(entries[0]?.supported_reasoning_levels, [
+        { 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.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 neutralizes stock-model behavior fields from the template", () => {
+    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" }],
+        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
+        }
+    };
+    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);
+});
+test("Codex launcher passes stock ModelInfo through for codex-native models only", () => {
+    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" }
+        ],
+        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, {
+        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"));
+});
+test("Codex launcher serializes one gateway provider and generic agent profiles", () => {
+    const role = { ...PROFILE, configPath: "/tmp/reviewer.toml" };
+    const config = codexLaunchConfigToml(SPEC, "/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, /config_file = "\/tmp\/reviewer\.toml"/);
+    const profile = codexAgentRoleToml(PROFILE);
+    assert.match(profile, /model = "opaque-secondary"/);
+    assert.match(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"
+        ]
+    ]);
+    assert.match(codexLaunchConfigToml(spec), /model = "gpt-5\.5"/);
+    assert.match(codexAgentRoleToml({
+        ...PROFILE,
+        model: "codex/gpt-5.5"
+    }), /model = "gpt-5\.5"/);
+});
+test("isolated Codex homes live under the user cache instead of the system temp root", () => {
+    const root = mkdtempSync(join(tmpdir(), "routekit-codex-home-test-"));
+    const userHome = join(root, "home");
+    try {
+        const isolated = createIsolatedCodexHome("driver-", { HOME: userHome });
+        assert.ok(isolated.startsWith(join(userHome, ".cache", "routekit", "codex", "driver-")));
+        assert.equal(existsSync(isolated), true);
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@velum-labs/routekit-tool-codex",
+  "private": false,
+  "version": "0.9.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/tool-codex"
+  },
+  "description": "Product-neutral Codex launcher, serializer, and canonical harness driver.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@openai/codex-sdk": "0.145.0",
+    "smol-toml": "1.7.0",
+    "zod": "4.4.3",
+    "@velum-labs/routekit-harness-core": "0.9.0",
+    "@velum-labs/routekit-runtime": "0.9.0",
+    "@velum-labs/routekit-registry": "0.9.0",
+    "@velum-labs/routekit-tools": "0.9.0"
+  },
+  "keywords": [
+    "llm",
+    "coding-agent",
+    "codex",
+    "harness",
+    "adapter"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "node --test \"dist/test/*.test.js\""
+  }
+}