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

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.92
+
+### Minor Changes
+
+-   8d23d56: Add global `AgentObserver` for app-level agent tracing
+
+    A new `observer` option on `FlinkOptions.ai` lets applications register a single, app-wide hook that fires for every agent execution — covering both streamed and awaited (`response.result`) callers without per-agent plumbing.
+
+    Events expose data that was previously only internal to `AgentRunner`:
+
+    -   `onRun` — pre-loop, with resolved system instructions and initial messages.
+    -   `onLlmCall` — per step, immediately before the adapter call. `messages` reflects post-compaction state and `tools` reflects per-step permission filtering.
+    -   `onStep` — per step end, with `assistantText`, per-step `toolCalls`, and `usage`.
+    -   `onFinish` — post-loop (success or error), with the final result, total `durationMs`, and the error message on failure.
+
+    All events share a stable `runId` per execution; the same ID is now also returned on `AgentExecuteResult.runId` so apps can correlate persisted results with observer traces.
+
+    Observer callbacks are 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.
+
+    The existing per-agent `beforeRun` / `onStep` / `afterRun` hooks remain unchanged — use the observer for cross-cutting concerns (tracing, APM, cost accounting, dev tools) and per-agent hooks for business logic that needs to block or mutate state (conversation persistence, guardrails).
+
+    Example:
+
+    ```typescript
+    new FlinkApp({
+        ai: {
+            llms: { default: new AnthropicAdapter({ ... }) },
+            observer: {
+                onRun(e) {
+                    trace.start(e.runId, { agentId: e.agentId, instructions: e.instructions });
+                },
+                onLlmCall(e) {
+                    trace.recordLlmCall(e.runId, e.step, e.messages, e.tools);
+                },
+                onStep(e) {
+                    trace.recordStep(e.runId, e.step, e.assistantText, e.toolCalls, e.usage);
+                },
+                onFinish(e) {
+                    trace.finish(e.runId, { result: e.result, error: e.error, durationMs: e.durationMs });
+                },
+            },
+        },
+    });
+    ```
+
 ## 2.0.0-alpha.91
 
 ## 2.0.0-alpha.90

package/dist/src/FlinkApp.d.ts

@@ -6,6 +6,7 @@ import { Db, MongoClient } from "mongodb";
 import { ToadScheduler } from "toad-scheduler";
 import { FlinkAgentFile } from "./ai/FlinkAgent";
 import { FlinkToolFile } from "./ai/FlinkTool";
+import { AgentObserver } from "./ai/FlinkAgent";
 import { LLMAdapter } from "./ai/LLMAdapter";
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkContext } from "./FlinkContext";
@@ -178,6 +179,21 @@ export interface FlinkOptions {
         llms?: {
             [id: string]: LLMAdapter;
         };
+        /**
+         * Global agent observer for app-level tracing, APM, cost accounting, dev tools, etc.
+         *
+         * 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.
+         *
+         * Events: `onRun` (pre-loop), `onLlmCall` (per step, pre-adapter call),
+         * `onStep` (per step end), `onFinish` (post-loop, including error path).
+         *
+         * For agent-local business logic (conversation persistence, guardrails) use the
+         * per-agent `beforeRun` / `onStep` / `afterRun` hooks on `FlinkAgent` instead.
+         */
+        observer?: AgentObserver;
     };
     /**
      * If true, the HTTP server will be disabled.
@@ -290,6 +306,7 @@ export declare class FlinkApp<C extends FlinkContext> {
     private repos;
     private services;
     private llmAdapters;
+    private agentObserver?;
     private tools;
     private agents;
     /**

package/dist/src/FlinkApp.js

@@ -117,7 +117,7 @@ exports.autoRegisteredAgents = [];
 exports.autoRegisteredServices = [];
 var FlinkApp = /** @class */ (function () {
     function FlinkApp(opts) {
-        var _a;
+        var _a, _b;
         this.handlers = [];
         this.started = false;
         this.debug = false;
@@ -160,6 +160,8 @@ var FlinkApp = /** @class */ (function () {
             // Convert plain object to Map for internal use
             this.llmAdapters = new Map(Object.entries(opts.ai.llms));
         }
+        // Register global agent observer if configured
+        this.agentObserver = (_b = opts.ai) === null || _b === void 0 ? void 0 : _b.observer;
     }
     Object.defineProperty(FlinkApp.prototype, "ctx", {
         get: function () {
@@ -1208,7 +1210,7 @@ var FlinkApp = /** @class */ (function () {
                 for (_i = 0, _a = Object.values(this.agents); _i < _a.length; _i++) {
                     agent = _a[_i];
                     agent.ctx = this.ctx;
-                    agent.__init(this.llmAdapters, this.tools);
+                    agent.__init(this.llmAdapters, this.tools, this.agentObserver);
                 }
                 return [2 /*return*/];
             });

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

@@ -1,4 +1,4 @@
-import { FlinkAgentProps, AgentExecuteInput, StreamChunk } from "./FlinkAgent";
+import { FlinkAgentProps, AgentExecuteInput, StreamChunk, AgentObserver } from "./FlinkAgent";
 import { ToolExecutor } from "./ToolExecutor";
 import { LLMAdapter } from "./LLMAdapter";
 export declare class AgentRunner {
@@ -6,14 +6,21 @@ export declare class AgentRunner {
     private tools;
     private agentName?;
     private ctx?;
+    private observer?;
     private llmAdapter;
     private maxTokens;
     private temperature;
     private maxSteps;
     private timeoutMs;
     constructor(agentProps: FlinkAgentProps<any>, tools: Map<string, ToolExecutor<any>>, llmAdapters: Map<string, LLMAdapter>, agentName?: string | undefined, // Optional agent name for logging
-    ctx?: any);
+    ctx?: any, // FlinkContext for instruction callbacks (any for flexibility)
+    observer?: AgentObserver | undefined);
     streamGenerator(input: AgentExecuteInput): AsyncGenerator<StreamChunk>;
+    /**
+     * Fire-and-forget observer dispatch: catches synchronous throws and
+     * rejected promises so observer failures never break agent execution.
+     */
+    private safeDispatch;
     /**
      * Convert Message[] to LLM message format
      * Supports multi-turn conversations with history