@mondaydotcomorg/atp-runtime 0.17.14

package/src/metadata/generated.ts

@@ -0,0 +1,293 @@
+/**
+ * AUTO-GENERATED - DO NOT EDIT
+ * Generated by scripts/generate-metadata.ts
+ * 
+ * Hybrid approach:
+ * - ts-json-schema-generator (OSS) for most types
+ * - ts-morph fallback for types OSS can't handle (generics)
+ */
+
+import type { RuntimeAPIMetadata } from './types';
+
+export const GENERATED_METADATA: RuntimeAPIMetadata[] = [
+  {
+    "name": "approval",
+    "description": "Approval API - Request explicit human approval for sensitive operations",
+    "methods": [
+      {
+        "name": "request",
+        "description": "Request approval from a human",
+        "params": [
+          {
+            "name": "message",
+            "type": "string",
+            "description": "The message to display to the user",
+            "optional": false
+          },
+          {
+            "name": "context",
+            "type": "Record<string, unknown>",
+            "description": "Optional context information about what needs approval",
+            "optional": true
+          }
+        ],
+        "returns": "Promise<ApprovalResponse>"
+      }
+    ]
+  },
+  {
+    "name": "cache",
+    "description": "Cache API - Store and retrieve data with optional TTL",
+    "methods": [
+      {
+        "name": "get",
+        "description": "Get a value from cache by key",
+        "params": [
+          {
+            "name": "key",
+            "type": "string",
+            "description": "Cache key",
+            "optional": false
+          }
+        ],
+        "returns": "Promise<T | null>"
+      },
+      {
+        "name": "set",
+        "description": "Set a value in cache with optional TTL",
+        "params": [
+          {
+            "name": "key",
+            "type": "string",
+            "description": "Cache key",
+            "optional": false
+          },
+          {
+            "name": "value",
+            "type": "unknown",
+            "description": "Value to cache",
+            "optional": false
+          },
+          {
+            "name": "ttl",
+            "type": "number",
+            "description": "Time to live in seconds",
+            "optional": true
+          }
+        ],
+        "returns": "Promise<void>"
+      },
+      {
+        "name": "delete",
+        "description": "Delete a value from cache",
+        "params": [
+          {
+            "name": "key",
+            "type": "string",
+            "description": "Cache key to delete",
+            "optional": false
+          }
+        ],
+        "returns": "Promise<void>"
+      },
+      {
+        "name": "has",
+        "description": "Check if a key exists in cache",
+        "params": [
+          {
+            "name": "key",
+            "type": "string",
+            "description": "Cache key to check",
+            "optional": false
+          }
+        ],
+        "returns": "Promise<boolean>"
+      },
+      {
+        "name": "clear",
+        "description": "Clear all cache entries",
+        "params": [],
+        "returns": "Promise<void>"
+      }
+    ]
+  },
+  {
+    "name": "embedding",
+    "description": "Embedding API - Client-side embedding with server-side vector storage",
+    "methods": [
+      {
+        "name": "embed",
+        "description": "Request client to generate and store embeddings",
+        "params": [
+          {
+            "name": "input",
+            "type": "string | string[]",
+            "description": "Text(s) to embed",
+            "optional": false
+          },
+          {
+            "name": "metadata",
+            "type": "Record<string, unknown>",
+            "description": "Optional metadata to store with embeddings",
+            "optional": true
+          }
+        ],
+        "returns": "Promise<string | string[]>"
+      },
+      {
+        "name": "search",
+        "description": "Search stored embeddings by similarity",
+        "params": [
+          {
+            "name": "query",
+            "type": "string",
+            "description": "Search query text (will be embedded by client)",
+            "optional": false
+          },
+          {
+            "name": "options",
+            "type": "Omit<SearchOptions, 'query'>",
+            "description": "Search options (topK, minSimilarity, filter)",
+            "optional": true
+          }
+        ],
+        "returns": "Promise<SearchResult[]>"
+      },
+      {
+        "name": "similarity",
+        "description": "Calculate cosine similarity between two embedding vectors",
+        "params": [
+          {
+            "name": "embedding1",
+            "type": "number[]",
+            "description": "First embedding vector",
+            "optional": false
+          },
+          {
+            "name": "embedding2",
+            "type": "number[]",
+            "description": "Second embedding vector",
+            "optional": false
+          }
+        ],
+        "returns": "number"
+      },
+      {
+        "name": "getAll",
+        "description": "Get all stored embeddings",
+        "params": [],
+        "returns": "EmbeddingRecord[]"
+      },
+      {
+        "name": "count",
+        "description": "Get count of stored embeddings",
+        "params": [],
+        "returns": "number"
+      }
+    ]
+  },
+  {
+    "name": "llm",
+    "description": "LLM API - Large Language Model calls using client-provided LLM (requires client.provideLLM())",
+    "methods": [
+      {
+        "name": "call",
+        "description": "Make an LLM call with a prompt",
+        "params": [
+          {
+            "name": "options",
+            "type": "LLMCallOptions",
+            "description": "LLM call options including prompt",
+            "optional": false
+          }
+        ],
+        "returns": "Promise<string>"
+      },
+      {
+        "name": "extract",
+        "description": "Extract structured data from text using an LLM",
+        "params": [
+          {
+            "name": "options",
+            "type": "LLMExtractOptions",
+            "description": "Extraction options with JSON schema",
+            "optional": false
+          }
+        ],
+        "returns": "Promise<T>"
+      },
+      {
+        "name": "classify",
+        "description": "Classify text into one of the provided categories",
+        "params": [
+          {
+            "name": "options",
+            "type": "LLMClassifyOptions",
+            "description": "Classification options with categories",
+            "optional": false
+          }
+        ],
+        "returns": "Promise<string>"
+      }
+    ]
+  },
+  {
+    "name": "progress",
+    "description": "Progress API - Report execution progress to clients",
+    "methods": [
+      {
+        "name": "report",
+        "description": "Report progress with message and completion fraction",
+        "params": [
+          {
+            "name": "message",
+            "type": "string",
+            "description": "Progress message",
+            "optional": false
+          },
+          {
+            "name": "fraction",
+            "type": "number",
+            "description": "Completion fraction (0-1)",
+            "optional": false
+          }
+        ],
+        "returns": "void"
+      }
+    ]
+  }
+];
+
+/**
+ * Type definitions extracted using ts-json-schema-generator
+ */
+export const TYPE_REGISTRY = [
+  {
+    "name": "ApprovalResponse",
+    "definition": "export interface ApprovalResponse<T = unknown> {\n\tapproved: boolean;\n\tresponse?: T;\n\ttimestamp: number;\n}"
+  },
+  {
+    "name": "SearchOptions",
+    "definition": "interface SearchOptions {\n  query: string;\n  topK?: number;\n  minSimilarity?: number;\n  filter?: Record<string, unknown>;\n}"
+  },
+  {
+    "name": "SearchResult",
+    "definition": "interface SearchResult {\n  id: string;\n  text: string;\n  similarity: number;\n  metadata?: Record<string, unknown>;\n}"
+  },
+  {
+    "name": "EmbeddingRecord",
+    "definition": "interface EmbeddingRecord {\n  id: string;\n  text: string;\n  embedding: number[];\n  metadata?: Record<string, unknown>;\n}"
+  },
+  {
+    "name": "LLMCallOptions",
+    "definition": "interface LLMCallOptions {\n  prompt: string;\n  context?: Record<string, unknown>;\n  model?: string;\n  maxTokens?: number;\n  temperature?: number;\n  systemPrompt?: string;\n}"
+  },
+  {
+    "name": "LLMExtractOptions",
+    "definition": "interface LLMExtractOptions {\n  prompt: string;\n  context?: Record<string, unknown>;\n  schema: unknown;\n}"
+  },
+  {
+    "name": "LLMClassifyOptions",
+    "definition": "interface LLMClassifyOptions {\n  text: string;\n  categories: string[];\n  context?: Record<string, unknown>;\n}"
+  }
+];

