@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/dist/src/ai/SubAgentExecutor.d.ts

@@ -0,0 +1,38 @@
+import { FlinkContext } from "../FlinkContext";
+import { ToolResult } from "./FlinkTool";
+import { AgentExecuteResult, AgentExecuteContext } from "./FlinkAgent";
+/**
+ * Special tool executor that wraps a sub-agent
+ * Automatically created for each agent reference in parent agent's `agents` array
+ */
+export declare class SubAgentExecutor<Ctx extends FlinkContext> {
+    private ctx;
+    private subAgentInstanceName;
+    private subAgentId;
+    constructor(subAgentInstanceName: string, ctx: Ctx);
+    /**
+     * Execute the sub-agent with the given input
+     */
+    execute(input: any, overrides?: {
+        user?: any;
+        permissions?: string[];
+    }, parentContext?: AgentExecuteContext): Promise<ToolResult<AgentExecuteResult>>;
+    /**
+     * Generate tool schema for this sub-agent
+     * LLM sees this as a regular tool
+     */
+    getToolSchema(): any;
+    /**
+     * Format sub-agent result for AI consumption
+     */
+    formatResultForAI(result: ToolResult<AgentExecuteResult>): string;
+    /**
+     * Check permissions - sub-agents handle their own permissions
+     */
+    checkPermissions(_user?: any, _input?: any, _userPermissions?: string[], _conversationContext?: any): Promise<boolean>;
+    /**
+     * Mark this as a sub-agent executor
+     */
+    isSubAgentExecutor(): boolean;
+    getSubAgentId(): string;
+}

package/dist/src/ai/SubAgentExecutor.js

