@dexto/core 1.5.8 → 1.6.0

package/dist/hooks/builtins/response-sanitizer.d.ts

@@ -0,0 +1,22 @@
+import type { Hook, BeforeResponsePayload, HookExecutionContext, HookResult } from '../types.js';
+export interface ResponseSanitizerConfig {
+    redactEmails?: boolean;
+    redactApiKeys?: boolean;
+    maxResponseLength?: number;
+}
+/**
+ * Response sanitizer built-in hook.
+ *
+ * This hook redacts sensitive information from LLM responses to prevent accidental leakage:
+ * - Email addresses
+ * - API keys and tokens
+ * - Optional: Truncates responses that exceed length limits
+ */
+export declare class ResponseSanitizerHook implements Hook {
+    private redactEmails;
+    private redactApiKeys;
+    private maxResponseLength;
+    initialize(config: Record<string, unknown>): Promise<void>;
+    beforeResponse(payload: BeforeResponsePayload, _context: HookExecutionContext): Promise<HookResult>;
+}
+//# sourceMappingURL=response-sanitizer.d.ts.map

package/dist/hooks/builtins/response-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-sanitizer.d.ts","sourceRoot":"","sources":["../../../src/hooks/builtins/response-sanitizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,IAAI,EACJ,qBAAqB,EACrB,oBAAoB,EACpB,UAAU,EAEb,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uBAAuB;IACpC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAQD;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,IAAI;IAC9C,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,iBAAiB,CAAsC;IAEzD,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1D,cAAc,CAChB,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,oBAAoB,GAC/B,OAAO,CAAC,UAAU,CAAC;CAyEzB"}

package/dist/{plugins → hooks}/builtins/response-sanitizer.js

@@ -4,7 +4,7 @@ const DEFAULTS = {
   redactApiKeys: false,
   maxResponseLength: 0
 };
-class ResponseSanitizerPlugin {
+class ResponseSanitizerHook {
   redactEmails = DEFAULTS.redactEmails;
   redactApiKeys = DEFAULTS.redactApiKeys;
   maxResponseLength = DEFAULTS.maxResponseLength;
@@ -75,5 +75,5 @@ class ResponseSanitizerPlugin {
   }
 }
 export {
-  ResponseSanitizerPlugin
+  ResponseSanitizerHook
 };

package/dist/hooks/error-codes.cjs

@@ -0,0 +1,43 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var error_codes_exports = {};
+__export(error_codes_exports, {
+  HookErrorCode: () => HookErrorCode
+});
+module.exports = __toCommonJS(error_codes_exports);
+var HookErrorCode = /* @__PURE__ */ ((HookErrorCode2) => {
+  HookErrorCode2["HOOK_LOAD_FAILED"] = "HOOK_LOAD_FAILED";
+  HookErrorCode2["HOOK_INVALID_SHAPE"] = "HOOK_INVALID_SHAPE";
+  HookErrorCode2["HOOK_INSTANTIATION_FAILED"] = "HOOK_INSTANTIATION_FAILED";
+  HookErrorCode2["HOOK_INITIALIZATION_FAILED"] = "HOOK_INITIALIZATION_FAILED";
+  HookErrorCode2["HOOK_CONFIGURATION_INVALID"] = "HOOK_CONFIGURATION_INVALID";
+  HookErrorCode2["HOOK_EXECUTION_FAILED"] = "HOOK_EXECUTION_FAILED";
+  HookErrorCode2["HOOK_EXECUTION_TIMEOUT"] = "HOOK_EXECUTION_TIMEOUT";
+  HookErrorCode2["HOOK_BLOCKED_EXECUTION"] = "HOOK_BLOCKED_EXECUTION";
+  HookErrorCode2["HOOK_DUPLICATE_PRIORITY"] = "HOOK_DUPLICATE_PRIORITY";
+  HookErrorCode2["HOOK_DEPENDENCY_NOT_INSTALLED"] = "HOOK_DEPENDENCY_NOT_INSTALLED";
+  HookErrorCode2["HOOK_PROVIDER_ALREADY_REGISTERED"] = "HOOK_PROVIDER_ALREADY_REGISTERED";
+  HookErrorCode2["HOOK_PROVIDER_NOT_FOUND"] = "HOOK_PROVIDER_NOT_FOUND";
+  HookErrorCode2["HOOK_PROVIDER_VALIDATION_FAILED"] = "HOOK_PROVIDER_VALIDATION_FAILED";
+  return HookErrorCode2;
+})(HookErrorCode || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HookErrorCode
+});

