basalt-ui 2.4.0 → 2.5.0

package/src/telemetry.ts

@@ -65,7 +65,61 @@ export type BasaltEvent =
   | Ok<'chat.turn', ChatAttrs>
   | Err<'chat.turn', ChatAttrs, Span>
 
-export type Telemetry = (event: BasaltEvent) => void
+/** W3C trace-context request headers a sink contributes to one chat turn's request. */
+export type TraceHeaders = {
+  readonly traceparent: string
+  readonly tracestate?: string | undefined
+}
+
+/**
+ * How a traced chat turn ended: its `chat.turn` event fired (`settled`/`failed`), or `stopped` — a
+ * `stop()`, an unmount or a newer run taking the thread over — which emits no event. The one
+ * lifecycle vocabulary of the run records too.
+ */
+export type ChatTurnEnd = 'settled' | 'failed' | 'stopped'
+
+/** The turn a sink is asked to trace. */
+type ChatTurnInit = { readonly threadId: string; readonly messageId: string }
+
+/**
+ * What a sink returns from `startChatTurn`. `settle` runs once, synchronously, right after the
+ * turn's `chat.turn` event (`settled`/`failed`), or when the turn is cut short (`stopped`) — the
+ * point to end a span opened in `startChatTurn`. It runs even when `headers` is absent or
+ * malformed (dropped, the request goes out untraced), so the span never leaks.
+ */
+export type ChatTurnTrace = {
+  readonly headers?: TraceHeaders | undefined
+  readonly settle?: ((end: ChatTurnEnd) => void) | undefined
+}
+
+/**
+ * The event sink. It may carry one optional hook, `startChatTurn`, called when a new chat turn
+ * begins (not on a resume): open your span there and return its `traceparent` (and `tracestate`)
+ * and `aiSdkTransport` sends them with that turn's request to the chat endpoint — never anywhere
+ * else. A sink without the hook, or no sink, changes nothing on the wire. basalt has no OTel
+ * dependency; the hook is where the consumer's SDK does the work.
+ *
+ * @example
+ * export const telemetry: Telemetry = Object.assign(onEvent, {
+ *   startChatTurn({ threadId }) {
+ *     const span = tracer.startSpan('chat.turn', {
+ *       attributes: { 'basalt.chat.thread_id': threadId },
+ *     })
+ *     const carrier: Record<string, string> = {}
+ *     propagation.inject(trace.setSpan(context.active(), span), carrier)
+ *     return {
+ *       headers: { traceparent: carrier.traceparent ?? '', tracestate: carrier.tracestate },
+ *       settle(end) {
+ *         if (end === 'failed') span.setStatus({ code: SpanStatusCode.ERROR })
+ *         span.end()
+ *       },
+ *     }
+ *   },
+ * })
+ */
+export type Telemetry = ((event: BasaltEvent) => void) & {
+  readonly startChatTurn?: ((turn: ChatTurnInit) => ChatTurnTrace | undefined) | undefined
+}
 
 export const now = (): number => performance.timeOrigin + performance.now()
 
@@ -73,18 +127,27 @@ export const now = (): number => performance.timeOrigin + performance.now()
 export const errorName = (error: unknown): string => (error instanceof Error ? error.name : 'Error')
 
 /**
- * Wrap a sink so it is called synchronously and a throwing sink never breaks a render. No sink, no
- * events.
+ * The wrapped emitter over a sink read at call time (a ref), so a swapped sink is never stale. It is
+ * called synchronously and a throwing sink never breaks a render; no sink, no events. Its
+ * `startChatTurn` forwards the sink's hook; the hook's consumer validates the headers.
  */
-export function createEmitter(sink: Telemetry | undefined): Telemetry {
-  if (sink === undefined) return noop
-  return (event) => {
+export function createLiveEmitter(read: () => Telemetry | undefined): Telemetry {
+  const emit = (event: BasaltEvent): void => {
     try {
-      sink(event)
+      read()?.(event)
     } catch {
       // a throwing sink must never break the app (§ 7 delivery rules)
     }
   }
+  return Object.assign(emit, {
+    startChatTurn(turn: ChatTurnInit): ChatTurnTrace | undefined {
+      try {
+        return read()?.startChatTurn?.(turn)
+      } catch {
+        return undefined
+      }
+    },
+  })
 }
 
 function noop(): void {}