@nocville/npc 0.2.2 → 0.3.0

package/dist/cjs/core/pixel-art.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodePixelArt = encodePixelArt;
+exports.pixelArtFromPng = pixelArtFromPng;
+exports.pixelDevice = pixelDevice;
+const node_fs_1 = require("node:fs");
+const pngjs_1 = require("pngjs");
+/**
+ * Helpers for custom pixel-art companions (`screenType: 'pixel-device'`): your NPC's own
+ * device, sign or machine, drawn frameless beside it in the office.
+ *
+ * Art is 32 pixels per tile (a 2×3-tile device is 64×96, like the office furniture) and is
+ * sent as `pixel-image` screen data: a palette of up to 255 colours plus one byte per pixel.
+ * Fully transparent pixels (alpha < 128) become see-through, and several frames stacked top
+ * to bottom animate at `fps`. Push a new image whenever its state changes (e.g. an LED turns
+ * red); the server rate-limits pushes, so animate with frames rather than many pushes.
+ */
+/** Largest single screen-data value the API accepts (base64 pixels). */
+const MAX_VALUE = 220_000;
+const MAX_COLORS = 255;
+const MAX_FRAMES = 16;
+/** Encode RGBA frames as `pixel-image` screen data. Throws with a fix-it message. */
+function encodePixelArt(art) {
+    const { width, height, frames } = art;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1)
+        throw new Error('Pixel art needs a positive whole-number width and height.');
+    if (width > 192 || height > 192)
+        throw new Error(`Pixel art is ${width}×${height}; keep it within 192×192 (6×6 tiles).`);
+    if (frames.length < 1 || frames.length > MAX_FRAMES)
+        throw new Error(`Pixel art needs 1–${MAX_FRAMES} frames (got ${frames.length}).`);
+    const size = width * height;
+    for (const frame of frames)
+        if (frame.length !== size * 4)
+            throw new Error(`Each frame must be ${width}×${height} RGBA (${size * 4} bytes).`);
+    // Index 0 is reserved for transparency when any pixel is see-through.
+    const transparent = frames.some((f) => {
+        for (let i = 3; i < f.length; i += 4)
+            if (f[i] < 128)
+                return true;
+        return false;
+    });
+    const colors = new Map();
+    const palette = transparent ? [0, 0, 0] : [];
+    const pixels = Buffer.alloc(size * frames.length);
+    frames.forEach((frame, f) => {
+        for (let i = 0; i < size; i++) {
+            const r = frame[i * 4], g = frame[i * 4 + 1], b = frame[i * 4 + 2];
+            if (transparent && frame[i * 4 + 3] < 128) {
+                pixels[f * size + i] = 0;
+                continue;
+            }
+            const key = (r << 16) | (g << 8) | b;
+            let index = colors.get(key);
+            if (index === undefined) {
+                index = palette.length / 3;
+                if (index > MAX_COLORS)
+                    throw new Error(`Pixel art uses more than ${MAX_COLORS} colours; reduce the palette (pixel art usually needs 8–32).`);
+                colors.set(key, index);
+                palette.push(r, g, b);
+            }
+            pixels[f * size + i] = index;
+        }
+    });
+    const tokens = [`idx8`, `${width}x${height}`, `p${palette.length / 3}`];
+    if (transparent)
+        tokens.push('t0');
+    if (frames.length > 1) {
+        const fps = Math.min(12, Math.max(1, Math.round(art.fps ?? 4)));
+        tokens.push(`f${frames.length}`, `fps${fps}`);
+    }
+    const encoded = pixels.toString('base64');
+    if (encoded.length > MAX_VALUE)
+        throw new Error('Pixel art is too large to send; use fewer frames or a smaller size.');
+    return {
+        layout: 'pixel-image',
+        values: [
+            { label: 'fmt', value: tokens.join(';') },
+            { label: 'palette', value: Buffer.from(palette).toString('base64') },
+            { label: 'pixels', value: encoded },
+        ],
+    };
+}
+/**
+ * Load a PNG (path or bytes) as pixel-device screen data. For animation, stack frames
+ * top to bottom in one PNG and pass `frameHeight`.
+ */
+function pixelArtFromPng(png, opts = {}) {
+    const image = pngjs_1.PNG.sync.read(typeof png === 'string' ? (0, node_fs_1.readFileSync)(png) : png);
+    const frameHeight = opts.frameHeight ?? image.height;
+    if (frameHeight < 1 || image.height % frameHeight !== 0)
+        throw new Error(`PNG height ${image.height} is not a whole number of ${frameHeight}px frames.`);
+    const frameBytes = image.width * frameHeight * 4;
+    const frames = [];
+    for (let offset = 0; offset < image.data.length; offset += frameBytes)
+        frames.push(image.data.subarray(offset, offset + frameBytes));
+    return encodePixelArt({ width: image.width, height: frameHeight, frames, fps: opts.fps });
+}
+/**
+ * Companion declaration for a pixel device: `size` in tiles (art is 32px per tile).
+ * Freestanding by default so it sits on the floor next to the NPC's home.
+ */
+function pixelDevice(opts) {
+    return {
+        screenType: 'pixel-device',
+        size: { w: opts.w, h: opts.h },
+        placement: opts.placement ?? 'freestanding',
+        ...(opts.label ? { label: opts.label } : {}),
+    };
+}
+//# sourceMappingURL=pixel-art.js.map

