@mauribadnights/clooks 0.1.0 → 0.2.2

package/dist/handlers.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetHandlerStates = resetHandlerStates;
 exports.getHandlerStates = getHandlerStates;
+exports.resetSessionIsolatedHandlers = resetSessionIsolatedHandlers;
 exports.executeHandlers = executeHandlers;
 exports.executeScriptHandler = executeScriptHandler;
 exports.executeInlineHandler = executeInlineHandler;
@@ -10,6 +11,8 @@ const child_process_1 = require("child_process");
 const url_1 = require("url");
 const path_1 = require("path");
 const constants_js_1 = require("./constants.js");
+const filter_js_1 = require("./filter.js");
+const llm_js_1 = require("./llm.js");
 /** Runtime state per handler ID */
 const handlerStates = new Map();
 function getState(id) {
@@ -28,53 +31,96 @@ function resetHandlerStates() {
 function getHandlerStates() {
     return new Map(handlerStates);
 }
+/**
+ * Reset handler states for handlers that have sessionIsolation: true.
+ * Called on SessionStart events.
+ */
+function resetSessionIsolatedHandlers(handlers) {
+    for (const handler of handlers) {
+        if (handler.sessionIsolation) {
+            const state = handlerStates.get(handler.id);
+            if (state) {
+                state.consecutiveFailures = 0;
+                state.disabled = false;
+                state.totalFires = 0;
+                state.totalErrors = 0;
+            }
+        }
+    }
+}
 /**
  * Execute all handlers for an event in parallel.
  * Returns merged results array.
+ * Optionally accepts pre-fetched context for LLM prompt rendering.
  */
-async function executeHandlers(_event, input, handlers) {
-    const promises = handlers.map(async (handler) => {
+async function executeHandlers(_event, input, handlers, context) {
+    // Separate LLM handlers from script/inline, applying shared pre-checks
+    const llmHandlers = [];
+    const otherPromises = [];
+    const skippedResults = [];
+    for (const handler of handlers) {
         // Skip disabled handlers (both manifest-disabled and auto-disabled)
         if (handler.enabled === false) {
-            return { id: handler.id, ok: true, output: undefined, duration_ms: 0 };
+            skippedResults.push({ id: handler.id, ok: true, output: undefined, duration_ms: 0 });
+            continue;
         }
         const state = getState(handler.id);
         if (state.disabled) {
-            return {
+            skippedResults.push({
                 id: handler.id,
                 ok: false,
                 error: `Auto-disabled after ${constants_js_1.MAX_CONSECUTIVE_FAILURES} consecutive failures`,
                 duration_ms: 0,
-            };
+            });
+            continue;
         }
-        state.totalFires++;
-        const start = performance.now();
-        let result;
-        try {
-            if (handler.type === 'script') {
-                result = await executeScriptHandler(handler, input);
-            }
-            else if (handler.type === 'inline') {
-                result = await executeInlineHandler(handler, input);
-            }
-            else {
-                result = {
+        // Evaluate keyword filter before execution
+        if (handler.filter) {
+            const inputStr = JSON.stringify(input);
+            if (!(0, filter_js_1.evaluateFilter)(handler.filter, inputStr)) {
+                skippedResults.push({
                     id: handler.id,
-                    ok: false,
-                    error: `Unknown handler type: ${handler.type}`,
+                    ok: true,
+                    output: undefined,
                     duration_ms: 0,
-                };
+                    filtered: true,
+                });
+                continue;
             }
         }
+        state.totalFires++;
+        if (handler.type === 'llm') {
+            llmHandlers.push(handler);
+        }
+        else {
+            // Execute script/inline handlers in parallel
+            otherPromises.push(executeOtherHandler(handler, input));
+        }
+    }
+    // Execute script/inline handlers in parallel
+    const otherResults = otherPromises.length > 0
+        ? await Promise.all(otherPromises)
+        : [];
+    // Execute LLM handlers with batching (graceful — never crashes)
+    let llmResults = [];
+    if (llmHandlers.length > 0) {
+        try {
+            llmResults = await (0, llm_js_1.executeLLMHandlersBatched)(llmHandlers, input, context ?? {});
+        }
         catch (err) {
-            result = {
-                id: handler.id,
+            // Graceful degradation: if LLM execution entirely fails, return error results
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            llmResults = llmHandlers.map(h => ({
+                id: h.id,
                 ok: false,
-                error: err instanceof Error ? err.message : String(err),
-                duration_ms: performance.now() - start,
-            };
+                error: `LLM execution failed: ${errorMsg}`,
+                duration_ms: 0,
+            }));
         }
-        // Update failure tracking
+    }
+    // Update failure tracking for all executed results
+    for (const result of [...otherResults, ...llmResults]) {
+        const state = getState(result.id);
         if (result.ok) {
             state.consecutiveFailures = 0;
         }
@@ -85,19 +131,49 @@ async function executeHandlers(_event, input, handlers) {
                 state.disabled = true;
             }
         }
-        return result;
-    });
-    return Promise.all(promises);
+    }
+    return [...skippedResults, ...otherResults, ...llmResults];
+}
+/**
+ * Execute a single script or inline handler with error handling.
+ */
+async function executeOtherHandler(handler, input) {
+    const start = performance.now();
+    try {
+        if (handler.type === 'script') {
+            return await executeScriptHandler(handler, input);
+        }
+        else if (handler.type === 'inline') {
+            return await executeInlineHandler(handler, input);
+        }
+        else {
+            return {
+                id: handler.id,
+                ok: false,
+                error: `Unknown handler type: ${handler.type}`,
+                duration_ms: 0,
+            };
+        }
+    }
+    catch (err) {
+        return {
+            id: handler.id,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+            duration_ms: performance.now() - start,
+        };
+    }
 }
 /**
  * Execute a script handler: spawn a child process, pipe input JSON to stdin,
  * read stdout as JSON response.
  */
 function executeScriptHandler(handler, input) {
-    const timeout = handler.timeout ?? constants_js_1.DEFAULT_HANDLER_TIMEOUT;
+    const h = handler;
+    const timeout = h.timeout ?? constants_js_1.DEFAULT_HANDLER_TIMEOUT;
     return new Promise((resolve) => {
         const start = performance.now();
-        const child = (0, child_process_1.spawn)('sh', ['-c', handler.command], {
+        const child = (0, child_process_1.spawn)('sh', ['-c', h.command], {
             stdio: ['pipe', 'pipe', 'pipe'],
             timeout,
         });
@@ -155,17 +231,18 @@ function executeScriptHandler(handler, input) {
  * Execute an inline handler: dynamically import a JS module and call its default export.
  */
 async function executeInlineHandler(handler, input) {
-    const timeout = handler.timeout ?? constants_js_1.DEFAULT_HANDLER_TIMEOUT;
+    const h = handler;
+    const timeout = h.timeout ?? constants_js_1.DEFAULT_HANDLER_TIMEOUT;
     const start = performance.now();
     try {
-        const modulePath = (0, path_1.resolve)(handler.module);
+        const modulePath = (0, path_1.resolve)(h.module);
         const moduleUrl = (0, url_1.pathToFileURL)(modulePath).href;
         const mod = await import(moduleUrl);
         if (typeof mod.default !== 'function') {
             return {
-                id: handler.id,
+                id: h.id,
                 ok: false,
-                error: `Module "${handler.module}" does not export a default function`,
+                error: `Module "${h.module}" does not export a default function`,
                 duration_ms: performance.now() - start,
             };
         }

package/dist/index.d.ts

@@ -4,6 +4,11 @@ export { MetricsCollector } from './metrics.js';
 export { migrate, restore, getSettingsPath } from './migrate.js';
 export type { MigratePathOptions } from './migrate.js';
 export { runDoctor } from './doctor.js';
-export { executeHandlers } from './handlers.js';
-export { DEFAULT_PORT, CONFIG_DIR, MANIFEST_PATH, PID_FILE, METRICS_FILE, LOG_FILE } from './constants.js';
-export type { HookEvent, HookInput, HandlerType, HandlerConfig, Manifest, HandlerResult, MetricEntry, HandlerState, DiagnosticResult, } from './types.js';
+export { executeHandlers, resetSessionIsolatedHandlers } from './handlers.js';
+export { startWatcher, stopWatcher } from './watcher.js';
+export { generateAuthToken, validateAuth } from './auth.js';
+export { evaluateFilter } from './filter.js';
+export { executeLLMHandler, executeLLMHandlersBatched, calculateCost, resetClient } from './llm.js';
+export { prefetchContext, renderPromptTemplate } from './prefetch.js';
+export { DEFAULT_PORT, CONFIG_DIR, MANIFEST_PATH, PID_FILE, METRICS_FILE, LOG_FILE, COSTS_FILE, DEFAULT_LLM_TIMEOUT, DEFAULT_LLM_MAX_TOKENS, LLM_PRICING } from './constants.js';
+export type { HookEvent, HookInput, HandlerType, HandlerConfig, ScriptHandlerConfig, InlineHandlerConfig, LLMHandlerConfig, LLMModel, Manifest, HandlerResult, MetricEntry, HandlerState, DiagnosticResult, PrefetchKey, PrefetchContext, TokenUsage, CostEntry, } from './types.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 // clooks — public API exports
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOG_FILE = exports.METRICS_FILE = exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = exports.executeHandlers = exports.runDoctor = exports.getSettingsPath = exports.restore = exports.migrate = exports.MetricsCollector = exports.createDefaultManifest = exports.validateManifest = exports.loadManifest = exports.isDaemonRunning = exports.stopDaemon = exports.startDaemon = exports.createServer = void 0;
+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.validateAuth = exports.generateAuthToken = exports.stopWatcher = exports.startWatcher = exports.resetSessionIsolatedHandlers = exports.executeHandlers = exports.runDoctor = exports.getSettingsPath = exports.restore = exports.migrate = exports.MetricsCollector = exports.createDefaultManifest = exports.validateManifest = exports.loadManifest = exports.isDaemonRunning = exports.stopDaemon = exports.startDaemon = exports.createServer = 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; } });
@@ -21,6 +21,23 @@ var doctor_js_1 = require("./doctor.js");
 Object.defineProperty(exports, "runDoctor", { enumerable: true, get: function () { return doctor_js_1.runDoctor; } });
 var handlers_js_1 = require("./handlers.js");
 Object.defineProperty(exports, "executeHandlers", { enumerable: true, get: function () { return handlers_js_1.executeHandlers; } });
+Object.defineProperty(exports, "resetSessionIsolatedHandlers", { enumerable: true, get: function () { return handlers_js_1.resetSessionIsolatedHandlers; } });
+var watcher_js_1 = require("./watcher.js");
+Object.defineProperty(exports, "startWatcher", { enumerable: true, get: function () { return watcher_js_1.startWatcher; } });
+Object.defineProperty(exports, "stopWatcher", { enumerable: true, get: function () { return watcher_js_1.stopWatcher; } });
+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; } });
+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");
+Object.defineProperty(exports, "executeLLMHandler", { enumerable: true, get: function () { return llm_js_1.executeLLMHandler; } });
+Object.defineProperty(exports, "executeLLMHandlersBatched", { enumerable: true, get: function () { return llm_js_1.executeLLMHandlersBatched; } });
+Object.defineProperty(exports, "calculateCost", { enumerable: true, get: function () { return llm_js_1.calculateCost; } });
+Object.defineProperty(exports, "resetClient", { enumerable: true, get: function () { return llm_js_1.resetClient; } });
+var prefetch_js_1 = require("./prefetch.js");
+Object.defineProperty(exports, "prefetchContext", { enumerable: true, get: function () { return prefetch_js_1.prefetchContext; } });
+Object.defineProperty(exports, "renderPromptTemplate", { enumerable: true, get: function () { return prefetch_js_1.renderPromptTemplate; } });
 var constants_js_1 = require("./constants.js");
 Object.defineProperty(exports, "DEFAULT_PORT", { enumerable: true, get: function () { return constants_js_1.DEFAULT_PORT; } });
 Object.defineProperty(exports, "CONFIG_DIR", { enumerable: true, get: function () { return constants_js_1.CONFIG_DIR; } });
@@ -28,3 +45,7 @@ Object.defineProperty(exports, "MANIFEST_PATH", { enumerable: true, get: functio
 Object.defineProperty(exports, "PID_FILE", { enumerable: true, get: function () { return constants_js_1.PID_FILE; } });
 Object.defineProperty(exports, "METRICS_FILE", { enumerable: true, get: function () { return constants_js_1.METRICS_FILE; } });
 Object.defineProperty(exports, "LOG_FILE", { enumerable: true, get: function () { return constants_js_1.LOG_FILE; } });
+Object.defineProperty(exports, "COSTS_FILE", { enumerable: true, get: function () { return constants_js_1.COSTS_FILE; } });
+Object.defineProperty(exports, "DEFAULT_LLM_TIMEOUT", { enumerable: true, get: function () { return constants_js_1.DEFAULT_LLM_TIMEOUT; } });
+Object.defineProperty(exports, "DEFAULT_LLM_MAX_TOKENS", { enumerable: true, get: function () { return constants_js_1.DEFAULT_LLM_MAX_TOKENS; } });
+Object.defineProperty(exports, "LLM_PRICING", { enumerable: true, get: function () { return constants_js_1.LLM_PRICING; } });

package/dist/llm.d.ts

@@ -0,0 +1,19 @@
+import type { LLMHandlerConfig, HandlerResult, HookInput, PrefetchContext, TokenUsage } from './types.js';
+/** Reset client (for testing) */
+export declare function resetClient(): void;
+/**
+ * Calculate cost in USD from token usage and model.
+ */
+export declare function calculateCost(model: string, usage: TokenUsage): number;
+/**
+ * Execute a single LLM handler: render prompt, call Messages API, return result.
+ */
+export declare function executeLLMHandler(handler: LLMHandlerConfig, input: HookInput, context: PrefetchContext): Promise<HandlerResult>;
+/**
+ * Execute multiple LLM handlers, batching those with the same batchGroup.
+ *
+ * Strategy: handlers with the same batchGroup get their prompts combined into
+ * a single API call with a structured multi-task prompt. Handlers without a
+ * batchGroup are executed individually.
+ */
+export declare function executeLLMHandlersBatched(handlers: LLMHandlerConfig[], input: HookInput, context: PrefetchContext): Promise<HandlerResult[]>;

package/dist/llm.js

@@ -0,0 +1,225 @@
+"use strict";
+// clooks LLM handler execution — Anthropic Messages API with batching
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetClient = resetClient;
+exports.calculateCost = calculateCost;
+exports.executeLLMHandler = executeLLMHandler;
+exports.executeLLMHandlersBatched = executeLLMHandlersBatched;
+const prefetch_js_1 = require("./prefetch.js");
+const constants_js_1 = require("./constants.js");
+/** Lazy-loaded Anthropic SDK client */
+let anthropicClient = null;
+async function getClient() {
+    if (!anthropicClient) {
+        if (!process.env.ANTHROPIC_API_KEY) {
+            throw new Error('ANTHROPIC_API_KEY environment variable is not set. ' +
+                'LLM handlers require a valid API key.');
+        }
+        try {
+            // Dynamic import with variable to avoid TypeScript resolving the module at compile time
+            const sdkModule = '@anthropic-ai/sdk';
+            const { default: Anthropic } = await import(/* webpackIgnore: true */ sdkModule);
+            anthropicClient = new Anthropic();
+        }
+        catch (err) {
+            throw new Error('Anthropic SDK not installed. Run: npm install @anthropic-ai/sdk\n' +
+                'Then set ANTHROPIC_API_KEY environment variable.');
+        }
+    }
+    return anthropicClient;
+}
+/** Reset client (for testing) */
+function resetClient() {
+    anthropicClient = null;
+}
+/**
+ * Calculate cost in USD from token usage and model.
+ */
+function calculateCost(model, usage) {
+    const pricing = constants_js_1.LLM_PRICING[model];
+    if (!pricing)
+        return 0;
+    const inputCost = (usage.input_tokens / 1_000_000) * pricing.input;
+    const outputCost = (usage.output_tokens / 1_000_000) * pricing.output;
+    return inputCost + outputCost;
+}
+/**
+ * Execute a single LLM handler: render prompt, call Messages API, return result.
+ */
+async function executeLLMHandler(handler, input, context) {
+    const start = performance.now();
+    const timeout = handler.timeout ?? constants_js_1.DEFAULT_LLM_TIMEOUT;
+    const maxTokens = handler.maxTokens ?? constants_js_1.DEFAULT_LLM_MAX_TOKENS;
+    try {
+        const client = await getClient();
+        const prompt = (0, prefetch_js_1.renderPromptTemplate)(handler.prompt, input, context);
+        const apiCall = client.messages.create({
+            model: handler.model,
+            max_tokens: maxTokens,
+            messages: [{ role: 'user', content: prompt }],
+        });
+        const timeoutPromise = new Promise((_resolve, reject) => setTimeout(() => reject(new Error(`LLM handler timed out after ${timeout}ms`)), timeout));
+        const response = await Promise.race([apiCall, timeoutPromise]);
+        const text = response.content?.[0]?.text ?? '';
+        const usage = {
+            input_tokens: response.usage?.input_tokens ?? 0,
+            output_tokens: response.usage?.output_tokens ?? 0,
+        };
+        const cost_usd = calculateCost(handler.model, usage);
+        return {
+            id: handler.id,
+            ok: true,
+            output: { additionalContext: text },
+            duration_ms: performance.now() - start,
+            usage,
+            cost_usd,
+        };
+    }
+    catch (err) {
+        return {
+            id: handler.id,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+            duration_ms: performance.now() - start,
+        };
+    }
+}
+/**
+ * Execute a batched group of LLM handlers: combine prompts into a single
+ * multi-task API call, parse JSON response back into individual results.
+ */
+async function executeBatchGroup(handlers, input, context) {
+    const start = performance.now();
+    // Use model from first handler; warn if others differ
+    const model = handlers[0].model;
+    for (let i = 1; i < handlers.length; i++) {
+        if (handlers[i].model !== model) {
+            console.warn(`[clooks] Batch group "${handlers[0].batchGroup}": handler "${handlers[i].id}" ` +
+                `uses model "${handlers[i].model}" but batch uses "${model}". Using "${model}".`);
+        }
+    }
+    // Use highest maxTokens and timeout among group members
+    const maxTokens = Math.max(...handlers.map(h => h.maxTokens ?? constants_js_1.DEFAULT_LLM_MAX_TOKENS));
+    const timeout = Math.max(...handlers.map(h => h.timeout ?? constants_js_1.DEFAULT_LLM_TIMEOUT));
+    // Build combined prompt
+    const taskSections = handlers.map((h, i) => {
+        const rendered = (0, prefetch_js_1.renderPromptTemplate)(h.prompt, input, context);
+        return `TASK "${h.id}":\n${rendered}`;
+    });
+    const combinedPrompt = 'You must complete multiple analysis tasks. Respond with a JSON object where each key is the task ID and the value is your analysis for that task.\n\n' +
+        taskSections.join('\n\n') +
+        '\n\nRespond ONLY with valid JSON in this format:\n' +
+        '{' + handlers.map(h => `"${h.id}": <your analysis>`).join(', ') + '}';
+    try {
+        const client = await getClient();
+        const apiCall = client.messages.create({
+            model,
+            max_tokens: maxTokens,
+            messages: [{ role: 'user', content: combinedPrompt }],
+        });
+        const timeoutPromise = new Promise((_resolve, reject) => setTimeout(() => reject(new Error(`Batched LLM call timed out after ${timeout}ms`)), timeout));
+        const response = await Promise.race([apiCall, timeoutPromise]);
+        const text = response.content?.[0]?.text ?? '';
+        const totalUsage = {
+            input_tokens: response.usage?.input_tokens ?? 0,
+            output_tokens: response.usage?.output_tokens ?? 0,
+        };
+        // Try to parse as JSON and split results
+        let parsed = {};
+        try {
+            // Strip markdown code fences if present
+            const cleaned = text.replace(/^```(?:json)?\s*\n?/m, '').replace(/\n?```\s*$/m, '').trim();
+            parsed = JSON.parse(cleaned);
+        }
+        catch {
+            // If JSON parsing fails, give all handlers the raw text
+            const duration = performance.now() - start;
+            return handlers.map(h => ({
+                id: h.id,
+                ok: true,
+                output: { additionalContext: text },
+                duration_ms: duration,
+                usage: splitUsage(totalUsage, handlers.length),
+                cost_usd: calculateCost(model, splitUsage(totalUsage, handlers.length)),
+            }));
+        }
+        // Distribute results to each handler
+        const duration = performance.now() - start;
+        const perHandlerUsage = splitUsage(totalUsage, handlers.length);
+        return handlers.map(h => {
+            const handlerResult = parsed[h.id];
+            const resultText = typeof handlerResult === 'string'
+                ? handlerResult
+                : JSON.stringify(handlerResult ?? '');
+            return {
+                id: h.id,
+                ok: true,
+                output: { additionalContext: resultText },
+                duration_ms: duration,
+                usage: perHandlerUsage,
+                cost_usd: calculateCost(model, perHandlerUsage),
+            };
+        });
+    }
+    catch (err) {
+        const duration = performance.now() - start;
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        return handlers.map(h => ({
+            id: h.id,
+            ok: false,
+            error: errorMsg,
+            duration_ms: duration,
+        }));
+    }
+}
+/**
+ * Split total token usage evenly across N handlers (for cost attribution in batches).
+ */
+function splitUsage(total, count) {
+    if (count <= 0)
+        return { input_tokens: 0, output_tokens: 0 };
+    return {
+        input_tokens: Math.ceil(total.input_tokens / count),
+        output_tokens: Math.ceil(total.output_tokens / count),
+    };
+}
+/**
+ * Execute multiple LLM handlers, batching those with the same batchGroup.
+ *
+ * Strategy: handlers with the same batchGroup get their prompts combined into
+ * a single API call with a structured multi-task prompt. Handlers without a
+ * batchGroup are executed individually.
+ */
+async function executeLLMHandlersBatched(handlers, input, context) {
+    // Group by batchGroup
+    const grouped = new Map();
+    const ungrouped = [];
+    for (const handler of handlers) {
+        if (handler.batchGroup) {
+            const existing = grouped.get(handler.batchGroup) ?? [];
+            existing.push(handler);
+            grouped.set(handler.batchGroup, existing);
+        }
+        else {
+            ungrouped.push(handler);
+        }
+    }
+    // Execute all in parallel: individual calls + batch groups
+    const promises = [];
+    // Individual (ungrouped) handlers
+    for (const handler of ungrouped) {
+        promises.push(executeLLMHandler(handler, input, context).then(r => [r]));
+    }
+    // Batch groups
+    for (const [_groupId, groupHandlers] of grouped) {
+        if (groupHandlers.length === 1) {
+            // Single handler in group — no point batching
+            promises.push(executeLLMHandler(groupHandlers[0], input, context).then(r => [r]));
+        }
+        else {
+            promises.push(executeBatchGroup(groupHandlers, input, context));
+        }
+    }
+    const resultArrays = await Promise.all(promises);
+    return resultArrays.flat();
+}

package/dist/manifest.d.ts

@@ -12,4 +12,4 @@ export declare function validateManifest(manifest: Manifest): void;
 /**
  * Create a default commented example manifest.yaml in CONFIG_DIR.
  */
-export declare function createDefaultManifest(): string;
+export declare function createDefaultManifest(authToken?: string): string;

package/dist/manifest.js

@@ -48,15 +48,40 @@ function validateManifest(manifest) {
                 throw new Error(`Duplicate handler id: "${handler.id}"`);
             }
             seenIds.add(handler.id);
-            if (!handler.type || !['script', 'inline'].includes(handler.type)) {
-                throw new Error(`Handler "${handler.id}" must have type "script" or "inline"`);
+            if (!handler.type || !['script', 'inline', 'llm'].includes(handler.type)) {
+                throw new Error(`Handler "${handler.id}" must have type "script", "inline", or "llm"`);
             }
-            if (handler.type === 'script' && !handler.command) {
+            if (handler.type === 'script' && !('command' in handler && handler.command)) {
                 throw new Error(`Script handler "${handler.id}" must have a "command" field`);
             }
-            if (handler.type === 'inline' && !handler.module) {
+            if (handler.type === 'inline' && !('module' in handler && handler.module)) {
                 throw new Error(`Inline handler "${handler.id}" must have a "module" field`);
             }
+            if (handler.type === 'llm') {
+                const llm = handler;
+                if (!llm.model) {
+                    throw new Error(`LLM handler "${handler.id}" must have a "model" field`);
+                }
+                if (!llm.prompt) {
+                    throw new Error(`LLM handler "${handler.id}" must have a "prompt" field`);
+                }
+                const validModels = ['claude-haiku-4-5', 'claude-sonnet-4-6', 'claude-opus-4-6'];
+                if (!validModels.includes(llm.model)) {
+                    throw new Error(`LLM handler "${handler.id}" model must be one of: ${validModels.join(', ')}`);
+                }
+            }
+        }
+    }
+    // Validate prefetch if present
+    if (manifest.prefetch !== undefined) {
+        if (!Array.isArray(manifest.prefetch)) {
+            throw new Error('prefetch must be an array');
+        }
+        const validKeys = ['transcript', 'git_status', 'git_diff'];
+        for (const key of manifest.prefetch) {
+            if (!validKeys.includes(key)) {
+                throw new Error(`Invalid prefetch key: "${key}". Valid keys: ${validKeys.join(', ')}`);
+            }
         }
     }
     // Validate settings if present
@@ -77,10 +102,17 @@ function validateManifest(manifest) {
 /**
  * Create a default commented example manifest.yaml in CONFIG_DIR.
  */
-function createDefaultManifest() {
+function createDefaultManifest(authToken) {
     if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
         (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
     }
+    const settings = {
+        port: 7890,
+        logLevel: 'info',
+    };
+    if (authToken) {
+        settings.authToken = authToken;
+    }
     const example = {
         handlers: {
             PreToolUse: [
@@ -93,10 +125,7 @@ function createDefaultManifest() {
                 },
             ],
         },
-        settings: {
-            port: 7890,
-            logLevel: 'info',
-        },
+        settings,
     };
     const yamlStr = '# clooks manifest — define your hook handlers here\n' +
         '# Docs: https://github.com/mauribadnights/clooks\n' +

package/dist/metrics.d.ts

@@ -1,4 +1,4 @@
-import type { MetricEntry } from './types.js';
+import type { MetricEntry, CostEntry } from './types.js';
 interface AggregatedStats {
     event: string;
     fires: number;
@@ -8,8 +8,15 @@ interface AggregatedStats {
     maxDuration: number;
 }
 export declare class MetricsCollector {
+    private static readonly MAX_ENTRIES;
     private entries;
-    /** Record a metric entry in memory and append to disk. */
+    private ringIndex;
+    private totalRecorded;
+    private static readonly METRICS_MAX_BYTES;
+    private static readonly COSTS_MAX_BYTES;
+    /** Rotate a log file if it exceeds maxBytes. Keeps one backup (.1). */
+    private rotateIfNeeded;
+    /** Record a metric entry in memory (ring buffer) and append to disk. */
     record(entry: MetricEntry): void;
     /** Get aggregated stats per event type. */
     getStats(): AggregatedStats[];
@@ -21,6 +28,26 @@ export declare class MetricsCollector {
     formatStatsTable(): string;
     /** Estimate how many process spawns were saved. */
     estimateSpawnsSaved(): number;
+    /** Track a cost entry — appends to costs.jsonl. */
+    trackCost(entry: CostEntry): void;
+    /** Get cost statistics from persisted cost entries. */
+    getCostStats(): {
+        totalCost: number;
+        totalTokens: number;
+        byModel: Record<string, {
+            cost: number;
+            tokens: number;
+        }>;
+        byHandler: Record<string, {
+            cost: number;
+            tokens: number;
+            calls: number;
+        }>;
+    };
+    /** Format cost data as a CLI-friendly table. */
+    formatCostTable(): string;
+    /** Load cost entries from disk. */
+    private loadCosts;
     /** Load all entries from disk + memory (deduped by combining disk file). */
     private loadAll;
 }