@nocville/npc 0.0.0-stage → 0.2.1

package/dist/npcs/codex/defaults.js

@@ -0,0 +1,28 @@
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const CODEX_DEFAULTS = {
+    /** Hook-mode per-session state (shared with the watcher to avoid double pushes). */
+    stateDir: join(tmpdir(), 'nocville-codex'),
+    stateFileMaxAge: 24 * 60 * 60 * 1000,
+    /** Watchdog-backed sessions become unknown after three minutes without a heartbeat. */
+    heartbeatSeconds: 90,
+    minPushGapMs: 1500,
+    hookTimeoutSeconds: 10,
+    /** Watcher: Codex session rollout logs. */
+    sessionsDir: join(process.env['CODEX_HOME'] ?? join(homedir(), '.codex'), 'sessions'),
+    /** Watcher: poll interval for new sessions / appended lines. */
+    pollMs: 1000,
+    /**
+     * Watcher: a session whose rollout file hasn't grown for this long is treated
+     * as ended (offline push). Matches Codex's own 30-minute idle SessionEnd.
+     */
+    idleTimeoutMs: 30 * 60 * 1000,
+    /** Watcher: bytes read from the end of an already-active rollout on discovery. */
+    initialTailBytes: 256 * 1024,
+    /** Watcher: max bytes read per tick per session before skipping ahead to the tail. */
+    maxReadBytes: 8 * 1024 * 1024,
+};
+export function codexHome() {
+    return process.env['CODEX_HOME'] ?? join(homedir(), '.codex');
+}
+//# sourceMappingURL=defaults.js.map

package/dist/npcs/codex/hook-handler.d.ts

@@ -0,0 +1,24 @@
+import type { NpcConfig } from '../../core/types.js';
+import type { AgentHookEvent, AgentHookSpec, HookRunOptions } from '../agent-common/hook-runner.js';
+import type { AgentAdapter, AgentSessionState, AgentTransition } from '../agent-common/session.js';
+export declare const CODEX_ADAPTER: AgentAdapter;
+/**
+ * Codex session ids are UUIDv7 (time-ordered): the leading chars are shared by
+ * sessions started close together, so key the serviceId on the random tail.
+ */
+export declare function codexServiceId(sessionId: string, cwd: string): string;
+/**
+ * Map one Codex hook event to a phase + activity line. Events and payload
+ * fields per the Codex hooks reference (developers.openai.com/codex/hooks):
+ * SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse,
+ * PermissionRequest, Stop, Interrupt, PreCompact, PostCompact, SubagentStart,
+ * SubagentStop. Bash/apply_patch carry `tool_input.command`.
+ */
+export declare function codexTransition(event: AgentHookEvent, prev: AgentSessionState | null): AgentTransition;
+export declare const CODEX_HOOK_SPEC: AgentHookSpec;
+/**
+ * Handle a single Codex hook event (stdin JSON unless `rawInput` is given).
+ * In-process push by default; the CLI passes `mode: 'detach'`. Never throws.
+ */
+export declare function handleCodexHookEvent(config: NpcConfig, rawInput?: string, opts?: HookRunOptions): Promise<void>;
+//# sourceMappingURL=hook-handler.d.ts.map

package/dist/npcs/codex/hook-handler.js

