@mastra/observability 1.22.0 → 1.23.0-alpha.0

package/dist/index.cjs

@@ -2317,9 +2317,10 @@ function addUsageStats(a, b) {
 * Provides span tracking for Model generations, including:
 * - MODEL_STEP spans (one per Model API call - includes processors and tool executions)
 * - MODEL_INFERENCE spans (the provider call itself - model latency only)
-* - MODEL_CHUNK spans (individual streaming chunks within an inference)
+* - MODEL_CHUNK spans (processed streaming content within a logical step)
 *
-* Hierarchy: MODEL_GENERATION -> MODEL_STEP -> MODEL_INFERENCE -> MODEL_CHUNK
+* Hierarchy: MODEL_GENERATION -> MODEL_STEP -> MODEL_INFERENCE (provider timing)
+*                                          -> MODEL_CHUNK (processed content)
 *
 * Processors and tool executions remain children of MODEL_STEP (siblings of
 * MODEL_INFERENCE), so MODEL_INFERENCE measures pure model time.
@@ -2336,6 +2337,12 @@ function addUsageStats(a, b) {
 function supportsModelInference() {
 	return _mastra_core_features.coreFeatures.has("model-inference-span");
 }
+function interruptedByRun(termination) {
+	return termination.outcome === "abort" || termination.stopReason === "timeout" && termination.stopReasonContext && "timeoutType" in termination.stopReasonContext && termination.stopReasonContext.timeoutType === "total" ? {
+		...termination,
+		outcome: "interrupted"
+	} : termination;
+}
 function parseGatewayCost(providerMetadata) {
 	const rawCost = providerMetadata?.gateway?.cost;
 	const cost = typeof rawCost === "number" ? rawCost : typeof rawCost === "string" && rawCost.trim().length > 0 ? Number(rawCost) : void 0;
@@ -2526,13 +2533,17 @@ var ModelSpanTracker = class {
 	#modelSpan;
 	#currentStepSpan;
 	#currentInferenceSpan;
+	#stepHasInference = false;
+	#tracksProviderStream = false;
 	#currentChunkSpan;
 	#currentChunkType;
 	#accumulator = {};
 	#stepIndex = 0;
 	#chunkSequence = 0;
 	#completionStartTime;
+	#timeToFirstTokenMs;
 	#inferenceCompletionStartTime;
+	#inferenceTimeToFirstTokenMs;
 	/**
 	* True between a step's `step-start` and `step-finish` chunks, the window in which
 	* the provider responds. Chunks outside it, such as a `tool-call` replayed for a
@@ -2561,22 +2572,41 @@ var ModelSpanTracker = class {
 		this.#inferenceContext = context;
 	}
 	/**
-	* Record when the provider's first chunk arrived and copy that clock up the
-	* agent's own chain (inference → step → generation → agent run), first write
-	* wins at each level. Time to first chunk is derived later as
-	* `completionStartTime - startTime` on whichever span is being read.
+	* Record when the provider's first chunk arrived. Time to first token is measured
+	* once here, from the start of the inference that streamed the chunk; the inference
+	* reports it when it ends, and the number is copied up the agent's own chain
+	* (step → generation → agent run) with the chunk's clock, first write wins at each
+	* level. Time to first chunk is `completionStartTime - startTime` on whichever span
+	* is being read.
 	*/
 	#captureCompletionStartTime() {
 		this.#ensureStepAndInference();
 		if (this.#inferenceCompletionStartTime) return;
 		const now = /* @__PURE__ */ new Date();
+		const inference = this.#currentInferenceSpan;
+		const timeToFirstTokenMs = inference ? now.getTime() - inference.startTime.getTime() : void 0;
 		this.#inferenceCompletionStartTime = now;
+		this.#inferenceTimeToFirstTokenMs = timeToFirstTokenMs;
 		this.#completionStartTime ??= now;
+		this.#timeToFirstTokenMs ??= timeToFirstTokenMs;
 		for (const span of [
 			this.#currentStepSpan,
 			this.#modelSpan,
 			this.#agentRunSpan
-		]) if (span && !span.attributes?.completionStartTime) span.update({ attributes: { completionStartTime: now } });
+		]) {
+			if (!span || span.attributes?.completionStartTime) continue;
+			span.update({ attributes: {
+				completionStartTime: now,
+				...timeToFirstTokenMs !== void 0 ? { timeToFirstTokenMs } : {}
+			} });
+		}
+	}
+	/** What the current inference streamed so far, for whichever way it ends. */
+	#inferenceStreamAttributes() {
+		return {
+			...this.#inferenceCompletionStartTime ? { completionStartTime: this.#inferenceCompletionStartTime } : {},
+			...this.#inferenceTimeToFirstTokenMs !== void 0 ? { timeToFirstTokenMs: this.#inferenceTimeToFirstTokenMs } : {}
+		};
 	}
 	/**
 	* Get the tracing context for creating child spans.
@@ -2591,21 +2621,33 @@ var ModelSpanTracker = class {
 	* doesn't leave them dangling. No-op if they were already closed.
 	*/
 	reportGenerationError(options) {
+		this.#endChunkSpan();
+		const termination = options.outcome != null ? {
+			outcome: options.outcome,
+			stopReason: options.stopReason,
+			stopReasonContext: options.stopReasonContext
+		} : _mastra_core_observability.executionFailureTermination?.(options.error);
 		if (this.#currentInferenceSpan) {
 			this.#currentInferenceSpan.error({
 				error: options.error,
-				endSpan: true
+				...termination ? interruptedByRun(termination) : {},
+				endSpan: true,
+				attributes: this.#inferenceStreamAttributes()
 			});
 			this.#currentInferenceSpan = void 0;
 		}
 		if (this.#currentStepSpan) {
 			this.#currentStepSpan.error({
 				error: options.error,
+				...termination ? interruptedByRun(termination) : {},
 				endSpan: true
 			});
 			this.#currentStepSpan = void 0;
 		}
