@kadi.build/core 0.0.1-alpha.0 → 0.0.1-alpha.10

package/dist/types/protocol.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Protocol Types Module
+ * ======================
+ *
+ * Re-exports protocol-related types for kadi-broker and other consumers.
+ * This provides a clean import path: @kadi.build/core/types/protocol
+ *
+ * @module types/protocol
+ */
+import type { NetworkId, ToolTag, KadiTool } from '../schemas/kadi-extensions.js';
+import type { AgentRole } from './config.js';
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, JsonRpcError, PendingRequest } from './broker.js';
+export type { NetworkId, ToolTag };
+export interface Provider {
+    agentId: string;
+    agentName?: string;
+    networks: NetworkId[];
+    tags?: ToolTag[];
+    displayName?: string;
+    lastSeen?: number;
+    registeredAt?: number;
+}
+export interface SystemSnapshot {
+    agents: Array<{
+        id: string;
+        name: string;
+        type: 'agent';
+        tools: string[];
+        networks: string[];
+        status: 'active' | 'disconnected';
+    }>;
+    networks: Array<{
+        id: string;
+        name: string;
+        type: 'network';
+        status: 'active';
+    }>;
+    connections: Array<{
+        from: string;
+        to: string;
+        status: 'connected' | 'disconnected';
+    }>;
+    timestamp: string;
+}
+export type { KadiTool as Tool };
+export type { AgentRole as SessionRole };
+export type QueueKind = 'direct' | 'fanout' | 'topic' | 'agent';
+//# sourceMappingURL=protocol.d.ts.map

package/dist/types/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/types/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,YAAY,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACf,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAGnC,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAGD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,OAAO,CAAC;QACd,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,MAAM,EAAE,QAAQ,GAAG,cAAc,CAAC;KACnC,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,SAAS,CAAC;QAChB,MAAM,EAAE,QAAQ,CAAC;KAClB,CAAC,CAAC;IACH,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,WAAW,GAAG,cAAc,CAAC;KACtC,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,YAAY,EAAE,QAAQ,IAAI,IAAI,EAAE,CAAC;AAGjC,YAAY,EAAE,SAAS,IAAI,WAAW,EAAE,CAAC;AAGzC,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC"}

package/dist/types/protocol.js