@@ -0,0 +1,110 @@
+import { THINKING, describeToolUse, failureText, isQuestionTool, } from '../agent-common/activity.js';
+import { hookEventName, readStdin, runAgentHook } from '../agent-common/hook-runner.js';
+import { projectNameOf, sanitizeServiceId } from '../agent-common/session.js';
+import { CODEX_DEFAULTS } from './defaults.js';
+export const CODEX_ADAPTER = {
+    command: 'codex',
+    label: 'Codex',
+    family: 'codex',
+    stateDir: CODEX_DEFAULTS.stateDir,
+    heartbeatSeconds: CODEX_DEFAULTS.heartbeatSeconds,
+    processNames: ['codex'],
+};
+/**
+ * Codex session ids are UUIDv7 (time-ordered): the leading chars are shared by
+ * sessions started close together, so key the serviceId on the random tail.
+ */
+export function codexServiceId(sessionId, cwd) {
+    const hex = sessionId.replace(/[^A-Za-z0-9]/g, '');
+    return sanitizeServiceId(`codex-${projectNameOf(cwd)}-${hex.slice(-8) || 'session'}`);
+}
+const working = (activity, warn = false) => ({
+    state: 'WORKING',
+    activity,
+    status: warn ? 'warning' : 'healthy',
+    mood: warn ? 'concerned' : 'happy',
+});
+const waiting = (activity) => ({
+    state: 'WAITING',
+    activity,
+    status: 'warning',
+    mood: 'concerned',
+});
+const idle = (activity) => ({
+    state: 'IDLE',
+    activity,
+    status: 'healthy',
+    mood: 'idle',
+});
+/**
+ * Map one Codex hook event to a phase + activity line. Events and payload
+ * fields per the Codex hooks reference (developers.openai.com/codex/hooks):
+ * SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse,
+ * PermissionRequest, Stop, Interrupt, PreCompact, PostCompact, SubagentStart,
+ * SubagentStop. Bash/apply_patch carry `tool_input.command`.
+ */
+export function codexTransition(event, prev) {
+    const name = hookEventName(event);
+    const cwd = (typeof event.cwd === 'string' && event.cwd) || prev?.projectDir;
+    const keep = prev?.state ?? 'IDLE';
+    switch (name) {
+        case 'SessionStart':
+            return idle('Ready for a task');
+        case 'UserPromptSubmit':
+            return working(THINKING);
+        case 'PreToolUse': {
+            const activity = describeToolUse(event.tool_name, event.tool_input, cwd);
+            return isQuestionTool(event.tool_name) ? waiting(activity) : working(activity);
+        }
+        case 'PostToolUse':
+        case 'PostCompact':
+            return { ...working(undefined), quiet: prev?.state === 'WORKING' };
+        case 'PostToolUseFailure':
+            return working(failureText(event.tool_name), true);
+        case 'PermissionRequest': {
+            const what = event.tool_name ? describeToolUse(event.tool_name, event.tool_input, cwd) : '';
+            return waiting(what ? `Needs your approval: ${what}` : 'Needs your approval');
+        }
+        case 'Stop':
+            return idle('Done — waiting for next task');
+        case 'Interrupt':
+            return idle('Interrupted — waiting for you');
+        case 'PreCompact':
+            return working('Compacting context');
+        case 'SubagentStart':
+            return working('Delegating to a subagent');
+        case 'SubagentStop':
+            return working('Subagent finished');
+        case 'SessionEnd':
+            return {
+                state: 'IDLE',
+                activity: 'Session ended',
+                status: 'unknown',
+                mood: 'idle',
+                offline: true,
+            };
+        default:
+            return {
+                state: keep,
+                status: prev?.status ?? 'healthy',
+                mood: prev?.mood ?? 'idle',
+                quiet: true,
+            };
+    }
+}
+export const CODEX_HOOK_SPEC = {
+    adapter: CODEX_ADAPTER,
+    serviceIdFor: codexServiceId,
+    transition: codexTransition,
+};
+/**
+ * Handle a single Codex hook event (stdin JSON unless `rawInput` is given).
+ * In-process push by default; the CLI passes `mode: 'detach'`. Never throws.
+ */
+export async function handleCodexHookEvent(config, rawInput, opts = {}) {
+    await runAgentHook(CODEX_HOOK_SPEC, config, rawInput ?? readStdin(), {
+        minPushGapMs: CODEX_DEFAULTS.minPushGapMs,
+        ...opts,
+    });
+}
+//# sourceMappingURL=hook-handler.js.map

package/dist/npcs/codex/index.d.ts

