attocode 0.2.3 → 0.2.5

package/dist/src/integrations/utilities/react.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Lesson 25: ReAct Pattern Integration
+ *
+ * Integrates the ReAct (Reasoning + Acting) pattern (from Lesson 18)
+ * into the production agent. Enables explicit reasoning traces
+ * with thought-action-observation loops.
+ */
+import type { LLMProvider, ToolDefinition } from '../../types.js';
+/**
+ * ReAct configuration.
+ */
+export interface ReActConfig {
+    /** Maximum reasoning steps */
+    maxSteps: number;
+    /** Stop on first valid answer */
+    stopOnAnswer: boolean;
+    /** Include reasoning in final output */
+    includeReasoning: boolean;
+    /** Custom patterns for parsing */
+    patterns?: ReActPatterns;
+}
+/**
+ * Patterns for parsing ReAct output.
+ */
+export interface ReActPatterns {
+    thought: RegExp;
+    action: RegExp;
+    actionInput: RegExp;
+    observation: RegExp;
+    finalAnswer: RegExp;
+}
+/**
+ * Single ReAct step.
+ */
+export interface ReActStep {
+    stepNumber: number;
+    thought: string;
+    action?: ReActAction;
+    observation?: string;
+    isFinal: boolean;
+}
+/**
+ * ReAct action (tool call).
+ */
+export interface ReActAction {
+    tool: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Full ReAct trace.
+ */
+export interface ReActTrace {
+    steps: ReActStep[];
+    finalAnswer?: string;
+    success: boolean;
+    totalSteps: number;
+}
+/**
+ * ReAct events.
+ */
+export type ReActEvent = {
+    type: 'react.start';
+    task: string;
+} | {
+    type: 'react.thought';
+    step: number;
+    thought: string;
+} | {
+    type: 'react.action';
+    step: number;
+    action: ReActAction;
+} | {
+    type: 'react.observation';
+    step: number;
+    observation: string;
+} | {
+    type: 'react.answer';
+    answer: string;
+} | {
+    type: 'react.complete';
+    trace: ReActTrace;
+};
+export type ReActEventListener = (event: ReActEvent) => void;
+/**
+ * ReActManager implements the ReAct reasoning pattern.
+ */
+export declare class ReActManager {
+    private provider;
+    private tools;
+    private config;
+    private patterns;
+    private listeners;
+    constructor(provider: LLMProvider, tools: ToolDefinition[], config?: Partial<ReActConfig>);
+    /**
+     * Run a task using the ReAct pattern.
+     */
+    run(task: string): Promise<ReActTrace>;
+    /**
+     * Subscribe to events.
+     */
+    on(listener: ReActEventListener): () => void;
+    /**
+     * Get the reasoning trace as a formatted string.
+     */
+    formatTrace(trace: ReActTrace): string;
+    private emit;
+    private buildSystemPrompt;
+    private parseOutput;
+    private parseActionInput;
+    private executeAction;
+    private formatObservation;
+}
+/**
+ * Create a ReAct manager.
+ */
+export declare function createReActManager(provider: LLMProvider, tools: ToolDefinition[], config?: Partial<ReActConfig>): ReActManager;
+/**
+ * Compare ReAct trace with standard agent execution.
+ */
+export interface ReActComparison {
+    reactTrace: ReActTrace;
+    standardResult: string;
+    reactSteps: number;
+    reactHasExplicitReasoning: boolean;
+    reasoningSteps: string[];
+}
+/**
+ * Extract all thoughts from a trace.
+ */
+export declare function extractThoughts(trace: ReActTrace): string[];
+/**
+ * Extract all actions from a trace.
+ */
+export declare function extractActions(trace: ReActTrace): ReActAction[];
+/**
+ * Check if trace shows coherent reasoning.
+ */
+export declare function hasCoherentReasoning(trace: ReActTrace): boolean;
+//# sourceMappingURL=react.d.ts.map

package/dist/src/integrations/utilities/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../../../src/integrations/utilities/react.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAqB,MAAM,gBAAgB,CAAC;AAMrF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,YAAY,EAAE,OAAO,CAAC;IACtB,wCAAwC;IACxC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAyC7D;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,SAAS,CAA4B;gBAG3C,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM;IAanC;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAmF5C;;OAEG;IACH,EAAE,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAQ5C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IAmCtC,OAAO,CAAC,IAAI;IAUZ,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,gBAAgB;YASV,aAAa;IAe3B,OAAO,CAAC,iBAAiB;CAe1B;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,YAAY,CAEd;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,UAAU,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB,EAAE,OAAO,CAAC;IACnC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,CAI3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,EAAE,CAI/D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAa/D"}

package/dist/src/integrations/utilities/react.js

@@ -0,0 +1,273 @@
+/**
+ * Lesson 25: ReAct Pattern Integration
+ *
+ * Integrates the ReAct (Reasoning + Acting) pattern (from Lesson 18)
+ * into the production agent. Enables explicit reasoning traces
+ * with thought-action-observation loops.
+ */
+// =============================================================================
+// DEFAULT PATTERNS
+// =============================================================================
+const DEFAULT_PATTERNS = {
+    thought: /Thought:\s*(.+?)(?=Action:|Final Answer:|$)/is,
+    action: /Action:\s*(\w+)/i,
+    actionInput: /Action Input:\s*(.+?)(?=Thought:|Observation:|Final Answer:|$)/is,
+    observation: /Observation:\s*(.+?)(?=Thought:|Action:|Final Answer:|$)/is,
+    finalAnswer: /Final Answer:\s*(.+?)$/is,
+};
+const REACT_SYSTEM_PROMPT = `You are a helpful AI assistant that uses the ReAct (Reasoning + Acting) framework.
+
+For each step:
+1. Thought: Reason about what to do next
+2. Action: Choose a tool to use
+3. Action Input: Provide the input for the tool
+4. Observation: (This will be provided after tool execution)
+
+When you have enough information:
+Final Answer: Provide your final response
+
+Format your response exactly like this:
+Thought: I need to...
+Action: tool_name
+Action Input: {"param": "value"}
+
+Or when ready to answer:
+Thought: I now have enough information...
+Final Answer: The answer is...
+
+Available tools:
+{tools}`;
+// =============================================================================
+// REACT MANAGER
+// =============================================================================
+/**
+ * ReActManager implements the ReAct reasoning pattern.
+ */
+export class ReActManager {
+    provider;
+    tools;
+    config;
+    patterns;
+    listeners = [];
+    constructor(provider, tools, config = {}) {
+        this.provider = provider;
+        this.tools = new Map(tools.map(t => [t.name, t]));
+        this.config = {
+            maxSteps: config.maxSteps ?? 15,
+            stopOnAnswer: config.stopOnAnswer ?? true,
+            includeReasoning: config.includeReasoning ?? true,
+            patterns: config.patterns,
+        };
+        this.patterns = config.patterns ?? DEFAULT_PATTERNS;
+    }
+    /**
+     * Run a task using the ReAct pattern.
+     */
+    async run(task) {
+        this.emit({ type: 'react.start', task });
+        const trace = {
+            steps: [],
+            success: false,
+            totalSteps: 0,
+        };
+        const messages = [
+            { role: 'system', content: this.buildSystemPrompt() },
+            { role: 'user', content: task },
+        ];
+        for (let step = 1; step <= this.config.maxSteps; step++) {
+            // Get LLM response
+            const response = await this.provider.chat(messages);
+            const output = response.content;
+            // Parse the response
+            const parsed = this.parseOutput(output);
+            const reactStep = {
+                stepNumber: step,
+                thought: parsed.thought || 'No explicit thought',
+                isFinal: !!parsed.finalAnswer,
+            };
+            if (parsed.thought) {
+                this.emit({ type: 'react.thought', step, thought: parsed.thought });
+            }
+            // Check for final answer
+            if (parsed.finalAnswer) {
+                trace.finalAnswer = parsed.finalAnswer;
+                trace.success = true;
+                reactStep.isFinal = true;
+                trace.steps.push(reactStep);
+                this.emit({ type: 'react.answer', answer: parsed.finalAnswer });
+                break;
+            }
+            // Execute action if present
+            if (parsed.action && parsed.actionInput) {
+                const action = {
+                    tool: parsed.action,
+                    input: this.parseActionInput(parsed.actionInput),
+                };
+                reactStep.action = action;
+                this.emit({ type: 'react.action', step, action });
+                // Execute the tool
+                const observation = await this.executeAction(action);
+                reactStep.observation = observation;
+                this.emit({ type: 'react.observation', step, observation });
+                // Add to messages for next iteration
+                messages.push({ role: 'assistant', content: output }, { role: 'user', content: `Observation: ${observation}` });
+            }
+            else {
+                // No action, just add the response
+                messages.push({ role: 'assistant', content: output });
+            }
+            trace.steps.push(reactStep);
+            trace.totalSteps = step;
+        }
+        // If we exhausted steps without answer
+        if (!trace.finalAnswer) {
+            trace.success = false;
+            trace.finalAnswer = 'Maximum steps reached without a final answer.';
+        }
+        this.emit({ type: 'react.complete', trace });
+        return trace;
+    }
+    /**
+     * Subscribe to events.
+     */
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    /**
+     * Get the reasoning trace as a formatted string.
+     */
+    formatTrace(trace) {
+        const lines = [];
+        for (const step of trace.steps) {
+            lines.push(`=== Step ${step.stepNumber} ===`);
+            lines.push(`Thought: ${step.thought}`);
+            if (step.action) {
+                lines.push(`Action: ${step.action.tool}`);
+                lines.push(`Input: ${JSON.stringify(step.action.input)}`);
+            }
+            if (step.observation) {
+                lines.push(`Observation: ${step.observation}`);
+            }
+            if (step.isFinal) {
+                lines.push(`[Final Step]`);
+            }
+            lines.push('');
+        }
+        if (trace.finalAnswer) {
+            lines.push(`=== Final Answer ===`);
+            lines.push(trace.finalAnswer);
+        }
+        return lines.join('\n');
+    }
+    // -------------------------------------------------------------------------
+    // PRIVATE METHODS
+    // -------------------------------------------------------------------------
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+    buildSystemPrompt() {
+        const toolDescriptions = Array.from(this.tools.values())
+            .map(t => `- ${t.name}: ${t.description}`)
+            .join('\n');
+        return REACT_SYSTEM_PROMPT.replace('{tools}', toolDescriptions);
+    }
+    parseOutput(output) {
+        const thoughtMatch = output.match(this.patterns.thought);
+        const actionMatch = output.match(this.patterns.action);
+        const actionInputMatch = output.match(this.patterns.actionInput);
+        const finalAnswerMatch = output.match(this.patterns.finalAnswer);
+        return {
+            thought: thoughtMatch?.[1]?.trim(),
+            action: actionMatch?.[1]?.trim(),
+            actionInput: actionInputMatch?.[1]?.trim(),
+            finalAnswer: finalAnswerMatch?.[1]?.trim(),
+        };
+    }
+    parseActionInput(input) {
+        try {
+            return JSON.parse(input);
+        }
+        catch {
+            // If not JSON, wrap as a single argument
+            return { input };
+        }
+    }
+    async executeAction(action) {
+        const tool = this.tools.get(action.tool);
+        if (!tool) {
+            return `Error: Unknown tool "${action.tool}". Available tools: ${Array.from(this.tools.keys()).join(', ')}`;
+        }
+        try {
+            const result = await tool.execute(action.input);
+            return this.formatObservation(result);
+        }
+        catch (error) {
+            return `Error executing ${action.tool}: ${error instanceof Error ? error.message : 'Unknown error'}`;
+        }
+    }
+    formatObservation(result) {
+        if (typeof result === 'string') {
+            return result;
+        }
+        if (result === null || result === undefined) {
+            return 'No result';
+        }
+        try {
+            return JSON.stringify(result, null, 2);
+        }
+        catch {
+            return String(result);
+        }
+    }
+}
+// =============================================================================
+// FACTORY
+// =============================================================================
+/**
+ * Create a ReAct manager.
+ */
+export function createReActManager(provider, tools, config) {
+    return new ReActManager(provider, tools, config);
+}
+/**
+ * Extract all thoughts from a trace.
+ */
+export function extractThoughts(trace) {
+    return trace.steps
+        .map(s => s.thought)
+        .filter(t => t && t !== 'No explicit thought');
+}
+/**
+ * Extract all actions from a trace.
+ */
+export function extractActions(trace) {
+    return trace.steps
+        .filter(s => s.action)
+        .map(s => s.action);
+}
+/**
+ * Check if trace shows coherent reasoning.
+ */
+export function hasCoherentReasoning(trace) {
+    const thoughts = extractThoughts(trace);
+    // At least 2 thoughts for reasoning chain
+    if (thoughts.length < 2)
+        return false;
+    // Check for progression keywords
+    const progressionKeywords = ['then', 'next', 'now', 'based on', 'after', 'since'];
+    const hasProgression = thoughts.some(t => progressionKeywords.some(k => t.toLowerCase().includes(k)));
+    return hasProgression;
+}
+//# sourceMappingURL=react.js.map

package/dist/src/integrations/utilities/react.js.map

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

package/dist/src/integrations/utilities/retry.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Generic Retry Utility
+ *
+ * Provides configurable retry logic with exponential backoff for transient failures.
+ * Used by tools, MCP client, and other operations that may encounter temporary errors.
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   {
+ *     maxAttempts: 3,
+ *     baseDelayMs: 1000,
+ *     retryableErrors: ['ETIMEDOUT', 'ECONNRESET'],
+ *   }
+ * );
+ * ```
+ */
+/**
+ * Configuration for retry behavior.
+ * @see RetryConfig in config/base-types.ts for the shared base pattern.
+ */
+export interface RetryConfig {
+    /** Maximum number of attempts (including initial) */
+    maxAttempts: number;
+    /** Base delay between retries in milliseconds (default: 1000) */
+    baseDelayMs?: number;
+    /** Maximum delay between retries in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Add random jitter to delays (default: true) */
+    jitter?: boolean;
+    /** Error message patterns that are retryable */
+    retryableErrors?: string[];
+    /** Error codes that are retryable (e.g., 'ETIMEDOUT', 'ECONNRESET') */
+    retryableCodes?: string[];
+    /** Custom function to determine if error is retryable */
+    isRetryable?: (error: Error) => boolean;
+    /** Callback on each retry attempt */
+    onRetry?: (attempt: number, error: Error, delayMs: number) => void;
+    /** Callback when all attempts exhausted */
+    onExhausted?: (attempts: number, lastError: Error) => void;
+}
+/**
+ * Result of a retry operation.
+ */
+export interface RetryResult<T> {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The result value (if successful) */
+    value?: T;
+    /** The error (if failed) */
+    error?: Error;
+    /** Number of attempts made */
+    attempts: number;
+    /** Total time spent (including delays) */
+    totalTimeMs: number;
+}
+/**
+ * Default retryable error patterns.
+ * These are common transient errors that often resolve on retry.
+ */
+export declare const DEFAULT_RETRYABLE_ERRORS: string[];
+/**
+ * Default retryable error codes.
+ */
+export declare const DEFAULT_RETRYABLE_CODES: string[];
+/**
+ * Execute a function with retry logic.
+ *
+ * @param fn - The async function to execute
+ * @param config - Retry configuration
+ * @returns Promise resolving to the result or throwing the last error
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const data = await withRetry(() => fetchData(), { maxAttempts: 3 });
+ *
+ * // With custom config
+ * const data = await withRetry(
+ *   () => unreliableApi(),
+ *   {
+ *     maxAttempts: 5,
+ *     baseDelayMs: 500,
+ *     backoffMultiplier: 1.5,
+ *     retryableErrors: ['timeout'],
+ *     onRetry: (attempt, err) => console.log(`Retry ${attempt}: ${err.message}`),
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;
+/**
+ * Execute a function with retry and return detailed result.
+ *
+ * Unlike withRetry, this never throws - it returns a result object
+ * that indicates success or failure.
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetryResult(() => unreliableOp(), { maxAttempts: 3 });
+ * if (result.success) {
+ *   console.log('Got:', result.value);
+ * } else {
+ *   console.log('Failed after', result.attempts, 'attempts:', result.error);
+ * }
+ * ```
+ */
+export declare function withRetryResult<T>(fn: () => Promise<T>, config: RetryConfig): Promise<RetryResult<T>>;
+/**
+ * Retry config for tool execution.
+ * Conservative: 2 attempts, short delays.
+ */
+export declare const TOOL_RETRY_CONFIG: Omit<RetryConfig, 'maxAttempts'>;
+/**
+ * Retry config for MCP calls.
+ * More aggressive: 3 attempts, longer delays.
+ */
+export declare const MCP_RETRY_CONFIG: Omit<RetryConfig, 'maxAttempts'>;
+/**
+ * Retry config for file operations.
+ * Short delays, handles busy files.
+ */
+export declare const FILE_RETRY_CONFIG: Omit<RetryConfig, 'maxAttempts'>;
+/**
+ * Retry config for network operations.
+ * Standard exponential backoff.
+ */
+export declare const NETWORK_RETRY_CONFIG: Omit<RetryConfig, 'maxAttempts'>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/src/integrations/utilities/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../../src/integrations/utilities/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IAEpB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,yDAAyD;IACzD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IAExC,qCAAqC;IACrC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnE,2CAA2C;IAC3C,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,KAAK,IAAI,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IAEjB,uCAAuC;IACvC,KAAK,CAAC,EAAE,CAAC,CAAC;IAEV,4BAA4B;IAC5B,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,UAapC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,UAUnC,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CA0DZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAwBzB;AAgDD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,CAM9D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,CAM7D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,CAM9D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,IAAI,CAAC,WAAW,EAAE,aAAa,CAMjE,CAAC"}