-		this.#modelSpan?.error(options);
+		this.#modelSpan?.error({
+			...options,
+			...termination
+		});
 	}
 	/**
 	* End the generation span with optional raw usage data.
@@ -2620,16 +2662,37 @@ var ModelSpanTracker = class {
 		}, model);
 		if (providerCostContext && !spanOptions.attributes) spanOptions.attributes = {};
 		if (spanOptions.attributes) {
-			spanOptions.attributes.completionStartTime = this.#completionStartTime ?? spanOptions.attributes.completionStartTime;
+			if (this.#completionStartTime) {
+				spanOptions.attributes.completionStartTime = this.#completionStartTime;
+				spanOptions.attributes.timeToFirstTokenMs = this.#timeToFirstTokenMs;
+			}
 			spanOptions.attributes.usage = extractUsageMetrics(usage, providerMetadata);
 			spanOptions.attributes.costContext = providerCostContext ?? spanOptions.attributes.costContext;
 			if (!spanOptions.attributes.costContext) spanOptions.attributes.costContext = getGatewayCostContext({ stepProviderMetadata });
 		}
+		if (spanOptions.outcome === "abort" || spanOptions.stopReason === "timeout") {
+			const termination = {
+				outcome: spanOptions.outcome,
+				stopReason: spanOptions.stopReason,
+				stopReasonContext: spanOptions.stopReasonContext
+			};
+			this.#endChunkSpan();
+			this.#currentStepSpan?.end({
+				...interruptedByRun(termination),
+				endTree: true
+			});
+			this.#currentStepSpan = void 0;
+			this.#currentInferenceSpan = void 0;
+			this.#currentStepInputIsFinal = false;
+		}
 		this.#modelSpan?.end(spanOptions);
 	}
 	getCompletionStartTime() {
 		return this.#completionStartTime;
 	}
+	getTimeToFirstTokenMs() {
+		return this.#timeToFirstTokenMs;
+	}
 	/**
 	* Update the generation span
 	*/