@@ -0,0 +1,11 @@
+/**
+ * Protocol Types Module
+ * ======================
+ *
+ * Re-exports protocol-related types for kadi-broker and other consumers.
+ * This provides a clean import path: @kadi.build/core/types/protocol
+ *
+ * @module types/protocol
+ */
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/types/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/types/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/types/tools.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Tool Types (MCP-Based)
+ * ========================
+ *
+ * Type definitions for tool registration, handlers, and schemas using the
+ * Model Context Protocol (MCP) standard.
+ *
+ * **Breaking Change (v2.0.0)**:
+ * - Replaced Zod schemas with MCP JSON Schemas
+ * - Full MCP compliance with KADI extensions
+ * - See migration guide for upgrading from v1.x
+ *
+ * @module types/tools
+ */
+export type { KadiTool, KadiToolResult, ToolDefinition, ToolHandler, RegisteredTool, ToolTag, NetworkId, ToolDiscoveryQuery, ToolDiscoveryResult } from '../schemas/index.js';
+export type { McpTool, McpCallToolResult, ToolAnnotations, ListToolsRequest, ListToolsResult, CallToolRequest, ToolListChangedNotification } from '../schemas/index.js';
+/**
+ * Tool invocation result
+ *
+ * Extended version of MCP CallToolResult with KADI-specific metadata.
+ *
+ * @template T - Result data type
+ */
+export interface ToolInvocationResult<T = unknown> {
+    /**
+     * Whether the invocation succeeded
+     */
+    success: boolean;
+    /**
+     * The result data if successful
+     */
+    data?: T;
+    /**
+     * Error information if failed
+     */
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    /**
+     * Execution metadata
+     */
+    metadata?: {
+        /**
+         * Execution time in milliseconds
+         */
+        executionTime?: number;
+        /**
+         * Timestamp when execution started
+         */
+        timestamp?: number;
+        /**
+         * Agent that executed the tool
+         */
+        agentId?: string;
+        /**
+         * Network the tool was executed on
+         */
+        networkId?: string;
+        /**
+         * Whether result was cached
+         */
+        cacheHit?: boolean;
+    };
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/types/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,YAAY,EACV,QAAQ,EACR,cAAc,EACd,cAAc,EACd,WAAW,EACX,cAAc,EACd,OAAO,EACP,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EACV,OAAO,EACP,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,2BAA2B,EAC5B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,CAAC,CAAC;IAET;;OAEG;IACH,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,EAAE;QACT;;WAEG;QACH,aAAa,CAAC,EAAE,MAAM,CAAC;QAEvB;;WAEG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB;;WAEG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB;;WAEG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB;;WAEG;QACH,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;CACH"}

package/dist/types/tools.js

@@ -0,0 +1,16 @@
+/**
+ * Tool Types (MCP-Based)
+ * ========================
+ *
+ * Type definitions for tool registration, handlers, and schemas using the
+ * Model Context Protocol (MCP) standard.
+ *
+ * **Breaking Change (v2.0.0)**:
+ * - Replaced Zod schemas with MCP JSON Schemas
+ * - Full MCP compliance with KADI extensions
+ * - See migration guide for upgrading from v1.x
+ *
+ * @module types/tools
+ */
+export {};
+//# sourceMappingURL=tools.js.map

package/dist/types/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/types/transport.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Transport Types
+ *
+ * Type definitions for ability transports.
+ * Transports enable loading and communicating with abilities across different protocols.
+ */
+import type { EventEmitter } from 'events';
+/**
+ * Ability Transport Interface
+ *
+ * All transports (Native, Stdio, Broker) must implement this interface.
+ * This provides a uniform way to load and communicate with abilities
+ * regardless of their deployment location or protocol.
+ *
+ * @example
+ * ```typescript
+ * class MyTransport implements AbilityTransport {
+ *   async connect() { / * ... * / }
+ *   async invoke(method, params) { / * ... * / }
+ *   getMethods() { / * ... * / }
+ *   async disconnect() { / * ... * / }
+ * }
+ * ```
+ */
+export interface AbilityTransport extends EventEmitter {
+    /**
+     * Establish connection to the ability
+     *
+     * - Native: Load the module from disk
+     * - Stdio: Spawn the child process
+     * - Broker: Connect to WebSocket and authenticate
+     *
+     * @throws {Error} If connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Invoke a method on the connected ability
+     *
+     * @template TInput - Input parameter type
+     * @template TOutput - Return value type
+     *
+     * @param method - Method name to invoke
+     * @param params - Parameters to pass
+     * @returns Promise resolving to the method result
+     *
+     * @throws {Error} If method doesn't exist or invocation fails
+     */
+    invoke<TInput = unknown, TOutput = unknown>(method: string, params: TInput): Promise<TOutput>;
+    /**
+     * Get list of available methods on this ability
+     *
+     * @returns Array of method names
+     */
+    getMethods(): string[];
+    /**
+     * Disconnect and cleanup resources
+     *
+     * - Native: Cleanup module references
+     * - Stdio: Terminate child process
+     * - Broker: Close WebSocket connection
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get schema for a specific method (optional)
+     *
+     * @param method - Method name
+     * @returns Method schema if available
+     */
+    getMethodSchema?(method: string): MethodSchema | undefined;
+    /**
+     * Publish an event from the ability (optional)
+     *
+     * @param eventName - Event name
+     * @param data - Event data
+     */
+    publishEvent?(eventName: string, data: unknown): void;
+}
+/**
+ * Method schema definition
+ */
+export interface MethodSchema {
+    /**
+     * Description of what the method does
+     */
+    description?: string;
+    /**
+     * Input schema (JSON Schema)
+     */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Output schema (JSON Schema)
+     */
+    outputSchema?: Record<string, unknown>;
+    /**
+     * Example usage
+     */
+    examples?: Array<{
+        input: unknown;
+        output: unknown;
+    }>;
+}
+/**
+ * Base transport configuration options
+ */
+export interface TransportOptions {
+    /**
+     * Ability name
+     */
+    abilityName: string;
+    /**
+     * Ability version (optional)
+     */
+    abilityVersion?: string;
+    /**
+     * Timeout for method invocations in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * Native transport options (in-process loading)
+ */
+export interface NativeTransportOptions extends TransportOptions {
+    /**
+     * Path to ability directory
+     */
+    abilityPath: string;
+    /**
+     * Entry point file (relative to abilityPath)
+     * @default 'index.js'
+     */
+    entryPoint?: string;
+}
+/**
+ * Stdio transport options (child process)
+ */
+export interface StdioTransportOptions extends TransportOptions {
+    /**
+     * Path to ability directory
+     */
+    abilityPath: string;
+    /**
+     * Command to execute
+     * @default 'node'
+     */
+    command?: string;
+    /**
+     * Command arguments
+     * @default ['index.js']
+     */
+    args?: string[];
+    /**
+     * Environment variables to pass
+     */
+    env?: Record<string, string>;
+    /**
+     * Working directory
+     */
+    cwd?: string;
+}
+/**
+ * Broker transport options (remote ability)
+ */
+export interface BrokerTransportOptions extends TransportOptions {
+    /**
+     * Broker URL
+     */
+    brokerUrl: string;
+    /**
+     * Broker name identifier
+     */
+    brokerName?: string;
+    /**
+     * Networks to search for the ability
+     */
+    networks?: string[];
+    /**
+     * Authentication token
+     */
+    authToken?: string;
+}
+/**
+ * Message transport interface (low-level)
+ *
+ * This is for the underlying message-passing layer (WebSocket, stdio streams, etc.)
+ * Distinct from AbilityTransport which is higher-level.
+ */
+export interface MessageTransport extends EventEmitter {
+    /**
+     * Connect to the message transport
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the message transport
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send raw data
+     */
+    send(data: Buffer | string): Promise<void>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+}
+/**
+ * Transport discovery result
+ */
+export interface TransportDiscoveryResult {
+    /**
+     * Available methods
+     */
+    methods: string[];
+    /**
+     * Method schemas
+     */
+    schemas?: Map<string, MethodSchema>;
+    /**
+     * Ability metadata
+     */
+    metadata?: {
+        name: string;
+        version?: string;
+        description?: string;
+    };
+}
+/**
+ * Stdio message framing
+ */
+export interface StdioFrame {
+    /**
+     * Message length
+     */
+    length: number;
+    /**
+     * Message content (JSON)
+     */
+    content: unknown;
+}
+/**
+ * Stdio protocol message types
+ */
+export declare enum StdioMessageType {
+    DISCOVER = "__kadi_discover",
+    INVOKE = "__kadi_invoke",
+    RESULT = "__kadi_result",
+    ERROR = "__kadi_error",
+    EVENT = "__kadi_event"
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/types/transport.d.ts.map

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

package/dist/types/transport.js

@@ -0,0 +1,18 @@
+/**
+ * Transport Types
+ *
+ * Type definitions for ability transports.
+ * Transports enable loading and communicating with abilities across different protocols.
+ */
+/**
+ * Stdio protocol message types
+ */
+export var StdioMessageType;
+(function (StdioMessageType) {
+    StdioMessageType["DISCOVER"] = "__kadi_discover";
+    StdioMessageType["INVOKE"] = "__kadi_invoke";
+    StdioMessageType["RESULT"] = "__kadi_result";
+    StdioMessageType["ERROR"] = "__kadi_error";
+    StdioMessageType["EVENT"] = "__kadi_event";
+})(StdioMessageType || (StdioMessageType = {}));
+//# sourceMappingURL=transport.js.map

package/dist/types/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/types/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgRH;;GAEG;AACH,MAAM,CAAN,IAAY,gBAMX;AAND,WAAY,gBAAgB;IAC1B,gDAA4B,CAAA;IAC5B,4CAAwB,CAAA;IACxB,4CAAwB,CAAA;IACxB,0CAAsB,CAAA;IACtB,0CAAsB,CAAA;AACxB,CAAC,EANW,gBAAgB,KAAhB,gBAAgB,QAM3B"}

package/dist/validation/SchemaValidator.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Schema Validator
+ * =================
+ *
+ * Validates tool input/output against MCP JSON Schemas using AJV.
+ * Implements global caching for performance at scale.
+ *
+ * **Performance Optimization**:
+ * - Global cache prevents redundant schema compilations
+ * - At scale (1000+ tools), this provides 1000x performance improvement
+ * - Memory efficient: ~5KB per compiled schema vs 5MB for duplicates
+ *
+ * @module validation/SchemaValidator
+ */
+import { ErrorObject } from 'ajv';
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    /**
+     * Whether validation passed
+     */
+    valid: boolean;
+    /**
+     * Human-readable error messages
+     */
+    errors: string[];
+    /**
+     * Detailed error objects from AJV (for debugging)
+     */
+    errorDetails?: ErrorObject[];
+}
+/**
+ * Schema Validator
+ * =================
+ *
+ * Validates tool inputs and outputs against JSON Schemas.
+ * Each instance manages schemas for a set of tools, but shares
+ * the global compilation cache for efficiency.
+ *
+ * **Usage**:
+ * ```typescript
+ * const validator = new SchemaValidator();
+ *
+ * // Register tool schemas
+ * validator.registerTool('add', inputSchema, outputSchema);
+ *
+ * // Validate input
+ * const result = validator.validateInput('add', { a: 5, b: 3 });
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors);
+ * }
+ * ```
+ */
+export declare class SchemaValidator {
+    /**
+     * Tool schemas (per validator instance)
+     */
+    private readonly toolSchemas;
+    /**
+     * Compiled validators (per validator instance, but reuses global cache)
+     */
+    private readonly validators;
+    /**
+     * Reference to global cache (shared across all instances)
+     */
+    private readonly globalCache;
+    constructor();
+    /**
+     * Register a tool with its input and output schemas
+     *
+     * Compiles schemas using global cache to avoid redundant work.
+     * If these schemas were compiled before (by any validator instance),
+     * the cached validators are reused.
+     *
+     * @param toolName - Tool name
+     * @param inputSchema - Input JSON Schema (MCP format)
+     * @param outputSchema - Optional output JSON Schema (MCP format)
+     * @throws {KadiError} If schema compilation fails
+     *
+     * @example
+     * ```typescript
+     * validator.registerTool('add', {
+     *   type: 'object',
+     *   properties: {
+     *     a: { type: 'number' },
+     *     b: { type: 'number' }
+     *   },
+     *   required: ['a', 'b']
+     * }, {
+     *   type: 'object',
+     *   properties: {
+     *     result: { type: 'number' }
+     *   }
+     * });
+     * ```
+     */
+    registerTool(toolName: string, inputSchema: object, outputSchema?: object): void;
+    /**
+     * Validate input data against a tool's input schema
+     *
+     * @param toolName - Tool name
+     * @param input - Input data to validate
+     * @returns Validation result
+     *
+     * @example
+     * ```typescript
+     * const result = validator.validateInput('add', { a: 5, b: 3 });
+     * if (!result.valid) {
+     *   console.error('Invalid input:', result.errors);
+     * }
+     * ```
+     */
+    validateInput(toolName: string, input: unknown): ValidationResult;
+    /**
+     * Validate output data against a tool's output schema
+     *
+     * @param toolName - Tool name
+     * @param output - Output data to validate
+     * @returns Validation result
+     *
+     * @example
+     * ```typescript
+     * const result = validator.validateOutput('add', { result: 8 });
+     * if (!result.valid) {
+     *   console.error('Invalid output:', result.errors);
+     * }
+     * ```
+     */
+    validateOutput(toolName: string, output: unknown): ValidationResult;
+    /**
+     * Get the schemas for a tool
+     *
+     * @param toolName - Tool name
+     * @returns Tool schemas or undefined if not registered
+     */
+    getToolSchemas(toolName: string): {
+        input: object;
+        output?: object;
+    } | undefined;
+    /**
+     * Check if a tool has registered schemas
+     *
+     * @param toolName - Tool name
+     * @returns Whether tool is registered
+     */
+    hasToolSchemas(toolName: string): boolean;
+    /**
+     * Remove schemas for a tool
+     *
+     * @param toolName - Tool name
+     */
+    unregisterTool(toolName: string): void;
+    /**
+     * Get all registered tool names
+     *
+     * @returns Array of tool names
+     */
+    getRegisteredTools(): string[];
+    /**
+     * Validate a schema definition itself (meta-validation)
+     *
+     * Checks if a schema is valid JSON Schema and can be compiled.
+     * Uses global cache to avoid redundant compilations.
+     *
+     * @param schema - JSON Schema to validate
+     * @returns Validation result
+     *
+     * @example
+     * ```typescript
+     * const result = validator.validateSchemaDefinition({
+     *   type: 'object',
+     *   properties: {
+     *     name: { type: 'string' }
+     *   }
+     * });
+     * if (!result.valid) {
+     *   console.error('Invalid schema:', result.errors);
+     * }
+     * ```
+     */
+    validateSchemaDefinition(schema: object): ValidationResult;
+    /**
+     * Format validation errors for human readability
+     *
+     * Converts AJV error objects into clear, actionable error messages.
+     *
+     * @param errors - AJV error objects
+     * @returns Human-readable error messages
+     */
+    private formatValidationErrors;
+    /**
+     * Get global cache statistics
+     *
+     * @returns Cache statistics
+     */
+    static getCacheStats(): {
+        cachedSchemas: number;
+    };
+    /**
+     * Clear global cache
+     *
+     * **Warning**: This affects all SchemaValidator instances.
+     * Primarily for testing.
+     */
+    static clearGlobalCache(): void;
+}
+//# sourceMappingURL=SchemaValidator.d.ts.map

package/dist/validation/SchemaValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaValidator.d.ts","sourceRoot":"","sources":["../../src/validation/SchemaValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAmB,EAA8B,WAAW,EAAE,MAAM,KAAK,CAAC;AAoB1E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;CAC9B;AAuGD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyD;IAErF;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAGvB;IAEJ;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;;IAOhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBhF;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB;IAsBjE;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,gBAAgB;IA2BnE;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAIhF;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIzC;;;;OAIG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKtC;;;;OAIG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAc1D;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IA6C9B;;;;OAIG;IACH,MAAM,CAAC,aAAa,IAAI;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE;IAIjD;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,IAAI,IAAI;CAGhC"}