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

package/src/TypeScriptUtils.ts

@@ -214,6 +214,11 @@ export function getTypeMetadata(type: Type<ts.Type>) {
         return [];
     }
 
+    // Handle empty object literal {} (used in streaming handlers)
+    if (type.getText() === "{}") {
+        return [];
+    }
+
     const symbol = getSymbolOrAlias(type);
 
     if (!symbol) {

package/src/ai/AgentRunner.ts

@@ -0,0 +1,646 @@
+import { v4 as uuidv4 } from "uuid";
+import {
+    FlinkAgentProps,
+    AgentExecuteResult,
+    AgentExecuteInput,
+    StreamChunk,
+    Message,
+    AgentExecuteContext,
+    AgentStepContext,
+    AgentFinishContext,
+    AgentObserver,
+} from "./FlinkAgent";
+import { ToolExecutor } from "./ToolExecutor";
+import { LLMAdapter, LLMMessage, LLMContentBlock, FlinkToolSchema } from "./LLMAdapter";
+import { FlinkLogFactory } from "../FlinkLogFactory";
+import { log } from "../FlinkLog";
+
+const observerLog = FlinkLogFactory.createLogger("flink.ai.observer");
+
+export class AgentRunner {
+    private llmAdapter: LLMAdapter;
+    private maxTokens: number;
+    private temperature: number;
+    private maxSteps: number;
+    private timeoutMs: number;
+
+    constructor(
+        private agentProps: FlinkAgentProps<any>,
+        private tools: Map<string, ToolExecutor<any>>,
+        llmAdapters: Map<string, LLMAdapter>,
+        private agentName?: string, // Optional agent name for logging
+        private ctx?: any, // FlinkContext for instruction callbacks (any for flexibility)
+        private observer?: AgentObserver
+    ) {
+        // Get appropriate LLM adapter based on adapterId
+        const adapterId = agentProps.model?.adapterId || "default";
+
+        const adapter = llmAdapters.get(adapterId);
+        if (!adapter) {
+            throw new Error(`LLM adapter "${adapterId}" not configured - register it in FlinkOptions.ai.llms`);
+        }
+
+        this.llmAdapter = adapter;
+        this.maxTokens = agentProps.model?.maxTokens || 4096;
+        this.temperature = agentProps.model?.temperature || 0.7;
+        this.maxSteps = agentProps.limits?.maxSteps || 10;
+        this.timeoutMs = agentProps.limits?.timeoutMs || 60000;
+    }
+
+    async *streamGenerator(input: AgentExecuteInput): AsyncGenerator<StreamChunk> {
+        const maxSteps = input.options?.maxSteps || this.maxSteps;
+        const toolCalls: AgentExecuteResult["toolCalls"] = [];
+        const runId = uuidv4();
+        const runStartedAt = Date.now();
+        const agentId = this.agentName || "unknown";
+        const modelInfo = {
+            adapterId: this.agentProps.model?.adapterId,
+            maxTokens: this.maxTokens,
+            temperature: this.temperature,
+        };
+        const declaredToolNames = Array.from(this.tools.keys());
+
+        // Build execution context
+        const execContext: AgentExecuteContext = {
+            agentId,
+            conversationId: input.conversationId,
+            user: input.user,
+            metadata: input.metadata,
+            conversationContext: input.conversationContext,
+        };
+
+        // Resolve instructions (callback or string)
+        let resolvedInstructions: string;
+        try {
+            resolvedInstructions =
+                typeof this.agentProps.instructions === "function" ? await this.agentProps.instructions(this.ctx, execContext) : this.agentProps.instructions;
+        } catch (err: any) {
+            throw new Error(`Failed to resolve instructions for agent ${this.agentName}: ${err.message}`);
+        }
+
+        // Initialize messages from history + new input
+        let messages: LLMMessage[];
+
+        if (input.history && input.history.length > 0) {
+            // Start with history
+            messages = this.convertMessages(input.history);
+        } else {
+            messages = [];
+        }
+
+        // Add new user message
+        if (typeof input.message === "string") {
+            messages.push({ role: "user", content: input.message });
+        } else if (Array.isArray(input.message) && input.message.length > 0 && "type" in input.message[0]) {
+            // LLMContentBlock[] — multimodal content (e.g. text + images)
+            messages.push({ role: "user", content: input.message as LLMContentBlock[] });
+        } else {
+            messages.push(...this.convertMessages(input.message as Message[]));
+        }
+
+        // Dispatch observer onRun (pre-loop, before compaction / tool filtering)
+        this.safeDispatch("onRun", () =>
+            this.observer?.onRun?.({
+                runId,
+                agentId,
+                instructions: resolvedInstructions,
+                input,
+                messages: [...messages],
+                tools: declaredToolNames,
+                model: modelInfo,
+                context: execContext,
+            })
+        );
+
+        let step = 0;
+        let finalMessage = "";
+        let stoppedEarly = false;
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalCachedInputTokens = 0;
+        let totalCacheCreationInputTokens = 0;
+        let finalProviderMetadata: Record<string, any> = {};
+
+        const buildResult = (): AgentExecuteResult => ({
+            runId,
+            message: finalMessage,
+            toolCalls,
+            stepsUsed: step,
+            stoppedEarly,
+            usage: {
+                inputTokens: totalInputTokens,
+                outputTokens: totalOutputTokens,
+                ...(totalCachedInputTokens > 0 && { cachedInputTokens: totalCachedInputTokens }),
+                ...(totalCacheCreationInputTokens > 0 && { cacheCreationInputTokens: totalCacheCreationInputTokens }),
+            },
+            providerMetadata: Object.keys(finalProviderMetadata).length > 0 ? finalProviderMetadata : undefined,
+        });
+
+        try {
+        while (step < maxSteps) {
+            step++;
+
+            // Filter tools based on user permissions (only show allowed tools to LLM)
+            const availableTools = await this.filterToolsByPermissions(input.user, input.userPermissions, input.conversationContext);
+
+            // Check if context compaction is needed
+            if (this.agentProps.shouldCompact) {
+                try {
+                    const needsCompaction = await this.agentProps.shouldCompact(messages, step);
+
+                    if (needsCompaction) {
+                        const beforeCount = messages.length;
+                        const originalMessages = messages; // Save original in case of error
+
+                        // Perform compaction using provided callback or default strategy
+                        let compactedMessages: LLMMessage[];
+                        if (this.agentProps.compactHistory) {
+                            compactedMessages = await this.agentProps.compactHistory(messages, step);
+                        } else {
+                            // Default strategy: sliding window keeping last 10 messages
+                            compactedMessages = messages.slice(-10);
+                        }
+
+                        // Validation: ensure compacted array is not empty
+                        if (!compactedMessages || compactedMessages.length === 0) {
+                            throw new Error("compactHistory must return at least one message");
+                        }
+
+                        // Apply compaction
+                        messages = compactedMessages;
+
+                        // Log compaction for debugging
+                        log.debug(`[Agent:${this.agentName}] Step ${step}: Compacted ${beforeCount} messages → ${messages.length}`);
+
+                        log.debug(`[Agent:${this.agentName}] Compacted messages:`, {
+                            messageCount: messages.length,
+                            messages: messages.map((m) => ({
+                                role: m.role,
+                                contentPreview:
+                                    typeof m.content === "string"
+                                        ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
+                                        : `${(m.content as any[]).length} blocks`,
+                            })),
+                        });
+                    }
+                } catch (error: any) {
+                    // Log error but don't fail execution - compaction is optional optimization
+                    log.error(`[Agent:${this.agentName}] Context compaction failed:`, error.message);
+                }
+            }
+
+            log.debug(`[Agent:${this.agentName}] Step ${step}/${maxSteps} - Calling LLM with:`, {
+                instructionsType: typeof this.agentProps.instructions === "function" ? "dynamic-callback" : "static",
+                messageCount: messages.length,
+                messages: messages.map((m) => ({
+                    role: m.role,
+                    contentPreview:
+                        typeof m.content === "string"
+                            ? m.content.substring(0, 100) + (m.content.length > 100 ? "..." : "")
+                            : `${(m.content as any[]).length} blocks`,
+                })),
+                toolCount: availableTools.length,
+                tools: availableTools.map((t) => t.name),
+                maxTokens: this.maxTokens,
+                temperature: this.temperature,
+            });
+
+            // Dispatch observer onLlmCall — messages reflect post-compaction state;
+            // tools reflect per-step permission filtering
+            this.safeDispatch("onLlmCall", () =>
+                this.observer?.onLlmCall?.({
+                    runId,
+                    agentId,
+                    step,
+                    maxSteps,
+                    instructions: resolvedInstructions,
+                    messages: [...messages],
+                    tools: availableTools.map((t) => t.name),
+                    model: modelInfo,
+                    context: execContext,
+                })
+            );
+
+            // Track tool call count before this step so we can slice the per-step
+            // tool calls for the onStep observer event
+            const toolCallsBeforeStep = toolCalls.length;
+
+            // Call AI model via adapter using streaming
+            const llmStream = this.llmAdapter.stream({
+                instructions: resolvedInstructions,
+                messages,
+                tools: availableTools,
+                maxTokens: this.maxTokens,
+                temperature: this.temperature,
+                providerMetadata: input.providerMetadata,
+            });
+
+            // Accumulate response from stream
+            let textContent = "";
+            const toolCallsFromStream: Array<{ id: string; name: string; input: any }> = [];
+            let usage: import("./LLMAdapter").LLMUsage = { inputTokens: 0, outputTokens: 0 };
+            let stopReason: "end_turn" | "tool_use" | "max_tokens" = "end_turn";
+            let providerMetadata: Record<string, any> = {};
+
+            // Process streaming chunks
+            for await (const chunk of llmStream) {
+                switch (chunk.type) {
+                    case "text":
+                        textContent += chunk.delta;
+                        // Yield text_delta event in real-time
+                        yield { type: "text_delta", delta: chunk.delta };
+                        break;
+
+                    case "tool_call":
+                        toolCallsFromStream.push(chunk.toolCall);
+                        break;
+
+                    case "usage":
+                        usage = chunk.usage;
+                        totalInputTokens += chunk.usage.inputTokens;
+                        totalOutputTokens += chunk.usage.outputTokens;
+                        totalCachedInputTokens += chunk.usage.cachedInputTokens || 0;
+                        totalCacheCreationInputTokens += chunk.usage.cacheCreationInputTokens || 0;
+                        break;
+
+                    case "metadata":
+                        // Merge provider metadata (e.g., responseId for continuation)
+                        providerMetadata = { ...providerMetadata, ...chunk.metadata };
+                        finalProviderMetadata = { ...finalProviderMetadata, ...chunk.metadata };
+                        break;
+
+                    case "done":
+                        stopReason = chunk.stopReason as "end_turn" | "tool_use" | "max_tokens";
+                        break;
+                }
+            }
+
+            // Create llmResponse structure for compatibility with existing code
+            const llmResponse = {
+                textContent: textContent || undefined,
+                toolCalls: toolCallsFromStream,
+                usage,
+                stopReason,
+            };
+
+            log.debug(`[Agent:${this.agentName}] Step ${step} - LLM Response:`, {
+                textLength: llmResponse.textContent?.length || 0,
+                textPreview: llmResponse.textContent?.substring(0, 200) + (llmResponse.textContent && llmResponse.textContent.length > 200 ? "..." : ""),
+                toolCallsCount: llmResponse.toolCalls.length,
+                toolCalls: llmResponse.toolCalls.map((tc) => ({
+                    name: tc.name,
+                    inputKeys: Object.keys(tc.input),
+                    input: tc.input,
+                })),
+                stopReason: llmResponse.stopReason,
+                usage: llmResponse.usage,
+            });
+
+            // Extract text response
+            if (llmResponse.textContent) {
+                finalMessage = llmResponse.textContent;
+            }
+
+            // Build assistant message
+            const assistantContent: LLMContentBlock[] = [];
+
+            if (llmResponse.textContent) {
+                assistantContent.push({
+                    type: "text",
+                    text: llmResponse.textContent,
+                });
+            }
+
+            for (const toolCall of llmResponse.toolCalls) {
+                assistantContent.push({
+                    type: "tool_use",
+                    id: toolCall.id,
+                    name: toolCall.name,
+                    input: toolCall.input,
+                });
+            }
+
+            messages.push({
+                role: "assistant",
+                content: assistantContent,
+            });
+
+            // Check for tool calls - if none, we're done after calling onStep
+            if (llmResponse.toolCalls.length === 0) {
+                // Call onStep hook before breaking
+                if (this.agentProps.onStep) {
+                    const stepContext: AgentStepContext = {
+                        ...execContext,
+                        step,
+                        maxSteps,
+                        messages: [...messages],
+                    };
+                    await this.agentProps.onStep(stepContext);
+                }
+                // Dispatch observer onStep (no tool calls executed this step)
+                this.safeDispatch("onStep", () =>
+                    this.observer?.onStep?.({
+                        runId,
+                        agentId,
+                        step,
+                        maxSteps,
+                        messages: [...messages],
+                        assistantText: llmResponse.textContent,
+                        toolCalls: toolCalls.slice(toolCallsBeforeStep),
+                        usage,
+                        context: execContext,
+                    })
+                );
+                break; // No more tool calls - done
+            }
+
+            // Execute all tool calls
+            const toolResults: LLMContentBlock[] = [];
+
+            for (const toolCall of llmResponse.toolCalls) {
+                const toolExecutor = this.tools.get(toolCall.name);
+                let toolOutput: any;
+                let toolError: string | undefined;
+
+                log.debug(`[Agent:${this.agentName}] Executing tool '${toolCall.name}':`, {
+                    input: toolCall.input,
+                    inputSize: JSON.stringify(toolCall.input).length,
+                });
+
+                try {
+                    if (!toolExecutor) {
+                        throw new Error(`Tool ${toolCall.name} not found`);
+                    }
+
+                    // Yield tool_call_start event
+                    yield {
+                        type: "tool_call_start",
+                        toolCall: {
+                            id: toolCall.id,
+                            name: toolCall.name,
+                            input: toolCall.input,
+                        },
+                    };
+
+                    // Execute tool
+                    const toolResult = await toolExecutor.execute(toolCall.input, {
+                        user: input.user,
+                        permissions: input.userPermissions,
+                        conversationContext: input.conversationContext,
+                    });
+
+                    // Format result for AI using new ToolResult format
+                    const formattedResult = toolExecutor.formatResultForAI(toolResult);
+
+                    toolResults.push({
+                        type: "tool_result",
+                        tool_use_id: toolCall.id,
+                        content: formattedResult,
+                        is_error: !toolResult.success,
+                    });
+
+                    // Yield tool_call_result event
+                    yield {
+                        type: "tool_call_result",
+                        toolCall: {
+                            id: toolCall.id,
+                            name: toolCall.name,
+                            input: toolCall.input,
+                        },
+                        output: toolResult.success ? toolResult.data : null,
+                        error: toolResult.success ? undefined : toolResult.error,
+                    };
+
+                    toolCalls.push({
+                        name: toolCall.name,
+                        input: toolCall.input,
+                        output: toolResult.success ? toolResult.data : null,
+                        error: toolResult.success ? undefined : toolResult.error,
+                    });
+
+                    log.debug(`[Agent:${this.agentName}] Tool '${toolCall.name}' ${toolResult.success ? "succeeded" : "failed"}:`, {
+                        success: toolResult.success,
+                        outputSize: toolResult.success ? JSON.stringify(toolResult.data).length : 0,
+                        outputPreview: toolResult.success
+                            ? JSON.stringify(toolResult.data).substring(0, 200) + (JSON.stringify(toolResult.data).length > 200 ? "..." : "")
+                            : toolResult.error,
+                        code: (toolResult as any).code,
+                    });
+
+                    if (!toolResult.success) {
+                        log.warn(`Tool ${toolCall.name} returned error:`, toolResult.error);
+                    }
+                } catch (err: any) {
+                    // Unexpected errors (not from tool itself)
+                    toolError = err.message;
+
+                    // Yield tool_call_result with error
+                    yield {
+                        type: "tool_call_result",
+                        toolCall: {
+                            id: toolCall.id,
+                            name: toolCall.name,
+                            input: toolCall.input,
+                        },
+                        output: null,
+                        error: toolError,
+                    };
+
+                    toolResults.push({
+                        type: "tool_result",
+                        tool_use_id: toolCall.id,
+                        content: `Error: ${err.message}`,
+                        is_error: true,
+                    });
+
+                    toolCalls.push({
+                        name: toolCall.name,
+                        input: toolCall.input,
+                        output: null,
+                        error: toolError,
+                    });
+                    log.error(`Tool ${toolCall.name} execution failed:`, err.message);
+                }
+            }
+
+            // Add tool results to conversation
+            messages.push({
+                role: "user",
+                content: toolResults,
+            });
+
+            // Call onStep hook after each step
+            if (this.agentProps.onStep) {
+                const stepContext: AgentStepContext = {
+                    ...execContext,
+                    step,
+                    maxSteps,
+                    messages: [...messages], // Clone to prevent mutation
+                };
+                await this.agentProps.onStep(stepContext);
+            }
+
+            // Dispatch observer onStep with per-step tool calls slice
+            this.safeDispatch("onStep", () =>
+                this.observer?.onStep?.({
+                    runId,
+                    agentId,
+                    step,
+                    maxSteps,
+                    messages: [...messages],
+                    assistantText: llmResponse.textContent,
+                    toolCalls: toolCalls.slice(toolCallsBeforeStep),
+                    usage,
+                    context: execContext,
+                })
+            );
+        }
+
+        if (step >= maxSteps && toolCalls.length > 0) {
+            stoppedEarly = true;
+            log.warn(`Agent ${this.agentName || "unknown"} stopped early after ${maxSteps} steps`);
+        }
+
+        const result = buildResult();
+
+        // Call afterRun hook with full context
+        if (this.agentProps.afterRun) {
+            const finishContext: AgentFinishContext = {
+                ...execContext,
+                messages: [...messages],
+                result,
+            };
+            await this.agentProps.afterRun(result, finishContext);
+        }
+
+        // Dispatch observer onFinish (success path)
+        this.safeDispatch("onFinish", () =>
+            this.observer?.onFinish?.({
+                runId,
+                agentId,
+                result,
+                messages: [...messages],
+                durationMs: Date.now() - runStartedAt,
+                context: execContext,
+            })
+        );
+
+        // Phase 1: Yield only complete event
+        // Phase 2: Will yield text_delta and tool events during loop
+        yield { type: "complete", result };
+
+        return result;
+        } catch (err: any) {
+            // Dispatch observer onFinish with error before rethrowing
+            this.safeDispatch("onFinish", () =>
+                this.observer?.onFinish?.({
+                    runId,
+                    agentId,
+                    result: buildResult(),
+                    messages: [...messages],
+                    durationMs: Date.now() - runStartedAt,
+                    error: err?.message || String(err),
+                    context: execContext,
+                })
+            );
+            throw err;
+        }
+    }
+
+    /**
+     * Fire-and-forget observer dispatch: catches synchronous throws and
+     * rejected promises so observer failures never break agent execution.
+     */
+    private safeDispatch(eventName: string, invoke: () => void | Promise<void> | undefined): void {
+        try {
+            const maybePromise = invoke();
+            if (maybePromise && typeof (maybePromise as Promise<void>).then === "function") {
+                (maybePromise as Promise<void>).catch((err: any) => {
+                    observerLog.warn(`AgentObserver.${eventName} threw (async):`, err?.message || err);
+                });
+            }
+        } catch (err: any) {
+            observerLog.warn(`AgentObserver.${eventName} threw (sync):`, err?.message || err);
+        }
+    }
+
+    /**
+     * Convert Message[] to LLM message format
+     * Supports multi-turn conversations with history
+     */
+    private convertMessages(messages: Message[]): LLMMessage[] {
+        return messages.map((m) => {
+            if (m.role === "user") {
+                return { role: "user" as const, content: m.content };
+            } else if (m.role === "assistant") {
+                // If assistant message has tool calls, convert to content blocks
+                if (m.toolCalls && m.toolCalls.length > 0) {
+                    const contentBlocks: LLMContentBlock[] = [];
+
+                    // Add text content if present
+                    if (m.content) {
+                        contentBlocks.push({ type: "text", text: m.content });
+                    }
+
+                    // Add tool use blocks
+                    for (const toolCall of m.toolCalls) {
+                        contentBlocks.push({
+                            type: "tool_use",
+                            id: toolCall.id,
+                            name: toolCall.name,
+                            input: toolCall.input,
+                        });
+                    }
+
+                    return { role: "assistant" as const, content: contentBlocks };
+                }
+
+                // Text-only assistant message
+                return { role: "assistant" as const, content: m.content };
+            } else {
+                // For tool messages, convert to user message with tool_result content block
+                return {
+                    role: "user" as const,
+                    content: [
+                        {
+                            type: "tool_result",
+                            tool_use_id: m.toolCallId,
+                            content: m.result,
+                        },
+                    ] as LLMContentBlock[],
+                };
+            }
+        });
+    }
+
+    private getToolSchemas(): FlinkToolSchema[] {
+        return Array.from(this.tools.values()).map((t) => t.getToolSchema());
+    }
+
+    /**
+     * Filter tools based on user permissions
+     * Only returns schemas for tools the user has permission to use
+     *
+     * @param user - User object
+     * @param userPermissions - Optional resolved permissions from auth plugin (preferred)
+     * @param conversationContext - Optional conversation context
+     */
+    private async filterToolsByPermissions(user?: any, userPermissions?: string[], conversationContext?: any): Promise<FlinkToolSchema[]> {
+        const allowedTools: FlinkToolSchema[] = [];
+        const toolExecutors = Array.from(this.tools.values());
+
+        for (const tool of toolExecutors) {
+            const hasPermission = await tool.checkPermissions(user, undefined, userPermissions, conversationContext);
+            if (hasPermission) {
+                allowedTools.push(tool.getToolSchema());
+            }
+        }
+
+        return allowedTools;
+    }
+
+    /**
+     * Build delegation chain from metadata for error messages
+     * Extracts parent agent IDs to show the full call stack
+     */
+}