package/src/metadata/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Metadata and Type Generation Utilities
+ */
+
+export type { RuntimeAPIParam, RuntimeAPIMethod, RuntimeAPIMetadata } from './types.js';
+export { RuntimeAPI, RuntimeMethod } from './decorators.js';
+
+import type { RuntimeAPIMetadata } from './types.js';
+
+/**
+ * Generates TypeScript definitions from runtime API metadata
+ */
+export function generateRuntimeTypes(apis: RuntimeAPIMetadata[]): string {
+	let typescript = '// Runtime SDK\ndeclare const atp: {\n';
+
+	for (const api of apis) {
+		typescript += `  /**\n`;
+		for (const line of api.description.split('\n')) {
+			typescript += `   * ${line}\n`;
+		}
+		typescript += `   */\n`;
+
+		typescript += `  ${api.name}: {\n`;
+
+		for (const method of api.methods) {
+			typescript += `    /**\n`;
+			typescript += `     * ${method.description}\n`;
+
+			for (const param of method.params) {
+				if (param.description) {
+					typescript += `     * @param ${param.name} - ${param.description}\n`;
+				}
+			}
+
+			if (method.returns !== 'void') {
+				const returnDesc = method.returns.startsWith('Promise')
+					? 'Promise resolving to result'
+					: 'Result value';
+				typescript += `     * @returns ${returnDesc}\n`;
+			}
+
+			typescript += `     */\n`;
+
+			const paramStrings = method.params.map((p) => {
+				const optional = p.optional ? '?' : '';
+				const type = p.type.includes('\n') ? p.type.replace(/\n/g, '\n      ') : p.type;
+				return `${p.name}${optional}: ${type}`;
+			});
+
+			typescript += `    ${method.name}(${paramStrings.join(', ')}): ${method.returns};\n`;
+
+			typescript += `\n`;
+		}
+
+		typescript += `  };\n\n`;
+	}
+
+	typescript += '};\n\n';
+
+	return typescript;
+}

