@nocville/npc 0.0.0-stage → 0.2.0

package/dist/npcs/claude-code/state-machine.d.ts

@@ -0,0 +1,28 @@
+import type { AgentHookEvent } from '../agent-common/hook-runner.js';
+import type { AgentPhase, AgentSessionState, AgentTransition, StatusOutput } from '../agent-common/session.js';
+export type SessionMachineState = AgentPhase;
+export type SessionState = AgentSessionState;
+export type { StatusOutput };
+export interface HookEvent extends AgentHookEvent {
+    /** User-facing session name — present in the SessionStart payload only. */
+    session_title?: string;
+    /** Notification events: permission_prompt | idle_prompt | … */
+    notification_type?: string;
+}
+/** Resolve the event name from either the real or legacy field. */
+export declare function eventName(event: HookEvent): string;
+/**
+ * Map one Claude Code hook event to a phase + activity line.
+ * Event names / payload fields per code.claude.com/docs/en/hooks.
+ * Prompt text is never read (privacy); tool inputs are summarized, not echoed.
+ */
+export declare function claudeTransition(event: HookEvent, prev: AgentSessionState | null): AgentTransition;
+/**
+ * Derive the NPC status output from a hook event (state + presentation).
+ * Kept for library consumers; the hook runner uses `claudeTransition` directly.
+ */
+export declare function processHookEvent(event: HookEvent, currentState: SessionState | null): {
+    state: SessionMachineState;
+    output: StatusOutput;
+};
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/npcs/claude-code/state-machine.js

@@ -0,0 +1,125 @@
+import { THINKING, describeToolUse, failureText, isQuestionTool, } from '../agent-common/activity.js';
+import { hookEventName } from '../agent-common/hook-runner.js';
+import { phasePresentation } from '../agent-common/session.js';
+/** Resolve the event name from either the real or legacy field. */
+export function eventName(event) {
+    return hookEventName(event);
+}
+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',
+});
+/** Notification types that mean "the human needs to act". */
+const WAITING_NOTIFICATIONS = new Set([
+    'permission_prompt',
+    'elicitation_dialog',
+    'elicitation_url_dialog',
+    'agent_needs_input',
+]);
+/**
+ * Map one Claude Code hook event to a phase + activity line.
+ * Event names / payload fields per code.claude.com/docs/en/hooks.
+ * Prompt text is never read (privacy); tool inputs are summarized, not echoed.
+ */
+export function claudeTransition(event, prev) {
+    const name = eventName(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);
+            if (isQuestionTool(event.tool_name))
+                return waiting(activity);
+            return working(activity);
+        }
+        case 'PostToolUse':
+        case 'PostToolBatch':
+            // Tool finished — still working; keep showing the same activity.
+            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 'Notification': {
+            const type = typeof event.notification_type === 'string' ? event.notification_type : '';
+            if (type === 'idle_prompt')
+                return idle('Done — waiting for next task');
+            if (type === 'permission_prompt')
+                return waiting('Needs your approval');
+            if (WAITING_NOTIFICATIONS.has(type) || !type)
+                return waiting('Waiting for you');
+            // auth_success, agent_completed, quota_* … → informational only.
+            return {
+                state: keep,
+                status: prev?.status ?? 'healthy',
+                mood: prev?.mood ?? 'idle',
+                quiet: true,
+            };
+        }
+        case 'Stop':
+            return idle('Done — waiting for next task');
+        case 'StopFailure':
+            return { ...idle('Stopped with an error'), status: 'warning', mood: 'concerned' };
+        case 'SubagentStart':
+            return working('Delegating to a subagent');
+        case 'SubagentStop':
+            return working('Subagent finished');
+        case 'PreCompact':
+            return working('Compacting context');
+        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,
+            };
+    }
+}
+/**
+ * Derive the NPC status output from a hook event (state + presentation).
+ * Kept for library consumers; the hook runner uses `claudeTransition` directly.
+ */
+export function processHookEvent(event, currentState) {
+    const t = claudeTransition(event, currentState);
+    const { subStatus, behavior } = phasePresentation(t.state, t.offline);
+    return {
+        state: t.state,
+        output: {
+            status: t.status,
+            mood: t.mood,
+            message: t.activity ?? currentState?.activity?.[0] ?? '',
+            subStatus,
+            behavior,
+            offline: t.offline,
+        },
+    };
+}
+//# sourceMappingURL=state-machine.js.map

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

@@ -0,0 +1,24 @@
+export declare const CODEX_DEFAULTS: {
+    /** Hook-mode per-session state (shared with the watcher to avoid double pushes). */
+    stateDir: string;
+    stateFileMaxAge: number;
+    /** Watchdog-backed sessions become unknown after three minutes without a heartbeat. */
+    heartbeatSeconds: number;
+    minPushGapMs: number;
+    hookTimeoutSeconds: number;
+    /** Watcher: Codex session rollout logs. */
+    sessionsDir: string;
+    /** Watcher: poll interval for new sessions / appended lines. */
+    pollMs: number;
+    /**
+     * 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: number;
+    /** Watcher: bytes read from the end of an already-active rollout on discovery. */
+    initialTailBytes: number;
+    /** Watcher: max bytes read per tick per session before skipping ahead to the tail. */
+    maxReadBytes: number;
+};
+export declare function codexHome(): string;
+//# sourceMappingURL=defaults.d.ts.map

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