@agtlantis/core 0.5.0 → 0.6.0

package/dist/execution/shared.d.ts

@@ -0,0 +1,86 @@
+import type { ExecutionStatus } from './types.js';
+/**
+ * Shared utilities for execution hosts.
+ *
+ * These functions extract common patterns from SimpleExecutionHost and
+ * StreamingExecutionHost to reduce code duplication and ensure consistent
+ * behavior across both implementations.
+ */
+/**
+ * Checks if an error is an abort-related error.
+ *
+ * An error is considered abort-related if either:
+ * - The error has the name 'AbortError' (standard for AbortController)
+ * - The signal has been aborted (covers edge cases where error name differs)
+ *
+ * @param error - The error to check
+ * @param signal - The AbortSignal associated with the execution
+ * @returns true if this is an abort-related error
+ */
+export declare function isAbortError(error: unknown, signal: AbortSignal): boolean;
+/**
+ * Normalizes an unknown error to an Error instance.
+ *
+ * If the error is already an Error instance, it's returned as-is.
+ * Otherwise, it's converted to a string and wrapped in a new Error.
+ *
+ * @param error - The unknown error to normalize
+ * @returns A proper Error instance
+ */
+export declare function normalizeError(error: unknown): Error;
+/**
+ * Determines the execution status based on the execution state.
+ *
+ * Status determination priority:
+ * 1. If user called cancel() OR the operation was aborted → 'canceled'
+ * 2. If there's an error → 'failed'
+ * 3. Otherwise → 'succeeded'
+ *
+ * Note: The 'aborted' flag takes precedence over 'hasError' because
+ * AbortError is treated as a normal cancellation, not a failure.
+ *
+ * @param cancelRequested - Whether cancel() was explicitly called
+ * @param aborted - Whether the signal was aborted (includes external abort)
+ * @param hasError - Whether the execution ended with an error
+ * @returns The appropriate execution status
+ */
+export declare function determineResultStatus(cancelRequested: boolean, aborted: boolean, hasError: boolean): ExecutionStatus;
+/**
+ * Return type for createHookRunner utility.
+ */
+export type HookRunner = {
+    /**
+     * Ensures hooks run exactly once.
+     * Safe to call multiple times - only executes on first call.
+     */
+    ensureRun: () => Promise<void>;
+    /**
+     * Check if hooks have already been run.
+     */
+    hasRun: () => boolean;
+};
+/**
+ * Creates a hook runner that ensures hooks run exactly once.
+ *
+ * This utility encapsulates the common pattern of running cleanup hooks
+ * with a guard flag to prevent double execution. Both SimpleExecutionHost
+ * and StreamingExecutionHost use this pattern for onDone hooks.
+ *
+ * @param runHooks - The async function to run hooks
+ * @returns Object with ensureRun() and hasRun() methods
+ *
+ * @example
+ * ```typescript
+ * const hookRunner = createHookRunner(async () => {
+ *   await session.runOnDoneHooks();
+ * });
+ *
+ * // In finally block or cleanup:
+ * await hookRunner.ensureRun();
+ *
+ * // Safe to call multiple times - only executes once
+ * await hookRunner.ensureRun(); // no-op
+ * ```
+ */
+export declare function createHookRunner(runHooks: () => Promise<void>): HookRunner;
+//# sourceMappingURL=shared.d.ts.map

package/dist/execution/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/execution/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAKzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAEpD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,eAAe,EAAE,OAAO,EACxB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,OAAO,GAChB,eAAe,CAajB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B;;OAEG;IACH,MAAM,EAAE,MAAM,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,UAAU,CAY1E"}

package/dist/execution/shared.js

