Promote finishReason/reasoningTokens to first-class trace + Model Hub fields

docs/api/tracing.md

@@ -323,6 +323,15 @@ Two fields depend on what the producer recorded:
 | `parentSpanId` | Event | Parent span identifier (for hierarchy) |
 | `source` | Session | Ingestion source: `custom` or `otlp` |
 
+## Token & Finish Reason Fields
+
+| Field | Scope | Description |
+|------|-------|-------------|
+| `reasoningTokens` | Event | Reasoning/thinking tokens the model spent before its answer (e.g. OpenAI's `completion_tokens_details.reasoning_tokens`). A **subset** of `outputTokens` — never billed on top of it. |
+| `finishReason` | Event | Normalized (trim + lowercase) raw provider stop reason — `stop`, `length`, `tool_calls`, etc. |
+| `totalReasoningTokens` | Session | Running total of the session's event `reasoningTokens`. Already counted within `totalOutputTokens` — never add it again in cost math. |
+| `truncatedEvents` | Session | Count of events whose `finishReason` signalled a token/length cutoff (`length`, `max_tokens`, …) rather than the model stopping on its own terms. |
+
 ## Event Types
 
 Console aggregates per type, so producers should use these names rather than

docs/guide/observability/data-model.md

@@ -35,6 +35,8 @@ tying them together.
 | `startedAt` / `endedAt` | ISO 8601 | |
 | `durationMs` | number | |
 | `summary` | totals | `totalInputTokens`, `totalOutputTokens`, `totalCachedInputTokens`, `totalDurationMs`, `eventCounts` |
+| `totalReasoningTokens` | number | Running total of the session's event `reasoningTokens`. Already counted within `totalOutputTokens` — see [Tokens](#tokens) — never add it again in cost math. |
+| `truncatedEvents` | number | Count of events whose `finishReason` signalled a token/length cutoff (`length`, `max_tokens`, …) rather than the model stopping on its own terms. |
 | `config` | object | Free-form run configuration, shown on the session header. |
 | `errors` | array | A non-empty list marks the session failed. |
 
@@ -74,6 +76,8 @@ Console aggregates per type, so use these rather than inventing names:
 | `error` | string or object | Attached to a failed step. |
 | `model` | string | **The provider's model id** (`gpt-4.1-mini`), not a nickname — see [Cost](#cost-and-double-counting). |
 | `inputTokens` / `outputTokens` / `cachedInputTokens` / `totalTokens` | number | See [Tokens](#tokens). |
+| `reasoningTokens` | number | Reasoning/thinking tokens the model spent before its answer (e.g. OpenAI's `completion_tokens_details.reasoning_tokens`). A **subset** of `outputTokens` — see [Tokens](#tokens) — never billed on top of it. |
+| `finishReason` | string | Normalized (trim + lowercase) raw provider stop reason — `stop`, `length`, `tool_calls`, etc. Feeds the session's `truncatedEvents` count. |
 | `toolName` / `toolExecutionId` | string | `toolExecutionId` correlates the run with the model's tool-call id. |
 | `toolDefinitions` | array | The tool menu offered on this call. See below. |
 | `actor` | `{scope, name}` | `scope` is `agent`, `model`, `tool`, `retriever` or `user`; drives the actor column. |
@@ -150,6 +154,12 @@ inputTokens       = input_tokens + cache_read_input_tokens + cache_creation_inpu
 cachedInputTokens = cache_read_input_tokens
 ```
 
+`reasoningTokens` is also a **subset** — of `outputTokens`, not `inputTokens` —
+covering the model's internal reasoning/thinking tokens. It is never added on
+top of `outputTokens` or `totalTokens` in cost math; it exists so the
+reasoning/answer split is visible without double-billing it. The session's
+`totalReasoningTokens` is the running sum of the field across its events.
+
 ::: warning Absent is not zero
 When a framework reports no usage — a streaming call without usage opt-in, a
 cancelled run — the fields are **omitted**. A zero would silently under-report

docs/public/openapi.yaml

@@ -19786,6 +19786,14 @@ components:
         totalTokens:
           type: integer
           nullable: true
+        reasoningTokens:
+          type: integer
+          nullable: true
+          description: Reasoning/thinking tokens spent by this event's model call. A subset of outputTokens — never billed, or summed into totalTokens, on top of it.
+        finishReason:
+          type: string
+          nullable: true
+          description: "Raw provider finish reason for this event's model call, e.g. stop, length, tool_calls."
         durationMs:
           type: integer
           description: Event duration in milliseconds.
@@ -20022,6 +20030,14 @@ components:
         totalCachedInputTokens:
           type: integer
           nullable: true
+        totalReasoningTokens:
+          type: integer
+          nullable: true
+          description: Sum of reasoningTokens across the session's events. A subset of totalOutputTokens — never billed, or summed into a token total, on top of it.
+        truncatedEvents:
+          type: integer
+          nullable: true
+          description: "Count of events whose finishReason indicates a token/length cutoff (e.g. length, max_tokens) rather than a normal stop."
         totalBytesIn:
           type: integer
           nullable: true

package.json

@@ -22,6 +22,7 @@
     "seed:beta-codes": "node --import tsx scripts/seed-beta-codes.ts",
     "backfill:usage-daily": "node --import tsx scripts/backfill-usage-daily.ts",
     "backfill:trace-usage": "node --import tsx scripts/backfill-trace-usage.ts",
+    "backfill:trace-fields": "node --import tsx scripts/backfill-trace-fields.ts",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"