@prism-d1/cli 1.1.2 → 1.2.0

package/dist/assets/github-workflows/prism-agent-eval.yml

@@ -6,7 +6,8 @@
 #   - OIDC provider configured for GitHub Actions in your AWS account
 #   - IAM role with bedrock:InvokeModel and events:PutEvents permissions
 #   - Repository secret PRISM_METRICS_ROLE_ARN set to the OIDC role ARN
-#   - .prism/config.json committed to the repo (created by: bash prism-cli bootstrapper install-git-hooks)
+#   - .prism/config.json committed to the repo with a "team_id" key; add it by hand, e.g.
+#     {"team_id": "team-payments"} (prism-cli enable codewatch keeps existing keys in this file)
 #   - .prism/eval-harness/ installed (run: bash prism-cli bootstrapper install-eval-harness)
 #   - (Optional) Agent entry point supports --mock flag for dry-run execution
 

package/dist/assets/github-workflows/prism-eval-gate-kiro.yml

@@ -4,7 +4,8 @@
 #
 # Required setup:
 #   - Kiro API key stored as repository secret: KIRO_API_KEY
-#   - .kiro/steering/code-review.md in your repo (review rules)
+#   - .prism/review/rules.md (shared with the local pre-push review) or
+#     .kiro/steering/code-review.md in your repo (review rules)
 #   - (Optional) PRISM_METRICS_ROLE_ARN for EventBridge metrics emission
 #   - (Optional) AWS Continuum configured for security scanning
 #
@@ -236,6 +237,15 @@ jobs:
             exit 0
           fi
 
