@elizaos/agent 0.25.8 → 2.0.0-alpha.83

package/packages/agent/src/hooks/discovery.js

@@ -0,0 +1,184 @@
+/**
+ * Discover hooks from workspace, managed (~/.eliza/hooks/), and bundled dirs.
+ * Later sources win on name conflicts.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { logger } from "@elizaos/core";
+const HOOK_MD = "HOOK.md";
+const HANDLER_NAMES = ["handler.ts", "handler", "index.ts", "index"];
+function parseFrontmatter(content) {
+    const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!fmMatch)
+        return null;
+    const fmBlock = fmMatch[1];
+    const result = { name: "", description: "" };
+    for (const line of fmBlock.split("\n")) {
+        const kvMatch = line.match(/^(\w+):\s*(.+)/);
+        if (!kvMatch)
+            continue;
+        const [, key, rawValue] = kvMatch;
+        const value = rawValue.replace(/^["']|["']$/g, "").trim();
+        switch (key) {
+            case "name":
+                result.name = value;
+                break;
+            case "description":
+                result.description = value;
+                break;
+            case "homepage":
+                result.homepage = value;
+                break;
+            case "metadata":
+                try {
+                    const metaStart = fmBlock.indexOf("metadata:");
+                    if (metaStart !== -1) {
+                        const metaRest = fmBlock
+                            .slice(metaStart + "metadata:".length)
+                            .trim();
+                        const jsonMatch = metaRest.match(/\{[\s\S]*\}/);
+                        if (jsonMatch) {
+                            result.metadata = JSON.parse(jsonMatch[0]);
+                        }
+                    }
+                }
+                catch {
+                    try {
+                        result.metadata = JSON.parse(value);
+                    }
+                    catch {
+                        logger.warn(`[hooks] Failed to parse metadata in HOOK.md`);
+                    }
+                }
+                break;
+        }
+    }
+    return result.name ? result : null;
+}
+function extractMetadata(frontmatter) {
+    const meta = frontmatter.metadata?.eliza;
+    if (!meta)
+        return undefined;
+    return {
+        always: meta.always,
+        hookKey: meta.hookKey,
+        emoji: meta.emoji,
+        homepage: meta.homepage ?? frontmatter.homepage,
+        events: Array.isArray(meta.events) ? meta.events : [],
+        export: meta.export,
+        os: meta.os,
+        requires: meta.requires,
+        install: meta.install,
+    };
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function findHandlerPath(dir) {
+    for (const name of HANDLER_NAMES) {
+        const p = join(dir, name);
+        if (await fileExists(p))
+            return p;
+    }
+    return null;
+}
+async function loadHookFromDir(dir, source, pluginId) {
+    const hookMdPath = join(dir, HOOK_MD);
+    if (!(await fileExists(hookMdPath)))
+        return null;
+    const handlerPath = await findHandlerPath(dir);
+    if (!handlerPath) {
+        logger.warn(`[hooks] Hook at ${dir} has HOOK.md but no handler`);
+        return null;
+    }
+    try {
+        const content = await readFile(hookMdPath, "utf-8");
+        const frontmatter = parseFrontmatter(content);
+        if (!frontmatter) {
+            logger.warn(`[hooks] Invalid frontmatter in ${hookMdPath}`);
+            return null;
+        }
+        const metadata = extractMetadata(frontmatter);
+        const hook = {
+            name: frontmatter.name,
+            description: frontmatter.description,
+            source,
+            pluginId,
+            filePath: hookMdPath,
+            baseDir: dir,
+            handlerPath,
+        };
+        return { hook, frontmatter, metadata };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[hooks] Error loading hook from ${dir}: ${msg}`);
+        return null;
+    }
+}
+async function scanHooksDir(dir, source) {
+    if (!(await isDirectory(dir)))
+        return [];
+    const entries = [];
+    try {
+        const items = await readdir(dir);
+        for (const item of items) {
+            const itemPath = join(dir, item);
+            if (!(await isDirectory(itemPath)))
+                continue;
+            const entry = await loadHookFromDir(itemPath, source);
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[hooks] Error scanning ${dir}: ${msg}`);
+    }
+    return entries;
+}
+/** Precedence: extra (lowest) -> bundled -> managed -> workspace (highest). */
+export async function discoverHooks(options = {}) {
+    const seen = new Map();
+    if (options.extraDirs) {
+        for (const dir of options.extraDirs) {
+            const resolved = resolve(dir.replace(/^~/, homedir()));
+            for (const entry of await scanHooksDir(resolved, "eliza-managed")) {
+                seen.set(entry.hook.name, entry);
+            }
+        }
+    }
+    if (options.bundledDir) {
+        for (const entry of await scanHooksDir(options.bundledDir, "eliza-bundled")) {
+            seen.set(entry.hook.name, entry);
+        }
+    }
+    const managedDir = join(homedir(), ".eliza", "hooks");
+    for (const entry of await scanHooksDir(managedDir, "eliza-managed")) {
+        seen.set(entry.hook.name, entry);
+    }
+    if (options.workspacePath) {
+        const wsHooksDir = join(options.workspacePath.replace(/^~/, homedir()), "hooks");
+        for (const entry of await scanHooksDir(wsHooksDir, "eliza-workspace")) {
+            seen.set(entry.hook.name, entry);
+        }
+    }
+    const all = Array.from(seen.values());
+    logger.info(`[hooks] Discovered ${all.length} hooks`);
+    return all;
+}

