@lleverage-ai/agent-sdk 0.0.1

package/dist/hooks/guardrails.js

@@ -0,0 +1,326 @@
+/**
+ * Guardrails hook utilities.
+ *
+ * Provides content filtering and safety hooks using the unified hook system.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extracts text content from a single message.
+ */
+function extractTextFromMessage(msg) {
+    if (typeof msg !== "object" || msg === null) {
+        return "";
+    }
+    const content = msg.content;
+    if (typeof content === "string") {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        const texts = [];
+        for (const part of content) {
+            if (typeof part === "object" &&
+                part !== null &&
+                "text" in part &&
+                typeof part.text === "string") {
+                texts.push(part.text);
+            }
+        }
+        return texts.join("\n");
+    }
+    return "";
+}
+/**
+ * Extracts text content from all messages for pattern matching.
+ */
+function extractTextFromMessages(messages = []) {
+    const texts = [];
+    for (const msg of messages) {
+        const text = extractTextFromMessage(msg);
+        if (text) {
+            texts.push(text);
+        }
+    }
+    return texts.join("\n");
+}
+/**
+ * Finds message IDs that match any of the given patterns.
+ * Returns IDs of messages containing blocked content.
+ */
+function findBlockedMessageIds(messages, patterns) {
+    const blockedIds = [];
+    for (const msg of messages) {
+        const typedMsg = msg;
+        if (!typedMsg.id)
+            continue;
+        const text = extractTextFromMessage(msg);
+        if (!text)
+            continue;
+        for (const pattern of patterns) {
+            if (pattern.test(text)) {
+                blockedIds.push(typedMsg.id);
+                break; // Only add each message once
+            }
+        }
+    }
+    return blockedIds;
+}
+/**
+ * Creates guardrails hooks for input and output content filtering.
+ *
+ * The PreGenerate hook blocks requests matching input patterns.
+ * The PostGenerate hook filters output matching output patterns.
+ *
+ * This replaces guardrails middleware with hook-based filtering that
+ * works correctly with the unified hook system.
+ *
+ * @param options - Configuration options
+ * @returns Array of two hooks: [PreGenerate input filter, PostGenerate output filter]
+ *
+ * @example
+ * ```typescript
+ * const [inputFilter, outputFilter] = createGuardrailsHooks({
+ *   blockedInputPatterns: [
+ *     /password/i,
+ *     /api.?key/i,
+ *     /secret/i,
+ *   ],
+ *   blockedOutputPatterns: [
+ *     /\b\d{16}\b/,  // Credit card numbers
+ *     /\b\d{3}-\d{2}-\d{4}\b/,  // SSN
+ *   ],
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [inputFilter] }],
+ *     PostGenerate: [{ hooks: [outputFilter] }],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom validation with transformation
+ * const hooks = createGuardrailsHooks({
+ *   checkInput: (input) => {
+ *     // Allow but transform: remove PII from messages
+ *     const cleaned = cleanPII(input.options.messages);
+ *     return {
+ *       ...input,
+ *       options: { ...input.options, messages: cleaned },
+ *     };
+ *   },
+ *   checkOutput: (input) => {
+ *     // Filter harmful content
+ *     if (isHarmful(input.result.text)) {
+ *       return { ...input.result, text: "[Content filtered for safety]" };
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function createGuardrailsHooks(options = {}) {
+    const { blockedInputPatterns = [], blockedOutputPatterns = [], blockedInputMessage = "Request blocked by content policy", filteredOutputMessage = "[Content filtered]", checkInput, checkOutput, } = options;
+    // PreGenerate: Block inputs matching patterns
+    const inputFilter = async (input) => {
+        if (input.hook_event_name !== "PreGenerate")
+            return {};
+        const preGenInput = input;
+        // Custom input validation
+        if (checkInput) {
+            const result = checkInput(preGenInput);
+            if (result && result !== preGenInput) {
+                // Transform input
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PreGenerate",
+                        updatedInput: result.options,
+                    },
+                };
+            }
+        }
+        // Pattern-based blocking
+        if (blockedInputPatterns.length > 0) {
+            const messages = preGenInput.options.messages;
+            const text = extractTextFromMessages(messages);
+            for (const pattern of blockedInputPatterns) {
+                if (pattern.test(text)) {
+                    // Find which messages contain blocked content
+                    const blockedMessageIds = findBlockedMessageIds(messages, [pattern]);
+                    return {
+                        hookSpecificOutput: {
+                            hookEventName: "PreGenerate",
+                            permissionDecision: "deny",
+                            permissionDecisionReason: blockedInputMessage,
+                            blockedMessageIds,
+                        },
+                    };
+                }
+            }
+        }
+        return {};
+    };
+    // PostGenerate: Filter outputs matching patterns
+    const outputFilter = async (input) => {
+        if (input.hook_event_name !== "PostGenerate")
+            return {};
+        const postGenInput = input;
+        // Custom output validation
+        if (checkOutput) {
+            const result = checkOutput(postGenInput);
+            if (result && result !== postGenInput.result) {
+                // Transform output
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PostGenerate",
+                        updatedResult: result,
+                    },
+                };
+            }
+        }
+        // Pattern-based filtering
+        if (blockedOutputPatterns.length > 0) {
+            const text = postGenInput.result.text || "";
+            for (const pattern of blockedOutputPatterns) {
+                if (pattern.test(text)) {
+                    // Replace output text with filter message
+                    return {
+                        hookSpecificOutput: {
+                            hookEventName: "PostGenerate",
+                            updatedResult: {
+                                ...postGenInput.result,
+                                text: filteredOutputMessage,
+                            },
+                        },
+                    };
+                }
+            }
+        }
+        return {};
+    };
+    return [inputFilter, outputFilter];
+}
+/**
+ * Creates guardrails hooks with statistics tracking.
+ *
+ * Returns hooks along with functions to get filtering statistics.
+ *
+ * @param options - Configuration options
+ * @returns Object with hooks and statistics getter
+ *
+ * @example
+ * ```typescript
+ * const { hooks, getStats } = createManagedGuardrailsHooks({
+ *   blockedInputPatterns: [/password/i, /secret/i],
+ *   blockedOutputPatterns: [/\b\d{16}\b/],
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [hooks[0]] }],
+ *     PostGenerate: [{ hooks: [hooks[1]] }],
+ *   },
+ * });
+ *
+ * // Check statistics
+ * const stats = getStats();
+ * console.log(`Blocked inputs: ${stats.blockedInputs}`);
+ * console.log(`Filtered outputs: ${stats.filteredOutputs}`);
+ * ```
+ *
+ * @category Hooks
+ */
+export function createManagedGuardrailsHooks(options = {}) {
+    const { blockedInputPatterns = [], blockedOutputPatterns = [], blockedInputMessage = "Request blocked by content policy", filteredOutputMessage = "[Content filtered]", checkInput, checkOutput, } = options;
+    let blockedInputs = 0;
+    let filteredOutputs = 0;
+    let totalInputs = 0;
+    let totalOutputs = 0;
+    const inputFilter = async (input) => {
+        if (input.hook_event_name !== "PreGenerate")
+            return {};
+        const preGenInput = input;
+        totalInputs++;
+        if (checkInput) {
+            const result = checkInput(preGenInput);
+            if (result && result !== preGenInput) {
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PreGenerate",
+                        updatedInput: result.options,
+                    },
+                };
+            }
+        }
+        if (blockedInputPatterns.length > 0) {
+            const messages = preGenInput.options.messages;
+            const text = extractTextFromMessages(messages);
+            for (const pattern of blockedInputPatterns) {
+                if (pattern.test(text)) {
+                    blockedInputs++;
+                    // Find which messages contain blocked content
+                    const blockedMessageIds = findBlockedMessageIds(messages, [pattern]);
+                    return {
+                        hookSpecificOutput: {
+                            hookEventName: "PreGenerate",
+                            permissionDecision: "deny",
+                            permissionDecisionReason: blockedInputMessage,
+                            blockedMessageIds,
+                        },
+                    };
+                }
+            }
+        }
+        return {};
+    };
+    const outputFilter = async (input) => {
+        if (input.hook_event_name !== "PostGenerate")
+            return {};
+        const postGenInput = input;
+        totalOutputs++;
+        if (checkOutput) {
+            const result = checkOutput(postGenInput);
+            if (result && result !== postGenInput.result) {
+                return {
+                    hookSpecificOutput: {
+                        hookEventName: "PostGenerate",
+                        updatedResult: result,
+                    },
+                };
+            }
+        }
+        if (blockedOutputPatterns.length > 0) {
+            const text = postGenInput.result.text || "";
+            for (const pattern of blockedOutputPatterns) {
+                if (pattern.test(text)) {
+                    filteredOutputs++;
+                    return {
+                        hookSpecificOutput: {
+                            hookEventName: "PostGenerate",
+                            updatedResult: {
+                                ...postGenInput.result,
+                                text: filteredOutputMessage,
+                            },
+                        },
+                    };
+                }
+            }
+        }
+        return {};
+    };
+    return {
+        hooks: [inputFilter, outputFilter],
+        getStats: () => ({
+            blockedInputs,
+            filteredOutputs,
+            totalInputs,
+            totalOutputs,
+        }),
+    };
+}
+//# sourceMappingURL=guardrails.js.map

