@alveus-ai/std 0.1.0

package/dist/agents/react.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @alveus-ai/std - Standard Library for Alveus
+ *
+ * Provides reusable agents and utilities for common patterns.
+ *
+ * @example
+ * ```ts
+ * import { createChatAgent } from '@alveus-ai/std/agents';
+ * import { saveHistory, loadHistory } from '@alveus-ai/std/memory';
+ *
+ * // Create a chat agent
+ * const assistant = createChatAgent('You are a helpful assistant.');
+ *
+ * // In agent handler, manage history
+ * const history = await loadHistory(ctx, event.historyRef);
+ * // ... use history
+ * const ref = await saveHistory(ctx, history);
+ * ```
+ */
+export * from './agents/index.js';
+export * from './memory/index.js';
+export * from './patterns/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,cAAc,mBAAmB,CAAC;AAGlC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @alveus-ai/std - Standard Library for Alveus
+ *
+ * Provides reusable agents and utilities for common patterns.
+ *
+ * @example
+ * ```ts
+ * import { createChatAgent } from '@alveus-ai/std/agents';
+ * import { saveHistory, loadHistory } from '@alveus-ai/std/memory';
+ *
+ * // Create a chat agent
+ * const assistant = createChatAgent('You are a helpful assistant.');
+ *
+ * // In agent handler, manage history
+ * const history = await loadHistory(ctx, event.historyRef);
+ * // ... use history
+ * const ref = await saveHistory(ctx, history);
+ * ```
+ */
+// Re-export all agents
+export * from './agents/index.js';
+// Re-export all memory utilities
+export * from './memory/index.js';
+// Re-export all patterns
+export * from './patterns/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,uBAAuB;AACvB,cAAc,mBAAmB,CAAC;AAElC,iCAAiC;AACjC,cAAc,mBAAmB,CAAC;AAElC,yBAAyB;AACzB,cAAc,qBAAqB,CAAC"}

package/dist/memory/history.d.ts

@@ -0,0 +1,109 @@
+/**
+ * History Manager - Intelligent Context Window Management
+ *
+ * Handles large conversation histories by offloading to blob storage.
+ * This solves the "Infinite Context" problem where conversations can
+ * grow beyond message size limits.
+ *
+ * Key features:
+ * - Automatic offloading when history exceeds threshold
+ * - Content-addressed storage for deduplication
+ * - Transparent loading/saving API
+ *
+ * @example
+ * ```ts
+ * // In an agent handler:
+ * const history = await loadHistory(ctx, event.historyRef);
+ * history.push({ role: 'user', content: event.message });
+ * history.push({ role: 'assistant', content: reply });
+ *
+ * // Save and potentially offload
+ * const ref = await saveHistory(ctx, history);
+ *
+ * // Pass ref to child agent (small payload even if history is huge)
+ * await ctx.call(childAgent, { historyRef: ref });
+ * ```
+ */
+import type { ExecutionContext, ChatMessage } from '@alveus-ai/core';
+/**
+ * Reference to history stored in blob storage
+ */
+export interface HistoryRef {
+    type: 'blob_ref';
+    key: string;
+    summary?: string;
+    messageCount?: number;
+}
+/**
+ * Union type for history that may be inline or referenced
+ */
+export type HistoryData = ChatMessage[] | HistoryRef;
+/**
+ * Options for history management
+ */
+export interface HistoryOptions {
+    /**
+     * Size threshold in bytes before offloading to blob storage
+     * Default: 10KB
+     */
+    offloadThreshold?: number;
+    /**
+     * Include a summary in the reference for debugging
+     * Default: true
+     */
+    includeSummary?: boolean;
+}
+/**
+ * Check if data is a blob reference
+ */
+export declare function isHistoryRef(data: HistoryData): data is HistoryRef;
+/**
+ * Save conversation history, offloading to blob storage if large
+ *
+ * @param ctx - The execution context with storage capability
+ * @param messages - The conversation history to save
+ * @param options - Configuration options
+ * @returns Inline messages if small, or a HistoryRef if offloaded
+ */
+export declare function saveHistory(ctx: ExecutionContext, messages: ChatMessage[], options?: HistoryOptions): Promise<HistoryData>;
+/**
+ * Load conversation history, retrieving from blob storage if necessary
+ *
+ * @param ctx - The execution context with storage capability
+ * @param ref - The history data (inline messages or blob reference)
+ * @returns The conversation history as an array of messages
+ */
+export declare function loadHistory(ctx: ExecutionContext, ref: HistoryData | undefined | null): Promise<ChatMessage[]>;
+/**
+ * Append a message to history and save
+ *
+ * Convenience function for common pattern of adding a message and saving.
+ *
+ * @param ctx - The execution context
+ * @param history - Current history (may be ref or inline)
+ * @param message - Message to append
+ * @param options - Save options
+ * @returns Updated history reference
+ */
+export declare function appendAndSave(ctx: ExecutionContext, history: HistoryData | undefined | null, message: ChatMessage, options?: HistoryOptions): Promise<HistoryData>;
+/**
+ * Truncate history to a maximum number of messages
+ *
+ * Keeps the most recent messages while preserving the system prompt.
+ *
+ * @param messages - The full history
+ * @param maxMessages - Maximum messages to keep (excluding system)
+ * @returns Truncated history
+ */
+export declare function truncateHistory(messages: ChatMessage[], maxMessages: number): ChatMessage[];
+/**
+ * Calculate approximate token count for history
+ *
+ * Uses a simple heuristic (4 chars per token) for estimation.
+ * For precise counts, use a tokenizer like tiktoken.
+ *
+ * @param messages - The conversation history
+ * @returns Estimated token count
+ */
+export declare function estimateTokens(messages: ChatMessage[]): number;
+//# sourceMappingURL=history.d.ts.map

