@mondaydotcomorg/atp-langchain 0.17.14

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,uBAAuB,EACvB,wBAAwB,GAGxB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,SAAiB,EACjB,OAAgC,EAChC,KAAmB;IAEnB,MAAM,MAAM,GAAG,IAAI,uBAAuB,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACnF,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IAEvB,MAAM,QAAQ,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAElD,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CACzB,CAAC,IAAU,EAAE,EAAE,CACd,IAAI,WAAW,CAAC;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE;QACnC,IAAI,EAAE,IAAI,CAAC,IAAI;KACf,CAAC,CACH,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACpD,OAAO,KAAK,CAAC,GAAG,CACf,CAAC,IAAU,EAAE,EAAE,CACd,IAAI,WAAW,CAAC;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE;QACnC,IAAI,EAAE,IAAI,CAAC,IAAI;KACf,CAAC,CACH,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@mondaydotcomorg/atp-langchain",
+	"version": "0.17.14",
+	"description": "LangChain integration for Agent Tool Protocol",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"dev": "tsc -p tsconfig.json --watch",
+		"clean": "rm -rf dist *.tsbuildinfo",
+		"test": "vitest run",
+		"lint": "tsc --noEmit"
+	},
+	"keywords": [
+		"agent",
+		"protocol",
+		"langchain",
+		"ai",
+		"llm"
+	],
+	"license": "MIT",
+	"dependencies": {
+		"@langchain/core": "^0.3.78",
+		"@mondaydotcomorg/atp-client": "0.17.14",
+		"@mondaydotcomorg/atp-protocol": "0.17.14",
+		"json-schema-to-zod": "^2.6.1",
+		"langchain": "^0.3.35",
+		"zod": "^4.1.11"
+	},
+	"devDependencies": {
+		"typescript": "^5.3.3",
+		"vitest": "^1.2.1"
+	}
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { createATPTools as createATPToolsBasic, convertToLangChainTools } from './tools.js';
+
+export * from './langgraph-client.js';
+export {
+	createATPTools,
+	createSimpleATPTool,
+	type CreateATPToolsOptions,
+	type ATPToolsResult,
+} from './langgraph-tools.js';
+
+export * from './node.js';

package/src/langgraph-client.ts

