@loopman/langchain-sdk 1.0.9 → 1.8.0

package/dist/langgraph/loopman-context-node.js

@@ -0,0 +1,131 @@
+/**
+ * Loopman Context Enrichment Node for LangGraph
+ *
+ * This node fetches validation guidelines and historical decision context
+ * from Loopman and adds them to the graph state.
+ */
+import { LoopmanService } from "../services/loopman.service";
+/**
+ * Factory function to create a Loopman context enrichment node
+ *
+ * This node fetches validation guidelines and historical decision context
+ * from Loopman and adds them to the graph state. This enriched context
+ * can then be used by agents to make better-informed decisions.
+ *
+ * **Works with any state**: This node only adds `guidelines` and `decisionContext`
+ * to your state. It doesn't require `LoopmanGraphState` - you can use your own
+ * custom state with any fields you want!
+ *
+ * @example With LoopmanGraphState
+ * ```typescript
+ * import { createLoopmanContextNode, LoopmanGraphState } from "loopman-langchain-sdk";
+ *
+ * const contextNode = createLoopmanContextNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ *   category: "email", // Optional category filter
+ * });
+ *
+ * const workflow = new StateGraph(LoopmanGraphState)
+ *   .addNode("load_context", contextNode)
+ *   .addNode("agent", agentNode)
+ *   .addEdge(START, "load_context")
+ *   .addEdge("load_context", "agent");
+ * ```
+ *
+ * @example With custom state
+ * ```typescript
+ * const MyCustomState = Annotation.Root({
+ *   messages: Annotation<BaseMessage[]>({ ... }),
+ *   myCustomField: Annotation<string>({ ... }),
+ *   guidelines: Annotation<LoopmanGuideline[]>({ ... }), // Add Loopman fields
+ *   decisionContext: Annotation<LoopmanDecision[]>({ ... }), // to your state
+ * });
+ *
+ * const contextNode = createLoopmanContextNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ * });
+ *
+ * const workflow = new StateGraph(MyCustomState)
+ *   .addNode("load_context", contextNode) // Works with custom state!
+ *   .addNode("agent", agentNode);
+ * ```
+ */
+export function createLoopmanContextNode(config) {
+    const loopmanService = new LoopmanService({
+        apiKey: config.apiKey,
+        workflowId: config.workflowId,
+        executionId: config.executionId || `exec-${Date.now()}`,
+        debug: config.debug,
+    });
+    const includeGuidelines = config.includeGuidelines ?? true;
+    const includeDecisionHistory = config.includeDecisionHistory ?? true;
+    const debug = config.debug ?? false;
+    const logger = loopmanService.logger;
+    return async (state) => {
+        logger.debug("[LoopmanContextNode] Loading context...");
+        const updates = {};
+        // Fetch guidelines if requested
+        if (includeGuidelines) {
+            try {
+                logger.debug(`[LoopmanContextNode] Fetching guidelines (category: ${config.category || "all"})`);
+                const response = await loopmanService.getGuidelines(config.category || undefined);
+                // Convert API response to graph state format (lowercase severity)
+                updates.guidelines = response.guidelines.map((g) => ({
+                    ruleId: g.ruleId,
+                    description: g.description,
+                    category: g.category,
+                    severity: g.severity.toLowerCase(),
+                }));
+                logger.debug(`[LoopmanContextNode] Loaded ${response.guidelines.length} guideline(s)`, {
+                    severities: response.guidelines.length > 0
+                        ? response.guidelines.map((g) => g.severity)
+                        : [],
+                });
+            }
+            catch (error) {
+                if (debug) {
+                    logger.error(`[LoopmanContextNode] Failed to fetch guidelines: ${error.message}`);
+                }
+                // Continue execution with empty guidelines
+                updates.guidelines = [];
+            }
+        }
+        // Fetch decision context if requested
+        // Note: Decision context requires a taskId to fetch decisions from that task
+        // If you need decision history, pass the taskId in the state
+        if (includeDecisionHistory) {
+            try {
+                logger.debug(`[LoopmanContextNode] Decision history requested (executionId: ${config.executionId || "auto-generated"})`);
+                // Check if state contains a taskId to fetch decisions from
+                const taskId = state.taskId;
+                if (taskId) {
+                    logger.debug(`[LoopmanContextNode] Fetching task ${taskId} to get decisions`);
+                    const task = await loopmanService.getTask(taskId);
+                    const response = loopmanService.getDecisionContextFromTask(task);
+                    updates.decisionContext = response.decisions;
+                    logger.debug(`[LoopmanContextNode] Loaded ${response.decisions.length} decision(s) from task ${taskId}`, {
+                        latest: response.decisions.length > 0
+                            ? response.decisions[response.decisions.length - 1]
+                            : null,
+                    });
+                }
+                else {
+                    logger.debug("[LoopmanContextNode] No taskId in state - skipping decision history");
+                    updates.decisionContext = [];
+                }
+            }
+            catch (error) {
+                if (debug) {
+                    logger.error(`[LoopmanContextNode] Failed to fetch decision context: ${error.message}`);
+                }
+                // Continue execution with empty decision context
+                updates.decisionContext = [];
+            }
+        }
+        logger.debug("[LoopmanContextNode] Context loaded successfully");
+        return updates;
+    };
+}
+//# sourceMappingURL=loopman-context-node.js.map

