@mauribadnights/clooks 0.2.2 → 0.3.0

package/dist/plugin.js

@@ -0,0 +1,279 @@
+"use strict";
+// clooks plugin system — load, install, uninstall, merge plugin manifests
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRegistry = loadRegistry;
+exports.saveRegistry = saveRegistry;
+exports.validatePluginManifest = validatePluginManifest;
+exports.loadPlugins = loadPlugins;
+exports.mergeManifests = mergeManifests;
+exports.installPlugin = installPlugin;
+exports.uninstallPlugin = uninstallPlugin;
+exports.listPlugins = listPlugins;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+const constants_js_1 = require("./constants.js");
+/**
+ * Load the plugin registry (installed.json).
+ */
+function loadRegistry(registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    if (!(0, fs_1.existsSync)(registryPath)) {
+        return { plugins: [] };
+    }
+    try {
+        const raw = (0, fs_1.readFileSync)(registryPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.plugins)) {
+            return { plugins: [] };
+        }
+        return parsed;
+    }
+    catch {
+        return { plugins: [] };
+    }
+}
+/**
+ * Save the plugin registry.
+ */
+function saveRegistry(registry, registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const dir = (0, path_1.resolve)(registryPath, '..');
+    if (!(0, fs_1.existsSync)(dir)) {
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(registryPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Validate a plugin manifest.
+ * Similar to validateManifest but checks plugin-specific fields (name, version required).
+ */
+function validatePluginManifest(manifest) {
+    if (!manifest.name || typeof manifest.name !== 'string') {
+        throw new Error('Plugin manifest must have a "name" string field');
+    }
+    if (!manifest.version || typeof manifest.version !== 'string') {
+        throw new Error('Plugin manifest must have a "version" string field');
+    }
+    if (!manifest.handlers || typeof manifest.handlers !== 'object') {
+        throw new Error('Plugin manifest must have a "handlers" object');
+    }
+    const seenIds = new Set();
+    for (const [eventName, handlers] of Object.entries(manifest.handlers)) {
+        if (!constants_js_1.HOOK_EVENTS.includes(eventName)) {
+            throw new Error(`Unknown hook event: "${eventName}". Valid events: ${constants_js_1.HOOK_EVENTS.join(', ')}`);
+        }
+        if (!Array.isArray(handlers)) {
+            throw new Error(`Handlers for "${eventName}" must be an array`);
+        }
+        for (const handler of handlers) {
+            if (!handler.id || typeof handler.id !== 'string') {
+                throw new Error(`Each handler must have a string "id" (event: ${eventName})`);
+            }
+            if (seenIds.has(handler.id)) {
+                throw new Error(`Duplicate handler id: "${handler.id}"`);
+            }
+            seenIds.add(handler.id);
+            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' && !('command' in handler && handler.command)) {
+                throw new Error(`Script handler "${handler.id}" must have a "command" field`);
+            }
+            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(', ')}`);
+            }
+        }
+    }
+}
+/**
+ * Load all installed plugins and return their manifests.
+ */
+function loadPlugins(pluginsDir = constants_js_1.PLUGINS_DIR, registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const registry = loadRegistry(registryPath);
+    const results = [];
+    for (const plugin of registry.plugins) {
+        const manifestPath = (0, path_1.join)(plugin.path, constants_js_1.PLUGIN_MANIFEST_NAME);
+        if (!(0, fs_1.existsSync)(manifestPath)) {
+            // Skip plugins with missing manifests (silently — doctor will catch this)
+            continue;
+        }
+        try {
+            const raw = (0, fs_1.readFileSync)(manifestPath, 'utf-8');
+            const parsed = (0, yaml_1.parse)(raw);
+            validatePluginManifest(parsed);
+            results.push({ name: plugin.name, manifest: parsed });
+        }
+        catch {
+            // Skip plugins with invalid manifests
+            continue;
+        }
+    }
+    return results;
+}
+/**
+ * Namespace a handler ID with a plugin name.
+ */
+function namespaceId(pluginName, handlerId) {
+    return `${pluginName}/${handlerId}`;
+}
+/**
+ * Merge user manifest + plugin manifests into a composite manifest.
+ * Plugin handler IDs are namespaced as "pluginName/handlerId".
+ * Prefetch keys are unioned.
+ * Settings come from user manifest only.
+ */
+function mergeManifests(userManifest, plugins) {
+    // Deep clone user manifest handlers
+    const merged = {
+        handlers: {},
+        prefetch: userManifest.prefetch ? [...userManifest.prefetch] : undefined,
+        settings: userManifest.settings,
+    };
+    // Copy user handlers
+    for (const [event, handlers] of Object.entries(userManifest.handlers)) {
+        if (handlers) {
+            merged.handlers[event] = [...handlers];
+        }
+    }
+    // Merge plugin handlers
+    for (const { name: pluginName, manifest: pluginManifest } of plugins) {
+        // Union prefetch keys
+        if (pluginManifest.prefetch && pluginManifest.prefetch.length > 0) {
+            if (!merged.prefetch) {
+                merged.prefetch = [];
+            }
+            for (const key of pluginManifest.prefetch) {
+                if (!merged.prefetch.includes(key)) {
+                    merged.prefetch.push(key);
+                }
+            }
+        }
+        // Namespace and add handlers
+        for (const [event, handlers] of Object.entries(pluginManifest.handlers)) {
+            if (!handlers)
+                continue;
+            const hookEvent = event;
+            if (!merged.handlers[hookEvent]) {
+                merged.handlers[hookEvent] = [];
+            }
+            for (const handler of handlers) {
+                const namespacedHandler = {
+                    ...handler,
+                    id: namespaceId(pluginName, handler.id),
+                };
+                // Namespace depends references too
+                if (namespacedHandler.depends) {
+                    namespacedHandler.depends = namespacedHandler.depends.map(dep => 
+                    // If the dep already contains a slash, it references another plugin — leave it
+                    dep.includes('/') ? dep : namespaceId(pluginName, dep));
+                }
+                merged.handlers[hookEvent].push(namespacedHandler);
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Install a plugin from a local directory path.
+ * 1. Read clooks-plugin.yaml from the path
+ * 2. Validate it
+ * 3. Copy the directory to plugins dir under {name}/
+ * 4. Register in installed.json
+ * 5. Resolve $PLUGIN_DIR in handler commands to the installed path
+ */
+function installPlugin(sourcePath, pluginsDir = constants_js_1.PLUGINS_DIR, registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const resolvedSource = (0, path_1.resolve)(sourcePath);
+    const manifestPath = (0, path_1.join)(resolvedSource, constants_js_1.PLUGIN_MANIFEST_NAME);
+    if (!(0, fs_1.existsSync)(manifestPath)) {
+        throw new Error(`No ${constants_js_1.PLUGIN_MANIFEST_NAME} found at ${resolvedSource}`);
+    }
+    const raw = (0, fs_1.readFileSync)(manifestPath, 'utf-8');
+    const pluginManifest = (0, yaml_1.parse)(raw);
+    validatePluginManifest(pluginManifest);
+    const destPath = (0, path_1.join)(pluginsDir, pluginManifest.name);
+    // Ensure plugins dir exists
+    if (!(0, fs_1.existsSync)(pluginsDir)) {
+        (0, fs_1.mkdirSync)(pluginsDir, { recursive: true });
+    }
+    // Remove existing installation if present
+    if ((0, fs_1.existsSync)(destPath)) {
+        (0, fs_1.rmSync)(destPath, { recursive: true, force: true });
+    }
+    // Copy plugin directory to plugins dir
+    (0, fs_1.cpSync)(resolvedSource, destPath, { recursive: true });
+    // Resolve $PLUGIN_DIR in handler commands within the installed copy
+    const installedManifestPath = (0, path_1.join)(destPath, constants_js_1.PLUGIN_MANIFEST_NAME);
+    const installedRaw = (0, fs_1.readFileSync)(installedManifestPath, 'utf-8');
+    const resolved = installedRaw.replace(/\$PLUGIN_DIR/g, destPath);
+    (0, fs_1.writeFileSync)(installedManifestPath, resolved, 'utf-8');
+    // Resolve relative extras.readme to absolute path
+    const resolvedManifest = (0, yaml_1.parse)(resolved);
+    if (resolvedManifest.extras?.readme && !resolvedManifest.extras.readme.startsWith('/')) {
+        resolvedManifest.extras.readme = (0, path_1.join)(destPath, resolvedManifest.extras.readme);
+        (0, fs_1.writeFileSync)(installedManifestPath, (0, yaml_1.stringify)(resolvedManifest), 'utf-8');
+    }
+    // Update registry
+    const registry = loadRegistry(registryPath);
+    // Remove any existing entry for this plugin
+    registry.plugins = registry.plugins.filter(p => p.name !== pluginManifest.name);
+    const entry = {
+        name: pluginManifest.name,
+        version: pluginManifest.version,
+        path: destPath,
+        installedAt: new Date().toISOString(),
+    };
+    registry.plugins.push(entry);
+    saveRegistry(registry, registryPath);
+    return entry;
+}
+/**
+ * Uninstall a plugin by name.
+ * 1. Remove from installed.json
+ * 2. Delete the plugin directory
+ */
+function uninstallPlugin(name, pluginsDir = constants_js_1.PLUGINS_DIR, registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const registry = loadRegistry(registryPath);
+    const plugin = registry.plugins.find(p => p.name === name);
+    if (!plugin) {
+        throw new Error(`Plugin "${name}" is not installed`);
+    }
+    // Remove from registry
+    registry.plugins = registry.plugins.filter(p => p.name !== name);
+    saveRegistry(registry, registryPath);
+    // Delete plugin directory
+    const pluginPath = (0, path_1.join)(pluginsDir, name);
+    if ((0, fs_1.existsSync)(pluginPath)) {
+        (0, fs_1.rmSync)(pluginPath, { recursive: true, force: true });
+    }
+}
+/**
+ * List installed plugins.
+ */
+function listPlugins(registryPath = constants_js_1.PLUGIN_REGISTRY) {
+    const registry = loadRegistry(registryPath);
+    return registry.plugins;
+}

package/dist/ratelimit.d.ts

@@ -0,0 +1,12 @@
+export declare class RateLimiter {
+    private attempts;
+    private maxAttempts;
+    private windowMs;
+    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;
+    /** Clean up old entries. */
+    cleanup(): void;
+}

package/dist/ratelimit.js

@@ -0,0 +1,44 @@
+"use strict";
+// clooks rate limiting — protect against auth brute-force
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+class RateLimiter {
+    attempts = new Map(); // source → timestamps
+    maxAttempts;
+    windowMs;
+    constructor(maxAttempts = 10, windowMs = 60_000) {
+        this.maxAttempts = maxAttempts;
+        this.windowMs = windowMs;
+    }
+    /** Check if source is rate-limited. Returns true if allowed. */
+    check(source) {
+        const now = Date.now();
+        const timestamps = this.attempts.get(source);
+        if (!timestamps)
+            return true;
+        // Count recent attempts within window
+        const recent = timestamps.filter(t => now - t <= this.windowMs);
+        return recent.length < this.maxAttempts;
+    }
+    /** Record an attempt from source. */
+    record(source) {
+        const now = Date.now();
+        const timestamps = this.attempts.get(source) ?? [];
+        timestamps.push(now);
+        this.attempts.set(source, timestamps);
+    }
+    /** Clean up old entries. */
+    cleanup() {
+        const now = Date.now();
+        for (const [source, timestamps] of this.attempts) {
+            const recent = timestamps.filter(t => now - t <= this.windowMs);
+            if (recent.length === 0) {
+                this.attempts.delete(source);
+            }
+            else {
+                this.attempts.set(source, recent);
+            }
+        }
+    }
+}
+exports.RateLimiter = RateLimiter;

package/dist/server.d.ts

@@ -1,6 +1,8 @@
 import { type Server } from 'http';
 import type { FSWatcher } from 'fs';
 import { MetricsCollector } from './metrics.js';
+import { DenyCache } from './shortcircuit.js';
+import { RateLimiter } from './ratelimit.js';
 import type { Manifest } from './types.js';
 export interface ServerContext {
     server: Server;
@@ -8,6 +10,9 @@ export interface ServerContext {
     startTime: number;
     manifest: Manifest;
     watcher?: FSWatcher;
+    denyCache: DenyCache;
+    rateLimiter: RateLimiter;
+    cleanupInterval?: ReturnType<typeof setInterval>;
 }
 /**
  * Create the HTTP server for hook handling.

package/dist/server.js

@@ -13,6 +13,8 @@ const handlers_js_1 = require("./handlers.js");
 const prefetch_js_1 = require("./prefetch.js");
 const watcher_js_1 = require("./watcher.js");
 const auth_js_1 = require("./auth.js");
+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");
 function log(msg) {
@@ -82,13 +84,43 @@ function sendJson(res, status, data) {
  */
 function createServer(manifest, metrics) {
     const startTime = Date.now();
-    const ctx = { server: null, metrics, startTime, manifest };
+    const denyCache = new shortcircuit_js_1.DenyCache();
+    const rateLimiter = new ratelimit_js_1.RateLimiter();
+    const ctx = {
+        server: null,
+        metrics,
+        startTime,
+        manifest,
+        denyCache,
+        rateLimiter,
+    };
     const authToken = manifest.settings?.authToken ?? '';
+    // Periodic cleanup for deny cache and rate limiter (every 60s)
+    ctx.cleanupInterval = setInterval(() => {
+        denyCache.cleanup();
+        rateLimiter.cleanup();
+    }, 60_000);
+    // Unref so it doesn't keep the process alive
+    if (ctx.cleanupInterval && typeof ctx.cleanupInterval === 'object' && 'unref' in ctx.cleanupInterval) {
+        ctx.cleanupInterval.unref();
+    }
     const server = (0, http_1.createServer)(async (req, res) => {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
-        // Health check endpoint — no auth required for monitoring
+        // Public health endpoint — minimal, no auth
         if (method === 'GET' && url === '/health') {
+            sendJson(res, 200, { status: 'ok' });
+            return;
+        }
+        // Detailed health endpoint — authenticated if authToken configured
+        if (method === 'GET' && url === '/health/detail') {
+            if (authToken) {
+                const authHeader = req.headers['authorization'];
+                if (!(0, auth_js_1.validateAuth)(authHeader, authToken)) {
+                    sendJson(res, 401, { error: 'Unauthorized' });
+                    return;
+                }
+            }
             const handlerCount = Object.values(ctx.manifest.handlers)
                 .reduce((sum, arr) => sum + (arr?.length ?? 0), 0);
             sendJson(res, 200, {
@@ -101,9 +133,16 @@ function createServer(manifest, metrics) {
         }
         // Auth check for all POST requests
         if (method === 'POST' && authToken) {
+            const source = req.socket.remoteAddress ?? 'unknown';
+            // Rate limiting check
+            if (!rateLimiter.check(source)) {
+                sendJson(res, 429, { error: 'Too many requests' });
+                return;
+            }
             const authHeader = req.headers['authorization'];
             if (!(0, auth_js_1.validateAuth)(authHeader, authToken)) {
-                log(`Auth failure from ${req.socket.remoteAddress}`);
+                rateLimiter.record(source);
+                log(`Auth failure from ${source}`);
                 sendJson(res, 401, { error: 'Unauthorized' });
                 return;
             }
@@ -139,6 +178,14 @@ function createServer(manifest, metrics) {
                 sendJson(res, 400, { error: 'Invalid JSON body' });
                 return;
             }
+            // 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)) {
+                    log(`PostToolUse skipped — PreToolUse denied for ${input.tool_name}`);
+                    sendJson(res, 200, {});
+                    return;
+                }
+            }
             log(`Hook: ${eventName} (${handlers.length} handler${handlers.length > 1 ? 's' : ''})`);
             try {
                 // Pre-fetch shared context if configured
@@ -163,7 +210,6 @@ function createServer(manifest, metrics) {
                     });
                     // Track cost for LLM handlers
                     if (result.usage && result.cost_usd !== undefined && result.cost_usd > 0) {
-                        // Find the handler config to get model info
                         const handlerConfig = handlers.find(h => h.id === result.id);
                         if (handlerConfig && handlerConfig.type === 'llm') {
                             const llmConfig = handlerConfig;
@@ -179,6 +225,27 @@ function createServer(manifest, metrics) {
                         }
                     }
                 }
+                // Short-circuit: if PreToolUse had a deny, record it in the cache
+                if (event === 'PreToolUse' && input.tool_name && input.session_id) {
+                    const hasDeny = results.some(r => {
+                        if (!r.ok || !r.output || typeof r.output !== 'object')
+                            return false;
+                        const out = r.output;
+                        // Check hookSpecificOutput.permissionDecision === 'deny'
+                        if (out.hookSpecificOutput && typeof out.hookSpecificOutput === 'object') {
+                            const hso = out.hookSpecificOutput;
+                            if (hso.permissionDecision === 'deny')
+                                return true;
+                        }
+                        // Check decision === 'block'
+                        if (out.decision === 'block')
+                            return true;
+                        return false;
+                    });
+                    if (hasDeny) {
+                        denyCache.recordDeny(input.session_id, input.tool_name);
+                    }
+                }
                 const merged = mergeResults(results);
                 log(`  -> ${results.filter((r) => r.ok).length}/${results.length} ok, response keys: ${Object.keys(merged).join(', ') || '(empty)'}`);
                 sendJson(res, 200, merged);
@@ -222,7 +289,52 @@ function startDaemon(manifest, metrics, options) {
             if (!options?.noWatch) {
                 ctx.watcher = (0, watcher_js_1.startWatcher)(constants_js_1.MANIFEST_PATH, () => {
                     try {
-                        const newManifest = (0, manifest_js_1.loadManifest)();
+                        const newManifest = (0, manifest_js_1.loadCompositeManifest)();
+                        // Diff handlers: find removed, added, and changed handlers
+                        const oldIds = new Set();
+                        const oldHandlerMap = new Map();
+                        for (const handlers of Object.values(ctx.manifest.handlers)) {
+                            if (!handlers)
+                                continue;
+                            for (const h of handlers) {
+                                oldIds.add(h.id);
+                                oldHandlerMap.set(h.id, h);
+                            }
+                        }
+                        const newIds = new Set();
+                        const newHandlerMap = new Map();
+                        for (const handlers of Object.values(newManifest.handlers)) {
+                            if (!handlers)
+                                continue;
+                            for (const h of handlers) {
+                                newIds.add(h.id);
+                                newHandlerMap.set(h.id, h);
+                            }
+                        }
+                        // Removed handlers: clean up their state
+                        for (const id of oldIds) {
+                            if (!newIds.has(id)) {
+                                (0, handlers_js_1.cleanupHandlerState)(id);
+                                log(`  Handler removed: ${id}`);
+                            }
+                        }
+                        // Added handlers: initialize fresh state (happens automatically on first use)
+                        for (const id of newIds) {
+                            if (!oldIds.has(id)) {
+                                log(`  Handler added: ${id}`);
+                            }
+                        }
+                        // Changed handlers with sessionIsolation: reset state
+                        for (const id of newIds) {
+                            if (oldIds.has(id)) {
+                                const newH = newHandlerMap.get(id);
+                                const oldH = oldHandlerMap.get(id);
+                                if (newH.sessionIsolation && JSON.stringify(oldH) !== JSON.stringify(newH)) {
+                                    (0, handlers_js_1.cleanupHandlerState)(id);
+                                    log(`  Handler changed (session-isolated, state reset): ${id}`);
+                                }
+                            }
+                        }
                         ctx.manifest = newManifest;
                         log('Manifest reloaded successfully');
                     }
@@ -240,6 +352,8 @@ function startDaemon(manifest, metrics, options) {
         const shutdown = () => {
             log('Shutting down...');
             (0, watcher_js_1.stopWatcher)(ctx.watcher ?? null);
+            if (ctx.cleanupInterval)
+                clearInterval(ctx.cleanupInterval);
             ctx.server.close(() => {
                 try {
                     if ((0, fs_1.existsSync)(constants_js_1.PID_FILE))

package/dist/shortcircuit.d.ts

@@ -0,0 +1,20 @@
+/**
+ * In-memory cache of denied PreToolUse calls.
+ * Keyed by session_id + tool_name.
+ * Entries expire after TTL_MS (30 seconds).
+ */
+export declare class DenyCache {
+    private cache;
+    private static TTL_MS;
+    private makeKey;
+    /** Record a denied PreToolUse. */
+    recordDeny(sessionId: string, toolName: string): void;
+    /** Check if a tool call was recently denied. */
+    isDenied(sessionId: string, toolName: string): boolean;
+    /** Clean up expired entries. */
+    cleanup(): void;
+    /** Clear all entries. */
+    clear(): void;
+    /** Get current cache size (for testing). */
+    get size(): number;
+}

package/dist/shortcircuit.js

@@ -0,0 +1,49 @@
+"use strict";
+// clooks short-circuit chains — deny cache for PreToolUse → PostToolUse
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DenyCache = void 0;
+/**
+ * In-memory cache of denied PreToolUse calls.
+ * Keyed by session_id + tool_name.
+ * Entries expire after TTL_MS (30 seconds).
+ */
+class DenyCache {
+    cache = new Map(); // key → timestamp
+    static TTL_MS = 30_000;
+    makeKey(sessionId, toolName) {
+        return `${sessionId}:${toolName}`;
+    }
+    /** Record a denied PreToolUse. */
+    recordDeny(sessionId, toolName) {
+        this.cache.set(this.makeKey(sessionId, toolName), Date.now());
+    }
+    /** Check if a tool call was recently denied. */
+    isDenied(sessionId, toolName) {
+        const ts = this.cache.get(this.makeKey(sessionId, toolName));
+        if (ts === undefined)
+            return false;
+        if (Date.now() - ts > DenyCache.TTL_MS) {
+            this.cache.delete(this.makeKey(sessionId, toolName));
+            return false;
+        }
+        return true;
+    }
+    /** Clean up expired entries. */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, ts] of this.cache) {
+            if (now - ts > DenyCache.TTL_MS) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /** Clear all entries. */
+    clear() {
+        this.cache.clear();
+    }
+    /** Get current cache size (for testing). */
+    get size() {
+        return this.cache.size;
+    }
+}
+exports.DenyCache = DenyCache;

package/dist/types.d.ts

@@ -31,6 +31,7 @@ export interface LLMHandlerConfig {
     timeout?: number;
     enabled?: boolean;
     sessionIsolation?: boolean;
+    depends?: string[];
 }
 /** Script handler config */
 export interface ScriptHandlerConfig {
@@ -41,6 +42,7 @@ export interface ScriptHandlerConfig {
     timeout?: number;
     enabled?: boolean;
     sessionIsolation?: boolean;
+    depends?: string[];
 }
 /** Inline handler config */
 export interface InlineHandlerConfig {
@@ -51,6 +53,7 @@ export interface InlineHandlerConfig {
     timeout?: number;
     enabled?: boolean;
     sessionIsolation?: boolean;
+    depends?: string[];
 }
 /** Union of all handler configs */
 export type HandlerConfig = ScriptHandlerConfig | InlineHandlerConfig | LLMHandlerConfig;
@@ -125,3 +128,31 @@ export interface DiagnosticResult {
     status: 'ok' | 'warn' | 'error';
     message: string;
 }
+/** Plugin extras metadata (freeform, extensible) */
+export interface PluginExtras {
+    skills?: string[];
+    agents?: string[];
+    readme?: string;
+    [key: string]: unknown;
+}
+/** Plugin manifest (clooks-plugin.yaml) */
+export interface PluginManifest {
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    handlers: Partial<Record<HookEvent, HandlerConfig[]>>;
+    prefetch?: PrefetchKey[];
+    extras?: PluginExtras;
+}
+/** Installed plugin registry entry */
+export interface InstalledPlugin {
+    name: string;
+    version: string;
+    path: string;
+    installedAt: string;
+}
+/** Plugin registry file format (installed.json) */
+export interface PluginRegistry {
+    plugins: InstalledPlugin[];
+}