+          # Shared rule set: .prism/review/rules.md is the one source for this
+          # gate and the local pre-push review (prism-cli enable security).
+          # kiro-cli loads rules from .kiro/steering/, so sync it in for this run.
+          if [ -f .prism/review/rules.md ]; then
+            mkdir -p .kiro/steering
+            cp .prism/review/rules.md .kiro/steering/code-review.md
+            echo "Review rules: .prism/review/rules.md"
+          fi
+
           # Get all changed source files in this PR
           FILES=$(git diff --name-only "${BASE_SHA}..${HEAD_SHA}" \
             | grep -E '\.(ts|js|py|go|java|rs|tsx|jsx)$' \

package/dist/assets/gitlab-workflows/prism-eval-gate.yml

@@ -186,6 +186,14 @@ prism-eval-gate:
       elif [ -z "${BASE_SHA}" ] || [ -z "${HEAD_SHA}" ]; then
         echo "⚠️  Missing base/head SHA — review skipped."
       else
+        # Shared rule set (also used by the local pre-push review). kiro-cli
+        # loads rules from .kiro/steering/, so sync it in for this run.
+        if [ -f .prism/review/rules.md ]; then
+          mkdir -p .kiro/steering
+          cp .prism/review/rules.md .kiro/steering/code-review.md
+          echo "Review rules: .prism/review/rules.md"
+        fi
+
         FILES=$(git diff --name-only "${BASE_SHA}..${HEAD_SHA}" \
           | grep -E '\.(ts|js|py|go|java|rs|tsx|jsx)$' \
           | grep -vE '\.test\.|\.spec\.|__test__|_test\.' \

package/dist/assets/infra/lib/constructs/otel-collector-construct.ts

@@ -24,6 +24,9 @@ import * as cognito from 'aws-cdk-lib/aws-cognito';
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as kms from 'aws-cdk-lib/aws-kms';
 import * as logs from 'aws-cdk-lib/aws-logs';
+import * as events from 'aws-cdk-lib/aws-events';
+import * as targets from 'aws-cdk-lib/aws-events-targets';
+import * as iam from 'aws-cdk-lib/aws-iam';
 import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
 import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 import { HttpJwtAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2-authorizers';
@@ -32,6 +35,7 @@ import * as ssm from 'aws-cdk-lib/aws-ssm';
 import * as path from 'path';
 import { Construct } from 'constructs';
 import { NagSuppressions } from 'cdk-nag';
+import { PRICES_KEY } from '../lambda/pricing/prices-key';
 
 /** codeburn sync fixed loopback callback ports (see codeburn src/sync/auth.ts). */
 const CODEBURN_CALLBACK_PORTS = [19876, 19877, 19878];
@@ -509,9 +513,101 @@ export class OtelCollectorConstruct extends Construct {
 
     props.aiUsageTable.grantReadWriteData(receiver);
     this.archiveBucket.grantPut(receiver);
+    // The LiteLLM price table the refresh Lambda maintains (pricing/price-source.ts).
+    // Exact key, read only. KMS decrypt comes from grantEncryptDecrypt below.
+    const pricesObjectArn = this.archiveBucket.arnForObjects(PRICES_KEY);
+    receiver.addToRolePolicy(new iam.PolicyStatement({
+      actions: ['s3:GetObject'],
+      resources: [pricesObjectArn],
+    }));
     props.kmsKey.grantEncryptDecrypt(receiver);
     this.receiverFunction = receiver;
 
+    // -------------------------------------------------------
+    // Price refresh + reprice — daily
+    // Keeps the receiver's LiteLLM fallback table current in S3, then
+    // corrects spans stored at $0 whose model has since been priced.
+    // See lib/lambda/pricing-refresh.ts.
+    //
+    // Deliberately NOT in the VPC: the PRISM VPC has no NAT gateway, and this
+    // function's one job that needs a network path is an HTTPS GET to
+    // raw.githubusercontent.com. It accepts no inbound traffic, and reaches
+    // only S3 and DynamoDB besides, both over their public endpoints with IAM.
+    // -------------------------------------------------------
+    const pricingRefresh = new lambda.Function(this, 'PricingRefresh', {
+      functionName: 'prism-d1-pricing-refresh',
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: 'pricing-refresh.handler',
+      code: lambda.Code.fromAsset(path.join(__dirname, '..', 'lambda'), {
+        bundling: {
+          image: lambda.Runtime.NODEJS_22_X.bundlingImage,
+          command: [
+            'bash', '-c',
+            [
+              'npm init -y > /dev/null 2>&1',
+              'npm install --save @aws-sdk/client-dynamodb @aws-sdk/client-s3 esbuild > /dev/null 2>&1',
+              'npx esbuild pricing-refresh.ts --bundle --platform=node --target=node22 --outfile=/asset-output/pricing-refresh.js --external:@aws-sdk/*',
+            ].join(' && '),
+          ],
+          local: {
+            tryBundle(outputDir: string): boolean {
+              try {
+                const { execSync } = require('child_process');
+                execSync(
+                  `npx esbuild ${path.join(__dirname, '..', 'lambda', 'pricing-refresh.ts')} --bundle --platform=node --target=node22 --outfile=${path.join(outputDir, 'pricing-refresh.js')} --external:@aws-sdk/*`,
+                  { stdio: 'pipe' },
+                );
+                return true;
+              } catch {
+                return false;
+              }
+            },
+          },
+        },
+      }),
+      // A full-table scan plus, on the first run, a read of the raw archive to
+      // recover cache-token counts for spans stored before they were kept.
+      timeout: cdk.Duration.minutes(15),
+      memorySize: 1024,
+      environment: {
+        AI_USAGE_TABLE: props.aiUsageTable.tableName,
+        ARCHIVE_BUCKET: this.archiveBucket.bucketName,
+      },
+      logRetention: logs.RetentionDays.ONE_MONTH,
+      description: 'Daily: refresh the LiteLLM price table in S3, then reprice usage spans stored at $0',
+    });
+    props.aiUsageTable.grantReadWriteData(pricingRefresh);
+    // Read the raw archive (to recover cache-token counts), and read/write the
+    // one price-table object. No delete: an old table is only ever overwritten.
+    this.archiveBucket.grantRead(pricingRefresh, 'otlp/*');
+    pricingRefresh.addToRolePolicy(new iam.PolicyStatement({
+      actions: ['s3:GetObject', 's3:PutObject'],
+      resources: [pricesObjectArn],
+    }));
+    props.kmsKey.grantEncryptDecrypt(pricingRefresh);
+
+    new events.Rule(this, 'PricingRefreshSchedule', {
+      ruleName: 'prism-d1-pricing-refresh-daily',
+      description: 'Refresh LiteLLM prices and reprice $0 spans',
+      // 06:17 UTC: off the hour so it is not queued behind other schedules.
+      schedule: events.Schedule.cron({ minute: '17', hour: '6' }),
+      // No retry: a failed run already repriced what it could and the next day's
+      // run starts from the same state. Errors surface on the Lambda metric.
+      targets: [new targets.LambdaFunction(pricingRefresh, { retryAttempts: 0 })],
+    });
+
+    NagSuppressions.addResourceSuppressions(pricingRefresh, [
+      {
+        id: 'AwsSolutions-IAM5',
+        reason: 'grantRead scopes S3 reads to the otlp/* prefix of the single archive bucket (raw OTLP batches, read to recover cache-token counts); grantReadWriteData adds the AI-usage table GSI index wildcard.',
+        appliesTo: [
+          'Action::s3:GetObject*', 'Action::s3:GetBucket*', 'Action::s3:List*',
+          { regex: '/^Resource::<OtelCollectorArchiveBucket.*\\.Arn>\\/otlp\\/\\*$/g' },
+          { regex: '/^Resource::<AiUsageTable.*\\.Arn>\\/index\\/\\*$/g' },
+        ],
+      },
+    ], true);
+
     // -------------------------------------------------------
     // CloudWatch Custom Widget: Developer Productivity
     // Invoked by CloudWatch dashboards with the VIEWING user's IAM creds

package/dist/assets/infra/lib/dashboard-stack.ts

@@ -808,6 +808,33 @@ export class DashboardStack extends cdk.Stack {
         }),
       );
 
+      // --- Row 5: Tools the model invoked (codeburn ai.tools) ---
+      // Store-backed like the spend tiles: OTEL#TOOLDAY rollups are bucketed by
+      // the call's own day and keep full history, so a backfilled sync push is
+      // not cut off at CloudWatch's two-week window. Follows the Developer filter.
+      devDashboard.addWidgets(
+        new cloudwatch.CustomWidget({
+          functionArn: props.velocityWidgetArn ?? '',
+          title: 'Tool Usage: Top Tools & MCP Servers',
+          width: 16,
+          height: 9,
+          params: { view: 'tool-usage-top', user: USER_TOKEN },
+          updateOnRefresh: true,
+          updateOnResize: false,
+          updateOnTimeRangeChange: true,
+        }),
+        new cloudwatch.CustomWidget({
+          functionArn: props.velocityWidgetArn ?? '',
+          title: 'Tool Calls / Day',
+          width: 8,
+          height: 9,
+          params: { view: 'tool-usage-trend', user: USER_TOKEN },
+          updateOnRefresh: true,
+          updateOnResize: false,
+          updateOnTimeRangeChange: true,
+        }),
+      );
+
       new cdk.CfnOutput(this, 'DevProductivityDashboardUrl', {
         value: `https://${this.region}.console.aws.amazon.com/cloudwatch/home?region=${this.region}#dashboards:name=PRISM-D1-Developer-Productivity`,
         description: 'Developer Productivity Dashboard URL',

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) {
@@ -1673,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;
@@ -1695,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' });
 }