@mondaydotcomorg/atp-server 0.17.14

package/src/handlers/execute.handler.ts

@@ -0,0 +1,286 @@
+import type { RequestContext, ResolvedServerConfig } from '../core/config.js';
+import type { SandboxExecutor } from '../executor/index.js';
+import type { ExecutionStateManager } from '../execution-state/index.js';
+import type { ClientSessionManager } from '../client-sessions.js';
+import type { AuditSink, AuditEvent } from '@mondaydotcomorg/atp-protocol';
+import { ExecutionStatus, ProvenanceMode } from '@mondaydotcomorg/atp-protocol';
+import { nanoid } from 'nanoid';
+import {
+	captureProvenanceSnapshot,
+	verifyProvenanceHints,
+	type ProvenanceMetadata,
+} from '@mondaydotcomorg/atp-provenance';
+import { emitProvenanceTokens } from '../utils/token-emitter.js';
+import { storeHintMap, clearHintMap } from '../utils/provenance-reattachment.js';
+import { log } from '@mondaydotcomorg/atp-runtime';
+
+/**
+ * Recursively remove __prov_id__ properties from result
+ * Handles both enumerable and non-enumerable properties
+ */
+function cleanProvenanceIds(value: unknown): unknown {
+	if (value === null || value === undefined) {
+		return value;
+	}
+	if (typeof value !== 'object') {
+		return value;
+	}
+	if (Array.isArray(value)) {
+		return value.map((item) => cleanProvenanceIds(item));
+	}
+	const cleaned: Record<string, unknown> = {};
+	// Use Object.getOwnPropertyNames to get ALL properties (including non-enumerable)
+	const allKeys = Object.getOwnPropertyNames(value);
+	for (const key of allKeys) {
+		if (key !== '__prov_id__') {
+			cleaned[key] = cleanProvenanceIds((value as Record<string, unknown>)[key]);
+		}
+	}
+	return cleaned;
+}
+
+export async function handleExecute(
+	ctx: RequestContext,
+	executor: SandboxExecutor,
+	stateManager: ExecutionStateManager,
+	config: ResolvedServerConfig,
+	auditSink?: AuditSink,
+	sessionManager?: ClientSessionManager
+): Promise<unknown> {
+	const request = ctx.body as any;
+	const code = request.code || '';
+	const requestConfig = request.config || request.options || {};
+
+	if (sessionManager && ctx.clientId && ctx.clientId !== 'anonymous') {
+		const requestToken = ctx.headers['authorization']?.replace('Bearer ', '');
+
+		if (!requestToken) {
+			log.warn('Execute attempt without token', { clientId: ctx.clientId });
+			ctx.throw(401, 'Authentication error: Invalid token or client ID mismatch');
+		}
+
+		const isValid = await sessionManager.verifyClient(ctx.clientId, requestToken);
+		if (!isValid) {
+			log.warn('Execute attempt with invalid token', { clientId: ctx.clientId });
+			ctx.throw(403, 'Authentication error: Invalid token or client ID mismatch');
+		}
+	}
+
+	const memoryInBytes =
+		requestConfig.memoryLimit || requestConfig.memory || config.execution.memory;
+
+	let clientServices = requestConfig.clientServices;
+	if (sessionManager && ctx.clientId && ctx.clientId !== 'anonymous') {
+		try {
+			const session = await sessionManager.getSession(ctx.clientId);
+			const hasTools = session?.tools && session.tools.length > 0;
+
+			clientServices = {
+				...clientServices,
+				hasTools: hasTools || false,
+			};
+		} catch (error) {}
+	}
+
+	const executionConfig = {
+		timeout: requestConfig.timeout || config.execution.timeout,
+		maxMemory: memoryInBytes,
+		maxLLMCalls: requestConfig.llmCalls || config.execution.llmCalls,
+		allowedAPIs: [],
+		allowLLMCalls: true,
+		clientServices,
+		provenanceMode:
+			requestConfig.provenanceMode || config.execution.provenanceMode || ProvenanceMode.NONE,
+		securityPolicies: config.execution.securityPolicies || [],
+		provenanceHints: requestConfig.provenanceHints,
+	};
+
+	// Verify provenance hints if provided
+	let hintMap: Map<string, ProvenanceMetadata> | undefined;
+	const prelimExecutionId = nanoid();
+	if (
+		executionConfig.provenanceHints &&
+		executionConfig.provenanceHints.length > 0 &&
+		executionConfig.provenanceMode !== ProvenanceMode.NONE &&
+		ctx.cache
+	) {
+		try {
+			// Cap hints at 1000
+			if (executionConfig.provenanceHints.length > 1000) {
+				log.warn('Provenance hints capped', {
+					provided: executionConfig.provenanceHints.length,
+					capped: 1000,
+				});
+				ctx.throw(400, 'Too many provenance hints (max 1000)');
+			}
+
+			hintMap = await verifyProvenanceHints(
+				executionConfig.provenanceHints,
+				ctx.clientId || 'anonymous',
+				prelimExecutionId,
+				ctx.cache,
+				1000 // maxHints
+			);
+
+			// Store hint map for this execution
+			if (hintMap && hintMap.size > 0) {
+				storeHintMap(prelimExecutionId, hintMap);
+			}
+
+			log.info('Provenance hints verified', {
+				hintsProvided: executionConfig.provenanceHints.length,
+				hintsValid: hintMap.size,
+				executionId: prelimExecutionId,
+			});
+		} catch (error) {
+			log.error('Failed to verify provenance hints', { error });
+		}
+	}
+
+	const startTime = Date.now();
+
+	if (auditSink) {
+		const startEvent: AuditEvent = {
+			eventId: nanoid(),
+			timestamp: startTime,
+			clientId: ctx.clientId || 'anonymous',
+			eventType: 'execution',
+			action: 'start',
+			code,
+			status: 'success',
+		};
+		await auditSink.write(startEvent).catch(() => {});
+	}
+
+	// Pass the prelimExecutionId so executor can access hints
+	const result = await executor.execute(code, executionConfig, ctx.clientId, {
+		callbackHistory: [],
+		newCallbackResult: undefined,
+		executionId: prelimExecutionId,
+	});
+
+	// Emit provenance tokens for completed executions
+	if (
+		result.status === ExecutionStatus.COMPLETED &&
+		executionConfig.provenanceMode &&
+		executionConfig.provenanceMode !== ProvenanceMode.NONE &&
+		ctx.cache &&
+		(result as any).provenanceSnapshot
+	) {
+		try {
+			log.info('Attempting to emit provenance tokens from snapshot', {
+				executionId: result.executionId,
+				provenanceMode: executionConfig.provenanceMode,
+				hasCache: !!ctx.cache,
+				hasSnapshot: !!(result as any).provenanceSnapshot,
+				resultType: typeof result.result,
+			});
+			const tokens = await emitProvenanceTokens(
+				result.result,
+				ctx.clientId || 'anonymous',
+				result.executionId,
+				executionConfig.provenanceMode,
+				ctx.cache,
+				log.child({ executionId: result.executionId }),
+				5000, // maxTokens
+				3600, // tokenTTL (1hr)
+				(result as any).provenanceSnapshot // Pass snapshot
+			);
+			log.info('Provenance tokens emitted', {
+				executionId: result.executionId,
+				tokenCount: tokens.length,
+			});
+			if (tokens.length > 0) {
+				(result as any).provenanceTokens = tokens;
+			}
+		} catch (error) {
+			log.error('Failed to emit provenance tokens', { error, executionId: result.executionId });
+		}
+	}
+
+	// Always clean snapshot and provenance IDs before returning
+	delete (result as any).provenanceSnapshot;
+	if (result.result && typeof result.result === 'object') {
+		const hasProv = '__prov_id__' in result.result;
+		(result as any).result = cleanProvenanceIds(result.result);
+		const stillHasProv =
+			result.result && typeof result.result === 'object' && '__prov_id__' in result.result;
+		if (hasProv && !stillHasProv) {
+			log.debug('Successfully cleaned __prov_id__ from result');
+		} else if (hasProv && stillHasProv) {
+			log.warn('Failed to clean __prov_id__ from result!');
+		}
+	}
+
+	if (auditSink) {
+		const endEvent: AuditEvent = {
+			eventId: nanoid(),
+			timestamp: Date.now(),
+			clientId: ctx.clientId || 'anonymous',
+			eventType: 'execution',
+			action: result.status === ExecutionStatus.PAUSED ? 'pause' : 'complete',
+			resourceId: result.executionId,
+			status:
+				result.status === ExecutionStatus.COMPLETED
+					? 'success'
+					: result.status === ExecutionStatus.FAILED
+						? 'failed'
+						: 'paused',
+			duration: Date.now() - startTime,
+			memoryUsed: result.stats?.memoryUsed,
+			llmCallsCount: result.stats?.llmCallsCount,
+			error: result.error
+				? {
+						message: result.error.message,
+						code: result.error.code,
+						stack: result.error.stack,
+					}
+				: undefined,
+		};
+		await auditSink.write(endEvent).catch(() => {});
+	}
+
+	if (
+		result.status === 'paused' &&
+		(result.needsCallback || result.needsCallbacks) &&
+		result.callbackHistory
+	) {
+		if (!ctx.clientId) {
+			ctx.throw(400, 'Client ID required for paused executions');
+		}
+
+		const provenanceSnap =
+			executionConfig.provenanceMode && executionConfig.provenanceMode !== ProvenanceMode.NONE
+				? captureProvenanceSnapshot(result.executionId)
+				: undefined;
+
+		const callbackRequest =
+			result.needsCallback || (result.needsCallbacks && result.needsCallbacks[0]);
+
+		if (!callbackRequest) {
+			ctx.throw(500, 'Invalid paused state: no callback request');
+		}
+
+		await stateManager.pause({
+			executionId: result.executionId,
+			code: (result as any).transformedCode || code,
+			config: executionConfig,
+			clientId: ctx.clientId,
+			callbackRequest,
+			pausedAt: Date.now(),
+			callbackHistory: result.callbackHistory,
+			currentCallbackIndex: result.callbackHistory.length - 1,
+			context: {
+				codeTransformed: !!(result as any).transformedCode,
+			},
+			provenanceState: provenanceSnap,
+		});
+	}
+
+	// Cleanup hint map
+	if (hintMap && hintMap.size > 0) {
+		clearHintMap(prelimExecutionId);
+	}
+
+	return result;
+}

