From 51ed21a11597f7cf1c369b3e795861b98936b75f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Sun, 19 Jul 2026 02:15:40 -0400 Subject: [PATCH] feat: add native Codex hook integration --- README.md | 3 + src/cli.ts | 2 + src/plugins/codex.ts | 204 ++++++++++++++++++++++++++++++++ src/plugins/registry.ts | 1 + test/codex-plugin.test.mjs | 236 +++++++++++++++++++++++++++++++++++++ 5 files changed, 446 insertions(+) create mode 100644 src/plugins/codex.ts create mode 100644 test/codex-plugin.test.mjs diff --git a/README.md b/README.md index e9c3e7f..c0adc9f 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ npx elydora install \ | Agent | Key | |-------|-----| | Claude Code | `claudecode` | +| OpenAI Codex | `codex` | | Cursor | `cursor` | | Gemini CLI | `gemini` | | Kiro CLI | `kirocli` | @@ -74,6 +75,8 @@ npx elydora install \ | Copilot CLI | `copilot` | | Letta Code | `letta` | +Codex performs a one-time trust review for user hooks. Run `/hooks` in Codex after installation and trust the Elydora `PreToolUse` and `PostToolUse` definitions. + ## API Reference ### Configuration diff --git a/src/cli.ts b/src/cli.ts index 25719b1..f8abb58 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -14,6 +14,7 @@ import { kiroidePlugin } from './plugins/kiroide.js'; import { opencodePlugin } from './plugins/opencode.js'; import { copilotPlugin } from './plugins/copilot.js'; import { lettaPlugin } from './plugins/letta.js'; +import { codexPlugin } from './plugins/codex.js'; const ELYDORA_DIR = path.join(os.homedir(), '.elydora'); @@ -26,6 +27,7 @@ const PLUGINS: ReadonlyMap = new Map([ ['opencode', opencodePlugin], ['copilot', copilotPlugin], ['letta', lettaPlugin], + ['codex', codexPlugin], ]); // --------------------------------------------------------------------------- diff --git a/src/plugins/codex.ts b/src/plugins/codex.ts new file mode 100644 index 0000000..04348c3 --- /dev/null +++ b/src/plugins/codex.ts @@ -0,0 +1,204 @@ +import fsp from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; +import type { AgentPlugin, InstallConfig, PluginStatus } from './base.js'; +import { SUPPORTED_AGENTS } from './registry.js'; + +const AGENT_KEY = 'codex'; +const GUARD_STATUS = 'Checking Elydora agent state'; +const AUDIT_STATUS = 'Recording Elydora tool use'; +const entry = SUPPORTED_AGENTS.get(AGENT_KEY)!; + +type JsonObject = Record; + +function isObject(value: unknown): value is JsonObject { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +function resolveConfigPath(): string { + const configDir = entry.configDir.replace(/^~/, os.homedir()); + return path.join(configDir, entry.configFile); +} + +function quotePosix(value: string): string { + return `'${value.replaceAll("'", `'"'"'`)}'`; +} + +function quoteWindows(value: string): string { + return `"${value.replaceAll('"', '\\"')}"`; +} + +function buildHandler(scriptPath: string, statusMessage: string): JsonObject { + return { + type: 'command', + command: `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`, + commandWindows: `${quoteWindows(process.execPath)} ${quoteWindows(scriptPath)}`, + timeout: 10, + statusMessage, + }; +} + +function eventGroups(hooks: JsonObject, event: string): JsonObject[] { + const value = hooks[event]; + if (value === undefined) return []; + if (!Array.isArray(value) || !value.every(isObject)) { + throw new Error(`Codex hooks config field "hooks.${event}" must be an array of objects`); + } + return value; +} + +function isElydoraHandler(handler: JsonObject, agentId?: string): boolean { + if (handler.statusMessage !== GUARD_STATUS && handler.statusMessage !== AUDIT_STATUS) return false; + if (!agentId) return true; + return [handler.command, handler.commandWindows].some( + (command) => typeof command === 'string' && command.includes(agentId), + ); +} + +function withoutElydora(groups: JsonObject[], agentId?: string): JsonObject[] { + const result: JsonObject[] = []; + for (const group of groups) { + if (!Array.isArray(group.hooks) || !group.hooks.every(isObject)) { + throw new Error('Codex hook matcher group must contain a hooks array'); + } + const handlers = group.hooks.filter((handler) => !isElydoraHandler(handler, agentId)); + if (handlers.length > 0) result.push({ ...group, hooks: handlers }); + } + return result; +} + +function findHandler(groups: JsonObject[], statusMessage: string): JsonObject | undefined { + for (const group of groups) { + if (!Array.isArray(group.hooks)) continue; + const handler = group.hooks.find( + (candidate) => isObject(candidate) && candidate.statusMessage === statusMessage, + ); + if (isObject(handler)) return handler; + } + return undefined; +} + +function commandReferences(handler: JsonObject, scriptPath: string): boolean { + return [handler.command, handler.commandWindows].some( + (command) => typeof command === 'string' && command.includes(scriptPath), + ); +} + +async function readSettings(configPath: string): Promise { + let raw: string; + try { + raw = await fsp.readFile(configPath, 'utf-8'); + } catch (error) { + if (isObject(error) && error.code === 'ENOENT') return undefined; + throw new Error(`Read Codex hooks config: ${error instanceof Error ? error.message : String(error)}`); + } + + let value: unknown; + try { + value = JSON.parse(raw); + } catch (error) { + throw new Error(`Failed to parse Codex hooks config: ${error instanceof Error ? error.message : String(error)}`); + } + if (!isObject(value)) throw new Error('Codex hooks config must contain a JSON object'); + return value; +} + +async function writeSettings(configPath: string, settings: JsonObject): Promise { + await fsp.mkdir(path.dirname(configPath), { recursive: true }); + const tempPath = `${configPath}.${process.pid}.${Date.now()}.tmp`; + try { + await fsp.writeFile(tempPath, JSON.stringify(settings, null, 2) + '\n', { + encoding: 'utf-8', + mode: 0o600, + }); + await fsp.rename(tempPath, configPath); + } catch (error) { + await fsp.unlink(tempPath).catch(() => undefined); + throw new Error(`Write Codex hooks config: ${error instanceof Error ? error.message : String(error)}`); + } +} + +function getHooks(settings: JsonObject): JsonObject { + if (settings.hooks === undefined) return {}; + if (!isObject(settings.hooks)) throw new Error('Codex hooks config field "hooks" must be an object'); + return { ...settings.hooks }; +} + +async function runtimeScriptsExist(guard: JsonObject, audit: JsonObject): Promise { + const root = path.join(os.homedir(), '.elydora'); + let entries; + try { + entries = await fsp.readdir(root, { withFileTypes: true }); + } catch { + return false; + } + + for (const directory of entries) { + if (!directory.isDirectory()) continue; + const agentDir = path.join(root, directory.name); + try { + const config = JSON.parse(await fsp.readFile(path.join(agentDir, 'config.json'), 'utf-8')); + if (config.agent_name !== AGENT_KEY) continue; + const guardPath = path.join(agentDir, 'guard.js'); + const hookPath = path.join(agentDir, 'hook.js'); + if (!commandReferences(guard, guardPath) || !commandReferences(audit, hookPath)) continue; + await Promise.all([fsp.access(guardPath), fsp.access(hookPath)]); + return true; + } catch { + continue; + } + } + return false; +} + +export const codexPlugin: AgentPlugin = { + async install(config: InstallConfig): Promise { + const configPath = resolveConfigPath(); + const settings = (await readSettings(configPath)) ?? {}; + const hooks = getHooks(settings); + + hooks.PreToolUse = [ + ...withoutElydora(eventGroups(hooks, 'PreToolUse')), + { matcher: '*', hooks: [buildHandler(config.guardScriptPath, GUARD_STATUS)] }, + ]; + hooks.PostToolUse = [ + ...withoutElydora(eventGroups(hooks, 'PostToolUse')), + { matcher: '*', hooks: [buildHandler(config.hookScriptPath, AUDIT_STATUS)] }, + ]; + + await writeSettings(configPath, { ...settings, hooks }); + console.log(' Codex: run /hooks to review and trust the Elydora hooks.'); + }, + + async uninstall(agentId?: string): Promise { + const configPath = resolveConfigPath(); + const settings = await readSettings(configPath); + if (!settings) return; + const hooks = getHooks(settings); + hooks.PreToolUse = withoutElydora(eventGroups(hooks, 'PreToolUse'), agentId); + hooks.PostToolUse = withoutElydora(eventGroups(hooks, 'PostToolUse'), agentId); + await writeSettings(configPath, { ...settings, hooks }); + }, + + async status(): Promise { + const configPath = resolveConfigPath(); + const settings = await readSettings(configPath); + let guard: JsonObject | undefined; + let audit: JsonObject | undefined; + if (settings) { + const hooks = getHooks(settings); + guard = findHandler(eventGroups(hooks, 'PreToolUse'), GUARD_STATUS); + audit = findHandler(eventGroups(hooks, 'PostToolUse'), AUDIT_STATUS); + } + const hookConfigured = Boolean(guard && audit); + const hookScriptExists = guard && audit ? await runtimeScriptsExist(guard, audit) : false; + return { + installed: hookConfigured && hookScriptExists, + agentName: AGENT_KEY, + displayName: entry.name, + hookConfigured, + hookScriptExists, + configPath, + }; + }, +}; diff --git a/src/plugins/registry.ts b/src/plugins/registry.ts index 26cc996..428c243 100644 --- a/src/plugins/registry.ts +++ b/src/plugins/registry.ts @@ -13,4 +13,5 @@ export const SUPPORTED_AGENTS: ReadonlyMap = new Map ['opencode', { name: 'OpenCode', configDir: '.config/opencode/plugins', configFile: 'elydora-audit.mjs' }], ['copilot', { name: 'Copilot CLI', configDir: '.github/hooks', configFile: 'hooks.json' }], ['letta', { name: 'Letta Code', configDir: '~/.letta', configFile: 'settings.json' }], + ['codex', { name: 'OpenAI Codex', configDir: '~/.codex', configFile: 'hooks.json' }], ]); diff --git a/test/codex-plugin.test.mjs b/test/codex-plugin.test.mjs new file mode 100644 index 0000000..f932af8 --- /dev/null +++ b/test/codex-plugin.test.mjs @@ -0,0 +1,236 @@ +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; +import test from 'node:test'; +import { pathToFileURL } from 'node:url'; + +const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/codex.js')).href; +const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href; + +function runNode(args, env, input = '') { + return new Promise((resolve, reject) => { + const child = spawn(process.execPath, args, { + env: { ...process.env, ...env }, + stdio: ['pipe', 'pipe', 'pipe'], + }); + let stdout = ''; + let stderr = ''; + child.stdout.on('data', (chunk) => { stdout += chunk; }); + child.stderr.on('data', (chunk) => { stderr += chunk; }); + child.once('error', reject); + child.once('close', (code) => resolve({ code, stdout, stderr })); + child.stdin.end(input); + }); +} + +function runCommand(command, input = '') { + return new Promise((resolve, reject) => { + const child = spawn(command, { + shell: true, + stdio: ['pipe', 'pipe', 'pipe'], + }); + let stdout = ''; + let stderr = ''; + child.stdout.on('data', (chunk) => { stdout += chunk; }); + child.stderr.on('data', (chunk) => { stderr += chunk; }); + child.once('error', reject); + child.once('close', (code) => resolve({ code, stdout, stderr })); + child.stdin.end(input); + }); +} + +function findHandler(settings, event, statusMessage) { + for (const group of settings.hooks?.[event] ?? []) { + const handler = group.hooks?.find((item) => item.statusMessage === statusMessage); + if (handler) return handler; + } + return undefined; +} + +async function runPlugin(homeDir, method, argument) { + const script = ` + import { codexPlugin } from ${JSON.stringify(pluginModuleUrl)}; + const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT); + const result = await codexPlugin[process.env.ELYDORA_TEST_METHOD](argument); + if (result !== undefined) console.log(JSON.stringify(result)); + `; + return runNode( + ['--input-type=module', '--eval', script], + { + HOME: homeDir, + USERPROFILE: homeDir, + ELYDORA_TEST_ARGUMENT: JSON.stringify(argument), + ELYDORA_TEST_METHOD: method, + }, + ); +} + +async function createFixture({ guardSource, hookSource, existingSettings } = {}) { + const homeDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-codex-')); + const agentDir = path.join(homeDir, '.elydora', 'agent-1'); + const configDir = path.join(homeDir, '.codex'); + await mkdir(agentDir, { recursive: true }); + await mkdir(configDir, { recursive: true }); + + const guardScriptPath = path.join(agentDir, 'guard.js'); + const hookScriptPath = path.join(agentDir, 'hook.js'); + await writeFile( + guardScriptPath, + guardSource ?? "process.stderr.write('Agent is frozen by Elydora.'); process.exit(2);\n", + ); + await writeFile(hookScriptPath, hookSource ?? 'process.exit(0);\n'); + await writeFile(path.join(agentDir, 'config.json'), JSON.stringify({ + agent_id: 'agent-1', + agent_name: 'codex', + })); + + const configPath = path.join(configDir, 'hooks.json'); + if (existingSettings !== undefined) { + await writeFile(configPath, typeof existingSettings === 'string' + ? existingSettings + : JSON.stringify(existingSettings, null, 2)); + } + + const installResult = await runPlugin(homeDir, 'install', { + agentName: 'codex', + agentId: 'agent-1', + baseUrl: 'https://api.elydora.com', + guardScriptPath, + hookScriptPath, + }); + + return { + agentDir, + configPath, + guardScriptPath, + homeDir, + hookScriptPath, + installResult, + async close() { + await rm(homeDir, { recursive: true, force: true }); + }, + }; +} + +test('Codex is registered as a native hook integration', async () => { + const { SUPPORTED_AGENTS } = await import(registryModuleUrl); + assert.deepEqual(SUPPORTED_AGENTS.get('codex'), { + name: 'OpenAI Codex', + configDir: '~/.codex', + configFile: 'hooks.json', + }); +}); + +test('Codex install preserves existing hooks and is idempotent', async () => { + const existing = { + description: 'Workspace hooks', + hooks: { + SessionStart: [{ hooks: [{ type: 'command', command: 'existing-command' }] }], + }, + }; + const fixture = await createFixture({ existingSettings: existing }); + try { + assert.equal(fixture.installResult.code, 0, fixture.installResult.stderr); + assert.match(fixture.installResult.stdout, /run \/hooks to review and trust/i); + const secondInstall = await runPlugin(fixture.homeDir, 'install', { + agentName: 'codex', + agentId: 'agent-1', + baseUrl: 'https://api.elydora.com', + guardScriptPath: fixture.guardScriptPath, + hookScriptPath: fixture.hookScriptPath, + }); + assert.equal(secondInstall.code, 0, secondInstall.stderr); + + const settings = JSON.parse(await readFile(fixture.configPath, 'utf-8')); + assert.equal(settings.description, 'Workspace hooks'); + assert.equal(settings.hooks.SessionStart[0].hooks[0].command, 'existing-command'); + assert.equal(settings.hooks.PreToolUse.length, 1); + assert.equal(settings.hooks.PostToolUse.length, 1); + assert.equal(settings.hooks.PreToolUse[0].matcher, '*'); + assert.equal(settings.hooks.PostToolUse[0].matcher, '*'); + } finally { + await fixture.close(); + } +}); + +test('Codex hook commands enforce freezes and forward the official event payload', async () => { + const capturePath = path.join(os.tmpdir(), `elydora-codex-event-${process.pid}-${Date.now()}.json`); + const hookSource = ` + const fs = require('node:fs'); + const chunks = []; + process.stdin.on('data', (chunk) => chunks.push(chunk)); + process.stdin.on('end', () => fs.writeFileSync(${JSON.stringify(capturePath)}, Buffer.concat(chunks))); + `; + const fixture = await createFixture({ hookSource }); + try { + assert.equal(fixture.installResult.code, 0, fixture.installResult.stderr); + const settings = JSON.parse(await readFile(fixture.configPath, 'utf-8')); + const guard = findHandler(settings, 'PreToolUse', 'Checking Elydora agent state'); + const audit = findHandler(settings, 'PostToolUse', 'Recording Elydora tool use'); + assert(guard); + assert(audit); + + const commandKey = process.platform === 'win32' ? 'commandWindows' : 'command'; + const guardResult = await runCommand(guard[commandKey], JSON.stringify({ + hook_event_name: 'PreToolUse', + session_id: 'session-1', + tool_name: 'Bash', + tool_input: { command: 'echo test' }, + })); + assert.equal(guardResult.code, 2); + assert.match(guardResult.stderr, /Agent is frozen by Elydora/); + + const payload = { + hook_event_name: 'PostToolUse', + session_id: 'session-1', + tool_name: 'Bash', + tool_use_id: 'call-1', + tool_input: { command: 'echo test' }, + tool_response: { output: 'test' }, + }; + const auditResult = await runCommand(audit[commandKey], JSON.stringify(payload)); + assert.equal(auditResult.code, 0, auditResult.stderr); + assert.deepEqual(JSON.parse(await readFile(capturePath, 'utf-8')), payload); + } finally { + await fixture.close(); + await rm(capturePath, { force: true }); + } +}); + +test('Codex status requires both runtime scripts and uninstall preserves other hooks', async () => { + const fixture = await createFixture({ existingSettings: { + hooks: { PreToolUse: [{ hooks: [{ type: 'command', command: 'existing-command' }] }] }, + } }); + try { + assert.equal(fixture.installResult.code, 0, fixture.installResult.stderr); + const status = await runPlugin(fixture.homeDir, 'status', null); + assert.equal(status.code, 0, status.stderr); + assert.equal(JSON.parse(status.stdout).installed, true); + + await rm(fixture.guardScriptPath); + const degradedStatus = await runPlugin(fixture.homeDir, 'status', null); + assert.equal(JSON.parse(degradedStatus.stdout).installed, false); + + const uninstall = await runPlugin(fixture.homeDir, 'uninstall', 'agent-1'); + assert.equal(uninstall.code, 0, uninstall.stderr); + const settings = JSON.parse(await readFile(fixture.configPath, 'utf-8')); + assert.equal(settings.hooks.PreToolUse.length, 1); + assert.equal(settings.hooks.PreToolUse[0].hooks[0].command, 'existing-command'); + assert.deepEqual(settings.hooks.PostToolUse, []); + } finally { + await fixture.close(); + } +}); + +test('Codex install preserves malformed config for recovery', async () => { + const fixture = await createFixture({ existingSettings: '{ malformed' }); + try { + assert.equal(fixture.installResult.code, 1); + assert.match(fixture.installResult.stderr, /parse Codex hooks config/i); + assert.equal(await readFile(fixture.configPath, 'utf-8'), '{ malformed'); + } finally { + await fixture.close(); + } +});