@prism-d1/cli 1.0.99 → 1.2.0

package/dist/assets/infra/lib/lambda/otel-receiver.ts

@@ -13,6 +13,12 @@
  * Item shapes in the AI-usage table:
  *   pk=USER#<identity>  sk=SPAN#<timestamp>#<spanId>            raw span, TTL 90d
  *   pk=USER#<identity>  sk=OTEL#DAY#<yyyy-mm-dd>#<tool>#<model> daily aggregate
+ *   pk=USER#<identity>  sk=OTEL#TOOLDAY#<yyyy-mm-dd>#<tool>#<toolName>
+ *                                                   daily tool-call rollup
+ *
+ * "tool" in the first two shapes is the AI tool (claude-code, kiro, ...).
+ * `toolName` is a tool the model invoked inside one call (Bash, Edit,
+ * mcp__<server>__<tool>), taken from codeburn's `ai.tools` attribute.
  */
 
 import {
@@ -26,6 +32,8 @@ import {
 } from '@aws-sdk/client-dynamodb';
 import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
 import { randomUUID } from 'crypto';
+import { PriceTable, lookupPrice, computeCost, hasTokens } from './pricing/price-table';
+import { loadPrices, BUNDLED_PRICES } from './pricing/price-source';
 
 const dynamoClient = new DynamoDBClient({});
 const s3Client = new S3Client({});
@@ -115,14 +123,29 @@ interface ParsedSpan {
   model: string;
   inputTokens: number;
   outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
   costUsd: number;
   project: string;
   costEstimated: boolean;
+  /**
+   * 'client' when codeburn priced the call, 'receiver' when the LiteLLM
+   * fallback did, 'unpriced' when neither could (the reprice job retries these).
+   */
+  costSource: 'client' | 'receiver' | 'unpriced';
+  /** LiteLLM key the receiver priced from, for audit. Empty when client-priced. */
+  pricedKey: string;
   /** True for spans the PRISM coding agent emitted: work no human prompted. */
   autonomous?: boolean;
   /** The issue the agent was handed. 0 when not an agent span. */
   issueNumber?: number;
   deviceId: string;
+  /**
+   * Distinct tool names the model invoked in this call, from `ai.tools`.
+   * Empty when the provider reports none -- which is not the same as "used no
+   * tools" for providers codeburn cannot read tool calls from.
+   */
+  toolNames: string[];
 }
 
 // ---- Attribution span types ----
@@ -193,6 +216,40 @@ function bool(v: OtlpValue | undefined): boolean {
 }
 
 /** Convert OTLP unix-nano string to ISO timestamp; empty string if invalid. */
+const MAX_TOOL_NAMES = 64;
+const MAX_TOOL_NAME_LEN = 128;
+
+/**
+ * Read `ai.tools` into a list of distinct, key-safe tool names.
+ *
+ * Deduplicated because codeburn providers disagree: most send a distinct set
+ * per call, Claude Code sends one entry per tool_use block. Counting distinct
+ * names makes the rollup mean "calls that used tool X" for every provider.
+ *
+ * The attribute is client-supplied, so it is bounded here regardless of what
+ * codeburn already caps: '#' is the sort-key delimiter and is stripped, control
+ * characters are dropped, and anything over the limits is ignored.
+ */
+export function parseToolNames(v: OtlpValue | undefined): string[] {
+  const values = v && 'arrayValue' in v ? v.arrayValue?.values ?? [] : [];
+  const out = new Set<string>();
+  for (const item of values) {
+    if (out.size >= MAX_TOOL_NAMES) break;
+    const raw = typeof item?.stringValue === 'string' ? item.stringValue : '';
+    // eslint-disable-next-line no-control-regex
+    const name = raw.replace(/[#\u0000-\u001f\u007f]/g, '').trim();
+    if (!name || name.length > MAX_TOOL_NAME_LEN) continue;
+    out.add(name);
+  }
+  return [...out];
+}
+
+/** `mcp__<server>__<tool>` -> `<server>`; '' for non-MCP tools. */
+export function mcpServerOf(toolName: string): string {
+  const m = /^mcp__(.+?)__.+$/.exec(toolName);
+  return m ? m[1]! : '';
+}
+
 function nanoToIso(nano: string | undefined): string {
   if (!nano || !/^\d+$/.test(nano)) return '';
   try {
@@ -227,7 +284,11 @@ function resolveIdentity(event: HttpApiEvent): string | null {
 }
 
 /** Extract and sanity-check spans from an OTLP payload. Returns usage spans, attribution spans, and rejected count. */
-export function parseOtlpSpans(payload: OtlpPayload): {
+export function parseOtlpSpans(
+  payload: OtlpPayload,
+  /** Fallback rates for spans the client sent unpriced. Defaults to the bundled snapshot. */
+  prices: PriceTable = BUNDLED_PRICES.entries,
+): {
   spans: ParsedSpan[];
   attributionSpans: ParsedAttributionSpan[];
   rejected: number;
@@ -248,6 +309,12 @@ export function parseOtlpSpans(payload: OtlpPayload): {
     noProvider: number;
     badTokens: number;
   };
+  /**
+   * Usage spans that arrived with cost 0 but tokens > 0. `repriced` were priced
+   * from the LiteLLM table; `unpriced` matched no entry and stayed $0.
+   * `unpricedModels` names the models so a table gap is one log line to fix.
+   */
+  pricing: { repriced: number; unpriced: number; unpricedModels: string[] };
 } {
   const spans: ParsedSpan[] = [];
   const attributionSpans: ParsedAttributionSpan[] = [];
@@ -258,6 +325,9 @@ export function parseOtlpSpans(payload: OtlpPayload): {
   let rejectedNoRepo = 0;
   let rejectedNoProvider = 0;
   let rejectedBadTokens = 0;
+  let repriced = 0;
+  let unpriced = 0;
+  const unpricedModels = new Set<string>();
 
   for (const rs of payload.resourceSpans ?? []) {
     const resourceAttrs = attrMap(rs.resource?.attributes);
@@ -364,33 +434,67 @@ export function parseOtlpSpans(payload: OtlpPayload): {
 
         const inputTokens = num(attrs.get('ai.input_tokens'));
         const outputTokens = num(attrs.get('ai.output_tokens'));
-        const costUsd = num(attrs.get('ai.cost_usd'));
+        const cacheReadTokens = num(attrs.get('ai.cache_read_tokens'));
+        const cacheWriteTokens = num(attrs.get('ai.cache_write_tokens'));
+        let costUsd = num(attrs.get('ai.cost_usd'));
         if (
           inputTokens < 0 || outputTokens < 0 || costUsd < 0 ||
-          inputTokens > 100_000_000 || outputTokens > 100_000_000 || costUsd > 10_000
+          cacheReadTokens < 0 || cacheWriteTokens < 0 ||
+          inputTokens > 100_000_000 || outputTokens > 100_000_000 ||
+          cacheReadTokens > 100_000_000 || cacheWriteTokens > 100_000_000 ||
+          costUsd > 10_000
         ) {
           rejectedBadTokens++;
           rejected++;
           continue;
         }
 
+        const model = str(attrs.get('ai.model')).slice(0, 128);
+        let costEstimated = bool(attrs.get('ai.cost_estimated'));
+        let costSource: ParsedSpan['costSource'] = 'client';
+        let pricedKey = '';
+        // codeburn sends 0 for a model missing from its price table and does not
+        // flag it estimated. Tokens with no cost is that case, not free usage.
+        // A client-supplied non-zero cost is never overwritten.
+        const tokens = { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens };
+        if (costUsd === 0 && hasTokens(tokens)) {
+          const match = lookupPrice(prices, model);
+          const priced = match ? computeCost(match.entry, tokens) : 0;
+          if (match && priced > 0) {
+            costUsd = priced;
+            costEstimated = true;
+            costSource = 'receiver';
+            pricedKey = match.key;
+            repriced++;
+          } else {
+            costSource = 'unpriced';
+            unpriced++;
+            if (unpricedModels.size < 20) unpricedModels.add(model || 'unknown');
+          }
+        }
+
         spans.push({
           spanId: spanId.toLowerCase(),
           traceId: traceId.toLowerCase(),
           timestamp,
           tool: PROVIDER_TO_TOOL[provider] ?? provider.slice(0, 32),
-          model: str(attrs.get('ai.model')).slice(0, 128),
+          model,
           inputTokens,
           outputTokens,
+          cacheReadTokens,
+          cacheWriteTokens,
           costUsd,
           project: str(attrs.get('ai.project')).slice(0, 256),
-          costEstimated: bool(attrs.get('ai.cost_estimated')),
+          costEstimated,
+          costSource,
+          pricedKey,
           deviceId,
           // Emitted by the PRISM coding agent. `autonomous` separates work no human
           // prompted from human-assisted AI use, which the PRISM levels treat as
           // different things -- L5 is about autonomous deployments, not AI share.
           autonomous: bool(attrs.get('prism.autonomous')),
           issueNumber: num(attrs.get('prism.issue_number')),
+          toolNames: parseToolNames(attrs.get('ai.tools')),
         });
       }
     }
@@ -408,6 +512,7 @@ export function parseOtlpSpans(payload: OtlpPayload): {
       noProvider: rejectedNoProvider,
       badTokens: rejectedBadTokens,
     },
+    pricing: { repriced, unpriced, unpricedModels: [...unpricedModels] },
   };
 }
 
@@ -455,10 +560,19 @@ async function writeSpanIfNew(user: string, s: ParsedSpan): Promise<boolean> {
         model: { S: s.model },
         input_tokens: { N: String(s.inputTokens) },
         output_tokens: { N: String(s.outputTokens) },
+        // Stored so a span priced by the fallback can be re-priced later from
+        // the record alone, without the raw archive.
+        cache_read_tokens: { N: String(s.cacheReadTokens) },
+        cache_write_tokens: { N: String(s.cacheWriteTokens) },
         cost_usd: { N: String(s.costUsd) },
         project: { S: s.project },
         device_id: { S: s.deviceId },
         cost_estimated: { BOOL: s.costEstimated },
+        cost_source: { S: s.costSource },
+        ...(s.pricedKey ? { priced_key: { S: s.pricedKey } } : {}),
+        // A DynamoDB string set cannot be empty, so the attribute is omitted
+        // rather than written as [] when the call reported no tools.
+        ...(s.toolNames.length > 0 ? { tool_names: { SS: s.toolNames } } : {}),
         timestamp: { S: s.timestamp },
         ttl: { N: String(ttl) },
       },
@@ -537,6 +651,44 @@ async function bumpDailyAggregate(user: string, s: ParsedSpan): Promise<void> {
   }));
 }
 
+/**
+ * ADD-increment one daily tool-call rollup per distinct tool in a newly-seen
+ * span. Same dedup contract as bumpDailyAggregate: the caller only reaches
+ * this after writeSpanIfNew succeeded, so a re-pushed span adds nothing.
+ *
+ * Kept under its own sk prefix (OTEL#TOOLDAY#, not OTEL#DAY#) so the existing
+ * OTEL#DAY range queries, the metrics-publisher stream filter and the reprice
+ * job never see these items.
+ */
+async function bumpToolAggregates(user: string, s: ParsedSpan): Promise<void> {
+  if (s.toolNames.length === 0) return;
+  const day = s.timestamp.slice(0, 10);
+  const now = new Date().toISOString();
+  await Promise.all(s.toolNames.map((name) => {
+    const server = mcpServerOf(name);
+    return dynamoClient.send(new UpdateItemCommand({
+      TableName: AI_USAGE_TABLE,
+      Key: {
+        pk: { S: `USER#${user}` },
+        sk: { S: `OTEL#TOOLDAY#${day}#${s.tool}#${name}` },
+      },
+      UpdateExpression:
+        'ADD call_count :one ' +
+        'SET record_type = :rt, tool = :tool, tool_name = :name, mcp_server = :srv, #day = :day, updated_at = :now',
+      ExpressionAttributeNames: { '#day': 'day' },
+      ExpressionAttributeValues: {
+        ':one': { N: '1' },
+        ':rt': { S: 'OTEL_TOOL_DAY' },
+        ':tool': { S: s.tool },
+        ':name': { S: name },
+        ':srv': { S: server },
+        ':day': { S: day },
+        ':now': { S: now },
+      },
+    }));
+  }));
+}
+
 // ---- Attribution DDB writes ----
 
 /**
@@ -758,7 +910,10 @@ async function processSpans(user: string, spans: ParsedSpan[]): Promise<number>
     const chunk = spans.slice(i, i + CONCURRENCY);
     const results = await Promise.all(chunk.map(async (s) => {
       const isNew = await writeSpanIfNew(user, s);
-      if (isNew) await bumpDailyAggregate(user, s);
+      if (isNew) {
+        await bumpDailyAggregate(user, s);
+        await bumpToolAggregates(user, s);
+      }
       return isNew;
     }));
     written += results.filter(Boolean).length;
@@ -783,7 +938,8 @@ async function handleTraces(event: HttpApiEvent): Promise<HttpApiResponse> {
     return jsonResponse(400, { message: 'Body is not valid JSON' });
   }
 
-  const { spans, attributionSpans, rejected, rejectedReasons } = parseOtlpSpans(payload);
+  const prices = await loadPrices(s3Client, ARCHIVE_BUCKET);
+  const { spans, attributionSpans, rejected, rejectedReasons, pricing } = parseOtlpSpans(payload, prices.doc.entries);
   const totalAccepted = spans.length + attributionSpans.length;
 
   if (totalAccepted > MAX_BATCH_SIZE) {
@@ -810,7 +966,12 @@ async function handleTraces(event: HttpApiEvent): Promise<HttpApiResponse> {
     `[otel-receiver] user=${user} ` +
     `usage: received=${spans.length} new=${usageWritten} dupes=${spans.length - usageWritten} | ` +
     `attribution: received=${attributionSpans.length} written=${attrWritten} | ` +
-    `rejected=${rejected}${reasonDetail ? ` (${reasonDetail})` : ''}`,
+    `rejected=${rejected}${reasonDetail ? ` (${reasonDetail})` : ''}` +
+    (pricing.repriced || pricing.unpriced
+      ? ` | pricing(${prices.origin} ${prices.doc.fetchedAt.slice(0, 10)}): ` +
+        `repriced=${pricing.repriced} unpriced=${pricing.unpriced}` +
+        (pricing.unpricedModels.length ? ` (${pricing.unpricedModels.join(',')})` : '')
+      : ''),
   );
 
   if (rejected > 0) {
@@ -1539,7 +1700,7 @@ async function handleCommitsDailyQuery(event: HttpApiEvent): Promise<HttpApiResp
   }
 
   // Scan COMMIT# items in the date range.
-  const days = new Map<string, { ai: number; human: number; mergedAi: number; mergedHuman: number }>();
+  const days = new Map<string, { ai: number; human: number; mergedAi: number; mergedHuman: number; costUsd: number }>();
   let lastKey: import('@aws-sdk/client-dynamodb').ScanCommandOutput['LastEvaluatedKey'];
   do {
     const result = await dynamoClient.send(new ScanCommand({
@@ -1561,7 +1722,7 @@ async function handleCommitsDailyQuery(event: HttpApiEvent): Promise<HttpApiResp
       const origin = item.ai_origin?.S ?? 'human';
       const inMain = item.in_main?.BOOL ?? false;
       let bucket = days.get(day);
-      if (!bucket) { bucket = { ai: 0, human: 0, mergedAi: 0, mergedHuman: 0 }; days.set(day, bucket); }
+      if (!bucket) { bucket = { ai: 0, human: 0, mergedAi: 0, mergedHuman: 0, costUsd: 0 }; days.set(day, bucket); }
       if (origin === 'ai-generated') {
         bucket.ai++;
         if (inMain) bucket.mergedAi++;
@@ -1573,10 +1734,52 @@ async function handleCommitsDailyQuery(event: HttpApiEvent): Promise<HttpApiResp
     lastKey = result.LastEvaluatedKey;
   } while (lastKey);
 
-  // Sort ascending by date and return as an array.
+  // Second pass: fold daily AI spend into the same buckets, so a cost-per-commit
+  // trend can be computed from one source instead of dividing a CloudWatch cost
+  // metric by a CloudWatch commit metric.
+  //
+  // The two passes key on DIFFERENT timestamps by design, and that is the whole
+  // point of serving this from the store. A COMMIT# item is bucketed by its real
+  // commit timestamp and an OTEL_DAY item by the day the usage happened, so both
+  // sides of the ratio land on the day the work actually occurred. The CloudWatch
+  // equivalent buckets by INGEST time, which is why a backfill dumps months of
+  // commits into the week it was pushed and collapses that week's ratio.
+  {
+    let costKey: import('@aws-sdk/client-dynamodb').ScanCommandOutput['LastEvaluatedKey'];
+    do {
+      const result = await dynamoClient.send(new ScanCommand({
+        TableName: AI_USAGE_TABLE,
+        FilterExpression: 'record_type = :rt AND #day BETWEEN :lo AND :hi',
+        ExpressionAttributeNames: { '#day': 'day' },
+        ExpressionAttributeValues: {
+          ':rt': { S: 'OTEL_DAY' },
+          ':lo': { S: from },
+          ':hi': { S: to },
+        },
+        ProjectionExpression: '#day, cost_usd',
+        ...(costKey ? { ExclusiveStartKey: costKey } : {}),
+      }));
+      for (const item of result.Items ?? []) {
+        const day = item.day?.S;
+        if (!day) continue;
+        const cost = Number(item.cost_usd?.N ?? '0');
+        if (!Number.isFinite(cost)) continue;
+        let bucket = days.get(day);
+        // A day with spend but no commits is a real observation — AI work that
+        // shipped nothing — so it gets a bucket rather than being dropped. The
+        // consumer renders its ratio as null, not as zero.
+        if (!bucket) { bucket = { ai: 0, human: 0, mergedAi: 0, mergedHuman: 0, costUsd: 0 }; days.set(day, bucket); }
+        bucket.costUsd += cost;
+      }
+      costKey = result.LastEvaluatedKey;
+    } while (costKey);
+  }
+
+  // Sort ascending by date and return as an array. Cost is rounded once, here,
+  // so every consumer renders the same figure.
   const sorted = [...days.entries()]
     .sort((a, b) => a[0].localeCompare(b[0]))
-    .map(([date, counts]) => ({ date, ...counts }));
+    .map(([date, counts]) => ({ ...counts, date, costUsd: Math.round(counts.costUsd * 100) / 100 }));
 
   return jsonResponse(200, {
     range: { from, to },
@@ -1631,6 +1834,112 @@ function accumulateUsage(u: UserProductivity, item: Record<string, { S?: string;
 
 // ---- Handler ----
 
+// ---- Route: tool usage ----
+
+export interface ToolUsageReport {
+  range: { from: string; to: string };
+  user: string;
+  generatedAt: string;
+  /** Sum of per-tool counts. One model call using three tools counts three. */
+  totalToolCalls: number;
+  tools: Array<{ name: string; mcpServer: string; calls: number; byAiTool: Record<string, number> }>;
+  mcpServers: Array<{ server: string; calls: number; tools: number }>;
+  days: Array<{ date: string; calls: number }>;
+}
+
+type DdbItem = Record<string, { S?: string; N?: string }>;
+
+/** Fold OTEL_TOOL_DAY items into the report shape. Pure, for the contract check. */
+export function aggregateToolUsage(items: DdbItem[], from: string, to: string, user: string): ToolUsageReport {
+  const tools = new Map<string, { name: string; mcpServer: string; calls: number; byAiTool: Record<string, number> }>();
+  const servers = new Map<string, { calls: number; tools: Set<string> }>();
+  const days = new Map<string, number>();
+  let total = 0;
+  for (const item of items) {
+    const name = item.tool_name?.S;
+    const day = item.day?.S;
+    const calls = Number(item.call_count?.N ?? '0');
+    if (!name || !day || !Number.isFinite(calls) || calls <= 0) continue;
+    const aiTool = item.tool?.S ?? 'unknown';
+    const server = item.mcp_server?.S ?? '';
+    let t = tools.get(name);
+    if (!t) { t = { name, mcpServer: server, calls: 0, byAiTool: {} }; tools.set(name, t); }
+    t.calls += calls;
+    t.byAiTool[aiTool] = (t.byAiTool[aiTool] ?? 0) + calls;
+    if (server) {
+      let sv = servers.get(server);
+      if (!sv) { sv = { calls: 0, tools: new Set() }; servers.set(server, sv); }
+      sv.calls += calls;
+      sv.tools.add(name);
+    }
+    days.set(day, (days.get(day) ?? 0) + calls);
+    total += calls;
+  }
+  return {
+    range: { from, to },
+    user,
+    generatedAt: new Date().toISOString(),
+    totalToolCalls: total,
+    tools: [...tools.values()].sort((a, b) => b.calls - a.calls || a.name.localeCompare(b.name)),
+    mcpServers: [...servers.entries()]
+      .map(([server, v]) => ({ server, calls: v.calls, tools: v.tools.size }))
+      .sort((a, b) => b.calls - a.calls || a.server.localeCompare(b.server)),
+    days: [...days.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([date, calls]) => ({ date, calls })),
+  };
+}
+
+/**
+ * GET /v1/tool-usage?from=YYYY-MM-DD&to=YYYY-MM-DD&user=<identity>|all
+ *
+ * Reads the OTEL#TOOLDAY rollups, bucketed by the day the call happened, so a
+ * backfilled `codeburn sync push` lands on the right days and keeps full history.
+ */
+async function handleToolUsageQuery(event: HttpApiEvent): Promise<HttpApiResponse> {
+  const caller = resolveIdentity(event);
+  if (!caller) return jsonResponse(401, { message: 'No resolvable identity claim in token' });
+
+  const url = new URL(event.rawPath + '?' + (event.rawQueryString ?? ''), 'http://localhost');
+  const userParam = url.searchParams.get('user') ?? 'all';
+  const now = new Date();
+  const from = url.searchParams.get('from') ?? new Date(now.getTime() - 30 * 86400_000).toISOString().slice(0, 10);
+  const to = url.searchParams.get('to') ?? now.toISOString().slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(from) || !/^\d{4}-\d{2}-\d{2}$/.test(to)) {
+    return jsonResponse(400, { message: 'from/to must be YYYY-MM-DD' });
+  }
+
+  const items: DdbItem[] = [];
+  let lastKey: import('@aws-sdk/client-dynamodb').QueryCommandOutput['LastEvaluatedKey'];
+  do {
+    const result = userParam !== 'all'
+      ? await dynamoClient.send(new QueryCommand({
+          TableName: AI_USAGE_TABLE,
+          KeyConditionExpression: 'pk = :pk AND sk BETWEEN :lo AND :hi',
+          ExpressionAttributeValues: {
+            ':pk': { S: `USER#${userParam}` },
+            ':lo': { S: `OTEL#TOOLDAY#${from}` },
+            ':hi': { S: `OTEL#TOOLDAY#${to}\uffff` },
+          },
+          ...(lastKey ? { ExclusiveStartKey: lastKey } : {}),
+        }))
+      // Fleet scope: same scan-with-filter shape as the OTEL_DAY fleet query.
+      : await dynamoClient.send(new ScanCommand({
+          TableName: AI_USAGE_TABLE,
+          FilterExpression: 'record_type = :rt AND #day BETWEEN :lo AND :hi',
+          ExpressionAttributeNames: { '#day': 'day' },
+          ExpressionAttributeValues: {
+            ':rt': { S: 'OTEL_TOOL_DAY' },
+            ':lo': { S: from },
+            ':hi': { S: to },
+          },
+          ...(lastKey ? { ExclusiveStartKey: lastKey } : {}),
+        }));
+    for (const item of result.Items ?? []) items.push(item as DdbItem);
+    lastKey = result.LastEvaluatedKey;
+  } while (lastKey);
+
+  return jsonResponse(200, aggregateToolUsage(items, from, to, userParam));
+}
+
 export async function handler(event: HttpApiEvent): Promise<HttpApiResponse> {
   const method = event.requestContext.http.method;
   const path = event.rawPath;
@@ -1653,5 +1962,8 @@ export async function handler(event: HttpApiEvent): Promise<HttpApiResponse> {
   if (method === 'GET' && path === '/v1/commits-daily') {
     return handleCommitsDailyQuery(event);
   }
+  if (method === 'GET' && path === '/v1/tool-usage') {
+    return handleToolUsageQuery(event);
+  }
   return jsonResponse(404, { message: 'Not found' });
 }

package/dist/assets/infra/lib/lambda/pre-token-generation.ts

@@ -0,0 +1,79 @@
+/**
+ * Pre token generation trigger (V2_0) — copies `email` into the ACCESS token.
+ *
+ * WHY THIS EXISTS
+ *
+ * Every per-developer number on these dashboards keys on the identity the
+ * otel-receiver derives from the caller's JWT, and the commit side of the
+ * pipeline keys on the git author email (`metrics-processor.ts` writes
+ * `gsi_user: USER#<author email>` from the CI census). For the two to join,
+ * the receiver's identity must also be an email.
+ *
+ * Cognito ID tokens carry `email`. Cognito ACCESS tokens do not — and API
+ * Gateway's HttpJwtAuthorizer validates the access token. So with a federated
+ * IdP the receiver falls back to `username`, which Cognito prefixes with the
+ * provider name (`corpidp_alice`). The same person then appears as two
+ * developers: one holding all the token spend and no commits, the other the
+ * reverse. On a pool with months of accumulated telemetry, effectively all of
+ * the AI-usage history lands on the prefixed identity while commit attribution
+ * lands on the email one.
+ *
+ * Mapping `email` on the identity provider is necessary but NOT sufficient: it
+ * populates the user ATTRIBUTE, which never reaches the access token on its
+ * own. This trigger is the piece that moves it there.
+ *
+ * PAIRED WITH `otelIdentityClaim=email`
+ *
+ * This function is inert by itself. The receiver resolves identity as
+ * `[IDENTITY_CLAIM, 'username', 'email', 'sub']`, and IDENTITY_CLAIM defaults
+ * to `username` — which is always present, so `email` is unreachable no matter
+ * what this trigger adds. Deploy this WITH `-c otelIdentityClaim=email`, or it
+ * adds a claim nothing reads.
+ *
+ * FAIL-OPEN, DELIBERATELY
+ *
+ * A federated user's `email` is populated by the IdP attribute mapping on
+ * sign-in, so a user who has not signed in since the mapping was added has no
+ * email yet. Returning the event unmodified in that case lets the receiver's
+ * chain fall through to `username` — the pre-existing behaviour — so those users
+ * keep writing to their old key until they next sign in, and the migration is
+ * self-completing. Throwing here would instead block token issuance and lock
+ * them out of sync entirely, turning a cosmetic split into an outage.
+ *
+ * Requires the Essentials or Plus feature plan; access token customization is
+ * unavailable on Lite. Deployed against a pool already on Plus.
+ */
+
+interface PreTokenGenerationV2Event {
+  request?: {
+    userAttributes?: Record<string, string>;
+  };
+  response?: unknown;
+}
+
+export async function handler(event: PreTokenGenerationV2Event): Promise<PreTokenGenerationV2Event> {
+  const email = event.request?.userAttributes?.email;
+
+  // Trim before testing: a whitespace-only attribute would satisfy a bare
+  // truthiness check here and then be rejected by the receiver's own
+  // `v.trim()` guard, silently reverting to `username` with no signal.
+  if (typeof email !== 'string' || email.trim() === '') {
+    return event;
+  }
+
+  // Lowercased to match the receiver, which lowercases every resolved identity
+  // before building `USER#<identity>`. Emitting mixed case here would create a
+  // second partition key for the same person the first time an IdP returned a
+  // capitalized address.
+  const normalized = email.trim().toLowerCase();
+
+  event.response = {
+    claimsAndScopeOverrideDetails: {
+      accessTokenGeneration: {
+        claimsToAddOrOverride: { email: normalized },
+      },
+    },
+  };
+
+  return event;
+}