@agent-native/core 0.172.3 → 0.172.4

package/dist/observability/traces.js

@@ -1,6 +1,6 @@
 import { captureError } from "../server/capture-error.js";
 import { getRequestContext } from "../server/request-context.js";
-import { MAX_AI_CONTENT_BYTES, MAX_AI_SPANS_PER_RUN, boundAiContent, emitAiSpanEvent, emitAiTraceEvent, toAiErrorDetail, } from "./posthog-ai.js";
+import { MAX_AI_CONTENT_BYTES, MAX_AI_SPANS_PER_RUN, boundAiContent, emitAiSpanEvent, emitAiTraceEvent, resolveAiError, toAiErrorDetail, } from "./posthog-ai.js";
 import { endAgentSpan, startAgentSpan } from "./tracing.js";
 import { trackingIdentityProperties } from "./tracking-identity.js";
 import { DEFAULT_OBSERVABILITY_CONFIG } from "./types.js";
@@ -143,6 +143,7 @@ function emitLlmGenerationTrackingEvent(args) {
         cost_cents_x100: args.costCentsX100,
         cost_usd: costUsd,
         duration_ms: args.durationMs,
+        stop_reason: args.stopReason,
         time_to_first_token_ms: args.firstTokenMs,
         status: args.status,
         tool_calls: args.toolCalls,
@@ -177,23 +178,24 @@ function emitLlmGenerationTrackingEvent(args) {
         $ai_output_tokens: args.outputTokens,
         $ai_latency: Math.round(args.llmDurationMs) / 1000,
         $ai_is_error: args.status === "error",
-        $ai_error: args.status === "error"
-            ? toAiErrorDetail(error, {
-                state: args.terminalOutcome?.state,
-                code: terminalCode,
-                retryable: terminalRetryable,
-            })
-            : undefined,
+        $ai_error: resolveAiError(args.status === "error", toAiErrorDetail(error, {
+            state: args.terminalOutcome?.state,
+            code: terminalCode,
+            retryable: terminalRetryable,
+        })),
+        // A generation fails only as the model layer, so the default kind says so;
+        // a classified terminal code names it more precisely.
+        $ai_error_type: args.status === "error" ? (terminalCode ?? "llm_error") : undefined,
         // Every engine here streams (`messages.stream`, `streamText`, gateway SSE),
         // which is also what makes `$ai_time_to_first_token` meaningful.
         $ai_stream: true,
         $ai_cache_read_input_tokens: args.cacheReadTokens,
         $ai_cache_creation_input_tokens: args.cacheWriteTokens,
         $ai_request_count: args.llmCallCount,
+        $ai_stop_reason: args.stopReason,
         $ai_total_cost_usd: costUsd,
         $ai_input: args.aiInput,
         $ai_output_choices: args.aiOutputChoices,
-        $ai_tools: args.aiTools,
         input_truncated: args.aiInputTruncated || undefined,
         output_truncated: args.aiOutputTruncated || undefined,
         latency_source: args.llmDurationMeasured ? "measured" : "derived",
@@ -237,18 +239,22 @@ function emitLlmGenerationTrackingEvent(args) {
     }
 }
 /**
- * Build the PostHog content fields for a run's `$ai_generation`.
+ * Build the PostHog content fields for one `$ai_generation`.
  *
- * This is one generation per run carrying the run's whole message list, not one
- * per model round-trip: the engine layer reports aggregate usage only
- * (`onUsage`) and exposes no per-step hook. Consequence to know when reading a
- * trace — per-round-trip latency and intermediate assistant turns are not
- * visible; a multi-step run collapses into a single generation node.
+ * One generation per model round-trip: `messages` is what that call was sent,
+ * `assistantText` what it answered, and `toolSpans` the tools it then asked
+ * for. An engine that never brackets its calls with `model_stream` has no
+ * round-trips to split on and falls back to a single generation covering the
+ * whole run — an aggregate, and reported as one.
  *
  * `$ai_output_choices` is emitted whenever tool calls happened even with
  * `capturePrompts` off, because PostHog derives `$ai_tools_called` /
  * `$ai_tool_call_count` from tool-call blocks inside it and nothing else. The
  * assistant's text content stays gated; only the structural call list ships.
+ *
+ * The app's tool DEFINITIONS are not sent at all. They are the same catalogue
+ * on every call — tens of kilobytes of descriptions — and a call is already
+ * identified by its name in `tool_calls` and by its own span.
  */
 function buildGenerationContent(args) {
     const { config } = args;
@@ -285,26 +291,9 @@ function buildGenerationContent(args) {
             },
         ])
         : undefined;
