kagent-ts 0.1.0

package/dist/core/agent.js

@@ -0,0 +1,398 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const context_manager_1 = require("../context/context-manager");
+const tool_registry_1 = require("../tools/tool-registry");
+const skill_manager_1 = require("../skills/skill-manager");
+const session_manager_1 = require("../session/session-manager");
+const preference_manager_1 = require("../preferences/preference-manager");
+/**
+ * Abstract base Agent class.
+ *
+ * Provides the shared infrastructure:
+ * - LLM provider
+ * - Context window management
+ * - Tool registry (with circuit breaker support)
+ * - Skill manager (progressive disclosure)
+ * - User preferences (system-prompt injection)
+ * - Session manager (checkpoint persistence & resume)
+ * - Abort controller (cancellation via SIGINT)
+ *
+ * Subclasses implement the actual agent logic (e.g., ReActAgent).
+ */
+class Agent {
+    llm;
+    contextManager;
+    toolRegistry;
+    skillManager;
+    /** The original core system prompt (before skill sections are appended). */
+    coreSystemPrompt;
+    /** User preferences — plain-text directives injected into the system prompt. */
+    preferences = {};
+    /** Preference manager for file-based persistence (optional). */
+    preferenceManager;
+    /** Lifecycle hooks for observing agent execution. */
+    hooks = {};
+    /**
+     * Trace ID of the most recent tool error waiting for LLM analysis.
+     * Set after a tool fails, cleared when the LLM's analysis is recorded. */
+    pendingErrorTraceId = null;
+    // ─── Session & Cancellation ─────────────────────────────────────────
+    /** Session manager for checkpoint persistence (optional). */
+    sessionManager;
+    /** Whether auto-checkpointing is enabled. */
+    checkpointingEnabled = false;
+    /** Abort controller for cancellation (SIGINT / user abort). */
+    abortController;
+    constructor(config) {
+        this.abortController = new AbortController();
+        this.llm = config.llm;
+        this.contextManager = config.contextManager ?? new context_manager_1.ContextManager();
+        // Prefer toolRegistry; fall back to plain tools array
+        if (config.toolRegistry) {
+            this.toolRegistry = config.toolRegistry;
+        }
+        else {
+            this.toolRegistry = new tool_registry_1.ToolRegistry(config.toolRetryCount, config.toolErrorTracker);
+            if (config.tools && config.tools.length > 0) {
+                this.toolRegistry.registerMany(config.tools);
+            }
+        }
+        // Skill manager — auto-bind the tool registry so skill tools register
+        if (config.skillManager) {
+            this.skillManager = config.skillManager;
+        }
+        else {
+            this.skillManager = new skill_manager_1.SkillManager();
+        }
+        this.skillManager.bindToolRegistry(this.toolRegistry);
+        // Register any skills passed directly
+        if (config.skills && config.skills.length > 0) {
+            this.skillManager.register(...config.skills);
+        }
+        // Register file-based skills if a directory is configured
+        if (config.skillsDir) {
+            this.skillManager.registerFromDirectory(config.skillsDir);
+        }
+        // Store core system prompt and set it
+        this.coreSystemPrompt = config.systemPrompt ?? "";
+        if (this.coreSystemPrompt) {
+            this.contextManager.setSystemMessage(this.coreSystemPrompt);
+        }
+        // Session manager — only created when session ID or session dir is provided
+        if (config.sessionId || config.sessionDir) {
+            this.sessionManager = new session_manager_1.SessionManager({
+                sessionId: config.sessionId,
+                sessionDir: config.sessionDir,
+            });
+        }
+        this.checkpointingEnabled = config.enableCheckpointing ?? false;
+        // ── Hooks ──────────────────────────────────────────────────────────────
+        this.hooks = config.hooks ?? {};
+        // ── User Preferences ─────────────────────────────────────────────────
+        this.preferenceManager = config.preferenceManager;
+        this.preferences = config.preferences ?? {};
+        // If a PreferenceManager is configured, load persisted prefs
+        // and merge with inline prefs (inline values take precedence)
+        if (this.preferenceManager) {
+            const persisted = this.preferenceManager.getAll();
+            this.preferences = { ...persisted, ...this.preferences };
+        }
+        // If preferences are non-empty, inject them into the system prompt
+        if (Object.keys(this.preferences).length > 0) {
+            this.rebuildSystemPrompt();
+        }
+    }
+    // ─── Tool Management ─────────────────────────────────────────────────
+    /**
+     * Add a tool to the agent's registry.
+     */
+    addTool(tool) {
+        this.toolRegistry.register(tool);
+    }
+    /**
+     * Get the tool registry (for advanced management).
+     */
+    getToolRegistry() {
+        return this.toolRegistry;
+    }
+    // ─── Skill Management ────────────────────────────────────────────────
+    /**
+     * Add skills to the agent's SkillManager.
+     */
+    addSkill(...skills) {
+        this.skillManager.register(...skills);
+    }
+    /**
+     * Get the SkillManager (for advanced management).
+     */
+    getSkillManager() {
+        return this.skillManager;
+    }
+    /**
+     * Activate a skill by name and rebuild the system prompt to include it.
+     *
+     * @returns true if the skill was newly activated.
+     */
+    activateSkill(name) {
+        const activated = this.skillManager.activate(name);
+        if (activated) {
+            this.rebuildSystemPrompt();
+        }
+        return activated;
+    }
+    /**
+     * Deactivate a skill and rebuild the system prompt.
+     */
+    deactivateSkill(name) {
+        const deactivated = this.skillManager.deactivate(name);
+        if (deactivated) {
+            this.rebuildSystemPrompt();
+        }
+        return deactivated;
+    }
+    /**
+     * Rebuild the system message from the core prompt + user preferences + active skills.
+     * Called automatically when skills are activated/deactivated or preferences change.
+     */
+    rebuildSystemPrompt() {
+        const prefsPrompt = preference_manager_1.PreferenceManager.toPrompt(this.preferences);
+        const skillsHint = this.skillManager.buildAvailableSkillsHint();
+        const skillsContent = this.skillManager.buildSkillsPrompt();
+        const fullPrompt = this.coreSystemPrompt + prefsPrompt + skillsHint + skillsContent;
+        this.contextManager.setSystemMessage(fullPrompt);
+    }
+    /**
+     * Pre-iteration maintenance:
+     * 1. Compress context window if needed.
+     * 2. Auto-reload preferences from disk if the file was manually edited.
+     */
+    checkAndCompress() {
+        if (this.contextManager.shouldCompress()) {
+            const { removedCount } = this.contextManager.compress();
+            console.log(`[Context] Compression triggered: removed ${removedCount} messages.`);
+        }
+        // Auto-reload preferences if the file was manually edited
+        if (this.preferenceManager?.hasFileChanged()) {
+            this.preferences = this.preferenceManager.reload();
+            this.rebuildSystemPrompt();
+            console.log("[Preferences] Reloaded from disk (file changed).");
+        }
+    }
+    // ─── Cancellation ────────────────────────────────────────────────────
+    /**
+     * Cancel the current run.
+     *
+     * This triggers the AbortSignal (passed to the LLM provider) and prevents
+     * any further checkpoint saves. Call this when the user presses SIGINT
+     * to discard the session rather than persisting it.
+     */
+    cancel() {
+        this.abortController.abort();
+    }
+    /**
+     * Whether the run has been cancelled by the user.
+     */
+    get isCancelled() {
+        return this.abortController.signal.aborted;
+    }
+    // ─── User Preferences ──────────────────────────────────────────────────
+    /**
+     * Set a single user preference and rebuild the system prompt.
+     * If a PreferenceManager is configured, the change is persisted to disk.
+     */
+    setPreference(key, value) {
+        this.preferences[key] = value;
+        this.preferenceManager?.set(key, value);
+        this.rebuildSystemPrompt();
+    }
+    /**
+     * Replace all user preferences and rebuild the system prompt.
+     * If a PreferenceManager is configured, the change is persisted to disk.
+     */
+    setPreferences(prefs) {
+        this.preferences = { ...prefs };
+        this.preferenceManager?.setAll(prefs);
+        this.rebuildSystemPrompt();
+    }
+    /**
+     * Get a single preference by key.
+     */
+    getPreference(key) {
+        return this.preferences[key];
+    }
+    /**
+     * Get all current preferences.
+     */
+    getPreferences() {
+        return { ...this.preferences };
+    }
+    /**
+     * Remove a single preference by key and rebuild the system prompt.
+     * If a PreferenceManager is configured, the change is persisted to disk.
+     */
+    removePreference(key) {
+        delete this.preferences[key];
+        this.preferenceManager?.delete(key);
+        this.rebuildSystemPrompt();
+    }
+    /**
+     * Clear all user preferences and rebuild the system prompt.
+     * If a PreferenceManager is configured, the change is persisted to disk.
+     */
+    clearPreferences() {
+        this.preferences = {};
+        this.preferenceManager?.clear();
+        this.rebuildSystemPrompt();
+    }
+    // ─── Session Persistence ─────────────────────────────────────────────
+    /**
+     * Build a base SessionState from the current agent state.
+     * Subclasses override this to include agent-specific state (e.g. plan).
+     */
+    buildBaseSessionState(status) {
+        return {
+            sessionId: this.sessionManager?.getSessionId() ?? "unknown",
+            agentType: this.getAgentType(),
+            systemPrompt: this.coreSystemPrompt,
+            messages: this.contextManager.getContextMessages(),
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            status,
+        };
+    }
+    /**
+     * Save a session checkpoint to disk (if session manager is configured
+     * and the run has NOT been cancelled).
+     */
+    saveCheckpoint(status = "active") {
+        if (!this.sessionManager)
+            return;
+        if (this.isCancelled)
+            return; // Don't save on abort
+        const state = this.buildBaseSessionState(status);
+        this.sessionManager.saveCheckpoint(state);
+    }
+    /**
+     * Restore agent state from a previously saved session.
+     *
+     * Loads the session file, restores the system prompt and message history
+     * into the context manager.
+     *
+     * @throws if the session is not found or is corrupt.
+     */
+    loadAndRestoreSession(sessionId) {
+        if (!this.sessionManager) {
+            throw new Error("Cannot resume: no SessionManager configured. " +
+                "Pass `sessionId` or `sessionDir` to the agent constructor.");
+        }
+        const state = this.sessionManager.loadSession(sessionId);
+        if (!state) {
+            throw new Error(`Session not found or corrupt: "${sessionId}"`);
+        }
+        // Validate agent type
+        const expectedType = this.getAgentType();
+        if (state.agentType !== expectedType) {
+            throw new Error(`Session "${sessionId}" was created by a ${state.agentType} agent, ` +
+                `but this agent is type "${expectedType}". Cannot resume.`);
+        }
+        // Sync session manager to the restored session ID so subsequent
+        // checkpoints write to the correct file
+        this.sessionManager.setSessionId(state.sessionId);
+        // Restore system prompt
+        this.coreSystemPrompt = state.systemPrompt;
+        this.contextManager.clear();
+        this.contextManager.setSystemMessage(state.systemPrompt);
+        // Restore all messages into context
+        for (const msg of state.messages) {
+            this.contextManager.addMessage(msg);
+        }
+        return state;
+    }
+    // ─── Conversation Lifecycle ─────────────────────────────────────────
+    /**
+     * Clear the current conversation history and reset the context.
+     *
+     * The system prompt (core prompt + preferences + skills) is preserved
+     * so the agent can start a fresh conversation with the same setup.
+     * Use this to begin a new topic without creating a new agent instance.
+     */
+    clearConversation() {
+        this.contextManager.clear();
+    }
+    /**
+     * Reset the agent to its initial state.
+     *
+     * Clears conversation history, session, and all runtime state.
+     * After calling reset(), the agent behaves as if newly constructed.
+     */
+    reset() {
+        this.contextManager.clear();
+        this.coreSystemPrompt = "";
+        this.preferences = {};
+        this.pendingErrorTraceId = null;
+        if (this.sessionManager) {
+            this.sessionManager.deleteSession(this.sessionManager.getSessionId());
+        }
+    }
+    /**
+     * Return the agent type identifier for session metadata.
+     * Subclasses override this ("react" or "plan-solve").
+     */
+    getAgentType() {
+        return "react";
+    }
+    // ─── Error Trace & Analysis ──────────────────────────────────────────
+    /**
+     * Get the error tracker (if configured via the ToolRegistry).
+     */
+    get errorTracker() {
+        return this.toolRegistry.getErrorTracker();
+    }
+    /**
+     * Call after a tool returns an error string — checks if the error
+     * indicates a tool failure (with retry guidance) and saves the trace ID
+     * so the next LLM analysis thought can be captured.
+     *
+     * @param toolName The name of the tool that failed.
+     * @param result   The string returned by ToolRegistry.execute().
+     */
+    trackToolErrorForAnalysis(toolName, result) {
+        const tracker = this.errorTracker;
+        if (!tracker)
+            return;
+        // Check if the result contains retry guidance (indicating a failure)
+        if (result.includes("[Retry Guidance]") || result.includes("has been automatically disabled")) {
+            const activeTraceId = tracker.getActiveTraceId(toolName);
+            if (activeTraceId) {
+                this.pendingErrorTraceId = activeTraceId;
+            }
+        }
+    }
+    /**
+     * Records the LLM's analysis thought against the pending tool error trace.
+     * Should be called each iteration after parsing the LLM's response.
+     *
+     * @param thought The LLM's thought/analysis content.
+     */
+    captureAnalysisFromThought(thought) {
+        if (this.pendingErrorTraceId && thought) {
+            const tracker = this.errorTracker;
+            if (tracker) {
+                tracker.recordAnalysis(this.pendingErrorTraceId, thought);
+            }
+            this.pendingErrorTraceId = null;
+        }
+    }
+    /**
+     * Generate a markdown report of all recorded tool error traces.
+     */
+    generateErrorReport() {
+        const tracker = this.errorTracker;
+        if (!tracker)
+            return "# Tool Error Trace Report\n\n*Error tracker not configured.*\n";
+        return tracker.generateMarkdownReport();
+    }
+}
+exports.Agent = Agent;
+//# sourceMappingURL=agent.js.map

