@runtypelabs/flue-otel 0.2.0 → 0.2.2

package/README.md

@@ -1,17 +1,30 @@
 # @runtypelabs/flue-otel
 
-OpenTelemetry instrumentation for [Flue](https://flueframework.com) agents that
-reports runs to [Runtype](https://runtype.com) at full fidelity.
+OpenTelemetry instrumentation for [Flue](https://flueframework.com) agents.
+It subscribes to a Flue runtime through `instrument()` and turns every agent
+run into a trace of GenAI semantic-convention spans carrying Runtype's
+`runtype.*` attributes. Export those spans to [Runtype](https://runtype.com)
+and each run appears in your dashboard as a first-class execution: model,
+token usage, cost, loop iterations, tool calls and stop reason.
 
-Install it with Flue's `instrument()`, point an OTLP exporter at Runtype, and
-every agent run appears in your Runtype dashboard as a first-class execution —
-with the model, token counts, cost, loop iterations, tool calls and stop reason
-that a native Runtype run has.
+- Works with Flue `>=1.0.0-beta.9` and 2.x from one entry point.
+- Depends on `@opentelemetry/api` only. It brings no SDK, provider, exporter or
+  sampler; it writes through whatever your application has registered.
+- Emits identifiers, structure and metrics only. No prompts, completions, tool
+  arguments, tool results, error messages or stack traces reach the wire.
+
+Full guide: [Instrumenting a Flue agent](https://docs.runtype.com/developer-guides/guides/flue-instrumentation).
+
+## Install
 
 ```bash
 npm install @runtypelabs/flue-otel @opentelemetry/api
 ```
 
+Requires Node 22+ and a Flue runtime that exposes `instrument()`.
+
+## Quick start
+
 ```ts
 import { instrument } from '@flue/runtime'
 import { createRuntypeFlueInstrumentation } from '@runtypelabs/flue-otel'
@@ -19,59 +32,19 @@ import { createRuntypeFlueInstrumentation } from '@runtypelabs/flue-otel'
 const stopInstrumenting = instrument(createRuntypeFlueInstrumentation())
 ```
 
-Works on **both** Flue lines — `>=1.0.0-beta.9` and 2.x — from one entry point.
-
-## Already exporting Flue traces to Runtype? Read this first
-
-Two things change, and one of them is a regression, so decide before you install:
-
-- **Replace your stock instrumentation, do not add to it.** Flue's
-  `instrument()` composes, and this package carries its own key, so calling both
-  is possible and silently wrong: Runtype receives two `invoke_agent` spans for
-  one run and the **token counts and cost double**. Point exactly one Flue
-  instrumentation at a given Runtype endpoint.
-- **You will lose the transcript.** Stock `@flue/opentelemetry` exports content
-  by default, so your runs currently carry prompts and completions. This release
-  exports none (below), which also means **eval capture from these runs stops
-  working**. In exchange the runs gain loop structure, an accurate iteration
-  count, a stop reason, and priced usage. If the transcript is what you rely on,
-  stay on stock until content ships.
-
-## It emits no content
-
-This release puts **no prompts, completions, tool arguments, tool results, error
-messages or stack traces on the wire.** Only identifiers, structure and metrics.
-
-That is deliberate and it is the default we intend to keep earning: a package
-that lands inside your process should not start shipping your users' text
-somewhere because you installed it. Content export is a later, explicitly
-opt-in increment. Until it exists, there is nothing to configure and nothing to
-audit — the spans carry model ids, token counts, durations, tool _names_, and
-correlation ids.
-
-Two consequences worth knowing:
-
-- Your Runtype executions will show timing, cost, iteration counts and the tool
-  call sequence, but **no transcript**. Eval capture from an external run needs
-  content and is not available yet.
-- If you also run stock `@flue/opentelemetry`, note that it treats calling
-  `instrument()` as consent to export content by default. That is a different
-  choice, not a bug — but it is worth checking before you point it at a
-  third-party backend.
-
-## It brings no OpenTelemetry SDK
-
-This package depends on `@opentelemetry/api` and nothing else. It creates no
-provider, no exporter, no sampler, no resource, and it never flushes. Your
-application owns all of that, and this instrumentation writes through whatever
-you have registered.
-
-If you already run OpenTelemetry, you are done after the `instrument()` call
-above — add the resource attributes below so Runtype knows which agent the runs
-belong to.
+That is the whole integration if your process already runs an OpenTelemetry
+SDK. Spans are written to the globally registered tracer provider, so anything
+you already export (an OTLP exporter, a vendor exporter, a collector) receives
+them. To send them to Runtype, add an OTLP/HTTP exporter pointed at
+`https://api.runtype.com/v1/otel` with a Runtype API key that has the
+`TELEMETRY:WRITE` scope, and set the resource attributes described under
+[Attribution](#attribution).
 
 ### If you have no OpenTelemetry setup yet
 
+You need `@opentelemetry/sdk-trace-node`,
+`@opentelemetry/exporter-trace-otlp-http` and `@opentelemetry/resources`.
+
 ```ts
 import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
@@ -85,7 +58,6 @@ import {
 const provider = new NodeTracerProvider({
   resource: resourceFromAttributes({
     'service.name': 'my-agent',
-    // Which Runtype agent these runs file under, plus adapter provenance.
     ...runtypeFlueResourceAttributes({ agentId: process.env.RUNTYPE_AGENT_ID }),
   }),
   spanProcessors: [
@@ -97,45 +69,61 @@ const provider = new NodeTracerProvider({
     ),
   ],
 })
-// `register()` also installs the context manager, WITHOUT WHICH nothing nests:
-// the OTel API's default is a no-op that makes every span a trace root.
+
+// Registers the provider AND a context manager. Without a context manager the
+// OTel API falls back to a no-op and every span becomes its own trace root.
 provider.register()
 
 instrument(createRuntypeFlueInstrumentation())
 
-// Flush before the process exits — see "Shutdown" below. This is not optional.
+// Flush before exit. See "Shutdown" below.
 process.on('beforeExit', () => void provider.shutdown())
 ```
 
-You will also need `@opentelemetry/sdk-trace-node`,
-`@opentelemetry/exporter-trace-otlp-http` and `@opentelemetry/resources`.
+## Configuration
+
+`createRuntypeFlueInstrumentation(options?)` accepts:
+
+| Option   | Type                     | Purpose                                                                                                                                                                      |
+| -------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents` | `Record<string, string>` | Runtype agent id per Flue agent name, e.g. `{ triage: 'agent_01j...' }`. Stamped as `runtype.agent.id` on that agent's `invoke_agent` span. See [Attribution](#attribution). |
+| `tracer` | `Tracer`                 | Where spans are written. Defaults to `trace.getTracer('@runtypelabs/flue-otel')` on the global provider. Pass one to route Runtype spans through a separate provider.        |
 
-## Shutdown is yours, and it matters
+The returned object implements Flue's full `FlueInstrumentation` contract:
+`observe` (builds spans from Flue's observation stream), `interceptor` (makes
+each span the active OTel context around the agent, model and tool work, so
+your own HTTP and database spans nest inside the run, and joins a dispatched
+run to its originating trace via `executionContext.traceCarrier`), and
+`dispose` (closes anything still open as `interrupted`).
 
-A `BatchSpanProcessor` flushes children before their parents. A process that
-exits without `forceFlush()` or `shutdown()` therefore tends to lose the
-**closing `invoke_agent` span specifically** — and a run whose envelope never
-arrives is recorded as still in flight, permanently.
+`instrument()` returns a disposer; call it when you want to stop instrumenting.
+Instrumentations compose, so installing this one never replaces another
+subscriber. Its key is exported as `RUNTYPE_FLUE_INSTRUMENTATION_KEY`.
 
-Wire the shutdown. In a serverless handler, `await provider.forceFlush()` before
-returning.
+### Other exports
 
-Flue's `instrument()` returns a disposer. Calling it ends any span still open as
-`interrupted`, which is what you want on an unclean exit — but it does not
-flush, because the exporter is not ours to flush.
+- `runtypeFlueResourceAttributes({ agentId? })` builds the `runtype.*` resource
+  attributes (`schema.version`, `adapter.name`, `adapter.version`, and
+  `agent.id` when given). Spread it into your SDK `Resource`.
+- `GEN_AI` and `RUNTYPE`: the attribute-name constants this package emits.
+- `RUNTYPE_STOP_REASONS`, `RUNTYPE_TOOL_TYPES`, `RUNTYPE_SCHEMA_VERSION`,
+  `ADAPTER_NAME`, `ADAPTER_VERSION`, plus the `RuntypeStopReason`,
+  `RuntypeToolType`, `FlueInstrumentation`, `FlueProjectionOptions`,
+  `SpanAttributes` and `SpanIntent` types.
 
-## Attribution: which Runtype agent owns the run
+## Attribution
 
-Runtype resolves the owning agent in this order:
+Runtype files each trace under one agent, resolved in this order:
 
-1. the `runtype.agent.id` **resource** attribute (what
-   `runtypeFlueResourceAttributes({ agentId })` sets) — preferred;
-2. the `x-runtype-agent-id` request header on the exporter;
-3. the `runtype.agent.id` attribute on the run's `invoke_agent` span.
+1. The `runtype.agent.id` **resource** attribute. `runtypeFlueResourceAttributes({ agentId })` sets it. Preferred.
+2. The `x-runtype-agent-id` **request header** on the exporter (for example via
+   `OTEL_EXPORTER_OTLP_HEADERS=x-runtype-agent-id=agent_...`).
+3. The `runtype.agent.id` attribute on the run's `invoke_agent` **span**, which
+   the `agents` option sets.
 
-The first two describe a whole process, so they are the right answer when it
-runs one Runtype agent. **One process running several Runtype agents** cannot
-express that in a shared resource, which is what the third placement is for:
+Use 1 or 2 when a process runs one Runtype agent. Use the `agents` option when a
+single process runs several Runtype agents, since a shared resource cannot name
+the right one per run:
 
 ```ts
 createRuntypeFlueInstrumentation({
@@ -146,72 +134,104 @@ createRuntypeFlueInstrumentation({
 })
 ```
 
-A delegated sub-agent is deliberately **not** attributed separately. Its work
-runs inside the delegating agent's trace, and one trace is one execution.
-
-> **One agent invocation per trace.** Runtype's model is that one trace is one
-> execution, and spans inherit whatever OTel context is active. So if an
-> enclosing span is active while two agent invocations run — an HTTP server span
-> from auto-instrumentation is the usual way this happens — both land in the
-> same trace, and Runtype either merges them into one execution (dropping the
-> second run's usage and stop reason) or, when they claim different
-> `runtype.agent.id` values through the `agents` map above with no resource
-> attribute and no header to fall back on, rejects the trace as
-> `ambiguous_agent_attribution` and writes nothing.
->
-> If you dispatch several agent invocations inside one request or job, start
-> each one in its own trace, or attribute at the resource level with one process
-> per agent. Flue's own `dispatch(...)` does not propagate trace context, so a
-> plain dispatch is already its own trace.
-
-## Composing with other instrumentations
-
-Flue's `instrument()` composes — an error reporter and a tracer subscribe side
-by side — and this package carries its own key, so installing it never replaces
-`@flue/opentelemetry`.
-
-> **Point exactly one instrumentation at Runtype.** If this package and a stock
-> `@flue/opentelemetry` both export to the same Runtype endpoint, Runtype sees
-> two `invoke_agent` spans for one run and the **token counts double**. Running
-> both is fine when they export to different backends.
+A trace with no attribution from any source is rejected, not guessed. A
+delegated sub-agent is not attributed separately: its work belongs to the
+delegating agent's trace, and one trace is one execution.
 
-## What it emits
+### One agent invocation per trace
+
+Spans inherit whatever OTel context is active. If an enclosing span is active
+while two agent invocations run (an HTTP server span from auto-instrumentation
+is the common case), both land in the same trace. Runtype then either merges
+them into one execution, dropping the second run's usage and stop reason, or,
+when they claim different ids through `agents` with no resource attribute or
+header to settle it, rejects the trace as `ambiguous_agent_attribution`.
+
+If you dispatch several agent invocations inside one request or job, start each
+in its own trace, or attribute at the resource level with one process per agent.
+Flue's own `dispatch(...)` does not propagate trace context, so a plain dispatch
+is already its own trace.
+
+## Shutdown
 
-| Span                                                           | When                               | Carries                                                                                                                                                                                        |
-| -------------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `invoke_agent <agent>`                                         | one per agent invocation           | the run's model, summed token usage, `runtype.stop_reason`, `runtype.tools.reported`, the highest loop iteration, `runtype.execution.id`, and `runtype.agent.id` when `agents` names the agent |
-| `chat <model>`                                                 | one per model turn                 | provider, request/response model, finish reason, per-turn usage, `runtype.turn.id` / `.turn.index` / `.iteration`                                                                              |
-| `execute_tool <tool>`                                          | one per tool call                  | `gen_ai.tool.name`, `gen_ai.tool.call.id`, the loop position it belongs to, and `runtype.tool.type` when the tool's class is actually known                                                    |
-| `flue.task <agent>`, `flue.compaction`, `flue.operation shell` | delegation, compaction, host shell | correlation ids only — these are framework structure, not agent invocations                                                                                                                    |
+This package never flushes; the exporter is yours. A `BatchSpanProcessor`
+exports children before their parents, so a process that exits without
+`forceFlush()` or `shutdown()` tends to lose the closing `invoke_agent` span
+specifically, and a run whose envelope never arrives is recorded as still in
+flight. Wire the shutdown. In a serverless handler, `await provider.forceFlush()`
+before returning.
 
-Every span also carries the `flue.*` correlation attributes stock
-`@flue/opentelemetry` emits, so dashboards you have already built keep working.
+The disposer returned by `instrument()` ends any still-open span as
+`interrupted`, folding the usage and iteration count seen so far onto the
+envelope first. It does not flush.
 
-### Two places it deliberately says nothing
+## Point one instrumentation at Runtype
+
+Flue's `instrument()` composes and this package carries its own key, so it can
+run alongside `@flue/opentelemetry`. Do not export both to the same Runtype
+endpoint: Runtype would receive two `invoke_agent` spans for one run and count
+its tokens and cost twice. Running both is fine when they export to different
+backends.
+
+## What it emits
 
-- **`runtype.tool.type` for an ordinary tool.** Flue's `origin` field classifies
-  who _initiated_ a call (`model` for every model-requested tool, whoever wrote
-  it), not what the tool _is_. Mapping it would fill the column with a value
-  that means nothing on that axis. Only a genuine class fact is emitted: a
-  sub-agent delegation, and a 1.x `datastore` tool.
-- **A stop reason it cannot determine.** A run that ended mid-tool-call reports
+| Span                                                           | When                                    | Carries                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `invoke_agent <agent>`                                         | once per agent invocation               | `gen_ai.agent.name`, `gen_ai.conversation.id`, the run's request/response model, summed token usage across every turn (`gen_ai.usage.*`), `runtype.stop_reason`, `runtype.tools.reported`, the highest loop iteration (`runtype.iteration`), `runtype.execution.id`, and `runtype.agent.id` when `agents` names the agent                                                                                                                                     |
+| `chat <model>`                                                 | once per model turn                     | `gen_ai.provider.name`, request/response model, response id, finish reason, per-turn usage, request parameters (`max_tokens`, `temperature`, reasoning level, server address), `runtype.turn.id` / `runtype.turn.index` / `runtype.iteration`, and `runtype.provider.finish_reason` / `runtype.gateway.log_id` when the provider records them (Workers AI attaches both — the gateway log id is a pointer to that exact request in your AI Gateway dashboard) |
+| `execute_tool <tool>`                                          | once per model-requested tool call      | `gen_ai.tool.name`, `gen_ai.tool.call.id`, the loop position it belongs to, `gen_ai.tool.type` (`function`) for every tool except a sub-agent delegation, and `runtype.tool.type` when the tool's class is known                                                                                                                                                                                                                                              |
+| `flue.task <agent>`, `flue.compaction`, `flue.operation shell` | delegation, compaction, host shell call | correlation ids only; framework structure, not agent invocations                                                                                                                                                                                                                                                                                                                                                                                              |
+
+Every span also carries Flue's own `flue.*` correlation attributes
+(`flue.instance.id`, `flue.submission.id`, `flue.agent.name`,
+`flue.session.name`, `flue.operation.id`, `flue.turn.id`, `flue.task.id`, and
+so on), so dashboards grouped on those keys keep working.
+
+Rules the projection follows:
+
+- **Exactly one `invoke_agent` span per run.** A sub-agent delegation is
+  reported as an `execute_tool` span typed `subagent`; the sub-agent's own work
+  gets a `flue.task` span. Nested `prompt` operations inside a task do not open
+  a second envelope.
+- **Usage is summed from model-turn leaves onto the envelope**, compaction
+  turns included, so the batch carrying the terminal span always carries the
+  complete total. `gen_ai.usage.input_tokens` is the total prompt-side count;
+  cache reads and writes are broken out separately.
+- **Loop position is counted in process.** `runtype.turn.index` and
+  `runtype.iteration` are absolute ordinals; only the root agent's turns carry
+  `runtype.iteration`, so delegated work never inflates the run's iteration
+  count.
+- **A failed span carries the error type and exception class name only.**
+- **Framework bookkeeping is never a trace root.** `flue.compaction` and
+  `flue.operation shell` are dropped when there is no run to nest under, so a
+  host-initiated `session.compact()` or `session.shell()` cannot register as an
+  execution.
+
+### Where it deliberately says nothing
+
+- **`runtype.tool.type` for an ordinary tool.** Flue's `origin` field says who
+  initiated a call, not what the tool is, so it is not mapped. Only genuine
+  class facts are emitted: `subagent` for a delegation, `data_connection` for a
+  1.x `datastore` tool.
+- **A stop reason it cannot determine.** A run that ended mid tool call reports
   `unknown` rather than guessing between a turn cap, a tool cap and a host
-  abort.
+  abort. `submission_settled` outcomes `failed` / `aborted` map to `error`; a
+  turn's finish reason maps to `end_turn`, `length`, `content_filter` or `error`.
 
 An absent attribute costs one column. A wrong one renders as a measurement.
 
-## Deriving from Flue's stable surface only
+## Flue compatibility
 
-Everything here comes from the observations Flue publishes as stable — event
-type names, envelope and correlation fields, and the normalized `turn_request` /
+The instrumentation reads only Flue's stable observation surface: event type
+names, envelope and correlation fields, and the normalized `turn_request` /
 `turn` / `tool_*` / `task` / `operation` / `compaction` / `submission_settled`
-payloads.
+payloads. It never reads `AgentMessage`, which Flue marks unstable. The few
+fields that differ between the 1.x and 2.x lines are detected by probing the
+observation rather than comparing versions, which is why one build serves both.
 
-Nothing reads `AgentMessage`, which Flue documents as explicitly unstable and
-which rides `message_start`, `message_end`, `turn_messages` and `agent_end`.
-That exclusion is why one entry point serves both the 1.x and 2.x lines: the
-observation plane was essentially frozen across Flue's major rewrite, and the
-handful of fields that did change are probed rather than version-compared.
+An instrumentation must never break the agent it observes: every observer and
+disposer path swallows its own errors, and an unparseable Flue timestamp falls
+back to the SDK clock instead of throwing.
 
 ## License
 

package/dist/index.cjs

@@ -76,7 +76,7 @@ function mapSettlementOutcome(outcome) {
 }
 
 // package.json
-var version = "0.2.0";
+var version = "0.2.2";
 
 // src/semconv.ts
 var GEN_AI = {
@@ -118,7 +118,9 @@ var RUNTYPE = {
   toolsReported: "runtype.tools.reported",
   toolType: "runtype.tool.type",
   turnId: "runtype.turn.id",
-  turnIndex: "runtype.turn.index"
+  turnIndex: "runtype.turn.index",
+  providerFinishReason: "runtype.provider.finish_reason",
+  gatewayLogId: "runtype.gateway.log_id"
 };
 var FLUE = {
   instanceId: "flue.instance.id",
@@ -459,7 +461,17 @@ function createFlueProjection(options = {}) {
       ...response.responseModel ? { [GEN_AI.responseModel]: response.responseModel } : {},
       ...response.responseId ? { [GEN_AI.responseId]: response.responseId } : {},
       ...response.finishReason ? { [GEN_AI.finishReasons]: [response.finishReason] } : {},
-      ...usageAttributes(response.usage)
+      ...usageAttributes(response.usage),
+      // Provider-diagnostic pointers, emitted only when Flue actually provides
+      // them. Both are optional and provider-dependent (Workers AI attaches
+      // both today); an absent value costs one column, a synthesized one would
+      // render as a measurement. `gatewayLogId` is a pointer to the content
+      // without shipping the content — a customer can click through to that
+      // exact request in their own AI Gateway dashboard. `providerFinishReason`
+      // is the provider's exact finish value before normalization, which our
+      // `GEN_AI.finishReasons` above deliberately hides.
+      ...response.providerFinishReason ? { [RUNTYPE.providerFinishReason]: response.providerFinishReason } : {},
+      ...response.gatewayLogId ? { [RUNTYPE.gatewayLogId]: response.gatewayLogId } : {}
     };
     const intents = [];
     if (Object.keys(attributes).length > 0) intents.push({ kind: "update", ref, attributes });

package/dist/index.d.cts

@@ -100,6 +100,13 @@ interface FlueModelResponse {
     finishReason?: string;
     /** 2.x only. The provider's raw finish value before normalization. */
     providerFinishReason?: string;
+    /**
+     * The response's own gateway log id (e.g. Cloudflare AI Gateway's
+     * `cf-aig-log-id`), for correlating a specific turn with its entry in the
+     * gateway dashboard. Telemetry only — present only when the provider records
+     * one. The Workers AI provider attaches it today.
+     */
+    gatewayLogId?: string;
     error?: FlueErrorInfo;
 }
 /**
@@ -475,6 +482,8 @@ declare const RUNTYPE: {
     readonly toolType: "runtype.tool.type";
     readonly turnId: "runtype.turn.id";
     readonly turnIndex: "runtype.turn.index";
+    readonly providerFinishReason: "runtype.provider.finish_reason";
+    readonly gatewayLogId: "runtype.gateway.log_id";
 };
 /**
  * `runtype.tool.type` values — the closed domain that drives display and

package/dist/index.d.ts

@@ -100,6 +100,13 @@ interface FlueModelResponse {
     finishReason?: string;
     /** 2.x only. The provider's raw finish value before normalization. */
     providerFinishReason?: string;
+    /**
+     * The response's own gateway log id (e.g. Cloudflare AI Gateway's
+     * `cf-aig-log-id`), for correlating a specific turn with its entry in the
+     * gateway dashboard. Telemetry only — present only when the provider records
+     * one. The Workers AI provider attaches it today.
+     */
+    gatewayLogId?: string;
     error?: FlueErrorInfo;
 }
 /**
@@ -475,6 +482,8 @@ declare const RUNTYPE: {
     readonly toolType: "runtype.tool.type";
     readonly turnId: "runtype.turn.id";
     readonly turnIndex: "runtype.turn.index";
+    readonly providerFinishReason: "runtype.provider.finish_reason";
+    readonly gatewayLogId: "runtype.gateway.log_id";
 };
 /**
  * `runtype.tool.type` values — the closed domain that drives display and

package/dist/index.mjs

@@ -43,7 +43,7 @@ function mapSettlementOutcome(outcome) {
 }
 
 // package.json
-var version = "0.2.0";
+var version = "0.2.2";
 
 // src/semconv.ts
 var GEN_AI = {
@@ -85,7 +85,9 @@ var RUNTYPE = {
   toolsReported: "runtype.tools.reported",
   toolType: "runtype.tool.type",
   turnId: "runtype.turn.id",
-  turnIndex: "runtype.turn.index"
+  turnIndex: "runtype.turn.index",
+  providerFinishReason: "runtype.provider.finish_reason",
+  gatewayLogId: "runtype.gateway.log_id"
 };
 var FLUE = {
   instanceId: "flue.instance.id",
@@ -426,7 +428,17 @@ function createFlueProjection(options = {}) {
       ...response.responseModel ? { [GEN_AI.responseModel]: response.responseModel } : {},
       ...response.responseId ? { [GEN_AI.responseId]: response.responseId } : {},
       ...response.finishReason ? { [GEN_AI.finishReasons]: [response.finishReason] } : {},
-      ...usageAttributes(response.usage)
+      ...usageAttributes(response.usage),
+      // Provider-diagnostic pointers, emitted only when Flue actually provides
+      // them. Both are optional and provider-dependent (Workers AI attaches
+      // both today); an absent value costs one column, a synthesized one would
+      // render as a measurement. `gatewayLogId` is a pointer to the content
+      // without shipping the content — a customer can click through to that
+      // exact request in their own AI Gateway dashboard. `providerFinishReason`
+      // is the provider's exact finish value before normalization, which our
+      // `GEN_AI.finishReasons` above deliberately hides.
+      ...response.providerFinishReason ? { [RUNTYPE.providerFinishReason]: response.providerFinishReason } : {},
+      ...response.gatewayLogId ? { [RUNTYPE.gatewayLogId]: response.gatewayLogId } : {}
     };
     const intents = [];
     if (Object.keys(attributes).length > 0) intents.push({ kind: "update", ref, attributes });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/flue-otel",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "OpenTelemetry instrumentation for Flue agents that emits GenAI semconv spans plus Runtype's runtype.* extension vocabulary, so a Flue run lands in Runtype at full fidelity.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,7 +34,7 @@
     "tsup": "^8.0.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.0",
-    "@runtypelabs/shared": "3.27.1"
+    "@runtypelabs/shared": "3.28.0"
   },
   "publishConfig": {
     "access": "public"