@combycode/llm-sdk 2.1.0 → 2.2.0

package/dist/network/types.d.ts

@@ -69,6 +69,12 @@ export interface TraceContext {
     sessionId?: string;
     requestId?: string;
     callId?: string;
+    /** W3C `traceparent` of the span this work runs UNDER, when the caller runs the SDK
+     *  inside its own trace. It rides with the ids because every span we emit needs it,
+     *  not only the ones built straight from a caller's RequestContext — an agent run
+     *  reaches its tool calls and its nested agents through this object, and those were
+     *  left rooting traces of their own while the LLM spans joined the caller's. */
+    traceparent?: string;
 }
 /** Point-in-time numeric state of one queue (for metrics / observability). */
 export interface QueueSnapshot {

package/dist/plugins/telemetry/telemetry.d.ts

@@ -11,10 +11,29 @@
  *  into OTLP-compatible JSON for a real OTel exporter to forward. */
 import type { HookBus } from '../../bus/hook-bus';
 import type { HookName } from '../../bus/hook-map';
+/** Derive a conformant hex id from one of our readable ids. `bytes` is 16 for a trace
+ *  id, 8 for a span id.
+ *
+ *  Deterministic on purpose: the same logical trace maps to the same OTLP id on every
+ *  export and in every process, so a trace stitched together from two exports — or
+ *  from two services sharing a sessionId — still joins up in the backend. */
+export declare function toOtlpId(input: string, bytes: 8 | 16): string;
+/** One attribute in OTLP's AnyValue shape, keeping numbers numeric. Integers go out as
+ *  `intValue` carrying a STRING, which is how OTLP/JSON encodes 64-bit integers; send
+ *  them as plain strings instead and no backend can sum them. */
+export declare function toOtlpValue(value: unknown): Record<string, unknown>;
 export type SpanKind = 'llm' | 'http' | 'media' | 'agent' | 'tool' | 'mcp' | 'other';
 export interface Span {
     traceId: string;
     spanId: string;
+    /** The span this one runs under. Without it every span is a sibling and a backend
+     *  draws a flat list instead of a tree — so a run reads as "9 things happened", not
+     *  "a turn, which called a tool, which asked a second model".
+     *
+     *  Resolved in this order: the innermost container span still open on this trace
+     *  (`agent.run` / `tool.call`), else the app's span from a supplied `traceparent`,
+     *  else none — this span is the root. */
+    parentSpanId?: string;
     name: string;
     kind: SpanKind;
     startTime: number;
@@ -23,6 +42,34 @@ export interface Span {
     status: 'unset' | 'ok' | 'error';
     attributes: Record<string, unknown>;
 }
+/** What kind of work an event describes. `message` is conversation content, which is not
+ *  a span — it is the thing you want in a debug store and NOT in your metrics backend,
+ *  which is exactly why it filters separately. */
+export type TraceEventType = 'agent' | 'tool' | 'llm' | 'http' | 'mcp' | 'media' | 'message' | 'other';
+/** One piece of work, carrying enough of the tree that a consumer can push it straight
+ *  into their own tracer without reconstructing anything. */
+export interface TraceEvent {
+    type: TraceEventType;
+    /** The app's trace when it supplied a `traceparent`, else ours. */
+    traceId: string;
+    spanId: string;
+    /** Already resolved past anything this subscriber filtered out — see `survivingParent`. */
+    parentSpanId?: string;
+    /** The conventional name (`chat gpt-5.4-nano`, `execute_tool search`). */
+    name: string;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: 'unset' | 'ok' | 'error';
+    attributes: Record<string, unknown>;
+}
+/** Declarative on purpose, rather than a predicate: knowing the types up front lets a
+ *  filtered-out event cost nothing, where a predicate would force us to build the payload
+ *  just to let the caller throw it away. */
+export interface TraceFilter {
+    types?: readonly TraceEventType[];
+}
+export type TraceHandler = (event: TraceEvent) => void;
 export interface TelemetryEvent {
     seq: number;
     time: number;
@@ -50,6 +97,13 @@ export interface TelemetryMetrics {
         avg: number;
     };
 }
+/** Parse a W3C `traceparent`: `00-<32 hex trace>-<16 hex span>-<flags>`.
+ *  Returns null for anything malformed or for the all-zero ids the spec forbids —
+ *  a bad header must not silently reroute telemetry into a garbage trace. */
+export declare function parseTraceparent(value: string | undefined): {
+    traceId: string;
+    spanId: string;
+} | null;
 /** OpenTelemetry Resource — identifies the SERVICE producing this telemetry, so
  *  a shared backend can separate streams from different apps and attribute cost
  *  per service (`sum by service.name`). Stamped on every span/metric/log. */
@@ -80,6 +134,32 @@ export interface TelemetryAdapterOptions {
      *  boundary (a shared collector, a vendor APM) and the message is replaced by a
      *  fixed `[redacted]` string while name/code/status are kept for triage. */
     includeSensitiveData?: boolean;
+    /** Which event types to hand to `onTrace`. Omitted → everything.
+     *
+     *  Filtering SPLICES the tree rather than punching holes in it: drop `http` and the
+     *  spans under it re-parent to the nearest surviving ancestor. Dropping without that
+     *  leaves orphans, and a backend draws an orphan as a second root — worse than not
+     *  filtering at all. */
+    types?: readonly TraceEventType[];
+    /** Whether conversation content rides along on `message` events. Default `'none'`:
+     *  prompts and completions are the debugging gold AND the PII, so sending them is a
+     *  decision to make on purpose rather than inherit. `'full'` adds the Opt-In
+     *  `gen_ai.input.messages` / `gen_ai.output.messages` attributes; `'none'` still
+     *  reports the shape (counts and sizes), which is enough to spot a runaway prompt. */
+    content?: 'none' | 'full';
+    /** Fraction of TRACES to emit, 0..1. Default 1.
+     *
+     *  Per trace, never per span: sampling spans independently shreds every tree it touches
+     *  — a tool call with no run, a model call with no tool. The decision is a hash of the
+     *  trace id, so it is stable across processes and two services sharing a trace agree
+     *  without coordinating.
+     *
+     *  This is HEAD sampling: the choice is made when the trace first appears, before we
+     *  know whether it ends in an error. Keeping all errors needs tail sampling, which
+     *  needs buffering; do that in your collector, which is built for it. */
+    sample?: number;
+    /** Convenience for the common case of a single sink — same as calling `onTrace`. */
+    onTrace?: TraceHandler;
 }
 export declare class TelemetryAdapter {
     readonly events: TelemetryEvent[];
@@ -88,15 +168,79 @@ export declare class TelemetryAdapter {
     /** Service identity stamped on exported telemetry. */
     readonly resource: TelemetryResource;
     private seq;
+    /** Discriminator for POINT spans (media, mcp connect/tool), whose natural keys are
+     *  not unique — the same server reconnects, a run emits two images, two tool calls
+     *  land in one millisecond. A duplicate span id inside a trace is invalid OTLP and
+     *  the backend silently keeps only one. */
+    private spanSeq;
+    /** Per trace: the app's span from a `traceparent`, and the CONTAINER spans currently
+     *  open on it. Together they decide what a new span hangs under — see `parentFor`.
+     *  Both are cleared once a trace has nothing open, so a long-lived process does not
+     *  accumulate an entry per conversation forever.
+     *
+     *  A list, not a single slot: an agent nested in a tool call (C2 inside C1's tool) is a
+     *  second run on the SAME trace, and with one slot it overwrote its own parent and then
+     *  deleted it on close — leaving the rest of the outer run parentless. */
+    private appParent;
+    private containers;
     private latSum;
     private readonly open;
     private readonly maxEvents;
     private readonly includeSensitiveData;
     private readonly unsub;
+    /** Subscribers, each with its own filter. Re-parenting is computed PER SINK: two
+     *  consumers asking for different types each get a tree that is correct for them. */
+    private readonly sinks;
+    private readonly content;
+    private readonly sampleRate;
+    /** spanId → its parent and type, for EVERY span including filtered ones — walking up
+     *  past a dropped ancestor is the whole point, so the dropped ones must still be here.
+     *  Bounded, because a long-lived process would otherwise remember every span it ever
+     *  saw. */
+    private readonly lineage;
+    private readonly maxLineage;
+    private msgSeq;
     constructor(hooks: HookBus, opts?: TelemetryAdapterOptions);
+    /** Subscribe to the event stream. Returns an unsubscribe function.
+     *
+     *  ```ts
+     *  const stop = telemetry.onTrace({ types: ['agent', 'tool'] }, (e) => pipeline.push(e));
+     *  ```
+     */
+    onTrace(handler: TraceHandler): () => void;
+    onTrace(filter: TraceFilter, handler: TraceHandler): () => void;
+    /** Record a finished span and hand it to the subscribers. Every span reaches the store
+     *  through here, so there is one place where an event can be missed rather than five. */
+    private recordSpan;
+    private remember;
+    private dispatch;
+    /** The nearest ancestor this subscriber actually receives. Without this, filtering out
+     *  `http` would leave its children pointing at a span that never arrives, and a backend
+     *  renders a dangling parent as a separate root. */
+    private survivingParent;
+    /** Hashed rather than random, so the same trace samples the same way in every process
+     *  and a trace shared by two services is kept or dropped by both. */
+    private isSampled;
+    /** Conversation content, as its own event so it can be routed somewhere different from
+     *  the spans — a debug store, not the metrics backend. */
+    private emitMessage;
     /** Stop tapping the bus. */
     destroy(): void;
     private handle;
+    /** What a new span on this trace hangs under: the innermost container still open on
+     *  it, else the app's span, else nothing (we are the root).
+     *
+     *  A container wins over the app's span because an LLM call made during a run belongs
+     *  to that run — attaching it straight to the app would flatten the very nesting the
+     *  tree exists to show. A span joins the stack only after it is built, so nothing can
+     *  become its own parent, and a run nested in a tool call lands under that tool call —
+     *  exactly where it happened.
+     *
+     *  Limit worth naming: with tools running in parallel two `tool.call` spans are open at
+     *  once and "innermost" is merely the more recent one. Attributing a nested run to the
+     *  right sibling needs real async context propagation, which this adapter does not
+     *  have; sequential tools, the common case, are exact. */
+    private parentFor;
     private openSpan;
     private closeSpan;
     private recordLatency;

package/dist/types/request-context.d.ts

@@ -25,6 +25,17 @@ export interface RequestContext {
      *  server/agent set it, else the LLM client mints in buildContext). Follows
      *  the whole chain; the request half of the trace id. */
     requestId?: string;
+    /** W3C trace context of the span this work runs UNDER — `00-<32 hex trace>-<16 hex
+     *  span>-<flags>`, exactly the `traceparent` header shape.
+     *
+     *  Pass it and the SDK stops rooting its own trace: its spans join that trace and hang
+     *  under that span. Without it the library cannot know it is inside an application's
+     *  request, so the business chain and the model calls reach the backend as two
+     *  unrelated traces.
+     *
+     *  Sources: the inbound `traceparent` header, or an active span from an OTel SDK if
+     *  the app already runs one. */
+    traceparent?: string;
     /** = `history.id`. Stable for the lifetime of the conversation. */
     conversationId?: string;
     /** Unique per `.complete()` / `.stream()` call. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
   "type": "module",
   "main": "./dist/index.js",