@sixb/core 0.1.6 → 0.1.7

package/src/storage/agents/types.ts

@@ -1,7 +1,10 @@
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message"
+import type { AgentReasoningLevel } from "../../agents/types"
 import type { Principal } from "../../auth"
+import type { FileRef } from "../../blob-storage"
 import type { SixbErrorCode, SixbFailure } from "../../errors/types"
 import type { JsonValue } from "../../json"
+import type { LanguageModelRef } from "../../models"
 
 // ── agent_threads — one conversation with an agent ──────────────────────────────────────────────
 
@@ -10,7 +13,6 @@ export type AgentThreadStatus = "active" | "archived"
 export interface AgentThreadRecord {
   readonly id: string
   readonly projectId: string
-  readonly agentId: string
   /** Who owns/opened the thread. Reuses the canonical auth principal (gains `agent` later for free). */
   readonly ownerPrincipal: Principal
   readonly title?: string
@@ -26,7 +28,6 @@ export interface AgentThreadRecord {
 export interface CreateAgentThreadInput {
   readonly id: string
   readonly projectId: string
-  readonly agentId: string
   readonly ownerPrincipal: Principal
   readonly title?: string
   readonly status?: AgentThreadStatus
@@ -36,9 +37,6 @@ export interface CreateAgentThreadInput {
 
 export interface ListAgentThreadsInput {
   readonly projectId: string
-  readonly agentId?: string
-  /** Optional allowlist intersected with `agentId` when both are provided. Empty means no rows. */
-  readonly agentIds?: readonly string[]
   readonly statuses?: readonly AgentThreadStatus[]
   readonly ownerPrincipal?: Principal
   readonly limit?: number
@@ -58,21 +56,23 @@ export interface ListAgentThreadsResult {
 export type AgentExecutionStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled"
 
 export type AgentRunStatus = AgentExecutionStatus
+export type AgentRunKind = "conversation" | "subagent"
 
 /** Error codes an agent execution can persist and expose through its public contract. */
 export const AGENT_RUN_FAILURE_CODES = [
   "internal.unexpected",
   "runtime.cancelled",
   "agent.execution_failed",
+  "ai.usage_limit_exceeded",
+  "ai.usage_limit_unavailable",
 ] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
 
 export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number]
 
 /**
- * Why a run ended — our own SDK-independent vocabulary. It includes the AI SDK's unified finish
- * reasons plus platform-level endings such as `timeout`, so reads are typed and exhaustive without
- * core depending on `ai`. `other`/`unknown` are catch-alls: an unrecognised provider value still
- * records *that* the run ended.
+ * 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.
  */
 export const AGENT_RUN_FINISH_REASONS = [
   "stop",
@@ -144,13 +144,10 @@ export interface AgentRunExecution {
   readonly queueLeaseExpiresAt: Date
 }
 
-export interface AgentRunRecord {
+interface AgentRunRecordBase {
   readonly id: string
   readonly projectId: string
   readonly executionId: string
-  readonly threadId: string
-  readonly agentId: string
-  readonly triggerMessageId: string
   /** Durable group memberships snapshotted when the run was admitted. */
   readonly requesterGroupIds: readonly string[]
   readonly status: AgentRunStatus
@@ -169,17 +166,73 @@ export interface AgentRunRecord {
   readonly completedAt?: Date
 }
 
+export interface ConversationAgentRunRecord extends AgentRunRecordBase {
+  readonly kind: "conversation"
+  readonly threadId: string
+  readonly triggerMessageId: string
+  /** Immutable model selection captured at admission. Absent only on runs predating this field. */
+  readonly spec?: ConversationAgentRunSpec
+}
+
+/** Immutable, serialisable model selection for one conversational turn. */
+export interface ConversationAgentRunSpec {
+  readonly model: LanguageModelRef
+  readonly reasoning?: AgentReasoningLevel
+}
+
+/** Immutable, serialisable child configuration captured before dispatch. */
+export interface SubagentRunSpec {
+  readonly model: LanguageModelRef
+  readonly reasoning?: AgentReasoningLevel
+  /** Focused task supplied by the parent Agent. */
+  readonly task: string
+  /** Project tools available when the child was admitted. Runtime tools are injected separately. */
+  readonly toolNames: readonly string[]
+  readonly maxSteps: number
+}
+
+/** Durable child output returned to its parent by `wait_agent`. */
+export interface SubagentRunResult {
+  readonly text?: string
+  readonly files?: readonly FileRef[]
+}
+
+export interface SubagentRunRecord extends AgentRunRecordBase {
+  readonly kind: "subagent"
+  readonly parentRunId: string
+  /** Stable parent-selected key that makes repeated tool execution idempotent. */
+  readonly spawnKey: string
+  readonly spec: SubagentRunSpec
+  readonly result?: SubagentRunResult
+}
+
+export type AgentRunRecord = ConversationAgentRunRecord | SubagentRunRecord
+
 export interface CreateAgentRunInput {
   readonly id: string
   readonly projectId: string
   readonly executionId: string
   readonly threadId: string
-  readonly agentId: string
   readonly triggerMessageId: string
+  readonly spec: ConversationAgentRunSpec
   readonly requesterGroupIds: readonly string[]
   readonly createdAt?: Date
 }
 
+export interface CreateSubagentRunInput {
+  readonly id: string
+  readonly projectId: string
+  readonly executionId: string
+  readonly parentRunId: string
+  /** Current parent delivery token. New children are admitted only while that delivery owns it. */
+  readonly parentExecutionToken: string
+  readonly spawnKey: string
+  readonly spec: SubagentRunSpec
+  /** Internal safety bound enforced atomically across worker processes. */
+  readonly maxActiveChildren: number
+  readonly createdAt?: Date
+}
+
 export interface StartAgentRunInput {
   readonly id: string
   readonly projectId: string
@@ -219,6 +272,7 @@ export type FinishAgentRunInput =
       readonly modelId?: string
       readonly finishReason?: AgentRunFinishReason
       readonly diagnostics?: readonly AgentRunDiagnostic[]
+      readonly result?: SubagentRunResult
       readonly completedAt?: Date
     }
   | {
@@ -235,8 +289,9 @@ export type FinishAgentRunInput =
 
 export interface ListAgentRunsInput {
   readonly projectId: string
+  readonly kinds?: readonly AgentRunKind[]
   readonly threadId?: string
-  readonly agentId?: string
+  readonly parentRunId?: string
   readonly statuses?: readonly AgentRunStatus[]
   /** Effective start time; runs that never started use `createdAt`. */
   readonly startedAfter?: Date
@@ -371,7 +426,9 @@ export interface AgentThreadStore {
 
 export interface AgentRunStore {
   /** Persist a queued run and atomically claim the thread's single-flight slot. */
-  create(input: CreateAgentRunInput): Promise<AgentRunRecord>
+  create(input: CreateAgentRunInput): Promise<ConversationAgentRunRecord>
+  /** Persist or replay one idempotent child run while atomically enforcing parent fan-out. */
+  createSubagent(input: CreateSubagentRunInput): Promise<SubagentRunRecord>
   /** Transition a queued run to running and install the first delivery's execution token. */
   start(input: StartAgentRunInput): Promise<AgentRunRecord>
   /** Finish a queued run before execution and release the thread's single-flight slot. */

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

@@ -59,7 +59,8 @@ export interface AiAccountingAggregateFragment {
   readonly start?: Date
   readonly providerId?: string
   readonly modelId?: string
-  readonly agentId?: string
+  readonly agentKind?: "agent" | "workflowAgent"
+  readonly agentStepId?: string
   readonly workflowId?: string
   readonly modelCallCount: string
   readonly usage: {
@@ -154,7 +155,19 @@ export function buildAiAccountingOverview(
       JSON.stringify([item.usage.providerId, item.usage.requestedModelId]),
       item
     )
-    if (item.attribution) appendGrouped(agentItems, item.attribution.agentId, item)
+    if (item.attribution?.kind === "agent") {
+      appendGrouped(agentItems, JSON.stringify(["agent"]), item)
+    } else if (item.attribution?.kind === "workflowAgent") {
+      appendGrouped(
+        agentItems,
+        JSON.stringify([
+          "workflowAgent",
+          item.attribution.workflowId,
+          item.attribution.agentStepId,
+        ]),
+        item
+      )
+    }
     if (item.attribution?.kind === "workflowAgent") {
       appendGrouped(workflowItems, item.attribution.workflowId, item)
     }
@@ -171,7 +184,21 @@ export function buildAiAccountingOverview(
     })
     .sort(compareModelBreakdowns)
   const agents: AiAccountingAgentBreakdown[] = [...agentItems]
-    .map(([agentId, grouped]) => ({ agentId, ...aggregateAccountingItems(grouped) }))
+    .map(([key, grouped]) => {
+      const [kind, workflowId, agentStepId] = JSON.parse(key) as [
+        "agent" | "workflowAgent",
+        string?,
+        string?,
+      ]
+      return kind === "agent"
+        ? { kind, ...aggregateAccountingItems(grouped) }
+        : {
+            kind,
+            workflowId: requiredFragmentString(workflowId, "workflowId"),
+            agentStepId: requiredFragmentString(agentStepId, "agentStepId"),
+            ...aggregateAccountingItems(grouped),
+          }
+    })
     .sort(compareAgentBreakdowns)
   const workflows: AiAccountingWorkflowBreakdown[] = [...workflowItems]
     .map(([workflowId, grouped]) => ({ workflowId, ...aggregateAccountingItems(grouped) }))
@@ -227,7 +254,14 @@ export function buildAiAccountingOverviewFromFragments(
         )
         break
       case "agent":
-        target = getFragmentAccumulator(agents, requiredFragmentString(fragment.agentId, "agentId"))
+        target = getFragmentAccumulator(
+          agents,
+          JSON.stringify([
+            requiredFragmentString(fragment.agentKind, "agentKind"),
+            fragment.workflowId,
+            fragment.agentStepId,
+          ])
+        )
         break
       case "workflow":
         target = getFragmentAccumulator(
@@ -254,7 +288,21 @@ export function buildAiAccountingOverviewFromFragments(
       })
       .sort(compareModelBreakdowns),
     agents: [...agents]
-      .map(([agentId, value]) => ({ agentId, ...finishAggregateFragment(value) }))
+      .map(([key, value]) => {
+        const [kind, workflowId, agentStepId] = JSON.parse(key) as [
+          "agent" | "workflowAgent",
+          string?,
+          string?,
+        ]
+        return kind === "agent"
+          ? { kind, ...finishAggregateFragment(value) }
+          : {
+              kind,
+              workflowId: requiredFragmentString(workflowId, "workflowId"),
+              agentStepId: requiredFragmentString(agentStepId, "agentStepId"),
+              ...finishAggregateFragment(value),
+            }
+      })
       .sort(compareAgentBreakdowns),
     workflows: [...workflows]
       .map(([workflowId, value]) => ({ workflowId, ...finishAggregateFragment(value) }))
@@ -560,7 +608,16 @@ function compareAgentBreakdowns(
   left: AiAccountingAgentBreakdown,
   right: AiAccountingAgentBreakdown
 ): number {
-  return right.modelCallCount - left.modelCallCount || left.agentId.localeCompare(right.agentId)
+  return (
+    right.modelCallCount - left.modelCallCount ||
+    agentBreakdownKey(left).localeCompare(agentBreakdownKey(right))
+  )
+}
+
+function agentBreakdownKey(value: AiAccountingAgentBreakdown): string {
+  return value.kind === "agent"
+    ? "agent"
+    : JSON.stringify(["workflowAgent", value.workflowId, value.agentStepId])
 }
 
 function compareWorkflowBreakdowns(

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

@@ -1,9 +1,16 @@
-import type { AiBillableMeter, AiModelCallCostRecord, AiPricingContext } from "./types"
-import { normalizeAiPricingContext } from "./validation"
+import type {
+  AiBillableMeter,
+  AiCostEstimate,
+  AiModelCallCostRecord,
+  AiPriceSource,
+  AiPricingContext,
+} from "./types"
+import { normalizeAiCostEstimate, normalizeAiPricingContext } from "./validation"
 
 export interface AiModelCallCostDetails {
+  readonly estimate?: AiCostEstimate
   readonly pricingContext: AiPricingContext
-  readonly priceSource: Omit<AiModelCallCostRecord["priceSource"], "observedAt"> & {
+  readonly priceSource?: Omit<AiPriceSource, "observedAt"> & {
     readonly observedAt: string
   }
   readonly components?: Extract<AiModelCallCostRecord, { status: "rated" }>["components"]
@@ -12,8 +19,16 @@ export interface AiModelCallCostDetails {
 
 export function aiModelCallCostDetails(record: AiModelCallCostRecord): AiModelCallCostDetails {
   return {
+    ...(record.estimate === undefined ? {} : { estimate: record.estimate }),
     pricingContext: record.pricingContext,
-    priceSource: { ...record.priceSource, observedAt: record.priceSource.observedAt.toISOString() },
+    ...(record.priceSource === undefined
+      ? {}
+      : {
+          priceSource: {
+            ...record.priceSource,
+            observedAt: record.priceSource.observedAt.toISOString(),
+          },
+        }),
     ...(record.status === "rated" ? { components: record.components } : {}),
     ...(record.status === "unpriceable" && record.missingMeters
       ? { missingMeters: record.missingMeters }
@@ -25,18 +40,25 @@ export function parseAiModelCallCostDetails(value: unknown): AiModelCallCostDeta
   const parsed: unknown = typeof value === "string" ? JSON.parse(value) : value
   if (!isRecord(parsed)) throw invalidDetails()
   const priceSource = parsed.priceSource
-  if (!isRecord(priceSource)) throw invalidDetails()
+  if (priceSource !== undefined && !isRecord(priceSource)) throw invalidDetails()
   const components = parsed.components
   const missingMeters = parsed.missingMeters
   return {
+    ...(parsed.estimate === undefined
+      ? {}
+      : { estimate: normalizeAiCostEstimate(parsed.estimate) }),
     pricingContext: pricingContextFromUnknown(parsed.pricingContext),
-    priceSource: {
-      sourceId: requiredString(priceSource.sourceId),
-      sourceEntryId: requiredString(priceSource.sourceEntryId),
-      sourceVersion: requiredString(priceSource.sourceVersion),
-      sourceUrl: requiredString(priceSource.sourceUrl),
-      observedAt: requiredString(priceSource.observedAt),
-    },
+    ...(priceSource === undefined
+      ? {}
+      : {
+          priceSource: {
+            sourceId: requiredString(priceSource.sourceId),
+            sourceEntryId: requiredString(priceSource.sourceEntryId),
+            sourceVersion: requiredString(priceSource.sourceVersion),
+            ...optionalStringProperty(priceSource, "sourceUrl"),
+            observedAt: requiredString(priceSource.observedAt),
+          },
+        }),
     ...(components === undefined ? {} : { components: costComponentsFromUnknown(components) }),
     ...(missingMeters === undefined ? {} : { missingMeters: metersFromUnknown(missingMeters) }),
   }
@@ -50,6 +72,7 @@ function pricingContextFromUnknown(value: unknown): AiPricingContext {
     ...optionalStringProperty(value, "region"),
     ...optionalStringProperty(value, "inferenceGeo"),
     ...optionalStringProperty(value, "routedProviderId"),
+    ...optionalStringProperty(value, "routedModelId"),
     ...optionalStringProperty(value, "deploymentId"),
     ...optionalStringProperty(value, "inferenceProfileId"),
     ...optionalNumberProperty(value, "cacheWriteTtlSeconds"),
@@ -83,6 +106,8 @@ function billableMeter(value: unknown): AiBillableMeter {
     value !== "tokens.input.uncached" &&
     value !== "tokens.input.cacheRead" &&
     value !== "tokens.input.cacheWrite" &&
+    value !== "tokens.input.cacheWrite5m" &&
+    value !== "tokens.input.cacheWrite1h" &&
     value !== "tokens.output.total" &&
     value !== "tokens.output.text" &&
     value !== "tokens.output.reasoning"

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

@@ -0,0 +1,248 @@
+import type { AiAccountingRecordSetItem } from "./analytics"
+import { aiAccountingItemMatchesQuery, normalizeAiModelCallAccountingQuery } from "./analytics"
+import type {
+  AiAccountingAttribution,
+  AiBillingIdentity,
+  AiCostSummary,
+  AiModelCallExecutionSummary,
+  AiModelCallGroup,
+  AiModelCallGroupSummary,
+  AiMoney,
+  ListAiModelCallGroupsInput,
+  ListAiModelCallGroupsResult,
+} from "./types"
+
+export interface AiAccountingGroupIdentity {
+  readonly executionId: string
+  readonly attribution?: AiAccountingAttribution
+}
+
+/** A compact SQL aggregate, never the raw provider response or a page of individual calls. */
+export interface AiModelCallGroupFragment {
+  readonly root: AiAccountingGroupIdentity
+  readonly execution: AiAccountingGroupIdentity
+  readonly model: AiBillingIdentity
+  readonly firstCallAt: Date
+  readonly lastCallAt: Date
+  readonly callCount: string
+  readonly tokenCount: string
+  readonly totalTokens: string | null
+  readonly valuationStatus: "rated" | "unpriceable" | "unvalued"
+  readonly money?: AiMoney
+}
+
+/** Common provider projection; SQL groups meters before returning rows to the runtime. */
+export interface AiModelCallGroupRow {
+  readonly root_execution_id: string
+  readonly execution_id: string
+  readonly provider_id: string
+  readonly requested_model_id: string
+  readonly first_call_at: Date | string
+  readonly last_call_at: Date | string
+  readonly call_count: string
+  readonly token_count: string
+  readonly total_tokens: string | null
+  readonly valuation_status: AiModelCallGroupFragment["valuationStatus"]
+  readonly amount_currency: string | null
+  readonly amount_high: string | null
+  readonly amount_middle: string | null
+  readonly amount_low: string | null
+  readonly root_agent_run_id: string | null
+  readonly root_thread_id: string | null
+  readonly direct_kind: string | null
+  readonly direct_run_id: string | null
+  readonly parent_run_id: string | null
+  readonly workflow_agent_step_id: string | null
+  readonly workflow_node_run_id: string | null
+  readonly workflow_id: string | null
+  readonly workflow_run_id: string | null
+}
+
+export function aiModelCallGroupFragmentFromRow(
+  row: AiModelCallGroupRow
+): AiModelCallGroupFragment {
+  let attribution: AiAccountingAttribution | undefined
+  if (row.root_agent_run_id && row.root_thread_id) {
+    attribution = {
+      kind: "agent",
+      agentRunId: row.root_agent_run_id,
+      threadId: row.root_thread_id,
+    }
+  } else if (
+    row.workflow_agent_step_id &&
+    row.workflow_node_run_id &&
+    row.workflow_id &&
+    row.workflow_run_id
+  ) {
+    attribution = {
+      kind: "workflowAgent",
+      agentStepId: row.workflow_agent_step_id,
+      nodeRunId: row.workflow_node_run_id,
+      workflowId: row.workflow_id,
+      workflowRunId: row.workflow_run_id,
+    }
+  }
+  const executionAttribution: AiAccountingAttribution | undefined =
+    row.direct_kind === "subagent" && row.direct_run_id && row.parent_run_id
+      ? { kind: "subagent", subagentRunId: row.direct_run_id, parentRunId: row.parent_run_id }
+      : attribution
+  return {
+    root: { executionId: row.root_execution_id, attribution },
+    execution: { executionId: row.execution_id, attribution: executionAttribution },
+    model: { providerId: row.provider_id, modelId: row.requested_model_id },
+    firstCallAt: new Date(row.first_call_at),
+    lastCallAt: new Date(row.last_call_at),
+    callCount: row.call_count,
+    tokenCount: row.token_count,
+    totalTokens: row.total_tokens,
+    valuationStatus: row.valuation_status,
+    ...(row.amount_currency === null
+      ? {}
+      : {
+          money: {
+            currency: row.amount_currency,
+            amountNanos: (
+              BigInt(row.amount_high ?? "0") * 1_000_000_000_000n +
+              BigInt(row.amount_middle ?? "0") * 1_000_000n +
+              BigInt(row.amount_low ?? "0")
+            ).toString(),
+          },
+        }),
+  }
+}
+
+export function buildAiModelCallGroupsFromFragments(
+  fragments: readonly AiModelCallGroupFragment[]
+): readonly AiModelCallGroup[] {
+  const roots = new Map<string, AiModelCallGroupFragment[]>()
+  for (const fragment of fragments) append(roots, fragment.root.executionId, fragment)
+  return [...roots.values()]
+    .map((rootFragments): AiModelCallGroup => {
+      const first = rootFragments[0]!
+      const executions = new Map<string, AiModelCallGroupFragment[]>()
+      for (const fragment of rootFragments)
+        append(executions, fragment.execution.executionId, fragment)
+      return {
+        ...first.root,
+        ...summarize(rootFragments),
+        ...timeRange(rootFragments),
+        executions: [...executions.values()]
+          .map(
+            (items): AiModelCallExecutionSummary => ({
+              ...items[0]!.execution,
+              ...summarize(items),
+              ...timeRange(items),
+              models: [
+                ...new Map(items.map(({ model }) => [JSON.stringify(model), model])).values(),
+              ].sort(
+                (a, b) =>
+                  compareText(a.providerId, b.providerId) || compareText(a.modelId, b.modelId)
+              ),
+            })
+          )
+          .sort(
+            (a, b) =>
+              a.firstCallAt.getTime() - b.firstCallAt.getTime() ||
+              compareText(a.executionId, b.executionId)
+          ),
+      }
+    })
+    .sort(
+      (a, b) =>
+        b.lastCallAt.getTime() - a.lastCallAt.getTime() || compareText(a.executionId, b.executionId)
+    )
+}
+
+export function buildAiModelCallGroups(
+  input: ListAiModelCallGroupsInput,
+  source: readonly (AiAccountingRecordSetItem & { readonly root: AiAccountingGroupIdentity })[]
+): ListAiModelCallGroupsResult {
+  const query = normalizeAiModelCallAccountingQuery(input)
+  const fragments = source
+    .filter(
+      (item) =>
+        aiAccountingItemMatchesQuery(item, query) &&
+        (query.valuationStatus === undefined ||
+          (item.cost?.status ?? "unvalued") === query.valuationStatus)
+    )
+    .map(
+      (item): AiModelCallGroupFragment => ({
+        root: item.root,
+        execution: { executionId: item.usage.executionId, attribution: item.attribution },
+        model: { providerId: item.usage.providerId, modelId: item.usage.requestedModelId },
+        firstCallAt: item.usage.occurredAt,
+        lastCallAt: item.usage.occurredAt,
+        callCount: "1",
+        tokenCount: item.usage.usage.totalTokens === undefined ? "0" : "1",
+        totalTokens: item.usage.usage.totalTokens?.toString() ?? null,
+        valuationStatus: item.cost?.status ?? "unvalued",
+        ...(item.cost && item.cost.status !== "unpriceable" ? { money: item.cost.money } : {}),
+      })
+    )
+  const groups = buildAiModelCallGroupsFromFragments(fragments)
+  const items = groups.slice(query.offset, query.offset + query.limit)
+  return structuredClone({
+    items,
+    total: groups.length,
+    hasMore: query.offset + items.length < groups.length,
+  })
+}
+
+function summarize(items: readonly AiModelCallGroupFragment[]): AiModelCallGroupSummary {
+  let calls = 0n
+  let tokenCount = 0n
+  let tokens = 0n
+  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)
+    tokens += BigInt(item.totalTokens ?? "0")
+    counts[item.valuationStatus] += count
+    if (item.money)
+      money.set(
+        item.money.currency,
+        (money.get(item.money.currency) ?? 0n) + BigInt(item.money.amountNanos)
+      )
+  }
+  const costs: AiCostSummary = {
+    amounts: [...money]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([currency, amount]) => ({ currency, amountNanos: amount.toString() })),
+    ratedCallCount: safeCount(counts.rated),
+    unpriceableCallCount: safeCount(counts.unpriceable),
+    unvaluedCallCount: safeCount(counts.unvalued),
+  }
+  return {
+    modelCallCount: safeCount(calls),
+    ...(calls === tokenCount ? { totalTokens: safeCount(tokens) } : {}),
+    costs,
+  }
+}
+
+function timeRange(items: readonly AiModelCallGroupFragment[]) {
+  let first = items[0]!.firstCallAt.getTime()
+  let last = items[0]!.lastCallAt.getTime()
+  for (const item of items) {
+    first = Math.min(first, item.firstCallAt.getTime())
+    last = Math.max(last, item.lastCallAt.getTime())
+  }
+  return { firstCallAt: new Date(first), lastCallAt: new Date(last) }
+}
+
+function compareText(a: string, b: string): number {
+  return a === b ? 0 : a < b ? -1 : 1
+}
+
+function safeCount(value: bigint): number {
+  if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER))
+    throw new RangeError("[Sixb] AI accounting group count exceeds the safe integer range.")
+  return Number(value)
+}
+
+function append<T>(map: Map<string, T[]>, key: string, item: T): void {
+  const items = map.get(key)
+  if (items) items.push(item)
+  else map.set(key, [item])
+}