@flink-app/flink 1.0.0 → 2.0.0-alpha.49

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

@@ -0,0 +1,119 @@
+/**
+ * Generic message format for LLM conversations
+ * Compatible with most LLM providers (Anthropic, OpenAI, etc.)
+ */
+export type LLMMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | LLMContentBlock[];
+} | {
+    role: "assistant";
+    content: string | LLMContentBlock[];
+};
+export type LLMContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: any;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+/**
+ * Standard Flink tool schema format
+ * This is the format generated by ToolExecutor.getToolSchema()
+ * Adapters convert this to provider-specific formats
+ */
+export interface FlinkToolSchema {
+    /**
+     * Tool name (kebab-case identifier)
+     */
+    name: string;
+    /**
+     * Human-readable description for the LLM
+     */
+    description: string;
+    /**
+     * JSON Schema for tool input validation
+     * Generated from Zod schema via z.toJSONSchema()
+     */
+    inputSchema: Record<string, any>;
+}
+/**
+ * LLM Adapter interface for provider abstraction
+ * Enables support for multiple AI providers (Anthropic, OpenAI, Mistral, etc.)
+ *
+ * All adapters use streaming as the primary method since:
+ * - All modern LLM providers support streaming
+ * - Better user experience (time-to-first-token <500ms)
+ * - Prevents HTTP timeouts for long responses
+ * - FlinkAgent's lazy generator pattern allows both streaming and awaiting final result
+ *
+ * @template ToolSchema - The tool schema format accepted by this adapter (defaults to FlinkToolSchema)
+ */
+export interface LLMAdapter<ToolSchema = FlinkToolSchema> {
+    /**
+     * Optional debug flag to enable detailed logging
+     * When enabled, adapters will log:
+     * - Full request parameters sent to the LLM provider
+     * - Tool call decisions made by the LLM
+     * - Token usage and performance metrics
+     * - Error details and response metadata
+     *
+     * Useful for development and troubleshooting.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * Stream a completion with tool calling support
+     * Returns async generator for streaming responses
+     *
+     * Even if you want non-streaming UX, use this method and await the final result:
+     * ```typescript
+     * const response = agent.execute({ message: "Hello" });
+     * const result = await response.result; // Non-streaming consumption
+     * ```
+     */
+    stream(params: {
+        /**
+         * Instructions that define agent behavior and personality.
+         * Adapters should prepend this as a system message to the conversation.
+         * Following Vercel AI SDK pattern.
+         */
+        instructions: string;
+        messages: LLMMessage[];
+        tools: ToolSchema[];
+        maxTokens: number;
+        temperature: number;
+    }): AsyncGenerator<LLMStreamChunk>;
+}
+/**
+ * Streaming chunk types
+ */
+export type LLMStreamChunk = {
+    type: "text";
+    delta: string;
+} | {
+    type: "tool_call";
+    toolCall: {
+        id: string;
+        name: string;
+        input: any;
+    };
+} | {
+    type: "usage";
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+} | {
+    type: "done";
+    stopReason: string;
+};

package/dist/src/ai/LLMAdapter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,36 @@
+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, user?: any, parentContext?: AgentExecuteContext, // NEW: parent agent context
+    userPermissions?: string[]): 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[]): Promise<boolean>;
+    /**
+     * Mark this as a sub-agent executor
+     */
+    isSubAgentExecutor(): boolean;
+    getSubAgentId(): string;
+}

package/dist/src/ai/SubAgentExecutor.js

