@mauribadnights/clooks 0.3.2 → 0.4.1

package/dist/manifest.js

@@ -74,6 +74,39 @@ function validateManifest(manifest) {
                     throw new Error(`LLM handler "${handler.id}" model must be one of: ${validModels.join(', ')}`);
                 }
             }
+            // Validate async field type
+            if ('async' in handler && typeof handler.async !== 'boolean') {
+                throw new Error(`Handler "${handler.id}" async field must be a boolean`);
+            }
+            // Validate agent field type
+            if ('agent' in handler && typeof handler.agent !== 'string') {
+                throw new Error(`Handler "${handler.id}" agent field must be a string`);
+            }
+            // Validate project field type
+            if ('project' in handler && typeof handler.project !== 'string') {
+                throw new Error(`Handler "${handler.id}" project field must be a string`);
+            }
+        }
+        // Warn about async handlers with dependency relationships
+        const eventHandlerIds = new Set(handlers.map(h => h.id));
+        const dependedUponIds = new Set();
+        for (const h of handlers) {
+            if (h.depends) {
+                for (const dep of h.depends) {
+                    if (eventHandlerIds.has(dep))
+                        dependedUponIds.add(dep);
+                }
+            }
+        }
+        for (const h of handlers) {
+            if (h.async) {
+                if (dependedUponIds.has(h.id)) {
+                    console.warn(`[clooks] Warning: async handler "${h.id}" has dependents — will run synchronously at runtime`);
+                }
+                if (h.depends?.some(d => eventHandlerIds.has(d))) {
+                    console.warn(`[clooks] Warning: async handler "${h.id}" has dependencies — will run synchronously at runtime`);
+                }
+            }
         }
     }
     // Validate prefetch if present

package/dist/server.d.ts

@@ -4,6 +4,13 @@ import { MetricsCollector } from './metrics.js';
 import { DenyCache } from './shortcircuit.js';
 import { RateLimiter } from './ratelimit.js';
 import type { Manifest } from './types.js';
