concevent-ai-agent-sdk 2.2.0 → 2.3.0

package/dist/tools/todo-write.js

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+/**
+ * Schema for a single todo item
+ */
+const todoItemSchema = z.object({
+    id: z.string().describe('Unique identifier for the todo item.'),
+    content: z.string().max(200).describe('Description of the todo item. Maximum 200 characters.'),
+    status: z
+        .enum(['pending', 'in_progress', 'completed', 'cancelled'])
+        .describe('Current status of the todo item.'),
+});
+/**
+ * Schema for the TodoWrite tool parameters
+ */
+export const todoWriteSchema = z.object({
+    todos: z
+        .array(todoItemSchema)
+        .min(1)
+        .describe('Array of todo items to write. Each item must have id, content, and status.'),
+    merge: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('If true, merge with existing todos (update by ID). If false, replace all todos.'),
+});
+/**
+ * In-memory todo storage implementation
+ */
+class InMemoryTodoStorage {
+    todos = new Map();
+    async getAll() {
+        return Array.from(this.todos.values());
+    }
+    async save(todos, merge) {
+        if (!merge) {
+            this.todos.clear();
+        }
+        for (const todo of todos) {
+            this.todos.set(todo.id, todo);
+        }
+        return this.getAll();
+    }
+    async clear() {
+        this.todos.clear();
+    }
+}
+// Singleton storage instance for when no custom storage is provided
+let defaultStorage = null;
+function getDefaultStorage() {
+    if (!defaultStorage) {
+        defaultStorage = new InMemoryTodoStorage();
+    }
+    return defaultStorage;
+}
+/**
+ * Creates the TodoWrite tool for managing todo items
+ */
+export function createTodoWriteTool(config = {}) {
+    const storage = config.todoStorage ?? getDefaultStorage();
+    return {
+        declaration: {
+            name: 'TodoWrite',
+            description: `Manages a structured todo list for tracking tasks.
+
+Use this tool to:
+- Create new todo items for complex multi-step tasks
+- Update task status as you progress (pending → in_progress → completed)
+- Track multiple parallel workstreams
+- Document what has been accomplished
+
+Status values:
+- pending: Task not yet started
+- in_progress: Currently working on this task
+- completed: Task finished successfully
+- cancelled: Task no longer needed
+
+Best practices:
+- Only one task should be in_progress at a time
+- Mark tasks complete immediately after finishing
+- Use clear, actionable descriptions`,
+            parametersJsonSchema: zodToJsonSchema(todoWriteSchema),
+        },
+        executor: async (args) => {
+            const params = todoWriteSchema.parse(args);
+            // Validate todos
+            const validatedTodos = params.todos.map((todo) => ({
+                id: todo.id,
+                content: todo.content,
+                status: todo.status,
+            }));
+            // Save todos
+            const updatedTodos = await storage.save(validatedTodos, params.merge);
+            // Generate summary
+            const summary = {
+                pending: 0,
+                in_progress: 0,
+                completed: 0,
+                cancelled: 0,
+            };
+            for (const todo of updatedTodos) {
+                summary[todo.status]++;
+            }
+            return {
+                success: true,
+                todos: updatedTodos,
+                summary,
+                total: updatedTodos.length,
+                message: params.merge
+                    ? `Updated ${params.todos.length} todo item${params.todos.length > 1 ? 's' : ''}`
+                    : `Set ${params.todos.length} todo item${params.todos.length > 1 ? 's' : ''} (replaced existing)`,
+            };
+        },
+        parallel: false, // Todo writes should be sequential to avoid race conditions
+    };
+}
+/**
+ * Creates a TodoRead tool for reading current todos (bonus utility)
+ */
+export function createTodoReadTool(config = {}) {
+    const storage = config.todoStorage ?? getDefaultStorage();
+    return {
+        declaration: {
+            name: 'TodoRead',
+            description: 'Reads the current todo list. Returns all todo items with their status.',
+            parametersJsonSchema: zodToJsonSchema(z.object({})),
+        },
+        executor: async () => {
+            const todos = await storage.getAll();
+            const summary = {
+                pending: 0,
+                in_progress: 0,
+                completed: 0,
+                cancelled: 0,
+            };
+            for (const todo of todos) {
+                summary[todo.status]++;
+            }
+            return {
+                todos,
+                summary,
+                total: todos.length,
+                message: todos.length > 0
+                    ? `Found ${todos.length} todo item${todos.length > 1 ? 's' : ''}`
+                    : 'No todos found',
+            };
+        },
+        parallel: true, // Reading is safe to do in parallel
+    };
+}
+//# sourceMappingURL=todo-write.js.map

package/dist/tools/todo-write.js.map

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

package/dist/tools/types.d.ts