@@ -0,0 +1,100 @@
+/**
+ * Shared utilities for execution hosts.
+ *
+ * These functions extract common patterns from SimpleExecutionHost and
+ * StreamingExecutionHost to reduce code duplication and ensure consistent
+ * behavior across both implementations.
+ */
+/**
+ * Checks if an error is an abort-related error.
+ *
+ * An error is considered abort-related if either:
+ * - The error has the name 'AbortError' (standard for AbortController)
+ * - The signal has been aborted (covers edge cases where error name differs)
+ *
+ * @param error - The error to check
+ * @param signal - The AbortSignal associated with the execution
+ * @returns true if this is an abort-related error
+ */
+export function isAbortError(error, signal) {
+    if (error instanceof Error && error.name === 'AbortError') {
+        return true;
+    }
+    return signal.aborted;
+}
+/**
+ * Normalizes an unknown error to an Error instance.
+ *
+ * If the error is already an Error instance, it's returned as-is.
+ * Otherwise, it's converted to a string and wrapped in a new Error.
+ *
+ * @param error - The unknown error to normalize
+ * @returns A proper Error instance
+ */
+export function normalizeError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/**
+ * Determines the execution status based on the execution state.
+ *
+ * Status determination priority:
+ * 1. If user called cancel() OR the operation was aborted → 'canceled'
+ * 2. If there's an error → 'failed'
+ * 3. Otherwise → 'succeeded'
+ *
+ * Note: The 'aborted' flag takes precedence over 'hasError' because
+ * AbortError is treated as a normal cancellation, not a failure.
+ *
+ * @param cancelRequested - Whether cancel() was explicitly called
+ * @param aborted - Whether the signal was aborted (includes external abort)
+ * @param hasError - Whether the execution ended with an error
+ * @returns The appropriate execution status
+ */
+export function determineResultStatus(cancelRequested, aborted, hasError) {
+    // Cancellation takes priority (abort errors are treated as cancellation)
+    if (cancelRequested || aborted) {
+        return 'canceled';
+    }
+    // Error state
+    if (hasError) {
+        return 'failed';
+    }
+    // Success
+    return 'succeeded';
+}
+/**
+ * Creates a hook runner that ensures hooks run exactly once.
+ *
+ * This utility encapsulates the common pattern of running cleanup hooks
+ * with a guard flag to prevent double execution. Both SimpleExecutionHost
+ * and StreamingExecutionHost use this pattern for onDone hooks.
+ *
+ * @param runHooks - The async function to run hooks
+ * @returns Object with ensureRun() and hasRun() methods
+ *
+ * @example
+ * ```typescript
+ * const hookRunner = createHookRunner(async () => {
+ *   await session.runOnDoneHooks();
+ * });
+ *
+ * // In finally block or cleanup:
+ * await hookRunner.ensureRun();
+ *
+ * // Safe to call multiple times - only executes once
+ * await hookRunner.ensureRun(); // no-op
+ * ```
+ */
+export function createHookRunner(runHooks) {
+    let ran = false;
+    return {
+        ensureRun: async () => {
+            if (!ran) {
+                ran = true;
+                await runHooks();
+            }
+        },
+        hasRun: () => ran,
+    };
+}
+//# sourceMappingURL=shared.js.map

package/dist/execution/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/execution/shared.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,MAAmB;IAC9D,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CACnC,eAAwB,EACxB,OAAgB,EAChB,QAAiB;IAEjB,yEAAyE;IACzE,IAAI,eAAe,IAAI,OAAO,EAAE,CAAC;QAC/B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,cAAc;IACd,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,UAAU;IACV,OAAO,WAAW,CAAC;AACrB,CAAC;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA6B;IAC5D,IAAI,GAAG,GAAG,KAAK,CAAC;IAEhB,OAAO;QACL,SAAS,EAAE,KAAK,IAAI,EAAE;YACpB,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,GAAG,GAAG,IAAI,CAAC;gBACX,MAAM,QAAQ,EAAE,CAAC;YACnB,CAAC;QACH,CAAC;QACD,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG;KAClB,CAAC;AACJ,CAAC"}

package/dist/execution/simple-host.d.ts