package/src/metadata/types.ts

@@ -0,0 +1,24 @@
+/**
+ * Common metadata interface for runtime APIs
+ * Each runtime module exports its metadata for the type generator
+ */
+
+export interface RuntimeAPIParam {
+	name: string;
+	type: string;
+	description?: string;
+	optional?: boolean;
+}
+
+export interface RuntimeAPIMethod {
+	name: string;
+	description: string;
+	params: RuntimeAPIParam[];
+	returns: string;
+}
+
+export interface RuntimeAPIMetadata {
+	name: string;
+	description: string;
+	methods: RuntimeAPIMethod[];
+}

package/src/pause/index.ts

@@ -0,0 +1,28 @@
+import { PauseExecutionError, CallbackType } from './types.js';
+
+export {
+	PauseExecutionError,
+	CallbackType,
+	LLMOperation,
+	EmbeddingOperation,
+	ApprovalOperation,
+	ToolOperation,
+} from './types.js';
+
+/**
+ * Helper to create pause error
+ */
+export function pauseForCallback(
+	type: CallbackType,
+	operation: string,
+	payload: Record<string, unknown>
+): never {
+	throw new PauseExecutionError(type, operation, payload);
+}
+
+/**
+ * Check if error is a pause request
+ */
+export function isPauseError(error: unknown): error is PauseExecutionError {
+	return error instanceof PauseExecutionError;
+}

