@didim365/agent-cli-core 0.1.0

package/dist/src/providers/errors.js

@@ -0,0 +1,255 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Provider-independent error types for multi-LLM support.
+ *
+ * @see docs/ai_adapter/03-technical-design.md §3.7
+ */
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * Error type categories.
+ */
+export var LlmErrorType;
+(function (LlmErrorType) {
+    /** Authentication/authorization error */
+    LlmErrorType["AUTHENTICATION"] = "authentication";
+    /** Rate limit exceeded */
+    LlmErrorType["RATE_LIMIT"] = "rate_limit";
+    /** Invalid request parameters */
+    LlmErrorType["INVALID_REQUEST"] = "invalid_request";
+    /** Content blocked by safety filters */
+    LlmErrorType["CONTENT_FILTER"] = "content_filter";
+    /** Model not found or not available */
+    LlmErrorType["MODEL_NOT_FOUND"] = "model_not_found";
+    /** Provider not registered in registry */
+    LlmErrorType["PROVIDER_NOT_FOUND"] = "provider_not_found";
+    /** Model overloaded (Claude-specific, temporary capacity issue) */
+    LlmErrorType["MODEL_OVERLOADED"] = "model_overloaded";
+    /** Context length exceeded */
+    LlmErrorType["CONTEXT_LENGTH_EXCEEDED"] = "context_length_exceeded";
+    /** Network/connection error */
+    LlmErrorType["NETWORK"] = "network";
+    /** Timeout error */
+    LlmErrorType["TIMEOUT"] = "timeout";
+    /** Server error (5xx) */
+    LlmErrorType["SERVER_ERROR"] = "server_error";
+    /** Feature not supported by provider */
+    LlmErrorType["UNSUPPORTED_FEATURE"] = "unsupported_feature";
+    /** Validation error */
+    LlmErrorType["VALIDATION"] = "validation";
+    /** Unknown/unclassified error */
+    LlmErrorType["UNKNOWN"] = "unknown";
+})(LlmErrorType || (LlmErrorType = {}));
+/**
+ * Provider-independent error class.
+ */
+export class LlmError extends Error {
+    /** Error type for programmatic handling */
+    type;
+    /** Provider name (e.g., 'gemini', 'claude', 'openai') */
+    provider;
+    /** Original error code from provider */
+    code;
+    /** HTTP status code if applicable */
+    statusCode;
+    /** Whether this error is retryable */
+    isRetryable;
+    /** Suggested retry delay in milliseconds */
+    retryAfterMs;
+    /** Original error object */
+    cause;
+    constructor(type, message, options) {
+        super(message);
+        this.name = 'LlmError';
+        this.type = type;
+        this.provider = options?.provider;
+        this.code = options?.code;
+        this.statusCode = options?.statusCode;
+        this.isRetryable = options?.isRetryable ?? this.isDefaultRetryable(type);
+        this.retryAfterMs = options?.retryAfterMs;
+        this.cause = options?.cause;
+        // Maintains proper stack trace for where our error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, LlmError);
+        }
+    }
+    isDefaultRetryable(type) {
+        switch (type) {
+            case LlmErrorType.RATE_LIMIT:
+            case LlmErrorType.NETWORK:
+            case LlmErrorType.TIMEOUT:
+            case LlmErrorType.SERVER_ERROR:
+                return true;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Creates a JSON representation of the error.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            type: this.type,
+            message: this.message,
+            provider: this.provider,
+            code: this.code,
+            statusCode: this.statusCode,
+            isRetryable: this.isRetryable,
+            retryAfterMs: this.retryAfterMs,
+            stack: this.stack,
+        };
+    }
+}
+// ============================================================================
+// Specific Error Classes
+// ============================================================================
+/**
+ * Authentication error.
+ */
+export class AuthenticationError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.AUTHENTICATION, message, {
+            ...options,
+            isRetryable: false,
+        });
+        this.name = 'AuthenticationError';
+    }
+}
+/**
+ * Rate limit error.
+ */
+export class RateLimitError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.RATE_LIMIT, message, {
+            ...options,
+            isRetryable: true,
+        });
+        this.name = 'RateLimitError';
+    }
+}
+/**
+ * Content filter error.
+ */
+export class ContentFilterError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.CONTENT_FILTER, message, {
+            ...options,
+            isRetryable: false,
+        });
+        this.name = 'ContentFilterError';
+    }
+}
+/**
+ * Context length exceeded error.
+ */
+export class ContextLengthExceededError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.CONTEXT_LENGTH_EXCEEDED, message, {
+            ...options,
+            isRetryable: false,
+        });
+        this.name = 'ContextLengthExceededError';
+    }
+}
+/**
+ * Validation error.
+ */
+export class ValidationError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.VALIDATION, message, {
+            ...options,
+            isRetryable: false,
+        });
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Unsupported feature error.
+ */
+export class UnsupportedFeatureError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.UNSUPPORTED_FEATURE, message, {
+            ...options,
+            isRetryable: false,
+        });
+        this.name = 'UnsupportedFeatureError';
+    }
+}
+/**
+ * Model not found error.
+ */
+export class ModelNotFoundError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.MODEL_NOT_FOUND, message, {
+            ...options,
+            isRetryable: false,
+        });
+        this.name = 'ModelNotFoundError';
+    }
+}
+/**
+ * Network error.
+ */
+export class NetworkError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.NETWORK, message, {
+            ...options,
+            isRetryable: true,
+        });
+        this.name = 'NetworkError';
+    }
+}
+/**
+ * Timeout error.
+ */
+export class TimeoutError extends LlmError {
+    constructor(message, options) {
+        super(LlmErrorType.TIMEOUT, message, {
+            ...options,
+            isRetryable: true,
+        });
+        this.name = 'TimeoutError';
+    }
+}
+// ============================================================================
+// Error Helpers
+// ============================================================================
+/**
+ * Checks if an error is an LlmError.
+ */
+export function isLlmError(error) {
+    return error instanceof LlmError;
+}
+/**
+ * Checks if an error is retryable.
+ */
+export function isRetryableError(error) {
+    if (isLlmError(error)) {
+        return error.isRetryable;
+    }
+    return false;
+}
+/**
+ * Wraps an unknown error as an LlmError.
+ */
+export function wrapError(error, provider) {
+    if (isLlmError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new LlmError(LlmErrorType.UNKNOWN, error.message, {
+            provider,
+            cause: error,
+        });
+    }
+    return new LlmError(LlmErrorType.UNKNOWN, String(error), {
+        provider,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/providers/errors.js.map

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

package/dist/src/providers/events.d.ts

@@ -0,0 +1,294 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Provider-independent stream event types.
+ *
+ * This module defines the unified event system that maps to provider-specific
+ * events (GeminiEventType, Anthropic events, OpenAI events, etc.)
+ *
+ * @see docs/ai_adapter/event-mapping-matrix.md
+ * @see docs/ai_adapter/03-technical-design.md §3.1
+ */
+import type { LlmTokenUsage } from './types.js';
+/**
+ * Unified stream event types for all LLM providers.
+ *
+ * Mapping from GeminiEventType (18 events) + MessageEnd = 19 total:
+ *
+ * | GeminiEventType              | LlmEventType              | Notes           |
+ * |------------------------------|---------------------------|-----------------|
+ * | Content                      | TextDelta                 | Common          |
+ * | ToolCallRequest              | ToolCallRequest           | Common          |
+ * | ToolCallResponse             | ToolCallResponse          | Common          |
+ * | ToolCallConfirmation         | ToolCallConfirmation      | Common          |
+ * | UserCancelled                | UserCancelled             | Common          |
+ * | Error                        | Error                     | Common          |
+ * | ChatCompressed               | ChatCompressed            | Gemini-specific |
+ * | Thought                      | ThoughtDelta              | Common (Claude) |
+ * | MaxSessionTurns              | MaxSessionTurns           | Common          |
+ * | Finished                     | Finished                  | Common          |
+ * | LoopDetected                 | LoopDetected              | Common          |
+ * | Citation                     | Citation                  | Gemini-specific |
+ * | Retry                        | Retry                     | Common          |
+ * | ContextWindowWillOverflow    | ContextWindowOverflow     | Common          |
+ * | InvalidStream                | InvalidStream             | Common          |
+ * | ModelInfo                    | ModelInfo                 | Common          |
+ * | AgentExecutionStopped        | AgentStopped              | Common          |
+ * | AgentExecutionBlocked        | AgentBlocked              | Common          |
+ */
+export declare enum LlmEventType {
+    /** Text content delta (streaming text chunk) */
+    TextDelta = "text_delta",
+    /** Thought/reasoning delta (extended thinking) */
+    ThoughtDelta = "thought_delta",
+    /** Tool call request from the model */
+    ToolCallRequest = "tool_call_request",
+    /** Tool call response (result) */
+    ToolCallResponse = "tool_call_response",
+    /** Tool call confirmation (user approval) */
+    ToolCallConfirmation = "tool_call_confirmation",
+    /** Generation finished normally */
+    Finished = "finished",
+    /** Message end with usage info */
+    MessageEnd = "message_end",
+    /** Error occurred */
+    Error = "error",
+    /** User cancelled the operation */
+    UserCancelled = "user_cancelled",
+    /** Retry signal */
+    Retry = "retry",
+    /** Invalid stream detected */
+    InvalidStream = "invalid_stream",
+    /** Context window will overflow */
+    ContextWindowOverflow = "context_window_overflow",
+    /** Maximum session turns reached */
+    MaxSessionTurns = "max_session_turns",
+    /** Chat history compressed */
+    ChatCompressed = "chat_compressed",
+    /** Loop detected in agent execution */
+    LoopDetected = "loop_detected",
+    /** Agent execution stopped */
+    AgentStopped = "agent_stopped",
+    /** Agent execution blocked */
+    AgentBlocked = "agent_blocked",
+    /** Model information */
+    ModelInfo = "model_info",
+    /** Citation/reference information */
+    Citation = "citation"
+}
+/**
+ * Base event interface with common fields.
+ */
+export interface LlmBaseEvent {
+    type: LlmEventType;
+    traceId?: string;
+}
+/**
+ * Text content delta event.
+ */
+export interface LlmTextDeltaEvent extends LlmBaseEvent {
+    type: LlmEventType.TextDelta;
+    text: string;
+}
+/**
+ * Thought/reasoning delta event.
+ */
+export interface LlmThoughtDeltaEvent extends LlmBaseEvent {
+    type: LlmEventType.ThoughtDelta;
+    thought: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Tool call request event.
+ */
+export interface LlmToolCallRequestEvent extends LlmBaseEvent {
+    type: LlmEventType.ToolCallRequest;
+    callId: string;
+    name: string;
+    args: Record<string, unknown>;
+    isClientInitiated?: boolean;
+    promptId?: string;
+}
+/**
+ * Tool call response event.
+ */
+export interface LlmToolCallResponseEvent extends LlmBaseEvent {
+    type: LlmEventType.ToolCallResponse;
+    callId: string;
+    name: string;
+    result: unknown;
+    isError?: boolean;
+}
+/**
+ * Tool call confirmation event.
+ */
+export interface LlmToolCallConfirmationEvent extends LlmBaseEvent {
+    type: LlmEventType.ToolCallConfirmation;
+    callId: string;
+    confirmed: boolean;
+}
+/**
+ * Finished event with stop reason and usage.
+ */
+export interface LlmFinishedEvent extends LlmBaseEvent {
+    type: LlmEventType.Finished;
+    finishReason?: LlmFinishReason;
+    usage?: LlmTokenUsage;
+}
+/**
+ * Message end event (stream completion).
+ */
+export interface LlmMessageEndEvent extends LlmBaseEvent {
+    type: LlmEventType.MessageEnd;
+    usage?: LlmTokenUsage;
+}
+/**
+ * Error event.
+ */
+export interface LlmErrorEvent extends LlmBaseEvent {
+    type: LlmEventType.Error;
+    error: Error | string;
+    code?: string;
+    isRetryable?: boolean;
+}
+/**
+ * User cancelled event.
+ */
+export interface LlmUserCancelledEvent extends LlmBaseEvent {
+    type: LlmEventType.UserCancelled;
+}
+/**
+ * Retry event.
+ */
+export interface LlmRetryEvent extends LlmBaseEvent {
+    type: LlmEventType.Retry;
+    attemptNumber?: number;
+    reason?: string;
+}
+/**
+ * Invalid stream event.
+ */
+export interface LlmInvalidStreamEvent extends LlmBaseEvent {
+    type: LlmEventType.InvalidStream;
+    reason?: string;
+}
+/**
+ * Context window overflow event.
+ */
+export interface LlmContextWindowOverflowEvent extends LlmBaseEvent {
+    type: LlmEventType.ContextWindowOverflow;
+    currentTokens?: number;
+    maxTokens?: number;
+}
+/**
+ * Max session turns event.
+ */
+export interface LlmMaxSessionTurnsEvent extends LlmBaseEvent {
+    type: LlmEventType.MaxSessionTurns;
+    currentTurns?: number;
+    maxTurns?: number;
+}
+/**
+ * Chat compressed event (Gemini-specific).
+ */
+export interface LlmChatCompressedEvent extends LlmBaseEvent {
+    type: LlmEventType.ChatCompressed;
+    originalTokens?: number;
+    compressedTokens?: number;
+}
+/**
+ * Loop detected event.
+ */
+export interface LlmLoopDetectedEvent extends LlmBaseEvent {
+    type: LlmEventType.LoopDetected;
+    loopCount?: number;
+    pattern?: string;
+}
+/**
+ * Agent stopped event.
+ */
+export interface LlmAgentStoppedEvent extends LlmBaseEvent {
+    type: LlmEventType.AgentStopped;
+    reason?: string;
+    systemMessage?: string;
+    contextCleared?: boolean;
+}
+/**
+ * Agent blocked event.
+ */
+export interface LlmAgentBlockedEvent extends LlmBaseEvent {
+    type: LlmEventType.AgentBlocked;
+    reason?: string;
+    blockType?: string;
+    systemMessage?: string;
+    contextCleared?: boolean;
+}
+/**
+ * Model info event.
+ */
+export interface LlmModelInfoEvent extends LlmBaseEvent {
+    type: LlmEventType.ModelInfo;
+    modelName: string;
+    modelVersion?: string;
+    capabilities?: Record<string, boolean>;
+}
+/**
+ * Citation event (Gemini-specific).
+ */
+export interface LlmCitationEvent extends LlmBaseEvent {
+    type: LlmEventType.Citation;
+    citations: LlmCitation[];
+}
+/**
+ * Citation reference.
+ */
+export interface LlmCitation {
+    startIndex?: number;
+    endIndex?: number;
+    url?: string;
+    title?: string;
+    license?: string;
+}
+/**
+ * Finish reason types.
+ */
+export type LlmFinishReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'content_filter' | 'error' | 'unknown';
+/**
+ * Union of all LLM stream events.
+ */
+export type LlmEvent = LlmTextDeltaEvent | LlmThoughtDeltaEvent | LlmToolCallRequestEvent | LlmToolCallResponseEvent | LlmToolCallConfirmationEvent | LlmFinishedEvent | LlmMessageEndEvent | LlmErrorEvent | LlmUserCancelledEvent | LlmRetryEvent | LlmInvalidStreamEvent | LlmContextWindowOverflowEvent | LlmMaxSessionTurnsEvent | LlmChatCompressedEvent | LlmLoopDetectedEvent | LlmAgentStoppedEvent | LlmAgentBlockedEvent | LlmModelInfoEvent | LlmCitationEvent;
+/**
+ * Stream type for events.
+ */
+export type LlmEventStream = AsyncGenerator<LlmEvent, void, unknown>;
+/**
+ * Type guard for text delta events.
+ */
+export declare function isTextDeltaEvent(event: LlmEvent): event is LlmTextDeltaEvent;
+/**
+ * Type guard for tool call request events.
+ */
+export declare function isToolCallRequestEvent(event: LlmEvent): event is LlmToolCallRequestEvent;
+/**
+ * Type guard for finished events.
+ */
+export declare function isFinishedEvent(event: LlmEvent): event is LlmFinishedEvent;
+/**
+ * Type guard for error events.
+ */
+export declare function isErrorEvent(event: LlmEvent): event is LlmErrorEvent;
+/**
+ * Creates a text delta event.
+ */
+export declare function createTextDeltaEvent(text: string, traceId?: string): LlmTextDeltaEvent;
+/**
+ * Creates a finished event.
+ */
+export declare function createFinishedEvent(finishReason?: LlmFinishReason, usage?: LlmTokenUsage, traceId?: string): LlmFinishedEvent;
+/**
+ * Creates an error event.
+ */
+export declare function createErrorEvent(error: Error | string, code?: string, isRetryable?: boolean, traceId?: string): LlmErrorEvent;

package/dist/src/providers/events.js

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// ============================================================================
+// Event Type Enum
+// ============================================================================
+/**
+ * Unified stream event types for all LLM providers.
+ *
+ * Mapping from GeminiEventType (18 events) + MessageEnd = 19 total:
+ *
+ * | GeminiEventType              | LlmEventType              | Notes           |
+ * |------------------------------|---------------------------|-----------------|
+ * | Content                      | TextDelta                 | Common          |
+ * | ToolCallRequest              | ToolCallRequest           | Common          |
+ * | ToolCallResponse             | ToolCallResponse          | Common          |
+ * | ToolCallConfirmation         | ToolCallConfirmation      | Common          |
+ * | UserCancelled                | UserCancelled             | Common          |
+ * | Error                        | Error                     | Common          |
+ * | ChatCompressed               | ChatCompressed            | Gemini-specific |
+ * | Thought                      | ThoughtDelta              | Common (Claude) |
+ * | MaxSessionTurns              | MaxSessionTurns           | Common          |
+ * | Finished                     | Finished                  | Common          |
+ * | LoopDetected                 | LoopDetected              | Common          |
+ * | Citation                     | Citation                  | Gemini-specific |
+ * | Retry                        | Retry                     | Common          |
+ * | ContextWindowWillOverflow    | ContextWindowOverflow     | Common          |
+ * | InvalidStream                | InvalidStream             | Common          |
+ * | ModelInfo                    | ModelInfo                 | Common          |
+ * | AgentExecutionStopped        | AgentStopped              | Common          |
+ * | AgentExecutionBlocked        | AgentBlocked              | Common          |
+ */
+export var LlmEventType;
+(function (LlmEventType) {
+    // === Text/Content Events ===
+    /** Text content delta (streaming text chunk) */
+    LlmEventType["TextDelta"] = "text_delta";
+    /** Thought/reasoning delta (extended thinking) */
+    LlmEventType["ThoughtDelta"] = "thought_delta";
+    // === Tool Events ===
+    /** Tool call request from the model */
+    LlmEventType["ToolCallRequest"] = "tool_call_request";
+    /** Tool call response (result) */
+    LlmEventType["ToolCallResponse"] = "tool_call_response";
+    /** Tool call confirmation (user approval) */
+    LlmEventType["ToolCallConfirmation"] = "tool_call_confirmation";
+    // === Completion Events ===
+    /** Generation finished normally */
+    LlmEventType["Finished"] = "finished";
+    /** Message end with usage info */
+    LlmEventType["MessageEnd"] = "message_end";
+    // === Error/Control Events ===
+    /** Error occurred */
+    LlmEventType["Error"] = "error";
+    /** User cancelled the operation */
+    LlmEventType["UserCancelled"] = "user_cancelled";
+    /** Retry signal */
+    LlmEventType["Retry"] = "retry";
+    /** Invalid stream detected */
+    LlmEventType["InvalidStream"] = "invalid_stream";
+    // === Session/Context Events ===
+    /** Context window will overflow */
+    LlmEventType["ContextWindowOverflow"] = "context_window_overflow";
+    /** Maximum session turns reached */
+    LlmEventType["MaxSessionTurns"] = "max_session_turns";
+    /** Chat history compressed */
+    LlmEventType["ChatCompressed"] = "chat_compressed";
+    /** Loop detected in agent execution */
+    LlmEventType["LoopDetected"] = "loop_detected";
+    // === Agent Control Events ===
+    /** Agent execution stopped */
+    LlmEventType["AgentStopped"] = "agent_stopped";
+    /** Agent execution blocked */
+    LlmEventType["AgentBlocked"] = "agent_blocked";
+    // === Metadata Events ===
+    /** Model information */
+    LlmEventType["ModelInfo"] = "model_info";
+    /** Citation/reference information */
+    LlmEventType["Citation"] = "citation";
+})(LlmEventType || (LlmEventType = {}));
+// ============================================================================
+// Event Helpers
+// ============================================================================
+/**
+ * Type guard for text delta events.
+ */
+export function isTextDeltaEvent(event) {
+    return event.type === LlmEventType.TextDelta;
+}
+/**
+ * Type guard for tool call request events.
+ */
+export function isToolCallRequestEvent(event) {
+    return event.type === LlmEventType.ToolCallRequest;
+}
+/**
+ * Type guard for finished events.
+ */
+export function isFinishedEvent(event) {
+    return event.type === LlmEventType.Finished;
+}
+/**
+ * Type guard for error events.
+ */
+export function isErrorEvent(event) {
+    return event.type === LlmEventType.Error;
+}
+/**
+ * Creates a text delta event.
+ */
+export function createTextDeltaEvent(text, traceId) {
+    return { type: LlmEventType.TextDelta, text, traceId };
+}
+/**
+ * Creates a finished event.
+ */
+export function createFinishedEvent(finishReason, usage, traceId) {
+    return { type: LlmEventType.Finished, finishReason, usage, traceId };
+}
+/**
+ * Creates an error event.
+ */
+export function createErrorEvent(error, code, isRetryable = false, traceId) {
+    return { type: LlmEventType.Error, error, code, isRetryable, traceId };
+}
+//# sourceMappingURL=events.js.map

package/dist/src/providers/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/providers/events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAN,IAAY,YAgEX;AAhED,WAAY,YAAY;IACtB,8BAA8B;IAC9B,gDAAgD;IAChD,wCAAwB,CAAA;IAExB,kDAAkD;IAClD,8CAA8B,CAAA;IAE9B,sBAAsB;IACtB,uCAAuC;IACvC,qDAAqC,CAAA;IAErC,kCAAkC;IAClC,uDAAuC,CAAA;IAEvC,6CAA6C;IAC7C,+DAA+C,CAAA;IAE/C,4BAA4B;IAC5B,mCAAmC;IACnC,qCAAqB,CAAA;IAErB,kCAAkC;IAClC,0CAA0B,CAAA;IAE1B,+BAA+B;IAC/B,qBAAqB;IACrB,+BAAe,CAAA;IAEf,mCAAmC;IACnC,gDAAgC,CAAA;IAEhC,mBAAmB;IACnB,+BAAe,CAAA;IAEf,8BAA8B;IAC9B,gDAAgC,CAAA;IAEhC,iCAAiC;IACjC,mCAAmC;IACnC,iEAAiD,CAAA;IAEjD,oCAAoC;IACpC,qDAAqC,CAAA;IAErC,8BAA8B;IAC9B,kDAAkC,CAAA;IAElC,uCAAuC;IACvC,8CAA8B,CAAA;IAE9B,+BAA+B;IAC/B,8BAA8B;IAC9B,8CAA8B,CAAA;IAE9B,8BAA8B;IAC9B,8CAA8B,CAAA;IAE9B,0BAA0B;IAC1B,wBAAwB;IACxB,wCAAwB,CAAA;IAExB,qCAAqC;IACrC,qCAAqB,CAAA;AACvB,CAAC,EAhEW,YAAY,KAAZ,YAAY,QAgEvB;AAqPD,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAe;IAC9C,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAe;IAEf,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,eAAe,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAe;IAC7C,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,QAAQ,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,KAAe;IAC1C,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,KAAK,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,OAAgB;IAEhB,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,YAA8B,EAC9B,KAAqB,EACrB,OAAgB;IAEhB,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAqB,EACrB,IAAa,EACb,WAAW,GAAG,KAAK,EACnB,OAAgB;IAEhB,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AACzE,CAAC"}