@intelligo-dev/executions 1.0.0-beta.1 → 1.0.0-beta.13

package/src/pricing.ts

@@ -0,0 +1,322 @@
+/**
+ * Model registry and execution cost accounting.
+ *
+ * A leaf: no database, no provider SDK. Its one import is
+ * `@intelligo-dev/core/registry`, which is itself dependency-free, so
+ * `@intelligo-dev/executions/pricing` is something a client bundle can
+ * read a display name or a price from without pulling in Drizzle.
+ *
+ * The registry is open: a product registers any model it runs, and
+ * `registerModels(DEFAULT_MODELS)` from the composition root registers
+ * the shipped catalogue. Nothing self-registers. An id with no price
+ * throws at the point where the price is needed, naming the id, rather
+ * than billing at a guessed rate.
+ */
+
+import {
+  convert,
+  currency,
+  money,
+  type CurrencyCode,
+  type Money,
+} from "@intelligo-dev/core/money";
+import { createRegistry } from "@intelligo-dev/core/registry";
+
+export type ModelCapabilities = {
+  thinking: boolean;
+  toolCall: boolean;
+  vision: boolean;
+  webSearch: boolean;
+  codeExec: boolean;
+};
+
+export type ModelPricing = {
+  /** Provider-prefixed id, e.g. `google/gemini-2.5-flash`. */
+  id: string;
+  provider: string;
+  /** The id the provider's own SDK expects, which is often dated. */
+  model: string;
+  displayName: string;
+  /** USD per million input tokens, as the provider quotes it. */
+  costPerMInputTokens: number;
+  /** USD per million output tokens. */
+  costPerMOutputTokens: number;
+  /**
+   * The ceiling on streamed output used for worst-case pre-request
+   * estimation.
+   */
+  maxOutputTokens: number;
+  capabilities: ModelCapabilities;
+};
+
+/** A provider-prefixed model id; any string, because the registry is open. */
+export type ModelId = string;
+
+export class UnknownModelError extends Error {
+  readonly code = "unknown_model";
+  readonly modelId: string;
+  constructor(modelId: string, registered: readonly string[]) {
+    super(
+      `No price registered for model "${modelId}". ` +
+        `Registered: ${registered.length > 0 ? registered.join(", ") : "none"}. ` +
+        `Call registerModels(DEFAULT_MODELS) — or your own catalogue — from the composition root.`
+    );
+    this.name = "UnknownModelError";
+    this.modelId = modelId;
+  }
+}
+
+const models = createRegistry<ModelPricing>("executions/model-pricing");
+
+/** Register (or replace) one model's price and capabilities. */
+export function registerModel(pricing: ModelPricing): void {
+  models.set(pricing.id, pricing);
+}
+
+export function registerModels(pricings: readonly ModelPricing[]): void {
+  for (const pricing of pricings) registerModel(pricing);
+}
+
+export function getModelPricing(modelId: string): ModelPricing | undefined {
+  return models.get(modelId);
+}
+
+export function isModelRegistered(modelId: string): boolean {
+  return models.has(modelId);
+}
+
+export function listModels(): readonly ModelPricing[] {
+  return [...models.values()];
+}
+
+export function registeredModelIds(): readonly string[] {
+  return [...models.keys()];
+}
+
+/** For tests composing a fresh root. */
+export function clearModels(): void {
+  models.clear();
+}
+
+/**
+ * The catalogue the framework ships, as data.
+ *
+ * Prices are the providers' published USD rates and go stale; a
+ * deployment that cares about the third decimal should register its own
+ * contracted rates over these.
+ */
+export const DEFAULT_MODELS: readonly ModelPricing[] = [
+  {
+    id: "google/gemini-2.5-flash",
+    provider: "google",
+    model: "gemini-2.5-flash",
+    displayName: "Gemini 2.5 Flash",
+    costPerMInputTokens: 0.3,
+    costPerMOutputTokens: 2.5,
+    maxOutputTokens: 8_000,
+    capabilities: {
+      thinking: true,
+      toolCall: true,
+      vision: true,
+      webSearch: true,
+      codeExec: true,
+    },
+  },
+  {
+    id: "google/gemini-2.5-pro",
+    provider: "google",
+    model: "gemini-2.5-pro",
+    displayName: "Gemini 2.5 Pro",
+    costPerMInputTokens: 1.25,
+    costPerMOutputTokens: 10,
+    maxOutputTokens: 8_000,
+    capabilities: {
+      thinking: true,
+      toolCall: true,
+      vision: true,
+      webSearch: true,
+      codeExec: true,
+    },
+  },
+  {
+    id: "openai/gpt-5-mini",
+    provider: "openai",
+    model: "gpt-5-mini",
+    displayName: "GPT-5 Mini",
+    costPerMInputTokens: 0.25,
+    costPerMOutputTokens: 2.0,
+    maxOutputTokens: 8_000,
+    capabilities: {
+      thinking: true,
+      toolCall: true,
+      vision: true,
+      webSearch: false,
+      codeExec: false,
+    },
+  },
+  {
+    id: "openai/gpt-5.4-mini",
+    provider: "openai",
+    model: "gpt-5.4-mini",
+    displayName: "GPT-5.4 Mini",
+    costPerMInputTokens: 0.75,
+    costPerMOutputTokens: 4.5,
+    maxOutputTokens: 8_000,
+    capabilities: {
+      thinking: true,
+      toolCall: true,
+      vision: true,
+      webSearch: true,
+      codeExec: true,
+    },
+  },
+  {
+    id: "openai/o4-mini",
+    provider: "openai",
+    model: "o4-mini",
+    displayName: "o4-mini",
+    costPerMInputTokens: 1.1,
+    costPerMOutputTokens: 4.4,
+    maxOutputTokens: 8_000,
+    capabilities: {
+      thinking: true,
+      toolCall: true,
+      vision: true,
+      webSearch: true,
+      codeExec: true,
+    },
+  },
+  {
+    id: "anthropic/claude-sonnet-4-6",
+    provider: "anthropic",
+    model: "claude-sonnet-4-6-20260214",
+    displayName: "Claude Sonnet 4.6",
+    costPerMInputTokens: 3.0,
+    costPerMOutputTokens: 15.0,
+    maxOutputTokens: 8_000,
+    capabilities: {
+      thinking: true,
+      toolCall: true,
+      vision: true,
+      webSearch: true,
+      codeExec: true,
+    },
+  },
+];
+
+/** The price of a model, or a loud failure naming the id. */
+function requireModel(modelId: string): ModelPricing {
+  const pricing = models.get(modelId);
+  if (!pricing) throw new UnknownModelError(modelId, registeredModelIds());
+  return pricing;
+}
+
+/** Providers quote in USD; every cost in this module starts there. */
+export const PROVIDER_CURRENCY: CurrencyCode = currency("USD");
+
+/**
+ * What the provider charges for this call, in USD.
+ *
+ * A price quoted per million tokens is, per token, that many millionths
+ * of a dollar — so the micros are `tokens × price`. The price is scaled
+ * to an integer first, because `100 × 1.1` in floating point is
+ * `110.00000000000001` and would round up to a micro nobody used.
+ * Fractions of a micro round up, which keeps the cheapest models from
+ * pricing a real call at nothing.
+ *
+ * @throws {UnknownModelError} when the id has no registered price.
+ */
+export function providerCost(
+  modelId: string,
+  inputTokens: number,
+  outputTokens: number
+): Money {
+  const config = requireModel(modelId);
+  const scaled = (price: number) => Math.round(price * PRICE_SCALE);
+  return money(
+    Math.ceil(
+      (inputTokens * scaled(config.costPerMInputTokens) +
+        outputTokens * scaled(config.costPerMOutputTokens)) /
+        PRICE_SCALE
+    ),
+    PROVIDER_CURRENCY
+  );
+}
+
+/** Prices carry at most six decimals of a dollar per million tokens. */
+const PRICE_SCALE = 1_000_000;
+
+/**
+ * What a deployment bills in: its currency, what one USD costs in it
+ * (micros, so `1_000_000` is a USD deployment and `920_000` a euro one
+ * at 0.92), and the margin over provider cost in basis points of a
+ * multiplier — `40_000` is 4×.
+ *
+ * Read per request from `billing_settings`; there is no ambient rate,
+ * because a framework that guesses an exchange rate is inventing money.
+ */
+export type BillingRate = {
+  currency: CurrencyCode;
+  usdRateMicros: number;
+  marginBp: number;
+};
+
+/**
+ * `40_000` bp = 4× provider cost, the fallback margin when a
+ * deployment's `billing_settings` row names none.
+ *
+ * INVARIANT — a 65% gross margin floor:
+ *   gross_margin = 1 − 1/multiplier
+ * Keeping gross_margin ≥ 0.65 means a multiplier ≥ 1/0.35 ≈ 2.857. At
+ * 4× this yields 75%, leaving buffer above the floor for FX moves and
+ * provider price rises. `pricing.test.ts` pins it.
+ */
+export const DEFAULT_MARGIN_BP = 40_000;
+
+const BP_PER_MULTIPLE = 10_000;
+
+/**
+ * Provider cost and what the reader is charged for it: cost × margin,
+ * converted into the deployment's currency at its own rate.
+ *
+ * Both steps round up, so a charge is at most two micros over — a
+ * millionth of a cent, against a fraction that would otherwise be the
+ * deployment's to eat on every request.
+ *
+ * @throws {UnknownModelError} when the id has no registered price.
+ * @throws {MoneyError} when a USD deployment passes a rate that is not 1.
+ */
+export function chargeFor(
+  modelId: string,
+  inputTokens: number,
+  outputTokens: number,
+  rate: BillingRate
+): { providerCost: Money; charged: Money } {
+  const cost = providerCost(modelId, inputTokens, outputTokens);
+  const withMargin = money(
+    Math.ceil((cost.amount * rate.marginBp) / BP_PER_MULTIPLE),
+    PROVIDER_CURRENCY
+  );
+  return {
+    providerCost: cost,
+    charged: convert(withMargin, rate.currency, rate.usdRateMicros),
+  };
+}
+
+/**
+ * The ceiling one turn on this model could charge, for admission:
+ * the model's own output limit against a 16K input budget (system
+ * prompt plus history). Refusing on the ceiling is what stops a turn
+ * that cannot be paid for from burning provider tokens first.
+ *
+ * @throws {UnknownModelError} when the id has no registered price.
+ */
+export function estimateWorstCaseCharge(
+  modelId: string,
+  rate: BillingRate
+): Money {
+  const outputBudget = requireModel(modelId).maxOutputTokens;
+  return chargeFor(modelId, ESTIMATE_INPUT_BUDGET, outputBudget, rate).charged;
+}
+
+const ESTIMATE_INPUT_BUDGET = 16_000;

