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

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@robota-sdk/agent-telemetry-otel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.0-beta.94",
+  "description": "OpenTelemetry tracing and metrics for Robota agents: content-free span projection of live prompt traces, a run observer and GenAI metric samples, with agent.* or GenAI semantic-convention names",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "node": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      },
+      "default": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@robota-sdk/agent-core": "3.0.0-beta.94",
+    "@robota-sdk/agent-interface-analytics": "3.0.0-beta.94"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-trace": "^2.11.0",
+    "@types/node": "^22.19.21",
+    "rimraf": "^5.0.10",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.6"
+  },
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "publishConfig": {
+    "access": "public"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota"
+  },
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "homepage": "https://robota.io/",
+  "scripts": {
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rimraf dist"
+  }
 }

package/src/__tests__/metrics.test.ts

@@ -0,0 +1,247 @@
+import type { ILivePromptTraceBatch } from '@robota-sdk/agent-interface-analytics';
+import { describe, expect, it } from 'vitest';
+
+import {
+  GEN_AI_AGENT_DURATION_BUCKETS_S,
+  GEN_AI_CALL_COUNT_BUCKETS,
+  GEN_AI_DURATION_BUCKETS_S,
+  GEN_AI_TOKEN_BUCKETS,
+  projectLivePromptMetricSamples,
+} from '../index.js';
+import type { IOtelMetricSample } from '../index.js';
+
+const TRACE = '0123456789abcdef0123456789abcdef';
+const ROOT = '1111111111111111';
+
+type TChild = ILivePromptTraceBatch['children'][number];
+type TProviderTrace = Extract<TChild, { kind: 'provider' }>['trace'];
+
+function provider(overrides: Partial<TProviderTrace> = {}): TChild {
+  return {
+    kind: 'provider',
+    trace: {
+      traceId: TRACE, parentSpanId: ROOT, spanId: '2222222222222222', outcome: 'success', round: 1,
+      startedAt: '2026-10-17T00:00:00.100Z', endedAt: '2026-10-17T00:00:01.300Z',
+      disposition: 'invoked', providerId: 'anthropic', modelId: 'claude-sonnet-4-5',
+      usageProvenance: 'complete', promptTokens: 120, completionTokens: 30, totalTokens: 150,
+      ...overrides,
+    },
+  };
+}
+
+function tool(overrides: Partial<Extract<TChild, { kind: 'tool' }>['trace']> = {}): TChild {
+  return {
+    kind: 'tool',
+    trace: {
+      traceId: TRACE, parentSpanId: ROOT, spanId: '3333333333333333', outcome: 'failure',
+      startedAt: '2026-10-17T00:00:01.500Z', endedAt: '2026-10-17T00:00:01.800Z',
+      toolCallId: 'toolu_01', toolName: 'Read', ...overrides,
+    },
+  };
+}
+
+function batch(children: TChild[], overrides: Partial<ILivePromptTraceBatch> = {}): ILivePromptTraceBatch {
+  return {
+    schemaVersion: 1, sessionId: 'session-1', turnId: 'turn-1',
+    root: {
+      traceId: TRACE, spanId: ROOT, outcome: 'failure',
+      startedAt: '2026-10-17T00:00:00.000Z', endedAt: '2026-10-17T00:00:03.000Z',
+    },
+    children,
+    omittedChildren: { provider: 0, tool: 0, permission: 0 },
+    ...overrides,
+  };
+}
+
+const names = (samples: IOtelMetricSample[]): string[] => samples.map((sample) => sample.name);
+const only = (samples: IOtelMetricSample[], name: string): IOtelMetricSample[] =>
+  samples.filter((sample) => sample.name === name);
+
+describe('projectLivePromptMetricSamples', () => {
+  it('projects every GenAI measurement for a rich batch', () => {
+    const permission: TChild = {
+      kind: 'permission',
+      decision: { traceId: TRACE, parentSpanId: ROOT, decidedAt: '2026-10-17T00:00:01.400Z', decision: 'allowed' },
+    };
+    const samples = projectLivePromptMetricSamples(batch([
+      provider(),
+      permission,
+      tool(),
+      provider({ outcome: 'failure', providerId: 'my-gateway', modelId: undefined, usageProvenance: 'partial',
+        promptTokens: undefined, completionTokens: undefined, totalTokens: undefined,
+        startedAt: '2026-10-17T00:00:01.900Z', endedAt: '2026-10-17T00:00:02.500Z' }),
+    ]), { mode: 'gen_ai', agentName: 'robota' });
+
+    const ok = {
+      'gen_ai.operation.name': 'chat', 'gen_ai.provider.name': 'anthropic', 'gen_ai.request.model': 'claude-sonnet-4-5',
+      'agent.provider.id': 'anthropic',
+    };
+    const failed = { 'gen_ai.operation.name': 'chat', 'agent.provider.id': 'my-gateway', 'error.type': '_OTHER' };
+    expect(samples).toEqual([
+      { name: 'gen_ai.client.inference.duration', instrument: 'histogram', unit: 's', value: 1.2, attributes: ok, boundaries: GEN_AI_DURATION_BUCKETS_S },
+      { name: 'gen_ai.client.inference.usage.input_tokens', instrument: 'counter', unit: '{token}', value: 120, attributes: { ...ok, 'gen_ai.token.modality': 'unknown' } },
+      { name: 'gen_ai.client.inference.usage.output_tokens', instrument: 'counter', unit: '{token}', value: 30, attributes: { ...ok, 'gen_ai.token.modality': 'unknown' } },
+      { name: 'gen_ai.client.inference.operation.input_tokens', instrument: 'histogram', unit: '{token}', value: 120, attributes: ok, boundaries: GEN_AI_TOKEN_BUCKETS },
+      { name: 'gen_ai.client.inference.operation.output_tokens', instrument: 'histogram', unit: '{token}', value: 30, attributes: ok, boundaries: GEN_AI_TOKEN_BUCKETS },
+      { name: 'gen_ai.client.inference.duration', instrument: 'histogram', unit: 's', value: 0.6, attributes: failed, boundaries: GEN_AI_DURATION_BUCKETS_S },
+      { name: 'gen_ai.client.inference.usage.input_tokens', instrument: 'counter', unit: '{token}', value: 0, attributes: { 'gen_ai.operation.name': 'chat', 'agent.provider.id': 'my-gateway', 'gen_ai.token.modality': 'unknown' } },
+      { name: 'gen_ai.client.inference.usage.output_tokens', instrument: 'counter', unit: '{token}', value: 0, attributes: { 'gen_ai.operation.name': 'chat', 'agent.provider.id': 'my-gateway', 'gen_ai.token.modality': 'unknown' } },
+      { name: 'gen_ai.client.inference.operation.input_tokens', instrument: 'histogram', unit: '{token}', value: 0, attributes: failed, boundaries: GEN_AI_TOKEN_BUCKETS },
+      { name: 'gen_ai.client.inference.operation.output_tokens', instrument: 'histogram', unit: '{token}', value: 0, attributes: failed, boundaries: GEN_AI_TOKEN_BUCKETS },
+      { name: 'gen_ai.execute_tool.duration', instrument: 'histogram', unit: 's', value: 0.3,
+        attributes: { 'gen_ai.tool.name': 'Read', 'gen_ai.agent.name': 'robota', 'error.type': '_OTHER' }, boundaries: GEN_AI_DURATION_BUCKETS_S },
+      { name: 'gen_ai.invoke_agent.duration', instrument: 'histogram', unit: 's', value: 3,
+        attributes: { 'gen_ai.agent.name': 'robota', 'error.type': '_OTHER' }, boundaries: GEN_AI_AGENT_DURATION_BUCKETS_S },
+      { name: 'gen_ai.invoke_agent.inference_calls', instrument: 'histogram', unit: '{inference_call}', value: 2,
+        attributes: { 'gen_ai.agent.name': 'robota' }, boundaries: GEN_AI_CALL_COUNT_BUCKETS },
+      { name: 'gen_ai.invoke_agent.tool_calls', instrument: 'histogram', unit: '{tool_call}', value: 1,
+        attributes: { 'gen_ai.agent.name': 'robota' }, boundaries: GEN_AI_CALL_COUNT_BUCKETS },
+    ]);
+  });
+
+  it('pins the recommended bucket boundaries', () => {
+    expect(GEN_AI_DURATION_BUCKETS_S).toEqual([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]);
+    expect(GEN_AI_AGENT_DURATION_BUCKETS_S).toEqual([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]);
+    expect(GEN_AI_TOKEN_BUCKETS).toEqual([1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864]);
+    expect(GEN_AI_CALL_COUNT_BUCKETS).toEqual([1, 2, 4, 8, 16, 32, 64, 128]);
+  });
+
+  it('records 0 tokens under the unknown modality unless usage is complete', () => {
+    for (const usage of [
+      { usageProvenance: 'partial' as const, promptTokens: 7, completionTokens: 3 },
+      { usageProvenance: 'absent' as const, promptTokens: undefined, completionTokens: undefined },
+      { usageProvenance: undefined, promptTokens: 7, completionTokens: 3 },
+      { usageProvenance: 'complete' as const, promptTokens: 7, completionTokens: undefined },
+      { usageProvenance: 'complete' as const, promptTokens: -1, completionTokens: 3 },
+      { usageProvenance: 'complete' as const, promptTokens: 1.5, completionTokens: 3 },
+      { usageProvenance: 'complete' as const, promptTokens: Number.MAX_SAFE_INTEGER + 1, completionTokens: 3 },
+    ]) {
+      const samples = projectLivePromptMetricSamples(batch([provider({ ...usage, totalTokens: undefined })]), { mode: 'gen_ai' });
+      const tokens = samples.filter((sample) => sample.name.includes('tokens'));
+      expect(tokens).toHaveLength(4);
+      expect(tokens.map((sample) => sample.value)).toEqual([0, 0, 0, 0]);
+      for (const counter of tokens.filter((sample) => sample.instrument === 'counter')) {
+        expect(counter.attributes).toMatchObject({ 'gen_ai.token.modality': 'unknown' });
+      }
+    }
+  });
+
+  it('keeps error.type off the token counters and the success path', () => {
+    const failed = projectLivePromptMetricSamples(batch([provider({ outcome: 'failure' })]), { mode: 'gen_ai' });
+    for (const sample of failed.filter((item) => item.name.startsWith('gen_ai.client.'))) {
+      const hasError = 'error.type' in sample.attributes;
+      expect(hasError).toBe(!sample.name.includes('.usage.'));
+    }
+    const interrupted = projectLivePromptMetricSamples(batch([provider({ outcome: 'interrupted' })]), { mode: 'gen_ai' });
+    expect(interrupted.some((item) => 'error.type' in item.attributes && item.name.startsWith('gen_ai.client.'))).toBe(false);
+  });
+
+  it('emits no provider-derived sample when provider children were omitted', () => {
+    const samples = projectLivePromptMetricSamples(
+      batch([provider(), tool()], { omittedChildren: { provider: 1, tool: 0, permission: 0 } }), { mode: 'gen_ai', agentName: 'robota' });
+    expect(names(samples)).toEqual([
+      'gen_ai.execute_tool.duration', 'gen_ai.invoke_agent.duration', 'gen_ai.invoke_agent.tool_calls',
+    ]);
+  });
+
+  it('emits no tool-derived sample when tool children were omitted', () => {
+    const samples = projectLivePromptMetricSamples(
+      batch([provider(), tool()], { omittedChildren: { provider: 0, tool: 2, permission: 0 } }), { mode: 'gen_ai', agentName: 'robota' });
+    expect(names(samples)).not.toContain('gen_ai.execute_tool.duration');
+    expect(names(samples)).not.toContain('gen_ai.invoke_agent.tool_calls');
+    expect(names(samples)).toContain('gen_ai.invoke_agent.inference_calls');
+    expect(names(samples)).toContain('gen_ai.client.inference.duration');
+  });
+
+  it('keeps the root duration when children were omitted, and counts nothing it cannot prove', () => {
+    const samples = projectLivePromptMetricSamples(
+      batch([], { omittedChildren: { provider: 3, tool: 3, permission: 0 } }), { mode: 'gen_ai' });
+    expect(names(samples)).toEqual(['gen_ai.invoke_agent.duration']);
+  });
+
+  it('excludes cache hits and refused calls from every inference measurement', () => {
+    const samples = projectLivePromptMetricSamples(batch([
+      provider({ disposition: 'cache-hit' }),
+      provider({ disposition: 'preflight-refused', outcome: 'failure' }),
+      provider({ disposition: undefined }),
+      provider(),
+    ]), { mode: 'gen_ai' });
+    expect(only(samples, 'gen_ai.client.inference.duration')).toHaveLength(1);
+    expect(only(samples, 'gen_ai.invoke_agent.inference_calls')[0]!.value).toBe(1);
+  });
+
+  it('records zero calls for a prompt without provider or tool children', () => {
+    const samples = projectLivePromptMetricSamples(batch([]), { mode: 'gen_ai' });
+    expect(only(samples, 'gen_ai.invoke_agent.inference_calls')[0]!.value).toBe(0);
+    expect(only(samples, 'gen_ai.invoke_agent.tool_calls')[0]!.value).toBe(0);
+  });
+
+  it('drops a model, tool name or provider that is not safe to label', () => {
+    const samples = projectLivePromptMetricSamples(batch([
+      provider({ modelId: 'private prompt text', providerId: 'constructor' }),
+      provider({ modelId: 'private prompt text', providerId: 'private provider text' }),
+      tool({ toolName: 'private tool output' }),
+    ]), { mode: 'gen_ai/dup', agentName: 'robota' });
+    const [constructorProvider, unsafeProvider] = only(samples, 'gen_ai.client.inference.duration');
+    // `constructor` is a label-safe id, just not a known GenAI provider name.
+    expect(constructorProvider!.attributes).toEqual({ 'gen_ai.operation.name': 'chat', 'agent.provider.id': 'constructor' });
+    expect(unsafeProvider!.attributes).toEqual({ 'gen_ai.operation.name': 'chat' });
+    expect(only(samples, 'gen_ai.execute_tool.duration')[0]!.attributes)
+      .toEqual({ 'gen_ai.agent.name': 'robota', 'error.type': '_OTHER' });
+    expect(JSON.stringify(samples)).not.toMatch(/private/u);
+  });
+
+  it('keeps the Robota provider id in both GenAI modes and the model id only in gen_ai/dup', () => {
+    const inference = (mode: 'gen_ai' | 'gen_ai/dup') => projectLivePromptMetricSamples(
+      batch([provider(), provider({ providerId: 'my-gateway', modelId: 'gateway-model' })]), { mode })
+      .filter((sample) => sample.name.startsWith('gen_ai.client.inference.'));
+    const providers = (mode: 'gen_ai' | 'gen_ai/dup') => inference(mode).map((sample) => sample.attributes['agent.provider.id']);
+    const models = (mode: 'gen_ai' | 'gen_ai/dup') => inference(mode).map((sample) => sample.attributes['agent.model.id']);
+    // All five inference metrics, for each of the two calls.
+    expect(inference('gen_ai')).toHaveLength(10);
+    for (const mode of ['gen_ai', 'gen_ai/dup'] as const) {
+      expect(providers(mode)).toEqual(['anthropic', 'anthropic', 'anthropic', 'anthropic', 'anthropic',
+        'my-gateway', 'my-gateway', 'my-gateway', 'my-gateway', 'my-gateway']);
+    }
+    expect(models('gen_ai').every((model) => model === undefined)).toBe(true);
+    expect(models('gen_ai/dup')).toEqual([
+      ...Array<string>(5).fill('claude-sonnet-4-5'), ...Array<string>(5).fill('gateway-model')]);
+    // The convention name for the model is present in both modes.
+    for (const mode of ['gen_ai', 'gen_ai/dup'] as const) {
+      expect(inference(mode).map((sample) => sample.attributes['gen_ai.request.model']))
+        .toEqual([...Array<string>(5).fill('claude-sonnet-4-5'), ...Array<string>(5).fill('gateway-model')]);
+    }
+  });
+
+  it('puts the Robota ids on no tool or agent metric', () => {
+    const samples = projectLivePromptMetricSamples(batch([provider(), tool()]), { mode: 'gen_ai/dup', agentName: 'robota' });
+    for (const sample of samples.filter((item) => !item.name.startsWith('gen_ai.client.inference.'))) {
+      expect(sample.attributes).not.toHaveProperty('agent.provider.id');
+      expect(sample.attributes).not.toHaveProperty('agent.model.id');
+    }
+  });
+
+  it('names a Gemini or Google provider with the convention name for any Google endpoint', () => {
+    const [gemini, google] = ['gemini', 'google'].map((providerId) =>
+      only(projectLivePromptMetricSamples(batch([provider({ providerId })]), { mode: 'gen_ai' }), 'gen_ai.client.inference.duration')[0]!);
+    expect(gemini!.attributes).toMatchObject({ 'gen_ai.provider.name': 'gcp.gen_ai' });
+    expect(google!.attributes).toMatchObject({ 'gen_ai.provider.name': 'gcp.gen_ai' });
+  });
+
+  it('omits the agent name when the host gives none and drops unmeasurable durations', () => {
+    const samples = projectLivePromptMetricSamples(batch([
+      tool({ startedAt: 'not a time' }),
+      provider({ endedAt: '2026-10-16T00:00:00.000Z' }),
+    ], { root: { traceId: TRACE, spanId: ROOT, outcome: 'success', startedAt: '2026-10-17T00:00:03.000Z', endedAt: '2026-10-17T00:00:00.000Z' } }), { mode: 'gen_ai' });
+    expect(names(samples)).not.toContain('gen_ai.execute_tool.duration');
+    expect(names(samples)).not.toContain('gen_ai.client.inference.duration');
+    expect(names(samples)).not.toContain('gen_ai.invoke_agent.duration');
+    expect(only(samples, 'gen_ai.invoke_agent.tool_calls')[0]!.attributes).toEqual({});
+  });
+
+  it('is pure: the same batch and options project to equal samples', () => {
+    const input = batch([provider(), tool()]);
+    expect(projectLivePromptMetricSamples(input, { mode: 'gen_ai', agentName: 'robota' }))
+      .toEqual(projectLivePromptMetricSamples(input, { mode: 'gen_ai', agentName: 'robota' }));
+  });
+});

