@sebastiantuyu/agest 0.3.3-next.3 → 0.3.3-next.5

package/dist/adapters/index.d.ts

@@ -1,3 +1,5 @@
 export { langchain } from "./langchain";
 export { remote } from "./remote";
 export type { RemoteAdapterOptions } from "./remote";
+export { createTrace, summarizeEvents } from "./tracing";
+export type { Trace } from "./tracing";

package/dist/adapters/index.js

@@ -1,2 +1,3 @@
 export { langchain } from "./langchain";
 export { remote } from "./remote";
+export { createTrace, summarizeEvents } from "./tracing";

package/dist/adapters/langchain.js

@@ -1,5 +1,4 @@
-import { computeCost } from "../pricing";
-import { createTracingHandle } from "./tracing";
+import { createTracingHandle, summarizeEvents } from "./tracing";
 /**
  * Adapter for LangChain runnables and agents.
  *
@@ -221,48 +220,5 @@ function extractTokensFromMessage(msg) {
     };
 }
 function summarizeRun(input) {
-    const modelEvents = input.events.filter((e) => e.kind === "model");
-    let inputTokens = 0;
-    let outputTokens = 0;
-    let providerCost = 0;
-    let hasProviderCost = false;
-    let hasTableCost = false;
-    let tableCost = 0;
-    let hasTokens = false;
-    for (const e of modelEvents) {
-        if (e.tokens) {
-            hasTokens = true;
-            inputTokens += e.tokens.input;
-            outputTokens += e.tokens.output;
-        }
-        if (e.cost?.source === "provider" && e.cost.totalUsd != null) {
-            hasProviderCost = true;
-            providerCost += e.cost.totalUsd;
-        }
-        else if (e.cost?.source === "table" && e.cost.totalUsd != null) {
-            hasTableCost = true;
-            tableCost += e.cost.totalUsd;
-        }
-    }
-    let tokens = hasTokens ? { input: inputTokens, output: outputTokens } : undefined;
-    if (!tokens && input.fallbackTokens)
-        tokens = input.fallbackTokens;
-    // Pick cost: provider > table > recompute from fallback tokens
-    let cost;
-    if (hasProviderCost) {
-        cost = { totalUsd: providerCost, source: "provider" };
-    }
-    else if (hasTableCost) {
-        cost = { totalUsd: tableCost, source: "table" };
-    }
-    else if (tokens && input.model) {
-        const computed = computeCost({
-            model: input.model,
-            inputTokens: tokens.input,
-            outputTokens: tokens.output,
-        });
-        if (computed.source !== "unavailable")
-            cost = computed;
-    }
-    return { tokens, cost };
+    return summarizeEvents(input.events, input.model, input.fallbackTokens);
 }

package/dist/adapters/tracing.d.ts

@@ -1,4 +1,4 @@
-import type { TimelineEvent } from "../types";
+import type { TimelineEvent, CostBreakdown } from "../types";
 export interface TracingHandle {
     /** Pass this into `runnable.invoke(..., { callbacks: [handler.callbacks] })` */
     callbacks: any[];