package/dist/hooks/error-codes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hook-specific error codes.
+ * Used for hook loading, validation, and execution errors.
+ */
+export declare enum HookErrorCode {
+    /** Hook file not found or cannot be loaded */
+    HOOK_LOAD_FAILED = "HOOK_LOAD_FAILED",
+    /** Hook does not implement required interface */
+    HOOK_INVALID_SHAPE = "HOOK_INVALID_SHAPE",
+    /** Hook constructor threw an error */
+    HOOK_INSTANTIATION_FAILED = "HOOK_INSTANTIATION_FAILED",
+    /** Hook initialization failed */
+    HOOK_INITIALIZATION_FAILED = "HOOK_INITIALIZATION_FAILED",
+    /** Hook configuration is invalid */
+    HOOK_CONFIGURATION_INVALID = "HOOK_CONFIGURATION_INVALID",
+    /** Hook execution failed */
+    HOOK_EXECUTION_FAILED = "HOOK_EXECUTION_FAILED",
+    /** Hook execution timed out */
+    HOOK_EXECUTION_TIMEOUT = "HOOK_EXECUTION_TIMEOUT",
+    /** Hook blocked execution */
+    HOOK_BLOCKED_EXECUTION = "HOOK_BLOCKED_EXECUTION",
+    /** Duplicate hook priority */
+    HOOK_DUPLICATE_PRIORITY = "HOOK_DUPLICATE_PRIORITY",
+    /** Required dependency not installed for hook loading */
+    HOOK_DEPENDENCY_NOT_INSTALLED = "HOOK_DEPENDENCY_NOT_INSTALLED",
+    /** Hook provider already registered in registry */
+    HOOK_PROVIDER_ALREADY_REGISTERED = "HOOK_PROVIDER_ALREADY_REGISTERED",
+    /** Hook provider not found in registry */
+    HOOK_PROVIDER_NOT_FOUND = "HOOK_PROVIDER_NOT_FOUND",
+    /** Hook provider configuration validation failed */
+    HOOK_PROVIDER_VALIDATION_FAILED = "HOOK_PROVIDER_VALIDATION_FAILED"
+}
+export type { HookErrorCode as default };
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/hooks/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../src/hooks/error-codes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,aAAa;IACrB,8CAA8C;IAC9C,gBAAgB,qBAAqB;IAErC,iDAAiD;IACjD,kBAAkB,uBAAuB;IAEzC,sCAAsC;IACtC,yBAAyB,8BAA8B;IAEvD,iCAAiC;IACjC,0BAA0B,+BAA+B;IAEzD,oCAAoC;IACpC,0BAA0B,+BAA+B;IAEzD,4BAA4B;IAC5B,qBAAqB,0BAA0B;IAE/C,+BAA+B;IAC/B,sBAAsB,2BAA2B;IAEjD,6BAA6B;IAC7B,sBAAsB,2BAA2B;IAEjD,8BAA8B;IAC9B,uBAAuB,4BAA4B;IAEnD,yDAAyD;IACzD,6BAA6B,kCAAkC;IAE/D,mDAAmD;IACnD,gCAAgC,qCAAqC;IAErE,0CAA0C;IAC1C,uBAAuB,4BAA4B;IAEnD,oDAAoD;IACpD,+BAA+B,oCAAoC;CACtE;AAED,YAAY,EAAE,aAAa,IAAI,OAAO,EAAE,CAAC"}

package/dist/hooks/error-codes.js

