@nocville/npc 0.0.0-stage → 0.2.0

package/dist/npcs/codex/watcher.js

@@ -0,0 +1,341 @@
+import { closeSync, existsSync, mkdirSync, openSync, readSync, readdirSync, statSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { NocvilleClient } from '@nocville/node';
+import { Logger } from '../../core/logger.js';
+import { buildAgentPayload, pushHistory, stateFilePath } from '../agent-common/session.js';
+import { CODEX_DEFAULTS } from './defaults.js';
+import { CODEX_ADAPTER, codexServiceId } from './hook-handler.js';
+import { parseRolloutLine } from './rollout.js';
+const pad = (n) => String(n).padStart(2, '0');
+/** Day directories to scan: today and yesterday (local time, like Codex). */
+export function recentDayDirs(root, now) {
+    const out = [];
+    for (const offset of [0, 1]) {
+        const d = new Date(now - offset * 24 * 60 * 60 * 1000);
+        out.push(join(root, String(d.getFullYear()), pad(d.getMonth() + 1), pad(d.getDate())));
+    }
+    return out;
+}
+/** Read the first line of a file (session_meta can be tens of KB). */
+function readFirstLine(file, maxBytes = 4 * 1024 * 1024) {
+    const fd = openSync(file, 'r');
+    try {
+        const chunk = Buffer.alloc(64 * 1024);
+        let acc = '';
+        let pos = 0;
+        while (pos < maxBytes) {
+            const n = readSync(fd, chunk, 0, chunk.length, pos);
+            if (n <= 0)
+                break;
+            const text = chunk.subarray(0, n).toString('utf-8');
+            const nl = text.indexOf('\n');
+            if (nl >= 0)
+                return acc + text.slice(0, nl);
+            acc += text;
+            pos += n;
+        }
+        return acc;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readRange(file, start, end) {
+    if (end <= start)
+        return '';
+    const fd = openSync(file, 'r');
+    try {
+        const buf = Buffer.alloc(end - start);
+        const n = readSync(fd, buf, 0, buf.length, start);
+        return buf.subarray(0, n).toString('utf-8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export class CodexWatcher {
+    config;
+    opts;
+    sessionsDir;
+    pollMs;
+    idleTimeoutMs;
+    includeExec;
+    minPushGapMs;
+    hookStateDir;
+    now;
+    logger;
+    sessions = new Map();
+    interval;
+    clients = new Map();
+    constructor(config, opts = {}) {
+        this.config = config;
+        this.opts = opts;
+        this.sessionsDir = opts.sessionsDir ?? CODEX_DEFAULTS.sessionsDir;
+        this.pollMs = opts.pollMs ?? CODEX_DEFAULTS.pollMs;
+        this.idleTimeoutMs = opts.idleTimeoutMs ?? CODEX_DEFAULTS.idleTimeoutMs;
+        this.includeExec = opts.includeExec ?? false;
+        this.minPushGapMs = opts.minPushGapMs ?? CODEX_DEFAULTS.minPushGapMs;
+        this.hookStateDir = opts.hookStateDir ?? CODEX_ADAPTER.stateDir;
+        this.now = opts.now ?? Date.now;
+        this.logger = new Logger('codex-watch', config.debug);
+    }
+    /** Active (non-ignored) sessions — exposed for tests/diagnostics. */
+    activeSessions() {
+        return [...this.sessions.values()].filter((s) => !s.ignored).map((s) => s.state);
+    }
+    async start() {
+        mkdirSync(this.hookStateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(join(this.hookStateDir, `watcher-${process.pid}.pid`), String(process.pid), {
+            mode: 0o600,
+        });
+        if (!existsSync(this.sessionsDir)) {
+            this.logger.warn(`${this.sessionsDir} not found yet — waiting for Codex sessions`);
+        }
+        this.logger.info(`Watching Codex sessions in ${this.sessionsDir}`);
+        await this.tick();
+        this.interval = setInterval(() => {
+            void this.tick().catch((err) => this.logger.warn('Watch tick failed', { error: err?.message }));
+        }, this.pollMs);
+        const onSignal = () => {
+            void this.stop().then(() => process.exit(0));
+        };
+        process.once('SIGINT', onSignal);
+        process.once('SIGTERM', onSignal);
+    }
+    /** Stop polling and despawn every live session. */
+    async stop() {
+        rmSync(join(this.hookStateDir, `watcher-${process.pid}.pid`), { force: true });
+        if (this.interval)
+            clearInterval(this.interval);
+        this.interval = undefined;
+        const live = [...this.sessions.values()].filter((s) => !s.ignored && s.spawned);
+        await Promise.all(live.map((s) => this.despawn(s)));
+        this.sessions.clear();
+    }
+    /** One poll: discover files, read appended lines, push, expire quiet sessions. */
+    async tick() {
+        const now = this.now();
+        for (const dir of recentDayDirs(this.sessionsDir, now)) {
+            let files;
+            try {
+                files = readdirSync(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const name of files) {
+                if (!name.startsWith('rollout-') || !name.endsWith('.jsonl'))
+                    continue;
+                const file = join(dir, name);
+                let st;
+                try {
+                    st = statSync(file);
+                }
+                catch {
+                    continue;
+                }
+                const tracked = this.sessions.get(file);
+                if (!tracked) {
+                    if (now - st.mtimeMs > this.idleTimeoutMs)
+                        continue;
+                    this.discover(file, st.size, st.mtimeMs);
+                }
+                else if (st.size > tracked.offset) {
+                    if (!tracked.ignored) {
+                        if (st.size - tracked.offset > CODEX_DEFAULTS.maxReadBytes) {
+                            // Huge burst (rollouts can reach hundreds of MB): jump to the tail.
+                            tracked.offset = st.size - CODEX_DEFAULTS.initialTailBytes;
+                            tracked.partial = '';
+                            this.readAppended(tracked, st.size, true);
+                        }
+                        else {
+                            this.readAppended(tracked, st.size);
+                        }
+                    }
+                    else {
+                        tracked.offset = st.size;
+                    }
+                    tracked.lastGrowthAt = now;
+                }
+                else if (st.size < tracked.offset) {
+                    // Truncated/rewritten: restart from the top.
+                    tracked.offset = 0;
+                    tracked.partial = '';
+                }
+            }
+        }
+        const pushes = [];
+        for (const [file, s] of this.sessions) {
+            if (s.ignored) {
+                if (now - s.lastGrowthAt > this.idleTimeoutMs * 2)
+                    this.sessions.delete(file);
+                continue;
+            }
+            if (now - s.lastGrowthAt > this.idleTimeoutMs) {
+                if (s.spawned)
+                    pushes.push(this.despawn(s));
+                this.sessions.delete(file);
+                continue;
+            }
+            pushes.push(this.maybePush(s));
+        }
+        await Promise.all(pushes);
+    }
+    discover(file, size, mtimeMs) {
+        let meta = null;
+        try {
+            const sig = parseRolloutLine(readFirstLine(file));
+            if (sig?.kind === 'meta')
+                meta = sig;
+        }
+        catch {
+            meta = null;
+        }
+        const sessionId = meta?.sessionId ?? file;
+        const cwd = meta?.cwd ?? '';
+        const ignored = !meta || meta.subagent || (meta.exec && !this.includeExec);
+        const tracked = {
+            file,
+            offset: 0,
+            partial: '',
+            lastGrowthAt: Math.min(this.now(), mtimeMs),
+            ignored,
+            spawned: false,
+            lastPushAt: 0,
+            pushedRev: 0,
+            state: {
+                sessionId,
+                serviceId: codexServiceId(sessionId, cwd || 'codex'),
+                state: 'IDLE',
+                projectDir: cwd,
+                lastEvent: 'discover',
+                lastUpdate: this.now(),
+                activity: ['Ready for a task'],
+                status: 'healthy',
+                mood: 'idle',
+                rev: 1,
+            },
+        };
+        this.sessions.set(file, tracked);
+        if (ignored) {
+            tracked.offset = size;
+            return;
+        }
+        // Replay only the tail of a long-running session to establish its state.
+        const start = Math.max(0, size - CODEX_DEFAULTS.initialTailBytes);
+        tracked.offset = start;
+        tracked.partial = '';
+        const skipFirst = start > 0;
+        this.readAppended(tracked, size, skipFirst);
+        this.logger.info(`Tracking Codex session ${sessionId} (${tracked.state.projectDir || '?'})`);
+    }
+    readAppended(s, size, skipFirstLine = false) {
+        let text;
+        try {
+            text = s.partial + readRange(s.file, s.offset, size);
+        }
+        catch {
+            return;
+        }
+        s.offset = size;
+        const lines = text.split('\n');
+        s.partial = lines.pop() ?? '';
+        if (skipFirstLine)
+            lines.shift();
+        for (const line of lines) {
+            const sig = parseRolloutLine(line, s.state.projectDir || undefined);
+            if (sig)
+                this.apply(s, sig);
+        }
+    }
+    /** Reduce one signal into the session state. Exposed via tick for tests. */
+    apply(s, sig) {
+        const st = s.state;
+        const set = (phase, activity, mood) => {
+            const history = pushHistory(st.activity, activity);
+            if (st.state === phase && history[0] === st.activity?.[0])
+                return;
+            st.state = phase;
+            st.activity = history;
+            st.status = phase === 'WAITING' ? 'warning' : 'healthy';
+            st.mood = mood;
+            st.lastUpdate = this.now();
+            st.rev = (st.rev ?? 0) + 1;
+        };
+        switch (sig.kind) {
+            case 'meta':
+                return;
+            case 'cwd':
+                if (sig.cwd && sig.cwd !== st.projectDir) {
+                    st.projectDir = sig.cwd;
+                    if (!s.spawned)
+                        st.serviceId = codexServiceId(st.sessionId, sig.cwd);
+                    st.rev = (st.rev ?? 0) + 1;
+                }
+                return;
+            case 'working':
+                return set('WORKING', sig.activity, 'happy');
+            case 'waiting':
+                return set('WAITING', sig.activity, 'concerned');
+            case 'idle':
+                return set('IDLE', sig.activity, 'idle');
+        }
+    }
+    hooksOwn(sessionId) {
+        return existsSync(stateFilePath(this.hookStateDir, sessionId));
+    }
+    async maybePush(s) {
+        const rev = s.state.rev ?? 0;
+        if (rev <= s.pushedRev)
+            return;
+        if (this.hooksOwn(s.state.sessionId)) {
+            s.pushedRev = rev;
+            return;
+        }
+        const now = this.now();
+        if (s.spawned && now - s.lastPushAt < this.minPushGapMs) {
+            // Coalesce; the next tick after the gap pushes the latest state.
+            return;
+        }
+        s.pushedRev = rev;
+        s.lastPushAt = now;
+        s.spawned = true;
+        await this.send(s.state.serviceId, buildAgentPayload(CODEX_ADAPTER, s.state, this.config));
+    }
+    async despawn(s) {
+        if (this.hooksOwn(s.state.sessionId))
+            return;
+        const offline = { ...s.state, offline: true };
+        await this.send(s.state.serviceId, buildAgentPayload(CODEX_ADAPTER, offline, this.config));
+        this.logger.info(`Codex session ${s.state.sessionId} ended`);
+    }
+    async send(serviceId, payload) {
+        try {
+            if (this.opts.push) {
+                await this.opts.push(serviceId, payload);
+                return;
+            }
+            if (!this.config.apiKey)
+                return;
+            let client = this.clients.get(serviceId);
+            if (!client) {
+                client = new NocvilleClient({
+                    apiUrl: this.config.apiUrl,
+                    apiKey: this.config.apiKey,
+                    serviceId,
+                    timeout: 5000,
+                    retries: 1,
+                    debug: this.config.debug,
+                });
+                this.clients.set(serviceId, client);
+            }
+            const result = await client.pushStatus(payload);
+            if (!result.success)
+                this.logger.warn('Push failed', { serviceId, error: result.error });
+        }
+        catch (err) {
+            this.logger.warn('Push error', { serviceId, error: err?.message });
+        }
+    }
+}
+//# sourceMappingURL=watcher.js.map

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

@@ -0,0 +1,9 @@
+export declare const CURSOR_DEFAULTS: {
+    stateDir: string;
+    stateFileMaxAge: number;
+    heartbeatSeconds: number;
+    minPushGapMs: number;
+    hookTimeoutSeconds: number;
+};
+export declare const cursorHome: () => string;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/cursor/defaults.js

@@ -0,0 +1,11 @@
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const CURSOR_DEFAULTS = {
+    stateDir: join(tmpdir(), 'nocville-cursor'),
+    stateFileMaxAge: 24 * 60 * 60 * 1000,
+    heartbeatSeconds: 90,
+    minPushGapMs: 1500,
+    hookTimeoutSeconds: 10,
+};
+export const cursorHome = () => join(homedir(), '.cursor');
+//# sourceMappingURL=defaults.js.map

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

@@ -0,0 +1,8 @@
+import type { NpcConfig } from '../../core/types.js';
+import type { AgentHookEvent, AgentHookSpec, HookRunOptions } from '../agent-common/hook-runner.js';
+import type { AgentAdapter } from '../agent-common/session.js';
+export declare const CURSOR_ADAPTER: AgentAdapter;
+export declare function cursorServiceId(sessionId: string, cwd: string): string;
+export declare const CURSOR_HOOK_SPEC: AgentHookSpec;
+export declare function handleCursorHookEvent(config: NpcConfig, rawInput?: string | AgentHookEvent, opts?: HookRunOptions, source?: 'native' | 'third-party'): Promise<void>;
+//# sourceMappingURL=hook-handler.d.ts.map

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

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import { describeToolUse } from '../agent-common/activity.js';
+import { readStdin, runAgentHook } from '../agent-common/hook-runner.js';
+import { projectNameOf, sanitizeServiceId } from '../agent-common/session.js';
+import { claudeTransition } from '../claude-code/state-machine.js';
+import { CURSOR_DEFAULTS } from './defaults.js';
+import { normalizeCursorEvent } from './normalize.js';
+export const CURSOR_ADAPTER = {
+    command: 'cursor',
+    label: 'Cursor',
+    family: 'cursor',
+    stateDir: CURSOR_DEFAULTS.stateDir,
+    heartbeatSeconds: 90,
+    processNames: [],
+};
+export function cursorServiceId(sessionId, cwd) {
+    return sanitizeServiceId(`cursor-${projectNameOf(cwd)}-${sessionId.slice(0, 8)}`);
+}
+export const CURSOR_HOOK_SPEC = {
+    adapter: CURSOR_ADAPTER,
+    serviceIdFor: cursorServiceId,
+    transition: (event, previous) => event.hook_event_name === 'PostToolUse'
+        ? {
+            state: 'WORKING',
+            status: 'healthy',
+            mood: 'happy',
+            activity: describeToolUse(event.tool_name, event.tool_input, event.cwd),
+        }
+        : claudeTransition(event, previous),
+    deliveryIdentity: (event) => ({
+        source: event['nocvilleHookSource'] === 'third-party' ? 'third-party' : 'native',
+        key: createHash('sha256')
+            .update(JSON.stringify([
+            event.hook_event_name,
+            event['generation_id'],
+            describeToolUse(event.tool_name, event.tool_input, event.cwd),
+        ]))
+            .digest('hex'),
+    }),
+};
+export async function handleCursorHookEvent(config, rawInput, opts = {}, source = 'native') {
+    try {
+        const input = rawInput ?? readStdin();
+        const event = typeof input === 'string' ? JSON.parse(input) : input;
+        if (!event || typeof event !== 'object' || Array.isArray(event))
+            return;
+        await runAgentHook(CURSOR_HOOK_SPEC, config, {
+            ...normalizeCursorEvent(event),
+            nocvilleHookSource: source,
+        }, { minPushGapMs: CURSOR_DEFAULTS.minPushGapMs, ...opts });
+    }
+    catch {
+        /* Hook failures never affect Cursor. */
+    }
+    finally {
+        // A schema-neutral response, including malformed/failed direct invocations.
+        process.stdout.write('{}\n');
+    }
+}
+//# sourceMappingURL=hook-handler.js.map

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

@@ -0,0 +1,18 @@
+import type { NpcConfig } from '../../core/types.js';
+export { CURSOR_DEFAULTS } from './defaults.js';
+export { CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent } from './hook-handler.js';
+export { setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './setup.js';
+export type { CursorSetupOptions } from './setup.js';
+export interface CursorSubcommandOptions {
+    subcommand: string;
+    config: NpcConfig;
+    flags: Record<string, string | boolean>;
+    args?: string[];
+}
+/**
+ * cursor subcommands: setup | uninstall | hook | flush | watchdog | cleanup.
+ * All hooks and detached helpers stay silent.
+ */
+export declare function handleCursorCommand(opts: CursorSubcommandOptions): Promise<void>;
+export { isCursorInvocation, normalizeCursorEvent, CURSOR_TO_CANON } from './normalize.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/npcs/cursor/index.js

@@ -0,0 +1,57 @@
+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 { CURSOR_DEFAULTS } from './defaults.js';
+import { CURSOR_ADAPTER, handleCursorHookEvent } from './hook-handler.js';
+import { setupCursorHooks, uninstallCursorHooks } from './setup.js';
+export { CURSOR_DEFAULTS } from './defaults.js';
+export { CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent } from './hook-handler.js';
+export { setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './setup.js';
+/**
+ * cursor subcommands: setup | uninstall | hook | flush | watchdog | cleanup.
+ * All hooks and detached helpers stay silent.
+ */
+export async function handleCursorCommand(opts) {
+    const { subcommand, config, flags } = opts;
+    switch (subcommand) {
+        case 'setup': {
+            if (flags['uninstall']) {
+                uninstallCursorHooks();
+                break;
+            }
+            const ok = setupCursorHooks({
+                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':
+            uninstallCursorHooks();
+            break;
+        case 'hook':
+            await handleCursorHookEvent(config, readStdin(), { mode: 'detach' });
+            break;
+        case 'watchdog':
+            await runWatchdog(CURSOR_ADAPTER, config, opts.args?.[0]);
+            break;
+        case 'flush':
+            await runFlushCommand(CURSOR_ADAPTER, config, opts.args?.[0], numberFlag(flags, 'delay'), flags['stats'] === true);
+            break;
+        case 'cleanup': {
+            const removed = await cleanupSessionStates(CURSOR_DEFAULTS.stateDir, CURSOR_DEFAULTS.stateFileMaxAge);
+            console.log(`Cleanup complete: ${removed} stale file(s) removed`);
+            break;
+        }
+        default:
+            console.error(`Unknown cursor subcommand: ${subcommand}`);
+            console.error('Available subcommands: setup, uninstall, hook, cleanup');
+            process.exitCode = 1;
+    }
+}
+export { isCursorInvocation, normalizeCursorEvent, CURSOR_TO_CANON } from './normalize.js';
+//# sourceMappingURL=index.js.map

package/dist/npcs/cursor/normalize.d.ts

@@ -0,0 +1,6 @@
+import type { AgentHookEvent } from '../agent-common/hook-runner.js';
+export declare const CURSOR_TO_CANON: Record<string, string>;
+export declare function isCursorInvocation(event: AgentHookEvent): boolean;
+/** Copy only telemetry fields; never retain prompts, model responses or tool output. */
+export declare function normalizeCursorEvent(event: AgentHookEvent): AgentHookEvent;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/npcs/cursor/normalize.js

@@ -0,0 +1,49 @@
+export const CURSOR_TO_CANON = {
+    sessionStart: 'SessionStart',
+    sessionEnd: 'SessionEnd',
+    beforeSubmitPrompt: 'UserPromptSubmit',
+    preToolUse: 'PreToolUse',
+    postToolUse: 'PostToolUse',
+    postToolUseFailure: 'PostToolUseFailure',
+    beforeShellExecution: 'PreToolUse',
+    afterFileEdit: 'PostToolUse',
+    stop: 'Stop',
+    subagentStart: 'SubagentStart',
+    subagentStop: 'SubagentStop',
+    preCompact: 'PreCompact',
+};
+export function isCursorInvocation(event) {
+    const transcript = typeof event['transcript_path'] === 'string'
+        ? event['transcript_path'].replace(/\\/g, '/')
+        : '';
+    return (typeof event['cursor_version'] === 'string' ||
+        (typeof event['conversation_id'] === 'string' && !/(?:^|\/)\.claude(?:\/|$)/.test(transcript)));
+}
+/** Copy only telemetry fields; never retain prompts, model responses or tool output. */
+export function normalizeCursorEvent(event) {
+    const name = event.hook_event_name ?? event.event ?? '';
+    const roots = event['workspace_roots'];
+    const shell = name === 'beforeShellExecution';
+    const tools = {
+        Shell: 'Bash',
+        ReadFile: 'Read',
+        Write: 'Write',
+        StrReplace: 'Edit',
+        Grep: 'Grep',
+        Delete: 'Delete',
+        Task: 'Task',
+    };
+    return {
+        session_id: typeof event['conversation_id'] === 'string' ? event['conversation_id'] : event.session_id,
+        cwd: Array.isArray(roots) && typeof roots[0] === 'string' ? roots[0] : event.cwd,
+        hook_event_name: CURSOR_TO_CANON[name] ?? name,
+        tool_name: shell
+            ? 'Bash'
+            : event.tool_name?.startsWith('MCP:')
+                ? `mcp__cursor__${event.tool_name.slice(4)}`
+                : (tools[event.tool_name ?? ''] ?? event.tool_name),
+        tool_input: shell ? { command: event['command'] } : event.tool_input,
+        generation_id: typeof event['generation_id'] === 'string' ? event['generation_id'] : undefined,
+    };
+}
+//# sourceMappingURL=normalize.js.map

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

@@ -0,0 +1,29 @@
+import type { HooksFile } from '../agent-common/hook-settings.js';
+/** Telemetry hooks only; model output and prompt text never enter Nocville. */
+export declare const CURSOR_HOOK_EVENTS: string[];
+export declare function cursorSettingsPath(): string;
+export interface CursorSetupOptions {
+    apiUrl?: string;
+    apiKey?: string;
+    map?: string;
+    cliPath?: string;
+    /** Override ~/.cursor/hooks.json (tests). */
+    settingsPath?: string;
+    quiet?: boolean;
+}
+/** Install the nocville group into every Cursor event. Mutates `file`. */
+export declare function installCursorHooksInto(file: HooksFile, command: string, opts?: {
+    timeout?: number;
+}): {
+    migrated: number;
+    installed: number;
+};
+export declare function buildCursorHookCommand(_cliPath: string): string;
+/** Merge into Cursor settings, preserving user hooks and a one-time backup. */
+export declare function setupCursorHooks(opts?: CursorSetupOptions): boolean;
+/** Remove all Nocville hooks from `~/.cursor/hooks.json`. */
+export declare function uninstallCursorHooks(opts?: {
+    settingsPath?: string;
+    quiet?: boolean;
+}): number;
+//# sourceMappingURL=setup.d.ts.map