groundswell 0.0.2 → 1.0.0

package/dist/types/streaming.js

@@ -0,0 +1,67 @@
+/**
+ * Streaming types for LLM streaming responses
+ *
+ * Provides types and utilities for streaming responses from LLM providers.
+ * Uses TypeScript's built-in AsyncGenerator for efficient streaming.
+ */
+/**
+ * Type guard for text delta events
+ *
+ * Narrows StreamEvent to text_delta type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is a text_delta event
+ *
+ * @example
+ * ```ts
+ * if (isTextDeltaEvent(event)) {
+ *   console.log(event.delta); // TypeScript knows delta exists
+ *   console.log(event.index); // TypeScript knows index exists
+ * }
+ * ```
+ */
+export function isTextDeltaEvent(event) {
+    return event.type === 'text_delta';
+}
+/**
+ * Type guard for tool call events
+ *
+ * Narrows StreamEvent to any tool call event type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is a tool_call_start, tool_call_delta, or tool_call_done event
+ *
+ * @example
+ * ```ts
+ * if (isToolCallEvent(event)) {
+ *   if (event.type === 'tool_call_start') {
+ *     console.log(event.name); // TypeScript knows name exists
+ *   }
+ * }
+ * ```
+ */
+export function isToolCallEvent(event) {
+    return event.type === 'tool_call_start' || event.type === 'tool_call_delta' || event.type === 'tool_call_done';
+}
+/**
+ * Type guard for error events
+ *
+ * Narrows StreamEvent to error type for type-safe access.
+ *
+ * @param event - The stream event to check
+ * @returns True if the event is an error event
+ *
+ * @example
+ * ```ts
+ * if (isErrorEvent(event)) {
+ *   console.error(event.error.message); // TypeScript knows error exists
+ *   if (event.retryable) {
+ *     // Retry logic
+ *   }
+ * }
+ * ```
+ */
+export function isErrorEvent(event) {
+    return event.type === 'error';
+}
+//# sourceMappingURL=streaming.js.map

package/dist/types/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/types/streaming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgHH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB;IAChD,OAAO,KAAK,CAAC,IAAI,KAAK,iBAAiB,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC;AACjH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAkB;IAC7C,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC;AAChC,CAAC"}

package/dist/types/workflow-context.d.ts

