@robota-sdk/agent-telemetry-otel 0.0.0-stage → 3.0.0-beta.95

package/src/__tests__/run-tracing.test.ts

@@ -0,0 +1,230 @@
+import { trace } from '@opentelemetry/api';
+import { InMemorySpanExporter, SimpleSpanProcessor, TracerProvider } from '@opentelemetry/sdk-trace';
+import { AbstractTool, ConversationAgent } from '@robota-sdk/agent-core';
+import { createScriptedProvider } from '@robota-sdk/agent-core/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createOtelTracing, createStructuralIdGenerator } from '../index.js';
+
+import type { TOtelProjectionMode } from '../index.js';
+import type { SpanContext } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace';
+import type {
+  IAgentConfig,
+  IToolExecutionContext,
+  IToolResult,
+  IToolSchema,
+  TToolParameters,
+} from '@robota-sdk/agent-core';
+
+const ORIGIN = 'https://model.example.com';
+
+class LookupTool extends AbstractTool {
+  readonly contexts: IToolExecutionContext[] = [];
+  constructor(private readonly fail = false) {
+    super();
+  }
+  override get schema(): IToolSchema {
+    return { name: 'lookup', description: 'lookup', parameters: { type: 'object' as const, properties: {} } };
+  }
+  override async execute(parameters: TToolParameters, context: IToolExecutionContext): Promise<IToolResult> {
+    this.contexts.push(context);
+    return super.execute(parameters, context);
+  }
+  protected override async executeImpl(): Promise<IToolResult> {
+    if (this.fail) throw new Error('lookup failed');
+    return { success: true, data: { ok: true } };
+  }
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0)) await cleanup();
+});
+
+async function tracedRun(mode: TOtelProjectionMode, options: { fail?: boolean; ids?: boolean; observe?: boolean } = {}) {
+  const exporter = new InMemorySpanExporter();
+  const idGenerator = createStructuralIdGenerator();
+  const provider = new TracerProvider({
+    ...(options.ids === false ? {} : { idGenerator }),
+    spanProcessors: [new SimpleSpanProcessor({ exporter })],
+  });
+  const tracer = provider.getTracer('test');
+  const tracing = createOtelTracing({ tracer, mode, ...(options.ids === false ? {} : { idGenerator }) });
+  const tool = new LookupTool(options.fail);
+  const scripted = createScriptedProvider([
+    { toolCalls: [{ name: 'lookup', args: {} }], usage: { inputTokens: 12, outputTokens: 3 } },
+    { text: 'done' },
+  ]);
+  // The scripted double neither carries trace context nor attests usage; this one does both, so the
+  // sent `traceparent` and the token counts are observable.
+  const chat = scripted.provider.chat.bind(scripted.provider);
+  const aiProvider = Object.assign(scripted.provider, {
+    canPropagateTraceContext: () => true,
+    chat: async (...args: Parameters<typeof chat>) => {
+      const message = await chat(...args);
+      return message.metadata?.['inputTokens'] === undefined
+        ? message : { ...message, metadata: { ...message.metadata, usageProvenance: 'complete' } };
+    },
+  });
+  const agent = new ConversationAgent({
+    name: 'traced',
+    aiProviders: [aiProvider],
+    defaultModel: { provider: 'scripted-test-provider', model: 'test-model' },
+    tools: [tool],
+    plugins: [tracing.plugin],
+    logging: { level: 'silent', enabled: false },
+  } as IAgentConfig);
+  cleanups.push(async () => {
+    await agent.destroy();
+    await provider.shutdown();
+  });
+  const root = tracer.startSpan('invoke_agent traced');
+  const run = tracing.startRun(root.spanContext(), { allowedOrigins: [ORIGIN], subprocessClasses: ['shell'] });
+  await agent.run('go', {
+    ...(run.traceContext ? { traceContext: run.traceContext } : {}),
+    ...(options.observe === false ? {} : { onExecutionEvent: run.onExecutionEvent }),
+  });
+  run.end();
+  root.end();
+  const spans = exporter.getFinishedSpans();
+  const sent = scripted.chatOptions.map((chat) => chat?.outboundTraceContext?.traceparent);
+  return { spans, sent, tool, root: root.spanContext(), tracing, tracer, exporter, agent };
+}
+
+const byName = (spans: ReadableSpan[], prefix: string) => spans.filter((span) => span.name.startsWith(prefix));
+const spanOf = (traceparent: string | undefined) => traceparent?.split('-')[2];
+
+describe('createOtelTracing', () => {
+  it('records provider calls and tool bodies under the host span, with the IDs Robota propagated', async () => {
+    const { spans, sent, tool, root } = await tracedRun('gen_ai');
+    const chats = byName(spans, 'chat');
+    const tools = byName(spans, 'execute_tool');
+    expect(chats.map((span) => span.name)).toEqual(['chat test-model', 'chat test-model']);
+    expect(tools.map((span) => span.name)).toEqual(['execute_tool lookup']);
+    for (const span of [...chats, ...tools]) {
+      expect(span.spanContext().traceId).toBe(root.traceId);
+      expect(span.parentSpanContext?.spanId).toBe(root.spanId);
+    }
+    // The span each recipient was told is its parent is the span the trace contains.
+    expect(chats.map((span) => span.spanContext().spanId)).toEqual(sent.map(spanOf));
+    expect(tools[0]?.spanContext().spanId).toBe(spanOf(tool.contexts[0]?.shellTraceEnv?.TRACEPARENT));
+    expect(chats[0]?.attributes).toMatchObject({
+      'gen_ai.operation.name': 'chat',
+      'gen_ai.request.model': 'test-model',
+      'gen_ai.usage.input_tokens': 12,
+      'gen_ai.usage.output_tokens': 3,
+      'agent.provider.round': 1,
+    });
+    expect(tools[0]?.attributes).toMatchObject({
+      'gen_ai.operation.name': 'execute_tool', 'gen_ai.tool.name': 'lookup', 'agent.outcome': 'success',
+    });
+    expect(tools[0]?.attributes['gen_ai.tool.call.id']).toEqual(expect.any(String));
+  });
+
+  it('names spans as the projection does in agent mode', async () => {
+    const { spans } = await tracedRun('agent');
+    expect(spans.map((span) => span.name).sort()).toEqual([
+      'agent.provider_call', 'agent.provider_call', 'agent.tool_body', 'invoke_agent traced',
+    ]);
+  });
+
+  it('records no tool body for a run it was not told about', async () => {
+    const { spans } = await tracedRun('gen_ai', { observe: false });
+    expect(spans.map((span) => span.name)).toEqual(['invoke_agent traced']);
+  });
+
+  it('marks a failed tool body as an error', async () => {
+    const { spans } = await tracedRun('gen_ai', { fail: true });
+    const [tool] = byName(spans, 'execute_tool');
+    expect(tool?.status.code).toBe(2);
+    expect(tool?.attributes).toMatchObject({ 'agent.outcome': 'failure', 'error.type': '_OTHER' });
+  });
+
+  it('keeps trace and parent without the ID generator, and says nothing about span IDs', async () => {
+    const { spans, sent, root } = await tracedRun('gen_ai', { ids: false });
+    const chats = byName(spans, 'chat');
+    expect(chats).toHaveLength(2);
+    for (const span of chats) {
+      expect(span.spanContext().traceId).toBe(root.traceId);
+      expect(span.parentSpanContext?.spanId).toBe(root.spanId);
+    }
+    expect(chats.map((span) => span.spanContext().spanId)).not.toEqual(sent.map(spanOf));
+  });
+
+  it('credits a nested agent\'s tool body to the nested run, not the traced parent run', async () => {
+    const exporter = new InMemorySpanExporter();
+    const provider = new TracerProvider({ spanProcessors: [new SimpleSpanProcessor({ exporter })] });
+    const tracer = provider.getTracer('test');
+    const tracing = createOtelTracing({ tracer, mode: 'gen_ai' });
+    const leaf = new LookupTool();
+    const config = (name: string, tools: AbstractTool[], script: ReturnType<typeof createScriptedProvider>) => ({
+      name, aiProviders: [script.provider], defaultModel: { provider: 'scripted-test-provider', model: 'm' },
+      tools, plugins: [tracing.plugin], logging: { level: 'silent', enabled: false },
+    });
+    class DelegateTool extends LookupTool {
+      override get schema(): IToolSchema {
+        return { name: 'delegate', description: 'delegate', parameters: { type: 'object' as const, properties: {} } };
+      }
+      override async execute(parameters: TToolParameters, context: IToolExecutionContext): Promise<IToolResult> {
+        // An agent built inside a tool keeps the caller's owner path, as IAgentConfig documents.
+        const child = new ConversationAgent({
+          ...config('child', [leaf], createScriptedProvider([{ toolCalls: [{ name: 'lookup', args: {} }] }, { text: 'ok' }])),
+          executionContext: { ownerPath: context.ownerPath ?? [] },
+        } as IAgentConfig);
+        await child.run('child');
+        await child.destroy();
+        return super.execute(parameters, context);
+      }
+    }
+    const parent = new ConversationAgent(config('parent', [new DelegateTool()],
+      createScriptedProvider([{ toolCalls: [{ name: 'delegate', args: {} }] }, { text: 'done' }])) as IAgentConfig);
+    const root = tracer.startSpan('root');
+    const run = tracing.startRun(root.spanContext());
+    await parent.run('go', { ...(run.traceContext ? { traceContext: run.traceContext } : {}), onExecutionEvent: run.onExecutionEvent });
+    run.end();
+    root.end();
+    await parent.destroy();
+    expect(leaf.contexts).toHaveLength(1);
+    expect(byName(exporter.getFinishedSpans(), 'execute_tool').map((span) => span.name)).toEqual(['execute_tool delegate']);
+    await provider.shutdown();
+  });
+
+  it('traces nothing and propagates nothing under a parent the host did not sample', () => {
+    const tracing = createOtelTracing({ tracer: trace.getTracer('noop'), mode: 'gen_ai' });
+    const run = tracing.startRun({ traceId: 'a'.repeat(32), spanId: 'b'.repeat(16), traceFlags: 0 });
+    expect(run.traceContext).toBeUndefined();
+  });
+
+  it('traces nothing and propagates nothing under an invalid parent', async () => {
+    const tracing = createOtelTracing({ tracer: trace.getTracer('noop'), mode: 'gen_ai' });
+    const invalid: SpanContext = { traceId: '0'.repeat(32), spanId: '0'.repeat(16), traceFlags: 0 };
+    const run = tracing.startRun(invalid);
+    expect(run.traceContext).toBeUndefined();
+    expect(() => run.onExecutionEvent('provider_call_completed', {})).not.toThrow();
+  });
+
+  it('ignores a malformed provider-call event instead of failing the run', async () => {
+    const exporter = new InMemorySpanExporter();
+    const provider = new TracerProvider({ spanProcessors: [new SimpleSpanProcessor({ exporter })] });
+    const tracer = provider.getTracer('test');
+    const tracing = createOtelTracing({ tracer, mode: 'gen_ai' });
+    const root = tracer.startSpan('root');
+    const run = tracing.startRun(root.spanContext());
+    run.onExecutionEvent('provider_call_completed', { executionId: 'e1', callId: 'not hex', outcome: 'success' });
+    run.onExecutionEvent('provider_call_completed', { executionId: 'e1', callId: '00000000-0000-4000-8000-000000000000' });
+    expect(exporter.getFinishedSpans()).toEqual([]);
+    await provider.shutdown();
+  });
+});
+
+describe('createStructuralIdGenerator', () => {
+  it('hands the chosen ID to exactly one span and random IDs otherwise', () => {
+    const ids = createStructuralIdGenerator();
+    expect(ids.withSpanId('1234567890abcdef', () => ids.generateSpanId())).toBe('1234567890abcdef');
+    expect(ids.generateSpanId()).toMatch(/^(?!0{16}$)[0-9a-f]{16}$/u);
+    ids.withSpanId('1234567890abcdef', () => undefined);
+    expect(ids.generateSpanId()).not.toBe('1234567890abcdef');
+    expect(ids.generateTraceId()).toMatch(/^(?!0{32}$)[0-9a-f]{32}$/u);
+  });
+});

