nolo-cli 0.1.29 → 0.1.31

package/ai/token/providerBillingHealthReport.ts

@@ -0,0 +1,366 @@
+import type { BillingAnomaly, BillingAnomalySeverity } from "./billingAnomaly";
+import type {
+  BillingAnomalyLifecycleEvent,
+} from "./billingAnomalyLifecycle";
+import type { BillingAnomalyStatus } from "./billingAnomaly";
+import type {
+  ProviderCallCompletedEvent,
+  ProviderCallEvent,
+} from "./providerCall";
+import type {
+  ProviderReconciliationBucket,
+  ProviderReconciliationStatus,
+} from "./providerReconciliation";
+
+export type ProviderBillingHealthStore = {
+  iterator(options: { gte?: string; lte?: string }): AsyncIterable<[string, unknown]>;
+};
+
+export type ProviderBillingHealthTotals = {
+  bucketCount: number;
+  openAnomalyCount: number;
+  totalOfficialRawProviderCostUsd: number;
+  totalLocalRawProviderCostUsd: number;
+  signedRawProviderCostDiffUsd: number;
+  absoluteRawProviderCostDiffUsd: number;
+  riskPlatformCredits: number;
+};
+
+export type ProviderBillingAccountTotals = {
+  provider: string;
+  providerAccountKey: string;
+  providerAccountAlias?: string;
+  officialBillingAccountId?: string;
+  environment?: string;
+  requestCount: number;
+  inputTokens: number;
+  outputTokens: number;
+  rawProviderCostUsd: number;
+  platformCredits: number;
+};
+
+export type ProviderBillingHealthReport = {
+  since: string;
+  until: string;
+  summary: ProviderBillingHealthTotals;
+  statusCounts: Partial<Record<ProviderReconciliationStatus, number>>;
+  severityCounts: Partial<Record<BillingAnomalySeverity, number>>;
+  anomalyStatusCounts: Partial<Record<BillingAnomalyStatus, number>>;
+  byProvider: Record<
+    string,
+    ProviderBillingHealthTotals & {
+      statusCounts: Partial<Record<ProviderReconciliationStatus, number>>;
+    }
+  >;
+  byProviderAccount: Record<string, ProviderBillingAccountTotals>;
+  topBuckets: ProviderReconciliationBucket[];
+  openAnomalies: BillingAnomaly[];
+};
+
+const RECONCILIATION_PREFIX = "provider-reconciliation-bucket-";
+const RECONCILIATION_RANGE_END = `${RECONCILIATION_PREFIX}\uffff`;
+const ANOMALY_PREFIX = "billing-anomaly-";
+const ANOMALY_RANGE_END = `${ANOMALY_PREFIX}\uffff`;
+const ANOMALY_LIFECYCLE_PREFIX = "billing-anomaly-lifecycle-";
+const ANOMALY_LIFECYCLE_RANGE_END = `${ANOMALY_LIFECYCLE_PREFIX}\uffff`;
+const PROVIDER_CALL_PREFIX = "provider-call-";
+const PROVIDER_CALL_RANGE_END = `${PROVIDER_CALL_PREFIX}\uffff`;
+
+const roundMoney = (value: number) => Number(value.toFixed(12));
+
+const emptyTotals = (): ProviderBillingHealthTotals => ({
+  bucketCount: 0,
+  openAnomalyCount: 0,
+  totalOfficialRawProviderCostUsd: 0,
+  totalLocalRawProviderCostUsd: 0,
+  signedRawProviderCostDiffUsd: 0,
+  absoluteRawProviderCostDiffUsd: 0,
+  riskPlatformCredits: 0,
+});
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === "object");
+
+const isProviderReconciliationBucket = (
+  value: unknown
+): value is ProviderReconciliationBucket =>
+  isObject(value) &&
+  typeof value.id === "string" &&
+  typeof value.provider === "string" &&
+  typeof value.bucketStart === "string" &&
+  typeof value.bucketEnd === "string" &&
+  isObject(value.official) &&
+  isObject(value.local) &&
+  isObject(value.diff);
+
+const isBillingAnomaly = (value: unknown): value is BillingAnomaly =>
+  isObject(value) &&
+  typeof value.id === "string" &&
+  typeof value.kind === "string" &&
+  typeof value.severity === "string" &&
+  typeof value.status === "string" &&
+  typeof value.createdAt === "string";
+
+const isBillingAnomalyLifecycleEvent = (
+  value: unknown
+): value is BillingAnomalyLifecycleEvent =>
+  isObject(value) &&
+  value.recordType === "billing_anomaly_lifecycle_event" &&
+  typeof value.anomalyId === "string" &&
+  typeof value.eventId === "string" &&
+  typeof value.status === "string" &&
+  typeof value.createdAt === "string";
+
+const isCompletedProviderCall = (
+  value: unknown
+): value is ProviderCallCompletedEvent =>
+  isObject(value) &&
+  (value as ProviderCallEvent).status === "completed" &&
+  typeof value.provider === "string" &&
+  typeof value.model === "string" &&
+  typeof value.completedAt === "string" &&
+  isObject(value.usage);
+
+const overlapsWindow = ({
+  start,
+  end,
+  sinceMs,
+  untilMs,
+}: {
+  start: string;
+  end: string;
+  sinceMs: number;
+  untilMs: number;
+}) => {
+  const startMs = Date.parse(start);
+  const endMs = Date.parse(end);
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return false;
+  return startMs < untilMs && endMs > sinceMs;
+};
+
+const insideWindow = ({
+  createdAt,
+  sinceMs,
+  untilMs,
+}: {
+  createdAt: string;
+  sinceMs: number;
+  untilMs: number;
+}) => {
+  const createdMs = Date.parse(createdAt);
+  return Number.isFinite(createdMs) && createdMs >= sinceMs && createdMs < untilMs;
+};
+
+const increment = <K extends string>(
+  target: Partial<Record<K, number>>,
+  key: K
+) => {
+  target[key] = (target[key] ?? 0) + 1;
+};
+
+const addBucketToTotals = (
+  totals: ProviderBillingHealthTotals,
+  bucket: ProviderReconciliationBucket
+) => {
+  totals.bucketCount += 1;
+  totals.totalOfficialRawProviderCostUsd = roundMoney(
+    totals.totalOfficialRawProviderCostUsd + bucket.official.rawProviderCostUsd
+  );
+  totals.totalLocalRawProviderCostUsd = roundMoney(
+    totals.totalLocalRawProviderCostUsd + bucket.local.rawProviderCostUsd
+  );
+  totals.signedRawProviderCostDiffUsd = roundMoney(
+    totals.signedRawProviderCostDiffUsd + bucket.diff.rawProviderCostUsd
+  );
+  totals.absoluteRawProviderCostDiffUsd = roundMoney(
+    totals.absoluteRawProviderCostDiffUsd + bucket.diff.absoluteRawProviderCostUsd
+  );
+};
+
+const addAnomalyToTotals = (
+  totals: ProviderBillingHealthTotals,
+  anomaly: BillingAnomaly
+) => {
+  totals.openAnomalyCount += 1;
+  totals.riskPlatformCredits = roundMoney(
+    totals.riskPlatformCredits + (anomaly.riskPlatformCredits ?? 0)
+  );
+};
+
+const addProviderCallToAccountTotals = (
+  target: ProviderBillingAccountTotals,
+  event: ProviderCallCompletedEvent
+) => {
+  target.requestCount += 1;
+  target.inputTokens += event.usage.inputTokens;
+  target.outputTokens += event.usage.outputTokens;
+  if (event.cost.rawProviderCurrency === "USD") {
+    target.rawProviderCostUsd = roundMoney(
+      target.rawProviderCostUsd + (event.cost.rawProviderCost ?? 0)
+    );
+  }
+  target.platformCredits = roundMoney(
+    target.platformCredits + (event.cost.platformCredits ?? 0)
+  );
+};
+
+export async function buildProviderBillingHealthReport({
+  store,
+  since,
+  until,
+  limit = 20,
+}: {
+  store: ProviderBillingHealthStore;
+  since: string;
+  until: string;
+  limit?: number;
+}): Promise<ProviderBillingHealthReport> {
+  const sinceMs = Date.parse(since);
+  const untilMs = Date.parse(until);
+  if (!Number.isFinite(sinceMs) || !Number.isFinite(untilMs) || untilMs <= sinceMs) {
+    throw new Error("since and until must be valid ISO timestamps");
+  }
+
+  const maxRows = Math.min(Math.max(Math.floor(limit), 1), 200);
+  const summary = emptyTotals();
+  const statusCounts: Partial<Record<ProviderReconciliationStatus, number>> = {};
+  const severityCounts: Partial<Record<BillingAnomalySeverity, number>> = {};
+  const anomalyStatusCounts: Partial<Record<BillingAnomalyStatus, number>> = {};
+  const byProvider: ProviderBillingHealthReport["byProvider"] = {};
+  const byProviderAccount: ProviderBillingHealthReport["byProviderAccount"] = {};
+  const buckets: ProviderReconciliationBucket[] = [];
+  const openAnomalies: BillingAnomaly[] = [];
+  const anomalyLifecycleById = new Map<string, BillingAnomalyLifecycleEvent>();
+
+  for await (const [, value] of store.iterator({
+    gte: ANOMALY_LIFECYCLE_PREFIX,
+    lte: ANOMALY_LIFECYCLE_RANGE_END,
+  })) {
+    if (!isBillingAnomalyLifecycleEvent(value)) continue;
+    const existing = anomalyLifecycleById.get(value.anomalyId);
+    if (!existing || Date.parse(value.createdAt) >= Date.parse(existing.createdAt)) {
+      anomalyLifecycleById.set(value.anomalyId, value);
+    }
+  }
+
+  for await (const [, value] of store.iterator({
+    gte: PROVIDER_CALL_PREFIX,
+    lte: PROVIDER_CALL_RANGE_END,
+  })) {
+    if (!isCompletedProviderCall(value)) continue;
+    if (
+      !insideWindow({
+        createdAt: value.completedAt,
+        sinceMs,
+        untilMs,
+      })
+    ) {
+      continue;
+    }
+    const accountKey = value.credential?.providerAccountKey;
+    if (!accountKey) continue;
+    const key = `${value.provider}:${accountKey}`;
+    const totals =
+      byProviderAccount[key] ??
+      ({
+        provider: value.provider,
+        providerAccountKey: accountKey,
+        providerAccountAlias: value.credential?.providerAccountAlias,
+        officialBillingAccountId: value.credential?.officialBillingAccountId,
+        environment: value.credential?.environment,
+        requestCount: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        rawProviderCostUsd: 0,
+        platformCredits: 0,
+      } satisfies ProviderBillingAccountTotals);
+    addProviderCallToAccountTotals(totals, value);
+    byProviderAccount[key] = totals;
+  }
+
+  for await (const [, value] of store.iterator({
+    gte: RECONCILIATION_PREFIX,
+    lte: RECONCILIATION_RANGE_END,
+  })) {
+    if (!isProviderReconciliationBucket(value)) continue;
+    if (
+      !overlapsWindow({
+        start: value.bucketStart,
+        end: value.bucketEnd,
+        sinceMs,
+        untilMs,
+      })
+    ) {
+      continue;
+    }
+
+    buckets.push(value);
+    addBucketToTotals(summary, value);
+    increment(statusCounts, value.status);
+
+    const providerTotals =
+      byProvider[value.provider] ??
+      ({
+        ...emptyTotals(),
+        statusCounts: {},
+      } satisfies ProviderBillingHealthReport["byProvider"][string]);
+    addBucketToTotals(providerTotals, value);
+    increment(providerTotals.statusCounts, value.status);
+    byProvider[value.provider] = providerTotals;
+  }
+
+  for await (const [, value] of store.iterator({
+    gte: ANOMALY_PREFIX,
+    lte: ANOMALY_RANGE_END,
+  })) {
+    if (!isBillingAnomaly(value)) continue;
+    const lifecycle = anomalyLifecycleById.get(value.id);
+    const effectiveStatus = lifecycle?.status ?? value.status;
+    if (!insideWindow({ createdAt: value.createdAt, sinceMs, untilMs })) continue;
+    increment(anomalyStatusCounts, effectiveStatus);
+    if (effectiveStatus !== "open") continue;
+    openAnomalies.push({ ...value, status: effectiveStatus });
+    addAnomalyToTotals(summary, value);
+    increment(severityCounts, value.severity);
+
+    const providerTotals =
+      byProvider[value.provider] ??
+      ({
+        ...emptyTotals(),
+        statusCounts: {},
+      } satisfies ProviderBillingHealthReport["byProvider"][string]);
+    addAnomalyToTotals(providerTotals, value);
+    byProvider[value.provider] = providerTotals;
+  }
+
+  const topBuckets = buckets
+    .sort(
+      (left, right) =>
+        right.diff.absoluteRawProviderCostUsd - left.diff.absoluteRawProviderCostUsd
+    )
+    .slice(0, maxRows);
+  const severityRank: Record<BillingAnomalySeverity, number> = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+  };
+  openAnomalies.sort((left, right) => {
+    const severityDiff = severityRank[right.severity] - severityRank[left.severity];
+    if (severityDiff !== 0) return severityDiff;
+    return Date.parse(right.createdAt) - Date.parse(left.createdAt);
+  });
+
+  return {
+    since,
+    until,
+    summary,
+    statusCounts,
+    severityCounts,
+    anomalyStatusCounts,
+    byProvider,
+    byProviderAccount,
+    topBuckets,
+    openAnomalies: openAnomalies.slice(0, maxRows),
+  };
+}

