@lleverage-ai/agent-sdk 0.0.1

package/dist/hooks/secrets.js

@@ -0,0 +1,306 @@
+/**
+ * Secrets filtering hook utilities.
+ *
+ * Provides hooks to detect and redact common secret patterns in inputs
+ * and outputs using the unified hook system.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Common secret patterns for automatic detection.
+ *
+ * @category Hooks
+ */
+export const COMMON_SECRET_PATTERNS = {
+    /** AWS access keys (AKIA...) */
+    AWS_ACCESS_KEY: /AKIA[0-9A-Z]{16}/g,
+    /** AWS secret keys (40 chars base64) */
+    AWS_SECRET_KEY: /[A-Za-z0-9/+=]{40}/g,
+    /** GitHub personal access tokens */
+    GITHUB_TOKEN: /ghp_[A-Za-z0-9]{36}/g,
+    /** GitHub OAuth tokens */
+    GITHUB_OAUTH: /gho_[A-Za-z0-9]{36}/g,
+    /** Generic API keys (common formats) */
+    API_KEY: /api[_-]?key[_-]?[=:]\s*['""]?[A-Za-z0-9_-]{20,}['""]?/gi,
+    /** Bearer tokens */
+    BEARER_TOKEN: /Bearer\s+[A-Za-z0-9_\-.]+/gi,
+    /** JWT tokens */
+    JWT: /eyJ[A-Za-z0-9_-]*\.eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*/g,
+    /** Private keys (PEM format headers) */
+    PRIVATE_KEY: /-----BEGIN\s+(?:RSA|EC|OPENSSH|DSA)?\s*PRIVATE KEY-----[\s\S]*?-----END\s+(?:RSA|EC|OPENSSH|DSA)?\s*PRIVATE KEY-----/g,
+    /** Generic passwords in common formats */
+    PASSWORD: /password[_-]?[=:]\s*['""]?[^\s'"",;]{6,}['""]?/gi,
+    /** Slack tokens */
+    SLACK_TOKEN: /xox[baprs]-[0-9a-zA-Z]{10,48}/g,
+    /** Stripe API keys */
+    STRIPE_KEY: /sk_(?:live|test)_[0-9a-zA-Z]{24,}/g,
+    /** Generic secrets in common formats */
+    GENERIC_SECRET: /secret[_-]?[=:]\s*['""]?[A-Za-z0-9_-]{20,}['""]?/gi,
+};
+/**
+ * Redacts secrets in text using the provided patterns.
+ */
+function redactSecrets(text, patterns, redactionText, onDetected) {
+    let redacted = text;
+    for (const pattern of patterns) {
+        // Reset lastIndex for global patterns
+        pattern.lastIndex = 0;
+        // Find all matches first (for callback)
+        if (onDetected) {
+            const matches = text.match(pattern);
+            if (matches) {
+                for (const match of matches) {
+                    onDetected(pattern, match);
+                }
+            }
+        }
+        // Redact all matches
+        redacted = redacted.replace(pattern, redactionText);
+    }
+    return redacted;
+}
+/**
+ * Extracts and redacts text from messages.
+ */
+function redactMessages(messages = [], patterns, redactionText, onDetected) {
+    return messages.map((msg) => {
+        if (typeof msg !== "object" || msg === null)
+            return msg;
+        const content = msg.content;
+        if (typeof content === "string") {
+            return {
+                ...msg,
+                content: redactSecrets(content, patterns, redactionText, onDetected),
+            };
+        }
+        else if (Array.isArray(content)) {
+            return {
+                ...msg,
+                content: content.map((part) => {
+                    if (typeof part === "object" &&
+                        part !== null &&
+                        "text" in part &&
+                        typeof part.text === "string") {
+                        return {
+                            ...part,
+                            text: redactSecrets(part.text, patterns, redactionText, onDetected),
+                        };
+                    }
+                    return part;
+                }),
+            };
+        }
+        return msg;
+    });
+}
+/**
+ * Creates secrets filtering hooks for input and output.
+ *
+ * The PreGenerate hook redacts secrets from input messages before sending
+ * to the model. The PostGenerate hook redacts secrets from model responses.
+ *
+ * This addresses the secrets redaction requirement from CODE_REVIEW.md
+ * using the unified hook system.
+ *
+ * @param options - Configuration options
+ * @returns Array of two hooks: [PreGenerate input filter, PostGenerate output filter]
+ *
+ * @example
+ * ```typescript
+ * const [inputFilter, outputFilter] = createSecretsFilterHooks({
+ *   redactionText: "***REDACTED***",
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [inputFilter] }],
+ *     PostGenerate: [{ hooks: [outputFilter] }],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom patterns with alerting
+ * const hooks = createSecretsFilterHooks({
+ *   customPatterns: [/my-secret-format-[A-Z0-9]{16}/g],
+ *   onSecretDetected: (type, pattern, match) => {
+ *     console.warn(`Secret detected in ${type}:`, pattern.source);
+ *     alertSecurityTeam({ type, pattern: pattern.source });
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Only specific patterns
+ * const hooks = createSecretsFilterHooks({
+ *   patterns: [
+ *     COMMON_SECRET_PATTERNS.AWS_ACCESS_KEY,
+ *     COMMON_SECRET_PATTERNS.GITHUB_TOKEN,
+ *   ],
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function createSecretsFilterHooks(options = {}) {
+    const { customPatterns = [], patterns = Object.values(COMMON_SECRET_PATTERNS), redactionText = "[REDACTED]", filterInput = true, filterOutput = true, onSecretDetected, } = options;
+    const allPatterns = [...patterns, ...customPatterns];
+    // PreGenerate: Redact secrets from input
+    const inputFilter = async (input) => {
+        if (input.hook_event_name !== "PreGenerate")
+            return {};
+        if (!filterInput)
+            return {};
+        const preGenInput = input;
+        const messages = preGenInput.options.messages;
+        if (!messages || messages.length === 0)
+            return {};
+        const redactedMessages = redactMessages(messages, allPatterns, redactionText, onSecretDetected ? (pattern, match) => onSecretDetected("input", pattern, match) : undefined);
+        // Only return updatedInput if we actually changed something
+        if (JSON.stringify(redactedMessages) !== JSON.stringify(messages)) {
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreGenerate",
+                    updatedInput: {
+                        ...preGenInput.options,
+                        messages: redactedMessages,
+                    },
+                },
+            };
+        }
+        return {};
+    };
+    // PostGenerate: Redact secrets from output
+    const outputFilter = async (input) => {
+        if (input.hook_event_name !== "PostGenerate")
+            return {};
+        if (!filterOutput)
+            return {};
+        const postGenInput = input;
+        const text = postGenInput.result.text || "";
+        const redactedText = redactSecrets(text, allPatterns, redactionText, onSecretDetected ? (pattern, match) => onSecretDetected("output", pattern, match) : undefined);
+        // Only return updatedResult if we actually changed something
+        if (redactedText !== text) {
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PostGenerate",
+                    updatedResult: {
+                        ...postGenInput.result,
+                        text: redactedText,
+                    },
+                },
+            };
+        }
+        return {};
+    };
+    return [inputFilter, outputFilter];
+}
+/**
+ * Creates managed secrets filter hooks with detection statistics.
+ *
+ * Returns hooks along with functions to get detection statistics.
+ *
+ * @param options - Configuration options
+ * @returns Object with hooks and statistics getter
+ *
+ * @example
+ * ```typescript
+ * const { hooks, getStats, getDetections } = createManagedSecretsFilterHooks();
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [hooks[0]] }],
+ *     PostGenerate: [{ hooks: [hooks[1]] }],
+ *   },
+ * });
+ *
+ * // Check statistics
+ * const stats = getStats();
+ * console.log(`Secrets detected: ${stats.totalDetections} (${stats.inputDetections} input, ${stats.outputDetections} output)`);
+ *
+ * // Get detailed detections
+ * const detections = getDetections();
+ * console.log('Recent detections:', detections.slice(0, 10));
+ * ```
+ *
+ * @category Hooks
+ */
+export function createManagedSecretsFilterHooks(options = {}) {
+    const { customPatterns = [], patterns = Object.values(COMMON_SECRET_PATTERNS), redactionText = "[REDACTED]", filterInput = true, filterOutput = true, onSecretDetected, } = options;
+    const allPatterns = [...patterns, ...customPatterns];
+    let inputDetections = 0;
+    let outputDetections = 0;
+    const detections = [];
+    const trackDetection = (type, pattern, match) => {
+        if (type === "input")
+            inputDetections++;
+        else
+            outputDetections++;
+        detections.push({
+            type,
+            pattern: pattern.source,
+            timestamp: Date.now(),
+        });
+        if (onSecretDetected) {
+            onSecretDetected(type, pattern, match);
+        }
+    };
+    const inputFilter = async (input) => {
+        if (input.hook_event_name !== "PreGenerate")
+            return {};
+        if (!filterInput)
+            return {};
+        const preGenInput = input;
+        const messages = preGenInput.options.messages;
+        if (!messages || messages.length === 0)
+            return {};
+        const redactedMessages = redactMessages(messages, allPatterns, redactionText, (pattern, match) => trackDetection("input", pattern, match));
+        if (JSON.stringify(redactedMessages) !== JSON.stringify(messages)) {
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreGenerate",
+                    updatedInput: {
+                        ...preGenInput.options,
+                        messages: redactedMessages,
+                    },
+                },
+            };
+        }
+        return {};
+    };
+    const outputFilter = async (input) => {
+        if (input.hook_event_name !== "PostGenerate")
+            return {};
+        if (!filterOutput)
+            return {};
+        const postGenInput = input;
+        const text = postGenInput.result.text || "";
+        const redactedText = redactSecrets(text, allPatterns, redactionText, (pattern, match) => trackDetection("output", pattern, match));
+        if (redactedText !== text) {
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PostGenerate",
+                    updatedResult: {
+                        ...postGenInput.result,
+                        text: redactedText,
+                    },
+                },
+            };
+        }
+        return {};
+    };
+    return {
+        hooks: [inputFilter, outputFilter],
+        getStats: () => ({
+            inputDetections,
+            outputDetections,
+            totalDetections: inputDetections + outputDetections,
+        }),
+        getDetections: () => [...detections],
+    };
+}
+//# sourceMappingURL=secrets.js.map

