@dexto/core 1.5.8 → 1.6.1

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/hooks/manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAwB,IAAI,EAAc,MAAM,YAAY,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,aAAa,EAAE,aAAa,CAAC;IAC7B,cAAc,EAAE,cAAc,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IACxC,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,iBAAiB,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,qBAAqB,CAA0C;IACvE,OAAO,CAAC,kBAAkB,CAAwC;IAClE,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,MAAM,CAAS;IAEvB,wDAAwD;IACxD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAQ;gBAEnC,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM;IAOtE;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAkB7B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BjC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAkBjC;;;;;;;;;OASG;IACG,YAAY,CAAC,CAAC,SAAS,MAAM,EAC/B,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,2BAA2B,GACrC,OAAO,CAAC,CAAC,CAAC;IAqKb;;;OAGG;YACW,kBAAkB;IA8BhC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB9B;;OAEG;IACH,QAAQ,IAAI;QACR,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;KACpD;IAaD;;;;;;;OAOG;IACH,YAAY,IAAI,MAAM,EAAE;IAMxB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,oBAAoB;CAsB/B"}