package/dist/cjs/core/polling-npc.js

@@ -1,17 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PollingNPC = void 0;
+exports.PollingNPC = exports.MIN_POLL_INTERVAL_MS = void 0;
 const base_npc_js_1 = require("./base-npc.js");
+/**
+ * Lower bound for any poll interval, so a typo can't exhaust the API's
+ * per-service rate limit (60 pushes/min) or hammer the watched source.
+ */
+exports.MIN_POLL_INTERVAL_MS = 5000;
+/** How long `stop()` waits for an in-flight collection before pushing offline anyway. */
+const STOP_DRAIN_TIMEOUT_MS = 10_000;
 function clamp(n, min, max) {
     return Math.min(max, Math.max(min, n));
 }
 class PollingNPC extends base_npc_js_1.BaseNPC {
     timer = null;
-    collecting = false;
+    keepaliveTimer = null;
+    /** The running collection + push, if any (awaited by `onStop`). */
+    inflight = null;
+    /** A `collectNow()` arrived while a collection was in flight: run once more after it. */
+    rerunRequested = false;
+    /** The last successfully pushed cycle, replayed (without its screen) by the keepalive. */
+    lastPushed = null;
+    lastPushAt = 0;
     pollInterval;
     constructor(config) {
         super(config);
-        this.pollInterval = config.pollInterval ?? 15000;
+        const requested = config.pollInterval ?? 15000;
+        this.pollInterval = Number.isFinite(requested)
+            ? Math.max(exports.MIN_POLL_INTERVAL_MS, requested)
+            : 15000;
     }
     /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
     get heartbeatSeconds() {
@@ -20,14 +37,22 @@ class PollingNPC extends base_npc_js_1.BaseNPC {
     async onStart() {
         // Collect immediately on start
         await this.runCollection();
+        // Stopped while the first collection ran: don't arm timers nobody will clear.
+        if (this.state !== 'running')
+            return;
         // Then on interval
         this.timer = setInterval(() => {
             void this.runCollection();
         }, this.pollInterval);
-        // For slow pollers, keep the NPC alive with a lightweight heartbeat between
-        // collections so it never falsely goes stale mid-interval.
-        if (this.pollInterval > 60_000) {
-            this.client.startHeartbeat(30_000);
+        // Only very slow pollers (> heartbeatSeconds, i.e. > 30 min given the clamp)
+        // could go stale between collections. Keep them alive by replaying the
+        // last cycle. The SDK's own heartbeat is not used: it omits `map`, `name`
+        // and `alertConfig`, so it would spawn a twin on the team's default map.
+        const heartbeatMs = this.heartbeatSeconds * 1000;
+        if (this.pollInterval > heartbeatMs) {
+            this.keepaliveTimer = setInterval(() => {
+                void this.keepalive(heartbeatMs);
+            }, heartbeatMs);
         }
     }
     async onStop() {
@@ -35,29 +60,89 @@ class PollingNPC extends base_npc_js_1.BaseNPC {
             clearInterval(this.timer);
             this.timer = null;
         }
-        this.client.stopHeartbeat();
+        if (this.keepaliveTimer) {
+            clearInterval(this.keepaliveTimer);
+            this.keepaliveTimer = null;
+        }
+        this.rerunRequested = false;
+        // Let an in-flight push land before the offline push, so it can't arrive
+        // afterwards and respawn the NPC. Bounded: a hung collector never blocks exit.
+        if (this.inflight) {
+            let timeout;
+            await Promise.race([
+                this.inflight,
+                new Promise((resolve) => {
+                    timeout = setTimeout(resolve, STOP_DRAIN_TIMEOUT_MS);
+                }),
+            ]);
+            clearTimeout(timeout);
+        }
     }
-    async runCollection() {
+    /**
+     * Collect and push now instead of waiting for the next tick — for NPCs that
+     * also react to events (e.g. a fresh error line). Coalesces: if a collection
+     * is already running, exactly one more runs after it.
+     */
+    collectNow() {
         if (this.state !== 'running')
             return;
+        if (this.inflight) {
+            this.rerunRequested = true;
+            return;
+        }
+        void this.runCollection();
+    }
+    runCollection() {
+        if (this.state !== 'running')
+            return Promise.resolve();
         // Overlap guard: if a slow collector is still running, skip this tick rather
         // than stacking collections (load-bearing for screenshot/render collectors).
-        if (this.collecting) {
+        if (this.inflight) {
             this.logger.debug('Previous collection still in flight, skipping this tick');
-            return;
+            return this.inflight;
         }
-        this.collecting = true;
+        const run = this.collectAndPush().finally(() => {
+            this.inflight = null;
+            if (this.rerunRequested && this.state === 'running') {
+                this.rerunRequested = false;
+                void this.runCollection();
+            }
+        });
+        this.inflight = run;
+        return run;
+    }
+    async collectAndPush() {
         try {
             const metrics = await this.collect();
+            // Stopped mid-collection: never push after (or race) the offline push.
+            if (this.state !== 'running')
+                return;
             await this.pushMetrics(metrics);
+            this.lastPushed = metrics;
+            this.lastPushAt = Date.now();
         }
         catch (err) {
+            if (this.state !== 'running')
+                return; // teardown aborted the collector
             this.logger.error('Collection failed', {
                 error: err instanceof Error ? err.message : String(err),
             });
         }
-        finally {
-            this.collecting = false;
+    }
+    /** Replay the last cycle (minus its screen, which the server keeps) if nothing was pushed recently. */
+    async keepalive(heartbeatMs) {
+        if (this.state !== 'running' || this.inflight || !this.lastPushed)
+            return;
+        if (Date.now() - this.lastPushAt < heartbeatMs / 2)
+            return;
+        try {
+            await this.pushMetrics({ ...this.lastPushed, screenData: undefined });
+            this.lastPushAt = Date.now();
+        }
+        catch (err) {
+            this.logger.debug('Keepalive push failed', {
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     }
 }

package/dist/cjs/core/text.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.truncate = truncate;
+exports.sanitizeText = sanitizeText;
 /**
  * Truncate a string to at most `max` characters, appending an ellipsis when cut.
  * Used to keep messages and screen lines within API limits.
@@ -12,4 +13,16 @@ function truncate(s, max = 200) {
         return s.slice(0, Math.max(0, max));
     return s.slice(0, max - 1) + '…';
 }
+// C0/C1 controls (incl. ESC, so no terminal escapes) plus the bidi overrides,
+// isolates and marks that can visually reorder text on a banner.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_CHARS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F؜‎‏‪-‮⁦-⁩]/g;
+/**
+ * Make untrusted remote text (commit messages, page titles, log lines) safe to
+ * display: drop control and bidi-override characters, collapse whitespace
+ * (including newlines and tabs) to single spaces, trim, and truncate.
+ */
+function sanitizeText(s, max = 200) {
+    return truncate(s.replace(UNSAFE_CHARS, '').replace(/\s+/g, ' ').trim(), max);
+}
 //# sourceMappingURL=text.js.map

package/dist/cjs/core/thresholds.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluateThreshold = evaluateThreshold;
 exports.worstStatus = worstStatus;
+exports.moodForStatus = moodForStatus;
+exports.thresholdProblem = thresholdProblem;
 /**
  * Evaluate a numeric value against thresholds to determine status.
  */
@@ -45,4 +47,31 @@ function worstStatus(statuses) {
     }
     return worst;
 }
+/** The NPC mood that matches a status (drives the NPC's demeanour and emotes). */
+function moodForStatus(status) {
+    switch (status) {
+        case 'healthy':
+            return 'happy';
+        case 'warning':
+            return 'concerned';
+        case 'critical':
+            return 'stressed';
+        default:
+            return 'idle';
+    }
+}
+/**
+ * Validate a warning/critical pair from user flags: both finite, and critical
+ * at least as severe as warning for the threshold's direction. Returns an error
+ * message, or null when the pair is usable.
+ */
+function thresholdProblem(label, t) {
+    if (!Number.isFinite(t.warning) || !Number.isFinite(t.critical)) {
+        return `${label}: thresholds must be numbers`;
+    }
+    const inverted = (t.direction ?? 'above') === 'above' ? t.critical < t.warning : t.critical > t.warning;
+    return inverted
+        ? `${label}: critical (${t.critical}) must be at least as severe as warning (${t.warning})`
+        : null;
+}
 //# sourceMappingURL=thresholds.js.map

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.geminiServiceId = exports.geminiTransition = exports.GEMINI_ADAPTER = exports.GEMINI_DEFAULTS = exports.WebPageWatcherNPC = exports.GitHubWatcherNPC = exports.ReceptionistNPC = exports.LogWatcherNPC = exports.ProcessWatcherNPC = exports.InternetConnectivityNPC = exports.ensureSessionFilterTemplate = exports.sessionPublishDecision = exports.sessionFilterPath = exports.loadSessionFilter = exports.userConfigPath = exports.saveUserConfig = exports.loadUserConfig = exports.redactSecrets = exports.shortPath = exports.shortCommand = exports.describeToolUse = exports.CodexWatcher = exports.parseRolloutLine = exports.uninstallCodexHooks = exports.setupCodexHooks = exports.codexTransition = exports.handleCodexHookEvent = exports.handleCodexCommand = exports.claudeTransition = exports.processHookEvent = exports.uninstallHooks = exports.setupHooks = exports.handleHookEvent = exports.handleClaudeCodeCommand = exports.ClaudeCodeNPC = exports.SystemMonitorNPC = exports.pushHistory = exports.statusColor = exports.truncate = exports.worstStatus = exports.evaluateThreshold = exports.numberFlag = exports.boolFlag = exports.stringFlag = exports.resolveConfig = exports.parseArgs = exports.Logger = exports.EventNPC = exports.PollingNPC = exports.BaseNPC = void 0;
-exports.normalizeCursorEvent = exports.isCursorInvocation = exports.CURSOR_HOOK_EVENTS = exports.installCursorHooksInto = exports.uninstallCursorHooks = exports.setupCursorHooks = exports.handleCursorHookEvent = exports.cursorServiceId = exports.CURSOR_ADAPTER = exports.CURSOR_DEFAULTS = exports.GEMINI_HOOK_EVENTS = exports.installGeminiHooksInto = exports.uninstallGeminiHooks = exports.setupGeminiHooks = exports.handleGeminiHookEvent = void 0;
+exports.ReceptionistNPC = exports.LogWatcherNPC = exports.ProcessWatcherNPC = exports.InternetConnectivityNPC = exports.ensureSessionFilterTemplate = exports.sessionPublishDecision = exports.sessionFilterPath = exports.loadSessionFilter = exports.pixelDevice = exports.pixelArtFromPng = exports.encodePixelArt = exports.userConfigPath = exports.saveUserConfig = exports.loadUserConfig = exports.redactSecrets = exports.shortPath = exports.shortCommand = exports.describeToolUse = exports.CodexWatcher = exports.parseRolloutLine = exports.uninstallCodexHooks = exports.setupCodexHooks = exports.codexTransition = exports.handleCodexHookEvent = exports.handleCodexCommand = exports.claudeTransition = exports.processHookEvent = exports.uninstallHooks = exports.setupHooks = exports.handleHookEvent = exports.handleClaudeCodeCommand = exports.ClaudeCodeNPC = exports.SystemMonitorNPC = exports.pushHistory = exports.statusColor = exports.NpcConfigError = exports.sanitizeText = exports.truncate = exports.moodForStatus = exports.worstStatus = exports.evaluateThreshold = exports.numberFlag = exports.boolFlag = exports.stringFlag = exports.resolveConfig = exports.parseArgs = exports.Logger = exports.EventNPC = exports.PollingNPC = exports.BaseNPC = void 0;
+exports.OFFICE_CHARACTER_NPCS = exports.OutOfTouchExecutiveNPC = exports.ITTechnicianNPC = exports.PlantCaretakerNPC = exports.OfficeDogNPC = exports.OfficeCatNPC = exports.BaristaNPC = exports.JanitorNPC = exports.SecurityNPC = exports.normalizeCursorEvent = exports.isCursorInvocation = exports.CURSOR_HOOK_EVENTS = exports.installCursorHooksInto = exports.uninstallCursorHooks = exports.setupCursorHooks = exports.handleCursorHookEvent = exports.cursorServiceId = exports.CURSOR_ADAPTER = exports.CURSOR_DEFAULTS = exports.GEMINI_HOOK_EVENTS = exports.installGeminiHooksInto = exports.uninstallGeminiHooks = exports.setupGeminiHooks = exports.handleGeminiHookEvent = exports.geminiServiceId = exports.geminiTransition = exports.GEMINI_ADAPTER = exports.GEMINI_DEFAULTS = exports.WebPageWatcherNPC = exports.GitHubWatcherNPC = void 0;
 // Core
 var base_npc_js_1 = require("./core/base-npc.js");
 Object.defineProperty(exports, "BaseNPC", { enumerable: true, get: function () { return base_npc_js_1.BaseNPC; } });
@@ -20,8 +20,12 @@ Object.defineProperty(exports, "numberFlag", { enumerable: true, get: function (
 var thresholds_js_1 = require("./core/thresholds.js");
 Object.defineProperty(exports, "evaluateThreshold", { enumerable: true, get: function () { return thresholds_js_1.evaluateThreshold; } });
 Object.defineProperty(exports, "worstStatus", { enumerable: true, get: function () { return thresholds_js_1.worstStatus; } });
+Object.defineProperty(exports, "moodForStatus", { enumerable: true, get: function () { return thresholds_js_1.moodForStatus; } });
 var text_js_1 = require("./core/text.js");
 Object.defineProperty(exports, "truncate", { enumerable: true, get: function () { return text_js_1.truncate; } });
+Object.defineProperty(exports, "sanitizeText", { enumerable: true, get: function () { return text_js_1.sanitizeText; } });
+var errors_js_1 = require("./core/errors.js");
+Object.defineProperty(exports, "NpcConfigError", { enumerable: true, get: function () { return errors_js_1.NpcConfigError; } });
 var screen_js_1 = require("./core/screen.js");
 Object.defineProperty(exports, "statusColor", { enumerable: true, get: function () { return screen_js_1.statusColor; } });
 Object.defineProperty(exports, "pushHistory", { enumerable: true, get: function () { return screen_js_1.pushHistory; } });
@@ -53,6 +57,10 @@ var user_config_js_1 = require("./core/user-config.js");
 Object.defineProperty(exports, "loadUserConfig", { enumerable: true, get: function () { return user_config_js_1.loadUserConfig; } });
 Object.defineProperty(exports, "saveUserConfig", { enumerable: true, get: function () { return user_config_js_1.saveUserConfig; } });
 Object.defineProperty(exports, "userConfigPath", { enumerable: true, get: function () { return user_config_js_1.userConfigPath; } });
+var pixel_art_js_1 = require("./core/pixel-art.js");
+Object.defineProperty(exports, "encodePixelArt", { enumerable: true, get: function () { return pixel_art_js_1.encodePixelArt; } });
+Object.defineProperty(exports, "pixelArtFromPng", { enumerable: true, get: function () { return pixel_art_js_1.pixelArtFromPng; } });
+Object.defineProperty(exports, "pixelDevice", { enumerable: true, get: function () { return pixel_art_js_1.pixelDevice; } });
 var session_filter_js_1 = require("./core/session-filter.js");
 Object.defineProperty(exports, "loadSessionFilter", { enumerable: true, get: function () { return session_filter_js_1.loadSessionFilter; } });
 Object.defineProperty(exports, "sessionFilterPath", { enumerable: true, get: function () { return session_filter_js_1.sessionFilterPath; } });
@@ -92,4 +100,15 @@ Object.defineProperty(exports, "CURSOR_HOOK_EVENTS", { enumerable: true, get: fu
 var normalize_js_1 = require("./npcs/cursor/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; } });
+var index_js_12 = require("./npcs/security/index.js");
+Object.defineProperty(exports, "SecurityNPC", { enumerable: true, get: function () { return index_js_12.SecurityNPC; } });
+var index_js_13 = require("./npcs/office-characters/index.js");
+Object.defineProperty(exports, "JanitorNPC", { enumerable: true, get: function () { return index_js_13.JanitorNPC; } });
+Object.defineProperty(exports, "BaristaNPC", { enumerable: true, get: function () { return index_js_13.BaristaNPC; } });
+Object.defineProperty(exports, "OfficeCatNPC", { enumerable: true, get: function () { return index_js_13.OfficeCatNPC; } });
+Object.defineProperty(exports, "OfficeDogNPC", { enumerable: true, get: function () { return index_js_13.OfficeDogNPC; } });
+Object.defineProperty(exports, "PlantCaretakerNPC", { enumerable: true, get: function () { return index_js_13.PlantCaretakerNPC; } });
+Object.defineProperty(exports, "ITTechnicianNPC", { enumerable: true, get: function () { return index_js_13.ITTechnicianNPC; } });
+Object.defineProperty(exports, "OutOfTouchExecutiveNPC", { enumerable: true, get: function () { return index_js_13.OutOfTouchExecutiveNPC; } });
+Object.defineProperty(exports, "OFFICE_CHARACTER_NPCS", { enumerable: true, get: function () { return index_js_13.OFFICE_CHARACTER_NPCS; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/npcs/agent-common/session.js

@@ -244,6 +244,7 @@ function buildAgentPayload(adapter, state, config) {
         name,
         message: current ? (0, text_js_1.truncate)(current, 120) : undefined,
         archetype: 'ai-agent',
+        kind: adapter.command,
         metrics: { sessionStartedAt: state.startedAt ?? state.lastUpdate },
         appearance: { family: adapter.family },
         agentStats: state.agentStats,

package/dist/cjs/npcs/agent-common/shim.js

@@ -83,13 +83,19 @@ try {
 if (neutral) process.stdout.write('{}\\n');
 `;
 function installHookShim(nodePath, cliPath) {
+    // Desktop ships this same CLI with Electron's Node runtime. Keep the flag in
+    // the launcher (never globally), inherited by flush/watchdog child processes.
+    const electron = !!process.versions['electron'];
     writeChanged((0, exports.RUNTIME_POINTER)(), JSON.stringify({ node: nodePath, cli: cliPath }, null, 2) + '\n', 0o600);
     writeChanged((0, node_path_1.join)((0, node_path_1.dirname)((0, exports.RUNTIME_POINTER)()), 'node-path'), nodePath + '\n', 0o600);
     writeChanged((0, node_path_1.join)((0, node_path_1.dirname)((0, exports.SHIM_PATH)()), 'launch.cjs'), LAUNCHER, 0o600);
-    writeChanged((0, exports.SHIM_PATH)(), SHIM, 0o755);
+    writeChanged((0, exports.SHIM_PATH)(), electron ? SHIM.replace('exec "$NODE"', 'export ELECTRON_RUN_AS_NODE=1\nexec "$NODE"') : SHIM, 0o755);
     (0, node_fs_1.chmodSync)((0, exports.SHIM_PATH)(), 0o755);
     // Both launchers use the same bootstrap, including imported-Cursor detection.
-    writeChanged((0, exports.SHIM_PATH)() + '.cmd', WINDOWS_SHIM.replace(/\n/g, '\r\n'), 0o755);
+    const windowsShim = electron
+        ? WINDOWS_SHIM.replace(':launch\n', ':launch\nset "ELECTRON_RUN_AS_NODE=1"\n')
+        : WINDOWS_SHIM;
+    writeChanged((0, exports.SHIM_PATH)() + '.cmd', windowsShim.replace(/\n/g, '\r\n'), 0o755);
     (0, runtime_js_1.pruneOldRuntimes)((0, node_path_1.dirname)((0, exports.RUNTIME_POINTER)()));
     return (0, exports.SHIM_PATH)();
 }

package/dist/cjs/npcs/github-watcher/defaults.js

@@ -2,10 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULTS = void 0;
 exports.DEFAULTS = {
-    pollInterval: 60000, // 60s
+    pollInterval: 60000, // 60s with a token
+    /** Without a token GitHub allows 60 requests/hour (304s included): poll every 90s. */
+    unauthenticatedPollInterval: 90000,
     fetchTimeoutMs: 5000,
     perPage: 10,
+    /** Commit rows on the board (plus a header row). */
+    boardRows: 8,
     /** Polls to keep the 'new-commit' sub-status active after a fresh commit. */
     newCommitPolls: 2,
+    /** Consecutive network/5xx failures tolerated (board kept, healthy) before warning. */
+    failuresBeforeWarning: 3,
 };
 //# sourceMappingURL=defaults.js.map

package/dist/cjs/npcs/github-watcher/github-api.js

@@ -1,102 +1,139 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidRepo = isValidRepo;
 exports.fetchDefaultBranch = fetchDefaultBranch;
 exports.fetchCommits = fetchCommits;
+exports.parseCommit = parseCommit;
 exports.commitsWithin = commitsWithin;
 exports.newCommitsSince = newCommitsSince;
+const http_js_1 = require("../../core/http.js");
+const text_js_1 = require("../../core/text.js");
+/** Largest GitHub API response we read (10 commits are ~30-60 KB). */
+const MAX_BODY_BYTES = 512 * 1024;
+// GitHub owner and repository names: letters, digits, '-', '_' and '.'.
+const REPO_RE = /^([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100})$/;
+/**
+ * Validate an "owner/name" repository slug. It is interpolated into the API
+ * URL path, so anything else (`../`, extra segments, query characters) is
+ * rejected rather than letting it — and the token — reach another endpoint.
+ */
+function isValidRepo(repo) {
+    const m = repo.match(REPO_RE);
+    return !!m && m[2] !== '.' && m[2] !== '..';
+}
 function toNum(v) {
-    if (v === null)
+    if (v === null || v.trim() === '')
         return null;
     const n = Number(v);
-    return Number.isNaN(n) ? null : n;
+    return Number.isFinite(n) ? n : null;
 }
 function ghHeaders(opts) {
     const headers = {
         Accept: 'application/vnd.github+json',
-        'User-Agent': 'nocville-npc',
+        'User-Agent': http_js_1.NPC_USER_AGENT,
         'X-GitHub-Api-Version': '2022-11-28',
     };
     if (opts.token)
         headers['Authorization'] = `Bearer ${opts.token}`;
     return headers;
 }
+function doFetchFn(opts) {
+    return opts.fetchFn ?? globalThis.fetch;
+}
+async function readJson(res) {
+    const { text, truncated } = await (0, http_js_1.readTextCapped)(res, MAX_BODY_BYTES);
+    if (truncated)
+        throw new Error('response too large');
+    return JSON.parse(text);
+}
 /** Look up a repo's default branch (one call at startup). Null on failure. */
 async function fetchDefaultBranch(repo, opts = {}) {
-    const doFetch = opts.fetchFn ?? globalThis.fetch;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
     try {
-        const res = await doFetch(`https://api.github.com/repos/${repo}`, {
+        const res = await doFetchFn(opts)(`https://api.github.com/repos/${repo}`, {
             headers: ghHeaders(opts),
-            signal: controller.signal,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
         });
         if (!res.ok)
             return null;
-        const body = (await res.json());
-        return body.default_branch ?? null;
+        const branch = (0, http_js_1.asRecord)(await readJson(res))?.['default_branch'];
+        return typeof branch === 'string' && branch.length > 0 && branch.length <= 255
+            ? (0, text_js_1.sanitizeText)(branch, 255)
+            : null;
     }
     catch {
         return null;
     }
-    finally {
-        clearTimeout(timer);
-    }
 }
 /**
  * Fetch recent commits from the GitHub REST API using conditional requests.
- * Passing the previous ETag yields a 304 (which does not count against the
- * unauthenticated 60/hour limit) when nothing has changed. Never throws —
- * network errors surface as `status: 0`.
+ * Passing the previous ETag yields a cheap 304 when nothing has changed (free
+ * of the rate limit for authenticated requests). Never throws — network
+ * errors and unreadable bodies surface as `status: 0`.
  */
 async function fetchCommits(repo, opts = {}) {
     const perPage = opts.perPage ?? 10;
-    const doFetch = opts.fetchFn ?? globalThis.fetch;
     let url = `https://api.github.com/repos/${repo}/commits?per_page=${perPage}`;
     if (opts.branch)
         url += `&sha=${encodeURIComponent(opts.branch)}`;
     const headers = ghHeaders(opts);
     if (opts.etag)
         headers['If-None-Match'] = opts.etag;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
+    const failed = {
+        notModified: false,
+        commits: [],
+        etag: null,
+        rateRemaining: null,
+        rateResetAt: null,
+        status: 0,
+    };
     try {
-        const res = await doFetch(url, { headers, signal: controller.signal });
+        const res = await doFetchFn(opts)(url, {
+            headers,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
+        });
         const rateRemaining = toNum(res.headers.get('x-ratelimit-remaining'));
+        const resetSecs = toNum(res.headers.get('x-ratelimit-reset'));
+        const rateResetAt = resetSecs === null ? null : resetSecs * 1000;
         const etag = res.headers.get('etag');
+        const meta = { rateRemaining, rateResetAt, status: res.status };
         if (res.status === 304) {
-            return {
-                notModified: true,
-                commits: [],
-                etag: opts.etag ?? null,
-                rateRemaining,
-                status: 304,
-            };
+            return { ...meta, notModified: true, commits: [], etag: opts.etag ?? null };
         }
         if (!res.ok) {
-            await res.text().catch(() => undefined);
-            return { notModified: false, commits: [], etag, rateRemaining, status: res.status };
+            await res.body?.cancel().catch(() => undefined);
+            return { ...meta, notModified: false, commits: [], etag };
         }
-        const body = (await res.json());
-        const commits = body.map((c) => parseCommit(c));
-        return { notModified: false, commits, etag, rateRemaining, status: res.status };
+        const body = await readJson(res);
+        if (!Array.isArray(body))
+            return failed;
+        const commits = body.map(parseCommit).filter((c) => c !== null);
+        return { ...meta, notModified: false, commits, etag };
     }
     catch {
-        return { notModified: false, commits: [], etag: null, rateRemaining: null, status: 0 };
-    }
-    finally {
-        clearTimeout(timer);
+        return failed;
     }
 }
-function parseCommit(c) {
-    const commit = c['commit'] ?? {};
-    const commitAuthor = commit['author'] ?? {};
-    const ghAuthor = c['author'] ?? {};
-    const message = String(commit['message'] ?? '').split('\n')[0] ?? '';
+/**
+ * Extract the displayed fields from one (untrusted) commit object: a hex sha,
+ * the subject line and author name with control/bidi characters removed and
+ * lengths capped. Null for anything without a valid sha.
+ */
+function parseCommit(raw) {
+    const c = (0, http_js_1.asRecord)(raw);
+    const sha = c?.['sha'];
+    if (typeof sha !== 'string' || !/^[0-9a-f]{7,64}$/i.test(sha))
+        return null;
+    const commit = (0, http_js_1.asRecord)(c['commit']) ?? {};
+    const commitAuthor = (0, http_js_1.asRecord)(commit['author']) ?? {};
+    const ghAuthor = (0, http_js_1.asRecord)(c['author']) ?? {};
+    const str = (v) => (typeof v === 'string' && v.trim() ? v : null);
+    const message = str(commit['message'])?.split('\n')[0] ?? '';
+    const date = str(commitAuthor['date']) ?? '';
     return {
-        sha: String(c['sha'] ?? ''),
-        author: String(commitAuthor['name'] ?? ghAuthor['login'] ?? 'unknown'),
-        message,
-        date: String(commitAuthor['date'] ?? ''),
+        sha: sha.toLowerCase(),
+        author: (0, text_js_1.sanitizeText)(str(commitAuthor['name']) ?? str(ghAuthor['login']) ?? 'unknown', 40),
+        message: (0, text_js_1.sanitizeText)(message, 200),
+        date: Number.isFinite(Date.parse(date)) ? date : '',
     };
 }
 /** Count how many commits landed within the last `hours`. */