@mastra/cloudflare 0.0.0-a2a-20250421213654

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2025 Mastra AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @mastra/cloudflare
+
+Cloudflare KV store for Mastra, providing scalable and serverless storage for threads, messages, workflow snapshots, and evaluations. Supports both Cloudflare Workers KV Bindings and the REST API for flexible deployment in serverless and Node.js environments.
+
+## Installation
+
+```bash
+npm install @mastra/cloudflare
+```
+
+## Prerequisites
+
+- Cloudflare account with KV namespaces set up
+- Node.js 16 or higher
+- (Optional) Cloudflare Worker for Workers API mode
+
+## Usage
+
+```typescript
+import { CloudflareStore } from '@mastra/cloudflare';
+
+// Using Workers Binding API
+const store = new CloudflareStore({
+  bindings: {
+    threads: THREADS_KV_NAMESPACE,
+    messages: MESSAGES_KV_NAMESPACE,
+    workflow_snapshot: WORKFLOW_KV_NAMESPACE,
+    evals: EVALS_KV_NAMESPACE,
+    traces: TRACES_KV_NAMESPACE,
+  },
+  keyPrefix: 'myapp_', // Optional
+});
+
+// Or using REST API
+const store = new CloudflareStore({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
+  apiToken: process.env.CLOUDFLARE_API_TOKEN!,
+  namespacePrefix: 'myapp_', // Optional
+});
+
+// Save a thread
+await store.saveThread({
+  id: 'thread-123',
+  resourceId: 'resource-456',
+  title: 'My Thread',
+  metadata: { key: 'value' },
+  createdAt: new Date(),
+  updatedAt: new Date(),
+});
+
+// Add messages
+await store.saveMessages({
+  messages: [
+    {
+      id: 'msg-1',
+      threadId: 'thread-123',
+      content: 'Hello Cloudflare!',
+      role: 'user',
+      createdAt: new Date(),
+    },
+  ],
+});
+
+// Query messages
+const messages = await store.getMessages({ threadId: 'thread-123' });
+```
+
+## Configuration
+
+- **Workers API**: Use the `bindings` option to pass KV namespaces directly (for Cloudflare Workers).
+- **REST API**: Use `accountId`, `apiToken`, and (optionally) `namespacePrefix` for server-side usage.
+- `keyPrefix`/`namespacePrefix`: Useful for isolating environments (e.g., dev/test/prod).
+
+## Features
+
+### Storage Features
+
+- Thread and message storage with JSON support
+- Rich metadata support (JSON-encoded)
+- Timestamp tracking for all records
+- Workflow snapshot persistence
+- Trace and evaluation storage
+- Sorted message order using simulated sorted sets
+- Supports both Cloudflare Workers KV Bindings and REST API
+- Automatic JSON serialization/deserialization for metadata and custom fields
+- Error handling and logging for all operations
+
+### Consistency & Performance
+
+- Eventually consistent (see Limitations)
+- Low-latency access via Workers Binding API
+- Scalable and serverless
+
+## Supported Methods
+
+### Thread Operations
+
+- `saveThread(thread)`: Create or update a thread
+- `getThreadById({ threadId })`: Get a thread by ID
+- `getThreadsByResourceId({ resourceId })`: Fetch all threads associated with a resource.
+- `updateThread({ id, title, metadata })`: Update thread title and metadata
+- `deleteThread({ threadId })`: Delete a thread and its messages
+
+### Message Operations
+
+- `saveMessages({ messages })`: Save multiple messages
+- `getMessages({ threadId, selectBy? })`: Get messages for a thread with optional filtering (last N, includes, etc)
+
+### Workflow Operations
+
+- `persistWorkflowSnapshot({ workflowName, runId, snapshot })`: Save workflow state for a given workflow/run.
+- `loadWorkflowSnapshot({ workflowName, runId })`: Load ed workflow state.
+
+### Trace Operations
+
+- `getTraces({ name?, scope?, page, perPage, attributes? })`: Query trace records with optional filters and pagination.
+
+### Utility
+
+- `clearTable({ tableName })`: Remove all records from a logical table
+- `batchInsert({ tableName, records })`: Batch insert multiple records.
+- `insert({ tableName, record })`: Insert a single record into a table.
+
+## Data Types
+
+- `text`: String
+- `timestamp`: ISO8601 string (converted to/from Date)
+- `uuid`: String
+- `jsonb`: JSON-encoded object
+
+All records are stored as JSON in KV, with automatic serialization/deserialization for metadata, arrays, and custom fields.
+
+## Configuration Reference
+
+- **Workers Binding API**: Use the `bindings` option to pass KV namespaces directly (for Cloudflare Workers).
+- **REST API**: Use `accountId`, `apiToken`, and (optionally) `namespacePrefix` for server-side usage.
+- `keyPrefix`/`namespacePrefix`: Useful for isolating environments (e.g., dev/test/prod).
+
+Example:
+
+```typescript
+const store = new CloudflareStore({
+  bindings: { ... }, // for Workers
+  keyPrefix: 'dev_',
+});
+// or
+const store = new CloudflareStore({
+  accountId: '...',
+  apiToken: '...',
+  namespacePrefix: 'prod_',
+});
+```
+
+## Table/Namespace Mapping
+
+Each logical Mastra table (threads, messages, workflow_snapshot, evals, traces) maps to a separate KV namespace. Keys are structured as `${prefix}${tableName}:${primaryKey}` or `${prefix}${tableName}:${threadId}:${messageId}` for messages. The prefix is set by `keyPrefix`/`namespacePrefix`.
+
+## Limitations
+
+- **Eventual Consistency:** Cloudflare KV is eventually consistent; concurrent operations may not be immediately visible across all reads.
+- **No Transactions:** Atomic multi-key operations are not supported.
+- **Rate Limits:** Large objects or high-frequency updates may be subject to Cloudflare KV rate limits.
+- **Query Limitations:** No native querying; all filtering is done in-memory after fetching keys/records.
+- **Best for:** Use for serverless, low-latency, and moderate-volume workloads. For relational or strongly consistent needs, consider D1 or a SQL backend.
+
+## Cloudflare-Specific Notes
+
+- **Workers Binding API** is recommended for production Workers deployments (low-latency, no API token required at runtime).
+- **REST API** is ideal for server-side Node.js or test environments.
+- Ensure your KV namespaces are provisioned and accessible by your Worker or API token.
+- Namespaces and keys are automatically created as needed.
+
+## Cleanup/Disconnect
+
+No explicit cleanup or disconnect is required; Cloudflare KV is fully managed.