package/src/handlers/explorer.handler.ts

@@ -0,0 +1,18 @@
+import type { RequestContext } from '../core/config.js';
+import type { ExplorerService } from '../explorer/index.js';
+
+export async function handleExplore(
+	ctx: RequestContext,
+	explorerService: ExplorerService
+): Promise<unknown> {
+	const body = ctx.body as { path?: string };
+	const path = body.path || '/';
+
+	const result = explorerService.explore(path);
+
+	if (!result) {
+		ctx.throw(404, `Path not found: ${path}`);
+	}
+
+	return result;
+}

package/src/handlers/init.handler.ts

@@ -0,0 +1,53 @@
+import type { RequestContext } from '../core/config.js';
+import type { ClientSessionManager } from '../client-sessions.js';
+import type { AuditSink, AuditEvent } from '@mondaydotcomorg/atp-protocol';
+import { nanoid } from 'nanoid';
+import { log } from '@mondaydotcomorg/atp-runtime';
+
+export async function handleInit(
+	ctx: RequestContext,
+	sessionManager: ClientSessionManager,
+	auditSink?: AuditSink
+): Promise<unknown> {
+	const request = ctx.body as any;
+
+	if (request.tools && Array.isArray(request.tools)) {
+		log.info('Client registering tools', {
+			toolCount: request.tools.length,
+			toolNames: request.tools.map((t: any) => t.name),
+		});
+
+		for (const tool of request.tools) {
+			if (!tool.name || typeof tool.name !== 'string') {
+				ctx.throw(400, 'Invalid tool definition: name is required');
+			}
+			if (!tool.description || typeof tool.description !== 'string') {
+				ctx.throw(400, `Invalid tool definition for '${tool.name}': description is required`);
+			}
+			if (!tool.inputSchema || typeof tool.inputSchema !== 'object') {
+				ctx.throw(400, `Invalid tool definition for '${tool.name}': inputSchema is required`);
+			}
+		}
+	}
+
+	const result = await sessionManager.initClient(request || {});
+
+	if (auditSink) {
+		const event: AuditEvent = {
+			eventId: nanoid(),
+			timestamp: Date.now(),
+			clientId: (result as any).clientId,
+			eventType: 'client_init',
+			action: 'init',
+			status: 'success',
+			metadata: {
+				clientInfo: request.clientInfo,
+				toolsRegistered: request.tools ? request.tools.length : 0,
+				toolNames: request.tools ? request.tools.map((t: any) => t.name) : [],
+			},
+		};
+		await auditSink.write(event).catch(() => {});
+	}
+
+	return result;
+}

