@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.334

package/packages/typescript/src/utils/prompt-batcher/dispatcher.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedSection } from "../../types/prompt-batcher";
+import type { IAgentRuntime } from "../../types/runtime";
+import { type DispatchOutcome, type PromptDispatcherSettings } from "./shared";
+export declare class PromptDispatcher {
+    private readonly settings;
+    constructor(settings: PromptDispatcherSettings);
+    dispatch(resolved: ResolvedSection[], runtime: IAgentRuntime): Promise<DispatchOutcome>;
+    private _buildCallPlans;
+    private _splitByModelPreference;
+    private _packingTokenLimit;
+    private _priorityRank;
+    private _buildPrompt;
+    private _mergeExecOptions;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/packages/typescript/src/utils/prompt-batcher/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../../../../../typescript/src/utils/prompt-batcher/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAIN,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAG7B,MAAM,UAAU,CAAC;AAElB,qBAAa,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,wBAAwB;IAEzD,QAAQ,CACb,QAAQ,EAAE,eAAe,EAAE,EAC3B,OAAO,EAAE,aAAa,GACpB,OAAO,CAAC,eAAe,CAAC;IA0F3B,OAAO,CAAC,eAAe;IAmFvB,OAAO,CAAC,uBAAuB;IAwC/B,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,YAAY;IAiCpB,OAAO,CAAC,iBAAiB;CAoCzB"}

package/packages/typescript/src/utils/prompt-batcher/dispatcher.js

@@ -0,0 +1,230 @@
+import { createMinimalState, Semaphore, sanitizeIdentifier, } from "./shared";
+export class PromptDispatcher {
+    settings;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    async dispatch(resolved, runtime) {
+        const results = new Map();
+        const calls = [];
+        const semaphore = new Semaphore(this.settings.maxParallelCalls);
+        const callPlans = this._buildCallPlans(resolved);
+        await Promise.all(callPlans.map(async (callPlan) => {
+            await semaphore.acquire();
+            const startedAt = Date.now();
+            try {
+                const prompt = this._buildPrompt(callPlan);
+                const schema = callPlan.sections.flatMap((resolvedSection) => {
+                    const prefix = sanitizeIdentifier(resolvedSection.section.id);
+                    return resolvedSection.section.schema.map((row) => ({
+                        ...row,
+                        field: `${prefix}__${row.field}`,
+                    }));
+                });
+                const mergedExecOptions = this._mergeExecOptions(callPlan.sections.map((item) => item.execOptions));
+                const state = createMinimalState(callPlan.sections
+                    .map((item) => `[${item.section.id}]\n${item.resolvedContext || "[context unavailable]"}`)
+                    .join("\n\n"));
+                const modelSize = callPlan.model;
+                const response = await runtime.dynamicPromptExecFromState({
+                    state,
+                    params: {
+                        prompt,
+                        ...mergedExecOptions,
+                    },
+                    schema,
+                    options: {
+                        modelSize,
+                        key: `prompt-batcher:${callPlan.sections.map((item) => item.section.id).join(",")}`,
+                    },
+                });
+                const durationMs = Date.now() - startedAt;
+                if (!response) {
+                    calls.push({
+                        model: modelSize,
+                        sectionIds: callPlan.sections.map((item) => item.section.id),
+                        estimatedTokens: callPlan.totalEstimatedTokens,
+                        durationMs,
+                        success: false,
+                        retried: false,
+                        fallbackUsed: callPlan.sections.map((item) => item.section.id),
+                    });
+                    return;
+                }
+                for (const section of callPlan.sections) {
+                    const prefix = `${sanitizeIdentifier(section.section.id)}__`;
+                    const stripped = {};
+                    for (const [key, value] of Object.entries(response)) {
+                        if (key.startsWith(prefix)) {
+                            stripped[key.slice(prefix.length)] = value;
+                        }
+                    }
+                    results.set(section.section.id, stripped);
+                }
+                calls.push({
+                    model: modelSize,
+                    sectionIds: callPlan.sections.map((item) => item.section.id),
+                    estimatedTokens: callPlan.totalEstimatedTokens,
+                    durationMs,
+                    success: true,
+                    retried: false,
+                    fallbackUsed: [],
+                });
+            }
+            finally {
+                semaphore.release();
+            }
+        }));
+        return { results, calls };
+    }
+    _buildCallPlans(resolved) {
+        const affinityGroups = new Map();
+        for (const section of resolved) {
+            const group = affinityGroups.get(section.affinityKey) ?? [];
+            group.push(section);
+            affinityGroups.set(section.affinityKey, group);
+        }
+        const callPlans = [];
+        for (const sections of affinityGroups.values()) {
+            for (const priority of ["immediate", "normal", "background"]) {
+                const prioritized = sections.filter((section) => section.priority === priority);
+                if (prioritized.length === 0) {
+                    continue;
+                }
+                for (const modelGroup of this._splitByModelPreference(prioritized)) {
+                    const isolated = modelGroup.sections.filter((item) => item.isolated);
+                    const packable = modelGroup.sections
+                        .filter((item) => !item.isolated)
+                        .sort((a, b) => b.estimatedTokens - a.estimatedTokens);
+                    for (const item of isolated) {
+                        callPlans.push({
+                            sections: [item],
+                            model: modelGroup.model,
+                            totalEstimatedTokens: item.estimatedTokens,
+                            priority,
+                        });
+                    }
+                    const tokenLimit = this._packingTokenLimit(priority);
+                    let current = [];
+                    let tokenCount = 0;
+                    let fieldCount = 0;
+                    for (const item of packable) {
+                        const nextTokens = tokenCount + item.estimatedTokens;
+                        const nextFieldCount = fieldCount + item.schemaFieldCount;
+                        const exceedsTokens = nextTokens > tokenLimit;
+                        const exceedsFields = nextFieldCount > this.settings.maxSectionsPerCall;
+                        const exceedsPromptSafety = nextTokens > 8192;
+                        if (current.length > 0 &&
+                            (exceedsTokens || exceedsFields || exceedsPromptSafety)) {
+                            callPlans.push({
+                                sections: current,
+                                model: modelGroup.model,
+                                totalEstimatedTokens: tokenCount,
+                                priority,
+                            });
+                            current = [];
+                            tokenCount = 0;
+                            fieldCount = 0;
+                        }
+                        current.push(item);
+                        tokenCount += item.estimatedTokens;
+                        fieldCount += item.schemaFieldCount;
+                    }
+                    if (current.length > 0) {
+                        callPlans.push({
+                            sections: current,
+                            model: modelGroup.model,
+                            totalEstimatedTokens: tokenCount,
+                            priority,
+                        });
+                    }
+                }
+            }
+        }
+        return callPlans.sort((a, b) => this._priorityRank(a.priority) - this._priorityRank(b.priority));
+    }
+    _splitByModelPreference(sections) {
+        const small = sections.filter((section) => section.preferredModel === "small");
+        const large = sections.filter((section) => section.preferredModel === "large");
+        if (small.length === 0) {
+            return [{ model: "large", sections: large }];
+        }
+        if (large.length === 0) {
+            return [{ model: "small", sections: small }];
+        }
+        const normalizedSeparation = Math.max(0, Math.min(1, this.settings.modelSeparation));
+        const total = small.length + large.length;
+        const smallRatio = small.length / total;
+        const promoteSmallIntoLarge = smallRatio < 1 - normalizedSeparation;
+        if (promoteSmallIntoLarge) {
+            return [
+                {
+                    model: "large",
+                    sections: [...large, ...small],
+                },
+            ];
+        }
+        return [
+            { model: "large", sections: large },
+            { model: "small", sections: small },
+        ];
+    }
+    _packingTokenLimit(priority) {
+        const density = Math.max(0, Math.min(1, this.settings.packingDensity));
+        const densityFloor = 0.35 + density * 0.65;
+        const priorityMultiplier = priority === "immediate" ? 0.65 : priority === "normal" ? 0.85 : 1;
+        return Math.max(512, Math.floor(this.settings.maxTokensPerCall * densityFloor * priorityMultiplier));
+    }
+    _priorityRank(priority) {
+        return priority === "immediate" ? 0 : priority === "normal" ? 1 : 2;
+    }
+    _buildPrompt(callPlan) {
+        const sectionBlocks = callPlan.sections.map((resolvedSection, index) => {
+            const fieldList = resolvedSection.section.schema
+                .map((row) => {
+                const prefix = sanitizeIdentifier(resolvedSection.section.id);
+                const namespacedField = `${prefix}__${row.field}`;
+                return `- ${namespacedField}: ${row.description}${row.required ? " (required)" : ""}`;
+            })
+                .join("\n");
+            return [
+                `SECTION ${index + 1}: ${resolvedSection.section.id}`,
+                resolvedSection.section.preamble
+                    ? `Instructions:\n${resolvedSection.section.preamble}`
+                    : "",
+                `Context:\n${resolvedSection.resolvedContext || "[context unavailable]"}`,
+                `Output fields for this section:\n${fieldList}`,
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+        });
+        return [
+            "You are answering multiple independent structured sections in one response.",
+            "Read each section carefully.",
+            "Use only the context provided for that section.",
+            "Fill every requested field exactly once.",
+            "Do not mix facts between sections.",
+            "",
+            sectionBlocks.join("\n\n====================\n\n"),
+        ].join("\n");
+    }
+    _mergeExecOptions(options) {
+        const temperatures = options
+            .map((item) => item?.temperature)
+            .filter((item) => typeof item === "number");
+        const maxTokens = options
+            .map((item) => item?.maxTokens)
+            .filter((item) => typeof item === "number");
+        const stopSequences = new Set();
+        for (const option of options) {
+            for (const stop of option?.stopSequences ?? []) {
+                stopSequences.add(stop);
+            }
+        }
+        return {
+            temperature: temperatures.length > 0 ? Math.min(...temperatures) : undefined,
+            maxTokens: maxTokens.length > 0 ? Math.max(...maxTokens) : undefined,
+            stopSequences: stopSequences.size > 0 ? Array.from(stopSequences) : undefined,
+        };
+    }
+}

package/packages/typescript/src/utils/prompt-batcher/shared.d.ts

@@ -0,0 +1,66 @@
+import type { Memory } from "../../types/memory";
+import type { BatcherResult, PromptSection, ResolvedSection } from "../../types/prompt-batcher";
+import type { IAgentRuntime } from "../../types/runtime";
+import type { SchemaRow, State } from "../../types/state";
+export type Deferred<T> = {
+    resolve: (value: T) => void;
+    reject: (reason?: unknown) => void;
+};
+export type CacheEntry = {
+    fields: Record<string, unknown>;
+    expiresAt: number;
+};
+/** Tracks a section's promise. resolved guards so we never resolve and reject the same deferred. */
+export type PendingResult = {
+    deferred: Deferred<BatcherResult | null>;
+    resolved: boolean;
+};
+export type DispatchCallMeta = {
+    model: "small" | "large";
+    sectionIds: string[];
+    estimatedTokens: number;
+    durationMs: number;
+    success: boolean;
+    retried: boolean;
+    fallbackUsed: string[];
+};
+export type DispatchOutcome = {
+    results: Map<string, Record<string, unknown>>;
+    calls: DispatchCallMeta[];
+};
+export type CallPlan = {
+    sections: ResolvedSection[];
+    model: "small" | "large";
+    totalEstimatedTokens: number;
+    priority: "background" | "normal" | "immediate";
+};
+export type PromptDispatcherSettings = {
+    packingDensity: number;
+    maxTokensPerCall: number;
+    maxParallelCalls: number;
+    modelSeparation: number;
+    maxSectionsPerCall: number;
+};
+export type PromptBatcherSettings = {
+    batchSize: number;
+    maxDrainIntervalMs: number;
+    maxSectionsPerCall: number;
+    packingDensity: number;
+    maxTokensPerCall: number;
+    maxParallelCalls: number;
+    modelSeparation: number;
+};
+/**
+ * Re-export so dispatcher keeps `import { Semaphore } from "./shared"`.
+ * Single `Semaphore` implementation under `utils/batch-queue` (see `batch-queue.ts` header).
+ */
+export { Semaphore } from "../batch-queue/semaphore.js";
+export declare function sanitizeIdentifier(value: string): string;
+export declare function clampRetryCount(value: number | undefined): number;
+export declare function createMinimalState(context: string): State;
+export declare function buildCharacterContext(runtime: IAgentRuntime): string;
+export declare function getSourceMessageId(message: Memory): string;
+export declare function pickFields(fields: Record<string, unknown> | null | undefined, schema: SchemaRow[]): Record<string, unknown>;
+export declare function hasMeaningfulSectionDrift(existing: PromptSection, incoming: PromptSection): boolean;
+export declare function rollingAverage(current: number, count: number, nextValue: number): number;
+//# sourceMappingURL=shared.d.ts.map

package/packages/typescript/src/utils/prompt-batcher/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../../../../../typescript/src/utils/prompt-batcher/shared.ts"],"names":[],"mappings":"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"}

package/packages/typescript/src/utils/prompt-batcher/shared.js

@@ -0,0 +1,101 @@
+import { toMultilineText } from "../text-normalize";
+/**
+ * Re-export so dispatcher keeps `import { Semaphore } from "./shared"`.
+ * Single `Semaphore` implementation under `utils/batch-queue` (see `batch-queue.ts` header).
+ */
+export { Semaphore } from "../batch-queue/semaphore.js";
+export function sanitizeIdentifier(value) {
+    const normalized = value.replace(/[^a-zA-Z0-9_]/g, "_");
+    if (/^[a-zA-Z_]/.test(normalized)) {
+        return normalized;
+    }
+    return `section_${normalized}`;
+}
+export function clampRetryCount(value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        return 0;
+    }
+    return Math.max(0, Math.min(2, Math.floor(value)));
+}
+export function createMinimalState(context) {
+    return {
+        text: context,
+        values: {
+            batcherContext: context,
+        },
+        data: {},
+    };
+}
+export function buildCharacterContext(runtime) {
+    const topics = toMultilineText(runtime.character.topics);
+    const bio = toMultilineText(runtime.character.bio);
+    const style = toMultilineText(runtime.character.style);
+    const knowledge = toMultilineText(runtime.character.knowledge);
+    return [
+        `Agent Name: ${runtime.character.name ?? "Unknown"}`,
+        bio ? `Bio:\n${bio}` : "",
+        style ? `Style:\n${style}` : "",
+        topics ? `Topics:\n${topics}` : "",
+        knowledge ? `Knowledge:\n${knowledge}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+}
+export function getSourceMessageId(message) {
+    const metadata = (message.metadata ?? {});
+    const content = (message.content ?? {});
+    const discordId = metadata.discordMessageId;
+    if (typeof discordId === "string" && discordId) {
+        return `discord:${discordId}`;
+    }
+    const telegramId = content.messageId;
+    if (telegramId != null) {
+        return `telegram:${String(telegramId)}`;
+    }
+    const slack = metadata.slack;
+    if (slack &&
+        typeof slack === "object" &&
+        "messageTs" in slack) {
+        return `slack:${String(slack.messageTs)}`;
+    }
+    return `internal:${message.id}`;
+}
+export function pickFields(fields, schema) {
+    const picked = {};
+    if (!fields) {
+        return picked;
+    }
+    for (const row of schema) {
+        if (row.field in fields) {
+            picked[row.field] = fields[row.field];
+        }
+    }
+    return picked;
+}
+export function hasMeaningfulSectionDrift(existing, incoming) {
+    const comparableExisting = {
+        frequency: existing.frequency,
+        providers: existing.providers,
+        preamble: existing.preamble,
+        schema: existing.schema,
+        priority: existing.priority,
+        model: existing.model,
+        affinityKey: existing.affinityKey,
+    };
+    const comparableIncoming = {
+        frequency: incoming.frequency,
+        providers: incoming.providers,
+        preamble: incoming.preamble,
+        schema: incoming.schema,
+        priority: incoming.priority,
+        model: incoming.model,
+        affinityKey: incoming.affinityKey,
+    };
+    return (JSON.stringify(comparableExisting) !== JSON.stringify(comparableIncoming));
+}
+export function rollingAverage(current, count, nextValue) {
+    if (count <= 1) {
+        return nextValue;
+    }
+    return current + (nextValue - current) / count;
+}

package/packages/typescript/src/utils/prompt-batcher.d.ts

@@ -0,0 +1,5 @@
+export { BatcherDisposedError, type BatcherStats, type ContextResolver, type DrainLog, type DrainMeta, type PreCallbackHandler, type PromptSection, type ResolvedSection, type SectionFrequency, } from "../types/prompt-batcher";
+export { PromptBatcher } from "./prompt-batcher/batcher.js";
+export { PromptDispatcher } from "./prompt-batcher/dispatcher.js";
+export { pickFields } from "./prompt-batcher/shared.js";
+//# sourceMappingURL=prompt-batcher.d.ts.map

package/packages/typescript/src/utils/prompt-batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-batcher.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/prompt-batcher.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC"}

package/packages/typescript/src/utils/prompt-batcher.js

@@ -0,0 +1,4 @@
+export { BatcherDisposedError, } from "../types/prompt-batcher";
+export { PromptBatcher } from "./prompt-batcher/batcher.js";
+export { PromptDispatcher } from "./prompt-batcher/dispatcher.js";
+export { pickFields } from "./prompt-batcher/shared.js";

package/packages/typescript/src/utils/retry.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Retry and backoff utilities for robust async operations.
+ *
+ * Provides:
+ * - Exponential backoff with jitter
+ * - Configurable retry logic
+ * - Abort signal support
+ *
+ * @module utils/retry
+ */
+/**
+ * Sleep for a specified duration.
+ *
+ * @param ms - Milliseconds to sleep
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Sleep with abort signal support.
+ *
+ * @param ms - Milliseconds to sleep
+ * @param abortSignal - Optional signal to abort sleep
+ * @throws If aborted
+ */
+export declare function sleepWithAbort(ms: number, abortSignal?: AbortSignal): Promise<void>;
+/**
+ * Configuration for exponential backoff.
+ */
+export type BackoffPolicy = {
+    /** Initial delay in milliseconds */
+    initialMs: number;
+    /** Maximum delay in milliseconds */
+    maxMs: number;
+    /** Multiplier for each attempt */
+    factor: number;
+    /** Random jitter factor (0-1) */
+    jitter: number;
+};
+/**
+ * Compute the backoff delay for a given attempt.
+ *
+ * @param policy - Backoff policy configuration
+ * @param attempt - Attempt number (1-based)
+ * @returns Delay in milliseconds
+ */
+export declare function computeBackoff(policy: BackoffPolicy, attempt: number): number;
+/**
+ * Basic retry configuration.
+ */
+export type RetryConfig = {
+    /** Maximum number of attempts */
+    attempts?: number;
+    /** Minimum delay between retries in ms */
+    minDelayMs?: number;
+    /** Maximum delay between retries in ms */
+    maxDelayMs?: number;
+    /** Random jitter factor (0-1) */
+    jitter?: number;
+};
+/**
+ * Information about a retry attempt.
+ */
+export type RetryInfo = {
+    /** Current attempt number */
+    attempt: number;
+    /** Maximum attempts configured */
+    maxAttempts: number;
+    /** Delay before this retry in ms */
+    delayMs: number;
+    /** The error that triggered the retry */
+    err: unknown;
+    /** Optional label for logging */
+    label?: string;
+};
+/**
+ * Full retry options including callbacks.
+ */
+export type RetryOptions = RetryConfig & {
+    /** Label for logging/debugging */
+    label?: string;
+    /** Custom function to determine if error should trigger retry */
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+    /** Custom function to extract retry-after from error */
+    retryAfterMs?: (err: unknown) => number | undefined;
+    /** Callback called before each retry */
+    onRetry?: (info: RetryInfo) => void;
+};
+/**
+ * Resolve retry configuration with defaults.
+ *
+ * @param defaults - Default configuration
+ * @param overrides - Override values
+ * @returns Fully resolved configuration
+ */
+export declare function resolveRetryConfig(defaults?: Required<RetryConfig>, overrides?: RetryConfig): Required<RetryConfig>;
+/**
+ * Execute an async function with automatic retries.
+ *
+ * Supports two calling styles:
+ * 1. Simple: `retryAsync(fn, attempts, initialDelayMs)`
+ * 2. Full options: `retryAsync(fn, { attempts, minDelayMs, ... })`
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const result = await retryAsync(() => fetch(url), 3, 1000);
+ *
+ * // Full options
+ * const result = await retryAsync(
+ *   () => fetch(url),
+ *   {
+ *     attempts: 5,
+ *     minDelayMs: 500,
+ *     maxDelayMs: 30000,
+ *     jitter: 0.2,
+ *     shouldRetry: (err) => isRetryable(err),
+ *     onRetry: ({ attempt, delayMs }) => log(`Retry ${attempt} in ${delayMs}ms`)
+ *   }
+ * );
+ * ```
+ *
+ * @param fn - Async function to execute
+ * @param attemptsOrOptions - Number of attempts or full options
+ * @param initialDelayMs - Initial delay (only used with simple calling style)
+ * @returns Promise resolving to function result
+ * @throws Last error after all retries exhausted
+ */
+export declare function retryAsync<T>(fn: () => Promise<T>, attemptsOrOptions?: number | RetryOptions, initialDelayMs?: number): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/packages/typescript/src/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CACnC,EAAE,EAAE,MAAM,EACV,WAAW,CAAC,EAAE,WAAW,GACvB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAMD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC3B,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAI7E;AAMD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACvB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,GAAG,EAAE,OAAO,CAAC;IACb,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG;IACxC,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACzD,wDAAwD;IACxD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACpD,wCAAwC;IACxC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;CACpC,CAAC;AA2BF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,GAAE,QAAQ,CAAC,WAAW,CAAwB,EACtD,SAAS,CAAC,EAAE,WAAW,GACrB,QAAQ,CAAC,WAAW,CAAC,CAevB;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,UAAU,CAAC,CAAC,EACjC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,iBAAiB,GAAE,MAAM,GAAG,YAAgB,EAC5C,cAAc,SAAM,GAClB,OAAO,CAAC,CAAC,CAAC,CA+DZ"}