@sixb/core 0.1.21 → 0.1.22

package/src/storage/ai-cost/analytics.ts

@@ -1,9 +1,11 @@
+import { MODEL_KINDS, type ModelKind } from "../../models/definitions"
 import { type AiModelCallUsageRecord, normalizeAiModelCallUsage } from "../ai-usage"
 import type {
   AiAccountingAgentBreakdown,
   AiAccountingAggregate,
   AiAccountingAttribution,
   AiAccountingBucket,
+  AiAccountingKindBreakdown,
   AiAccountingModelBreakdown,
   AiAccountingOverview,
   AiAccountingTimeBucket,
@@ -50,10 +52,12 @@ interface AiAccountingUsageMeterFragment {
 
 /** One SQL-aggregated currency fragment; providers merge fragments without loading model calls. */
 export interface AiAccountingAggregateFragment {
-  readonly dimension: "totals" | "series" | "model" | "agent" | "workflow"
+  readonly dimension: "totals" | "series" | "model" | "kind" | "agent" | "workflow"
   readonly start?: Date
   readonly providerId?: string
   readonly modelId?: string
+  /** The `kind` dimension's key; absent for calls recorded before their kind was captured. */
+  readonly modelKind?: ModelKind
   readonly agentKind?: "agent" | "workflowAgent"
   readonly agentStepId?: string
   readonly workflowId?: string
@@ -69,6 +73,10 @@ export interface AiAccountingAggregateFragment {
     readonly textOutputTokens: AiAccountingUsageMeterFragment
     readonly reasoningOutputTokens: AiAccountingUsageMeterFragment
     readonly audioDurationMs: AiAccountingUsageMeterFragment
+    readonly imageOutputTokens: AiAccountingUsageMeterFragment
+    readonly audioOutputTokens: AiAccountingUsageMeterFragment
+    readonly outputImages: AiAccountingUsageMeterFragment
+    readonly inputCharacters: AiAccountingUsageMeterFragment
   }
   readonly costs: {
     readonly amount?: AiMoney
@@ -141,6 +149,8 @@ export function buildAiAccountingOverview(
     periods.map((period) => [period.start.getTime(), []])
   )
   const modelItems = new Map<string, AiAccountingRecordSetItem[]>()
+  // An empty key collects calls recorded before their kind was captured.
+  const kindItems = new Map<ModelKind | "", AiAccountingRecordSetItem[]>()
   const agentItems = new Map<string, AiAccountingRecordSetItem[]>()
   const workflowItems = new Map<string, AiAccountingRecordSetItem[]>()
 
@@ -152,6 +162,7 @@ export function buildAiAccountingOverview(
       JSON.stringify([item.usage.providerId, item.usage.requestedModelId]),
       item
     )
+    appendGrouped(kindItems, item.usage.modelKind ?? "", item)
     if (item.attribution?.kind === "agent") {
       appendGrouped(agentItems, JSON.stringify(["agent"]), item)
     } else if (item.attribution?.kind === "workflowAgent") {
@@ -180,6 +191,9 @@ export function buildAiAccountingOverview(
       return { providerId, modelId, ...aggregateAccountingItems(grouped) }
     })
     .sort(compareModelBreakdowns)
+  const kinds: AiAccountingKindBreakdown[] = [...kindItems]
+    .map(([kind, grouped]) => kindBreakdown(kind, aggregateAccountingItems(grouped)))
+    .sort(compareKindBreakdowns)
   const agents: AiAccountingAgentBreakdown[] = [...agentItems]
     .map(([key, grouped]) => {
       const [kind, workflowId, agentStepId] = JSON.parse(key) as [
@@ -207,11 +221,20 @@ export function buildAiAccountingOverview(
     totals: aggregateAccountingItems(items),
     series,
     models,
+    kinds,
     agents,
     workflows,
   })
 }
 
+/** A stored `kind` dimension key; null for calls recorded before their kind was captured. */
+export function aiAccountingModelKind(value: string | null): ModelKind | undefined {
+  if (value === null) return undefined
+  const kind = MODEL_KINDS.find((candidate) => candidate === value)
+  if (!kind) throw new TypeError(`[Sixb] AI accounting returned an unknown model kind '${value}'.`)
+  return kind
+}
+
 export function buildAiAccountingOverviewFromFragments(
   input: QueryAiAccountingOverviewInput,
   fragments: Iterable<AiAccountingAggregateFragment>
@@ -223,6 +246,7 @@ export function buildAiAccountingOverviewFromFragments(
     periods.map((period) => [period.start.getTime(), aggregateFragmentAccumulator()])
   )
   const models = new Map<string, AggregateFragmentAccumulator>()
+  const kinds = new Map<ModelKind | "", AggregateFragmentAccumulator>()
   const agents = new Map<string, AggregateFragmentAccumulator>()
   const workflows = new Map<string, AggregateFragmentAccumulator>()
 
@@ -250,6 +274,9 @@ export function buildAiAccountingOverviewFromFragments(
           ])
         )
         break
+      case "kind":
+        target = getFragmentAccumulator(kinds, fragment.modelKind ?? "")
+        break
       case "agent":
         target = getFragmentAccumulator(
           agents,
@@ -284,6 +311,9 @@ export function buildAiAccountingOverviewFromFragments(
         return { providerId, modelId, ...finishAggregateFragment(value) }
       })
       .sort(compareModelBreakdowns),
+    kinds: [...kinds]
+      .map(([kind, value]) => kindBreakdown(kind, finishAggregateFragment(value)))
+      .sort(compareKindBreakdowns),
     agents: [...agents]
       .map(([key, value]) => {
         const [kind, workflowId, agentStepId] = JSON.parse(key) as [
@@ -408,6 +438,10 @@ const AGGREGATE_USAGE_FIELDS = [
   "textOutputTokens",
   "reasoningOutputTokens",
   "audioDurationMs",
+  "imageOutputTokens",
+  "audioOutputTokens",
+  "outputImages",
+  "inputCharacters",
 ] as const
 
 type AggregateUsageField = (typeof AGGREGATE_USAGE_FIELDS)[number]
@@ -438,9 +472,9 @@ function aggregateFragmentAccumulator(): AggregateFragmentAccumulator {
   }
 }
 
-function getFragmentAccumulator(
-  values: Map<string, AggregateFragmentAccumulator>,
-  key: string
+function getFragmentAccumulator<TKey extends string>(
+  values: Map<TKey, AggregateFragmentAccumulator>,
+  key: TKey
 ): AggregateFragmentAccumulator {
   const existing = values.get(key)
   if (existing) return existing
@@ -603,9 +637,9 @@ function nextBucket(start: Date, bucket: AiAccountingBucket): Date {
   return next
 }
 
-function appendGrouped(
-  groups: Map<string, AiAccountingRecordSetItem[]>,
-  key: string,
+function appendGrouped<TKey extends string>(
+  groups: Map<TKey, AiAccountingRecordSetItem[]>,
+  key: TKey,
   item: AiAccountingRecordSetItem
 ): void {
   const existing = groups.get(key)
@@ -669,6 +703,25 @@ function compareWorkflowBreakdowns(
   )
 }
 
+function kindBreakdown(
+  kind: ModelKind | "",
+  aggregate: AiAccountingAggregate
+): AiAccountingKindBreakdown {
+  return kind ? { modelKind: kind, ...aggregate } : aggregate
+}
+
+function compareKindBreakdowns(
+  left: AiAccountingKindBreakdown,
+  right: AiAccountingKindBreakdown
+): number {
+  // Calls recorded before their kind was captured sort after every kind.
+  return (
+    right.modelCallCount - left.modelCallCount ||
+    Number(left.modelKind === undefined) - Number(right.modelKind === undefined) ||
+    (left.modelKind ?? "").localeCompare(right.modelKind ?? "")
+  )
+}
+
 function compareModelBreakdowns(
   left: AiAccountingModelBreakdown,
   right: AiAccountingModelBreakdown

package/src/storage/ai-cost/codec.ts

@@ -91,6 +91,7 @@ function costComponentsFromUnknown(
       quantity: requiredString(component.quantity),
       rateAmountNanosPerMillion: requiredString(component.rateAmountNanosPerMillion),
       chargeAmountNanos: requiredString(component.chargeAmountNanos),
+      ...optionalStringProperty(component, "variant"),
     }
   })
 }
@@ -111,7 +112,11 @@ function billableMeter(value: unknown): AiBillableMeter {
     value !== "tokens.output.total" &&
     value !== "tokens.output.text" &&
     value !== "tokens.output.reasoning" &&
-    value !== "audio.input.milliseconds"
+    value !== "tokens.output.image" &&
+    value !== "tokens.output.audio" &&
+    value !== "audio.input.milliseconds" &&
+    value !== "images.output" &&
+    value !== "characters.input"
   ) {
     throw invalidDetails()
   }

package/src/storage/ai-cost/groups.ts

@@ -1,3 +1,4 @@
+import { TOKENLESS_MODEL_KINDS } from "../../models/definitions"
 import type { AiAccountingRecordSetItem } from "./analytics"
 import { aiAccountingItemMatchesQuery, normalizeAiModelCallAccountingQuery } from "./analytics"
 import { directModelCallAttribution } from "./attribution"
@@ -27,7 +28,12 @@ export interface AiModelCallGroupFragment {
   readonly lastCallAt: Date
   readonly callCount: string
   readonly tokenCount: string
+  /** Calls of a tokenless kind that reported no tokens, which leave no gap in the total. */
+  readonly tokenlessCount: string
   readonly totalTokens: string | null
+  readonly outputImages: string | null
+  readonly inputCharacters: string | null
+  readonly audioDurationMs: string | null
   readonly valuationStatus: "rated" | "unpriceable" | "unvalued"
   readonly money?: AiMoney
 }
@@ -42,7 +48,11 @@ export interface AiModelCallGroupRow {
   readonly last_call_at: Date | string
   readonly call_count: string
   readonly token_count: string
+  readonly tokenless_count: string
   readonly total_tokens: string | null
+  readonly output_images: string | null
+  readonly input_characters: string | null
+  readonly audio_duration_ms: string | null
   readonly valuation_status: AiModelCallGroupFragment["valuationStatus"]
   readonly amount_currency: string | null
   readonly amount_high: string | null
@@ -98,7 +108,11 @@ export function aiModelCallGroupFragmentFromRow(
     lastCallAt: new Date(row.last_call_at),
     callCount: row.call_count,
     tokenCount: row.token_count,
+    tokenlessCount: row.tokenless_count,
     totalTokens: row.total_tokens,
+    outputImages: row.output_images,
+    inputCharacters: row.input_characters,
+    audioDurationMs: row.audio_duration_ms,
     valuationStatus: row.valuation_status,
     ...(row.amount_currency === null
       ? {}
@@ -178,7 +192,16 @@ export function buildAiModelCallGroups(
         lastCallAt: item.usage.occurredAt,
         callCount: "1",
         tokenCount: item.usage.usage.totalTokens === undefined ? "0" : "1",
+        tokenlessCount:
+          item.usage.usage.totalTokens === undefined &&
+          item.usage.modelKind !== undefined &&
+          TOKENLESS_MODEL_KINDS.includes(item.usage.modelKind)
+            ? "1"
+            : "0",
         totalTokens: item.usage.usage.totalTokens?.toString() ?? null,
+        outputImages: item.usage.usage.outputImages?.toString() ?? null,
+        inputCharacters: item.usage.usage.inputCharacters?.toString() ?? null,
+        audioDurationMs: item.usage.usage.audioDurationMs?.toString() ?? null,
         valuationStatus: item.cost?.status ?? "unvalued",
         ...(item.cost && item.cost.status !== "unpriceable" ? { money: item.cost.money } : {}),
       })
@@ -195,14 +218,25 @@ export function buildAiModelCallGroups(
 function summarize(items: readonly AiModelCallGroupFragment[]): AiModelCallGroupSummary {
   let calls = 0n
   let tokenCount = 0n
+  let tokenless = 0n
   let tokens = 0n
+  const media = {
+    outputImages: undefined as bigint | undefined,
+    inputCharacters: undefined as bigint | undefined,
+    audioDurationMs: undefined as bigint | undefined,
+  }
   const counts = { rated: 0n, unpriceable: 0n, unvalued: 0n }
   const money = new Map<string, bigint>()
   for (const item of items) {
     const count = BigInt(item.callCount)
     calls += count
     tokenCount += BigInt(item.tokenCount)
+    tokenless += BigInt(item.tokenlessCount)
     tokens += BigInt(item.totalTokens ?? "0")
+    for (const field of ["outputImages", "inputCharacters", "audioDurationMs"] as const) {
+      const value = item[field]
+      if (value !== null) media[field] = (media[field] ?? 0n) + BigInt(value)
+    }
     counts[item.valuationStatus] += count
     if (item.money)
       money.set(
@@ -220,7 +254,16 @@ function summarize(items: readonly AiModelCallGroupFragment[]): AiModelCallGroup
   }
   return {
     modelCallCount: safeCount(calls),
-    ...(calls === tokenCount ? { totalTokens: safeCount(tokens) } : {}),
+    ...(tokenCount > 0n && calls === tokenCount + tokenless
+      ? { totalTokens: safeCount(tokens) }
+      : {}),
+    ...(media.outputImages === undefined ? {} : { outputImages: safeCount(media.outputImages) }),
+    ...(media.inputCharacters === undefined
+      ? {}
+      : { inputCharacters: safeCount(media.inputCharacters) }),
+    ...(media.audioDurationMs === undefined
+      ? {}
+      : { audioDurationMs: safeCount(media.audioDurationMs) }),
     costs,
   }
 }

package/src/storage/ai-cost/index.ts

@@ -10,6 +10,7 @@ export type {
   AiAccountingAggregate,
   AiAccountingAttribution,
   AiAccountingBucket,
+  AiAccountingKindBreakdown,
   AiAccountingModelBreakdown,
   AiAccountingOverview,
   AiAccountingRange,

package/src/storage/ai-cost/provider.ts

@@ -1,5 +1,6 @@
 /** @internal Storage-provider helpers; not part of the app-author API. */
 
+export { TOKENLESS_MODEL_KINDS } from "../../models/definitions"
 export type {
   AiAccountingAggregateFragment,
   AiAccountingRecordSetItem,
@@ -7,6 +8,7 @@ export type {
   NormalizedAiModelCallAccountingQuery,
 } from "./analytics"
 export {
+  aiAccountingModelKind,
   buildAiAccountingOverviewFromFragments,
   normalizeAiAccountingQuery,
   normalizeAiModelCallAccountingQuery,

package/src/storage/ai-cost/types.ts

@@ -4,9 +4,11 @@ import type {
   AiUsageReportingStatus,
 } from "../ai-usage"
 
-/** Token meters supported by deterministic local rate cards. */
+/** Meters supported by deterministic local rate cards. */
 export type AiBillableMeter =
   | "audio.input.milliseconds"
+  | "characters.input"
+  | "images.output"
   | "tokens.input.total"
   | "tokens.input.uncached"
   | "tokens.input.cacheRead"
@@ -16,6 +18,8 @@ export type AiBillableMeter =
   | "tokens.output.total"
   | "tokens.output.text"
   | "tokens.output.reasoning"
+  | "tokens.output.image"
+  | "tokens.output.audio"
 
 /** Exact money in nanounits of a currency's major unit. */
 export interface AiMoney {
@@ -58,6 +62,8 @@ export interface AiCostComponent {
   readonly quantity: string
   readonly rateAmountNanosPerMillion: string
   readonly chargeAmountNanos: string
+  /** The price variant that applied, such as `1024x1024 · high`. Display only. */
+  readonly variant?: string
 }
 
 export type AiUnpriceableReason =
@@ -189,12 +195,18 @@ export interface AiAccountingModelBreakdown extends AiAccountingAggregate {
   readonly modelId: string
 }
 
+export interface AiAccountingKindBreakdown extends AiAccountingAggregate {
+  /** Absent for calls recorded before their kind was captured. */
+  readonly modelKind?: import("../../models/definitions").ModelKind
+}
+
 export interface AiAccountingOverview {
   readonly range: AiAccountingRange
   readonly bucket: AiAccountingBucket
   readonly totals: AiAccountingAggregate
   readonly series: readonly AiAccountingTimeBucket[]
   readonly models: readonly AiAccountingModelBreakdown[]
+  readonly kinds: readonly AiAccountingKindBreakdown[]
   readonly agents: readonly AiAccountingAgentBreakdown[]
   readonly workflows: readonly AiAccountingWorkflowBreakdown[]
 }
@@ -243,7 +255,12 @@ export type ListAiModelCallGroupsInput = Omit<ListAiModelCallAccountingInput, "e
 /** Filtered usage; an absent token total means at least one call did not report it. */
 export interface AiModelCallGroupSummary {
   readonly modelCallCount: number
+  /** Present when every call that reports tokens did; tokenless kinds such as images don't. */
   readonly totalTokens?: number
+  /** Sums over the calls that reported them. */
+  readonly outputImages?: number
+  readonly inputCharacters?: number
+  readonly audioDurationMs?: number
   readonly costs: AiCostSummary
 }
 

package/src/storage/ai-cost/validation.ts

@@ -29,6 +29,10 @@ const METER_ORDER: Readonly<Record<AiBillableMeter, number>> = {
   "tokens.output.text": 7,
   "tokens.output.reasoning": 8,
   "audio.input.milliseconds": 9,
+  "tokens.output.image": 10,
+  "tokens.output.audio": 11,
+  "images.output": 12,
+  "characters.input": 13,
 }
 const METERS = new Set(Object.keys(METER_ORDER) as AiBillableMeter[])
 const UNPRICEABLE_REASONS = new Set<AiUnpriceableReason>([
@@ -133,17 +137,26 @@ export function aiModelCallCostMatchesUsage(
   return componentsMatchUsage(components, usage)
 }
 
+const UNIT_METERS = [
+  ["audio.input.milliseconds", "audioDurationMs"],
+  ["characters.input", "inputCharacters"],
+  ["images.output", "outputImages"],
+] as const
+
 function componentsMatchUsage(
   components: ReadonlyMap<AiBillableMeter, AiCostComponent>,
   usage: AiModelCallUsage
 ): boolean {
-  const audio = components.get("audio.input.milliseconds")
-  if (audio) {
-    return (
-      components.size === 1 &&
-      usage.audioDurationMs !== undefined &&
-      BigInt(audio.quantity) === BigInt(usage.audioDurationMs)
-    )
+  for (const [meter, field] of UNIT_METERS) {
+    const component = components.get(meter)
+    const expected = usage[field]
+    if (component && (expected === undefined || BigInt(component.quantity) !== BigInt(expected))) {
+      return false
+    }
+  }
+  // A call billed only by units carries no token components.
+  if (![...components.keys()].some((meter) => meter.startsWith("tokens."))) {
+    return components.size > 0
   }
 
   return (
@@ -203,18 +216,28 @@ function outputComponentsMatchUsage(
 ): boolean {
   if (usage.outputTokens === undefined) return false
   const total = components.get("tokens.output.total")
+  // Per-image prices cover the image tokens of a call that returned images.
+  const images = components.get("images.output")
+  const covered = images && BigInt(images.quantity) > 0n ? usage.imageOutputTokens : 0
+  if (covered === undefined) return false
   const partitions = [
     ["tokens.output.text", usage.textOutputTokens],
     ["tokens.output.reasoning", usage.reasoningOutputTokens],
+    ["tokens.output.image", usage.imageOutputTokens],
+    ["tokens.output.audio", usage.audioOutputTokens],
   ] as const
   const presentPartitions = partitions.filter(([meter]) => components.has(meter))
 
   if (total) {
-    return presentPartitions.length === 0 && BigInt(total.quantity) === BigInt(usage.outputTokens)
+    return (
+      presentPartitions.length === 0 &&
+      covered === 0 &&
+      BigInt(total.quantity) === BigInt(usage.outputTokens)
+    )
   }
-  if (presentPartitions.length === 0) return false
+  if (presentPartitions.length === 0 && covered === 0) return false
 
-  let quantity = 0n
+  let quantity = BigInt(covered)
   for (const [meter, expected] of presentPartitions) {
     if (expected === undefined) return false
     const component = components.get(meter)!
@@ -271,7 +294,8 @@ export function normalizeAiCostEstimate(value: unknown): AiCostEstimate {
           !meter ||
           typeof component.quantity !== "string" ||
           typeof component.rateAmountNanosPerMillion !== "string" ||
-          typeof component.chargeAmountNanos !== "string"
+          typeof component.chargeAmountNanos !== "string" ||
+          (component.variant !== undefined && typeof component.variant !== "string")
         )
           throw new TypeError("[Sixb] Invalid cost estimate component.")
         return normalizeCostComponent({
@@ -279,6 +303,7 @@ export function normalizeAiCostEstimate(value: unknown): AiCostEstimate {
           quantity: component.quantity,
           rateAmountNanosPerMillion: component.rateAmountNanosPerMillion,
           chargeAmountNanos: component.chargeAmountNanos,
+          ...(component.variant === undefined ? {} : { variant: component.variant }),
         })
       })
       .sort(compareComponents)
@@ -365,7 +390,9 @@ function normalizeCostComponent(input: AiCostComponent): AiCostComponent {
   if (expected.chargeAmountNanos !== input.chargeAmountNanos) {
     throw new TypeError(`[Sixb] AI cost component '${input.meter}' charge is invalid.`)
   }
-  return expected
+  if (input.variant === undefined) return expected
+  assertNonBlank(input.variant, `cost component '${input.meter}' variant`)
+  return { ...expected, variant: input.variant }
 }
 
 function calculateComponent(

package/src/storage/ai-limits/provider.ts

@@ -1,4 +1,4 @@
-import type { ModelKind } from "../../models/definitions"
+import { type ModelKind, TOKENLESS_MODEL_KINDS } from "../../models/definitions"
 import type { AiMoney } from "../ai-cost"
 import { AiLimitStorageError } from "./errors"
 import { aiLimitCalendarMonth } from "./period"
@@ -18,18 +18,15 @@ import type {
 
 const SIGNED_INT64_MAX = 9_223_372_036_854_775_807n
 
-// These calls are billed per audio second or per search, and their providers report no tokens.
-// Token limits neither admit nor count them; cost limits still do.
-const TOKENLESS_MODEL_KINDS: ReadonlySet<ModelKind> = new Set(["transcription", "reranking"])
+// Token limits neither admit nor count tokenless calls; cost limits still do.
+const TOKENLESS_KINDS: ReadonlySet<ModelKind> = new Set(TOKENLESS_MODEL_KINDS)
 
 /** @internal Whether a limit meter governs calls of this kind. Unclassified calls are metered. */
 export function aiLimitMeterApplies(
   meter: AiLimitMeter,
   modelKind: ModelKind | undefined
 ): boolean {
-  return (
-    meter !== "tokens.total" || modelKind === undefined || !TOKENLESS_MODEL_KINDS.has(modelKind)
-  )
+  return meter !== "tokens.total" || modelKind === undefined || !TOKENLESS_KINDS.has(modelKind)
 }
 
 /** @internal Serialize compound limit operations, including within an existing transaction. */

package/src/storage/ai-usage/in-memory.ts

@@ -1,11 +1,19 @@
 import type { ExecutionStorage } from "../executions"
 import { AiUsageStorageError } from "./errors"
-import { assertAiUsageExecutionId, normalizeAiModelCallRecord } from "./record"
+import {
+  assertAiUsageExecutionId,
+  assertSameCallExecution,
+  normalizeAiModelCallFilesRecord,
+  normalizeAiModelCallRecord,
+} from "./record"
 import type {
+  AiModelCallFilesRecord,
   AiModelCallUsageRecord,
   AiUsageExecutionSummary,
   AiUsageStorage,
+  GetAiModelCallFilesInput,
   GetLatestAiModelCallForExecutionInput,
+  RecordAiModelCallFilesInput,
   RecordAiModelCallInput,
   RecordAiModelCallResult,
   SummarizeAiUsageExecutionInput,
@@ -24,6 +32,7 @@ export interface InMemoryAiUsageStorageSnapshot {
   readonly records: Map<string, AiModelCallUsageRecord>
   readonly recordKeysByIdempotencyKey: Map<string, string>
   readonly groupRows: Map<string, InMemoryAiUsageGroupRow>
+  readonly callFiles: Map<string, AiModelCallFilesRecord>
 }
 
 /** In-memory model-call ledger used by development runtimes and storage contract tests. */
@@ -31,6 +40,7 @@ export class InMemoryAiUsageStorage implements AiUsageStorage {
   private readonly records = new Map<string, AiModelCallUsageRecord>()
   private readonly recordKeysByIdempotencyKey = new Map<string, string>()
   private readonly groupRows = new Map<string, InMemoryAiUsageGroupRow>()
+  private readonly callFiles = new Map<string, AiModelCallFilesRecord>()
 
   constructor(private readonly executions: Pick<ExecutionStorage, "getById">) {}
 
@@ -130,11 +140,27 @@ export class InMemoryAiUsageStorage implements AiUsageStorage {
     })
   }
 
+  async recordModelCallFiles(input: RecordAiModelCallFilesInput): Promise<AiModelCallFilesRecord> {
+    const record = normalizeAiModelCallFilesRecord(input)
+    const key = modelCallRecordKey(record.projectId, record.callId)
+    const existing = this.callFiles.get(key)
+    if (existing) return structuredClone(assertSameCallExecution(existing, record))
+    await this.assertExecutionExists(record.projectId, record.executionId)
+    this.callFiles.set(key, structuredClone(record))
+    return structuredClone(record)
+  }
+
+  async getModelCallFiles(input: GetAiModelCallFilesInput): Promise<AiModelCallFilesRecord | null> {
+    const record = this.callFiles.get(modelCallRecordKey(input.projectId, input.callId))
+    return record ? structuredClone(record) : null
+  }
+
   snapshot(): InMemoryAiUsageStorageSnapshot {
     return structuredClone({
       records: this.records,
       recordKeysByIdempotencyKey: this.recordKeysByIdempotencyKey,
       groupRows: this.groupRows,
+      callFiles: this.callFiles,
     })
   }
 
@@ -142,6 +168,7 @@ export class InMemoryAiUsageStorage implements AiUsageStorage {
     replaceMap(this.records, snapshot.records)
     replaceMap(this.recordKeysByIdempotencyKey, snapshot.recordKeysByIdempotencyKey)
     replaceMap(this.groupRows, snapshot.groupRows)
+    replaceMap(this.callFiles, snapshot.callFiles)
   }
 
   /** @internal Immutable accounting source used by in-memory AI limit enforcement. */

package/src/storage/ai-usage/index.ts

@@ -5,15 +5,23 @@ export type {
   InMemoryAiUsageStorageSnapshot,
 } from "./in-memory"
 export { InMemoryAiUsageStorage } from "./in-memory"
-export { assertAiUsageExecutionId, normalizeAiModelCallRecord } from "./record"
+export {
+  assertAiUsageExecutionId,
+  assertSameCallExecution,
+  normalizeAiModelCallFilesRecord,
+  normalizeAiModelCallRecord,
+} from "./record"
 export type {
+  AiModelCallFilesRecord,
   AiModelCallUsage,
   AiModelCallUsageInput,
   AiModelCallUsageRecord,
   AiUsageExecutionSummary,
   AiUsageReportingStatus,
   AiUsageStorage,
+  GetAiModelCallFilesInput,
   GetLatestAiModelCallForExecutionInput,
+  RecordAiModelCallFilesInput,
   RecordAiModelCallInput,
   RecordAiModelCallResult,
   SummarizeAiUsageExecutionInput,