From e2b2af695babec5350887aeb8295239adc4c8bc9 Mon Sep 17 00:00:00 2001 From: Jee Date: Wed, 4 Nov 2026 15:08:54 +0800 Subject: [PATCH] feat(codex): support explicit local model catalog configuration (#2266) * fix(codex): reuse local model catalogs by default * fix(codex): verify catalog provenance and native schema before reuse * fix(codex): keep refresh credentials out of discovery homes * refactor(codex): reduce catalog support to explicit configuration * fix(codex): invalidate selected catalogs and resolve shim names --- cli/README.md | 21 +++++ cli/src/codex/codexAppServerClient.test.ts | 16 ++++ cli/src/codex/codexAppServerClient.ts | 11 ++- cli/src/codex/shared/launch.ts | 2 + cli/src/codex/utils/codexExecutable.test.ts | 33 ++++++++ cli/src/codex/utils/codexExecutable.ts | 15 ++++ .../utils/modelCatalog.integration.test.ts | 81 +++++++++++++++++++ cli/src/codex/utils/modelCatalog.test.ts | 52 ++++++++++++ cli/src/codex/utils/modelCatalog.ts | 24 ++++++ cli/src/modules/common/codexModels.test.ts | 24 ++++++ cli/src/modules/common/codexModels.ts | 6 +- 11 files changed, 280 insertions(+), 5 deletions(-) create mode 100644 cli/src/codex/utils/modelCatalog.integration.test.ts create mode 100644 cli/src/codex/utils/modelCatalog.test.ts create mode 100644 cli/src/codex/utils/modelCatalog.ts diff --git a/cli/README.md b/cli/README.md index 8b86d89f..21749222 100644 --- a/cli/README.md +++ b/cli/README.md @@ -186,6 +186,27 @@ tail reload. Local transcript timing uses the original start and completion timestamps; imported history and turns without an observed live start do not receive a new duration. +### Codex model catalog + +To use an existing static Codex model catalog, set +`HAPI_CODEX_MODEL_CATALOG_JSON` on the CLI/runner machine to an absolute path +or `~/...`. HAPI passes it as `-c model_catalog_json=...` to standalone and +shared app-servers, including resumed sessions. This explicit HAPI setting +has precedence over Codex configuration files; an explicit launch +`-c 'model_catalog_json="/path/to/catalog.json"'` takes precedence over HAPI. + +When unset, HAPI adds no catalog override and Codex uses its normal configuration +and discovery. You can also configure `model_catalog_json` directly in Codex's +`config.toml`. HAPI does not inspect, generate, refresh or copy catalogs or +credentials, and does not start extra processes to prepare them. Codex validates +catalog contents during its normal startup and reports invalid files itself. +Use a complete catalog appropriate for the current provider/account and update +it when availability changes; a static catalog bypasses native discovery. + +Paths support macOS, Linux and Windows, including spaces. Restart the runner +after changing its environment; existing servers use the new setting after +they are safely stopped and resumed. Inference traffic is unaffected. + ### Codex MCP servers Codex sessions keep the MCP servers configured in the user's Codex diff --git a/cli/src/codex/codexAppServerClient.test.ts b/cli/src/codex/codexAppServerClient.test.ts index e2f3488c..2fb08fbc 100644 --- a/cli/src/codex/codexAppServerClient.test.ts +++ b/cli/src/codex/codexAppServerClient.test.ts @@ -106,6 +106,22 @@ describe('CodexAppServerClient process cwd', () => { await client.disconnect(); }); + it('passes the explicit catalog to a single app-server without preparation processes', async () => { + const file = process.platform === 'win32' ? 'C:\\Models with spaces\\catalog.json' : '/Models with spaces/catalog.json'; + vi.stubEnv('HAPI_CODEX_MODEL_CATALOG_JSON', file); + const client = new CodexAppServerClient(); + try { + spawnMock.mockReturnValue(fakeChild()); + await client.connect(); + expect(spawnMock).toHaveBeenCalledTimes(1); + expect(spawnMock).toHaveBeenCalledWith('codex', ['app-server', '-c', `model_catalog_json=${JSON.stringify(file)}`], + expect.objectContaining({ shell: false })); + } finally { + await client.disconnect(); + vi.unstubAllEnvs(); + } + }); + it('steerTurn resolves dispatch on stdin accept and completes with the turn response', async () => { const child = fakeChild(); child.stdin.write = vi.fn((_data: unknown, cb?: (error?: Error | null) => void) => { diff --git a/cli/src/codex/codexAppServerClient.ts b/cli/src/codex/codexAppServerClient.ts index 21e5cb8a..06a75415 100644 --- a/cli/src/codex/codexAppServerClient.ts +++ b/cli/src/codex/codexAppServerClient.ts @@ -5,6 +5,8 @@ import { logger } from '@/ui/logger'; import { JsonLineParser } from '@/utils/jsonLineParser'; import { killProcessByChildProcess } from '@/utils/process'; import { CODEX_WEBSOCKET_MAX_PAYLOAD } from './websocketLimits'; +import { resolveModelCatalogArgs } from './utils/modelCatalog'; +import { resolveSelectedCodexCommand } from './utils/codexExecutable'; import type { CollaborationModeListResponse, InitializeParams, @@ -255,9 +257,10 @@ export class CodexAppServerClient extends JsonLineParser { return; } - const codexCommand = resolveCodexAppServerCommand(); - logger.debug(`[CodexAppServer] Starting ${codexCommand} app-server`); - const child = spawn(codexCommand, ['app-server'], { + const codexCommand = resolveSelectedCodexCommand(resolveCodexAppServerCommand()); + logger.debug(`[CodexAppServer] Starting ${codexCommand.command} app-server`); + const catalogArgs = resolveModelCatalogArgs(); + const child = spawn(codexCommand.command, [...codexCommand.args, 'app-server', ...catalogArgs], { cwd: this.options.cwd, env: Object.keys(process.env).reduce((acc, key) => { const value = process.env[key]; @@ -265,7 +268,7 @@ export class CodexAppServerClient extends JsonLineParser { return acc; }, {} as Record), stdio: ['pipe', 'pipe', 'pipe'], - shell: process.platform === 'win32', + shell: false, windowsHide: process.platform === 'win32' }); this.process = child; diff --git a/cli/src/codex/shared/launch.ts b/cli/src/codex/shared/launch.ts index 74cda49c..4fe07490 100644 --- a/cli/src/codex/shared/launch.ts +++ b/cli/src/codex/shared/launch.ts @@ -4,6 +4,7 @@ import { z } from 'zod'; import { resolveCodexCommand, type CodexCommand } from '../utils/codexExecutable'; import { parseCodexCliOverrides, stripCodexCliOverrides } from '../utils/codexCliOverrides'; import { resolveCodexPermissionModeConfig } from '../utils/permissionModeConfig'; +import { resolveModelCatalogArgs } from '../utils/modelCatalog'; import { getCodexSystemPrompt } from '../utils/systemPrompt'; import type { CodexAppServerClient } from '../codexAppServerClient'; @@ -136,6 +137,7 @@ export function sharedLaunchConfig(options: SharedLaunchOptions, cwd: string): { // Launch-wide flags also apply to later native /new roots, not just the // initial HAPI-created root. Explicit config layers keep their order. for (const [key, value] of Object.entries(config)) serverArgs.push('-c', `${key}=${JSON.stringify(value)}`); + serverArgs.push(...resolveModelCatalogArgs(serverArgs)); return { cwd: directory, serverArgs, tuiArgs, threadParams: { diff --git a/cli/src/codex/utils/codexExecutable.test.ts b/cli/src/codex/utils/codexExecutable.test.ts index 03de6c92..8e822f57 100644 --- a/cli/src/codex/utils/codexExecutable.test.ts +++ b/cli/src/codex/utils/codexExecutable.test.ts @@ -93,6 +93,39 @@ describe('resolveCodexCommand', () => { } }); + it('resolves an explicitly selected Windows npm shim without a shell', async () => { + const shim = 'C:\\Users\\Test User\\AppData\\Roaming\\npm\\codex.cmd'; + const script = win32.join(win32.dirname(shim), 'node_modules', '@openai', 'codex', 'bin', 'codex.js'); + existsSyncMock.mockImplementation((candidate: string) => candidate === shim || candidate === script); + const { resolveSelectedCodexCommand } = await import('./codexExecutable'); + expect(resolveSelectedCodexCommand(shim, 'win32')).toEqual({ command: 'node', args: [script] }); + }); + + it('resolves an explicitly selected npm shim name through PATH', async () => { + const shim = 'C:\\Elsewhere\\npm\\codex.cmd'; + const script = win32.join(win32.dirname(shim), 'node_modules', '@openai', 'codex', 'bin', 'codex.js'); + execFileSyncMock.mockImplementation((command: string, args: string[]) => { + if (command === 'where.exe' && args[0] === 'codex.cmd') return `${shim}\r\n`; + throw new Error('not found'); + }); + existsSyncMock.mockImplementation((candidate: string) => candidate === shim || candidate === script); + const { resolveSelectedCodexCommand } = await import('./codexExecutable'); + expect(resolveSelectedCodexCommand('codex.cmd', 'win32')).toEqual({ command: 'node', args: [script] }); + expect(execFileSyncMock).toHaveBeenCalledWith('where.exe', ['codex.cmd'], expect.anything()); + }); + + it('rejects unsupported Windows batch launchers instead of shell-interpreting JSON', async () => { + const { resolveSelectedCodexCommand } = await import('./codexExecutable'); + expect(() => resolveSelectedCodexCommand('C:\\custom.cmd', 'win32')).toThrow('Use a Codex executable'); + }); + + it('preserves explicitly selected macOS and Linux executables', async () => { + const { resolveSelectedCodexCommand } = await import('./codexExecutable'); + for (const platform of ['darwin', 'linux'] as const) { + expect(resolveSelectedCodexCommand('/custom path/codex', platform)).toEqual({ command: '/custom path/codex', args: [] }); + } + }); + it('resolves a Windows npm codex.cmd shim through the Codex launcher', async () => { setPlatform('win32'); const shim = codexShimPath(); diff --git a/cli/src/codex/utils/codexExecutable.ts b/cli/src/codex/utils/codexExecutable.ts index 5299ad5e..640f3406 100644 --- a/cli/src/codex/utils/codexExecutable.ts +++ b/cli/src/codex/utils/codexExecutable.ts @@ -68,6 +68,21 @@ function resolveWindowsCodexCommand(): CodexCommand { return { command: 'codex', args: [] }; } +/** Resolve a selected app-server executable without passing JSON overrides through cmd.exe. */ +export function resolveSelectedCodexCommand(command: string, platform: NodeJS.Platform = process.platform): CodexCommand { + if (platform !== 'win32') return { command, args: [] }; + if (command === 'codex') return resolveWindowsCodexCommand(); + const candidates = windowsPath.basename(command) === command ? findWhereResults(command) : []; + for (const candidate of [...candidates, command]) { + const resolved = resolveWindowsCandidate(candidate); + if (resolved) return resolved; + } + if (/\.(cmd|bat)$/i.test(command)) { + throw new Error('Use a Codex executable or an npm Codex shim with its launcher script on Windows.'); + } + return { command, args: [] }; +} + export const MACOS_CODEX_APP_COMMAND = '/Applications/Codex.app/Contents/Resources/codex'; export function resolveCodexCommand( diff --git a/cli/src/codex/utils/modelCatalog.integration.test.ts b/cli/src/codex/utils/modelCatalog.integration.test.ts new file mode 100644 index 00000000..93d24882 --- /dev/null +++ b/cli/src/codex/utils/modelCatalog.integration.test.ts @@ -0,0 +1,81 @@ +import { spawn } from 'node:child_process'; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { createInterface } from 'node:readline'; +import { describe, expect, it, vi } from 'vitest'; +import { CodexAppServerClient } from '../codexAppServerClient'; +import { sharedLaunchConfig } from '../shared/launch'; + +// Opt-in native check; no credentials, inference calls, or production config changes. +const executable = process.env.HAPI_TEST_CODEX_BIN; +const fixture = process.env.HAPI_TEST_CODEX_CATALOG; +describe.skipIf(!executable || !fixture)('local model catalog with native Codex', () => { + it.each(['standalone', 'shared-resume', 'configured-standalone'])('loads the configured catalog offline for %s', async mode => { + const home = mkdtempSync(join(tmpdir(), 'hapi-catalog-native-')); + const catalog = JSON.parse(readFileSync(fixture!, 'utf8')); + catalog.models[0].display_name = 'HAPI local catalog probe'; + const path = join(home, 'models_cache.json'); + writeFileSync(path, JSON.stringify(catalog)); + vi.stubEnv('CODEX_HOME', home); + vi.stubEnv('HAPI_CODEX_MODEL_CATALOG_JSON', mode === 'configured-standalone' ? '' : path); + if (mode === 'configured-standalone') writeFileSync(join(home, 'config.toml'), `model_catalog_json=${JSON.stringify(path)}\n`); + vi.stubEnv('HAPI_CODEX_APP_SERVER_BIN', executable!); + for (const name of ['HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'http_proxy', 'https_proxy', 'all_proxy']) { + vi.stubEnv(name, 'http://127.0.0.1:9'); + } + vi.stubEnv('NO_PROXY', ''); + vi.stubEnv('no_proxy', ''); + try { + let models: Array<{ displayName?: string }>; + if (mode !== 'shared-resume') { + const client = new CodexAppServerClient({ cwd: home }); + try { + await client.connect(); + await client.initialize({ clientInfo: { name: 'hapi-catalog-test', version: '1' }, capabilities: null }); + models = (await client.listModels()).data ?? []; + } finally { + await client.disconnect(); + } + } else { + const launch = sharedLaunchConfig({ resumeSessionId: 'existing-thread' }, home); + const child = spawn(executable!, ['app-server', ...launch.serverArgs], { + cwd: home, env: process.env, stdio: ['pipe', 'pipe', 'pipe'] + }); + const lines = createInterface({ input: child.stdout }); + try { + models = await new Promise>((resolve, reject) => { + const timer = setTimeout(() => reject(new Error('Native catalog probe timed out')), 10_000); + const finish = () => clearTimeout(timer); + child.once('error', error => { finish(); reject(error); }); + child.once('exit', () => { finish(); reject(new Error('Native Codex exited before model/list')); }); + lines.on('line', line => { + const response = JSON.parse(line); + if (response.error) { finish(); reject(new Error(JSON.stringify(response.error))); return; } + if (response.id === 1) { + child.stdin.write(JSON.stringify({ method: 'initialized' }) + '\n'); + child.stdin.write(JSON.stringify({ id: 2, method: 'model/list', params: {} }) + '\n'); + } else if (response.id === 2) { + finish(); resolve(response.result.data); + } + }); + child.stdin.write(JSON.stringify({ id: 1, method: 'initialize', params: { + clientInfo: { name: 'hapi-catalog-test', version: '1' } + } }) + '\n'); + }); + } finally { + lines.close(); + child.kill(); + await new Promise(resolve => { + if (child.exitCode !== null || child.signalCode !== null) resolve(); + else child.once('exit', () => resolve()); + }); + } + } + expect(models).toContainEqual(expect.objectContaining({ displayName: 'HAPI local catalog probe' })); + } finally { + vi.unstubAllEnvs(); + rmSync(home, { recursive: true, force: true }); + } + }, 20_000); +}); diff --git a/cli/src/codex/utils/modelCatalog.test.ts b/cli/src/codex/utils/modelCatalog.test.ts new file mode 100644 index 00000000..251cd3ea --- /dev/null +++ b/cli/src/codex/utils/modelCatalog.test.ts @@ -0,0 +1,52 @@ +import { afterEach, describe, expect, it, vi } from 'vitest'; +import { resolveModelCatalogArgs } from './modelCatalog'; +import { sharedLaunchConfig } from '../shared/launch'; + +afterEach(() => vi.unstubAllEnvs()); + +describe('explicit Codex model catalog configuration', () => { + it.each([undefined, '', ' '])('leaves native configuration intact when unset (%s)', value => { + expect(resolveModelCatalogArgs([], { HAPI_CODEX_MODEL_CATALOG_JSON: value })).toEqual([]); + }); + it.each([ + ['linux', '/home/alice', '/catalogs/models with spaces.json', '/catalogs/models with spaces.json'], + ['darwin', '/Users/alice', '~/Models/catalog.json', '/Users/alice/Models/catalog.json'], + ['win32', 'C:\\Users\\Alice', 'D:\\Model Data\\catalog.json', 'D:\\Model Data\\catalog.json'], + ['win32', 'C:\\Users\\Alice', '~\\Models\\catalog.json', 'C:\\Users\\Alice\\Models\\catalog.json'], + ['win32', 'C:\\Users\\Alice', '\\\\server\\share\\catalog.json', '\\\\server\\share\\catalog.json'] + ] as const)('serializes a single TOML argument on %s', (platform, home, file, expected) => { + expect(resolveModelCatalogArgs([], { HAPI_CODEX_MODEL_CATALOG_JSON: file }, home, platform)) + .toEqual(['-c', `model_catalog_json=${JSON.stringify(expected)}`]); + }); + it('passes through the path without reading or validating a catalog', () => { + expect(resolveModelCatalogArgs([], { HAPI_CODEX_MODEL_CATALOG_JSON: '/not-created/catalog.json' }, '/home/alice', 'linux')) + .toEqual(['-c', 'model_catalog_json="/not-created/catalog.json"']); + }); + it('rejects relative paths so runner and session working directories cannot change their meaning', () => { + expect(() => resolveModelCatalogArgs([], { HAPI_CODEX_MODEL_CATALOG_JSON: 'catalog.json' })).toThrow('absolute path'); + }); + it.each(['-c', '--config'])('preserves an explicit %s launch override', flag => { + expect(resolveModelCatalogArgs([flag, 'model_catalog_json="explicit.json"'], { + HAPI_CODEX_MODEL_CATALOG_JSON: 'ignored-relative-path' + })).toEqual([]); + }); + it('does not treat another setting value as a catalog override', () => { + expect(resolveModelCatalogArgs(['-c', 'model="model_catalog_json"'], { + HAPI_CODEX_MODEL_CATALOG_JSON: '/catalog.json' + }, '/home/alice', 'linux')).toHaveLength(2); + }); + it('applies the setting to new and resumed shared launch configurations', () => { + const file = process.platform === 'win32' ? 'C:\\Models\\catalog.json' : '/Models/catalog.json'; + vi.stubEnv('HAPI_CODEX_MODEL_CATALOG_JSON', file); + for (const options of [{}, { resumeSessionId: 'existing-thread' }]) { + const launch = sharedLaunchConfig(options, process.cwd()); + expect(launch.serverArgs).toContain(`model_catalog_json=${JSON.stringify(file)}`); + expect(launch.tuiArgs).not.toContain(`model_catalog_json=${JSON.stringify(file)}`); + } + }); + it('normalizes and preserves an inline shared launch override', () => { + vi.stubEnv('HAPI_CODEX_MODEL_CATALOG_JSON', '/ignored.json'); + const launch = sharedLaunchConfig({ codexArgs: ['--config=model_catalog_json="explicit.json"'] }, process.cwd()); + expect(launch.serverArgs).toEqual(['--config', 'model_catalog_json="explicit.json"']); + }); +}); diff --git a/cli/src/codex/utils/modelCatalog.ts b/cli/src/codex/utils/modelCatalog.ts new file mode 100644 index 00000000..bf34fd9a --- /dev/null +++ b/cli/src/codex/utils/modelCatalog.ts @@ -0,0 +1,24 @@ +import { homedir } from 'node:os'; +import path from 'node:path'; + +const CATALOG_KEY = /^\s*(?:model_catalog_json|"model_catalog_json"|'model_catalog_json')\s*=/; + +/** Pass an explicit HAPI setting to Codex. Catalog contents and lifecycle belong to Codex. */ +export function resolveModelCatalogArgs( + args: string[] = [], + env: NodeJS.ProcessEnv = process.env, + userHome = homedir(), + platform: NodeJS.Platform = process.platform +): string[] { + // Shared launch flags are normalized before this helper runs. + if (args.some((arg, index) => (arg === '-c' || arg === '--config') && CATALOG_KEY.test(args[index + 1] ?? ''))) return []; + const configured = env.HAPI_CODEX_MODEL_CATALOG_JSON; + if (!configured?.trim()) return []; + const paths = platform === 'win32' ? path.win32 : path.posix; + const file = configured.startsWith('~/') || configured.startsWith('~\\') + ? paths.join(userHome, configured.slice(2)) : configured; + if (!paths.isAbsolute(file)) { + throw new Error('HAPI_CODEX_MODEL_CATALOG_JSON must be an absolute path (or start with ~/).'); + } + return ['-c', `model_catalog_json=${JSON.stringify(file)}`]; +} diff --git a/cli/src/modules/common/codexModels.test.ts b/cli/src/modules/common/codexModels.test.ts index ebfb8376..4b618dd3 100644 --- a/cli/src/modules/common/codexModels.test.ts +++ b/cli/src/modules/common/codexModels.test.ts @@ -146,6 +146,30 @@ describe('listCodexModels cwd', () => { expect(constructorOptions).toHaveLength(4); }); + it('invalidates the environment-selected catalog and honors its precedence over config.toml', async () => { + const home = await mkdtemp(join(tmpdir(), 'hapi-codex-env-models-')); + temporaryHomes.push(home); + vi.stubEnv('CODEX_HOME', home); + const configured = join(home, 'configured.json'); + const selected = join(home, 'selected.json'); + await writeFile(join(home, 'config.toml'), `model_catalog_json = ${JSON.stringify(configured)}\n`); + await writeFile(configured, 'configured'); + await writeFile(selected, 'first'); + vi.stubEnv('HAPI_CODEX_MODEL_CATALOG_JSON', selected); + listModelsMock.mockResolvedValue({ data: [{ id: 'first' }] }); + await listCodexModels(); + await writeFile(configured, 'unused-change'); + await listCodexModels(); + expect(constructorOptions).toHaveLength(1); + await writeFile(selected, 'second'); + listModelsMock.mockResolvedValue({ data: [{ id: 'second' }] }); + expect((await listCodexModels())[0]?.id).toBe('second'); + expect(constructorOptions).toHaveLength(2); + vi.stubEnv('HAPI_CODEX_MODEL_CATALOG_JSON', ''); + await listCodexModels(); + expect(constructorOptions).toHaveLength(3); + }); + it('resolves a relative catalog path from the Codex config directory', async () => { const home = await mkdtemp(join(tmpdir(), 'hapi-codex-models-')); temporaryHomes.push(home); diff --git a/cli/src/modules/common/codexModels.ts b/cli/src/modules/common/codexModels.ts index 30a4cdee..4750b3cd 100644 --- a/cli/src/modules/common/codexModels.ts +++ b/cli/src/modules/common/codexModels.ts @@ -4,6 +4,7 @@ import { readFile } from 'node:fs/promises'; import { join, resolve } from 'node:path'; import type { CodexModelsResponse, CodexModelSummary } from '@hapi/protocol/apiTypes'; import { CodexAppServerClient } from '@/codex/codexAppServerClient'; +import { resolveModelCatalogArgs } from '@/codex/utils/modelCatalog'; import { resolveCodexHome } from '@/codex/utils/codexHome'; import { getErrorMessage } from './rpcResponses'; @@ -114,7 +115,10 @@ async function catalogFingerprint(): Promise { const rootConfig = config?.toString('utf8').split(/^\s*\[/m, 1)[0] ?? ''; const rawPath = rootConfig.match(/^\s*model_catalog_json\s*=\s*("(?:[^"\\]|\\.)*"|'[^']*')/m)?.[1]; let catalogPath: string | undefined; - if (rawPath) { + const override = resolveModelCatalogArgs(); + if (override.length) { + catalogPath = JSON.parse(override[1].slice('model_catalog_json='.length)) as string; + } else if (rawPath) { catalogPath = rawPath.startsWith('"') ? JSON.parse(rawPath) as string : rawPath.slice(1, -1); } const catalog = catalogPath ? await readOptionalFile(resolve(home, catalogPath)) : null;