@mondaydotcomorg/atp-runtime 0.17.14

package/src/index.ts

@@ -0,0 +1,35 @@
+export * from './llm/index.js';
+export * from './progress/index.js';
+export * from './cache/index.js';
+export * from './utils.js';
+export * from './approval/index.js';
+export * from './embedding/index.js';
+export * from './registry.js';
+export * from './metadata/index.js';
+
+export { log, initializeLogger, shutdownLogger } from './log/index.js';
+export type { LogLevel, LoggerConfig, Logger } from './log/index.js';
+
+export { GENERATED_METADATA } from './metadata/generated.js';
+
+export {
+	setClientLLMCallback,
+	setPauseForClient,
+	setReplayMode,
+	getCallSequenceNumber,
+} from './llm/index.js';
+export { initializeCache } from './cache/index.js';
+export { initializeApproval } from './approval/index.js';
+export { setProgressCallback } from './progress/index.js';
+export { initializeVectorStore, clearVectorStore, getVectorStore } from './embedding/index.js';
+
+export {
+	PauseExecutionError,
+	isPauseError,
+	pauseForCallback,
+	CallbackType,
+	LLMOperation,
+	EmbeddingOperation,
+	ApprovalOperation,
+	ToolOperation,
+} from './pause/index.js';

package/src/llm/callback.ts

@@ -0,0 +1,24 @@
+/**
+ */
+import type { ClientLLMCallback } from './types';
+
+/**
+ * Client callback handler for LLM operations
+ * When set, LLM calls will be routed to client instead of server LLM
+ */
+let clientLLMCallback: ClientLLMCallback | undefined;
+
+/**
+ * Sets a client callback handler for LLM operations
+ * @param callback - Client callback handler
+ */
+export function setClientLLMCallback(callback: ClientLLMCallback | undefined): void {
+	clientLLMCallback = callback;
+}
+
+/**
+ * Gets the current client callback handler
+ */
+export function getClientLLMCallback(): ClientLLMCallback | undefined {
+	return clientLLMCallback;
+}

package/src/llm/index.ts

@@ -0,0 +1,121 @@
+/**
+ * LLM 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 (replay, callback, API)
+ */
+import { pauseForCallback, CallbackType, LLMOperation } from '../pause/index.js';
+import { RuntimeAPI, RuntimeMethod } from '../metadata/decorators.js';
+import { nextSequenceNumber, getCachedResult, isReplayMode } from './replay.js';
+import type { LLMCallOptions, LLMExtractOptions, LLMClassifyOptions } from './types';
+
+export type {
+	LLMCallOptions,
+	LLMExtractOptions,
+	LLMClassifyOptions,
+	ClientLLMCallback,
+} from './types';
+export { setClientLLMCallback, getClientLLMCallback } from './callback.js';
+export {
+	setPauseForClient,
+	setReplayMode,
+	getCallSequenceNumber,
+	nextSequenceNumber,
+	getCachedResult,
+	runInExecutionContext,
+	setCurrentExecutionId,
+	clearCurrentExecutionId,
+} from './replay.js';
+
+/**
+ * LLM Runtime API
+ *
+ * Provides client-side LLM operations with pause/resume support.
+ * All calls pause execution and route to client-provided LLM.
+ */
+@RuntimeAPI(
+	'llm',
+	'LLM API - Large Language Model calls using client-provided LLM (requires client.provideLLM())'
+)
+class LLMAPI {
+	/**
+	 * Makes a standard LLM call
+	 * Always pauses execution and routes to client-provided LLM
+	 */
+	@RuntimeMethod('Make an LLM call with a prompt', {
+		options: {
+			description: 'LLM call options including prompt',
+			type: 'LLMCallOptions',
+		},
+	})
+	async call(options: LLMCallOptions): Promise<string> {
+		const currentSequence = nextSequenceNumber();
+
+		const cachedResult = getCachedResult(currentSequence);
+		if (cachedResult !== undefined) {
+			return cachedResult as string;
+		}
+
+		pauseForCallback(CallbackType.LLM, LLMOperation.CALL, {
+			prompt: options.prompt,
+			options,
+			sequenceNumber: currentSequence,
+		});
+	}
+
+	/**
+	 * Extracts structured data using LLM
+	 * Always pauses execution and routes to client-provided LLM
+	 */
+	@RuntimeMethod('Extract structured data from text using an LLM', {
+		options: {
+			description: 'Extraction options with JSON schema',
+			type: 'LLMExtractOptions',
+		},
+	})
+	async extract<T>(options: LLMExtractOptions): Promise<T> {
+		const currentSequence = nextSequenceNumber();
+
+		const cachedResult = getCachedResult(currentSequence);
+		if (cachedResult !== undefined) {
+			return cachedResult as T;
+		}
+
+		pauseForCallback(CallbackType.LLM, LLMOperation.EXTRACT, {
+			prompt: options.prompt,
+			schema: options.schema,
+			options,
+			sequenceNumber: currentSequence,
+		});
+	}
+
+	/**
+	 * Classifies text into one of the provided categories
+	 * Always pauses execution and routes to client-provided LLM
+	 */
+	@RuntimeMethod('Classify text into one of the provided categories', {
+		options: {
+			description: 'Classification options with categories',
+			type: 'LLMClassifyOptions',
+		},
+	})
+	async classify(options: LLMClassifyOptions): Promise<string> {
+		const currentSequence = nextSequenceNumber();
+
+		const cachedResult = getCachedResult(currentSequence);
+		if (cachedResult !== undefined) {
+			return cachedResult as string;
+		}
+
+		pauseForCallback(CallbackType.LLM, LLMOperation.CLASSIFY, {
+			text: options.text,
+			categories: options.categories,
+			options,
+			sequenceNumber: currentSequence,
+		});
+	}
+}
+
+export const llm = new LLMAPI();

