@agntk/core 0.1.0

package/dist/workflow/durable-agent.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @agntk/core - Durable Agent Factory
+ *
+ * Creates agents with workflow durability features.
+ * Uses the Workflow DevKit ("use workflow" / "use step" directives)
+ * for crash recovery, auto-retry, and step-level observability.
+ *
+ * When the `workflow` package is installed and the app runs under the
+ * Workflow runtime, every LLM call and tool execution becomes a
+ * discrete, checkpointed step. Without the runtime, the directives
+ * are inert string literals and the agent operates normally.
+ *
+ * @see https://useworkflow.dev
+ */
+import type { Agent } from '../agent.js';
+import type { AgentOptions, WorkflowOptions } from '../types/agent.js';
+/**
+ * Extended options for creating a durable agent.
+ * Includes all standard AgentOptions plus workflow-specific config.
+ */
+export interface DurableAgentOptions extends AgentOptions {
+    /** Force durability even if detection is uncertain. Default: true */
+    durable?: boolean;
+    /** Workflow-specific configuration. */
+    workflowOptions?: WorkflowOptions;
+}
+/**
+ * Result from a durable generation.
+ */
+export interface DurableGenerateResult {
+    text: string;
+    workflowRunId?: string;
+    steps?: Array<{
+        name: string;
+        status: 'completed' | 'failed' | 'skipped';
+        durationMs?: number;
+    }>;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Webhook response for approval workflows.
+ */
+export interface WebhookResponse {
+    approved: boolean;
+    feedback?: string;
+    modifiedContent?: string;
+}
+/**
+ * Extended agent interface with durable workflow capabilities.
+ * Extends the base Agent interface with workflow-specific methods.
+ */
+export interface DurableAgent extends Agent {
+    /**
+     * Durable generate that wraps the LLM call as a workflow step.
+     * Survives crashes — the workflow runtime checkpoints progress.
+     */
+    durableGenerate: (prompt: string) => Promise<DurableGenerateResult>;
+    /**
+     * Generate with approval workflow.
+     * Pauses execution (zero compute) until webhook approval is received.
+     */
+    withApproval: (prompt: string, webhookPath: string) => Promise<DurableGenerateResult>;
+    /**
+     * Scheduled generation with durable delay.
+     * Uses workflow sleep() — doesn't hold compute during the delay.
+     */
+    scheduled: (prompt: string, delay: string) => Promise<DurableGenerateResult>;
+    /** Whether workflows are actually active (runtime detected). */
+    readonly isWorkflowActive: boolean;
+    /** The workflow run ID (set after first workflow execution). */
+    readonly workflowRunId: string | undefined;
+}
+/**
+ * Check if the Workflow DevKit runtime is available.
+ * Result is cached after first check.
+ */
+export declare function checkWorkflowAvailability(): Promise<boolean>;
+/**
+ * Reset workflow availability cache (for testing).
+ * @internal
+ */
+export declare function _resetWorkflowCache(): void;
+/**
+ * Create a durable agent with workflow integration.
+ *
+ * The durable agent wraps a standard Agent with workflow directives
+ * that make every LLM call and tool execution a recoverable step.
+ *
+ * @param baseAgent - The base agent to wrap with durability
+ * @param options - Durable agent options
+ * @returns DurableAgent instance with both standard and durable methods
+ *
+ * @example
+ * ```typescript
+ * import { createAgent } from '@agntk/core';
+ * import { createDurableAgent } from '@agntk/core/workflow';
+ *
+ * const base = createAgent({ role: 'coder', toolPreset: 'standard' });
+ * const agent = createDurableAgent(base);
+ *
+ * // Standard generation (no durability)
+ * const result = await agent.generate({ prompt: 'Hello' });
+ *
+ * // Durable generation (survives crashes)
+ * const durable = await agent.durableGenerate('Create a component');
+ *
+ * // With approval workflow
+ * const approved = await agent.withApproval('Draft email', '/api/approve');
+ *
+ * // Scheduled generation
+ * const delayed = await agent.scheduled('Send reminder', '1h');
+ * ```
+ */
+export declare function createDurableAgent(baseAgent: Agent, options?: DurableAgentOptions): DurableAgent;
+/**
+ * Parse a duration string into milliseconds.
+ * Supports: 30s, 5m, 1h, 1d
+ */
+export declare function parseDuration(duration: string): number;
+/**
+ * Format milliseconds as a human-readable duration.
+ */
+export declare function formatDuration(ms: number): string;
+//# sourceMappingURL=durable-agent.d.ts.map

package/dist/workflow/durable-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-agent.d.ts","sourceRoot":"","sources":["../../src/workflow/durable-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAQpE;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;QAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,KAAK,CAAC,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,KAAK;IACzC;;;OAGG;IACH,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAEpE;;;OAGG;IACH,YAAY,EAAE,CACZ,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,KAChB,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAEpC;;;OAGG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAE7E,gEAAgE;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IAEnC,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAgBD;;;GAGG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,OAAO,CAAC,CAalE;AAeD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AA4KD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,KAAK,EAChB,OAAO,GAAE,mBAAwB,GAChC,YAAY,CAsEd;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAqBtD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/dist/workflow/durable-agent.js

@@ -0,0 +1,323 @@
+/**
+ * @agntk/core - Durable Agent Factory
+ *
+ * Creates agents with workflow durability features.
+ * Uses the Workflow DevKit ("use workflow" / "use step" directives)
+ * for crash recovery, auto-retry, and step-level observability.
+ *
+ * When the `workflow` package is installed and the app runs under the
+ * Workflow runtime, every LLM call and tool execution becomes a
+ * discrete, checkpointed step. Without the runtime, the directives
+ * are inert string literals and the agent operates normally.
+ *
+ * @see https://useworkflow.dev
+ */
+import { createLogger } from '@agntk/logger';
+const log = createLogger('@agntk/core:workflow:durable');
+// ============================================================================
+// Workflow Runtime Detection
+// ============================================================================
+/** Cached availability result */
+let _workflowAvailable = null;
+let _workflowModule = null;
+/**
+ * Check if the Workflow DevKit runtime is available.
+ * Result is cached after first check.
+ */
+export async function checkWorkflowAvailability() {
+    if (_workflowAvailable !== null)
+        return _workflowAvailable;
+    try {
+        _workflowModule = await import('workflow');
+        _workflowAvailable = true;
+        log.info('Workflow runtime detected');
+        return true;
+    }
+    catch (_e) {
+        _workflowAvailable = false;
+        log.debug('Workflow runtime not available — durable features disabled');
+        return false;
+    }
+}
+/**
+ * Get the workflow module (throws if not available).
+ */
+function getWorkflowModule() {
+    if (!_workflowModule) {
+        throw new Error('Workflow package is not installed. Install it with: npm install workflow\n' +
+            'See https://useworkflow.dev for documentation.');
+    }
+    return _workflowModule;
+}
+/**
+ * Reset workflow availability cache (for testing).
+ * @internal
+ */
+export function _resetWorkflowCache() {
+    _workflowAvailable = null;
+    _workflowModule = null;
+}
+// ============================================================================
+// Durable Execution Wrappers
+// ============================================================================
+/**
+ * Wrap an agent's generate call as a workflow.
+ * The "use workflow" directive marks the entire function as a durable workflow.
+ * Named step functions give the workflow inspector descriptive labels.
+ *
+ * Inspector view: durableGenerateWorkflow → llmGenerate
+ */
+async function durableGenerateWorkflow(agent, prompt) {
+    "use workflow";
+    log.info('durableGenerateWorkflow started', { promptLength: prompt.length });
+    // Named step function — inspector displays "llmGenerate"
+    async function llmGenerate() {
+        "use step";
+        log.debug('step:llmGenerate — executing LLM call');
+        return agent.generate({ prompt });
+    }
+    const result = await llmGenerate();
+    const text = await result.text;
+    const totalUsage = result.totalUsage;
+    log.info('durableGenerateWorkflow completed', { textLength: text?.length ?? 0 });
+    return {
+        text: text ?? '',
+        steps: [{
+                name: 'llm-generate',
+                status: 'completed',
+            }],
+        usage: totalUsage ? {
+            promptTokens: totalUsage.inputTokens ?? 0,
+            completionTokens: totalUsage.outputTokens ?? 0,
+            totalTokens: totalUsage.totalTokens ?? 0,
+        } : undefined,
+    };
+}
+/**
+ * Wrap an agent's generate call with approval workflow.
+ * The function suspends (zero compute) while waiting for webhook approval.
+ *
+ * Inspector view: durableWithApprovalWorkflow → llmDraft → webhookApproval → llmFinalize
+ */
+async function durableWithApprovalWorkflow(agent, prompt, _webhookPath) {
+    "use workflow";
+    log.info('durableWithApprovalWorkflow started', { prompt: prompt.slice(0, 100) });
+    // Step 1: Generate draft — inspector displays "llmDraft"
+    async function llmDraft() {
+        "use step";
+        log.debug('step:llmDraft — generating draft');
+        return agent.generate({ prompt });
+    }
+    const draftResult = await llmDraft();
+    const draftText = await draftResult.text;
+    // Step 2: Wait for approval — inspector displays "webhookApproval"
+    log.info('Waiting for approval webhook');
+    async function webhookApproval() {
+        "use step";
+        log.debug('step:webhookApproval — suspending for webhook');
+        // The workflow runtime handles webhook suspension here.
+        // This stub returns approved=true when not running under the runtime.
+        return { approved: true };
+    }
+    const approval = await webhookApproval();
+    if (!approval.approved) {
+        log.warn('Approval rejected', { feedback: approval.feedback });
+        throw new Error(`Approval rejected: ${approval.feedback || 'No reason provided'}`);
+    }
+    // Step 3: Finalize — inspector displays "llmFinalize"
+    const finalPrompt = approval.modifiedContent
+        ? `Finalize with modifications: ${approval.modifiedContent}. Original: ${draftText}`
+        : prompt;
+    async function llmFinalize() {
+        "use step";
+        log.debug('step:llmFinalize — finalizing after approval');
+        return agent.generate({ prompt: finalPrompt });
+    }
+    const finalResult = await llmFinalize();
+    const finalText = await finalResult.text;
+    return {
+        text: finalText ?? '',
+        steps: [
+            { name: 'llm-draft', status: 'completed' },
+            { name: 'webhook-approval', status: 'completed' },
+            { name: 'llm-finalize', status: 'completed' },
+        ],
+    };
+}
+/**
+ * Wrap an agent's generate call with a durable delay.
+ * Uses workflow sleep() — doesn't hold compute during the delay.
+ *
+ * Inspector view: durableScheduledWorkflow → durableSleep → llmGenerate
+ */
+async function durableScheduledWorkflow(agent, prompt, delay) {
+    "use workflow";
+    log.info('durableScheduledWorkflow started', { delay });
+    // Step 1: Sleep (zero compute) — inspector displays "durableSleep"
+    async function durableSleep() {
+        "use step";
+        log.debug('step:durableSleep — sleeping', { delay });
+        try {
+            const wf = getWorkflowModule();
+            await wf.sleep(delay);
+        }
+        catch (_e) {
+            // If workflow not available, use regular setTimeout as fallback
+            const ms = parseDuration(delay);
+            log.warn('Workflow sleep unavailable, using setTimeout fallback', { ms });
+            await new Promise(resolve => setTimeout(resolve, ms));
+        }
+    }
+    await durableSleep();
+    log.info('Sleep completed, executing prompt');
+    // Step 2: Generate — inspector displays "llmGenerate"
+    async function llmGenerate() {
+        "use step";
+        log.debug('step:llmGenerate — executing LLM call after sleep');
+        return agent.generate({ prompt });
+    }
+    const result = await llmGenerate();
+    const text = await result.text;
+    return {
+        text: text ?? '',
+        steps: [
+            { name: 'sleep', status: 'completed' },
+            { name: 'llm-generate', status: 'completed' },
+        ],
+    };
+}
+// ============================================================================
+// Durable Agent Factory
+// ============================================================================
+/**
+ * Create a durable agent with workflow integration.
+ *
+ * The durable agent wraps a standard Agent with workflow directives
+ * that make every LLM call and tool execution a recoverable step.
+ *
+ * @param baseAgent - The base agent to wrap with durability
+ * @param options - Durable agent options
+ * @returns DurableAgent instance with both standard and durable methods
+ *
+ * @example
+ * ```typescript
+ * import { createAgent } from '@agntk/core';
+ * import { createDurableAgent } from '@agntk/core/workflow';
+ *
+ * const base = createAgent({ role: 'coder', toolPreset: 'standard' });
+ * const agent = createDurableAgent(base);
+ *
+ * // Standard generation (no durability)
+ * const result = await agent.generate({ prompt: 'Hello' });
+ *
+ * // Durable generation (survives crashes)
+ * const durable = await agent.durableGenerate('Create a component');
+ *
+ * // With approval workflow
+ * const approved = await agent.withApproval('Draft email', '/api/approve');
+ *
+ * // Scheduled generation
+ * const delayed = await agent.scheduled('Send reminder', '1h');
+ * ```
+ */
+export function createDurableAgent(baseAgent, options = {}) {
+    log.info('Creating durable agent', {
+        agentId: baseAgent.agentId,
+        role: baseAgent.role,
+        workflowOptions: options.workflowOptions,
+    });
+    let workflowRunId = options.workflowOptions?.workflowRunId;
+    /**
+     * Guard: ensure workflow is available before executing a durable method.
+     * Throws a clear, actionable error if the workflow package isn't installed.
+     * Standard Agent methods (generate, stream) still work without workflow.
+     */
+    async function ensureWorkflowAvailable() {
+        const available = await checkWorkflowAvailability();
+        if (!available) {
+            throw new Error('Workflow package is not installed. Durable agent features require the workflow package.\n' +
+                'Install with: npm install workflow\n' +
+                'See https://useworkflow.dev for documentation.');
+        }
+    }
+    const durableAgent = {
+        // Delegate standard Agent interface to the base agent
+        agentId: baseAgent.agentId,
+        role: baseAgent.role,
+        init: () => baseAgent.init(),
+        getToolLoopAgent: () => baseAgent.getToolLoopAgent(),
+        getSystemPrompt: () => baseAgent.getSystemPrompt(),
+        // Standard methods — pass through to base agent (work without workflow)
+        stream: (input) => baseAgent.stream(input),
+        generate: (input) => baseAgent.generate(input),
+        // Durable methods — require workflow package
+        durableGenerate: async (prompt) => {
+            await ensureWorkflowAvailable();
+            log.info('durableGenerate() called', { promptLength: prompt.length });
+            const result = await durableGenerateWorkflow(baseAgent, prompt);
+            if (result.workflowRunId)
+                workflowRunId = result.workflowRunId;
+            return result;
+        },
+        withApproval: async (prompt, webhookPath) => {
+            await ensureWorkflowAvailable();
+            log.info('withApproval() called', { promptLength: prompt.length, webhookPath });
+            return durableWithApprovalWorkflow(baseAgent, prompt, webhookPath);
+        },
+        scheduled: async (prompt, delay) => {
+            await ensureWorkflowAvailable();
+            log.info('scheduled() called', { promptLength: prompt.length, delay });
+            return durableScheduledWorkflow(baseAgent, prompt, delay);
+        },
+        get isWorkflowActive() {
+            return _workflowAvailable === true;
+        },
+        get workflowRunId() {
+            return workflowRunId;
+        },
+    };
+    log.info('Durable agent created', { agentId: baseAgent.agentId });
+    return durableAgent;
+}
+// ============================================================================
+// Workflow Helpers
+// ============================================================================
+/**
+ * Parse a duration string into milliseconds.
+ * Supports: 30s, 5m, 1h, 1d
+ */
+export function parseDuration(duration) {
+    const match = duration.match(/^(\d+)(s|m|h|d)$/);
+    if (!match) {
+        throw new Error(`Invalid duration format: ${duration}. Use format like '30s', '5m', '1h', '1d'`);
+    }
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    switch (unit) {
+        case 's':
+            return value * 1000;
+        case 'm':
+            return value * 60 * 1000;
+        case 'h':
+            return value * 60 * 60 * 1000;
+        case 'd':
+            return value * 24 * 60 * 60 * 1000;
+        default:
+            throw new Error(`Unknown duration unit: ${unit}`);
+    }
+}
+/**
+ * Format milliseconds as a human-readable duration.
+ */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${Math.round(ms / 1000)}s`;
+    if (ms < 3600000)
+        return `${Math.round(ms / 60000)}m`;
+    if (ms < 86400000)
+        return `${Math.round(ms / 3600000)}h`;
+    return `${Math.round(ms / 86400000)}d`;
+}
+//# sourceMappingURL=durable-agent.js.map

package/dist/workflow/durable-agent.js.map

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

package/dist/workflow/durable-tool.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @agntk/core - Durable Tool Wrapper
+ *
+ * Wraps tools with durability directives for crash recovery.
+ * Uses the Workflow DevKit's "use step" directive to checkpoint tool executions.
+ * Each tool step gets a descriptive name for observability in the workflow inspector.
+ *
+ * @see https://useworkflow.dev
+ */
+import type { Tool } from 'ai';
+type ToolSet = Record<string, Tool>;
+export interface DurabilityConfig {
+    /** Enable durability for this tool. Default: true */
+    enabled?: boolean;
+    /** Whether this tool can run independently in parallel. Default: false */
+    independent?: boolean;
+    /** Number of retry attempts on failure. Default: 3 */
+    retryCount?: number;
+    /** Timeout duration string (e.g., "30s", "5m"). Default: "5m" */
+    timeout?: string;
+    /** Custom step name for the workflow inspector. Default: "tool-exec-{toolName}" */
+    stepName?: string;
+}
+/**
+ * Wrap a single tool with durability directives.
+ *
+ * When wrapped, the tool's execute function uses the "use step" directive
+ * to create a checkpoint. If the process crashes, the workflow runtime
+ * resumes from the last checkpoint.
+ *
+ * Each wrapped tool gets a descriptive step name for the workflow inspector:
+ * - Default: "tool-exec-{toolName}"
+ * - Custom via `config.stepName`
+ *
+ * @param tool - The tool to wrap
+ * @param config - Durability configuration
+ * @param toolName - Name of the tool (used for step naming)
+ * @returns Wrapped tool with durability enabled
+ *
+ * @example
+ * ```typescript
+ * const durableReadFile = wrapToolAsDurableStep(readFileTool, {
+ *   retryCount: 3,
+ *   timeout: '30s',
+ * }, 'read_file');
+ * ```
+ */
+export declare function wrapToolAsDurableStep(tool: Tool, config?: DurabilityConfig, toolName?: string): Tool;
+/**
+ * Wrap all tools in a set with durability directives.
+ * Each tool gets a step name based on its key in the record.
+ *
+ * @param tools - Record of tools to wrap
+ * @param config - Durability configuration applied to all tools
+ * @returns Record of wrapped tools
+ *
+ * @example
+ * ```typescript
+ * const durableTools = wrapToolsAsDurable(myTools, {
+ *   retryCount: 3,
+ *   timeout: '5m',
+ * });
+ * ```
+ */
+export declare function wrapToolsAsDurable(tools: ToolSet, config?: DurabilityConfig): ToolSet;
+/**
+ * Wrap only specified tools with durability, leaving others unchanged.
+ *
+ * @param tools - All tools
+ * @param toolNames - Names of tools to wrap
+ * @param config - Durability configuration
+ * @returns Tools with selective durability applied
+ */
+export declare function wrapSelectedToolsAsDurable(tools: ToolSet, toolNames: string[], config?: DurabilityConfig): ToolSet;
+/**
+ * Wrap a tool as an independent durable step.
+ *
+ * Independent steps can be executed in parallel with other independent steps.
+ * The workflow runtime optimizes by running these concurrently.
+ *
+ * @param tool - The tool to wrap
+ * @param toolName - Name of the tool (used for step naming)
+ * @returns Wrapped tool marked as independent
+ */
+export declare function wrapToolAsIndependentStep(tool: Tool, toolName?: string): Tool;
+/**
+ * Symbol for storing durability metadata on tools.
+ */
+export declare const DURABILITY_CONFIG: unique symbol;
+/**
+ * Get durability configuration from a tool (if set).
+ */
+export declare function getDurabilityConfig(tool: Tool): DurabilityConfig | undefined;
+/**
+ * Set durability configuration on a tool.
+ */
+export declare function setDurabilityConfig(tool: Tool, config: DurabilityConfig): Tool;
+/**
+ * Get the step name assigned to a durable tool.
+ */
+export declare function getStepName(tool: Tool): string | undefined;
+export {};
+//# sourceMappingURL=durable-tool.d.ts.map

package/dist/workflow/durable-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-tool.d.ts","sourceRoot":"","sources":["../../src/workflow/durable-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAS/B,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEpC,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,gBAAqB,EAC7B,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CAgDN;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAST;AAMD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EAAE,EACnB,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAaT;AAMD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAE7E;AAMD;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAA6B,CAAC;AAE5D;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,GAAG,SAAS,CAG5E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAI9E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAE1D"}