@nocville/npc 0.0.0-stage → 0.2.0

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

package/dist/npcs/codex/setup.js

@@ -0,0 +1,96 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { maskKey, persistCredentials } from '../../core/user-config.js';
+import { buildShimHookCommand, stableNodePath, installHookGroups, readJsonFile, removeHookGroups, resolveCliPath, writeJsonFile, } from '../agent-common/hook-settings.js';
+import { installHookShim } from '../agent-common/shim.js';
+import { ensureStableCliPath } from '../agent-common/runtime.js';
+import { CODEX_DEFAULTS, codexHome } from './defaults.js';
+/**
+ * Codex hook events we install (developers.openai.com/codex/hooks). PostCompact
+ * is omitted — it carries nothing displayable.
+ */
+export const CODEX_HOOK_EVENTS = [
+    'SessionStart',
+    'SessionEnd',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PostToolUse',
+    'PermissionRequest',
+    'Stop',
+    'Interrupt',
+    'PreCompact',
+    'SubagentStart',
+    'SubagentStop',
+];
+export function codexHooksPath() {
+    return join(codexHome(), 'hooks.json');
+}
+/** Install the nocville group into every Codex event. Mutates `file`. */
+export function installCodexHooksInto(file, command, opts = {}) {
+    return installHookGroups(file, command, CODEX_HOOK_EVENTS, {
+        perEvent: Object.fromEntries(CODEX_HOOK_EVENTS.map((event) => [
+            event,
+            event === 'SessionEnd' || event === 'Interrupt'
+                ? { timeout: 3 }
+                : { async: true, timeout: opts.timeout ?? 10 },
+        ])),
+    });
+}
+export function buildCodexHookCommand(_cliPath) {
+    return buildShimHookCommand('codex');
+}
+function out(opts, msg) {
+    if (!opts.quiet)
+        console.log(msg);
+}
+/**
+ * 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 function setupCodexHooks(opts = {}) {
+    const hooksPath = opts.hooksPath ?? codexHooksPath();
+    const dir = join(hooksPath, '..');
+    if (!existsSync(dir)) {
+        console.error(`${dir} does not exist — is Codex installed? Skipping Codex setup.`);
+        return false;
+    }
+    const file = readJsonFile(hooksPath);
+    if (file === null) {
+        console.error(`Could not parse ${hooksPath}; fix it (or move it aside) and re-run setup.`);
+        return false;
+    }
+    const creds = persistCredentials(opts);
+    const resolved = resolveCliPath(opts.cliPath);
+    const cliPath = ensureStableCliPath(resolved);
+    installHookShim(stableNodePath(), cliPath);
+    const { installed } = installCodexHooksInto(file, buildCodexHookCommand(cliPath), {
+        timeout: CODEX_DEFAULTS.hookTimeoutSeconds,
+    });
+    writeJsonFile(hooksPath, file);
+    out(opts, `✓ Codex: installed Nocville hooks for ${installed} events in ${hooksPath}`);
+    out(opts, `  Hook runs: ${process.execPath} ${cliPath}`);
+    out(opts, `  API: ${creds.apiUrl ?? 'https://nocville.com'}  key: ${maskKey(creds.apiKey)}`);
+    if (!creds.apiKey) {
+        out(opts, '  ⚠ No API key saved yet — run: nocville-npc init --api-key=<your team key>');
+    }
+    out(opts, '  ➜ One-time step: start Codex and run /hooks to review and trust the Nocville');
+    out(opts, '    hooks (Codex skips new hooks until trusted).');
+    return true;
+}
+/** Remove all Nocville hooks from `~/.codex/hooks.json`. */
+export function uninstallCodexHooks(opts = {}) {
+    const hooksPath = opts.hooksPath ?? codexHooksPath();
+    const file = readJsonFile(hooksPath);
+    if (!file || !existsSync(hooksPath)) {
+        out(opts, 'Codex: no hooks.json — nothing to remove.');
+        return 0;
+    }
+    const removed = removeHookGroups(file);
+    if (removed > 0)
+        writeJsonFile(hooksPath, file);
+    out(opts, `✓ Codex: removed ${removed} Nocville hook(s) from ${hooksPath}`);
+    return removed;
+}
+//# sourceMappingURL=setup.js.map

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

@@ -0,0 +1,62 @@
+import type { StatusUpdate } from '@nocville/node';
+import type { NpcConfig } from '../../core/types.js';
+import type { AgentSessionState } from '../agent-common/session.js';
+/**
+ * `nocville-npc codex watch` — zero-config Codex integration that tails the
+ * session rollout logs Codex writes under ~/.codex/sessions/YYYY/MM/DD/.
+ *
+ * One NPC per live interactive session (subagent and guardian threads are
+ * skipped; `codex exec` runs only with --include-exec). Phase + activity are
+ * derived from the log; a session whose log stops growing for `idleTimeoutMs`
+ * despawns. Sessions whose hooks are active (any hook state file exists)
+ * are left to the hooks so nothing is pushed twice. Ctrl-C despawns all.
+ */
+export interface CodexWatcherOptions {
+    sessionsDir?: string;
+    pollMs?: number;
+    idleTimeoutMs?: number;
+    includeExec?: boolean;
+    minPushGapMs?: number;
+    /** Push override (tests). */
+    push?: (serviceId: string, payload: StatusUpdate) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    now?: () => number;
+    /** Hook state dir consulted for hook ownership (tests). */
+    hookStateDir?: string;
+}
+/** Day directories to scan: today and yesterday (local time, like Codex). */
+export declare function recentDayDirs(root: string, now: number): string[];
+export declare class CodexWatcher {
+    private readonly config;
+    private readonly opts;
+    private readonly sessionsDir;
+    private readonly pollMs;
+    private readonly idleTimeoutMs;
+    private readonly includeExec;
+    private readonly minPushGapMs;
+    private readonly hookStateDir;
+    private readonly now;
+    private readonly logger;
+    private readonly sessions;
+    private interval?;
+    private clients;
+    constructor(config: NpcConfig, opts?: CodexWatcherOptions);
+    /** Active (non-ignored) sessions — exposed for tests/diagnostics. */
+    activeSessions(): AgentSessionState[];
+    start(): Promise<void>;
+    /** Stop polling and despawn every live session. */
+    stop(): Promise<void>;
+    /** One poll: discover files, read appended lines, push, expire quiet sessions. */
+    tick(): Promise<void>;
+    private discover;
+    private readAppended;
+    /** Reduce one signal into the session state. Exposed via tick for tests. */
+    private apply;
+    private hooksOwn;
+    private maybePush;
+    private despawn;
+    private send;
+}
+//# sourceMappingURL=watcher.d.ts.map