package/dist/hooks/guardrails.js.map

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

package/dist/hooks/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hook utility factories.
+ *
+ * This module provides convenience factories that create hooks for common
+ * use cases like caching, retries, rate limiting, and content filtering.
+ *
+ * @packageDocumentation
+ * @category Hooks
+ */
+export { type AuditEvent, type AuditEventCategory, type AuditEventHandler, type AuditHooksOptions, createAuditHooks, createInMemoryAuditStore, exportAuditEventsJSONLines, } from "./audit.js";
+export { type CacheEntry, type CacheHooksOptions, type CacheStore, createCacheHooks, createManagedCacheHooks, InMemoryCacheStore, } from "./cache.js";
+export { createGuardrailsHooks, createManagedGuardrailsHooks, type GuardrailsHooksOptions, } from "./guardrails.js";
+export { createCompactionLoggingHooks, createComprehensiveLoggingHooks, createLoggingHooks, createToolLoggingHooks, type LoggingHooksOptions, } from "./logging.js";
+export { type BufferedGuardrailState, BufferedOutputGuardrail, createBufferedOutputGuardrail, createRegexGuardrail, extractTextFromMessages, findLastUserMessageId, type Guardrail, type GuardrailCheckResult, type OutputGuardrailConfig, type RaceGuardrailsOptions, raceGuardrails, runWithGuardrails, withTimeout, wrapStreamWithOutputGuardrail, } from "./parallel-guardrails.js";
+export { createManagedRateLimitHooks, createRateLimitHooks, extractStandardRateLimitHeaders, type RateLimitHooksOptions, type ServerRateLimitInfo, TokenBucketRateLimiter, } from "./rate-limit.js";
+export { createManagedRetryHooks, createRetryHooks, type RetryHooksOptions, } from "./retry.js";
+export { COMMON_SECRET_PATTERNS, createManagedSecretsFilterHooks, createSecretsFilterHooks, type SecretsFilterHooksOptions, } from "./secrets.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;;;;;;;;GAQG;AAGH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,4BAA4B,EAC5B,+BAA+B,EAC/B,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,sBAAsB,EAC3B,uBAAuB,EAEvB,6BAA6B,EAE7B,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAE1B,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,2BAA2B,EAC3B,oBAAoB,EACpB,+BAA+B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAC/B,wBAAwB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,32 @@
+/**
+ * Hook utility factories.
+ *
+ * This module provides convenience factories that create hooks for common
+ * use cases like caching, retries, rate limiting, and content filtering.
+ *
+ * @packageDocumentation
+ * @category Hooks
+ */
+// Audit hooks
+export { createAuditHooks, createInMemoryAuditStore, exportAuditEventsJSONLines, } from "./audit.js";
+// Cache hooks
+export { createCacheHooks, createManagedCacheHooks, InMemoryCacheStore, } from "./cache.js";
+// Guardrails hooks
+export { createGuardrailsHooks, createManagedGuardrailsHooks, } from "./guardrails.js";
+// Logging hooks
+export { createCompactionLoggingHooks, createComprehensiveLoggingHooks, createLoggingHooks, createToolLoggingHooks, } from "./logging.js";
+// Guardrails (composable content moderation)
+export { BufferedOutputGuardrail, 
+// Buffered output guardrails
+createBufferedOutputGuardrail, 
+// Helpers
+createRegexGuardrail, extractTextFromMessages, findLastUserMessageId, 
+// Core
+raceGuardrails, runWithGuardrails, withTimeout, wrapStreamWithOutputGuardrail, } from "./parallel-guardrails.js";
+// Rate limit hooks
+export { createManagedRateLimitHooks, createRateLimitHooks, extractStandardRateLimitHeaders, TokenBucketRateLimiter, } from "./rate-limit.js";
+// Retry hooks
+export { createManagedRetryHooks, createRetryHooks, } from "./retry.js";
+// Secrets filter hooks
+export { COMMON_SECRET_PATTERNS, createManagedSecretsFilterHooks, createSecretsFilterHooks, } from "./secrets.js";
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc;AACd,OAAO,EAKL,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AACpB,cAAc;AACd,OAAO,EAIL,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,mBAAmB;AACnB,OAAO,EACL,qBAAqB,EACrB,4BAA4B,GAE7B,MAAM,iBAAiB,CAAC;AAEzB,gBAAgB;AAChB,OAAO,EACL,4BAA4B,EAC5B,+BAA+B,EAC/B,kBAAkB,EAClB,sBAAsB,GAEvB,MAAM,cAAc,CAAC;AACtB,6CAA6C;AAC7C,OAAO,EAEL,uBAAuB;AACvB,6BAA6B;AAC7B,6BAA6B;AAC7B,UAAU;AACV,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB;AAKrB,OAAO;AACP,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,mBAAmB;AACnB,OAAO,EACL,2BAA2B,EAC3B,oBAAoB,EACpB,+BAA+B,EAG/B,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,cAAc;AACd,OAAO,EACL,uBAAuB,EACvB,gBAAgB,GAEjB,MAAM,YAAY,CAAC;AACpB,uBAAuB;AACvB,OAAO,EACL,sBAAsB,EACtB,+BAA+B,EAC/B,wBAAwB,GAEzB,MAAM,cAAc,CAAC"}