@@ -0,0 +1,147 @@
+import type { ToolDefinition } from '../types/index.js';
+/**
+ * Status of a todo item
+ */
+export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled';
+/**
+ * A single todo item
+ */
+export interface TodoItem {
+    id: string;
+    content: string;
+    status: TodoStatus;
+}
+/**
+ * Interface for custom todo storage implementations
+ */
+export interface TodoStorage {
+    /** Get all todos */
+    getAll(): Promise<TodoItem[]>;
+    /** Save todos (replaces all or merges based on implementation) */
+    save(todos: TodoItem[], merge: boolean): Promise<TodoItem[]>;
+    /** Clear all todos */
+    clear(): Promise<void>;
+}
+/**
+ * Configuration for creating a sub-agent via the Task tool
+ */
+export interface TaskAgentConfig {
+    description: string;
+    prompt: string;
+    allowedTools?: string[];
+}
+/**
+ * Factory function type for creating sub-agents
+ */
+export type AgentFactory = (config: TaskAgentConfig) => Promise<{
+    message: string;
+}>;
+/**
+ * Information about a running background process
+ */
+export interface ProcessInfo {
+    id: string;
+    command: string;
+    startTime: Date;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    running: boolean;
+}
+/**
+ * Manager for background shell processes
+ */
+export interface ProcessManager {
+    /** Get a process by ID */
+    get(id: string): ProcessInfo | undefined;
+    /** Get all processes */
+    getAll(): ProcessInfo[];
+    /** Kill a process by ID */
+    kill(id: string): Promise<boolean>;
+    /** Clean up all processes */
+    cleanup(): Promise<void>;
+}
+/**
+ * Base configuration options for built-in tools (used by individual tool creators)
+ */
+export interface ToolConfig {
+    /** Working directory for file operations (defaults to process.cwd()) */
+    workingDirectory?: string;
+    /**
+     * Allowed file paths for sandboxing.
+     * If specified, file operations are restricted to these paths.
+     * Supports directory paths - files under these directories are allowed.
+     */
+    allowedPaths?: string[];
+    /**
+     * Blocked shell command patterns.
+     * Commands matching these patterns will be rejected.
+     * Defaults to common dangerous patterns like 'rm -rf /', etc.
+     */
+    blockedCommands?: RegExp[];
+    /** Default timeout for shell commands in milliseconds (defaults to 30000) */
+    defaultTimeout?: number;
+    /**
+     * Agent factory for the Task tool.
+     * If not provided, the Task tool will not be available.
+     */
+    agentFactory?: AgentFactory;
+    /**
+     * Custom todo storage for the TodoWrite tool.
+     * If not provided, uses in-memory storage.
+     */
+    todoStorage?: TodoStorage;
+}
+/**
+ * Configuration for creating multiple built-in tools.
+ * Extends ToolConfig and requires specifying which tools to include.
+ */
+export interface BuiltInToolsConfig extends ToolConfig {
+    /**
+     * Which tools to include. You must explicitly specify which tools you need.
+     * Tool names are strongly typed with autocomplete support.
+     * @example
+     * ```typescript
+     * import { createBuiltInTools } from 'concevent-ai-agent-sdk';
+     *
+     * const { tools } = createBuiltInTools({
+     *   workingDirectory: '/project',
+     *   tools: ['Read', 'Write', 'Glob'],
+     * });
+     * ```
+     */
+    tools: ToolName[];
+}
+/**
+ * Result of a shell command execution
+ */
+export interface ShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut?: boolean;
+}
+/**
+ * Tool names constant for type-safe tool selection
+ */
+export declare const TOOL_NAMES: {
+    readonly READ: "Read";
+    readonly WRITE: "Write";
+    readonly EDIT: "Edit";
+    readonly GLOB: "Glob";
+    readonly GREP: "Grep";
+    readonly BASH: "Bash";
+    readonly BASH_OUTPUT: "BashOutput";
+    readonly KILL_BASH: "KillBash";
+    readonly TASK: "Task";
+    readonly TODO_WRITE: "TodoWrite";
+};
+/**
+ * Union type of all valid tool name values
+ */
+export type ToolName = (typeof TOOL_NAMES)[keyof typeof TOOL_NAMES];
+/**
+ * Type for tool creator functions
+ */
+export type ToolCreator = (config: ToolConfig, processManager?: ProcessManager) => ToolDefinition;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/tools/types.js