package/dist/_tsup-dts-rollup.d.cts

@@ -0,0 +1,257 @@
+import type { EvalRow } from '@mastra/core/storage';
+import type { KVNamespace as KVNamespace_2 } from '@cloudflare/workers-types';
+import { KVNamespaceListKey as KVNamespaceListKey_2 } from '@cloudflare/workers-types';
+import { MastraStorage } from '@mastra/core/storage';
+import type { MessageType } from '@mastra/core/memory';
+import type { MessageType as MessageType_2 } from '@mastra/core';
+import type { StorageColumn } from '@mastra/core/storage';
+import type { StorageGetMessagesArg } from '@mastra/core/storage';
+import type { StorageThreadType } from '@mastra/core/memory';
+import type { TABLE_EVALS } from '@mastra/core/storage';
+import type { TABLE_MESSAGES } from '@mastra/core/storage';
+import type { TABLE_NAMES } from '@mastra/core/storage';
+import type { TABLE_THREADS } from '@mastra/core/storage';
+import type { TABLE_TRACES } from '@mastra/core/storage';
+import type { TABLE_WORKFLOW_SNAPSHOT } from '@mastra/core/storage';
+import type { WorkflowRuns } from '@mastra/core/storage';
+import type { WorkflowRunState } from '@mastra/core/workflows';
+import type { WorkflowRunState as WorkflowRunState_2 } from '@mastra/core';
+
+/**
+ * Configuration for Cloudflare KV using REST API
+ */
+export declare interface CloudflareRestConfig {
+    /** Cloudflare account ID */
+    accountId: string;
+    /** Cloudflare API token with KV access */
+    apiToken: string;
+    /**
+     * Prefix for KV namespace names.
+     * Recommended for production use to ensure data isolation between different instances.
+     * If not provided, no prefix will be used
+     */
+    namespacePrefix?: string;
+}
+
+declare class CloudflareStore extends MastraStorage {
+    private client?;
+    private accountId?;
+    private namespacePrefix;
+    private bindings?;
+    private validateWorkersConfig;
+    private validateRestConfig;
+    constructor(config: CloudflareStoreConfig);
+    private getBinding;
+    private listNamespaces;
+    private getNamespaceValue;
+    private putNamespaceValue;
+    private deleteNamespaceValue;
+    listNamespaceKeys(tableName: TABLE_NAMES, options?: {
+        limit?: number;
+        prefix?: string;
+    }): Promise<KVNamespaceListKey_2<unknown, string>[]>;
+    private createNamespaceById;
+    private getNamespaceIdByName;
+    private createNamespace;
+    private getOrCreateNamespaceId;
+    private getNamespaceId;
+    /**
+     * Helper to safely serialize data for KV storage
+     */
+    private safeSerialize;
+    /**
+     * Helper to safely parse data from KV storage
+     */
+    private safeParse;
+    private putKV;
+    private getKV;
+    private deleteKV;
+    private listKV;
+    private getSortedMessages;
+    private updateSorting;
+    private getIncludedMessagesWithContext;
+    private getRecentMessages;
+    private fetchAndParseMessages;
+    /**
+     * Queue for serializing sorted order updates.
+     * Updates the sorted order for a given key. This operation is eventually consistent.
+     */
+    private updateQueue;
+    /**
+     * Updates the sorted order for a given key. This operation is eventually consistent.
+     * Note: Operations on the same orderKey are serialized using a queue to prevent
+     * concurrent updates from conflicting with each other.
+     */
+    private updateSortedMessages;
+    private getRank;
+    private getRange;
+    private getLastN;
+    private getFullOrder;
+    private getKey;
+    private getSchemaKey;
+    private getTableSchema;
+    private validateColumnValue;
+    private validateAgainstSchema;
+    private validateRecord;
+    private ensureDate;
+    private serializeDate;
+    private ensureMetadata;
+    createTable({ tableName, schema, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+    }): Promise<void>;
+    clearTable({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+    insert<T extends TABLE_NAMES>({ tableName, record }: {
+        tableName: T;
+        record: RecordTypes[T];
+    }): Promise<void>;
+    load<R>({ tableName, keys }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, string>;
+    }): Promise<R | null>;
+    getThreadById({ threadId }: {
+        threadId: string;
+    }): Promise<StorageThreadType | null>;
+    getThreadsByResourceId({ resourceId }: {
+        resourceId: string;
+    }): Promise<StorageThreadType[]>;
+    saveThread({ thread }: {
+        thread: StorageThreadType;
+    }): Promise<StorageThreadType>;
+    updateThread({ id, title, metadata, }: {
+        id: string;
+        title: string;
+        metadata: Record<string, unknown>;
+    }): Promise<StorageThreadType>;
+    deleteThread({ threadId }: {
+        threadId: string;
+    }): Promise<void>;
+    private getMessageKey;
+    private getThreadMessagesKey;
+    saveMessages({ messages }: {
+        messages: MessageType[];
+    }): Promise<MessageType[]>;
+    getMessages<T extends MessageType = MessageType>({ threadId, selectBy }: StorageGetMessagesArg): Promise<T[]>;
+    private validateWorkflowParams;
+    private validateWorkflowState;
+    private normalizeSteps;
+    private normalizeWorkflowState;
+    persistWorkflowSnapshot(params: {
+        namespace: string;
+        workflowName: string;
+        runId: string;
+        snapshot: WorkflowRunState;
+    }): Promise<void>;
+    loadWorkflowSnapshot(params: {
+        namespace: string;
+        workflowName: string;
+        runId: string;
+    }): Promise<WorkflowRunState | null>;
+    batchInsert<T extends TABLE_NAMES>(input: {
+        tableName: T;
+        records: Partial<RecordTypes[T]>[];
+    }): Promise<void>;
+    getTraces({ name, scope, page, perPage, attributes, }: {
+        name?: string;
+        scope?: string;
+        page: number;
+        perPage: number;
+        attributes?: Record<string, string>;
+    }): Promise<any[]>;
+    private parseJSON;
+    getEvalsByAgentName(_agentName: string, _type?: 'test' | 'live'): Promise<EvalRow[]>;
+    getWorkflowRuns(_args?: {
+        namespace?: string;
+        workflowName?: string;
+        fromDate?: Date;
+        toDate?: Date;
+        limit?: number;
+        offset?: number;
+    }): Promise<WorkflowRuns>;
+    close(): Promise<void>;
+}
+export { CloudflareStore }
+export { CloudflareStore as CloudflareStore_alias_1 }
+
+/**
+ * Combined configuration type supporting both REST API and Workers Binding API
+ */
+export declare type CloudflareStoreConfig = CloudflareRestConfig | CloudflareWorkersConfig;
+
+/**
+ * Configuration for Cloudflare KV using Workers Binding API
+ */
+export declare interface CloudflareWorkersConfig {
+    /** KV namespace bindings from Workers environment */
+    bindings: {
+        [key in TABLE_NAMES]: KVNamespace_2;
+    };
+    /** Optional prefix for keys within namespaces */
+    keyPrefix?: string;
+}
+
+export declare const createSampleMessage: (threadId: string) => MessageType_2;
+
+export declare const createSampleThread: () => {
+    id: string;
+    resourceId: string;
+    title: string;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata: {
+        key: string;
+    };
+};
+
+export declare const createSampleTrace: (name: string, scope?: string, attributes?: Record<string, string>) => {
+    id: string;
+    parentSpanId: string;
+    traceId: string;
+    name: string;
+    scope: string | undefined;
+    kind: string;
+    status: string;
+    events: string;
+    links: string;
+    attributes: string | undefined;
+    startTime: string;
+    endTime: string;
+    other: string;
+    createdAt: string;
+};
+
+export declare const createSampleWorkflowSnapshot: (threadId: string) => WorkflowRunState_2;
+
+/**
+ * Helper to determine if a config is using Workers bindings
+ */
+export declare function isWorkersConfig(config: CloudflareStoreConfig): config is CloudflareWorkersConfig;
+
+/**
+ * Interface for KV operations with type support
+ */
+export declare interface KVOperation {
+    /** Table/namespace to operate on */
+    tableName: TABLE_NAMES;
+    /** Key to read/write */
+    key: string;
+    /** Value to write (for put operations) */
+    value?: any;
+    /** Optional metadata to associate with the value */
+    metadata?: any;
+}
+
+export declare type RecordTypes = {
+    [TABLE_THREADS]: StorageThreadType;
+    [TABLE_MESSAGES]: MessageType;
+    [TABLE_WORKFLOW_SNAPSHOT]: WorkflowRunState;
+    [TABLE_EVALS]: EvalRow;
+    [TABLE_TRACES]: any;
+};
+
+export declare const retryUntil: <T>(fn: () => Promise<T>, condition: (result: T) => boolean, timeout?: number, // REST API needs longer timeout due to higher latency
+interval?: number) => Promise<T>;
+
+export { }

package/dist/_tsup-dts-rollup.d.ts

@@ -0,0 +1,257 @@
+import type { EvalRow } from '@mastra/core/storage';
+import type { KVNamespace as KVNamespace_2 } from '@cloudflare/workers-types';
+import { KVNamespaceListKey as KVNamespaceListKey_2 } from '@cloudflare/workers-types';
+import { MastraStorage } from '@mastra/core/storage';
+import type { MessageType } from '@mastra/core/memory';
+import type { MessageType as MessageType_2 } from '@mastra/core';
+import type { StorageColumn } from '@mastra/core/storage';
+import type { StorageGetMessagesArg } from '@mastra/core/storage';
+import type { StorageThreadType } from '@mastra/core/memory';
+import type { TABLE_EVALS } from '@mastra/core/storage';
+import type { TABLE_MESSAGES } from '@mastra/core/storage';
+import type { TABLE_NAMES } from '@mastra/core/storage';
+import type { TABLE_THREADS } from '@mastra/core/storage';
+import type { TABLE_TRACES } from '@mastra/core/storage';
+import type { TABLE_WORKFLOW_SNAPSHOT } from '@mastra/core/storage';
+import type { WorkflowRuns } from '@mastra/core/storage';
+import type { WorkflowRunState } from '@mastra/core/workflows';
+import type { WorkflowRunState as WorkflowRunState_2 } from '@mastra/core';
+
+/**
+ * Configuration for Cloudflare KV using REST API
+ */
+export declare interface CloudflareRestConfig {
+    /** Cloudflare account ID */
+    accountId: string;
+    /** Cloudflare API token with KV access */
+    apiToken: string;
+    /**
+     * Prefix for KV namespace names.
+     * Recommended for production use to ensure data isolation between different instances.
+     * If not provided, no prefix will be used
+     */
+    namespacePrefix?: string;
+}
+
+declare class CloudflareStore extends MastraStorage {
+    private client?;
+    private accountId?;
+    private namespacePrefix;
+    private bindings?;
+    private validateWorkersConfig;
+    private validateRestConfig;
+    constructor(config: CloudflareStoreConfig);
+    private getBinding;
+    private listNamespaces;
+    private getNamespaceValue;
+    private putNamespaceValue;
+    private deleteNamespaceValue;
+    listNamespaceKeys(tableName: TABLE_NAMES, options?: {
+        limit?: number;
+        prefix?: string;
+    }): Promise<KVNamespaceListKey_2<unknown, string>[]>;
+    private createNamespaceById;
+    private getNamespaceIdByName;
+    private createNamespace;
+    private getOrCreateNamespaceId;
+    private getNamespaceId;
+    /**
+     * Helper to safely serialize data for KV storage
+     */
+    private safeSerialize;
+    /**
+     * Helper to safely parse data from KV storage
+     */
+    private safeParse;
+    private putKV;
+    private getKV;
+    private deleteKV;
+    private listKV;
+    private getSortedMessages;
+    private updateSorting;
+    private getIncludedMessagesWithContext;
+    private getRecentMessages;
+    private fetchAndParseMessages;
+    /**
+     * Queue for serializing sorted order updates.
+     * Updates the sorted order for a given key. This operation is eventually consistent.
+     */
+    private updateQueue;
+    /**
+     * Updates the sorted order for a given key. This operation is eventually consistent.
+     * Note: Operations on the same orderKey are serialized using a queue to prevent
+     * concurrent updates from conflicting with each other.
+     */
+    private updateSortedMessages;
+    private getRank;
+    private getRange;
+    private getLastN;
+    private getFullOrder;
+    private getKey;
+    private getSchemaKey;
+    private getTableSchema;
+    private validateColumnValue;
+    private validateAgainstSchema;
+    private validateRecord;
+    private ensureDate;
+    private serializeDate;
+    private ensureMetadata;
+    createTable({ tableName, schema, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+    }): Promise<void>;
+    clearTable({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+    insert<T extends TABLE_NAMES>({ tableName, record }: {
+        tableName: T;
+        record: RecordTypes[T];
+    }): Promise<void>;
+    load<R>({ tableName, keys }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, string>;
+    }): Promise<R | null>;
+    getThreadById({ threadId }: {
+        threadId: string;
+    }): Promise<StorageThreadType | null>;
+    getThreadsByResourceId({ resourceId }: {
+        resourceId: string;
+    }): Promise<StorageThreadType[]>;
+    saveThread({ thread }: {
+        thread: StorageThreadType;
+    }): Promise<StorageThreadType>;
+    updateThread({ id, title, metadata, }: {
+        id: string;
+        title: string;
+        metadata: Record<string, unknown>;
+    }): Promise<StorageThreadType>;
+    deleteThread({ threadId }: {
+        threadId: string;
+    }): Promise<void>;
+    private getMessageKey;
+    private getThreadMessagesKey;
+    saveMessages({ messages }: {
+        messages: MessageType[];
+    }): Promise<MessageType[]>;
+    getMessages<T extends MessageType = MessageType>({ threadId, selectBy }: StorageGetMessagesArg): Promise<T[]>;
+    private validateWorkflowParams;
+    private validateWorkflowState;
+    private normalizeSteps;
+    private normalizeWorkflowState;
+    persistWorkflowSnapshot(params: {
+        namespace: string;
+        workflowName: string;
+        runId: string;
+        snapshot: WorkflowRunState;
+    }): Promise<void>;
+    loadWorkflowSnapshot(params: {
+        namespace: string;
+        workflowName: string;
+        runId: string;
+    }): Promise<WorkflowRunState | null>;
+    batchInsert<T extends TABLE_NAMES>(input: {
+        tableName: T;
+        records: Partial<RecordTypes[T]>[];
+    }): Promise<void>;
+    getTraces({ name, scope, page, perPage, attributes, }: {
+        name?: string;
+        scope?: string;
+        page: number;
+        perPage: number;
+        attributes?: Record<string, string>;
+    }): Promise<any[]>;
+    private parseJSON;
+    getEvalsByAgentName(_agentName: string, _type?: 'test' | 'live'): Promise<EvalRow[]>;
+    getWorkflowRuns(_args?: {
+        namespace?: string;
+        workflowName?: string;
+        fromDate?: Date;
+        toDate?: Date;
+        limit?: number;
+        offset?: number;
+    }): Promise<WorkflowRuns>;
+    close(): Promise<void>;
+}
+export { CloudflareStore }
+export { CloudflareStore as CloudflareStore_alias_1 }
+
+/**
+ * Combined configuration type supporting both REST API and Workers Binding API
+ */
+export declare type CloudflareStoreConfig = CloudflareRestConfig | CloudflareWorkersConfig;
+
+/**
+ * Configuration for Cloudflare KV using Workers Binding API
+ */
+export declare interface CloudflareWorkersConfig {
+    /** KV namespace bindings from Workers environment */
+    bindings: {
+        [key in TABLE_NAMES]: KVNamespace_2;
+    };
+    /** Optional prefix for keys within namespaces */
+    keyPrefix?: string;
+}
+
+export declare const createSampleMessage: (threadId: string) => MessageType_2;
+
+export declare const createSampleThread: () => {
+    id: string;
+    resourceId: string;
+    title: string;
+    createdAt: Date;
+    updatedAt: Date;
+    metadata: {
+        key: string;
+    };
+};
+
+export declare const createSampleTrace: (name: string, scope?: string, attributes?: Record<string, string>) => {
+    id: string;
+    parentSpanId: string;
+    traceId: string;
+    name: string;
+    scope: string | undefined;
+    kind: string;
+    status: string;
+    events: string;
+    links: string;
+    attributes: string | undefined;
+    startTime: string;
+    endTime: string;
+    other: string;
+    createdAt: string;
+};
+
+export declare const createSampleWorkflowSnapshot: (threadId: string) => WorkflowRunState_2;
+
+/**
+ * Helper to determine if a config is using Workers bindings
+ */
+export declare function isWorkersConfig(config: CloudflareStoreConfig): config is CloudflareWorkersConfig;
+
+/**
+ * Interface for KV operations with type support
+ */
+export declare interface KVOperation {
+    /** Table/namespace to operate on */
+    tableName: TABLE_NAMES;
+    /** Key to read/write */
+    key: string;
+    /** Value to write (for put operations) */
+    value?: any;
+    /** Optional metadata to associate with the value */
+    metadata?: any;
+}
+
+export declare type RecordTypes = {
+    [TABLE_THREADS]: StorageThreadType;
+    [TABLE_MESSAGES]: MessageType;
+    [TABLE_WORKFLOW_SNAPSHOT]: WorkflowRunState;
+    [TABLE_EVALS]: EvalRow;
+    [TABLE_TRACES]: any;
+};
+
+export declare const retryUntil: <T>(fn: () => Promise<T>, condition: (result: T) => boolean, timeout?: number, // REST API needs longer timeout due to higher latency
+interval?: number) => Promise<T>;
+
+export { }