@combycode/llm-sdk 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,115 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [2.2.0] — 2026-08-17
+
+### Added
+
+- **Agents can be named: `label`, `source` and an `attributes` bag.** An unlabelled agent
+  exported as a bare `invoke_agent` carrying only a per-process id, so a trace could not say
+  which agent ran or be compared across runs. `label` becomes `gen_ai.agent.name` and names
+  the span (`invoke_agent briefing`); `source` records which part of the host system the
+  agent belongs to, as free text because the taxonomy is the application's; `attributes`
+  stamps anything else onto the run. Library attributes win on a key collision, so the bag
+  cannot rewrite what a span claims to be.
+
+- **`onTrace` -- an event surface, so this SDK can be one source in a bigger pipeline.**
+  Configure it at `createEngine({ telemetry: { types, content, sample, onTrace } })` and take
+  the levels you want: an operator reading business traces does not want our HTTP retries,
+  and an SDK that ships its own exporter just competes with the pipeline they already run.
+  Events carry `traceId` / `spanId` / `parentSpanId`, so a consumer pushes them straight
+  into their own tracer. Nothing is sent anywhere by the library.
+
+  Filtering **splices** the tree rather than punching holes in it -- drop `http` and its
+  children re-parent to the nearest ancestor that subscriber still receives, because a
+  dangling parent renders as a second root. Sampling is per **trace**, hashed from the
+  trace id so two services sharing one agree without coordinating; sampling per span would
+  shred every tree it touched. Conversation content is off by default and rides on
+  `message` events only, never on spans, so spans can go to a metrics backend without
+  carrying prompts into it.
+
+- **The SDK can run inside your application's trace.** Pass `ctx.traceparent` -- the W3C header
+  shape -- and every span the run emits joins that trace and hangs under that span instead of
+  rooting one of its own. A business chain and the model calls it triggers now arrive as one
+  request rather than two unrelated traces. A malformed header is ignored rather than fatal.
+
+### Changed
+
+- **Exported spans follow the GenAI semantic conventions.** `agent.run` and `tool.call` export as
+  `invoke_agent` and `execute_tool {name}`, carrying `gen_ai.operation.name`, `gen_ai.agent.id`,
+  `gen_ai.tool.name` and `gen_ai.tool.call.id`. Names only this library understood forced every
+  consumer to write its own mapping; a backend that speaks the conventions now recognises the work
+  without one. Internal names are unchanged, so `snapshot()` and the sandbox sidebar group as
+  before.
+
+  **If you read span attributes,** three keys moved: `tool.name` → `gen_ai.tool.name`,
+  `agent.id` → `gen_ai.agent.id`, `agent.model` → `gen_ai.request.model`. Span *names* in
+  `snapshot()` are untouched; only the exported ones changed.
+
+### Fixed
+
+- **Spans had no parent, so a backend drew a flat list instead of a tree.** Every span was a
+  sibling, and a turn read as "nine things happened" rather than "a run, which called a tool, which
+  asked a second model". Spans now carry `parentSpanId`, resolved to the innermost enclosing
+  `agent.run` / `tool.call`, else the caller's span, else none.
+
+- **An agent nested inside a tool call orphaned the run around it.** The enclosing span was tracked
+  as one slot per trace, so a second run on the same trace overwrote it and then deleted it on
+  close, leaving the rest of the outer run parentless. It is a stack now, and a container is removed
+  by id rather than popped, because parallel tool calls close out of order.
+
+- **`traceparent` was dropped at two layers, each by hand-picking fields off the trace.** `beginRun`
+  built `{ sessionId, requestId }` and `LLMClient` handed `{ sessionId, requestId, callId }` to the
+  network layer. One request became three traces: the model calls joined the caller's, while
+  `agent.run`, every `tool.call`, every nested agent and every `http.request` rooted their own. The
+  trace now travels whole, and `RunTrace` replaces a shape written inline at eleven signatures.
+
+- **One agent run arrived as several unrelated traces.** The agent built a `runTrace` for its own
+  spans and never handed it to the LLM calls it made, so each call fell through to mint-if-absent and
+  invented its own `requestId`. Since the trace id is `sessionId:requestId`, a single conversation
+  fragmented: measured against a live Grafana Tempo endpoint, one turn with one tool call produced
+  SIX traces. Every span looked correct on its own, which is why it survived until telemetry was
+  pointed at a real backend.
+
+- **A caller's own trace ids were discarded, then half-honoured.** `ctx.sessionId` / `ctx.requestId`
+  now win over the agent's, and the run trace is derived in ONE place from them — deriving it
+  separately for agent spans and LLM calls meant a caller passing only `sessionId` split the run in
+  two. `ctx.conversationId` likewise wins over the history id instead of being silently overwritten.
+
+- **`agent.run` and `tool.call` spans used an entity id as the trace id** — the run id and the tool
+  call id respectively — putting them in a different trace from the work they describe. One span's
+  trace id was literally `t1`. MCP spans keyed their trace by server name, merging every call to a
+  server over the process lifetime into one eternal trace.
+
+- **Span ids collided once a run shared one trace.** The span KEY (`llm:${traceId}`) doubled as the
+  span ID, so every LLM call in a run emitted the same id and the collector merged them into one
+  span. Key and id are now separate.
+
+
+
+
+- **`toOtlpTraces()` produced JSON that only LOOKED like OTLP, and no collector would accept it.**
+  Trace ids went out as `s:r` and span ids as `llm:s:r` where the protocol requires 16- and 8-byte
+  hex; `kind` was the string `'llm'` where it must be the int enum; and every attribute value was
+  `String(value)`, so `gen_ai.usage.input_tokens` arrived as text and could not be summed by any
+  backend. Ids are now derived deterministically from the readable internal ones, so a trace split
+  across two exports still joins up.
+
+- **LLM spans used attribute names no backend recognises.** `gen_ai.provider` / `gen_ai.model` are
+  not in the OTel GenAI semantic conventions; the required names are `gen_ai.provider.name` and
+  `gen_ai.operation.name`, with `gen_ai.request.model`. A span carrying the old names is not
+  identified as a model call at all. Adds `gen_ai.response.model` (the model that actually answered,
+  which an alias can change) and `gen_ai.conversation.id` (the agent's history id).
+
+- **Point spans could share an id, and the backend silently dropped the duplicates.**
+  `mcp:connect:${server}` repeated on every reconnect and `media:${traceId}` repeated for a second
+  image in the same run; `mcp:tool:…:${Date.now()}` collided for two calls in one millisecond. A
+  duplicate span id within a trace is invalid OTLP, so those runs looked like they did less work
+  than they did.
+
+  The in-memory model is unchanged — `snapshot()` still returns readable ids and the domain `kind`,
+  which is what the sandbox groups by. Only the export is translated.
+
 ## [2.1.0] — 2026-08-17
 
 Minor, not major: everything below is additive or a bug fix, and no export was removed or

package/dist/agent/loop-config.d.ts

@@ -14,6 +14,25 @@ import type { Persistence } from '../plugins/persistence/types';
 export interface AgentLoopConfig {
     /** LLM client. AgentLoop reads `client.model` and uses `client.complete`/`client.stream`. */
     client: LLMClient;
+    /** Human name for this agent, e.g. `'briefing'`. Without it telemetry only has the
+     *  agent's generated id, and a trace reads as `invoke_agent` with no clue which of your
+     *  agents ran — the ids differ per process, so they cannot be compared across runs
+     *  either. With it the span becomes `invoke_agent briefing` and carries
+     *  `gen_ai.agent.name`, which is what the conventions ask for. */
+    label?: string;
+    /** Which part of YOUR system this agent belongs to, e.g. `'customer'`, `'moderation'`.
+     *
+     *  Free text rather than a fixed set, because the taxonomy is the application's: a
+     *  library cannot know whether you divide by product surface, team, or bounded context,
+     *  and forcing our categories on you would only make you encode yours inside a `label`.
+     *  Exported as `agent.source` — our attribute, not a convention one; the GenAI spec has
+     *  no term for it. */
+    source?: string;
+    /** Extra attributes stamped on this agent's span, for whatever the fixed fields do not
+     *  cover — tenant, tier, experiment arm. Keys are used verbatim, so namespace them
+     *  (`app.tenant`) to stay clear of convention attributes; ours win on a collision, so a
+     *  stray key here cannot corrupt `gen_ai.*`. */
+    attributes?: Record<string, string | number | boolean>;
     /** Persona / role text for the agent. Stored as the `agentloop.system` registry
      *  layer (priority 10). Composed with other system-tagged layers when sending.
      *  When passed as a function, it is re-evaluated at the start of every

package/dist/agent/loop-internals.d.ts

@@ -7,6 +7,19 @@ import type { StreamEvent } from '../llm/types/stream';
 import type { TraceContext } from '../network/types';
 import type { AgentStreamEvent, AgentTool, ToolCallReport, ToolExecutionContext } from './types';
 import type { StepState } from './loop-step-state';
+/** The trace one agent run belongs to — resolved once in `beginRun` and handed to
+ *  everything the run emits: its own span, its LLM calls, its tool calls, and any agent
+ *  nested inside a tool.
+ *
+ *  Not a bare `TraceContext` because `sessionId`/`requestId` are always resolved here
+ *  (mint-if-absent), while `traceparent` appears only when the caller runs us inside a
+ *  span of its own. Named rather than written inline because the shape was repeated at
+ *  eleven signatures — and adding a field to ten of them is how a run ends up split
+ *  across two traces. */
+export type RunTrace = TraceContext & {
+    sessionId: string;
+    requestId: string;
+};
 /** Create a fresh StepState for the start of a streaming step. */
 export declare function makeStepState(): StepState;
 /** Accumulate one SSE StreamEvent into StepState.

package/dist/agent/loop.d.ts

@@ -23,6 +23,12 @@ import type { PermissionPolicy } from '../plugins/permissions/policy';
 import type { ApprovalRequest, ApprovalDecision, PendingToolCall } from './approval-types';
 export declare class AgentLoop {
     readonly id: string;
+    /** Human name, surfaced as `gen_ai.agent.name` — see AgentLoopConfig.label. */
+    readonly label?: string;
+    /** Which part of the host system this agent belongs to. */
+    readonly source?: string;
+    /** Extra attributes stamped on this agent's spans. */
+    readonly attributes?: Record<string, string | number | boolean>;
     readonly client: LLMClient;
     readonly hooks: HookBus;
     private _system;

package/dist/bus/hook-map.d.ts

@@ -226,6 +226,12 @@ export interface AgentDestroyContext {
 export interface RunStartContext {
     runId: string;
     agentId: string;
+    /** Human name for the agent, when one was configured. */
+    label?: string;
+    /** Which part of the host system the agent belongs to. */
+    source?: string;
+    /** Extra attributes the host stamped on this agent. */
+    attributes?: Record<string, string | number | boolean>;
     userMessage: string | ContentPart[] | Message[];
     model: string;
     system?: string;

package/dist/helpers/engine.d.ts

@@ -24,6 +24,7 @@ import type { EngineConnect, EngineFetch, EngineFetchStream, FetchFn } from '../
 import { Cache } from '../plugins/cache/cache';
 import { CostCollector } from '../plugins/cost-collector/collector';
 import { ModelCatalog } from '../plugins/model-catalog/catalog';
+import { TelemetryAdapter, type TelemetryAdapterOptions } from '../plugins/telemetry/telemetry';
 import type { Persistence } from '../plugins/persistence/types';
 export interface EngineHandle {
     /** Trace session id — minted once for this engine (the holder), shared by
@@ -54,6 +55,10 @@ export interface EngineHandle {
     /** CostCollector — subscribes to onCompletion + onMediaGenerated and
      *  prices via catalog. Call `engine.cost.total()` for a running tally. */
     cost: CostCollector;
+    /** TelemetryAdapter — present only when `telemetry` was configured, because an
+     *  unwanted one would sit there accumulating spans for a process that never reads
+     *  them. Subscribe with `engine.telemetry.onTrace(...)`, or use it directly. */
+    telemetry: TelemetryAdapter | null;
     /** API keys per provider. Helpers (createLLM, createAgent,
      *  createMediaOutput, complete) read these to wire LLM clients without
      *  the caller passing apiKey explicitly. */
@@ -95,6 +100,20 @@ export interface EngineConfig {
     /** Per-provider API keys. Helpers consult this when no apiKey is passed
      *  alongside `model: 'provider/...'`. */
     apiKeys?: Partial<Record<ProviderName, string>>;
+    /** Observability. Omitted → no adapter is built and nothing is collected.
+     *
+     *  ```ts
+     *  createEngine({
+     *    telemetry: {
+     *      types: ['agent', 'tool'],        // http/llm detail stays out
+     *      content: 'none',                 // conversation text off by default
+     *      sample: 0.05,                    // per trace, not per span
+     *      onTrace: (e) => myPipeline.push(e),
+     *    },
+     *  });
+     *  ```
+     */
+    telemetry?: TelemetryAdapterOptions;
     /** Retry policy for every request this engine makes.
      *
      *  Retry is a cross-cutting concern, so it is configured once here rather than threaded through