@uselemma/tracing 7.6.0 → 7.7.0

package/dist/vercel-ai.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.vercelAI = vercelAI;
 const client_1 = require("./client");
 const tool_result_1 = require("./tool-result");
+const CONCURRENT_REUSE_ERROR = "vercelAI() is already tracing a run. Create a new vercelAI() integration per concurrent AI SDK operation.";
 function addMs(startedAt, durationMs) {
     return typeof durationMs === "number"
         ? new Date(startedAt.getTime() + durationMs)
@@ -33,6 +34,18 @@ function stringifyContent(content) {
         return text;
     return JSON.stringify(content);
 }
+function structuredAssistantOutput(text, content) {
+    if (typeof text === "string")
+        return text;
+    if (!content)
+        return undefined;
+    const hasNonText = content.some((part) => part &&
+        typeof part === "object" &&
+        part.type !== "text");
+    if (hasNonText)
+        return content;
+    return stringifyContent(content);
+}
 function errorToolFields(error, recordOutputs) {
     return recordOutputs
         ? { error, status: "ERROR" }
@@ -70,25 +83,89 @@ function resolveDurationMs(startedAt, endedAt, reportedMs) {
     // step cannot outlast a too-short reported model-only duration.
     return Math.max(reportedMs, wallMs);
 }
-function v6Input(event) {
-    if ("messages" in event && event.messages)
+function messageContent(message) {
+    if (!message || typeof message !== "object")
+        return message;
+    const record = message;
+    if ("content" in record)
+        return record.content;
+    return message;
+}
+function lookupString(sources, keys) {
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const key of keys) {
+            const value = source[key];
+            if (typeof value === "string" && value)
+                return value;
+        }
+    }
+    return undefined;
+}
+/** Normalize v6 system/prompt/messages into a chat message list when possible. */
+function v6NormalizedMessages(event) {
+    if (Array.isArray(event.messages))
         return event.messages;
-    return "prompt" in event ? event.prompt : undefined;
+    const messages = [];
+    if ("system" in event && typeof event.system === "string" && event.system) {
+        messages.push({ role: "system", content: event.system });
+    }
+    if ("prompt" in event && event.prompt !== undefined) {
+        if (Array.isArray(event.prompt)) {
+            return messages.length > 0
+                ? [...messages, ...event.prompt]
+                : event.prompt;
+        }
+        if (typeof event.prompt === "string") {
+            messages.push({ role: "user", content: event.prompt });
+        }
+    }
+    return messages.length > 0 ? messages : undefined;
+}
+function v6Input(event) {
+    const normalized = v6NormalizedMessages(event);
+    if (normalized)
+        return normalized;
+    if ("prompt" in event)
+        return event.prompt;
+    return undefined;
+}
+/**
+ * Prefer the current user turn for the Lemma root input.
+ * Accepts a bare string, message array, or prompt/system start payload.
+ */
+function rootTraceInput(input) {
+    if (typeof input === "string")
+        return input;
+    if (!Array.isArray(input) || input.length === 0)
+        return input;
+    for (let i = input.length - 1; i >= 0; i--) {
+        const message = input[i];
+        if (!message || typeof message !== "object")
+            continue;
+        const role = message.role;
+        if (role === "user")
+            return messageContent(message);
+    }
+    return messageContent(input[input.length - 1]);
 }
-function traceInput(event) {
+function eventTraceInput(event) {
     if (!event)
         return undefined;
+    if ("messages" in event || "prompt" in event || "system" in event) {
+        if (!("callId" in event) || "model" in event) {
+            return v6Input(event);
+        }
+    }
     if ("messages" in event && event.messages)
         return event.messages;
     if ("prompt" in event)
         return event.prompt;
     return undefined;
 }
-function traceMetadata(options, event) {
-    return {
-        ...options.metadata,
-        ...(event && "metadata" in event ? (event.metadata ?? {}) : {}),
-    };
+function eventMetadata(event) {
+    return event && "metadata" in event ? (event.metadata ?? undefined) : undefined;
 }
 function traceName(options, event) {
     if (options.agentName)
@@ -98,31 +175,61 @@ function traceName(options, event) {
         : undefined;
     return functionId || "vercel-ai-agent";
 }
-function v6InputMessages(event) {
-    const input = v6Input(event);
-    return Array.isArray(input) ? input : undefined;
-}
 function v6Output(event) {
-    if (typeof event.text === "string")
-        return event.text;
-    if (event.content)
-        return stringifyContent(event.content);
-    return undefined;
+    return structuredAssistantOutput(event.text, event.content);
+}
+function endOutput(event) {
+    return structuredAssistantOutput(event.text, event.content);
+}
+function errorMessage(error) {
+    if (typeof error === "string" && error)
+        return error;
+    if (error instanceof Error && error.message)
+        return error.message;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
 }
 function vercelAI(options = {}) {
     let lemma = options.lemma;
-    const modelCalls = new Map();
-    const v7Steps = new Map();
-    const v6Steps = new Map();
-    const v6Starts = [];
-    const generationSpanIdsByCallId = new Map();
-    const generationSpanIdsByToolCallId = new Map();
-    const generationHandlesById = new Map();
-    const toolExecutions = new Map();
+    const pending = new Set();
+    let phase = "idle";
+    let modelCalls = new Map();
+    let v7Steps = new Map();
+    let v6Steps = new Map();
+    let v6Starts = [];
+    let generationSpanIdsByCallId = new Map();
+    let generationSpanIdsByToolCallId = new Map();
+    let generationHandlesById = new Map();
+    let toolExecutions = new Map();
+    let latestV6GenerationId;
     let managedTrace;
     let recordedV6Step = false;
-    let endedExplicitTrace = false;
-    let endedManagedTrace = false;
+    let sawV7StepZero = false;
+    let runStartedAt;
+    let runError;
+    let endingTrace;
+    function resetRunState() {
+        phase = "idle";
+        modelCalls = new Map();
+        v7Steps = new Map();
+        v6Steps = new Map();
+        v6Starts = [];
+        generationSpanIdsByCallId = new Map();
+        generationSpanIdsByToolCallId = new Map();
+        generationHandlesById = new Map();
+        toolExecutions = new Map();
+        latestV6GenerationId = undefined;
+        managedTrace = undefined;
+        recordedV6Step = false;
+        sawV7StepZero = false;
+        runStartedAt = undefined;
+        runError = undefined;
+        endingTrace = undefined;
+    }
     function trackGeneration(handle) {
         generationHandlesById.set(handle.id, handle);
     }
@@ -140,55 +247,188 @@ function vercelAI(options = {}) {
         });
         return lemma;
     }
+    function resolveThreadId(metadata) {
+        const key = options.threadIdKey ?? "threadId";
+        return lookupString([metadata, options.metadata], [key]);
+    }
+    function resolveUserId(metadata) {
+        const key = options.userIdKey ?? "userId";
+        return lookupString([metadata, options.metadata], [key]);
+    }
+    function mergedMetadata(metadata) {
+        return {
+            ...options.metadata,
+            ...(metadata ?? {}),
+        };
+    }
+    function beginActivity() {
+        if (phase === "idle") {
+            phase = "active";
+            runStartedAt = new Date();
+        }
+    }
+    function beginNewRun() {
+        if (phase === "active" || phase === "ending") {
+            throw new Error(CONCURRENT_REUSE_ERROR);
+        }
+        resetRunState();
+        phase = "active";
+        runStartedAt = new Date();
+    }
+    function hasExplicitEndableTrace() {
+        const trace = options.trace;
+        return Boolean(trace && typeof trace.end === "function");
+    }
+    function applyIdentity(trace, metadata) {
+        const threadId = resolveThreadId(metadata);
+        const userId = resolveUserId(metadata);
+        if (threadId)
+            trace.threadId(threadId);
+        if (userId)
+            trace.userId(userId);
+    }
+    function rootErrorPayload(message) {
+        // Preserve ERROR status while redacting message bodies when outputs are off.
+        return options.recordOutputs === false ? "error" : message;
+    }
     function resolveTrace(event) {
-        if (options.trace)
+        // Trailing AI SDK callbacks can arrive while terminal delivery is in flight.
+        // Attach them to the still-open trace instead of throwing.
+        if (phase === "ending") {
+            const trace = options.trace ?? managedTrace;
+            return trace
+                ? {
+                    trace,
+                    source: options.trace ? "explicit" : "managed",
+                }
+                : null;
+        }
+        beginActivity();
+        const metadata = eventMetadata(event);
+        if (options.trace) {
+            applyIdentity(options.trace, metadata);
             return { trace: options.trace, source: "explicit" };
+        }
         if (!managedTrace) {
+            const rawInput = options.recordInputs === false ? undefined : eventTraceInput(event);
             managedTrace = getLemma().trace({
                 name: traceName(options, event),
-                input: options.recordInputs === false ? undefined : traceInput(event),
-                metadata: traceMetadata(options, event),
+                input: options.recordInputs === false
+                    ? undefined
+                    : rootTraceInput(rawInput),
+                metadata: mergedMetadata(metadata),
+                threadId: resolveThreadId(metadata),
+                userId: resolveUserId(metadata),
+                startedAt: runStartedAt,
             });
         }
+        else {
+            applyIdentity(managedTrace, metadata);
+            if (options.recordInputs !== false && event) {
+                const rawInput = eventTraceInput(event);
+                if (rawInput !== undefined) {
+                    // Keep root input as the latest known current-turn value.
+                    managedTrace.input(rootTraceInput(rawInput));
+                }
+            }
+        }
         return { trace: managedTrace, source: "managed" };
     }
-    function endOutput(event) {
-        if (typeof event.text === "string")
-            return event.text;
-        if (event.content)
-            return stringifyContent(event.content);
-        return undefined;
+    function trackPending(promise) {
+        pending.add(promise);
+        void promise.finally(() => pending.delete(promise));
+        return promise;
+    }
+    function ensureManagedTrace(event) {
+        if (options.trace || managedTrace)
+            return;
+        beginActivity();
+        managedTrace = getLemma().trace({
+            name: traceName(options, event),
+            metadata: mergedMetadata(eventMetadata(event)),
+            threadId: resolveThreadId(eventMetadata(event)),
+            userId: resolveUserId(eventMetadata(event)),
+            startedAt: runStartedAt,
+        });
     }
     async function endOwnedTrace(event) {
+        if (phase === "idle")
+            return;
+        if (phase === "ending")
+            return;
+        phase = "ending";
         const trace = options.trace;
         let ownedTrace;
+        let explicit = false;
         if (trace && typeof trace.end === "function") {
-            ownedTrace = { trace: { end: trace.end.bind(trace) }, explicit: true };
-        }
-        else if (managedTrace) {
-            ownedTrace = { trace: managedTrace, explicit: false };
-        }
-        if (!ownedTrace)
-            return;
-        if (ownedTrace.explicit) {
-            if (endedExplicitTrace)
-                return;
-            endedExplicitTrace = true;
+            explicit = true;
+            ownedTrace = {
+                end: trace.end.bind(trace),
+                fail: trace.fail.bind(trace),
+                output: trace.output.bind(trace),
+            };
         }
         else {
-            if (endedManagedTrace)
-                return;
-            endedManagedTrace = true;
+            ensureManagedTrace(event);
+            if (managedTrace) {
+                ownedTrace = managedTrace;
+            }
         }
-        const output = endOutput(event);
-        if (options.recordOutputs === false || output === undefined) {
-            await ownedTrace.trace.end();
-            return;
+        const identityTrace = (options.trace ?? managedTrace);
+        if (identityTrace) {
+            applyIdentity(identityTrace, eventMetadata(event));
+        }
+        const eventError = "error" in event && event.error != null
+            ? errorMessage(event.error)
+            : undefined;
+        if (eventError && !runError) {
+            runError = eventError;
         }
-        await ownedTrace.trace.end({ output });
+        const endedAt = new Date();
+        const startedAt = runStartedAt ?? endedAt;
+        const durationMs = Math.max(0, endedAt.getTime() - startedAt.getTime());
+        const successOutput = endOutput(event);
+        endingTrace = ownedTrace;
+        const endPromise = (async () => {
+            try {
+                if (!ownedTrace)
+                    return;
+                // Yield so a racing fail()/trailing callback in this turn can settle.
+                await Promise.resolve();
+                const terminalError = runError;
+                // Explicit handles already own startedAt from construction; only pass
+                // durationMs for managed traces we started with runStartedAt.
+                const timing = explicit
+                    ? { endedAt }
+                    : { durationMs, endedAt };
+                if (terminalError) {
+                    ownedTrace.fail(rootErrorPayload(terminalError));
+                    ownedTrace.output(undefined);
+                    await ownedTrace.end(timing);
+                    return;
+                }
+                if (options.recordOutputs === false || successOutput === undefined) {
+                    await ownedTrace.end(timing);
+                }
+                else {
+                    await ownedTrace.end({
+                        output: successOutput,
+                        ...timing,
+                    });
+                }
+            }
+            finally {
+                // Fully reset so the same integration object can be reused sequentially.
+                resetRunState();
+            }
+        })();
+        await trackPending(endPromise);
     }
     function recordV6Generation(event, stored) {
-        const { trace } = resolveTrace(stored?.event);
+        const resolved = resolveTrace(stored?.event);
+        if (!resolved)
+            return;
+        const { trace } = resolved;
         const startedAt = stored?.startedAt ?? new Date();
         const endedAt = new Date();
         const durationMs = resolveDurationMs(startedAt, endedAt, undefined);
@@ -197,12 +437,17 @@ function vercelAI(options = {}) {
             ? options.generationName(event)
             : (options.generationName ?? "vercel-ai-generation");
         const output = v6Output(event);
+        const generationError = "error" in event && event.error != null
+            ? errorMessage(event.error)
+            : undefined;
         const generation = {
             name,
             input: options.recordInputs === false
                 ? undefined
                 : stored?.event && v6Input(stored.event),
-            output: options.recordOutputs === false ? undefined : output,
+            output: options.recordOutputs === false || generationError
+                ? undefined
+                : output,
             metadata: options.metadata,
             model: event.model.modelId,
             startedAt,
@@ -211,15 +456,19 @@ function vercelAI(options = {}) {
             llmProvider: event.model.provider,
             llmInputMessages: options.recordInputs === false || !stored?.event
                 ? undefined
-                : v6InputMessages(stored.event),
-            llmOutputMessages: options.recordOutputs === false || output === undefined
+                : v6NormalizedMessages(stored.event),
+            llmOutputMessages: options.recordOutputs === false ||
+                output === undefined ||
+                generationError
                 ? undefined
                 : [{ role: "assistant", content: output }],
             llmTools: stored?.event.tools,
+            status: generationError ? "ERROR" : undefined,
+            error: options.recordOutputs === false ? undefined : generationError,
         };
         if (stored?.handle) {
             stored.handle.end(generation);
-            generationSpanIdsByCallId.set("v6-latest", stored.handle.id);
+            latestV6GenerationId = stored.handle.id;
             trackGeneration(stored.handle);
             return;
         }
@@ -227,10 +476,19 @@ function vercelAI(options = {}) {
             id,
             ...generation,
         });
-        generationSpanIdsByCallId.set("v6-latest", id);
+        latestV6GenerationId = id;
     }
     function startV7Generation(event) {
-        const { trace } = resolveTrace(event);
+        if (event.stepNumber === 0) {
+            if (sawV7StepZero && phase === "active") {
+                throw new Error(CONCURRENT_REUSE_ERROR);
+            }
+            sawV7StepZero = true;
+        }
+        const resolved = resolveTrace(event);
+        if (!resolved)
+            return;
+        const { trace } = resolved;
         const name = typeof options.generationName === "function"
             ? options.generationName({
                 callId: event.callId,
@@ -256,8 +514,11 @@ function vercelAI(options = {}) {
         generationSpanIdsByCallId.set(event.callId, handle.id);
         trackGeneration(handle);
     }
-    function startV6Generation(event) {
-        const { trace } = resolveTrace(event);
+    function startV6Generation(event, key) {
+        const resolved = resolveTrace(event);
+        if (!resolved)
+            return undefined;
+        const { trace } = resolved;
         const startedAt = new Date();
         const name = typeof options.generationName === "function"
             ? options.generationName({
@@ -273,44 +534,68 @@ function vercelAI(options = {}) {
             model: event.model.modelId,
             startedAt,
             llmProvider: event.model.provider,
-            llmInputMessages: options.recordInputs === false ? undefined : v6InputMessages(event),
+            llmInputMessages: options.recordInputs === false
+                ? undefined
+                : v6NormalizedMessages(event),
             llmTools: event.tools,
         });
-        generationSpanIdsByCallId.set("v6-latest", handle.id);
+        latestV6GenerationId = handle.id;
         trackGeneration(handle);
-        return { event, startedAt, handle };
+        return { event, startedAt, handle, key };
     }
     function endV7Generation(event) {
-        const stored = v7Steps.get(v7StepKey(event.callId, event.stepNumber));
-        v7Steps.delete(v7StepKey(event.callId, event.stepNumber));
+        const key = v7StepKey(event.callId, event.stepNumber);
+        const stored = v7Steps.get(key);
+        v7Steps.delete(key);
         if (!stored)
             return;
         const endedAt = new Date();
         const durationMs = resolveDurationMs(stored.startedAt, endedAt, event.performance?.stepTimeMs ?? event.performance?.responseTimeMs);
-        const output = typeof event.text === "string"
-            ? event.text
-            : event.content
-                ? stringifyContent(event.content)
-                : undefined;
+        const output = structuredAssistantOutput(event.text, event.content);
+        const generationError = event.error != null ? errorMessage(event.error) : undefined;
         for (const toolCall of event.toolCalls ?? []) {
             if (toolCall.toolCallId) {
                 generationSpanIdsByToolCallId.set(toolCall.toolCallId, stored.handle.id);
             }
         }
         stored.handle.end({
-            output: options.recordOutputs === false ? undefined : output,
+            output: options.recordOutputs === false || generationError
+                ? undefined
+                : output,
             model: event.model.modelId,
             durationMs,
             endedAt: addMs(stored.startedAt, durationMs),
             llmProvider: event.model.provider,
-            llmOutputMessages: options.recordOutputs === false || output === undefined
+            llmOutputMessages: options.recordOutputs === false ||
+                output === undefined ||
+                generationError
                 ? undefined
                 : [{ role: "assistant", content: output }],
+            status: generationError ? "ERROR" : undefined,
+            error: options.recordOutputs === false ? undefined : generationError,
         });
     }
-    return {
+    function resolveToolParentId(callId, toolCallId) {
+        return ((toolCallId && generationSpanIdsByToolCallId.get(toolCallId)) ||
+            (callId ? generationSpanIdsByCallId.get(callId) : undefined) ||
+            latestV6GenerationId);
+    }
+    const integration = {
         onLanguageModelCallStart(event) {
-            const { trace } = resolveTrace(event);
+            if (phase === "active" &&
+                generationSpanIdsByCallId.size > 0 &&
+                !generationSpanIdsByCallId.has(event.callId)) {
+                const belongsToActiveStep = [...v7Steps.values()].some((step) => step.event.callId === event.callId);
+                // Multi-step v7 registers the next callId on step start before the
+                // model callback. Any other new callId is concurrent reuse.
+                if (!belongsToActiveStep) {
+                    throw new Error(CONCURRENT_REUSE_ERROR);
+                }
+            }
+            const resolved = resolveTrace(event);
+            if (!resolved)
+                return;
+            const { trace } = resolved;
             if (generationSpanIdsByCallId.has(event.callId)) {
                 modelCalls.set(event.callId, { event, startedAt: new Date() });
                 return;
@@ -340,32 +625,32 @@ function vercelAI(options = {}) {
             trackGeneration(handle);
         },
         onLanguageModelCallEnd(event) {
+            if (phase !== "active" && phase !== "ending")
+                return;
             const stored = modelCalls.get(event.callId);
             modelCalls.delete(event.callId);
             if (!stored?.handle)
                 return;
             const endedAt = new Date();
             const durationMs = resolveDurationMs(stored.startedAt, endedAt, event.performance.responseTimeMs);
+            const output = structuredAssistantOutput(undefined, event.content);
             stored.handle.end({
-                output: options.recordOutputs === false
-                    ? undefined
-                    : stringifyContent(event.content),
+                output: options.recordOutputs === false ? undefined : output,
                 model: event.modelId,
                 durationMs,
                 endedAt: addMs(stored.startedAt, durationMs),
                 llmProvider: event.provider,
-                llmOutputMessages: options.recordOutputs === false
+                llmOutputMessages: options.recordOutputs === false || output === undefined
                     ? undefined
-                    : [{ role: "assistant", content: stringifyContent(event.content) }],
+                    : [{ role: "assistant", content: output }],
             });
         },
         onToolExecutionStart(event) {
-            const { trace } = resolveTrace();
-            const parentId = (event.toolCall.toolCallId &&
-                generationSpanIdsByToolCallId.get(event.toolCall.toolCallId)) ||
-                (event.callId
-                    ? generationSpanIdsByCallId.get(event.callId)
-                    : generationSpanIdsByCallId.get("v6-latest"));
+            const resolved = resolveTrace();
+            if (!resolved)
+                return;
+            const { trace } = resolved;
+            const parentId = resolveToolParentId(event.callId, event.toolCall.toolCallId);
             const name = typeof options.toolName === "function"
                 ? options.toolName({
                     ...event,
@@ -380,6 +665,7 @@ function vercelAI(options = {}) {
                 input: options.recordInputs === false ? undefined : event.toolCall.input,
                 metadata: options.metadata,
                 startedAt,
+                toolName: event.toolCall.toolName,
             });
             if (event.toolCall.toolCallId) {
                 toolExecutions.set(event.toolCall.toolCallId, {
@@ -390,10 +676,13 @@ function vercelAI(options = {}) {
             }
         },
         onToolCallStart(event) {
-            this.onToolExecutionStart?.(event);
+            integration.onToolExecutionStart?.(event);
         },
         onToolExecutionEnd(event) {
-            const { trace } = resolveTrace();
+            const resolved = resolveTrace();
+            if (!resolved)
+                return;
+            const { trace } = resolved;
             const name = typeof options.toolName === "function"
                 ? options.toolName(event)
                 : (options.toolName ?? event.toolCall.toolName);
@@ -409,6 +698,7 @@ function vercelAI(options = {}) {
                 storedTool.handle.end({
                     durationMs,
                     endedAt: addMs(storedTool.startedAt, durationMs),
+                    toolName: event.toolCall.toolName,
                     ...toolOutput(event, options.recordOutputs !== false),
                 });
                 coverParent(storedTool.parentId, addMs(storedTool.startedAt, durationMs));
@@ -417,14 +707,11 @@ function vercelAI(options = {}) {
             const endedAt = new Date();
             const startedAt = subtractMs(endedAt, event.toolExecutionMs);
             const durationMs = resolveDurationMs(startedAt, endedAt, event.toolExecutionMs);
-            const parentId = (event.toolCall.toolCallId &&
-                generationSpanIdsByToolCallId.get(event.toolCall.toolCallId)) ||
-                (event.callId
-                    ? generationSpanIdsByCallId.get(event.callId)
-                    : generationSpanIdsByCallId.get("v6-latest"));
+            const parentId = resolveToolParentId(event.callId, event.toolCall.toolCallId);
             trace.recordTool({
                 name,
                 parentId,
+                toolName: event.toolCall.toolName,
                 input: options.recordInputs === false ? undefined : event.toolCall.input,
                 metadata: options.metadata,
                 durationMs,
@@ -435,8 +722,10 @@ function vercelAI(options = {}) {
             coverParent(parentId, endedAt);
         },
         onStart(event) {
+            beginNewRun();
             recordedV6Step = false;
-            v6Starts.push({ event, startedAt: new Date() });
+            const key = `start:${v6Starts.length}:${Date.now()}`;
+            v6Starts.push({ event, startedAt: new Date(), key });
             resolveTrace(event);
         },
         onStepStart(event) {
@@ -444,32 +733,60 @@ function vercelAI(options = {}) {
                 startV7Generation(event);
                 return;
             }
-            v6Steps.set(event.stepNumber, startV6Generation(event));
+            const key = `step:${event.stepNumber}`;
+            if (v6Steps.has(key)) {
+                // Duplicate step start for the same step number — ignore.
+                return;
+            }
+            const stored = startV6Generation(event, key);
+            if (stored)
+                v6Steps.set(key, stored);
         },
         onStepEnd(event) {
+            if (phase !== "active" && phase !== "ending")
+                return;
             endV7Generation(event);
         },
         onStepFinish(event) {
+            if (phase !== "active" && phase !== "ending")
+                return;
             recordedV6Step = true;
-            const stored = v6Steps.get(event.stepNumber);
-            v6Steps.delete(event.stepNumber);
+            const key = `step:${event.stepNumber}`;
+            const stored = v6Steps.get(key);
+            v6Steps.delete(key);
             recordV6Generation(event, stored);
         },
         async onFinish(event) {
-            if (recordedV6Step) {
-                v6Starts.shift();
-                recordedV6Step = false;
-                await endOwnedTrace(event);
-                return;
+            if (phase === "idle") {
+                // Terminal-only path for an explicit trace handle with no prior events.
+                if (!hasExplicitEndableTrace())
+                    return;
+                beginActivity();
+            }
+            if (phase === "active") {
+                if (recordedV6Step) {
+                    v6Starts.shift();
+                    recordedV6Step = false;
+                }
+                else {
+                    recordV6Generation(event, v6Starts.shift());
+                }
             }
-            recordV6Generation(event, v6Starts.shift());
             await endOwnedTrace(event);
         },
         async onEnd(event) {
+            if (phase === "idle") {
+                if (!hasExplicitEndableTrace())
+                    return;
+                beginActivity();
+            }
             await endOwnedTrace(event);
         },
         onToolCallFinish(event) {
-            const { trace } = resolveTrace();
+            const resolved = resolveTrace();
+            if (!resolved)
+                return;
+            const { trace } = resolved;
             const name = typeof options.toolName === "function"
                 ? options.toolName(event)
                 : (options.toolName ?? event.toolCall.toolName);
@@ -486,6 +803,7 @@ function vercelAI(options = {}) {
                 storedTool.handle.end({
                     durationMs,
                     endedAt: toolEndedAt,
+                    toolName: event.toolCall.toolName,
                     ...v6ToolOutput(event, options.recordOutputs !== false),
                 });
                 coverParent(storedTool.parentId, toolEndedAt);
@@ -494,12 +812,11 @@ function vercelAI(options = {}) {
             const endedAt = new Date();
             const durationMs = resolveDurationMs(subtractMs(endedAt, event.durationMs), endedAt, event.durationMs);
             const startedAt = subtractMs(endedAt, durationMs);
-            const parentId = (event.toolCall.toolCallId &&
-                generationSpanIdsByToolCallId.get(event.toolCall.toolCallId)) ||
-                generationSpanIdsByCallId.get("v6-latest");
+            const parentId = resolveToolParentId(undefined, event.toolCall.toolCallId);
             trace.recordTool({
                 name,
                 parentId,
+                toolName: event.toolCall.toolName,
                 input: options.recordInputs === false ? undefined : event.toolCall.input,
                 metadata: options.metadata,
                 durationMs,
@@ -509,6 +826,31 @@ function vercelAI(options = {}) {
             });
             coverParent(parentId, endedAt);
         },
+        async fail(error) {
+            const message = errorMessage(error);
+            runError = message;
+            if (phase === "ending") {
+                // Best-effort: apply before the in-flight terminal send reads error state.
+                endingTrace?.fail(rootErrorPayload(message));
+                endingTrace?.output(undefined);
+                return;
+            }
+            if (phase === "idle") {
+                beginActivity();
+            }
+            await endOwnedTrace({ error });
+        },
+        async flush() {
+            await Promise.all(Array.from(pending));
+        },
+        async shutdown() {
+            if (phase === "active") {
+                await endOwnedTrace({});
+            }
+            await integration.flush();
+            resetRunState();
+        },
     };
+    return integration;
 }
 //# sourceMappingURL=vercel-ai.js.map