@glassflow-ai/rius 0.7.0 → 0.8.0

package/README.md

@@ -118,8 +118,30 @@ automatically and recording any thrown exception. The options argument is
 optional in both, so `startAsCurrentSpan("step", async (span) => { ... })`
 works when you have nothing to configure.
 
+`kind` sets the span's taxonomy (`openinference.span.kind`, our `SpanKind`
+enum: CHAIN by default, or TOOL, RETRIEVER, EMBEDDING, AGENT, LLM). A TOOL
+span also carries `gen_ai.tool.name`, set to the span name. Each kind also
+decides the OpenTelemetry `SpanKind` field the conventions expect: LLM,
+EMBEDDING and RETRIEVER spans are CLIENT, everything else INTERNAL. Pass
+`otelKind` to override it, for example CLIENT for a call to a hosted agent.
+Note the name collision: `SpanKind` exported by this package is the taxonomy
+enum; the value for `otelKind` is `SpanKind` from `@opentelemetry/api`, so
+import that one under an alias.
+
+```ts
+import { SpanKind as OtelSpanKind } from "@opentelemetry/api";
+import { SpanKind, startAsCurrentSpan } from "@glassflow-ai/rius";
+
+await startAsCurrentSpan(
+  "delegate-to-planner",
+  { kind: SpanKind.AGENT, otelKind: OtelSpanKind.CLIENT, input: task },
+  async (span) => { ... },
+);
+```
+
 On the manual path, `recordException()` does what the scoped form does for