package/src/index.ts

@@ -0,0 +1,31 @@
+export {
+  GEN_AI_SCHEMA_URL,
+  projectLivePromptTrace,
+  type IOtelProjectionOptions,
+  type IOtelSpanProjection,
+  type IOtelTraceProjection,
+  type TOtelAttributes,
+  type TOtelProjectionMode,
+  type TOtelSpanKind,
+} from './projection.js';
+export {
+  GEN_AI_AGENT_DURATION_BUCKETS_S,
+  GEN_AI_CALL_COUNT_BUCKETS,
+  GEN_AI_DURATION_BUCKETS_S,
+  GEN_AI_TOKEN_BUCKETS,
+  projectLivePromptMetricSamples,
+  type IOtelMetricSample,
+  type IOtelMetricSampleOptions,
+} from './metrics.js';
+export {
+  createOtelTracing,
+  type IOtelRunPropagation,
+  type IOtelRunTracing,
+  type IOtelTracing,
+  type IOtelTracingOptions,
+} from './run-tracing.js';
+export {
+  createStructuralIdGenerator,
+  type IOtelIdGenerator,
+  type IStructuralIdGenerator,
+} from './span-ids.js';

package/src/metrics.ts

@@ -0,0 +1,140 @@
+import type { ILivePromptTraceBatch, IProviderCallTraceEntry } from '@robota-sdk/agent-interface-analytics';
+
+import { genAiProviderName, label } from './projection.js';
+import type { TOtelAttributes, TOtelProjectionMode } from './projection.js';
+
+/**
+ * Bucket boundaries the GenAI conventions recommend, as pinned at semantic-conventions-genai
+ * f3c6d0c9bb66ebd474668a3a0be25c61226f02c2. A histogram needs one more count than it has boundaries,
+ * for values above the last one.
+ */
+export const GEN_AI_DURATION_BUCKETS_S: readonly number[] =
+  [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92];
+export const GEN_AI_AGENT_DURATION_BUCKETS_S: readonly number[] =
+  [0.1, 0.2, 0.4, 0.8, 1.6, 3.2, 6.4, 12.8, 25.6, 51.2, 102.4, 204.8, 409.6];
+export const GEN_AI_TOKEN_BUCKETS: readonly number[] =
+  [1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864];
+export const GEN_AI_CALL_COUNT_BUCKETS: readonly number[] = [1, 2, 4, 8, 16, 32, 64, 128];
+
+/** One measurement to record, independent of any OpenTelemetry SDK: a counter increment or a histogram value. */
+export interface IOtelMetricSample {
+  readonly name: string;
+  readonly instrument: 'counter' | 'histogram';
+  readonly unit: string;
+  readonly value: number;
+  readonly attributes: TOtelAttributes;
+  /** Explicit bucket upper bounds of a histogram; absent for a counter. */
+  readonly boundaries?: readonly number[];
+}
+
+export interface IOtelMetricSampleOptions {
+  /** The GenAI attribute set in use, as for spans: `gen_ai/dup` also keeps `agent.model.id`, `gen_ai` does not. */
+  readonly mode: Exclude<TOtelProjectionMode, 'agent'>;
+  /** Host-chosen agent name carried on the agent, tool and root metrics. */
+  readonly agentName?: string;
+}
+
+/** Same fallback value the span projection uses: the batch records that a call failed, not why. */
+const ERROR_TYPE = { 'error.type': '_OTHER' } as const;
+
+const seconds = (startedAt: string, endedAt: string): number | undefined => {
+  const value = (Date.parse(endedAt) - Date.parse(startedAt)) / 1000;
+  return Number.isFinite(value) && value >= 0 ? value : undefined;
+};
+const tokenCount = (value: unknown): number | undefined =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+
+function providerCallSamples(trace: IProviderCallTraceEntry, mode: IOtelMetricSampleOptions['mode']): IOtelMetricSample[] {
+  const providerName = genAiProviderName(trace.providerId);
+  const providerId = label(trace.providerId);
+  const model = label(trace.modelId);
+  // Same rule as the provider span: a fact the conventions do not define keeps its `agent.*` name, so an
+  // operator's provider split survives (a provider outside the known map has no `gen_ai.provider.name`);
+  // the model has a convention name, so `agent.model.id` is repeated only while both sets are emitted.
+  const base: TOtelAttributes = {
+    'gen_ai.operation.name': 'chat',
+    ...(providerName ? { 'gen_ai.provider.name': providerName } : {}),
+    ...(model ? { 'gen_ai.request.model': model } : {}),
+    ...(providerId ? { 'agent.provider.id': providerId } : {}),
+    ...(mode === 'gen_ai/dup' && model ? { 'agent.model.id': model } : {}),
+  };
+  const attributes: TOtelAttributes = trace.outcome === 'failure' ? { ...base, ...ERROR_TYPE } : base;
+  // Without a complete count the conventions ask for 0, not for a missing sample; providers do not
+  // report usage per modality, so the counters' modality is `unknown`.
+  const promptTokens = tokenCount(trace.promptTokens);
+  const completionTokens = tokenCount(trace.completionTokens);
+  const known = trace.usageProvenance === 'complete' && promptTokens !== undefined && completionTokens !== undefined;
+  const input = known ? promptTokens : 0;
+  const output = known ? completionTokens : 0;
+  const counterAttributes: TOtelAttributes = { ...base, 'gen_ai.token.modality': 'unknown' };
+  const duration = seconds(trace.startedAt, trace.endedAt);
+  const tokens = (name: string, value: number): IOtelMetricSample => ({
+    name, instrument: 'histogram', unit: '{token}', value, attributes, boundaries: GEN_AI_TOKEN_BUCKETS,
+  });
+  return [
+    ...(duration === undefined ? [] : [{
+      name: 'gen_ai.client.inference.duration', instrument: 'histogram' as const, unit: 's', value: duration,
+      attributes, boundaries: GEN_AI_DURATION_BUCKETS_S,
+    }]),
+    { name: 'gen_ai.client.inference.usage.input_tokens', instrument: 'counter', unit: '{token}', value: input, attributes: counterAttributes },
+    { name: 'gen_ai.client.inference.usage.output_tokens', instrument: 'counter', unit: '{token}', value: output, attributes: counterAttributes },
+    tokens('gen_ai.client.inference.operation.input_tokens', input),
+    tokens('gen_ai.client.inference.operation.output_tokens', output),
+  ];
+}
+
+/**
+ * Map one live prompt trace batch onto the GenAI metrics a host records: one inference measurement set
+ * per invoked provider call, one duration per tool body, and the prompt's agent-level duration and call
+ * counts. Provider-derived samples are left out when the batch omitted provider children, and
+ * tool-derived ones when it omitted tool children, because a bounded child list cannot prove a complete
+ * total. Cache hits and refused calls were not inferences, and permission decisions have no duration, so
+ * they produce nothing. Like the span projection, it is pure and content-free.
+ */
+export function projectLivePromptMetricSamples(
+  batch: ILivePromptTraceBatch, options: IOtelMetricSampleOptions,
+): IOtelMetricSample[] {
+  const agent: TOtelAttributes = options.agentName ? { 'gen_ai.agent.name': options.agentName } : {};
+  const samples: IOtelMetricSample[] = [];
+  const providerComplete = batch.omittedChildren.provider === 0;
+  const toolComplete = batch.omittedChildren.tool === 0;
+  let invokedCalls = 0;
+  let toolBodies = 0;
+
+  for (const child of batch.children) {
+    if (child.kind !== 'provider' || child.trace.disposition !== 'invoked') continue;
+    invokedCalls += 1;
+    if (providerComplete) samples.push(...providerCallSamples(child.trace, options.mode));
+  }
+  for (const child of batch.children) {
+    if (child.kind !== 'tool') continue;
+    toolBodies += 1;
+    const duration = toolComplete ? seconds(child.trace.startedAt, child.trace.endedAt) : undefined;
+    if (duration === undefined) continue;
+    const toolName = label(child.trace.toolName);
+    samples.push({
+      name: 'gen_ai.execute_tool.duration', instrument: 'histogram', unit: 's', value: duration,
+      boundaries: GEN_AI_DURATION_BUCKETS_S,
+      attributes: {
+        ...(toolName ? { 'gen_ai.tool.name': toolName } : {}), ...agent,
+        ...(child.trace.outcome === 'failure' ? ERROR_TYPE : {}),
+      },
+    });
+  }
+
+  const rootDuration = seconds(batch.root.startedAt, batch.root.endedAt);
+  if (rootDuration !== undefined) samples.push({
+    name: 'gen_ai.invoke_agent.duration', instrument: 'histogram', unit: 's', value: rootDuration,
+    boundaries: GEN_AI_AGENT_DURATION_BUCKETS_S,
+    attributes: { ...agent, ...(batch.root.outcome === 'failure' ? ERROR_TYPE : {}) },
+  });
+  if (providerComplete) samples.push({
+    name: 'gen_ai.invoke_agent.inference_calls', instrument: 'histogram', unit: '{inference_call}',
+    value: invokedCalls, attributes: agent, boundaries: GEN_AI_CALL_COUNT_BUCKETS,
+  });
+  if (toolComplete) samples.push({
+    name: 'gen_ai.invoke_agent.tool_calls', instrument: 'histogram', unit: '{tool_call}',
+    value: toolBodies, attributes: agent, boundaries: GEN_AI_CALL_COUNT_BUCKETS,
+  });
+  return samples;
+}

