@sixb/core 0.1.16 → 0.1.18

package/src/security/registry.ts

@@ -1,10 +1,17 @@
 import { type ResolvedRole, resolveRoleGrants } from "../authorization"
 import { APPLICATION_IDS } from "./applications"
-import type { GroupDefinition, MembershipPolicyDefinition, RoleDefinition } from "./types"
+import type {
+  GroupDefinition,
+  MarkingDefinition,
+  MembershipPolicyDefinition,
+  RoleDefinition,
+} from "./types"
 import { validateSecurityDefinitionsAtStartup } from "./validation"
 
 /** Read-only access to validated security definitions and resolved role grants. */
 export interface SecurityDefinitionCatalog {
+  listMarkings(): readonly MarkingDefinition[]
+  getMarkingById(markingId: string): MarkingDefinition | null
   listGroups(): readonly GroupDefinition[]
   getGroupById(groupId: string): GroupDefinition | null
   listRoles(): readonly RoleDefinition[]
@@ -15,6 +22,7 @@ export interface SecurityDefinitionCatalog {
 }
 
 export interface SecurityRegistryOptions {
+  readonly markings?: readonly MarkingDefinition[]
   readonly groups?: readonly GroupDefinition[]
   readonly roles?: readonly RoleDefinition[]
   readonly membershipPolicies?: readonly MembershipPolicyDefinition[]
@@ -32,6 +40,7 @@ export interface SecurityRegistryOptions {
 }
 
 export class SecurityRegistry implements SecurityDefinitionCatalog {
+  private readonly markingsById: ReadonlyMap<string, MarkingDefinition>
   private readonly groupsById: ReadonlyMap<string, GroupDefinition>
   private readonly rolesById: ReadonlyMap<string, RoleDefinition>
   private readonly membershipPoliciesById: ReadonlyMap<string, MembershipPolicyDefinition>
@@ -39,6 +48,7 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
 
   constructor(input: SecurityRegistryOptions) {
     const definitions = validateSecurityDefinitionsAtStartup({
+      markings: input.markings ?? [],
       groups: input.groups ?? [],
       roles: input.roles ?? [],
       membershipPolicies: input.membershipPolicies ?? [],
@@ -71,6 +81,7 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       getSubTypes: input.getSubTypes ?? (() => []),
     }
 
+    this.markingsById = definitions.markingsById
     this.groupsById = definitions.groupsById
     this.rolesById = definitions.rolesById
     this.membershipPoliciesById = definitions.membershipPoliciesById
@@ -78,9 +89,18 @@ export class SecurityRegistry implements SecurityDefinitionCatalog {
       id: role.id,
       grantedToGroupIds: role.grantedToGroupIds,
       grants: resolveRoleGrants(role, universe),
+      clearances: new Set(role.clearances ?? []),
     }))
   }
 
+  listMarkings(): readonly MarkingDefinition[] {
+    return [...this.markingsById.values()]
+  }
+
+  getMarkingById(markingId: string): MarkingDefinition | null {
+    return this.markingsById.get(markingId) ?? null
+  }
+
   listGroups(): readonly GroupDefinition[] {
     return [...this.groupsById.values()]
   }

package/src/security/types.ts

@@ -7,6 +7,28 @@ export interface GroupDefinition<TId extends string = string> {
   readonly description?: string
 }
 
+/**
+ * A classification carried by sensitive properties and dataset columns.
+ *
+ * A principal reads a marked value only when one of its roles lists the marking in `clearances`.
+ * No grant bypasses a marking.
+ */
+export interface MarkingDefinition<TId extends string = string> {
+  readonly kind: "marking"
+  readonly id: TId
+  readonly label?: string
+  readonly description?: string
+}
+
+/** Why a value was omitted from a read. */
+export type RedactionReason = "missing_clearance"
+
+/**
+ * Values omitted from a read, keyed by property id or column name. A redacted value is absent,
+ * never `null`.
+ */
+export type Redactions = Readonly<Record<string, { readonly reason: RedactionReason }>>
+
 /**
  * A group named either by its definition or by its id.
  *
@@ -149,6 +171,8 @@ export interface RoleDefinition<TId extends string = string> {
   readonly description?: string
   readonly grantedToGroupIds: readonly string[]
   readonly grants: readonly GrantDefinition[]
+  /** Ids of the markings this role's members may read. Absent means none. */
+  readonly clearances?: readonly string[]
 }
 
 export type MembershipOperation = "invite" | "assignGroups" | "suspend"
@@ -162,6 +186,8 @@ export interface MembershipPolicyDefinition<TId extends string = string> {
 }
 
 export interface RegisteredSecurityDefinitions {
+  readonly markings: readonly MarkingDefinition[]
+  readonly markingsById: ReadonlyMap<string, MarkingDefinition>
   readonly groups: readonly GroupDefinition[]
   readonly groupsById: ReadonlyMap<string, GroupDefinition>
   readonly roles: readonly RoleDefinition[]

package/src/security/validation.ts

@@ -5,6 +5,7 @@ import type {
   GrantCapability,
   GrantDefinition,
   GroupDefinition,
+  MarkingDefinition,
   MembershipPolicyDefinition,
   RegisteredSecurityDefinitions,
   RoleDefinition,
@@ -132,6 +133,32 @@ function assertNoDuplicateOperations(
   }
 }
 
+export function assertMarkingDefinition(
+  value: unknown,
+  createError: CreateSecurityError = (message) => new SecurityValidationError(message)
+): asserts value is MarkingDefinition {
+  if (!isRecord(value)) {
+    throw createError("[Sixb] Marking definition must be an object.")
+  }
+
+  if (value.kind !== "marking") {
+    throw createError("[Sixb] Marking definition kind must be 'marking'.")
+  }
+
+  assertNonEmptyString(value.id, "Marking id", createError)
+  assertOptionalString(value.label, `Marking '${value.id}' label`, createError)
+  assertOptionalString(value.description, `Marking '${value.id}' description`, createError)
+}
+
+export function isMarkingDefinition(value: unknown): value is MarkingDefinition {
+  try {
+    assertMarkingDefinition(value, (message) => new Error(message))
+    return true
+  } catch {
+    return false
+  }
+}
+
 export function assertGroupDefinition(
   value: unknown,
   createError: CreateSecurityError = (message) => new SecurityValidationError(message)
@@ -285,6 +312,10 @@ export function assertRoleDefinition(
   for (const grant of value.grants) {
     assertGrantDefinition(grant, `Role '${value.id}' grants`, createError)
   }
+
+  if (value.clearances !== undefined) {
+    assertStringArray(value.clearances, `Role '${value.id}' clearances`, createError)
+  }
 }
 
 export function isRoleDefinition(value: unknown): value is RoleDefinition {
@@ -297,6 +328,7 @@ export function isRoleDefinition(value: unknown): value is RoleDefinition {
 }
 
 export function validateSecurityDefinitionsAtStartup(input: {
+  readonly markings?: readonly MarkingDefinition[]
   readonly groups: readonly GroupDefinition[]
   readonly membershipPolicies: readonly MembershipPolicyDefinition[]
   readonly roles?: readonly RoleDefinition[]
@@ -325,10 +357,21 @@ export function validateSecurityDefinitionsAtStartup(input: {
   /** Registered Share ids — when provided, share grants must reference them. */
   readonly shareIds?: ReadonlySet<string>
 }): RegisteredSecurityDefinitions {
+  const markingsById = new Map<string, MarkingDefinition>()
   const groupsById = new Map<string, GroupDefinition>()
   const rolesById = new Map<string, RoleDefinition>()
   const membershipPoliciesById = new Map<string, MembershipPolicyDefinition>()
 
+  for (const marking of input.markings ?? []) {
+    assertMarkingDefinition(marking)
+
+    if (markingsById.has(marking.id)) {
+      throw new SecurityValidationError(`[Sixb] Duplicate marking id: ${marking.id}`)
+    }
+
+    markingsById.set(marking.id, marking)
+  }
+
   for (const group of input.groups) {
     assertGroupDefinition(group)
 
@@ -352,11 +395,23 @@ export function validateSecurityDefinitionsAtStartup(input: {
       )
     }
 
-    if (role.grants.length === 0) {
-      throw new SecurityValidationError(`[Sixb] Role '${role.id}' must declare at least one grant.`)
+    const clearances = role.clearances ?? []
+    if (role.grants.length === 0 && clearances.length === 0) {
+      throw new SecurityValidationError(
+        `[Sixb] Role '${role.id}' must declare at least one grant or clearance.`
+      )
     }
 
     assertNoDuplicateIds(role.grantedToGroupIds, `Role '${role.id}' grantedTo`)
+    assertNoDuplicateIds(clearances, `Role '${role.id}' clearances`)
+
+    for (const markingId of clearances) {
+      if (!markingsById.has(markingId)) {
+        throw new SecurityValidationError(
+          `[Sixb] Role '${role.id}' clearances reference unknown marking '${markingId}'. Add it to 'security/markings/' or pass it to createSixb({ markings }).`
+        )
+      }
+    }
 
     for (const groupId of role.grantedToGroupIds) {
       if (!groupsById.has(groupId)) {
@@ -416,6 +471,8 @@ export function validateSecurityDefinitionsAtStartup(input: {
   }
 
   return {
+    markings: [...markingsById.values()],
+    markingsById,
     groups: [...groupsById.values()],
     groupsById,
     roles: [...rolesById.values()],

package/src/storage/agents/provider.ts

@@ -150,6 +150,17 @@ export function assertConversationAgentRunSpec(
       `[${prefix}] Conversational Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
     )
   }
+  for (const [name, value] of [
+    ["timeZone", spec.timeZone],
+    ["locale", spec.locale],
+  ] as const) {
+    if (value !== undefined && (typeof value !== "string" || value.trim().length === 0)) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Conversational Agent run '${name}' must be a non-empty string.`
+      )
+    }
+  }
 }
 
 function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {

package/src/storage/agents/types.ts

@@ -1,5 +1,5 @@
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message"
-import type { AgentReasoningLevel } from "../../agents/types"
+import type { AgentReasoning } from "../../agents/types"
 import type { Principal } from "../../auth"
 import type { FileRef } from "../../blob-storage"
 import type { SixbErrorCode, SixbFailure } from "../../errors/types"
@@ -123,8 +123,9 @@ export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number]
 
 /**
  * Why a run ended — Sixb's provider-independent vocabulary. It includes model-loop reasons plus
- * platform-level endings such as `timeout`, so reads remain typed and exhaustive. `other` and
- * `unknown` preserve terminal state when a provider adds a new reason.
+ * platform-level endings such as `timeout`, or `interrupted` for a turn whose worker died before
+ * finishing it, so reads remain typed and exhaustive. `other` and `unknown` preserve terminal state
+ * when a provider adds a new reason.
  */
 export const AGENT_RUN_FINISH_REASONS = [
   "stop",
@@ -132,6 +133,7 @@ export const AGENT_RUN_FINISH_REASONS = [
   "content-filter",
   "tool-calls",
   "timeout",
+  "interrupted",
   "error",
   "other",
   "unknown",
@@ -162,6 +164,7 @@ export const AGENT_RUN_DIAGNOSTIC_CODES = [
   "output_collection_failed",
   "output_file_changed",
   "output_storage_failed",
+  "step_limit_reached",
 ] as const
 
 /**
@@ -178,7 +181,8 @@ export type AgentRunDiagnosticSeverity = "warning" | "error"
 export interface AgentRunDiagnostic {
   readonly code: AgentRunDiagnosticCode
   readonly severity: AgentRunDiagnosticSeverity
-  readonly scope: "output"
+  /** `output` for published files, `run` for the turn as a whole. */
+  readonly scope: "output" | "run"
   /** Relative path inside the run's published output directory, when one file is involved. */
   readonly path?: string
   /** Sanitized, stable copy suitable for display to an end user. */
@@ -224,16 +228,20 @@ export interface ConversationAgentRunRecord extends AgentRunRecordBase {
   readonly spec?: ConversationAgentRunSpec
 }
 
-/** Immutable, serialisable model selection for one conversational turn. */
+/** Immutable, serialisable model selection and requester settings for one conversational turn. */
 export interface ConversationAgentRunSpec {
   readonly model: LanguageModelRef
-  readonly reasoning?: AgentReasoningLevel
+  readonly reasoning?: AgentReasoning
+  /** Canonical IANA time zone of the requester. Absent uses the project time zone. */
+  readonly timeZone?: string
+  /** Canonical BCP 47 language of the requester. Absent uses the project locale. */
+  readonly locale?: string
 }
 
 /** Immutable, serialisable child configuration captured before dispatch. */
 export interface SubagentRunSpec {
   readonly model: LanguageModelRef
-  readonly reasoning?: AgentReasoningLevel
+  readonly reasoning?: AgentReasoning
   /** Focused task supplied by the parent Agent. */
   readonly task: string
   /** Project tools available when the child was admitted. Runtime tools are injected separately. */

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

@@ -68,6 +68,7 @@ export interface AiAccountingAggregateFragment {
     readonly cacheWriteInputTokens: AiAccountingUsageMeterFragment
     readonly textOutputTokens: AiAccountingUsageMeterFragment
     readonly reasoningOutputTokens: AiAccountingUsageMeterFragment
+    readonly audioDurationMs: AiAccountingUsageMeterFragment
   }
   readonly costs: {
     readonly amount?: AiMoney
@@ -406,6 +407,7 @@ const AGGREGATE_USAGE_FIELDS = [
   "cacheWriteInputTokens",
   "textOutputTokens",
   "reasoningOutputTokens",
+  "audioDurationMs",
 ] as const
 
 type AggregateUsageField = (typeof AGGREGATE_USAGE_FIELDS)[number]

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

@@ -110,7 +110,8 @@ function billableMeter(value: unknown): AiBillableMeter {
     value !== "tokens.input.cacheWrite1h" &&
     value !== "tokens.output.total" &&
     value !== "tokens.output.text" &&
-    value !== "tokens.output.reasoning"
+    value !== "tokens.output.reasoning" &&
+    value !== "audio.input.milliseconds"
   ) {
     throw invalidDetails()
   }

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

@@ -6,6 +6,7 @@ import type {
 
 /** Token meters supported by deterministic local rate cards. */
 export type AiBillableMeter =
+  | "audio.input.milliseconds"
   | "tokens.input.total"
   | "tokens.input.uncached"
   | "tokens.input.cacheRead"

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

@@ -15,8 +15,8 @@ import type {
 } from "./types"
 
 const SIGNED_INT64_MAX = 9_223_372_036_854_775_807n
-const TOKENS_PER_MILLION = 1_000_000n
-const HALF_MILLION = TOKENS_PER_MILLION / 2n
+const UNITS_PER_MILLION = 1_000_000n
+const HALF_MILLION = UNITS_PER_MILLION / 2n
 const MAX_NUMERIC_TEXT_LENGTH = 128
 const METER_ORDER: Readonly<Record<AiBillableMeter, number>> = {
   "tokens.input.total": 0,
@@ -28,6 +28,7 @@ const METER_ORDER: Readonly<Record<AiBillableMeter, number>> = {
   "tokens.output.total": 6,
   "tokens.output.text": 7,
   "tokens.output.reasoning": 8,
+  "audio.input.milliseconds": 9,
 }
 const METERS = new Set(Object.keys(METER_ORDER) as AiBillableMeter[])
 const UNPRICEABLE_REASONS = new Set<AiUnpriceableReason>([
@@ -120,11 +121,7 @@ export function aiModelCallCostMatchesUsage(
     const components = new Map(
       record.estimate.components.map((component) => [component.meter, component])
     )
-    if (
-      !inputComponentsMatchUsage(components, usage) ||
-      !outputComponentsMatchUsage(components, usage)
-    )
-      return false
+    if (!componentsMatchUsage(components, usage)) return false
   }
   if (record.status === "unpriceable") return true
   if (record.components.length === 0 && isExternalValuationSource(record.priceSource.sourceId)) {
@@ -133,6 +130,22 @@ export function aiModelCallCostMatchesUsage(
 
   const usage = normalizeAiModelCallUsage(usageRecord.usage)
   const components = new Map(record.components.map((component) => [component.meter, component]))
+  return componentsMatchUsage(components, usage)
+}
+
+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)
+    )
+  }
+
   return (
     inputComponentsMatchUsage(components, usage) && outputComponentsMatchUsage(components, usage)
   )
@@ -362,7 +375,7 @@ function calculateComponent(
 ): AiCostComponent {
   const normalizedQuantity = parseQuantity(quantity, `${meter} quantity`)
   const rate = parseNonnegativeInt64(rateAmountNanosPerMillion, `${meter} rate`)
-  const charge = (normalizedQuantity * rate + HALF_MILLION) / TOKENS_PER_MILLION
+  const charge = (normalizedQuantity * rate + HALF_MILLION) / UNITS_PER_MILLION
   assertSignedInt64(charge, `${meter} charge`)
   return {
     meter,

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

@@ -8,6 +8,7 @@ import {
   AiLimitOperationLock,
   aiLimitAccountingEntryAppliesToSubject,
   aiLimitAmountKey,
+  aiLimitMeterApplies,
   aiLimitPolicyDimensionKey,
   aiLimitQuantityFromAmount,
   aiLimitReservationBuckets,
@@ -227,7 +228,12 @@ export class InMemoryAiLimitStorage implements AiLimitStorage {
       const unavailablePolicies: AiLimitPolicyStatus[] = []
       const unavailableReasons = new Set<"missingEstimate" | "incompleteAccounting">()
       for (const policy of enabledPolicies) {
-        if (!subjectKeys.has(aiLimitSubjectKey(policy.subject))) continue
+        if (
+          !subjectKeys.has(aiLimitSubjectKey(policy.subject)) ||
+          !aiLimitMeterApplies(policy.limit.meter, request.modelKind)
+        ) {
+          continue
+        }
         const limit = normalizeAiLimitAmount(policy.limit)
         const estimate = estimates.get(aiLimitAmountKey(limit))
         const status = await this.policyStatus(policy, request.period)
@@ -268,7 +274,8 @@ export class InMemoryAiLimitStorage implements AiLimitStorage {
       const buckets = aiLimitReservationBuckets(
         enabledPolicies,
         request.subjects,
-        request.estimates
+        request.estimates,
+        request.modelKind
       )
       if (buckets.length === 0) return { status: "notRequired" }
       for (const bucket of buckets) {
@@ -601,6 +608,7 @@ export class InMemoryAiLimitStorage implements AiLimitStorage {
       attempt: record.attempt,
       callId: record.callId,
       occurredAt: new Date(record.occurredAt),
+      ...(record.modelKind === undefined ? {} : { modelKind: record.modelKind }),
       ...(record.usage.totalTokens === undefined ? {} : { totalTokens: record.usage.totalTokens }),
       requesterGroupIds: [...record.requesterGroupIds],
       ...(requester?.type === "user" || requester?.type === "serviceAccount"

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

@@ -1,7 +1,9 @@
+import type { ModelKind } from "../../models/definitions"
 import type { AiMoney } from "../ai-cost"
 import { AiLimitStorageError } from "./errors"
 import { aiLimitCalendarMonth } from "./period"
 import type {
+  AiLimitMeter,
   AiLimitPeriod,
   AiLimitPolicy,
   AiLimitQuantity,
@@ -16,6 +18,20 @@ 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"])
+
+/** @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)
+  )
+}
+
 /** @internal Serialize compound limit operations, including within an existing transaction. */
 export class AiLimitOperationLock {
   private tail: Promise<void> = Promise.resolve()
@@ -55,6 +71,7 @@ export interface AiLimitAccountingEntry {
   readonly attempt: number
   readonly callId: string
   readonly occurredAt: Date
+  readonly modelKind?: ModelKind
   readonly totalTokens?: number
   readonly requesterGroupIds: readonly string[]
   readonly requester?:
@@ -228,6 +245,7 @@ export function normalizeReserveAiModelCall(input: ReserveAiModelCallInput): {
   readonly identity: AiModelCallReservationIdentity
   readonly subjects: readonly AiLimitSubject[]
   readonly estimates: readonly AiLimitQuantity[]
+  readonly modelKind?: ModelKind
   readonly period: AiLimitPeriod
   readonly reservedAt: Date
 } {
@@ -237,6 +255,7 @@ export function normalizeReserveAiModelCall(input: ReserveAiModelCallInput): {
     identity,
     subjects: normalizeAiLimitSubjects(input.subjects),
     estimates: normalizeAiLimitQuantities(input.estimates, "estimates"),
+    ...(input.modelKind === undefined ? {} : { modelKind: input.modelKind }),
     period: aiLimitCalendarMonth(reservedAt),
     reservedAt,
   }
@@ -297,13 +316,16 @@ export function aiLimitReservationRequestKey(
       const amount = normalizeAiLimitAmount(quantity)
       return [amount.meter, amount.currency, amount.amount.toString()]
     }),
+    // Appended only when present, so keys of reservations made before model kinds stay valid.
+    ...(request.modelKind === undefined ? [] : [request.modelKind]),
   ])
 }
 
 export function aiLimitReservationBuckets(
   policies: readonly AiLimitPolicy[],
   subjects: readonly AiLimitSubject[],
-  estimates: readonly AiLimitQuantity[]
+  estimates: readonly AiLimitQuantity[],
+  modelKind?: ModelKind
 ): readonly AiLimitReservationBucket[] {
   const subjectKeys = new Set(subjects.map(aiLimitSubjectKey))
   const estimatesByDimension = new Map(
@@ -313,7 +335,11 @@ export function aiLimitReservationBuckets(
     })
   )
   return policies
-    .filter((policy) => subjectKeys.has(aiLimitSubjectKey(policy.subject)))
+    .filter(
+      (policy) =>
+        subjectKeys.has(aiLimitSubjectKey(policy.subject)) &&
+        aiLimitMeterApplies(policy.limit.meter, modelKind)
+    )
     .flatMap((policy) => {
       const estimate = estimatesByDimension.get(
         aiLimitAmountKey(normalizeAiLimitAmount(policy.limit))
@@ -357,6 +383,7 @@ export function resolveAiLimitActual(
   let accountingStatus: ResolvedAiLimitActual["accountingStatus"] = "complete"
   for (const entry of entries) {
     if (dimension.meter === "tokens.total") {
+      if (!aiLimitMeterApplies(dimension.meter, entry.modelKind)) continue
       if (entry.totalTokens === undefined) {
         accountingStatus = "unavailable"
       } else {

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

@@ -1,3 +1,4 @@
+import type { ModelKind } from "../../models/definitions"
 import type { AiMoney } from "../ai-cost"
 
 /** A project-wide, group, or durable requester identity charged for AI model calls. */
@@ -129,6 +130,8 @@ export interface ReserveAiModelCallInput extends AiModelCallReservationIdentity
   /** The project subject is always added, even when omitted here. */
   readonly subjects: readonly AiLimitSubject[]
   readonly estimates: readonly AiLimitQuantity[]
+  /** Transcription and reranking calls are outside token limits; see `aiLimitMeterApplies`. */
+  readonly modelKind?: ModelKind
   readonly reservedAt?: Date
 }
 

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

@@ -19,6 +19,14 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
   }
   assertNonBlank(input.responseId, "responseId")
 
+  if (
+    input.modelKind !== undefined &&
+    !["language", "image", "video", "embedding", "decision", "transcription", "reranking"].includes(
+      input.modelKind
+    )
+  ) {
+    throw new TypeError("[Sixb] AI model kind is invalid.")
+  }
   const occurredAt = cloneValidDate(input.occurredAt, "occurredAt")
   const recordedAt = cloneValidDate(input.recordedAt ?? new Date(), "recordedAt")
   const requesterGroupIds = normalizeRequesterGroupIds(input.requesterGroupIds)
@@ -37,6 +45,7 @@ export function normalizeAiModelCallRecord(input: RecordAiModelCallInput): AiMod
       ? {}
       : { providerIds: normalizeModelProviderIds(input.providerIds) }),
     requestedModelId: input.requestedModelId,
+    ...(input.modelKind === undefined ? {} : { modelKind: input.modelKind }),
     ...(requestedReasoning === undefined ? {} : { requestedReasoning }),
     ...(input.responseModelId === undefined ? {} : { responseModelId: input.responseModelId }),
     responseId: input.responseId,

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

@@ -1,11 +1,13 @@
 import type { ReadonlyJsonObject } from "../../json"
 import type { ModelReasoning } from "../../models/language-model"
 
-/** How much normalized token usage a provider reported for one model call. */
+/** Coverage of normalized usage. Complete means both token totals are known; duration alone is partial. */
 export type AiUsageReportingStatus = "complete" | "partial" | "unavailable"
 
-/** Provider-neutral token counts accepted at the model-call boundary. */
+/** Provider-neutral usage accepted at the model-call boundary. */
 export interface AiModelCallUsageInput {
+  /** Audio content duration in milliseconds, rounded to the nearest millisecond. Not billed duration. */
+  readonly audioDurationMs?: number
   readonly inputTokens?: number
   readonly outputTokens?: number
   readonly uncachedInputTokens?: number
@@ -15,7 +17,7 @@ export interface AiModelCallUsageInput {
   readonly reasoningOutputTokens?: number
 }
 
-/** Normalized token counts for one completed model call. Details overlap their input/output totals. */
+/** Normalized usage for one completed model call. Token details overlap their input/output totals. */
 export interface AiModelCallUsage extends AiModelCallUsageInput {
   /** Present only when both input and output totals are known. */
   readonly totalTokens?: number
@@ -32,6 +34,8 @@ export interface AiUsageExecutionSummary {
 
 /** Input for an idempotent model-call ledger append. */
 export interface RecordAiModelCallInput {
+  /** Absent for historical calls whose kind was not captured. */
+  readonly modelKind?: import("../../models/definitions").ModelKind
   readonly providerIds?: import("../../models/events").ModelProviderIds
   readonly id: string
   readonly projectId: string
@@ -89,7 +93,7 @@ export interface GetLatestAiModelCallForExecutionInput {
   readonly executionId: string
 }
 
-/** Durable, provider-neutral accounting for completed language-model calls. */
+/** Durable, provider-neutral accounting for completed model calls. */
 export interface AiUsageStorage {
   /**
    * Append one model-call record idempotently. The identity is project, execution ID, attempt, call

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

@@ -8,6 +8,7 @@ const USAGE_FIELDS = [
   "cacheWriteInputTokens",
   "textOutputTokens",
   "reasoningOutputTokens",
+  "audioDurationMs",
 ] as const
 
 type AiUsageField = (typeof USAGE_FIELDS)[number]
@@ -30,6 +31,7 @@ export function normalizeAiModelCallUsage(input: AiModelCallUsageInput): AiModel
         : "unavailable"
 
   return {
+    ...(input.audioDurationMs === undefined ? {} : { audioDurationMs: input.audioDurationMs }),
     ...(input.inputTokens === undefined ? {} : { inputTokens: input.inputTokens }),
     ...(input.outputTokens === undefined ? {} : { outputTokens: input.outputTokens }),
     ...(totalTokens === undefined ? {} : { totalTokens }),