package/dist/hooks/logging.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Logging hook utilities.
+ *
+ * Provides logging hooks for observability and debugging using the unified
+ * hook system.
+ *
+ * @packageDocumentation
+ */
+import type { HookCallback } from "../types.js";
+/**
+ * Options for creating logging hooks.
+ *
+ * @category Hooks
+ */
+export interface LoggingHooksOptions {
+    /**
+     * Custom logging function.
+     * @defaultValue console.log
+     */
+    log?: (message: string) => void;
+    /**
+     * Whether to log generation requests.
+     * @defaultValue true
+     */
+    logGeneration?: boolean;
+    /**
+     * Whether to log tool usage.
+     * @defaultValue true
+     */
+    logTools?: boolean;
+    /**
+     * Whether to log timing information.
+     * @defaultValue true
+     */
+    logTiming?: boolean;
+    /**
+     * Whether to log errors.
+     * @defaultValue true
+     */
+    logErrors?: boolean;
+    /**
+     * Whether to log compaction events.
+     * @defaultValue true
+     */
+    logCompaction?: boolean;
+    /**
+     * Maximum length for logged text content.
+     * @defaultValue 200
+     */
+    maxTextLength?: number;
+    /**
+     * Prefix for all log messages.
+     * @defaultValue "[Agent]"
+     */
+    prefix?: string;
+    /**
+     * Whether to log full message arrays.
+     * @defaultValue false (just count)
+     */
+    logFullMessages?: boolean;
+}
+/**
+ * Creates logging hooks for generation lifecycle events.
+ *
+ * Provides Pre/Post logging for generation with timing information,
+ * usage statistics, and error logging.
+ *
+ * @param options - Configuration options
+ * @returns Array of hooks for generation events
+ *
+ * @example
+ * ```typescript
+ * const logHooks = createLoggingHooks({
+ *   prefix: "[MyAgent]",
+ *   logTiming: true,
+ *   maxTextLength: 100,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [logHooks[0]] }],
+ *     PostGenerate: [{ hooks: [logHooks[1]] }],
+ *     PostGenerateFailure: [{ hooks: [logHooks[2]] }],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom logger (e.g., structured logging)
+ * const logHooks = createLoggingHooks({
+ *   log: (msg) => logger.info(msg),
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function createLoggingHooks(options?: LoggingHooksOptions): HookCallback[];
+/**
+ * Creates logging hooks for tool execution events.
+ *
+ * Provides Pre/Post logging for tool calls with arguments, results,
+ * and error information.
+ *
+ * @param options - Configuration options
+ * @returns Array of hooks for tool events
+ *
+ * @example
+ * ```typescript
+ * const toolLogHooks = createToolLoggingHooks({
+ *   prefix: "[Tools]",
+ *   maxTextLength: 150,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreToolUse: [{ hooks: [toolLogHooks[0]] }],
+ *     PostToolUse: [{ hooks: [toolLogHooks[1]] }],
+ *     PostToolUseFailure: [{ hooks: [toolLogHooks[2]] }],
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function createToolLoggingHooks(options?: LoggingHooksOptions): HookCallback[];
+/**
+ * Creates logging hooks for context compaction events.
+ *
+ * Provides Pre/Post logging for compaction with token savings
+ * and message count information.
+ *
+ * @param options - Configuration options
+ * @returns Array of hooks for compaction events
+ *
+ * @example
+ * ```typescript
+ * const compactLogHooks = createCompactionLoggingHooks({
+ *   prefix: "[Compaction]",
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreCompact: [compactLogHooks[0]],
+ *     PostCompact: [compactLogHooks[1]],
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function createCompactionLoggingHooks(options?: LoggingHooksOptions): HookCallback[];
+/**
+ * Creates comprehensive logging hooks for all lifecycle events.
+ *
+ * Combines generation, tool, and compaction logging into a single set of hooks.
+ *
+ * @param options - Configuration options
+ * @returns Object with hooks for all events
+ *
+ * @example
+ * ```typescript
+ * const { generationHooks, toolHooks, compactionHooks } = createComprehensiveLoggingHooks({
+ *   prefix: "[MyAgent]",
+ *   logTiming: true,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [generationHooks[0]],
+ *     PostGenerate: [generationHooks[1]],
+ *     PostGenerateFailure: [generationHooks[2]],
+ *     PreToolUse: [toolHooks[0]],
+ *     PostToolUse: [toolHooks[1]],
+ *     PostToolUseFailure: [toolHooks[2]],
+ *     PreCompact: [compactionHooks[0]],
+ *     PostCompact: [compactionHooks[1]],
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function createComprehensiveLoggingHooks(options?: LoggingHooksOptions): {
+    generationHooks: HookCallback[];
+    toolHooks: HookCallback[];
+    compactionHooks: HookCallback[];
+};
+//# sourceMappingURL=logging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/hooks/logging.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EASb,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,EAAE,CA6FpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,EAAE,CAmFxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,EAAE,CA0D9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,GAAE,mBAAwB,GAAG;IAClF,eAAe,EAAE,YAAY,EAAE,CAAC;IAChC,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,eAAe,EAAE,YAAY,EAAE,CAAC;CACjC,CAMA"}