@@ -0,0 +1,16 @@
+/**
+ * Tool names constant for type-safe tool selection
+ */
+export const TOOL_NAMES = {
+    READ: 'Read',
+    WRITE: 'Write',
+    EDIT: 'Edit',
+    GLOB: 'Glob',
+    GREP: 'Grep',
+    BASH: 'Bash',
+    BASH_OUTPUT: 'BashOutput',
+    KILL_BASH: 'KillBash',
+    TASK: 'Task',
+    TODO_WRITE: 'TodoWrite',
+};
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAyIA;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,YAAY;IACzB,SAAS,EAAE,UAAU;IACrB,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,WAAW;CACf,CAAC"}

package/dist/tools/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './path.js';
+export * from './shell.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/tools/utils/index.js

@@ -0,0 +1,3 @@
+export * from './path.js';
+export * from './shell.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/tools/utils/path.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Normalizes a file path and resolves it relative to the working directory.
+ * Handles cross-platform path differences.
+ */
+export declare function resolvePath(filePath: string, workingDirectory: string): string;
+/**
+ * Checks if a path is within the allowed paths (for sandboxing).
+ * Returns true if no allowedPaths are specified (no sandboxing).
+ */
+export declare function isPathAllowed(targetPath: string, allowedPaths?: string[]): boolean;
+/**
+ * Checks for path traversal attempts.
+ * Returns true if the path is safe (no traversal detected).
+ */
+export declare function isPathSafe(filePath: string, workingDirectory: string): boolean;
+/**
+ * Ensures a directory exists, creating it if necessary.
+ */
+export declare function ensureDirectory(dirPath: string): Promise<void>;
+/**
+ * Gets the relative path from the working directory.
+ */
+export declare function getRelativePath(absolutePath: string, workingDirectory: string): string;
+/**
+ * Normalizes line endings to the current platform's standard.
+ */
+export declare function normalizeLineEndings(content: string): string;
+/**
+ * Simple glob pattern matching.
+ * Supports *, **, and ? wildcards.
+ */
+export declare function matchGlobPattern(pattern: string, filePath: string): boolean;
+/**
+ * Recursively walks a directory and returns all file paths.
+ */
+export declare function walkDirectory(dir: string, options?: {
+    ignore?: string[];
+    maxDepth?: number;
+}): Promise<string[]>;
+//# sourceMappingURL=path.d.ts.map

package/dist/tools/utils/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/path.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAO9E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAelF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAa9E;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CA2B3E;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACd,GACL,OAAO,CAAC,MAAM,EAAE,CAAC,CA0CnB"}

package/dist/tools/utils/path.js