package/ai/token/providerCall.ts

@@ -0,0 +1,144 @@
+import type { ProviderCredentialIdentity } from "./providerCredential";
+
+export type ProviderCallStatus =
+  | "pending"
+  | "completed"
+  | "failed"
+  | "interrupted"
+  | "anomaly";
+
+export type ProviderCallBillingStatus =
+  | "unpriced"
+  | "pending_ledger"
+  | "charged"
+  | "zero_policy"
+  | "failed";
+
+export type ProviderCallBase = {
+  providerCallId: string;
+  eventId: string;
+  userId: string;
+  dialogId?: string;
+  agentId?: string;
+  provider: string;
+  model: string;
+  endpoint?: string;
+  serviceTier?: string;
+  credential?: ProviderCredentialIdentity;
+  startedAt: string;
+};
+
+export type ProviderCallPendingEvent = ProviderCallBase & {
+  status: "pending";
+};
+
+export type ProviderCallCompletedEvent = ProviderCallBase & {
+  status: "completed";
+  completedAt: string;
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+  };
+  cost: {
+    rawProviderCost?: number;
+    rawProviderCurrency?: string;
+    platformCredits?: number;
+    pricingVersion?: string;
+  };
+  billingStatus: ProviderCallBillingStatus;
+};
+
+export type ProviderCallFailedEvent = ProviderCallBase & {
+  status: "failed";
+  failedAt: string;
+  error: {
+    name?: string;
+    message: string;
+  };
+  billingStatus: "failed";
+};
+
+export type ProviderCallEvent =
+  | ProviderCallPendingEvent
+  | ProviderCallCompletedEvent
+  | ProviderCallFailedEvent;
+
+export const buildProviderCallKey = (providerCallId: string, eventId: string) =>
+  `provider-call-${providerCallId}-event-${eventId}`;
+
+export const createProviderCallPendingEvent = (
+  input: ProviderCallBase
+): ProviderCallPendingEvent => ({
+  ...input,
+  status: "pending",
+});
+
+export const createProviderCallCompletedEvent = (
+  input: ProviderCallBase & {
+    completedAt: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    rawProviderCost?: number;
+    rawProviderCurrency?: string;
+    platformCredits?: number;
+    pricingVersion?: string;
+    billingStatus: ProviderCallBillingStatus;
+  }
+): ProviderCallCompletedEvent => ({
+  providerCallId: input.providerCallId,
+  eventId: input.eventId,
+  userId: input.userId,
+  dialogId: input.dialogId,
+  agentId: input.agentId,
+  provider: input.provider,
+  model: input.model,
+  endpoint: input.endpoint,
+  serviceTier: input.serviceTier,
+  credential: input.credential,
+  startedAt: input.startedAt,
+  status: "completed",
+  completedAt: input.completedAt,
+  usage: {
+    inputTokens: input.inputTokens,
+    outputTokens: input.outputTokens,
+    cacheCreationInputTokens: input.cacheCreationInputTokens,
+    cacheReadInputTokens: input.cacheReadInputTokens,
+  },
+  cost: {
+    rawProviderCost: input.rawProviderCost,
+    rawProviderCurrency: input.rawProviderCurrency,
+    platformCredits: input.platformCredits,
+    pricingVersion: input.pricingVersion,
+  },
+  billingStatus: input.billingStatus,
+});
+
+export const createProviderCallFailedEvent = (
+  input: ProviderCallBase & {
+    failedAt: string;
+    error: {
+      name?: string;
+      message: string;
+    };
+  }
+): ProviderCallFailedEvent => ({
+  providerCallId: input.providerCallId,
+  eventId: input.eventId,
+  userId: input.userId,
+  dialogId: input.dialogId,
+  agentId: input.agentId,
+  provider: input.provider,
+  model: input.model,
+  endpoint: input.endpoint,
+  serviceTier: input.serviceTier,
+  credential: input.credential,
+  startedAt: input.startedAt,
+  status: "failed",
+  failedAt: input.failedAt,
+  error: input.error,
+  billingStatus: "failed",
+});

