@mondaydotcomorg/atp-runtime 0.17.14

package/src/approval/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Human Approval API Types
+ */
+
+export interface ApprovalRequest {
+	message: string;
+	context?: Record<string, unknown>;
+	timeout?: number;
+	schema?: ApprovalSchema;
+}
+
+export interface ApprovalSchema {
+	type: 'boolean' | 'text' | 'choice' | 'structured';
+	choices?: string[];
+	structuredSchema?: Record<string, unknown>;
+	required?: boolean;
+}
+
+export interface ApprovalResponse<T = unknown> {
+	approved: boolean;
+	response?: T;
+	timestamp: number;
+}

package/src/cache/backends.ts

@@ -0,0 +1,196 @@
+/**
+ */
+import NodeCache from 'node-cache';
+import type { CacheBackend, CacheConfig } from './types';
+
+/**
+ * In-memory cache implementation using node-cache
+ */
+export class MemoryCacheBackend implements CacheBackend {
+	private cache: NodeCache;
+
+	constructor(config?: { maxKeys?: number; defaultTTL?: number; checkPeriod?: number }) {
+		this.cache = new NodeCache({
+			stdTTL: config?.defaultTTL ?? 600,
+			checkperiod: config?.checkPeriod ?? 120,
+			maxKeys: config?.maxKeys ?? 1000,
+			useClones: false,
+		});
+	}
+
+	async get<T>(key: string): Promise<T | null> {
+		const value = this.cache.get<T>(key);
+		return value ?? null;
+	}
+
+	async set(key: string, value: unknown, ttl?: number): Promise<void> {
+		if (ttl) {
+			this.cache.set(key, value, ttl);
+		} else {
+			this.cache.set(key, value);
+		}
+	}
+
+	async delete(key: string): Promise<void> {
+		this.cache.del(key);
+	}
+
+	async has(key: string): Promise<boolean> {
+		return this.cache.has(key);
+	}
+
+	async clear(): Promise<void> {
+		this.cache.flushAll();
+	}
+}
+
+/**
+ * Redis cache implementation (lazy-loaded only if configured)
+ */
+export class RedisCacheBackend implements CacheBackend {
+	private client: any;
+	private connected: boolean = false;
+
+	constructor(config: NonNullable<CacheConfig['redis']>) {
+		import('ioredis')
+			.then((Redis) => {
+				this.client = new Redis.default({
+					host: config.host,
+					port: config.port,
+					password: config.password,
+					db: config.db ?? 0,
+					retryStrategy: (times: number) => {
+						if (times > 3) {
+							return null;
+						}
+						return Math.min(times * 100, 2000);
+					},
+					lazyConnect: true,
+				});
+
+				this.client
+					.connect()
+					.then(() => {
+						this.connected = true;
+					})
+					.catch(() => {
+						this.connected = false;
+					});
+			})
+			.catch(() => {
+				throw new Error('ioredis package not installed. Install it with: yarn add ioredis');
+			});
+	}
+
+	async get<T>(key: string): Promise<T | null> {
+		if (!this.connected) {
+			console.warn('[Redis Cache] Not connected, cannot get key:', key);
+			return null;
+		}
+		try {
+			const value = await this.client.get(key);
+			return value ? JSON.parse(value) : null;
+		} catch (error) {
+			console.error(
+				'[Redis Cache] Failed to get key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+			return null;
+		}
+	}
+
+	async set(key: string, value: unknown, ttl?: number): Promise<void> {
+		if (!this.connected) {
+			console.warn('[Redis Cache] Not connected, cannot set key:', key);
+			return;
+		}
+		try {
+			const serialized = JSON.stringify(value);
+			if (ttl) {
+				await this.client.setex(key, ttl, serialized);
+			} else {
+				await this.client.set(key, serialized);
+			}
+		} catch (error) {
+			console.error(
+				'[Redis Cache] Failed to set key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async delete(key: string): Promise<void> {
+		if (!this.connected) {
+			console.warn('[Redis Cache] Not connected, cannot delete key:', key);
+			return;
+		}
+		try {
+			await this.client.del(key);
+		} catch (error) {
+			console.error(
+				'[Redis Cache] Failed to delete key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+
+	async has(key: string): Promise<boolean> {
+		if (!this.connected) {
+			console.warn('[Redis Cache] Not connected, cannot check key:', key);
+			return false;
+		}
+		try {
+			const exists = await this.client.exists(key);
+			return exists === 1;
+		} catch (error) {
+			console.error(
+				'[Redis Cache] Failed to check key:',
+				key,
+				error instanceof Error ? error.message : error
+			);
+			return false;
+		}
+	}
+
+	async clear(): Promise<void> {
+		if (!this.connected) {
+			console.warn('[Redis Cache] Not connected, cannot clear cache');
+			return;
+		}
+		try {
+			await this.client.flushdb();
+		} catch (error) {
+			console.error(
+				'[Redis Cache] Failed to clear cache:',
+				error instanceof Error ? error.message : error
+			);
+		}
+	}
+}
+
+let cacheBackend: CacheBackend = new MemoryCacheBackend();
+
+/**
+ * Initializes the cache system with configuration
+ */
+export function initializeCache(config: CacheConfig): void {
+	if (config.type === 'redis' && config.redis) {
+		cacheBackend = new RedisCacheBackend(config.redis);
+	} else {
+		cacheBackend = new MemoryCacheBackend({
+			maxKeys: config.maxKeys,
+			defaultTTL: config.defaultTTL,
+			checkPeriod: config.checkPeriod,
+		});
+	}
+}
+
+/**
+ * Get the current cache backend
+ */
+export function getCacheBackend(): CacheBackend {
+	return cacheBackend;
+}

package/src/cache/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Cache API - Clean refactored version with decorators and extracted modules
+ *
+ * Benefits:
+ * - No duplication between implementation and metadata
+ * - Types auto-detected from TypeScript signatures
+ * - Clean separation of concerns (backends, API)
+ */
+import { RuntimeAPI, RuntimeMethod } from '../metadata/decorators.js';
+import { getCacheBackend } from './backends.js';
+
+export type { CacheConfig, CacheBackend } from './types';
+export { MemoryCacheBackend, RedisCacheBackend, initializeCache } from './backends.js';
+
+/**
+ * Cache Runtime API
+ *
+ * Store and retrieve data with optional TTL (Time To Live).
+ * Supports in-memory (node-cache) and Redis backends.
+ */
+@RuntimeAPI('cache', 'Cache API - Store and retrieve data with optional TTL')
+class CacheAPI {
+	/**
+	 * Gets a value from cache
+	 */
+	@RuntimeMethod('Get a value from cache by key', {
+		key: { description: 'Cache key' },
+	})
+	async get<T>(key: string): Promise<T | null> {
+		return getCacheBackend().get<T>(key);
+	}
+
+	/**
+	 * Sets a value in cache with optional TTL in seconds
+	 */
+	@RuntimeMethod('Set a value in cache with optional TTL', {
+		key: { description: 'Cache key' },
+		value: { description: 'Value to cache', type: 'unknown' },
+		ttl: { description: 'Time to live in seconds', optional: true },
+	})
+	async set(key: string, value: unknown, ttl?: number): Promise<void> {
+		return getCacheBackend().set(key, value, ttl);
+	}
+
+	/**
+	 * Deletes a value from cache
+	 */
+	@RuntimeMethod('Delete a value from cache', {
+		key: { description: 'Cache key to delete' },
+	})
+	async delete(key: string): Promise<void> {
+		return getCacheBackend().delete(key);
+	}
+
+	/**
+	 * Checks if a key exists in cache
+	 */
+	@RuntimeMethod('Check if a key exists in cache', {
+		key: { description: 'Cache key to check' },
+	})
+	async has(key: string): Promise<boolean> {
+		return getCacheBackend().has(key);
+	}
+
+	/**
+	 * Clears all cache entries
+	 */
+	@RuntimeMethod('Clear all cache entries')
+	async clear(): Promise<void> {
+		return getCacheBackend().clear();
+	}
+}
+
+export const cache = new CacheAPI();

package/src/cache/types.ts

@@ -0,0 +1,20 @@
+export interface CacheConfig {
+	type: 'memory' | 'redis';
+	redis?: {
+		host: string;
+		port: number;
+		password?: string;
+		db?: number;
+	};
+	maxKeys?: number;
+	defaultTTL?: number;
+	checkPeriod?: number;
+}
+
+export interface CacheBackend {
+	get<T>(key: string): Promise<T | null>;
+	set(key: string, value: unknown, ttl?: number): Promise<void>;
+	delete(key: string): Promise<void>;
+	has(key: string): Promise<boolean>;
+	clear(): Promise<void>;
+}

package/src/embedding/index.ts

@@ -0,0 +1,153 @@
+import { pauseForCallback, CallbackType, EmbeddingOperation } from '../pause/index.js';
+import { RuntimeAPI, RuntimeMethod } from '../metadata/decorators.js';
+import { getVectorStore } from './vector-store.js';
+import { cosineSimilarity, generateEmbeddingId } from './utils.js';
+import { nextSequenceNumber, getCachedResult, shouldPauseForClient } from '../llm/replay.js';
+import type { EmbeddingRecord, SearchOptions, SearchResult } from './types';
+
+export type { EmbeddingOptions, EmbeddingRecord, SearchOptions, SearchResult } from './types';
+export {
+	VectorStore,
+	initializeVectorStore,
+	clearVectorStore,
+	getVectorStore,
+	setVectorStoreExecutionId,
+	clearVectorStoreExecutionId,
+} from './vector-store.js';
+export { cosineSimilarity, generateEmbeddingId } from './utils.js';
+
+/**
+ * Embedding Runtime API
+ *
+ * Decorators automatically:
+ * - Extract parameter names and types
+ * - Generate metadata for type definitions
+ * - Maintain single source of truth
+ */
+@RuntimeAPI('embedding', 'Embedding API - Client-side embedding with server-side vector storage')
+class EmbeddingAPI {
+	/**
+	 * Request client to generate embedding and store it
+	 * For batch inputs, returns array of IDs for stored embeddings
+	 */
+	@RuntimeMethod('Request client to generate and store embeddings', {
+		input: {
+			description: 'Text(s) to embed',
+			type: 'string | string[]',
+		},
+		metadata: {
+			description: 'Optional metadata to store with embeddings',
+			optional: true,
+			type: 'Record<string, unknown>',
+		},
+	})
+	async embed(
+		input: string | string[],
+		metadata?: Record<string, unknown>
+	): Promise<string | string[]> {
+		const isBatch = Array.isArray(input);
+		const texts = isBatch ? input : [input];
+		const ids = texts.map((_, i) => generateEmbeddingId(i));
+
+		const currentSequence = nextSequenceNumber();
+
+		const cachedResult = getCachedResult(currentSequence);
+		if (cachedResult !== undefined && cachedResult !== null) {
+			const vectorStore = getVectorStore();
+			const embedding = cachedResult as number[];
+			for (let i = 0; i < texts.length; i++) {
+				vectorStore.store(ids[i]!, texts[i]!, embedding, metadata);
+			}
+			return isBatch ? ids : ids[0]!;
+		}
+
+		if (shouldPauseForClient()) {
+			pauseForCallback(CallbackType.EMBEDDING, EmbeddingOperation.EMBED, {
+				text: isBatch ? texts.join('\n') : texts[0]!,
+				input,
+				ids,
+				metadata,
+				sequenceNumber: currentSequence,
+			});
+		}
+
+		throw new Error('Embedding service not provided by client');
+	}
+
+	/**
+	 * Search stored embeddings by similarity
+	 * Query must be embedded first via embed()
+	 */
+	@RuntimeMethod('Search stored embeddings by similarity', {
+		query: {
+			description: 'Search query text (will be embedded by client)',
+		},
+		options: {
+			description: 'Search options (topK, minSimilarity, filter)',
+			optional: true,
+			type: 'SearchOptions',
+		},
+	})
+	async search(query: string, options?: Omit<SearchOptions, 'query'>): Promise<SearchResult[]> {
+		const currentSequence = nextSequenceNumber();
+		const vectorStore = getVectorStore();
+
+		const cachedQueryEmbedding = getCachedResult(currentSequence);
+		if (cachedQueryEmbedding !== undefined && cachedQueryEmbedding !== null) {
+			vectorStore.setQueryEmbedding(cachedQueryEmbedding as number[]);
+
+			const searchOptions: any = { ...options, query };
+			if ((options as any)?.collection) {
+				searchOptions.filter = {
+					...searchOptions.filter,
+					collection: (options as any).collection,
+				};
+			}
+
+			return vectorStore.search(searchOptions);
+		}
+
+		if (shouldPauseForClient()) {
+			pauseForCallback(CallbackType.EMBEDDING, EmbeddingOperation.SEARCH, {
+				query,
+				options: {
+					...options,
+					query,
+				},
+				sequenceNumber: currentSequence,
+			});
+		}
+
+		throw new Error('Embedding service not provided by client');
+	}
+
+	/**
+	 * Calculate cosine similarity between two embedding vectors
+	 * This is a utility function that doesn't require client interaction
+	 */
+	@RuntimeMethod('Calculate cosine similarity between two embedding vectors', {
+		embedding1: { description: 'First embedding vector', type: 'number[]' },
+		embedding2: { description: 'Second embedding vector', type: 'number[]' },
+	})
+	similarity(embedding1: number[], embedding2: number[]): number {
+		return cosineSimilarity(embedding1, embedding2);
+	}
+
+	/**
+	 * Get all stored embeddings (useful for debugging)
+	 */
+	@RuntimeMethod('Get all stored embeddings')
+	getAll(): EmbeddingRecord[] {
+		return getVectorStore().getAll();
+	}
+
+	/**
+	 * Get count of stored embeddings
+	 */
+	@RuntimeMethod('Get count of stored embeddings')
+	count(): number {
+		return getVectorStore().count();
+	}
+}
+
+export const embedding = new EmbeddingAPI();

package/src/embedding/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Embedding API Types
+ */
+
+export interface EmbeddingOptions {
+	input: string | string[];
+	model?: string;
+	dimensions?: number;
+	context?: Record<string, unknown>;
+}
+
+export interface EmbeddingRecord {
+	id: string;
+	text: string;
+	embedding: number[];
+	metadata?: Record<string, unknown>;
+}
+
+export interface SearchOptions {
+	query: string;
+	topK?: number;
+	minSimilarity?: number;
+	filter?: Record<string, unknown>;
+}
+
+export interface SearchResult {
+	id: string;
+	text: string;
+	similarity: number;
+	metadata?: Record<string, unknown>;
+}

package/src/embedding/utils.ts

@@ -0,0 +1,34 @@
+/**
+
+/**
+ * Calculate cosine similarity between two vectors
+ */
+export function cosineSimilarity(vec1: number[], vec2: number[]): number {
+	if (vec1.length !== vec2.length) {
+		throw new Error(`Vectors must have the same length (${vec1.length} vs ${vec2.length})`);
+	}
+
+	let dotProduct = 0;
+	let norm1 = 0;
+	let norm2 = 0;
+
+	for (let i = 0; i < vec1.length; i++) {
+		dotProduct += vec1[i]! * vec2[i]!;
+		norm1 += vec1[i]! * vec1[i]!;
+		norm2 += vec2[i]! * vec2[i]!;
+	}
+
+	const denominator = Math.sqrt(norm1) * Math.sqrt(norm2);
+	if (denominator === 0) {
+		return 0;
+	}
+
+	return dotProduct / denominator;
+}
+
+/**
+ * Generate a unique ID for an embedding
+ */
+export function generateEmbeddingId(index: number = 0): string {
+	return `emb_${Date.now()}_${index}_${Math.random().toString(36).slice(2)}`;
+}

package/src/embedding/vector-store.ts

@@ -0,0 +1,164 @@
+/**
+ */
+import type { EmbeddingRecord, SearchOptions, SearchResult } from './types.js';
+import { cosineSimilarity } from './utils.js';
+
+/**
+ * In-memory vector store for the current execution
+ * Cleared after each execution completes
+ */
+export class VectorStore {
+	private records: Map<string, EmbeddingRecord> = new Map();
+	private queryEmbedding: number[] | null = null;
+
+	/**
+	 * Store embeddings from client response
+	 */
+	store(id: string, text: string, embedding: number[], metadata?: Record<string, unknown>): void {
+		this.records.set(id, { id, text, embedding, metadata });
+	}
+
+	/**
+	 * Store multiple embeddings
+	 */
+	storeBatch(records: EmbeddingRecord[]): void {
+		for (const record of records) {
+			this.records.set(record.id, record);
+		}
+	}
+
+	/**
+	 * Set the query embedding for search
+	 */
+	setQueryEmbedding(embedding: number[]): void {
+		this.queryEmbedding = embedding;
+	}
+
+	/**
+	 * Search stored embeddings by similarity to query
+	 */
+	search(options: SearchOptions): SearchResult[] {
+		if (!this.queryEmbedding) {
+			throw new Error('No query embedding set. Call embed() with query first.');
+		}
+
+		const topK = options.topK ?? 5;
+		const minSimilarity = options.minSimilarity ?? 0;
+
+		const results: SearchResult[] = [];
+		for (const record of this.records.values()) {
+			if (options.filter && record.metadata) {
+				let matches = true;
+				for (const [key, value] of Object.entries(options.filter)) {
+					if (record.metadata[key] !== value) {
+						matches = false;
+						break;
+					}
+				}
+				if (!matches) continue;
+			}
+
+			const similarity = cosineSimilarity(this.queryEmbedding, record.embedding);
+			if (similarity >= minSimilarity) {
+				results.push({
+					id: record.id,
+					text: record.text,
+					similarity,
+					metadata: record.metadata,
+				});
+			}
+		}
+
+		results.sort((a, b) => b.similarity - a.similarity);
+		return results.slice(0, topK);
+	}
+
+	/**
+	 * Get all stored embeddings
+	 */
+	getAll(): EmbeddingRecord[] {
+		return Array.from(this.records.values());
+	}
+
+	/**
+	 * Get embedding by ID
+	 */
+	get(id: string): EmbeddingRecord | undefined {
+		return this.records.get(id);
+	}
+
+	/**
+	 * Clear all stored embeddings
+	 */
+	clear(): void {
+		this.records.clear();
+		this.queryEmbedding = null;
+	}
+
+	/**
+	 * Get count of stored embeddings
+	 */
+	count(): number {
+		return this.records.size;
+	}
+}
+
+const vectorStores = new Map<string, VectorStore>();
+
+let currentVectorStoreExecutionId: string | null = null;
+
+/**
+ * Set the current execution ID for vector store operations
+ */
+export function setVectorStoreExecutionId(executionId: string): void {
+	currentVectorStoreExecutionId = executionId;
+}
+
+/**
+ * Clear the current execution ID
+ */
+export function clearVectorStoreExecutionId(): void {
+	currentVectorStoreExecutionId = null;
+}
+
+/**
+ * Initialize a new vector store for a new execution
+ */
+export function initializeVectorStore(executionId?: string): void {
+	const id = executionId || currentVectorStoreExecutionId;
+	if (!id) {
+		throw new Error('No execution ID set for vector store');
+	}
+	vectorStores.set(id, new VectorStore());
+}
+
+/**
+ * Clear the vector store after execution completes
+ */
+export function clearVectorStore(executionId?: string): void {
+	const id = executionId || currentVectorStoreExecutionId;
+	if (!id) return;
+
+	const store = vectorStores.get(id);
+	if (store) {
+		store.clear();
+		vectorStores.delete(id);
+	}
+}
+
+/**
+ * Get the current vector store (for executor to manage)
+ */
+export function getVectorStore(executionId?: string): VectorStore {
+	const id = executionId || currentVectorStoreExecutionId;
+	if (!id) {
+		throw new Error('No execution ID set for vector store');
+	}
+
+	let store = vectorStores.get(id);
+	if (!store) {
+		store = new VectorStore();
+		vectorStores.set(id, store);
+	}
+	return store;
+}