@@ -0,0 +1,369 @@
+/**
+ * LangGraph-aware ATP Client
+ *
+ * This client integrates ATP execution with LangGraph's interrupt-based
+ * human-in-the-loop (HITL) system. When ATP code calls atp.approval.request(),
+ * it triggers a LangGraph interrupt for production-ready async approval flows.
+ *
+ * Features:
+ * - LangGraph interrupt integration for approvals
+ * - LLM sampling via LangChain models
+ * - Checkpoint-aware state management
+ * - Production-ready async approval workflows
+ */
+
+import { AgentToolProtocolClient, ClientCallbackError } from '@mondaydotcomorg/atp-client';
+import type { ClientHooks } from '@mondaydotcomorg/atp-client';
+import type { ExecutionResult, ExecutionConfig, ClientTool } from '@mondaydotcomorg/atp-protocol';
+import { ExecutionStatus, CallbackType } from '@mondaydotcomorg/atp-protocol';
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { BaseMessage } from '@langchain/core/messages';
+import { HumanMessage, SystemMessage, AIMessage } from '@langchain/core/messages';
+import type { Embeddings } from '@langchain/core/embeddings';
+
+/**
+ * Approval request that needs human decision
+ */
+export interface ApprovalRequest {
+	message: string;
+	context?: Record<string, unknown>;
+	executionId: string;
+	timestamp: number;
+}
+
+/**
+ * Approval response from human
+ */
+export interface ApprovalResponse {
+	approved: boolean;
+	reason?: string;
+	timestamp: number;
+}
+
+/**
+ * Options for creating the LangGraph ATP client
+ */
+export interface LangGraphATPClientOptions {
+	/** Base URL of ATP server */
+	serverUrl: string;
+	/** Custom headers for authentication (e.g., { Authorization: 'Bearer token' }) */
+	headers?: Record<string, string>;
+	/** LangChain LLM for atp.llm.call() sampling */
+	llm: BaseChatModel;
+	/**
+	 * LangChain embeddings model for atp.embedding.embed() and atp.embedding.search()
+	 * Optional - if not provided, embedding calls will fail
+	 */
+	embeddings?: Embeddings;
+	/**
+	 * Client-provided tools that execute locally (e.g., file operations, browser automation)
+	 * These tools are registered with the server and can be called from server code execution
+	 */
+	tools?: ClientTool[];
+	/**
+	 * Whether to use LangGraph interrupts for approvals (production mode).
+	 * If false, will use a direct callback handler.
+	 * Default: true
+	 */
+	useLangGraphInterrupts?: boolean;
+	/**
+	 * Direct approval handler (only used if useLangGraphInterrupts = false)
+	 */
+	approvalHandler?: (message: string, context?: Record<string, unknown>) => Promise<boolean>;
+	/**
+	 * Hooks for intercepting and modifying client behavior
+	 */
+	hooks?: ClientHooks;
+}
+
+/**
+ * Result of ATP execution that may need approval
+ */
+export interface ATPExecutionResult {
+	/** Standard execution result */
+	result: ExecutionResult;
+	/** If true, execution is waiting for approval via LangGraph interrupt */
+	needsApproval: boolean;
+	/** Approval request details (if needsApproval = true) */
+	approvalRequest?: ApprovalRequest;
+}
+
+/**
+ * Exception thrown when approval is needed - this triggers LangGraph interrupt
+ */
+export class ApprovalRequiredException extends ClientCallbackError {
+	constructor(public readonly approvalRequest: ApprovalRequest) {
+		super(`Approval required: ${approvalRequest.message}`);
+		this.name = 'ApprovalRequiredException';
+	}
+}
+
+/**
+ * LangGraph-aware ATP Client
+ *
+ * Integrates ATP with LangGraph's production-ready interrupt system:
+ * - atp.llm.call() → Routes to LangChain LLM (no interrupt)
+ * - atp.approval.request() → Throws ApprovalRequiredException (triggers LangGraph interrupt)
+ * - Supports checkpoint-based state persistence
+ * - Enables async approval workflows
+ */
+export class LangGraphATPClient {
+	private client: AgentToolProtocolClient;
+	private llm: BaseChatModel;
+	private embeddings?: Embeddings;
+	private useLangGraphInterrupts: boolean;
+	private directApprovalHandler?: (
+		message: string,
+		context?: Record<string, unknown>
+	) => Promise<boolean>;
+
+	private pendingApprovals = new Map<string, ApprovalRequest>();
+
+	constructor(options: LangGraphATPClientOptions) {
+		const {
+			serverUrl,
+			headers,
+			llm,
+			embeddings,
+			tools,
+			useLangGraphInterrupts = true,
+			approvalHandler,
+			hooks,
+		} = options;
+
+		this.client = new AgentToolProtocolClient({
+			baseUrl: serverUrl,
+			headers,
+			hooks,
+			serviceProviders: tools ? { tools } : undefined,
+		});
+		this.llm = llm;
+		this.embeddings = embeddings;
+		this.useLangGraphInterrupts = useLangGraphInterrupts;
+		this.directApprovalHandler = approvalHandler;
+
+		this.client.provideLLM({
+			call: async (prompt: string, options?: any) => {
+				return await this.handleLLMCall(prompt, options);
+			},
+			extract: async (prompt: string, schema: any, options?: any) => {
+				return await this.handleLLMExtract(prompt, schema, options);
+			},
+			classify: async (text: string, categories: string[], options?: any) => {
+				return await this.handleLLMClassify(text, categories, options);
+			},
+		});
+
+		if (this.embeddings) {
+			this.client.provideEmbedding({
+				embed: async (text: string) => {
+					return await this.handleEmbedding(text);
+				},
+			});
+		}
+
+		this.client.provideApproval({
+			request: async (message: string, context?: Record<string, unknown>) => {
+				return await this.handleApprovalRequest(message, context);
+			},
+		});
+	}
+
+	/**
+	 * Initialize the client connection
+	 */
+	async connect(): Promise<void> {
+		await this.client.init({ name: 'langgraph-atp-client', version: '1.0.0' });
+		await this.client.connect();
+	}
+
+	/**
+	 * Get TypeScript API definitions
+	 */
+	getTypeDefinitions(): string {
+		return this.client.getTypeDefinitions();
+	}
+
+	/**
+	 * Execute ATP code with LangGraph interrupt support
+	 *
+	 * When approval is needed:
+	 * - If useLangGraphInterrupts=true: Throws ApprovalRequiredException
+	 * - If useLangGraphInterrupts=false: Uses direct approval handler
+	 *
+	 * @throws ApprovalRequiredException when approval is needed (interrupt mode)
+	 */
+	async execute(code: string, config?: Partial<ExecutionConfig>): Promise<ATPExecutionResult> {
+		const result = await this.client.execute(code, config);
+
+		return {
+			result,
+			needsApproval: false,
+		};
+	}
+
+	/**
+	 * Resume execution after approval decision
+	 *
+	 * Call this after LangGraph resumes from interrupt with approval decision.
+	 */
+	async resumeWithApproval(
+		executionId: string,
+		approved: boolean,
+		reason?: string
+	): Promise<ExecutionResult> {
+		const approvalResponse: ApprovalResponse = {
+			approved,
+			reason,
+			timestamp: Date.now(),
+		};
+
+		this.pendingApprovals.delete(executionId);
+
+		return await this.client.resume(executionId, approvalResponse);
+	}
+
+	/**
+	 * Get pending approval request for an execution
+	 */
+	getPendingApproval(executionId: string): ApprovalRequest | undefined {
+		return this.pendingApprovals.get(executionId);
+	}
+
+	/**
+	 * Handle LLM call - route to LangChain LLM
+	 */
+	private async handleLLMCall(prompt: string, options?: any): Promise<string> {
+		const messages: BaseMessage[] = [];
+
+		if (options?.systemPrompt) {
+			messages.push(new SystemMessage(options.systemPrompt));
+		}
+
+		messages.push(new HumanMessage(prompt));
+
+		const response = await this.llm.invoke(messages);
+
+		return typeof response.content === 'string'
+			? response.content
+			: JSON.stringify(response.content);
+	}
+
+	/**
+	 * Handle LLM extract - route to LangChain LLM with structured output
+	 */
+	private async handleLLMExtract(prompt: string, schema: any, options?: any): Promise<any> {
+		const structuredLLM = this.llm.withStructuredOutput(schema);
+
+		const messages: BaseMessage[] = [];
+		if (options?.systemPrompt) {
+			messages.push(new SystemMessage(options.systemPrompt));
+		}
+		messages.push(new HumanMessage(prompt));
+
+		const result = await structuredLLM.invoke(messages);
+
+		return result;
+	}
+
+	/**
+	 * Handle LLM classify - route to LangChain LLM
+	 */
+	private async handleLLMClassify(
+		text: string,
+		categories: string[],
+		options?: any
+	): Promise<string> {
+		const prompt = `Classify the following text into one of these categories: ${categories.join(', ')}\n\nText: ${text}\n\nCategory:`;
+
+		const messages: BaseMessage[] = [];
+		if (options?.systemPrompt) {
+			messages.push(new SystemMessage(options.systemPrompt));
+		}
+		messages.push(new HumanMessage(prompt));
+
+		const response = await this.llm.invoke(messages);
+
+		const result =
+			typeof response.content === 'string'
+				? response.content.trim()
+				: JSON.stringify(response.content).trim();
+
+		if (!categories.includes(result)) {
+			for (const category of categories) {
+				if (result.toLowerCase().includes(category.toLowerCase())) {
+					return category;
+				}
+			}
+			const fallback = categories[0];
+			if (!fallback) {
+				throw new Error('No categories provided for classification');
+			}
+			return fallback;
+		}
+
+		return result;
+	}
+
+	/**
+	 * Handle embedding - route to LangChain embeddings model
+	 */
+	private async handleEmbedding(text: string): Promise<number[]> {
+		if (!this.embeddings) {
+			throw new Error(
+				'Embeddings model not provided. Pass embeddings option when creating LangGraphATPClient.'
+			);
+		}
+
+		return await this.embeddings.embedQuery(text);
+	}
+
+	/**
+	 * Get the underlying ATP client for advanced usage
+	 */
+	getUnderlyingClient(): AgentToolProtocolClient {
+		return this.client;
+	}
+
+	private async handleApprovalRequest(
+		message: string,
+		context?: Record<string, unknown>
+	): Promise<{ approved: boolean; reason?: string; timestamp: number }> {
+		const executionId = (context as any)?.executionId;
+		const cleanContext = context ? { ...context } : undefined;
+		if (cleanContext) {
+			delete (cleanContext as any).executionId;
+		}
+
+		if (this.useLangGraphInterrupts) {
+			if (typeof executionId !== 'string' || !executionId) {
+				throw new Error('executionId is missing in approval request context');
+			}
+
+			const approvalRequest: ApprovalRequest = {
+				message,
+				context: cleanContext,
+				executionId,
+				timestamp: Date.now(),
+			};
+
+			this.pendingApprovals.set(executionId, approvalRequest);
+
+			throw new ApprovalRequiredException(approvalRequest);
+		}
+
+		if (this.directApprovalHandler) {
+			const approved = await this.directApprovalHandler(message, cleanContext);
+			return {
+				approved,
+				timestamp: Date.now(),
+			};
+		}
+
+		console.warn(`Approval request rejected (no handler): ${message}`);
+		return {
+			approved: false,
+			timestamp: Date.now(),
+		};
+	}
+}

