@combycode/llm-sdk 2.1.0 → 2.2.0

package/dist/index.js

@@ -114,6 +114,86 @@ var REDACTED = "***REDACTED***";
 var SENSITIVE_QUERY_PARAMS = /* @__PURE__ */ new Set(["key", "api_key", "access_token", "token"]);
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set(["authorization", "x-goog-api-key", "x-api-key", "api-key"]);
 var MAX_ERROR_RAW_CHARS = 512;
+var OTLP_SPAN_KIND = { internal: 1, client: 3 };
+var OTLP_KIND_BY_SPAN = {
+  llm: OTLP_SPAN_KIND.client,
+  http: OTLP_SPAN_KIND.client,
+  mcp: OTLP_SPAN_KIND.client,
+  media: OTLP_SPAN_KIND.client,
+  agent: OTLP_SPAN_KIND.internal,
+  tool: OTLP_SPAN_KIND.internal,
+  other: OTLP_SPAN_KIND.internal
+};
+function fnv1a32(input, seed) {
+  let h = seed >>> 0;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h >>> 0;
+}
+var isHex = (value, chars) => value.length === chars && /^[0-9a-f]+$/.test(value);
+function toOtlpId(input, bytes) {
+  let out = "";
+  for (let i = 0; i < bytes / 4; i++) {
+    out += fnv1a32(input, 2166136261 + i * 2654435769 >>> 0).toString(16).padStart(8, "0");
+  }
+  return /^0+$/.test(out) ? `${out.slice(0, -1)}1` : out;
+}
+function toOtlpValue(value) {
+  if (typeof value === "boolean") return { boolValue: value };
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+  if (typeof value === "string") return { stringValue: value };
+  if (value === null || value === void 0) return { stringValue: "" };
+  return { stringValue: typeof value === "object" ? JSON.stringify(value) : String(value) };
+}
+var SPAN_NAME_SUBJECT = {
+  chat: "gen_ai.request.model",
+  invoke_agent: "gen_ai.agent.name",
+  execute_tool: "gen_ai.tool.name"
+};
+function otlpSpanName(span) {
+  const op = span.attributes["gen_ai.operation.name"];
+  if (typeof op !== "string") return span.name;
+  const subject = SPAN_NAME_SUBJECT[op] ? span.attributes[SPAN_NAME_SUBJECT[op]] : void 0;
+  return typeof subject === "string" && subject ? `${op} ${subject}` : op;
+}
+function toMessageList(payload, defaultRole) {
+  if (payload == null) return [];
+  if (typeof payload === "string") {
+    return payload ? [{ role: defaultRole, content: payload }] : [];
+  }
+  if (Array.isArray(payload)) {
+    const parts2 = payload;
+    if (parts2.length > 0 && parts2[0] && "role" in parts2[0]) {
+      return parts2.map((m) => ({ role: String(m.role ?? defaultRole), content: contentToText(m.content) })).filter((m) => m.content);
+    }
+    const text2 = contentToText(parts2);
+    return text2 ? [{ role: defaultRole, content: text2 }] : [];
+  }
+  const text = contentToText(payload);
+  return text ? [{ role: defaultRole, content: text }] : [];
+}
+function contentToText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => {
+    const p = part;
+    return typeof p?.text === "string" ? p.text : "";
+  }).filter(Boolean).join("");
+}
+var EVENT_TYPE_BY_KIND = {
+  agent: "agent",
+  tool: "tool",
+  llm: "llm",
+  http: "http",
+  mcp: "mcp",
+  media: "media",
+  other: "other"
+};
+var SAMPLE_SEED = 2654435769;
 var CATEGORY = {
   // Network
   onEnqueue: "network",
@@ -182,10 +262,29 @@ function traceIdsOf(ctx) {
   const t = c?.trace ?? c?.ctx ?? c;
   return {
     sessionId: t?.sessionId,
-    requestId: t?.requestId
+    requestId: t?.requestId,
+    /** W3C parent context, when the app is already inside a trace of its own. */
+    traceparent: t?.traceparent,
+    // `gen_ai.conversation.id` in the semantic conventions — the thread a turn
+    // belongs to, which is what lets a backend group turns into one conversation.
+    // AgentLoop sets it from the history id; a bare client call has none.
+    conversationId: t?.conversationId
   };
 }
-var traceKey = (ids) => ids.requestId ? `${ids.sessionId ?? "?"}:${ids.requestId}` : void 0;
+function parseTraceparent(value) {
+  if (!value) return null;
+  const m = /^[0-9a-f]{2}-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/.exec(value.trim().toLowerCase());
+  if (!m) return null;
+  const [, traceId, spanId] = m;
+  if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) return null;
+  return { traceId, spanId };
+}
+var CONTAINER_SPANS = /* @__PURE__ */ new Set(["agent.run", "tool.call"]);
+var traceKey = (ids) => {
+  const parent = parseTraceparent(ids.traceparent);
+  if (parent) return parent.traceId;
+  return ids.requestId ? `${ids.sessionId ?? "?"}:${ids.requestId}` : void 0;
+};
 var TelemetryAdapter = class {
   events = [];
   spans = [];
@@ -206,17 +305,138 @@ var TelemetryAdapter = class {
   /** Service identity stamped on exported telemetry. */
   resource;
   seq = 0;
+  /** 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. */
+  spanSeq = 0;
+  /** 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. */
+  appParent = /* @__PURE__ */ new Map();
+  containers = /* @__PURE__ */ new Map();
   latSum = 0;
   open = /* @__PURE__ */ new Map();
   maxEvents;
   includeSensitiveData;
   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. */
+  sinks = [];
+  content;
+  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. */
+  lineage = /* @__PURE__ */ new Map();
+  maxLineage;
+  msgSeq = 0;
   constructor(hooks, opts = {}) {
     this.maxEvents = opts.maxEvents ?? 2e3;
     this.includeSensitiveData = opts.includeSensitiveData ?? true;
     this.resource = opts.resource ?? { serviceName: "unknown_service" };
+    this.content = opts.content ?? "none";
+    this.sampleRate = opts.sample ?? 1;
+    this.maxLineage = this.maxEvents * 2;
+    if (opts.onTrace) this.onTrace({ types: opts.types }, opts.onTrace);
     this.unsub = hooks.onAny((name, ctx) => this.handle(name, ctx));
   }
+  onTrace(filterOrHandler, maybeHandler) {
+    const handler = typeof filterOrHandler === "function" ? filterOrHandler : maybeHandler;
+    if (!handler) throw new Error("onTrace requires a handler");
+    const filter = typeof filterOrHandler === "function" ? {} : filterOrHandler;
+    const sink = { types: filter.types ? new Set(filter.types) : void 0, handler };
+    this.sinks.push(sink);
+    return () => {
+      const at = this.sinks.indexOf(sink);
+      if (at !== -1) this.sinks.splice(at, 1);
+    };
+  }
+  /** 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. */
+  recordSpan(span) {
+    this.spans.push(span);
+    const type = EVENT_TYPE_BY_KIND[span.kind];
+    if (!this.lineage.has(span.spanId)) this.remember(span.spanId, span.parentSpanId, type);
+    this.dispatch({
+      type,
+      traceId: span.traceId,
+      spanId: span.spanId,
+      parentSpanId: span.parentSpanId,
+      name: otlpSpanName(span),
+      startTime: span.startTime,
+      endTime: span.endTime,
+      durationMs: span.durationMs,
+      status: span.status,
+      attributes: span.attributes
+    });
+  }
+  remember(spanId, parentSpanId, type) {
+    this.lineage.set(spanId, { parentSpanId, type });
+    if (this.lineage.size > this.maxLineage) {
+      const oldest = this.lineage.keys().next().value;
+      if (oldest !== void 0) this.lineage.delete(oldest);
+    }
+  }
+  dispatch(event) {
+    if (this.sinks.length === 0) return;
+    if (!this.isSampled(event.traceId)) return;
+    for (const sink of this.sinks) {
+      if (sink.types && !sink.types.has(event.type)) continue;
+      const parentSpanId = sink.types ? this.survivingParent(event.parentSpanId, sink.types) : event.parentSpanId;
+      sink.handler(parentSpanId === event.parentSpanId ? event : { ...event, parentSpanId });
+    }
+  }
+  /** 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. */
+  survivingParent(parentSpanId, types) {
+    let id = parentSpanId;
+    while (id) {
+      const node = this.lineage.get(id);
+      if (!node) return void 0;
+      if (types.has(node.type)) return id;
+      id = node.parentSpanId;
+    }
+    return void 0;
+  }
+  /** 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. */
+  isSampled(traceId) {
+    if (this.sampleRate >= 1) return true;
+    if (this.sampleRate <= 0) return false;
+    return fnv1a32(traceId, SAMPLE_SEED) / 4294967296 < this.sampleRate;
+  }
+  /** Conversation content, as its own event so it can be routed somewhere different from
+   *  the spans — a debug store, not the metrics backend. */
+  emitMessage(span, direction, payload) {
+    if (this.sinks.length === 0) return;
+    const messages = toMessageList(payload, direction === "input" ? "user" : "assistant");
+    if (messages.length === 0) return;
+    const chars = messages.reduce((n, m) => n + m.content.length, 0);
+    this.dispatch({
+      type: "message",
+      traceId: span.traceId,
+      spanId: `${span.spanId}:msg${this.msgSeq++}`,
+      parentSpanId: span.spanId,
+      name: `message.${direction}`,
+      startTime: Date.now(),
+      status: "unset",
+      attributes: clean({
+        "message.direction": direction,
+        "message.count": messages.length,
+        "message.chars": chars,
+        // Opt-In in the spec, and off by default here for the same reason.
+        [`gen_ai.${direction}.messages`]: this.content === "full" ? messages : void 0
+      })
+    });
+  }
   /** Stop tapping the bus. */
   destroy() {
     this.unsub();
@@ -224,6 +444,8 @@ var TelemetryAdapter = class {
   handle(name, ctx) {
     const ids = traceIdsOf(ctx);
     const traceId = traceKey(ids);
+    const parent = parseTraceparent(ids.traceparent);
+    if (parent && traceId) this.appParent.set(traceId, parent.spanId);
     this.events.push({
       seq: this.seq++,
       time: Date.now(),
@@ -246,20 +468,27 @@ var TelemetryAdapter = class {
           this.metrics.outputTokens += usage.outputTokens ?? 0;
         }
         if (traceId) {
+          const responseModel = c.response?.model;
           const attrs = {
-            "gen_ai.provider": c.provider,
-            "gen_ai.model": c.model,
+            "gen_ai.provider.name": c.provider,
+            "gen_ai.operation.name": "chat",
+            "gen_ai.request.model": c.model,
+            // The model that actually answered, which can differ from the one asked
+            // for (an alias resolving to a dated snapshot, a router picking a peer).
+            "gen_ai.response.model": responseModel,
+            "gen_ai.conversation.id": ids.conversationId,
             "gen_ai.usage.input_tokens": usage?.inputTokens,
             "gen_ai.usage.output_tokens": usage?.outputTokens
           };
           const key = `llm:${traceId}`;
+          let llmSpan;
           if (this.open.has(key)) {
-            this.closeSpan(key, "ok", attrs);
+            llmSpan = this.closeSpan(key, "ok", attrs);
           } else {
             const http = [...this.spans].reverse().find((s) => s.traceId === traceId && s.kind === "http");
             const start = http?.startTime ?? Date.now();
             const end = Date.now();
-            this.spans.push({
+            llmSpan = {
               traceId,
               spanId: key,
               name: "llm.request",
@@ -269,7 +498,12 @@ var TelemetryAdapter = class {
               durationMs: end - start,
               status: "ok",
               attributes: clean(attrs)
-            });
+            };
+            this.recordSpan(llmSpan);
+          }
+          if (llmSpan) {
+            const response = c.response;
+            this.emitMessage(llmSpan, "output", response?.content ?? response?.text);
           }
         }
         break;
@@ -315,9 +549,11 @@ var TelemetryAdapter = class {
         this.metrics.mediaGenerated += c.count ?? 1;
         if (traceId) {
           const now = Date.now();
-          this.spans.push({
+          this.recordSpan({
             traceId,
-            spanId: `media:${traceId}`,
+            // One run can generate several images; `media:${traceId}` would give them
+            // all the same span id, which is invalid within a trace.
+            spanId: `media:${traceId}:${this.spanSeq++}`,
             name: "media.generate",
             kind: "media",
             startTime: now,
@@ -332,10 +568,21 @@ var TelemetryAdapter = class {
       case "onRunStart": {
         const runId = c.runId;
         if (runId) {
-          this.openSpan(`agent:${runId}`, runId, "agent.run", "agent", {
-            "agent.id": c.agentId,
-            "agent.model": c.model
+          const runSpan = this.openSpan(`agent:${runId}`, traceId ?? runId, "agent.run", "agent", {
+            // The host's own attributes go FIRST so ours win on a key collision: a stray
+            // `gen_ai.*` key in a caller's bag must not be able to rewrite the identity
+            // of the span.
+            ...c.attributes,
+            "gen_ai.operation.name": "invoke_agent",
+            // Named when the agent was given a label; the exported span is then
+            // `invoke_agent {label}` rather than the bare operation.
+            "gen_ai.agent.name": c.label,
+            "gen_ai.agent.id": c.agentId,
+            "gen_ai.request.model": c.model,
+            // Ours, not a convention attribute — the GenAI spec has no term for it.
+            "agent.source": c.source
           });
+          this.emitMessage(runSpan, "input", c.userMessage);
         }
         break;
       }
@@ -362,9 +609,11 @@ var TelemetryAdapter = class {
       case "onToolCallStart": {
         const callId = c.callId;
         if (callId) {
-          this.openSpan(`tool:${callId}`, callId, "tool.call", "tool", {
-            "tool.name": c.toolName,
-            "agent.id": c.agentId
+          this.openSpan(`tool:${callId}`, traceId ?? callId, "tool.call", "tool", {
+            "gen_ai.operation.name": "execute_tool",
+            "gen_ai.tool.name": c.toolName,
+            "gen_ai.tool.call.id": callId,
+            "gen_ai.agent.id": c.agentId
           });
         }
         break;
@@ -373,7 +622,7 @@ var TelemetryAdapter = class {
         const callId = c.callId;
         if (callId) {
           this.closeSpan(`tool:${callId}`, "ok", {
-            "tool.name": c.toolName,
+            "gen_ai.tool.name": c.toolName,
             "tool.latency_ms": c.latencyMs
           });
         }
@@ -383,7 +632,7 @@ var TelemetryAdapter = class {
         const callId = c.callId;
         if (callId) {
           this.closeSpan(`tool:${callId}`, "error", {
-            "tool.name": c.toolName,
+            "gen_ai.tool.name": c.toolName,
             "tool.error": c.error?.message
           });
         }
@@ -394,9 +643,17 @@ var TelemetryAdapter = class {
         const server = c.server;
         if (server) {
           const now = Date.now();
-          this.spans.push({
-            traceId: server,
-            spanId: `mcp:connect:${server}`,
+          this.recordSpan({
+            // A connect usually happens at startup, outside any run, so there is often
+            // no trace to join — but keying the trace by server name merged every
+            // reconnect over the process lifetime into one trace. Falls back to a span
+            // of its own instead.
+            traceId: traceId ?? `mcp:connect:${server}:${this.spanSeq}`,
+            // `${server}` alone repeats on every reconnect, and a duplicate span id
+            // within a trace is invalid OTLP — the backend keeps one and drops the
+            // rest. The counter is monotonic where a timestamp is not: two connects
+            // inside the same millisecond would still collide.
+            spanId: `mcp:connect:${server}:${this.spanSeq++}`,
             name: "mcp.connect",
             kind: "mcp",
             startTime: now,
@@ -418,9 +675,14 @@ var TelemetryAdapter = class {
         if (server && tool) {
           const now = Date.now();
           const lat = c.latencyMs;
-          this.spans.push({
-            traceId: server,
-            spanId: `mcp:tool:${server}:${tool}:${now}`,
+          this.recordSpan({
+            // An MCP tool call happens INSIDE a run, so it belongs to that run's trace.
+            // Keying it by server put every call to one server in a single eternal
+            // trace, and none of them with the agent that made the call.
+            traceId: traceId ?? `mcp:${server}`,
+            // A timestamp is not a unique key: two tool calls in the same millisecond
+            // share it. The counter is.
+            spanId: `mcp:tool:${server}:${tool}:${this.spanSeq++}`,
             name: "mcp.tool_call",
             kind: "mcp",
             startTime: now - (lat ?? 0),
@@ -438,10 +700,33 @@ var TelemetryAdapter = class {
       }
     }
   }
+  /** 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. */
+  parentFor(traceId) {
+    const stack = this.containers.get(traceId);
+    return stack?.[stack.length - 1] ?? this.appParent.get(traceId);
+  }
   openSpan(key, traceId, spanName, kind, attributes) {
+    const parentSpanId = this.parentFor(traceId);
     const span = {
       traceId,
-      spanId: key,
+      ...parentSpanId ? { parentSpanId } : {},
+      // The KEY pairs open with close (`llm:${traceId}`); the SPAN ID must be unique.
+      // Those were the same string until a run stopped fragmenting into one trace per
+      // call — at which point every LLM call in a run produced the identical key, and
+      // the collision merged them into one span at the collector.
+      spanId: `${key}#${this.spanSeq++}`,
       name: spanName,
       kind,
       startTime: Date.now(),
@@ -449,17 +734,33 @@ var TelemetryAdapter = class {
       attributes
     };
     this.open.set(key, span);
+    this.remember(span.spanId, parentSpanId, EVENT_TYPE_BY_KIND[kind]);
+    if (CONTAINER_SPANS.has(spanName)) {
+      const stack = this.containers.get(traceId);
+      if (stack) stack.push(span.spanId);
+      else this.containers.set(traceId, [span.spanId]);
+    }
     return span;
   }
   closeSpan(key, status, attributes) {
     const span = this.open.get(key);
-    if (!span) return;
+    if (!span) return void 0;
+    const stack = this.containers.get(span.traceId);
+    if (stack) {
+      const at = stack.lastIndexOf(span.spanId);
+      if (at !== -1) stack.splice(at, 1);
+      if (stack.length === 0) {
+        this.containers.delete(span.traceId);
+        this.appParent.delete(span.traceId);
+      }
+    }
     span.endTime = Date.now();
     span.durationMs = span.endTime - span.startTime;
     span.status = status;
     Object.assign(span.attributes, clean(attributes));
     this.open.delete(key);
-    this.spans.push(span);
+    this.recordSpan(span);
+    return span;
   }
   recordLatency(ms) {
     if (typeof ms !== "number") return;
@@ -509,14 +810,27 @@ var TelemetryAdapter = class {
             {
               scope: { name: "combycode.telemetry" },
               spans: this.spans.map((s) => ({
-                traceId: s.traceId,
-                spanId: s.spanId,
-                name: s.name,
+                // An app-supplied trace id is ALREADY a real 32-hex id — hashing it
+                // would produce a different trace and defeat the whole point of
+                // accepting a parent.
+                traceId: isHex(s.traceId, 32) ? s.traceId : toOtlpId(s.traceId, 16),
+                // Scoped by trace: two conversations can each hold a span keyed
+                // `llm:…`, and colliding their ids would merge unrelated traces.
+                spanId: toOtlpId(`${s.traceId}|${s.spanId}`, 8),
+                // The app's own span id arrives as hex and passes through; one of ours
+                // is hashed exactly as it was when we emitted it, so the link matches.
+                ...s.parentSpanId ? {
+                  parentSpanId: isHex(s.parentSpanId, 16) ? s.parentSpanId : toOtlpId(`${s.traceId}|${s.parentSpanId}`, 8)
+                } : {},
+                name: otlpSpanName(s),
                 startTimeUnixNano: Math.round(s.startTime * 1e6),
                 endTimeUnixNano: Math.round((s.endTime ?? s.startTime) * 1e6),
-                kind: s.kind,
+                kind: OTLP_KIND_BY_SPAN[s.kind] ?? OTLP_SPAN_KIND.internal,
                 status: { code: s.status === "error" ? 2 : s.status === "ok" ? 1 : 0 },
-                attributes: Object.entries(s.attributes).map(([key, value]) => ({ key, value: { stringValue: String(value) } }))
+                attributes: Object.entries(s.attributes).map(([key, value]) => ({
+                  key,
+                  value: toOtlpValue(value)
+                }))
               }))
             }
           ]
@@ -25147,7 +25461,7 @@ function extractSystem(messages) {
   const rest = [];
   for (const m of messages) {
     if (m.role === "system") {
-      const text = typeof m.content === "string" ? m.content : contentToText(m.content);
+      const text = typeof m.content === "string" ? m.content : contentToText2(m.content);
       if (text) systemTexts.push(text);
     } else {
       rest.push(m);
@@ -25158,7 +25472,7 @@ function extractSystem(messages) {
     messages: rest
   };
 }
-function contentToText(content) {
+function contentToText2(content) {
   return content.filter((p) => p.type === "text").map((p) => p.text).join("\n");
 }
 function parseStructured(text) {
@@ -25440,7 +25754,15 @@ var LLMClient = class {
         signal: options.signal,
         provider: this.provider,
         model: this.model,
-        trace: { sessionId: ctx.sessionId, requestId: ctx.requestId, callId: ctx.callId }
+        // Every trace field, not a hand-picked three: `traceparent` rides with the ids,
+        // and picking fields here is what left the HTTP spans rooting a trace of their
+        // own while the LLM span they belong to had joined the caller's.
+        trace: {
+          sessionId: ctx.sessionId,
+          requestId: ctx.requestId,
+          callId: ctx.callId,
+          traceparent: ctx.traceparent
+        }
       };
       response = await this.fetchFn(httpReq, {
         queueName: this.queueName,
@@ -25568,7 +25890,15 @@ var LLMClient = class {
       stream: true,
       provider: this.provider,
       model: this.model,
-      trace: { sessionId: ctx.sessionId, requestId: ctx.requestId, callId: ctx.callId }
+      // Every trace field, not a hand-picked three: `traceparent` rides with the ids,
+      // and picking fields here is what left the HTTP spans rooting a trace of their
+      // own while the LLM span they belong to had joined the caller's.
+      trace: {
+        sessionId: ctx.sessionId,
+        requestId: ctx.requestId,
+        callId: ctx.callId,
+        traceparent: ctx.traceparent
+      }
     };
     const start = performance.now();
     let text = "";
@@ -31475,6 +31805,12 @@ async function handleToolError(e, tc, hooks, runId, agentId, step, metrics, repo
 // src/agent/loop.ts
 var AgentLoop = class _AgentLoop {
   id;
+  /** Human name, surfaced as `gen_ai.agent.name` — see AgentLoopConfig.label. */
+  label;
+  /** Which part of the host system this agent belongs to. */
+  source;
+  /** Extra attributes stamped on this agent's spans. */
+  attributes;
   client;
   hooks;
   _system;
@@ -31548,6 +31884,9 @@ var AgentLoop = class _AgentLoop {
       this._history = new ConversationHistory();
     }
     this.id = this._history.id;
+    this.label = config.label;
+    this.source = config.source;
+    this.attributes = config.attributes;
     writeAgentLoopSystem(this._history.registry, this._system, "agent-loop");
     writeAgentLoopContext(this._history.registry, this._context, "agent-loop");
     this.syncLazyProtocol();
@@ -31652,7 +31991,7 @@ var AgentLoop = class _AgentLoop {
   }
   // ─── complete (non-streaming) ───────────────────────────────────────────
   async complete(input, options = {}) {
-    const { runId, startedAt, startPerf, userMessageText, runTrace } = await this.beginRun(input);
+    const { runId, startedAt, startPerf, userMessageText, runTrace } = await this.beginRun(input, options.ctx);
     const steps = [];
     const totalUsage = emptyUsage();
     let totalLlmTimeMs = 0;
@@ -31704,7 +32043,23 @@ var AgentLoop = class _AgentLoop {
           thinking: options.thinking ?? this._thinking,
           cache: options.cache ?? this._cache,
           tools: this.toolDefinitions(options),
-          ctx: { ...options.ctx, conversationId: this._history.id },
+          ctx: {
+            // The RUN's trace, handed down to every LLM call it makes.
+            //
+            // Without this the agent kept `runTrace` to itself: its own spans used it
+            // while each `client.complete()` fell through to mint-if-absent and
+            // invented a fresh `requestId`. Since the trace id is `sessionId:requestId`,
+            // one conversation arrived at the backend as SEVERAL unrelated traces —
+            // measured against a real collector: a single turn with one tool call
+            // produced six. Correlation is the whole point of a trace id, so this is
+            // the one thing it must not get wrong.
+            ...runTrace,
+            conversationId: this._history.id,
+            // A caller's explicit ctx wins over all of the above: an app that already
+            // owns a request id or a conversation id has better information than we do,
+            // and silently overwriting it is how its telemetry stops joining up.
+            ...options.ctx
+          },
           signal: options.signal ?? this._abortController?.signal
         });
         const stepLatency = performance.now() - stepStart;
@@ -31872,7 +32227,7 @@ var AgentLoop = class _AgentLoop {
   }
   // ─── stream ─────────────────────────────────────────────────────────────
   async *stream(input, options = {}) {
-    const { runId, startedAt, startPerf, userMessageText, runTrace } = await this.beginRun(input);
+    const { runId, startedAt, startPerf, userMessageText, runTrace } = await this.beginRun(input, options.ctx);
     const steps = [];
     const totalUsage = emptyUsage();
     let totalLlmTimeMs = 0;
@@ -31928,7 +32283,23 @@ var AgentLoop = class _AgentLoop {
           thinking: options.thinking ?? this._thinking,
           cache: options.cache ?? this._cache,
           tools: this.toolDefinitions(options),
-          ctx: { ...options.ctx, conversationId: this._history.id },
+          ctx: {
+            // The RUN's trace, handed down to every LLM call it makes.
+            //
+            // Without this the agent kept `runTrace` to itself: its own spans used it
+            // while each `client.complete()` fell through to mint-if-absent and
+            // invented a fresh `requestId`. Since the trace id is `sessionId:requestId`,
+            // one conversation arrived at the backend as SEVERAL unrelated traces —
+            // measured against a real collector: a single turn with one tool call
+            // produced six. Correlation is the whole point of a trace id, so this is
+            // the one thing it must not get wrong.
+            ...runTrace,
+            conversationId: this._history.id,
+            // A caller's explicit ctx wins over all of the above: an app that already
+            // owns a request id or a conversation id has better information than we do,
+            // and silently overwriting it is how its telemetry stops joining up.
+            ...options.ctx
+          },
           signal: options.signal ?? this._abortController?.signal
         })) {
           const toYield = accumulateStreamEvent(event, state);
@@ -32140,7 +32511,7 @@ var AgentLoop = class _AgentLoop {
         arguments: tc.arguments,
         callId: tc.id,
         step,
-        trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id }
+        trace: { ...runTrace, callId: tc.id }
       });
       if (!decision.pass) {
         return this.buildDeniedResult(tc, decision.reason, reports);
@@ -32160,7 +32531,7 @@ var AgentLoop = class _AgentLoop {
       }
     }
     try {
-      const baseCtx = { step, callId: tc.id, metrics, trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id } };
+      const baseCtx = { step, callId: tc.id, metrics, trace: { ...runTrace, callId: tc.id } };
       const result = await executeWithTimeout(lookup.tool, tc, baseCtx, this._toolTimeout);
       return await this.buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace, lookup.tool, baseCtx);
     } catch (e) {
@@ -32218,7 +32589,7 @@ var AgentLoop = class _AgentLoop {
       arguments: tc.arguments,
       reason,
       step,
-      trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id }
+      trace: { ...runTrace, callId: tc.id }
     };
     const pending = {
       callId: tc.id,
@@ -32251,7 +32622,7 @@ var AgentLoop = class _AgentLoop {
         return this.buildOverriddenResult(tc, decision.overrideResult, reports);
       }
       try {
-        const baseCtx = { step, callId: tc.id, metrics, trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId, callId: tc.id } };
+        const baseCtx = { step, callId: tc.id, metrics, trace: { ...runTrace, callId: tc.id } };
         const result = await executeWithTimeout(tool, tc, baseCtx, this._toolTimeout);
         return await this.buildSuccessResult(tc, result, runId, step, metrics, reports, toolStart, runTrace, tool, baseCtx);
       } catch (e) {
@@ -32347,7 +32718,7 @@ var AgentLoop = class _AgentLoop {
     return own.length > 0 ? own : void 0;
   }
   // ─── Run helpers ────────────────────────────────────────────────────────
-  async beginRun(input) {
+  async beginRun(input, callerCtx) {
     if (this._running) throw new Error("AgentLoop is already running");
     this._running = true;
     this._stopRequested = false;
@@ -32364,10 +32735,23 @@ var AgentLoop = class _AgentLoop {
     const startedAt = Date.now();
     const startPerf = performance.now();
     const userMessageText = typeof input === "string" ? input : Array.isArray(input) && input.length > 0 && "role" in input[0] ? contentText(input[input.length - 1].content) : contentText(input);
-    const runTrace = { sessionId: this.id, requestId: runId };
+    const runTrace = {
+      sessionId: callerCtx?.sessionId ?? this.id,
+      requestId: callerCtx?.requestId ?? runId,
+      // The caller's span travels WITH the ids, for the same reason they do: `agent.run`,
+      // every `tool.call`, and any agent nested inside a tool reach the telemetry through
+      // `runTrace` and nothing else. While this field was missing from it only the LLM
+      // calls joined the app's trace — they are built from the caller's ctx directly —
+      // and the run that made them sat in a second, unrelated one. Measured against a
+      // live backend; the unit tests fed the hooks directly and never saw it.
+      ...callerCtx?.traceparent ? { traceparent: callerCtx.traceparent } : {}
+    };
     await this.hooks.emit("onRunStart", {
       runId,
       agentId: this.id,
+      label: this.label,
+      source: this.source,
+      attributes: this.attributes,
       userMessage: input,
       model: this.client.model,
       system: this._history.system,
@@ -32422,7 +32806,7 @@ var AgentLoop = class _AgentLoop {
       if (g.kind !== "input") continue;
       const decision = await g.check({
         kind: "input",
-        trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId },
+        trace: { ...runTrace },
         step,
         messages,
         system
@@ -32450,7 +32834,7 @@ var AgentLoop = class _AgentLoop {
       if (g.kind !== "output") continue;
       const decision = await g.check({
         kind: "output",
-        trace: { sessionId: runTrace.sessionId, requestId: runTrace.requestId },
+        trace: { ...runTrace },
         step,
         response
       });
@@ -34615,6 +34999,7 @@ function createEngine(config = {}) {
   const fetchStreamBound = (req, options) => network.fetchStream(req, options);
   const connectBound = (req) => network.connect(req);
   const cost = new CostCollector({ hooks, catalog });
+  const telemetry = config.telemetry ? new TelemetryAdapter(hooks, config.telemetry) : null;
   const handle = {
     sessionId,
     hooks,
@@ -34627,9 +35012,11 @@ function createEngine(config = {}) {
     connect: connectBound,
     catalog,
     cost,
+    telemetry,
     apiKeys: config.apiKeys ?? {},
     destroy() {
       cost.destroy();
+      telemetry?.destroy();
       network.destroy();
     }
   };