package/dist/memory/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/memory/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAOD;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,UAAU,CAIlE;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,WAAW,EAAE,EACvB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,GAClC,OAAO,CAAC,WAAW,EAAE,CAAC,CAsBxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,EACvC,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAItB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CAY3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,MAAM,CAG9D"}

package/dist/memory/history.js

@@ -0,0 +1,140 @@
+/**
+ * History Manager - Intelligent Context Window Management
+ *
+ * Handles large conversation histories by offloading to blob storage.
+ * This solves the "Infinite Context" problem where conversations can
+ * grow beyond message size limits.
+ *
+ * Key features:
+ * - Automatic offloading when history exceeds threshold
+ * - Content-addressed storage for deduplication
+ * - Transparent loading/saving API
+ *
+ * @example
+ * ```ts
+ * // In an agent handler:
+ * const history = await loadHistory(ctx, event.historyRef);
+ * history.push({ role: 'user', content: event.message });
+ * history.push({ role: 'assistant', content: reply });
+ *
+ * // Save and potentially offload
+ * const ref = await saveHistory(ctx, history);
+ *
+ * // Pass ref to child agent (small payload even if history is huge)
+ * await ctx.call(childAgent, { historyRef: ref });
+ * ```
+ */
+const DEFAULT_OPTIONS = {
+    offloadThreshold: 1024 * 10, // 10KB
+    includeSummary: true,
+};
+/**
+ * Check if data is a blob reference
+ */
+export function isHistoryRef(data) {
+    return (typeof data === 'object' && !Array.isArray(data) && data !== null && data.type === 'blob_ref');
+}
+/**
+ * Save conversation history, offloading to blob storage if large
+ *
+ * @param ctx - The execution context with storage capability
+ * @param messages - The conversation history to save
+ * @param options - Configuration options
+ * @returns Inline messages if small, or a HistoryRef if offloaded
+ */
+export async function saveHistory(ctx, messages, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const payload = JSON.stringify(messages);
+    // If under threshold, return inline
+    if (payload.length <= opts.offloadThreshold) {
+        return messages;
+    }
+    // Offload to blob storage
+    const key = await ctx.storage.put(payload);
+    const ref = {
+        type: 'blob_ref',
+        key,
+        messageCount: messages.length,
+    };
+    if (opts.includeSummary) {
+        ref.summary = `History of ${messages.length} messages (${(payload.length / 1024).toFixed(1)}KB)`;
+    }
+    return ref;
+}
+/**
+ * Load conversation history, retrieving from blob storage if necessary
+ *
+ * @param ctx - The execution context with storage capability
+ * @param ref - The history data (inline messages or blob reference)
+ * @returns The conversation history as an array of messages
+ */
+export async function loadHistory(ctx, ref) {
+    // Handle undefined/null
+    if (!ref) {
+        return [];
+    }
+    // If inline array, return directly
+    if (Array.isArray(ref)) {
+        return ref;
+    }
+    // Load from blob storage
+    if (isHistoryRef(ref)) {
+        const raw = await ctx.storage.get(ref.key);
+        if (!raw) {
+            console.warn(`History not found for key: ${ref.key}`);
+            return [];
+        }
+        return JSON.parse(raw);
+    }
+    return [];
+}
+/**
+ * Append a message to history and save
+ *
+ * Convenience function for common pattern of adding a message and saving.
+ *
+ * @param ctx - The execution context
+ * @param history - Current history (may be ref or inline)
+ * @param message - Message to append
+ * @param options - Save options
+ * @returns Updated history reference
+ */
+export async function appendAndSave(ctx, history, message, options = {}) {
+    const messages = await loadHistory(ctx, history);
+    messages.push(message);
+    return saveHistory(ctx, messages, options);
+}
+/**
+ * Truncate history to a maximum number of messages
+ *
+ * Keeps the most recent messages while preserving the system prompt.
+ *
+ * @param messages - The full history
+ * @param maxMessages - Maximum messages to keep (excluding system)
+ * @returns Truncated history
+ */
+export function truncateHistory(messages, maxMessages) {
+    // Find system messages (usually first)
+    const systemMessages = messages.filter((m) => m.role === 'system');
+    const nonSystemMessages = messages.filter((m) => m.role !== 'system');
+    // Keep system messages + most recent conversation
+    if (nonSystemMessages.length <= maxMessages) {
+        return messages;
+    }
+    const recentMessages = nonSystemMessages.slice(-maxMessages);
+    return [...systemMessages, ...recentMessages];
+}
+/**
+ * Calculate approximate token count for history
+ *
+ * Uses a simple heuristic (4 chars per token) for estimation.
+ * For precise counts, use a tokenizer like tiktoken.
+ *
+ * @param messages - The conversation history
+ * @returns Estimated token count
+ */
+export function estimateTokens(messages) {
+    const totalChars = messages.reduce((sum, m) => sum + m.content.length, 0);
+    return Math.ceil(totalChars / 4);
+}
+//# sourceMappingURL=history.js.map