@@ -2683,10 +2746,12 @@ var ModelSpanTracker = class {
 	*/
 	startStep(payload) {
 		if (this.#currentStepSpan) return;
+		this.#stepHasInference = false;
 		const input = extractStepInput(payload);
 		this.#currentStepSpan = this.#modelSpan?.createChildSpan({
 			name: `step: ${this.#stepIndex}`,
 			type: _mastra_core_observability.SpanType.MODEL_STEP,
+			...typeof _mastra_core_observability.agentLoopTermination === "function" ? { outcome: null } : {},
 			attributes: {
 				stepIndex: this.#stepIndex,
 				...payload?.messageId ? { messageId: payload.messageId } : {},
@@ -2698,6 +2763,7 @@ var ModelSpanTracker = class {
 		this.#currentStepInputIsFinal = Array.isArray(payload?.inputMessages);
 		this.#chunkSequence = 0;
 		this.#inferenceCompletionStartTime = void 0;
+		this.#inferenceTimeToFirstTokenMs = void 0;
 	}
 	/**
 	* End the current MODEL_INFERENCE span when the provider stream finishes.
@@ -2707,22 +2773,31 @@ var ModelSpanTracker = class {
 	*
 	* Safe to call multiple times - no-ops if the span is already closed.
 	*/
-	#endInferenceSpan(payload) {
+	#endInferenceSpan(payload, captureOutput = true) {
 		if (!this.#currentInferenceSpan) return;
 		const { usage: rawUsage, ...otherOutput } = payload.output;
 		const usage = extractUsageMetrics(rawUsage, payload.metadata?.providerMetadata);
 		const responseModel = typeof payload.metadata?.modelId === "string" ? payload.metadata.modelId : void 0;
 		this.#currentInferenceSpan.end({
-			output: otherOutput,
+			..._mastra_core_observability.agentLoopTermination?.({
+				stopCause: "model_finished",
+				finishReason: payload.stepResult.reason
+			}),
+			...payload.stepResult.reason === "error" ? {
+				outcome: "error",
+				stopReason: "model_error"
+			} : {},
+			...captureOutput ? { output: otherOutput } : {},
 			attributes: {
 				usage,
 				finishReason: payload.stepResult.reason,
 				warnings: payload.stepResult.warnings,
-				completionStartTime: this.#inferenceCompletionStartTime,
+				...this.#inferenceStreamAttributes(),
 				...responseModel?.trim() ? { responseModel } : {}
 			}
 		});
 		this.#currentInferenceSpan = void 0;
+		this.#inferenceCompletionStartTime = void 0;
 	}
 	/**
 	* Open the MODEL_INFERENCE span for the current step. Chunks (including tool-call
@@ -2740,31 +2815,56 @@ var ModelSpanTracker = class {
 	* start time.
 	*
 	* `payload.modelId` / `payload.provider` name the model the caller is about
-	* to invoke and are recorded on MODEL_STEP, also when a fallback attempt
-	* reuses the step's open inference span. The safety net never records them:
-	* a replayed step-start chunk names the model of the original call.
+	* to invoke and are recorded on MODEL_STEP and the inference. A named call
+	* while an inference is still open is the next attempt of the same step (a
+	* fallback model after a failure): that inference ends as failed and the
+	* attempt gets its own, so its timing and model are its own. The safety net
+	* never records them: a replayed step-start chunk names the model of the
+	* original call.
 	*/
 	startInference(payload) {
-		if (payload?.modelId && payload.provider) this.#currentStepSpan?.update({ attributes: {
-			model: payload.modelId,
-			provider: payload.provider
-		} });
+		if (payload?.modelId && payload.provider) {
+			this.#currentStepSpan?.update({ attributes: {
+				model: payload.modelId,
+				provider: payload.provider
+			} });
+			this.failInference(/* @__PURE__ */ new Error("Model call ended without a result before the next attempt started"));
+		}
 		this.#openInference(payload);
 	}
