@mauribadnights/clooks 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -11,7 +11,12 @@ export { DenyCache } from './shortcircuit.js';
 export { RateLimiter } from './ratelimit.js';
 export { startWatcher, stopWatcher } from './watcher.js';
 export { generateAuthToken, validateAuth, rotateToken } from './auth.js';
+export { syncSettings } from './sync.js';
+export { installService, uninstallService, isServiceInstalled, getServiceStatus } from './service.js';
+export type { ServiceStatus } from './service.js';
+export type { SyncOptions } from './sync.js';
 export type { RotateTokenOptions } from './auth.js';
+export { installAgent, isAgentInstalled } from './agent.js';
 export { evaluateFilter } from './filter.js';
 export { executeLLMHandler, executeLLMHandlersBatched, calculateCost, resetClient } from './llm.js';
 export { prefetchContext, renderPromptTemplate } from './prefetch.js';

package/dist/index.js

@@ -1,8 +1,8 @@
 "use strict";
 // clooks — public API exports
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PLUGINS_DIR = exports.LLM_PRICING = exports.DEFAULT_LLM_MAX_TOKENS = exports.DEFAULT_LLM_TIMEOUT = exports.COSTS_FILE = exports.LOG_FILE = exports.METRICS_FILE = exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = exports.renderPromptTemplate = exports.prefetchContext = exports.resetClient = exports.calculateCost = exports.executeLLMHandlersBatched = exports.executeLLMHandler = exports.evaluateFilter = exports.rotateToken = exports.validateAuth = exports.generateAuthToken = exports.stopWatcher = exports.startWatcher = exports.RateLimiter = exports.DenyCache = exports.resolveExecutionOrder = exports.cleanupHandlerState = exports.resetSessionIsolatedHandlers = exports.executeHandlers = exports.runDoctor = exports.getSettingsPath = exports.restore = exports.migrate = exports.MetricsCollector = exports.listPlugins = exports.uninstallPlugin = exports.installPlugin = exports.saveRegistry = exports.loadRegistry = exports.validatePluginManifest = exports.mergeManifests = exports.loadPlugins = exports.createDefaultManifest = exports.validateManifest = exports.loadCompositeManifest = exports.loadManifest = exports.isDaemonRunning = exports.stopDaemon = exports.startDaemon = exports.createServer = void 0;
-exports.PLUGIN_MANIFEST_NAME = exports.PLUGIN_REGISTRY = void 0;
+exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = exports.renderPromptTemplate = exports.prefetchContext = exports.resetClient = exports.calculateCost = exports.executeLLMHandlersBatched = exports.executeLLMHandler = exports.evaluateFilter = exports.isAgentInstalled = exports.installAgent = exports.getServiceStatus = exports.isServiceInstalled = exports.uninstallService = exports.installService = exports.syncSettings = exports.rotateToken = exports.validateAuth = exports.generateAuthToken = exports.stopWatcher = exports.startWatcher = exports.RateLimiter = exports.DenyCache = exports.resolveExecutionOrder = exports.cleanupHandlerState = exports.resetSessionIsolatedHandlers = exports.executeHandlers = exports.runDoctor = exports.getSettingsPath = exports.restore = exports.migrate = exports.MetricsCollector = exports.listPlugins = exports.uninstallPlugin = exports.installPlugin = exports.saveRegistry = exports.loadRegistry = exports.validatePluginManifest = exports.mergeManifests = exports.loadPlugins = exports.createDefaultManifest = exports.validateManifest = exports.loadCompositeManifest = exports.loadManifest = exports.isDaemonRunning = exports.stopDaemon = exports.startDaemon = exports.createServer = void 0;
+exports.PLUGIN_MANIFEST_NAME = exports.PLUGIN_REGISTRY = exports.PLUGINS_DIR = exports.LLM_PRICING = exports.DEFAULT_LLM_MAX_TOKENS = exports.DEFAULT_LLM_TIMEOUT = exports.COSTS_FILE = exports.LOG_FILE = exports.METRICS_FILE = void 0;
 var server_js_1 = require("./server.js");
 Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return server_js_1.createServer; } });
 Object.defineProperty(exports, "startDaemon", { enumerable: true, get: function () { return server_js_1.startDaemon; } });
@@ -47,6 +47,16 @@ var auth_js_1 = require("./auth.js");
 Object.defineProperty(exports, "generateAuthToken", { enumerable: true, get: function () { return auth_js_1.generateAuthToken; } });
 Object.defineProperty(exports, "validateAuth", { enumerable: true, get: function () { return auth_js_1.validateAuth; } });
 Object.defineProperty(exports, "rotateToken", { enumerable: true, get: function () { return auth_js_1.rotateToken; } });