@@ -0,0 +1,223 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubAgentExecutor = void 0;
+var zod_1 = require("zod");
+var FlinkLog_1 = require("../FlinkLog");
+var utils_1 = require("../utils");
+var uuid_1 = require("uuid");
+/**
+ * Special tool executor that wraps a sub-agent
+ * Automatically created for each agent reference in parent agent's `agents` array
+ */
+var SubAgentExecutor = /** @class */ (function () {
+    function SubAgentExecutor(subAgentInstanceName, ctx) {
+        this.ctx = ctx;
+        this.subAgentInstanceName = subAgentInstanceName;
+        // Convert instance name to kebab-case for consistency with agent IDs
+        this.subAgentId = (0, utils_1.toKebabCase)(subAgentInstanceName);
+    }
+    /**
+     * Execute the sub-agent with the given input
+     */
+    SubAgentExecutor.prototype.execute = function (input, overrides, parentContext // Parent agent context for sub-agent delegation
+    ) {
+        return __awaiter(this, void 0, void 0, function () {
+            var user, userPermissions, agents, subAgent, boundAgent, strategy, conversationId, response, result, err_1;
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        user = overrides === null || overrides === void 0 ? void 0 : overrides.user;
+                        userPermissions = overrides === null || overrides === void 0 ? void 0 : overrides.permissions;
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 3, , 4]);
+                        agents = this.ctx.agents;
+                        if (!agents) {
+                            return [2 /*return*/, {
+                                    success: false,
+                                    error: "Agents not available in context",
+                                    code: "NO_AGENTS",
+                                }];
+                        }
+                        subAgent = agents[this.subAgentInstanceName];
+                        if (!subAgent) {
+                            return [2 /*return*/, {
+                                    success: false,
+                                    error: "Sub-agent ".concat(this.subAgentInstanceName, " not found"),
+                                    code: "AGENT_NOT_FOUND",
+                                }];
+                        }
+                        boundAgent = subAgent;
+                        if (user) {
+                            boundAgent = boundAgent.withUser(user);
+                        }
+                        if (userPermissions) {
+                            boundAgent = boundAgent.withPermissions(userPermissions);
+                        }
+                        strategy = subAgent.conversationStrategy || "inherit";
+                        conversationId = void 0;
+                        if (strategy === "inherit") {
+                            // Use parent's conversation ID
+                            conversationId = parentContext === null || parentContext === void 0 ? void 0 : parentContext.conversationId;
+                        }
+                        else if (strategy === "independent") {
+                            // Create nested conversation
+                            conversationId = (parentContext === null || parentContext === void 0 ? void 0 : parentContext.conversationId)
+                                ? "".concat(parentContext.conversationId, ":").concat(this.subAgentInstanceName, ":").concat((0, utils_1.generateShortId)())
+                                : (0, uuid_1.v4)();
+                        }
+                        else {
+                            // strategy === "none"
+                            conversationId = undefined;
+                        }
+                        FlinkLog_1.log.debug("Delegating to sub-agent ".concat(this.subAgentInstanceName, " from parent ").concat((parentContext === null || parentContext === void 0 ? void 0 : parentContext.agentId) || "unknown", ", ") +
+                            "strategy: \"".concat(strategy, "\", conversationId: ").concat(conversationId || "none"));
+                        response = boundAgent.run({
+                            message: input.query || input.message || JSON.stringify(input),
+                            user: user,
+                            userPermissions: userPermissions,
+                            conversationId: conversationId,
+                            conversationContext: parentContext === null || parentContext === void 0 ? void 0 : parentContext.conversationContext,
+                            metadata: __assign(__assign({}, input.metadata), { parentConversationId: parentContext === null || parentContext === void 0 ? void 0 : parentContext.conversationId, parentAgentId: parentContext === null || parentContext === void 0 ? void 0 : parentContext.agentId, parentMetadata: parentContext === null || parentContext === void 0 ? void 0 : parentContext.metadata, isSubAgentCall: true, subAgentDepth: ((_a = parentContext === null || parentContext === void 0 ? void 0 : parentContext.subAgentDepth) !== null && _a !== void 0 ? _a : 0) + 1 }),
+                        });
+                        return [4 /*yield*/, response.result];
+                    case 2:
+                        result = _b.sent();
+                        FlinkLog_1.log.debug("Sub-agent ".concat(this.subAgentInstanceName, " completed with ").concat(result.stepsUsed, " steps"));
+                        return [2 /*return*/, {
+                                success: true,
+                                data: result,
+                            }];
+                    case 3:
+                        err_1 = _b.sent();
+                        FlinkLog_1.log.error("Sub-agent ".concat(this.subAgentInstanceName, " execution failed:"), err_1.message);
+                        return [2 /*return*/, {
+                                success: false,
+                                error: "Sub-agent execution failed: ".concat(err_1.message),
+                                code: "SUB_AGENT_ERROR",
+                            }];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Generate tool schema for this sub-agent
+     * LLM sees this as a regular tool
+     */
+    SubAgentExecutor.prototype.getToolSchema = function () {
+        var agents = this.ctx.agents;
+        if (!(agents === null || agents === void 0 ? void 0 : agents[this.subAgentInstanceName])) {
+            throw new Error("Missing subagent: " + this.subAgentInstanceName);
+        }
+        var subAgent = agents === null || agents === void 0 ? void 0 : agents[this.subAgentInstanceName];
+        var description = subAgent ? "Delegate to ".concat(this.subAgentId, ": ").concat(subAgent.description) : "Delegate to ".concat(this.subAgentId);
+        // Simple schema - accepts a query string
+        var inputSchema = zod_1.z.object({
+            query: zod_1.z.string().describe("The question or task to send to the specialist agent"),
+        });
+        var toolName = this.subAgentId;
+        return {
+            name: toolName,
+            description: description,
+            inputSchema: inputSchema.schema
+                ? inputSchema.schema()
+                : {
+                    type: "object",
+                    properties: {
+                        query: { type: "string" },
+                    },
+                    required: ["query"],
+                },
+        };
+    };
+    /**
+     * Format sub-agent result for AI consumption
+     */
+    SubAgentExecutor.prototype.formatResultForAI = function (result) {
+        var _a, _b;
+        if (result.success) {
+            var agentResult = result.data;
+            // Return the agent's final message as the tool result
+            return JSON.stringify({
+                answer: agentResult.message,
+                stepsUsed: agentResult.stepsUsed,
+                tokensUsed: (((_a = agentResult.usage) === null || _a === void 0 ? void 0 : _a.inputTokens) || 0) + (((_b = agentResult.usage) === null || _b === void 0 ? void 0 : _b.outputTokens) || 0),
+            });
+        }
+        else {
+            return "Error: ".concat(result.error).concat(result.code ? " (".concat(result.code, ")") : "");
+        }
+    };
+    /**
+     * Check permissions - sub-agents handle their own permissions
+     */
+    SubAgentExecutor.prototype.checkPermissions = function (_user, _input, _userPermissions, _conversationContext) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                // Sub-agents manage their own permissions
+                // The sub-agent's permissions will be checked when executed
+                return [2 /*return*/, true];
+            });
+        });
+    };
+    /**
+     * Mark this as a sub-agent executor
+     */
+    SubAgentExecutor.prototype.isSubAgentExecutor = function () {
+        return true;
+    };
+    SubAgentExecutor.prototype.getSubAgentId = function () {
+        return this.subAgentId;
+    };
+    return SubAgentExecutor;
+}());
+exports.SubAgentExecutor = SubAgentExecutor;