package/src/projection.ts

@@ -0,0 +1,216 @@
+import type {
+  ILivePromptTraceBatch,
+  IProviderCallTraceEntry,
+  IToolBodyTraceEntry,
+} from '@robota-sdk/agent-interface-analytics';
+
+import { timingAttributes } from './timing.js';
+
+/**
+ * Which names a projected span carries. `agent` keeps Robota's own `agent.*` names; `gen_ai` uses the
+ * OpenTelemetry GenAI semantic conventions; `gen_ai/dup` uses GenAI span names and emits both attribute
+ * sets, so a backend can move from one set of names to the other without a gap.
+ */
+export type TOtelProjectionMode = 'agent' | 'gen_ai/dup' | 'gen_ai';
+
+export interface IOtelProjectionOptions {
+  readonly mode: TOtelProjectionMode;
+  /** Host-chosen agent name for the root `invoke_agent` span; GenAI modes only. */
+  readonly agentName?: string;
+}
+
+export type TOtelSpanKind = 'internal' | 'client';
+export type TOtelAttributes = Readonly<Record<string, string | number>>;
+
+/** One span to record, independent of any OpenTelemetry SDK. */
+export interface IOtelSpanProjection {
+  readonly name: string;
+  readonly kind: TOtelSpanKind;
+  readonly traceId: string;
+  readonly spanId: string;
+  /** Absent on the root; every child's parent is the root. */
+  readonly parentSpanId?: string;
+  readonly startedAt: string;
+  readonly endedAt: string;
+  /** `error` for a failed outcome; an interrupted one is not an error. */
+  readonly status: 'unset' | 'error';
+  readonly attributes: TOtelAttributes;
+}
+
+export interface IOtelTraceProjection {
+  /** The schema the attribute names follow; absent in `agent` mode, whose names are Robota's own. */
+  readonly schemaUrl?: string;
+  readonly root: IOtelSpanProjection;
+  readonly children: readonly IOtelSpanProjection[];
+}
+
+/** The GenAI semantic-convention version the `gen_ai` names follow. */
+export const GEN_AI_SCHEMA_URL = 'https://opentelemetry.io/schemas/gen-ai-dev/1.42.0-dev';
+
+/** The same opaque-ID shape the framework's live-prompt-trace boundary allows through. */
+const OPAQUE_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+/** The same label shape the framework allows for provider and model labels. */
+const LABEL = /^[A-Za-z0-9._:/-]{1,128}$/u;
+
+/**
+ * Robota provider IDs whose GenAI provider name is certain. A Gemini client can point at either the
+ * Gemini API or Vertex AI, so it gets the convention's name for any Google GenAI endpoint. An ID not
+ * listed here gets no `gen_ai.provider.name` rather than a guessed one; `agent.provider.id` still names it.
+ */
+const GEN_AI_PROVIDER_NAMES: Readonly<Record<string, string>> = {
+  anthropic: 'anthropic',
+  openai: 'openai',
+  deepseek: 'deepseek',
+  gemini: 'gcp.gen_ai',
+  google: 'gcp.gen_ai',
+};
+
+const opaqueId = (value: unknown): string | undefined =>
+  typeof value === 'string' && OPAQUE_ID.test(value) ? value : undefined;
+/** A model or tool name only in the label shape the framework allows; anything else is dropped. */
+export const label = (value: unknown): string | undefined =>
+  typeof value === 'string' && LABEL.test(value) ? value : undefined;
+/** Own keys only: an inherited property such as `constructor` is not a provider. */
+export const genAiProviderName = (providerId: string | undefined): string | undefined =>
+  providerId !== undefined && Object.hasOwn(GEN_AI_PROVIDER_NAMES, providerId) ? GEN_AI_PROVIDER_NAMES[providerId] : undefined;
+const status = (outcome: string): 'unset' | 'error' => outcome === 'failure' ? 'error' : 'unset';
+const spanName = (operation: string, subject: string | undefined): string =>
+  subject ? `${operation} ${subject}` : operation;
+
+/**
+ * GenAI conventions require `error.type` on a failed operation. The batch records that a span failed
+ * but not why, so the projection uses the conventions' fallback value instead of naming a cause.
+ */
+function withErrorType(attributes: TOtelAttributes, outcome: string, mode: TOtelProjectionMode): TOtelAttributes {
+  return mode !== 'agent' && outcome === 'failure' ? { ...attributes, 'error.type': '_OTHER' } : attributes;
+}
+
+/** A provider-call or tool-body child of a trace: the children that get a span. */
+export type TSpannedChild = Exclude<ILivePromptTraceBatch['children'][number], { readonly kind: 'permission' }>;
+
+/** A permission decision is content-free but has no duration of its own — it never gets a span. */
+function hasSpan(child: ILivePromptTraceBatch['children'][number]): child is TSpannedChild {
+  return child.kind !== 'permission';
+}
+
+function rootAttributes(batch: ILivePromptTraceBatch, options: IOtelProjectionOptions): TOtelAttributes {
+  const shared = {
+    'agent.turn.id': batch.turnId,
+    'agent.outcome': batch.root.outcome,
+    'agent.omitted.provider_count': batch.omittedChildren.provider,
+    'agent.omitted.tool_count': batch.omittedChildren.tool,
+    'agent.omitted.permission_count': batch.omittedChildren.permission,
+    ...timingAttributes(batch.timingTotals),
+  };
+  const agent = { 'agent.session.id': batch.sessionId };
+  const genAi = {
+    'gen_ai.operation.name': 'invoke_agent',
+    ...(options.agentName ? { 'gen_ai.agent.name': options.agentName } : {}),
+    'gen_ai.conversation.id': batch.sessionId,
+  };
+  if (options.mode === 'agent') return { ...agent, ...shared };
+  return options.mode === 'gen_ai' ? { ...genAi, ...shared } : { ...genAi, ...agent, ...shared };
+}
+
+function providerAttributes(trace: IProviderCallTraceEntry, mode: TOtelProjectionMode): TOtelAttributes {
+  const complete = trace.usageProvenance === 'complete';
+  const requestId = opaqueId(trace.providerRequestId);
+  const agentOnly = mode !== 'gen_ai';
+  // The CLI's attribute order, with the facts GenAI names differently present only outside `gen_ai`.
+  const robota = {
+    'agent.outcome': trace.outcome,
+    'agent.provider.round': trace.round,
+    ...(trace.disposition ? { 'agent.provider.disposition': trace.disposition } : {}),
+    ...(trace.providerId ? { 'agent.provider.id': trace.providerId } : {}),
+    ...(agentOnly && trace.modelId ? { 'agent.model.id': trace.modelId } : {}),
+    ...(trace.usageProvenance ? { 'agent.usage.provenance': trace.usageProvenance } : {}),
+    ...(complete ? {
+      ...(agentOnly ? {
+        'agent.usage.input_tokens': trace.promptTokens ?? 0,
+        'agent.usage.output_tokens': trace.completionTokens ?? 0,
+      } : {}),
+      // GenAI conventions define input and output tokens but no total.
+      'agent.usage.total_tokens': trace.totalTokens ?? 0,
+    } : {}),
+    ...(requestId ? { 'agent.provider.request_id': requestId } : {}),
+  };
+  const providerName = genAiProviderName(trace.providerId);
+  const genAi = {
+    'gen_ai.operation.name': 'chat',
+    ...(providerName ? { 'gen_ai.provider.name': providerName } : {}),
+    ...(trace.modelId ? { 'gen_ai.request.model': trace.modelId } : {}),
+    ...(complete ? {
+      'gen_ai.usage.input_tokens': trace.promptTokens ?? 0,
+      'gen_ai.usage.output_tokens': trace.completionTokens ?? 0,
+    } : {}),
+  };
+  return mode === 'agent' ? robota : { ...genAi, ...robota };
+}
+
+function toolAttributes(trace: IToolBodyTraceEntry, mode: TOtelProjectionMode): TOtelAttributes {
+  const callId = opaqueId(trace.toolCallId);
+  const toolName = label(trace.toolName);
+  const shared = { 'agent.outcome': trace.outcome };
+  const agent: TOtelAttributes = callId ? { 'agent.tool.call_id': callId } : {};
+  const genAi = {
+    'gen_ai.operation.name': 'execute_tool',
+    ...(toolName ? { 'gen_ai.tool.name': toolName } : {}),
+    ...(callId ? { 'gen_ai.tool.call.id': callId } : {}),
+  };
+  if (mode === 'agent') return { ...shared, ...agent };
+  return mode === 'gen_ai' ? { ...genAi, ...shared } : { ...genAi, ...shared, ...agent };
+}
+
+/** One child's span under `parentSpanId` in trace `traceId`; shared by the batch projection and the run observer. */
+export function projectTraceChild(
+  child: TSpannedChild, traceId: string, parentSpanId: string, mode: TOtelProjectionMode,
+): IOtelSpanProjection {
+  const { trace } = child;
+  const common = {
+    traceId,
+    spanId: trace.spanId,
+    parentSpanId,
+    startedAt: trace.startedAt,
+    endedAt: trace.endedAt,
+    status: status(trace.outcome),
+  };
+  if (child.kind === 'provider') {
+    return {
+      ...common,
+      name: mode === 'agent' ? 'agent.provider_call' : spanName('chat', child.trace.modelId),
+      kind: mode === 'agent' ? 'internal' : 'client',
+      attributes: withErrorType(providerAttributes(child.trace, mode), trace.outcome, mode),
+    };
+  }
+  return {
+    ...common,
+    name: mode === 'agent' ? 'agent.tool_body' : spanName('execute_tool', label(child.trace.toolName)),
+    kind: 'internal',
+    attributes: withErrorType(toolAttributes(child.trace, mode), trace.outcome, mode),
+  };
+}
+
+/**
+ * Map one live prompt trace batch onto the spans an OpenTelemetry exporter records: the prompt root,
+ * then one child per provider call and tool body, in batch order. Permission decisions get no span.
+ * The result carries only what the batch carries, so it stays content-free.
+ */
+export function projectLivePromptTrace(
+  batch: ILivePromptTraceBatch, options: IOtelProjectionOptions,
+): IOtelTraceProjection {
+  const { mode } = options;
+  const root: IOtelSpanProjection = {
+    name: mode === 'agent' ? 'agent.prompt_execution' : spanName('invoke_agent', options.agentName),
+    kind: 'internal',
+    traceId: batch.root.traceId,
+    spanId: batch.root.spanId,
+    startedAt: batch.root.startedAt,
+    endedAt: batch.root.endedAt,
+    status: status(batch.root.outcome),
+    attributes: withErrorType(rootAttributes(batch, options), batch.root.outcome, mode),
+  };
+  // Every child belongs to the root's trace, whatever trace ID an unchecked batch gave it.
+  const children = batch.children.filter(hasSpan)
+    .map((child) => projectTraceChild(child, root.traceId, root.spanId, mode));
+  return { ...(mode === 'agent' ? {} : { schemaUrl: GEN_AI_SCHEMA_URL }), root, children };
+}