+var sync_js_1 = require("./sync.js");
+Object.defineProperty(exports, "syncSettings", { enumerable: true, get: function () { return sync_js_1.syncSettings; } });
+var service_js_1 = require("./service.js");
+Object.defineProperty(exports, "installService", { enumerable: true, get: function () { return service_js_1.installService; } });
+Object.defineProperty(exports, "uninstallService", { enumerable: true, get: function () { return service_js_1.uninstallService; } });
+Object.defineProperty(exports, "isServiceInstalled", { enumerable: true, get: function () { return service_js_1.isServiceInstalled; } });
+Object.defineProperty(exports, "getServiceStatus", { enumerable: true, get: function () { return service_js_1.getServiceStatus; } });
+var agent_js_1 = require("./agent.js");
+Object.defineProperty(exports, "installAgent", { enumerable: true, get: function () { return agent_js_1.installAgent; } });
+Object.defineProperty(exports, "isAgentInstalled", { enumerable: true, get: function () { return agent_js_1.isAgentInstalled; } });
 var filter_js_1 = require("./filter.js");
 Object.defineProperty(exports, "evaluateFilter", { enumerable: true, get: function () { return filter_js_1.evaluateFilter; } });
 var llm_js_1 = require("./llm.js");

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/ratelimit.d.ts

@@ -5,8 +5,13 @@ export declare class RateLimiter {
     constructor(maxAttempts?: number, windowMs?: number);
     /** Check if source is rate-limited. Returns true if allowed. */
     check(source: string): boolean;
-    /** Record an attempt from source. */
-    record(source: string): void;
+    /** Record an auth failure from source. */
+    recordFailure(source: string): void;
+    /**
+     * How many seconds until the rate limit resets for a given source.
+     * Returns 0 if the source is not rate-limited.
+     */
+    retryAfter(source: string): number;
     /** Clean up old entries. */
     cleanup(): void;
 }

package/dist/ratelimit.js

@@ -1,9 +1,13 @@
 "use strict";
 // clooks rate limiting — protect against auth brute-force
+//
+// IMPORTANT: This rate limiter should ONLY be used when auth is configured.
+// It tracks auth failures per source IP. When the limit is exceeded, requests
+// from that source are blocked with 429 until the window expires.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RateLimiter = void 0;
 class RateLimiter {
-    attempts = new Map(); // source → timestamps
+    attempts = new Map(); // source → auth failure timestamps
     maxAttempts;
     windowMs;
     constructor(maxAttempts = 10, windowMs = 60_000) {
@@ -16,17 +20,34 @@ class RateLimiter {
         const timestamps = this.attempts.get(source);
         if (!timestamps)
             return true;
-        // Count recent attempts within window
+        // Count recent auth failures within window
         const recent = timestamps.filter(t => now - t <= this.windowMs);
         return recent.length < this.maxAttempts;
     }
-    /** Record an attempt from source. */
-    record(source) {
+    /** Record an auth failure from source. */
+    recordFailure(source) {
         const now = Date.now();
         const timestamps = this.attempts.get(source) ?? [];
         timestamps.push(now);
         this.attempts.set(source, timestamps);
     }
+    /**
+     * How many seconds until the rate limit resets for a given source.
+     * Returns 0 if the source is not rate-limited.
+     */
+    retryAfter(source) {
+        const now = Date.now();
+        const timestamps = this.attempts.get(source);
+        if (!timestamps)
+            return 0;
+        const recent = timestamps.filter(t => now - t <= this.windowMs);
+        if (recent.length < this.maxAttempts)
+            return 0;
+        // The oldest recent attempt determines when the window expires
+        const oldest = Math.min(...recent);
+        const expiresAt = oldest + this.windowMs;
+        return Math.ceil((expiresAt - now) / 1000);
+    }
     /** Clean up old entries. */
     cleanup() {
         const now = Date.now();

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) {
@@ -131,17 +147,24 @@ function createServer(manifest, metrics) {
             });
             return;
         }
-        // Auth check for all POST requests
+        // Auth check for all POST requests — only when auth token is configured
         if (method === 'POST' && authToken) {
             const source = req.socket.remoteAddress ?? 'unknown';
-            // Rate limiting check
+            // Rate limiting: check if this source has too many auth failures
             if (!rateLimiter.check(source)) {
-                sendJson(res, 429, { error: 'Too many requests' });
+                const retryAfter = rateLimiter.retryAfter(source);
+                const body = JSON.stringify({ error: 'Too many auth failures' });
+                res.writeHead(429, {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(body),
+                    'Retry-After': String(retryAfter),
+                });
+                res.end(body);
                 return;
             }
             const authHeader = req.headers['authorization'];
             if (!(0, auth_js_1.validateAuth)(authHeader, authToken)) {
-                rateLimiter.record(source);
+                rateLimiter.recordFailure(source);
                 log(`Auth failure from ${source}`);
                 sendJson(res, 401, { error: 'Unauthorized' });
                 return;
@@ -156,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()
@@ -178,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)) {
@@ -186,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,
@@ -208,9 +244,8 @@ function createServer(manifest, metrics) {
                         cost_usd: result.cost_usd,
                         session_id: input.session_id,
                     });
-                    // 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({
@@ -224,6 +259,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) {
@@ -373,6 +413,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)');
+        });
     });
 }
 /**
@@ -415,7 +462,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))
@@ -433,10 +481,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 };