@@ -0,0 +1,275 @@
+/**
+ * WorkflowContext - Interface for functional workflow execution
+ *
+ * Provides step(), spawnWorkflow(), and other methods for
+ * composing workflows in arbitrary JavaScript control flow.
+ */
+import type { WorkflowNode } from './workflow.js';
+import type { ReflectionAPI } from './reflection.js';
+import type { AgentResponse } from './agent.js';
+import type { ErrorMergeStrategy } from './error-strategy.js';
+export type { ReflectionAPI } from './reflection.js';
+/**
+ * Handle for querying the event tree
+ */
+export interface EventTreeHandle {
+    /** Root node of the event tree */
+    readonly root: EventNode;
+    /**
+     * Get a node by ID
+     * @param id Node ID to find
+     */
+    getNode(id: string): EventNode | undefined;
+    /**
+     * Get all children of a node
+     * @param id Parent node ID
+     */
+    getChildren(id: string): EventNode[];
+    /**
+     * Get all ancestors of a node (from node up to root)
+     * @param id Node ID
+     */
+    getAncestors(id: string): EventNode[];
+    /**
+     * Export tree as JSON
+     */
+    toJSON(): EventNode;
+}
+/**
+ * Event node in the queryable tree
+ */
+export interface EventNode {
+    id: string;
+    type: string;
+    timestamp: number;
+    name?: string;
+    payload?: unknown;
+    metrics?: EventMetrics;
+    parentId?: string;
+    children: EventNode[];
+}
+/**
+ * Metrics associated with an event node
+ */
+export interface EventMetrics {
+    duration?: number;
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+    toolCalls?: number;
+}
+/**
+ * Agent interface for context revision (minimal to avoid circular deps)
+ */
+export interface AgentLike {
+    prompt<T>(prompt: PromptLike<T>): Promise<AgentResponse<T>>;
+}
+/**
+ * Prompt interface for context revision (minimal to avoid circular deps)
+ */
+export interface PromptLike<T> {
+    id: string;
+    buildUserMessage(): string;
+    validateResponse(data: unknown): T;
+}
+/**
+ * WorkflowContext - Available within functional workflow executor
+ */
+export interface WorkflowContext {
+    /** Unique ID of this workflow */
+    readonly workflowId: string;
+    /** Parent workflow ID if nested */
+    readonly parentWorkflowId?: string;
+    /**
+     * Execute a named step
+     * Can be called anywhere in JavaScript control flow (loops, conditionals, etc.)
+     *
+     * @param name Step name for logging and debugging
+     * @param fn Step function to execute
+     * @returns Result of the step function
+     */
+    step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Spawn a child workflow
+     * The child workflow is automatically attached to this workflow's tree
+     *
+     * @param workflow Workflow instance to spawn
+     * @returns Result of the child workflow
+     */
+    spawnWorkflow<T>(workflow: {
+        run(): Promise<T>;
+    }): Promise<T>;
+    /**
+     * Replace the last prompt result with a new one (context revision)
+     * The previous prompt node is marked as 'revised' and the new result is attached as sibling
+     *
+     * @param newPrompt The new prompt to execute
+     * @param agent The agent to use for execution
+     * @returns Result of the new prompt
+     */
+    replaceLastPromptResult<T>(newPrompt: PromptLike<T>, agent: AgentLike): Promise<T>;
+    /**
+     * Access to the event tree for this workflow
+     */
+    readonly eventTree: EventTreeHandle;
+    /**
+     * Reflection API for error handling and retry logic
+     */
+    readonly reflection: ReflectionAPI;
+}
+/**
+ * Event history configuration for workflow execution
+ *
+ * @remarks
+ * When enabled, events are stored in memory and can be accessed via
+ * the workflow's replay functionality. Events include step execution,
+ * errors, agent prompts, tool invocations, and state changes.
+ *
+ * **Memory Management:**
+ * - Events are trimmed based on both count (`maxEvents`) and age (`maxAgeMs`)
+ * - Lazy trimming is used for performance (only trims when significantly over limit)
+ * - When disabled, no events are stored in history (still emitted to observers)
+ *
+ * **Performance Impact:**
+ * - Enabled: Minimal overhead (~1-2ms per event)
+ * - Disabled: Zero overhead
+ *
+ * @example Enable event history with defaults
+ * ```ts
+ * const config: WorkflowConfig = {
+ *   name: 'MyWorkflow',
+ *   eventHistory: { enabled: true }
+ * };
+ * ```
+ *
+ * @example Custom limits
+ * ```ts
+ * const config: WorkflowConfig = {
+ *   name: 'MyWorkflow',
+ *   eventHistory: {
+ *     enabled: true,
+ *     maxEvents: 500,
+ *     maxAgeMs: 1800000  // 30 minutes
+ *   }
+ * };
+ * ```
+ */
+export interface EventHistoryConfig {
+    /**
+     * Enable event history collection
+     *
+     * When false (default), no events are stored in history.
+     * Events are still emitted to observers in real-time.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of events to store in history
+     *
+     * When the limit is exceeded, oldest events are removed first.
+     * Uses lazy trimming for performance (trims at 1.5x the limit).
+     *
+     * @default 1000
+     * @minimum 1
+     */
+    maxEvents?: number;
+    /**
+     * Maximum age of events in milliseconds
+     *
+     * Events older than this are removed from history.
+     * Age is based on insertion time, not event timestamp.
+     *
+     * @default 3600000 (1 hour)
+     * @minimum 1000 (1 second)
+     */
+    maxAgeMs?: number;
+}
+/**
+ * Configuration for creating a functional workflow
+ */
+export interface WorkflowConfig {
+    /** Human-readable workflow name */
+    name?: string;
+    /** Enable reflection for this workflow */
+    enableReflection?: boolean;
+    /** Automatically validate AgentResponse results after agent.prompt() calls */
+    autoValidateResponses?: boolean;
+    /**
+     * Event history configuration
+     *
+     * @remarks
+     * Controls whether events are stored in memory for replay functionality.
+     * When disabled (default), events are still emitted to observers but not
+     * stored in the internal event history array.
+     *
+     * @example Enable with defaults
+     * ```ts
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow',
+     *   eventHistory: { enabled: true }
+     * };
+     * ```
+     *
+     * @example Custom limits
+     * ```ts
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow',
+     *   eventHistory: {
+     *     enabled: true,
+     *     maxEvents: 500,
+     *     maxAgeMs: 1800000
+     *   }
+     * };
+     * ```
+     */
+    eventHistory?: EventHistoryConfig;
+    /**
+     * Strategy for merging multiple errors
+     *
+     * @remarks
+     * When provided, enables workflow-level error merge for multiple failures.
+     * Default: undefined (first error wins behavior).
+     *
+     * @example
+     * ```ts
+     * // Enable error merging with default strategy
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow',
+     *   errorMergeStrategy: { enabled: true }
+     * };
+     *
+     * // Enable with custom combine function
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow',
+     *   errorMergeStrategy: {
+     *     enabled: true,
+     *     combine: (errors) => ({
+     *       message: `Custom: ${errors.length} failures`,
+     *       // ... custom error object
+     *     })
+     *   }
+     * };
+     *
+     * // Default behavior (first error wins)
+     * const config: WorkflowConfig = {
+     *   name: 'MyWorkflow'
+     *   // errorMergeStrategy not provided = first error wins
+     * };
+     * ```
+     */
+    errorMergeStrategy?: ErrorMergeStrategy;
+}
+/**
+ * Result from workflow execution
+ */
+export interface WorkflowResult<T = unknown> {
+    /** The result value */
+    data: T;
+    /** The workflow node */
+    node: WorkflowNode;
+    /** Total duration in milliseconds */
+    duration: number;
+}
+//# sourceMappingURL=workflow-context.d.ts.map

