@sixb/core 0.1.6 → 0.1.8

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])
+}

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

@@ -2,6 +2,7 @@ import type { AiModelCallUsageRecord, InMemoryAiUsageStorageSnapshot } from "../
 import type { AiAccountingRecordSetItem } from "./analytics"
 import { buildAiAccountingOverview, buildAiModelCallAccountingList } from "./analytics"
 import { AiCostStorageError } from "./errors"
+import { type AiAccountingGroupIdentity, buildAiModelCallGroups } from "./groups"
 import type {
   AiAccountingAttribution,
   AiAccountingOverview,
@@ -11,6 +12,8 @@ import type {
   AiMoney,
   ListAiModelCallAccountingInput,
   ListAiModelCallAccountingResult,
+  ListAiModelCallGroupsInput,
+  ListAiModelCallGroupsResult,
   QueryAiAccountingOverviewInput,
   SummarizeAiCostExecutionsInput,
 } from "./types"
@@ -25,6 +28,10 @@ interface InMemoryAiCostUsageSource {
 }
 
 export interface InMemoryAiAccountingAttributionSource {
+  resolveGroup?(input: {
+    readonly projectId: string
+    readonly executionId: string
+  }): Promise<{ readonly executionId: string; readonly attribution?: AiAccountingAttribution }>
   resolve(input: {
     readonly projectId: string
     readonly executionId: string
@@ -85,10 +92,45 @@ export class InMemoryAiCostStorage implements AiCostStorage {
     return structuredClone({ recordsByUsage: this.recordsByUsage })
   }
 
+  async listModelCallGroups(
+    input: ListAiModelCallGroupsInput
+  ): Promise<ListAiModelCallGroupsResult> {
+    const items = await this.accountingItems()
+    const roots = new Map<string, Promise<AiAccountingGroupIdentity>>()
+    return buildAiModelCallGroups(
+      input,
+      await Promise.all(
+        items.map(async (item) => {
+          const key = usageRecordKey(item.usage.projectId, item.usage.executionId)
+          let root = roots.get(key)
+          if (!root) {
+            root =
+              this.attribution?.resolveGroup?.({
+                projectId: item.usage.projectId,
+                executionId: item.usage.executionId,
+              }) ??
+              Promise.resolve({
+                executionId: item.usage.executionId,
+                attribution: item.attribution,
+              })
+            roots.set(key, root)
+          }
+          return { ...item, root: await root }
+        })
+      )
+    )
+  }
+
   restore(snapshot: InMemoryAiCostStorageSnapshot): void {
     replaceMap(this.recordsByUsage, snapshot.recordsByUsage)
   }
 
+  /** @internal Immutable accounting source used by in-memory AI limit enforcement. */
+  getRecord(projectId: string, usageRecordId: string): AiModelCallCostRecord | null {
+    const record = this.recordsByUsage.get(usageRecordKey(projectId, usageRecordId))
+    return record ? structuredClone(record) : null
+  }
+
   private usageRecord(projectId: string, id: string): AiModelCallUsageRecord | undefined {
     return [...this.usage.snapshot().records.values()].find(
       (record) => record.projectId === projectId && record.id === id

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

@@ -18,10 +18,14 @@ export type {
   AiBillableMeter,
   AiBillingIdentity,
   AiCostComponent,
+  AiCostEstimate,
   AiCostStorage,
   AiCostSummary,
   AiModelCallAccountingItem,
   AiModelCallCostRecord,
+  AiModelCallExecutionSummary,
+  AiModelCallGroup,
+  AiModelCallGroupSummary,
   AiMoney,
   AiPriceSource,
   AiPricingContext,
@@ -30,6 +34,8 @@ export type {
   AiUnpriceableReason,
   ListAiModelCallAccountingInput,
   ListAiModelCallAccountingResult,
+  ListAiModelCallGroupsInput,
+  ListAiModelCallGroupsResult,
   QueryAiAccountingOverviewInput,
   SummarizeAiCostExecutionsInput,
 } from "./types"

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

@@ -1,4 +1,5 @@
 /** @internal Storage-provider helpers; not part of the app-author API. */
+
 export type {
   AiAccountingAggregateFragment,
   AiAccountingRecordSetItem,
@@ -13,6 +14,12 @@ export {
 } from "./analytics"
 export type { AiModelCallCostDetails } from "./codec"
 export { aiModelCallCostDetails, parseAiModelCallCostDetails } from "./codec"
+export type {
+  AiAccountingGroupIdentity,
+  AiModelCallGroupFragment,
+  AiModelCallGroupRow,
+} from "./groups"
+export { aiModelCallGroupFragmentFromRow, buildAiModelCallGroupsFromFragments } from "./groups"
 export {
   aiModelCallCostMatchesUsage,
   normalizeAiModelCallCostRecord,

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

@@ -1,11 +1,13 @@
 import type { AiModelCallUsageRecord } from "../ai-usage"
 
-/** Token meters supported by the deterministic local catalog rater. */
+/** Token meters supported by deterministic local rate cards. */
 export type AiBillableMeter =
   | "tokens.input.total"
   | "tokens.input.uncached"
   | "tokens.input.cacheRead"
   | "tokens.input.cacheWrite"
+  | "tokens.input.cacheWrite5m"
+  | "tokens.input.cacheWrite1h"
   | "tokens.output.total"
   | "tokens.output.text"
   | "tokens.output.reasoning"
@@ -17,7 +19,7 @@ export interface AiMoney {
   readonly amountNanos: string
 }
 
-/** Provider and model key in a pricing catalog. */
+/** Provider and model identity used for billing. */
 export interface AiBillingIdentity {
   readonly providerId: string
   readonly modelId: string
@@ -30,18 +32,19 @@ export interface AiPricingContext {
   readonly region?: string
   readonly inferenceGeo?: string
   readonly routedProviderId?: string
+  readonly routedModelId?: string
   readonly deploymentId?: string
   readonly inferenceProfileId?: string
   readonly cacheWriteTtlSeconds?: number
   readonly mode?: string
 }
 
-/** Immutable provenance of the compact catalog entry applied to a valuation. */
+/** Immutable provenance of the provider report or rate card applied to a valuation. */
 export interface AiPriceSource {
   readonly sourceId: string
   readonly sourceEntryId: string
   readonly sourceVersion: string
-  readonly sourceUrl: string
+  readonly sourceUrl?: string
   readonly observedAt: Date
 }
 
@@ -54,31 +57,46 @@ export interface AiCostComponent {
 
 export type AiUnpriceableReason =
   | "missingBillingIdentity"
-  | "missingCatalogEntry"
+  | "missingRateCard"
   | "missingUsageMeter"
   | "unsupportedPricingDimension"
   | "invalidUsageForFormula"
 
 interface AiModelCallCostRecordBase {
+  /** Local estimate retained independently when an inline provider cost is selected. */
+  readonly estimate?: AiCostEstimate
   readonly projectId: string
   readonly usageRecordId: string
   readonly pricingContext: AiPricingContext
-  readonly priceSource: AiPriceSource
   readonly ratedAt: Date
 }
 
-/** Exact arithmetic under one immutable catalog snapshot; not a provider-settled charge. */
+export type AiCostEstimate =
+  | {
+      readonly status: "rated"
+      readonly money: AiMoney
+      readonly components: readonly AiCostComponent[]
+    }
+  | {
+      readonly status: "unpriceable"
+      readonly reason: AiUnpriceableReason
+      readonly missingMeters?: readonly AiBillableMeter[]
+    }
+
+/** Selected monetary valuation; its observation/provenance distinguishes estimates from reports. */
 export interface AiRatedModelCallCostRecord extends AiModelCallCostRecordBase {
   readonly status: "rated"
   readonly billingIdentity: AiBillingIdentity
+  readonly priceSource: AiPriceSource
   readonly money: AiMoney
   readonly components: readonly AiCostComponent[]
 }
 
-/** Explicit result when the compact catalog cannot completely and safely value a call. */
+/** Explicit result when a call cannot be completely and safely valued. */
 export interface AiUnpriceableModelCallCostRecord extends AiModelCallCostRecordBase {
   readonly status: "unpriceable"
   readonly billingIdentity?: AiBillingIdentity
+  readonly priceSource?: AiPriceSource
   readonly reason: AiUnpriceableReason
   readonly missingMeters?: readonly AiBillableMeter[]
 }
@@ -91,6 +109,7 @@ export interface SummarizeAiCostExecutionsInput {
 }
 
 export interface AiCostSummary {
+  /** Selected request valuations, never the sum of competing observations or period reports. */
   readonly amounts: readonly AiMoney[]
   readonly ratedCallCount: number
   readonly unpriceableCallCount: number
@@ -133,9 +152,15 @@ export interface AiAccountingTimeBucket extends AiAccountingAggregate {
   readonly end: Date
 }
 
-export interface AiAccountingAgentBreakdown extends AiAccountingAggregate {
-  readonly agentId: string
-}
+export type AiAccountingAgentBreakdown = AiAccountingAggregate &
+  (
+    | { readonly kind: "agent" }
+    | {
+        readonly kind: "workflowAgent"
+        readonly workflowId: string
+        readonly agentStepId: string
+      }
+  )
 
 export interface AiAccountingWorkflowBreakdown extends AiAccountingAggregate {
   readonly workflowId: string
@@ -159,17 +184,21 @@ export interface AiAccountingOverview {
 export type AiAccountingAttribution =
   | {
       readonly kind: "agent"
-      readonly agentId: string
       readonly agentRunId: string
       readonly threadId: string
     }
   | {
       readonly kind: "workflowAgent"
-      readonly agentId: string
+      readonly agentStepId: string
       readonly nodeRunId: string
       readonly workflowId: string
       readonly workflowRunId: string
     }
+  | {
+      readonly kind: "subagent"
+      readonly subagentRunId: string
+      readonly parentRunId: string
+    }
 
 export interface AiModelCallAccountingItem {
   readonly usage: AiModelCallUsageRecord
@@ -184,10 +213,43 @@ export interface ListAiModelCallAccountingResult {
   readonly total: number
 }
 
-/** Immutable model-call costs plus execution and project accounting reads. */
+export type ListAiModelCallGroupsInput = Omit<ListAiModelCallAccountingInput, "executionId">
+
+/** Filtered usage; an absent token total means at least one call did not report it. */
+export interface AiModelCallGroupSummary {
+  readonly modelCallCount: number
+  readonly totalTokens?: number
+  readonly costs: AiCostSummary
+}
+
+export interface AiModelCallExecutionSummary extends AiModelCallGroupSummary {
+  readonly executionId: string
+  readonly attribution?: AiAccountingAttribution
+  readonly firstCallAt: Date
+  readonly lastCallAt: Date
+  readonly models: readonly AiBillingIdentity[]
+}
+
+/** One initiating execution, including only calls matching the accounting filters. */
+export interface AiModelCallGroup extends AiModelCallGroupSummary {
+  readonly executionId: string
+  readonly attribution?: AiAccountingAttribution
+  readonly firstCallAt: Date
+  readonly lastCallAt: Date
+  readonly executions: readonly AiModelCallExecutionSummary[]
+}
+
+export interface ListAiModelCallGroupsResult {
+  readonly items: readonly AiModelCallGroup[]
+  readonly total: number
+  readonly hasMore: boolean
+}
+
+/** Immutable call-time costs. Inline provider costs take precedence over local estimates. */
 export interface AiCostStorage {
   recordModelCallCost(input: AiModelCallCostRecord): Promise<void>
   summarizeExecutions(input: SummarizeAiCostExecutionsInput): Promise<readonly AiCostSummary[]>
   queryProjectOverview(input: QueryAiAccountingOverviewInput): Promise<AiAccountingOverview>
   listModelCalls(input: ListAiModelCallAccountingInput): Promise<ListAiModelCallAccountingResult>
+  listModelCallGroups(input: ListAiModelCallGroupsInput): Promise<ListAiModelCallGroupsResult>
 }