@mastra/clickhouse 1.27.0-alpha.2 → 1.28.0-alpha.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import { TupleParam, createClient } from "@clickhouse/client";
 import { ErrorCategory, ErrorDomain, MastraError } from "@mastra/core/error";
 import * as coreStorage from "@mastra/core/storage";
-import { BRANCH_SPAN_TYPES, EntityType, METRIC_DISTINCT_COLUMNS, MastraCompositeStore, MemoryStorage, ObservabilityStorage, SCORERS_SCHEMA, SPAN_SCHEMA, ScoresStorage, TABLE_AGENT_VERSIONS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_HARNESS_SESSIONS, TABLE_KNOWLEDGE_ACTIVITY, TABLE_KNOWLEDGE_MENTIONS, TABLE_KNOWLEDGE_NODES, TABLE_KNOWLEDGE_RECORDS, TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_THREAD_STATE, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_TRACES, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TraceStatus, WorkflowsStorage, calculatePagination, computeTraceStatus, createStorageErrorId, getDefaultValue, getSqlType, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, normalizePerPage, safelyParseJSON, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
+import { BRANCH_SPAN_TYPES, EntityType, METRIC_DISTINCT_COLUMNS, MastraCompositeStore, MemoryStorage, ObservabilityStorage, SCORERS_SCHEMA, SPAN_SCHEMA, ScoresStorage, TABLE_AGENT_VERSIONS, TABLE_DATASETS, TABLE_DATASET_ITEMS, TABLE_DATASET_VERSIONS, TABLE_EXPERIMENTS, TABLE_EXPERIMENT_RESULTS, TABLE_FAVORITES, TABLE_HARNESS_SESSIONS, TABLE_KNOWLEDGE_ACTIVITY, TABLE_KNOWLEDGE_MENTIONS, TABLE_KNOWLEDGE_NODES, TABLE_KNOWLEDGE_RECORDS, TABLE_KNOWLEDGE_SEMANTIC_OUTBOX, TABLE_MCP_CLIENTS, TABLE_MCP_CLIENT_VERSIONS, TABLE_MCP_SERVERS, TABLE_MCP_SERVER_VERSIONS, TABLE_MESSAGES, TABLE_NOTIFICATIONS, TABLE_PROMPT_BLOCKS, TABLE_PROMPT_BLOCK_VERSIONS, TABLE_RESOURCES, TABLE_SCHEDULES, TABLE_SCHEDULE_TRIGGERS, TABLE_SCHEMAS, TABLE_SCORERS, TABLE_SCORER_DEFINITIONS, TABLE_SCORER_DEFINITION_VERSIONS, TABLE_SKILLS, TABLE_SKILL_BLOBS, TABLE_SKILL_VERSIONS, TABLE_SPANS, TABLE_THREADS, TABLE_THREAD_STATE, TABLE_TOOL_PROVIDER_CONNECTIONS, TABLE_TRACES, TABLE_WORKFLOW_DEFINITIONS, TABLE_WORKFLOW_SNAPSHOT, TABLE_WORKSPACES, TABLE_WORKSPACE_VERSIONS, TraceStatus, WorkflowsStorage, calculatePagination, computeTraceStatus, createStorageErrorId, getDefaultValue, getSqlType, getStringAttribute, listBranchesArgsSchema, listFeedbackArgsSchema, listLogsArgsSchema, listMetricsArgsSchema, listScoresArgsSchema, listTracesArgsSchema, normalizePerPage, safelyParseJSON, toTraceSpans, transformScoreRow, validateStorageMetadataFilter } from "@mastra/core/storage";
 import { MessageList } from "@mastra/core/agent";
 import { MastraBase } from "@mastra/core/base";
 import { parseFieldKey } from "@mastra/core/utils";
@@ -301,7 +301,8 @@ const JSON_FIELDS = [
 	"output",
 	"error",
 	"scope",
-	"links"
+	"links",
+	"stopReasonContext"
 ];
 const NULLABLE_STRING_FIELDS = ["parentSpanId", "error"];
 function transformRow(row) {
@@ -2716,6 +2717,17 @@ CREATE TABLE IF NOT EXISTS ${TABLE_SPAN_EVENTS} (
   endedAt            DateTime64(3, 'UTC'),
   timeToFirstChunkMs Nullable(Float64),
 
+  -- Native span fields, stored as supplied (NULL when the producer set none)
+  externalParentSpanId Nullable(String),
+  resumedFromSpanId  Nullable(String),
+  model              LowCardinality(Nullable(String)),
+  provider           LowCardinality(Nullable(String)),
+  outcome            LowCardinality(Nullable(String)),
+  stopReason         LowCardinality(Nullable(String)),
+  stopReasonContext  Nullable(String),
+  timeToFirstTokenMs Nullable(Float64),
+  errorCount         Nullable(UInt32),
+
   -- Query-relevant flexible fields
   tags               Array(LowCardinality(String)) DEFAULT [],
   metadataSearch     Map(LowCardinality(String), String) DEFAULT map(),
@@ -2790,6 +2802,17 @@ CREATE TABLE IF NOT EXISTS ${TABLE_TRACE_ROOTS} (
   endedAt            DateTime64(3, 'UTC'),
   timeToFirstChunkMs Nullable(Float64),
 
+  -- Native span fields, stored as supplied (NULL when the producer set none)
+  externalParentSpanId Nullable(String),
+  resumedFromSpanId  Nullable(String),
+  model              LowCardinality(Nullable(String)),
+  provider           LowCardinality(Nullable(String)),
+  outcome            LowCardinality(Nullable(String)),
+  stopReason         LowCardinality(Nullable(String)),
+  stopReasonContext  Nullable(String),
+  timeToFirstTokenMs Nullable(Float64),
+  errorCount         Nullable(UInt32),
+
   -- Query-relevant flexible fields
   tags               Array(LowCardinality(String)) DEFAULT [],
   metadataSearch     Map(LowCardinality(String), String) DEFAULT map(),
@@ -2876,6 +2899,17 @@ CREATE TABLE IF NOT EXISTS ${TABLE_TRACE_BRANCHES} (
   endedAt            DateTime64(3, 'UTC'),
   timeToFirstChunkMs Nullable(Float64),
 
+  -- Native span fields, stored as supplied (NULL when the producer set none)
+  externalParentSpanId Nullable(String),
+  resumedFromSpanId  Nullable(String),
+  model              LowCardinality(Nullable(String)),
+  provider           LowCardinality(Nullable(String)),
+  outcome            LowCardinality(Nullable(String)),
+  stopReason         LowCardinality(Nullable(String)),
+  stopReasonContext  Nullable(String),
+  timeToFirstTokenMs Nullable(Float64),
+  errorCount         Nullable(UInt32),
+
   -- Query-relevant flexible fields
   tags               Array(LowCardinality(String)) DEFAULT [],
   metadataSearch     Map(LowCardinality(String), String) DEFAULT map(),
@@ -3611,6 +3645,25 @@ function buildAllMvDDL(strategy) {
 }
 /** Discovery-specific refreshable MVs — created separately from core MVs. */
 const DISCOVERY_MV_DDL = [DISCOVERY_VALUES_MV_DDL, DISCOVERY_PAIRS_MV_DDL];
+/**
+* Span columns added after the first span tables shipped, with their types.
+* Present on span events, trace roots and trace branches.
+*/
+const ADDED_SPAN_COLUMNS = [
+	["inputPreview", "Nullable(String)"],
+	["outputPreview", "Nullable(String)"],
+	["errorPreview", "Nullable(String)"],
+	["timeToFirstChunkMs", "Nullable(Float64)"],
+	["externalParentSpanId", "Nullable(String)"],
+	["resumedFromSpanId", "Nullable(String)"],
+	["model", "LowCardinality(Nullable(String))"],
+	["provider", "LowCardinality(Nullable(String))"],
+	["outcome", "LowCardinality(Nullable(String))"],
+	["stopReason", "LowCardinality(Nullable(String))"],
+	["stopReasonContext", "Nullable(String)"],
+	["timeToFirstTokenMs", "Nullable(Float64)"],
+	["errorCount", "Nullable(UInt32)"]
+];
 const addColumn = (table, name, type) => ({
 	kind: "column",
 	table,
@@ -3635,14 +3688,11 @@ const LOG_SKIP_INDEX_COLUMNS = [
 	"requestId"
 ];
 const ALL_MIGRATIONS = [
-	...[
-		"inputPreview",
-		"outputPreview",
-		"errorPreview"
-	].flatMap((column) => [addColumn(TABLE_TRACE_ROOTS, column, "Nullable(String)"), addColumn(TABLE_TRACE_BRANCHES, column, "Nullable(String)")]),
-	addColumn(TABLE_SPAN_EVENTS, "inputPreview", "Nullable(String)"),
-	addColumn(TABLE_SPAN_EVENTS, "outputPreview", "Nullable(String)"),
-	addColumn(TABLE_SPAN_EVENTS, "errorPreview", "Nullable(String)"),
+	...ADDED_SPAN_COLUMNS.flatMap(([column, type]) => [
+		addColumn(TABLE_TRACE_ROOTS, column, type),
+		addColumn(TABLE_TRACE_BRANCHES, column, type),
+		addColumn(TABLE_SPAN_EVENTS, column, type)
+	]),
 	addColumn(TABLE_TRACE_BRANCHES, "entityVersionId", "Nullable(String)"),
 	addColumn(TABLE_TRACE_BRANCHES, "parentEntityVersionId", "Nullable(String)"),
 	addColumn(TABLE_TRACE_BRANCHES, "rootEntityVersionId", "Nullable(String)"),
@@ -3683,10 +3733,7 @@ const ALL_MIGRATIONS = [
 	addBloomIndex(TABLE_METRIC_EVENTS, "idx_sessionId", "sessionId"),
 	addBloomIndex(TABLE_METRIC_EVENTS, "idx_requestId", "requestId"),
 	...LOG_SKIP_INDEX_COLUMNS.map((column) => addBloomIndex(TABLE_LOG_EVENTS, `idx_${column}`, column)),
-	addBloomIndex(TABLE_DELETION_REQUESTS, "idx_predicateValues", "predicateValues"),
-	addColumn(TABLE_TRACE_ROOTS, "timeToFirstChunkMs", "Nullable(Float64)"),
-	addColumn(TABLE_TRACE_BRANCHES, "timeToFirstChunkMs", "Nullable(Float64)"),
-	addColumn(TABLE_SPAN_EVENTS, "timeToFirstChunkMs", "Nullable(Float64)")
+	addBloomIndex(TABLE_DELETION_REQUESTS, "idx_predicateValues", "predicateValues")
 ];
 const ALL_TABLE_NAMES = [
 	TABLE_SPAN_EVENTS,
@@ -3937,6 +3984,11 @@ const PROMOTED_KEYS = /* @__PURE__ */ new Set([
 	"executionSource",
 	"serviceName"
 ]);
+function nullableNumber$1(value) {
+	if (value == null || value === "") return null;
+	const n = Number(value);
+	return Number.isNaN(n) ? null : n;
+}
 function nullableString(value) {
 	return typeof value === "string" ? value === "" ? null : value : value == null ? null : String(value);
 }
@@ -4018,6 +4070,7 @@ function rowToSpanRecord(row) {
 	const startedAt = toDate(row.startedAt);
 	const endedAt = row.isEvent ? startedAt : toDateOrNull(row.endedAt);
 	const error = parseJson(row.error);
+	const attributes = parseJson(row.attributes);
 	return {
 		traceId: row.traceId,
 		spanId: row.spanId,
@@ -4053,12 +4106,21 @@ function rowToSpanRecord(row) {
 		tags: normalizeTags(row.tags),
 		metadata: parseJson(row.metadataRaw) ?? void 0,
 		scope: parseJson(row.scope) ?? void 0,
-		attributes: parseJson(row.attributes) ?? void 0,
+		attributes: attributes ?? void 0,
 		links: parseJson(row.links) ?? void 0,
 		input: parseJson(row.input) ?? void 0,
 		output: parseJson(row.output) ?? void 0,
 		error: error ?? void 0,
 		requestContext: parseJson(row.requestContext) ?? void 0,
+		externalParentSpanId: nullableString(row.externalParentSpanId),
+		resumedFromSpanId: nullableString(row.resumedFromSpanId),
+		model: nullableString(row.model) ?? getStringAttribute(attributes, "model"),
+		provider: nullableString(row.provider) ?? getStringAttribute(attributes, "provider"),
+		outcome: nullableString(row.outcome),
+		stopReason: nullableString(row.stopReason),
+		stopReasonContext: parseJson(row.stopReasonContext) ?? null,
+		timeToFirstTokenMs: nullableNumber$1(row.timeToFirstTokenMs),
+		errorCount: nullableNumber$1(row.errorCount),
 		createdAt: startedAt,
 		updatedAt: null
 	};
@@ -4132,6 +4194,15 @@ function spanRecordToRow(span) {
 		startedAt: toISOString(span.startedAt),
 		endedAt: toISOString(endedAt),
 		timeToFirstChunkMs: span.timeToFirstChunkMs ?? null,
+		externalParentSpanId: span.externalParentSpanId ?? null,
+		resumedFromSpanId: span.resumedFromSpanId ?? null,
+		model: span.model ?? null,
+		provider: span.provider ?? null,
+		outcome: span.outcome ?? null,
+		stopReason: span.stopReason ?? null,
+		stopReasonContext: jsonEncode(span.stopReasonContext),
+		timeToFirstTokenMs: span.timeToFirstTokenMs ?? null,
+		errorCount: span.errorCount ?? null,
 		tags: normalizeTags(span.tags),
 		metadataSearch: buildMetadataSearch(metadata),
 		metadataRaw: jsonEncode(metadata),
@@ -6835,7 +6906,17 @@ const TRACE_STATUS_SQL = `if(isNotNull(r.error), 'error', 'success')`;
 const timeToFirstChunkSupported = "timeToFirstChunkMs" in (coreStorage.TRACE_QUERY_FIELD_REGISTRY?.trace ?? {});
 /** Core before the sort rejects `orderBy` on the field, so the sort is only declared when core plans it. */
 const timeToFirstChunkSortSupported = coreStorage.TRACE_QUERY_ORDER_FIELDS?.includes("timeToFirstChunkMs") === true;
-const timeToFirstChunkFeatures = timeToFirstChunkSupported ? timeToFirstChunkSortSupported ? ["trace-query-time-to-first-chunk", "trace-query-time-to-first-chunk-sort"] : ["trace-query-time-to-first-chunk"] : [];
+/** Same rule for time to first token: returned and sorted only when core knows the field. */
+const timeToFirstTokenSupported = "timeToFirstTokenMs" in (coreStorage.TRACE_QUERY_FIELD_REGISTRY?.trace ?? {});
+const timeToFirstTokenSortSupported = coreStorage.TRACE_QUERY_ORDER_FIELDS?.includes("timeToFirstTokenMs") === true;
+const timingFeatures = [
+	...timeToFirstChunkSupported ? ["trace-query-time-to-first-chunk"] : [],
+	...timeToFirstChunkSupported && timeToFirstChunkSortSupported ? ["trace-query-time-to-first-chunk-sort"] : [],
+	...timeToFirstTokenSupported ? ["trace-query-time-to-first-token"] : [],
+	...timeToFirstTokenSupported && timeToFirstTokenSortSupported ? ["trace-query-time-to-first-token-sort"] : []
+];
+/** Order fields holding numbers that can be empty; the rest are timestamps. */
+const NUMERIC_ORDER_FIELDS = /* @__PURE__ */ new Set(["timeToFirstChunkMs", "timeToFirstTokenMs"]);
 function durationMsSql(startedAt, endedAt) {
 	return `dateDiff('millisecond', ${startedAt}, ${endedAt})`;
 }
@@ -6888,6 +6969,10 @@ const TRACE_FIELDS = {
 		sql: "r.timeToFirstChunkMs",
 		parameterType: "Float64"
 	},
+	timeToFirstTokenMs: {
+		sql: "r.timeToFirstTokenMs",
+		parameterType: "Float64"
+	},
 	entityId: {
 		sql: "r.entityId",
 		parameterType: "String"
@@ -6954,6 +7039,10 @@ const SPAN_FIELDS = {
 		sql: "s.timeToFirstChunkMs",
 		parameterType: "Float64"
 	},
+	timeToFirstTokenMs: {
+		sql: "s.timeToFirstTokenMs",
+		parameterType: "Float64"
+	},
 	status: {
 		sql: "s.status",
 		parameterType: "String"
@@ -7166,6 +7255,7 @@ const TRACE_SELECT = `
   r.entityType AS entityType,
   r.environment AS environment,
   r.timeToFirstChunkMs AS timeToFirstChunkMs,
+  r.timeToFirstTokenMs AS timeToFirstTokenMs,
   ${TRACE_STATUS_SQL} AS status`;
 var ParameterBuilder = class {
 	params = {};
@@ -7182,7 +7272,7 @@ function fieldDefinition(registry, field) {
 	return definition;
 }
 function resolveOrderField(field) {
-	if (field === "startedAt" || field === "endedAt" || field === "timeToFirstChunkMs") return field;
+	if (field === "startedAt" || field === "endedAt" || NUMERIC_ORDER_FIELDS.has(field)) return field;
 	throw new Error(`Unsupported trusted trace-query field: ${field}`);
 }
 function isMetadataField(field) {
@@ -7372,6 +7462,7 @@ function compileClickHouseTraceScope(selection, relationCollections, parameters,
       endedAt,
       ${durationMsSql("startedAt", "endedAt")} AS durationMs,
       timeToFirstChunkMs,
+      timeToFirstTokenMs,
       if(isNotNull(error), 'error', 'success') AS status,
       error,
       entityType,
@@ -7487,7 +7578,7 @@ function traceOrder(plan) {
 function keysetCursorCondition(plan, order, parameters) {
 	if (plan.paginationMode !== "keyset" || !plan.cursor) return "";
 	if (plan.cursor.sortValue === null) return `(isNull(sortValue) AND traceId > ${parameters.add(plan.cursor.traceId, "String")})`;
-	const numeric = order.field === "timeToFirstChunkMs";
+	const numeric = NUMERIC_ORDER_FIELDS.has(order.field);
 	const comparison = order.direction === "ASC" ? ">" : "<";
 	const sortValue = parameters.add(plan.cursor.sortValue, numeric ? "Float64" : "DateTime64(3, 'UTC')");
 	return `(sortValue ${comparison} ${sortValue} OR (sortValue = ${sortValue} AND traceId > ${parameters.add(plan.cursor.traceId, "String")})${numeric ? " OR isNull(sortValue)" : ""})`;
@@ -7501,7 +7592,7 @@ function compileClickHouseTraceQueryKeys(plan) {
 	if (plan.paginationMode === "delta") throw new Error("Delta trace queries have no keys statement");
 	const parameters = new ParameterBuilder();
 	const order = traceOrder(plan);
-	const ctes = compileClickHouseTraceCandidates(plan, "r.traceId AS traceId, r.dedupeKey AS dedupeKey, r.startedAt AS startedAt, r.endedAt AS endedAt, r.timeToFirstChunkMs AS timeToFirstChunkMs", parameters, QUERY_TRACES_SCOPE);
+	const ctes = compileClickHouseTraceCandidates(plan, "r.traceId AS traceId, r.dedupeKey AS dedupeKey, r.startedAt AS startedAt, r.endedAt AS endedAt, r.timeToFirstChunkMs AS timeToFirstChunkMs, r.timeToFirstTokenMs AS timeToFirstTokenMs", parameters, QUERY_TRACES_SCOPE);
 	const cursor = keysetCursorCondition(plan, order, parameters);
 	const limit = plan.paginationMode === "page" ? `LIMIT ${parameters.add(plan.perPage, "UInt64")} OFFSET ${parameters.add(plan.page * plan.perPage, "UInt64")}` : `LIMIT ${parameters.add(plan.limit + 1, "UInt64")}`;
 	return {
@@ -7902,7 +7993,8 @@ async function queryTraces(client, plan, timeoutMs, strategy = null) {
 		entityType: row.entityType == null ? null : String(row.entityType),
 		environment: row.environment == null ? null : String(row.environment),
 		status: row.status,
-		...timeToFirstChunkSupported && { timeToFirstChunkMs: row.timeToFirstChunkMs == null ? null : Number(row.timeToFirstChunkMs) }
+		...timeToFirstChunkSupported && { timeToFirstChunkMs: row.timeToFirstChunkMs == null ? null : Number(row.timeToFirstChunkMs) },
+		...timeToFirstTokenSupported && { timeToFirstTokenMs: row.timeToFirstTokenMs == null ? null : Number(row.timeToFirstTokenMs) }
 	});
 	if (plan.paginationMode === "delta") {
 		const rows = await run(compileClickHouseTraceQuery(plan, deltaHead));
@@ -7925,7 +8017,7 @@ async function queryTraces(client, plan, timeoutMs, strategy = null) {
 		});
 	}
 	const keys = await run(compileClickHouseTraceQueryKeys(plan));
-	const sortValue = (value) => plan.orderBy.field !== "timeToFirstChunkMs" ? asIsoTimestamp(value) : value == null ? null : Number(value);
+	const sortValue = (value) => !NUMERIC_ORDER_FIELDS.has(plan.orderBy.field) ? asIsoTimestamp(value) : value == null ? null : Number(value);
 	let total = Number(keys[0]?.__total ?? 0);
 	if (plan.paginationMode === "page" && keys.length === 0 && plan.page > 0) {
 		const [stats] = await run(compileClickHouseTraceQueryTotal(plan));
@@ -8028,6 +8120,7 @@ const displayFields = [
 	"provider",
 	"durationMs",
 	"timeToFirstChunkMs",
+	"timeToFirstTokenMs",
 	"status"
 ];
 var Parameters = class {
@@ -8056,7 +8149,7 @@ function afterCursor$1(plan, parameters) {
 	const equal = [];
 	if (cursor.sortValue === null) equal.push(`isNull(${field})`);
 	else {
-		const numeric = plan.orderBy.field === "timeToFirstChunkMs";
+		const numeric = plan.orderBy.field === "timeToFirstChunkMs" || plan.orderBy.field === "timeToFirstTokenMs";
 		const value = parameters.add(cursor.sortValue, numeric ? "Float64" : "DateTime64(3, 'UTC')");
 		terms.push(`${field} ${plan.orderBy.direction === "asc" ? ">" : "<"} ${value}`);
 		if (numeric) terms.push(`isNull(${field})`);
@@ -8152,6 +8245,7 @@ const TRACE_BRANCHES_SPAN_FIELD_COLUMNS = {
 		"startedAt",
 		"endedAt",
 		"timeToFirstChunkMs",
+		"timeToFirstTokenMs",
 		"threadId",
 		"runId",
 		"sessionId",
@@ -8312,12 +8406,13 @@ async function querySpans(client, plan, timeoutMs) {
 	const hydrated = page.flatMap((identity) => {
 		const row = byIdentity.get(coreStorage.spanQueryIdentityKey(identity));
 		if (!row) return [];
-		const { inputPreview: _input, outputPreview: _output, errorPreview: _error, timeToFirstChunkMs, ...metadata } = row;
+		const { inputPreview: _input, outputPreview: _output, errorPreview: _error, timeToFirstChunkMs, timeToFirstTokenMs, ...metadata } = row;
 		return [{
 			...metadata,
 			...identity,
 			durationMs: Number(row.durationMs),
-			...timeToFirstChunkSupported && { timeToFirstChunkMs: timeToFirstChunkMs == null ? null : Number(timeToFirstChunkMs) }
+			...timeToFirstChunkSupported && { timeToFirstChunkMs: timeToFirstChunkMs == null ? null : Number(timeToFirstChunkMs) },
+			...timeToFirstTokenSupported && { timeToFirstTokenMs: timeToFirstTokenMs == null ? null : Number(timeToFirstTokenMs) }
 		}];
 	});
 	let metrics = [];
@@ -8440,7 +8535,11 @@ function compileClickHouseThreadRowsQuery(plan, strategy = "full") {
 	const after = afterCursor(plan, parameters);
 	const qualify = plan.timeRange.mode === "traces" ? "s.inWindow > 0" : `s.${plan.timeRange.field} >= ${from} AND s.${plan.timeRange.field} < ${to}`;
 	const filtered = predicateFields(plan.where);
-	const firstContext = [...contextFields, "timeToFirstChunkMs"].filter((field) => field === "resourceId" || filtered.has(field));
+	const firstContext = [
+		...contextFields,
+		"timeToFirstChunkMs",
+		"timeToFirstTokenMs"
+	].filter((field) => field === "resourceId" || filtered.has(field));
 	const firstFields = [
 		"startedAt",
 		"traceId",
@@ -8464,7 +8563,7 @@ function compileClickHouseThreadRowsQuery(plan, strategy = "full") {
 		...firstContext,
 		...filtered.has("status") ? ["status"] : []
 	];
-	const rootExpression = (field) => field === "timeToFirstChunkMs" ? "if(spanType = 'agent_run', timeToFirstChunkMs, NULL)" : field === "status" ? "if(isNull(error), 'success', 'error')" : field;
+	const rootExpression = (field) => field === "timeToFirstChunkMs" || field === "timeToFirstTokenMs" ? `if(spanType = 'agent_run', ${field}, NULL)` : field === "status" ? "if(isNull(error), 'success', 'error')" : field;
 	const sortedRoots = `roots AS (
     SELECT organizationId, traceId, ${rootDataFields.map((field) => `${rootExpression(field)} AS ${field}`).join(", ")}
     FROM ${TABLE_TRACE_ROOTS} ${scope.length || strategy === "candidates" ? `WHERE ${[...scope, ...strategy === "candidates" ? [candidateTracesFilter] : []].join(" AND ")}` : ""}
@@ -8568,6 +8667,7 @@ async function queryThreadRows(client, plan, timeoutMs, strategy = "auto") {
 	for (const batch of batches([...roots.values()])) stored.push(...await run({
 		query: `SELECT organizationId, traceId, spanId, startedAt, endedAt,
       ${contextFields.join(", ")}, if(spanType = 'agent_run', timeToFirstChunkMs, NULL) AS timeToFirstChunkMs,
+      if(spanType = 'agent_run', timeToFirstTokenMs, NULL) AS timeToFirstTokenMs,
       if(isNull(error), 'success', 'error') AS status, ${PREVIEW_COLUMNS.join(", ")}
       FROM ${TABLE_TRACE_ROOTS} WHERE ${rootWhere}
       ORDER BY ${ROOT_VERSION_ORDER} LIMIT 1 BY organizationId, traceId, spanId`,
@@ -8601,6 +8701,7 @@ async function queryThreadRows(client, plan, timeoutMs, strategy = "auto") {
 			endedAt: iso(row.endedAt),
 			traceCount: Number(row.traceCount),
 			timeToFirstChunkMs: first.timeToFirstChunkMs,
+			...timeToFirstTokenSupported && { timeToFirstTokenMs: first.timeToFirstTokenMs },
 			inputPreview: resolveStoredPreviews(first).inputPreview,
 			outputPreview: resolveStoredPreviews(last).outputPreview,
 			errorPreview: resolveStoredPreviews(last).errorPreview
@@ -10257,7 +10358,7 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
 			"trace-query-tenant-scope",
 			"feedback",
 			"trace-query-context-ids",
-			...timeToFirstChunkFeatures,
+			...timingFeatures,
 			"trace-query-root-span-fields",
 			"trace-query-root-entity-id",
 			"trace-aggregate",
@@ -10282,7 +10383,7 @@ var ObservabilityStorageClickhouseVNext = class extends ObservabilityStorage {
 			"trace-query-tenant-scope",
 			"feedback",
 			"trace-query-context-ids",
-			...timeToFirstChunkFeatures,
+			...timingFeatures,
 			"trace-query-root-span-fields",
 			"trace-query-root-entity-id",
 			"trace-aggregate",