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

package/dist/src/ai/FlinkAgent.js

@@ -0,0 +1,633 @@
+"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 };
+    }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlinkAgent = void 0;
+var FlinkLog_1 = require("../FlinkLog");
+var utils_1 = require("../utils");
+var AgentRunner_1 = require("./AgentRunner");
+var FlinkErrors_1 = require("../FlinkErrors");
+/**
+ * Base class for Flink agents (similar to FlinkRepo pattern)
+ *
+ * Agents extend this class and define their configuration as properties.
+ * Auto-registered by scanning src/agents/ directory.
+ *
+ * Tool references are validated at startup to ensure all referenced tools exist.
+ *
+ * Agents define their own domain-specific entry points that call `this.execute()`.
+ * This provides better type safety and developer experience than a generic `run()` method.
+ *
+ * ## Lifecycle Hooks
+ *
+ * Agents support lifecycle hooks for advanced orchestration:
+ * - `beforeRun`: Load conversation history, prepare context
+ * - `onStep`: Save state after each LLM turn
+ * - `afterRun`: Persist final conversation state
+ * - `transformSubAgentInput`: Compact/brief context before delegating to sub-agents
+ * - `onSubAgentCall`: Log/track delegations
+ * - `onSubAgentComplete`: Process sub-agent results
+ *
+ * Example:
+ * ```typescript
+ * export default class CarAgent extends FlinkAgent<AppCtx> {
+ *     id = "car-agent"; // Optional: defaults to kebab-case class name "car-agent"
+ *     description = "Expert in car models";
+ *     instructions = "You are a car expert...";
+ *     tools = ["get-cars-tool"]; // Validated at startup
+ *     agents = [UserAgent, "external-agent"]; // Can use class references or strings
+ *
+ *     // Domain-specific entry points with proper types
+ *     async searchByBrand(brand: string) {
+ *         const response = this.execute({
+ *             message: `Find all ${brand} cars`
+ *         });
+ *         return await response.result;
+ *     }
+ *
+ *     async compareModels(model1: string, model2: string) {
+ *         const response = this.execute({
+ *             message: `Compare ${model1} and ${model2}`
+ *         });
+ *         return await response.result;
+ *     }
+ *
+ *     // Hook: Compact context when delegating to sub-agents
+ *     protected async transformSubAgentInput(subAgentId, input, context) {
+ *         const summary = await this.summarizeContext(context.conversationId);
+ *         return { ...input, query: `Context: ${summary}\n\n${input.query}` };
+ *     }
+ * }
+ * ```
+ */
+var FlinkAgent = /** @class */ (function () {
+    function FlinkAgent() {
+    }
+    /**
+     * Internal initialization called by FlinkApp
+     * @internal
+     */
+    FlinkAgent.prototype.__init = function (llmAdapters, tools) {
+        this._llmAdapters = llmAdapters;
+        this._tools = tools;
+    };
+    /**
+     * Bind a user to this agent for permission checks
+     *
+     * This creates a new agent instance with the user bound, allowing clean API:
+     * ```typescript
+     * const result = await ctx.agents.carAgent
+     *     .withUser(req.user)
+     *     .searchByBrand("Volvo");
+     * ```
+     *
+     * The bound user is used for:
+     * - Agent-level permission checks
+     * - Tool filtering (only allowed tools shown to LLM)
+     * - Tool-level permission checks
+     */
+    FlinkAgent.prototype.withUser = function (user) {
+        var bound = Object.create(Object.getPrototypeOf(this));
+        Object.assign(bound, this);
+        bound._boundUser = user;
+        bound.runner = undefined; // Clear runner cache to use new user
+        // Explicitly ensure ctx and internal properties are copied (in case they're not enumerable)
+        if (this.ctx) {
+            bound.ctx = this.ctx;
+        }
+        if (this._llmAdapters) {
+            bound._llmAdapters = this._llmAdapters;
+        }
+        if (this._tools) {
+            bound._tools = this._tools;
+        }
+        if (this._boundUserPermissions !== undefined) {
+            bound._boundUserPermissions = this._boundUserPermissions;
+        }
+        return bound;
+    };
+    /**
+     * Bind resolved permissions to this agent for permission checks
+     *
+     * This creates a new agent instance with permissions bound, allowing clean API:
+     * ```typescript
+     * const result = await ctx.agents.carAgent
+     *     .withUser(req.user)
+     *     .withPermissions(req.userPermissions) // Resolved permissions from auth plugin
+     *     .searchByBrand("Volvo");
+     * ```
+     *
+     * The bound permissions are used for:
+     * - Tool filtering (only allowed tools shown to LLM)
+     * - Tool-level permission checks
+     *
+     * Permissions are typically populated by auth plugins during authentication
+     * based on roles, dynamic roles, or custom permission resolution.
+     */
+    FlinkAgent.prototype.withPermissions = function (userPermissions) {
+        var bound = Object.create(Object.getPrototypeOf(this));
+        Object.assign(bound, this);
+        bound._boundUserPermissions = userPermissions;
+        bound.runner = undefined; // Clear runner cache to use new permissions
+        // Explicitly ensure ctx and internal properties are copied (in case they're not enumerable)
+        if (this.ctx) {
+            bound.ctx = this.ctx;
+        }
+        if (this._llmAdapters) {
+            bound._llmAdapters = this._llmAdapters;
+        }
+        if (this._tools) {
+            bound._tools = this._tools;
+        }
+        if (this._boundUser !== undefined) {
+            bound._boundUser = this._boundUser;
+        }
+        return bound;
+    };
+    /**
+     * Override the LLM adapter for this agent
+     *
+     * This creates a new agent instance with a different LLM adapter, allowing runtime selection:
+     * ```typescript
+     * const result = await ctx.agents.carAgent
+     *     .withUser(req.user)
+     *     .withLlm("fast")  // Use fast LLM instead of default
+     *     .searchByBrand("Volvo");
+     * ```
+     *
+     * The LLM adapter ID must be registered in FlinkApp's ai.llms configuration.
+     *
+     * @param adapterId - The ID of the LLM adapter to use (e.g., "default", "fake", "fast", "anthropic")
+     * @returns A new agent instance with the specified LLM adapter
+     */
+    FlinkAgent.prototype.withLlm = function (adapterId) {
+        var bound = Object.create(Object.getPrototypeOf(this));
+        Object.assign(bound, this);
+        // Override the model configuration with the new adapter ID
+        bound.model = __assign(__assign({}, (this.model || {})), { adapterId: adapterId });
+        bound.runner = undefined; // Clear runner cache to use new adapter
+        // Explicitly ensure ctx and internal properties are copied (in case they're not enumerable)
+        if (this.ctx) {
+            bound.ctx = this.ctx;
+        }
+        if (this._llmAdapters) {
+            bound._llmAdapters = this._llmAdapters;
+        }
+        if (this._tools) {
+            bound._tools = this._tools;
+        }
+        if (this._boundUser !== undefined) {
+            bound._boundUser = this._boundUser;
+        }
+        if (this._boundUserPermissions !== undefined) {
+            bound._boundUserPermissions = this._boundUserPermissions;
+        }
+        return bound;
+    };
+    /**
+     * Public execution method for external callers (handlers, sub-agents, etc.)
+     *
+     * Use this when calling an agent from outside the agent class.
+     * For internal use within agent subclasses, use `execute()` instead.
+     */
+    FlinkAgent.prototype.run = function (input) {
+        return this.execute(input);
+    };
+    /**
+     * Internal execution method - supports both awaiting and streaming
+     *
+     * Uses lazy generator pattern (similar to Vercel AI SDK) to allow
+     * multiple consumption without re-execution.
+     *
+     * Agents call this method from their run() implementation to execute the AI logic.
+     *
+     * Examples:
+     *   const response = this.execute({ message: "Hello" });
+     *   const result = await response.result;  // Await final result
+     *   for await (const text of response.textStream) { ... }  // Stream text
+     *   for await (const chunk of response.fullStream) { ... }  // Stream all events
+     */
+    FlinkAgent.prototype.execute = function (input) {
+        var _this = this;
+        var _a, _b, _c, _d, _e, _f;
+        // Use bound user if not explicitly provided in input
+        var user = (_a = input.user) !== null && _a !== void 0 ? _a : this._boundUser;
+        var userPermissions = (_b = input.userPermissions) !== null && _b !== void 0 ? _b : this._boundUserPermissions;
+        var executeInput = __assign(__assign({}, input), { user: user, userPermissions: userPermissions });
+        // Permission check
+        if (this.permissions) {
+            this.checkPermissionsSync(user, userPermissions);
+        }
+        // Build execution context
+        var execContext = {
+            agentId: this.getAgentId(),
+            conversationId: executeInput.conversationId,
+            user: user,
+            isSubAgent: ((_c = executeInput.metadata) === null || _c === void 0 ? void 0 : _c.isSubAgentCall) === true,
+            parentAgentId: (_d = executeInput.metadata) === null || _d === void 0 ? void 0 : _d.parentAgentId,
+            subAgentDepth: (_f = (_e = executeInput.metadata) === null || _e === void 0 ? void 0 : _e.subAgentDepth) !== null && _f !== void 0 ? _f : 0,
+            metadata: executeInput.metadata,
+        };
+        // Call optional beforeRun hook with context
+        if (this.beforeRun) {
+            var result = this.beforeRun(executeInput, execContext);
+            if (result instanceof Promise) {
+                // If beforeRun is async, we need to handle it properly
+                // For now, we'll let the runner handle async hooks
+            }
+        }
+        var runner = this.getRunner();
+        FlinkLog_1.log.debug("Running agent ".concat(this.constructor.name));
+        // Lazy evaluation - generator only starts when first consumed
+        var baseGenerator = null;
+        var buffer = [];
+        var done = false;
+        var fetchPromise = null; // Prevent concurrent fetches
+        var getBaseGenerator = function () {
+            if (!baseGenerator) {
+                baseGenerator = runner.streamGenerator(executeInput);
+            }
+            return baseGenerator;
+        };
+        // Fetch next chunk from base generator (only one consumer at a time)
+        var fetchNext = function () { return __awaiter(_this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!fetchPromise) return [3 /*break*/, 2];
+                        // Another iterator is already fetching, wait for it
+                        return [4 /*yield*/, fetchPromise];
+                    case 1:
+                        // Another iterator is already fetching, wait for it
+                        _a.sent();
+                        return [2 /*return*/];
+                    case 2:
+                        if (done) {
+                            return [2 /*return*/];
+                        }
+                        fetchPromise = (function () { return __awaiter(_this, void 0, void 0, function () {
+                            var gen, _a, value, isDone;
+                            return __generator(this, function (_b) {
+                                switch (_b.label) {
+                                    case 0:
+                                        gen = getBaseGenerator();
+                                        return [4 /*yield*/, gen.next()];
+                                    case 1:
+                                        _a = _b.sent(), value = _a.value, isDone = _a.done;
+                                        if (isDone) {
+                                            done = true;
+                                        }
+                                        else {
+                                            buffer.push(value);
+                                        }
+                                        return [2 /*return*/];
+                                }
+                            });
+                        }); })();
+                        return [4 /*yield*/, fetchPromise];
+                    case 3:
+                        _a.sent();
+                        fetchPromise = null;
+                        return [2 /*return*/];
+                }
+            });
+        }); };
+        // Create independent iterators that share buffered chunks
+        var createIterator = function () {
+            var index = 0;
+            return (function () {
+                return __asyncGenerator(this, arguments, function () {
+                    return __generator(this, function (_a) {
+                        switch (_a.label) {
+                            case 0:
+                                if (!true) return [3 /*break*/, 9];
+                                if (!(index < buffer.length)) return [3 /*break*/, 3];
+                                return [4 /*yield*/, __await(buffer[index++])];
+                            case 1: return [4 /*yield*/, _a.sent()];
+                            case 2:
+                                _a.sent();
+                                return [3 /*break*/, 0];
+                            case 3:
+                                // If already done, exit
+                                if (done) {
+                                    return [3 /*break*/, 9];
+                                }
+                                // Fetch next chunk (synchronized)
+                                return [4 /*yield*/, __await(fetchNext())];
+                            case 4:
+                                // Fetch next chunk (synchronized)
+                                _a.sent();
+                                if (!(index < buffer.length)) return [3 /*break*/, 7];
+                                return [4 /*yield*/, __await(buffer[index++])];
+                            case 5: return [4 /*yield*/, _a.sent()];
+                            case 6:
+                                _a.sent();
+                                return [3 /*break*/, 8];
+                            case 7:
+                                if (done) {
+                                    return [3 /*break*/, 9];
+                                }
+                                _a.label = 8;
+                            case 8: return [3 /*break*/, 0];
+                            case 9: return [2 /*return*/];
+                        }
+                    });
+                });
+            })();
+        };
+        return {
+            result: this.consumeAsResult(createIterator()),
+            textStream: this.consumeAsTextStream(createIterator()),
+            fullStream: createIterator(),
+        };
+    };
+    /**
+     * Consume stream as final result (for await pattern)
+     */
+    FlinkAgent.prototype.consumeAsResult = function (stream) {
+        return __awaiter(this, void 0, void 0, function () {
+            var result, chunk, e_1_1, err_1;
+            var _a, stream_1, stream_1_1;
+            var _b, e_1, _c, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        _e.trys.push([0, 13, , 14]);
+                        _e.label = 1;
+                    case 1:
+                        _e.trys.push([1, 6, 7, 12]);
+                        _a = true, stream_1 = __asyncValues(stream);
+                        _e.label = 2;
+                    case 2: return [4 /*yield*/, stream_1.next()];
+                    case 3:
+                        if (!(stream_1_1 = _e.sent(), _b = stream_1_1.done, !_b)) return [3 /*break*/, 5];
+                        _d = stream_1_1.value;
+                        _a = false;
+                        chunk = _d;
+                        if (chunk.type === "complete") {
+                            result = chunk.result;
+                            return [3 /*break*/, 5]; // Exit early once we have the result
+                        }
+                        _e.label = 4;
+                    case 4:
+                        _a = true;
+                        return [3 /*break*/, 2];
+                    case 5: return [3 /*break*/, 12];
+                    case 6:
+                        e_1_1 = _e.sent();
+                        e_1 = { error: e_1_1 };
+                        return [3 /*break*/, 12];
+                    case 7:
+                        _e.trys.push([7, , 10, 11]);
+                        if (!(!_a && !_b && (_c = stream_1.return))) return [3 /*break*/, 9];
+                        return [4 /*yield*/, _c.call(stream_1)];
+                    case 8:
+                        _e.sent();
+                        _e.label = 9;
+                    case 9: return [3 /*break*/, 11];
+                    case 10:
+                        if (e_1) throw e_1.error;
+                        return [7 /*endfinally*/];
+                    case 11: return [7 /*endfinally*/];
+                    case 12: return [3 /*break*/, 14];
+                    case 13:
+                        err_1 = _e.sent();
+                        // If stream was already consumed or interrupted, that's okay
+                        // as long as we got the result
+                        if (!result) {
+                            throw err_1;
+                        }
+                        return [3 /*break*/, 14];
+                    case 14:
+                        if (!result) {
+                            throw new Error("Agent execution did not complete");
+                        }
+                        // Note: afterRun hook is called by AgentRunner now with full context
+                        return [2 /*return*/, result];
+                }
+            });
+        });
+    };
+    /**
+     * Consume stream as text-only stream (for simple streaming UX)
+     */
+    FlinkAgent.prototype.consumeAsTextStream = function (stream) {
+        return __asyncGenerator(this, arguments, function consumeAsTextStream_1() {
+            var _a, stream_2, stream_2_1, chunk, e_2_1;
+            var _b, e_2, _c, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        _e.trys.push([0, 7, 8, 13]);
+                        _a = true, stream_2 = __asyncValues(stream);
+                        _e.label = 1;
+                    case 1: return [4 /*yield*/, __await(stream_2.next())];
+                    case 2:
+                        if (!(stream_2_1 = _e.sent(), _b = stream_2_1.done, !_b)) return [3 /*break*/, 6];
+                        _d = stream_2_1.value;
+                        _a = false;
+                        chunk = _d;
+                        if (!(chunk.type === "text_delta")) return [3 /*break*/, 5];
+                        return [4 /*yield*/, __await(chunk.delta)];
+                    case 3: return [4 /*yield*/, _e.sent()];
+                    case 4:
+                        _e.sent();
+                        _e.label = 5;
+                    case 5:
+                        _a = true;
+                        return [3 /*break*/, 1];
+                    case 6: return [3 /*break*/, 13];
+                    case 7:
+                        e_2_1 = _e.sent();
+                        e_2 = { error: e_2_1 };
+                        return [3 /*break*/, 13];
+                    case 8:
+                        _e.trys.push([8, , 11, 12]);
+                        if (!(!_a && !_b && (_c = stream_2.return))) return [3 /*break*/, 10];
+                        return [4 /*yield*/, __await(_c.call(stream_2))];
+                    case 9:
+                        _e.sent();
+                        _e.label = 10;
+                    case 10: return [3 /*break*/, 12];
+                    case 11:
+                        if (e_2) throw e_2.error;
+                        return [7 /*endfinally*/];
+                    case 12: return [7 /*endfinally*/];
+                    case 13: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    FlinkAgent.prototype.getRunner = function () {
+        if (!this.runner) {
+            if (!this._llmAdapters) {
+                throw new Error("Agent not initialized - __init() must be called by FlinkApp");
+            }
+            // Get tools map and LLM adapters from internal properties
+            var toolsMap = this.resolveTools();
+            var llmAdapters = this._llmAdapters;
+            this.runner = new AgentRunner_1.AgentRunner(this.toAgentProps(), toolsMap, llmAdapters, this.getAgentId());
+        }
+        return this.runner;
+    };
+    /**
+     * Get agent id - uses explicit id property or falls back to kebab-case class name
+     *
+     * Examples:
+     * - CarAgent → car-agent
+     * - APIAgent → api-agent
+     * - HTMLParserAgent → html-parser-agent
+     */
+    FlinkAgent.prototype.getAgentId = function () {
+        if (this.id) {
+            return this.id;
+        }
+        // Convert class name to kebab-case using shared utility
+        return (0, utils_1.toKebabCase)(this.constructor.name);
+    };
+    FlinkAgent.prototype.toAgentProps = function () {
+        var _a, _b, _c, _d, _e, _f;
+        return {
+            id: this.getAgentId(),
+            description: this.description,
+            instructions: this.instructions,
+            tools: this.tools,
+            agents: this.agents,
+            model: this.model,
+            limits: this.limits,
+            permissions: this.permissions,
+            conversationStrategy: this.conversationStrategy,
+            debug: this.debug,
+            // Pass lifecycle hooks
+            beforeRun: (_a = this.beforeRun) === null || _a === void 0 ? void 0 : _a.bind(this),
+            onStep: (_b = this.onStep) === null || _b === void 0 ? void 0 : _b.bind(this),
+            afterRun: (_c = this.afterRun) === null || _c === void 0 ? void 0 : _c.bind(this),
+            transformSubAgentInput: (_d = this.transformSubAgentInput) === null || _d === void 0 ? void 0 : _d.bind(this),
+            onSubAgentCall: (_e = this.onSubAgentCall) === null || _e === void 0 ? void 0 : _e.bind(this),
+            onSubAgentComplete: (_f = this.onSubAgentComplete) === null || _f === void 0 ? void 0 : _f.bind(this),
+        };
+    };
+    FlinkAgent.prototype.resolveTools = function () {
+        var _this = this;
+        var toolsMap = new Map();
+        if (!this._tools) {
+            throw new Error("Agent not initialized - __init() must be called by FlinkApp");
+        }
+        var getTool = function (name) { return _this._tools[name]; };
+        // Resolve tool names/references to tool executors
+        for (var _i = 0, _a = this.tools; _i < _a.length; _i++) {
+            var toolRef = _a[_i];
+            // Handle both string IDs and tool file references (similar to agent resolution)
+            var toolId = typeof toolRef === "string" ? toolRef : toolRef.Tool.id; // Extract ID from FlinkToolFile
+            var tool = getTool(toolId);
+            if (!tool) {
+                throw new Error("Tool ".concat(toolId, " not found in context"));
+            }
+            toolsMap.set(toolId, tool);
+        }
+        // Auto-include sub-agent tools
+        if (this.agents && this.agents.length > 0) {
+            for (var _b = 0, _c = this.agents; _b < _c.length; _b++) {
+                var agentRef = _c[_b];
+                // Convert class reference to kebab-case id
+                var agentId = typeof agentRef === "string" ? agentRef : agentRef.name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+                var subAgentToolName = "ask_".concat(agentId.replace(/-/g, "_"));
+                var subAgentTool = getTool(subAgentToolName);
+                if (!subAgentTool) {
+                    throw new Error("Sub-agent tool ".concat(subAgentToolName, " not found in context for agent ").concat(agentId));
+                }
+                toolsMap.set(subAgentToolName, subAgentTool);
+            }
+        }
+        return toolsMap;
+    };
+    FlinkAgent.prototype.checkPermissionsSync = function (user, userPermissions) {
+        var perms = this.permissions;
+        if (!perms)
+            return;
+        if (typeof perms === "function") {
+            var hasPermission = perms(user);
+            if (!hasPermission) {
+                throw (0, FlinkErrors_1.forbidden)("Permission denied for agent ".concat(this.getAgentId()));
+            }
+            return;
+        }
+        if (!user) {
+            throw (0, FlinkErrors_1.forbidden)("Permission denied for agent ".concat(this.getAgentId()));
+        }
+        // Prefer userPermissions from request if available
+        var effectivePerms = userPermissions || user.permissions || [];
+        var requiredPerms = Array.isArray(perms) ? perms : [perms];
+        if (!requiredPerms.every(function (p) { return effectivePerms.includes(p); })) {
+            throw (0, FlinkErrors_1.forbidden)("Permission denied for agent ".concat(this.getAgentId()));
+        }
+    };
+    return FlinkAgent;
+}());
+exports.FlinkAgent = FlinkAgent;

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

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { FlinkContext } from "../FlinkContext";
+/**
+ * Standardized tool result format for better error handling
+ */
+export type ToolResult<T = any> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+    code?: string;
+};
+export interface FlinkToolProps {
+    /**
+     * Unique identifier for the tool (kebab-case)
+     * Used to reference the tool in agents and for registration
+     * Example: "get-cars-tool", "search-users-tool"
+     */
+    id: string;
+    description: string;
+    inputSchema: z.ZodType<any>;
+    outputSchema?: z.ZodType<any>;
+    permissions?: string | string[] | ((input: any, user?: any) => boolean | Promise<boolean>);
+}
+export interface FlinkTool<Ctx extends FlinkContext, Input = any, Output = any> {
+    (params: {
+        input: Input;
+        ctx: Ctx;
+        user?: any;
+    }): Promise<ToolResult<Output>>;
+}
+export type FlinkToolFile = {
+    default: FlinkTool<any, any, any>;
+    Tool: FlinkToolProps;
+    __file?: string;
+};

package/dist/src/ai/FlinkTool.js

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