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

package/src/ai/FlinkAgent.ts

@@ -0,0 +1,1069 @@
+import { FlinkContext } from "../FlinkContext";
+import { forbidden } from "../FlinkErrors";
+import { FlinkLogFactory } from "../FlinkLogFactory";
+import { getRequestContext, getRequestUser } from "../FlinkRequestContext";
+import { AgentRunner } from "./AgentRunner";
+import { FlinkToolFile, FlinkToolProps } from "./FlinkTool";
+import { resolveInstructionsReturn, type InstructionsReturn } from "./instructionFileLoader";
+export type { InstructionsReturn } from "./instructionFileLoader";
+import { LLMContentBlock, LLMMessage } from "./LLMAdapter";
+import { ToolExecutor } from "./ToolExecutor";
+
+const logger = FlinkLogFactory.createLogger("flink.ai.flink-agent");
+const instructionsLog = FlinkLogFactory.createLogger("flink.ai.instructions");
+
+/**
+ * Callback function for dynamic instruction generation
+ * Receives agent context and execution context to build custom instructions
+ *
+ * @param ctx - FlinkContext with access to repos, plugins, etc.
+ * @param agentContext - AgentExecuteContext with user, conversationId, metadata, etc.
+ * @returns Instructions string (can be async)
+ *
+ * @example
+ * const instructions = async (ctx, agentContext) => {
+ *     const profile = await ctx.repos.userRepo.getById(agentContext.user.id);
+ *     return `You are a support agent. Customer tier: ${profile.tier}`;
+ * };
+ */
+export type InstructionsCallback<Ctx extends FlinkContext> = (ctx: Ctx, agentContext: AgentExecuteContext) => Promise<string> | string;
+
+/**
+ * Agent instructions can be either a static string or a dynamic callback
+ */
+export type AgentInstructions<Ctx extends FlinkContext> = string | InstructionsCallback<Ctx>;
+
+/**
+ * Callback to determine if history compaction is needed
+ * Called before each LLM call to check if messages should be compacted
+ *
+ * @param messages - Current conversation messages
+ * @param step - Current step number (1-indexed)
+ * @returns true if compaction should be performed
+ *
+ * @example Check message count
+ * shouldCompact: (messages) => messages.length > 20
+ *
+ * @example Check total size in bytes
+ * shouldCompact: (messages) => {
+ *     const totalSize = JSON.stringify(messages).length;
+ *     return totalSize > 100_000; // ~100KB
+ * }
+ *
+ * @example Estimate token count (rough: 1 token ≈ 4 chars)
+ * shouldCompact: (messages) => {
+ *     const totalChars = messages.reduce((sum, m) => {
+ *         if (typeof m.content === 'string') return sum + m.content.length;
+ *         if (Array.isArray(m.content)) {
+ *             return sum + m.content.reduce((s, block) => {
+ *                 if (block.type === 'text') return s + block.text.length;
+ *                 if (block.type === 'tool_result') return s + JSON.stringify(block.content).length;
+ *                 return s;
+ *             }, 0);
+ *         }
+ *         return sum;
+ *     }, 0);
+ *     return totalChars > 60_000; // ~15k tokens
+ * }
+ */
+export type ShouldCompactCallback = (messages: LLMMessage[], step: number) => boolean | Promise<boolean>;
+
+/**
+ * Callback to compact conversation history
+ * Called when shouldCompact returns true
+ *
+ * @param messages - Current conversation messages to compact
+ * @param step - Current step number (1-indexed)
+ * @returns Compacted messages array (must not be empty)
+ *
+ * @example Sliding window (keep last N messages)
+ * compactHistory: (messages) => messages.slice(-10)
+ *
+ * @example Keep first message + last N (preserve initial context)
+ * compactHistory: (messages) => [messages[0], ...messages.slice(-8)]
+ *
+ * @example LLM-based summarization
+ * compactHistory: async (messages, step) => {
+ *     const oldMessages = messages.slice(0, -5);
+ *     const recentMessages = messages.slice(-5);
+ *     const summary = await this.summarize(oldMessages);
+ *     return [
+ *         { role: "user", content: `[Summary: ${summary}]` },
+ *         ...recentMessages
+ *     ];
+ * }
+ */
+export type CompactHistoryCallback = (messages: LLMMessage[], step: number) => Promise<LLMMessage[]> | LLMMessage[];
+
+export interface FlinkAgentProps<Ctx extends FlinkContext> {
+    id: string;
+    description: string;
+
+    /**
+     * Instructions that define the agent's behavior and personality.
+     * Can be a static string or a callback function that generates dynamic instructions.
+     *
+     * @example Static instructions
+     * instructions: "You are a helpful customer support agent."
+     *
+     * @example Dynamic instructions
+     * instructions: async (ctx, agentContext) => {
+     *     const user = await ctx.repos.userRepo.getById(agentContext.user.id);
+     *     return `You are a support agent. Customer: ${user.name}, Tier: ${user.tier}`;
+     * }
+     */
+    instructions: string | InstructionsCallback<Ctx>;
+
+    tools?: Array<string | FlinkToolFile | FlinkToolProps>; // Tool ids, tool file references, or tool props (validated at startup) - optional, defaults to []
+    model?: {
+        /**
+         * ID of the LLM adapter to use (must be registered in FlinkOptions.ai.llmAdapters)
+         * Examples: "anthropic", "openai", "anthropic-eu", "gpt4", etc.
+         * Defaults to "default" if not specified
+         */
+        adapterId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    limits?: {
+        maxSteps?: number; // Default: 10
+        timeoutMs?: number; // Phase 2: Not yet implemented
+    };
+    permissions?: string | string[] | ((user?: any) => boolean);
+
+    /**
+     * Callback to determine if history compaction is needed
+     * Called before each LLM call in the agentic loop
+     *
+     * When shouldCompact returns true, the framework calls compactHistory
+     * to reduce the message array size before the next LLM call
+     *
+     * If not provided, no compaction occurs (backward compatible)
+     */
+    shouldCompact?: ShouldCompactCallback;
+
+    /**
+     * Callback to compact conversation history
+     * Called when shouldCompact returns true
+     *
+     * Must return a non-empty array of messages
+     * If not provided but shouldCompact triggers, uses default strategy (keep last 10 messages)
+     */
+    compactHistory?: CompactHistoryCallback;
+
+    // Lifecycle hooks (passed from agent instance)
+    beforeRun?: (input: AgentExecuteInput<any>, context: AgentExecuteContext) => void | Promise<void>;
+    onStep?: (context: AgentStepContext) => void | Promise<void>;
+    afterRun?: (result: AgentExecuteResult, context: AgentFinishContext) => void | Promise<void>;
+}
+
+export type FlinkAgentFile<Ctx extends FlinkContext, ConversationCtx = any> = {
+    default?: new () => FlinkAgent<Ctx, ConversationCtx>; // Class extending FlinkAgent
+    __file?: string; // Set by compiler
+};
+
+/**
+ * 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;
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any> {
+    ctx!: Ctx;
+    private runner?: AgentRunner;
+    private _boundUser?: any; // User bound via withUser()
+    private _boundUserPermissions?: string[]; // User permissions bound via withPermissions()
+    private _boundConversationContext?: ConversationCtx; // Conversation context bound via withConversationContext()
+    private _llmAdapters?: Map<string, any>;
+    private _tools?: { [x: string]: ToolExecutor<Ctx> };
+    private _observer?: AgentObserver;
+
+    // Abstract properties (must be defined by subclass)
+    abstract id: string;
+    abstract description: string;
+
+    /**
+     * Define the agent's instructions. Override this method in your agent subclass.
+     *
+     * `ctx` is automatically typed as your app's context — no annotation needed.
+     *
+     * Supported return values:
+     * - `string` — Plain text used as-is
+     * - `string` ending with a known text extension (`.md`, `.txt`, `.yaml`, `.yml`, `.xml`, …) — Auto-loaded from disk (project-root-relative)
+     * - `{ file, params? }` — Explicitly load a file (any extension) with optional Handlebars template params
+     *
+     * @example Plain text
+     * instructions() {
+     *     return "You are a helpful car assistant.";
+     * }
+     *
+     * @example Dynamic instructions using ctx and agentContext
+     * async instructions(ctx, agentContext) {
+     *     const user = await ctx.repos.userRepo.getById(agentContext.user?.id);
+     *     return `You are a support agent for ${user.name}.`;
+     * }
+     *
+     * @example Auto-load file by extension (.md, .txt, .yaml, .yml, .xml, … — path relative to project root)
+     * instructions() {
+     *     return "src/agents/instructions/car-agent.md";
+     * }
+     *
+     * @example File with template params
+     * async instructions(ctx, agentContext) {
+     *     return {
+     *         file: "src/agents/instructions/support.md",
+     *         params: {
+     *             customerTier: agentContext.user?.tier || "standard",
+     *             isBusinessHours: new Date().getHours() >= 9,
+     *         },
+     *     };
+     * }
+     *
+     * @example Agent-file-relative path (use agentInstructions helper)
+     * instructions(ctx, agentContext) {
+     *     return agentInstructions("./instructions/support.md", { date: new Date() })(ctx, agentContext);
+     * }
+     */
+    abstract instructions(ctx: Ctx, agentContext: AgentExecuteContext): Promise<InstructionsReturn> | InstructionsReturn;
+
+    // Optional properties
+    tools?: Array<string | FlinkToolFile | FlinkToolProps>; // Tool ids, tool file references, or tool props (defaults to empty array)
+    model?: {
+        adapterId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    limits?: { maxSteps?: number; timeoutMs?: number };
+    permissions?: string | string[] | ((user?: any) => boolean);
+    protected shouldCompact?: ShouldCompactCallback;
+    protected compactHistory?: CompactHistoryCallback;
+
+    /**
+     * Internal initialization called by FlinkApp
+     * @internal
+     */
+    __init(llmAdapters: Map<string, any>, tools: { [x: string]: ToolExecutor<Ctx> }, observer?: AgentObserver): void {
+        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
+     */
+    withUser(user: any): this {
+        const 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.
+     */
+    withPermissions(userPermissions?: string[]): this {
+        const 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
+     */
+    withLlm(adapterId: string): this {
+        const bound = Object.create(Object.getPrototypeOf(this));
+        Object.assign(bound, this);
+        // Override the model configuration with the new adapter ID
+        bound.model = {
+            ...(this.model || {}),
+            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
+     */
+    withConversationContext(conversationContext: ConversationCtx): this {
+        const 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.
+     */
+    public run(input: AgentExecuteInput<ConversationCtx>): AgentResponse {
+        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
+     */
+    protected execute(input: AgentExecuteInput<ConversationCtx>): AgentResponse {
+        // Use bound user if not explicitly provided in input, fall back to AsyncLocalStorage request context
+        const user = input.user ?? this._boundUser ?? getRequestUser();
+        const userPermissions = input.userPermissions ?? this._boundUserPermissions ?? getRequestContext()?.userPermissions;
+        const conversationContext = input.conversationContext ?? this._boundConversationContext;
+        const executeInput = { ...input, user, userPermissions, conversationContext };
+
+        // Permission check
+        if (this.permissions) {
+            this.checkPermissionsSync(user, userPermissions);
+        }
+
+        // Build execution context
+        const execContext: AgentExecuteContext = {
+            agentId: this.getAgentId(),
+            conversationId: executeInput.conversationId,
+            user,
+            metadata: executeInput.metadata,
+            conversationContext: executeInput.conversationContext,
+        };
+
+        const runner = this.getRunner();
+        logger.debug(`Running agent ${this.constructor.name}`);
+
+        // Lazy evaluation - generator only starts when first consumed
+        let baseGenerator: AsyncGenerator<StreamChunk> | null = null;
+        const buffer: StreamChunk[] = [];
+        let done = false;
+        let fetchPromise: Promise<void> | null = null; // Prevent concurrent fetches
+        let beforeRunCalled = false;
+
+        const getBaseGenerator = async () => {
+            if (!baseGenerator) {
+                // Call optional beforeRun hook before starting generator (only once)
+                if (!beforeRunCalled && this.beforeRun) {
+                    beforeRunCalled = true;
+                    await this.beforeRun(executeInput, execContext);
+                }
+                baseGenerator = runner.streamGenerator(executeInput);
+            }
+            return baseGenerator;
+        };
+
+        // Fetch next chunk from base generator (only one consumer at a time)
+        const fetchNext = async (): Promise<void> => {
+            if (fetchPromise) {
+                // Another iterator is already fetching, wait for it
+                await fetchPromise;
+                return;
+            }
+
+            if (done) {
+                return;
+            }
+
+            fetchPromise = (async () => {
+                const gen = await getBaseGenerator();
+                const { value, done: isDone } = await gen.next();
+
+                if (isDone) {
+                    done = true;
+                } else {
+                    buffer.push(value);
+                }
+            })();
+
+            await fetchPromise;
+            fetchPromise = null;
+        };
+
+        // Create independent iterators that share buffered chunks
+        const createIterator = (): AsyncGenerator<StreamChunk> => {
+            let index = 0;
+
+            return (async function* () {
+                while (true) {
+                    // Yield buffered chunks first
+                    if (index < buffer.length) {
+                        yield buffer[index++];
+                        continue;
+                    }
+
+                    // If already done, exit
+                    if (done) {
+                        break;
+                    }
+
+                    // Fetch next chunk (synchronized)
+                    await fetchNext();
+
+                    // Check again after fetch
+                    if (index < buffer.length) {
+                        yield buffer[index++];
+                    } else if (done) {
+                        break;
+                    }
+                }
+            })();
+        };
+
+        return {
+            result: this.consumeAsResult(createIterator()),
+            textStream: this.consumeAsTextStream(createIterator()),
+            fullStream: createIterator(),
+        };
+    }
+
+    // Optional lifecycle hooks
+    /**
+     * Called before agent execution starts
+     * Use this to load conversation history, prepare context, etc.
+     *
+     * @example
+     * protected async beforeRun(input: AgentExecuteInput, context: AgentExecuteContext) {
+     *     if (input.conversationId) {
+     *         const conv = await this.ctx.repos.conversationRepo.getById(input.conversationId);
+     *         input.history = conv?.messages;
+     *     }
+     * }
+     */
+    protected beforeRun?(input: AgentExecuteInput<ConversationCtx>, context: AgentExecuteContext): void | Promise<void>;
+
+    /**
+     * Called after each step (LLM call + tool executions)
+     * Use this to save intermediate state, emit progress events, etc.
+     *
+     * @example
+     * protected async onStep(context: AgentStepContext) {
+     *     if (context.conversationId) {
+     *         await this.saveConversationState(context.conversationId, context.messages);
+     *     }
+     * }
+     */
+    protected onStep?(context: AgentStepContext): void | Promise<void>;
+
+    /**
+     * Called when agent execution completes
+     * This is where you typically save the final conversation state
+     *
+     * @example
+     * protected async afterRun(result: AgentExecuteResult, context: AgentFinishContext) {
+     *     if (context.conversationId && !context.isSubAgent) {
+     *         await this.ctx.repos.conversationRepo.save({
+     *             id: context.conversationId,
+     *             messages: context.messages,
+     *             result
+     *         });
+     *     }
+     * }
+     */
+    protected afterRun?(result: AgentExecuteResult, context: AgentFinishContext): void | Promise<void>;
+
+    /**
+     * Consume stream as final result (for await pattern)
+     */
+    private async consumeAsResult(stream: AsyncGenerator<StreamChunk>): Promise<AgentExecuteResult> {
+        let result: AgentExecuteResult | undefined;
+
+        try {
+            for await (const chunk of stream) {
+                if (chunk.type === "complete") {
+                    result = chunk.result;
+                    break; // Exit early once we have the result
+                }
+            }
+        } catch (err) {
+            // If stream was already consumed or interrupted, that's okay
+            // as long as we got the result
+            if (!result) {
+                throw err;
+            }
+        }
+
+        if (!result) {
+            throw new Error("Agent execution did not complete");
+        }
+
+        // Note: afterRun hook is called by AgentRunner now with full context
+        return result;
+    }
+
+    /**
+     * Consume stream as text-only stream (for simple streaming UX)
+     */
+    private async *consumeAsTextStream(stream: AsyncGenerator<StreamChunk>): AsyncGenerator<string> {
+        for await (const chunk of stream) {
+            if (chunk.type === "text_delta") {
+                yield chunk.delta;
+            }
+        }
+    }
+
+    private getRunner(): AgentRunner {
+        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
+            const toolsMap = this.resolveTools();
+            const llmAdapters = this._llmAdapters;
+
+            this.runner = new 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
+     */
+    private getAgentId(): string {
+        return this.id;
+    }
+
+    private toAgentProps(): FlinkAgentProps<Ctx> {
+        return {
+            id: this.getAgentId(),
+            description: this.description,
+            instructions: async (ctx, agentContext) => {
+                const resolved = await resolveInstructionsReturn(await Promise.resolve(this.instructions(ctx as Ctx, agentContext)), ctx, agentContext);
+                instructionsLog.debug(`[${this.getAgentId()}] Resolved instructions:\n${resolved}`);
+                return resolved;
+            },
+            tools: this.tools,
+            model: this.model,
+            limits: this.limits,
+            permissions: this.permissions,
+            // Pass context compaction callbacks
+            shouldCompact: this.shouldCompact?.bind(this),
+            compactHistory: this.compactHistory?.bind(this),
+            // Pass lifecycle hooks
+            beforeRun: this.beforeRun?.bind(this),
+            onStep: this.onStep?.bind(this),
+            afterRun: this.afterRun?.bind(this),
+        };
+    }
+
+    private resolveTools(): Map<string, ToolExecutor<Ctx>> {
+        const toolsMap = new Map<string, ToolExecutor<Ctx>>();
+
+        if (!this._tools) {
+            throw new Error("Agent not initialized - __init() must be called by FlinkApp");
+        }
+
+        const getTool = (name: string) => this._tools![name];
+
+        // Resolve tool names/references to tool executors
+        if (this.tools) {
+            for (const toolRef of this.tools) {
+                // Handle string IDs, tool file references, and tool props
+                let toolId: string;
+                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;
+                }
+
+                const tool = getTool(toolId);
+                if (!tool) {
+                    throw new Error(`Tool ${toolId} not found in context`);
+                }
+                toolsMap.set(toolId, tool);
+            }
+        }
+
+        return toolsMap;
+    }
+
+    private checkPermissionsSync(user?: any, userPermissions?: string[]): void {
+        const perms = this.permissions;
+        if (!perms) return;
+
+        if (typeof perms === "function") {
+            const hasPermission = perms(user);
+            if (!hasPermission) {
+                throw forbidden(`Permission denied for agent ${this.getAgentId()}`);
+            }
+            return;
+        }
+
+        // Get effective permissions (prefer explicit userPermissions)
+        const effectivePerms = userPermissions || user?.permissions || [];
+
+        // If no user and no explicit permissions, deny access
+        if (!user && !userPermissions) {
+            throw forbidden(`Permission denied for agent ${this.getAgentId()}`);
+        }
+
+        const requiredPerms = Array.isArray(perms) ? perms : [perms];
+
+        if (!requiredPerms.every((p) => effectivePerms.includes(p))) {
+            throw forbidden(`Permission denied for agent ${this.getAgentId()}`);
+        }
+    }
+}
+
+/**
+ * Execution context shared across agent lifecycle hooks
+ */
+export interface AgentExecuteContext {
+    agentId: string;
+    conversationId?: string;
+    user?: any;
+    metadata?: Record<string, any>; // Arbitrary metadata from input
+    conversationContext?: any; // Transient conversation-scoped data passed from agent to tools
+}
+
+/**
+ * Context for onStep hook - includes current conversation state
+ */
+export interface AgentStepContext extends AgentExecuteContext {
+    step: number;
+    maxSteps: number;
+    messages: LLMMessage[]; // Current conversation state (read-only)
+}
+
+/**
+ * Context for afterRun hook - includes final conversation and result
+ */
+export interface AgentFinishContext extends AgentExecuteContext {
+    messages: LLMMessage[]; // Full conversation including final turn (read-only)
+    result: AgentExecuteResult;
+}
+
+/**
+ * Message structure for agent conversations
+ * Supports both simple strings and structured message arrays
+ */
+export type Message =
+    | { role: "user"; content: string }
+    | { role: "assistant"; content: string; toolCalls?: ToolCall[] }
+    | { role: "tool"; toolCallId: string; toolName: string; result: string };
+
+export interface ToolCall {
+    id: string;
+    name: string;
+    input: any;
+}
+
+export interface AgentExecuteInput<ConversationCtx = any> {
+    message: string | LLMContentBlock[] | Message[]; // string, multimodal content blocks, or structured messages
+    user?: any;
+    userPermissions?: string[]; // Resolved permissions from auth plugin
+
+    /**
+     * Optional ID for tracking multi-turn conversations
+     * Used in lifecycle hooks (beforeRun/onStep/afterRun) to load/save conversation state
+     * @example "conv_abc123" - caller-provided ID to persist conversation history
+     */
+    conversationId?: string;
+
+    /**
+     * Transient, conversation-scoped data that flows from agent to tools
+     * Examples: session IDs, feature flags, request tracing, tenant config
+     * Typed by agent's ConversationCtx parameter
+     */
+    conversationContext?: ConversationCtx;
+
+    /**
+     * Previous conversation messages for context, in chronological order (oldest first).
+     * The new `message` will be appended after these history messages.
+     * Agent can load this in beforeRun hook based on conversationId.
+     */
+    history?: Message[];
+
+    /**
+     * Provider-specific metadata for optimizations like server-side persistence
+     *
+     * Examples:
+     * - OpenAI Responses API: `{ openai: { previousResponseId: "resp_123" } }`
+     * - Anthropic: `{ anthropic: { ... } }`
+     *
+     * When provided, adapters may use this instead of full history for better performance
+     */
+    providerMetadata?: Record<string, any>;
+
+    /**
+     * Arbitrary metadata that flows through the execution
+     * Available in all callbacks
+     */
+    metadata?: Record<string, any>;
+
+    options?: {
+        maxSteps?: number;
+        timeoutMs?: number;
+    };
+}
+
+export interface AgentExecuteResult {
+    /**
+     * Framework-generated unique ID for this agent execution.
+     * Matches the `runId` emitted in AgentObserver events, enabling apps to
+     * correlate persisted results with observer traces.
+     */
+    runId: string;
+    message: string; // Final AI response
+    toolCalls: Array<{
+        name: string;
+        input: any;
+        output: any;
+        error?: string;
+    }>;
+    stepsUsed: number;
+    usage?: import("./LLMAdapter").LLMUsage;
+    stoppedEarly: boolean; // True if max steps reached
+
+    /**
+     * Provider-specific metadata for conversation continuation
+     *
+     * Examples:
+     * - OpenAI Responses API: `{ openai: { responseId: "resp_123" } }`
+     * - Anthropic: `{ anthropic: { ... } }`
+     *
+     * Use this for next turn's `providerMetadata` input for optimized server-side history
+     */
+    providerMetadata?: Record<string, any>;
+}
+
+/**
+ * Stream chunk types for different streaming events
+ *
+ * Phase 1: Only "complete" event is emitted
+ * Phase 2: Will emit real-time "text_delta", "tool_call_start", and "tool_call_result" events
+ */
+export type StreamChunk =
+    | { type: "text_delta"; delta: string } // Phase 2: Stream text as it's generated
+    | { type: "tool_call_start"; toolCall: ToolCall } // Phase 2: Tool execution started
+    | {
+          type: "tool_call_result"; // Phase 2: Tool execution completed
+          toolCall: ToolCall;
+          output: any;
+          error?: string;
+      }
+    | { type: "complete"; result: AgentExecuteResult }; // Phase 1: Final result only
+
+/**
+ * Unified response that supports both awaiting and streaming
+ */
+export interface AgentResponse {
+    result: Promise<AgentExecuteResult>; // Await for final result
+    textStream: AsyncGenerator<string>; // Stream only text deltas
+    fullStream: AsyncGenerator<StreamChunk>; // Stream all events
+}
+
+/**
+ * Event fired once per agent execution, before the first LLM call.
+ * Contains the resolved system instructions and the initial message array
+ * (post-history, pre-compaction, pre-tool-filtering).
+ */
+export interface AgentObserverRunEvent {
+    runId: string;
+    agentId: string;
+    instructions: string;
+    input: AgentExecuteInput;
+    messages: LLMMessage[];
+    tools: string[];
+    model: { adapterId?: string; maxTokens?: number; temperature?: number };
+    context: AgentExecuteContext;
+}
+
+/**
+ * Event fired immediately before each LLM call in the agentic loop.
+ * Reflects the messages and tools actually sent to the model after
+ * compaction and per-step permission filtering.
+ */
+export interface AgentObserverLlmCallEvent {
+    runId: string;
+    agentId: string;
+    step: number;
+    maxSteps: number;
+    instructions: string;
+    messages: LLMMessage[];
+    tools: string[];
+    model: { adapterId?: string; maxTokens?: number; temperature?: number };
+    context: AgentExecuteContext;
+}
+
+/**
+ * Event fired after each step (LLM call + tool executions) completes.
+ * `toolCalls` contains only the tool calls executed during this step.
+ */
+export interface AgentObserverStepEvent {
+    runId: string;
+    agentId: string;
+    step: number;
+    maxSteps: number;
+    messages: LLMMessage[];
+    assistantText?: string;
+    toolCalls: AgentExecuteResult["toolCalls"];
+    usage?: import("./LLMAdapter").LLMUsage;
+    context: AgentExecuteContext;
+}
+
+/**
+ * Event fired when an agent execution completes (successfully or with error).
+ * On error, `result` contains whatever was accumulated before the throw.
+ */
+export interface AgentObserverFinishEvent {
+    runId: string;
+    agentId: string;
+    result: AgentExecuteResult;
+    messages: LLMMessage[];
+    durationMs: number;
+    error?: string;
+    context: AgentExecuteContext;
+}
+
+/**
+ * Global agent observer for app-level tracing, APM, cost accounting, dev tools, etc.
+ *
+ * Register once on `FlinkOptions.ai.observer`; fires for every agent execution in the app.
+ *
+ * Observer callbacks are invoked fire-and-forget: they may return a Promise but the
+ * framework does not await them, and any thrown/rejected errors are caught and logged
+ * without affecting agent execution. Observers are read-only — they must not mutate
+ * inputs, messages, or results. Use the per-agent `beforeRun`/`onStep`/`afterRun` hooks
+ * for business logic that needs to block or mutate.
+ *
+ * Typical use cases:
+ * - Persisted traces for a dev tools page (correlate via `context.metadata`)
+ * - OpenTelemetry / Sentry integration
+ * - Cost accounting and token-usage dashboards
+ *
+ * All events share a stable `runId` per execution so persisted records can be joined
+ * across events. The same `runId` is returned on `AgentExecuteResult.runId`.
+ */
+export interface AgentObserver {
+    onRun?(event: AgentObserverRunEvent): void | Promise<void>;
+    onLlmCall?(event: AgentObserverLlmCallEvent): void | Promise<void>;
+    onStep?(event: AgentObserverStepEvent): void | Promise<void>;
+    onFinish?(event: AgentObserverFinishEvent): void | Promise<void>;
+}