autotel 3.2.0 → 3.3.1

package/skills/review-otel-patterns/SKILL.md

@@ -7,6 +7,7 @@ description: >
   missing span attributes, manual exporter setup, broken context propagation, exposed PII, and ad-hoc
   error handling. Covers spans, metrics, logs, structured errors, the autotel processor pipeline
   (tail-sampling, attribute redaction, span-name normalisation, filtering, baggage),
+  built-in enrichers (user agent, geo, request size) and custom `defineEnricher`,
   `defineWorkerFetch` for Cloudflare async drains, multi-vendor OTLP backends (Honeycomb, Datadog,
   Grafana Cloud, Sentry, Axiom, HyperDX), `composeSpanProcessors` / `composeSubscribers` /
   `composePostProcessors` for pipelines, AI SDK observability with gen-ai semantic conventions, and
@@ -232,6 +233,49 @@ All options work with `init()`, framework adapters, and `wrapModule` / `defineWo
 
 ---
 
+## Built-in enrichers
+
+Enrichers turn raw request data into standard, low-cardinality span attributes. Import the helpers from `autotel/enrichers` and spread their output onto the active span or request logger. Each returns `undefined` when there is nothing to add, so spreading is safe.
+
+| Helper                                 | Returns attributes                                                           | Source                          |
+| -------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------- |
+| `userAgent(headers)`                   | `user_agent.raw`, `user_agent.browser`, `user_agent.os`, `user_agent.device` | `user-agent` request header     |
+| `geo(headers)`                         | `geo.country`, `geo.region`, `geo.city`, `geo.latitude`, `geo.longitude`     | Vercel / Cloudflare geo headers |
+| `requestSize(reqHeaders, resHeaders?)` | `http.request.body.size`, `http.response.body.size`                          | `content-length` headers        |
+
+```typescript
+import { userAgent, geo, requestSize } from 'autotel/enrichers';
+
+export const handler = trace((ctx) => async (request: Request) => {
+  ctx.setAttributes({
+    ...userAgent(request.headers),
+    ...geo(request.headers),
+    ...requestSize(request.headers),
+  });
+  // ... handle request
+});
+```
+
+For your own derived fields on a request's wide event, build a reusable enricher with `defineEnricher` (from `autotel`) instead of scattering ad-hoc field writes. `compute` returns an object that is merged into the named `field`; return `undefined` to skip. Keep the output low-cardinality (bucket or hash high-cardinality values):
+
+```typescript
+import { defineEnricher } from 'autotel';
+
+// Merge a derived, low-cardinality object into event.user on each request.
+const enrichTier = defineEnricher<
+  { user?: { plan?: string } },
+  { tier: string }
+>({
+  name: 'user-tier',
+  field: 'user',
+  compute: ({ event }) => ({ tier: event.user?.plan ?? 'anonymous' }),
+});
+```
+
+**Review checks:** raw `User-Agent` strings stored verbatim (use `userAgent()` to parse), geo data hand-parsed per framework (use `geo()`), and high-cardinality values (full URLs, emails, ids) set directly as attributes instead of being bucketed or hashed.
+
+---
+
 ## Backends (multi-vendor OTLP)
 
 Switch backends with **no code changes** — autotel speaks OTLP HTTP/JSON and HTTP/protobuf out of the box.

package/src/error-catalog.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import {
+  defineErrorCatalog,
+  defineAuditCatalog,
+  isCatalogError,
+  getCatalogCode,
+} from './error-catalog';
+
+describe('defineErrorCatalog', () => {
+  const billing = defineErrorCatalog('billing', {
+    PAYMENT_DECLINED: {
+      status: 402,
+      message: 'Card declined',
+      why: 'The issuer rejected the charge',
+      fix: 'Try a different payment method',
+      link: 'https://docs.example.com/billing',
+    },
+    INSUFFICIENT_FUNDS: {
+      status: 402,
+      message: ({
+        available,
+        required,
+      }: {
+        available: number;
+        required: number;
+      }) => `Insufficient funds: $${available} of $${required}`,
+      why: ({ required }: { available: number; required: number }) =>
+        `Needs $${required}`,
+    },
+    LEGACY: {
+      code: 'BILLING_LEGACY_42',
+      message: 'Legacy failure',
+    },
+  });
+
+  it('builds a structured error from a static entry', () => {
+    const err = billing.PAYMENT_DECLINED();
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toBe('Card declined');
+    expect(err.status).toBe(402);
+    expect(err.why).toBe('The issuer rejected the charge');
+    expect(err.fix).toBe('Try a different payment method');
+    expect(err.link).toBe('https://docs.example.com/billing');
+    expect(err.code).toBe('billing.PAYMENT_DECLINED');
+    expect(err.name).toBe('PAYMENT_DECLINED');
+  });
+
+  it('interpolates typed params in message and why', () => {
+    const err = billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });
+    expect(err.message).toBe('Insufficient funds: $5 of $100');
+    expect(err.why).toBe('Needs $100');
+  });
+
+  it('honors a custom code', () => {
+    const err = billing.LEGACY();
+    expect(err.code).toBe('BILLING_LEGACY_42');
+  });
+
+  it('exposes the code on the builder', () => {
+    expect(billing.PAYMENT_DECLINED.code).toBe('billing.PAYMENT_DECLINED');
+    expect(billing.LEGACY.code).toBe('BILLING_LEGACY_42');
+  });
+
+  it('matches its own errors and rejects others', () => {
+    const declined = billing.PAYMENT_DECLINED();
+    const funds = billing.INSUFFICIENT_FUNDS({ available: 1, required: 2 });
+    expect(billing.PAYMENT_DECLINED.match(declined)).toBe(true);
+    expect(billing.PAYMENT_DECLINED.match(funds)).toBe(false);
+    expect(billing.PAYMENT_DECLINED.match(new Error('nope'))).toBe(false);
+    expect(billing.PAYMENT_DECLINED.match(null)).toBe(false);
+  });
+
+  it('tags errors so isCatalogError / getCatalogCode work', () => {
+    const err = billing.PAYMENT_DECLINED();
+    expect(isCatalogError(err)).toBe(true);
+    expect(isCatalogError(new Error('plain'))).toBe(false);
+    expect(getCatalogCode(err)).toBe('billing.PAYMENT_DECLINED');
+    expect(getCatalogCode(new Error('plain'))).toBeUndefined();
+  });
+
+  it('passes cause, details, and internal through build options', () => {
+    const cause = new Error('stripe boom');
+    const err = billing.PAYMENT_DECLINED({
+      cause,
+      details: { attempt: 2 },
+      internal: { stripeId: 'ch_1' },
+    });
+    expect(err.cause).toBe(cause);
+    expect(err.details).toEqual({ attempt: 2 });
+    expect(err.internal).toEqual({ stripeId: 'ch_1' });
+  });
+
+  it('accepts options as the second arg for param entries', () => {
+    const cause = new Error('root');
+    const err = billing.INSUFFICIENT_FUNDS(
+      { available: 5, required: 100 },
+      { cause },
+    );
+    expect(err.message).toBe('Insufficient funds: $5 of $100');
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('defineAuditCatalog', () => {
+  const audit = defineAuditCatalog('user', {
+    LOGIN: { message: 'User logged in' },
+    ROLE_CHANGED: {
+      severity: 'critical',
+      message: ({ role }: { role: string }) => `Role set to ${role}`,
+    },
+    DELETED: { action: 'user.account.deleted', severity: 'warn' },
+  });
+
+  it('produces typed action descriptors with defaults', () => {
+    const action = audit.LOGIN();
+    expect(action.action).toBe('user.LOGIN');
+    expect(action.severity).toBe('info');
+    expect(action.message).toBe('User logged in');
+  });
+
+  it('interpolates params and respects severity', () => {
+    const action = audit.ROLE_CHANGED({ role: 'admin' });
+    expect(action.action).toBe('user.ROLE_CHANGED');
+    expect(action.severity).toBe('critical');
+    expect(action.message).toBe('Role set to admin');
+  });
+
+  it('honors a custom action name', () => {
+    expect(audit.DELETED.action).toBe('user.account.deleted');
+    expect(audit.DELETED.severity).toBe('warn');
+    expect(audit.DELETED().message).toBeUndefined();
+  });
+});

package/src/error-catalog.ts

@@ -0,0 +1,262 @@
+/**
+ * Typed error and audit catalogs.
+ *
+ * Group related errors into one catalog and get a refactor-safe builder per
+ * code, with autocomplete at every call site and typed message parameters.
+ *
+ * @example
+ * ```typescript
+ * import { defineErrorCatalog } from 'autotel';
+ *
+ * export const billing = defineErrorCatalog('billing', {
+ *   PAYMENT_DECLINED: {
+ *     status: 402,
+ *     message: 'Card declined',
+ *     why: 'The issuer rejected the charge',
+ *     fix: 'Try a different payment method',
+ *   },
+ *   INSUFFICIENT_FUNDS: {
+ *     status: 402,
+ *     message: ({ available, required }: { available: number; required: number }) =>
+ *       `Insufficient funds: $${available} of $${required}`,
+ *   },
+ * });
+ *
+ * throw billing.PAYMENT_DECLINED({ cause: stripeError });
+ * throw billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });
+ *
+ * // In a catch block — refactor-safe, no magic strings:
+ * if (billing.PAYMENT_DECLINED.match(err)) { ... }
+ * ```
+ */
+
+import {
+  createStructuredError,
+  type StructuredError,
+} from './structured-error';
+
+const catalogCodeKey = Symbol.for('autotel.catalog.code');
+
+/** Definition of a single error in a catalog. */
+export interface ErrorCatalogEntry {
+  /**
+   * Human-readable message. Use a function to interpolate typed parameters;
+   * the parameter type flows through to the call site.
+   */
+  message: string | ((params: never) => string);
+  /** HTTP status to surface to clients. */
+  status?: number;
+  /** Stable error code. Defaults to `${namespace}.${KEY}`. */
+  code?: string | number;
+  /** Why it happened. A function receives the same params as `message`. */
+  why?: string | ((params: never) => string);
+  /** What the caller should do next. */
+  fix?: string;
+  /** Docs or runbook link. */
+  link?: string;
+  /** Error name. Defaults to the catalog key. */
+  name?: string;
+}
+
+/** Per-call options passed alongside (or instead of) typed params. */
+export interface ErrorBuildOptions {
+  cause?: unknown;
+  details?: Record<string, unknown>;
+  /** Backend-only context. Never serialized to clients. */
+  internal?: Record<string, unknown>;
+}
+
+type ParamsOf<E> = E extends { message: (params: infer P) => string }
+  ? P
+  : E extends { why: (params: infer P) => string }
+    ? P
+    : void;
+
+type BuilderArgs<E extends ErrorCatalogEntry> =
+  ParamsOf<E> extends void
+    ? [options?: ErrorBuildOptions]
+    : [params: ParamsOf<E>, options?: ErrorBuildOptions];
+
+/** A callable error factory produced by {@link defineErrorCatalog}. */
+export interface ErrorBuilder<E extends ErrorCatalogEntry> {
+  (...args: BuilderArgs<E>): StructuredError;
+  /** Stable code assigned to every error from this entry. */
+  readonly code: string | number;
+  /** True when `error` was produced by this catalog entry. */
+  match(error: unknown): boolean;
+}
+
+export type ErrorCatalog<T extends Record<string, ErrorCatalogEntry>> = {
+  readonly [K in keyof T]: ErrorBuilder<T[K]>;
+};
+
+function readCatalogCode(error: unknown): string | number | undefined {
+  if (error === null || typeof error !== 'object') return undefined;
+  return (error as Record<symbol, unknown>)[catalogCodeKey] as
+    | string
+    | number
+    | undefined;
+}
+
+/** True when `error` was produced by any autotel error catalog. */
+export function isCatalogError(error: unknown): error is StructuredError {
+  return readCatalogCode(error) !== undefined;
+}
+
+/** Returns the catalog code of `error`, or `undefined` if it has none. */
+export function getCatalogCode(error: unknown): string | number | undefined {
+  return readCatalogCode(error);
+}
+
+/**
+ * Define a typed error catalog. Returns an object whose keys are error
+ * builders. Each builder produces a {@link StructuredError} carrying the
+ * entry's message, status, code, why, fix, and link.
+ */
+export function defineErrorCatalog<
+  const T extends Record<string, ErrorCatalogEntry>,
+>(namespace: string, entries: T): ErrorCatalog<T> {
+  const catalog: Record<string, ErrorBuilder<ErrorCatalogEntry>> = {};
+
+  for (const [key, entry] of Object.entries(entries) as [
+    string,
+    ErrorCatalogEntry,
+  ][]) {
+    const code = entry.code ?? `${namespace}.${key}`;
+    const usesParams =
+      typeof entry.message === 'function' || typeof entry.why === 'function';
+
+    const builder = ((
+      paramsOrOptions?: unknown,
+      maybeOptions?: ErrorBuildOptions,
+    ): StructuredError => {
+      const params = usesParams ? paramsOrOptions : undefined;
+      const options = (usesParams ? maybeOptions : paramsOrOptions) as
+        | ErrorBuildOptions
+        | undefined;
+
+      const message =
+        typeof entry.message === 'function'
+          ? (entry.message as (p: unknown) => string)(params)
+          : entry.message;
+      const why =
+        typeof entry.why === 'function'
+          ? (entry.why as (p: unknown) => string)(params)
+          : entry.why;
+
+      const error = createStructuredError({
+        message,
+        name: entry.name ?? key,
+        code,
+        ...(entry.status === undefined ? {} : { status: entry.status }),
+        ...(why === undefined ? {} : { why }),
+        ...(entry.fix === undefined ? {} : { fix: entry.fix }),
+        ...(entry.link === undefined ? {} : { link: entry.link }),
+        ...(options?.cause === undefined ? {} : { cause: options.cause }),
+        ...(options?.details === undefined ? {} : { details: options.details }),
+        ...(options?.internal === undefined
+          ? {}
+          : { internal: options.internal }),
+      });
+
+      Object.defineProperty(error, catalogCodeKey, {
+        value: code,
+        enumerable: false,
+        writable: false,
+        configurable: true,
+      });
+
+      return error;
+    }) as ErrorBuilder<ErrorCatalogEntry>;
+
+    Object.defineProperty(builder, 'code', {
+      value: code,
+      enumerable: true,
+    });
+    Object.defineProperty(builder, 'match', {
+      value: (error: unknown): boolean => readCatalogCode(error) === code,
+      enumerable: false,
+    });
+
+    catalog[key] = builder;
+  }
+
+  return Object.freeze(catalog) as ErrorCatalog<T>;
+}
+
+/** Severity of an audit action. */
+export type AuditSeverity = 'info' | 'warn' | 'critical';
+
+/** Definition of a single action in an audit catalog. */
+export interface AuditCatalogEntry {
+  /** Human-readable description. Use a function for typed params. */
+  message?: string | ((params: never) => string);
+  /** Stable action name. Defaults to `${namespace}.${KEY}`. */
+  action?: string;
+  /** Severity of the action. Defaults to `'info'`. */
+  severity?: AuditSeverity;
+}
+
+/** A resolved audit action descriptor produced by an audit catalog. */
+export interface AuditAction {
+  readonly action: string;
+  readonly severity: AuditSeverity;
+  readonly message?: string;
+}
+
+type AuditDescriptorArgs<E extends AuditCatalogEntry> =
+  ParamsOf<E> extends void ? [] : [params: ParamsOf<E>];
+
+/** A callable audit-action descriptor produced by {@link defineAuditCatalog}. */
+export interface AuditDescriptor<E extends AuditCatalogEntry> {
+  (...args: AuditDescriptorArgs<E>): AuditAction;
+  readonly action: string;
+  readonly severity: AuditSeverity;
+}
+
+export type AuditCatalog<T extends Record<string, AuditCatalogEntry>> = {
+  readonly [K in keyof T]: AuditDescriptor<T[K]>;
+};
+
+/**
+ * Define a typed audit catalog. Returns typed action descriptors you can pass
+ * to `track()` or audit helpers without scattering magic strings.
+ */
+export function defineAuditCatalog<
+  const T extends Record<string, AuditCatalogEntry>,
+>(namespace: string, entries: T): AuditCatalog<T> {
+  const catalog: Record<string, AuditDescriptor<AuditCatalogEntry>> = {};
+
+  for (const [key, entry] of Object.entries(entries) as [
+    string,
+    AuditCatalogEntry,
+  ][]) {
+    const action = entry.action ?? `${namespace}.${key}`;
+    const severity: AuditSeverity = entry.severity ?? 'info';
+
+    const descriptor = ((params?: unknown): AuditAction => {
+      const message =
+        typeof entry.message === 'function'
+          ? (entry.message as (p: unknown) => string)(params)
+          : entry.message;
+      return Object.freeze({
+        action,
+        severity,
+        ...(message === undefined ? {} : { message }),
+      });
+    }) as AuditDescriptor<AuditCatalogEntry>;
+
+    Object.defineProperty(descriptor, 'action', {
+      value: action,
+      enumerable: true,
+    });
+    Object.defineProperty(descriptor, 'severity', {
+      value: severity,
+      enumerable: true,
+    });
+
+    catalog[key] = descriptor;
+  }
+
+  return Object.freeze(catalog) as AuditCatalog<T>;
+}

package/src/gen-ai-cost.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  estimateLLMCost,
+  recordLLMCost,
+  GEN_AI_COST_ATTRIBUTE,
+} from './gen-ai-cost';
+
+describe('estimateLLMCost', () => {
+  it('estimates cost from input and output tokens', () => {
+    // claude-sonnet-4: $3 / 1M in, $15 / 1M out
+    const cost = estimateLLMCost('claude-sonnet-4', {
+      inputTokens: 1_000_000,
+      outputTokens: 1_000_000,
+    });
+    expect(cost).toBe(18);
+  });
+
+  it('matches versioned model ids by longest prefix', () => {
+    const cost = estimateLLMCost('claude-sonnet-4-6-20251101', {
+      inputTokens: 1_000_000,
+      outputTokens: 0,
+    });
+    expect(cost).toBe(3);
+  });
+
+  it('returns undefined for an unknown model', () => {
+    expect(
+      estimateLLMCost('totally-made-up', { inputTokens: 1000 }),
+    ).toBeUndefined();
+  });
+
+  it('bills cached input tokens at the cached rate', () => {
+    const pricing = {
+      custom: { inputPer1M: 10, outputPer1M: 30, cachedInputPer1M: 1 },
+    };
+    // 1M input, of which 800k cached: 200k @ $10/M + 800k @ $1/M = 2 + 0.8
+    const cost = estimateLLMCost(
+      'custom',
+      { inputTokens: 1_000_000, cachedInputTokens: 800_000 },
+      { pricing },
+    );
+    expect(cost).toBeCloseTo(2.8, 6);
+  });
+
+  it('accepts a pricing override and extends the table', () => {
+    const cost = estimateLLMCost(
+      'my-model',
+      { inputTokens: 500_000, outputTokens: 500_000 },
+      { pricing: { 'my-model': { inputPer1M: 4, outputPer1M: 8 } } },
+    );
+    expect(cost).toBe(6);
+  });
+
+  it('handles partial usage without throwing', () => {
+    expect(estimateLLMCost('gpt-4o-mini', {})).toBe(0);
+    expect(estimateLLMCost('gpt-4o-mini', { outputTokens: 1_000_000 })).toBe(
+      0.6,
+    );
+  });
+});
+
+describe('recordLLMCost', () => {
+  it('sets the cost attribute on the context for a known model', () => {
+    const setAttribute = vi.fn();
+    const cost = recordLLMCost({ setAttribute }, 'gpt-4o', {
+      inputTokens: 1_000_000,
+      outputTokens: 0,
+    });
+    expect(cost).toBe(2.5);
+    expect(setAttribute).toHaveBeenCalledWith(GEN_AI_COST_ATTRIBUTE, 2.5);
+  });
+
+  it('sets no attribute for an unknown model', () => {
+    const setAttribute = vi.fn();
+    const cost = recordLLMCost({ setAttribute }, 'unknown-model', {
+      inputTokens: 100,
+    });
+    expect(cost).toBeUndefined();
+    expect(setAttribute).not.toHaveBeenCalled();
+  });
+});

package/src/gen-ai-cost.ts

@@ -0,0 +1,145 @@
+/**
+ * Per-model LLM cost estimation.
+ *
+ * Estimate the USD cost of an LLM call from its token usage and record it as a
+ * span attribute (`gen_ai.usage.cost.usd`). Pair with the
+ * `gen_ai.client.cost.usd` metric bucket advice in `gen-ai-metrics`.
+ *
+ * @example
+ * ```typescript
+ * import { trace, recordLLMCost } from 'autotel';
+ *
+ * export const chat = trace((ctx) => async (prompt: string) => {
+ *   const res = await client.messages.create({ model, ... });
+ *   recordLLMCost(ctx, model, {
+ *     inputTokens: res.usage.input_tokens,
+ *     outputTokens: res.usage.output_tokens,
+ *   });
+ *   return res;
+ * });
+ * ```
+ */
+
+import type { TraceContext } from './trace-context';
+
+/** Span attribute key autotel sets for an estimated call cost. */
+export const GEN_AI_COST_ATTRIBUTE = 'gen_ai.usage.cost.usd';
+
+/** Pricing for a single model, in USD per 1,000,000 tokens. */
+export interface ModelPricing {
+  /** USD per 1M input (prompt) tokens. */
+  inputPer1M: number;
+  /** USD per 1M output (completion) tokens. */
+  outputPer1M: number;
+  /** USD per 1M cached input tokens. Defaults to {@link ModelPricing.inputPer1M}. */
+  cachedInputPer1M?: number;
+}
+
+/** Token counts for a single LLM call. */
+export interface TokenUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  /** Cached input tokens, billed at {@link ModelPricing.cachedInputPer1M}. */
+  cachedInputTokens?: number;
+}
+
+export interface EstimateCostOptions {
+  /** Override or extend {@link MODEL_PRICING}. Keys are matched first. */
+  pricing?: Record<string, ModelPricing>;
+}
+
+/**
+ * Approximate public list prices (USD per 1M tokens) at the time of writing.
+ * Prices change; treat these as convenience defaults, not a billing source of
+ * truth. Override per call via `options.pricing` or mutate this table at init.
+ * Matching is exact first, then by longest key prefix, so versioned model ids
+ * (`claude-sonnet-4-6-20251101`) resolve to a base entry (`claude-sonnet-4-6`).
+ */
+export const MODEL_PRICING: Record<string, ModelPricing> = {
+  // OpenAI
+  'gpt-4o': { inputPer1M: 2.5, outputPer1M: 10 },
+  'gpt-4o-mini': { inputPer1M: 0.15, outputPer1M: 0.6 },
+  'gpt-4.1': { inputPer1M: 2, outputPer1M: 8 },
+  'gpt-4.1-mini': { inputPer1M: 0.4, outputPer1M: 1.6 },
+  'gpt-4.1-nano': { inputPer1M: 0.1, outputPer1M: 0.4 },
+  'o3-mini': { inputPer1M: 1.1, outputPer1M: 4.4 },
+  // Anthropic Claude
+  'claude-opus-4': { inputPer1M: 15, outputPer1M: 75 },
+  'claude-sonnet-4': { inputPer1M: 3, outputPer1M: 15 },
+  'claude-3-5-sonnet': { inputPer1M: 3, outputPer1M: 15 },
+  'claude-3-5-haiku': { inputPer1M: 0.8, outputPer1M: 4 },
+  'claude-3-opus': { inputPer1M: 15, outputPer1M: 75 },
+  'claude-3-haiku': { inputPer1M: 0.25, outputPer1M: 1.25 },
+  // Google Gemini
+  'gemini-1.5-pro': { inputPer1M: 1.25, outputPer1M: 5 },
+  'gemini-1.5-flash': { inputPer1M: 0.075, outputPer1M: 0.3 },
+  'gemini-2.0-flash': { inputPer1M: 0.1, outputPer1M: 0.4 },
+};
+
+function resolvePricing(
+  table: Record<string, ModelPricing>,
+  model: string,
+): ModelPricing | undefined {
+  const exact = table[model];
+  if (exact) return exact;
+
+  let best: ModelPricing | undefined;
+  let bestLength = 0;
+  for (const key of Object.keys(table)) {
+    if (model.startsWith(key) && key.length > bestLength) {
+      best = table[key];
+      bestLength = key.length;
+    }
+  }
+  return best;
+}
+
+function round(value: number): number {
+  return Math.round(value * 1e6) / 1e6;
+}
+
+/**
+ * Estimate the USD cost of an LLM call. Returns `undefined` when the model has
+ * no known pricing (supply one via `options.pricing`).
+ */
+export function estimateLLMCost(
+  model: string,
+  usage: TokenUsage,
+  options?: EstimateCostOptions,
+): number | undefined {
+  const table = options?.pricing
+    ? { ...MODEL_PRICING, ...options.pricing }
+    : MODEL_PRICING;
+  const price = resolvePricing(table, model);
+  if (!price) return undefined;
+
+  const cachedInput = usage.cachedInputTokens ?? 0;
+  const billedInput = Math.max(0, (usage.inputTokens ?? 0) - cachedInput);
+  const output = usage.outputTokens ?? 0;
+  const cachedRate = price.cachedInputPer1M ?? price.inputPer1M;
+
+  const cost =
+    (billedInput / 1_000_000) * price.inputPer1M +
+    (cachedInput / 1_000_000) * cachedRate +
+    (output / 1_000_000) * price.outputPer1M;
+
+  return round(cost);
+}
+
+/**
+ * Estimate cost and record it on `ctx` as the `gen_ai.usage.cost.usd` span
+ * attribute. Returns the estimated cost, or `undefined` when the model is
+ * unknown (in which case no attribute is set).
+ */
+export function recordLLMCost(
+  ctx: Pick<TraceContext, 'setAttribute'>,
+  model: string,
+  usage: TokenUsage,
+  options?: EstimateCostOptions,
+): number | undefined {
+  const cost = estimateLLMCost(model, usage, options);
+  if (cost !== undefined) {
+    ctx.setAttribute(GEN_AI_COST_ATTRIBUTE, cost);
+  }
+  return cost;
+}