package/src/handlers/resume.handler.ts

@@ -0,0 +1,316 @@
+import type { RequestContext, ResolvedServerConfig } from '../core/config.js';
+import type { SandboxExecutor } from '../executor/index.js';
+import type { ExecutionStateManager } from '../execution-state/index.js';
+import type { ClientSessionManager } from '../client-sessions.js';
+import { log } from '@mondaydotcomorg/atp-runtime';
+import { ExecutionStatus, ProvenanceMode } from '@mondaydotcomorg/atp-protocol';
+import {
+	restoreProvenanceSnapshot,
+	captureProvenanceSnapshot,
+	createProvenanceProxy,
+	markPrimitiveTainted,
+	ProvenanceSource,
+	type ProvenanceSnapshot,
+	type ProvenanceState,
+	type SourceMetadata,
+} from '@mondaydotcomorg/atp-provenance';
+import { nanoid } from 'nanoid';
+
+/**
+ * Tag a callback result with provenance metadata
+ */
+function tagCallbackResult(
+	callbackRecord: { type: string; operation: string; payload: any },
+	result: unknown,
+	provenanceMode?: string
+): unknown {
+	// Don't tag if provenance is disabled or not specified
+	// ProvenanceMode.NONE is 'none', so just check for falsy or 'none'
+	if (!provenanceMode || provenanceMode === ProvenanceMode.NONE) {
+		return result;
+	}
+
+	if (result === null || result === undefined) {
+		return result;
+	}
+
+	const tagValue = (value: unknown, source: SourceMetadata): unknown => {
+		if (value === null || value === undefined) {
+			return value;
+		}
+
+		// Primitive: taint it
+		if (typeof value === 'string' || typeof value === 'number') {
+			const metadata = {
+				id: nanoid(),
+				source,
+				readers: { type: 'public' as const },
+				dependencies: [],
+				context: {},
+			};
+			markPrimitiveTainted(value, metadata);
+			return value;
+		}
+
+		// Objects/arrays: create provenance proxy
+		if (typeof value === 'object') {
+			return createProvenanceProxy(value, source, { type: 'public' });
+		}
+
+		return value;
+	};
+
+	// Determine source based on callback type
+	if (callbackRecord.type === 'llm') {
+		const source: SourceMetadata = {
+			type: ProvenanceSource.LLM,
+			operation: (callbackRecord.operation as 'call' | 'extract' | 'classify') || 'call',
+			timestamp: Date.now(),
+		};
+		return Array.isArray(result)
+			? result.map((r) => tagValue(r, source))
+			: tagValue(result, source);
+	}
+
+	if (callbackRecord.type === 'tool') {
+		const source: SourceMetadata = {
+			type: ProvenanceSource.TOOL,
+			toolName: (callbackRecord.payload as any)?.toolName || 'clientTool',
+			apiGroup: (callbackRecord.payload as any)?.namespace || 'client',
+			timestamp: Date.now(),
+		};
+		return Array.isArray(result)
+			? result.map((r) => tagValue(r, source))
+			: tagValue(result, source);
+	}
+
+	// No tagging for other callback types
+	return result;
+}
+
+export async function handleResume(
+	ctx: RequestContext,
+	executionId: string,
+	executor: SandboxExecutor,
+	stateManager: ExecutionStateManager,
+	serverConfig: ResolvedServerConfig,
+	sessionManager?: ClientSessionManager
+): Promise<unknown> {
+	const requestClientId = ctx.headers['x-client-id'] || ctx.clientId;
+	const requestToken = ctx.headers['authorization']?.replace('Bearer ', '');
+
+	if (!requestClientId || !requestToken) {
+		log.warn('Resume attempt without authentication', { executionId });
+		ctx.throw(401, 'Authentication required');
+	}
+
+	ctx.clientId = requestClientId;
+
+	if (sessionManager) {
+		const isValid = await sessionManager.verifyClient(requestClientId, requestToken);
+		if (!isValid) {
+			log.warn('Resume attempt with invalid token', { executionId, clientId: requestClientId });
+			ctx.throw(403, 'Invalid client credentials');
+		}
+	}
+
+	const pausedState = await stateManager.get(executionId);
+
+	if (!pausedState) {
+		ctx.throw(404, 'Not found');
+	}
+
+	if (pausedState.clientId !== requestClientId) {
+		log.warn('Resume attempt by unauthorized client', {
+			executionId,
+			requestClientId,
+			ownerClientId: pausedState.clientId,
+		});
+		ctx.throw(403, 'Unauthorized: execution belongs to different client');
+	}
+
+	log.info('Resume authorized', { executionId, clientId: requestClientId });
+
+	if (
+		pausedState.provenanceState &&
+		pausedState.config.provenanceMode &&
+		pausedState.config.provenanceMode !== ProvenanceMode.NONE
+	) {
+		// Check if it's a ProvenanceSnapshot (with primitives) or old ProvenanceState
+		const state = pausedState.provenanceState;
+		if ('primitives' in state) {
+			// New snapshot format
+			restoreProvenanceSnapshot(executionId, state as ProvenanceSnapshot);
+			log.info('Provenance snapshot restored', {
+				executionId,
+				registryEntries: state.registry.length,
+				primitiveEntries: state.primitives.length,
+			});
+		} else {
+			// Old state format (backward compat)
+			const provenanceMap = new Map<string, any>(state.registry);
+			restoreProvenanceSnapshot(executionId, {
+				registry: state.registry,
+				primitives: [],
+			});
+			log.info('Provenance state restored (legacy format)', {
+				executionId,
+				entries: provenanceMap.size,
+			});
+		}
+	}
+
+	const request = ctx.body as any;
+
+	let updatedHistory: any[];
+	let callbackResult: unknown;
+
+	const lastRecord = pausedState.callbackHistory[pausedState.currentCallbackIndex];
+
+	if (!lastRecord) {
+		log.error('No callback record found at current index', {
+			executionId,
+			currentIndex: pausedState.currentCallbackIndex,
+		});
+		ctx.throw(500, 'Invalid paused state: no callback record');
+	}
+
+	if (request.results) {
+		const batchResults = request.results as Array<{ id: string; result: unknown }>;
+		log.info('Processing batch callback results', {
+			executionId,
+			batchCount: batchResults.length,
+		});
+
+		for (const br of batchResults) {
+			if (br.result && typeof br.result === 'object' && '__error' in br.result) {
+				const errorObj = br.result as { __error: boolean; message: string };
+				if (errorObj.message && errorObj.message.includes('service not provided')) {
+					log.error('Service provider error in batch', { executionId, error: errorObj.message });
+					await stateManager.delete(executionId);
+					return {
+						executionId,
+						status: ExecutionStatus.FAILED,
+						error: {
+							message: errorObj.message || 'Service not available',
+							code: 'SERVICE_NOT_PROVIDED',
+						},
+						stats: {
+							duration: 0,
+							memoryUsed: 0,
+							llmCallsCount: 0,
+							approvalCallsCount: 0,
+						},
+					};
+				}
+			}
+		}
+
+		// Tag batch results
+		const taggedBatchResults = batchResults.map((br) => ({
+			...br,
+			result: tagCallbackResult(lastRecord, br.result, pausedState.config.provenanceMode),
+		}));
+		callbackResult = taggedBatchResults.map((br) => br.result);
+
+		updatedHistory = pausedState.callbackHistory.map((record, index) => {
+			if (index === pausedState.currentCallbackIndex) {
+				return { ...record, result: callbackResult };
+			}
+			return record;
+		});
+	} else {
+		// Tag single result
+		const rawResult = request.result;
+
+		// Check for service provider errors (not tool errors)
+		if (rawResult && typeof rawResult === 'object' && '__error' in rawResult) {
+			const errorObj = rawResult as { __error: boolean; message: string };
+			// Only fail execution for service provider errors (service not available)
+			if (errorObj.message && errorObj.message.includes('service not provided')) {
+				log.error('Service provider error', { executionId, error: errorObj.message });
+				await stateManager.delete(executionId);
+				return {
+					executionId,
+					status: ExecutionStatus.FAILED,
+					error: {
+						message: errorObj.message || 'Service not available',
+						code: 'SERVICE_NOT_PROVIDED',
+					},
+					stats: {
+						duration: 0,
+						memoryUsed: 0,
+						llmCallsCount: 0,
+						approvalCallsCount: 0,
+					},
+				};
+			}
+		}
+
+		callbackResult = tagCallbackResult(lastRecord, rawResult, pausedState.config.provenanceMode);
+
+		updatedHistory = pausedState.callbackHistory.map((record, index) => {
+			if (index === pausedState.currentCallbackIndex) {
+				return { ...record, result: callbackResult };
+			}
+			return record;
+		});
+	}
+
+	const restoredConfig = {
+		...pausedState.config,
+		securityPolicies: serverConfig.execution.securityPolicies || [],
+	};
+
+	const result = await executor.execute(pausedState.code, restoredConfig, pausedState.clientId, {
+		callbackHistory: updatedHistory,
+		newCallbackResult: callbackResult,
+		executionId,
+	});
+
+	if (result.status === ExecutionStatus.PAUSED && result.needsCallbacks && result.callbackHistory) {
+		const provenanceState =
+			pausedState.config.provenanceMode && pausedState.config.provenanceMode !== ProvenanceMode.NONE
+				? captureProvenanceSnapshot(result.executionId)
+				: undefined;
+
+		await stateManager.pause({
+			executionId: result.executionId,
+			code: pausedState.code,
+			config: pausedState.config,
+			clientId: pausedState.clientId,
+			callbackRequest: result.needsCallbacks[0]!,
+			pausedAt: Date.now(),
+			callbackHistory: result.callbackHistory,
+			currentCallbackIndex: result.callbackHistory.length - 1,
+			context: {},
+			provenanceState,
+		});
+	} else if (
+		result.status === ExecutionStatus.PAUSED &&
+		result.needsCallback &&
+		result.callbackHistory
+	) {
+		const provenanceState =
+			pausedState.config.provenanceMode && pausedState.config.provenanceMode !== ProvenanceMode.NONE
+				? captureProvenanceSnapshot(result.executionId)
+				: undefined;
+
+		await stateManager.pause({
+			executionId: result.executionId,
+			code: pausedState.code,
+			config: pausedState.config,
+			clientId: pausedState.clientId,
+			callbackRequest: result.needsCallback,
+			pausedAt: Date.now(),
+			callbackHistory: result.callbackHistory,
+			currentCallbackIndex: result.callbackHistory.length - 1,
+			context: {},
+			provenanceState,
+		});
+	} else {
+		await stateManager.delete(executionId);
+	}
+
+	return result;
+}

package/src/handlers/search.handler.ts

@@ -0,0 +1,32 @@
+import type { RequestContext, ResolvedServerConfig } from '../core/config.js';
+import type { SearchEngine } from '../search/index.js';
+
+export async function handleSearch(
+	ctx: RequestContext,
+	searchEngine: SearchEngine,
+	config: ResolvedServerConfig
+): Promise<unknown> {
+	const searchOptions = ctx.body as any;
+	const results = await searchEngine.search(
+		searchOptions,
+		ctx.userId,
+		ctx.auth,
+		config.discovery.scopeFiltering
+	);
+	return { results };
+}
+
+export async function handleSearchQuery(
+	ctx: RequestContext,
+	searchEngine: SearchEngine,
+	config: ResolvedServerConfig
+): Promise<unknown> {
+	const query = ctx.query.query || ctx.query.keyword || '';
+	const results = await searchEngine.search(
+		{ query },
+		ctx.userId,
+		ctx.auth,
+		config.discovery.scopeFiltering
+	);
+	return { results };
+}