package/dist/types/workflow-context.d.ts.map

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

package/dist/types/workflow-context.js

@@ -0,0 +1,8 @@
+/**
+ * WorkflowContext - Interface for functional workflow execution
+ *
+ * Provides step(), spawnWorkflow(), and other methods for
+ * composing workflows in arbitrary JavaScript control flow.
+ */
+export {};
+//# sourceMappingURL=workflow-context.js.map

package/dist/types/workflow-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-context.js","sourceRoot":"","sources":["../../src/types/workflow-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/types/workflow.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Workflow status representing the current execution state
+ */
+export type WorkflowStatus = 'idle' | 'running' | 'completed' | 'failed' | 'cancelled';
+import type { LogEntry } from './logging.js';
+import type { WorkflowEvent } from './events.js';
+import type { SerializedWorkflowState } from './snapshot.js';
+/**
+ * Represents a node in the workflow execution tree
+ * This is the data structure, not the Workflow class
+ */
+export interface WorkflowNode {
+    /** Unique identifier for this workflow instance */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Parent node reference (null for root) */
+    parent: WorkflowNode | null;
+    /** Child workflow nodes */
+    children: WorkflowNode[];
+    /** Current execution status */
+    status: WorkflowStatus;
+    /** Log entries for this node */
+    logs: LogEntry[];
+    /** Events emitted by this node */
+    events: WorkflowEvent[];
+    /** Optional serialized state snapshot */
+    stateSnapshot: SerializedWorkflowState | null;
+}
+//# sourceMappingURL=workflow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/types/workflow.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,SAAS,GACT,WAAW,GACX,QAAQ,GACR,WAAW,CAAC;AAGhB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,2BAA2B;IAC3B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,+BAA+B;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,gCAAgC;IAChC,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,kCAAkC;IAClC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,yCAAyC;IACzC,aAAa,EAAE,uBAAuB,GAAG,IAAI,CAAC;CAC/C"}

package/dist/types/workflow.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workflow.js.map

package/dist/types/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/types/workflow.ts"],"names":[],"mappings":""}

