@lleverage-ai/agent-sdk 0.0.1

package/dist/hooks/audit.js

@@ -0,0 +1,305 @@
+/**
+ * Audit hook utilities.
+ *
+ * Provides structured audit event emission for compliance and monitoring
+ * using the unified hook system.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Determines audit category from tool name.
+ */
+function categorizeToolUse(toolName) {
+    const name = toolName.toLowerCase();
+    if (name === "bash" || name === "execute") {
+        return "command_execution";
+    }
+    if (name === "read" ||
+        name === "write" ||
+        name === "edit" ||
+        name === "glob" ||
+        name === "grep") {
+        return "file_access";
+    }
+    return "tool_execution";
+}
+/**
+ * Creates audit hooks for all lifecycle events.
+ *
+ * Emits structured audit events for tool execution, generation,
+ * and errors. Useful for compliance, security monitoring, and
+ * debugging.
+ *
+ * This addresses the audit events requirement from CODE_REVIEW.md
+ * using the unified hook system.
+ *
+ * @param options - Configuration options
+ * @returns Array of hooks for all audited events
+ *
+ * @example
+ * ```typescript
+ * const auditHooks = createAuditHooks({
+ *   onEvent: (event) => {
+ *     // Send to your logging service
+ *     logger.info('Audit event', event);
+ *
+ *     // Send to SIEM
+ *     siem.send(event);
+ *
+ *     // Store in database
+ *     db.auditEvents.insert(event);
+ *   },
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreToolUse: [{ hooks: [auditHooks[0]] }],
+ *     PostToolUse: [{ hooks: [auditHooks[1]] }],
+ *     PostToolUseFailure: [{ hooks: [auditHooks[2]] }],
+ *     PreGenerate: [{ hooks: [auditHooks[3]] }],
+ *     PostGenerate: [{ hooks: [auditHooks[4]] }],
+ *     PostGenerateFailure: [{ hooks: [auditHooks[5]] }],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Selective auditing
+ * const auditHooks = createAuditHooks({
+ *   categories: ['command_execution', 'file_access', 'policy_denial'],
+ *   onEvent: (event) => {
+ *     if (event.category === 'command_execution') {
+ *       securityLog.command(event);
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // JSON lines export for log aggregation
+ * const auditHooks = createAuditHooks({
+ *   onEvent: (event) => {
+ *     console.log(JSON.stringify(event));
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function createAuditHooks(options) {
+    const { onEvent, categories, auditTools = true, auditGeneration = true, auditErrors = true, metadata = {}, } = options;
+    const shouldAuditCategory = (category) => {
+        if (!categories)
+            return true;
+        return categories.includes(category);
+    };
+    // PreToolUse: Audit tool calls
+    const preToolUse = async (input, toolUseId) => {
+        if (input.hook_event_name !== "PreToolUse")
+            return {};
+        if (!auditTools)
+            return {};
+        const preToolInput = input;
+        const category = categorizeToolUse(preToolInput.tool_name);
+        if (!shouldAuditCategory(category))
+            return {};
+        const event = {
+            category,
+            event: "PreToolUse",
+            timestamp: Date.now(),
+            sessionId: preToolInput.session_id,
+            toolUseId,
+            toolName: preToolInput.tool_name,
+            toolInput: preToolInput.tool_input,
+            metadata,
+        };
+        await onEvent(event);
+        return {};
+    };
+    // PostToolUse: Audit successful tool execution
+    const postToolUse = async (input, toolUseId) => {
+        if (input.hook_event_name !== "PostToolUse")
+            return {};
+        if (!auditTools)
+            return {};
+        const postToolInput = input;
+        const category = categorizeToolUse(postToolInput.tool_name);
+        if (!shouldAuditCategory(category))
+            return {};
+        const event = {
+            category,
+            event: "PostToolUse",
+            timestamp: Date.now(),
+            sessionId: postToolInput.session_id,
+            toolUseId,
+            toolName: postToolInput.tool_name,
+            toolInput: postToolInput.tool_input,
+            toolOutput: postToolInput.tool_response,
+            metadata,
+        };
+        await onEvent(event);
+        return {};
+    };
+    // PostToolUseFailure: Audit tool errors
+    const postToolUseFailure = async (input, toolUseId) => {
+        if (input.hook_event_name !== "PostToolUseFailure")
+            return {};
+        if (!auditErrors)
+            return {};
+        const failureInput = input;
+        const category = categorizeToolUse(failureInput.tool_name);
+        if (!shouldAuditCategory(category) && !shouldAuditCategory("error"))
+            return {};
+        const event = {
+            category: "error",
+            event: "PostToolUseFailure",
+            timestamp: Date.now(),
+            sessionId: failureInput.session_id,
+            toolUseId,
+            toolName: failureInput.tool_name,
+            toolInput: failureInput.tool_input,
+            error: typeof failureInput.error === "string" ? failureInput.error : failureInput.error.message,
+            metadata,
+        };
+        await onEvent(event);
+        return {};
+    };
+    // PreGenerate: Audit generation requests
+    const preGenerate = async (input) => {
+        if (input.hook_event_name !== "PreGenerate")
+            return {};
+        if (!auditGeneration)
+            return {};
+        if (!shouldAuditCategory("generation"))
+            return {};
+        const preGenInput = input;
+        const event = {
+            category: "generation",
+            event: "PreGenerate",
+            timestamp: Date.now(),
+            sessionId: preGenInput.session_id,
+            metadata: {
+                ...metadata,
+                messageCount: preGenInput.options.messages?.length || 0,
+            },
+        };
+        await onEvent(event);
+        return {};
+    };
+    // PostGenerate: Audit generation results
+    const postGenerate = async (input) => {
+        if (input.hook_event_name !== "PostGenerate")
+            return {};
+        if (!auditGeneration)
+            return {};
+        if (!shouldAuditCategory("generation"))
+            return {};
+        const postGenInput = input;
+        const event = {
+            category: "generation",
+            event: "PostGenerate",
+            timestamp: Date.now(),
+            sessionId: postGenInput.session_id,
+            usage: postGenInput.result.usage,
+            metadata: {
+                ...metadata,
+                finishReason: postGenInput.result.finishReason,
+            },
+        };
+        await onEvent(event);
+        return {};
+    };
+    // PostGenerateFailure: Audit generation errors
+    const postGenerateFailure = async (input) => {
+        if (input.hook_event_name !== "PostGenerateFailure")
+            return {};
+        if (!auditErrors)
+            return {};
+        if (!shouldAuditCategory("error"))
+            return {};
+        const failureInput = input;
+        const event = {
+            category: "error",
+            event: "PostGenerateFailure",
+            timestamp: Date.now(),
+            sessionId: failureInput.session_id,
+            error: failureInput.error.message,
+            metadata,
+        };
+        await onEvent(event);
+        return {};
+    };
+    return [
+        preToolUse,
+        postToolUse,
+        postToolUseFailure,
+        preGenerate,
+        postGenerate,
+        postGenerateFailure,
+    ];
+}
+/**
+ * Export audit events to JSON Lines format.
+ *
+ * Returns a function that writes audit events to console.log
+ * in JSON Lines format (one JSON object per line), suitable for
+ * log aggregation tools.
+ *
+ * @returns Audit event handler for JSON Lines export
+ *
+ * @example
+ * ```typescript
+ * const auditHooks = createAuditHooks({
+ *   onEvent: exportAuditEventsJSONLines(),
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function exportAuditEventsJSONLines() {
+    return (event) => {
+        console.log(JSON.stringify(event));
+    };
+}
+/**
+ * Creates an in-memory audit event store.
+ *
+ * Useful for testing and development. Events are kept in memory
+ * with a configurable size limit.
+ *
+ * @param maxEvents - Maximum events to keep
+ * @returns Object with event handler and getter
+ *
+ * @example
+ * ```typescript
+ * const { onEvent, getEvents, clear } = createInMemoryAuditStore(1000);
+ *
+ * const auditHooks = createAuditHooks({ onEvent });
+ *
+ * // Later, retrieve events
+ * const events = getEvents();
+ * console.log(`Captured ${events.length} audit events`);
+ * ```
+ *
+ * @category Hooks
+ */
+export function createInMemoryAuditStore(maxEvents = 1000) {
+    const events = [];
+    return {
+        onEvent: (event) => {
+            events.push(event);
+            // LRU eviction
+            if (events.length > maxEvents) {
+                events.shift();
+            }
+        },
+        getEvents: () => [...events],
+        clear: () => {
+            events.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=audit.js.map

package/dist/hooks/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/hooks/audit.ts"],"names":[],"mappings":"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"}

package/dist/hooks/cache.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Cache hook utilities.
+ *
+ * Provides cache hooks that replace the cache middleware functionality
+ * using the unified hook system.
+ *
+ * @packageDocumentation
+ */
+import type { HookCallback, HookCallbackContext, PreGenerateInput } from "../types.js";
+/**
+ * Cache entry with timestamp for TTL enforcement.
+ *
+ * @category Hooks
+ */
+export interface CacheEntry {
+    /** Cached result */
+    result: unknown;
+    /** Timestamp when cached (milliseconds since epoch) */
+    timestamp: number;
+}
+/**
+ * Cache storage interface.
+ *
+ * Implement this interface to provide custom cache backends
+ * (Redis, file-based, etc.).
+ *
+ * @category Hooks
+ */
+export interface CacheStore {
+    /** Get a cached entry by key */
+    get(key: string): Promise<CacheEntry | undefined> | CacheEntry | undefined;
+    /** Store a cache entry */
+    set(key: string, value: CacheEntry): Promise<void> | void;
+    /** Delete a cache entry */
+    delete(key: string): Promise<boolean> | boolean;
+    /** Clear all cache entries */
+    clear(): Promise<void> | void;
+}
+/**
+ * Default in-memory cache store implementation with LRU eviction.
+ *
+ * @category Hooks
+ */
+export declare class InMemoryCacheStore implements CacheStore {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    get(key: string): CacheEntry | undefined;
+    set(key: string, value: CacheEntry): void;
+    delete(key: string): boolean;
+    clear(): void;
+    /** Get current cache size */
+    get size(): number;
+}
+/**
+ * Options for creating cache hooks.
+ *
+ * @category Hooks
+ */
+export interface CacheHooksOptions {
+    /**
+     * Time-to-live in milliseconds. Cached entries older than this are ignored.
+     * @defaultValue 300000 (5 minutes)
+     */
+    ttl?: number;
+    /**
+     * Maximum number of cache entries (for in-memory store).
+     * @defaultValue 100
+     */
+    maxSize?: number;
+    /**
+     * Custom cache key generator.
+     * @defaultValue Hashes messages, model, temperature, and maxTokens
+     */
+    keyGenerator?: (input: PreGenerateInput, context?: HookCallbackContext) => string;
+    /**
+     * Cache storage backend.
+     * @defaultValue New InMemoryCacheStore
+     */
+    store?: CacheStore;
+    /**
+     * Optional predicate to determine if a request should be cached.
+     * @defaultValue Always cache
+     */
+    shouldCache?: (input: PreGenerateInput) => boolean;
+}
+/**
+ * Creates cache hooks for PreGenerate and PostGenerate events.
+ *
+ * The PreGenerate hook checks for cached results and returns them via
+ * `respondWith` to short-circuit generation. The PostGenerate hook stores
+ * results in the cache.
+ *
+ * This replaces the cache middleware with hook-based caching that works
+ * correctly with streaming (hooks fire at lifecycle boundaries).
+ *
+ * @param options - Configuration options
+ * @returns Array of two hooks: [PreGenerate cache check, PostGenerate cache store]
+ *
+ * @example
+ * ```typescript
+ * const [cacheCheck, cacheStore] = createCacheHooks({
+ *   ttl: 60000,  // 1 minute
+ *   maxSize: 50,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [cacheCheck] }],
+ *     PostGenerate: [{ hooks: [cacheStore] }],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom cache key based on last message
+ * const hooks = createCacheHooks({
+ *   keyGenerator: (input) => {
+ *     const lastMsg = input.options.messages?.[input.options.messages.length - 1];
+ *     return JSON.stringify(lastMsg);
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Conditional caching (only cache when no tools)
+ * const hooks = createCacheHooks({
+ *   shouldCache: (input) => !input.options.tools || Object.keys(input.options.tools).length === 0,
+ *   ttl: 300000,
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function createCacheHooks(options?: CacheHooksOptions): [HookCallback, HookCallback];
+/**
+ * Creates managed cache hooks with programmatic cache control.
+ *
+ * Returns hooks along with functions to clear cache, delete entries,
+ * and get statistics.
+ *
+ * @param options - Configuration options
+ * @returns Object with hooks and cache control functions
+ *
+ * @example
+ * ```typescript
+ * const { hooks, clearCache, getStats } = createManagedCacheHooks();
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [hooks[0]] }],
+ *     PostGenerate: [{ hooks: [hooks[1]] }],
+ *   },
+ * });
+ *
+ * // Clear cache when needed
+ * await clearCache();
+ *
+ * // Get cache statistics
+ * const { size, hits, misses } = getStats();
+ * console.log(`Cache hit rate: ${hits / (hits + misses)}`);
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function createManagedCacheHooks(options?: CacheHooksOptions): {
+    hooks: [HookCallback, HookCallback];
+    clearCache: () => Promise<void> | void;
+    deleteEntry: (key: string) => Promise<boolean> | boolean;
+    getStats: () => {
+        size: number;
+        hits: number;
+        misses: number;
+    };
+};
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/hooks/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EAEnB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,oBAAoB;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,UAAU,GAAG,SAAS,CAAC;IAC3E,0BAA0B;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1D,2BAA2B;IAC3B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAChD,8BAA8B;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,SAAM;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAWzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,KAAK,IAAI,IAAI;IAIb,6BAA6B;IAC7B,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,MAAM,CAAC;IAElF;;;OAGG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC;CACpD;AAoCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,CAqE9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,iBAAsB,GAAG;IACxE,KAAK,EAAE,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IACpC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvC,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACzD,QAAQ,EAAE,MAAM;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAChE,CA4EA"}