@flink-app/flink 2.0.0-alpha.91 → 2.0.0-alpha.92

package/src/ai/AgentRunner.ts

@@ -1,3 +1,4 @@
+import { v4 as uuidv4 } from "uuid";
 import {
     FlinkAgentProps,
     AgentExecuteResult,
@@ -7,11 +8,15 @@ import {
     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;
@@ -24,7 +29,8 @@ export class AgentRunner {
         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 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";
@@ -44,10 +50,19 @@ export class AgentRunner {
     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: this.agentName || "unknown",
+            agentId,
             conversationId: input.conversationId,
             user: input.user,
             metadata: input.metadata,
@@ -83,6 +98,20 @@ export class AgentRunner {
             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;
@@ -92,6 +121,22 @@ export class AgentRunner {
         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++;
 
@@ -160,6 +205,26 @@ export class AgentRunner {
                 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,
@@ -272,6 +337,20 @@ export class AgentRunner {
                     };
                     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
             }
 
@@ -400,6 +479,21 @@ export class AgentRunner {
                 };
                 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) {
@@ -407,19 +501,7 @@ export class AgentRunner {
             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,
-                ...(totalCachedInputTokens > 0 && { cachedInputTokens: totalCachedInputTokens }),
-                ...(totalCacheCreationInputTokens > 0 && { cacheCreationInputTokens: totalCacheCreationInputTokens }),
-            },
-            providerMetadata: Object.keys(finalProviderMetadata).length > 0 ? finalProviderMetadata : undefined,
-        };
+        const result = buildResult();
 
         // Call afterRun hook with full context
         if (this.agentProps.afterRun) {
@@ -431,11 +513,55 @@ export class AgentRunner {
             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);
+        }
     }
 
     /**

package/src/ai/FlinkAgent.ts

@@ -250,6 +250,7 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
     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;
@@ -315,9 +316,10 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
      * Internal initialization called by FlinkApp
      * @internal
      */
-    __init(llmAdapters: Map<string, any>, tools: { [x: string]: ToolExecutor<Ctx> }): void {
+    __init(llmAdapters: Map<string, any>, tools: { [x: string]: ToolExecutor<Ctx> }, observer?: AgentObserver): void {
         this._llmAdapters = llmAdapters;
         this._tools = tools;
+        this._observer = observer;
     }
 
     /**
@@ -350,6 +352,9 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
         if (this._tools) {
             bound._tools = this._tools;
         }
+        if (this._observer) {
+            bound._observer = this._observer;
+        }
         if (this._boundUserPermissions !== undefined) {
             bound._boundUserPermissions = this._boundUserPermissions;
         }
@@ -389,6 +394,9 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
         if (this._tools) {
             bound._tools = this._tools;
         }
+        if (this._observer) {
+            bound._observer = this._observer;
+        }
         if (this._boundUser !== undefined) {
             bound._boundUser = this._boundUser;
         }
@@ -430,6 +438,9 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
         if (this._tools) {
             bound._tools = this._tools;
         }
+        if (this._observer) {
+            bound._observer = this._observer;
+        }
         if (this._boundUser !== undefined) {
             bound._boundUser = this._boundUser;
         }
@@ -471,6 +482,9 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
         if (this._tools) {
             bound._tools = this._tools;
         }
+        if (this._observer) {
+            bound._observer = this._observer;
+        }
         if (this._boundUser !== undefined) {
             bound._boundUser = this._boundUser;
         }
@@ -712,7 +726,8 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
                 toolsMap,
                 llmAdapters,
                 this.getAgentId(),
-                this.ctx // Pass ctx to runner so callbacks can access it
+                this.ctx, // Pass ctx to runner so callbacks can access it
+                this._observer
             );
         }
         return this.runner;
@@ -909,6 +924,12 @@ export interface AgentExecuteInput<ConversationCtx = any> {
 }
 
 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;
@@ -957,3 +978,92 @@ export interface AgentResponse {
     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>;
+}