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

package/dist/src/ai/FlinkAgent.js

@@ -0,0 +1,729 @@
+"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 FlinkErrors_1 = require("../FlinkErrors");
+var FlinkLogFactory_1 = require("../FlinkLogFactory");
+var FlinkRequestContext_1 = require("../FlinkRequestContext");
+var AgentRunner_1 = require("./AgentRunner");
+var instructionFileLoader_1 = require("./instructionFileLoader");
+var logger = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.ai.flink-agent");
+var instructionsLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.ai.instructions");
+/**
+ * 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
+ *
+ * ## Context Compaction
+ *
+ * Long-running agents can accumulate large message histories. Use context compaction
+ * to automatically manage history size during execution:
+ *
+ * ```typescript
+ * export default class MyAgent extends FlinkAgent<AppCtx> {
+ *     id = "my-agent";
+ *     description = "Agent with automatic context management";
+ *     instructions = "You are a helpful assistant...";
+ *
+ *     // Compact when history exceeds 20 messages
+ *     shouldCompact = (messages) => messages.length > 20;
+ *
+ *     // Keep only last 10 messages
+ *     compactHistory = (messages) => messages.slice(-10);
+ * }
+ * ```
+ *
+ * Compaction happens before each LLM call in the agentic loop, ensuring consistent
+ * token usage and preventing context window overflow.
+ *
+ * Example:
+ * ```typescript
+ * import { Tool as GetCarsTool } from "./tools/GetCarsTool";
+ * import * as UpdateCarTool from "./tools/UpdateCarTool";
+ *
+ * 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",      // String ID reference
+ *         GetCarsTool,          // Direct FlinkToolProps import
+ *         UpdateCarTool,        // Tool file reference
+ *     ];
+ *
+ *     // Domain-specific entry points with proper types
+ *     async searchByBrand(brand: string) {
+ *         const response = this.run({
+ *             message: `Find all ${brand} cars`
+ *         });
+ *         return await response.result;
+ *     }
+ *
+ *     async compareModels(model1: string, model2: string) {
+ *         const response = this.run({
+ *             message: `Compare ${model1} and ${model2}`
+ *         });
+ *         return await response.result;
+ *     }
+ *
+ *     // Lifecycle hook: Load conversation history
+ *     protected async beforeRun(input, context) {
+ *         if (context.conversationId) {
+ *             const conv = await this.ctx.repos.conversationRepo.getById(context.conversationId);
+ *             input.history = conv.messages;
+ *         }
+ *     }
+ * }
+ * ```
+ */
+var FlinkAgent = /** @class */ (function () {
+    function FlinkAgent() {
+    }
+    /**
+     * Internal initialization called by FlinkApp
+     * @internal
+     */
+    FlinkAgent.prototype.__init = function (llmAdapters, tools, observer) {
+        this._llmAdapters = llmAdapters;
+        this._tools = tools;
+        this._observer = observer;
+    };
+    /**
+     * 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._observer) {
+            bound._observer = this._observer;
+        }
+        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._observer) {
+            bound._observer = this._observer;
+        }
+        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._observer) {
+            bound._observer = this._observer;
+        }
+        if (this._boundUser !== undefined) {
+            bound._boundUser = this._boundUser;
+        }
+        if (this._boundUserPermissions !== undefined) {
+            bound._boundUserPermissions = this._boundUserPermissions;
+        }
+        return bound;
+    };
+    /**
+     * Bind conversation context to this agent for passing to tools
+     *
+     * This creates a new agent instance with the conversation context bound, allowing clean API:
+     * ```typescript
+     * const result = await ctx.agents.carAgent
+     *     .withUser(req.user)
+     *     .withConversationContext({ sessionId: req.session.id, featureFlags: req.flags })
+     *     .searchByBrand("Volvo");
+     * ```
+     *
+     * The bound conversation context is used for:
+     * - Passing request-scoped data to tools
+     * - Sharing state between agent and tools without polluting global context
+     * - Propagating to sub-agents automatically
+     */
+    FlinkAgent.prototype.withConversationContext = function (conversationContext) {
+        var bound = Object.create(Object.getPrototypeOf(this));
+        Object.assign(bound, this);
+        bound._boundConversationContext = conversationContext;
+        bound.runner = undefined; // Clear runner cache
+        // Copy non-enumerable properties
+        if (this.ctx) {
+            bound.ctx = this.ctx;
+        }
+        if (this._llmAdapters) {
+            bound._llmAdapters = this._llmAdapters;
+        }
+        if (this._tools) {
+            bound._tools = this._tools;
+        }
+        if (this._observer) {
+            bound._observer = this._observer;
+        }
+        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, fall back to AsyncLocalStorage request context
+        var user = (_b = (_a = input.user) !== null && _a !== void 0 ? _a : this._boundUser) !== null && _b !== void 0 ? _b : (0, FlinkRequestContext_1.getRequestUser)();
+        var userPermissions = (_d = (_c = input.userPermissions) !== null && _c !== void 0 ? _c : this._boundUserPermissions) !== null && _d !== void 0 ? _d : (_e = (0, FlinkRequestContext_1.getRequestContext)()) === null || _e === void 0 ? void 0 : _e.userPermissions;
+        var conversationContext = (_f = input.conversationContext) !== null && _f !== void 0 ? _f : this._boundConversationContext;
+        var executeInput = __assign(__assign({}, input), { user: user, userPermissions: userPermissions, conversationContext: conversationContext });
+        // Permission check
+        if (this.permissions) {
+            this.checkPermissionsSync(user, userPermissions);
+        }
+        // Build execution context
+        var execContext = {
+            agentId: this.getAgentId(),
+            conversationId: executeInput.conversationId,
+            user: user,
+            metadata: executeInput.metadata,
+            conversationContext: executeInput.conversationContext,
+        };
+        var runner = this.getRunner();
+        logger.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 beforeRunCalled = false;
+        var getBaseGenerator = function () { return __awaiter(_this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!!baseGenerator) return [3 /*break*/, 3];
+                        if (!(!beforeRunCalled && this.beforeRun)) return [3 /*break*/, 2];
+                        beforeRunCalled = true;
+                        return [4 /*yield*/, this.beforeRun(executeInput, execContext)];
+                    case 1:
+                        _a.sent();
+                        _a.label = 2;
+                    case 2:
+                        baseGenerator = runner.streamGenerator(executeInput);
+                        _a.label = 3;
+                    case 3: return [2 /*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: return [4 /*yield*/, getBaseGenerator()];
+                                    case 1:
+                                        gen = _b.sent();
+                                        return [4 /*yield*/, gen.next()];
+                                    case 2:
+                                        _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(), this.ctx, // Pass ctx to runner so callbacks can access it
+            this._observer);
+        }
+        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 () {
+        return this.id;
+    };
+    FlinkAgent.prototype.toAgentProps = function () {
+        var _this = this;
+        var _a, _b, _c, _d, _e;
+        return {
+            id: this.getAgentId(),
+            description: this.description,
+            instructions: function (ctx, agentContext) { return __awaiter(_this, void 0, void 0, function () {
+                var resolved, _a;
+                return __generator(this, function (_b) {
+                    switch (_b.label) {
+                        case 0:
+                            _a = instructionFileLoader_1.resolveInstructionsReturn;
+                            return [4 /*yield*/, Promise.resolve(this.instructions(ctx, agentContext))];
+                        case 1: return [4 /*yield*/, _a.apply(void 0, [_b.sent(), ctx, agentContext])];
+                        case 2:
+                            resolved = _b.sent();
+                            instructionsLog.debug("[".concat(this.getAgentId(), "] Resolved instructions:\n").concat(resolved));
+                            return [2 /*return*/, resolved];
+                    }
+                });
+            }); },
+            tools: this.tools,
+            model: this.model,
+            limits: this.limits,
+            permissions: this.permissions,
+            // Pass context compaction callbacks
+            shouldCompact: (_a = this.shouldCompact) === null || _a === void 0 ? void 0 : _a.bind(this),
+            compactHistory: (_b = this.compactHistory) === null || _b === void 0 ? void 0 : _b.bind(this),
+            // Pass lifecycle hooks
+            beforeRun: (_c = this.beforeRun) === null || _c === void 0 ? void 0 : _c.bind(this),
+            onStep: (_d = this.onStep) === null || _d === void 0 ? void 0 : _d.bind(this),
+            afterRun: (_e = this.afterRun) === null || _e === void 0 ? void 0 : _e.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
+        if (this.tools) {
+            for (var _i = 0, _a = this.tools; _i < _a.length; _i++) {
+                var toolRef = _a[_i];
+                // Handle string IDs, tool file references, and tool props
+                var toolId = void 0;
+                if (typeof toolRef === "string") {
+                    toolId = toolRef;
+                }
+                else if ("Tool" in toolRef) {
+                    // FlinkToolFile - extract ID from Tool property
+                    toolId = toolRef.Tool.id;
+                }
+                else {
+                    // FlinkToolProps - extract ID directly
+                    toolId = toolRef.id;
+                }
+                var tool = getTool(toolId);
+                if (!tool) {
+                    throw new Error("Tool ".concat(toolId, " not found in context"));
+                }
+                toolsMap.set(toolId, tool);
+            }
+        }
+        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;
+        }
+        // Get effective permissions (prefer explicit userPermissions)
+        var effectivePerms = userPermissions || (user === null || user === void 0 ? void 0 : user.permissions) || [];
+        // If no user and no explicit permissions, deny access
+        if (!user && !userPermissions) {
+            throw (0, FlinkErrors_1.forbidden)("Permission denied for agent ".concat(this.getAgentId()));
+        }
+        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;