package/dist/utils/agent-validation.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Agent response validation utilities
+ *
+ * Provides pure, side-effect-free functions for validating AgentResponse
+ * instances using Zod schemas. The utilities enable both Agent and Workflow
+ * classes to perform validation without duplicating code.
+ *
+ * @module agent-validation
+ */
+import type { AgentResponse } from '../types/agent.js';
+import { z } from 'zod';
+/**
+ * Validation result type for agent response validation
+ *
+ * Provides structured validation result with boolean validity flag
+ * and optional ZodError for detailed error information.
+ */
+export interface ValidationResult {
+    /** Whether the response is valid according to the schema */
+    valid: boolean;
+    /** Zod validation errors (present when valid is false) */
+    errors?: z.ZodError;
+}
+/**
+ * Validate an AgentResponse against a Zod schema
+ *
+ * This is a pure, side-effect-free function that validates AgentResponse
+ * instances using Zod schemas. It returns a structured ValidationResult
+ * with validity flag and optional error details.
+ *
+ * **Validation Flow:**
+ * 1. Create AgentResponseSchema using provided dataSchema
+ * 2. Call schema.safeParse(response) for non-throwing validation
+ * 3. Return { valid: true } if validation succeeds
+ * 4. Return { valid: false, errors: ZodError } if validation fails
+ *
+ * **Pure Function Guarantee:**
+ * - Deterministic: Same input always produces same output
+ * - No side effects: Doesn't modify inputs, emit events, or log
+ * - No external dependencies: Doesn't use Date.now(), Math.random(), etc.
+ *
+ * @template T - The type of response data
+ * @param response - The AgentResponse to validate
+ * @param dataSchema - The Zod schema for the response data (defaults to z.unknown())
+ * @returns Structured validation result with validity flag and optional errors
+ *
+ * @example Valid response
+ * ```ts
+ * const response: AgentResponse<string> = {
+ *   status: 'success',
+ *   data: 'Hello, World!',
+ *   error: null,
+ *   metadata: { agentId: 'agent-123', timestamp: Date.now() }
+ * };
+ *
+ * const result = validateAgentResponse(response);
+ * // Returns: { valid: true }
+ * ```
+ *
+ * @example Invalid response
+ * ```ts
+ * const response = {
+ *   status: 'success',
+ *   data: null,  // Invalid: data should be string, not null
+ *   error: null,
+ *   metadata: { agentId: 'agent-123', timestamp: Date.now() }
+ * };
+ *
+ * const result = validateAgentResponse(response, z.string());
+ * // Returns: { valid: false, errors: ZodError }
+ * ```
+ *
+ * @remarks
+ * **Integration with Agent.validateResponse():**
+ * This utility is called by Agent.validateResponse() which adds:
+ * - console.error logging with agentId
+ * - INTERNAL_ERROR response creation on validation failure
+ *
+ * **Integration with Workflow.validateAgentResponse():**
+ * This utility is called by Workflow.validateAgentResponse() which adds:
+ * - invalidResponse event emission
+ * - WorkflowError creation with INVALID_RESPONSE_FORMAT context
+ *
+ * @see {@link AgentResponseSchema} - Schema factory used for validation
+ * @see {@link ValidationResult} - Return type structure
+ */
+export declare function validateAgentResponse<T>(response: AgentResponse<T>, dataSchema?: z.ZodTypeAny): ValidationResult;
+//# sourceMappingURL=agent-validation.d.ts.map

package/dist/utils/agent-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-validation.d.ts","sourceRoot":"","sources":["../../src/utils/agent-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,KAAK,EAAE,OAAO,CAAC;IACf,0DAA0D;IAC1D,MAAM,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,UAAU,GAAE,CAAC,CAAC,UAAwB,GACrC,gBAAgB,CAclB"}

package/dist/utils/agent-validation.js