package/src/llm/replay.ts

@@ -0,0 +1,141 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+/**
+ * Execution-scoped state
+ */
+interface ExecutionState {
+	shouldPauseForClient: boolean;
+	replayResults: Map<number, unknown> | undefined;
+	callSequenceNumber: number;
+}
+
+/**
+ * Map of executionId -> ExecutionState
+ * Each execution has its own isolated state
+ */
+const executionStates = new Map<string, ExecutionState>();
+
+/**
+ * AsyncLocalStorage for execution ID - provides proper async context isolation
+ * This ensures each async execution chain has its own isolated execution ID
+ */
+const executionContext = new AsyncLocalStorage<string>();
+
+/**
+ * Current execution ID - set by runtime API wrappers
+ * This is a thread-local variable that's set before each runtime API call
+ * and cleared after, providing isolation even when AsyncLocalStorage fails
+ */
+let currentExecutionId: string | null = null;
+
+/**
+ * Sets the current execution ID for this call
+ * Called by executor before each runtime API invocation
+ */
+export function setCurrentExecutionId(executionId: string): void {
+	currentExecutionId = executionId;
+}
+
+/**
+ * Clears the current execution ID after a call
+ * Called by executor after each runtime API invocation
+ */
+export function clearCurrentExecutionId(): void {
+	currentExecutionId = null;
+}
+
+/**
+ * Gets the current execution state, creating it if needed
+ */
+function getCurrentState(): ExecutionState {
+	let executionId = currentExecutionId;
+
+	if (!executionId) {
+		executionId = executionContext.getStore() || null;
+	}
+
+	if (!executionId) {
+		throw new Error(
+			'No execution context set. Executor must call setCurrentExecutionId() before runtime API calls.'
+		);
+	}
+
+	let state = executionStates.get(executionId);
+	if (!state) {
+		state = {
+			shouldPauseForClient: false,
+			replayResults: undefined,
+			callSequenceNumber: 0,
+		};
+		executionStates.set(executionId, state);
+	}
+	return state;
+}
+
+/**
+ * Runs a function within an execution context
+ * @param executionId - Unique ID for this execution
+ * @param fn - Function to run within the context
+ */
+export function runInExecutionContext<T>(executionId: string, fn: () => T): T {
+	return executionContext.run(executionId, fn);
+}
+
+/**
+ * Configures whether to pause execution for client services
+ * @param pause - If true, throws PauseExecutionError instead of calling callback
+ */
+export function setPauseForClient(pause: boolean): void {
+	getCurrentState().shouldPauseForClient = pause;
+}
+
+/**
+ * Checks if should pause for client
+ */
+export function shouldPauseForClient(): boolean {
+	return getCurrentState().shouldPauseForClient;
+}
+
+/**
+ * Sets up replay mode for resumption
+ * @param results - Map of sequence number to result for replaying callbacks
+ */
+export function setReplayMode(results: Map<number, unknown> | undefined): void {
+	const state = getCurrentState();
+	state.replayResults = results;
+	state.callSequenceNumber = 0;
+}
+
+/**
+ * Gets current call sequence number
+ */
+export function getCallSequenceNumber(): number {
+	return getCurrentState().callSequenceNumber;
+}
+
+/**
+ * Increments and returns the next sequence number
+ */
+export function nextSequenceNumber(): number {
+	const state = getCurrentState();
+	return state.callSequenceNumber++;
+}
+
+/**
+ * Check if we have a cached result for the current sequence
+ */
+export function getCachedResult(sequenceNumber: number): unknown | undefined {
+	const state = getCurrentState();
+	if (state.replayResults && state.replayResults.has(sequenceNumber)) {
+		const result = state.replayResults.get(sequenceNumber);
+		return result;
+	}
+	return undefined;
+}
+
+/**
+ * Check if we're in replay mode
+ */
+export function isReplayMode(): boolean {
+	return getCurrentState().replayResults !== undefined;
+}