package/src/langgraph-tools.ts

@@ -0,0 +1,219 @@
+/**
+ * LangGraph Tools Integration for ATP
+ *
+ * Creates LangChain-compatible tools from ATP with full support for:
+ * - LangGraph interrupts for human-in-the-loop approvals
+ * - LLM sampling via LangChain models
+ * - Checkpoint-based state persistence
+ */
+
+import { Tool, DynamicTool, DynamicStructuredTool } from '@langchain/core/tools';
+import { type JSONSchema } from '@langchain/core/utils/json_schema';
+import {
+	LangGraphATPClient,
+	type LangGraphATPClientOptions,
+	ApprovalRequiredException,
+} from './langgraph-client.js';
+import {
+	createToolsFromATPClient,
+	ToolNames,
+	type Tool as ATPTool,
+} from '@mondaydotcomorg/atp-client';
+import { ExecutionStatus, type ExecutionConfig } from '@mondaydotcomorg/atp-protocol';
+
+/**
+ * Options for creating ATP tools with LangGraph integration
+ */
+export interface CreateATPToolsOptions extends Omit<LangGraphATPClientOptions, 'serverUrl'> {
+	/** ATP server URL */
+	serverUrl: string;
+	/**
+	 * Default execution config for all ATP code executions
+	 */
+	defaultExecutionConfig?: Partial<ExecutionConfig>;
+}
+
+/**
+ * Result of creating ATP tools
+ */
+export interface ATPToolsResult {
+	/** The LangGraph-aware ATP client */
+	client: LangGraphATPClient;
+	/** LangChain tools for agent use */
+	tools: (Tool | DynamicStructuredTool)[];
+	/**
+	 * Helper to check if an error is an approval request
+	 */
+	isApprovalRequired: (error: any) => error is ApprovalRequiredException;
+	/**
+	 * Helper to resume after approval
+	 */
+	resumeWithApproval: (executionId: string, approved: boolean, reason?: string) => Promise<any>;
+}
+
+/**
+ * Creates LangChain tools from ATP server with LangGraph interrupt support
+ *
+ * Example usage with LangGraph:
+ * ```typescript
+ * import { StateGraph } from "@langchain/langgraph";
+ * import { MemorySaver } from "@langchain/langgraph";
+ * import { ChatOpenAI } from "@langchain/openai";
+ *
+ * const llm = new ChatOpenAI({ modelName: "gpt-4" });
+ * const { client, tools, isApprovalRequired, resumeWithApproval } = await createATPTools({
+ *   serverUrl: 'http://localhost:3333',
+ *   headers: { Authorization: 'Bearer test-key' }, // Optional
+ *   llm,
+ * });
+ *
+ * // Use tools in LangGraph agent
+ * const graph = new StateGraph({...})
+ *   .addNode("agent", agentNode)
+ *   .addNode("approval", async (state) => {
+ *     // Human reviews state.approvalRequest
+ *     return interrupt({ value: state.approvalRequest });
+ *   });
+ *
+ * const checkpointer = new MemorySaver();
+ * const app = graph.compile({
+ *   checkpointer,
+ *   interruptBefore: ["approval"]
+ * });
+ * ```
+ */
+export async function createATPTools(options: CreateATPToolsOptions): Promise<ATPToolsResult> {
+	const { serverUrl, defaultExecutionConfig, ...clientOptions } = options;
+
+	const client = new LangGraphATPClient({
+		serverUrl,
+		...clientOptions,
+	});
+
+	await client.connect();
+
+	const atpTools = createToolsFromATPClient(client.getUnderlyingClient());
+
+	const tools = atpTools.map((atpTool: ATPTool) => {
+		if (atpTool.name === ToolNames.EXECUTE_CODE) {
+			class ATPExecuteTool extends Tool {
+				name = `atp_${atpTool.name}`;
+				description = atpTool.description || 'Execute TypeScript code in ATP sandbox';
+
+				async _call(input: string): Promise<string> {
+					try {
+						let code: string;
+						try {
+							const parsed = JSON.parse(input);
+							code = parsed.code || input;
+						} catch {
+							code = input;
+						}
+
+						const result = await client.execute(code, defaultExecutionConfig);
+
+						if (result.result.status === ExecutionStatus.COMPLETED) {
+							return JSON.stringify(
+								{
+									success: true,
+									result: result.result.result,
+									stats: result.result.stats,
+								},
+								null,
+								2
+							);
+						} else if (result.result.status === ExecutionStatus.FAILED) {
+							return JSON.stringify(
+								{
+									success: false,
+									error: result.result.error,
+									stats: result.result.stats,
+								},
+								null,
+								2
+							);
+						} else {
+							return JSON.stringify(
+								{
+									success: false,
+									error: 'Execution in unexpected state: ' + result.result.status,
+								},
+								null,
+								2
+							);
+						}
+					} catch (error: any) {
+						if (error instanceof ApprovalRequiredException) {
+							throw error;
+						}
+						return JSON.stringify(
+							{
+								success: false,
+								error: error.message || 'Unknown error',
+							},
+							null,
+							2
+						);
+					}
+				}
+			}
+
+			return new ATPExecuteTool();
+		}
+
+		return new DynamicStructuredTool({
+			name: `atp_${atpTool.name}`,
+			description: atpTool.description || '',
+			schema: atpTool.zodSchema || (atpTool.inputSchema as JSONSchema),
+			func: async (input: any) => {
+				try {
+					const result = await atpTool.func(input);
+					return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+				} catch (error: any) {
+					return JSON.stringify(
+						{
+							success: false,
+							error: error.message,
+						},
+						null,
+						2
+					);
+				}
+			},
+		});
+	});
+
+	return {
+		client,
+		tools,
+		isApprovalRequired: (error: any): error is ApprovalRequiredException => {
+			return error instanceof ApprovalRequiredException;
+		},
+		resumeWithApproval: async (executionId: string, approved: boolean, reason?: string) => {
+			return await client.resumeWithApproval(executionId, approved, reason);
+		},
+	};
+}
+
+/**
+ * Helper to create a simple ATP tool for existing LangGraph agents
+ *
+ * This creates a single tool that can execute ATP code. For more control,
+ * use createATPTools() directly.
+ */
+export async function createSimpleATPTool(
+	serverUrl: string,
+	llm: any,
+	headers?: Record<string, string>
+): Promise<Tool | DynamicStructuredTool> {
+	const result = await createATPTools({
+		serverUrl,
+		headers,
+		llm,
+	});
+	const tool = result.tools.find((t) => t.name === `atp_${ToolNames.EXECUTE_CODE}`);
+	if (!tool) {
+		throw new Error('Failed to create ATP execute_code tool');
+	}
+	return tool;
+}