@@ -0,0 +1,87 @@
+/**
+ * Agent response validation utilities
+ *
+ * Provides pure, side-effect-free functions for validating AgentResponse
+ * instances using Zod schemas. The utilities enable both Agent and Workflow
+ * classes to perform validation without duplicating code.
+ *
+ * @module agent-validation
+ */
+import { AgentResponseSchema } from '../types/agent.js';
+import { z } from 'zod';
+/**
+ * Validate an AgentResponse against a Zod schema
+ *
+ * This is a pure, side-effect-free function that validates AgentResponse
+ * instances using Zod schemas. It returns a structured ValidationResult
+ * with validity flag and optional error details.
+ *
+ * **Validation Flow:**
+ * 1. Create AgentResponseSchema using provided dataSchema
+ * 2. Call schema.safeParse(response) for non-throwing validation
+ * 3. Return { valid: true } if validation succeeds
+ * 4. Return { valid: false, errors: ZodError } if validation fails
+ *
+ * **Pure Function Guarantee:**
+ * - Deterministic: Same input always produces same output
+ * - No side effects: Doesn't modify inputs, emit events, or log
+ * - No external dependencies: Doesn't use Date.now(), Math.random(), etc.
+ *
+ * @template T - The type of response data
+ * @param response - The AgentResponse to validate
+ * @param dataSchema - The Zod schema for the response data (defaults to z.unknown())
+ * @returns Structured validation result with validity flag and optional errors
+ *
+ * @example Valid response
+ * ```ts
+ * const response: AgentResponse<string> = {
+ *   status: 'success',
+ *   data: 'Hello, World!',
+ *   error: null,
+ *   metadata: { agentId: 'agent-123', timestamp: Date.now() }
+ * };
+ *
+ * const result = validateAgentResponse(response);
+ * // Returns: { valid: true }
+ * ```
+ *
+ * @example Invalid response
+ * ```ts
+ * const response = {
+ *   status: 'success',
+ *   data: null,  // Invalid: data should be string, not null
+ *   error: null,
+ *   metadata: { agentId: 'agent-123', timestamp: Date.now() }
+ * };
+ *
+ * const result = validateAgentResponse(response, z.string());
+ * // Returns: { valid: false, errors: ZodError }
+ * ```
+ *
+ * @remarks
+ * **Integration with Agent.validateResponse():**
+ * This utility is called by Agent.validateResponse() which adds:
+ * - console.error logging with agentId
+ * - INTERNAL_ERROR response creation on validation failure
+ *
+ * **Integration with Workflow.validateAgentResponse():**
+ * This utility is called by Workflow.validateAgentResponse() which adds:
+ * - invalidResponse event emission
+ * - WorkflowError creation with INVALID_RESPONSE_FORMAT context
+ *
+ * @see {@link AgentResponseSchema} - Schema factory used for validation
+ * @see {@link ValidationResult} - Return type structure
+ */
+export function validateAgentResponse(response, dataSchema = z.unknown()) {
+    // Create schema for this response type
+    const schema = AgentResponseSchema(dataSchema);
+    // Validate response against schema (non-throwing)
+    const validation = schema.safeParse(response);
+    if (validation.success) {
+        // Response is valid
+        return { valid: true };
+    }
+    // Validation failed - return structured error
+    return { valid: false, errors: validation.error };
+}
+//# sourceMappingURL=agent-validation.js.map

package/dist/utils/agent-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-validation.js","sourceRoot":"","sources":["../../src/utils/agent-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAA0B,EAC1B,aAA2B,CAAC,CAAC,OAAO,EAAE;IAEtC,uCAAuC;IACvC,MAAM,MAAM,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAE/C,kDAAkD;IAClD,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE9C,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;QACvB,oBAAoB;QACpB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,8CAA8C;IAC9C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC;AACpD,CAAC"}

package/dist/utils/delay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Creates a promise that resolves after a specified delay
+ * @param ms - Delay in milliseconds
+ * @returns Promise that resolves after delay
+ */
+export declare function delay(ms: number): Promise<void>;
+//# sourceMappingURL=delay.d.ts.map

package/dist/utils/delay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../../src/utils/delay.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/utils/delay.js

@@ -0,0 +1,9 @@
+/**
+ * Creates a promise that resolves after a specified delay
+ * @param ms - Delay in milliseconds
+ * @returns Promise that resolves after delay
+ */
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=delay.js.map

package/dist/utils/delay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.js","sourceRoot":"","sources":["../../src/utils/delay.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}