+	/** End the current attempt only; generation and agent spans belong to their owners. */
+	endAttempt(termination) {
+		termination = interruptedByRun(termination);
+		const payload = this.#pendingStepFinishPayload;
+		if (payload) this.#endStepSpan(payload, termination);
+		else {
+			this.#endChunkSpan();
+			this.#currentInferenceSpan?.end(termination);
+			this.#currentStepSpan?.end(termination);
+			this.#currentStepSpan = void 0;
+			this.#currentInferenceSpan = void 0;
+		}
+		this.#pendingStepFinishPayload = void 0;
+		this.#inferenceCompletionStartTime = void 0;
+		this.#currentStepInputIsFinal = false;
+	}
 	#openInference(payload) {
 		if (!supportsModelInference()) return;
 		if (!this.#currentStepSpan || this.#currentInferenceSpan) return;
 		this.#inferenceCompletionStartTime = void 0;
+		this.#inferenceTimeToFirstTokenMs = void 0;
 		const input = extractStepInput(payload);
 		const generationAttrs = this.#modelSpan?.attributes;
 		const ctx = this.#inferenceContext;
+		this.#stepHasInference = true;
 		this.#currentInferenceSpan = this.#currentStepSpan.createChildSpan({
 			name: `inference: ${this.#stepIndex}`,
 			type: _mastra_core_observability.SpanType.MODEL_INFERENCE,
+			...typeof _mastra_core_observability.agentLoopTermination === "function" ? { outcome: null } : {},
 			attributes: {
 				stepIndex: this.#stepIndex,
-				model: generationAttrs?.model,
-				provider: generationAttrs?.provider,
+				model: payload?.modelId ?? generationAttrs?.model,
+				provider: payload?.provider ?? generationAttrs?.provider,
 				streaming: generationAttrs?.streaming,
 				...ctx?.parameters !== void 0 ? { parameters: ctx.parameters } : {},
 				...ctx?.providerOptions !== void 0 ? { providerOptions: ctx.providerOptions } : {},
@@ -2781,11 +2881,37 @@ var ModelSpanTracker = class {
 	* End the open MODEL_INFERENCE span as interrupted while keeping MODEL_STEP open,
 	* so a replacement request for the same step gets its own inference span.
 	*/
-	interruptInference() {
+	interruptInference(termination) {
 		this.#endChunkSpan();
 		if (!this.#currentInferenceSpan) return;
-		this.#currentInferenceSpan.end({ attributes: { finishReason: "interrupted" } });
+		this.#currentInferenceSpan.end({
+			attributes: {
+				finishReason: "interrupted",
+				...this.#inferenceStreamAttributes()
+			},
+			...termination ?? (typeof _mastra_core_observability.agentLoopTermination === "function" ? {
+				outcome: "interrupted",
+				stopReason: null,
+				stopReasonContext: null
+			} : {})
+		});
 		this.#currentInferenceSpan = void 0;
+		this.#inferenceCompletionStartTime = void 0;
+		this.#inferenceTimeToFirstTokenMs = void 0;
+	}
+	/** End the open inference span, if any, with `error` and what it streamed. */
+	failInference(error) {
+		this.#endChunkSpan();
+		if (!this.#currentInferenceSpan) return;
+		this.#currentInferenceSpan.error({
+			error,
+			..._mastra_core_observability.executionFailureTermination?.(error, "model_error"),
+			endSpan: true,
+			attributes: this.#inferenceStreamAttributes()
+		});
+		this.#inferenceTimeToFirstTokenMs = void 0;
+		this.#currentInferenceSpan = void 0;
+		this.#inferenceCompletionStartTime = void 0;
 	}
 	/**
 	* Update the current step span with additional payload data.
@@ -2807,10 +2933,11 @@ var ModelSpanTracker = class {
 	/**
 	* End the current Model execution step with token usage, finish reason, output, and metadata
 	*/
-	#endStepSpan(payload) {
+	#endStepSpan(payload, termination) {
 		this.#endChunkSpan();
 		if (!this.#currentStepSpan) return;
-		const { usage: rawUsage, ...otherOutput } = payload.output;
+		const output = payload.output;
+		const { usage: rawUsage, ...otherOutput } = output;
 		const stepResult = payload.stepResult;
 		const metadata = payload.metadata;
 		const usage = extractUsageMetrics(rawUsage, metadata?.providerMetadata);
@@ -2826,6 +2953,11 @@ var ModelSpanTracker = class {
 		]) delete cleanMetadata[key];
 		this.#endInferenceSpan(payload);
 		this.#currentStepSpan.end({
+			...termination ?? _mastra_core_observability.agentLoopTermination?.({
+				stopCause: "model_finished",
+				finishReason: stepResult.reason,
+				tripwire: output.steps?.at(-1)?.tripwire
+			}),
 			output: otherOutput,
 			attributes: {
 				usage,
@@ -2857,26 +2989,23 @@ var ModelSpanTracker = class {
 				warnings: []
 			},
 			metadata: {}
-		});
+		}, _mastra_core_observability.agentLoopTermination?.({
+			finishReason: "suspended",
+			suspension: {
+				approvalRequired: chunk.type === "tool-call-approval",
+				toolCallId: chunk.payload.toolCallId,
+				toolName: chunk.payload.toolName
+			}
+		}));
 	}
-	/**
-	* Returns the parent span for chunks. Chunks parent under MODEL_INFERENCE
-	* (the provider call) when available, falling back to MODEL_STEP only if
-	* startStep() was bypassed.
-	*/
+	/** Processed content belongs to the logical step, independently of provider timing. */
 	#chunkParent() {