package/src/queries.ts

@@ -0,0 +1,235 @@
+/**
+ * Read models over the executions table, for the product's usage UI
+ * and the admin console.
+ */
+
+import { db } from "@intelligo-dev/core/db";
+import { money, type Money } from "@intelligo-dev/core/money";
+import { and, desc, eq, gte, inArray, lt, lte, sql } from "drizzle-orm";
+
+import { executions } from "./db/schema";
+
+/**
+ * Charges summed per currency.
+ *
+ * A workspace bills in one currency, so this is normally one entry —
+ * but the rows are what the ledger holds, and adding two currencies
+ * into a single number is how a total starts lying. Rows with no
+ * currency are executions that were never charged.
+ */
+function chargedByCurrency(
+  rows: ReadonlyArray<{ currency: string | null; chargedMicros: unknown }>
+): Money[] {
+  const totals = new Map<string, number>();
+  for (const row of rows) {
+    if (!row.currency) continue;
+    // `sum()` of a bigint column arrives as a string.
+    const amount = Number(row.chargedMicros ?? 0);
+    if (amount === 0) continue;
+    totals.set(row.currency, (totals.get(row.currency) ?? 0) + amount);
+  }
+  return [...totals].map(([code, amount]) => money(amount, code));
+}
+
+export type ListExecutionsOptions = {
+  /** Required: every query is scoped to one tenant. */
+  workspaceId: string;
+  userId?: string;
+  capability?: string;
+  status?: "running" | "settling" | "succeeded" | "failed" | "refused";
+  /** Keyset pagination: rows started strictly before this. */
+  before?: Date;
+  limit?: number;
+};
+
+export async function listExecutions(options: ListExecutionsOptions) {
+  const filters = [
+    eq(executions.workspaceId, options.workspaceId),
+    options.userId ? eq(executions.userId, options.userId) : undefined,
+    options.capability
+      ? eq(executions.capability, options.capability)
+      : undefined,
+    options.status ? eq(executions.status, options.status) : undefined,
+    options.before ? lt(executions.startedAt, options.before) : undefined,
+  ].filter(Boolean);
+
+  return db
+    .select()
+    .from(executions)
+    .where(filters.length > 0 ? and(...filters) : undefined)
+    .orderBy(desc(executions.startedAt))
+    .limit(Math.min(options.limit ?? 50, 500));
+}
+
+export async function getExecutionByRequestId(requestId: string) {
+  const [row] = await db
+    .select()
+    .from(executions)
+    .where(eq(executions.requestId, requestId))
+    .limit(1);
+  return row ?? null;
+}
+
+/**
+ * Aggregate counts, tokens, and charge for a workspace over a window.
+ * Refused executions are counted separately — they consumed no tokens
+ * but they are the signal that a plan's limits are biting.
+ */
+export async function summarizeExecutions(
+  workspaceId: string,
+  window: { from: Date; to: Date }
+) {
+  const rows = await db
+    .select({
+      status: executions.status,
+      currency: executions.currency,
+      count: sql<number>`count(*)`,
+      totalTokens: sql<number>`coalesce(sum(${executions.totalTokens}), 0)`,
+      chargedMicros: sql<string>`coalesce(sum(${executions.chargedMicros}), 0)`,
+    })
+    .from(executions)
+    .where(
+      and(
+        eq(executions.workspaceId, workspaceId),
+        gte(executions.startedAt, window.from),
+        lte(executions.startedAt, window.to)
+      )
+    )
+    .groupBy(executions.status, executions.currency);
+
+  // A status can arrive as several rows — one per currency — so the
+  // per-status view folds them back together.
+  const byStatus: Record<
+    string,
+    { count: number; totalTokens: number; charged: Money[] }
+  > = {};
+  for (const r of rows) {
+    const seen = byStatus[r.status] ?? {
+      count: 0,
+      totalTokens: 0,
+      charged: [],
+    };
+    byStatus[r.status] = {
+      count: seen.count + Number(r.count),
+      totalTokens: seen.totalTokens + Number(r.totalTokens),
+      charged: chargedByCurrency(rows.filter((row) => row.status === r.status)),
+    };
+  }
+
+  return {
+    byStatus,
+    totals: {
+      ...rows.reduce(
+        (acc, r) => ({
+          count: acc.count + Number(r.count),
+          totalTokens: acc.totalTokens + Number(r.totalTokens),
+        }),
+        { count: 0, totalTokens: 0 }
+      ),
+      charged: chargedByCurrency(rows),
+    },
+  };
+}
+
+/**
+ * Per-day totals for a workspace over a window — the read model behind
+ * a usage chart.
+ *
+ * Aggregated in SQL rather than by bucketing rows in the application:
+ * a month of a busy workspace is thousands of rows to ship over the
+ * wire to produce thirty numbers, and any consumer that had to do that
+ * bucketing itself would be writing the query this package should own.
+ *
+ * Days with no activity are absent rather than zero — the caller knows
+ * the window it asked for, and a gap means "nothing ran", which a
+ * chart should draw as zero and a table should leave empty.
+ *
+ * `date` is a `YYYY-MM-DD` string in `timeZone`, which defaults to UTC.
+ * Pass the reader's own zone: bucketing a +08:00 reader's 00:36 turn in
+ * UTC files it on the previous day.
+ */
+export async function summarizeExecutionsByDay(
+  workspaceId: string,
+  window: { from: Date; to: Date },
+  options: { timeZone?: string } = {}
+): Promise<
+  Array<{
+    date: string;
+    count: number;
+    totalTokens: number;
+    charged: Money[];
+  }>
+> {
+  // Bound, not interpolated: the zone reaches here from a cookie the
+  // browser wrote, so it is caller input like any other.
+  //
+  // Two conversions, both needed. `started_at` is a naive timestamp
+  // holding a UTC instant, so `AT TIME ZONE 'UTC'` turns it into an
+  // instant, and the second `AT TIME ZONE` reads that instant as wall
+  // time where the reader is. One conversion would instead *declare*
+  // the stored time to be the reader's, which is a different moment.
+  const timeZone = options.timeZone ?? "UTC";
+  const day = sql<string>`to_char(${executions.startedAt} AT TIME ZONE 'UTC' AT TIME ZONE ${timeZone}, 'YYYY-MM-DD')`;
+
+  const rows = await db
+    .select({
+      date: day,
+      currency: executions.currency,
+      count: sql<number>`count(*)`,
+      totalTokens: sql<number>`coalesce(sum(${executions.totalTokens}), 0)`,
+      chargedMicros: sql<string>`coalesce(sum(${executions.chargedMicros}), 0)`,
+    })
+    .from(executions)
+    .where(
+      and(
+        eq(executions.workspaceId, workspaceId),
+        gte(executions.startedAt, window.from),
+        lte(executions.startedAt, window.to)
+      )
+    )
+    // By ordinal, not by the expression: drizzle inlines the fragment
+    // again for each clause, and with the zone bound as a parameter
+    // that makes three *different* expressions — Postgres then refuses
+    // the grouping. A literal zone matched textually and hid this.
+    .groupBy(sql`1`, executions.currency)
+    .orderBy(sql`1`);
+
+  // One row per day and currency; the series a chart draws is per day.
+  const byDay = new Map<string, (typeof rows)[number][]>();
+  for (const row of rows) {
+    byDay.set(row.date, [...(byDay.get(row.date) ?? []), row]);
+  }
+
+  return [...byDay].map(([date, dayRows]) => ({
+    date,
+    count: dayRows.reduce((sum, row) => sum + Number(row.count), 0),
+    totalTokens: dayRows.reduce((sum, row) => sum + Number(row.totalTokens), 0),
+    charged: chargedByCurrency(dayRows),
+  }));
+}
+
+/**
+ * Executions stuck in a non-terminal state past a cutoff.
+ *
+ * `running`: the stream died without reaching complete()/fail() —
+ * tokens were consumed and nothing was charged. `settling`: the charge
+ * was claimed but never confirmed — EITHER `settleUsage` threw and the
+ * workspace was not charged, OR the charge committed and the process
+ * died before the final `settling → succeeded` flip, in which case the
+ * workspace WAS charged. A `usage_records` row (or a `settled`
+ * reservation) for the same `requestId` distinguishes the two. This
+ * only reports; `createExecutions().reconcile()` repairs a row.
+ */
+export async function findStaleExecutions(olderThan: Date, limit = 100) {
+  return db
+    .select()
+    .from(executions)
+    .where(
+      and(
+        inArray(executions.status, ["running", "settling"]),
+        lt(executions.startedAt, olderThan)
+      )
+    )
+    .orderBy(desc(executions.startedAt))
+    .limit(limit);
+}