-    const toolList = Array.isArray(args.tools)
-        ? args.tools
-            .filter((tool) => !!tool && typeof tool.name === "string")
-            .map((tool) => ({
-            type: "function",
-            function: {
-                name: tool.name,
-                ...(typeof tool.description === "string"
-                    ? { description: tool.description }
-                    : {}),
-            },
-        }))
-        : [];
     return {
         aiInput: input?.value,
         aiOutputChoices: output?.value,
-        // Tool definitions are app configuration rather than user content, so they
-        // are not gated — without them a trace shows calls to tools nobody can
-        // identify. Schemas are excluded to keep the event small.
-        aiTools: toolList.length ? toolList : undefined,
         aiInputTruncated: input?.truncated,
         aiOutputTruncated: output?.truncated,
     };
@@ -408,13 +397,31 @@ export async function instrumentAgentLoop(opts) {
     let toolCallCount = 0;
     let successfulTools = 0;
     let failedTools = 0;
+    /** Tools that reported a failure of their own, excluding the ones the run's
+     *  death interrupted — those are a consequence of the failure, never
+     *  evidence of what caused it. */
+    let reportedToolFailures = 0;
     // One `model_stream` start/end bracket is emitted per LLM round-trip, and it
     // closes before any tool of that turn is started — so these intervals ARE the
-    // model's wall clock, not an estimate of it. Recording them is what lets the
+    // model's wall clock, not an estimate of it. Recording them is what lets each
     // generation report a measured `$ai_latency` instead of backing tool time out
-    // of the run duration.
+    // of the run duration, and what makes a round-trip the unit PostHog draws:
+    // one `$ai_generation` per model call, with that call's tools underneath it.
+    // Engines that never bracket their calls record none, and the run falls back
+    // to a single aggregate generation.
+    const modelRoundTrips = [];
+    /** The call currently streaming, or the last one that streamed — text and
+     *  usage arriving between calls belong to the call that just finished. */
+    const currentRoundTrip = () => modelRoundTrips[modelRoundTrips.length - 1];
     const modelStreamIntervals = [];
     let modelStreamOpenedAt = null;
+    /** Tool span id → the round-trip that requested it. */
+    const toolSpanRoundTrip = new Map();
+    /** Tool invocation counter → the same, for the generation's `tools` list. */
+    const toolCounterRoundTrip = new Map();
+    /** Tool span id → how it failed. A class, not the tool's output, so it
+     *  travels even when `captureToolResults` withholds the message. */
+    const toolSpanErrorClass = new Map();
     // Track in-flight OTel tool spans so they're all ended even if the loop
     // throws before a matching `tool_done` arrives.
     const openOtelToolSpans = new Set();
@@ -463,6 +470,7 @@ export async function instrumentAgentLoop(opts) {
                 assistantTextLength < MAX_AI_CONTENT_BYTES) {
                 assistantTextParts.push(event.text);
                 assistantTextLength += event.text.length;
+                currentRoundTrip()?.assistantText.push(event.text);
             }
             // Some guardrails intentionally stop the loop by emitting a terminal
             // event and returning usage instead of throwing. Preserve that terminal
@@ -502,19 +510,54 @@ export async function instrumentAgentLoop(opts) {
                 // The emitter brackets these itself, so a repeated start or an
                 // unmatched end is a no-op here rather than a fabricated interval.
                 if (event.status === "start") {
-                    modelStreamOpenedAt ??= Date.now();
+                    if (modelStreamOpenedAt === null) {
+                        modelStreamOpenedAt = Date.now();
+                        modelRoundTrips.push({
+                            spanId: spanId(),
+                            start: modelStreamOpenedAt,
+                            end: modelStreamOpenedAt,
+                            // Copied: the loop appends this call's answer and its tool
+                            // results to the same array as the run continues, so a reference
+                            // held here would report the whole transcript as this call's
+                            // prompt.
+                            //
+                            // This is the loop's message list, which is not byte-for-byte
+                            // what the engine received: Context X-Ray, observational memory
+                            // and overflow trimming build a separate `contextMessages` for
+                            // the provider. Reporting a prompt the model never saw is a
+                            // known gap, and closing it needs the loop to hand its
+                            // per-call request to instrumentation.
+                            ...(config.capturePrompts
+                                ? { input: [...loopOpts.messages] }
+                                : {}),
+                            assistantText: [],
+                        });
+                    }
                 }
                 else if (modelStreamOpenedAt !== null) {
-                    modelStreamIntervals.push({
-                        start: modelStreamOpenedAt,
-                        end: Date.now(),
-                    });
+                    const end = Date.now();
+                    modelStreamIntervals.push({ start: modelStreamOpenedAt, end });
+                    const trip = currentRoundTrip();
+                    if (trip) {
+                        trip.end = end;
+                        if (event.reason)
+                            trip.stopReason = event.reason;
+                    }
                     modelStreamOpenedAt = null;
                 }
             }
             if (event.type === "tool_start") {
                 const counter = toolInvocationCounter++;
                 const sid = spanId();
+                // Recorded here, not at `tool_done`: a tool the run's death interrupts
+                // never reaches that path, and would then hang under the trace root
+                // instead of the call that asked for it. The model_stream bracket
+                // closes before the turn's tools start, so the last round-trip is the
+                // requesting call.
+                if (modelRoundTrips.length > 0) {
+                    toolSpanRoundTrip.set(sid, modelRoundTrips.length - 1);
+                    toolCounterRoundTrip.set(counter, modelRoundTrips.length - 1);
+                }
                 // Start the OTel tool span synchronously-ish: kick off the async
                 // resolution and stash the span once it lands. Tool spans are short
                 // and the api tracer is synchronous in practice, but we tolerate the
@@ -589,8 +632,10 @@ export async function instrumentAgentLoop(opts) {
                     : typeof event.result === "string" &&
                         (event.result.startsWith("Error") ||
                             event.result.startsWith("Error running "));
-                if (isError)
+                if (isError) {
                     failedTools++;
+                    reportedToolFailures++;
+                }
                 else
                     successfulTools++;
                 if (counter !== undefined &&
@@ -647,8 +692,14 @@ export async function instrumentAgentLoop(opts) {
                 const spanMetadata = Object.keys(spanMetadataFields).length
                     ? spanMetadataFields
                     : null;
+                const toolSpanId = pending?.spanId ?? spanId();
+                // The model_stream bracket closes before the turn's tools start, so the
+                // last recorded round-trip is the call that requested this one.
+                if (isError) {
+                    toolSpanErrorClass.set(toolSpanId, explicitError ? "tool_error" : "legacy_inferred_error");
+                }
                 const span = {
-                    id: pending?.spanId ?? spanId(),
+                    id: toolSpanId,
                     runId,
                     threadId,
                     userId,
@@ -675,12 +726,30 @@ export async function instrumentAgentLoop(opts) {
         catch { }
         loopOpts.send(event);
     };
+    // The loop appends to this array in place — its own assistant turns, tool
+    // results, internal continuation prompts. Read after the run it is the final
+    // transcript, not the request, so the model's reply showed up inside
+    // `$ai_input` as well as `$ai_output_choices`. Snapshot the array before the
+    // loop can grow it. The message objects stay shared on purpose: the last user
+    // message is enriched in place (screen context, @-mention responses), and the
+    // enriched text is what the model actually received.
+    const requestMessages = Array.isArray(loopOpts.messages)
+        ? [...loopOpts.messages]
+        : loopOpts.messages;
     try {
         usage = await runAgentLoop({
             ...loopOpts,
             runId,
             send: instrumentedSend,
             onOutcome: instrumentedOutcome,
+            // Fires once per model round-trip with THAT call's tokens, not the
+            // running total — which is what lets each generation report its own.
+            onUsage: (callUsage) => {
+                const trip = currentRoundTrip();
+                if (trip)
+                    trip.usage = callUsage;
+                loopOpts.onUsage?.(callUsage);
+            },
         });
     }
     catch (err) {
@@ -711,8 +780,12 @@ export async function instrumentAgentLoop(opts) {
             // The loop threw or was killed mid-stream, so no `end` ever arrived. The
             // model was still running when the run stopped, so the interval closes at
             // the run's end rather than being dropped.
+            const failedInsideModelCall = modelStreamOpenedAt !== null;
             if (modelStreamOpenedAt !== null) {
                 modelStreamIntervals.push({ start: modelStreamOpenedAt, end: runEnd });
+                const trip = currentRoundTrip();
+                if (trip)
+                    trip.end = runEnd;
                 modelStreamOpenedAt = null;
             }
             // Undefined means the engine never bracketed its model calls, NOT that
@@ -730,6 +803,7 @@ export async function instrumentAgentLoop(opts) {
                     toolCallCount += 1;
                     failedTools += 1;
                     const interruptedMessage = "Tool call interrupted before completion";
+                    toolSpanErrorClass.set(pending.spanId, "interrupted");
                     if (counter < MAX_TRACKED_GENERATION_TOOL_CALLS) {
                         generationToolCalls.set(counter, {
                             name: pending.toolName,
@@ -781,8 +855,11 @@ export async function instrumentAgentLoop(opts) {
                 toolCallIdToCounter.clear();
             }
             let costCentsX100 = 0;
+            // Held for the per-generation costs below, which price each round-trip
+            // from its own tokens rather than splitting the run total.
+            let calculateCost;
             try {
-                const { calculateCost } = await import("../usage/store.js");
+                ({ calculateCost } = await import("../usage/store.js"));
                 if (usage) {
                     costCentsX100 = calculateCost(usage.inputTokens, usage.outputTokens, usage.model, usage.cacheReadTokens, usage.cacheWriteTokens);
                 }
@@ -813,6 +890,15 @@ export async function instrumentAgentLoop(opts) {
             const emittedToolSpans = (config.captureLlmSpans ? collectedToolSpans : []).slice(0, MAX_AI_SPANS_PER_RUN);
             const droppedToolSpans = (config.captureLlmSpans ? collectedToolSpans.length : 0) -
                 emittedToolSpans.length;
+            // Elapsed to the run's first engine event. Belongs to the run, and is
+            // reported on its first generation as PostHog's per-call field.
+            const runFirstTokenMs = usage?.firstEngineEventAtMs !== undefined
+                ? Math.max(0, usage.firstEngineEventAtMs - runStart)
+                : undefined;
+            const modelCallFailed = failedInsideModelCall ||
+                (modelRoundTrips.length === 0 &&
+                    cutOffReason === null &&
+                    reportedToolFailures === 0);
             let llmCallCount = 0;
             if (usage || runStatus === "error") {
                 llmCallCount =
@@ -820,7 +906,7 @@ export async function instrumentAgentLoop(opts) {
                         // Compatibility for custom loop implementations that predate the
                         // attempt counter: a measured run still counts as one call.
                         1;
-                const generationUsage = usage ?? {
+                const runUsage = usage ?? {
                     inputTokens: 0,
                     outputTokens: 0,
                     cacheReadTokens: 0,
@@ -829,15 +915,13 @@ export async function instrumentAgentLoop(opts) {
                 };
                 // The engine never reported a `usage` event for this run (killed for
                 // silence before any provider response, or the loop threw before
-                // returning). `generationUsage`'s token fields are placeholder zeros in
-                // that case, not measured values — the tracking event below must omit
-                // them rather than report a fabricated 0.
+                // returning). `runUsage`'s token fields are placeholder zeros in that
+                // case, not measured values — the tracking events below must omit them
+                // rather than report a fabricated 0.
                 const usageReported = usage?.usageReported === true;
-                const firstTokenMs = usage?.firstEngineEventAtMs !== undefined
-                    ? Math.max(0, usage.firstEngineEventAtMs - runStart)
+                const engineName = typeof loopOpts.engine?.name === "string"
+                    ? loopOpts.engine.name
                     : undefined;
-                const llmSpanId = spanId();
-                const generationToolSpans = collectedToolSpans;
                 // Measured model time when the engine bracketed its round-trips.
                 //
                 // The fallback backs tool time out of the run instead, which is an
@@ -845,79 +929,164 @@ export async function instrumentAgentLoop(opts) {
                 // skip tools PostHog will not receive, and clamp at zero. Engines that
                 // report `model_stream` need none of that, so `latency_source` records
                 // which of the two a given `$ai_latency` came from.
-                const llmDurationMs = measuredModelDurationMs ??
+                const derivedLlmDurationMs = measuredModelDurationMs ??
                     Math.max(0, totalDurationMs -
                         coveredDurationMs(spanIntervals(emittedToolSpans)));
-                const generationContent = buildGenerationContent({
-                    config,
-                    messages: loopOpts.messages,
-                    tools: loopOpts.tools,
-                    assistantText: assistantTextParts.join(""),
-                    toolSpans: generationToolSpans,
-                });
-                const llmSpan = {
-                    id: llmSpanId,
-                    runId,
-                    threadId,
-                    userId,
-                    parentSpanId,
-                    spanType: "llm_call",
-                    name: generationUsage.model,
-                    inputTokens: generationUsage.inputTokens,
-                    outputTokens: generationUsage.outputTokens,
-                    cacheReadTokens: generationUsage.cacheReadTokens,
-                    cacheWriteTokens: generationUsage.cacheWriteTokens,
-                    costCentsX100,
-                    durationMs: totalDurationMs,
-                    status: runStatus,
-                    errorMessage,
-                    metadata: null,
-                    createdAt: runStart,
-                };
-                spans.push(llmSpan);
-                emitLlmGenerationTrackingEvent({
-                    runId,
-                    threadId,
-                    userId,
-                    parentSpanId,
-                    llmSpanId,
-                    engineName: typeof loopOpts.engine?.name === "string"
-                        ? loopOpts.engine.name
-                        : undefined,
-                    model: generationUsage.model,
-                    inputTokens: usageReported ? generationUsage.inputTokens : undefined,
-                    outputTokens: usageReported
-                        ? generationUsage.outputTokens
-                        : undefined,
-                    cacheReadTokens: usageReported
-                        ? generationUsage.cacheReadTokens
-                        : undefined,
-                    cacheWriteTokens: usageReported
-                        ? generationUsage.cacheWriteTokens
-                        : undefined,
-                    costCentsX100: usageReported ? costCentsX100 : undefined,
-                    durationMs: totalDurationMs,
-                    llmDurationMs,
-                    llmDurationMeasured: measuredModelDurationMs !== undefined,
-                    llmCallCount,
-                    firstTokenMs,
-                    status: runStatus,
-                    errorMessage,
-                    toolCalls: toolCallCount,
-                    successfulTools,
-                    failedTools,
-                    tools: [...generationToolCalls.entries()]
-                        .sort(([a], [b]) => a - b)
-                        .map(([, detail]) => detail),
-                    toolsTruncated: toolInvocationCounter > MAX_TRACKED_GENERATION_TOOL_CALLS,
-                    terminalOutcome: effectiveTerminalOutcome,
-                    delegation: opts.delegation,
-                    createdAt: runStart,
-                    experimentAssignments: opts.experimentAssignments,
-                    modelSelectionSource: opts.modelSelectionSource,
-                    browserSessionId,
-                    ...generationContent,
-                });
+                // One generation per model round-trip, so a trace reads as the run
+                // actually happened: call, its tools, next call. An engine that never
+                // brackets its calls records no round-trips and falls back to a single
+                // generation covering the run — an aggregate, and visibly one.
+                const generations = modelRoundTrips.length > 0
+                    ? modelRoundTrips.map((trip, index) => ({
+                        spanId: trip.spanId,
+                        model: trip.usage?.model ?? runUsage.model,
+                        createdAt: trip.start,
+                        latencyMs: Math.max(0, trip.end - trip.start),
+                        callUsage: trip.usage,
+                        stopReason: trip.stopReason,
+                        // The engine reported this call's usage as the call happened,
+                        // so its presence IS the report — the loop's aggregate return
+                        // value never arrives when a later call throws, and gating on
+                        // it dropped the tokens of every call that had succeeded.
+                        tokensKnown: trip.usage !== undefined,
+                        input: trip.input,
+                        assistantText: trip.assistantText.join(""),
+                        toolSpans: collectedToolSpans.filter((span) => toolSpanRoundTrip.get(span.id) === index),
+                        toolDetails: [...generationToolCalls.entries()]
+                            .filter(([counter]) => toolCounterRoundTrip.get(counter) === index)
+                            .sort(([a], [b]) => a - b)
+                            .map(([, detail]) => detail),
+                        isFirst: index === 0,
+                        // Only the last call can carry the run's failure: an earlier
+                        // one that had failed would have ended the run there.
+                        isLast: index === modelRoundTrips.length - 1,
+                    }))
+                    : [
+                        {
+                            spanId: spanId(),
+                            model: runUsage.model,
+                            createdAt: runStart,
+                            latencyMs: derivedLlmDurationMs,
+                            callUsage: usage,
+                            stopReason: undefined,
+                            tokensKnown: usageReported,
+                            input: requestMessages,
+                            assistantText: assistantTextParts.join(""),
+                            toolSpans: collectedToolSpans,
+                            toolDetails: [...generationToolCalls.entries()]
+                                .sort(([a], [b]) => a - b)
+                                .map(([, detail]) => detail),
+                            isFirst: true,
+                            isLast: true,
+                        },
+                    ];
+                for (const generation of generations) {
+                    const callUsage = generation.callUsage;
+                    let callCostCentsX100;
+                    if (calculateCost && callUsage && generation.tokensKnown) {
+                        try {
+                            callCostCentsX100 = calculateCost(callUsage.inputTokens, callUsage.outputTokens, callUsage.model, callUsage.cacheReadTokens, callUsage.cacheWriteTokens);
+                            // Cost estimation is enrichment: a pricing-table miss leaves the
+                            // generation without a cost rather than failing the trace.
+                        }
+                        catch { } // coercion-ok: see above
+                    }
+                    // `$ai_is_error` on a generation means the MODEL call failed —
+                    // a provider error, a dropped stream, an SDK throw. A tool that
+                    // aborted the run, a step budget or a cut-off is the trace's failure
+                    // (and the tool span's), and painting the last generation red hides
+                    // which layer actually broke.
+                    //
+                    // Two ways to know it was the model: the run died with this call's
+                    // stream still open, or the engine never bracketed its calls at all
+                    // and nothing else can account for the failure — no run boundary, no
+                    // failed tool.
+                    const generationStatus = 
+                    // The engine reported this call itself as failed. Its bracket
+                    // closes on the way out, so waiting for an open stream at
+                    // finalization would report a provider error as a healthy call —
+                    // and a later retry would leave the failed attempt green.
+                    generation.stopReason === "error" ||
+                        (generation.isLast && runStatus === "error" && modelCallFailed)
+                        ? "error"
+                        : "success";
+                    const generationError = generationStatus === "error" ? errorMessage : null;
+                    const generationContent = buildGenerationContent({
+                        config,
+                        messages: generation.input,
+                        assistantText: generation.assistantText,
+                        toolSpans: generation.toolSpans,
+                    });
+                    spans.push({
+                        id: generation.spanId,
+                        runId,
+                        threadId,
+                        userId,
+                        parentSpanId,
+                        spanType: "llm_call",
+                        name: generation.model,
+                        inputTokens: callUsage?.inputTokens ?? 0,
+                        outputTokens: callUsage?.outputTokens ?? 0,
+                        cacheReadTokens: callUsage?.cacheReadTokens ?? 0,
+                        cacheWriteTokens: callUsage?.cacheWriteTokens ?? 0,
+                        costCentsX100: callCostCentsX100 ?? 0,
+                        durationMs: generation.latencyMs,
+                        status: generationStatus,
+                        errorMessage: generationError,
+                        metadata: null,
+                        createdAt: generation.createdAt,
+                    });
+                    emitLlmGenerationTrackingEvent({
+                        runId,
+                        threadId,
+                        userId,
+                        parentSpanId,
+                        llmSpanId: generation.spanId,
+                        engineName,
+                        model: generation.model,
+                        inputTokens: generation.tokensKnown
+                            ? callUsage?.inputTokens
+                            : undefined,
+                        outputTokens: generation.tokensKnown
+                            ? callUsage?.outputTokens
+                            : undefined,
+                        cacheReadTokens: generation.tokensKnown
+                            ? callUsage?.cacheReadTokens
+                            : undefined,
+                        cacheWriteTokens: generation.tokensKnown
+                            ? callUsage?.cacheWriteTokens
+                            : undefined,
+                        costCentsX100: callCostCentsX100,
+                        durationMs: generation.latencyMs,
+                        llmDurationMs: generation.latencyMs,
+                        llmDurationMeasured: measuredModelDurationMs !== undefined,
+                        stopReason: generation.stopReason,
+                        // One request per generation now. `$ai_request_count` is what
+                        // PostHog multiplies by per-request pricing, so it counts this
+                        // call, not the run.
+                        llmCallCount: modelRoundTrips.length > 0 ? 1 : llmCallCount,
+                        firstTokenMs: generation.isFirst ? runFirstTokenMs : undefined,
+                        status: generationStatus,
+                        errorMessage: generationError,
+                        toolCalls: generation.toolSpans.length,
+                        successfulTools: generation.toolSpans.filter((span) => span.status === "success").length,
+                        failedTools: generation.toolSpans.filter((span) => span.status === "error").length,
+                        tools: generation.toolDetails,
+                        toolsTruncated: toolInvocationCounter > MAX_TRACKED_GENERATION_TOOL_CALLS,
+                        // Only the layer that failed carries the run's terminal outcome;
+                        // on a healthy call `terminal_state: failed` reads as this call
+                        // having failed.
+                        terminalOutcome: generationStatus === "error"
+                            ? effectiveTerminalOutcome
+                            : undefined,
+                        delegation: opts.delegation,
+                        createdAt: generation.createdAt,
+                        experimentAssignments: opts.experimentAssignments,
+                        modelSelectionSource: opts.modelSelectionSource,
+                        browserSessionId,
+                        ...generationContent,
+                    });
+                }
             }
             const parentSpan = {
                 id: parentSpanId,
@@ -959,22 +1128,6 @@ export async function instrumentAgentLoop(opts) {
                 const provider = llmProviderFromEngine(typeof loopOpts.engine?.name === "string"
                     ? loopOpts.engine.name
                     : undefined, usage?.model ?? loopOpts.model);
-                // PostHog reads a trace's input/output state ONLY from the `$ai_trace`
-                // event — never from its children — so a trace whose detail view should
-                // show what the run was asked and what it answered has to carry them
-                // here. Gated on `capturePrompts` and omitted, not emptied, when off.
-                const traceInputState = config.capturePrompts
-                    ? redactSensitiveFields(loopOpts.messages)
-                    : undefined;
-                const traceAssistantText = assistantTextParts.join("");
-                const traceOutputState = config.capturePrompts && traceAssistantText
-                    ? [
-                        {
-                            role: "assistant",
-                            content: redactToolErrorMessage(traceAssistantText),
-                        },
-                    ]
-                    : undefined;
                 emitAiTraceEvent({
                     runId,
                     threadId,
@@ -985,6 +1138,16 @@ export async function instrumentAgentLoop(opts) {
                     durationMs: totalDurationMs,
                     isError: runStatus === "error",
                     error: aiError,
+                    // What ended the run: our own budget or timeout (`run_timeout`,
+                    // `no_progress`), a terminal outcome code, or a failure with neither.
+                    errorType: runStatus === "error"
+                        ? (cutOffReason ??
+                            (effectiveTerminalOutcome?.state === "failed" ||
+                                effectiveTerminalOutcome?.state === "input_required"
+                                ? effectiveTerminalOutcome.code
+                                : undefined) ??
+                            effectiveTerminalOutcome?.state)
+                        : undefined,
                     inputTokens: usage?.usageReported ? usage.inputTokens : undefined,
                     outputTokens: usage?.usageReported ? usage.outputTokens : undefined,
                     costUsd: usage?.usageReported
@@ -992,13 +1155,20 @@ export async function instrumentAgentLoop(opts) {
                         : undefined,
                     createdAt: runStart,
                     browserSessionId,
-                    inputState: traceInputState,
-                    outputState: traceOutputState,
                     extraProperties: {
                         ...trackingIdentityProperties(),
                         source: "agent_observability",
                         run_id: runId,
                         thread_id: threadId,
+                        // Run totals. Each generation counts only the call it describes, so
+                        // without these the run-level numbers would have to be summed back
+                        // out of the children.
+                        llm_calls: llmCallCount || undefined,
+                        tool_calls: toolCallCount,
+                        successful_tools: successfulTools,
+                        failed_tools: failedTools,
+                        time_to_first_token_ms: runFirstTokenMs,
+                        latency_source: measuredModelDurationMs !== undefined ? "measured" : "derived",
                         ...aiTraceMetadataProperties(runMetadata),
                         // Present for planned boundaries too, which are not errors: the ratio
                         // of run_timeout to no_progress is the signal, and it is unreadable
@@ -1026,17 +1196,35 @@ export async function instrumentAgentLoop(opts) {
                         config.captureToolResults
                         ? truncateToolErrorMessage(redactToolErrorMessage(span.errorMessage))
                         : undefined;
+                    // "Withheld" and "never reported" are different failures to debug,
+                    // and a span that says only `$ai_is_error` tells the reader neither.
+                    const toolErrorDetail = span.status !== "error"
+                        ? undefined
+                        : toolErrorMessage
+                            ? toAiErrorDetail(toolErrorMessage)
+                            : span.errorMessage
+                                ? {
+                                    message: "error text withheld: captureToolResults is off for this app",
+                                }
+                                : undefined;
+                    const requestingGeneration = toolSpanRoundTrip.get(span.id);
                     emitAiSpanEvent({
                         runId,
                         threadId,
                         userId,
                         spanId: span.id,
+                        // Under the generation that asked for it, so PostHog draws the run
+                        // as call → tools → call. Falls back to the trace root when the
+                        // engine never bracketed its model calls and there is no
+                        // generation to hang the tool under.
+                        parentId: requestingGeneration !== undefined
+                            ? modelRoundTrips[requestingGeneration]?.spanId
+                            : undefined,
                         spanName: span.name,
                         latencySeconds: Math.round(span.durationMs) / 1000,
                         isError: span.status === "error",
-                        error: toolErrorMessage
-                            ? toAiErrorDetail(toolErrorMessage)
-                            : undefined,
+                        error: toolErrorDetail,
+                        errorType: toolSpanErrorClass.get(span.id),
                         createdAt: span.createdAt,
                         browserSessionId,
                         // `metadata.input` / `metadata.output` are already redacted and