package/dist/langgraph/loopman-context-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopman-context-node.js","sourceRoot":"","sources":["../../src/langgraph/loopman-context-node.ts"],"names":[],"mappings":"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"}

package/dist/langgraph/loopman-validation-node.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Loopman Validation Node for LangGraph
+ *
+ * This node handles human-in-the-loop validation by:
+ * 1. Extracting tool calls from agent messages
+ * 2. Creating validation tasks in Loopman
+ * 3. Polling for human decisions
+ * 4. Enriching state with guidelines and decision context
+ */
+/**
+ * Configuration for Loopman validation node
+ */
+export interface LoopmanValidationNodeConfig {
+    /** Loopman API key for authentication */
+    apiKey: string;
+    /** Workflow identifier */
+    workflowId: string;
+    /** Execution identifier (auto-generated if not provided) */
+    executionId?: string;
+    /** Category to filter guidelines (optional) */
+    category?: string;
+    /** Polling timeout in milliseconds (default: 5 minutes) */
+    timeout?: number;
+    /** Polling interval in milliseconds (default: 5 seconds) */
+    pollingInterval?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom message to display when creating task */
+    taskMessage?: string;
+    /** Custom function to extract tool call from message */
+    extractToolCall?: (messages: any[]) => {
+        name: string;
+        args: any;
+        id: string;
+    } | null;
+}
+/**
+ * Creates a Loopman validation node for LangGraph
+ *
+ * This node:
+ * 1. Extracts the tool call from the last AI message
+ * 2. Creates a Loopman task for human validation
+ * 3. Polls until human decision is received
+ * 4. Automatically enriches state with guidelines and decisionContext
+ *
+ * **Works with any state**: This node reads `messages` and `requiresValidation`
+ * from the state, and updates it with `loopmanTaskId`, `loopmanTaskStatus`,
+ * `guidelines`, and `decisionContext`. You can use your own custom state schema!
+ *
+ * **Context Enrichment**: After validation, this node automatically fetches
+ * and adds `guidelines` and `decisionContext` to the state, making them
+ * available for the agent on retry (NEEDS_CHANGES) or subsequent executions.
+ *
+ * @example With LoopmanGraphState
+ * ```typescript
+ * import { createLoopmanValidationNode, LoopmanGraphState } from "loopman-langchain-sdk";
+ *
+ * const loopmanNode = createLoopmanValidationNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ *   executionId: `exec-${Date.now()}`,
+ *   timeout: 5 * 60 * 1000,
+ *   pollingInterval: 5000,
+ *   debug: true,
+ *   taskMessage: "Please review this action"
+ * });
+ *
+ * workflow.addNode("loopman_validation", loopmanNode);
+ * ```
+ *
+ * @example With custom state
+ * ```typescript
+ * const MyCustomState = Annotation.Root({
+ *   messages: Annotation<BaseMessage[]>({ ... }),
+ *   requiresValidation: Annotation<boolean>({ ... }),
+ *   loopmanTaskId: Annotation<string | null>({ ... }),
+ *   loopmanTaskStatus: Annotation<string | null>({ ... }),
+ *   guidelines: Annotation<LoopmanGuideline[]>({ ... }),
+ *   decisionContext: Annotation<LoopmanDecision[]>({ ... }),
+ *   // ... your custom fields
+ * });
+ *
+ * const loopmanNode = createLoopmanValidationNode({ ... });
+ * const workflow = new StateGraph(MyCustomState)
+ *   .addNode("validation", loopmanNode); // Works!
+ * ```
+ */
+export declare function createLoopmanValidationNode(config: LoopmanValidationNodeConfig): (state: any) => Promise<any>;
+//# sourceMappingURL=loopman-validation-node.d.ts.map

