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

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

@@ -0,0 +1,446 @@
+import { FlinkContext } from "../FlinkContext";
+import { LLMMessage } from "./LLMAdapter";
+import { FlinkToolFile } from "./FlinkTool";
+import { ToolExecutor } from "./ToolExecutor";
+export interface FlinkAgentProps {
+    id?: string;
+    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>;
+    agents?: Array<string | (new () => FlinkAgent<any>)>;
+    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;
+        timeoutMs?: number;
+        maxSubAgentDepth?: number;
+    };
+    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;
+    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;
+    default?: new () => FlinkAgent<any>;
+    __file?: string;
+};
+/**
+ * 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 declare abstract class FlinkAgent<Ctx extends FlinkContext> {
+    ctx: Ctx;
+    private runner?;
+    private _boundUser?;
+    private _boundUserPermissions?;
+    private _llmAdapters?;
+    private _tools?;
+    abstract description: string;
+    abstract instructions: string;
+    abstract tools: Array<string | FlinkToolFile>;
+    id?: string;
+    agents?: Array<string | (new () => FlinkAgent<any>)>;
+    model?: {
+        adapterId?: string;
+        maxTokens?: number;
+        temperature?: number;
+    };
+    limits?: {
+        maxSteps?: number;
+        timeoutMs?: number;
+        maxSubAgentDepth?: number;
+    };
+    permissions?: string | string[] | ((user?: any) => boolean);
+    conversationStrategy?: "inherit" | "independent" | "none";
+    debug?: boolean;
+    /**
+     * Internal initialization called by FlinkApp
+     * @internal
+     */
+    __init(llmAdapters: Map<string, any>, tools: {
+        [x: string]: ToolExecutor<Ctx>;
+    }): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    run(input: AgentExecuteInput): AgentResponse;
+    /**
+     * 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;
+    /**
+     * 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 consumeAsResult;
+    /**
+     * Consume stream as text-only stream (for simple streaming UX)
+     */
+    private consumeAsTextStream;
+    private getRunner;
+    /**
+     * 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;
+    private toAgentProps;
+    private resolveTools;
+    private checkPermissionsSync;
+}
+/**
+ * Execution context shared across agent lifecycle hooks
+ */
+export interface AgentExecuteContext {
+    agentId: string;
+    conversationId?: string;
+    user?: any;
+    isSubAgent: boolean;
+    parentAgentId?: string;
+    subAgentDepth: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Context for onStep hook - includes current conversation state
+ */
+export interface AgentStepContext extends AgentExecuteContext {
+    step: number;
+    maxSteps: number;
+    messages: LLMMessage[];
+}
+/**
+ * Context for afterRun hook - includes final conversation and result
+ */
+export interface AgentFinishContext extends AgentExecuteContext {
+    messages: LLMMessage[];
+    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[];
+    user?: any;
+    userPermissions?: string[];
+    conversationId?: string;
+    /**
+     * 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;
+    toolCalls: Array<{
+        name: string;
+        input: any;
+        output: any;
+        error?: string;
+        isAgentCall?: boolean;
+        agentId?: string;
+    }>;
+    stepsUsed: number;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    stoppedEarly: boolean;
+    subAgentCalls?: Array<{
+        agentId: string;
+        input: any;
+        result: AgentExecuteResult;
+    }>;
+}
+/**
+ * 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;
+} | {
+    type: "tool_call_start";
+    toolCall: ToolCall;
+} | {
+    type: "tool_call_result";
+    toolCall: ToolCall;
+    output: any;
+    error?: string;
+} | {
+    type: "agent_call_start";
+    agentId: string;
+    input: any;
+} | {
+    type: "agent_call_result";
+    agentId: string;
+    result: AgentExecuteResult;
+} | {
+    type: "complete";
+    result: AgentExecuteResult;
+};
+/**
+ * Unified response that supports both awaiting and streaming
+ */
+export interface AgentResponse {
+    result: Promise<AgentExecuteResult>;
+    textStream: AsyncGenerator<string>;
+    fullStream: AsyncGenerator<StreamChunk>;
+}