@nocville/npc 0.0.0-stage → 0.2.1

package/dist/cjs/npcs/codex/watcher.js

@@ -0,0 +1,361 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodexWatcher = void 0;
+exports.recentDayDirs = recentDayDirs;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_1 = require("@nocville/node");
+const logger_js_1 = require("../../core/logger.js");
+const session_filter_js_1 = require("../../core/session-filter.js");
+const session_js_1 = require("../agent-common/session.js");
+const defaults_js_1 = require("./defaults.js");
+const hook_handler_js_1 = require("./hook-handler.js");
+const rollout_js_1 = require("./rollout.js");
+const pad = (n) => String(n).padStart(2, '0');
+/** Day directories to scan: today and yesterday (local time, like Codex). */
+function recentDayDirs(root, now) {
+    const out = [];
+    for (const offset of [0, 1]) {
+        const d = new Date(now - offset * 24 * 60 * 60 * 1000);
+        out.push((0, node_path_1.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 = (0, node_fs_1.openSync)(file, 'r');
+    try {
+        const chunk = Buffer.alloc(64 * 1024);
+        let acc = '';
+        let pos = 0;
+        while (pos < maxBytes) {
+            const n = (0, node_fs_1.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 {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+function readRange(file, start, end) {
+    if (end <= start)
+        return '';
+    const fd = (0, node_fs_1.openSync)(file, 'r');
+    try {
+        const buf = Buffer.alloc(end - start);
+        const n = (0, node_fs_1.readSync)(fd, buf, 0, buf.length, start);
+        return buf.subarray(0, n).toString('utf-8');
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+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 ?? defaults_js_1.CODEX_DEFAULTS.sessionsDir;
+        this.pollMs = opts.pollMs ?? defaults_js_1.CODEX_DEFAULTS.pollMs;
+        this.idleTimeoutMs = opts.idleTimeoutMs ?? defaults_js_1.CODEX_DEFAULTS.idleTimeoutMs;
+        this.includeExec = opts.includeExec ?? false;
+        this.minPushGapMs = opts.minPushGapMs ?? defaults_js_1.CODEX_DEFAULTS.minPushGapMs;
+        this.hookStateDir = opts.hookStateDir ?? hook_handler_js_1.CODEX_ADAPTER.stateDir;
+        this.now = opts.now ?? Date.now;
+        this.logger = new logger_js_1.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() {
+        (0, node_fs_1.mkdirSync)(this.hookStateDir, { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(this.hookStateDir, `watcher-${process.pid}.pid`), String(process.pid), {
+            mode: 0o600,
+        });
+        if (!(0, node_fs_1.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() {
+        (0, node_fs_1.rmSync)((0, node_path_1.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 = (0, node_fs_1.readdirSync)(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const name of files) {
+                if (!name.startsWith('rollout-') || !name.endsWith('.jsonl'))
+                    continue;
+                const file = (0, node_path_1.join)(dir, name);
+                let st;
+                try {
+                    st = (0, node_fs_1.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 > defaults_js_1.CODEX_DEFAULTS.maxReadBytes) {
+                            // Huge burst (rollouts can reach hundreds of MB): jump to the tail.
+                            tracked.offset = st.size - defaults_js_1.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 = (0, rollout_js_1.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: (0, hook_handler_js_1.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 - defaults_js_1.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 = (0, rollout_js_1.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 = (0, session_js_1.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 = (0, hook_handler_js_1.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 (0, node_fs_1.existsSync)((0, session_js_1.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 verdict = (0, session_filter_js_1.sessionPublishDecision)(this.opts.sessionFilter ?? (0, session_filter_js_1.loadSessionFilter)(), {
+            projectDir: s.state.projectDir,
+            name: s.state.name,
+        });
+        if (!verdict.publish) {
+            // Filtered out by sessions.json: never show it, and remove it if it was showing.
+            s.pushedRev = rev;
+            if (s.spawned) {
+                s.spawned = false;
+                const offline = { ...s.state, offline: true };
+                await this.send(s.state.serviceId, (0, session_js_1.buildAgentPayload)(hook_handler_js_1.CODEX_ADAPTER, offline, this.config));
+            }
+            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, (0, session_js_1.buildAgentPayload)(hook_handler_js_1.CODEX_ADAPTER, s.state, this.config));
+    }
+    async despawn(s) {
+        if (this.hooksOwn(s.state.sessionId) || !s.spawned)
+            return;
+        const offline = { ...s.state, offline: true };
+        await this.send(s.state.serviceId, (0, session_js_1.buildAgentPayload)(hook_handler_js_1.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 node_1.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 });
+        }
+    }
+}
+exports.CodexWatcher = CodexWatcher;
+//# sourceMappingURL=watcher.js.map

package/dist/cjs/npcs/cursor/defaults.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cursorHome = exports.CURSOR_DEFAULTS = void 0;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+exports.CURSOR_DEFAULTS = {
+    stateDir: (0, node_path_1.join)((0, node_os_1.tmpdir)(), 'nocville-cursor'),
+    stateFileMaxAge: 24 * 60 * 60 * 1000,
+    heartbeatSeconds: 90,
+    minPushGapMs: 1500,
+    hookTimeoutSeconds: 10,
+};
+const cursorHome = () => (0, node_path_1.join)((0, node_os_1.homedir)(), '.cursor');
+exports.cursorHome = cursorHome;
+//# sourceMappingURL=defaults.js.map

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

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURSOR_HOOK_SPEC = exports.CURSOR_ADAPTER = void 0;
+exports.cursorServiceId = cursorServiceId;
+exports.handleCursorHookEvent = handleCursorHookEvent;
+const node_crypto_1 = require("node:crypto");
+const activity_js_1 = require("../agent-common/activity.js");
+const hook_runner_js_1 = require("../agent-common/hook-runner.js");
+const session_js_1 = require("../agent-common/session.js");
+const state_machine_js_1 = require("../claude-code/state-machine.js");
+const defaults_js_1 = require("./defaults.js");
+const normalize_js_1 = require("./normalize.js");
+exports.CURSOR_ADAPTER = {
+    command: 'cursor',
+    label: 'Cursor',
+    family: 'cursor',
+    stateDir: defaults_js_1.CURSOR_DEFAULTS.stateDir,
+    heartbeatSeconds: 90,
+    processNames: [],
+};
+function cursorServiceId(sessionId, cwd) {
+    return (0, session_js_1.sanitizeServiceId)(`cursor-${(0, session_js_1.projectNameOf)(cwd)}-${sessionId.slice(0, 8)}`);
+}
+exports.CURSOR_HOOK_SPEC = {
+    adapter: exports.CURSOR_ADAPTER,
+    serviceIdFor: cursorServiceId,
+    transition: (event, previous) => event.hook_event_name === 'PostToolUse'
+        ? {
+            state: 'WORKING',
+            status: 'healthy',
+            mood: 'happy',
+            activity: (0, activity_js_1.describeToolUse)(event.tool_name, event.tool_input, event.cwd),
+        }
+        : (0, state_machine_js_1.claudeTransition)(event, previous),
+    deliveryIdentity: (event) => ({
+        source: event['nocvilleHookSource'] === 'third-party' ? 'third-party' : 'native',
+        key: (0, node_crypto_1.createHash)('sha256')
+            .update(JSON.stringify([
+            event.hook_event_name,
+            event['generation_id'],
+            (0, activity_js_1.describeToolUse)(event.tool_name, event.tool_input, event.cwd),
+        ]))
+            .digest('hex'),
+    }),
+};
+async function handleCursorHookEvent(config, rawInput, opts = {}, source = 'native') {
+    try {
+        const input = rawInput ?? (0, hook_runner_js_1.readStdin)();
+        const event = typeof input === 'string' ? JSON.parse(input) : input;
+        if (!event || typeof event !== 'object' || Array.isArray(event))
+            return;
+        await (0, hook_runner_js_1.runAgentHook)(exports.CURSOR_HOOK_SPEC, config, {
+            ...(0, normalize_js_1.normalizeCursorEvent)(event),
+            nocvilleHookSource: source,
+        }, { minPushGapMs: defaults_js_1.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/cjs/npcs/cursor/index.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURSOR_TO_CANON = exports.normalizeCursorEvent = exports.isCursorInvocation = exports.CURSOR_HOOK_EVENTS = exports.installCursorHooksInto = exports.uninstallCursorHooks = exports.setupCursorHooks = exports.handleCursorHookEvent = exports.cursorServiceId = exports.CURSOR_ADAPTER = exports.CURSOR_DEFAULTS = void 0;
+exports.handleCursorCommand = handleCursorCommand;
+const config_js_1 = require("../../core/config.js");
+const hook_runner_js_1 = require("../agent-common/hook-runner.js");
+const watchdog_js_1 = require("../agent-common/watchdog.js");
+const session_js_1 = require("../agent-common/session.js");
+const defaults_js_1 = require("./defaults.js");
+const hook_handler_js_1 = require("./hook-handler.js");
+const setup_js_1 = require("./setup.js");
+var defaults_js_2 = require("./defaults.js");
+Object.defineProperty(exports, "CURSOR_DEFAULTS", { enumerable: true, get: function () { return defaults_js_2.CURSOR_DEFAULTS; } });
+var hook_handler_js_2 = require("./hook-handler.js");
+Object.defineProperty(exports, "CURSOR_ADAPTER", { enumerable: true, get: function () { return hook_handler_js_2.CURSOR_ADAPTER; } });
+Object.defineProperty(exports, "cursorServiceId", { enumerable: true, get: function () { return hook_handler_js_2.cursorServiceId; } });
+Object.defineProperty(exports, "handleCursorHookEvent", { enumerable: true, get: function () { return hook_handler_js_2.handleCursorHookEvent; } });
+var setup_js_2 = require("./setup.js");
+Object.defineProperty(exports, "setupCursorHooks", { enumerable: true, get: function () { return setup_js_2.setupCursorHooks; } });
+Object.defineProperty(exports, "uninstallCursorHooks", { enumerable: true, get: function () { return setup_js_2.uninstallCursorHooks; } });
+Object.defineProperty(exports, "installCursorHooksInto", { enumerable: true, get: function () { return setup_js_2.installCursorHooksInto; } });
+Object.defineProperty(exports, "CURSOR_HOOK_EVENTS", { enumerable: true, get: function () { return setup_js_2.CURSOR_HOOK_EVENTS; } });
+/**
+ * cursor subcommands: setup | uninstall | hook | flush | watchdog | cleanup.
+ * All hooks and detached helpers stay silent.
+ */
+async function handleCursorCommand(opts) {
+    const { subcommand, config, flags } = opts;
+    switch (subcommand) {
+        case 'setup': {
+            if (flags['uninstall']) {
+                (0, setup_js_1.uninstallCursorHooks)();
+                break;
+            }
+            const ok = (0, setup_js_1.setupCursorHooks)({
+                apiUrl: (0, config_js_1.stringFlag)(flags, 'api-url') ?? process.env['NOCVILLE_API_URL'],
+                apiKey: (0, config_js_1.stringFlag)(flags, 'api-key') ?? process.env['NOCVILLE_API_KEY'],
+                map: (0, config_js_1.stringFlag)(flags, 'map'),
+                cliPath: process.argv[1],
+            });
+            if (!ok)
+                process.exitCode = 1;
+            break;
+        }
+        case 'uninstall':
+            (0, setup_js_1.uninstallCursorHooks)();
+            break;
+        case 'hook':
+            await (0, hook_handler_js_1.handleCursorHookEvent)(config, (0, hook_runner_js_1.readStdin)(), { mode: 'detach' });
+            break;
+        case 'watchdog':
+            await (0, watchdog_js_1.runWatchdog)(hook_handler_js_1.CURSOR_ADAPTER, config, opts.args?.[0]);
+            break;
+        case 'flush':
+            await (0, hook_runner_js_1.runFlushCommand)(hook_handler_js_1.CURSOR_ADAPTER, config, opts.args?.[0], (0, config_js_1.numberFlag)(flags, 'delay'), flags['stats'] === true);
+            break;
+        case 'cleanup': {
+            const removed = await (0, session_js_1.cleanupSessionStates)(defaults_js_1.CURSOR_DEFAULTS.stateDir, defaults_js_1.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;
+    }
+}
+var normalize_js_1 = require("./normalize.js");
+Object.defineProperty(exports, "isCursorInvocation", { enumerable: true, get: function () { return normalize_js_1.isCursorInvocation; } });
+Object.defineProperty(exports, "normalizeCursorEvent", { enumerable: true, get: function () { return normalize_js_1.normalizeCursorEvent; } });
+Object.defineProperty(exports, "CURSOR_TO_CANON", { enumerable: true, get: function () { return normalize_js_1.CURSOR_TO_CANON; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/npcs/cursor/normalize.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURSOR_TO_CANON = void 0;
+exports.isCursorInvocation = isCursorInvocation;
+exports.normalizeCursorEvent = normalizeCursorEvent;
+exports.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',
+};
+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. */
+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: exports.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/cjs/npcs/cursor/setup.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURSOR_HOOK_EVENTS = void 0;
+exports.cursorSettingsPath = cursorSettingsPath;
+exports.installCursorHooksInto = installCursorHooksInto;
+exports.buildCursorHookCommand = buildCursorHookCommand;
+exports.setupCursorHooks = setupCursorHooks;
+exports.uninstallCursorHooks = uninstallCursorHooks;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const user_config_js_1 = require("../../core/user-config.js");
+const hook_settings_js_1 = require("../agent-common/hook-settings.js");
+const shim_js_1 = require("../agent-common/shim.js");
+const runtime_js_1 = require("../agent-common/runtime.js");
+const defaults_js_1 = require("./defaults.js");
+/** Telemetry hooks only; model output and prompt text never enter Nocville. */
+exports.CURSOR_HOOK_EVENTS = [
+    'sessionStart',
+    'sessionEnd',
+    'beforeSubmitPrompt',
+    'postToolUse',
+    'postToolUseFailure',
+    'afterFileEdit',
+    'stop',
+    'subagentStop',
+    'preCompact',
+];
+function cursorSettingsPath() {
+    return (0, node_path_1.join)((0, defaults_js_1.cursorHome)(), 'hooks.json');
+}
+/** Install the nocville group into every Cursor event. Mutates `file`. */
+function installCursorHooksInto(file, command, opts = {}) {
+    const migrated = (0, hook_settings_js_1.removeHookGroups)(file);
+    file.version = 1;
+    file.hooks ??= {};
+    for (const event of exports.CURSOR_HOOK_EVENTS) {
+        const existing = Array.isArray(file.hooks[event]) ? file.hooks[event] : [];
+        file.hooks[event] = [
+            ...existing,
+            { command, timeout: opts.timeout ?? defaults_js_1.CURSOR_DEFAULTS.hookTimeoutSeconds },
+        ];
+    }
+    return { migrated, installed: exports.CURSOR_HOOK_EVENTS.length };
+}
+function buildCursorHookCommand(_cliPath) {
+    return (0, hook_settings_js_1.buildShimHookCommand)('cursor');
+}
+function out(opts, msg) {
+    if (!opts.quiet)
+        console.log(msg);
+}
+/** Merge into Cursor settings, preserving user hooks and a one-time backup. */
+function setupCursorHooks(opts = {}) {
+    const settingsPath = opts.settingsPath ?? cursorSettingsPath();
+    const dir = (0, node_path_1.join)(settingsPath, '..');
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        console.error(`${dir} does not exist — is Cursor installed? Skipping Cursor setup.`);
+        return false;
+    }
+    const file = (0, hook_settings_js_1.readJsonFile)(settingsPath);
+    if (file === null ||
+        (file.version !== undefined && file.version !== 1) ||
+        (file.hooks !== undefined &&
+            (!file.hooks || typeof file.hooks !== 'object' || Array.isArray(file.hooks)))) {
+        console.error(`Unsupported or invalid Cursor hook settings in ${settingsPath}; no settings changed.`);
+        return false;
+    }
+    const creds = (0, user_config_js_1.persistCredentials)(opts);
+    const resolved = (0, hook_settings_js_1.resolveCliPath)(opts.cliPath);
+    const cliPath = (0, runtime_js_1.ensureStableCliPath)(resolved);
+    (0, shim_js_1.installHookShim)((0, hook_settings_js_1.stableNodePath)(), cliPath);
+    const { installed } = installCursorHooksInto(file, buildCursorHookCommand(cliPath), {
+        timeout: defaults_js_1.CURSOR_DEFAULTS.hookTimeoutSeconds,
+    });
+    (0, hook_settings_js_1.writeJsonFile)(settingsPath, file);
+    out(opts, `✓ Cursor: installed Nocville hooks for ${installed} events in ${settingsPath}`);
+    out(opts, `  Hook runs: ${process.execPath} ${cliPath}`);
+    out(opts, `  API: ${creds.apiUrl ?? 'https://nocville.com'}  key: ${(0, user_config_js_1.maskKey)(creds.apiKey)}`);
+    if (!creds.apiKey) {
+        out(opts, '  ⚠ No API key saved yet — run: nocville-npc init --api-key=<your team key>');
+    }
+    return true;
+}
+/** Remove all Nocville hooks from `~/.cursor/hooks.json`. */
+function uninstallCursorHooks(opts = {}) {
+    const settingsPath = opts.settingsPath ?? cursorSettingsPath();
+    const file = (0, hook_settings_js_1.readJsonFile)(settingsPath);
+    if (!file || !(0, node_fs_1.existsSync)(settingsPath)) {
+        out(opts, 'Cursor: no hooks.json — nothing to remove.');
+        return 0;
+    }
+    const removed = (0, hook_settings_js_1.removeHookGroups)(file);
+    if (removed > 0)
+        (0, hook_settings_js_1.writeJsonFile)(settingsPath, file);
+    out(opts, `✓ Cursor: removed ${removed} Nocville hook(s) from ${settingsPath}`);
+    return removed;
+}
+//# sourceMappingURL=setup.js.map

package/dist/cjs/npcs/gemini/defaults.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.geminiHome = exports.GEMINI_DEFAULTS = void 0;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+exports.GEMINI_DEFAULTS = {
+    stateDir: (0, node_path_1.join)((0, node_os_1.tmpdir)(), 'nocville-gemini'),
+    stateFileMaxAge: 24 * 60 * 60 * 1000,
+    heartbeatSeconds: 90,
+    minPushGapMs: 1500,
+    hookTimeoutMs: 5000,
+};
+const geminiHome = () => (0, node_path_1.join)((0, node_os_1.homedir)(), '.gemini');
+exports.geminiHome = geminiHome;
+//# sourceMappingURL=defaults.js.map