+/** Session agent cache: session_id → { agent_type, timestamp } */
+declare const sessionAgents: Map<string, {
+    agent: string;
+    ts: number;
+}>;
+/** Exported for testing */
+export { sessionAgents };
 export interface ServerContext {
     server: Server;
     metrics: MetricsCollector;
@@ -29,11 +36,24 @@ export declare function startDaemon(manifest: Manifest, metrics: MetricsCollecto
  */
 export declare function stopDaemon(): boolean;
 /**
- * Check if daemon is currently running.
+ * Check if daemon is currently running (PID check only).
+ * Use for stop/status where a quick check is fine.
  */
 export declare function isDaemonRunning(): boolean;
+/**
+ * Check if daemon is running AND healthy (PID + health endpoint).
+ * Defends against stale PIDs reused by macOS after sleep/lid-close.
+ * Use for ensure-running and start where correctness matters.
+ */
+export declare function isDaemonHealthy(): Promise<boolean>;
+/**
+ * Clean up a stale daemon: remove PID file and attempt to kill the process.
+ * Returns the stale PID for logging purposes.
+ */
+export declare function cleanupStaleDaemon(): number | null;
 /**
  * Start daemon as a detached background process.
+ * Always removes any existing PID file first — the new daemon writes its own.
  */
 export declare function startDaemonBackground(options?: {
     noWatch?: boolean;

package/dist/server.js

@@ -1,10 +1,13 @@
 "use strict";
 // clooks HTTP server — persistent hook daemon
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionAgents = void 0;
 exports.createServer = createServer;
 exports.startDaemon = startDaemon;
 exports.stopDaemon = stopDaemon;
 exports.isDaemonRunning = isDaemonRunning;
+exports.isDaemonHealthy = isDaemonHealthy;
+exports.cleanupStaleDaemon = cleanupStaleDaemon;
 exports.startDaemonBackground = startDaemonBackground;
 const http_1 = require("http");
 const fs_1 = require("fs");
@@ -17,6 +20,18 @@ const shortcircuit_js_1 = require("./shortcircuit.js");
 const ratelimit_js_1 = require("./ratelimit.js");
 const constants_js_1 = require("./constants.js");
 const manifest_js_1 = require("./manifest.js");
+/** Session agent cache: session_id → { agent_type, timestamp } */
+const sessionAgents = new Map();
+exports.sessionAgents = sessionAgents;
+const SESSION_AGENT_TTL = 24 * 60 * 60 * 1000; // 24 hours
+function cleanupSessionAgents() {
+    const now = Date.now();
+    for (const [id, entry] of sessionAgents) {
+        if (now - entry.ts > SESSION_AGENT_TTL) {
+            sessionAgents.delete(id);
+        }
+    }
+}
 function log(msg) {
     const line = `[${new Date().toISOString()}] ${msg}\n`;
     try {
@@ -99,6 +114,7 @@ function createServer(manifest, metrics) {
     ctx.cleanupInterval = setInterval(() => {
         denyCache.cleanup();
         rateLimiter.cleanup();
+        cleanupSessionAgents();
     }, 60_000);
     // Unref so it doesn't keep the process alive
     if (ctx.cleanupInterval && typeof ctx.cleanupInterval === 'object' && 'unref' in ctx.cleanupInterval) {
@@ -163,7 +179,7 @@ function createServer(manifest, metrics) {
                 return;
             }
             const event = eventName;
-            // On SessionStart, reset session-isolated handlers across ALL events
+            // On SessionStart, cache agent and reset session-isolated handlers
             if (event === 'SessionStart') {
                 const allHandlers = Object.values(ctx.manifest.handlers)
                     .flat()
@@ -185,6 +201,12 @@ function createServer(manifest, metrics) {
                 sendJson(res, 400, { error: 'Invalid JSON body' });
                 return;
             }
+            // Cache agent_type on SessionStart
+            if (event === 'SessionStart' && input.agent_type && input.session_id) {
+                sessionAgents.set(input.session_id, { agent: input.agent_type, ts: Date.now() });
+            }
+            // Resolve current agent for this session
+            const currentAgent = input.session_id ? sessionAgents.get(input.session_id)?.agent : undefined;
             // Short-circuit: skip PostToolUse if PreToolUse denied this tool
             if (event === 'PostToolUse' && input.tool_name && input.session_id) {
                 if (denyCache.isDenied(input.session_id, input.tool_name)) {
@@ -193,16 +215,23 @@ function createServer(manifest, metrics) {
                     return;
                 }
             }
-            log(`Hook: ${eventName} (${handlers.length} handler${handlers.length > 1 ? 's' : ''})`);
+            const allHandlerConfigs = handlers;
+            const syncCount = allHandlerConfigs.filter(h => !h.async).length;
+            const asyncCount = allHandlerConfigs.filter(h => h.async).length;
+            if (asyncCount > 0) {
+                log(`Hook: ${eventName} (${syncCount} sync, ${asyncCount} async handler${syncCount + asyncCount > 1 ? 's' : ''})`);
+            }
+            else {
+                log(`Hook: ${eventName} (${handlers.length} handler${handlers.length > 1 ? 's' : ''})`);
+            }
             try {
                 // Pre-fetch shared context if configured
                 let context;
                 if (ctx.manifest.prefetch && ctx.manifest.prefetch.length > 0) {
                     context = await (0, prefetch_js_1.prefetchContext)(ctx.manifest.prefetch, input);
                 }
-                const results = await (0, handlers_js_1.executeHandlers)(event, input, handlers, context);
-                // Record metrics and costs
-                for (const result of results) {
+                // Callback for recording async handler metrics when they complete
+                const recordResult = (result) => {
                     metrics.record({
                         ts: new Date().toISOString(),
                         event,
@@ -214,10 +243,10 @@ function createServer(manifest, metrics) {
                         usage: result.usage,
                         cost_usd: result.cost_usd,
                         session_id: input.session_id,
+                        agent_type: currentAgent,
                     });
-                    // Track cost for LLM handlers
                     if (result.usage && result.cost_usd !== undefined && result.cost_usd > 0) {
-                        const handlerConfig = handlers.find(h => h.id === result.id);
+                        const handlerConfig = allHandlerConfigs.find(h => h.id === result.id);
                         if (handlerConfig && handlerConfig.type === 'llm') {
                             const llmConfig = handlerConfig;
                             metrics.trackCost({
@@ -231,6 +260,11 @@ function createServer(manifest, metrics) {
                             });
                         }
                     }
+                };
+                const results = await (0, handlers_js_1.executeHandlers)(event, input, allHandlerConfigs, context, recordResult, currentAgent);
+                // Record metrics and costs for sync results
+                for (const result of results) {
+                    recordResult(result);
                 }
                 // Short-circuit: if PreToolUse had a deny, record it in the cache
                 if (event === 'PreToolUse' && input.tool_name && input.session_id) {
@@ -380,6 +414,13 @@ function startDaemon(manifest, metrics, options) {
         };
         process.on('SIGTERM', shutdown);
         process.on('SIGINT', shutdown);
+        // Visibility into macOS sleep/wake cycles
+        process.on('SIGTSTP', () => {
+            log('Daemon suspended (system sleep)');
+        });
+        process.on('SIGCONT', () => {
+            log('Daemon resumed (system wake)');
+        });
     });
 }
 /**
@@ -422,7 +463,8 @@ function stopDaemon() {
     return true;
 }
 /**
- * Check if daemon is currently running.
+ * Check if daemon is currently running (PID check only).
+ * Use for stop/status where a quick check is fine.
  */
 function isDaemonRunning() {
     if (!(0, fs_1.existsSync)(constants_js_1.PID_FILE))
@@ -440,10 +482,86 @@ function isDaemonRunning() {
         return false;
     }
 }
+/**
+ * Check if daemon is running AND healthy (PID + health endpoint).
+ * Defends against stale PIDs reused by macOS after sleep/lid-close.
+ * Use for ensure-running and start where correctness matters.
+ */
+async function isDaemonHealthy() {
+    if (!(0, fs_1.existsSync)(constants_js_1.PID_FILE))
+        return false;
+    const pidStr = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+    const pid = parseInt(pidStr, 10);
+    if (isNaN(pid))
+        return false;
+    // Step 1: PID alive?
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        return false;
+    }
+    // Step 2: Health endpoint responds?
+    const port = constants_js_1.DEFAULT_PORT; // health check always on default port
+    try {
+        const { get } = await import('http');
+        const data = await new Promise((resolve, reject) => {
+            const req = get(`http://127.0.0.1:${port}/health`, (res) => {
+                let body = '';
+                res.on('data', (chunk) => { body += chunk.toString(); });
+                res.on('end', () => resolve(body));
+            });
+            req.on('error', reject);
+            req.setTimeout(2000, () => { req.destroy(); reject(new Error('timeout')); });
+        });
+        const health = JSON.parse(data);
+        return health.status === 'ok';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Clean up a stale daemon: remove PID file and attempt to kill the process.
+ * Returns the stale PID for logging purposes.
+ */
+function cleanupStaleDaemon() {
+    if (!(0, fs_1.existsSync)(constants_js_1.PID_FILE))
+        return null;
+    const pidStr = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+    const pid = parseInt(pidStr, 10);
+    // Remove stale PID file
+    try {
+        (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+    }
+    catch {
+        // ignore
+    }
+    // Try to kill the stale process (might be our daemon but unhealthy)
+    if (!isNaN(pid)) {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            // Process doesn't exist — that's fine
+        }
+        return pid;
+    }
+    return null;
+}
 /**
  * Start daemon as a detached background process.
+ * Always removes any existing PID file first — the new daemon writes its own.
  */
 function startDaemonBackground(options) {
+    // Clean any stale PID file before spawning
+    try {
+        if ((0, fs_1.existsSync)(constants_js_1.PID_FILE))
+            (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+    }
+    catch {
+        // ignore
+    }
     const args = [process.argv[1], 'start', '--foreground'];
     if (options?.noWatch) {
         args.push('--no-watch');

package/dist/service.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Find the clooks binary path by checking PATH or falling back to process.argv[1].
+ */
+declare function findClooksPath(): string;
+declare const PLIST_LABEL = "com.clooks.daemon";
+declare function getPlistPath(): string;
+declare const SYSTEMD_SERVICE_NAME = "clooks";
+declare function getSystemdServicePath(): string;
+declare const TASK_NAME = "clooks";
+export type ServiceStatus = 'running' | 'stopped' | 'not-installed';
+/**
+ * Install clooks as an OS service (launchd on macOS, systemd on Linux, schtasks on Windows).
+ */
+export declare function installService(): void;
+/**
+ * Uninstall the clooks OS service.
+ */
+export declare function uninstallService(): void;
+/**
+ * Check if the clooks OS service is installed.
+ */
+export declare function isServiceInstalled(): boolean;
+/**
+ * Get the current service status.
+ */
+export declare function getServiceStatus(): ServiceStatus;
+export { findClooksPath, getPlistPath, getSystemdServicePath, PLIST_LABEL, SYSTEMD_SERVICE_NAME, TASK_NAME };

package/dist/service.js

@@ -0,0 +1,242 @@
+"use strict";
+// clooks service management — cross-platform OS service installer/uninstaller
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_NAME = exports.SYSTEMD_SERVICE_NAME = exports.PLIST_LABEL = void 0;
+exports.installService = installService;
+exports.uninstallService = uninstallService;
+exports.isServiceInstalled = isServiceInstalled;
+exports.getServiceStatus = getServiceStatus;
+exports.findClooksPath = findClooksPath;
+exports.getPlistPath = getPlistPath;
+exports.getSystemdServicePath = getSystemdServicePath;
+const os_1 = require("os");
+const path_1 = require("path");
+const fs_1 = require("fs");
+const child_process_1 = require("child_process");
+const constants_js_1 = require("./constants.js");
+/**
+ * Find the clooks binary path by checking PATH or falling back to process.argv[1].
+ */
+function findClooksPath() {
+    try {
+        const cmd = (0, os_1.platform)() === 'win32' ? 'where clooks' : 'which clooks';
+        return (0, child_process_1.execSync)(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim().split('\n')[0];
+    }
+    catch {
+        // Fallback: resolve from current process
+        return process.argv[1];
+    }
+}
+// --- macOS (launchd) ---
+const PLIST_LABEL = 'com.clooks.daemon';
+exports.PLIST_LABEL = PLIST_LABEL;
+function getPlistPath() {
+    return (0, path_1.join)((0, os_1.homedir)(), 'Library', 'LaunchAgents', `${PLIST_LABEL}.plist`);
+}
+function installMacOS() {
+    const plistPath = getPlistPath();
+    const launchAgentsDir = (0, path_1.join)((0, os_1.homedir)(), 'Library', 'LaunchAgents');
+    if (!(0, fs_1.existsSync)(launchAgentsDir)) {
+        (0, fs_1.mkdirSync)(launchAgentsDir, { recursive: true });
+    }
+    const nodePath = process.execPath;
+    const clooksPath = findClooksPath();
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${PLIST_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath}</string>
+    <string>${clooksPath}</string>
+    <string>start</string>
+    <string>--foreground</string>
+  </array>
+  <key>KeepAlive</key>
+  <true/>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${(0, path_1.join)(constants_js_1.CONFIG_DIR, 'daemon-stdout.log')}</string>
+  <key>StandardErrorPath</key>
+  <string>${(0, path_1.join)(constants_js_1.CONFIG_DIR, 'daemon-stderr.log')}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin'}</string>
+  </dict>
+</dict>
+</plist>`;
+    (0, fs_1.writeFileSync)(plistPath, plist, 'utf-8');
+    (0, child_process_1.execSync)(`launchctl load ${plistPath}`, { stdio: 'pipe' });
+}
+function uninstallMacOS() {
+    const plistPath = getPlistPath();
+    if ((0, fs_1.existsSync)(plistPath)) {
+        try {
+            (0, child_process_1.execSync)(`launchctl unload ${plistPath}`, { stdio: 'pipe' });
+        }
+        catch {
+            // May fail if not loaded — that's fine
+        }
+        (0, fs_1.unlinkSync)(plistPath);
+    }
+}
+function isInstalledMacOS() {
+    return (0, fs_1.existsSync)(getPlistPath());
+}
+// --- Linux (systemd user service) ---
+const SYSTEMD_SERVICE_NAME = 'clooks';
+exports.SYSTEMD_SERVICE_NAME = SYSTEMD_SERVICE_NAME;
+function getSystemdServicePath() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.config', 'systemd', 'user', `${SYSTEMD_SERVICE_NAME}.service`);
+}
+function installLinux() {
+    const serviceDir = (0, path_1.join)((0, os_1.homedir)(), '.config', 'systemd', 'user');
+    (0, fs_1.mkdirSync)(serviceDir, { recursive: true });
+    const servicePath = getSystemdServicePath();
+    const nodePath = process.execPath;
+    const clooksPath = findClooksPath();
+    const unit = `[Unit]
+Description=clooks - Persistent hook runtime for Claude Code
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${nodePath} ${clooksPath} start --foreground
+Restart=always
+RestartSec=3
+Environment=PATH=${process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin'}
+
+[Install]
+WantedBy=default.target`;
+    (0, fs_1.writeFileSync)(servicePath, unit, 'utf-8');
+    (0, child_process_1.execSync)('systemctl --user daemon-reload', { stdio: 'pipe' });
+    (0, child_process_1.execSync)(`systemctl --user enable ${SYSTEMD_SERVICE_NAME}`, { stdio: 'pipe' });
+    (0, child_process_1.execSync)(`systemctl --user start ${SYSTEMD_SERVICE_NAME}`, { stdio: 'pipe' });
+}
+function uninstallLinux() {
+    try {
+        (0, child_process_1.execSync)(`systemctl --user stop ${SYSTEMD_SERVICE_NAME}`, { stdio: 'pipe' });
+    }
+    catch { /* ignore */ }
+    try {
+        (0, child_process_1.execSync)(`systemctl --user disable ${SYSTEMD_SERVICE_NAME}`, { stdio: 'pipe' });
+    }
+    catch { /* ignore */ }
+    const servicePath = getSystemdServicePath();
+    if ((0, fs_1.existsSync)(servicePath))
+        (0, fs_1.unlinkSync)(servicePath);
+    try {
+        (0, child_process_1.execSync)('systemctl --user daemon-reload', { stdio: 'pipe' });
+    }
+    catch { /* ignore */ }
+}
+function isInstalledLinux() {
+    try {
+        const result = (0, child_process_1.execSync)(`systemctl --user is-enabled ${SYSTEMD_SERVICE_NAME} 2>/dev/null`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        return result.trim() === 'enabled';
+    }
+    catch {
+        return false;
+    }
+}
+// --- Windows (Task Scheduler) ---
+const TASK_NAME = 'clooks';
+exports.TASK_NAME = TASK_NAME;
+function installWindows() {
+    const nodePath = process.execPath;
+    const clooksPath = findClooksPath();
+    (0, child_process_1.execSync)(`schtasks /create /tn "${TASK_NAME}" /tr "\\"${nodePath}\\" \\"${clooksPath}\\" start --foreground" ` +
+        `/sc onlogon /rl limited /f`, { stdio: 'pipe' });
+    // Start it now
+    (0, child_process_1.execSync)(`schtasks /run /tn "${TASK_NAME}"`, { stdio: 'pipe' });
+}
+function uninstallWindows() {
+    try {
+        (0, child_process_1.execSync)(`schtasks /end /tn "${TASK_NAME}"`, { stdio: 'pipe' });
+    }
+    catch { /* ignore */ }
+    try {
+        (0, child_process_1.execSync)(`schtasks /delete /tn "${TASK_NAME}" /f`, { stdio: 'pipe' });
+    }
+    catch { /* ignore */ }
+}
+function isInstalledWindows() {
+    try {
+        (0, child_process_1.execSync)(`schtasks /query /tn "${TASK_NAME}" 2>nul`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install clooks as an OS service (launchd on macOS, systemd on Linux, schtasks on Windows).
+ */
+function installService() {
+    const os = (0, os_1.platform)();
+    if (os === 'darwin')
+        installMacOS();
+    else if (os === 'linux')
+        installLinux();
+    else if (os === 'win32')
+        installWindows();
+    else
+        throw new Error(`Unsupported platform: ${os}`);
+}
+/**
+ * Uninstall the clooks OS service.
+ */
+function uninstallService() {
+    const os = (0, os_1.platform)();
+    if (os === 'darwin')
+        uninstallMacOS();
+    else if (os === 'linux')
+        uninstallLinux();
+    else if (os === 'win32')
+        uninstallWindows();
+    else
+        throw new Error(`Unsupported platform: ${os}`);
+}
+/**
+ * Check if the clooks OS service is installed.
+ */
+function isServiceInstalled() {
+    const os = (0, os_1.platform)();
+    if (os === 'darwin')
+        return isInstalledMacOS();
+    else if (os === 'linux')
+        return isInstalledLinux();
+    else if (os === 'win32')
+        return isInstalledWindows();
+    return false;
+}
+/**
+ * Get the current service status.
+ */
+function getServiceStatus() {
+    if (!isServiceInstalled())
+        return 'not-installed';
+    const os = (0, os_1.platform)();
+    try {
+        if (os === 'darwin') {
+            const result = (0, child_process_1.execSync)(`launchctl list ${PLIST_LABEL} 2>/dev/null`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            return result.includes('PID') ? 'running' : 'stopped';
+        }
+        else if (os === 'linux') {
+            const result = (0, child_process_1.execSync)(`systemctl --user is-active ${SYSTEMD_SERVICE_NAME} 2>/dev/null`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            return result.trim() === 'active' ? 'running' : 'stopped';
+        }
+        else if (os === 'win32') {
+            const result = (0, child_process_1.execSync)(`schtasks /query /tn "${TASK_NAME}" /fo csv 2>nul`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            return result.includes('Running') ? 'running' : 'stopped';
+        }
+    }
+    catch {
+        // Fall through
+    }
+    return 'stopped';
+}

package/dist/tui.d.ts

@@ -0,0 +1 @@
+export declare function launchDashboard(): void;