@@ -17,3 +17,57 @@ export interface TracingHandle {
  * than throwing — the underlying agent run must not be broken by tracing.
  */
 export declare function createTracingHandle(baselineMs: number): Promise<TracingHandle>;
+export interface Trace {
+    /**
+     * Attach to your top-level LangChain/LangGraph call:
+     * `await graph.invoke(input, { callbacks: trace.callbacks })`.
+     * Callbacks propagate to nested nodes automatically.
+     */
+    callbacks: any[];
+    /**
+     * Collect the captured timeline plus aggregated tokens and cost. Call once
+     * after the run completes; the result is memoized so repeat calls are safe.
+     * Spread the result into your `AgentResponse.metadata` to surface the
+     * per-scene cost/timeline waterfall in the report.
+     */
+    collect(): {
+        events: TimelineEvent[];
+        tokens?: {
+            input: number;
+            output: number;
+        };
+        cost?: CostBreakdown;
+    };
+}
+/**
+ * Public tracing helper for custom executors (i.e. agents not wired through
+ * the `langchain()` adapter). Create one per scene run, hand its `callbacks`
+ * to your LangChain/LangGraph invocation, then spread `collect()` into the
+ * response metadata.
+ *
+ * @example
+ * ```ts
+ * const trace = await createTrace({ model: env.OPENROUTER_MODEL });
+ * const plan = await generatePlan(input, { callbacks: trace.callbacks });
+ * return { text: render(plan), metadata: { model, tools, ...trace.collect() } };
+ * ```
+ */
+export declare function createTrace(opts?: {
+    model?: string;
+}): Promise<Trace>;
+/**
+ * Aggregate token counts and cost across a timeline's model events.
+ * Provider-reported cost wins; otherwise the table-derived cost; otherwise
+ * cost is recomputed from `model` and the summed tokens. `fallbackTokens` is
+ * used only when no model event carried usage.
+ */
+export declare function summarizeEvents(events: TimelineEvent[], model?: string, fallbackTokens?: {
+    input: number;
+    output: number;
+}): {
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    cost?: CostBreakdown;
+};

package/dist/adapters/tracing.js

@@ -1,4 +1,5 @@
 import { computeCost } from "../pricing";
+import { logger } from "../logger";
 /**
  * Creates a LangChain callback handler that records every LLM and tool
  * invocation as a `TimelineEvent`. Returns a handle whose `drain()` method
@@ -15,7 +16,9 @@ export async function createTracingHandle(baselineMs) {
     try {
         ({ BaseCallbackHandler } = await import("@langchain/core/callbacks/base"));
     }
-    catch {
+    catch (err) {
+        logger.debug(`[agest] tracing disabled: could not load @langchain/core/callbacks/base — ` +
+            `install @langchain/core as a peer to capture per-scene cost/timeline. (${err.message})`);
         return { callbacks: [], drain: () => ({ events: [] }) };
     }
     const events = [];
@@ -125,6 +128,86 @@ export async function createTracingHandle(baselineMs) {
         },
     };
 }
+/**
+ * Public tracing helper for custom executors (i.e. agents not wired through
+ * the `langchain()` adapter). Create one per scene run, hand its `callbacks`
+ * to your LangChain/LangGraph invocation, then spread `collect()` into the
+ * response metadata.
+ *
+ * @example
+ * ```ts
+ * const trace = await createTrace({ model: env.OPENROUTER_MODEL });
+ * const plan = await generatePlan(input, { callbacks: trace.callbacks });
+ * return { text: render(plan), metadata: { model, tools, ...trace.collect() } };
+ * ```
+ */
+export async function createTrace(opts) {
+    const baseline = performance.now();
+    const handle = await createTracingHandle(baseline);
+    let collected;
+    return {
+        callbacks: handle.callbacks,
+        collect() {
+            if (collected)
+                return collected;
+            const drained = handle.drain();
+            const { tokens, cost } = summarizeEvents(drained.events, opts?.model ?? drained.modelName);
+            collected = { events: drained.events, tokens, cost };
+            return collected;
+        },
+    };
+}
+/**
+ * Aggregate token counts and cost across a timeline's model events.
+ * Provider-reported cost wins; otherwise the table-derived cost; otherwise
+ * cost is recomputed from `model` and the summed tokens. `fallbackTokens` is
+ * used only when no model event carried usage.
+ */
+export function summarizeEvents(events, model, fallbackTokens) {
+    const modelEvents = events.filter((e) => e.kind === "model");
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let providerCost = 0;
+    let hasProviderCost = false;
+    let hasTableCost = false;
+    let tableCost = 0;
+    let hasTokens = false;
+    for (const e of modelEvents) {
+        if (e.tokens) {
+            hasTokens = true;
+            inputTokens += e.tokens.input;
+            outputTokens += e.tokens.output;
+        }
+        if (e.cost?.source === "provider" && e.cost.totalUsd != null) {
+            hasProviderCost = true;
+            providerCost += e.cost.totalUsd;
+        }
+        else if (e.cost?.source === "table" && e.cost.totalUsd != null) {
+            hasTableCost = true;
+            tableCost += e.cost.totalUsd;
+        }
+    }
+    let tokens = hasTokens ? { input: inputTokens, output: outputTokens } : undefined;
+    if (!tokens && fallbackTokens)
+        tokens = fallbackTokens;
+    let cost;
+    if (hasProviderCost) {
+        cost = { totalUsd: providerCost, source: "provider" };
+    }
+    else if (hasTableCost) {
+        cost = { totalUsd: tableCost, source: "table" };
+    }
+    else if (tokens && model) {
+        const computed = computeCost({
+            model,
+            inputTokens: tokens.input,
+            outputTokens: tokens.output,
+        });
+        if (computed.source !== "unavailable")
+            cost = computed;
+    }
+    return { tokens, cost };
+}
 function now() {
     return performance.now();
 }

package/dist/index.d.ts

@@ -3,11 +3,13 @@ import { SceneBuilder } from "./context";
 export { expect } from "./assertions";
 export { logger } from "./logger";
 export { defineConfig } from "./config";
+export { createTrace, summarizeEvents } from "./adapters/tracing";
+export type { Trace } from "./adapters/tracing";
 export type { AgestConfig, JudgeConfig, JudgeExecutor } from "./config";
 export type { LogLevel } from "./logger";
 export type { AgentExpectation, AgentMatchers } from "./assertions";
 export type { JudgeCriteria } from "./judge";
-export type { AgentExecutor, ExecutorOptions, AgentResponse, AgentReport, SceneResult, RunResult, JudgeVerdict, JudgeResult, HookFn, } from "./types";
+export type { AgentExecutor, ExecutorOptions, AgentResponse, AgentReport, SceneResult, RunResult, JudgeVerdict, JudgeResult, HookFn, TimelineEvent, TimelineEventKind, CostBreakdown, CostSource, } from "./types";
 export interface AgentOptions {
     name?: string;
 }

package/dist/index.js

@@ -2,6 +2,7 @@ import { AgentContext, setContext, getContext } from "./context";
 export { expect } from "./assertions";
 export { logger } from "./logger";
 export { defineConfig } from "./config";
+export { createTrace, summarizeEvents } from "./adapters/tracing";
 export function scene(prompt) {
     return getContext().registerScene(prompt);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebastiantuyu/agest",
-  "version": "0.3.3-next.3",
+  "version": "0.3.3-next.5",
   "description": "A testing library for agents",
   "repository": {
     "type": "git",
@@ -58,5 +58,13 @@
   },
   "dependencies": {
     "@supercharge/promise-pool": "3.3.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3.0 <2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    }
   }
 }