@@ -0,0 +1,220 @@
+"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, user, parentContext, // NEW: parent agent context
+    userPermissions // Resolved permissions from auth plugin
+    ) {
+        return __awaiter(this, void 0, void 0, function () {
+            var agents, subAgent, boundAgent, strategy, conversationId, response, result, err_1;
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _b.trys.push([0, 2, , 3]);
+                        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,
+                            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 1:
+                        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 2:
+                        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 3: 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"),
+        });
+        // Convert kebab-case ID to snake_case for tool name (ask_car_agent, not ask_car-agent)
+        var toolName = "ask_".concat((0, utils_1.toSnakeCase)(this.subAgentId));
+        return {
+            name: toolName,
+            description: description,
+            input_schema: 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) {
+        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,35 @@
+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;
+    constructor(toolProps: FlinkToolProps, toolFn: FlinkTool<Ctx, any, any>, ctx: Ctx);
+    execute(input: any, user?: any, userPermissions?: string[]): Promise<ToolResult<any>>;
+    getToolSchema(): FlinkToolSchema;
+    /**
+     * Fallback schema generation if toJSONSchema is not available
+     */
+    private fallbackSchema;
+    /**
+     * 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)
+     */
+    checkPermissions(user?: any, input?: any, userPermissions?: string[]): Promise<boolean>;
+    private checkPermissionsInternal;
+    /**
+     * Format Zod validation errors into LLM-friendly error messages
+     * Provides specific guidance on what's missing or incorrect
+     */
+    private formatValidationError;
+}

package/dist/src/ai/ToolExecutor.js

@@ -0,0 +1,237 @@
+"use strict";
+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.ToolExecutor = void 0;
+var FlinkLog_1 = require("../FlinkLog");
+var ToolExecutor = /** @class */ (function () {
+    function ToolExecutor(toolProps, toolFn, ctx) {
+        this.toolProps = toolProps;
+        this.toolFn = toolFn;
+        this.ctx = ctx;
+    }
+    ToolExecutor.prototype.execute = function (input, user, userPermissions) {
+        return __awaiter(this, void 0, void 0, function () {
+            var hasPermission, validatedInput, errorDetails, result, err_1, validatedData;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!this.toolProps.permissions) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.checkPermissionsInternal(input, user, userPermissions)];
+                    case 1:
+                        hasPermission = _a.sent();
+                        if (!hasPermission) {
+                            return [2 /*return*/, {
+                                    success: false,
+                                    error: "Permission denied for tool ".concat(this.toolProps.id),
+                                    code: "PERMISSION_DENIED",
+                                }];
+                        }
+                        _a.label = 2;
+                    case 2:
+                        try {
+                            validatedInput = this.toolProps.inputSchema.parse(input);
+                        }
+                        catch (err) {
+                            FlinkLog_1.log.warn("Tool ".concat(this.toolProps.id, " input validation failed:"), err.message);
+                            errorDetails = this.formatValidationError(err, input);
+                            return [2 /*return*/, {
+                                    success: false,
+                                    error: "Invalid input for tool '".concat(this.toolProps.id, "': ").concat(errorDetails),
+                                    code: "VALIDATION_ERROR",
+                                }];
+                        }
+                        // 3. Execute tool
+                        FlinkLog_1.log.debug("Executing tool ".concat(this.toolProps.id));
+                        _a.label = 3;
+                    case 3:
+                        _a.trys.push([3, 5, , 6]);
+                        return [4 /*yield*/, this.toolFn({
+                                input: validatedInput,
+                                ctx: this.ctx,
+                                user: user,
+                            })];
+                    case 4:
+                        result = _a.sent();
+                        return [3 /*break*/, 6];
+                    case 5:
+                        err_1 = _a.sent();
+                        FlinkLog_1.log.error("Tool ".concat(this.toolProps.id, " threw error:"), err_1.message);
+                        return [2 /*return*/, {
+                                success: false,
+                                error: "Tool execution failed: ".concat(err_1.message),
+                                code: "EXECUTION_ERROR",
+                            }];
+                    case 6:
+                        // 4. Handle error results
+                        if (!result.success) {
+                            FlinkLog_1.log.warn("Tool ".concat(this.toolProps.id, " returned error:"), result.error);
+                            return [2 /*return*/, result]; // Return error result as-is
+                        }
+                        // 5. Output validation (if schema provided)
+                        if (this.toolProps.outputSchema) {
+                            try {
+                                validatedData = this.toolProps.outputSchema.parse(result.data);
+                                return [2 /*return*/, { success: true, data: validatedData }];
+                            }
+                            catch (err) {
+                                FlinkLog_1.log.error("Tool ".concat(this.toolProps.id, " output validation failed:"), err.message);
+                                return [2 /*return*/, {
+                                        success: false,
+                                        error: "Invalid output from tool ".concat(this.toolProps.id, ": ").concat(err.message),
+                                        code: "OUTPUT_VALIDATION_ERROR",
+                                    }];
+                            }
+                        }
+                        return [2 /*return*/, result];
+                }
+            });
+        });
+    };
+    ToolExecutor.prototype.getToolSchema = function () {
+        // Use Zod 4's built-in z.toJSONSchema()
+        var zodSchema = this.toolProps.inputSchema;
+        var z = require("zod");
+        return {
+            name: this.toolProps.id,
+            description: this.toolProps.description,
+            inputSchema: z.toJSONSchema ? z.toJSONSchema(zodSchema) : this.fallbackSchema(zodSchema),
+        };
+    };
+    /**
+     * Fallback schema generation if toJSONSchema is not available
+     */
+    ToolExecutor.prototype.fallbackSchema = function (zodSchema) {
+        // Try to use _def to extract basic schema info
+        FlinkLog_1.log.warn("Tool ".concat(this.toolProps.id, ": z.toJSONSchema() not available, using fallback schema generation"));
+        return {
+            type: "object",
+            properties: {},
+            required: [],
+        };
+    };
+    /**
+     * Get tool result for AI consumption
+     * Formats ToolResult into string for AI context
+     */
+    ToolExecutor.prototype.formatResultForAI = function (result) {
+        if (result.success) {
+            return JSON.stringify(result.data);
+        }
+        else {
+            return "Error: ".concat(result.error).concat(result.code ? " (".concat(result.code, ")") : "");
+        }
+    };
+    /**
+     * 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)
+     */
+    ToolExecutor.prototype.checkPermissions = function (user, input, userPermissions) {
+        return __awaiter(this, void 0, void 0, function () {
+            var perms, effectivePerms, requiredPerms;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        perms = this.toolProps.permissions;
+                        if (!perms)
+                            return [2 /*return*/, true];
+                        if (!(typeof perms === "function")) return [3 /*break*/, 2];
+                        return [4 /*yield*/, perms(input !== null && input !== void 0 ? input : {}, user)];
+                    case 1: return [2 /*return*/, _a.sent()];
+                    case 2:
+                        if (!user)
+                            return [2 /*return*/, false];
+                        effectivePerms = userPermissions || user.permissions || [];
+                        requiredPerms = Array.isArray(perms) ? perms : [perms];
+                        return [2 /*return*/, requiredPerms.every(function (p) { return effectivePerms.includes(p); })];
+                }
+            });
+        });
+    };
+    ToolExecutor.prototype.checkPermissionsInternal = function (input, user, userPermissions) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                return [2 /*return*/, this.checkPermissions(user, input, userPermissions)];
+            });
+        });
+    };
+    /**
+     * Format Zod validation errors into LLM-friendly error messages
+     * Provides specific guidance on what's missing or incorrect
+     */
+    ToolExecutor.prototype.formatValidationError = function (err, receivedInput) {
+        // Check if it's a Zod error with issues array
+        if (err.issues && Array.isArray(err.issues)) {
+            var issues = err.issues.map(function (issue) {
+                var path = issue.path.join('.');
+                var field = path || 'input';
+                if (issue.code === 'invalid_type') {
+                    if (issue.received === 'undefined') {
+                        return "Missing required field '".concat(field, "' (expected ").concat(issue.expected, ")");
+                    }
+                    return "Field '".concat(field, "' has wrong type: expected ").concat(issue.expected, ", got ").concat(issue.received);
+                }
+                if (issue.code === 'too_small') {
+                    if (issue.type === 'string') {
+                        return "Field '".concat(field, "' is too short (minimum ").concat(issue.minimum, " characters)");
+                    }
+                    return "Field '".concat(field, "' is too small (minimum ").concat(issue.minimum, ")");
+                }
+                if (issue.code === 'too_big') {
+                    if (issue.type === 'string') {
+                        return "Field '".concat(field, "' is too long (maximum ").concat(issue.maximum, " characters)");
+                    }
+                    return "Field '".concat(field, "' is too large (maximum ").concat(issue.maximum, ")");
+                }
+                // Generic fallback
+                return "".concat(field, ": ").concat(issue.message);
+            });
+            var inputInfo = Object.keys(receivedInput || {}).length === 0
+                ? 'You provided an empty object {}.'
+                : "You provided: ".concat(JSON.stringify(receivedInput));
+            return "".concat(issues.join('; '), ". ").concat(inputInfo);
+        }
+        // Fallback for non-Zod errors
+        return err.message || 'Unknown validation error';
+    };
+    return ToolExecutor;
+}());
+exports.ToolExecutor = ToolExecutor;

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

@@ -0,0 +1,5 @@
+export * from "./FlinkTool";
+export * from "./FlinkAgent";
+export * from "./ToolExecutor";
+export * from "./AgentRunner";
+export * from "./LLMAdapter";