package/dist/core/agent.js.map

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

package/dist/core/hooks.d.ts

@@ -0,0 +1,34 @@
+import { LLMResponse } from "../llm/interface";
+import { LLMNetworkError } from "../llm/openai-provider";
+/**
+ * Lifecycle hooks for agent execution.
+ *
+ * Each hook is called at a specific point in the agent loop, enabling
+ * consumers to add logging, tracing, metrics, or UI updates without
+ * subclassing the agent.
+ *
+ * All hooks are optional — only the ones you provide are called.
+ */
+export interface AgentHooks {
+    /** Called before each LLM chat() call. */
+    onLLMStart?: () => void;
+    /** Called after a successful LLM response. */
+    onLLMEnd?: (response: LLMResponse) => void;
+    /** Called when a network error exhausts all retries. */
+    onLLMError?: (error: LLMNetworkError) => void;
+    /** Called before a tool begins execution. */
+    onToolStart?: (toolName: string, args: Record<string, unknown>) => void;
+    /** Called after a tool returns successfully. */
+    onToolEnd?: (toolName: string, result: string) => void;
+    /** Called when a tool throws or returns an error string. */
+    onToolError?: (toolName: string, error: string) => void;
+    /** Called when the LLM produces a reasoning thought. */
+    onThought?: (thought: string) => void;
+    /** Called when an initial plan is created. */
+    onPlanCreated?: (plan: string[]) => void;
+    /** Called when the plan is revised mid-execution. */
+    onPlanRevised?: (plan: string[]) => void;
+    /** Called when a final answer is produced. */
+    onFinish?: (answer: string) => void;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/core/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/core/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IAGzB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IAExB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAE3C,wDAAwD;IACxD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAI9C,6CAA6C;IAC7C,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAExE,gDAAgD;IAChD,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEvD,4DAA4D;IAC5D,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAIxD,wDAAwD;IACxD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAItC,8CAA8C;IAC9C,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAEzC,qDAAqD;IACrD,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAIzC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC"}

package/dist/core/hooks.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=hooks.js.map

package/dist/core/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/core/hooks.ts"],"names":[],"mappings":""}

package/dist/core/plan-solve-agent.d.ts

@@ -0,0 +1,114 @@
+import { Agent, AgentConfig } from "./agent";
+import { SessionState, SessionStatus } from "../session/session-types";
+/**
+ * Configuration specific to the Plan-and-Solve Agent.
+ */
+export interface PlanSolveAgentConfig extends AgentConfig {
+    /** Maximum iterations for the Plan-Solve loop (default: 15). */
+    maxIterations?: number;
+    /** Maximum number of steps in a plan (default: 12). */
+    maxPlanSteps?: number;
+    /**
+     * Enable progressive skill disclosure.
+     * When true, skills are auto-detected from user input and loaded
+     * into the system prompt on demand (default: true).
+     */
+    enableSkillAutoDetect?: boolean;
+    /**
+     * Number of consecutive tool failures before a "replan hint" is injected
+     * into the system prompt, nudging the LLM to consider revising its plan.
+     * Set to 0 to disable auto-replan triggering (default: 2).
+     */
+    replanThreshold?: number;
+}
+/**
+ * Plan-and-Solve Agent implementing a structured Plan → Resolve → Final Answer loop.
+ *
+ * This paradigm separates high-level planning from step-by-step execution:
+ * - **Phase 1 (Plan):**  The LLM analyzes the request and creates a numbered plan.
+ * - **Phase 2 (Resolve):** The LLM executes each step, using tools. The plan is
+ *   injected into the system prompt to keep the LLM focused. If obstacles arise,
+ *   the LLM can output a `revised_plan` to adjust remaining steps.
+ * - **Final:** When all steps are complete, the LLM provides the final answer.
+ *
+ * Compared to ReAct, Plan-and-Solve encourages more deliberate decomposition
+ * up front, reducing the chance of the agent getting lost mid-task.
+ *
+ * Session persistence:
+ * When `enableCheckpointing` is set, the agent auto-saves checkpoints that
+ * include full plan state (current plan, completed steps, replan info) so the
+ * session can be resumed after a network interruption.
+ */
+export declare class PlanSolveAgent extends Agent {
+    private maxIterations;
+    private maxPlanSteps;
+    private enableSkillAutoDetect;
+    /** The current plan steps (empty until the plan is created). */
+    private currentPlan;
+    /** Whether a plan has been created in this run. */
+    private hasPlan;
+    /**
+     * How many consecutive tool failures before a replan hint is injected.
+     * 0 = disabled (no auto-replanning hints).
+     */
+    private replanThreshold;
+    /** Consecutive tool failures in the current run (resets on success). */
+    private consecutiveFailures;
+    /** How many plan steps have been completed (used for plan display). */
+    private completedSteps;
+    /** Internal flag: when true, run() skips plan state reset (used by resume()). */
+    private _skipPlanReset;
+    constructor(config: PlanSolveAgentConfig);
+    run(input: string): Promise<string>;
+    /**
+     * Agent type identifier for session metadata.
+     */
+    protected getAgentType(): "plan-solve";
+    /**
+     * Include plan state in session checkpoints.
+     */
+    protected buildBaseSessionState(status: SessionStatus): SessionState;
+    /**
+     * Restore plan state from a saved session.
+     */
+    protected loadAndRestoreSession(sessionId: string): SessionState;
+    /**
+     * Resume a previously interrupted session.
+     *
+     * Restores messages, system prompt, and plan state so the agent can
+     * continue from where it left off.
+     *
+     * @param sessionId The session ID to resume.
+     * @param input     New user input to continue the conversation.
+     */
+    resume(sessionId: string, input: string): Promise<string>;
+    /**
+     * Handle an LLMNetworkError: save an interrupted checkpoint if
+     * checkpointing is enabled, and return a user-facing message with
+     * resume instructions.
+     */
+    private handleNetworkError;
+    /**
+     * Rebuild the system prompt to include the current plan context
+     * alongside the core prompt and active skill prompts.
+     *
+     * Called each iteration so the LLM always sees the up-to-date plan.
+     *
+     * @param replanHint Optional hint injected when consecutive tool
+     *                   failures exceed the threshold, nudging the LLM
+     *                   to consider revising its plan.
+     */
+    private rebuildContextWithPlan;
+    /**
+     * Compute a replan hint based on the current consecutive failure count.
+     *
+     * When consecutive failures reach the configured threshold, a message is
+     * returned that will be appended to the system prompt, nudging the LLM
+     * to consider revising its plan rather than continuing with a failing approach.
+     *
+     * Returns undefined when no hint is needed (failures below threshold
+     * or auto-replan is disabled).
+     */
+    private computeReplanHint;
+}
+//# sourceMappingURL=plan-solve-agent.d.ts.map

package/dist/core/plan-solve-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-solve-agent.d.ts","sourceRoot":"","sources":["../../src/core/plan-solve-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAQ7C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAqCvE;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,qBAAqB,CAAU;IAEvC,gEAAgE;IAChE,OAAO,CAAC,WAAW,CAAgB;IAEnC,mDAAmD;IACnD,OAAO,CAAC,OAAO,CAAS;IAExB;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAS;IAEhC,wEAAwE;IACxE,OAAO,CAAC,mBAAmB,CAAK;IAEhC,uEAAuE;IACvE,OAAO,CAAC,cAAc,CAAK;IAE3B,iFAAiF;IACjF,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,EAAE,oBAAoB;IAoBlC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwRzC;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,YAAY;IAItC;;OAEG;IACH,SAAS,CAAC,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY;IAapE;;OAEG;IACH,SAAS,CAAC,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;IAehE;;;;;;;;OAQG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAS/D;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAsC9B;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;CAc1B"}