nolo-cli 0.1.30 → 0.1.31

package/ai/token/providerGateway.ts

@@ -0,0 +1,260 @@
+import crypto from "crypto";
+
+import {
+  createProviderCallFailedEvent,
+  createProviderCallPendingEvent,
+} from "./providerCall";
+import { writeProviderCallEvent, type ProviderCallStore } from "./providerCallWriter";
+import { writeBillingAnomaly } from "./billingAnomalyWriter";
+import {
+  writeRevokedProviderCredentialBlockedAnomalyIfNeeded,
+  writeRevokedProviderCredentialUsedAnomalyIfNeeded,
+} from "./providerCredentialAnomaly";
+import { createProviderDispatchIntent } from "./providerDispatchIntent";
+import {
+  writeProviderDispatchIntent,
+  type ProviderDispatchIntentStore,
+} from "./providerDispatchIntentWriter";
+import type { ProviderCredentialIdentity } from "./providerCredential";
+
+type ProviderGatewayStore = ProviderCallStore & ProviderDispatchIntentStore;
+
+type ProviderGatewayIds = {
+  providerCallId?: () => string;
+  pendingEventId?: () => string;
+  dispatchIntentId?: () => string;
+  failedEventId?: () => string;
+};
+
+type ProviderGatewayWriters = {
+  providerCallWriter?: typeof writeProviderCallEvent;
+  providerDispatchIntentWriter?: typeof writeProviderDispatchIntent;
+  billingAnomalyWriter?: typeof writeBillingAnomaly;
+};
+
+type ProviderRequestCall = {
+  userId: string;
+  dialogId?: string;
+  agentId?: string;
+  provider: string;
+  model: string;
+  endpoint?: string;
+  serviceTier?: string;
+  credential?: ProviderCredentialIdentity;
+  url: string;
+  init?: RequestInit;
+};
+
+type DispatchProviderRequestInput = {
+  store: ProviderGatewayStore;
+  call: ProviderRequestCall;
+  fetchImpl?: typeof fetch;
+  now?: () => Date;
+  ids?: ProviderGatewayIds;
+  writers?: ProviderGatewayWriters;
+};
+
+type DispatchProviderRequestResult = {
+  providerCallId: string;
+  pendingEventId: string;
+  dispatchIntentId: string;
+  response: Response;
+};
+
+export class ProviderCredentialRevokedError extends Error {
+  constructor() {
+    super("Provider credential is revoked");
+    this.name = "ProviderCredentialRevokedError";
+  }
+}
+
+const randomId = (prefix: string) => `${prefix}_${crypto.randomUUID()}`;
+
+const methodOf = (init?: RequestInit) => init?.method?.toUpperCase() || "GET";
+
+const bodyHashOf = (body: BodyInit | null | undefined) => {
+  if (body == null) return undefined;
+  if (typeof body === "string") {
+    return `sha256:${crypto.createHash("sha256").update(body).digest("hex")}`;
+  }
+  if (body instanceof URLSearchParams) {
+    return `sha256:${crypto.createHash("sha256").update(body.toString()).digest("hex")}`;
+  }
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(String(Object.prototype.toString.call(body)))
+    .digest("hex")}`;
+};
+
+const withClientRequestIdHeader = (
+  init: RequestInit | undefined,
+  providerCallId: string
+): RequestInit => {
+  if (init?.headers instanceof Headers) {
+    const headers = new Headers(init.headers);
+    if (!headers.has("x-client-request-id")) {
+      headers.set("x-client-request-id", providerCallId);
+    }
+    return {
+      ...init,
+      headers,
+    };
+  }
+
+  if (Array.isArray(init?.headers)) {
+    const headers = new Headers(init.headers);
+    if (!headers.has("x-client-request-id")) {
+      headers.set("x-client-request-id", providerCallId);
+    }
+    return {
+      ...init,
+      headers,
+    };
+  }
+
+  const headers = {
+    ...((init?.headers as Record<string, string> | undefined) ?? {}),
+  };
+  const hasClientRequestId = Object.keys(headers).some(
+    (key) => key.toLowerCase() === "x-client-request-id"
+  );
+  if (!hasClientRequestId) {
+    headers["x-client-request-id"] = providerCallId;
+  }
+  return {
+    ...init,
+    headers,
+  };
+};
+
+function errorShape(error: unknown) {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+    };
+  }
+  return { message: String(error) };
+}
+
+export async function dispatchProviderRequest({
+  store,
+  call,
+  fetchImpl = fetch,
+  now = () => new Date(),
+  ids = {},
+  writers = {},
+}: DispatchProviderRequestInput): Promise<DispatchProviderRequestResult> {
+  const providerCallId = ids.providerCallId?.() ?? randomId("pcall");
+  const pendingEventId = ids.pendingEventId?.() ?? randomId("evt_pending");
+  const dispatchIntentId = ids.dispatchIntentId?.() ?? randomId("intent");
+  const failedEventIdFactory = ids.failedEventId ?? (() => randomId("evt_failed"));
+  const startedAt = now().toISOString();
+
+  await (writers.providerCallWriter ?? writeProviderCallEvent)({
+    store,
+    event: createProviderCallPendingEvent({
+      providerCallId,
+      eventId: pendingEventId,
+      userId: call.userId,
+      dialogId: call.dialogId,
+      agentId: call.agentId,
+      provider: call.provider,
+      model: call.model,
+      endpoint: call.endpoint,
+      serviceTier: call.serviceTier,
+      credential: call.credential,
+      startedAt,
+    }),
+  });
+
+  if (call.credential?.registryStatus === "revoked") {
+    const error = new ProviderCredentialRevokedError();
+    const failedEvent = createProviderCallFailedEvent({
+      providerCallId,
+      eventId: failedEventIdFactory(),
+      userId: call.userId,
+      dialogId: call.dialogId,
+      agentId: call.agentId,
+      provider: call.provider,
+      model: call.model,
+      endpoint: call.endpoint,
+      serviceTier: call.serviceTier,
+      credential: call.credential,
+      startedAt,
+      failedAt: now().toISOString(),
+      error: errorShape(error),
+    });
+    await (writers.providerCallWriter ?? writeProviderCallEvent)({
+      store,
+      event: failedEvent,
+    });
+    await writeRevokedProviderCredentialBlockedAnomalyIfNeeded({
+      store,
+      event: failedEvent,
+      now,
+      billingAnomalyWriter: writers.billingAnomalyWriter ?? writeBillingAnomaly,
+    });
+    throw error;
+  }
+
+  await (writers.providerDispatchIntentWriter ?? writeProviderDispatchIntent)({
+    store,
+    intent: createProviderDispatchIntent({
+      providerCallId,
+      intentId: dispatchIntentId,
+      userId: call.userId,
+      dialogId: call.dialogId,
+      agentId: call.agentId,
+      provider: call.provider,
+      model: call.model,
+      endpoint: call.endpoint,
+      serviceTier: call.serviceTier,
+      credential: call.credential,
+      url: call.url,
+      method: methodOf(call.init),
+      bodyHash: bodyHashOf(call.init?.body),
+      createdAt: now().toISOString(),
+    }),
+  });
+
+  try {
+    const response = await fetchImpl(
+      call.url,
+      withClientRequestIdHeader(call.init, providerCallId)
+    );
+    return {
+      providerCallId,
+      pendingEventId,
+      dispatchIntentId,
+      response,
+    };
+  } catch (error) {
+    const failedEvent = createProviderCallFailedEvent({
+      providerCallId,
+      eventId: failedEventIdFactory(),
+      userId: call.userId,
+      dialogId: call.dialogId,
+      agentId: call.agentId,
+      provider: call.provider,
+      model: call.model,
+      endpoint: call.endpoint,
+      serviceTier: call.serviceTier,
+      credential: call.credential,
+      startedAt,
+      failedAt: now().toISOString(),
+      error: errorShape(error),
+    });
+    await (writers.providerCallWriter ?? writeProviderCallEvent)({
+      store,
+      event: failedEvent,
+    });
+    await writeRevokedProviderCredentialUsedAnomalyIfNeeded({
+      store,
+      event: failedEvent,
+      now,
+      billingAnomalyWriter: writers.billingAnomalyWriter ?? writeBillingAnomaly,
+    });
+    throw error;
+  }
+}

package/ai/token/providerReconciliation.ts

@@ -0,0 +1,148 @@
+export type ProviderReconciliationStatus =
+  | "matched"
+  | "missing_local"
+  | "extra_local"
+  | "mismatched_usage"
+  | "mismatched_cost"
+  | "waiting_provider";
+
+export type ProviderReconciliationBucketTotals = {
+  requestCount: number;
+  inputTokens: number;
+  outputTokens: number;
+  rawProviderCostUsd: number;
+};
+
+export type LocalProviderReconciliationBucketTotals =
+  ProviderReconciliationBucketTotals & {
+    platformCredits: number;
+  };
+
+export type ProviderReconciliationBucketDiff = {
+  requestCount: number;
+  inputTokens: number;
+  outputTokens: number;
+  rawProviderCostUsd: number;
+  platformCredits: number;
+  absoluteRawProviderCostUsd: number;
+};
+
+export type ProviderReconciliationBucket = {
+  id: string;
+  provider: string;
+  model?: string;
+  endpoint?: string;
+  serviceTier?: string;
+  officialEvidence?: Record<string, unknown>;
+  bucketStart: string;
+  bucketEnd: string;
+  status: ProviderReconciliationStatus;
+  official: ProviderReconciliationBucketTotals;
+  local: LocalProviderReconciliationBucketTotals;
+  diff: ProviderReconciliationBucketDiff;
+  needsAnomaly: boolean;
+  createdAt: string;
+};
+
+export type CreateProviderReconciliationBucketInput = {
+  bucketId: string;
+  provider: string;
+  model?: string;
+  endpoint?: string;
+  serviceTier?: string;
+  bucketStart: string;
+  bucketEnd: string;
+  official: ProviderReconciliationBucketTotals;
+  local: LocalProviderReconciliationBucketTotals;
+  createdAt: string;
+  rawProviderCostToleranceUsd?: number;
+};
+
+export const buildProviderReconciliationBucketKey = (bucketId: string) =>
+  `provider-reconciliation-bucket-${bucketId}`;
+
+const hasOfficialEvidence = (totals: ProviderReconciliationBucketTotals) =>
+  totals.requestCount > 0 ||
+  totals.inputTokens > 0 ||
+  totals.outputTokens > 0 ||
+  totals.rawProviderCostUsd > 0;
+
+const hasLocalEvidence = (totals: LocalProviderReconciliationBucketTotals) =>
+  totals.requestCount > 0 ||
+  totals.inputTokens > 0 ||
+  totals.outputTokens > 0 ||
+  totals.rawProviderCostUsd > 0 ||
+  totals.platformCredits > 0;
+
+const roundMoney = (value: number) => Number(value.toFixed(12));
+
+const classifyBucket = ({
+  official,
+  local,
+  diff,
+  costTolerance,
+}: {
+  official: ProviderReconciliationBucketTotals;
+  local: LocalProviderReconciliationBucketTotals;
+  diff: ProviderReconciliationBucketDiff;
+  costTolerance: number;
+}): ProviderReconciliationStatus => {
+  const officialExists = hasOfficialEvidence(official);
+  const localExists = hasLocalEvidence(local);
+  if (officialExists && !localExists) return "missing_local";
+  if (!officialExists && localExists) return "extra_local";
+  if (!officialExists && !localExists) return "waiting_provider";
+  if (
+    diff.requestCount !== 0 ||
+    diff.inputTokens !== 0 ||
+    diff.outputTokens !== 0
+  ) {
+    return "mismatched_usage";
+  }
+  if (diff.absoluteRawProviderCostUsd > costTolerance) {
+    return "mismatched_cost";
+  }
+  return "matched";
+};
+
+export const createProviderReconciliationBucket = (
+  input: CreateProviderReconciliationBucketInput
+): ProviderReconciliationBucket => {
+  const diff: ProviderReconciliationBucketDiff = {
+    requestCount: input.official.requestCount - input.local.requestCount,
+    inputTokens: input.official.inputTokens - input.local.inputTokens,
+    outputTokens: input.official.outputTokens - input.local.outputTokens,
+    rawProviderCostUsd: roundMoney(
+      input.official.rawProviderCostUsd - input.local.rawProviderCostUsd
+    ),
+    platformCredits: input.local.platformCredits,
+    absoluteRawProviderCostUsd: roundMoney(
+      Math.abs(input.official.rawProviderCostUsd - input.local.rawProviderCostUsd)
+    ),
+  };
+  const status = classifyBucket({
+    official: input.official,
+    local: input.local,
+    diff,
+    costTolerance: input.rawProviderCostToleranceUsd ?? 0.000001,
+  });
+
+  return {
+    id: input.bucketId,
+    provider: input.provider,
+    model: input.model,
+    endpoint: input.endpoint,
+    serviceTier: input.serviceTier,
+    officialEvidence: input.officialEvidence
+      ? { ...input.officialEvidence }
+      : undefined,
+    bucketStart: input.bucketStart,
+    bucketEnd: input.bucketEnd,
+    status,
+    official: { ...input.official },
+    local: { ...input.local },
+    diff,
+    needsAnomaly: status !== "matched" && status !== "waiting_provider",
+    createdAt: input.createdAt,
+  };
+};

package/ai/token/providerReconciliationLocal.ts

@@ -0,0 +1,97 @@
+import type { ProviderCallCompletedEvent, ProviderCallEvent } from "./providerCall";
+import type { RatingResult } from "./ratingResult";
+import type { LocalProviderReconciliationBucketTotals } from "./providerReconciliation";
+
+export type ProviderReconciliationLocalStore = {
+  iterator(options: { gte?: string; lte?: string }): AsyncIterable<[string, unknown]>;
+};
+
+const PROVIDER_CALL_PREFIX = "provider-call-";
+const PROVIDER_CALL_RANGE_END = `${PROVIDER_CALL_PREFIX}\uffff`;
+const RATING_RESULT_PREFIX = "rating-result-";
+const RATING_RESULT_RANGE_END = `${RATING_RESULT_PREFIX}\uffff`;
+
+const isProviderCallCompletedEvent = (
+  value: unknown
+): value is ProviderCallCompletedEvent =>
+  Boolean(
+    value &&
+      typeof value === "object" &&
+      (value as ProviderCallEvent).status === "completed" &&
+      typeof (value as { provider?: unknown }).provider === "string" &&
+      typeof (value as { model?: unknown }).model === "string" &&
+      typeof (value as { completedAt?: unknown }).completedAt === "string"
+  );
+
+const isRatingResult = (value: unknown): value is RatingResult =>
+  Boolean(
+    value &&
+      typeof value === "object" &&
+      typeof (value as { id?: unknown }).id === "string" &&
+      typeof (value as { provider?: unknown }).provider === "string" &&
+      typeof (value as { model?: unknown }).model === "string" &&
+      typeof (value as { platformCredits?: unknown }).platformCredits === "number" &&
+      typeof (value as { createdAt?: unknown }).createdAt === "string"
+  );
+
+const isWithinWindow = (iso: string, bucketStartMs: number, bucketEndMs: number) => {
+  const time = Date.parse(iso);
+  return Number.isFinite(time) && time >= bucketStartMs && time < bucketEndMs;
+};
+
+const roundMoney = (value: number) => Number(value.toFixed(12));
+
+export async function aggregateLocalProviderBillingBucket({
+  store,
+  provider,
+  model,
+  bucketStart,
+  bucketEnd,
+}: {
+  store: ProviderReconciliationLocalStore;
+  provider: string;
+  model?: string;
+  bucketStart: string;
+  bucketEnd: string;
+}): Promise<LocalProviderReconciliationBucketTotals> {
+  const bucketStartMs = Date.parse(bucketStart);
+  const bucketEndMs = Date.parse(bucketEnd);
+  const totals: LocalProviderReconciliationBucketTotals = {
+    requestCount: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    rawProviderCostUsd: 0,
+    platformCredits: 0,
+  };
+
+  for await (const [, value] of store.iterator({
+    gte: PROVIDER_CALL_PREFIX,
+    lte: PROVIDER_CALL_RANGE_END,
+  })) {
+    if (!isProviderCallCompletedEvent(value)) continue;
+    if (value.provider !== provider) continue;
+    if (model && value.model !== model) continue;
+    if (!isWithinWindow(value.completedAt, bucketStartMs, bucketEndMs)) continue;
+    totals.requestCount += 1;
+    totals.inputTokens += value.usage.inputTokens;
+    totals.outputTokens += value.usage.outputTokens;
+    if (value.cost.rawProviderCurrency === "USD") {
+      totals.rawProviderCostUsd += value.cost.rawProviderCost ?? 0;
+    }
+  }
+
+  for await (const [, value] of store.iterator({
+    gte: RATING_RESULT_PREFIX,
+    lte: RATING_RESULT_RANGE_END,
+  })) {
+    if (!isRatingResult(value)) continue;
+    if (value.provider !== provider) continue;
+    if (model && value.model !== model) continue;
+    if (!isWithinWindow(value.createdAt, bucketStartMs, bucketEndMs)) continue;
+    totals.platformCredits += value.platformCredits;
+  }
+
+  totals.rawProviderCostUsd = roundMoney(totals.rawProviderCostUsd);
+  totals.platformCredits = roundMoney(totals.platformCredits);
+  return totals;
+}

package/ai/token/providerReconciliationRunner.ts

@@ -0,0 +1,165 @@
+import { resolveCommercialMultiplier } from "../policy/commercialMultiplier";
+import { createBillingAnomaly } from "./billingAnomaly";
+import {
+  writeBillingAnomaly,
+  type BillingAnomalyStore,
+} from "./billingAnomalyWriter";
+import type { NormalizedOfficialProviderBucket } from "./deepinfraReconciliation";
+import {
+  aggregateLocalProviderBillingBucket,
+  type ProviderReconciliationLocalStore,
+} from "./providerReconciliationLocal";
+import {
+  createProviderReconciliationBucket,
+  type ProviderReconciliationBucket,
+} from "./providerReconciliation";
+import {
+  writeProviderReconciliationBucket,
+  type ProviderReconciliationBucketStore,
+} from "./providerReconciliationWriter";
+
+type ProviderReconciliationStore =
+  ProviderReconciliationLocalStore &
+    ProviderReconciliationBucketStore &
+    BillingAnomalyStore;
+
+export type RunProviderReconciliationResult = {
+  bucketsProcessed: number;
+  bucketsWritten: number;
+  anomaliesWritten: number;
+  bucketsProposed: number;
+  anomaliesProposed: number;
+  riskPlatformCreditsProposed: number;
+  alreadyExisted: number;
+  dryRun: boolean;
+};
+
+const sanitizeIdPart = (value: string) =>
+  value.replace(/[^A-Za-z0-9_.-]+/g, "-");
+
+const buildBucketId = (bucket: NormalizedOfficialProviderBucket) =>
+  [
+    "recon",
+    bucket.provider,
+    bucket.model ? sanitizeIdPart(bucket.model) : "all-models",
+    sanitizeIdPart(bucket.bucketStart),
+    sanitizeIdPart(bucket.bucketEnd),
+  ].join("_");
+
+const isAlreadyExistsError = (error: unknown) =>
+  error instanceof Error && error.message.includes("already exists:");
+
+const estimateRiskPlatformCredits = (bucket: ProviderReconciliationBucket) => {
+  const model = bucket.model ?? "";
+  const multiplier = resolveCommercialMultiplier(bucket.provider, model);
+  return Number((bucket.diff.absoluteRawProviderCostUsd * multiplier).toFixed(6));
+};
+
+export async function runProviderReconciliation({
+  store,
+  officialBuckets,
+  createdAt,
+  dryRun = false,
+}: {
+  store: ProviderReconciliationStore;
+  officialBuckets: NormalizedOfficialProviderBucket[];
+  createdAt: string;
+  dryRun?: boolean;
+}): Promise<RunProviderReconciliationResult> {
+  const result: RunProviderReconciliationResult = {
+    bucketsProcessed: 0,
+    bucketsWritten: 0,
+    anomaliesWritten: 0,
+    bucketsProposed: 0,
+    anomaliesProposed: 0,
+    riskPlatformCreditsProposed: 0,
+    alreadyExisted: 0,
+    dryRun,
+  };
+
+  for (const officialBucket of officialBuckets) {
+    result.bucketsProcessed += 1;
+    const local = await aggregateLocalProviderBillingBucket({
+      store,
+      provider: officialBucket.provider,
+      model: officialBucket.model,
+      bucketStart: officialBucket.bucketStart,
+      bucketEnd: officialBucket.bucketEnd,
+    });
+    const bucket = createProviderReconciliationBucket({
+      bucketId: buildBucketId(officialBucket),
+      provider: officialBucket.provider,
+      model: officialBucket.model,
+      endpoint: officialBucket.endpoint,
+      officialEvidence: officialBucket.evidence,
+      bucketStart: officialBucket.bucketStart,
+      bucketEnd: officialBucket.bucketEnd,
+      official: officialBucket.official,
+      local,
+      createdAt,
+    });
+    result.bucketsProposed += 1;
+
+    if (!dryRun) {
+      try {
+        await writeProviderReconciliationBucket({ store, bucket });
+        result.bucketsWritten += 1;
+      } catch (error) {
+        if (isAlreadyExistsError(error)) {
+          result.alreadyExisted += 1;
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    if (!bucket.needsAnomaly) continue;
+    result.anomaliesProposed += 1;
+    result.riskPlatformCreditsProposed = Number(
+      (
+        result.riskPlatformCreditsProposed + estimateRiskPlatformCredits(bucket)
+      ).toFixed(6)
+    );
+    if (dryRun) continue;
+
+    try {
+      await writeBillingAnomaly({
+        store,
+        anomaly: createBillingAnomaly({
+          anomalyId: `anom_${bucket.id}`,
+          kind: "provider_reconciliation_diff",
+          severity:
+            bucket.status === "missing_local" || bucket.status === "mismatched_cost"
+              ? "critical"
+              : "high",
+          stage: "reconciliation",
+          userId: "provider-reconciliation",
+          provider: bucket.provider,
+          model: bucket.model ?? "unknown",
+          riskPlatformCredits: estimateRiskPlatformCredits(bucket),
+          message: `Provider official bucket differs from local billing evidence: ${bucket.status}`,
+          evidence: {
+            bucketId: bucket.id,
+            bucketStart: bucket.bucketStart,
+            bucketEnd: bucket.bucketEnd,
+            status: bucket.status,
+            official: bucket.official,
+            local: bucket.local,
+            diff: bucket.diff,
+            officialEvidence: officialBucket.evidence,
+          },
+          createdAt,
+        }),
+      });
+      result.anomaliesWritten += 1;
+    } catch (error) {
+      if (isAlreadyExistsError(error)) {
+        result.alreadyExisted += 1;
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  return result;
+}

package/ai/token/providerReconciliationWriter.ts

@@ -0,0 +1,41 @@
+import {
+  buildProviderReconciliationBucketKey,
+  type ProviderReconciliationBucket,
+} from "./providerReconciliation";
+
+export type ProviderReconciliationBucketStore = {
+  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;
+  const message = (error as { message?: unknown }).message;
+  return (
+    code === "LEVEL_NOT_FOUND" ||
+    code === "NOT_FOUND" ||
+    message === "NotFound"
+  );
+};
+
+export async function writeProviderReconciliationBucket({
+  store,
+  bucket,
+}: {
+  store: ProviderReconciliationBucketStore;
+  bucket: ProviderReconciliationBucket;
+}): Promise<{ key: string }> {
+  const key = buildProviderReconciliationBucketKey(bucket.id);
+  let existing: unknown;
+  try {
+    existing = await store.get(key);
+  } catch (error) {
+    if (!isMissingRecordError(error)) throw error;
+  }
+  if (existing) {
+    throw new Error(`provider reconciliation bucket already exists: ${key}`);
+  }
+  await store.put(key, bucket);
+  return { key };
+}