concevent-ai-agent-sdk 1.0.5 → 2.0.0

package/dist/core/middleware.js

@@ -0,0 +1,125 @@
+const LOG_PREFIX = '[AI-Agent-SDK:Middleware]';
+/**
+ * Executes middleware hooks in registration order (first registered = first executed).
+ * Provides a clean API for running middleware at various points in the agent lifecycle.
+ */
+export class MiddlewareExecutor {
+    middlewares;
+    constructor(middlewares = []) {
+        this.middlewares = middlewares;
+    }
+    /**
+     * Returns true if any middleware is registered.
+     */
+    hasMiddleware() {
+        return this.middlewares.length > 0;
+    }
+    /**
+     * Execute beforeChat hooks in order.
+     * Each middleware can modify the message before passing to the next.
+     *
+     * @param ctx - The before chat context
+     * @returns The potentially modified message
+     */
+    async executeBeforeChat(ctx) {
+        let message = ctx.message;
+        for (const middleware of this.middlewares) {
+            if (middleware.beforeChat) {
+                try {
+                    message = await middleware.beforeChat({ ...ctx, message });
+                }
+                catch (error) {
+                    console.error(`${LOG_PREFIX} ${middleware.name} beforeChat error:`, error);
+                    throw error;
+                }
+            }
+        }
+        return message;
+    }
+    /**
+     * Execute afterChat hooks in order.
+     * Each middleware can modify the result before passing to the next.
+     *
+     * @param ctx - The after chat context
+     * @returns The potentially modified result
+     */
+    async executeAfterChat(ctx) {
+        let result = ctx.result;
+        for (const middleware of this.middlewares) {
+            if (middleware.afterChat) {
+                try {
+                    result = await middleware.afterChat({ ...ctx, result });
+                }
+                catch (error) {
+                    console.error(`${LOG_PREFIX} ${middleware.name} afterChat error:`, error);
+                    throw error;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Execute beforeToolCall hooks in order.
+     * Each middleware can modify the tool call before passing to the next.
+     *
+     * @param ctx - The before tool call context
+     * @returns The potentially modified tool call
+     */
+    async executeBeforeToolCall(ctx) {
+        let toolCall = ctx.toolCall;
+        for (const middleware of this.middlewares) {
+            if (middleware.beforeToolCall) {
+                try {
+                    toolCall = await middleware.beforeToolCall({ ...ctx, toolCall });
+                }
+                catch (error) {
+                    console.error(`${LOG_PREFIX} ${middleware.name} beforeToolCall error:`, error);
+                    throw error;
+                }
+            }
+        }
+        return toolCall;
+    }
+    /**
+     * Execute afterToolCall hooks in order.
+     * Each middleware can modify the result before passing to the next.
+     *
+     * @param ctx - The after tool call context
+     * @returns The potentially modified function call result
+     */
+    async executeAfterToolCall(ctx) {
+        let result = ctx.result;
+        for (const middleware of this.middlewares) {
+            if (middleware.afterToolCall) {
+                try {
+                    result = await middleware.afterToolCall({ ...ctx, result });
+                }
+                catch (error) {
+                    console.error(`${LOG_PREFIX} ${middleware.name} afterToolCall error:`, error);
+                    throw error;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Execute onError hooks in order.
+     * These are for observation only and do not modify the error.
+     *
+     * @param ctx - The error context
+     */
+    async executeOnError(ctx) {
+        for (const middleware of this.middlewares) {
+            if (middleware.onError) {
+                try {
+                    await middleware.onError(ctx);
+                }
+                catch (error) {
+                    // Log but don't throw - onError hooks should not break the error flow
+                    console.error(`${LOG_PREFIX} ${middleware.name} onError handler failed:`, error);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=middleware.js.map

package/dist/core/middleware.js.map

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

package/dist/core/orchestrator.d.ts

@@ -0,0 +1,31 @@
+import type { OrchestratorConfig, OrchestratorAgent } from '../types/orchestrator.js';
+/**
+ * Creates an orchestrator agent that can delegate work to specialized sub-agents.
+ *
+ * The orchestrator automatically generates tools for each sub-agent, allowing the
+ * underlying LLM to route requests based on agent descriptions. Sub-agents operate
+ * statelessly—the orchestrator is responsible for providing necessary context.
+ *
+ * @param config - Configuration for the orchestrator agent
+ * @returns An OrchestratorAgent instance
+ *
+ * @example
+ * ```typescript
+ * const codeAgent = createAgent({ ... });
+ * const researchAgent = createAgent({ ... });
+ *
+ * const orchestrator = createOrchestratorAgent({
+ *   apiKey: 'your-api-key',
+ *   model: 'openai/gpt-4',
+ *   systemPrompts: [], // Additional prompts (orchestrator prompt is auto-injected)
+ *   subAgents: [
+ *     { agent: codeAgent, name: 'code_expert', description: 'Handles coding tasks' },
+ *     { agent: researchAgent, name: 'researcher', description: 'Researches topics' },
+ *   ],
+ * });
+ *
+ * const result = await orchestrator.chat('Write a function to sort an array', context);
+ * ```
+ */
+export declare function createOrchestratorAgent(config: OrchestratorConfig): OrchestratorAgent;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/core/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/core/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,0BAA0B,CAAC;AA2HlC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,CA0GrF"}

package/dist/core/orchestrator.js

@@ -0,0 +1,206 @@
+import { createAgent } from './agent.js';
+import { AgentError } from './errors.js';
+import { logger } from './logger.js';
+/**
+ * Symbol used to mark an agent as an orchestrator.
+ * Used to prevent nested orchestrators.
+ */
+const ORCHESTRATOR_MARKER = Symbol.for('concevent.orchestrator');
+/**
+ * Type guard to check if an agent is an orchestrator.
+ */
+function isOrchestratorAgent(agent) {
+    return ORCHESTRATOR_MARKER in agent;
+}
+/**
+ * Creates a tool definition that delegates to a sub-agent.
+ * The tool allows the orchestrator to invoke the sub-agent with a message.
+ */
+function createSubAgentTool(definition, callbacks) {
+    return {
+        declaration: {
+            name: definition.name,
+            description: definition.description,
+            parametersJsonSchema: {
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                        description: 'The complete message to send to this agent. Include all necessary context since the agent has no prior conversation history.',
+                    },
+                },
+                required: ['message'],
+                additionalProperties: false,
+            },
+        },
+        executor: async (args, context) => {
+            const message = args.message;
+            logger.subAgentStart(definition.name, message);
+            // Fire onSubAgentStart callback
+            callbacks?.onSubAgentStart?.({
+                agentName: definition.name,
+                message,
+            });
+            try {
+                // Clear sub-agent history to ensure stateless execution
+                definition.agent.clearHistory();
+                // Delegate to the sub-agent
+                const result = await definition.agent.chat(message, context, {
+                    // Forward abort handling
+                    onAborted: callbacks?.onAborted,
+                    // Forward error handling
+                    onError: callbacks?.onError,
+                });
+                logger.subAgentComplete(definition.name, result.iterations);
+                // Fire onSubAgentComplete callback
+                callbacks?.onSubAgentComplete?.({
+                    agentName: definition.name,
+                    result,
+                });
+                // Return the sub-agent's response message for the orchestrator to synthesize
+                return result.message;
+            }
+            catch (error) {
+                logger.error(`Sub-agent "${definition.name}" failed`, error);
+                throw error;
+            }
+        },
+        parallel: definition.parallel ?? false,
+    };
+}
+/**
+ * Generates the system prompt for the orchestrator.
+ * Explains the orchestrator's role and lists available sub-agents.
+ */
+function generateOrchestratorSystemPrompt(subAgents) {
+    const agentList = subAgents.map((def) => `- **${def.name}**: ${def.description}`).join('\n');
+    return `You are an orchestrator agent responsible for routing tasks to specialized sub-agents.
+
+## Your Role
+- Analyze incoming requests and determine which sub-agent(s) are best suited to handle them.
+- Delegate work by calling the appropriate sub-agent tool(s).
+- When delegating, provide COMPLETE context in your message since sub-agents have no prior conversation history.
+- Synthesize responses from sub-agents into coherent final answers.
+- You may call multiple sub-agents if a task requires different specializations.
+
+## Available Sub-Agents
+${agentList}
+
+## Guidelines
+1. Always include all necessary context when delegating to a sub-agent.
+2. If a task can be handled by multiple agents, choose the most specialized one.
+3. For complex tasks, break them down and delegate parts to appropriate agents.
+4. Combine and summarize sub-agent responses into a unified response for the user.
+5. If no sub-agent is suitable for a request, explain what you can help with.`;
+}
+/**
+ * Creates an orchestrator agent that can delegate work to specialized sub-agents.
+ *
+ * The orchestrator automatically generates tools for each sub-agent, allowing the
+ * underlying LLM to route requests based on agent descriptions. Sub-agents operate
+ * statelessly—the orchestrator is responsible for providing necessary context.
+ *
+ * @param config - Configuration for the orchestrator agent
+ * @returns An OrchestratorAgent instance
+ *
+ * @example
+ * ```typescript
+ * const codeAgent = createAgent({ ... });
+ * const researchAgent = createAgent({ ... });
+ *
+ * const orchestrator = createOrchestratorAgent({
+ *   apiKey: 'your-api-key',
+ *   model: 'openai/gpt-4',
+ *   systemPrompts: [], // Additional prompts (orchestrator prompt is auto-injected)
+ *   subAgents: [
+ *     { agent: codeAgent, name: 'code_expert', description: 'Handles coding tasks' },
+ *     { agent: researchAgent, name: 'researcher', description: 'Researches topics' },
+ *   ],
+ * });
+ *
+ * const result = await orchestrator.chat('Write a function to sort an array', context);
+ * ```
+ */
+export function createOrchestratorAgent(config) {
+    const { subAgents, systemPrompts, ...restConfig } = config;
+    // Validate no nested orchestrators
+    for (const definition of subAgents) {
+        if (isOrchestratorAgent(definition.agent)) {
+            throw new AgentError('NESTED_ORCHESTRATOR_NOT_ALLOWED', `Sub-agent "${definition.name}" is an orchestrator. Nested orchestrators are not allowed.`);
+        }
+    }
+    // Validate unique agent names
+    const names = new Set();
+    for (const definition of subAgents) {
+        if (names.has(definition.name)) {
+            throw new AgentError('GENERIC_ERROR', `Duplicate sub-agent name: "${definition.name}". Each sub-agent must have a unique name.`);
+        }
+        names.add(definition.name);
+    }
+    // We need to create tools that capture callbacks, but callbacks are passed per-chat call.
+    // So we create a mutable reference that gets updated on each chat call.
+    let currentCallbacks;
+    // Generate delegation tools for each sub-agent
+    const subAgentTools = subAgents.map((definition) => {
+        // Create a wrapper that uses the current callbacks
+        const baseToolDef = createSubAgentTool(definition, undefined);
+        return {
+            ...baseToolDef,
+            executor: async (args, context) => {
+                // Create tool with current callbacks
+                const toolWithCallbacks = createSubAgentTool(definition, currentCallbacks);
+                return toolWithCallbacks.executor(args, context);
+            },
+        };
+    });
+    // Generate orchestrator system prompt
+    const orchestratorSystemPrompt = generateOrchestratorSystemPrompt(subAgents);
+    // Combine orchestrator prompt with user-provided prompts
+    const combinedSystemPrompts = [orchestratorSystemPrompt, ...systemPrompts];
+    // Create the underlying agent with generated tools
+    const underlyingAgent = createAgent({
+        ...restConfig,
+        systemPrompts: combinedSystemPrompts,
+        tools: subAgentTools,
+    });
+    // Create the orchestrator agent wrapper
+    const orchestratorAgent = {
+        async chat(message, context, callbacks) {
+            // Update current callbacks for sub-agent tools to use
+            currentCallbacks = callbacks;
+            try {
+                return await underlyingAgent.chat(message, context, callbacks);
+            }
+            finally {
+                currentCallbacks = undefined;
+            }
+        },
+        abort() {
+            underlyingAgent.abort();
+        },
+        getHistory() {
+            return underlyingAgent.getHistory();
+        },
+        setHistory(history) {
+            underlyingAgent.setHistory(history);
+        },
+        clearHistory() {
+            underlyingAgent.clearHistory();
+        },
+        getTokenUsage() {
+            return underlyingAgent.getTokenUsage();
+        },
+        getSubAgents() {
+            return [...subAgents];
+        },
+    };
+    // Mark as orchestrator to prevent nesting
+    Object.defineProperty(orchestratorAgent, ORCHESTRATOR_MARKER, {
+        value: true,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return orchestratorAgent;
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/core/orchestrator.js.map

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

package/dist/core/response-format.d.ts

@@ -0,0 +1,44 @@
+import type OpenAI from 'openai';
+import type { ZodType, ZodError } from 'zod';
+import type { ResponseFormatConfig } from '../types/config.js';
+/**
+ * Result of response validation.
+ */
+export type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: ZodError;
+    rawResponse: string;
+};
+/**
+ * Converts SDK ResponseFormatConfig to OpenAI API response_format parameter.
+ */
+export declare function buildResponseFormat(config?: ResponseFormatConfig): OpenAI.Chat.Completions.ChatCompletionCreateParams['response_format'];
+/**
+ * Parses and validates a JSON response against a Zod schema.
+ *
+ * @param response - The raw response string from the API
+ * @param schema - The Zod schema to validate against
+ * @returns ValidationResult with either parsed data or error details
+ */
+export declare function validateResponse<T>(response: string, schema: ZodType<T>): ValidationResult<T>;
+/**
+ * Formats a validation error for inclusion in a retry prompt.
+ */
+export declare function formatValidationError(error: ZodError): string;
+/**
+ * Checks if a response format config requires JSON parsing/validation.
+ */
+export declare function requiresJsonParsing(config?: ResponseFormatConfig): boolean;
+/**
+ * Checks if a response format config has a schema for validation.
+ */
+export declare function hasSchema(config?: ResponseFormatConfig): config is {
+    type: 'json_schema';
+    schema: ZodType<unknown>;
+    name?: string;
+    strict?: boolean;
+};
+//# sourceMappingURL=response-format.d.ts.map

package/dist/core/response-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-format.d.ts","sourceRoot":"","sources":["../../src/core/response-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAE7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC1B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,0BAA0B,CAAC,iBAAiB,CAAC,CAoCvE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CA8C7F;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAO7D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAE1E;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,MAAM,CAAC,EAAE,oBAAoB,GAC5B,MAAM,IAAI;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAE9F"}

package/dist/core/response-format.js

@@ -0,0 +1,107 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+/**
+ * Converts SDK ResponseFormatConfig to OpenAI API response_format parameter.
+ */
+export function buildResponseFormat(config) {
+    if (!config) {
+        return undefined;
+    }
+    switch (config.type) {
+        case 'text':
+            return { type: 'text' };
+        case 'json_object':
+            return { type: 'json_object' };
+        case 'json_schema': {
+            const jsonSchema = zodToJsonSchema(config.schema, {
+                $refStrategy: 'none',
+                target: 'openApi3',
+            });
+            // Remove $schema property as OpenAI doesn't accept it
+            if ('$schema' in jsonSchema) {
+                delete jsonSchema['$schema'];
+            }
+            return {
+                type: 'json_schema',
+                json_schema: {
+                    name: config.name ?? 'response',
+                    schema: jsonSchema,
+                    strict: config.strict ?? true,
+                },
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Parses and validates a JSON response against a Zod schema.
+ *
+ * @param response - The raw response string from the API
+ * @param schema - The Zod schema to validate against
+ * @returns ValidationResult with either parsed data or error details
+ */
+export function validateResponse(response, schema) {
+    let parsed;
+    try {
+        parsed = JSON.parse(response);
+    }
+    catch {
+        // Return a synthetic ZodError for JSON parse failures
+        const issues = [
+            {
+                code: 'custom',
+                path: [],
+                message: `Invalid JSON: ${response.slice(0, 100)}${response.length > 100 ? '...' : ''}`,
+            },
+        ];
+        const parseError = {
+            issues,
+            name: 'ZodError',
+            get errors() {
+                return issues;
+            },
+            format: () => ({}),
+            flatten: () => ({ formErrors: [], fieldErrors: {} }),
+            isEmpty: false,
+            addIssue: () => { },
+            addIssues: () => { },
+        };
+        return {
+            success: false,
+            error: parseError,
+            rawResponse: response,
+        };
+    }
+    const result = schema.safeParse(parsed);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return {
+        success: false,
+        error: result.error,
+        rawResponse: response,
+    };
+}
+/**
+ * Formats a validation error for inclusion in a retry prompt.
+ */
+export function formatValidationError(error) {
+    const issues = error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? `at "${issue.path.join('.')}"` : 'at root';
+        return `- ${path}: ${issue.message}`;
+    });
+    return `The previous response did not match the required schema:\n${issues.join('\n')}\n\nPlease provide a valid response.`;
+}
+/**
+ * Checks if a response format config requires JSON parsing/validation.
+ */
+export function requiresJsonParsing(config) {
+    return config?.type === 'json_object' || config?.type === 'json_schema';
+}
+/**
+ * Checks if a response format config has a schema for validation.
+ */
+export function hasSchema(config) {
+    return config?.type === 'json_schema';
+}
+//# sourceMappingURL=response-format.js.map

package/dist/core/response-format.js.map

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

package/dist/core/retry.d.ts

@@ -0,0 +1,76 @@
+import type { RetryConfig } from '../types/index.js';
+/**
+ * Information about a retry attempt passed to callbacks.
+ */
+export interface RetryAttemptInfo {
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Maximum number of attempts configured */
+    maxAttempts: number;
+    /** The error that triggered the retry */
+    error: Error;
+    /** Delay in milliseconds before the next attempt */
+    delayMs: number;
+}
+/**
+ * Options for the executeWithRetry function.
+ */
+export interface ExecuteWithRetryOptions {
+    /** Retry configuration */
+    config?: RetryConfig;
+    /** AbortSignal to cancel the operation */
+    abortSignal?: AbortSignal;
+    /** Callback invoked before each retry attempt */
+    onRetry?: (info: RetryAttemptInfo) => void;
+    /** Custom function to determine if an error is retryable */
+    isRetryable?: (error: Error) => boolean;
+}
+/**
+ * Resolves retry configuration with defaults.
+ */
+export declare function resolveRetryConfig(config?: RetryConfig): Required<RetryConfig>;
+/**
+ * Calculates the delay for a retry attempt using exponential backoff with jitter.
+ * @param attempt - The attempt number (1-based, so first retry is attempt 2)
+ * @param config - Resolved retry configuration
+ * @returns Delay in milliseconds
+ */
+export declare function calculateRetryDelay(attempt: number, config: Required<RetryConfig>): number;
+/**
+ * Extracts HTTP status code from an error if available.
+ * Works with OpenAI SDK errors and standard HTTP errors.
+ */
+export declare function getErrorStatusCode(error: Error): number | undefined;
+/**
+ * Extracts Retry-After header value from an error if available.
+ * Returns the delay in milliseconds, or undefined if not present.
+ */
+export declare function getRetryAfterMs(error: Error): number | undefined;
+/**
+ * Sleeps for a specified duration, respecting abort signals.
+ * @param ms - Duration in milliseconds
+ * @param abortSignal - Optional abort signal to cancel the sleep
+ * @returns Promise that resolves after the delay or rejects if aborted
+ */
+export declare function sleep(ms: number, abortSignal?: AbortSignal): Promise<void>;
+/**
+ * Executes an async function with retry logic using exponential backoff.
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry options including config, abort signal, and callbacks
+ * @returns The result of the function if successful
+ * @throws The last error if all retry attempts fail
+ *
+ * @example
+ * ```typescript
+ * const result = await executeWithRetry(
+ *   () => apiCall(),
+ *   {
+ *     config: { maxAttempts: 3, baseDelayMs: 1000 },
+ *     onRetry: (info) => console.log(`Retry ${info.attempt}/${info.maxAttempts}`),
+ *   }
+ * );
+ * ```
+ */
+export declare function executeWithRetry<T>(fn: () => Promise<T>, options?: ExecuteWithRetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/core/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/core/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AASrD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,KAAK,EAAE,KAAK,CAAC;IACb,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,0BAA0B;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,iDAAiD;IACjD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC3C,4DAA4D;IAC5D,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CACzC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC,CAO9E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,MAAM,CAW1F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAiBnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAwBhE;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,CAAC,CAAC,CAkDZ"}