@hazeljs/agent 0.2.0-alpha.1

package/dist/executor/tool.executor.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * Tool Executor
+ * Executes tools with approval workflow and error handling
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolExecutor = void 0;
+const crypto_1 = require("crypto");
+const tool_types_1 = require("../types/tool.types");
+const event_types_1 = require("../types/event.types");
+/**
+ * Tool Executor
+ * Handles tool execution with approval and retry logic
+ */
+class ToolExecutor {
+    constructor(eventEmitter, guardrailsService) {
+        this.eventEmitter = eventEmitter;
+        this.guardrailsService = guardrailsService;
+        this.pendingApprovals = new Map();
+        this.executionContexts = new Map();
+    }
+    /**
+     * Execute a tool
+     */
+    async execute(tool, input, agentId, sessionId, userId) {
+        const executionId = (0, crypto_1.randomUUID)();
+        const startTime = Date.now();
+        const context = {
+            executionId,
+            toolName: tool.name,
+            agentId,
+            sessionId,
+            userId,
+            input,
+            status: tool_types_1.ToolExecutionStatus.PENDING,
+            startedAt: new Date(),
+        };
+        this.executionContexts.set(executionId, context);
+        this.emitEvent(event_types_1.AgentEventType.TOOL_EXECUTION_STARTED, {
+            toolName: tool.name,
+            input,
+        });
+        try {
+            if (this.guardrailsService) {
+                const inputResult = this.guardrailsService.checkInput(input);
+                if (!inputResult.allowed) {
+                    context.status = tool_types_1.ToolExecutionStatus.FAILED;
+                    context.completedAt = new Date();
+                    context.duration = Date.now() - startTime;
+                    this.emitEvent(event_types_1.AgentEventType.TOOL_EXECUTION_FAILED, {
+                        toolName: tool.name,
+                        input,
+                        error: inputResult.blockedReason ?? 'Input blocked by guardrails',
+                        duration: context.duration,
+                    });
+                    return {
+                        success: false,
+                        error: new Error(inputResult.blockedReason ?? 'Input blocked by guardrails'),
+                        duration: context.duration,
+                    };
+                }
+                if (inputResult.modified !== undefined) {
+                    Object.assign(input, inputResult.modified);
+                }
+            }
+            if (tool.requiresApproval) {
+                const approved = await this.requestApproval(tool, input, agentId, executionId);
+                if (!approved) {
+                    context.status = tool_types_1.ToolExecutionStatus.REJECTED;
+                    this.emitEvent(event_types_1.AgentEventType.TOOL_APPROVAL_DENIED, {
+                        requestId: executionId,
+                        toolName: tool.name,
+                        input,
+                    });
+                    return {
+                        success: false,
+                        error: new Error('Tool execution rejected by user'),
+                        duration: Date.now() - startTime,
+                    };
+                }
+                context.status = tool_types_1.ToolExecutionStatus.APPROVED;
+                this.emitEvent(event_types_1.AgentEventType.TOOL_APPROVAL_GRANTED, {
+                    requestId: executionId,
+                    toolName: tool.name,
+                    input,
+                });
+            }
+            context.status = tool_types_1.ToolExecutionStatus.EXECUTING;
+            const result = await this.executeWithRetry(tool, input, tool.retries || 0);
+            context.status = tool_types_1.ToolExecutionStatus.COMPLETED;
+            context.completedAt = new Date();
+            context.duration = Date.now() - startTime;
+            this.emitEvent(event_types_1.AgentEventType.TOOL_EXECUTION_COMPLETED, {
+                toolName: tool.name,
+                input,
+                output: result,
+                duration: context.duration,
+            });
+            return {
+                success: true,
+                output: result,
+                duration: context.duration,
+            };
+        }
+        catch (error) {
+            context.status = tool_types_1.ToolExecutionStatus.FAILED;
+            context.completedAt = new Date();
+            context.duration = Date.now() - startTime;
+            this.emitEvent(event_types_1.AgentEventType.TOOL_EXECUTION_FAILED, {
+                toolName: tool.name,
+                input,
+                error: error.message,
+                duration: context.duration,
+            });
+            return {
+                success: false,
+                error: error,
+                duration: context.duration,
+            };
+        }
+        finally {
+            this.executionContexts.delete(executionId);
+        }
+    }
+    /**
+     * Execute tool with retry logic
+     */
+    async executeWithRetry(tool, input, maxRetries) {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const timeout = tool.timeout || 30000;
+                const result = await this.executeWithTimeout(tool, input, timeout);
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxRetries) {
+                    await this.delay(Math.pow(2, attempt) * 1000);
+                }
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Execute tool with timeout
+     */
+    async executeWithTimeout(tool, input, timeout) {
+        let timeoutId;
+        try {
+            const result = await Promise.race([
+                tool.method.call(tool.target, input),
+                new Promise((_, reject) => {
+                    timeoutId = setTimeout(() => reject(new Error(`Tool execution timeout after ${timeout}ms`)), timeout);
+                }),
+            ]);
+            if (this.guardrailsService && result !== undefined && result !== null) {
+                const outputResult = this.guardrailsService.checkOutput(result);
+                if (!outputResult.allowed) {
+                    throw new Error(outputResult.blockedReason ?? 'Output blocked by guardrails');
+                }
+                return outputResult.modified ?? result;
+            }
+            return result;
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    /**
+     * Request approval for tool execution
+     */
+    async requestApproval(tool, input, agentId, executionId) {
+        const requestId = (0, crypto_1.randomUUID)();
+        const request = {
+            requestId,
+            executionId,
+            toolName: tool.name,
+            agentId,
+            input,
+            requestedAt: new Date(),
+            expiresAt: new Date(Date.now() + 300000),
+        };
+        this.pendingApprovals.set(requestId, request);
+        this.emitEvent(event_types_1.AgentEventType.TOOL_APPROVAL_REQUESTED, {
+            requestId,
+            toolName: tool.name,
+            input,
+        });
+        return new Promise((resolve) => {
+            const checkInterval = setInterval(() => {
+                const req = this.pendingApprovals.get(requestId);
+                if (!req) {
+                    // Request was removed unexpectedly
+                    clearInterval(checkInterval);
+                    resolve(false);
+                    return;
+                }
+                // Check if approved
+                if (req.status === 'approved') {
+                    this.pendingApprovals.delete(requestId);
+                    clearInterval(checkInterval);
+                    resolve(true);
+                    return;
+                }
+                // Check if rejected
+                if (req.status === 'rejected') {
+                    this.pendingApprovals.delete(requestId);
+                    clearInterval(checkInterval);
+                    resolve(false);
+                    return;
+                }
+                // Check if expired
+                if (req.expiresAt && req.expiresAt < new Date()) {
+                    this.pendingApprovals.delete(requestId);
+                    clearInterval(checkInterval);
+                    resolve(false);
+                }
+            }, 1000);
+        });
+    }
+    /**
+     * Approve a tool execution
+     */
+    approveExecution(requestId, approvedBy) {
+        const request = this.pendingApprovals.get(requestId);
+        if (request) {
+            request.status =
+                'approved';
+            request.approvedBy = approvedBy;
+        }
+    }
+    /**
+     * Reject a tool execution
+     */
+    rejectExecution(requestId) {
+        const request = this.pendingApprovals.get(requestId);
+        if (request) {
+            request.status = 'rejected';
+        }
+    }
+    /**
+     * Get pending approval requests
+     */
+    getPendingApprovals() {
+        return Array.from(this.pendingApprovals.values());
+    }
+    /**
+     * Emit event
+     */
+    emitEvent(type, data) {
+        if (this.eventEmitter) {
+            this.eventEmitter(type, data);
+        }
+    }
+    /**
+     * Delay helper
+     */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.ToolExecutor = ToolExecutor;
+//# sourceMappingURL=tool.executor.js.map

package/dist/executor/tool.executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.executor.js","sourceRoot":"","sources":["../../src/executor/tool.executor.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,mCAAoC;AACpC,oDAM6B;AAC7B,sDAAsD;AAGtD;;;GAGG;AACH,MAAa,YAAY;IAIvB,YACU,YAA4D,EAC5D,iBAAsC;QADtC,iBAAY,GAAZ,YAAY,CAAgD;QAC5D,sBAAiB,GAAjB,iBAAiB,CAAqB;QALxC,qBAAgB,GAAqC,IAAI,GAAG,EAAE,CAAC;QAC/D,sBAAiB,GAAsC,IAAI,GAAG,EAAE,CAAC;IAKtE,CAAC;IAEJ;;OAEG;IACH,KAAK,CAAC,OAAO,CACX,IAAkB,EAClB,KAA8B,EAC9B,OAAe,EACf,SAAiB,EACjB,MAAe;QAEf,MAAM,WAAW,GAAG,IAAA,mBAAU,GAAE,CAAC;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,MAAM,OAAO,GAAyB;YACpC,WAAW;YACX,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,OAAO;YACP,SAAS;YACT,MAAM;YACN,KAAK;YACL,MAAM,EAAE,gCAAmB,CAAC,OAAO;YACnC,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC;QAEF,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAEjD,IAAI,CAAC,SAAS,CAAC,4BAAc,CAAC,sBAAsB,EAAE;YACpD,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,KAAK;SACN,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBAC7D,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;oBACzB,OAAO,CAAC,MAAM,GAAG,gCAAmB,CAAC,MAAM,CAAC;oBAC5C,OAAO,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;oBACjC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;oBAE1C,IAAI,CAAC,SAAS,CAAC,4BAAc,CAAC,qBAAqB,EAAE;wBACnD,QAAQ,EAAE,IAAI,CAAC,IAAI;wBACnB,KAAK;wBACL,KAAK,EAAE,WAAW,CAAC,aAAa,IAAI,6BAA6B;wBACjE,QAAQ,EAAE,OAAO,CAAC,QAAQ;qBAC3B,CAAC,CAAC;oBAEH,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,IAAI,KAAK,CAAC,WAAW,CAAC,aAAa,IAAI,6BAA6B,CAAC;wBAC5E,QAAQ,EAAE,OAAO,CAAC,QAAQ;qBAC3B,CAAC;gBACJ,CAAC;gBACD,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;oBACvC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,QAAmC,CAAC,CAAC;gBACxE,CAAC;YACH,CAAC;YAED,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;gBAE/E,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,OAAO,CAAC,MAAM,GAAG,gCAAmB,CAAC,QAAQ,CAAC;oBAE9C,IAAI,CAAC,SAAS,CAAC,4BAAc,CAAC,oBAAoB,EAAE;wBAClD,SAAS,EAAE,WAAW;wBACtB,QAAQ,EAAE,IAAI,CAAC,IAAI;wBACnB,KAAK;qBACN,CAAC,CAAC;oBAEH,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,IAAI,KAAK,CAAC,iCAAiC,CAAC;wBACnD,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;qBACjC,CAAC;gBACJ,CAAC;gBAED,OAAO,CAAC,MAAM,GAAG,gCAAmB,CAAC,QAAQ,CAAC;gBAC9C,IAAI,CAAC,SAAS,CAAC,4BAAc,CAAC,qBAAqB,EAAE;oBACnD,SAAS,EAAE,WAAW;oBACtB,QAAQ,EAAE,IAAI,CAAC,IAAI;oBACnB,KAAK;iBACN,CAAC,CAAC;YACL,CAAC;YAED,OAAO,CAAC,MAAM,GAAG,gCAAmB,CAAC,SAAS,CAAC;YAE/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;YAE3E,OAAO,CAAC,MAAM,GAAG,gCAAmB,CAAC,SAAS,CAAC;YAC/C,OAAO,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;YACjC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAE1C,IAAI,CAAC,SAAS,CAAC,4BAAc,CAAC,wBAAwB,EAAE;gBACtD,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,KAAK;gBACL,MAAM,EAAE,MAAM;gBACd,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,MAAM;gBACd,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,GAAG,gCAAmB,CAAC,MAAM,CAAC;YAC5C,OAAO,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;YACjC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAE1C,IAAI,CAAC,SAAS,CAAC,4BAAc,CAAC,qBAAqB,EAAE;gBACnD,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,KAAK;gBACL,KAAK,EAAG,KAAe,CAAC,OAAO;gBAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,KAAc;gBACrB,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,gBAAgB,CAC5B,IAAkB,EAClB,KAA8B,EAC9B,UAAkB;QAElB,IAAI,SAA4B,CAAC;QAEjC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YACvD,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;gBACtC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;gBACnE,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS,GAAG,KAAc,CAAC;gBAE3B,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;oBACzB,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;gBAChD,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,SAAS,CAAC;IAClB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,kBAAkB,CAC9B,IAAkB,EAClB,KAA8B,EAC9B,OAAe;QAEf,IAAI,SAAqC,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;gBAChC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC;gBACpC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;oBACxB,SAAS,GAAG,UAAU,CACpB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,OAAO,IAAI,CAAC,CAAC,EACpE,OAAO,CACR,CAAC;gBACJ,CAAC,CAAC;aACH,CAAC,CAAC;YAEH,IAAI,IAAI,CAAC,iBAAiB,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACtE,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,MAAyB,CAAC,CAAC;gBACnF,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;oBAC1B,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,aAAa,IAAI,8BAA8B,CAAC,CAAC;gBAChF,CAAC;gBACD,OAAO,YAAY,CAAC,QAAQ,IAAI,MAAM,CAAC;YACzC,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;gBAAS,CAAC;YACT,IAAI,SAAS,EAAE,CAAC;gBACd,YAAY,CAAC,SAAS,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe,CAC3B,IAAkB,EAClB,KAA8B,EAC9B,OAAe,EACf,WAAmB;QAEnB,MAAM,SAAS,GAAG,IAAA,mBAAU,GAAE,CAAC;QAE/B,MAAM,OAAO,GAAwB;YACnC,SAAS;YACT,WAAW;YACX,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,OAAO;YACP,KAAK;YACL,WAAW,EAAE,IAAI,IAAI,EAAE;YACvB,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;SACzC,CAAC;QAEF,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAE9C,IAAI,CAAC,SAAS,CAAC,4BAAc,CAAC,uBAAuB,EAAE;YACrD,SAAS;YACT,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,KAAK;SACN,CAAC,CAAC;QAEH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,EAAE;gBACrC,MAAM,GAAG,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBAEjD,IAAI,CAAC,GAAG,EAAE,CAAC;oBACT,mCAAmC;oBACnC,aAAa,CAAC,aAAa,CAAC,CAAC;oBAC7B,OAAO,CAAC,KAAK,CAAC,CAAC;oBACf,OAAO;gBACT,CAAC;gBAED,oBAAoB;gBACpB,IAAK,GAAiD,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;oBAC7E,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;oBACxC,aAAa,CAAC,aAAa,CAAC,CAAC;oBAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;oBACd,OAAO;gBACT,CAAC;gBAED,oBAAoB;gBACpB,IAAK,GAAiD,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;oBAC7E,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;oBACxC,aAAa,CAAC,aAAa,CAAC,CAAC;oBAC7B,OAAO,CAAC,KAAK,CAAC,CAAC;oBACf,OAAO;gBACT,CAAC;gBAED,mBAAmB;gBACnB,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;oBAChD,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;oBACxC,aAAa,CAAC,aAAa,CAAC,CAAC;oBAC7B,OAAO,CAAC,KAAK,CAAC,CAAC;gBACjB,CAAC;YACH,CAAC,EAAE,IAAI,CAAC,CAAC;QACX,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,SAAiB,EAAE,UAAkB;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,OAAO,EAAE,CAAC;YACX,OAA0E,CAAC,MAAM;gBAChF,UAAU,CAAC;YACZ,OAAyD,CAAC,UAAU,GAAG,UAAU,CAAC;QACrF,CAAC;IACH,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,SAAiB;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,OAAO,EAAE,CAAC;YACX,OAAqD,CAAC,MAAM,GAAG,UAAU,CAAC;QAC7E,CAAC;IACH,CAAC;IAED;;OAEG;IACH,mBAAmB;QACjB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,IAAoB,EAAE,IAAa;QACnD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF;AApTD,oCAoTC"}

package/dist/graph/agent-graph.d.ts

@@ -0,0 +1,131 @@
+/**
+ * AgentGraph — Multi-Agent Orchestration Graph
+ *
+ * Provides a LangGraph-inspired DAG runtime for orchestrating multiple agents.
+ * Supports sequential pipelines, conditional routing, and parallel fan-out/fan-in.
+ *
+ * @example Sequential pipeline
+ * ```ts
+ * const graph = runtime.createGraph('pipeline')
+ *   .addNode('researcher', { type: 'agent', agentName: 'ResearchAgent' })
+ *   .addNode('writer',     { type: 'agent', agentName: 'WriterAgent' })
+ *   .addEdge('researcher', 'writer')
+ *   .addEdge('writer', END)
+ *   .setEntryPoint('researcher')
+ *   .compile();
+ *
+ * const result = await graph.execute('Write a blog about LLMs');
+ * ```
+ *
+ * @example Conditional routing
+ * ```ts
+ * const graph = runtime.createGraph('router')
+ *   .addNode('classifier', { type: 'agent', agentName: 'ClassifierAgent' })
+ *   .addNode('coder',      { type: 'agent', agentName: 'CoderAgent' })
+ *   .addNode('writer',     { type: 'agent', agentName: 'WriterAgent' })
+ *   .setEntryPoint('classifier')
+ *   .addConditionalEdge('classifier', state => state.data.type === 'code' ? 'coder' : 'writer')
+ *   .addEdge('coder',  END)
+ *   .addEdge('writer', END)
+ *   .compile();
+ * ```
+ *
+ * @example Parallel fan-out / fan-in
+ * ```ts
+ * const graph = runtime.createGraph('parallel')
+ *   .addNode('splitter',    { type: 'function', fn: splitTask })
+ *   .addNode('parallel-1', { type: 'parallel', branches: ['agent-a', 'agent-b'] })
+ *   .addNode('agent-a',    { type: 'agent', agentName: 'AgentA' })
+ *   .addNode('agent-b',    { type: 'agent', agentName: 'AgentB' })
+ *   .addNode('combiner',   { type: 'function', fn: combineResults })
+ *   .addEdge('splitter',   'parallel-1')
+ *   .addEdge('parallel-1', 'combiner')
+ *   .addEdge('combiner',    END)
+ *   .setEntryPoint('splitter')
+ *   .compile();
+ * ```
+ */
+import { GraphNode, GraphNodeConfig, GraphEdge, RouterFunction, GraphExecutionOptions, GraphExecutionResult, GraphStreamChunk } from './agent-graph.types';
+import { AgentExecutionResult } from '../types/agent.types';
+interface RuntimeLike {
+    execute(agentName: string, input: string, options?: Record<string, unknown>): Promise<AgentExecutionResult>;
+    getAgentMetadata(agentName: string): {
+        description?: string;
+    } | undefined;
+}
+/**
+ * Fluent builder for constructing a multi-agent graph.
+ * Call `.compile()` to get an executable `CompiledGraph`.
+ */
+export declare class AgentGraph {
+    private readonly graphId;
+    private readonly runtime;
+    private readonly nodes;
+    private readonly edges;
+    private entryPoint?;
+    constructor(graphId: string, runtime: RuntimeLike);
+    /**
+     * Add a node to the graph.
+     *
+     * Node types:
+     * - `'agent'`    — runs a named agent via AgentRuntime
+     * - `'function'` — runs an arbitrary async function
+     * - `'parallel'` — fans-out to multiple child nodes concurrently
+     */
+    addNode(id: string, config: GraphNodeConfig): this;
+    /**
+     * Add an unconditional directed edge from `from` → `to`.
+     * Use `END` as the target to terminate the graph.
+     */
+    addEdge(from: string, to: string): this;
+    /**
+     * Add a conditional edge from `from`.
+     * The `routerFn` inspects the current `GraphState` and returns the ID of
+     * the next node (or `END` to stop).
+     *
+     * @param routeMap Optional mapping of routerFn return values to node IDs,
+     *                 so you can use short keys like `'code'` → `'CoderNode'`.
+     */
+    addConditionalEdge(from: string, routerFn: RouterFunction, routeMap?: Record<string, string>): this;
+    /** Set the node where graph execution begins */
+    setEntryPoint(nodeId: string): this;
+    /**
+     * Validate the graph and return an executable `CompiledGraph`.
+     * Throws if the graph is malformed (missing entry point, dangling edges, etc.)
+     */
+    compile(): CompiledGraph;
+}
+/**
+ * Executable graph produced by `AgentGraph.compile()`.
+ */
+export declare class CompiledGraph {
+    private readonly graphId;
+    private readonly nodes;
+    private readonly edges;
+    private readonly entryPoint;
+    private readonly runtime;
+    constructor(graphId: string, nodes: Map<string, GraphNode>, edges: GraphEdge[], entryPoint: string, runtime: RuntimeLike);
+    /**
+     * Execute the graph synchronously (collects all results before returning).
+     */
+    execute(input: string, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
+    /**
+     * Execute the graph and yield a `GraphStreamChunk` after each node completes.
+     * Useful for streaming progress updates to the client in real-time.
+     *
+     * @example
+     * ```ts
+     * for await (const chunk of graph.stream('Research LLMs')) {
+     *   console.log(`[${chunk.nodeId}]`, chunk.chunk);
+     * }
+     * ```
+     */
+    stream(input: string, options?: GraphExecutionOptions): AsyncGenerator<GraphStreamChunk>;
+    private executeNode;
+    private executeParallelBranches;
+    private defaultMerge;
+    private resolveNextNode;
+    private applyPatch;
+}
+export {};
+//# sourceMappingURL=agent-graph.d.ts.map

package/dist/graph/agent-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-graph.d.ts","sourceRoot":"","sources":["../../src/graph/agent-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,EAGL,SAAS,EACT,eAAe,EACf,SAAS,EACT,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EAEpB,gBAAgB,EAGjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAI5D,UAAU,WAAW;IACnB,OAAO,CACL,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CAC3E;AAMD;;;GAGG;AACH,qBAAa,UAAU;IAMnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW;IAUvC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAelD;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAKvC;;;;;;;OAOG;IACH,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,EACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,IAAI;IAYP,gDAAgD;IAChD,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IASnC;;;OAGG;IACH,OAAO,IAAI,aAAa;CAyCzB;AAMD;;GAEG;AACH,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAJP,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAC7B,KAAK,EAAE,SAAS,EAAE,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW;IAOvC;;OAEG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAmGhG;;;;;;;;;;OAUG;IACI,MAAM,CACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAAC,gBAAgB,CAAC;YA+ErB,WAAW;YAyEX,uBAAuB;IAqBrC,OAAO,CAAC,YAAY;IAmCpB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,UAAU;CAUnB"}