@agntk/core 0.2.0 → 0.3.1

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/schedulers.d.ts

@@ -0,0 +1,231 @@
+/**
+ * @agntk/core - Scheduled Workflows
+ *
+ * Implements recurring task execution using Workflow DevKit's `sleep()`.
+ * Each scheduled workflow is a durable loop: execute → sleep → repeat.
+ * Zero compute cost during sleep — the workflow runtime suspends the process.
+ *
+ * @see ADV-SCHEDULER-018
+ * @see https://useworkflow.dev
+ */
+import { parseDuration, formatDuration } from './utils.js';
+/**
+ * Configuration for a scheduled workflow.
+ *
+ * @typeParam T - The return type of the task function
+ */
+export interface ScheduledWorkflowConfig<T = void> {
+    /** Human-readable name for this schedule. */
+    name: string;
+    /** Description of what the scheduled task does. */
+    description?: string;
+    /**
+     * Interval between executions.
+     * Duration string (e.g., "1h", "1d", "7d").
+     */
+    interval: string;
+    /**
+     * The task to execute on each tick.
+     * Receives the current iteration number (0-indexed) and returns a result.
+     */
+    task: (iteration: number) => Promise<T> | T;
+    /**
+     * Maximum number of iterations before the workflow stops.
+     * Omit or set to `Infinity` for an infinite loop.
+     * @default Infinity
+     */
+    maxIterations?: number;
+    /**
+     * Whether to run the task immediately on start, or wait for the first interval.
+     * @default true
+     */
+    immediate?: boolean;
+    /**
+     * Called after each successful task execution.
+     */
+    onTick?: (result: T, iteration: number) => void | Promise<void>;
+    /**
+     * Called when a task execution throws an error.
+     * Return `true` to continue the schedule despite the error (default).
+     * Return `false` to stop the schedule.
+     * @default continue
+     */
+    onError?: (error: Error, iteration: number) => boolean | Promise<boolean>;
+}
+/**
+ * A running scheduled workflow instance.
+ *
+ * @typeParam T - The return type of the task function
+ */
+export interface ScheduledWorkflow<T = void> {
+    /** The schedule configuration name. */
+    readonly name: string;
+    /** The schedule configuration description. */
+    readonly description?: string;
+    /** The interval between executions. */
+    readonly interval: string;
+    /**
+     * Start the schedule loop. Returns a promise that resolves
+     * when the schedule completes (hits maxIterations or is cancelled).
+     */
+    start: () => Promise<ScheduleResult<T>>;
+    /**
+     * Cancel the schedule. The current sleep will be interrupted,
+     * and the loop will exit after the current tick completes.
+     */
+    cancel: () => void;
+    /** Whether the schedule is currently running. */
+    readonly isRunning: boolean;
+    /** Number of completed iterations. */
+    readonly completedIterations: number;
+    /** Results from completed iterations. */
+    readonly results: ScheduleTickResult<T>[];
+}
+/**
+ * Result from a single scheduled tick.
+ */
+export interface ScheduleTickResult<T = void> {
+    /** 0-indexed iteration number. */
+    iteration: number;
+    /** Whether the tick succeeded. */
+    success: boolean;
+    /** The result value (if success). */
+    result?: T;
+    /** The error message (if failed). */
+    error?: string;
+    /** Timestamp when the tick completed. */
+    completedAt: Date;
+}
+/**
+ * Final result from a completed schedule.
+ */
+export interface ScheduleResult<T = void> {
+    /** Schedule name. */
+    name: string;
+    /** Total completed iterations. */
+    totalIterations: number;
+    /** Whether the schedule was cancelled. */
+    cancelled: boolean;
+    /** All tick results. */
+    ticks: ScheduleTickResult<T>[];
+}
+/**
+ * Create a scheduled workflow that loops with durable sleep.
+ *
+ * The workflow executes a task, sleeps for the configured interval,
+ * and repeats. Under the Workflow runtime, sleep is zero-compute.
+ *
+ * @param config - Schedule configuration
+ * @returns A `ScheduledWorkflow` instance (call `.start()` to begin)
+ *
+ * @example
+ * ```typescript
+ * const daily = createScheduledWorkflow({
+ *   name: 'daily-briefing',
+ *   interval: '1d',
+ *   task: async (iteration) => {
+ *     const agent = createAgent({ role: 'analyst' });
+ *     const result = await agent.generate({
+ *       prompt: 'Generate a daily briefing summary.',
+ *     });
+ *     return result.text;
+ *   },
+ *   onTick: (text, i) => console.log(`Briefing #${i}:`, text),
+ * });
+ *
+ * await daily.start(); // Loops forever with 1d sleep between ticks
+ * ```
+ */
+export declare function createScheduledWorkflow<T = void>(config: ScheduledWorkflowConfig<T>): ScheduledWorkflow<T>;
+/**
+ * Options for the daily briefing schedule preset.
+ */
+export interface DailyBriefingOptions {
+    /**
+     * The task that generates the briefing content.
+     * Receives the iteration number.
+     */
+    generateBriefing: (iteration: number) => Promise<string>;
+    /**
+     * Called with each briefing (e.g., send email, post to Slack).
+     */
+    deliver: (briefing: string, iteration: number) => void | Promise<void>;
+    /**
+     * Override the default interval. Default: "1d"
+     */
+    interval?: string;
+    /**
+     * Maximum number of briefings. Default: Infinity
+     */
+    maxIterations?: number;
+}
+/**
+ * Create a daily briefing scheduled workflow.
+ *
+ * Runs a briefing generation task once per day (configurable),
+ * delivering the result via a callback.
+ *
+ * @example
+ * ```typescript
+ * const briefing = createDailyBriefing({
+ *   generateBriefing: async () => {
+ *     const agent = createAgent({ role: 'analyst' });
+ *     const result = await agent.generate({
+ *       prompt: 'Summarize today\'s calendar, emails, and tasks.',
+ *     });
+ *     return result.text;
+ *   },
+ *   deliver: (text) => sendSlackMessage('#daily', text),
+ * });
+ *
+ * await briefing.start();
+ * ```
+ */
+export declare function createDailyBriefing(options: DailyBriefingOptions): ScheduledWorkflow<string>;
+/**
+ * Options for the weekly report schedule preset.
+ */
+export interface WeeklyReportOptions {
+    /**
+     * The task that generates the weekly report.
+     * Receives the iteration (week) number.
+     */
+    generateReport: (week: number) => Promise<string>;
+    /**
+     * Called with each report (e.g., send email, save to file).
+     */
+    deliver: (report: string, week: number) => void | Promise<void>;
+    /**
+     * Override the default interval. Default: "7d"
+     */
+    interval?: string;
+    /**
+     * Maximum number of reports. Default: Infinity
+     */
+    maxIterations?: number;
+}
+/**
+ * Create a weekly report scheduled workflow.
+ *
+ * Runs a report generation task once per week (configurable),
+ * delivering the result via a callback.
+ *
+ * @example
+ * ```typescript
+ * const report = createWeeklyReport({
+ *   generateReport: async (week) => {
+ *     const agent = createAgent({ role: 'analyst' });
+ *     const result = await agent.generate({
+ *       prompt: `Generate weekly report #${week + 1}.`,
+ *     });
+ *     return result.text;
+ *   },
+ *   deliver: (text) => sendEmail('team@company.com', 'Weekly Report', text),
+ * });
+ *
+ * await report.start();
+ * ```
+ */
+export declare function createWeeklyReport(options: WeeklyReportOptions): ScheduledWorkflow<string>;
+export { parseDuration, formatDuration };
+//# sourceMappingURL=schedulers.d.ts.map

package/dist/workflow/schedulers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedulers.d.ts","sourceRoot":"","sources":["../../src/workflow/schedulers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAQxD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,GAAG,IAAI;IAC/C,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IAEb,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAE5C;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,IAAI;IACzC,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAExC;;;OAGG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IAEnB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,sCAAsC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAErC,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,IAAI;IAC1C,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAElB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IAEjB,qCAAqC;IACrC,MAAM,CAAC,EAAE,CAAC,CAAC;IAEX,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,yCAAyC;IACzC,WAAW,EAAE,IAAI,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,IAAI;IACtC,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;IAExB,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAC;IAEnB,wBAAwB;IACxB,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,IAAI,EAC9C,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACjC,iBAAiB,CAAC,CAAC,CAAC,CAkKtB;AAMD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzD;;OAEG;IACH,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CAAC,MAAM,CAAC,CAoB3B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAElD;;OAEG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,GAC3B,iBAAiB,CAAC,MAAM,CAAC,CAoB3B;AAGD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}