@@ -0,0 +1,20 @@
+import "../chunk-PTJYTZNU.js";
+var HookErrorCode = /* @__PURE__ */ ((HookErrorCode2) => {
+  HookErrorCode2["HOOK_LOAD_FAILED"] = "HOOK_LOAD_FAILED";
+  HookErrorCode2["HOOK_INVALID_SHAPE"] = "HOOK_INVALID_SHAPE";
+  HookErrorCode2["HOOK_INSTANTIATION_FAILED"] = "HOOK_INSTANTIATION_FAILED";
+  HookErrorCode2["HOOK_INITIALIZATION_FAILED"] = "HOOK_INITIALIZATION_FAILED";
+  HookErrorCode2["HOOK_CONFIGURATION_INVALID"] = "HOOK_CONFIGURATION_INVALID";
+  HookErrorCode2["HOOK_EXECUTION_FAILED"] = "HOOK_EXECUTION_FAILED";
+  HookErrorCode2["HOOK_EXECUTION_TIMEOUT"] = "HOOK_EXECUTION_TIMEOUT";
+  HookErrorCode2["HOOK_BLOCKED_EXECUTION"] = "HOOK_BLOCKED_EXECUTION";
+  HookErrorCode2["HOOK_DUPLICATE_PRIORITY"] = "HOOK_DUPLICATE_PRIORITY";
+  HookErrorCode2["HOOK_DEPENDENCY_NOT_INSTALLED"] = "HOOK_DEPENDENCY_NOT_INSTALLED";
+  HookErrorCode2["HOOK_PROVIDER_ALREADY_REGISTERED"] = "HOOK_PROVIDER_ALREADY_REGISTERED";
+  HookErrorCode2["HOOK_PROVIDER_NOT_FOUND"] = "HOOK_PROVIDER_NOT_FOUND";
+  HookErrorCode2["HOOK_PROVIDER_VALIDATION_FAILED"] = "HOOK_PROVIDER_VALIDATION_FAILED";
+  return HookErrorCode2;
+})(HookErrorCode || {});
+export {
+  HookErrorCode
+};

package/dist/{storage/cache/providers/memory.cjs → hooks/index.cjs}