package/packages/agent/src/hooks/eligibility.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hook eligibility: checks OS, binary, env, and config requirements.
+ */
+import type { HookConfig, InternalHooksConfig } from "../config/types.hooks";
+import type { ElizaHookMetadata } from "./types";
+export interface EligibilityResult {
+    eligible: boolean;
+    missing: string[];
+}
+export declare function checkEligibility(metadata: ElizaHookMetadata | undefined, hookConfig: HookConfig | undefined, elizaConfig?: Record<string, unknown>): EligibilityResult;
+export declare function resolveHookConfig(internalConfig: InternalHooksConfig | undefined, hookKey: string): HookConfig | undefined;
+//# sourceMappingURL=eligibility.d.ts.map

package/packages/agent/src/hooks/eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/eligibility.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAgEjD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACxC,iBAAiB,CAyDnB;AAED,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,mBAAmB,GAAG,SAAS,EAC/C,OAAO,EAAE,MAAM,GACd,UAAU,GAAG,SAAS,CAExB"}

package/packages/agent/src/hooks/eligibility.js

@@ -0,0 +1,100 @@
+/**
+ * Hook eligibility: checks OS, binary, env, and config requirements.
+ */
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { delimiter, extname, isAbsolute, join } from "node:path";
+function binaryExists(name) {
+    const pathExts = process.platform === "win32"
+        ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+            .split(";")
+            .map((ext) => ext.trim().toLowerCase())
+            .filter(Boolean)
+        : [];
+    const baseCandidates = process.platform === "win32" && extname(name) === ""
+        ? [name, ...pathExts.map((ext) => `${name}${ext}`)]
+        : [name];
+    if (isAbsolute(name) &&
+        baseCandidates.some((candidate) => existsSync(candidate))) {
+        return true;
+    }
+    const pathDirs = (process.env.PATH ?? "").split(delimiter);
+    for (const dir of pathDirs) {
+        for (const candidate of baseCandidates) {
+            if (existsSync(join(dir, candidate)))
+                return true;
+        }
+    }
+    return false;
+}
+function resolveConfigPath(config, pathStr) {
+    const parts = pathStr.split(".");
+    let current = config;
+    for (const part of parts) {
+        if (current === null ||
+            current === undefined ||
+            typeof current !== "object") {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function isConfigPathTruthy(config, pathStr) {
+    const value = resolveConfigPath(config, pathStr);
+    return (value !== undefined &&
+        value !== null &&
+        value !== false &&
+        value !== "" &&
+        value !== 0);
+}
+export function checkEligibility(metadata, hookConfig, elizaConfig = {}) {
+    const missing = [];
+    if (!metadata) {
+        return { eligible: true, missing: [] };
+    }
+    // Note: hookConfig.enabled is intentionally NOT checked here.
+    // "Disabled" (user choice) vs "ineligible" (missing requirements) are
+    // separate concerns — the loader handles the enabled flag.
+    if (metadata.os && metadata.os.length > 0) {
+        if (!metadata.os.includes(platform())) {
+            missing.push(`OS: requires ${metadata.os.join("|")}, current: ${platform()}`);
+        }
+    }
+    if (metadata.always) {
+        return { eligible: missing.length === 0, missing };
+    }
+    if (metadata.requires?.bins) {
+        for (const bin of metadata.requires.bins) {
+            if (!binaryExists(bin)) {
+                missing.push(`Binary missing: ${bin}`);
+            }
+        }
+    }
+    if (metadata.requires?.anyBins && metadata.requires.anyBins.length > 0) {
+        const hasAny = metadata.requires.anyBins.some(binaryExists);
+        if (!hasAny) {
+            missing.push(`None of: ${metadata.requires.anyBins.join(", ")}`);
+        }
+    }
+    if (metadata.requires?.env) {
+        for (const envVar of metadata.requires.env) {
+            const hasInProcess = Boolean(process.env[envVar]);
+            const hasInHookConfig = Boolean(hookConfig?.env?.[envVar]);
+            if (!hasInProcess && !hasInHookConfig) {
+                missing.push(`Env missing: ${envVar}`);
+            }
+        }
+    }
+    if (metadata.requires?.config) {
+        for (const configPath of metadata.requires.config) {
+            if (!isConfigPathTruthy(elizaConfig, configPath)) {
+                missing.push(`Config missing: ${configPath}`);
+            }
+        }
+    }
+    return { eligible: missing.length === 0, missing };
+}
+export function resolveHookConfig(internalConfig, hookKey) {
+    return internalConfig?.entries?.[hookKey];
+}

package/packages/agent/src/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { type LoadHooksOptions, loadHooks, } from "./loader";
+export { createHookEvent, triggerHook, } from "./registry";
+//# sourceMappingURL=index.d.ts.map

package/packages/agent/src/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,eAAe,EACf,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/packages/agent/src/hooks/index.js

@@ -0,0 +1,2 @@
+export { loadHooks, } from "./loader";
+export { createHookEvent, triggerHook, } from "./registry";

package/packages/agent/src/hooks/loader.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hook Loader — load and register hooks into the event system.
+ *
+ * Orchestrates discovery -> eligibility -> loading -> registration.
+ *
+ * @module hooks/loader
+ */
+import type { InternalHooksConfig } from "../config/types.hooks";
+import { type DiscoveryOptions } from "./discovery";
+export interface LoadHooksOptions extends DiscoveryOptions {
+    /** Internal hooks configuration. */
+    internalConfig?: InternalHooksConfig;
+    /** Full Eliza config for eligibility checks. */
+    elizaConfig?: Record<string, unknown>;
+}
+export interface LoadHooksResult {
+    /** Total hooks discovered. */
+    discovered: number;
+    /** Hooks that passed eligibility. */
+    eligible: number;
+    /** Hooks successfully loaded and registered. */
+    registered: number;
+    /** Hooks that were skipped (disabled or ineligible). */
+    skipped: string[];
+    /** Hooks that failed to load. */
+    failed: string[];
+}
+/**
+ * Discover, filter, load, and register all hooks.
+ *
+ * This is the main entry point called during gateway startup.
+ */
+export declare function loadHooks(options?: LoadHooksOptions): Promise<LoadHooksResult>;
+//# sourceMappingURL=loader.d.ts.map

package/packages/agent/src/hooks/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,KAAK,gBAAgB,EAAiB,MAAM,aAAa,CAAC;AAkEnE,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,oCAAoC;IACpC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iCAAiC;IACjC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAqJ1B"}

package/packages/agent/src/hooks/loader.js

@@ -0,0 +1,176 @@
+/**
+ * Hook Loader — load and register hooks into the event system.
+ *
+ * Orchestrates discovery -> eligibility -> loading -> registration.
+ *
+ * @module hooks/loader
+ */
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { logger } from "@elizaos/core";
+import { discoverHooks } from "./discovery";
+import { checkEligibility, resolveHookConfig } from "./eligibility";
+import { clearHooks, registerHook } from "./registry";
+// ---------- Path Safety ----------
+/** Directories from which hook modules may be loaded. */
+function getSafeHookRoots(workspacePath, bundledDir) {
+    const roots = [resolve(homedir(), ".eliza", "hooks")];
+    if (bundledDir)
+        roots.push(resolve(bundledDir));
+    if (workspacePath) {
+        roots.push(resolve(workspacePath.replace(/^~/, homedir()), "hooks"));
+    }
+    return roots;
+}
+/**
+ * Ensure a module path resolves to a file under one of the allowed hook
+ * roots.  Blocks absolute paths to arbitrary locations and path-traversal
+ * attacks (e.g. "../../etc/malicious").
+ */
+function isPathUnderRoots(modulePath, roots) {
+    const resolved = resolve(modulePath);
+    return roots.some((root) => {
+        const r = root.endsWith(sep) ? root : root + sep;
+        return resolved.startsWith(r) || resolved === root;
+    });
+}
+// ---------- Dynamic Handler Loading ----------
+/**
+ * Dynamically import a hook handler module.
+ * Uses cache-busting query parameter for dev mode hot reload.
+ */
+async function loadHandlerModule(handlerPath, exportName = "default") {
+    try {
+        const url = pathToFileURL(handlerPath).href;
+        // Cache-busting for dev mode
+        const mod = await import(`${url}?t=${Date.now()}`);
+        const handler = mod[exportName];
+        if (typeof handler !== "function") {
+            logger.warn(`[hooks] Handler at ${handlerPath} does not export a function as "${exportName}"`);
+            return null;
+        }
+        return handler;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(`[hooks] Failed to load handler ${handlerPath}: ${msg}`);
+        return null;
+    }
+}
+/**
+ * Discover, filter, load, and register all hooks.
+ *
+ * This is the main entry point called during gateway startup.
+ */
+export async function loadHooks(options = {}) {
+    const { internalConfig, elizaConfig = {} } = options;
+    // Check if hooks are enabled
+    if (internalConfig?.enabled === false) {
+        logger.info("[hooks] Internal hooks disabled");
+        return {
+            discovered: 0,
+            eligible: 0,
+            registered: 0,
+            skipped: [],
+            failed: [],
+        };
+    }
+    // Clear existing hooks (for reload)
+    clearHooks();
+    // Validate config-supplied extraDirs: only allow paths under ~/.eliza/
+    // to prevent config injection from scanning attacker-controlled directories.
+    const safeExtraDirs = [...(options.extraDirs ?? [])];
+    const elizaHome = resolve(homedir(), ".eliza");
+    for (const dir of internalConfig?.load?.extraDirs ?? []) {
+        const resolved = resolve(dir.replace(/^~/, homedir()));
+        if (resolved.startsWith(elizaHome + sep) || resolved === elizaHome) {
+            safeExtraDirs.push(dir);
+        }
+        else {
+            logger.warn(`[hooks] Rejected config extraDir "${dir}": must be under ~/.eliza/`);
+        }
+    }
+    // Discover hooks
+    const entries = await discoverHooks({
+        workspacePath: options.workspacePath,
+        bundledDir: options.bundledDir,
+        extraDirs: safeExtraDirs,
+    });
+    const result = {
+        discovered: entries.length,
+        eligible: 0,
+        registered: 0,
+        skipped: [],
+        failed: [],
+    };
+    // Process each hook
+    for (const entry of entries) {
+        const hookKey = entry.metadata?.hookKey ?? entry.hook.name;
+        const hookConfig = resolveHookConfig(internalConfig, hookKey);
+        // Check eligibility
+        const eligibility = checkEligibility(entry.metadata, hookConfig, elizaConfig);
+        if (!eligibility.eligible) {
+            result.skipped.push(`${entry.hook.name}: ${eligibility.missing.join(", ")}`);
+            continue;
+        }
+        result.eligible++;
+        // Check if explicitly disabled
+        if (hookConfig?.enabled === false) {
+            result.skipped.push(`${entry.hook.name}: disabled in config`);
+            continue;
+        }
+        // Load handler
+        const exportName = entry.metadata?.export ?? "default";
+        const handler = await loadHandlerModule(entry.hook.handlerPath, exportName);
+        if (!handler) {
+            result.failed.push(entry.hook.name);
+            continue;
+        }
+        // Register for all configured events
+        const events = entry.metadata?.events ?? [];
+        if (events.length === 0) {
+            logger.warn(`[hooks] Hook "${entry.hook.name}" has no events configured`);
+            result.skipped.push(`${entry.hook.name}: no events`);
+            continue;
+        }
+        for (const eventKey of events) {
+            registerHook(eventKey, handler);
+        }
+        const emoji = entry.metadata?.emoji ?? "🔗";
+        logger.info(`[hooks] ${emoji} Registered: ${entry.hook.name} -> ${events.join(", ")}`);
+        result.registered++;
+    }
+    // Load legacy config handlers (backwards compatibility)
+    if (internalConfig?.handlers) {
+        const safeRoots = getSafeHookRoots(options.workspacePath, options.bundledDir);
+        for (const legacyHandler of internalConfig.handlers) {
+            // Validate module path is under a known hook directory to prevent
+            // arbitrary code execution via config-injected module paths.
+            if (!isPathUnderRoots(legacyHandler.module, safeRoots)) {
+                logger.warn(`[hooks] Rejected legacy handler: module path "${legacyHandler.module}" is outside allowed hook directories`);
+                result.failed.push(legacyHandler.module);
+                continue;
+            }
+            try {
+                const handler = await loadHandlerModule(legacyHandler.module, legacyHandler.export ?? "default");
+                if (handler) {
+                    registerHook(legacyHandler.event, handler);
+                    logger.info(`[hooks] Registered legacy handler: ${legacyHandler.event} -> ${legacyHandler.module}`);
+                    result.registered++;
+                }
+                else {
+                    result.failed.push(legacyHandler.module);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.warn(`[hooks] Failed to load legacy handler: ${msg}`);
+                result.failed.push(legacyHandler.module);
+            }
+        }
+    }
+    logger.info(`[hooks] Load complete: ${result.registered}/${result.discovered} registered, ` +
+        `${result.skipped.length} skipped, ${result.failed.length} failed`);
+    return result;
+}

package/packages/agent/src/hooks/registry.d.ts

@@ -0,0 +1,11 @@
+import type { HookEvent, HookHandler } from "./types";
+/**
+ * Event keys: "command" matches all command events,
+ * "command:new" matches only /new.
+ */
+export declare function registerHook(eventKey: string, handler: HookHandler): void;
+export declare function clearHooks(): void;
+/** Dispatches to specific ("command:new") then general ("command") handlers. */
+export declare function triggerHook(event: HookEvent): Promise<void>;
+export declare function createHookEvent(type: HookEvent["type"], action: string, sessionKey: string, context?: Record<string, unknown>): HookEvent;
+//# sourceMappingURL=registry.d.ts.map

package/packages/agent/src/hooks/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAItD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAIzE;AAED,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED,gFAAgF;AAChF,wBAAsB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAqCjE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,SAAS,CASX"}

package/packages/agent/src/hooks/registry.js

@@ -0,0 +1,58 @@
+import { logger } from "@elizaos/core";
+const registry = new Map();
+/**
+ * Event keys: "command" matches all command events,
+ * "command:new" matches only /new.
+ */
+export function registerHook(eventKey, handler) {
+    const handlers = registry.get(eventKey) ?? [];
+    handlers.push(handler);
+    registry.set(eventKey, handlers);
+}
+export function clearHooks() {
+    registry.clear();
+}
+/** Dispatches to specific ("command:new") then general ("command") handlers. */
+export async function triggerHook(event) {
+    const specificKey = `${event.type}:${event.action}`;
+    const generalKey = event.type;
+    const handlers = [];
+    const specificHandlers = registry.get(specificKey);
+    if (specificHandlers) {
+        for (const handler of specificHandlers) {
+            handlers.push({ key: specificKey, handler });
+        }
+    }
+    const generalHandlers = registry.get(generalKey);
+    if (generalHandlers) {
+        for (const handler of generalHandlers) {
+            handlers.push({ key: generalKey, handler });
+        }
+    }
+    if (handlers.length === 0)
+        return;
+    const errors = [];
+    for (const { key, handler } of handlers) {
+        try {
+            await handler(event);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            logger.error(`[hooks] Handler error for "${key}": ${error.message}`);
+            errors.push(error);
+        }
+    }
+    if (errors.length > 0) {
+        logger.warn(`[hooks] ${errors.length} hook handler(s) failed — errors were logged above`);
+    }
+}
+export function createHookEvent(type, action, sessionKey, context = {}) {
+    return {
+        type,
+        action,
+        sessionKey,
+        timestamp: new Date(),
+        messages: [],
+        context,
+    };
+}