package/src/llm/types.ts

@@ -0,0 +1,29 @@
+export interface LLMCallOptions {
+	prompt: string;
+	context?: Record<string, unknown>;
+	model?: string;
+	maxTokens?: number;
+	temperature?: number;
+	systemPrompt?: string;
+}
+
+export interface LLMExtractOptions {
+	prompt: string;
+	context?: Record<string, unknown>;
+	schema: unknown;
+}
+
+export interface LLMClassifyOptions {
+	text: string;
+	categories: string[];
+	context?: Record<string, unknown>;
+}
+
+/**
+ * Client callback handler for LLM operations
+ * Set when client provides their own LLM implementation
+ */
+export type ClientLLMCallback = (
+	operation: string,
+	payload: Record<string, unknown>
+) => Promise<unknown>;

package/src/log/index.ts

@@ -0,0 +1,167 @@
+import pino from 'pino';
+import type { LogLevel, LoggerConfig, Logger } from './types.js';
+
+export type { LogLevel, LoggerConfig, Logger } from './types.js';
+
+let logger: pino.Logger | null = null;
+
+/**
+ * Initializes the logger with configuration
+ */
+export function initializeLogger(config?: LoggerConfig): void {
+	const options: pino.LoggerOptions = {
+		level: config?.level ?? 'info',
+		timestamp: pino.stdTimeFunctions.isoTime,
+		formatters: {
+			level: (label) => {
+				return { level: label };
+			},
+		},
+		redact: {
+			paths: config?.redact ?? ['apiKey', 'password', '*.apiKey', '*.password', 'authorization'],
+			censor: '[REDACTED]',
+		},
+	};
+
+	if (config?.pretty) {
+		logger = pino({
+			...options,
+			transport: {
+				target: 'pino-pretty',
+				options: {
+					colorize: true,
+					translateTime: 'SYS:standard',
+					ignore: 'pid,hostname',
+				},
+			},
+		});
+	} else if (config?.destination && config.destination !== 'stdout') {
+		logger = pino(options, pino.destination(config.destination));
+	} else {
+		logger = pino(options);
+	}
+}
+
+/**
+ * Gets or initializes the logger
+ */
+function getLogger(): pino.Logger {
+	if (!logger) {
+		initializeLogger({ level: 'info', pretty: false });
+	}
+	return logger!;
+}
+
+export const log: Logger = {
+	/**
+	 * Logs an informational message
+	 */
+	info(message: string, data?: unknown): void {
+		const l = getLogger();
+		if (data) {
+			l.info(data, message);
+		} else {
+			l.info(message);
+		}
+	},
+
+	/**
+	 * Logs a warning message
+	 */
+	warn(message: string, data?: unknown): void {
+		const l = getLogger();
+		if (data) {
+			l.warn(data, message);
+		} else {
+			l.warn(message);
+		}
+	},
+
+	/**
+	 * Logs an error message
+	 */
+	error(message: string, data?: unknown): void {
+		const l = getLogger();
+		if (data) {
+			l.error(data, message);
+		} else {
+			l.error(message);
+		}
+	},
+
+	/**
+	 * Logs a debug message
+	 */
+	debug(message: string, data?: unknown): void {
+		const l = getLogger();
+		if (data) {
+			l.debug(data, message);
+		} else {
+			l.debug(message);
+		}
+	},
+
+	/**
+	 * Logs a fatal error message
+	 */
+	fatal(message: string, data?: unknown): void {
+		const l = getLogger();
+		if (data) {
+			l.fatal(data, message);
+		} else {
+			l.fatal(message);
+		}
+	},
+
+	/**
+	 * Creates a child logger with additional context
+	 */
+	child(bindings: Record<string, unknown>): typeof log {
+		const childLogger = getLogger().child(bindings);
+		return {
+			info: (message: string, data?: unknown) => {
+				if (data) {
+					childLogger.info(data, message);
+				} else {
+					childLogger.info(message);
+				}
+			},
+			warn: (message: string, data?: unknown) => {
+				if (data) {
+					childLogger.warn(data, message);
+				} else {
+					childLogger.warn(message);
+				}
+			},
+			error: (message: string, data?: unknown) => {
+				if (data) {
+					childLogger.error(data, message);
+				} else {
+					childLogger.error(message);
+				}
+			},
+			debug: (message: string, data?: unknown) => {
+				if (data) {
+					childLogger.debug(data, message);
+				} else {
+					childLogger.debug(message);
+				}
+			},
+			fatal: (message: string, data?: unknown) => {
+				if (data) {
+					childLogger.fatal(data, message);
+				} else {
+					childLogger.fatal(message);
+				}
+			},
+			child: log.child,
+		};
+	},
+};
+
+/**
+ * Shuts down the logger (for cleanup in tests)
+ */
+export function shutdownLogger(): void {
+	logger = null;
+}