package/ai/token/providerCallSweeper.ts

@@ -0,0 +1,168 @@
+import {
+  type ProviderCallEvent,
+  type ProviderCallPendingEvent,
+} from "./providerCall";
+import type { ProviderDispatchIntent } from "./providerDispatchIntent";
+import { createBillingAnomaly } from "./billingAnomaly";
+import {
+  writeBillingAnomaly,
+  type BillingAnomalyStore,
+} from "./billingAnomalyWriter";
+
+export const STALE_PROVIDER_CALL_DEFAULT_TIMEOUT_MS = 10 * 60_000;
+
+type ProviderCallSweeperStore = BillingAnomalyStore & {
+  iterator(options: { gte?: string; lte?: string }): AsyncIterable<[string, unknown]>;
+};
+
+export type SweepStaleProviderCallsResult = {
+  scannedProviderCalls: number;
+  stalePendingCalls: number;
+  anomaliesWritten: number;
+  anomaliesAlreadyExisted: number;
+};
+
+type ProviderCallState = {
+  pending?: ProviderCallPendingEvent;
+  dispatchIntent?: ProviderDispatchIntent;
+  hasTerminal: boolean;
+};
+
+const PROVIDER_CALL_PREFIX = "provider-call-";
+const PROVIDER_CALL_RANGE_END = `${PROVIDER_CALL_PREFIX}\uffff`;
+const PROVIDER_DISPATCH_INTENT_PREFIX = "provider-dispatch-intent-";
+const PROVIDER_DISPATCH_INTENT_RANGE_END = `${PROVIDER_DISPATCH_INTENT_PREFIX}\uffff`;
+
+const isProviderCallEvent = (value: unknown): value is ProviderCallEvent =>
+  Boolean(
+    value &&
+      typeof value === "object" &&
+      typeof (value as { providerCallId?: unknown }).providerCallId === "string" &&
+      typeof (value as { eventId?: unknown }).eventId === "string" &&
+      typeof (value as { status?: unknown }).status === "string"
+  );
+
+const isProviderDispatchIntent = (value: unknown): value is ProviderDispatchIntent =>
+  Boolean(
+    value &&
+      typeof value === "object" &&
+      typeof (value as { providerCallId?: unknown }).providerCallId === "string" &&
+      typeof (value as { intentId?: unknown }).intentId === "string" &&
+      (value as { status?: unknown }).status === "dispatching"
+  );
+
+const isAlreadyExistsError = (error: unknown) =>
+  error instanceof Error &&
+  error.message.startsWith("billing anomaly already exists:");
+
+const pendingTimeoutAnomalyId = (providerCallId: string) =>
+  `anom_provider_call_pending_timeout_${providerCallId}`;
+
+const sentUnknownAnomalyId = (providerCallId: string) =>
+  `anom_provider_call_sent_unknown_${providerCallId}`;
+
+export async function sweepStaleProviderCalls({
+  store,
+  nowMs = Date.now(),
+  timeoutMs = STALE_PROVIDER_CALL_DEFAULT_TIMEOUT_MS,
+}: {
+  store: ProviderCallSweeperStore;
+  nowMs?: number;
+  timeoutMs?: number;
+}): Promise<SweepStaleProviderCallsResult> {
+  const states = new Map<string, ProviderCallState>();
+
+  for await (const [, value] of store.iterator({
+    gte: PROVIDER_CALL_PREFIX,
+    lte: PROVIDER_CALL_RANGE_END,
+  })) {
+    if (!isProviderCallEvent(value)) continue;
+    const existing = states.get(value.providerCallId) ?? { hasTerminal: false };
+    if (value.status === "pending") {
+      existing.pending = value;
+    }
+    if (value.status === "completed" || value.status === "failed") {
+      existing.hasTerminal = true;
+    }
+    states.set(value.providerCallId, existing);
+  }
+  for await (const [, value] of store.iterator({
+    gte: PROVIDER_DISPATCH_INTENT_PREFIX,
+    lte: PROVIDER_DISPATCH_INTENT_RANGE_END,
+  })) {
+    if (!isProviderDispatchIntent(value)) continue;
+    const existing = states.get(value.providerCallId) ?? { hasTerminal: false };
+    existing.dispatchIntent = value;
+    states.set(value.providerCallId, existing);
+  }
+
+  const result: SweepStaleProviderCallsResult = {
+    scannedProviderCalls: states.size,
+    stalePendingCalls: 0,
+    anomaliesWritten: 0,
+    anomaliesAlreadyExisted: 0,
+  };
+
+  for (const [providerCallId, state] of states) {
+    if (!state.pending || state.hasTerminal) continue;
+    const startedAtMs = Date.parse(state.pending.startedAt);
+    if (!Number.isFinite(startedAtMs)) continue;
+    const pendingAgeMs = nowMs - startedAtMs;
+    if (pendingAgeMs < timeoutMs) continue;
+
+    result.stalePendingCalls += 1;
+    const isSentUnknown = Boolean(state.dispatchIntent);
+    const anomalyId = isSentUnknown
+      ? sentUnknownAnomalyId(providerCallId)
+      : pendingTimeoutAnomalyId(providerCallId);
+    const kind = isSentUnknown
+      ? "provider_call_sent_unknown"
+      : "provider_call_pending_timeout";
+    const message = isSentUnknown
+      ? "Provider call was dispatched but no terminal billing evidence was recorded"
+      : "Provider call stayed pending past the billing SLA";
+    try {
+      await writeBillingAnomaly({
+        store,
+        anomaly: createBillingAnomaly({
+          anomalyId,
+          kind,
+          severity: "critical",
+          stage: "reconciliation",
+          userId: state.pending.userId,
+          dialogId: state.pending.dialogId,
+          agentId: state.pending.agentId,
+          provider: state.pending.provider,
+          model: state.pending.model,
+          providerCallId,
+          message,
+          evidence: {
+            pendingEventId: state.pending.eventId,
+            endpoint: state.pending.endpoint,
+            serviceTier: state.pending.serviceTier,
+            startedAt: state.pending.startedAt,
+            pendingAgeMs,
+            timeoutMs,
+            ...(state.dispatchIntent
+              ? {
+                  dispatchIntentId: state.dispatchIntent.intentId,
+                  dispatchCreatedAt: state.dispatchIntent.createdAt,
+                  request: state.dispatchIntent.request,
+                }
+              : {}),
+          },
+          createdAt: new Date(nowMs).toISOString(),
+        }),
+      });
+      result.anomaliesWritten += 1;
+    } catch (error) {
+      if (isAlreadyExistsError(error)) {
+        result.anomaliesAlreadyExisted += 1;
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  return result;
+}

package/ai/token/providerCallWriter.ts

@@ -0,0 +1,33 @@
+import { buildProviderCallKey, type ProviderCallEvent } from "./providerCall";
+
+export type ProviderCallStore = {
+  get(key: string): Promise<unknown>;
+  put(key: string, value: unknown): Promise<void>;
+};
+
+const isMissingRecordError = (error: unknown) => {
+  if (!error || typeof error !== "object") return false;
+  const code = (error as { code?: unknown }).code;
+  return code === "LEVEL_NOT_FOUND" || code === "NOT_FOUND";
+};
+
+export async function writeProviderCallEvent({
+  store,
+  event,
+}: {
+  store: ProviderCallStore;
+  event: ProviderCallEvent;
+}): Promise<{ key: string }> {
+  const key = buildProviderCallKey(event.providerCallId, event.eventId);
+  let existing: unknown;
+  try {
+    existing = await store.get(key);
+  } catch (error) {
+    if (!isMissingRecordError(error)) throw error;
+  }
+  if (existing) {
+    throw new Error(`provider-call event already exists: ${key}`);
+  }
+  await store.put(key, event);
+  return { key };
+}