package/src/pause/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Callback types that can pause execution
+ */
+export enum CallbackType {
+	LLM = 'llm',
+	APPROVAL = 'approval',
+	EMBEDDING = 'embedding',
+	TOOL = 'tool',
+}
+
+/**
+ * LLM callback operations
+ */
+export enum LLMOperation {
+	CALL = 'call',
+	EXTRACT = 'extract',
+	CLASSIFY = 'classify',
+}
+
+/**
+ * Embedding callback operations
+ */
+export enum EmbeddingOperation {
+	EMBED = 'embed',
+	SEARCH = 'search',
+}
+
+/**
+ * Approval callback operations
+ */
+export enum ApprovalOperation {
+	REQUEST = 'request',
+}
+
+/**
+ * Tool callback operations
+ */
+export enum ToolOperation {
+	CALL = 'call',
+}
+
+/**
+ * Thrown when execution needs to pause for client callback
+ */
+export class PauseExecutionError extends Error {
+	public readonly type: CallbackType;
+	public readonly operation: string;
+	public readonly payload: Record<string, unknown>;
+
+	constructor(type: CallbackType, operation: string, payload: Record<string, unknown>) {
+		super(`Execution paused: waiting for ${type}.${operation}`);
+		this.name = 'PauseExecutionError';
+		this.type = type;
+		this.operation = operation;
+		this.payload = payload;
+	}
+}

package/src/progress/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Progress API - Clean refactored version with decorators
+ *
+ * Benefits:
+ * - No duplication between implementation and metadata
+ * - Types auto-detected from TypeScript signatures
+ */
+import { RuntimeAPI, RuntimeMethod } from '../metadata/decorators.js';
+import type { ProgressCallback } from './types.js';
+
+export type { ProgressCallback } from './types.js';
+
+/**
+ * Global progress callback (set by executor)
+ */
+let progressCallback: ProgressCallback | null = null;
+
+/**
+ * Set the progress callback handler
+ */
+export function setProgressCallback(callback: ProgressCallback | null): void {
+	progressCallback = callback;
+}
+
+/**
+ * Progress Runtime API
+ *
+ * Allows reporting execution progress to clients
+ */
+@RuntimeAPI('progress', 'Progress API - Report execution progress to clients')
+class ProgressAPI {
+	/**
+	 * Report progress with message and completion fraction
+	 */
+	@RuntimeMethod('Report progress with message and completion fraction', {
+		message: { description: 'Progress message' },
+		fraction: { description: 'Completion fraction (0-1)' },
+	})
+	report(message: string, fraction: number): void {
+		if (progressCallback) {
+			try {
+				progressCallback(message, fraction);
+			} catch (error) {
+				console.error('Progress callback error:', error);
+			}
+		}
+	}
+}
+
+export const progress = new ProgressAPI();

package/src/progress/types.ts

@@ -0,0 +1,6 @@
+/**
+
+/**
+ * Progress callback function type
+ */
+export type ProgressCallback = (message: string, fraction: number) => void;

package/src/registry.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime API Registry
+ *
+ */
+import type { RuntimeAPIMetadata } from './metadata/index.js';
+import { GENERATED_METADATA } from './metadata/generated.js';
+
+/**
+ * Get all registered runtime APIs metadata
+ *
+ * This is generated at BUILD TIME by ts-morph, not at runtime
+ */
+export function getAllAPIs(): RuntimeAPIMetadata[] {
+	return GENERATED_METADATA;
+}
+
+/**
+ * Get metadata for a specific API by name
+ */
+export function getAPI(name: string): RuntimeAPIMetadata | undefined {
+	return GENERATED_METADATA.find((api) => api.name === name);
+}

package/src/utils.ts

@@ -0,0 +1,37 @@
+export interface RetryOptions {
+	maxAttempts: number;
+	delayMs: number;
+}
+
+export const utils = {
+	async sleep(ms: number): Promise<void> {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	},
+
+	async retry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T> {
+		let lastError: Error | undefined;
+		for (let attempt = 1; attempt <= options.maxAttempts; attempt++) {
+			try {
+				return await fn();
+			} catch (error) {
+				lastError = error as Error;
+				if (attempt < options.maxAttempts) {
+					await this.sleep(options.delayMs);
+				}
+			}
+		}
+		throw lastError;
+	},
+
+	async parallel<T>(tasks: Array<() => Promise<T>>): Promise<T[]> {
+		return Promise.all(tasks.map((task) => task()));
+	},
+
+	async sequence<T>(tasks: Array<() => Promise<T>>): Promise<T[]> {
+		const results: T[] = [];
+		for (const task of tasks) {
+			results.push(await task());
+		}
+		return results;
+	},
+};