@lleverage-ai/agent-sdk 0.0.1

package/dist/tools/skills.js

@@ -0,0 +1,413 @@
+/**
+ * Skill tool for progressive disclosure of capabilities.
+ *
+ * The skill tool allows agents to load skills (tools + prompts) on-demand
+ * based on conversation context. This keeps the initial context small and
+ * focused, expanding capabilities only as needed.
+ *
+ * @packageDocumentation
+ */
+import { tool } from "ai";
+import { z } from "zod";
+// =============================================================================
+// Skill Registry
+// =============================================================================
+/**
+ * Registry for managing loadable skills.
+ *
+ * The registry tracks available skills and which ones have been loaded.
+ * Skills are loaded on-demand by the agent using the skill tool.
+ *
+ * @example
+ * ```typescript
+ * const registry = new SkillRegistry({
+ *   skills: [gitSkill, dockerSkill],
+ * });
+ *
+ * // Register more skills later
+ * registry.register(kubernetesSkill);
+ *
+ * // Check available skills
+ * const available = registry.listAvailable();
+ *
+ * // Load a skill
+ * const result = registry.load("git");
+ * ```
+ *
+ * @category Tools
+ */
+export class SkillRegistry {
+    /** All registered skills */
+    skills = new Map();
+    /** Currently loaded skills */
+    loadedSkills = new Set();
+    /** Callback for skill load events */
+    onSkillLoaded;
+    /** MCP manager for loading MCP tools */
+    mcpManager;
+    /**
+     * Creates a new skill registry.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options = {}) {
+        this.onSkillLoaded = options.onSkillLoaded;
+        this.mcpManager = options.mcpManager;
+        if (options.skills) {
+            for (const skill of options.skills) {
+                this.register(skill);
+            }
+        }
+    }
+    /**
+     * Register a skill with the registry.
+     *
+     * @param skill - The skill definition to register
+     * @throws Error if a skill with the same name is already registered
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   name: "aws",
+     *   description: "AWS cloud operations",
+     *   tools: { ... },
+     *   prompt: "You now have access to AWS tools.",
+     * });
+     * ```
+     */
+    register(skill) {
+        if (this.skills.has(skill.name)) {
+            throw new Error(`Skill '${skill.name}' is already registered`);
+        }
+        this.skills.set(skill.name, skill);
+    }
+    /**
+     * Unregister a skill from the registry.
+     *
+     * @param name - The name of the skill to unregister
+     * @returns True if the skill was found and removed
+     */
+    unregister(name) {
+        this.loadedSkills.delete(name);
+        return this.skills.delete(name);
+    }
+    /**
+     * Check if a skill is registered.
+     *
+     * @param name - The name of the skill to check
+     * @returns True if the skill is registered
+     */
+    has(name) {
+        return this.skills.has(name);
+    }
+    /**
+     * Check if a skill is currently loaded.
+     *
+     * @param name - The name of the skill to check
+     * @returns True if the skill is loaded
+     */
+    isLoaded(name) {
+        return this.loadedSkills.has(name);
+    }
+    /**
+     * Get a registered skill definition.
+     *
+     * @param name - The name of the skill
+     * @returns The skill definition or undefined if not found
+     */
+    get(name) {
+        return this.skills.get(name);
+    }
+    /**
+     * Load a skill, making its tools and prompt available.
+     *
+     * This method handles dependencies, loading them first if specified.
+     * Already-loaded skills are skipped (no duplicate loading).
+     *
+     * @param name - The name of the skill to load
+     * @param args - Optional arguments to pass to the skill's prompt function
+     * @returns The load result with tools, prompt, and status
+     *
+     * @example
+     * ```typescript
+     * const result = registry.load("git");
+     * if (result.success) {
+     *   // Inject result.tools into agent
+     *   // Inject result.prompt into context
+     * }
+     * ```
+     */
+    load(name, args) {
+        // Check if already loaded
+        if (this.loadedSkills.has(name)) {
+            return {
+                success: true,
+                tools: {},
+                prompt: "",
+                error: `Skill '${name}' is already loaded`,
+            };
+        }
+        // Check if skill exists
+        const skill = this.skills.get(name);
+        if (!skill) {
+            return {
+                success: false,
+                tools: {},
+                prompt: "",
+                error: `Skill '${name}' not found. Available: ${this.listAvailable()
+                    .map((s) => s.name)
+                    .join(", ")}`,
+            };
+        }
+        // Load dependencies first
+        const loadedDependencies = [];
+        const aggregatedTools = {};
+        let aggregatedPrompt = "";
+        if (skill.dependencies && skill.dependencies.length > 0) {
+            for (const depName of skill.dependencies) {
+                if (this.loadedSkills.has(depName)) {
+                    continue; // Skip already loaded dependencies
+                }
+                const depResult = this.load(depName);
+                if (!depResult.success) {
+                    return {
+                        success: false,
+                        tools: {},
+                        prompt: "",
+                        error: `Failed to load dependency '${depName}': ${depResult.error}`,
+                    };
+                }
+                // Aggregate dependency tools and prompts
+                Object.assign(aggregatedTools, depResult.tools);
+                if (depResult.prompt) {
+                    aggregatedPrompt += `${depResult.prompt}\n\n`;
+                }
+                loadedDependencies.push(depName);
+            }
+        }
+        // Mark as loaded
+        this.loadedSkills.add(name);
+        // Track MCP tool loading results
+        let loadedMcpTools;
+        let notFoundMcpTools;
+        // Load MCP tools if specified
+        if (skill.mcpTools && skill.mcpTools.length > 0 && this.mcpManager) {
+            const mcpLoadResult = this.mcpManager.loadTools(skill.mcpTools);
+            if (mcpLoadResult.loaded.length > 0 || mcpLoadResult.alreadyLoaded.length > 0) {
+                loadedMcpTools = [...mcpLoadResult.loaded, ...mcpLoadResult.alreadyLoaded];
+            }
+            if (mcpLoadResult.notFound.length > 0) {
+                notFoundMcpTools = mcpLoadResult.notFound;
+                // Log warning but continue - some MCP tools may be unavailable
+                console.warn(`Skill '${name}': Some MCP tools not found: ${mcpLoadResult.notFound.join(", ")}`);
+            }
+        }
+        // Get the prompt
+        const prompt = typeof skill.prompt === "function" ? skill.prompt(args) : skill.prompt;
+        // Build result - MCP tools are loaded via MCPManager, not returned directly
+        const result = {
+            success: true,
+            tools: { ...aggregatedTools, ...skill.tools },
+            prompt: aggregatedPrompt + prompt,
+            loadedDependencies: loadedDependencies.length > 0 ? loadedDependencies : undefined,
+            loadedMcpTools,
+            notFoundMcpTools,
+        };
+        // Notify callback
+        if (this.onSkillLoaded) {
+            this.onSkillLoaded(name, result);
+        }
+        return result;
+    }
+    /**
+     * List skills that are available but not yet loaded.
+     *
+     * @returns Array of skill summaries (name and description)
+     */
+    listAvailable() {
+        const available = [];
+        for (const [name, skill] of this.skills) {
+            if (!this.loadedSkills.has(name)) {
+                available.push({
+                    name,
+                    description: skill.description,
+                });
+            }
+        }
+        return available;
+    }
+    /**
+     * List all loaded skills.
+     *
+     * @returns Array of loaded skill names
+     */
+    listLoaded() {
+        return Array.from(this.loadedSkills);
+    }
+    /**
+     * List all registered skills (loaded and available).
+     *
+     * @returns Array of all skill summaries
+     */
+    listAll() {
+        const all = [];
+        for (const [name, skill] of this.skills) {
+            all.push({
+                name,
+                description: skill.description,
+                loaded: this.loadedSkills.has(name),
+            });
+        }
+        return all;
+    }
+    /**
+     * Reset the registry, marking all skills as unloaded.
+     *
+     * This does not unregister skills, only resets the loaded state.
+     */
+    reset() {
+        this.loadedSkills.clear();
+    }
+    /**
+     * Get the number of registered skills.
+     */
+    get size() {
+        return this.skills.size;
+    }
+    /**
+     * Get the number of loaded skills.
+     */
+    get loadedCount() {
+        return this.loadedSkills.size;
+    }
+}
+/**
+ * Creates a tool that allows agents to load skills on-demand.
+ *
+ * The tool's description dynamically lists available (not yet loaded) skills,
+ * so the agent can decide which skill to load based on the conversation.
+ *
+ * @param options - Configuration options
+ * @returns An AI SDK compatible tool for loading skills
+ *
+ * @example
+ * ```typescript
+ * import { createSkillTool, SkillRegistry } from "@lleverage-ai/agent-sdk";
+ *
+ * const registry = new SkillRegistry({
+ *   skills: [gitSkill, dockerSkill],
+ * });
+ *
+ * const skillTool = createSkillTool({ registry });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: { load_skill: skillTool },
+ * });
+ *
+ * // Agent can now invoke load_skill to gain new capabilities
+ * ```
+ *
+ * @category Tools
+ */
+export function createSkillTool(options) {
+    const { registry, descriptionPrefix } = options;
+    // Build dynamic description based on available skills
+    const buildDescription = () => {
+        const available = registry.listAvailable();
+        if (available.length === 0) {
+            return "No skills available to load.";
+        }
+        const prefix = descriptionPrefix ??
+            "Load a skill to gain additional capabilities. After loading, new tools and instructions become available.";
+        const skillList = available.map((s) => `- ${s.name}: ${s.description}`).join("\n");
+        return `${prefix}\n\nAvailable skills:\n${skillList}`;
+    };
+    return tool({
+        description: buildDescription(),
+        inputSchema: z.object({
+            skill_name: z.string().describe("Name of the skill to load"),
+            args: z.string().optional().describe("Optional arguments to pass to the skill"),
+        }),
+        execute: async ({ skill_name, args }) => {
+            const result = registry.load(skill_name, args);
+            if (!result.success) {
+                return {
+                    success: false,
+                    error: result.error,
+                };
+            }
+            // Format the response
+            const toolNames = Object.keys(result.tools);
+            const response = {
+                success: true,
+                skill: skill_name,
+                newTools: toolNames,
+                instructions: result.prompt,
+            };
+            if (result.loadedDependencies && result.loadedDependencies.length > 0) {
+                response.dependencies = result.loadedDependencies;
+            }
+            if (toolNames.length === 0) {
+                response.message = `Loaded skill '${skill_name}' (provides instructions only, no new tools)`;
+            }
+            else {
+                response.message = `Loaded skill '${skill_name}'. New tools available: ${toolNames.join(", ")}`;
+            }
+            return response;
+        },
+    });
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Creates a new skill registry with the given skills.
+ *
+ * This is a convenience function for creating a SkillRegistry instance.
+ *
+ * @param skills - Initial skills to register
+ * @param options - Additional options
+ * @returns A new SkillRegistry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = createSkillRegistry([gitSkill, dockerSkill]);
+ * ```
+ *
+ * @category Tools
+ */
+export function createSkillRegistry(skills, options) {
+    return new SkillRegistry({
+        ...options,
+        skills,
+    });
+}
+/**
+ * Creates a skill definition.
+ *
+ * This is a helper function for creating LoadableSkillDefinition objects
+ * with proper typing.
+ *
+ * @param options - Skill configuration
+ * @returns A LoadableSkillDefinition object
+ *
+ * @example
+ * ```typescript
+ * const gitSkill = defineLoadableSkill({
+ *   name: "git",
+ *   description: "Git version control operations",
+ *   tools: {
+ *     git_status: tool({ ... }),
+ *     git_commit: tool({ ... }),
+ *   },
+ *   prompt: "You now have access to Git tools.",
+ * });
+ * ```
+ *
+ * @category Tools
+ */
+export function defineLoadableSkill(options) {
+    return options;
+}
+//# sourceMappingURL=skills.js.map

package/dist/tools/skills.js.map

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

package/dist/tools/task.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Task tool for delegating work to specialized subagents.
+ *
+ * Provides a single `task` tool for spawning subagents, similar to Claude Code's
+ * Task tool. Supports both foreground and background execution, as well as
+ * streaming subagents that can write to the parent's data stream.
+ *
+ * @packageDocumentation
+ */
+import type { LanguageModel, Tool } from "ai";
+import type { BackgroundTask, BaseTaskStore } from "../task-store/index.js";
+import type { Agent, StreamingContext, SubagentDefinition } from "../types.js";
+/**
+ * Status of a background task.
+ *
+ * @category Subagents
+ */
+export type TaskStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * Options for creating the task tool.
+ *
+ * @category Subagents
+ */
+export interface TaskToolOptions {
+    /** Available subagent definitions */
+    subagents: SubagentDefinition[];
+    /** Default model for subagents that don't specify one */
+    defaultModel: LanguageModel;
+    /** Parent agent for creating subagents */
+    parentAgent: Agent;
+    /** Custom tool description */
+    description?: string;
+    /** Default max turns for subagents */
+    defaultMaxTurns?: number;
+    /** Include a general-purpose subagent automatically */
+    includeGeneralPurpose?: boolean;
+    /** Model to use for general-purpose subagent */
+    generalPurposeModel?: LanguageModel;
+    /** System prompt for general-purpose subagent */
+    generalPurposePrompt?: string;
+    /**
+     * Streaming context from the parent agent.
+     *
+     * When provided, streaming subagents (those with `streaming: true`) can
+     * write custom data directly to the parent's data stream. This enables
+     * progressive rendering, real-time updates, and structured data streaming.
+     *
+     * Typically set when the parent agent is using `streamDataResponse()`.
+     *
+     * @example
+     * ```typescript
+     * // In agent.ts streamDataResponse
+     * const streamingContext: StreamingContext = { writer };
+     * const task = createTaskTool({
+     *   subagents,
+     *   defaultModel,
+     *   parentAgent,
+     *   streamingContext, // Pass to enable streaming subagents
+     * });
+     * ```
+     */
+    streamingContext?: StreamingContext;
+    /**
+     * Task store for persisting background task state.
+     *
+     * When provided, background tasks will be persisted and can be recovered
+     * across process restarts. Without a task store, tasks are kept in memory
+     * only and lost when the process exits.
+     *
+     * @example
+     * ```typescript
+     * import { FileTaskStore } from "@lleverage-ai/agent-sdk/task-store";
+     *
+     * const taskStore = new FileTaskStore({
+     *   directory: "./task-data",
+     *   expirationMs: 86400000, // 24 hours
+     * });
+     *
+     * const task = createTaskTool({
+     *   subagents,
+     *   defaultModel,
+     *   parentAgent,
+     *   taskStore, // Tasks now persist across restarts
+     * });
+     * ```
+     */
+    taskStore?: BaseTaskStore;
+    /**
+     * Parent span context for distributed tracing.
+     *
+     * When provided, subagents will create child spans linked to this parent
+     * span, enabling cross-agent trace correlation. This allows full request
+     * tracing across parent and child agents in distributed tracing systems.
+     *
+     * @example
+     * ```typescript
+     * import { createTracer } from "@lleverage-ai/agent-sdk";
+     *
+     * const tracer = createTracer({ name: "parent-agent" });
+     * const span = tracer.startSpan("handle-request");
+     *
+     * const task = createTaskTool({
+     *   subagents,
+     *   defaultModel,
+     *   parentAgent,
+     *   parentSpanContext: {
+     *     traceId: span.traceId,
+     *     spanId: span.spanId,
+     *   },
+     * });
+     * ```
+     */
+    parentSpanContext?: import("../observability/tracing.js").SpanContext;
+}
+/**
+ * Get a background task by ID.
+ *
+ * @param taskId - The task ID
+ * @returns The tracked task or undefined
+ *
+ * @category Subagents
+ */
+export declare function getBackgroundTask(taskId: string): Promise<BackgroundTask | undefined>;
+/**
+ * List all background tasks.
+ *
+ * @param filter - Optional filter by status
+ * @returns Array of all tracked tasks
+ *
+ * @category Subagents
+ */
+export declare function listBackgroundTasks(filter?: {
+    status?: TaskStatus | TaskStatus[];
+}): Promise<BackgroundTask[]>;
+/**
+ * Clear completed/failed background tasks.
+ *
+ * Removes tasks older than the expiration time (if using task store)
+ * or all completed/failed tasks (if using in-memory storage).
+ *
+ * @returns Number of tasks cleared
+ *
+ * @category Subagents
+ */
+export declare function clearCompletedTasks(): Promise<number>;
+/**
+ * Recover running tasks on agent restart.
+ *
+ * When using a task store, this function loads all "running" tasks
+ * and marks them as "failed" since they were interrupted by the restart.
+ *
+ * Call this function when initializing your agent to handle crashed tasks.
+ *
+ * @param store - Optional task store to use. If not provided, uses the global task store.
+ * @returns Number of tasks recovered
+ *
+ * @category Subagents
+ * @example
+ * ```typescript
+ * // On agent startup
+ * const recovered = await recoverRunningTasks();
+ * console.log(`Recovered ${recovered} interrupted tasks`);
+ * ```
+ */
+export declare function recoverRunningTasks(store?: BaseTaskStore): Promise<number>;
+/**
+ * Recover failed tasks for retry.
+ *
+ * Loads all "failed" tasks from the store and returns them for inspection
+ * or automatic retry. Applications can decide which tasks to retry based
+ * on error type, retry count, or other criteria.
+ *
+ * To retry a task, update its status back to "pending" and process it
+ * through your task execution logic.
+ *
+ * @param store - The task store to query
+ * @param options - Optional filter options
+ * @returns Array of failed tasks
+ *
+ * @category Subagents
+ * @example
+ * ```typescript
+ * // Load failed tasks and retry those with transient errors
+ * const failedTasks = await recoverFailedTasks(taskStore);
+ *
+ * for (const task of failedTasks) {
+ *   // Check if error is retryable
+ *   if (task.error?.includes("timeout") || task.error?.includes("network")) {
+ *     // Mark for retry
+ *     const retryTask = updateBackgroundTask(task, {
+ *       status: "pending",
+ *       error: undefined,
+ *     });
+ *     await taskStore.save(retryTask);
+ *   }
+ * }
+ * ```
+ */
+export declare function recoverFailedTasks(store: BaseTaskStore, options?: {
+    /** Only return tasks with errors matching this pattern */
+    errorPattern?: RegExp;
+    /** Only return tasks newer than this timestamp */
+    minCreatedAt?: Date;
+    /** Only return tasks older than this timestamp */
+    maxCreatedAt?: Date;
+}): Promise<BackgroundTask[]>;
+/**
+ * Clean up stale tasks from the task store.
+ *
+ * Removes tasks that have been in a terminal state (completed or failed)
+ * for longer than the specified age. This prevents unbounded storage growth
+ * and maintains system health.
+ *
+ * @param store - The task store to clean
+ * @param maxAge - Maximum age in milliseconds for terminal tasks
+ * @returns Number of tasks cleaned up
+ *
+ * @category Subagents
+ * @example
+ * ```typescript
+ * // Clean up tasks older than 7 days
+ * const sevenDays = 7 * 24 * 60 * 60 * 1000;
+ * const cleaned = await cleanupStaleTasks(taskStore, sevenDays);
+ * console.log(`Cleaned up ${cleaned} stale tasks`);
+ *
+ * // Or use a shorter retention for testing
+ * const oneHour = 60 * 60 * 1000;
+ * await cleanupStaleTasks(taskStore, oneHour);
+ * ```
+ */
+export declare function cleanupStaleTasks(store: BaseTaskStore, maxAge: number): Promise<number>;
+/**
+ * Creates the task tool for delegating work to specialized subagents.
+ *
+ * This tool delegates tasks to subagents with isolated context. It supports
+ * both foreground (blocking) and background execution.
+ *
+ * @param options - Configuration options
+ * @returns An AI SDK tool for task delegation
+ *
+ * @example
+ * ```typescript
+ * import { createTaskTool } from "@lleverage-ai/agent-sdk";
+ *
+ * const task = createTaskTool({
+ *   subagents: [
+ *     {
+ *       type: "researcher",
+ *       description: "Searches for information",
+ *       create: () => createSubagent(parentAgent, { ... }),
+ *     },
+ *     {
+ *       type: "coder",
+ *       description: "Writes and modifies code",
+ *       create: () => createSubagent(parentAgent, { ... }),
+ *     },
+ *   ],
+ *   defaultModel: anthropic("claude-sonnet-4-20250514"),
+ *   parentAgent,
+ *   includeGeneralPurpose: true,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   tools: { task },
+ * });
+ * ```
+ *
+ * @category Subagents
+ */
+export declare function createTaskTool(options: TaskToolOptions): Tool;
+//# sourceMappingURL=task.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/tools/task.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAI9C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5E,OAAO,KAAK,EACV,KAAK,EACL,gBAAgB,EAGhB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAMrB;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAExE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,yDAAyD;IACzD,YAAY,EAAE,aAAa,CAAC;IAC5B,0CAA0C;IAC1C,WAAW,EAAE,KAAK,CAAC;IACnB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,gDAAgD;IAChD,mBAAmB,CAAC,EAAE,aAAa,CAAC;IACpC,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAE1B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,iBAAiB,CAAC,EAAE,OAAO,6BAA6B,EAAE,WAAW,CAAC;CACvE;AAyBD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAK3F;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,CAAC,EAAE;IACjD,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAa5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAc3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE;IACR,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,YAAY,CAAC,EAAE,IAAI,CAAC;IACpB,kDAAkD;IAClD,YAAY,CAAC,EAAE,IAAI,CAAC;CACrB,GACA,OAAO,CAAC,cAAc,EAAE,CAAC,CAsB3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB7F;AAoCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CA0R7D"}