package/dist/src/ai/ToolExecutor.d.ts

@@ -0,0 +1,64 @@
+import { FlinkContext } from "../FlinkContext";
+import { FlinkTool, FlinkToolProps, ToolResult } from "./FlinkTool";
+import { FlinkToolSchema } from "./LLMAdapter";
+export declare class ToolExecutor<Ctx extends FlinkContext> {
+    private toolProps;
+    private toolFn;
+    private ctx;
+    private autoSchemas?;
+    private allSchemas?;
+    private ajv;
+    private compiledInputValidator?;
+    private compiledOutputValidator?;
+    constructor(toolProps: FlinkToolProps, toolFn: FlinkTool<Ctx, any, any>, ctx: Ctx, autoSchemas?: {
+        inputSchema?: any;
+        outputSchema?: any;
+        inputTypeHint?: "void" | "any" | "named";
+        outputTypeHint?: "void" | "any" | "named";
+    } | undefined, allSchemas?: Record<string, any> | undefined);
+    /**
+     * Execute the tool with input
+     * @param input - Tool input data
+     * @param overrides - Optional overrides for user/permissions/conversationContext (for testing)
+     */
+    execute(input: any, overrides?: {
+        user?: any;
+        permissions?: string[];
+        conversationContext?: any;
+    }): Promise<ToolResult<any>>;
+    getToolSchema(): FlinkToolSchema;
+    /**
+     * Resolve cross-schema $ref values into $defs so the schema is self-contained.
+     *
+     * Flink's schema manifest stores schemas as separate documents with IDs like
+     * "Canvas.ElementInput". These are valid for AJV (which uses a schema registry),
+     * but LLM providers like OpenAI require a single self-contained schema where all
+     * $ref values point to #/$defs/... entries at the top level.
+     */
+    private resolveSchemaRefs;
+    /**
+     * Get tool result for AI consumption
+     * Formats ToolResult into string for AI context
+     */
+    formatResultForAI(result: ToolResult<any>): string;
+    /**
+     * Check if user has permission to use this tool
+     * Used by AgentRunner to filter tools before showing to LLM
+     *
+     * @param user - User object
+     * @param input - Tool input (for function-based permissions)
+     * @param userPermissions - Optional resolved permissions from auth plugin (preferred)
+     * @param conversationContext - Optional conversation context
+     */
+    checkPermissions(user?: any, input?: any, userPermissions?: string[], conversationContext?: any): Promise<boolean>;
+    private checkPermissionsInternal;
+    /**
+     * Format Zod validation errors into LLM-friendly error messages
+     * Provides specific guidance on what's missing or incorrect
+     */
+    private formatZodError;
+    /**
+     * Format AJV validation errors into LLM-friendly error messages
+     */
+    private formatAjvErrors;
+}