package/src/log/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Log API Types
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+export interface LoggerConfig {
+	level: LogLevel;
+	pretty?: boolean;
+	destination?: string;
+	redact?: string[];
+}
+
+export interface Logger {
+	info(message: string, data?: unknown): void;
+	warn(message: string, data?: unknown): void;
+	error(message: string, data?: unknown): void;
+	debug(message: string, data?: unknown): void;
+	fatal(message: string, data?: unknown): void;
+	child(bindings: Record<string, unknown>): Logger;
+}

package/src/metadata/decorators.ts

@@ -0,0 +1,44 @@
+/**
+ * Decorator-based metadata system for runtime APIs
+ *
+ * These decorators are MARKERS ONLY - they don't extract types at runtime.
+ * All type extraction happens at BUILD TIME using ts-morph.
+ *
+
+/**
+ * Class decorator to mark a runtime API
+ *
+ * This is just a marker - ts-morph extracts all metadata at build time
+ */
+export function RuntimeAPI(name: string, description: string) {
+	return function <T extends { new (...args: any[]): {} }>(constructor: T) {
+		(constructor as any).API_NAME = name;
+		(constructor as any).API_DESCRIPTION = description;
+
+		return constructor;
+	};
+}
+
+/**
+ * Method decorator to mark a runtime method
+ *
+ * This is just a marker - ts-morph extracts types/params at build time
+ * Only the description and optional param descriptions are stored
+ */
+export function RuntimeMethod(
+	description: string,
+	paramDescriptions?: Record<string, { description?: string; optional?: boolean; type?: string }>
+) {
+	return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+		if (!target.constructor.__methods) {
+			target.constructor.__methods = {};
+		}
+
+		target.constructor.__methods[propertyKey] = {
+			description,
+			paramDescriptions: paramDescriptions || {},
+		};
+
+		return descriptor;
+	};
+}