@nocville/npc 0.0.0-stage → 0.2.1

package/dist/npcs/claude-code/hook-handler.d.ts

@@ -0,0 +1,40 @@
+import type { NpcConfig } from '../../core/types.js';
+import type { AgentHookSpec, HookRunOptions } from '../agent-common/hook-runner.js';
+import type { AgentAdapter } from '../agent-common/session.js';
+import type { HookEvent } from './state-machine.js';
+export declare const CLAUDE_ADAPTER: AgentAdapter;
+/**
+ * Derive a serviceId from the session and project directory.
+ * Format: "claude-{project_name}-{session_id_prefix}" (≤100 chars).
+ */
+export declare function deriveServiceId(sessionId: string, cwd: string): string;
+/**
+ * Humanize a project dir name into a banner label: split on punctuation and
+ * title-case each word ("gridbreak" -> "Gridbreak", "my-cool-app" -> "My Cool App").
+ */
+export declare function humanizeProjectName(cwd: string): string;
+/**
+ * Correlate a session_id to its user-facing name via the local session store.
+ * Claude Code writes ~/.claude/sessions/<pid>.json — keyed by pid, each holding
+ * `{ sessionId, name, ... }` — so we scan for the file whose sessionId matches.
+ * `dir` is injectable for testing.
+ */
+export declare function lookupSessionNameFromStore(sessionId: string, dir?: string): string | null;
+/**
+ * Resolve the user-facing session name. Checked fresh only on the cheap,
+ * low-frequency events (SessionStart carries `session_title`; UserPromptSubmit
+ * falls back to the store scan) so renames propagate; otherwise the cached
+ * value is reused. Returns null when unknown (banner falls back to the project).
+ */
+export declare function resolveSessionName(event: HookEvent, cached: string | null, dir?: string): string | null;
+export declare const CLAUDE_HOOK_SPEC: AgentHookSpec;
+/**
+ * Handle a single Claude Code hook event.
+ *
+ * Reads the JSON payload (from `rawInput` if provided, else stdin), updates the
+ * per-session state file, and pushes an NPC status update (banner
+ * "Claude · <session name or project>"). Defaults to an in-process push; the CLI
+ * passes `mode: 'detach'` so the push runs in a background process. Never throws.
+ */
+export declare function handleHookEvent(config: NpcConfig, rawInput?: string, opts?: HookRunOptions): Promise<void>;
+//# sourceMappingURL=hook-handler.d.ts.map

package/dist/npcs/claude-code/hook-handler.js

