wave-agent-sdk 0.0.4 → 0.0.6

package/dist/agent.d.ts

@@ -1,8 +1,8 @@
 import { type MessageManagerCallbacks } from "./managers/messageManager.js";
 import { type McpManagerCallbacks } from "./managers/mcpManager.js";
 import { type BackgroundBashManagerCallbacks } from "./managers/backgroundBashManager.js";
-import type { SlashCommand, CustomSlashCommand } from "./types.js";
-import type { Message, Logger, McpServerStatus } from "./types.js";
+import type { SlashCommand, CustomSlashCommand } from "./types/index.js";
+import type { Message, Logger, McpServerStatus, Usage } from "./types/index.js";
 /**
  * Configuration options for Agent instances
  *
@@ -25,6 +25,12 @@ export interface AgentOptions {
     workdir?: string;
     /**Optional custom system prompt - if provided, replaces default system prompt */
     systemPrompt?: string;
+    /**
+     * Optional custom directory for session file storage
+     * @default join(homedir(), ".wave", "sessions")
+     * @example "/path/to/custom/sessions"
+     */
+    sessionDir?: string;
 }
 export interface AgentCallbacks extends MessageManagerCallbacks, BackgroundBashManagerCallbacks, McpManagerCallbacks {
 }
@@ -41,20 +47,35 @@ export declare class Agent {
     private hookManager;
     private workdir;
     private systemPrompt?;
+    private _usages;
     private gatewayConfig;
     private modelConfig;
     private tokenLimit;
     /**
      * Agent constructor - handles configuration resolution and validation
      *
-     * IMPORTANT: Keep this constructor's signature exactly the same as Agent.create()
-     * to maintain API consistency. Both methods should accept the same AgentOptions.
+     * IMPORTANT: This constructor is private. Use Agent.create() instead for proper
+     * async initialization. Keep this constructor's signature exactly the same as
+     * Agent.create() to maintain API consistency.
      *
      * @param options - Configuration options for the Agent instance
+     * @param options.sessionDir - Optional custom directory for session storage
      */
-    constructor(options: AgentOptions);
+    private constructor();
     get sessionId(): string;
     get messages(): Message[];
+    get usages(): Usage[];
+    get sessionFilePath(): string;
+    /**
+     * Rebuild usage array from messages containing usage metadata
+     * Called during session restoration to reconstruct usage tracking
+     */
+    private rebuildUsageFromMessages;
+    /**
+     * Add usage data to the tracking array and trigger callbacks
+     * @param usage Usage data from AI operations
+     */
+    private addUsage;
     get latestTotalTokens(): number;
     get userInputHistory(): string[];
     /** Get working directory */
@@ -82,6 +103,43 @@ export declare class Agent {
      * @param options - Same AgentOptions interface used by constructor
      * @returns Promise<Agent> - Fully initialized Agent instance
      */
+    /**
+     * Create a new Agent instance with async initialization
+     *
+     * This is the recommended way to create Agent instances. The constructor is private
+     * to ensure proper async initialization of all components.
+     *
+     * @param options - Configuration options for the Agent instance
+     * @param options.apiKey - API key for the AI service (or set WAVE_API_KEY env var)
+     * @param options.baseURL - Base URL for the AI service (or set WAVE_BASE_URL env var)
+     * @param options.sessionDir - Optional custom directory for session file storage.
+     *   If not provided, defaults to ~/.wave/sessions/. Can be relative or absolute path.
+     *   Examples: "./app-sessions", "/var/myapp/sessions", "~/Documents/sessions"
+     * @param options.callbacks - Optional callbacks for various Agent events
+     * @param options.restoreSessionId - Optional session ID to restore from
+     * @param options.continueLastSession - Whether to continue the last session automatically
+     * @param options.logger - Optional custom logger implementation
+     * @param options.messages - Optional initial messages for testing convenience
+     * @param options.workdir - Working directory (defaults to process.cwd())
+     * @param options.systemPrompt - Optional custom system prompt
+     * @returns Promise that resolves to initialized Agent instance
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with default session directory
+     * const agent = await Agent.create({
+     *   apiKey: 'your-api-key',
+     *   baseURL: 'https://api.example.com'
+     * });
+     *
+     * // Custom session directory
+     * const agent = await Agent.create({
+     *   apiKey: 'your-api-key',
+     *   baseURL: 'https://api.example.com',
+     *   sessionDir: './app-sessions'
+     * });
+     * ```
+     */
     static create(options: AgentOptions): Promise<Agent>;
     /** Private initialization method, handles async initialization logic */
     private initialize;
@@ -98,10 +156,6 @@ export declare class Agent {
     abortBashCommand(): void;
     /** Interrupt slash command execution */
     abortSlashCommand(): void;
-    /** Interrupt all subagent execution */
-    abortSubagents(): void;
-    /** Interrupt specific subagent execution */
-    abortSubagent(subagentId: string): boolean;
     /** Destroy managers, clean up resources */
     destroy(): Promise<void>;
     sendMessage(content: string, images?: Array<{

package/dist/agent.d.ts.map

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

package/dist/agent.js

@@ -7,7 +7,7 @@ import { McpManager } from "./managers/mcpManager.js";
 import { BashManager } from "./managers/bashManager.js";
 import { BackgroundBashManager, } from "./managers/backgroundBashManager.js";
 import { SlashCommandManager } from "./managers/slashCommandManager.js";
-import { HookManager } from "./hooks/index.js";
+import { HookManager } from "./managers/hookManager.js";
 import { configResolver } from "./utils/configResolver.js";
 import { configValidator } from "./utils/configValidator.js";
 import { SkillManager } from "./managers/skillManager.js";
@@ -15,14 +15,17 @@ export class Agent {
     /**
      * Agent constructor - handles configuration resolution and validation
      *
-     * IMPORTANT: Keep this constructor's signature exactly the same as Agent.create()
-     * to maintain API consistency. Both methods should accept the same AgentOptions.
+     * IMPORTANT: This constructor is private. Use Agent.create() instead for proper
+     * async initialization. Keep this constructor's signature exactly the same as
+     * Agent.create() to maintain API consistency.
      *
      * @param options - Configuration options for the Agent instance
+     * @param options.sessionDir - Optional custom directory for session storage
      */
     constructor(options) {
         this.bashManager = null;
-        const { callbacks = {}, logger, workdir, systemPrompt } = options;
+        this._usages = []; // Usage tracking array
+        const { callbacks = {}, logger, workdir, systemPrompt, sessionDir, } = options;
         // Resolve configuration from constructor args and environment variables
         const gatewayConfig = configResolver.resolveGatewayConfig(options.apiKey, options.baseURL);
         const modelConfig = configResolver.resolveModelConfig(options.agentModel, options.fastModel);
@@ -47,12 +50,13 @@ export class Agent {
             mcpManager: this.mcpManager,
             logger: this.logger,
         }); // Initialize tool registry, pass MCP manager
-        this.hookManager = new HookManager(this.workdir, undefined, undefined, this.logger); // Initialize hooks manager
+        this.hookManager = new HookManager(this.workdir, undefined, this.logger); // Initialize hooks manager
         // Initialize MessageManager
         this.messageManager = new MessageManager({
             callbacks,
             workdir: this.workdir,
             logger: this.logger,
+            sessionDir,
         });
         // Initialize subagent manager with all dependencies in constructor
         // IMPORTANT: Must be initialized AFTER MessageManager
@@ -64,6 +68,7 @@ export class Agent {
             gatewayConfig,
             modelConfig,
             tokenLimit,
+            onUsageAdded: (usage) => this.addUsage(usage),
         });
         // Initialize AI manager with resolved configuration
         this.aiManager = new AIManager({
@@ -72,7 +77,12 @@ export class Agent {
             logger: this.logger,
             backgroundBashManager: this.backgroundBashManager,
             hookManager: this.hookManager,
-            callbacks,
+            callbacks: {
+                ...callbacks,
+                onUsageAdded: (usage) => {
+                    this.addUsage(usage);
+                },
+            },
             workdir: this.workdir,
             systemPrompt: this.systemPrompt,
             gatewayConfig: this.gatewayConfig,
@@ -99,6 +109,34 @@ export class Agent {
     get messages() {
         return this.messageManager.getMessages();
     }
+    get usages() {
+        return [...this._usages]; // Return copy to prevent external modification
+    }
+    get sessionFilePath() {
+        return this.messageManager.getTranscriptPath();
+    }
+    /**
+     * Rebuild usage array from messages containing usage metadata
+     * Called during session restoration to reconstruct usage tracking
+     */
+    rebuildUsageFromMessages() {
+        this._usages = [];
+        this.messages.forEach((message) => {
+            if (message.role === "assistant" && message.usage) {
+                this._usages.push(message.usage);
+            }
+        });
+        // Trigger callback after rebuilding usage array
+        this.messageManager.triggerUsageChange();
+    }
+    /**
+     * Add usage data to the tracking array and trigger callbacks
+     * @param usage Usage data from AI operations
+     */
+    addUsage(usage) {
+        this._usages.push(usage);
+        this.messageManager.triggerUsageChange();
+    }
     get latestTotalTokens() {
         return this.messageManager.getlatestTotalTokens();
     }
@@ -138,6 +176,43 @@ export class Agent {
      * @param options - Same AgentOptions interface used by constructor
      * @returns Promise<Agent> - Fully initialized Agent instance
      */
+    /**
+     * Create a new Agent instance with async initialization
+     *
+     * This is the recommended way to create Agent instances. The constructor is private
+     * to ensure proper async initialization of all components.
+     *
+     * @param options - Configuration options for the Agent instance
+     * @param options.apiKey - API key for the AI service (or set WAVE_API_KEY env var)
+     * @param options.baseURL - Base URL for the AI service (or set WAVE_BASE_URL env var)
+     * @param options.sessionDir - Optional custom directory for session file storage.
+     *   If not provided, defaults to ~/.wave/sessions/. Can be relative or absolute path.
+     *   Examples: "./app-sessions", "/var/myapp/sessions", "~/Documents/sessions"
+     * @param options.callbacks - Optional callbacks for various Agent events
+     * @param options.restoreSessionId - Optional session ID to restore from
+     * @param options.continueLastSession - Whether to continue the last session automatically
+     * @param options.logger - Optional custom logger implementation
+     * @param options.messages - Optional initial messages for testing convenience
+     * @param options.workdir - Working directory (defaults to process.cwd())
+     * @param options.systemPrompt - Optional custom system prompt
+     * @returns Promise that resolves to initialized Agent instance
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with default session directory
+     * const agent = await Agent.create({
+     *   apiKey: 'your-api-key',
+     *   baseURL: 'https://api.example.com'
+     * });
+     *
+     * // Custom session directory
+     * const agent = await Agent.create({
+     *   apiKey: 'your-api-key',
+     *   baseURL: 'https://api.example.com',
+     *   sessionDir: './app-sessions'
+     * });
+     * ```
+     */
     static async create(options) {
         // Create Agent instance - configuration resolution and validation now happens in constructor
         const instance = new Agent(options);
@@ -178,7 +253,7 @@ export class Agent {
         // Initialize hooks configuration
         try {
             // Load hooks configuration from user and project settings
-            this.logger?.info("Loading hooks configuration...");
+            this.logger?.debug("Loading hooks configuration...");
             this.hookManager.loadConfigurationFromSettings();
             this.logger?.debug("Hooks system initialized successfully");
         }
@@ -190,10 +265,14 @@ export class Agent {
         if (options?.messages) {
             // If messages are provided, use them directly (useful for testing)
             this.messageManager.setMessages(options.messages);
+            // Rebuild usage array from restored messages
+            this.rebuildUsageFromMessages();
         }
         else {
             // Otherwise, handle session restoration
             await this.messageManager.handleSessionRestoration(options?.restoreSessionId, options?.continueLastSession);
+            // Rebuild usage array from restored messages
+            this.rebuildUsageFromMessages();
         }
     }
     abortAIMessage() {
@@ -211,10 +290,9 @@ export class Agent {
     }
     /** Unified interrupt method, interrupts both AI messages and command execution */
     abortMessage() {
-        this.abortAIMessage();
+        this.abortAIMessage(); // This will abort tools including Task tool (subagents)
         this.abortBashCommand();
         this.abortSlashCommand();
-        this.abortSubagents();
     }
     /** Add to input history */
     addToInputHistory(input) {
@@ -228,21 +306,12 @@ export class Agent {
     abortSlashCommand() {
         this.slashCommandManager.abortCurrentCommand();
     }
-    /** Interrupt all subagent execution */
-    abortSubagents() {
-        this.subagentManager.abortAllInstances();
-    }
-    /** Interrupt specific subagent execution */
-    abortSubagent(subagentId) {
-        return this.subagentManager.abortInstance(subagentId);
-    }
     /** Destroy managers, clean up resources */
     async destroy() {
-        this.messageManager.saveSession();
-        this.abortAIMessage();
+        await this.messageManager.saveSession();
+        this.abortAIMessage(); // This will abort tools including Task tool (subagents)
         this.abortBashCommand();
         this.abortSlashCommand();
-        this.abortSubagents();
         // Cleanup background bash manager
         this.backgroundBashManager.cleanup();
         // Cleanup MCP connections
@@ -272,10 +341,15 @@ export class Agent {
             // Handle normal AI message
             // Add user message to history
             this.addToInputHistory(content);
-            // Execute UserPromptSubmit hooks before processing the prompt
+            // Add user message first, will automatically sync to UI
+            this.messageManager.addUserMessage(content, images?.map((img) => ({
+                path: img.path,
+                mimeType: img.mimeType,
+            })));
+            // Execute UserPromptSubmit hooks after adding the user message
             if (this.hookManager) {
                 try {
-                    await this.hookManager.executeHooks("UserPromptSubmit", {
+                    const hookResults = await this.hookManager.executeHooks("UserPromptSubmit", {
                         event: "UserPromptSubmit",
                         projectDir: this.workdir,
                         timestamp: new Date(),
@@ -285,17 +359,19 @@ export class Agent {
                         cwd: this.workdir,
                         userPrompt: content,
                     });
+                    // Process hook results and determine if we should continue
+                    const processResult = this.hookManager.processHookResults("UserPromptSubmit", hookResults, this.messageManager);
+                    // If hook processing indicates we should block (exit code 2), stop here
+                    if (processResult.shouldBlock) {
+                        this.logger?.info("UserPromptSubmit hook blocked prompt processing with error:", processResult.errorMessage);
+                        return; // Don't send to AI
+                    }
                 }
                 catch (error) {
                     this.logger?.warn("UserPromptSubmit hooks execution failed:", error);
                     // Continue processing even if hooks fail
                 }
             }
-            // Add user message, will automatically sync to UI
-            this.messageManager.addUserMessage(content, images?.map((img) => ({
-                path: img.path,
-                mimeType: img.mimeType,
-            })));
             // Send AI message
             await this.aiManager.sendAIMessage();
         }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./services/aiService.js";
 export * from "./services/memory.js";
 export * from "./services/session.js";
+export * from "./services/hook.js";
 export * from "./agent.js";
 export * from "./utils/bashHistory.js";
 export * from "./utils/convertMessagesForAPI.js";
@@ -10,6 +11,6 @@ export * from "./utils/messageOperations.js";
 export * from "./utils/path.js";
 export * from "./utils/stringUtils.js";
 export * from "./utils/customCommands.js";
-export * from "./hooks/index.js";
-export * from "./types.js";
+export * from "./utils/hookMatcher.js";
+export * from "./types/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,YAAY,CAAC;AAG3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,kBAAkB,CAAC;AAGjC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,YAAY,CAAC;AAG3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -2,6 +2,7 @@
 export * from "./services/aiService.js";
 export * from "./services/memory.js";
 export * from "./services/session.js";
+export * from "./services/hook.js";
 // Export main agent
 export * from "./agent.js";
 // Export all utilities
@@ -13,7 +14,6 @@ export * from "./utils/messageOperations.js";
 export * from "./utils/path.js";
 export * from "./utils/stringUtils.js";
 export * from "./utils/customCommands.js";
-// Export hooks system
-export * from "./hooks/index.js";
+export * from "./utils/hookMatcher.js";
 // Export types
-export * from "./types.js";
+export * from "./types/index.js";

package/dist/managers/aiManager.d.ts

@@ -1,10 +1,11 @@
-import type { Logger, GatewayConfig, ModelConfig } from "../types.js";
+import type { Logger, GatewayConfig, ModelConfig, Usage } from "../types/index.js";
 import type { ToolManager } from "./toolManager.js";
 import type { MessageManager } from "./messageManager.js";
 import type { BackgroundBashManager } from "./backgroundBashManager.js";
-import type { HookManager } from "../hooks/index.js";
+import type { HookManager } from "./hookManager.js";
 export interface AIManagerCallbacks {
     onCompressionStateChange?: (isCompressing: boolean) => void;
+    onUsageAdded?: (usage: Usage) => void;
 }
 export interface AIManagerOptions {
     messageManager: MessageManager;
@@ -53,10 +54,12 @@ export declare class AIManager {
     }): Promise<void>;
     /**
      * Execute Stop hooks when AI response cycle completes
+     * @returns Promise<boolean> - true if should continue conversation, false if should stop
      */
     private executeStopHooks;
     /**
      * Execute PreToolUse hooks before tool execution
+     * Returns true if hooks allow tool execution, false if blocked
      */
     private executePreToolUseHooks;
     /**

package/dist/managers/aiManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiManager.d.ts","sourceRoot":"","sources":["../../src/managers/aiManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,MAAM,WAAW,kBAAkB;IACjC,wBAAwB,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,cAAc,CAAC;IAC/B,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,SAAS;IACb,SAAS,EAAE,OAAO,CAAS;IAClC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,mBAAmB,CAAgC;IAC3D,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,qBAAqB,CAAC,CAAwB;IACtD,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAS;IAG9B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,gBAAgB;IAgBrC,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,SAAS,CAAqB;IAEtC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAYvB,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAItC,cAAc,IAAI,IAAI;IAuB7B,OAAO,CAAC,qBAAqB;YAqBf,8BAA8B;IAoDrC,gBAAgB,IAAI,OAAO;IAI3B,gBAAgB,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI;IAOxC,aAAa,CACxB,OAAO,GAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,GACL,OAAO,CAAC,IAAI,CAAC;IA+PhB;;OAEG;YACW,gBAAgB;IAmC9B;;OAEG;YACW,sBAAsB;IA0CpC;;OAEG;YACW,uBAAuB;CA2CtC"}
+{"version":3,"file":"aiManager.d.ts","sourceRoot":"","sources":["../../src/managers/aiManager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,MAAM,EACN,aAAa,EACb,WAAW,EACX,KAAK,EACN,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,MAAM,WAAW,kBAAkB;IACjC,wBAAwB,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5D,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,cAAc,CAAC;IAC/B,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,SAAS;IACb,SAAS,EAAE,OAAO,CAAS;IAClC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,mBAAmB,CAAgC;IAC3D,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,qBAAqB,CAAC,CAAwB;IACtD,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAS;IAG9B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,gBAAgB;IAgBrC,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,SAAS,CAAqB;IAEtC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAYvB,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAItC,cAAc,IAAI,IAAI;IAuB7B,OAAO,CAAC,qBAAqB;YAqBf,8BAA8B;IAoErC,gBAAgB,IAAI,OAAO;IAI3B,gBAAgB,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI;IAOxC,aAAa,CACxB,OAAO,GAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,GACL,OAAO,CAAC,IAAI,CAAC;IAyShB;;;OAGG;YACW,gBAAgB;IAyD9B;;;OAGG;YACW,sBAAsB;IA0DpC;;OAEG;YACW,uBAAuB;CAyDtC"}