@mondaydotcomorg/atp-client 0.17.14

package/src/core/execution-operations.ts

@@ -0,0 +1,301 @@
+import type { ExecutionResult, ExecutionConfig } from '@mondaydotcomorg/atp-protocol';
+import { ExecutionStatus } from '@mondaydotcomorg/atp-protocol';
+import type { ClientSession } from './session.js';
+import type { ServiceProviders } from './service-providers';
+import { ClientCallbackError } from '../errors.js';
+import { ProvenanceTokenRegistry } from './provenance-registry.js';
+
+export class ExecutionOperations {
+	private session: ClientSession;
+	private serviceProviders: ServiceProviders;
+	private tokenRegistry: ProvenanceTokenRegistry;
+
+	constructor(session: ClientSession, serviceProviders: ServiceProviders) {
+		this.session = session;
+		this.serviceProviders = serviceProviders;
+		this.tokenRegistry = new ProvenanceTokenRegistry();
+	}
+
+	/**
+	 * Executes code on the server with real-time progress updates via SSE.
+	 */
+	async executeStream(
+		code: string,
+		config?: Partial<ExecutionConfig>,
+		onProgress?: (message: string, fraction: number) => void
+	): Promise<ExecutionResult> {
+		await this.session.ensureInitialized();
+
+		const url = `${this.session.getBaseUrl()}/api/execute/stream`;
+		const body = JSON.stringify({ code, config });
+		const headers = await this.session.prepareHeaders('POST', url, body);
+
+		return new Promise((resolve, reject) => {
+			const fetchImpl = typeof fetch !== 'undefined' ? fetch : require('undici').fetch;
+
+			fetchImpl(url, {
+				method: 'POST',
+				headers,
+				body,
+			})
+				.then(async (response: Response) => {
+					if (!response.ok) {
+						throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+					}
+
+					const reader = response.body?.getReader();
+					if (!reader) {
+						throw new Error('Response body is not readable');
+					}
+
+					const decoder = new TextDecoder();
+					let buffer = '';
+					let result: ExecutionResult | null = null;
+
+					while (true) {
+						const { done, value } = await reader.read();
+
+						if (done) break;
+
+						buffer += decoder.decode(value, { stream: true });
+						const lines = buffer.split('\n');
+						buffer = lines.pop() || '';
+
+						for (let i = 0; i < lines.length; i++) {
+							const line = lines[i];
+
+							if (line && line.startsWith('event:')) {
+								const event = line.substring(6).trim();
+
+								for (let j = i + 1; j < lines.length; j++) {
+									const dataLine = lines[j];
+									if (dataLine && dataLine.startsWith('data:')) {
+										const dataStr = dataLine.substring(5).trim();
+										if (dataStr) {
+											try {
+												const data = JSON.parse(dataStr);
+
+												if (event === 'progress' && onProgress) {
+													onProgress(data.message, data.fraction);
+												} else if (event === 'result') {
+													result = data as ExecutionResult;
+												} else if (event === 'error') {
+													reject(new Error(data.message));
+													return;
+												}
+											} catch (e) {
+												console.error('Failed to parse SSE data:', dataStr);
+											}
+										}
+										break;
+									}
+								}
+							}
+						}
+					}
+
+					if (result) {
+						resolve(result);
+					} else {
+						reject(new Error('No result received from server'));
+					}
+				})
+				.catch(reject);
+		});
+	}
+
+	/**
+	 * Executes code on the server in a sandboxed environment.
+	 */
+	async execute(code: string, config?: Partial<ExecutionConfig>): Promise<ExecutionResult> {
+		await this.session.ensureInitialized();
+
+		const hints = this.tokenRegistry.getRecentTokens(1000);
+
+		const executionConfig = {
+			...config,
+			clientServices: {
+				hasLLM: !!this.serviceProviders.getLLM(),
+				hasApproval: !!this.serviceProviders.getApproval(),
+				hasEmbedding: !!this.serviceProviders.getEmbedding(),
+				hasTools: this.serviceProviders.hasTools(),
+			},
+			provenanceHints: hints.length > 0 ? hints : undefined,
+		};
+
+		const url = `${this.session.getBaseUrl()}/api/execute`;
+		const body = JSON.stringify({ code, config: executionConfig });
+		const headers = await this.session.prepareHeaders('POST', url, body);
+
+		const response = await fetch(url, {
+			method: 'POST',
+			headers,
+			body,
+		});
+
+		this.session.updateToken(response);
+
+		if (!response.ok) {
+			const error = (await response.json()) as { error: string };
+			throw new Error(`Execution failed: ${error.error || response.statusText}`);
+		}
+
+		const result = (await response.json()) as ExecutionResult;
+
+		if (result.provenanceTokens && result.provenanceTokens.length > 0) {
+			for (const { token } of result.provenanceTokens) {
+				this.tokenRegistry.add(token);
+			}
+		}
+
+		if (result.status === ExecutionStatus.PAUSED && result.needsCallbacks) {
+			return await this.handleBatchCallbacksAndResume(result);
+		}
+
+		if (result.status === ExecutionStatus.PAUSED && result.needsCallback) {
+			return await this.handlePauseAndResume(result);
+		}
+
+		return result;
+	}
+
+	/**
+	 * Handles batch callbacks by executing them in parallel and resuming.
+	 */
+	private async handleBatchCallbacksAndResume(
+		pausedResult: ExecutionResult
+	): Promise<ExecutionResult> {
+		if (!pausedResult.needsCallbacks || pausedResult.needsCallbacks.length === 0) {
+			throw new Error('No batch callback requests in paused execution');
+		}
+
+		const batchResults = await Promise.all(
+			pausedResult.needsCallbacks.map(async (cb) => {
+				const callbackResult = await this.serviceProviders.handleCallback(cb.type, {
+					...cb.payload,
+					operation: cb.operation,
+				});
+				return { id: cb.id, result: callbackResult };
+			})
+		);
+
+		return await this.resumeWithBatchResults(pausedResult.executionId, batchResults);
+	}
+
+	/**
+	 * Handles a paused execution by processing the callback and resuming.
+	 */
+	private async handlePauseAndResume(pausedResult: ExecutionResult): Promise<ExecutionResult> {
+		if (!pausedResult.needsCallback) {
+			throw new Error('No callback request in paused execution');
+		}
+
+		try {
+			const callbackResult = await this.serviceProviders.handleCallback(
+				pausedResult.needsCallback.type,
+				{
+					...pausedResult.needsCallback.payload,
+					operation: pausedResult.needsCallback.operation,
+					executionId: pausedResult.executionId,
+				}
+			);
+
+			return await this.resume(pausedResult.executionId, callbackResult);
+		} catch (error) {
+			if (error instanceof ClientCallbackError) {
+				throw error;
+			}
+			return await this.resume(pausedResult.executionId, {
+				__error: true,
+				message: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
+	/**
+	 * Resumes a paused execution with a callback result.
+	 */
+	async resume(executionId: string, callbackResult: unknown): Promise<ExecutionResult> {
+		await this.session.ensureInitialized();
+
+		const url = `${this.session.getBaseUrl()}/api/resume/${executionId}`;
+		const body = JSON.stringify({ result: callbackResult });
+		const headers = await this.session.prepareHeaders('POST', url, body);
+
+		const response = await fetch(url, {
+			method: 'POST',
+			headers,
+			body,
+		});
+
+		this.session.updateToken(response);
+
+		if (!response.ok) {
+			const error = (await response.json()) as { error: string };
+			throw new Error(`Resume failed: ${error.error || response.statusText}`);
+		}
+
+		const result = (await response.json()) as ExecutionResult;
+
+		if (result.provenanceTokens && result.provenanceTokens.length > 0) {
+			for (const { token } of result.provenanceTokens) {
+				this.tokenRegistry.add(token);
+			}
+		}
+
+		if (result.status === ExecutionStatus.PAUSED && result.needsCallbacks) {
+			return await this.handleBatchCallbacksAndResume(result);
+		}
+
+		if (result.status === ExecutionStatus.PAUSED && result.needsCallback) {
+			return await this.handlePauseAndResume(result);
+		}
+
+		return result;
+	}
+
+	/**
+	 * Resumes a paused execution with batch callback results.
+	 */
+	private async resumeWithBatchResults(
+		executionId: string,
+		batchResults: Array<{ id: string; result: unknown }>
+	): Promise<ExecutionResult> {
+		await this.session.ensureInitialized();
+
+		const url = `${this.session.getBaseUrl()}/api/resume/${executionId}`;
+		const body = JSON.stringify({ results: batchResults });
+		const headers = await this.session.prepareHeaders('POST', url, body);
+
+		const response = await fetch(url, {
+			method: 'POST',
+			headers,
+			body,
+		});
+
+		this.session.updateToken(response);
+
+		if (!response.ok) {
+			const error = (await response.json()) as { error: string };
+			throw new Error(`Batch resume failed: ${error.error || response.statusText}`);
+		}
+
+		const result = (await response.json()) as ExecutionResult;
+
+		if (result.provenanceTokens && result.provenanceTokens.length > 0) {
+			for (const { token } of result.provenanceTokens) {
+				this.tokenRegistry.add(token);
+			}
+		}
+
+		if (result.status === ExecutionStatus.PAUSED && result.needsCallbacks) {
+			return await this.handleBatchCallbacksAndResume(result);
+		}
+
+		if (result.status === ExecutionStatus.PAUSED && result.needsCallback) {
+			return await this.handlePauseAndResume(result);
+		}
+
+		return result;
+	}
+}

package/src/core/index.ts

@@ -0,0 +1,13 @@
+export * from './session.js';
+export * from './api-operations.js';
+export * from './execution-operations.js';
+export * from './service-providers.js';
+export * from './types.js';
+
+export { CallbackType } from '@mondaydotcomorg/atp-protocol';
+export type {
+	ClientLLMHandler,
+	ClientApprovalHandler,
+	ClientEmbeddingHandler,
+	ClientServiceProviders,
+} from '@mondaydotcomorg/atp-protocol';

package/src/core/provenance-registry.ts

@@ -0,0 +1,129 @@
+/**
+ * Provenance Token Registry for Client
+ *
+ * Stores and manages provenance tokens for multi-step tracking
+ */
+
+export interface TokenEntry {
+	token: string;
+	addedAt: number;
+}
+
+export class ProvenanceTokenRegistry {
+	private cache: Map<string, TokenEntry> = new Map();
+	private maxSize: number;
+	private ttl: number;
+
+	constructor(maxSize: number = 10000, ttlHours: number = 1) {
+		this.maxSize = maxSize;
+		this.ttl = ttlHours * 3600 * 1000;
+	}
+
+	/**
+	 * Add a token to the registry
+	 */
+	add(token: string): void {
+		// Evict expired tokens first
+		this.evictExpired();
+
+		// Check if at capacity and evict LRU if needed
+		if (this.cache.size >= this.maxSize) {
+			this.evictLRU();
+		}
+
+		// Store token
+		this.cache.set(token, {
+			token,
+			addedAt: Date.now(),
+		});
+	}
+
+	/**
+	 * Get recent tokens (non-expired, sorted by age, limited)
+	 */
+	getRecentTokens(maxCount: number = 1000): string[] {
+		this.evictExpired();
+
+		const now = Date.now();
+		const expiredTokens: string[] = [];
+
+		const entries = Array.from(this.cache.values())
+			.filter((entry) => {
+				try {
+					const [body] = entry.token.split('.');
+					if (!body) {
+						expiredTokens.push(entry.token);
+						return false;
+					}
+					const payload = JSON.parse(Buffer.from(body, 'base64url').toString());
+					if (!payload.expiresAt || payload.expiresAt <= now) {
+						expiredTokens.push(entry.token);
+						return false;
+					}
+					return true;
+				} catch {
+					expiredTokens.push(entry.token);
+					return false;
+				}
+			})
+			.sort((a, b) => b.addedAt - a.addedAt)
+			.slice(0, maxCount);
+
+		for (const token of expiredTokens) {
+			this.cache.delete(token);
+		}
+
+		return entries.map((e) => e.token);
+	}
+
+	/**
+	 * Clear all tokens
+	 */
+	clear(): void {
+		this.cache.clear();
+	}
+
+	/**
+	 * Get registry size
+	 */
+	size(): number {
+		return this.cache.size;
+	}
+
+	/**
+	 * Evict expired tokens
+	 */
+	private evictExpired(): void {
+		const now = Date.now();
+		const toDelete: string[] = [];
+
+		for (const [token, entry] of this.cache.entries()) {
+			if (now - entry.addedAt > this.ttl) {
+				toDelete.push(token);
+			}
+		}
+
+		for (const token of toDelete) {
+			this.cache.delete(token);
+		}
+	}
+
+	/**
+	 * Evict least recently used (oldest) token
+	 */
+	private evictLRU(): void {
+		let oldestToken: string | null = null;
+		let oldestTime = Infinity;
+
+		for (const [token, entry] of this.cache.entries()) {
+			if (entry.addedAt < oldestTime) {
+				oldestTime = entry.addedAt;
+				oldestToken = token;
+			}
+		}
+
+		if (oldestToken) {
+			this.cache.delete(oldestToken);
+		}
+	}
+}

package/src/core/service-providers.ts

@@ -0,0 +1,176 @@
+import { CallbackType, ToolOperation } from '@mondaydotcomorg/atp-protocol';
+import type {
+	ClientLLMHandler,
+	ClientApprovalHandler,
+	ClientEmbeddingHandler,
+	ClientServiceProviders,
+	ClientTool,
+	ClientToolDefinition,
+	ClientToolHandler,
+} from '@mondaydotcomorg/atp-protocol';
+
+const LLMOperation = {
+	CALL: 'call',
+	EXTRACT: 'extract',
+	CLASSIFY: 'classify',
+} as const;
+
+const EmbeddingOperation = {
+	EMBED: 'embed',
+	SEARCH: 'search',
+} as const;
+
+export class ServiceProviders {
+	private providers: ClientServiceProviders = {};
+	private toolHandlers: Map<string, ClientToolHandler> = new Map();
+
+	constructor(providers?: ClientServiceProviders) {
+		this.providers = providers || {};
+
+		if (providers?.tools) {
+			for (const tool of providers.tools) {
+				this.toolHandlers.set(tool.name, tool.handler);
+			}
+		}
+	}
+
+	provideLLM(handler: ClientLLMHandler): void {
+		this.providers.llm = handler;
+	}
+
+	provideApproval(handler: ClientApprovalHandler): void {
+		this.providers.approval = handler;
+	}
+
+	provideEmbedding(handler: ClientEmbeddingHandler): void {
+		this.providers.embedding = handler;
+	}
+
+	provideTools(tools: ClientTool[]): void {
+		this.providers.tools = tools;
+		for (const tool of tools) {
+			this.toolHandlers.set(tool.name, tool.handler);
+		}
+	}
+
+	getLLM(): ClientLLMHandler | undefined {
+		return this.providers.llm;
+	}
+
+	getApproval(): ClientApprovalHandler | undefined {
+		return this.providers.approval;
+	}
+
+	getEmbedding(): ClientEmbeddingHandler | undefined {
+		return this.providers.embedding;
+	}
+
+	getTools(): ClientTool[] | undefined {
+		return this.providers.tools;
+	}
+
+	/**
+	 * Get tool definitions (without handlers) for sending to server
+	 */
+	getToolDefinitions(): ClientToolDefinition[] {
+		if (!this.providers.tools) {
+			return [];
+		}
+
+		return this.providers.tools.map((tool) => {
+			const { handler, ...definition } = tool;
+			return definition;
+		});
+	}
+
+	/**
+	 * Check if client has tools
+	 */
+	hasTools(): boolean {
+		return !!(this.providers.tools && this.providers.tools.length > 0);
+	}
+
+	/**
+	 * Check if client has any services or tools
+	 */
+	hasAnyServices(): boolean {
+		return !!(
+			this.providers.llm ||
+			this.providers.approval ||
+			this.providers.embedding ||
+			this.hasTools()
+		);
+	}
+
+	async handleCallback(callbackType: CallbackType, payload: any): Promise<any> {
+		if (payload.operation === 'batch_parallel' && payload.calls) {
+			return await Promise.all(
+				payload.calls.map(async (call: any) => {
+					return await this.handleCallback(call.type, {
+						...call.payload,
+						operation: call.operation,
+					});
+				})
+			);
+		}
+
+		switch (callbackType) {
+			case CallbackType.LLM:
+				if (!this.providers.llm) {
+					throw new Error('LLM service not provided by client');
+				}
+				if (payload.operation === LLMOperation.CALL) {
+					return await this.providers.llm.call(payload.prompt, payload.options);
+				} else if (payload.operation === LLMOperation.EXTRACT && this.providers.llm.extract) {
+					return await this.providers.llm.extract(payload.prompt, payload.schema, payload.options);
+				} else if (payload.operation === LLMOperation.CLASSIFY && this.providers.llm.classify) {
+					return await this.providers.llm.classify(
+						payload.text,
+						payload.categories,
+						payload.options
+					);
+				}
+				throw new Error(`Unsupported LLM operation: ${payload.operation}`);
+
+			case CallbackType.APPROVAL:
+				if (!this.providers.approval) {
+					throw new Error('Approval service not provided by client');
+				}
+				const contextWithExecutionId = payload.context
+					? { ...payload.context, executionId: payload.executionId }
+					: { executionId: payload.executionId };
+				return await this.providers.approval.request(payload.message, contextWithExecutionId);
+
+			case CallbackType.EMBEDDING:
+				if (!this.providers.embedding) {
+					throw new Error('Embedding service not provided by client');
+				}
+				if (payload.operation === EmbeddingOperation.EMBED) {
+					return await this.providers.embedding.embed(payload.text);
+				} else if (payload.operation === EmbeddingOperation.SEARCH) {
+					const queryEmbedding = await this.providers.embedding.embed(payload.query);
+					return queryEmbedding;
+				} else if (payload.operation === 'similarity' && this.providers.embedding.similarity) {
+					return await this.providers.embedding.similarity(payload.text1, payload.text2);
+				}
+				throw new Error(`Unsupported embedding operation: ${payload.operation}`);
+
+			case CallbackType.TOOL:
+				if (payload.operation === ToolOperation.CALL) {
+					const toolName = payload.toolName;
+					const handler = this.toolHandlers.get(toolName);
+
+					if (!handler) {
+						throw new Error(`Tool '${toolName}' not found in client tools`);
+					}
+
+					const result = await handler(payload.input);
+					return result;
+				}
+				throw new Error(`Unsupported tool operation: ${payload.operation}`);
+
+			default:
+				throw new Error(`Unknown callback type: ${callbackType}`);
+		}
+	}
+}