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

package/src/ai/AgentRunner.ts

@@ -0,0 +1,549 @@
+import {
+  FlinkAgentProps,
+  AgentExecuteResult,
+  AgentExecuteInput,
+  StreamChunk,
+  Message,
+  AgentExecuteContext,
+  AgentStepContext,
+  AgentFinishContext,
+} from "./FlinkAgent";
+import { ToolExecutor } from "./ToolExecutor";
+import { SubAgentExecutor } from "./SubAgentExecutor";
+import { LLMAdapter, LLMMessage, LLMContentBlock, FlinkToolSchema } from "./LLMAdapter";
+import { log } from "../FlinkLog";
+
+export class AgentRunner {
+  private llmAdapter: LLMAdapter;
+  private maxTokens: number;
+  private temperature: number;
+  private maxSteps: number;
+  private timeoutMs: number;
+  private maxSubAgentDepth: number;
+
+  constructor(
+    private agentProps: FlinkAgentProps,
+    private tools: Map<string, ToolExecutor<any>>,
+    llmAdapters: Map<string, LLMAdapter>,
+    private agentName?: string, // Optional agent name for logging
+  ) {
+    // 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;
+    this.maxSubAgentDepth = agentProps.limits?.maxSubAgentDepth || 5;
+  }
+
+  /**
+   * Phase 1: Stream generator that yields complete event on finish
+   * Phase 2: Will yield text_delta and tool events during execution
+   */
+  async *streamGenerator(
+    input: AgentExecuteInput,
+  ): AsyncGenerator<StreamChunk> {
+    const maxSteps = input.options?.maxSteps || this.maxSteps;
+    const toolCalls: AgentExecuteResult["toolCalls"] = [];
+    const subAgentCalls: AgentExecuteResult["subAgentCalls"] = [];
+
+    // Get current depth from metadata, defaulting to 0 for root agents
+    const currentDepth = input.metadata?.subAgentDepth ?? 0;
+
+    // Check depth limit before execution
+    if (currentDepth > this.maxSubAgentDepth) {
+      // Build delegation chain for debugging
+      const chain = this.buildDelegationChain(input.metadata);
+      const chainStr = chain.length > 0 ? ` Delegation chain: ${chain.join(" → ")} → ${this.agentName || "unknown"}` : "";
+
+      throw new Error(
+        `Sub-agent recursion depth limit exceeded (max: ${this.maxSubAgentDepth}, current: ${currentDepth}). ` +
+        `This usually indicates a circular delegation loop.${chainStr}`
+      );
+    }
+
+    // Build execution context
+    const execContext: AgentExecuteContext = {
+      agentId: this.agentName || "unknown",
+      conversationId: input.conversationId,
+      user: input.user,
+      isSubAgent: input.metadata?.isSubAgentCall === true,
+      parentAgentId: input.metadata?.parentAgentId,
+      subAgentDepth: currentDepth,
+      metadata: input.metadata,
+    };
+
+    // 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 {
+      messages.push(...this.convertMessages(input.message));
+    }
+
+    let step = 0;
+    let finalMessage = "";
+    let stoppedEarly = false;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+
+    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);
+
+      // Debug logging: Show what we're sending to the LLM
+      if (this.agentProps.debug) {
+        log.debug(`[Agent:${this.agentName}] Step ${step}/${maxSteps} - Calling LLM with:`, {
+          instructions: this.agentProps.instructions,
+          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,
+        });
+      }
+
+      // Call AI model via adapter using streaming
+      const llmStream = this.llmAdapter.stream({
+        instructions: this.agentProps.instructions,
+        messages,
+        tools: availableTools,
+        maxTokens: this.maxTokens,
+        temperature: this.temperature,
+      });
+
+      // Accumulate response from stream
+      let textContent = "";
+      const toolCallsFromStream: Array<{ id: string; name: string; input: any }> = [];
+      let usage = { inputTokens: 0, outputTokens: 0 };
+      let stopReason: "end_turn" | "tool_use" | "max_tokens" = "end_turn";
+
+      // 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;
+            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,
+      };
+
+      // Debug logging: Show what the LLM responded with
+      if (this.agentProps.debug) {
+        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);
+        }
+        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;
+
+        // Debug logging: Tool execution start
+        if (this.agentProps.debug) {
+          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`);
+          }
+
+          // Check if this is a sub-agent executor
+          const isSubAgent =
+            toolExecutor instanceof SubAgentExecutor ||
+            (toolExecutor as any).isSubAgentExecutor?.();
+
+          if (isSubAgent) {
+            const subAgentId = (toolExecutor as any).getSubAgentId();
+
+            // Transform input if hook exists
+            let transformedInput = toolCall.input;
+            if (this.agentProps.transformSubAgentInput) {
+              try {
+                transformedInput = await this.agentProps.transformSubAgentInput(
+                  subAgentId,
+                  toolCall.input,
+                  execContext
+                );
+              } catch (err: any) {
+                log.warn(`transformSubAgentInput hook failed for ${subAgentId}:`, err.message);
+                // Continue with original input if transformation fails
+              }
+            }
+
+            // Update the tool call input with transformed version
+            toolCall.input = transformedInput;
+
+            // Call onSubAgentCall hook if it exists (after transformation)
+            if (this.agentProps.onSubAgentCall) {
+              await this.agentProps.onSubAgentCall(
+                subAgentId,
+                transformedInput,
+                execContext
+              );
+            }
+
+            // Yield agent_call_start event
+            yield {
+              type: "agent_call_start",
+              agentId: subAgentId,
+              input: transformedInput,
+            };
+          } else {
+            // Yield tool_call_start for regular tools
+            yield {
+              type: "tool_call_start",
+              toolCall: {
+                id: toolCall.id,
+                name: toolCall.name,
+                input: toolCall.input,
+              },
+            };
+          }
+
+          // Pass parent context if this is a sub-agent executor
+          const toolResult = isSubAgent
+            ? await (toolExecutor as any).execute(
+                toolCall.input,
+                input.user,
+                execContext, // Pass parent context to sub-agent
+                input.userPermissions, // Pass resolved permissions
+              )
+            : await toolExecutor.execute(toolCall.input, input.user, input.userPermissions);
+
+          // 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,
+          });
+
+          // Track sub-agent calls separately
+          if (isSubAgent && toolResult.success) {
+            const subAgentId = (toolExecutor as any).getSubAgentId();
+            const agentResult = toolResult.data as AgentExecuteResult;
+
+            // Merge token usage from sub-agent
+            totalInputTokens += agentResult.usage?.inputTokens || 0;
+            totalOutputTokens += agentResult.usage?.outputTokens || 0;
+
+            subAgentCalls.push({
+              agentId: subAgentId,
+              input: toolCall.input,
+              result: agentResult,
+            });
+
+            // Call onSubAgentComplete hook if it exists
+            if (this.agentProps.onSubAgentComplete) {
+              await this.agentProps.onSubAgentComplete(
+                subAgentId,
+                agentResult,
+                execContext
+              );
+            }
+
+            // Yield agent_call_result event
+            yield {
+              type: "agent_call_result",
+              agentId: subAgentId,
+              result: agentResult,
+            };
+          } else {
+            // Yield tool_call_result for regular tools
+            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,
+            isAgentCall: isSubAgent,
+            agentId: isSubAgent ? (toolExecutor as any).getSubAgentId() : undefined,
+          });
+
+          // Debug logging: Tool execution result
+          if (this.agentProps.debug) {
+            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.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);
+      }
+    }
+
+    if (step >= maxSteps && toolCalls.length > 0) {
+      stoppedEarly = true;
+      log.warn(
+        `Agent ${this.agentName || "unknown"} stopped early after ${maxSteps} steps`,
+      );
+    }
+
+    const result: AgentExecuteResult = {
+      message: finalMessage,
+      toolCalls,
+      stepsUsed: step,
+      stoppedEarly,
+      usage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens },
+      subAgentCalls: subAgentCalls.length > 0 ? subAgentCalls : undefined,
+    };
+
+    // Call afterRun hook with full context
+    if (this.agentProps.afterRun) {
+      const finishContext: AgentFinishContext = {
+        ...execContext,
+        messages: [...messages],
+        result,
+      };
+      await this.agentProps.afterRun(result, finishContext);
+    }
+
+    // Phase 1: Yield only complete event
+    // Phase 2: Will yield text_delta and tool events during loop
+    yield { type: "complete", result };
+
+    return result;
+  }
+
+  /**
+   * 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") {
+        return { role: "assistant" as const, content: m.content };
+      } else {
+        // For tool messages, convert to user message with tool result
+        return { role: "user" as const, content: m.result };
+      }
+    });
+  }
+
+  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)
+   */
+  private async filterToolsByPermissions(user?: any, userPermissions?: string[]): 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);
+      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
+   */
+  private buildDelegationChain(metadata?: Record<string, any>): string[] {
+    if (!metadata?.parentAgentId) {
+      return [];
+    }
+
+    const chain: string[] = [];
+    let current = metadata;
+
+    // Walk up the parent chain
+    while (current?.parentAgentId) {
+      chain.unshift(current.parentAgentId);
+      // If parent metadata exists, continue walking up
+      current = current.parentMetadata;
+    }
+
+    return chain;
+  }
+}