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

package/src/ai/FlinkAgent.ts

@@ -0,0 +1,770 @@
+import { FlinkContext } from "../FlinkContext";
+import { log } from "../FlinkLog";
+import { toKebabCase } from "../utils";
+import { AgentRunner } from "./AgentRunner";
+import { LLMMessage } from "./LLMAdapter";
+import { FlinkToolFile } from "./FlinkTool";
+import { ToolExecutor } from "./ToolExecutor";
+import { forbidden } from "../FlinkErrors";
+
+export interface FlinkAgentProps {
+    id?: string; // Optional agent id (defaults to kebab-case class name if not provided)
+    description: string;
+
+    /**
+     * Instructions that define the agent's behavior and personality.
+     * Converted to a system message and prepended to the conversation.
+     * Follows Vercel AI SDK pattern.
+     *
+     * @example "You are a helpful customer support agent for Acme Corp."
+     */
+    instructions: string;
+
+    tools: Array<string | FlinkToolFile>; // Tool ids or tool file references (validated at startup)
+    agents?: Array<string | (new () => FlinkAgent<any>)>; // Sub-agent ids or class references (validated at startup, auto-converted to tools)
+    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
+        maxSubAgentDepth?: number; // Default: 5 - prevents infinite sub-agent recursion
+    };
+    permissions?: string | string[] | ((user?: any) => boolean);
+    /**
+     * How this agent handles conversations when called as a sub-agent
+     * - "inherit": Use parent's conversationId (default) - saves to parent's conversation
+     * - "independent": Create own nested conversation for detailed tracking
+     * - "none": Don't track conversations
+     */
+    conversationStrategy?: "inherit" | "independent" | "none";
+    /**
+     * Enable verbose debug logging for this agent
+     * When true, logs detailed information about:
+     * - Full LLM requests (messages, tools, parameters)
+     * - Full LLM responses (text, tool calls)
+     * - Tool execution details (input, output, errors)
+     * - Conversation state changes
+     *
+     * Useful for debugging tool calling issues and understanding agent behavior
+     */
+    debug?: boolean;
+
+    // Lifecycle hooks (passed from agent instance)
+    beforeRun?: (input: AgentExecuteInput, context: AgentExecuteContext) => void | Promise<void>;
+    onStep?: (context: AgentStepContext) => void | Promise<void>;
+    afterRun?: (result: AgentExecuteResult, context: AgentFinishContext) => void | Promise<void>;
+    transformSubAgentInput?: (subAgentId: string, input: any, context: AgentExecuteContext) => any | Promise<any>;
+    onSubAgentCall?: (subAgentId: string, input: any, context: AgentExecuteContext) => void | Promise<void>;
+    onSubAgentComplete?: (subAgentId: string, result: AgentExecuteResult, context: AgentExecuteContext) => void | Promise<void>;
+}
+
+export type FlinkAgentFile = {
+    Agent?: FlinkAgentProps; // Old pattern: declarative props (deprecated)
+    default?: new () => FlinkAgent<any>; // New pattern: 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
+ * - `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}` };
+ *     }
+ * }
+ * ```
+ */
+export abstract class FlinkAgent<Ctx extends FlinkContext> {
+    ctx!: Ctx;
+    private runner?: AgentRunner;
+    private _boundUser?: any; // User bound via withUser()
+    private _boundUserPermissions?: string[]; // User permissions bound via withPermissions()
+    private _llmAdapters?: Map<string, any>;
+    private _tools?: { [x: string]: ToolExecutor<Ctx> };
+
+    // Abstract properties (must be defined by subclass)
+    abstract description: string;
+    abstract instructions: string;
+    abstract tools: Array<string | FlinkToolFile>; // Tool ids or tool file references
+
+    // Optional properties
+    id?: string; // Optional agent id (defaults to kebab-case class name if not provided)
+    agents?: Array<string | (new () => FlinkAgent<any>)>; // Sub-agent ids or class references (auto-converted to special tools)
+    model?: {
+        adapterId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    limits?: { maxSteps?: number; timeoutMs?: number; maxSubAgentDepth?: number };
+    permissions?: string | string[] | ((user?: any) => boolean);
+    conversationStrategy?: "inherit" | "independent" | "none"; // How to handle conversations as sub-agent
+    debug?: boolean; // Enable verbose debug logging
+
+    /**
+     * Internal initialization called by FlinkApp
+     * @internal
+     */
+    __init(llmAdapters: Map<string, any>, tools: { [x: string]: ToolExecutor<Ctx> }): void {
+        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
+     */
+    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._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._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._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): 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): AgentResponse {
+        // Use bound user if not explicitly provided in input
+        const user = input.user ?? this._boundUser;
+        const userPermissions = input.userPermissions ?? this._boundUserPermissions;
+        const executeInput = { ...input, user, userPermissions };
+
+        // Permission check
+        if (this.permissions) {
+            this.checkPermissionsSync(user, userPermissions);
+        }
+
+        // Build execution context
+        const execContext: AgentExecuteContext = {
+            agentId: this.getAgentId(),
+            conversationId: executeInput.conversationId,
+            user,
+            isSubAgent: executeInput.metadata?.isSubAgentCall === true,
+            parentAgentId: executeInput.metadata?.parentAgentId,
+            subAgentDepth: executeInput.metadata?.subAgentDepth ?? 0,
+            metadata: executeInput.metadata,
+        };
+
+        // Call optional beforeRun hook with context
+        if (this.beforeRun) {
+            const 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
+            }
+        }
+
+        const runner = this.getRunner();
+        log.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
+
+        const getBaseGenerator = () => {
+            if (!baseGenerator) {
+                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 = 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, 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>;
+
+    /**
+     * Transform/compact input before sending to sub-agent
+     * Parent agent can summarize context, add briefings, or modify the query
+     *
+     * Return value becomes the new input sent to the sub-agent
+     *
+     * @example
+     * protected async transformSubAgentInput(subAgentId: string, input: any, context: AgentExecuteContext) {
+     *     // Load parent conversation
+     *     const messages = await this.loadConversation(context.conversationId);
+     *
+     *     // Summarize relevant context
+     *     const summary = this.compactContext(messages, subAgentId);
+     *
+     *     // Add briefing to query
+     *     return {
+     *         ...input,
+     *         query: `Context: ${summary}\n\nQuery: ${input.query}`
+     *     };
+     * }
+     */
+    protected transformSubAgentInput?(subAgentId: string, input: any, context: AgentExecuteContext): any | Promise<any>;
+
+    /**
+     * Called when a sub-agent is about to be invoked (after transformSubAgentInput)
+     * Parent agent can log, or track the delegation
+     * Cannot modify input - use transformSubAgentInput for that
+     */
+    protected onSubAgentCall?(subAgentId: string, input: any, context: AgentExecuteContext): void | Promise<void>;
+
+    /**
+     * Called after sub-agent completes
+     * Parent agent can process the result, track metrics, etc.
+     */
+    protected onSubAgentComplete?(subAgentId: string, result: AgentExecuteResult, context: AgentExecuteContext): 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());
+        }
+        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 {
+        if (this.id) {
+            return this.id;
+        }
+        // Convert class name to kebab-case using shared utility
+        return toKebabCase(this.constructor.name);
+    }
+
+    private toAgentProps(): FlinkAgentProps {
+        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: this.beforeRun?.bind(this),
+            onStep: this.onStep?.bind(this),
+            afterRun: this.afterRun?.bind(this),
+            transformSubAgentInput: this.transformSubAgentInput?.bind(this),
+            onSubAgentCall: this.onSubAgentCall?.bind(this),
+            onSubAgentComplete: this.onSubAgentComplete?.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
+        for (const toolRef of this.tools) {
+            // Handle both string IDs and tool file references (similar to agent resolution)
+            const toolId = typeof toolRef === "string" ? toolRef : toolRef.Tool.id; // Extract ID from FlinkToolFile
+
+            const tool = getTool(toolId);
+            if (!tool) {
+                throw new Error(`Tool ${toolId} not found in context`);
+            }
+            toolsMap.set(toolId, tool);
+        }
+
+        // Auto-include sub-agent tools
+        if (this.agents && this.agents.length > 0) {
+            for (const agentRef of this.agents) {
+                // Convert class reference to kebab-case id
+                const agentId = typeof agentRef === "string" ? agentRef : agentRef.name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+
+                const subAgentToolName = `ask_${agentId.replace(/-/g, "_")}`;
+                const subAgentTool = getTool(subAgentToolName);
+                if (!subAgentTool) {
+                    throw new Error(`Sub-agent tool ${subAgentToolName} not found in context for agent ${agentId}`);
+                }
+                toolsMap.set(subAgentToolName, subAgentTool);
+            }
+        }
+
+        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;
+        }
+
+        if (!user) {
+            throw forbidden(`Permission denied for agent ${this.getAgentId()}`);
+        }
+
+        // Prefer userPermissions from request if available
+        const effectivePerms = userPermissions || user.permissions || [];
+
+        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;
+    isSubAgent: boolean; // True if this is a sub-agent call
+    parentAgentId?: string; // ID of parent agent if sub-agent
+    subAgentDepth: number; // Current depth in sub-agent call chain (0 for root)
+    metadata?: Record<string, any>; // Arbitrary metadata from input
+}
+
+/**
+ * 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 {
+    message: string | Message[]; // Accept either simple string or structured messages
+    user?: any;
+    userPermissions?: string[]; // Resolved permissions from auth plugin
+
+    conversationId?: string; // Optional ID for tracking conversations
+
+    /**
+     * Previous conversation messages for context
+     * Agent can load this in beforeRun hook based on conversationId
+     */
+    history?: Message[];
+
+    /**
+     * Arbitrary metadata that flows through the execution
+     * Available in all callbacks
+     */
+    metadata?: Record<string, any>;
+
+    options?: { maxSteps?: number; timeoutMs?: number };
+}
+
+export interface AgentExecuteResult {
+    message: string; // Final AI response
+    toolCalls: Array<{
+        name: string;
+        input: any;
+        output: any;
+        error?: string;
+        isAgentCall?: boolean; // True if this was a sub-agent delegation
+        agentId?: string; // ID of the sub-agent that was called
+    }>;
+    stepsUsed: number;
+    usage?: { inputTokens: number; outputTokens: number };
+    stoppedEarly: boolean; // True if max steps reached
+    subAgentCalls?: Array<{
+        agentId: string;
+        input: any;
+        result: AgentExecuteResult; // Nested result from sub-agent
+    }>;
+}
+
+/**
+ * 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: "agent_call_start"; agentId: string; input: any } // Sub-agent started
+    | { type: "agent_call_result"; agentId: string; result: AgentExecuteResult } // Sub-agent completed
+    | { 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
+}