package/dist/langgraph/loopman-validation-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopman-validation-node.d.ts","sourceRoot":"","sources":["../../src/langgraph/loopman-validation-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK;QACrC,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,GAAG,CAAC;QACV,EAAE,EAAE,MAAM,CAAC;KACZ,GAAG,IAAI,CAAC;CACV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,2BAA2B,IAYrB,OAAO,GAAG,kBAkLzB"}

package/dist/langgraph/loopman-validation-node.js

@@ -0,0 +1,297 @@
+/**
+ * Loopman Validation Node for LangGraph
+ *
+ * This node handles human-in-the-loop validation by:
+ * 1. Extracting tool calls from agent messages
+ * 2. Creating validation tasks in Loopman
+ * 3. Polling for human decisions
+ * 4. Enriching state with guidelines and decision context
+ */
+import { ToolMessage } from "@langchain/core/messages";
+import { LoopmanService } from "../services/loopman.service";
+import { createLoopmanContextNode } from "./loopman-context-node";
+/**
+ * Creates a Loopman validation node for LangGraph
+ *
+ * This node:
+ * 1. Extracts the tool call from the last AI message
+ * 2. Creates a Loopman task for human validation
+ * 3. Polls until human decision is received
+ * 4. Automatically enriches state with guidelines and decisionContext
+ *
+ * **Works with any state**: This node reads `messages` and `requiresValidation`
+ * from the state, and updates it with `loopmanTaskId`, `loopmanTaskStatus`,
+ * `guidelines`, and `decisionContext`. You can use your own custom state schema!
+ *
+ * **Context Enrichment**: After validation, this node automatically fetches
+ * and adds `guidelines` and `decisionContext` to the state, making them
+ * available for the agent on retry (NEEDS_CHANGES) or subsequent executions.
+ *
+ * @example With LoopmanGraphState
+ * ```typescript
+ * import { createLoopmanValidationNode, LoopmanGraphState } from "loopman-langchain-sdk";
+ *
+ * const loopmanNode = createLoopmanValidationNode({
+ *   apiKey: process.env.LOOPMAN_API_KEY!,
+ *   workflowId: "my-workflow",
+ *   executionId: `exec-${Date.now()}`,
+ *   timeout: 5 * 60 * 1000,
+ *   pollingInterval: 5000,
+ *   debug: true,
+ *   taskMessage: "Please review this action"
+ * });
+ *
+ * workflow.addNode("loopman_validation", loopmanNode);
+ * ```
+ *
+ * @example With custom state
+ * ```typescript
+ * const MyCustomState = Annotation.Root({
+ *   messages: Annotation<BaseMessage[]>({ ... }),
+ *   requiresValidation: Annotation<boolean>({ ... }),
+ *   loopmanTaskId: Annotation<string | null>({ ... }),
+ *   loopmanTaskStatus: Annotation<string | null>({ ... }),
+ *   guidelines: Annotation<LoopmanGuideline[]>({ ... }),
+ *   decisionContext: Annotation<LoopmanDecision[]>({ ... }),
+ *   // ... your custom fields
+ * });
+ *
+ * const loopmanNode = createLoopmanValidationNode({ ... });
+ * const workflow = new StateGraph(MyCustomState)
+ *   .addNode("validation", loopmanNode); // Works!
+ * ```
+ */
+export function createLoopmanValidationNode(config) {
+    // Create LoopmanService instance with the provided configuration
+    const loopmanService = new LoopmanService({
+        apiKey: config.apiKey,
+        workflowId: config.workflowId,
+        executionId: config.executionId || `exec-${Date.now()}`,
+        timeout: config.timeout,
+        pollingInterval: config.pollingInterval,
+        debug: config.debug,
+    });
+    return async (state) => {
+        const { messages, requiresValidation, loopmanTaskId } = state;
+        const { debug } = config;
+        const logger = loopmanService.logger;
+        // Skip if validation not required
+        if (!requiresValidation) {
+            logger.debug("[LoopmanNode] Validation not required, skipping");
+            return {};
+        }
+        // Extract tool call from last message
+        const lastMessage = messages[messages.length - 1];
+        const toolCall = config.extractToolCall
+            ? config.extractToolCall(messages)
+            : extractDefaultToolCall(lastMessage);
+        if (!toolCall) {
+            logger.warn("[LoopmanNode] No tool call found, skipping");
+            return { requiresValidation: false };
+        }
+        // Step 1: Check if we're retrying an existing task (NEEDS_CHANGES scenario)
+        const isRetry = !!loopmanTaskId;
+        if (isRetry) {
+            logger.debug("[LoopmanNode] Updating existing validation task", {
+                taskId: loopmanTaskId,
+                tool: toolCall.name,
+                args: toolCall.args,
+            });
+        }
+        else {
+            logger.debug("[LoopmanNode] Creating validation task", {
+                tool: toolCall.name,
+                args: toolCall.args,
+            });
+        }
+        // Step 2: Create or update task in Loopman
+        const taskMessage = config.taskMessage || `Validation required for tool: ${toolCall.name}`;
+        try {
+            const task = await loopmanService.createTaskForValidation(toolCall.name, toolCall.args, taskMessage, toolCall.id, undefined, // businessContext
+            undefined, // parentTaskId
+            undefined, // proposedDecision
+            undefined, // decisionReasoning
+            isRetry ? loopmanTaskId : undefined // existingTaskId for retry
+            );
+            logger.debug("[LoopmanNode] Task created, polling for human decision", {
+                taskId: task.id,
+            });
+            // Step 2: Poll for human decision
+            const pollingResult = await loopmanService.polling.waitForDecision(loopmanService.getPollingOptions(task.id));
+            logger.debug("[LoopmanNode] Polling result", {
+                status: pollingResult.status,
+            });
+            // Step 3: Handle timeout/abort
+            if (pollingResult.status === "TIMEOUT") {
+                return {
+                    loopmanTaskId: task.id,
+                    loopmanTaskStatus: "TIMEOUT",
+                    requiresValidation: false,
+                    messages: [
+                        new ToolMessage({
+                            content: "Human validation timeout - task was not reviewed in time",
+                            tool_call_id: toolCall.id,
+                        }),
+                    ],
+                };
+            }
+            if (pollingResult.status === "ABORTED") {
+                return {
+                    loopmanTaskId: task.id,
+                    loopmanTaskStatus: "ABORTED",
+                    requiresValidation: false,
+                };
+            }
+            // Step 4: Get final task with decision
+            const finalTask = await loopmanService.getTask(task.id);
+            const latestDecision = finalTask.decisions?.[0];
+            const feedback = latestDecision?.comment || null;
+            if (debug) {
+                logger.debug("[LoopmanNode] Human decision received", {
+                    status: finalTask.status,
+                    feedback,
+                });
+            }
+            // Step 5: Fetch enriched context only if NEEDS_CHANGES
+            // This optimizes API calls by loading guidelines and decisions only when needed
+            let contextUpdates = {};
+            if (finalTask.status === "NEEDS_CHANGES") {
+                logger.debug("[LoopmanNode] Status is NEEDS_CHANGES - loading context for retry");
+                try {
+                    // Use the context node to load guidelines and decisions
+                    const contextNode = createLoopmanContextNode({
+                        apiKey: config.apiKey,
+                        workflowId: config.workflowId,
+                        executionId: config.executionId,
+                        category: config.category,
+                        includeGuidelines: true,
+                        includeDecisionHistory: true,
+                        debug,
+                    });
+                    // Add taskId to state so context node can fetch decisions
+                    const stateWithTaskId = { ...state, taskId: finalTask.id };
+                    contextUpdates = await contextNode(stateWithTaskId);
+                    if (debug) {
+                        const guidelinesCount = contextUpdates.guidelines?.length || 0;
+                        const decisionsCount = contextUpdates.decisionContext?.length || 0;
+                        logger.debug("[LoopmanNode] Context loaded", {
+                            guidelinesCount,
+                            decisionsCount,
+                        });
+                    }
+                }
+                catch (error) {
+                    logger.warn(`[LoopmanNode] Failed to load context: ${error.message} (continuing without)`);
+                    // Continue without context if loading fails
+                    contextUpdates = {};
+                }
+            }
+            else if (debug) {
+                logger.debug(`[LoopmanNode] Status is ${finalTask.status} - skipping context loading`);
+            }
+            // Step 6: Return state update with enriched context (only if NEEDS_CHANGES)
+            return {
+                loopmanTaskId: task.id,
+                loopmanTaskStatus: finalTask.status,
+                requiresValidation: false, // Reset flag
+                ...contextUpdates, // Add guidelines and decisionContext if loaded
+                messages: buildDecisionMessages(finalTask.status, feedback, toolCall.id),
+            };
+        }
+        catch (error) {
+            if (debug) {
+                logger.error("[LoopmanNode] Error during validation", error.message);
+            }
+            return {
+                loopmanTaskStatus: "ERROR",
+                requiresValidation: false,
+                messages: [
+                    new ToolMessage({
+                        content: `Error during validation: ${error.message}`,
+                        tool_call_id: toolCall.id,
+                    }),
+                ],
+            };
+        }
+    };
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Extracts tool call from a message
+ */
+function extractDefaultToolCall(message) {
+    if (!message)
+        return null;
+    // Handle AIMessage with tool_calls
+    if (message.tool_calls && message.tool_calls.length > 0) {
+        const tc = message.tool_calls[0];
+        return {
+            name: tc.name,
+            args: tc.args,
+            id: tc.id || `call_${Date.now()}`,
+        };
+    }
+    // Handle raw message with toolCalls
+    if (message.toolCalls && message.toolCalls.length > 0) {
+        const tc = message.toolCalls[0];
+        return {
+            name: tc.name,
+            args: tc.args,
+            id: tc.id || `call_${Date.now()}`,
+        };
+    }
+    return null;
+}
+/**
+ * Builds messages to add to state based on decision
+ */
+function buildDecisionMessages(status, feedback, toolCallId) {
+    switch (status) {
+        case "APPROVED":
+            return [
+                new ToolMessage({
+                    content: feedback
+                        ? `Approved by human reviewer. Feedback: "${feedback}"`
+                        : "Approved by human reviewer. Proceed with execution.",
+                    tool_call_id: toolCallId,
+                }),
+            ];
+        case "REJECTED":
+            return [
+                new ToolMessage({
+                    content: feedback
+                        ? `Rejected by human reviewer. Reason: "${feedback}"`
+                        : "Rejected by human reviewer. Action cannot be executed.",
+                    tool_call_id: toolCallId,
+                }),
+            ];
+        case "NEEDS_CHANGES":
+            return [
+                new ToolMessage({
+                    content: feedback
+                        ? `Changes requested by human reviewer: "${feedback}"`
+                        : "Changes requested by human reviewer. Please revise your approach.",
+                    tool_call_id: toolCallId,
+                }),
+            ];
+        case "TIMEOUT":
+            return [
+                new ToolMessage({
+                    content: "Human validation timeout - task was not reviewed in time",
+                    tool_call_id: toolCallId,
+                }),
+            ];
+        case "PENDING":
+        case "ERROR":
+        default:
+            return [
+                new ToolMessage({
+                    content: `Validation status: ${status}`,
+                    tool_call_id: toolCallId,
+                }),
+            ];
+    }
+}
+//# sourceMappingURL=loopman-validation-node.js.map

package/dist/langgraph/loopman-validation-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopman-validation-node.js","sourceRoot":"","sources":["../../src/langgraph/loopman-validation-node.ts"],"names":[],"mappings":"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"}

package/dist/langgraph/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Common types and state definition for LangGraph integration
+ */
+/**
+ * Guideline from Loopman API
+ */
+export interface LoopmanGuideline {
+    ruleId: string;
+    description: string;
+    category?: string | null;
+    severity: "critical" | "major" | "minor";
+}
+/**
+ * Decision from Loopman decision context
+ */
+export interface LoopmanDecision {
+    date: string;
+    userType: "USER" | "SYSTEM";
+    status: "PENDING" | "APPROVED" | "REJECTED" | "NEEDS_CHANGES";
+    comment?: string;
+    firstName?: string;
+    lastName?: string;
+}
+/**
+ * State definition for LangGraph with Loopman integration
+ *
+ * This state includes all fields needed for Loopman's Human-in-the-Loop
+ * validation and context enrichment features. You can also use your own
+ * custom state by including only the fields you need.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const workflow = new StateGraph(LoopmanGraphState)
+ *   .addNode("agent", agentNode)
+ *   .addNode("validation", validationNode);
+ * ```
+ *
+ * @example Custom state
+ * ```typescript
+ * const MyState = Annotation.Root({
+ *   messages: Annotation<BaseMessage[]>({ ... }),
+ *   myCustomField: Annotation<string>({ ... }),
+ *   // Add only Loopman fields you need:
+ *   guidelines: Annotation<LoopmanGuideline[]>({ ... }),
+ *   requiresValidation: Annotation<boolean>({ ... }),
+ * });
+ * ```
+ */
+export declare const LoopmanGraphState: import("@langchain/langgraph").AnnotationRoot<{
+    /**
+     * Messages in the conversation
+     */
+    messages: import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
+    /**
+     * ID of the Loopman task awaiting validation
+     */
+    loopmanTaskId: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+    /**
+     * Status of the Loopman task (APPROVED, REJECTED, NEEDS_CHANGES, etc.)
+     */
+    loopmanTaskStatus: import("@langchain/langgraph").BinaryOperatorAggregate<string | null, string | null>;
+    /**
+     * Flag indicating if the current action requires validation
+     */
+    requiresValidation: import("@langchain/langgraph").BinaryOperatorAggregate<boolean, boolean>;
+    /**
+     * Validation guidelines for the workflow
+     */
+    guidelines: import("@langchain/langgraph").BinaryOperatorAggregate<LoopmanGuideline[], LoopmanGuideline[]>;
+    /**
+     * Historical decision context from previous human reviews
+     */
+    decisionContext: import("@langchain/langgraph").BinaryOperatorAggregate<LoopmanDecision[], LoopmanDecision[]>;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/langgraph/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/langgraph/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,eAAe,CAAC;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;;IAMH;;OAEG;;IAMH;;OAEG;;IAMH;;OAEG;;IAMH;;OAEG;;IAMH;;OAEG;;EAKH,CAAC"}