@@ -16,25 +16,22 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var memory_exports = {};
-__export(memory_exports, {
-  inMemoryCacheProvider: () => inMemoryCacheProvider
+var hooks_exports = {};
+__export(hooks_exports, {
+  ContentPolicyHook: () => import_content_policy.ContentPolicyHook,
+  HookErrorCode: () => import_error_codes.HookErrorCode,
+  HookManager: () => import_manager.HookManager,
+  ResponseSanitizerHook: () => import_response_sanitizer.ResponseSanitizerHook
 });
-module.exports = __toCommonJS(memory_exports);
-var import_schemas = require("../schemas.js");
-var import_memory_cache_store = require("../memory-cache-store.js");
-const inMemoryCacheProvider = {
-  type: "in-memory",
-  configSchema: import_schemas.InMemoryCacheSchema,
-  create: (_config, _logger) => new import_memory_cache_store.MemoryCacheStore(),
-  metadata: {
-    displayName: "In-Memory",
-    description: "Store cache data in RAM (ephemeral, for testing and development)",
-    requiresNetwork: false,
-    supportsTTL: true
-  }
-};
+module.exports = __toCommonJS(hooks_exports);
+var import_manager = require("./manager.js");
+var import_error_codes = require("./error-codes.js");
+var import_content_policy = require("./builtins/content-policy.js");
+var import_response_sanitizer = require("./builtins/response-sanitizer.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  inMemoryCacheProvider
+  ContentPolicyHook,
+  HookErrorCode,
+  HookManager,
+  ResponseSanitizerHook
 });

package/dist/hooks/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Hook System
+ *
+ * Unified hook architecture for extending agent behavior at key extension points.
+ */
+export type { Hook, HookConfig, HookExecutionContext, HookResult, HookNotice, ExtensionPoint, BeforeLLMRequestPayload, BeforeToolCallPayload, AfterToolResultPayload, BeforeResponsePayload, } from './types.js';
+export { HookManager } from './manager.js';
+export type { HookManagerOptions, HookExecutionContextOptions } from './manager.js';
+export { HookErrorCode } from './error-codes.js';
+export { ContentPolicyHook } from './builtins/content-policy.js';
+export type { ContentPolicyConfig } from './builtins/content-policy.js';
+export { ResponseSanitizerHook } from './builtins/response-sanitizer.js';
+export type { ResponseSanitizerConfig } from './builtins/response-sanitizer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACR,IAAI,EACJ,UAAU,EACV,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,GACxB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAGpF,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACzE,YAAY,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,11 @@
+import "../chunk-PTJYTZNU.js";
+import { HookManager } from "./manager.js";
+import { HookErrorCode } from "./error-codes.js";
+import { ContentPolicyHook } from "./builtins/content-policy.js";
+import { ResponseSanitizerHook } from "./builtins/response-sanitizer.js";
+export {
+  ContentPolicyHook,
+  HookErrorCode,
+  HookManager,
+  ResponseSanitizerHook
+};

package/dist/hooks/manager.cjs

@@ -0,0 +1,354 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var manager_exports = {};
+__export(manager_exports, {
+  HookManager: () => HookManager
+});
+module.exports = __toCommonJS(manager_exports);
+var import_errors = require("../errors/index.js");
+var import_error_codes = require("./error-codes.js");
+var import_async_context = require("../utils/async-context.js");
+var import_types = require("../logger/v2/types.js");
+class HookManager {
+  hooks = [];
+  hooksByExtensionPoint = /* @__PURE__ */ new Map();
+  hookNameByInstance = /* @__PURE__ */ new WeakMap();
+  options;
+  initialized = false;
+  logger;
+  /** Default timeout for hook execution (milliseconds) */
+  static DEFAULT_TIMEOUT = 5e3;
+  constructor(options, hooks, logger) {
+    this.options = options;
+    this.logger = logger.createChild(import_types.DextoLogComponent.HOOK);
+    this.setHooks(hooks);
+    this.logger.debug("HookManager created");
+  }
+  /**
+   * Provide the concrete hooks this manager should orchestrate.
+   * Hooks must be fully resolved and initialized before calling `initialize()`.
+   */
+  setHooks(hooks) {
+    if (this.initialized) {
+      throw new import_errors.DextoRuntimeError(
+        import_error_codes.HookErrorCode.HOOK_CONFIGURATION_INVALID,
+        import_errors.ErrorScope.HOOK,
+        import_errors.ErrorType.SYSTEM,
+        "Cannot set hooks after initialization"
+      );
+    }
+    this.hooks = [...hooks];
+    this.hooksByExtensionPoint.clear();
+    this.hookNameByInstance = /* @__PURE__ */ new WeakMap();
+    for (const [index, hook] of this.hooks.entries()) {
+      this.hookNameByInstance.set(hook, this.deriveHookName(hook, index));
+    }
+  }
+  /**
+   * Initialize hook orchestration.
+   * Validates hook shapes and registers them to extension points.
+   * @throws {DextoRuntimeError} If any hook fails validation (fail-fast)
+   */
+  async initialize() {
+    if (this.initialized) {
+      throw new import_errors.DextoRuntimeError(
+        import_error_codes.HookErrorCode.HOOK_CONFIGURATION_INVALID,
+        import_errors.ErrorScope.HOOK,
+        import_errors.ErrorType.SYSTEM,
+        "HookManager already initialized"
+      );
+    }
+    for (const [index, hook] of this.hooks.entries()) {
+      this.assertValidHookShape(hook, index);
+      this.registerToExtensionPoints(hook);
+    }
+    for (const [extensionPoint, hooks] of this.hooksByExtensionPoint.entries()) {
+      this.logger.debug(
+        `Extension point '${extensionPoint}': ${hooks.length} hook(s) registered`
+      );
+    }
+    this.initialized = true;
+    this.logger.info(`HookManager initialized with ${this.hooks.length} hook(s)`);
+  }
+  /**
+   * Register a hook to the extension points it implements.
+   */
+  registerToExtensionPoints(hook) {
+    const extensionPoints = [
+      "beforeLLMRequest",
+      "beforeToolCall",
+      "afterToolResult",
+      "beforeResponse"
+    ];
+    for (const point of extensionPoints) {
+      if (typeof hook[point] === "function") {
+        if (!this.hooksByExtensionPoint.has(point)) {
+          this.hooksByExtensionPoint.set(point, []);
+        }
+        this.hooksByExtensionPoint.get(point).push(hook);
+      }
+    }
+  }
+  /**
+   * Execute all hooks at a specific extension point.
+   * Hooks execute sequentially in the order they were provided.
+   *
+   * @param extensionPoint - Which extension point to execute
+   * @param payload - Payload for this extension point (must be an object)
+   * @param options - Options for building execution context
+   * @returns Modified payload after all hooks execute
+   * @throws {DextoRuntimeError} If a hook cancels execution or payload is not an object
+   */
+  async executeHooks(extensionPoint, payload, options) {
+    const hooks = this.hooksByExtensionPoint.get(extensionPoint) || [];
+    if (hooks.length === 0) {
+      return payload;
+    }
+    if (payload === null || typeof payload !== "object") {
+      throw new import_errors.DextoRuntimeError(
+        import_error_codes.HookErrorCode.HOOK_INVALID_SHAPE,
+        import_errors.ErrorScope.HOOK,
+        import_errors.ErrorType.USER,
+        `Payload for ${extensionPoint} must be an object (got ${payload === null ? "null" : typeof payload})`,
+        { extensionPoint, payloadType: typeof payload }
+      );
+    }
+    let currentPayload = { ...payload };
+    const asyncCtx = (0, import_async_context.getContext)();
+    const llmConfig = options.stateManager.getLLMConfig(options.sessionId);
+    const context = {
+      sessionId: options.sessionId ?? void 0,
+      userId: asyncCtx?.userId ?? void 0,
+      tenantId: asyncCtx?.tenantId ?? void 0,
+      llmConfig,
+      logger: this.logger,
+      abortSignal: options.abortSignal ?? void 0,
+      agent: {
+        sessionManager: options.sessionManager,
+        mcpManager: options.mcpManager,
+        toolManager: options.toolManager,
+        stateManager: options.stateManager,
+        agentEventBus: this.options.agentEventBus,
+        storageManager: this.options.storageManager
+      }
+    };
+    for (const [index, hook] of hooks.entries()) {
+      const method = hook[extensionPoint];
+      if (!method) continue;
+      const hookName = this.hookNameByInstance.get(hook) ?? this.deriveHookName(hook, index);
+      const startTime = Date.now();
+      try {
+        const result = await this.executeWithTimeout(
+          method.call(hook, currentPayload, context),
+          hookName,
+          HookManager.DEFAULT_TIMEOUT
+        );
+        const duration = Date.now() - startTime;
+        this.logger.debug(`Hook '${hookName}' executed at ${extensionPoint}`, {
+          ok: result.ok,
+          cancelled: result.cancel,
+          duration,
+          hasModifications: !!result.modify
+        });
+        if (result.notices && result.notices.length > 0) {
+          for (const notice of result.notices) {
+            const level = notice.kind === "block" || notice.kind === "warn" ? "warn" : "info";
+            this.logger[level](`Hook notice (${notice.kind}): ${notice.message}`, {
+              hook: hookName,
+              code: notice.code,
+              details: notice.details
+            });
+          }
+        }
+        if (!result.ok) {
+          this.logger.warn(`Hook '${hookName}' returned error`, {
+            message: result.message
+          });
+          if (result.cancel) {
+            throw new import_errors.DextoRuntimeError(
+              import_error_codes.HookErrorCode.HOOK_BLOCKED_EXECUTION,
+              import_errors.ErrorScope.HOOK,
+              import_errors.ErrorType.FORBIDDEN,
+              result.message || `Operation blocked by hook '${hookName}'`,
+              {
+                hook: hookName,
+                extensionPoint,
+                notices: result.notices
+              }
+            );
+          }
+          continue;
+        }
+        if (result.modify) {
+          currentPayload = {
+            ...currentPayload,
+            ...result.modify
+          };
+          this.logger.debug(`Hook '${hookName}' modified payload`, {
+            keys: Object.keys(result.modify)
+          });
+        }
+        if (result.cancel) {
+          throw new import_errors.DextoRuntimeError(
+            import_error_codes.HookErrorCode.HOOK_BLOCKED_EXECUTION,
+            import_errors.ErrorScope.HOOK,
+            import_errors.ErrorType.FORBIDDEN,
+            result.message || `Operation cancelled by hook '${hookName}'`,
+            {
+              hook: hookName,
+              extensionPoint,
+              notices: result.notices
+            }
+          );
+        }
+      } catch (error) {
+        const duration = Date.now() - startTime;
+        if (error instanceof import_errors.DextoRuntimeError) {
+          throw error;
+        }
+        this.logger.error(`Hook '${hookName}' threw error`, {
+          error: error instanceof Error ? error.message : String(error),
+          duration
+        });
+        throw new import_errors.DextoRuntimeError(
+          import_error_codes.HookErrorCode.HOOK_EXECUTION_FAILED,
+          import_errors.ErrorScope.HOOK,
+          import_errors.ErrorType.SYSTEM,
+          `Hook '${hookName}' failed: ${error instanceof Error ? error.message : String(error)}`,
+          {
+            hook: hookName,
+            extensionPoint
+          }
+        );
+      }
+    }
+    return currentPayload;
+  }
+  /**
+   * Execute a promise with timeout, properly clearing timer on completion
+   * Prevents timer leaks and unhandled rejections from Promise.race
+   */
+  async executeWithTimeout(promise, hookName, ms) {
+    let timer;
+    return await new Promise((resolve, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          new import_errors.DextoRuntimeError(
+            import_error_codes.HookErrorCode.HOOK_EXECUTION_TIMEOUT,
+            import_errors.ErrorScope.HOOK,
+            import_errors.ErrorType.TIMEOUT,
+            `Hook '${hookName}' execution timed out after ${ms}ms`
+          )
+        );
+      }, ms);
+      promise.then(
+        (val) => {
+          if (timer) clearTimeout(timer);
+          resolve(val);
+        },
+        (err) => {
+          if (timer) clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+  /**
+   * Cleanup all hooks.
+   * Called when agent shuts down
+   */
+  async cleanup() {
+    for (const [index, hook] of this.hooks.entries()) {
+      const hookName = this.hookNameByInstance.get(hook) ?? this.deriveHookName(hook, index);
+      if (hook.cleanup) {
+        try {
+          await hook.cleanup();
+          this.logger.debug(`Hook cleaned up: ${hookName}`);
+        } catch (error) {
+          this.logger.error(`Hook cleanup failed: ${hookName}`, {
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    }
+    this.logger.info("HookManager cleanup complete");
+  }
+  /**
+   * Get hook statistics.
+   */
+  getStats() {
+    const byExtensionPoint = {};
+    for (const [point, hooks] of this.hooksByExtensionPoint.entries()) {
+      byExtensionPoint[point] = hooks.length;
+    }
+    return {
+      total: this.hooks.length,
+      enabled: this.hooks.length,
+      byExtensionPoint
+    };
+  }
+  /**
+   * List hook display names in execution order.
+   *
+   * Names are derived from:
+   * - `hook.name` (if present)
+   * - constructor/class name (if available)
+   * - fallback `hook#N`
+   */
+  getHookNames() {
+    return this.hooks.map((hook, index) => {
+      return this.hookNameByInstance.get(hook) ?? this.deriveHookName(hook, index);
+    });
+  }
+  deriveHookName(hook, index) {
+    const maybeNamed = hook;
+    if (typeof maybeNamed.name === "string" && maybeNamed.name.trim().length > 0) {
+      return maybeNamed.name;
+    }
+    const ctorName = hook.constructor?.name;
+    if (typeof ctorName === "string" && ctorName !== "Object" && ctorName.trim().length > 0) {
+      return ctorName;
+    }
+    return `hook#${index + 1}`;
+  }
+  assertValidHookShape(hook, index) {
+    const extensionPoints = [
+      "beforeLLMRequest",
+      "beforeToolCall",
+      "afterToolResult",
+      "beforeResponse"
+    ];
+    const hasExtensionPoint = extensionPoints.some(
+      (point) => typeof hook[point] === "function"
+    );
+    if (!hasExtensionPoint) {
+      throw new import_errors.DextoRuntimeError(
+        import_error_codes.HookErrorCode.HOOK_INVALID_SHAPE,
+        import_errors.ErrorScope.HOOK,
+        import_errors.ErrorType.USER,
+        `Hook '${this.deriveHookName(hook, index)}' must implement at least one extension point method`,
+        { availableExtensionPoints: extensionPoints }
+      );
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HookManager
+});

package/dist/hooks/manager.d.ts

@@ -0,0 +1,103 @@
+import type { ExtensionPoint, Hook } from './types.js';
+import type { AgentEventBus } from '../events/index.js';
+import type { StorageManager } from '../storage/index.js';
+import type { SessionManager } from '../session/index.js';
+import type { MCPManager } from '../mcp/manager.js';
+import type { ToolManager } from '../tools/tool-manager.js';
+import type { AgentStateManager } from '../agent/state-manager.js';
+import type { Logger } from '../logger/v2/types.js';
+/**
+ * Options for HookManager construction.
+ */
+export interface HookManagerOptions {
+    agentEventBus: AgentEventBus;
+    storageManager: StorageManager;
+}
+/**
+ * Options for building hook execution context.
+ * Used when calling `executeHooks()`.
+ */
+export interface HookExecutionContextOptions {
+    sessionManager: SessionManager;
+    mcpManager: MCPManager;
+    toolManager: ToolManager;
+    stateManager: AgentStateManager;
+    sessionId?: string;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Hook Manager - Orchestrates hook execution.
+ *
+ * Responsibilities:
+ * - Validate hook shape
+ * - Manage hook lifecycle (initialize, execute, cleanup)
+ * - Execute hooks sequentially at extension points
+ * - Handle timeouts and errors with fail-fast policy
+ */
+export declare class HookManager {
+    private hooks;
+    private hooksByExtensionPoint;
+    private hookNameByInstance;
+    private options;
+    private initialized;
+    private logger;
+    /** Default timeout for hook execution (milliseconds) */
+    private static readonly DEFAULT_TIMEOUT;
+    constructor(options: HookManagerOptions, hooks: Hook[], logger: Logger);
+    /**
+     * Provide the concrete hooks this manager should orchestrate.
+     * Hooks must be fully resolved and initialized before calling `initialize()`.
+     */
+    setHooks(hooks: Hook[]): void;
+    /**
+     * Initialize hook orchestration.
+     * Validates hook shapes and registers them to extension points.
+     * @throws {DextoRuntimeError} If any hook fails validation (fail-fast)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Register a hook to the extension points it implements.
+     */
+    private registerToExtensionPoints;
+    /**
+     * Execute all hooks at a specific extension point.
+     * Hooks execute sequentially in the order they were provided.
+     *
+     * @param extensionPoint - Which extension point to execute
+     * @param payload - Payload for this extension point (must be an object)
+     * @param options - Options for building execution context
+     * @returns Modified payload after all hooks execute
+     * @throws {DextoRuntimeError} If a hook cancels execution or payload is not an object
+     */
+    executeHooks<T extends object>(extensionPoint: ExtensionPoint, payload: T, options: HookExecutionContextOptions): Promise<T>;
+    /**
+     * Execute a promise with timeout, properly clearing timer on completion
+     * Prevents timer leaks and unhandled rejections from Promise.race
+     */
+    private executeWithTimeout;
+    /**
+     * Cleanup all hooks.
+     * Called when agent shuts down
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get hook statistics.
+     */
+    getStats(): {
+        total: number;
+        enabled: number;
+        byExtensionPoint: Record<ExtensionPoint, number>;
+    };
+    /**
+     * List hook display names in execution order.
+     *
+     * Names are derived from:
+     * - `hook.name` (if present)
+     * - constructor/class name (if available)
+     * - fallback `hook#N`
+     */
+    getHookNames(): string[];
+    private deriveHookName;
+    private assertValidHookShape;
+}
+//# sourceMappingURL=manager.d.ts.map