@@ -0,0 +1,21 @@
+import type { NpcConfig } from '../../core/types.js';
+export { CODEX_DEFAULTS } from './defaults.js';
+export { CODEX_ADAPTER, codexTransition, codexServiceId, handleCodexHookEvent, } from './hook-handler.js';
+export { setupCodexHooks, uninstallCodexHooks, installCodexHooksInto, CODEX_HOOK_EVENTS, } from './setup.js';
+export type { CodexSetupOptions } from './setup.js';
+export { parseRolloutLine, describeExecScript } from './rollout.js';
+export type { RolloutSignal } from './rollout.js';
+export { CodexWatcher } from './watcher.js';
+export type { CodexWatcherOptions } from './watcher.js';
+export interface CodexSubcommandOptions {
+    subcommand: string;
+    config: NpcConfig;
+    flags: Record<string, string | boolean>;
+    args?: string[];
+}
+/**
+ * codex subcommands: setup | uninstall | hook | flush | watch | cleanup.
+ * `hook`/`flush` are invoked by Codex / ourselves and stay silent on stdout.
+ */
+export declare function handleCodexCommand(opts: CodexSubcommandOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/npcs/codex/index.js

@@ -0,0 +1,76 @@
+import { boolFlag, numberFlag, stringFlag } from '../../core/config.js';
+import { readStdin, runFlushCommand } from '../agent-common/hook-runner.js';
+import { runWatchdog } from '../agent-common/watchdog.js';
+import { cleanupSessionStates } from '../agent-common/session.js';
+import { CODEX_DEFAULTS } from './defaults.js';
+import { CODEX_ADAPTER, handleCodexHookEvent } from './hook-handler.js';
+import { setupCodexHooks, uninstallCodexHooks } from './setup.js';
+import { CodexWatcher } from './watcher.js';
+export { CODEX_DEFAULTS } from './defaults.js';
+export { CODEX_ADAPTER, codexTransition, codexServiceId, handleCodexHookEvent, } from './hook-handler.js';
+export { setupCodexHooks, uninstallCodexHooks, installCodexHooksInto, CODEX_HOOK_EVENTS, } from './setup.js';
+export { parseRolloutLine, describeExecScript } from './rollout.js';
+export { CodexWatcher } from './watcher.js';
+/**
+ * codex subcommands: setup | uninstall | hook | flush | watch | cleanup.
+ * `hook`/`flush` are invoked by Codex / ourselves and stay silent on stdout.
+ */
+export async function handleCodexCommand(opts) {
+    const { subcommand, config, flags } = opts;
+    switch (subcommand) {
+        case 'setup': {
+            if (flags['uninstall']) {
+                uninstallCodexHooks();
+                break;
+            }
+            const ok = setupCodexHooks({
+                apiUrl: stringFlag(flags, 'api-url') ?? process.env['NOCVILLE_API_URL'],
+                apiKey: stringFlag(flags, 'api-key') ?? process.env['NOCVILLE_API_KEY'],
+                map: stringFlag(flags, 'map'),
+                cliPath: process.argv[1],
+            });
+            if (!ok)
+                process.exitCode = 1;
+            break;
+        }
+        case 'uninstall':
+            uninstallCodexHooks();
+            break;
+        case 'hook':
+            await handleCodexHookEvent(config, readStdin(), { mode: 'detach' });
+            break;
+        case 'watchdog':
+            await runWatchdog(CODEX_ADAPTER, config, opts.args?.[0]);
+            break;
+        case 'flush':
+            await runFlushCommand(CODEX_ADAPTER, config, opts.args?.[0], numberFlag(flags, 'delay'), flags['stats'] === true);
+            break;
+        case 'watch': {
+            console.error('codex watch is a fallback for Codex builds without hooks; prefer `nocville-npc codex setup`.');
+            if (!config.apiKey) {
+                console.error('Error: no API key — run `nocville-npc init --api-key=<key>` or pass --api-key');
+                process.exitCode = 1;
+                return;
+            }
+            const idleMin = numberFlag(flags, 'idle-timeout');
+            const watcher = new CodexWatcher(config, {
+                sessionsDir: stringFlag(flags, 'sessions-dir'),
+                idleTimeoutMs: idleMin !== undefined ? idleMin * 60_000 : undefined,
+                includeExec: boolFlag(flags, 'include-exec') ?? false,
+                pollMs: numberFlag(flags, 'poll-interval'),
+            });
+            await watcher.start();
+            break;
+        }
+        case 'cleanup': {
+            const removed = await cleanupSessionStates(CODEX_DEFAULTS.stateDir, CODEX_DEFAULTS.stateFileMaxAge);
+            console.log(`Cleanup complete: ${removed} stale file(s) removed`);
+            break;
+        }
+        default:
+            console.error(`Unknown codex subcommand: ${subcommand}`);
+            console.error('Available subcommands: setup, uninstall, watch, hook, cleanup');
+            process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/npcs/codex/rollout.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Parser for Codex session rollout logs (`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`).
+ *
+ * Each line is `{ timestamp, type, payload }`. The format is internal to Codex
+ * and has shifted between releases, so this is deliberately defensive: it
+ * recognises both the older `event_msg` records (exec_command_begin,
+ * patch_apply_begin, *_approval_request, user_message) and the newer ones
+ * (custom_tool_call "exec" scripts, function_call, item_completed), and
+ * ignores everything else. Content (prompts, outputs) is never surfaced.
+ */
+export type RolloutSignal = {
+    kind: 'meta';
+    sessionId: string;
+    cwd?: string;
+    /** Spawned subagent / guardian reviewer — not a user-facing session. */
+    subagent: boolean;
+    /** Non-interactive `codex exec` run. */
+    exec: boolean;
+} | {
+    kind: 'cwd';
+    cwd: string;
+} | {
+    kind: 'working';
+    activity: string;
+} | {
+    kind: 'waiting';
+    activity: string;
+} | {
+    kind: 'idle';
+    activity: string;
+};
+/**
+ * Describe a Codex "exec" code-mode script (`text(await tools.exec_command({cmd:"…"}))`)
+ * by its first tool call. Returns null for no-op helpers.
+ */
+export declare function describeExecScript(script: string, cwd?: string): string | null;
+/** Parse one rollout line into a signal (or null when it carries nothing useful). */
+export declare function parseRolloutLine(line: string, cwd?: string): RolloutSignal | null;
+//# sourceMappingURL=rollout.d.ts.map

package/dist/npcs/codex/rollout.js

@@ -0,0 +1,242 @@
+// Unsupported, best-effort fallback: Codex rollout logs are an internal format. Prefer hooks.
+import { THINKING, describeToolUse, editingFiles, patchFiles, shortCommand, } from '../agent-common/activity.js';
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const s = (v) => (typeof v === 'string' && v ? v : undefined);
+function stripFileUrl(p) {
+    return p.replace(/^file:\/\//, '');
+}
+/** Pull a JS/JSON string property (`cmd:"…"` / `"cmd": "…"`) out of a script. */
+function scriptString(script, key) {
+    const re = new RegExp(`["']?${key}["']?\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)"`);
+    const m = script.match(re);
+    if (!m)
+        return undefined;
+    try {
+        return JSON.parse(`"${m[1]}"`);
+    }
+    catch {
+        return m[1];
+    }
+}
+/** Tool helpers inside exec scripts that carry nothing worth showing. */
+const QUIET_SCRIPT_TOOLS = new Set(['write_stdin', 'wait', 'clock__curr_time', 'get_goal']);
+/**
+ * Describe a Codex "exec" code-mode script (`text(await tools.exec_command({cmd:"…"}))`)
+ * by its first tool call. Returns null for no-op helpers.
+ */
+export function describeExecScript(script, cwd) {
+    const m = script.match(/tools\.([A-Za-z0-9_]+)\s*\(/);
+    if (!m)
+        return 'Running code';
+    const tool = m[1];
+    if (QUIET_SCRIPT_TOOLS.has(tool))
+        return null;
+    switch (tool) {
+        case 'exec_command': {
+            const cmd = scriptString(script, 'cmd') ?? scriptString(script, 'command');
+            const short = cmd ? shortCommand(cmd) : '';
+            return short ? `Running ${short}` : 'Running a command';
+        }
+        case 'apply_patch': {
+            // The patch is embedded as a JS string with escaped newlines.
+            return editingFiles(patchFiles(script.replace(/\\n/g, '\n')), cwd);
+        }
+        case 'view_image':
+            return 'Viewing an image';
+        case 'update_plan':
+            return 'Planning';
+        case 'web__run':
+        case 'web_search':
+            return 'Browsing the web';
+        case 'image_gen__imagegen':
+            return 'Generating an image';
+        case 'spawn_agent':
+            return 'Delegating to a subagent';
+        default:
+            return describeToolUse(tool.includes('__') ? `mcp__${tool}` : tool, {}, cwd);
+    }
+}
+function parseArgs(raw) {
+    if (isObj(raw))
+        return raw;
+    if (typeof raw === 'string') {
+        try {
+            const parsed = JSON.parse(raw);
+            if (isObj(parsed))
+                return parsed;
+        }
+        catch {
+            return { input: raw };
+        }
+    }
+    return {};
+}
+/** Describe a `function_call` / `custom_tool_call` response item. */
+function describeCall(name, rawArgs, cwd) {
+    switch (name) {
+        case 'exec':
+            return typeof rawArgs === 'string' ? describeExecScript(rawArgs, cwd) : 'Running code';
+        case 'wait':
+        case 'write_stdin':
+        case 'list_agents':
+            return null;
+        case 'send_message':
+        case 'followup_task':
+            return 'Coordinating subagents';
+        case 'apply_patch': {
+            const args = parseArgs(rawArgs);
+            const patch = s(args['input']) ?? s(args['patch']) ?? (typeof rawArgs === 'string' ? rawArgs : '');
+            return editingFiles(patchFiles(patch), cwd);
+        }
+        case 'shell':
+        case 'local_shell':
+        case 'exec_command':
+        case 'container.exec': {
+            const args = parseArgs(rawArgs);
+            return describeToolUse('Bash', { command: args['command'] ?? args['cmd'] }, cwd);
+        }
+        default:
+            return describeToolUse(name, parseArgs(rawArgs), cwd);
+    }
+}
+function approvalText(payload, cwd) {
+    const cmd = payload['command'];
+    if (cmd) {
+        const short = shortCommand(cmd);
+        if (short)
+            return `Needs your approval: Running ${short}`;
+    }
+    const changes = payload['changes'];
+    if (isObj(changes)) {
+        return `Needs your approval: ${editingFiles(Object.keys(changes).map(stripFileUrl), cwd)}`;
+    }
+    return 'Needs your approval';
+}
+function parseEventMsg(payload, cwd) {
+    const type = s(payload['type']) ?? '';
+    switch (type) {
+        case 'task_started':
+        case 'user_message':
+            return { kind: 'working', activity: THINKING };
+        case 'task_complete':
+            return { kind: 'idle', activity: 'Done — waiting for next task' };
+        case 'turn_aborted':
+            return { kind: 'idle', activity: 'Interrupted — waiting for you' };
+        case 'exec_command_begin': {
+            const short = shortCommand(payload['command']);
+            return { kind: 'working', activity: short ? `Running ${short}` : 'Running a command' };
+        }
+        case 'patch_apply_begin': {
+            const changes = isObj(payload['changes']) ? Object.keys(payload['changes']) : [];
+            return { kind: 'working', activity: editingFiles(changes.map(stripFileUrl), cwd) };
+        }
+        case 'web_search_begin':
+            return { kind: 'working', activity: 'Searching the web' };
+        case 'request_user_input':
+            return { kind: 'waiting', activity: 'Has a question for you' };
+        case 'item_started': {
+            const item = isObj(payload['item']) ? payload['item'] : {};
+            const itemType = s(item['type']);
+            if (itemType === 'CommandExecution') {
+                const short = shortCommand(item['command']);
+                return { kind: 'working', activity: short ? `Running ${short}` : 'Running a command' };
+            }
+            if (itemType === 'FileChange' && isObj(item['changes'])) {
+                return {
+                    kind: 'working',
+                    activity: editingFiles(Object.keys(item['changes']).map(stripFileUrl), cwd),
+                };
+            }
+            return null;
+        }
+        case 'item_completed': {
+            // Newer builds log file edits only on completion; still the best signal.
+            const item = isObj(payload['item']) ? payload['item'] : {};
+            if (s(item['type']) === 'FileChange' && isObj(item['changes'])) {
+                return {
+                    kind: 'working',
+                    activity: editingFiles(Object.keys(item['changes']).map(stripFileUrl), cwd),
+                };
+            }
+            return null;
+        }
+        default:
+            if (/approval_request$/.test(type) || type === 'request_permissions') {
+                return { kind: 'waiting', activity: approvalText(payload, cwd) };
+            }
+            return null;
+    }
+}
+function parseResponseItem(payload, cwd) {
+    const type = s(payload['type']) ?? '';
+    if (type === 'custom_tool_call' || type === 'function_call') {
+        const name = s(payload['name']) ?? '';
+        const activity = describeCall(name, payload['input'] ?? payload['arguments'], cwd);
+        return activity ? { kind: 'working', activity } : null;
+    }
+    if (type === 'local_shell_call') {
+        const action = isObj(payload['action']) ? payload['action'] : {};
+        const short = shortCommand(action['command']);
+        return { kind: 'working', activity: short ? `Running ${short}` : 'Running a command' };
+    }
+    if (type === 'web_search_call')
+        return { kind: 'working', activity: 'Searching the web' };
+    return null;
+}
+/** Parse one rollout line into a signal (or null when it carries nothing useful). */
+export function parseRolloutLine(line, cwd) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed[0] !== '{')
+        return null;
+    let rec;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!isObj(parsed))
+            return null;
+        rec = parsed;
+    }
+    catch {
+        return null;
+    }
+    const type = s(rec['type']) ?? '';
+    const payload = isObj(rec['payload']) ? rec['payload'] : {};
+    switch (type) {
+        case 'session_meta': {
+            const meta = isObj(payload['meta']) ? payload['meta'] : payload; // older nesting
+            const sessionId = s(meta['id']) ?? s(meta['session_id']);
+            if (!sessionId)
+                return null;
+            const source = meta['source'];
+            const threadSource = s(meta['thread_source']);
+            const subagent = (isObj(source) && 'subagent' in source) ||
+                threadSource === 'subagent' ||
+                threadSource === 'guardian_review';
+            const exec = source === 'exec' || s(meta['originator']) === 'codex_exec';
+            return { kind: 'meta', sessionId, cwd: s(meta['cwd']), subagent, exec };
+        }
+        case 'turn_context': {
+            const c = s(payload['cwd']);
+            return c ? { kind: 'cwd', cwd: c } : null;
+        }
+        case 'event_msg':
+            return parseEventMsg(payload, cwd);
+        case 'response_item':
+            return parseResponseItem(payload, cwd);
+        case 'function_call':
+        case 'custom_tool_call':
+        case 'local_shell_call':
+        case 'web_search_call':
+            // 2025-era rollouts wrote response items unwrapped.
+            return parseResponseItem(rec, cwd);
+        case '': {
+            // 2025-era first line: bare `{ id, timestamp, instructions }` session header.
+            const id = s(rec['id']);
+            return id && s(rec['timestamp'])
+                ? { kind: 'meta', sessionId: id, subagent: false, exec: false }
+                : null;
+        }
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=rollout.js.map

package/dist/npcs/codex/setup.d.ts

@@ -0,0 +1,37 @@
+import type { HooksFile } from '../agent-common/hook-settings.js';
+/**
+ * Codex hook events we install (developers.openai.com/codex/hooks). PostCompact
+ * is omitted — it carries nothing displayable.
+ */
+export declare const CODEX_HOOK_EVENTS: readonly ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "Stop", "Interrupt", "PreCompact", "SubagentStart", "SubagentStop"];
+export declare function codexHooksPath(): string;
+export interface CodexSetupOptions {
+    apiUrl?: string;
+    apiKey?: string;
+    map?: string;
+    cliPath?: string;
+    /** Override ~/.codex/hooks.json (tests). */
+    hooksPath?: string;
+    quiet?: boolean;
+}
+/** Install the nocville group into every Codex event. Mutates `file`. */
+export declare function installCodexHooksInto(file: HooksFile, command: string, opts?: {
+    timeout?: number;
+}): {
+    migrated: number;
+    installed: number;
+};
+export declare function buildCodexHookCommand(_cliPath: string): string;
+/**
+ * Install Nocville hooks into `~/.codex/hooks.json` (same matcher-group JSON
+ * format as Claude Code). Merges with existing hooks, idempotent, keeps a
+ * one-time `.nocville-backup`. Codex requires new hooks to be reviewed and
+ * trusted once via `/hooks` before they run — we print that instruction.
+ */
+export declare function setupCodexHooks(opts?: CodexSetupOptions): boolean;
+/** Remove all Nocville hooks from `~/.codex/hooks.json`. */
+export declare function uninstallCodexHooks(opts?: {
+    hooksPath?: string;
+    quiet?: boolean;
+}): number;
+//# sourceMappingURL=setup.d.ts.map