package/dist/memory/history.js.map

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

package/dist/memory/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Memory Management Utilities
+ *
+ * Tools for handling conversation history and large payloads.
+ */
+export { saveHistory, loadHistory, appendAndSave, truncateHistory, estimateTokens, isHistoryRef, type HistoryRef, type HistoryData, type HistoryOptions, } from './history.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,EACX,aAAa,EACb,eAAe,EACf,cAAc,EACd,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC"}

package/dist/memory/index.js

@@ -0,0 +1,7 @@
+/**
+ * Memory Management Utilities
+ *
+ * Tools for handling conversation history and large payloads.
+ */
+export { saveHistory, loadHistory, appendAndSave, truncateHistory, estimateTokens, isHistoryRef, } from './history.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,EACX,aAAa,EACb,eAAe,EACf,cAAc,EACd,YAAY,GAIb,MAAM,cAAc,CAAC"}

package/dist/patterns/approval.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Approval Pattern - Human-in-the-Loop Workflows
+ *
+ * Provides utilities for implementing approval workflows where
+ * agents can pause and wait for human decisions.
+ *
+ * Uses the Event capability for durable waiting:
+ * 1. Emit an "approval-needed" event with request details
+ * 2. Wait for an "approval-response" event
+ * 3. Continue based on the approval decision
+ *
+ * @example
+ * ```ts
+ * import { waitForApproval, type ApprovalRequest } from '@alveus-ai/std/patterns';
+ *
+ * const myAgent = agent$(async (state, event, ctx) => {
+ *   // Do some work...
+ *   const result = await performRiskyOperation();
+ *
+ *   // Request human approval before continuing
+ *   const approval = await waitForApproval(ctx, {
+ *     action: 'deploy-to-production',
+ *     details: { version: '1.2.3', environment: 'prod' },
+ *     message: 'Please approve deployment to production',
+ *   });
+ *
+ *   if (!approval.approved) {
+ *     return { status: 'rejected', reason: approval.reason };
+ *   }
+ *
+ *   // Continue with deployment...
+ *   return { status: 'deployed', approvedBy: approval.approvedBy };
+ * });
+ * ```
+ */
+import type { ExecutionContext } from '@alveus-ai/core';
+/**
+ * Request for approval
+ */
+export interface ApprovalRequest {
+    /** The action requiring approval */
+    action: string;
+    /** Additional details about the action */
+    details?: Record<string, unknown>;
+    /** Human-readable message for the approver */
+    message?: string;
+    /** Timeout in milliseconds (default: 24 hours) */
+    timeoutMs?: number;
+}
+/**
+ * Response from an approval request
+ */
+export interface ApprovalResponse {
+    /** Whether the action was approved */
+    approved: boolean;
+    /** Who approved/rejected (if known) */
+    approvedBy?: string;
+    /** Reason for rejection (if rejected) */
+    reason?: string;
+    /** Timestamp of the decision */
+    timestamp: number;
+}
+/**
+ * Topics used for approval events
+ */
+export declare const ApprovalTopics: {
+    /** Topic for approval requests */
+    readonly NEEDED: "approval.needed";
+    /** Topic for approval responses */
+    readonly RESPONSE: "approval.response";
+};
+/**
+ * Wait for human approval
+ *
+ * Emits an approval request event and durably waits for a response.
+ * The workflow will pause until an approval response is received.
+ *
+ * @param ctx - The execution context
+ * @param request - The approval request details
+ * @returns The approval response
+ * @throws Error if timeout is reached
+ */
+export declare function waitForApproval(ctx: ExecutionContext, request: ApprovalRequest): Promise<ApprovalResponse>;
+/**
+ * Send an approval decision
+ *
+ * Use this from an approval UI or API to respond to an approval request.
+ * The response will be delivered to the waiting workflow via the Event Bridge.
+ *
+ * @param ctx - The execution context
+ * @param workflowId - The ID of the workflow waiting for approval
+ * @param approved - Whether to approve or reject
+ * @param options - Additional response options
+ */
+export declare function sendApproval(ctx: ExecutionContext, workflowId: string, approved: boolean, options?: {
+    approvedBy?: string;
+    reason?: string;
+}): Promise<void>;
+/**
+ * Create an approval-gated operation wrapper
+ *
+ * Wraps an async operation with an approval requirement.
+ * The operation will only execute if approval is granted.
+ *
+ * @param operation - The operation requiring approval
+ * @param getRequest - Function to build the approval request from the input
+ * @returns A function that requests approval before executing
+ *
+ * @example
+ * ```ts
+ * const safeDelete = requireApproval(
+ *   async (ctx, userId: string) => {
+ *     await database.deleteUser(userId);
+ *     return { deleted: userId };
+ *   },
+ *   (userId) => ({
+ *     action: 'delete-user',
+ *     details: { userId },
+ *     message: `Delete user ${userId}?`,
+ *   })
+ * );
+ *
+ * // In agent handler:
+ * const result = await safeDelete(ctx, 'user-123');
+ * if (!result.approved) {
+ *   return { error: 'Deletion rejected' };
+ * }
+ * return result.result;
+ * ```
+ */
+export declare function requireApproval<TInput, TResult>(operation: (ctx: ExecutionContext, input: TInput) => Promise<TResult>, getRequest: (input: TInput) => ApprovalRequest): (ctx: ExecutionContext, input: TInput) => Promise<{
+    approved: true;
+    result: TResult;
+    approvedBy?: string;
+} | {
+    approved: false;
+    reason?: string;
+}>;
+/**
+ * Multi-step approval chain
+ *
+ * Requires multiple approvals before proceeding.
+ * Useful for critical operations requiring sign-off from multiple parties.
+ *
+ * @param ctx - The execution context
+ * @param request - The base approval request
+ * @param approvers - List of required approver identifiers
+ * @returns Array of approval responses
+ */
+export declare function waitForMultipleApprovals(ctx: ExecutionContext, request: ApprovalRequest, approvers: string[]): Promise<ApprovalResponse[]>;
+//# sourceMappingURL=approval.d.ts.map

package/dist/patterns/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/patterns/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IAEf,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,QAAQ,EAAE,OAAO,CAAC;IAElB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;IACzB,kCAAkC;;IAGlC,mCAAmC;;CAE3B,CAAC;AAEX;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAwB3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAC7C,SAAS,EAAE,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EACrE,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,eAAe,GAC7C,CACD,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,MAAM,KACV,OAAO,CACV;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAChG,CAmBA;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,gBAAgB,EACrB,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoC7B"}