package/dist/hooks/secrets.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Hook system for observing agent lifecycle events.
+ *
+ * @packageDocumentation
+ */
+import type { Agent, HookCallback, HookInput, HookMatcher, HookOutput } from "./types.js";
+/**
+ * Checks if a tool name matches a HookMatcher pattern.
+ *
+ * @param toolName - The tool name to test
+ * @param matcher - The matcher pattern (undefined matches all)
+ * @returns true if the tool name matches the pattern
+ *
+ * @internal
+ */
+export declare function matchesToolName(toolName: string, matcher: string | undefined): boolean;
+/**
+ * Error thrown when a hook times out.
+ *
+ * @category Hooks
+ */
+export declare class HookTimeoutError extends Error {
+    constructor(timeout: number);
+}
+/**
+ * Invokes hook callbacks with timeout support.
+ *
+ * This function enforces a hard timeout using `Promise.race`. If a hook does not complete
+ * within the specified timeout, it will be treated as returning an empty result `{}`.
+ * The abort signal is also set when the timeout is reached, allowing cooperative hooks
+ * to clean up resources.
+ *
+ * @param hooks - Array of hook callbacks to invoke
+ * @param input - The hook input data
+ * @param toolUseId - The tool use ID (null for non-tool hooks)
+ * @param agent - The agent instance
+ * @param timeout - Timeout in milliseconds (default: 60000). Each hook must complete within this time.
+ * @param retryAttempt - Current retry attempt number (default: 0)
+ * @returns Array of hook outputs. Timed out hooks return empty objects `{}`.
+ *
+ * @example
+ * ```typescript
+ * // Hook that respects the abort signal for cooperative cancellation
+ * const cooperativeHook: HookCallback = async (input, toolUseId, ctx) => {
+ *   for (const item of items) {
+ *     if (ctx.signal.aborted) {
+ *       return {}; // Early exit on abort
+ *     }
+ *     await processItem(item);
+ *   }
+ *   return { hookSpecificOutput: { ... } };
+ * };
+ *
+ * // Even if a hook doesn't check the signal, it will be timed out
+ * const results = await invokeHooksWithTimeout(
+ *   [cooperativeHook, slowHook],
+ *   input,
+ *   toolUseId,
+ *   agent,
+ *   5000 // 5 second timeout
+ * );
+ * ```
+ *
+ * @internal
+ */
+export declare function invokeHooksWithTimeout(hooks: HookCallback[], input: HookInput, toolUseId: string | null, agent: Agent, timeout?: number, retryAttempt?: number): Promise<HookOutput[]>;
+/**
+ * Filters and invokes matching hooks for a tool use event.
+ *
+ * @param matchers - Array of HookMatcher configurations
+ * @param toolName - The name of the tool being used
+ * @param input - The hook input data
+ * @param toolUseId - The tool use ID
+ * @param agent - The agent instance
+ * @returns Array of hook outputs from all matching hooks
+ *
+ * @example
+ * ```typescript
+ * const matchers: HookMatcher[] = [
+ *   { matcher: 'Write|Edit', hooks: [protectFiles], timeout: 30000 },
+ *   { hooks: [auditLogger] }  // Matches all tools
+ * ];
+ *
+ * const outputs = await invokeMatchingHooks(
+ *   matchers,
+ *   'Write',
+ *   input,
+ *   toolUseId,
+ *   agent
+ * );
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function invokeMatchingHooks(matchers: HookMatcher[], toolName: string, input: HookInput, toolUseId: string, agent: Agent): Promise<HookOutput[]>;
+/**
+ * Aggregates permission decisions from multiple hook outputs.
+ *
+ * Follows the hierarchy: deny > ask > allow > default
+ *
+ * @param hookOutputs - Array of hook outputs to aggregate
+ * @param defaultDecision - Default decision if no hooks provide one (default: 'allow')
+ * @returns The aggregated permission decision
+ *
+ * @example
+ * ```typescript
+ * const outputs: HookOutput[] = [
+ *   { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } },
+ *   { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny' } },
+ * ];
+ *
+ * const decision = aggregatePermissionDecisions(outputs);
+ * // Returns 'deny' because deny wins over allow
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function aggregatePermissionDecisions(hookOutputs: HookOutput[], defaultDecision?: "allow" | "deny" | "ask"): "allow" | "deny" | "ask";
+/**
+ * Extracts a cached/mock result from hook outputs for short-circuit execution.
+ *
+ * Returns the first non-undefined `respondWith` value found in the hook outputs.
+ * This enables cache hooks to return cached results without executing the actual operation.
+ *
+ * @param hookOutputs - Array of hook outputs to scan
+ * @returns The cached result if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const outputs: HookOutput[] = [
+ *   { hookSpecificOutput: { hookEventName: 'PreGenerate' } },
+ *   { hookSpecificOutput: { hookEventName: 'PreGenerate', respondWith: cachedResult } },
+ * ];
+ *
+ * const result = extractRespondWith(outputs);
+ * // Returns cachedResult
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function extractRespondWith<T = unknown>(hookOutputs: HookOutput[]): T | undefined;
+/**
+ * Extracts transformed input from hook outputs.
+ *
+ * Returns the first non-undefined `updatedInput` value found in the hook outputs.
+ * This enables hooks to modify inputs before they are used (e.g., redirect file paths,
+ * add rate limit headers, sanitize user input).
+ *
+ * @param hookOutputs - Array of hook outputs to scan
+ * @returns The transformed input if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const outputs: HookOutput[] = [
+ *   { hookSpecificOutput: { hookEventName: 'PreToolUse' } },
+ *   { hookSpecificOutput: {
+ *       hookEventName: 'PreToolUse',
+ *       updatedInput: { file_path: '/sandbox/file.txt' }
+ *     }
+ *   },
+ * ];
+ *
+ * const transformed = extractUpdatedInput(outputs);
+ * // Returns { file_path: '/sandbox/file.txt' }
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function extractUpdatedInput<T = unknown>(hookOutputs: HookOutput[]): T | undefined;
+/**
+ * Extracts transformed result from hook outputs.
+ *
+ * Returns the first non-undefined `updatedResult` value found in the hook outputs.
+ * This enables hooks to modify outputs after execution (e.g., filter sensitive data,
+ * add metadata, transform format, apply post-processing).
+ *
+ * @param hookOutputs - Array of hook outputs to scan
+ * @returns The transformed result if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const outputs: HookOutput[] = [
+ *   { hookSpecificOutput: { hookEventName: 'PostGenerate' } },
+ *   { hookSpecificOutput: {
+ *       hookEventName: 'PostGenerate',
+ *       updatedResult: { ...originalResult, filtered: true }
+ *     }
+ *   },
+ * ];
+ *
+ * const transformed = extractUpdatedResult(outputs);
+ * // Returns { ...originalResult, filtered: true }
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function extractUpdatedResult<T = unknown>(hookOutputs: HookOutput[]): T | undefined;
+/**
+ * Extracts retry decision from PostGenerateFailure or PostToolUseFailure hook outputs.
+ *
+ * Returns the first retry decision found in the hook outputs. If any hook requests a retry,
+ * the operation will be retried after the specified delay (or 0ms if no delay specified).
+ *
+ * @param hookOutputs - Array of hook outputs to scan
+ * @returns Object with retry flag and delay, or undefined if no retry requested
+ *
+ * @example
+ * ```typescript
+ * const outputs: HookOutput[] = [
+ *   { hookSpecificOutput: { hookEventName: 'PostGenerateFailure' } },
+ *   { hookSpecificOutput: {
+ *       hookEventName: 'PostGenerateFailure',
+ *       retry: true,
+ *       retryDelayMs: 1000  // Wait 1s before retrying
+ *     }
+ *   },
+ * ];
+ *
+ * const retryDecision = extractRetryDecision(outputs);
+ * // Returns { retry: true, retryDelayMs: 1000 }
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function extractRetryDecision(hookOutputs: HookOutput[]): {
+    retry: boolean;
+    retryDelayMs: number;
+} | undefined;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM1F;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAYtF;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,YAAY,EAAE,EACrB,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,KAAK,EACZ,OAAO,SAAQ,EACf,YAAY,SAAI,GACf,OAAO,CAAC,UAAU,EAAE,CAAC,CA6CvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,WAAW,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,UAAU,EAAE,CAAC,CAYvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,UAAU,EAAE,EACzB,eAAe,GAAE,OAAO,GAAG,MAAM,GAAG,KAAe,GAClD,OAAO,GAAG,MAAM,GAAG,KAAK,CAsB1B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,GAAG,SAAS,CAQxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,GAAG,SAAS,CAQzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,GAAG,SAAS,CAQ1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,UAAU,EAAE,GACxB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAStD"}