@@ -0,0 +1,56 @@
+import type { SimpleSession } from '../session/simple-session.js';
+import type { SimpleExecution, SimpleResult } from './types.js';
+/**
+ * SimpleExecutionHost implements the SimpleExecution interface for eager execution.
+ *
+ * Execution starts immediately on construction (eager evaluation).
+ * Use result() to get the execution outcome with status and summary.
+ *
+ * Signal combination:
+ * - If userSignal is provided, it's combined with internal AbortController
+ * - Both cancel() and userSignal abort will trigger cancellation
+ * - The combined signal is passed to SimpleSession for AI SDK calls
+ *
+ * @example
+ * ```typescript
+ * const execution = new SimpleExecutionHost(createSession, async (session) => {
+ *   return await session.generateText({ prompt: 'Hello' });
+ * });
+ *
+ * const result = await execution.result();
+ *
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value);
+ * }
+ * console.log(`Cost: $${result.summary.totalCost}`);
+ * ```
+ */
+export declare class SimpleExecutionHost<TResult> implements SimpleExecution<TResult> {
+    private readonly abortController;
+    private readonly effectiveSignal;
+    private readonly consumerPromise;
+    private cachedSession?;
+    private readonly startTime;
+    private cancelRequested;
+    constructor(createSession: (signal?: AbortSignal) => SimpleSession, fn: (session: SimpleSession) => Promise<TResult>, userSignal?: AbortSignal);
+    private execute;
+    /**
+     * Request cancellation of the execution.
+     * Aborts the current LLM call if in progress.
+     * No-op if execution already completed.
+     */
+    cancel(): void;
+    /**
+     * Get the execution result with status and summary.
+     * Never throws - returns a discriminated union with status.
+     */
+    result(): Promise<SimpleResult<TResult>>;
+    /**
+     * Cleanup resources.
+     * For SimpleExecution, hooks are already run during execution,
+     * so this is intentionally a no-op.
+     */
+    cleanup(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=simple-host.d.ts.map

package/dist/execution/simple-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-host.d.ts","sourceRoot":"","sources":["../../src/execution/simple-host.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAYhE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,mBAAmB,CAAC,OAAO,CAAE,YAAW,eAAe,CAAC,OAAO,CAAC;IAC3E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAc;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,eAAe,CAAS;IAEhC,YACE,aAAa,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,aAAa,EACtD,EAAE,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,EAChD,UAAU,CAAC,EAAE,WAAW,EASzB;YAEa,OAAO;IA0CrB;;;;OAIG;IACH,MAAM,IAAI,IAAI,CAGb;IAED;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CA0B7C;IAED;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7B;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;CACF"}

package/dist/execution/simple-host.js

@@ -0,0 +1,126 @@
+import { combineSignals } from './utils.js';
+import { isAbortError, normalizeError, createHookRunner } from './shared.js';
+/**
+ * SimpleExecutionHost implements the SimpleExecution interface for eager execution.
+ *
+ * Execution starts immediately on construction (eager evaluation).
+ * Use result() to get the execution outcome with status and summary.
+ *
+ * Signal combination:
+ * - If userSignal is provided, it's combined with internal AbortController
+ * - Both cancel() and userSignal abort will trigger cancellation
+ * - The combined signal is passed to SimpleSession for AI SDK calls
+ *
+ * @example
+ * ```typescript
+ * const execution = new SimpleExecutionHost(createSession, async (session) => {
+ *   return await session.generateText({ prompt: 'Hello' });
+ * });
+ *
+ * const result = await execution.result();
+ *
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value);
+ * }
+ * console.log(`Cost: $${result.summary.totalCost}`);
+ * ```
+ */
+export class SimpleExecutionHost {
+    abortController = new AbortController();
+    effectiveSignal;
+    consumerPromise;
+    cachedSession;
+    startTime = Date.now();
+    cancelRequested = false;
+    constructor(createSession, fn, userSignal) {
+        // Combine user signal with internal controller for dual cancellation support
+        this.effectiveSignal = userSignal
+            ? combineSignals(userSignal, this.abortController.signal)
+            : this.abortController.signal;
+        // Start execution immediately (eager evaluation)
+        this.consumerPromise = this.execute(createSession, fn);
+    }
+    async execute(createSession, fn) {
+        const session = createSession(this.effectiveSignal);
+        this.cachedSession = session;
+        const hookRunner = createHookRunner(() => session.runOnDoneHooks());
+        // Notify execution start
+        session.notifyExecutionStart();
+        try {
+            const result = await fn(session);
+            // Notify execution done
+            await session.notifyExecutionDone(result, this.startTime);
+            return {
+                success: true,
+                result,
+                summary: await session.getSummary(),
+            };
+        }
+        catch (error) {
+            const errorObj = normalizeError(error);
+            const isCancellation = isAbortError(error, this.abortController.signal);
+            // Notify execution error (AbortError excluded - treated as normal cancellation)
+            if (!isCancellation) {
+                await session.notifyExecutionError(errorObj, this.startTime);
+            }
+            return {
+                success: false,
+                error: errorObj,
+                aborted: isCancellation,
+                summary: await session.getSummary(),
+            };
+        }
+        finally {
+            await hookRunner.ensureRun();
+        }
+    }
+    /**
+     * Request cancellation of the execution.
+     * Aborts the current LLM call if in progress.
+     * No-op if execution already completed.
+     */
+    cancel() {
+        this.cancelRequested = true;
+        this.abortController.abort();
+    }
+    /**
+     * Get the execution result with status and summary.
+     * Never throws - returns a discriminated union with status.
+     */
+    async result() {
+        const internal = await this.consumerPromise;
+        // Success state
+        if (internal.success) {
+            return {
+                status: 'succeeded',
+                value: internal.result,
+                summary: internal.summary,
+            };
+        }
+        // Canceled state (user called cancel() or external signal aborted)
+        if (this.cancelRequested || internal.aborted) {
+            return {
+                status: 'canceled',
+                summary: internal.summary,
+            };
+        }
+        // Failed state
+        return {
+            status: 'failed',
+            error: internal.error,
+            summary: internal.summary,
+        };
+    }
+    /**
+     * Cleanup resources.
+     * For SimpleExecution, hooks are already run during execution,
+     * so this is intentionally a no-op.
+     */
+    async cleanup() {
+        // SimpleExecution runs hooks in execute(), nothing to clean up
+    }
+    async [Symbol.asyncDispose]() {
+        await this.cleanup();
+    }
+}
+//# sourceMappingURL=simple-host.js.map

package/dist/execution/simple-host.js.map

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

package/dist/execution/streaming-host.d.ts

@@ -0,0 +1,79 @@
+import type { StreamingSession } from '../session/streaming-session.js';
+import type { ErrorEvent, ExtractResult, SessionEvent, SessionStreamGeneratorFn, StreamingExecution, StreamingResult } from './types.js';
+/**
+ * Streaming execution host that uses StreamingSession.
+ * Starts execution eagerly on construction - events are buffered automatically.
+ *
+ * @typeParam TEvent - User's pure domain event type with required `type` field (metrics added automatically)
+ *
+ * @example
+ * ```typescript
+ * const execution = new StreamingExecutionHost(
+ *   () => new StreamingSession({
+ *     defaultLanguageModel: provider.model,
+ *     fileManager: new GoogleFileManager(apiKey),
+ *   }),
+ *   async function* (session) {
+ *     session.onDone(() => session.fileManager.clear());
+ *     const result = await session.generateText({ prompt: 'Hello' });
+ *     yield session.emit({ type: 'progress', message: 'Working...' });
+ *     return session.done(result.text);
+ *   }
+ * );
+ * // ↑ Execution already started, events being buffered
+ *
+ * // Option 1: Stream events (buffered + real-time)
+ * for await (const event of execution.stream()) {
+ *   console.log(event.type, event.metrics.elapsedMs);
+ * }
+ * const result = await execution.result();
+ *
+ * // Option 2: Skip streaming, events available in result
+ * const result = await execution.result();
+ * console.log(`Received ${result.events.length} events`);
+ *
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value);
+ * }
+ * ```
+ */
+export declare class StreamingExecutionHost<TEvent extends {
+    type: string;
+}> implements StreamingExecution<TEvent> {
+    private readonly createSession;
+    private readonly generator;
+    private readonly abortController;
+    private readonly effectiveSignal;
+    private readonly consumerPromise;
+    private readonly eventBuffer;
+    private readonly subscribers;
+    private completed;
+    private cleaned;
+    private hookRunner;
+    private cancelRequested;
+    private extractedOutcome;
+    private extractedSummary;
+    constructor(createSession: (signal?: AbortSignal) => StreamingSession<TEvent>, generator: SessionStreamGeneratorFn<TEvent>, userSignal?: AbortSignal);
+    private hasDataField;
+    private hasSummaryField;
+    private hasErrorField;
+    private extractResultAndMetadata;
+    private notifySubscribers;
+    private startConsuming;
+    private buildResult;
+    /**
+     * Get the event stream.
+     * Returns buffered events first, then real-time events.
+     * Can be called multiple times - replays buffer each time.
+     */
+    stream(): AsyncIterable<SessionEvent<TEvent | ErrorEvent>>;
+    cancel(): void;
+    cleanup(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Get the execution result with status, summary, and all events.
+     * Never throws - returns a discriminated union with status.
+     */
+    result(): Promise<StreamingResult<SessionEvent<TEvent | ErrorEvent>, ExtractResult<TEvent>>>;
+}
+//# sourceMappingURL=streaming-host.d.ts.map

package/dist/execution/streaming-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-host.d.ts","sourceRoot":"","sources":["../../src/execution/streaming-host.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAYzI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,sBAAsB,CAC/B,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CACjC,YAAW,kBAAkB,CAAC,MAAM,CAAC;IAkB/B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAlB9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAc;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0D;IAC1F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoD;IAChF,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,gBAAgB,CAGN;IAClB,OAAO,CAAC,gBAAgB,CAA+B;IAEvD,YACqB,aAAa,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,gBAAgB,CAAC,MAAM,CAAC,EACjE,SAAS,EAAE,wBAAwB,CAAC,MAAM,CAAC,EAC5D,UAAU,CAAC,EAAE,WAAW,EAS3B;IAED,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,wBAAwB;IAmBhC,OAAO,CAAC,iBAAiB;YAIX,cAAc;YA8Ed,WAAW;IA8BzB;;;;OAIG;IACI,MAAM,IAAI,aAAa,CAAC,YAAY,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,CAkChE;IAED,MAAM,IAAI,IAAI,CAGb;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAgB7B;IAEK,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;IAED;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CA8BjG;CACJ"}