-you: it records the error and sets ERROR status.
+you: it records the error, sets ERROR status and sets `error.type` to the
+error's name.
 
 ```ts
 const span = startSpan("fetch-documents");
@@ -182,7 +204,7 @@ Install only the ones you use:
 - **`anthropic`** wraps the Anthropic SDK, via `@arizeai/openinference-instrumentation-anthropic`, turning Messages calls into LLM spans with model, messages and token counts.
 - **`langchain`** traces LangChain.js chains, models, tools and retrievers, via `@arizeai/openinference-instrumentation-langchain`. It patches the callback manager in `@langchain/core`, which every LangChain.js application already has, and the SDK resolves that module for you so nothing has to be passed in at `init()`.
 - **`vercel-ai`** attaches to spans the Vercel AI SDK's own OpenTelemetry integration produces, via `@arizeai/openinference-vercel`, adding OpenInference attributes to them. This package requires Node 22 or newer.
-- **`mcp`** patches `@modelcontextprotocol/sdk`'s `Client.callTool` so every MCP tool call becomes a TOOL span, carrying the tool name, arguments, result, latency, and error status.
+- **`mcp`** patches `@modelcontextprotocol/sdk`'s `Client.callTool` so every MCP tool call becomes a TOOL span named `execute_tool <tool>`, carrying the tool name, arguments, result, latency, and error status. The span follows the OpenTelemetry MCP conventions: OTel `SpanKind` CLIENT, `mcp.method.name` set to `tools/call`, `mcp.protocol.version` set to the negotiated version when the transport exposes it (Streamable HTTP does; stdio and SSE do not), and `error.type` set to `tool_error` when the server returns an `isError` result.
 
 There is no selection option: `init()` always attempts every bundled
 integration, so which ones actually attach is determined entirely by

package/dist/index.cjs

@@ -367,17 +367,22 @@ var init_heartbeat = __esm({
 });
 
 // src/semconv.ts
-function kindAttributes(kind) {
+function otelSpanKind(kind) {
+  return OTEL_KIND_BY_KIND[kind];
+}
+function kindAttributes(kind, name) {
   const attributes = { [OPENINFERENCE_SPAN_KIND]: kind };
   const operation = OPERATION_BY_KIND[kind];
   if (operation !== void 0) attributes[GEN_AI_OPERATION_NAME] = operation;
+  if (kind === "TOOL" /* TOOL */ && name !== void 0) attributes[GEN_AI_TOOL_NAME] = name;
   return attributes;
 }
-var TRACER_NAME, SERVICE_INSTANCE_ID, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, SESSION_ID, USER_ID, WORKSPACE_ROUTE, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_REQUEST_REASONING_LEVEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS, GEN_AI_USAGE_REASONING_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_TOOL_DEFINITIONS, GEN_AI_REQUEST_PREFIX, MCP_METHOD_NAME, MCP_METHOD_TOOLS_CALL, MCP_PROTOCOL_VERSION, ERROR_TYPE, ERROR_TYPE_TOOL_ERROR, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, CONTENT_ATTRIBUTES, LLM_INVOCATION_PARAMETERS, INVOCATION_PARAMETERS_CONTENT_MEMBERS, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
+var import_api, TRACER_NAME, SERVICE_INSTANCE_ID, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, SESSION_ID, USER_ID, WORKSPACE_ROUTE, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_REQUEST_REASONING_LEVEL, GEN_AI_RESPONSE_MODEL, GEN_AI_REQUEST_STREAM, GEN_AI_RESPONSE_TIME_TO_FIRST_CHUNK, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS, GEN_AI_USAGE_REASONING_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_TOOL_DEFINITIONS, GEN_AI_REQUEST_PREFIX, MCP_METHOD_NAME, MCP_METHOD_TOOLS_CALL, MCP_PROTOCOL_VERSION, ERROR_TYPE, ERROR_TYPE_TOOL_ERROR, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, OTEL_KIND_BY_KIND, CONTENT_ATTRIBUTES, LLM_INVOCATION_PARAMETERS, INVOCATION_PARAMETERS_CONTENT_MEMBERS, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
 var init_semconv = __esm({
   "src/semconv.ts"() {
     "use strict";
     init_cjs_shims();
+    import_api = require("@opentelemetry/api");
     TRACER_NAME = "glassflow";
     SERVICE_INSTANCE_ID = "service.instance.id";
     OPENINFERENCE_SPAN_KIND = "openinference.span.kind";
@@ -391,6 +396,8 @@ var init_semconv = __esm({
     GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
     GEN_AI_REQUEST_REASONING_LEVEL = "gen_ai.request.reasoning.level";
     GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+    GEN_AI_REQUEST_STREAM = "gen_ai.request.stream";
+    GEN_AI_RESPONSE_TIME_TO_FIRST_CHUNK = "gen_ai.response.time_to_first_chunk";
     GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
     GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
     GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens";
@@ -424,6 +431,14 @@ var init_semconv = __esm({
       ["EMBEDDING" /* EMBEDDING */]: "embeddings",
       ["AGENT" /* AGENT */]: "invoke_agent"
     };
+    OTEL_KIND_BY_KIND = {
+      ["LLM" /* LLM */]: import_api.SpanKind.CLIENT,
+      ["EMBEDDING" /* EMBEDDING */]: import_api.SpanKind.CLIENT,
+      ["RETRIEVER" /* RETRIEVER */]: import_api.SpanKind.CLIENT,
+      ["TOOL" /* TOOL */]: import_api.SpanKind.INTERNAL,
+      ["AGENT" /* AGENT */]: import_api.SpanKind.INTERNAL,
+      ["CHAIN" /* CHAIN */]: import_api.SpanKind.INTERNAL
+    };
     CONTENT_ATTRIBUTES = /* @__PURE__ */ new Set([
       INPUT_VALUE,
       OUTPUT_VALUE,
@@ -568,6 +583,9 @@ function toAttributeValue(value) {
     return "[unserializable]";
   }
 }
+function errorType(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
 var MAX_ATTR_CHARS, TRUNCATION_MARKER;
 var init_serde = __esm({
   "src/serde.ts"() {
@@ -580,16 +598,16 @@ var init_serde = __esm({
 
 // src/user.ts
 function withUser(userId, fn) {
-  return import_api.context.with(import_api.context.active().setValue(USER_KEY, userId), () => fn(userId));
+  return import_api2.context.with(import_api2.context.active().setValue(USER_KEY, userId), () => fn(userId));
 }
-var import_api, USER_KEY, UserSpanProcessor;
+var import_api2, USER_KEY, UserSpanProcessor;
 var init_user = __esm({
   "src/user.ts"() {
     "use strict";
     init_cjs_shims();
-    import_api = require("@opentelemetry/api");
+    import_api2 = require("@opentelemetry/api");
     init_semconv();
-    USER_KEY = (0, import_api.createContextKey)("rius-user-id");
+    USER_KEY = (0, import_api2.createContextKey)("rius-user-id");
     UserSpanProcessor = class {
       onStart(span, parentContext) {
         const value = parentContext.getValue(USER_KEY);
@@ -610,15 +628,18 @@ function configure(observation, options) {
   if (options.input !== void 0) observation.setInput(options.input);
   return observation;
 }
-function creationAttributes(options) {
-  const attributes = { ...kindAttributes(options.kind ?? "CHAIN" /* CHAIN */), ...options.attributes };
+function creationAttributes(name, options) {
+  const attributes = {
+    ...kindAttributes(options.kind ?? "CHAIN" /* CHAIN */, name),
+    ...options.attributes
+  };
   if (options.userId !== void 0) attributes[USER_ID] = options.userId;
   return attributes;
 }
 function startSpan(name, options = {}) {
   const span = getTracer().startSpan(name, {
-    kind: options.otelKind,
-    attributes: creationAttributes(options)
+    kind: options.otelKind ?? otelSpanKind(options.kind ?? "CHAIN" /* CHAIN */),
+    attributes: creationAttributes(name, options)
   });
   return configure(new Observation(span), options);
 }
@@ -626,11 +647,11 @@ function startAsCurrentSpan(name, optionsOrFn, maybeFn) {
   const [options, fn] = typeof optionsOrFn === "function" ? [{}, optionsOrFn] : [optionsOrFn, maybeFn];
   return runActive(
     name,
-    creationAttributes(options),
+    creationAttributes(name, options),
     options.userId,
     (span) => configure(new Observation(span), options),
     fn,
-    options.otelKind
+    options.otelKind ?? otelSpanKind(options.kind ?? "CHAIN" /* CHAIN */)
   );
 }
 function runActive(name, attributes, userId, makeHandle, fn, otelKind) {
@@ -647,12 +668,12 @@ function runActive(name, attributes, userId, makeHandle, fn, otelKind) {
   });
   return userId !== void 0 ? withUser(userId, run) : run();
 }
-var import_api2, Observation;
+var import_api3, Observation;
 var init_spans = __esm({
   "src/spans.ts"() {
     "use strict";
     init_cjs_shims();
-    import_api2 = require("@opentelemetry/api");
+    import_api3 = require("@opentelemetry/api");
     init_client();
     init_semconv();
     init_serde();
@@ -696,9 +717,15 @@ var init_spans = __esm({
         return this;
       }
       /**
-       * Record an error on the span and set ERROR status. This is exactly what the
-       * `startAsCurrent*` helpers do on a thrown error, exposed so the manual
-       * `start*` path does not have to reach through `.span` to match it.
+       * Record an error on the span, set ERROR status and `error.type`. This is
+       * exactly what the `startAsCurrent*` helpers do on a thrown error, exposed
+       * so the manual `start*` path does not have to reach through `.span` to
+       * match it.
+       *
+       * `error.type` is Conditionally Required by the GenAI conventions on every
+       * span that ends in an error, and every helper's throw path funnels through
+       * here, so this is the one place that sets it. The error's name only, never
+       * the message: it must stay low-cardinality and free of echoed content.
        *
        * Accepts `unknown` because that is what a `catch` binding is; a non-Error
        * throwable is wrapped so `recordException` still gets a real Error.
@@ -706,7 +733,8 @@ var init_spans = __esm({
       recordException(error) {
         const wrapped = error instanceof Error ? error : new Error(String(error));
         this.span.recordException(wrapped);
-        this.span.setStatus({ code: import_api2.SpanStatusCode.ERROR, message: wrapped.message });
+        this.span.setStatus({ code: import_api3.SpanStatusCode.ERROR, message: wrapped.message });
+        this.span.setAttribute(ERROR_TYPE, errorType(error));
         return this;
       }
       end() {
@@ -754,15 +782,12 @@ function recordResult(observation, result) {
   observation.setAttribute(OUTPUT_VALUE, serializeResult(result));
   if (resultIsError(result)) {
     observation.span.setStatus({
-      code: import_api3.SpanStatusCode.ERROR,
+      code: import_api4.SpanStatusCode.ERROR,
       message: "tool returned an error result"
     });
     observation.setAttribute(ERROR_TYPE, ERROR_TYPE_TOOL_ERROR);
   }
 }
-function errorType(error) {
-  return error instanceof Error ? error.name : typeof error;
-}
 function negotiatedProtocolVersion(client) {
   const version = asRecord(asRecord(client)?.transport)?.protocolVersion;
   return typeof version === "string" ? version : void 0;
@@ -792,18 +817,12 @@ function instrumentMcpClient(ClientClass) {
         // The OTel SpanKind FIELD (orthogonal to our taxonomy attribute above):
         // a remote tool call is CLIENT under both the MCP and the GenAI
         // execute-tool conventions.
-        otelKind: import_api3.SpanKind.CLIENT,
+        otelKind: import_api4.SpanKind.CLIENT,
         input: params.arguments,
         attributes: callAttributes(params.name, negotiatedProtocolVersion(this))
       },
       async (observation) => {
-        let result;
-        try {
-          result = await original.call(this, params, ...rest);
-        } catch (error) {
-          observation.setAttribute(ERROR_TYPE, errorType(error));
-          throw error;
-        }
+        const result = await original.call(this, params, ...rest);
         recordResult(observation, result);
         return result;
       }
@@ -815,12 +834,12 @@ function instrumentMcpClient(ClientClass) {
     ClientClass.prototype.callTool = original;
   };
 }
-var import_api3, INPUT_REQUIRED;
+var import_api4, INPUT_REQUIRED;
 var init_instrumentationMcp = __esm({
   "src/instrumentationMcp.ts"() {
     "use strict";
     init_cjs_shims();
-    import_api3 = require("@opentelemetry/api");
+    import_api4 = require("@opentelemetry/api");
     init_semconv();
     init_serde();
     init_spans();
@@ -1094,12 +1113,12 @@ function redactInvocationParameters(value) {
   for (const member of INVOCATION_PARAMETERS_CONTENT_MEMBERS) delete bag[member];
   return JSON.stringify(bag);
 }
-var import_api4, METADATA_PREFIX, EXCEPTION_EVENT_NAME, EXCEPTION_CONTENT_KEYS, STATUS_DESCRIPTION_KEY, MaskingSpanExporter;
+var import_api5, METADATA_PREFIX, EXCEPTION_EVENT_NAME, EXCEPTION_CONTENT_KEYS, STATUS_DESCRIPTION_KEY, MaskingSpanExporter;
 var init_masking = __esm({
   "src/masking.ts"() {
     "use strict";
     init_cjs_shims();
-    import_api4 = require("@opentelemetry/api");
+    import_api5 = require("@opentelemetry/api");
     init_semconv();
     init_serde();
     METADATA_PREFIX = "metadata.";
@@ -1143,7 +1162,7 @@ var init_masking = __esm({
        */
       sanitizeStatus(span) {
         const status = span.status;
-        if (status?.code !== import_api4.SpanStatusCode.ERROR || !status.message) return;
+        if (status?.code !== import_api5.SpanStatusCode.ERROR || !status.message) return;
         if (!this.opts.captureContent) {
           status.message = void 0;
           return;
@@ -1213,7 +1232,7 @@ function buildSnapshot(span) {
     startTime: span.startTime,
     endTime: span.startTime,
     duration: [0, 0],
-    status: { code: import_api5.SpanStatusCode.UNSET },
+    status: { code: import_api6.SpanStatusCode.UNSET },
     attributes,
     links: [],
     events: [],
@@ -1228,12 +1247,12 @@ function buildSnapshot(span) {
 function spanKey(context2) {
   return `${context2.traceId}:${context2.spanId}`;
 }
-var import_api5, PendingSpanProcessor;
+var import_api6, PendingSpanProcessor;
 var init_pending = __esm({
   "src/pending.ts"() {
     "use strict";
     init_cjs_shims();
-    import_api5 = require("@opentelemetry/api");
+    import_api6 = require("@opentelemetry/api");
     init_semconv();
     PendingSpanProcessor = class {
       delegate;
@@ -1281,17 +1300,17 @@ var init_pending = __esm({
 // src/session.ts
 function withSession(sessionIdOrFn, maybeFn) {
   const [sessionId, fn] = typeof sessionIdOrFn === "function" ? [(0, import_node_crypto.randomUUID)(), sessionIdOrFn] : [sessionIdOrFn, maybeFn];
-  return import_api6.context.with(import_api6.context.active().setValue(SESSION_KEY, sessionId), () => fn(sessionId));
+  return import_api7.context.with(import_api7.context.active().setValue(SESSION_KEY, sessionId), () => fn(sessionId));
 }
-var import_node_crypto, import_api6, SESSION_KEY, SessionSpanProcessor;
+var import_node_crypto, import_api7, SESSION_KEY, SessionSpanProcessor;
 var init_session = __esm({
   "src/session.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_crypto = require("crypto");
-    import_api6 = require("@opentelemetry/api");
+    import_api7 = require("@opentelemetry/api");
     init_semconv();
-    SESSION_KEY = (0, import_api6.createContextKey)("rius-session-id");
+    SESSION_KEY = (0, import_api7.createContextKey)("rius-session-id");
     SessionSpanProcessor = class {
       constructor(defaultSessionId) {
         this.defaultSessionId = defaultSessionId;
@@ -1299,7 +1318,7 @@ var init_session = __esm({
       defaultSessionId;
       onStart(span, parentContext) {
         const value = parentContext.getValue(SESSION_KEY);
-        const parent = import_api6.trace.getSpan(parentContext);
+        const parent = import_api7.trace.getSpan(parentContext);
         const inherited = parent?.attributes?.[SESSION_ID];
         const sessionId = typeof value === "string" ? value : typeof inherited === "string" ? inherited : this.defaultSessionId;
         if (sessionId !== void 0) span.setAttribute(SESSION_ID, sessionId);
@@ -1317,7 +1336,7 @@ var init_session = __esm({
 // src/workspace.ts
 function withWorkspace(alias, fn) {
   if (!alias) throw new Error("workspace alias must be a non-empty string");
-  return import_api7.context.with(import_api7.context.active().setValue(WORKSPACE_KEY, alias), () => fn(alias));
+  return import_api8.context.with(import_api8.context.active().setValue(WORKSPACE_KEY, alias), () => fn(alias));
 }
 function setGlobalRouting(routing) {
   globalRouting = routing;
@@ -1330,20 +1349,20 @@ function registerWorkspace(alias, apiKey) {
   }
   globalRouting.register(alias, apiKey);
 }
-var import_api7, WORKSPACE_KEY, WorkspaceSpanProcessor, RoutingSpanExporter, globalRouting;
+var import_api8, WORKSPACE_KEY, WorkspaceSpanProcessor, RoutingSpanExporter, globalRouting;
 var init_workspace = __esm({
   "src/workspace.ts"() {
     "use strict";
     init_cjs_shims();
-    import_api7 = require("@opentelemetry/api");
+    import_api8 = require("@opentelemetry/api");
     init_esm();
     init_semconv();
-    WORKSPACE_KEY = (0, import_api7.createContextKey)("rius-workspace-alias");
+    WORKSPACE_KEY = (0, import_api8.createContextKey)("rius-workspace-alias");
     WorkspaceSpanProcessor = class {
       /** Straddles already warned about, as "parentAlias->alias"; one warning each, not one per span. */
       warnedStraddles = /* @__PURE__ */ new Set();
       onStart(span, parentContext) {
-        const parent = import_api7.trace.getSpan(parentContext);
+        const parent = import_api8.trace.getSpan(parentContext);
         const parentAlias = parent?.attributes?.[WORKSPACE_ROUTE];
         const scoped = parentContext.getValue(WORKSPACE_KEY);
         const alias = typeof scoped === "string" ? scoped : parentAlias;
@@ -1532,15 +1551,15 @@ function init(options = {}) {
   return globalClient;
 }
 function getTracer() {
-  return import_api8.trace.getTracer(TRACER_NAME, SDK_VERSION);
+  return import_api9.trace.getTracer(TRACER_NAME, SDK_VERSION);
 }
-var import_node_crypto2, import_api8, import_exporter_trace_otlp_proto, import_resources, import_sdk_trace_base, import_sdk_trace_node, import_semantic_conventions, sinks, heartbeats, createClient, RiusClient, globalClient;
+var import_node_crypto2, import_api9, import_exporter_trace_otlp_proto, import_resources, import_sdk_trace_base, import_sdk_trace_node, import_semantic_conventions, sinks, heartbeats, createClient, RiusClient, globalClient;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_crypto2 = require("crypto");
-    import_api8 = require("@opentelemetry/api");
+    import_api9 = require("@opentelemetry/api");
     import_exporter_trace_otlp_proto = require("@opentelemetry/exporter-trace-otlp-proto");
     import_resources = require("@opentelemetry/resources");
     import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
@@ -1611,9 +1630,9 @@ var init_client = __esm({
           if (globalClient === this) {
             globalClient = void 0;
             setGlobalRouting(void 0);
-            import_api8.trace.disable();
-            import_api8.context.disable();
-            import_api8.propagation.disable();
+            import_api9.trace.disable();
+            import_api9.context.disable();
+            import_api9.propagation.disable();
           }
         }
       }
@@ -1723,6 +1742,12 @@ var Generation = class extends Observation {
   }
   provider;
   firstTokenRecorded = false;
+  /**
+   * Monotonic clock at construction, which is span creation for both
+   * `startGeneration` and the scoped form. The API `Span` exposes no start
+   * time, so this is what `recordFirstToken` measures the first chunk against.
+   */
+  startedAt = performance.now();
   /**
    * Record the request messages (`gen_ai.input.messages`), normalised to the
    * GenAI `{role, parts}` shape like the Python SDK does: bare strings, OpenAI
@@ -1797,17 +1822,24 @@ var Generation = class extends Observation {
     return this;
   }
   /**
-   * The TTFT anchor: event time minus span start. Idempotent: only the
-   * first call records the event, so a streaming loop can call this
-   * unconditionally on every chunk without inflating the span. A no-op
-   * after the span has ended.
+   * Mark the arrival of the first streamed token. Records the
+   * `gen_ai.first_token` event (the timestamp the backend derives TTFT from)
+   * and, per the GenAI conventions, the derived
+   * `gen_ai.response.time_to_first_chunk` (seconds since span creation) plus
+   * `gen_ai.request.stream = true`: a first chunk arriving is what tells the
+   * SDK the request streamed. Idempotent: only the first call records, so a
+   * streaming loop can call this unconditionally on every chunk without
+   * inflating the span. A no-op after the span has ended.
    */
   recordFirstToken() {
     if (this.firstTokenRecorded || !this.span.isRecording()) {
       return this;
     }
+    const elapsedSeconds = Math.max(performance.now() - this.startedAt, 0) / 1e3;
     this.span.addEvent(GEN_AI_FIRST_TOKEN_EVENT);
     this.firstTokenRecorded = true;
+    this.span.setAttribute(GEN_AI_REQUEST_STREAM, true);
+    this.span.setAttribute(GEN_AI_RESPONSE_TIME_TO_FIRST_CHUNK, elapsedSeconds);
     return this;
   }
 };
@@ -1831,7 +1863,10 @@ function configure2(generation, options) {
   return generation;
 }
 function startGeneration(name, options = {}) {
-  const span = getTracer().startSpan(name, { attributes: attributesFor(options) });
+  const span = getTracer().startSpan(name, {
+    kind: otelSpanKind("LLM" /* LLM */),
+    attributes: attributesFor(options)
+  });
   return configure2(new Generation(span, options.provider), options);
 }
 function startAsCurrentGeneration(name, optionsOrFn, maybeFn) {
@@ -1841,7 +1876,8 @@ function startAsCurrentGeneration(name, optionsOrFn, maybeFn) {
     attributesFor(options),
     options.userId,
     (span) => configure2(new Generation(span, options.provider), options),
-    fn
+    fn,
+    otelSpanKind("LLM" /* LLM */)
   );
 }
 
@@ -1874,7 +1910,7 @@ init_session();
 init_user();
 init_spans();
 init_workspace();
-var VERSION = "0.7.0";
+var VERSION = "0.8.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Generation,

package/dist/index.d.cts

@@ -174,8 +174,8 @@ interface SpanOptions {
     /**
      * The OpenTelemetry `SpanKind` FIELD (INTERNAL, CLIENT, …), orthogonal to
      * `kind` above, which is our taxonomy attribute. Conventions set it per
-     * operation — a remote tool call is CLIENT — so it is opt-in here and left
-     * at the tracer's default (INTERNAL) otherwise.
+     * operation, so by default it is derived from `kind` (see `otelSpanKind`);
+     * set this to override, as the MCP wrapper does for a remote tool call.
      */
     otelKind?: SpanKind$1;
     input?: unknown;
@@ -210,9 +210,15 @@ declare class Observation {
      */
     setAttribute(key: string, value: unknown): this;
     /**
-     * Record an error on the span and set ERROR status. This is exactly what the
-     * `startAsCurrent*` helpers do on a thrown error, exposed so the manual
-     * `start*` path does not have to reach through `.span` to match it.
+     * Record an error on the span, set ERROR status and `error.type`. This is
+     * exactly what the `startAsCurrent*` helpers do on a thrown error, exposed
+     * so the manual `start*` path does not have to reach through `.span` to
+     * match it.
+     *
+     * `error.type` is Conditionally Required by the GenAI conventions on every
+     * span that ends in an error, and every helper's throw path funnels through
+     * here, so this is the one place that sets it. The error's name only, never
+     * the message: it must stay low-cardinality and free of echoed content.
      *
      * Accepts `unknown` because that is what a `catch` binding is; a non-Error
      * throwable is wrapped so `recordException` still gets a real Error.
@@ -282,6 +288,12 @@ interface GenerationOptions {
 declare class Generation extends Observation {
     private readonly provider?;
     private firstTokenRecorded;
+    /**
+     * Monotonic clock at construction, which is span creation for both
+     * `startGeneration` and the scoped form. The API `Span` exposes no start
+     * time, so this is what `recordFirstToken` measures the first chunk against.
+     */
+    private readonly startedAt;
     /**
      * The provider passed at creation; drives the Anthropic input-token summing
      * in {@link setUsage}. A bare `new Generation(span)` has none and never sums.
@@ -341,10 +353,14 @@ declare class Generation extends Observation {
      */
     setFinishReasons(reasons: string | string[]): this;
     /**
-     * The TTFT anchor: event time minus span start. Idempotent: only the
-     * first call records the event, so a streaming loop can call this
-     * unconditionally on every chunk without inflating the span. A no-op
-     * after the span has ended.
+     * Mark the arrival of the first streamed token. Records the
+     * `gen_ai.first_token` event (the timestamp the backend derives TTFT from)
+     * and, per the GenAI conventions, the derived
+     * `gen_ai.response.time_to_first_chunk` (seconds since span creation) plus
+     * `gen_ai.request.stream = true`: a first chunk arriving is what tells the
+     * SDK the request streamed. Idempotent: only the first call records, so a
+     * streaming loop can call this unconditionally on every chunk without
+     * inflating the span. A no-op after the span has ended.
      */
     recordFirstToken(): this;
 }
@@ -448,6 +464,6 @@ declare function withSession<T>(sessionId: string, fn: (sessionId: string) => T)
  */
 declare function withUser<T>(userId: string, fn: (userId: string) => T): T;
 
-declare const VERSION = "0.7.0";
+declare const VERSION = "0.8.0";
 
 export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, type WorkspaceExporterFactory, getTracer, init, observe, registerWorkspace, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan, withSession, withUser, withWorkspace };

package/dist/index.d.ts

@@ -174,8 +174,8 @@ interface SpanOptions {
     /**
      * The OpenTelemetry `SpanKind` FIELD (INTERNAL, CLIENT, …), orthogonal to
      * `kind` above, which is our taxonomy attribute. Conventions set it per
-     * operation — a remote tool call is CLIENT — so it is opt-in here and left
-     * at the tracer's default (INTERNAL) otherwise.
+     * operation, so by default it is derived from `kind` (see `otelSpanKind`);
+     * set this to override, as the MCP wrapper does for a remote tool call.
      */
     otelKind?: SpanKind$1;
     input?: unknown;
@@ -210,9 +210,15 @@ declare class Observation {
      */
     setAttribute(key: string, value: unknown): this;
     /**
-     * Record an error on the span and set ERROR status. This is exactly what the
-     * `startAsCurrent*` helpers do on a thrown error, exposed so the manual
-     * `start*` path does not have to reach through `.span` to match it.
+     * Record an error on the span, set ERROR status and `error.type`. This is
+     * exactly what the `startAsCurrent*` helpers do on a thrown error, exposed
+     * so the manual `start*` path does not have to reach through `.span` to
+     * match it.
+     *
+     * `error.type` is Conditionally Required by the GenAI conventions on every
+     * span that ends in an error, and every helper's throw path funnels through
+     * here, so this is the one place that sets it. The error's name only, never
+     * the message: it must stay low-cardinality and free of echoed content.
      *
      * Accepts `unknown` because that is what a `catch` binding is; a non-Error
      * throwable is wrapped so `recordException` still gets a real Error.
@@ -282,6 +288,12 @@ interface GenerationOptions {
 declare class Generation extends Observation {
     private readonly provider?;
     private firstTokenRecorded;
+    /**
+     * Monotonic clock at construction, which is span creation for both
+     * `startGeneration` and the scoped form. The API `Span` exposes no start
+     * time, so this is what `recordFirstToken` measures the first chunk against.
+     */
+    private readonly startedAt;
     /**
      * The provider passed at creation; drives the Anthropic input-token summing
      * in {@link setUsage}. A bare `new Generation(span)` has none and never sums.
@@ -341,10 +353,14 @@ declare class Generation extends Observation {
      */
     setFinishReasons(reasons: string | string[]): this;
     /**
-     * The TTFT anchor: event time minus span start. Idempotent: only the
-     * first call records the event, so a streaming loop can call this
-     * unconditionally on every chunk without inflating the span. A no-op
-     * after the span has ended.
+     * Mark the arrival of the first streamed token. Records the
+     * `gen_ai.first_token` event (the timestamp the backend derives TTFT from)
+     * and, per the GenAI conventions, the derived
+     * `gen_ai.response.time_to_first_chunk` (seconds since span creation) plus
+     * `gen_ai.request.stream = true`: a first chunk arriving is what tells the
+     * SDK the request streamed. Idempotent: only the first call records, so a
+     * streaming loop can call this unconditionally on every chunk without
+     * inflating the span. A no-op after the span has ended.
      */
     recordFirstToken(): this;
 }
@@ -448,6 +464,6 @@ declare function withSession<T>(sessionId: string, fn: (sessionId: string) => T)
  */
 declare function withUser<T>(userId: string, fn: (userId: string) => T): T;
 
-declare const VERSION = "0.7.0";
+declare const VERSION = "0.8.0";
 
 export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, type WorkspaceExporterFactory, getTracer, init, observe, registerWorkspace, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan, withSession, withUser, withWorkspace };

package/dist/index.js

@@ -354,13 +354,18 @@ var init_heartbeat = __esm({
 });
 
 // src/semconv.ts
-function kindAttributes(kind) {
+import { SpanKind as OtelSpanKind } from "@opentelemetry/api";
+function otelSpanKind(kind) {
+  return OTEL_KIND_BY_KIND[kind];
+}
+function kindAttributes(kind, name) {
   const attributes = { [OPENINFERENCE_SPAN_KIND]: kind };
   const operation = OPERATION_BY_KIND[kind];
   if (operation !== void 0) attributes[GEN_AI_OPERATION_NAME] = operation;
+  if (kind === "TOOL" /* TOOL */ && name !== void 0) attributes[GEN_AI_TOOL_NAME] = name;
   return attributes;
 }
-var TRACER_NAME, SERVICE_INSTANCE_ID, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, SESSION_ID, USER_ID, WORKSPACE_ROUTE, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_REQUEST_REASONING_LEVEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS, GEN_AI_USAGE_REASONING_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_TOOL_DEFINITIONS, GEN_AI_REQUEST_PREFIX, MCP_METHOD_NAME, MCP_METHOD_TOOLS_CALL, MCP_PROTOCOL_VERSION, ERROR_TYPE, ERROR_TYPE_TOOL_ERROR, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, CONTENT_ATTRIBUTES, LLM_INVOCATION_PARAMETERS, INVOCATION_PARAMETERS_CONTENT_MEMBERS, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
+var TRACER_NAME, SERVICE_INSTANCE_ID, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, SESSION_ID, USER_ID, WORKSPACE_ROUTE, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_REQUEST_REASONING_LEVEL, GEN_AI_RESPONSE_MODEL, GEN_AI_REQUEST_STREAM, GEN_AI_RESPONSE_TIME_TO_FIRST_CHUNK, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS, GEN_AI_USAGE_REASONING_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_TOOL_DEFINITIONS, GEN_AI_REQUEST_PREFIX, MCP_METHOD_NAME, MCP_METHOD_TOOLS_CALL, MCP_PROTOCOL_VERSION, ERROR_TYPE, ERROR_TYPE_TOOL_ERROR, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, OTEL_KIND_BY_KIND, CONTENT_ATTRIBUTES, LLM_INVOCATION_PARAMETERS, INVOCATION_PARAMETERS_CONTENT_MEMBERS, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
 var init_semconv = __esm({
   "src/semconv.ts"() {
     "use strict";
@@ -378,6 +383,8 @@ var init_semconv = __esm({
     GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
     GEN_AI_REQUEST_REASONING_LEVEL = "gen_ai.request.reasoning.level";
     GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
+    GEN_AI_REQUEST_STREAM = "gen_ai.request.stream";
+    GEN_AI_RESPONSE_TIME_TO_FIRST_CHUNK = "gen_ai.response.time_to_first_chunk";
     GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
     GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
     GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens";
@@ -411,6 +418,14 @@ var init_semconv = __esm({
       ["EMBEDDING" /* EMBEDDING */]: "embeddings",
       ["AGENT" /* AGENT */]: "invoke_agent"
     };
+    OTEL_KIND_BY_KIND = {
+      ["LLM" /* LLM */]: OtelSpanKind.CLIENT,
+      ["EMBEDDING" /* EMBEDDING */]: OtelSpanKind.CLIENT,
+      ["RETRIEVER" /* RETRIEVER */]: OtelSpanKind.CLIENT,
+      ["TOOL" /* TOOL */]: OtelSpanKind.INTERNAL,
+      ["AGENT" /* AGENT */]: OtelSpanKind.INTERNAL,
+      ["CHAIN" /* CHAIN */]: OtelSpanKind.INTERNAL
+    };
     CONTENT_ATTRIBUTES = /* @__PURE__ */ new Set([
       INPUT_VALUE,
       OUTPUT_VALUE,
@@ -555,6 +570,9 @@ function toAttributeValue(value) {
     return "[unserializable]";
   }
 }
+function errorType(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
 var MAX_ATTR_CHARS, TRUNCATION_MARKER;
 var init_serde = __esm({
   "src/serde.ts"() {
@@ -598,15 +616,18 @@ function configure(observation, options) {
   if (options.input !== void 0) observation.setInput(options.input);
   return observation;
 }
-function creationAttributes(options) {
-  const attributes = { ...kindAttributes(options.kind ?? "CHAIN" /* CHAIN */), ...options.attributes };
+function creationAttributes(name, options) {
+  const attributes = {
+    ...kindAttributes(options.kind ?? "CHAIN" /* CHAIN */, name),
+    ...options.attributes
+  };
   if (options.userId !== void 0) attributes[USER_ID] = options.userId;
   return attributes;
 }
 function startSpan(name, options = {}) {
   const span = getTracer().startSpan(name, {
-    kind: options.otelKind,
-    attributes: creationAttributes(options)
+    kind: options.otelKind ?? otelSpanKind(options.kind ?? "CHAIN" /* CHAIN */),
+    attributes: creationAttributes(name, options)
   });
   return configure(new Observation(span), options);
 }
@@ -614,11 +635,11 @@ function startAsCurrentSpan(name, optionsOrFn, maybeFn) {
   const [options, fn] = typeof optionsOrFn === "function" ? [{}, optionsOrFn] : [optionsOrFn, maybeFn];
   return runActive(
     name,
-    creationAttributes(options),
+    creationAttributes(name, options),
     options.userId,
     (span) => configure(new Observation(span), options),
     fn,
-    options.otelKind
+    options.otelKind ?? otelSpanKind(options.kind ?? "CHAIN" /* CHAIN */)
   );
 }
 function runActive(name, attributes, userId, makeHandle, fn, otelKind) {
@@ -683,9 +704,15 @@ var init_spans = __esm({
         return this;
       }
       /**
-       * Record an error on the span and set ERROR status. This is exactly what the
-       * `startAsCurrent*` helpers do on a thrown error, exposed so the manual
-       * `start*` path does not have to reach through `.span` to match it.
+       * Record an error on the span, set ERROR status and `error.type`. This is
+       * exactly what the `startAsCurrent*` helpers do on a thrown error, exposed
+       * so the manual `start*` path does not have to reach through `.span` to
+       * match it.
+       *
+       * `error.type` is Conditionally Required by the GenAI conventions on every
+       * span that ends in an error, and every helper's throw path funnels through
+       * here, so this is the one place that sets it. The error's name only, never
+       * the message: it must stay low-cardinality and free of echoed content.
        *
        * Accepts `unknown` because that is what a `catch` binding is; a non-Error
        * throwable is wrapped so `recordException` still gets a real Error.
@@ -694,6 +721,7 @@ var init_spans = __esm({
         const wrapped = error instanceof Error ? error : new Error(String(error));
         this.span.recordException(wrapped);
         this.span.setStatus({ code: SpanStatusCode.ERROR, message: wrapped.message });
+        this.span.setAttribute(ERROR_TYPE, errorType(error));
         return this;
       }
       end() {
@@ -714,7 +742,7 @@ var instrumentationMcp_exports = {};
 __export(instrumentationMcp_exports, {
   instrumentMcpClient: () => instrumentMcpClient
 });
-import { SpanKind as OtelSpanKind, SpanStatusCode as SpanStatusCode2 } from "@opentelemetry/api";
+import { SpanKind as OtelSpanKind2, SpanStatusCode as SpanStatusCode2 } from "@opentelemetry/api";
 function serializeResult(result) {
   const record = asRecord(result);
   if (record === void 0) return toAttributeValue(result);
@@ -748,9 +776,6 @@ function recordResult(observation, result) {
     observation.setAttribute(ERROR_TYPE, ERROR_TYPE_TOOL_ERROR);
   }
 }
-function errorType(error) {
-  return error instanceof Error ? error.name : typeof error;
-}
 function negotiatedProtocolVersion(client) {
   const version = asRecord(asRecord(client)?.transport)?.protocolVersion;
   return typeof version === "string" ? version : void 0;
@@ -780,18 +805,12 @@ function instrumentMcpClient(ClientClass) {
         // The OTel SpanKind FIELD (orthogonal to our taxonomy attribute above):
         // a remote tool call is CLIENT under both the MCP and the GenAI
         // execute-tool conventions.
-        otelKind: OtelSpanKind.CLIENT,
+        otelKind: OtelSpanKind2.CLIENT,
         input: params.arguments,
         attributes: callAttributes(params.name, negotiatedProtocolVersion(this))
       },
       async (observation) => {
-        let result;
-        try {
-          result = await original.call(this, params, ...rest);
-        } catch (error) {
-          observation.setAttribute(ERROR_TYPE, errorType(error));
-          throw error;
-        }
+        const result = await original.call(this, params, ...rest);
         recordResult(observation, result);
         return result;
       }
@@ -1694,6 +1713,12 @@ var Generation = class extends Observation {
   }
   provider;
   firstTokenRecorded = false;
+  /**
+   * Monotonic clock at construction, which is span creation for both
+   * `startGeneration` and the scoped form. The API `Span` exposes no start
+   * time, so this is what `recordFirstToken` measures the first chunk against.
+   */
+  startedAt = performance.now();
   /**
    * Record the request messages (`gen_ai.input.messages`), normalised to the
    * GenAI `{role, parts}` shape like the Python SDK does: bare strings, OpenAI
@@ -1768,17 +1793,24 @@ var Generation = class extends Observation {
     return this;
   }
   /**
-   * The TTFT anchor: event time minus span start. Idempotent: only the
-   * first call records the event, so a streaming loop can call this
-   * unconditionally on every chunk without inflating the span. A no-op
-   * after the span has ended.
+   * Mark the arrival of the first streamed token. Records the
+   * `gen_ai.first_token` event (the timestamp the backend derives TTFT from)
+   * and, per the GenAI conventions, the derived
+   * `gen_ai.response.time_to_first_chunk` (seconds since span creation) plus
+   * `gen_ai.request.stream = true`: a first chunk arriving is what tells the
+   * SDK the request streamed. Idempotent: only the first call records, so a
+   * streaming loop can call this unconditionally on every chunk without
+   * inflating the span. A no-op after the span has ended.
    */
   recordFirstToken() {
     if (this.firstTokenRecorded || !this.span.isRecording()) {
       return this;
     }
+    const elapsedSeconds = Math.max(performance.now() - this.startedAt, 0) / 1e3;
     this.span.addEvent(GEN_AI_FIRST_TOKEN_EVENT);
     this.firstTokenRecorded = true;
+    this.span.setAttribute(GEN_AI_REQUEST_STREAM, true);
+    this.span.setAttribute(GEN_AI_RESPONSE_TIME_TO_FIRST_CHUNK, elapsedSeconds);
     return this;
   }
 };
@@ -1802,7 +1834,10 @@ function configure2(generation, options) {
   return generation;
 }
 function startGeneration(name, options = {}) {
-  const span = getTracer().startSpan(name, { attributes: attributesFor(options) });
+  const span = getTracer().startSpan(name, {
+    kind: otelSpanKind("LLM" /* LLM */),
+    attributes: attributesFor(options)
+  });
   return configure2(new Generation(span, options.provider), options);
 }
 function startAsCurrentGeneration(name, optionsOrFn, maybeFn) {
@@ -1812,7 +1847,8 @@ function startAsCurrentGeneration(name, optionsOrFn, maybeFn) {
     attributesFor(options),
     options.userId,
     (span) => configure2(new Generation(span, options.provider), options),
-    fn
+    fn,
+    otelSpanKind("LLM" /* LLM */)
   );
 }
 
@@ -1845,7 +1881,7 @@ init_session();
 init_user();
 init_spans();
 init_workspace();
-var VERSION = "0.7.0";
+var VERSION = "0.8.0";
 export {
   Generation,
   Observation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glassflow-ai/rius",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "OpenTelemetry-native tracing for AI agents and LLM applications",
   "keywords": [
     "opentelemetry",