@@ -0,0 +1,131 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { runAgentHook, readStdin } from '../agent-common/hook-runner.js';
+import { projectNameOf, sanitizeServiceId } from '../agent-common/session.js';
+import { isCursorInvocation } from '../cursor/normalize.js';
+import { handleCursorHookEvent } from '../cursor/hook-handler.js';
+import { DEFAULTS } from './defaults.js';
+import { claudeTransition, eventName } from './state-machine.js';
+export const CLAUDE_ADAPTER = {
+    command: 'claude-code',
+    label: 'Claude',
+    family: 'claude',
+    stateDir: DEFAULTS.stateDir,
+    heartbeatSeconds: DEFAULTS.heartbeatSeconds,
+    processNames: ['claude'],
+};
+/**
+ * Derive a serviceId from the session and project directory.
+ * Format: "claude-{project_name}-{session_id_prefix}" (≤100 chars).
+ */
+export function deriveServiceId(sessionId, cwd) {
+    return sanitizeServiceId(`claude-${projectNameOf(cwd)}-${sessionId.slice(0, 8)}`);
+}
+/**
+ * Humanize a project dir name into a banner label: split on punctuation and
+ * title-case each word ("gridbreak" -> "Gridbreak", "my-cool-app" -> "My Cool App").
+ */
+export function humanizeProjectName(cwd) {
+    const raw = projectNameOf(cwd);
+    const words = raw
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+    if (words.length === 0)
+        return raw;
+    return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+/** Default location of Claude Code's per-session sidecar files. */
+function sessionsStoreDir() {
+    return join(homedir(), '.claude', 'sessions');
+}
+/**
+ * Correlate a session_id to its user-facing name via the local session store.
+ * Claude Code writes ~/.claude/sessions/<pid>.json — keyed by pid, each holding
+ * `{ sessionId, name, ... }` — so we scan for the file whose sessionId matches.
+ * `dir` is injectable for testing.
+ */
+export function lookupSessionNameFromStore(sessionId, dir = sessionsStoreDir()) {
+    if (!sessionId)
+        return null;
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    for (const file of files) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const obj = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+            if (obj.sessionId === sessionId && typeof obj.name === 'string' && obj.name.trim()) {
+                return obj.name.trim();
+            }
+        }
+        catch {
+            // Skip unreadable / partially-written session files.
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the user-facing session name. Checked fresh only on the cheap,
+ * low-frequency events (SessionStart carries `session_title`; UserPromptSubmit
+ * falls back to the store scan) so renames propagate; otherwise the cached
+ * value is reused. Returns null when unknown (banner falls back to the project).
+ */
+export function resolveSessionName(event, cached, dir) {
+    const name = eventName(event);
+    const shouldRefresh = name === 'SessionStart' || name === 'UserPromptSubmit' || !cached;
+    if (!shouldRefresh)
+        return cached;
+    const fromPayload = typeof event.session_title === 'string' ? event.session_title.trim() : '';
+    if (fromPayload)
+        return fromPayload;
+    return lookupSessionNameFromStore(event.session_id ?? '', dir) ?? cached;
+}
+export const CLAUDE_HOOK_SPEC = {
+    adapter: CLAUDE_ADAPTER,
+    serviceIdFor: deriveServiceId,
+    transition: (event, prev) => claudeTransition(event, prev),
+    resolveName: (event, prev) => {
+        // Only scan the store on the low-frequency events; never on PreToolUse.
+        const name = eventName(event);
+        if (prev && name !== 'SessionStart' && name !== 'UserPromptSubmit')
+            return undefined;
+        return resolveSessionName(event, prev?.name ?? null) ?? undefined;
+    },
+};
+/**
+ * Handle a single Claude Code hook event.
+ *
+ * Reads the JSON payload (from `rawInput` if provided, else stdin), updates the
+ * per-session state file, and pushes an NPC status update (banner
+ * "Claude · <session name or project>"). Defaults to an in-process push; the CLI
+ * passes `mode: 'detach'` so the push runs in a background process. Never throws.
+ */
+export async function handleHookEvent(config, rawInput, opts = {}) {
+    const input = rawInput ?? readStdin();
+    let event;
+    try {
+        event = JSON.parse(input);
+    }
+    catch {
+        return;
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event))
+        return;
+    if (isCursorInvocation(event)) {
+        await handleCursorHookEvent(config, event, opts, 'third-party');
+        return;
+    }
+    await runAgentHook(CLAUDE_HOOK_SPEC, config, event, {
+        minPushGapMs: DEFAULTS.minPushGapMs,
+        ...opts,
+    });
+}
+//# sourceMappingURL=hook-handler.js.map

package/dist/npcs/claude-code/index.d.ts

@@ -0,0 +1,36 @@
+import type { NpcConfig } from '../../core/types.js';
+export { DEFAULTS } from './defaults.js';
+export { processHookEvent, claudeTransition } from './state-machine.js';
+export type { SessionState, HookEvent, StatusOutput, SessionMachineState, } from './state-machine.js';
+export { handleHookEvent, CLAUDE_ADAPTER } from './hook-handler.js';
+export { setupHooks, uninstallHooks } from './setup.js';
+export type { SetupOptions } from './setup.js';
+export interface ClaudeCodeSubcommandOptions {
+    subcommand: string;
+    config: NpcConfig;
+    flags: Record<string, string | boolean>;
+    /** Positional args after the subcommand (e.g. the session id for `flush`). */
+    args?: string[];
+}
+/**
+ * claude-code subcommands: setup | uninstall | hook | flush | cleanup.
+ * `hook` and `flush` are invoked by Claude Code / ourselves and must stay
+ * silent on stdout and never exit non-zero.
+ */
+export declare function handleClaudeCodeCommand(opts: ClaudeCodeSubcommandOptions): Promise<void>;
+/**
+ * ClaudeCodeNPC class for programmatic use.
+ */
+export declare class ClaudeCodeNPC {
+    private config;
+    constructor(config: NpcConfig);
+    /** Process a hook event from stdin (in-process push). */
+    handleHook(): Promise<void>;
+    /** Install hooks into Claude Code settings. */
+    setup(): void;
+    /** Remove all Nocville hooks from Claude Code settings. */
+    uninstall(): void;
+    /** Clean up stale session state files. */
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/npcs/claude-code/index.js

@@ -0,0 +1,92 @@
+import { 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 { DEFAULTS } from './defaults.js';
+import { CLAUDE_ADAPTER, handleHookEvent } from './hook-handler.js';
+import { setupHooks, uninstallHooks } from './setup.js';
+export { DEFAULTS } from './defaults.js';
+export { processHookEvent, claudeTransition } from './state-machine.js';
+export { handleHookEvent, CLAUDE_ADAPTER } from './hook-handler.js';
+export { setupHooks, uninstallHooks } from './setup.js';
+/** Remove stale session state files. */
+async function cleanupStateFiles() {
+    const removed = await cleanupSessionStates(DEFAULTS.stateDir, DEFAULTS.stateFileMaxAge);
+    console.log(`Cleanup complete: ${removed} stale file(s) removed`);
+}
+/**
+ * claude-code subcommands: setup | uninstall | hook | flush | cleanup.
+ * `hook` and `flush` are invoked by Claude Code / ourselves and must stay
+ * silent on stdout and never exit non-zero.
+ */
+export async function handleClaudeCodeCommand(opts) {
+    const { subcommand, config, flags } = opts;
+    switch (subcommand) {
+        case 'setup': {
+            if (flags['uninstall']) {
+                uninstallHooks();
+                break;
+            }
+            const ok = setupHooks({
+                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],
+                debug: config.debug,
+            });
+            if (!ok)
+                process.exitCode = 1;
+            break;
+        }
+        case 'uninstall':
+            uninstallHooks();
+            break;
+        case 'hook':
+            await handleHookEvent(config, readStdin(), { mode: 'detach' });
+            break;
+        case 'watchdog':
+            await runWatchdog(CLAUDE_ADAPTER, config, opts.args?.[0]);
+            break;
+        case 'flush':
+            await runFlushCommand(CLAUDE_ADAPTER, config, opts.args?.[0], numberFlag(flags, 'delay'), flags['stats'] === true);
+            break;
+        case 'cleanup':
+            await cleanupStateFiles();
+            break;
+        default: {
+            console.error(`Unknown claude-code subcommand: ${subcommand}`);
+            console.error('Available subcommands: setup, uninstall, hook, cleanup');
+            process.exitCode = 1;
+        }
+    }
+}
+/**
+ * ClaudeCodeNPC class for programmatic use.
+ */
+export class ClaudeCodeNPC {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Process a hook event from stdin (in-process push). */
+    async handleHook() {
+        await handleHookEvent(this.config);
+    }
+    /** Install hooks into Claude Code settings. */
+    setup() {
+        setupHooks({
+            apiUrl: this.config.apiUrl,
+            apiKey: this.config.apiKey,
+            debug: this.config.debug,
+        });
+    }
+    /** Remove all Nocville hooks from Claude Code settings. */
+    uninstall() {
+        uninstallHooks();
+    }
+    /** Clean up stale session state files. */
+    async cleanup() {
+        await cleanupStateFiles();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/npcs/claude-code/setup.d.ts

@@ -0,0 +1,58 @@
+import type { HooksFile } from '../agent-common/hook-settings.js';
+export { extractFlag } from '../agent-common/hook-settings.js';
+export declare function claudeSettingsPath(): string;
+/**
+ * Hook events to install. Verified against code.claude.com/docs/en/hooks —
+ * all exist; events without matcher support ignore the empty matcher.
+ */
+export declare const CLAUDE_HOOK_EVENTS: readonly ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionRequest", "Notification", "Stop", "SubagentStart", "SubagentStop", "PreCompact"];
+export interface SetupOptions {
+    /** Explicit --api-url (or env). Saved to the user config. */
+    apiUrl?: string;
+    /** Explicit --api-key (or env). Saved to the user config. */
+    apiKey?: string;
+    /** Explicit --map. Saved to the user config. */
+    map?: string;
+    /** Absolute path to the built cli.js; defaults to the running script. */
+    cliPath?: string;
+    /** Override ~/.claude/settings.json (tests). */
+    settingsPath?: string;
+    debug?: boolean;
+    /** Suppress console output (tests). */
+    quiet?: boolean;
+}
+type ClaudeSettings = HooksFile;
+/** Install the nocville group into every Claude Code event. Mutates `settings`. */
+export declare function installHooksInto(settings: ClaudeSettings, command: string, opts?: {
+    timeout?: number;
+    platform?: NodeJS.Platform;
+}): {
+    migrated: number;
+    installed: number;
+};
+/** Remove all nocville entries (nested or legacy flat). Mutates `settings`. */
+export declare function removeHooksFrom(settings: ClaudeSettings): number;
+export { findNocvilleCommand as findExistingNocvilleCommand } from '../agent-common/hook-settings.js';
+/** `'<node>' '<cli.js>' claude-code hook # nocville-npc-hook` — no key on the command line. */
+export declare function buildHookCommand(_cliPath: string): string;
+/**
+ * Credentials embedded in a legacy hook command (`--api-url=… --api-key=…`),
+ * so upgrading setup can move them into the user config.
+ */
+export declare function legacyCredentials(settings: ClaudeSettings): {
+    apiUrl?: string;
+    apiKey?: string;
+};
+/**
+ * Install Nocville hooks into Claude Code settings (matcher-group format,
+ * absolute node/cli paths, 10s timeout safety net). Idempotent: migrates and
+ * de-duplicates legacy entries and moves any legacy inline credentials into
+ * ~/.config/nocville/config.json. Returns false if setup could not complete.
+ */
+export declare function setupHooks(opts: SetupOptions): boolean;
+/** Remove all Nocville hooks from Claude Code settings. */
+export declare function uninstallHooks(opts?: {
+    settingsPath?: string;
+    quiet?: boolean;
+} | boolean): number;
+//# sourceMappingURL=setup.d.ts.map

package/dist/npcs/claude-code/setup.js

@@ -0,0 +1,121 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { maskKey, persistCredentials } from '../../core/user-config.js';
+import { buildShimHookCommand, stableNodePath, extractFlag, findNocvilleCommand, 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 { DEFAULTS } from './defaults.js';
+export { extractFlag } from '../agent-common/hook-settings.js';
+export function claudeSettingsPath() {
+    return join(homedir(), '.claude', 'settings.json');
+}
+/**
+ * Hook events to install. Verified against code.claude.com/docs/en/hooks —
+ * all exist; events without matcher support ignore the empty matcher.
+ */
+export const CLAUDE_HOOK_EVENTS = [
+    'SessionStart',
+    'SessionEnd',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'PermissionRequest',
+    'Notification',
+    'Stop',
+    'SubagentStart',
+    'SubagentStop',
+    'PreCompact',
+];
+/** Install the nocville group into every Claude Code event. Mutates `settings`. */
+export function installHooksInto(settings, command, opts = {}) {
+    return installHookGroups(settings, command, CLAUDE_HOOK_EVENTS, {
+        perEvent: Object.fromEntries(CLAUDE_HOOK_EVENTS.map((event) => [
+            event,
+            {
+                ...((opts.platform ?? process.platform) === 'win32' ? { shell: 'powershell' } : {}),
+                ...(event === 'SessionEnd'
+                    ? { timeout: 5 }
+                    : { async: true, timeout: opts.timeout ?? 10 }),
+            },
+        ])),
+    });
+}
+/** Remove all nocville entries (nested or legacy flat). Mutates `settings`. */
+export function removeHooksFrom(settings) {
+    return removeHookGroups(settings);
+}
+export { findNocvilleCommand as findExistingNocvilleCommand } from '../agent-common/hook-settings.js';
+/** `'<node>' '<cli.js>' claude-code hook # nocville-npc-hook` — no key on the command line. */
+export function buildHookCommand(_cliPath) {
+    return buildShimHookCommand('claude-code');
+}
+/**
+ * Credentials embedded in a legacy hook command (`--api-url=… --api-key=…`),
+ * so upgrading setup can move them into the user config.
+ */
+export function legacyCredentials(settings) {
+    const prev = findNocvilleCommand(settings);
+    if (!prev)
+        return {};
+    return { apiUrl: extractFlag(prev, 'api-url'), apiKey: extractFlag(prev, 'api-key') };
+}
+function out(opts, msg) {
+    if (!opts.quiet)
+        console.log(msg);
+}
+/**
+ * Install Nocville hooks into Claude Code settings (matcher-group format,
+ * absolute node/cli paths, 10s timeout safety net). Idempotent: migrates and
+ * de-duplicates legacy entries and moves any legacy inline credentials into
+ * ~/.config/nocville/config.json. Returns false if setup could not complete.
+ */
+export function setupHooks(opts) {
+    const settingsPath = opts.settingsPath ?? claudeSettingsPath();
+    const dir = join(settingsPath, '..');
+    if (!existsSync(dir)) {
+        console.error(`${dir} does not exist — is Claude Code installed? Skipping Claude Code setup.`);
+        return false;
+    }
+    const settings = readJsonFile(settingsPath);
+    if (settings === null) {
+        console.error(`Could not parse ${settingsPath}; fix it (or move it aside) and re-run setup.`);
+        return false;
+    }
+    const creds = persistCredentials(opts, legacyCredentials(settings));
+    const resolved = resolveCliPath(opts.cliPath);
+    const cliPath = ensureStableCliPath(resolved);
+    installHookShim(stableNodePath(), cliPath);
+    const command = buildHookCommand(cliPath);
+    const { migrated, installed } = installHooksInto(settings, command, {
+        timeout: DEFAULTS.hookTimeoutSeconds,
+    });
+    writeJsonFile(settingsPath, settings);
+    out(opts, `✓ Claude Code: installed Nocville hooks for ${installed} events in ${settingsPath}`);
+    if (migrated > 0)
+        out(opts, `  (migrated ${migrated} legacy entr${migrated === 1 ? 'y' : 'ies'})`);
+    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, '  New Claude Code sessions will appear in your office. Restart running sessions.');
+    return true;
+}
+/** Remove all Nocville hooks from Claude Code settings. */
+export function uninstallHooks(opts = {}) {
+    const o = typeof opts === 'boolean' ? {} : opts;
+    const settingsPath = o.settingsPath ?? claudeSettingsPath();
+    const settings = readJsonFile(settingsPath);
+    if (!settings || !existsSync(settingsPath)) {
+        out(o, 'Claude Code: no settings.json — nothing to remove.');
+        return 0;
+    }
+    const removed = removeHooksFrom(settings);
+    if (removed > 0)
+        writeJsonFile(settingsPath, settings);
+    out(o, `✓ Claude Code: removed ${removed} Nocville hook(s) from ${settingsPath}`);
+    return removed;
+}
+//# sourceMappingURL=setup.js.map

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