-		return this.#currentInferenceSpan ?? this.#currentStepSpan;
+		return this.#currentStepSpan?.endTime ? void 0 : this.#currentStepSpan;
 	}
-	/**
-	* Safety-net invoked from chunk handlers: auto-create MODEL_STEP and
-	* MODEL_INFERENCE if a chunk arrives before the loop has explicitly opened
-	* them, so chunks parent under MODEL_INFERENCE rather than falling through
-	* to MODEL_STEP. Idempotent — each public start* method is itself a no-op
-	* when its span is already live.
-	*/
+	/** Ensure a logical step and provider timing span exist for legacy stream callers. */
 	#ensureStepAndInference() {
 		if (!this.#currentStepSpan) this.startStep();
-		if (!this.#currentInferenceSpan) this.#openInference();
+		if (!this.#currentInferenceSpan && !this.#stepHasInference) this.#openInference();
 	}
 	/**
 	* Create a new chunk span (for multi-part chunks like text-start/delta/end)
@@ -3037,20 +3166,39 @@ var ModelSpanTracker = class {
 			tracingPolicy: this.#modelSpan?.tracingPolicy
 		})) this.#chunkSequence++;
 	}
+	/** Track provider timing and completion without recording unprocessed content. */
+	wrapInferenceStream(stream) {
+		this.#tracksProviderStream = true;
+		return this.wrapStream(stream, true);
+	}
 	/**
 	* Wraps a stream with model tracing transform to track MODEL_STEP and MODEL_CHUNK spans.
 	*
 	* This should be added to the stream pipeline to automatically
 	* create MODEL_STEP and MODEL_CHUNK spans for each semantic unit in the stream.
 	*/
-	wrapStream(stream) {
+	wrapStream(stream, inferenceOnly = false) {
 		return stream.pipeThrough(new stream_web.TransformStream({ transform: (chunk, controller) => {
-			if ((this.#inModelResponse || this.#deferStepClose) && MODEL_RESPONSE_CHUNK_TYPES.has(chunk.type)) this.#captureCompletionStartTime();
+			if (inferenceOnly) {
+				try {
+					if (MODEL_RESPONSE_CHUNK_TYPES.has(chunk.type)) this.#captureCompletionStartTime();
+					if (chunk.type === "finish") this.#endInferenceSpan(chunk.payload, false);
+				} catch {}
+				controller.enqueue(chunk);
+				return;
+			}
+			this.recordChunk(chunk);
+			controller.enqueue(chunk);
+		} }));
+	}
+	/** @internal Record a chunk only after output processors accept it. */
+	recordChunk(chunk) {
+		try {
+			if (!this.#tracksProviderStream && (this.#inModelResponse || this.#deferStepClose) && MODEL_RESPONSE_CHUNK_TYPES.has(chunk.type)) this.#captureCompletionStartTime();
 			if (chunk.type === "tool-call-suspended" || chunk.type === "tool-call-approval") {
 				if (chunk.type === "tool-call-approval") this.#handleToolApprovalChunk(chunk);
 				this.#endSuspendedStep(chunk);
 			}
-			controller.enqueue(chunk);
 			switch (chunk.type) {
 				case "text-start":
 				case "text-delta":
@@ -3076,7 +3224,7 @@ var ModelSpanTracker = class {
 					this.#inModelResponse = true;
 					if (this.#currentStepSpan) this.updateStep(chunk.payload);
 					else this.startStep(chunk.payload);
-					if (!this.#currentInferenceSpan) this.#openInference(chunk.payload);
+					if (!this.#currentInferenceSpan && !this.#stepHasInference) this.#openInference(chunk.payload);
 					break;
 				case "step-finish":
 					this.#inModelResponse = false;
@@ -3086,15 +3234,20 @@ var ModelSpanTracker = class {
 						this.#endInferenceSpan(chunk.payload);
 					} else this.#endStepSpan(chunk.payload);
 					break;
+				case "tripwire": {
+					const termination = _mastra_core_observability.agentLoopTermination?.({ tripwire: chunk.payload });
+					if (!termination) break;
+					this.endAttempt(termination);
+					break;
+				}
+				case "finish": break;
 				case "raw":
 				case "start":
-				case "finish":
 				case "response-metadata":
 				case "source":
 				case "file":
 				case "error":
 				case "abort":
-				case "tripwire":
 				case "watch":
 				case "tool-error":
 				case "reasoning-signature":
@@ -3119,7 +3272,7 @@ var ModelSpanTracker = class {
 					break;
 				}
 			}
-		} }));
+		} catch {}
 	}
 };
 // src/spans/metadata.ts
@@ -3308,6 +3461,9 @@ var BaseSpan = class BaseSpan {
 	observabilityInstance;
 	input;
 	output;
+	outcome;
+	stopReason;
+	stopReasonContext;
 	errorInfo;
 	metadata;
 	requestContext;
@@ -3324,11 +3480,7 @@ var BaseSpan = class BaseSpan {
 	parentSpanId;
 	/** Parent from an external tracing system (ambient OTel / dd-trace span) that Mastra did not create; carried for external correlation, not part of Mastra's own parent/child linkage */
 	externalParentSpanId;
-	/** Native span fields (see `SpanData`); carried as supplied and exported only when set */
 	resumedFromSpanId;
-	outcome;
-	stopReason;
-	stopReasonContext;
 	/** Deep clean options for serialization */
 	deepCleanOptions;
 	/**
@@ -3356,6 +3508,7 @@ var BaseSpan = class BaseSpan {
 	* live `parent`, so its original ancestors are only known from the cached export.
 	*/
 	restoredLineage;
+	restoredIsRootSpan;
 	/**
 	* Version declared for this span's own entity, or inherited from a parent span
 	* of the same entity. Unlike `metadata.entityVersionId`, never an ancestor's
@@ -3376,6 +3529,7 @@ var BaseSpan = class BaseSpan {
 	constructor(options, observabilityInstance) {
 		const observabilityConfig = observabilityInstance.getConfig();
 		this.deepCleanOptions = mergeSerializationOptions(observabilityConfig.serializationOptions);
+		this.applyOutcome(options);
 		this.name = options.name;
 		this.type = options.type;
 		this.isInternal = isSpanInternal(this.type, options.tracingPolicy?.internal);
@@ -3396,9 +3550,6 @@ var BaseSpan = class BaseSpan {
 		this.tags = !options.parent && options.tags?.length ? options.tags : void 0;
 		this.links = validLinks(options.links);
 		this.resumedFromSpanId = options.resumedFromSpanId;
-		this.outcome = options.outcome;
-		this.stopReason = options.stopReason;
-		this.stopReasonContext = deepClean(options.stopReasonContext, this.deepCleanOptions);
 		const entityParent = this.getParentSpan(false);
 		this.entityType = options.entityType ?? entityParent?.entityType;
 		this.entityId = options.entityId ?? entityParent?.entityId;
@@ -3440,14 +3591,49 @@ var BaseSpan = class BaseSpan {
 			return value;
 		}
 	}
-	/** End the span and any descendant spans that are still open, applying `options` to each */
+	/** Preserve explicitly supplied native fields; never derive results from payloads/errors. */
+	applyOutcome(options) {
+		if (this.endTime) return;
+		if (options.outcome !== void 0) {
+			this.outcome = options.outcome;
+			this.stopReason = options.stopReason ?? null;
+			this.stopReasonContext = options.stopReasonContext == null ? null : deepClean(options.stopReasonContext, this.deepCleanOptions);
+			return;
+		}
+		if (options.stopReason !== void 0 && options.stopReason !== this.stopReason) this.stopReasonContext = null;
+		if (options.stopReason !== void 0) this.stopReason = options.stopReason;
+		if (options.stopReasonContext !== void 0) this.stopReasonContext = options.stopReasonContext == null ? null : deepClean(options.stopReasonContext, this.deepCleanOptions);
+	}
+	/** Forward options to open descendants, with interruption outcomes for cascading termination. */
 	endTree(options) {
-		if (this.#openChildren) for (const child of [...this.#openChildren]) child.endTree(options);
+		this.endOpenDescendants(options, true);
 		this.end(options);
 	}
-	/** Close any still-open descendant spans without applying options to them */
-	endOpenDescendants() {
-		if (this.#openChildren) for (const child of [...this.#openChildren]) child.endTree();
+	/** Preserve completed children; only known cascading termination interrupts open work. */
+	endOpenDescendants(options, forwardOptions = false) {
+		const outcome = options?.outcome !== void 0 ? options.outcome : this.outcome;
+		const stopReason = options?.stopReason !== void 0 ? options.stopReason : this.stopReason;
+		const stopReasonContext = options?.stopReasonContext !== void 0 ? options.stopReasonContext : this.stopReasonContext;
+		const interrupts = outcome === "abort" || outcome === "interrupted" || outcome === "limit" && stopReason === "timeout";
+		const forwarded = forwardOptions ? { ...options } : {};
+		delete forwarded.outcome;
+		delete forwarded.stopReason;
+		delete forwarded.stopReasonContext;
+		if (this.#openChildren) for (const child of [...this.#openChildren]) {
+			const childOptions = {
+				...forwarded,
+				...interrupts ? {
+					outcome: "interrupted",
+					stopReason,
+					stopReasonContext
+				} : {}
+			};
+			if (forwardOptions) child.endTree(childOptions);
+			else child.end({
+				...childOptions,
+				endTree: true
+			});
+		}
 	}
 	/**
 	* Release this span from its parent's open-child set once it has ended.
@@ -3498,7 +3684,7 @@ var BaseSpan = class BaseSpan {
 	}
 	/** Returns `TRUE` if the span is the root span of a trace */
 	get isRootSpan() {
-		return !this.parent;
+		return this.restoredIsRootSpan ?? !this.parent;
 	}
 	/**
 	* Get the closest parent span.
@@ -3562,6 +3748,7 @@ var BaseSpan = class BaseSpan {
 	*/
 	restoreEntityLineage(cached) {
 		this.ownEntityVersionId = cached.ownEntityVersionId ?? void 0;
+		this.restoredIsRootSpan = cached.isRootSpan;
 		const lineage = definedLineage(cached);
 		if (Object.keys(lineage).length > 0) {
 			this.restoredLineage = lineage;
@@ -3644,6 +3831,7 @@ var BaseSpan = class BaseSpan {
 		const nestedUnderParent = this.traceState?.nestedUnderParent ?? false;
 		const links = validLinks(this.links);
 		const correlation = this.getCorrelationContext();
+		const timeToFirstTokenMs = this.attributes?.timeToFirstTokenMs;
 		return {
 			id: this.id,
 			traceId: this.traceId,
@@ -3659,6 +3847,9 @@ var BaseSpan = class BaseSpan {
 			input: hideInput ? void 0 : this.input,
 			output: hideOutput ? void 0 : this.output,
 			errorInfo: this.errorInfo,
+			...this.outcome !== void 0 ? { outcome: this.outcome } : {},
+			...this.stopReason !== void 0 ? { stopReason: this.stopReason } : {},
+			...this.stopReasonContext !== void 0 ? { stopReasonContext: this.stopReasonContext } : {},
 			requestContext: this.requestContext,
 			isEvent: this.isEvent,
 			isRootSpan: this.isRootSpan,
@@ -3668,9 +3859,7 @@ var BaseSpan = class BaseSpan {
 			parentSpanId: this.getParentSpanId(includeInternalSpans),
 			externalParentSpanId: this.getExportedExternalParentSpanId(includeInternalSpans),
 			...this.resumedFromSpanId !== void 0 ? { resumedFromSpanId: this.resumedFromSpanId } : {},
-			...this.outcome !== void 0 ? { outcome: this.outcome } : {},
-			...this.stopReason !== void 0 ? { stopReason: this.stopReason } : {},
-			...this.stopReasonContext !== void 0 ? { stopReasonContext: this.stopReasonContext } : {},
+			...typeof timeToFirstTokenMs === "number" ? { timeToFirstTokenMs } : {},
 			...nestedUnderParent ? { nestedUnderParent: true } : {},
 			...links ? { links } : {},
 			...this.isRootSpan && !nestedUnderParent && this.tags?.length ? { tags: this.tags } : {}
@@ -3780,7 +3969,9 @@ var DefaultSpan = class extends BaseSpan {
 	end(options) {
 		if (this.isEvent) return;
 		if (this.endTime) return;
-		if (options?.endTree) this.endOpenDescendants();
+		if (options?.endTree) this.endOpenDescendants(options);
+		if (options) this.applyOutcome(options);
+		if (this.outcome === null) this.outcome = "unknown";
 		this.endTime = /* @__PURE__ */ new Date();
 		this.detachFromParent();
 		if (options?.metadata) this.metadata = {
@@ -3795,8 +3986,9 @@ var DefaultSpan = class extends BaseSpan {
 		};
 	}
 	error(options) {
-		if (this.isEvent) return;
+		if (this.isEvent || this.endTime) return;
 		const { error, endSpan = true, endTree, attributes, metadata } = options;
+		this.applyOutcome(options);
 		if (metadata) this.metadata = {
 			...this.metadata,
 			...deepClean(this.prepareSpanMetadata(metadata), this.deepCleanOptions)
@@ -3831,6 +4023,7 @@ var DefaultSpan = class extends BaseSpan {
 	}
 	update(options) {
 		if (this.isEvent) return;
+		this.applyOutcome(options);
 		if (options.name !== void 0) this.name = options.name;
 		if (options.metadata) this.metadata = {
 			...this.metadata,
@@ -5300,13 +5493,13 @@ var BaseObservabilityInstance = class extends _mastra_core_base.MastraBase {
 				...rest,
 				metadata
 			}, this);
-		} else if (!this.shouldSample(customSamplerOptions)) return new NoOpSpan({
+		} else if (!(options.samplingDecision ?? this.shouldSample(customSamplerOptions))) return new NoOpSpan({
 			...rest,
 			metadata
 		}, this);
 		let traceState;
 		if (options.parent) traceState = options.parent.traceState;
-		else traceState = this.computeTraceState(tracingOptions);
+		else traceState = options.traceState ?? this.computeTraceState(tracingOptions);
 		const tracingMetadata = !options.parent ? tracingOptions?.metadata : void 0;
 		const mergedMetadata = mergeMetadata$1(stripUndefined(metadata), stripUndefined(tracingMetadata));
 		const enrichedMetadata = this.extractMetadataFromRequestContext(requestContext, mergedMetadata, traceState);
@@ -5361,6 +5554,11 @@ var BaseObservabilityInstance = class extends _mastra_core_base.MastraBase {
 	* @returns A span that can have lifecycle methods called on it
 	*/
 	rebuildSpan(cached) {
+		if (cached.id === "no-op" && cached.traceId === "no-op-trace") return new NoOpSpan({
+			name: cached.name,
+			type: cached.type,
+			traceState: cached.traceState
+		}, this);
 		const span = this.createSpan({
 			name: cached.name,
 			type: cached.type,
@@ -5384,6 +5582,11 @@ var BaseObservabilityInstance = class extends _mastra_core_base.MastraBase {
 			traceState: this.rebuildTraceState(cached)
 		});
 		if (span instanceof BaseSpan) span.restoreEntityLineage(cached);
+		if (cached.endTime) {
+			span.endTime = cached.endTime instanceof Date ? cached.endTime : new Date(cached.endTime);
+			span.output = cached.output;
+			span.errorInfo = cached.errorInfo;
+		}
 		this.wireSpanLifecycle(span);
 		return span;
 	}
@@ -9148,7 +9351,11 @@ var TestExporter = class extends BaseExporter {
 			if (span.parentSpanId && spanIdMap.has(span.parentSpanId)) normalizedSpan.parentId = spanIdMap.get(span.parentSpanId);
 			if (span.entityType) normalizedSpan.entityType = span.entityType;
 			if (span.entityId) normalizedSpan.entityId = normalizeValue(span.entityId, "entityId");
-			if (span.attributes && Object.keys(span.attributes).length > 0) normalizedSpan.attributes = normalizeValue(span.attributes);
+			if (span.attributes && Object.keys(span.attributes).length > 0) {
+				const attributes = normalizeValue(span.attributes);
+				if (typeof attributes.timeToFirstTokenMs === "number") attributes.timeToFirstTokenMs = "<ms>";
+				normalizedSpan.attributes = attributes;
+			}
 			if (span.metadata && Object.keys(span.metadata).length > 0) normalizedSpan.metadata = normalizeValue(span.metadata);
 			if (span.input !== void 0) normalizedSpan.input = normalizeValue(span.input);
 			if (span.output !== void 0) normalizedSpan.output = normalizeValue(span.output);
@@ -10040,6 +10247,7 @@ var SensitiveDataFilter = class {
 		span.input = this.tryFilter(span.input, indexedState);
 		span.output = this.tryFilter(span.output, indexedState);
 		span.errorInfo = this.tryFilter(span.errorInfo, indexedState);
+		span.stopReasonContext = this.tryFilter(span.stopReasonContext, indexedState);
 		span.requestContext = this.tryFilter(span.requestContext, indexedState);
 		return span;
 	}