package/src/__tests__/projection.test.ts

@@ -0,0 +1,262 @@
+import type { ILivePromptTraceBatch } from '@robota-sdk/agent-interface-analytics';
+import { describe, expect, it } from 'vitest';
+
+import { GEN_AI_SCHEMA_URL, projectLivePromptTrace } from '../index.js';
+
+const TRACE = '0123456789abcdef0123456789abcdef';
+const ROOT = '1111111111111111';
+const PROVIDER = '2222222222222222';
+const TOOL = '3333333333333333';
+
+function batch(overrides: Partial<ILivePromptTraceBatch> = {}): ILivePromptTraceBatch {
+  return {
+    schemaVersion: 1,
+    sessionId: 'session-1',
+    turnId: 'turn-1',
+    root: {
+      traceId: TRACE, spanId: ROOT, outcome: 'failure',
+      startedAt: '2026-10-17T00:00:00.000Z', endedAt: '2026-10-17T00:00:03.000Z',
+    },
+    timingTotals: {
+      provider: { durationMs: 1200, samples: 1, invalid: 0 },
+      tool: { durationMs: 300, samples: 1, invalid: 0 },
+      queue: { durationMs: 5, samples: 1, invalid: 0, admissionStarted: 1, notDispatched: 0 },
+    },
+    children: [
+      {
+        kind: 'provider',
+        trace: {
+          traceId: TRACE, parentSpanId: ROOT, spanId: PROVIDER, outcome: 'success', round: 1,
+          startedAt: '2026-10-17T00:00:00.100Z', endedAt: '2026-10-17T00:00:01.300Z',
+          disposition: 'invoked', providerId: 'anthropic', modelId: 'claude-sonnet-4-5',
+          usageProvenance: 'complete', promptTokens: 120, completionTokens: 30, totalTokens: 150,
+          providerRequestId: 'req_01',
+        },
+      },
+      {
+        kind: 'permission',
+        decision: { traceId: TRACE, parentSpanId: ROOT, decidedAt: '2026-10-17T00:00:01.400Z', decision: 'allowed' },
+      },
+      {
+        kind: 'tool',
+        trace: {
+          traceId: TRACE, parentSpanId: ROOT, spanId: TOOL, outcome: 'failure',
+          startedAt: '2026-10-17T00:00:01.500Z', endedAt: '2026-10-17T00:00:01.800Z',
+          toolCallId: 'toolu_01', toolName: 'Read',
+        },
+      },
+    ],
+    omittedChildren: { provider: 0, tool: 1, permission: 2 },
+    ...overrides,
+  };
+}
+
+const ROOT_TIMING = {
+  'agent.timing.provider.duration_ms': 1200,
+  'agent.timing.provider.samples': 1,
+  'agent.timing.provider.invalid': 0,
+  'agent.timing.tool.duration_ms': 300,
+  'agent.timing.tool.samples': 1,
+  'agent.timing.tool.invalid': 0,
+  'agent.timing.queue.duration_ms': 5,
+  'agent.timing.queue.samples': 1,
+  'agent.timing.queue.invalid': 0,
+  'agent.timing.queue.admission_started': 1,
+  'agent.timing.queue.not_dispatched': 0,
+};
+const ROOT_SHARED = {
+  'agent.turn.id': 'turn-1',
+  'agent.outcome': 'failure',
+  'agent.omitted.provider_count': 0,
+  'agent.omitted.tool_count': 1,
+  'agent.omitted.permission_count': 2,
+  ...ROOT_TIMING,
+};
+const PROVIDER_SHARED = {
+  'agent.outcome': 'success',
+  'agent.provider.round': 1,
+  'agent.provider.disposition': 'invoked',
+  'agent.provider.id': 'anthropic',
+  'agent.usage.provenance': 'complete',
+  'agent.usage.total_tokens': 150,
+  'agent.provider.request_id': 'req_01',
+};
+const PROVIDER_AGENT = {
+  'agent.model.id': 'claude-sonnet-4-5',
+  'agent.usage.input_tokens': 120,
+  'agent.usage.output_tokens': 30,
+};
+const PROVIDER_GEN_AI = {
+  'gen_ai.operation.name': 'chat',
+  'gen_ai.provider.name': 'anthropic',
+  'gen_ai.request.model': 'claude-sonnet-4-5',
+  'gen_ai.usage.input_tokens': 120,
+  'gen_ai.usage.output_tokens': 30,
+};
+const TOOL_GEN_AI = {
+  'gen_ai.operation.name': 'execute_tool',
+  'gen_ai.tool.name': 'Read',
+  'gen_ai.tool.call.id': 'toolu_01',
+};
+
+describe('projectLivePromptTrace', () => {
+  it('reproduces the CLI agent.* spans in agent mode, skipping permission decisions', () => {
+    expect(projectLivePromptTrace(batch(), { mode: 'agent' })).toEqual({
+      root: {
+        name: 'agent.prompt_execution', kind: 'internal', traceId: TRACE, spanId: ROOT, status: 'error',
+        startedAt: '2026-10-17T00:00:00.000Z', endedAt: '2026-10-17T00:00:03.000Z',
+        attributes: { 'agent.session.id': 'session-1', ...ROOT_SHARED },
+      },
+      children: [
+        {
+          name: 'agent.provider_call', kind: 'internal', traceId: TRACE, spanId: PROVIDER, parentSpanId: ROOT,
+          status: 'unset', startedAt: '2026-10-17T00:00:00.100Z', endedAt: '2026-10-17T00:00:01.300Z',
+          attributes: { ...PROVIDER_SHARED, ...PROVIDER_AGENT },
+        },
+        {
+          name: 'agent.tool_body', kind: 'internal', traceId: TRACE, spanId: TOOL, parentSpanId: ROOT,
+          status: 'error', startedAt: '2026-10-17T00:00:01.500Z', endedAt: '2026-10-17T00:00:01.800Z',
+          attributes: { 'agent.outcome': 'failure', 'agent.tool.call_id': 'toolu_01' },
+        },
+      ],
+    });
+  });
+
+  it('keeps the CLI attribute order and no error.type in agent mode', () => {
+    const projection = projectLivePromptTrace(batch(), { mode: 'agent' });
+    expect(Object.keys(projection.children[0]?.attributes ?? {})).toEqual([
+      'agent.outcome', 'agent.provider.round', 'agent.provider.disposition', 'agent.provider.id', 'agent.model.id',
+      'agent.usage.provenance', 'agent.usage.input_tokens', 'agent.usage.output_tokens', 'agent.usage.total_tokens',
+      'agent.provider.request_id',
+    ]);
+    expect(Object.keys(projection.root.attributes).slice(0, 3)).toEqual([
+      'agent.session.id', 'agent.turn.id', 'agent.outcome',
+    ]);
+    expect(projection.root.attributes).not.toHaveProperty('error.type');
+  });
+
+  it('puts every child in the root trace, as children of the root', () => {
+    const base = batch();
+    const projection = projectLivePromptTrace(batch({
+      children: [{
+        kind: 'tool',
+        trace: { ...(base.children[2] as { trace: object }).trace, traceId: 'f'.repeat(32), parentSpanId: '4'.repeat(16) } as never,
+      }],
+    }), { mode: 'agent' });
+    expect(projection.children[0]).toMatchObject({ traceId: TRACE, parentSpanId: ROOT });
+  });
+
+  it('uses GenAI span names, kinds and attributes in gen_ai mode, keeping Robota-only facts as agent.*', () => {
+    const projection = projectLivePromptTrace(batch(), { mode: 'gen_ai', agentName: 'robota' });
+    expect(projection.schemaUrl).toBe(GEN_AI_SCHEMA_URL);
+    expect(projection.root).toMatchObject({ name: 'invoke_agent robota', kind: 'internal' });
+    expect(projection.root.attributes).toEqual({
+      'gen_ai.operation.name': 'invoke_agent',
+      'gen_ai.agent.name': 'robota',
+      'gen_ai.conversation.id': 'session-1',
+      ...ROOT_SHARED,
+      'error.type': '_OTHER',
+    });
+    const [provider, tool] = projection.children;
+    expect(provider).toMatchObject({ name: 'chat claude-sonnet-4-5', kind: 'client', parentSpanId: ROOT });
+    expect(provider?.attributes).toEqual({ ...PROVIDER_GEN_AI, ...PROVIDER_SHARED });
+    expect(tool).toMatchObject({ name: 'execute_tool Read', kind: 'internal', status: 'error' });
+    expect(tool?.attributes).toEqual({ ...TOOL_GEN_AI, 'agent.outcome': 'failure', 'error.type': '_OTHER' });
+  });
+
+  it('emits both attribute sets under GenAI names in gen_ai/dup mode', () => {
+    const projection = projectLivePromptTrace(batch(), { mode: 'gen_ai/dup', agentName: 'robota' });
+    expect(projection.schemaUrl).toBe(GEN_AI_SCHEMA_URL);
+    expect(projection.root.name).toBe('invoke_agent robota');
+    expect(projection.root.attributes).toEqual({
+      'gen_ai.operation.name': 'invoke_agent',
+      'gen_ai.agent.name': 'robota',
+      'gen_ai.conversation.id': 'session-1',
+      'agent.session.id': 'session-1',
+      ...ROOT_SHARED,
+      'error.type': '_OTHER',
+    });
+    const [provider, tool] = projection.children;
+    expect(provider?.kind).toBe('client');
+    expect(provider?.attributes).toEqual({ ...PROVIDER_GEN_AI, ...PROVIDER_SHARED, ...PROVIDER_AGENT });
+    expect(tool?.attributes).toEqual({
+      ...TOOL_GEN_AI, 'agent.outcome': 'failure', 'agent.tool.call_id': 'toolu_01', 'error.type': '_OTHER',
+    });
+  });
+
+  it('falls back to bare operation names when the agent, model or tool name is unknown', () => {
+    const base = batch();
+    const projection = projectLivePromptTrace(batch({
+      children: [
+        { kind: 'provider', trace: { ...(base.children[0] as { trace: object }).trace, modelId: undefined } as never },
+        { kind: 'tool', trace: { ...(base.children[2] as { trace: object }).trace, toolName: 'bad name\n' } as never },
+      ],
+    }), { mode: 'gen_ai' });
+    expect(projection.root.name).toBe('invoke_agent');
+    expect(projection.root.attributes).not.toHaveProperty('gen_ai.agent.name');
+    expect(projection.children.map((child) => child.name)).toEqual(['chat', 'execute_tool']);
+    expect(projection.children[0]?.attributes).not.toHaveProperty('gen_ai.request.model');
+    expect(projection.children[1]?.attributes).not.toHaveProperty('gen_ai.tool.name');
+  });
+
+  it.each([
+    ['anthropic', 'anthropic'],
+    ['openai', 'openai'],
+    ['deepseek', 'deepseek'],
+    ['gemini', 'gcp.gen_ai'],
+    ['google', 'gcp.gen_ai'],
+    ['qwen', undefined],
+    ['my-gateway', undefined],
+  ])('names provider %s as GenAI provider %s', (providerId, expected) => {
+    const base = batch();
+    const projection = projectLivePromptTrace(batch({
+      children: [{ kind: 'provider', trace: { ...(base.children[0] as { trace: object }).trace, providerId } as never }],
+    }), { mode: 'gen_ai' });
+    expect(projection.children[0]?.attributes['gen_ai.provider.name']).toBe(expected);
+    expect(projection.children[0]?.attributes['agent.provider.id']).toBe(providerId);
+  });
+
+  it.each(['constructor', 'hasOwnProperty'])('does not mistake the inherited property %s for a known provider', (providerId) => {
+    const base = batch();
+    for (const mode of ['gen_ai', 'gen_ai/dup'] as const) {
+      const projection = projectLivePromptTrace(batch({
+        children: [{ kind: 'provider', trace: { ...(base.children[0] as { trace: object }).trace, providerId } as never }],
+      }), { mode });
+      expect(projection.children[0]?.attributes).not.toHaveProperty('gen_ai.provider.name');
+      expect(projection.children[0]?.attributes['agent.provider.id']).toBe(providerId);
+    }
+  });
+
+  it('omits token counts unless usage is complete, and drops IDs outside the opaque-ID shape', () => {
+    const base = batch();
+    const projection = projectLivePromptTrace(batch({
+      children: [
+        {
+          kind: 'provider',
+          trace: {
+            ...(base.children[0] as { trace: object }).trace,
+            usageProvenance: 'partial', providerRequestId: 'req 01\nsecret',
+          } as never,
+        },
+        { kind: 'tool', trace: { ...(base.children[2] as { trace: object }).trace, toolCallId: 'x'.repeat(129) } as never },
+      ],
+    }), { mode: 'gen_ai/dup' });
+    const [provider, tool] = projection.children;
+    expect(Object.keys(provider?.attributes ?? {}).filter((key) => key.includes('tokens'))).toEqual([]);
+    expect(provider?.attributes).not.toHaveProperty('agent.provider.request_id');
+    expect(tool?.attributes).not.toHaveProperty('agent.tool.call_id');
+    expect(tool?.attributes).not.toHaveProperty('gen_ai.tool.call.id');
+  });
+
+  it('drops malformed timing totals and treats an interrupted outcome as no error', () => {
+    const projection = projectLivePromptTrace(batch({
+      root: { ...batch().root, outcome: 'interrupted' },
+      timingTotals: { provider: { durationMs: 5, samples: 0, invalid: 0 }, tool: { durationMs: -1, samples: 1, invalid: 0 } },
+      children: [],
+    }), { mode: 'agent' });
+    expect(projection.root.status).toBe('unset');
+    expect(Object.keys(projection.root.attributes).filter((key) => key.startsWith('agent.timing.'))).toEqual([]);
+    expect(projection.children).toEqual([]);
+    expect(projection).not.toHaveProperty('schemaUrl');
+  });
+});