package/src/node.ts

@@ -0,0 +1,60 @@
+import { AgentToolProtocolClient } from '@mondaydotcomorg/atp-client';
+import { ExecutionStatus } from '@mondaydotcomorg/atp-protocol';
+
+/**
+ * LangGraph-compatible node for ATP execution
+ */
+export class ATPExecutionNode {
+	private client: AgentToolProtocolClient;
+
+	constructor(client: AgentToolProtocolClient) {
+		this.client = client;
+	}
+
+	/**
+	 * Execute code from the state and update the state with results
+	 */
+	async execute(state: { code?: string; messages?: any[]; [key: string]: any }): Promise<any> {
+		if (!state.code) {
+			throw new Error('No code provided in state');
+		}
+
+		const result = await this.client.execute(state.code);
+
+		return {
+			...state,
+			executionResult: result,
+			lastExecutionStatus: result.status,
+			lastExecutionOutput:
+				result.status === ExecutionStatus.COMPLETED ? result.result : result.error,
+		};
+	}
+
+	/**
+	 * Create a function suitable for LangGraph node
+	 */
+	asFunction() {
+		return this.execute.bind(this);
+	}
+}
+
+/**
+ * Helper to create a simple ATP execution node function
+ */
+export function createATPNode(client: AgentToolProtocolClient) {
+	return async (state: any) => {
+		if (!state.code) {
+			throw new Error('No code provided in state');
+		}
+
+		const result = await client.execute(state.code);
+
+		return {
+			...state,
+			executionResult: result,
+			lastExecutionStatus: result.status,
+			lastExecutionOutput:
+				result.status === ExecutionStatus.COMPLETED ? result.result : result.error,
+		};
+	};
+}