@lleverage-ai/agent-sdk 0.0.1

package/dist/task-store/kv-store.js

@@ -0,0 +1,169 @@
+/**
+ * Key-value store task implementation.
+ *
+ * Stores tasks in a key-value store (Redis, DynamoDB, etc.).
+ * Provides persistence with fast access.
+ *
+ * @packageDocumentation
+ */
+import { isBackgroundTask, shouldExpireTask } from "./types.js";
+/**
+ * Key-value store implementation of the task store.
+ *
+ * Stores tasks in a key-value store (Redis, DynamoDB, etc.).
+ * Requires a KeyValueStore implementation.
+ *
+ * @example
+ * ```typescript
+ * // Using Redis
+ * import { createClient } from "redis";
+ *
+ * const redisClient = createClient();
+ * await redisClient.connect();
+ *
+ * const kvStore: KeyValueStore = {
+ *   async get(key) {
+ *     return redisClient.get(key);
+ *   },
+ *   async set(key, value, options) {
+ *     if (options?.ttl) {
+ *       await redisClient.setEx(key, options.ttl, value);
+ *     } else {
+ *       await redisClient.set(key, value);
+ *     }
+ *   },
+ *   async delete(key) {
+ *     const result = await redisClient.del(key);
+ *     return result > 0;
+ *   },
+ *   async exists(key) {
+ *     const result = await redisClient.exists(key);
+ *     return result > 0;
+ *   },
+ *   async keys(pattern) {
+ *     return redisClient.keys(pattern);
+ *   },
+ * };
+ *
+ * const store = new KVTaskStore(kvStore, {
+ *   namespace: "myapp",
+ * });
+ * ```
+ *
+ * @category TaskStore
+ */
+export class KVTaskStore {
+    kv;
+    namespace;
+    expirationMs;
+    /**
+     * Create a new KV-based task store.
+     *
+     * @param kv - The key-value store implementation
+     * @param options - Configuration options
+     */
+    constructor(kv, options = {}) {
+        this.kv = kv;
+        this.namespace = options.namespace;
+        this.expirationMs = options.expirationMs ?? 86400000; // 24 hours default
+    }
+    /**
+     * Get the storage key for a task ID.
+     * @internal
+     */
+    getKey(taskId) {
+        return this.namespace ? `${this.namespace}:task:${taskId}` : `task:${taskId}`;
+    }
+    /**
+     * Get the task ID from a storage key.
+     * @internal
+     */
+    getTaskIdFromKey(key) {
+        const prefix = this.namespace ? `${this.namespace}:task:` : "task:";
+        if (key.startsWith(prefix)) {
+            return key.slice(prefix.length);
+        }
+        return null;
+    }
+    /**
+     * Get the key pattern for listing tasks.
+     * @internal
+     */
+    getKeyPattern() {
+        return this.namespace ? `${this.namespace}:task:*` : "task:*";
+    }
+    async save(task) {
+        const key = this.getKey(task.id);
+        const data = JSON.stringify(task);
+        await this.kv.set(key, data);
+    }
+    async load(taskId) {
+        const key = this.getKey(taskId);
+        const data = await this.kv.get(key);
+        if (!data) {
+            return undefined;
+        }
+        try {
+            const task = JSON.parse(data);
+            if (!isBackgroundTask(task)) {
+                console.warn(`Invalid task data for key ${key}, skipping`);
+                return undefined;
+            }
+            return task;
+        }
+        catch (error) {
+            console.warn(`Failed to parse task data for key ${key}:`, error);
+            return undefined;
+        }
+    }
+    async list(filter) {
+        const tasks = await this.listTasks(filter);
+        return tasks.map((t) => t.id);
+    }
+    async listTasks(filter) {
+        const pattern = this.getKeyPattern();
+        const keys = await this.kv.keys(pattern);
+        const tasks = [];
+        for (const key of keys) {
+            const taskId = this.getTaskIdFromKey(key);
+            if (!taskId) {
+                continue;
+            }
+            const task = await this.load(taskId);
+            if (!task) {
+                continue;
+            }
+            // Apply status filter if provided
+            if (filter?.status) {
+                const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+                if (!statuses.includes(task.status)) {
+                    continue;
+                }
+            }
+            tasks.push(task);
+        }
+        return tasks;
+    }
+    async delete(taskId) {
+        const key = this.getKey(taskId);
+        return this.kv.delete(key);
+    }
+    async exists(taskId) {
+        const key = this.getKey(taskId);
+        return this.kv.exists(key);
+    }
+    async cleanup() {
+        const allTasks = await this.listTasks({
+            status: ["completed", "failed"],
+        });
+        let cleaned = 0;
+        for (const task of allTasks) {
+            if (shouldExpireTask(task, this.expirationMs)) {
+                await this.delete(task.id);
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
+}
+//# sourceMappingURL=kv-store.js.map

package/dist/task-store/kv-store.js.map

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

package/dist/task-store/memory-store.d.ts

@@ -0,0 +1,66 @@
+/**
+ * In-memory task store implementation.
+ *
+ * Stores tasks in a Map. Tasks are lost when the process exits.
+ * Useful for development, testing, or scenarios where persistence isn't needed.
+ *
+ * @packageDocumentation
+ */
+import type { BackgroundTask, BackgroundTaskStatus, BaseTaskStore, TaskStoreOptions } from "./types.js";
+/**
+ * In-memory implementation of the task store.
+ *
+ * Stores tasks in a Map in memory. All tasks are lost when the process exits.
+ *
+ * @example
+ * ```typescript
+ * const store = new MemoryTaskStore();
+ *
+ * await store.save({
+ *   id: "task-123",
+ *   subagentType: "researcher",
+ *   description: "Research topic",
+ *   status: "running",
+ *   createdAt: new Date().toISOString(),
+ *   updatedAt: new Date().toISOString(),
+ * });
+ *
+ * const task = await store.load("task-123");
+ * ```
+ *
+ * @category TaskStore
+ */
+export declare class MemoryTaskStore implements BaseTaskStore {
+    private tasks;
+    private namespace?;
+    private expirationMs;
+    /**
+     * Create a new in-memory task store.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: TaskStoreOptions);
+    /**
+     * Get the storage key for a task ID.
+     * @internal
+     */
+    private getKey;
+    save(task: BackgroundTask): Promise<void>;
+    load(taskId: string): Promise<BackgroundTask | undefined>;
+    list(filter?: {
+        status?: BackgroundTaskStatus | BackgroundTaskStatus[];
+    }): Promise<string[]>;
+    listTasks(filter?: {
+        status?: BackgroundTaskStatus | BackgroundTaskStatus[];
+    }): Promise<BackgroundTask[]>;
+    delete(taskId: string): Promise<boolean>;
+    exists(taskId: string): Promise<boolean>;
+    cleanup(): Promise<number>;
+    /**
+     * Clear all tasks from the store.
+     *
+     * Useful for testing.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/task-store/memory-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/task-store/memory-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAGpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAgB,YAAW,aAAa;IACnD,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAS;IAE7B;;;;OAIG;gBACS,OAAO,GAAE,gBAAqB;IAK1C;;;OAGG;IACH,OAAO,CAAC,MAAM;IAIR,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAMzD,IAAI,CAAC,MAAM,CAAC,EAAE;QAClB,MAAM,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,CAAC;KACxD,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKf,SAAS,CAAC,MAAM,CAAC,EAAE;QACvB,MAAM,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,CAAC;KACxD,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAwBvB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKxC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAgBhC;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAYd"}

package/dist/task-store/memory-store.js

@@ -0,0 +1,125 @@
+/**
+ * In-memory task store implementation.
+ *
+ * Stores tasks in a Map. Tasks are lost when the process exits.
+ * Useful for development, testing, or scenarios where persistence isn't needed.
+ *
+ * @packageDocumentation
+ */
+import { shouldExpireTask } from "./types.js";
+/**
+ * In-memory implementation of the task store.
+ *
+ * Stores tasks in a Map in memory. All tasks are lost when the process exits.
+ *
+ * @example
+ * ```typescript
+ * const store = new MemoryTaskStore();
+ *
+ * await store.save({
+ *   id: "task-123",
+ *   subagentType: "researcher",
+ *   description: "Research topic",
+ *   status: "running",
+ *   createdAt: new Date().toISOString(),
+ *   updatedAt: new Date().toISOString(),
+ * });
+ *
+ * const task = await store.load("task-123");
+ * ```
+ *
+ * @category TaskStore
+ */
+export class MemoryTaskStore {
+    tasks = new Map();
+    namespace;
+    expirationMs;
+    /**
+     * Create a new in-memory task store.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options = {}) {
+        this.namespace = options.namespace;
+        this.expirationMs = options.expirationMs ?? 86400000; // 24 hours default
+    }
+    /**
+     * Get the storage key for a task ID.
+     * @internal
+     */
+    getKey(taskId) {
+        return this.namespace ? `${this.namespace}:${taskId}` : taskId;
+    }
+    async save(task) {
+        const key = this.getKey(task.id);
+        this.tasks.set(key, { ...task });
+    }
+    async load(taskId) {
+        const key = this.getKey(taskId);
+        const task = this.tasks.get(key);
+        return task ? { ...task } : undefined;
+    }
+    async list(filter) {
+        const tasks = await this.listTasks(filter);
+        return tasks.map((t) => t.id);
+    }
+    async listTasks(filter) {
+        const prefix = this.namespace ? `${this.namespace}:` : "";
+        const tasks = [];
+        for (const [key, task] of this.tasks) {
+            // Skip if not in our namespace
+            if (prefix && !key.startsWith(prefix)) {
+                continue;
+            }
+            // Apply status filter if provided
+            if (filter?.status) {
+                const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+                if (!statuses.includes(task.status)) {
+                    continue;
+                }
+            }
+            tasks.push({ ...task });
+        }
+        return tasks;
+    }
+    async delete(taskId) {
+        const key = this.getKey(taskId);
+        return this.tasks.delete(key);
+    }
+    async exists(taskId) {
+        const key = this.getKey(taskId);
+        return this.tasks.has(key);
+    }
+    async cleanup() {
+        const allTasks = await this.listTasks({
+            status: ["completed", "failed"],
+        });
+        let cleaned = 0;
+        for (const task of allTasks) {
+            if (shouldExpireTask(task, this.expirationMs)) {
+                await this.delete(task.id);
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
+    /**
+     * Clear all tasks from the store.
+     *
+     * Useful for testing.
+     */
+    clear() {
+        if (this.namespace) {
+            const prefix = `${this.namespace}:`;
+            for (const key of this.tasks.keys()) {
+                if (key.startsWith(prefix)) {
+                    this.tasks.delete(key);
+                }
+            }
+        }
+        else {
+            this.tasks.clear();
+        }
+    }
+}
+//# sourceMappingURL=memory-store.js.map

package/dist/task-store/memory-store.js.map

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

package/dist/task-store/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Type definitions for the task store system.
+ *
+ * Task stores provide persistence for background task state, allowing tasks
+ * to survive process restarts and be recovered when the agent resumes.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Status of a background task.
+ *
+ * - `pending`: Task created but not yet started
+ * - `running`: Task is currently executing
+ * - `completed`: Task finished successfully
+ * - `failed`: Task encountered an error
+ *
+ * @category TaskStore
+ */
+export type BackgroundTaskStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * Complete snapshot of a background task's state.
+ *
+ * A background task captures the execution state of an async subagent,
+ * including:
+ * - Task metadata (ID, type, description)
+ * - Current status and timestamps
+ * - Result or error information
+ * - Optional metadata for custom data
+ *
+ * @example
+ * ```typescript
+ * const task: BackgroundTask = {
+ *   id: "task-123",
+ *   subagentType: "researcher",
+ *   description: "Research TypeScript history",
+ *   status: "running",
+ *   createdAt: "2026-01-30T10:00:00Z",
+ *   updatedAt: "2026-01-30T10:05:00Z",
+ * };
+ * ```
+ *
+ * @category TaskStore
+ */
+export interface BackgroundTask {
+    /** Unique identifier for this task */
+    id: string;
+    /** Type of subagent handling this task */
+    subagentType: string;
+    /** Task description/prompt */
+    description: string;
+    /** Current status */
+    status: BackgroundTaskStatus;
+    /** ISO 8601 timestamp when this task was created */
+    createdAt: string;
+    /** ISO 8601 timestamp when this task was last updated */
+    updatedAt: string;
+    /** ISO 8601 timestamp when this task completed (if completed/failed) */
+    completedAt?: string;
+    /** Result text (when completed) */
+    result?: string;
+    /** Error message (when failed) */
+    error?: string;
+    /** Optional metadata for custom data */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for creating a task store.
+ *
+ * @category TaskStore
+ */
+export interface TaskStoreOptions {
+    /**
+     * Namespace for isolating tasks.
+     *
+     * Useful for multi-tenant scenarios where different users or sessions
+     * need separate task storage.
+     *
+     * @defaultValue undefined (no namespace)
+     */
+    namespace?: string;
+    /**
+     * Task expiration time in milliseconds.
+     *
+     * Completed/failed tasks older than this will be automatically cleaned up.
+     *
+     * @defaultValue 86400000 (24 hours)
+     */
+    expirationMs?: number;
+}
+/**
+ * Abstract storage interface for background tasks.
+ *
+ * Implement this interface to create custom task storage backends
+ * such as Redis, SQLite, cloud storage, or any other persistence layer.
+ *
+ * @example
+ * ```typescript
+ * class RedisTaskStore implements BaseTaskStore {
+ *   constructor(private redis: RedisClient) {}
+ *
+ *   async save(task: BackgroundTask): Promise<void> {
+ *     const key = `task:${task.id}`;
+ *     await this.redis.set(key, JSON.stringify(task));
+ *   }
+ *
+ *   async load(taskId: string): Promise<BackgroundTask | undefined> {
+ *     const key = `task:${taskId}`;
+ *     const data = await this.redis.get(key);
+ *     return data ? JSON.parse(data) : undefined;
+ *   }
+ *
+ *   // ... other methods
+ * }
+ * ```
+ *
+ * @category TaskStore
+ */
+export interface BaseTaskStore {
+    /**
+     * Save a task.
+     *
+     * If a task with the same `id` exists, it should be updated.
+     *
+     * @param task - The task to save
+     */
+    save(task: BackgroundTask): Promise<void>;
+    /**
+     * Load a task by ID.
+     *
+     * @param taskId - The unique task identifier
+     * @returns The task if found, undefined otherwise
+     */
+    load(taskId: string): Promise<BackgroundTask | undefined>;
+    /**
+     * List all task IDs.
+     *
+     * @param filter - Optional filter by status
+     * @returns Array of task IDs
+     */
+    list(filter?: {
+        status?: BackgroundTaskStatus | BackgroundTaskStatus[];
+    }): Promise<string[]>;
+    /**
+     * List all tasks.
+     *
+     * @param filter - Optional filter by status
+     * @returns Array of tasks
+     */
+    listTasks(filter?: {
+        status?: BackgroundTaskStatus | BackgroundTaskStatus[];
+    }): Promise<BackgroundTask[]>;
+    /**
+     * Delete a task.
+     *
+     * @param taskId - The task ID to delete
+     * @returns True if a task was deleted, false if not found
+     */
+    delete(taskId: string): Promise<boolean>;
+    /**
+     * Check if a task exists.
+     *
+     * @param taskId - The task ID to check
+     * @returns True if the task exists
+     */
+    exists(taskId: string): Promise<boolean>;
+    /**
+     * Clean up expired tasks.
+     *
+     * Removes completed/failed tasks older than the expiration time.
+     *
+     * @returns Number of tasks cleaned up
+     */
+    cleanup(): Promise<number>;
+}
+/**
+ * Create a new background task with the given data.
+ *
+ * This is a convenience function that ensures timestamps are set correctly.
+ *
+ * @param data - Partial task data (id, subagentType, description required)
+ * @returns A complete task object
+ *
+ * @example
+ * ```typescript
+ * const task = createBackgroundTask({
+ *   id: "task-123",
+ *   subagentType: "researcher",
+ *   description: "Research topic X",
+ * });
+ * ```
+ *
+ * @category TaskStore
+ */
+export declare function createBackgroundTask(data: Pick<BackgroundTask, "id" | "subagentType" | "description"> & Partial<Omit<BackgroundTask, "id" | "subagentType" | "description">>): BackgroundTask;
+/**
+ * Update an existing task with new data.
+ *
+ * Automatically updates the `updatedAt` timestamp.
+ *
+ * @param task - The existing task
+ * @param updates - Partial updates to apply
+ * @returns A new task object with updates applied
+ *
+ * @example
+ * ```typescript
+ * const updated = updateBackgroundTask(task, {
+ *   status: "completed",
+ *   result: "Task completed successfully",
+ *   completedAt: new Date().toISOString(),
+ * });
+ * ```
+ *
+ * @category TaskStore
+ */
+export declare function updateBackgroundTask(task: BackgroundTask, updates: Partial<Omit<BackgroundTask, "id" | "createdAt">>): BackgroundTask;
+/**
+ * Type guard to check if an object is a valid BackgroundTask.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid BackgroundTask
+ *
+ * @category TaskStore
+ */
+export declare function isBackgroundTask(value: unknown): value is BackgroundTask;
+/**
+ * Check if a task should be expired based on age and status.
+ *
+ * @param task - The task to check
+ * @param expirationMs - Expiration time in milliseconds
+ * @returns True if the task should be expired
+ *
+ * @category TaskStore
+ */
+export declare function shouldExpireTask(task: BackgroundTask, expirationMs: number): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/task-store/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/task-store/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IAEX,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IAErB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IAEpB,qBAAqB;IACrB,MAAM,EAAE,oBAAoB,CAAC;IAE7B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAElB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAElB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAMD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAE1D;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE7F;;;;;OAKG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE;QACjB,MAAM,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,EAAE,CAAC;KACxD,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE9B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzC;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,cAAc,GAAG,aAAa,CAAC,GAC/D,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,cAAc,GAAG,aAAa,CAAC,CAAC,GACrE,cAAc,CAQhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC,GACzD,cAAc,CAMhB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAkBxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAYpF"}