@@ -0,0 +1,146 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+/**
+ * Normalizes a file path and resolves it relative to the working directory.
+ * Handles cross-platform path differences.
+ */
+export function resolvePath(filePath, workingDirectory) {
+    // If it's already an absolute path, normalize it
+    if (path.isAbsolute(filePath)) {
+        return path.normalize(filePath);
+    }
+    // Otherwise resolve relative to working directory
+    return path.resolve(workingDirectory, filePath);
+}
+/**
+ * Checks if a path is within the allowed paths (for sandboxing).
+ * Returns true if no allowedPaths are specified (no sandboxing).
+ */
+export function isPathAllowed(targetPath, allowedPaths) {
+    if (!allowedPaths || allowedPaths.length === 0) {
+        return true;
+    }
+    const normalizedTarget = path.normalize(path.resolve(targetPath));
+    return allowedPaths.some((allowedPath) => {
+        const normalizedAllowed = path.normalize(path.resolve(allowedPath));
+        // Check if target is the allowed path or is under it
+        return (normalizedTarget === normalizedAllowed ||
+            normalizedTarget.startsWith(normalizedAllowed + path.sep));
+    });
+}
+/**
+ * Checks for path traversal attempts.
+ * Returns true if the path is safe (no traversal detected).
+ */
+export function isPathSafe(filePath, workingDirectory) {
+    const resolved = resolvePath(filePath, workingDirectory);
+    const normalizedWorking = path.normalize(path.resolve(workingDirectory));
+    // The resolved path should be within or equal to the working directory
+    // or be an absolute path that was explicitly provided
+    if (path.isAbsolute(filePath)) {
+        // Absolute paths are allowed but still need normalization
+        return !filePath.includes('..');
+    }
+    // For relative paths, ensure they don't escape the working directory
+    return resolved.startsWith(normalizedWorking) || resolved === normalizedWorking;
+}
+/**
+ * Ensures a directory exists, creating it if necessary.
+ */
+export async function ensureDirectory(dirPath) {
+    try {
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+    catch (error) {
+        // Directory might already exist
+        const stat = await fs.stat(dirPath).catch(() => null);
+        if (!stat?.isDirectory()) {
+            throw error;
+        }
+    }
+}
+/**
+ * Gets the relative path from the working directory.
+ */
+export function getRelativePath(absolutePath, workingDirectory) {
+    return path.relative(workingDirectory, absolutePath);
+}
+/**
+ * Normalizes line endings to the current platform's standard.
+ */
+export function normalizeLineEndings(content) {
+    // Always use LF internally, let consumers handle platform-specific needs
+    return content.replace(/\r\n/g, '\n');
+}
+/**
+ * Simple glob pattern matching.
+ * Supports *, **, and ? wildcards.
+ */
+export function matchGlobPattern(pattern, filePath) {
+    // Normalize path separators
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    const normalizedPattern = pattern.replace(/\\/g, '/');
+    // Convert glob pattern to regex
+    let regexPattern = normalizedPattern
+        // Escape special regex characters (except our wildcards)
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        // Convert ** to a placeholder
+        .replace(/\*\*/g, '{{GLOBSTAR}}')
+        // Convert * to match anything except /
+        .replace(/\*/g, '[^/]*')
+        // Convert ? to match any single character except /
+        .replace(/\?/g, '[^/]')
+        // Convert ** placeholder back to match any path
+        .replace(/\{\{GLOBSTAR\}\}/g, '.*');
+    // Anchor the pattern
+    regexPattern = `^${regexPattern}$`;
+    try {
+        const regex = new RegExp(regexPattern);
+        return regex.test(normalizedPath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Recursively walks a directory and returns all file paths.
+ */
+export async function walkDirectory(dir, options = {}) {
+    const { ignore = [], maxDepth = 100 } = options;
+    const results = [];
+    async function walk(currentDir, depth) {
+        if (depth > maxDepth) {
+            return;
+        }
+        try {
+            const entries = await fs.readdir(currentDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(currentDir, entry.name);
+                const relativePath = path.relative(dir, fullPath);
+                // Check if path should be ignored
+                const shouldIgnore = ignore.some((pattern) => {
+                    // Simple check for common ignore patterns
+                    if (pattern.startsWith('**/')) {
+                        return matchGlobPattern(pattern, relativePath) || entry.name === pattern.slice(3);
+                    }
+                    return matchGlobPattern(pattern, relativePath) || matchGlobPattern(pattern, entry.name);
+                });
+                if (shouldIgnore) {
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    await walk(fullPath, depth + 1);
+                }
+                else if (entry.isFile()) {
+                    results.push(fullPath);
+                }
+            }
+        }
+        catch {
+            // Directory might not be readable, skip it
+        }
+    }
+    await walk(dir, 0);
+    return results;
+}
+//# sourceMappingURL=path.js.map

package/dist/tools/utils/path.js.map

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

package/dist/tools/utils/shell.d.ts

@@ -0,0 +1,49 @@
+import { ChildProcess } from 'child_process';
+import type { ShellResult, ProcessInfo, ProcessManager } from '../types.js';
+/**
+ * Default dangerous command patterns that should be blocked
+ */
+export declare const DEFAULT_BLOCKED_COMMANDS: RegExp[];
+/**
+ * Gets the appropriate shell command for the current platform
+ */
+export declare function getShellCommand(): {
+    shell: string;
+    args: string[];
+};
+/**
+ * Checks if a command matches any blocked patterns
+ */
+export declare function isCommandBlocked(command: string, blockedPatterns?: RegExp[]): string | null;
+/**
+ * Executes a shell command and returns the result
+ */
+export declare function executeCommand(command: string, options?: {
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+    abortSignal?: AbortSignal;
+}): Promise<ShellResult>;
+/**
+ * Creates a ProcessManager for managing background processes
+ */
+export declare function createProcessManager(): ProcessManager;
+/**
+ * Spawns a background process and registers it with the ProcessManager
+ */
+export declare function spawnBackgroundProcess(command: string, processManager: ProcessManager & {
+    _register?: (id: string, process: ChildProcess, info: ProcessInfo) => void;
+}, options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+}): ProcessInfo;
+/**
+ * Creates a ProcessManager with internal registration capability
+ */
+export declare function createProcessManagerWithInternal(): ProcessManager & {
+    _processes: Map<string, {
+        process: ChildProcess;
+        info: ProcessInfo;
+    }>;
+};
+//# sourceMappingURL=shell.d.ts.map

package/dist/tools/utils/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,YAAY,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,EAS5C,CAAC;AAEF;;GAEG;AACH,wBAAgB,eAAe,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAmBnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAU3F;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,WAAW,CAAC;CACtB,GACL,OAAO,CAAC,WAAW,CAAC,CA6EtB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAqCrD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,cAAc,GAAG;IAC/B,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CAC5E,EACD,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB,GACL,WAAW,CAkDb;AAED;;GAEG;AACH,wBAAgB,gCAAgC,IAAI,cAAc,GAAG;IACnE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;CACvE,CAsCA"}