omnigateway 0.11.4 → 0.12.0

package/gateway.js

@@ -26376,6 +26376,54 @@ var _003_key_expiry_default = `-- The Postgres half of the sqlite migration of t
 ALTER TABLE api_keys ADD COLUMN expires_at BIGINT;
 `;
 
+// packages/store/src/postgres/migrations/004_log_keyset.sql
+var _004_log_keyset_default = `-- Indexes for the keyset traversal of \`request_logs\`. The SQLite copy,
+-- \`015_log_keyset.sql\`, carries the reasoning: \`id\` in the index is what makes
+-- "the row after this one" a question with one answer when \`at\` repeats, and
+-- the three shorter indexes are replaced rather than kept because a redundant
+-- prefix costs a write per row and answers nothing the longer one does not.
+DROP INDEX IF EXISTS idx_request_logs_at;
+DROP INDEX IF EXISTS idx_request_logs_key_at;
+DROP INDEX IF EXISTS idx_request_logs_cred;
+
+CREATE INDEX idx_request_logs_at ON request_logs (at DESC, id DESC);
+CREATE INDEX idx_request_logs_key_at ON request_logs (api_key_id, at DESC, id DESC);
+CREATE INDEX idx_request_logs_cred ON request_logs (credential_id, at DESC, id DESC);
+`;
+
+// packages/store/src/postgres/migrations/005_log_filter_indexes.sql
+var _005_log_filter_indexes_default = `-- An index for the provider filter on \`request_logs\`. Filtering by a provider
+-- with no traffic has nothing to seek, so proving the absence reads every row,
+-- and the console offers exactly that query because its dropdown is built from
+-- the provider catalog rather than from traffic. Measured here at 500,000 rows,
+-- and separately in the SQLite copy \`016_log_filter_indexes.sql\`:
+--
+--   resolved_provider =        without index    with index
+--   a provider with no rows        17.17ms        0.01ms
+--   a minority provider             0.04ms        0.02ms
+--   the dominant provider           0.02ms        0.02ms
+--
+-- Only the first row justifies the index, and it justifies it on both backends:
+-- without it the planner falls back to a sequential scan with a sort on top,
+-- because there is no prefix to seek and every row has to be rejected before the
+-- absence is proven. The other two answer off \`idx_request_logs_at\` either way \u2014
+-- a provider that has traffic fills a page near the head immediately.
+--
+-- Leading column then the keyset pair, so one seek answers the filter and the
+-- walk from it is already in page order.
+--
+-- **This is the only log-filter index on this backend, and the SQLite copy has
+-- one more.** There, \`017_log_text_search.sql\` moves \`requested_model\`,
+-- \`resolved_model\` and \`error_code\` into the keyset index so a substring scan
+-- tests the match against entries it is already walking. Do not mirror that
+-- here: this planner reads a leading-wildcard \`ILIKE\` as unindexable, so a
+-- substring miss plans as a parallel sequential scan with a sort on top and
+-- \`idx_request_logs_at\` is never opened. Measured at 500,000 rows, widening it
+-- cost 15MB to 58MB and a wider row per insert, and bought 0.25ms of 86ms. The
+-- backends share the predicate in \`logPage.ts\`, not the index shape.
+CREATE INDEX idx_request_logs_provider ON request_logs (resolved_provider, at DESC, id DESC);
+`;
+
 // packages/store/src/postgres/db.ts
 var num = (v) => Number(v);
 var numOrNull = (v) => v === null ? null : Number(v);
@@ -26383,7 +26431,9 @@ var MIGRATION_LOCK = 7140641;
 var MIGRATIONS = [
   { id: 1, sql: _001_init_default },
   { id: 2, sql: _002_health_measurements_default },
-  { id: 3, sql: _003_key_expiry_default }
+  { id: 3, sql: _003_key_expiry_default },
+  { id: 4, sql: _004_log_keyset_default },
+  { id: 5, sql: _005_log_filter_indexes_default }
 ];
 async function openPg(url2) {
   const sql = new SQL({ url: url2 });
@@ -27415,6 +27465,57 @@ function isRtkFilterId(value) {
   return FILTER_IDS.has(value);
 }
 
+// packages/store/src/logPage.ts
+function logPageClauses(query, placeholder, like = "LIKE") {
+  const clauses = [];
+  const bindings = [];
+  const bind = (value) => {
+    bindings.push(value);
+    return placeholder(bindings.length);
+  };
+  const contains = (column, value) => {
+    if (value === undefined)
+      return;
+    const escaped = value.replace(/[\\%_]/g, "\\$&");
+    clauses.push(`${column} ${like} ${bind(`%${escaped}%`)} ESCAPE '\\'`);
+  };
+  const eq = (column, value) => {
+    if (value !== undefined)
+      clauses.push(`${column} = ${bind(value)}`);
+  };
+  if (query.cursor !== null) {
+    const cursor = query.cursor;
+    clauses.push(`(at < ${bind(cursor.at)} OR (at = ${bind(cursor.at)} AND id < ${bind(cursor.id)}))`);
+  }
+  eq("api_key_id", query.apiKeyId);
+  eq("credential_id", query.credentialId);
+  eq("resolved_provider", query.provider);
+  eq("state", query.state);
+  contains("requested_model", query.requestedModel);
+  contains("resolved_model", query.resolvedModel);
+  contains("error_code", query.errorCode);
+  if (query.model !== undefined) {
+    const before = clauses.length;
+    contains("requested_model", query.model);
+    contains("resolved_model", query.model);
+    clauses.push(`(${clauses.splice(before).join(" OR ")})`);
+  }
+  if (query.since !== undefined)
+    clauses.push(`at >= ${bind(query.since)}`);
+  if (query.until !== undefined)
+    clauses.push(`at <= ${bind(query.until)}`);
+  if (query.failed === true)
+    clauses.push("state = 'done' AND status >= 400");
+  return { where: clauses.length === 0 ? "" : `WHERE ${clauses.join(" AND ")}`, bindings };
+}
+function splitPage(rows, limit) {
+  if (rows.length <= limit)
+    return { logs: rows, next: null };
+  const logs = rows.slice(0, limit);
+  const last = logs[logs.length - 1];
+  return { logs, next: last === undefined ? null : { at: last.at, id: last.id } };
+}
+
 // packages/store/src/postgres/rollup.ts
 var DAILY_UPSERT = `
   INSERT INTO usage_daily
@@ -27719,6 +27820,12 @@ function createUsageRepo(sql, nodeId, dayOffsetMinutes) {
       ]) : await sql.unsafe("SELECT * FROM request_logs WHERE api_key_id = $1 ORDER BY at DESC LIMIT $2", [apiKeyId, limit]);
       return rows.map(toLog);
     },
+    async page(query) {
+      const { where, bindings } = logPageClauses(query, (n) => `$${n}`, "ILIKE");
+      const rows = (await sql.unsafe(`SELECT * FROM request_logs ${where}
+            ORDER BY at DESC, id DESC LIMIT $${bindings.length + 1}`, [...bindings, query.limit + 1])).map(toLog);
+      return splitPage(rows, query.limit);
+    },
     async lastUsedByCredential(credentialId) {
       const rows = await sql.unsafe("SELECT MAX(at) AS at FROM request_logs WHERE credential_id = $1", [credentialId]);
       return numOrNull(rows[0]?.at ?? null);
@@ -28950,6 +29057,114 @@ var _014_key_expiry_default = `-- An optional expiry on a gateway API key: an ab
 ALTER TABLE api_keys ADD COLUMN expires_at INTEGER;
 `;
 
+// packages/store/src/sqlite/migrations/015_log_keyset.sql
+var _015_log_keyset_default = "-- Indexes for the keyset traversal of `request_logs`.\n--\n-- Ordering by `at DESC, id DESC` is what makes a page boundary exact: `at`\n-- repeats within a millisecond, so an index on `at` alone leaves SQLite to\n-- resolve the tie however the scan happens to reach it, and the resolution can\n-- differ between two reads of the same table. The `id` column in the index is\n-- therefore not a tie-break for display \u2014 it is what makes \"the row after this\n-- one\" a question with one answer.\n--\n-- Each of the three replaces a shorter index with the same leading columns, so\n-- they are dropped rather than kept beside the new ones. A redundant prefix\n-- index costs a write on every row inserted and answers no query the longer one\n-- does not: `(at DESC, id DESC)` seeks and scans exactly as `(at DESC)` did for\n-- every reader that never mentions `id`, including `prune`'s range delete and\n-- `aggregate`'s window.\n--\n-- The key and credential indexes are the two scoped reads that must stay\n-- bounded. `api_key_id` is every client page and every scoped operator read,\n-- and it is also the sliding-window limiter's edge scan, which runs on the\n-- request hot path. `credential_id` is `lastUsedByCredential` \u2014 one seek to a\n-- head \u2014 and the account investigation an operator reaches for first.\n--\n-- Deliberately no index for `provider`, `resolved_model`, `state` or\n-- `error_code`. One index per filter is a combinatorial answer to a question\n-- nobody has measured yet, paid for on every insert; the cursor and the time\n-- bounds already keep a filtered page's scan to the rows above it. A production\n-- measurement of the query distribution is what should buy the next index.\nDROP INDEX IF EXISTS idx_request_logs_at;\nDROP INDEX IF EXISTS idx_request_logs_key_at;\nDROP INDEX IF EXISTS idx_request_logs_cred;\n\nCREATE INDEX idx_request_logs_at ON request_logs (at DESC, id DESC);\nCREATE INDEX idx_request_logs_key_at ON request_logs (api_key_id, at DESC, id DESC);\nCREATE INDEX idx_request_logs_cred ON request_logs (credential_id, at DESC, id DESC);\n";
+
+// packages/store/src/sqlite/migrations/016_log_filter_indexes.sql
+var _016_log_filter_indexes_default = `-- An index for the provider filter on \`request_logs\`, which \`015_log_keyset.sql\`
+-- deliberately left out pending a measurement. This is that measurement.
+--
+-- Without it, filtering by a provider that has *no* traffic scans the whole
+-- table: there is nothing to seek, so proving the absence means reading every
+-- row. \`bun:sqlite\` is synchronous, so that scan is the event loop \u2014 time in
+-- which no proxied request moves. Measured at 500,000 rows:
+--
+--   resolved_provider =        without index    with index
+--   a provider with no rows          84.0ms         0.0ms
+--   a minority provider              0.19ms         0.10ms
+--   the dominant provider            0.09ms         0.08ms
+--
+-- Only the first row justifies the index, and it justifies it completely. It is
+-- also the case the console invites: the filter is a dropdown built from the
+-- provider catalog rather than from traffic, so every provider this gateway
+-- *could* route to is offered, including the ones an operator has no account
+-- for. Selecting one is a normal thing to do and it was the most expensive
+-- query on the surface.
+--
+-- Leading column then the keyset pair, so one seek answers the filter and the
+-- walk from it is already in page order.
+--
+-- \`state\` gets nothing: \`idx_request_logs_pending\` already covers the only
+-- selective half, and \`state = 'done'\` is every row, so the keyset index fills a
+-- page immediately. Nothing per-column for \`failed\` either, whose predicate is
+-- \`state = 'done' AND status >= 400\` and which reads at 1.0ms off the keyset
+-- index, because failures cluster near the head an operator is looking at.
+--
+-- The filters an operator *types* are not here, and not by omission: they match
+-- substrings, which no B-tree can seek. \`017_log_text_search.sql\` carries them,
+-- and carries them inside the keyset index rather than beside it.
+CREATE INDEX idx_request_logs_provider ON request_logs (resolved_provider, at DESC, id DESC);
+`;
+
+// packages/store/src/sqlite/migrations/017_log_text_search.sql
+var _017_log_text_search_default = `-- Indexes the typed log filters, which match substrings rather than values.
+--
+-- \`requested_model\`, \`resolved_model\`, \`error_code\`, and the \`model\` filter that
+-- reads the first two, became \`LIKE '%value%'\`, because an exact match on a name
+-- nobody recalls exactly answered "no such traffic" for every spelling but one. A
+-- leading wildcard cannot seek a B-tree: there is no prefix to range over.
+--
+-- The three \`DROP\`s below are **upgrade-only cleanup and no-ops on a fresh
+-- install.** An earlier draft of 016 created a per-column index for each of these
+-- three filters, back when they were equalities. Nothing released ever ran it, so
+-- 016 now creates only the provider index it still justifies \u2014 but a database
+-- that applied the draft is carrying three indexes that can no longer be seeked
+-- and still cost a write per row, so they are named here rather than left to rot.
+-- Building them only to drop them cost an upgrading install 1,334ms at 1,000,000
+-- rows, which is why the fix was to stop creating them rather than to keep the
+-- symmetry.
+--
+-- What the typed filters get instead is those same columns moved *into* the keyset
+-- index. The scan is going to walk \`(at DESC, id DESC)\` regardless \u2014 that is where
+-- the ordering comes from \u2014 and carrying the three text columns in that index lets
+-- it test the match against index entries rather than fetching each row to do it.
+-- Only the page that survives is fetched.
+--
+-- Measured at 1,000,000 rows of 300 bytes, filter matching nothing, which is the
+-- case that has to scan to the end to prove it:
+--
+--   keyset index          model filter   error filter   head read   index size
+--   (at, id)                   204.4ms        160.1ms      0.08ms        44.2MB
+--   (at, id, + 3 columns)       78.3ms         33.0ms      0.08ms        87.0MB
+--
+-- So: 2.6x on the model filter, 4.8x on the error one, no cost to the unfiltered
+-- head read every board opens with, and double the index. The size is the price
+-- and it is worth naming \u2014 at a million rows this index is 87MB against 44MB \u2014
+-- but it is one index instead of three, and it is the only shape a substring can
+-- use at all.
+--
+-- A second, separate covering index does **not** work: SQLite prefers the
+-- narrower index that supplies the ordering and ignores the wider one, measured
+-- at 198ms against 202ms. The columns have to be in the index the scan already
+-- wants, which is why this replaces \`idx_request_logs_at\` rather than joining it.
+--
+-- \`resolved_provider\` keeps 016's index and its \`=\`: it arrives from a dropdown
+-- of ids the gateway supplied, so it is never half-typed, a substring would only
+-- widen it, and an equality can still seek \u2014 which is worth 84ms to 0 on a
+-- provider with no traffic.
+--
+-- The \`ANALYZE\` trap an earlier draft of 016 documented is gone with the plan
+-- that had it. There is one plan for a leading wildcard, so statistics have
+-- nothing to choose between: measured identical, 22.5ms either way at 300,000
+-- rows.
+--
+-- A time bound still collapses all of this \u2014 the same 22.5ms miss is 0.23ms with
+-- \`since\` set to the newest 1% \u2014 because \`at\` still leads the index. That remains
+-- the cheapest thing an operator can do, and the reason export requires both
+-- bounds. If a substring miss on a very large log ever needs to be free rather
+-- than linear, the next step is FTS5's trigram tokenizer, which is a shadow
+-- table and a trigger to keep in sync and a \`pg_trgm\` GIN index to match it on
+-- the other backend. Not worth it for one query per typed name, behind a
+-- debounce.
+DROP INDEX IF EXISTS idx_request_logs_resolved_model;
+DROP INDEX IF EXISTS idx_request_logs_requested_model;
+DROP INDEX IF EXISTS idx_request_logs_error_code;
+
+DROP INDEX IF EXISTS idx_request_logs_at;
+CREATE INDEX idx_request_logs_at
+  ON request_logs (at DESC, id DESC, requested_model, resolved_model, error_code);
+`;
+
 // packages/store/src/sqlite/db.ts
 var MIGRATIONS2 = [
   { id: 1, sql: _001_init_default2 },
@@ -28965,7 +29180,10 @@ var MIGRATIONS2 = [
   { id: 11, sql: _011_plugin_migrations_default },
   { id: 12, sql: _012_nodes_default },
   { id: 13, sql: _013_health_measurements_default },
-  { id: 14, sql: _014_key_expiry_default }
+  { id: 14, sql: _014_key_expiry_default },
+  { id: 15, sql: _015_log_keyset_default },
+  { id: 16, sql: _016_log_filter_indexes_default },
+  { id: 17, sql: _017_log_text_search_default }
 ];
 function statements(sql) {
   return sql.split(`
@@ -29466,6 +29684,11 @@ function createUsageRepo2(db, nodeId, dayOffsetMinutes = hostDayOffsetMinutes())
       }
       return db.query("SELECT * FROM request_logs WHERE api_key_id = ? ORDER BY at DESC LIMIT ?").all(apiKeyId, limit).map(toLog2);
     },
+    async page(query) {
+      const { where, bindings } = logPageClauses(query, () => "?");
+      const rows = db.query(`SELECT * FROM request_logs ${where} ORDER BY at DESC, id DESC LIMIT ?`).all(...bindings, query.limit + 1).map(toLog2);
+      return splitPage(rows, query.limit);
+    },
     async lastUsedByCredential(credentialId) {
       const row = db.query("SELECT MAX(at) AS at FROM request_logs WHERE credential_id = ?").get(credentialId);
       return row?.at ?? null;
@@ -29660,6 +29883,7 @@ async function createStore(opts) {
       append: (log) => handle.usage.append(log),
       sweepPending: (now) => handle.usage.sweepPending(now),
       recent: (limit, apiKeyId) => handle.usage.recent(limit, apiKeyId),
+      page: (query) => handle.usage.page(query),
       lastUsedByCredential: (credentialId) => handle.usage.lastUsedByCredential(credentialId),
       scan: (cursor, limit) => handle.usage.scan(cursor, limit),
       aggregate: (q) => handle.usage.aggregate(q),
@@ -37466,6 +37690,13 @@ var credentialPatchSchema = exports_external.object({
   tier: exports_external.number().int().min(1).optional(),
   weight: exports_external.number().positive().optional()
 }).strict();
+var quotaRefreshSchema = exports_external.discriminatedUnion("kind", [
+  exports_external.object({
+    kind: exports_external.literal("one"),
+    credentialId: exports_external.string().trim().min(1).max(64).regex(/^[A-Za-z0-9_-]+$/, "credentialId must be an account id")
+  }).strict(),
+  exports_external.object({ kind: exports_external.literal("all") }).strict()
+]);
 var dimensionSchema = exports_external.enum([
   "credential",
   "model",
@@ -38697,6 +38928,243 @@ async function requestRestart(deps) {
 async function requestShutdown(deps) {
   deps.stop(0);
 }
+// packages/control/src/principal.ts
+var ALL = { kind: "all" };
+var NONE2 = { kind: "none" };
+function scopeOf(principal) {
+  switch (principal.kind) {
+    case "admin":
+    case "viewer":
+      return ALL;
+    case "client":
+      return principal.apiKeyId === "" ? NONE2 : { kind: "key", apiKeyId: principal.apiKeyId };
+    case "machine":
+      return NONE2;
+  }
+}
+function scopeKey(scope) {
+  return scope.kind === "key" ? scope.apiKeyId : undefined;
+}
+function readsNothing(scope) {
+  return scope.kind === "none" || scope.kind === "key" && scope.apiKeyId === "";
+}
+
+// packages/control/src/usage.ts
+var MAX_LOG_LIMIT = 500;
+var DEFAULT_LOG_LIMIT = 100;
+async function queryUsage(deps, input2, scope = ALL) {
+  const grain = parseOrThrow(grainSchema, input2.grain ?? "raw");
+  const groupBy = requireDimension(grain, parseOrThrow(dimensionSchema, input2.groupBy ?? "model"));
+  const splitBy = input2.splitBy === undefined ? undefined : requireDimension(grain, parseOrThrow(dimensionSchema, input2.splitBy));
+  if (scope.kind !== "all") {
+    for (const dimension of [groupBy, splitBy]) {
+      if (dimension === "credential") {
+        throw new GatewayError("BAD_REQUEST", "this dimension is not available on this surface");
+      }
+    }
+  }
+  if (readsNothing(scope))
+    return [];
+  const apiKeyId = scopeKey(scope);
+  return deps.store.usage.aggregate({
+    grain,
+    groupBy,
+    ...splitBy === undefined ? {} : { splitBy },
+    ...apiKeyId === undefined ? {} : { apiKeyId },
+    since: optionalNumber(input2.since, 0),
+    until: optionalNumber(input2.until, deps.now())
+  });
+}
+function logLimit(requested) {
+  const value = optionalNumber(requested, DEFAULT_LOG_LIMIT);
+  return Math.floor(Math.min(Math.max(1, value), MAX_LOG_LIMIT));
+}
+
+// packages/control/src/logs.ts
+var CURSOR_VERSION = 1;
+var MAX_ID_LENGTH = 128;
+var MAX_FILTER_LENGTH = 256;
+var idSchema = exports_external.string().min(1).max(MAX_ID_LENGTH);
+var textSchema = exports_external.string().min(1).max(MAX_FILTER_LENGTH);
+var instantSchema = exports_external.union([
+  exports_external.number(),
+  exports_external.string().regex(/^-?\d+$/, "must be epoch milliseconds").transform(Number)
+]).pipe(exports_external.number().int());
+var logFilterSchema = exports_external.object({
+  cursor: exports_external.string().max(512).optional(),
+  limit: exports_external.union([exports_external.string(), exports_external.number()]).optional(),
+  since: instantSchema.optional(),
+  until: instantSchema.optional(),
+  state: exports_external.enum(["pending", "done"]).optional(),
+  failed: exports_external.enum(["true", "false"]).optional(),
+  provider: providerIdSchema.optional(),
+  requestedModel: textSchema.optional(),
+  resolvedModel: textSchema.optional(),
+  model: textSchema.optional(),
+  credentialId: idSchema.optional(),
+  apiKeyId: idSchema.optional(),
+  errorCode: textSchema.optional()
+}).strict();
+function present(input2) {
+  const out = {};
+  for (const [key, value] of Object.entries(input2)) {
+    if (value === undefined || value === "")
+      continue;
+    out[key] = typeof value === "boolean" ? String(value) : value;
+  }
+  return out;
+}
+function encodeLogCursor(cursor) {
+  const json10 = JSON.stringify({ v: CURSOR_VERSION, at: cursor.at, id: cursor.id });
+  return Buffer.from(json10, "utf8").toString("base64url");
+}
+function decodeLogCursor(raw) {
+  const reject = () => {
+    throw new GatewayError("BAD_REQUEST", "cursor: malformed");
+  };
+  let parsed2;
+  try {
+    parsed2 = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+  } catch {
+    return reject();
+  }
+  if (typeof parsed2 !== "object" || parsed2 === null || Array.isArray(parsed2))
+    return reject();
+  const record2 = parsed2;
+  const keys = Object.keys(record2);
+  if (keys.length !== 3)
+    return reject();
+  if (record2.v !== CURSOR_VERSION) {
+    throw new GatewayError("BAD_REQUEST", "cursor: unknown version");
+  }
+  const { at, id } = record2;
+  if (typeof at !== "number" || !Number.isSafeInteger(at))
+    return reject();
+  if (typeof id !== "string" || id.length === 0 || id.length > MAX_ID_LENGTH)
+    return reject();
+  const cursor = { at, id };
+  if (encodeLogCursor(cursor) !== raw)
+    return reject();
+  return cursor;
+}
+function toQuery(input2, scope) {
+  const filters = parseOrThrow(logFilterSchema, present(input2));
+  const { since, until } = filters;
+  if (since !== undefined && until !== undefined && since > until) {
+    throw new GatewayError("BAD_REQUEST", "since: must not be after until");
+  }
+  const scoped = scopeKey(scope);
+  return {
+    limit: logLimit(filters.limit),
+    cursor: filters.cursor === undefined ? null : decodeLogCursor(filters.cursor),
+    ...filters.apiKeyId === undefined ? {} : { apiKeyId: filters.apiKeyId },
+    ...scoped === undefined ? {} : { apiKeyId: scoped },
+    ...filters.credentialId === undefined ? {} : { credentialId: filters.credentialId },
+    ...filters.provider === undefined ? {} : { provider: filters.provider },
+    ...filters.requestedModel === undefined ? {} : { requestedModel: filters.requestedModel },
+    ...filters.resolvedModel === undefined ? {} : { resolvedModel: filters.resolvedModel },
+    ...filters.model === undefined ? {} : { model: filters.model },
+    ...filters.errorCode === undefined ? {} : { errorCode: filters.errorCode },
+    ...filters.state === undefined ? {} : { state: filters.state },
+    ...filters.failed === "true" ? { failed: true } : {},
+    ...since === undefined ? {} : { since },
+    ...until === undefined ? {} : { until }
+  };
+}
+async function pageLogs(store, input2 = {}, scope = ALL) {
+  const query = toQuery(input2, scope);
+  if (readsNothing(scope))
+    return { logs: [], nextCursor: null };
+  const page = await store.usage.page(query);
+  return {
+    logs: page.logs,
+    nextCursor: page.next === null ? null : encodeLogCursor(page.next)
+  };
+}
+var EXPORT_BATCH = 500;
+var EXPORT_COLUMNS = [
+  "id",
+  "state",
+  "at",
+  "apiKeyId",
+  "requestedModel",
+  "resolvedProvider",
+  "resolvedModel",
+  "credentialId",
+  "attempts",
+  "status",
+  "errorCode",
+  "inputTokens",
+  "outputTokens",
+  "cacheReadTokens",
+  "cacheWriteTokens",
+  "ttftMs",
+  "durationMs",
+  "costUsd",
+  "degradations",
+  "rtkApplied",
+  "rtkFilterHits",
+  "rtkOriginalCodeUnits",
+  "rtkCompressedCodeUnits",
+  "rtkEstimatedTokensSaved",
+  "rtkFilters"
+];
+function csvCell(value) {
+  if (value === null || value === undefined)
+    return "";
+  const text = Array.isArray(value) ? JSON.stringify(value) : String(value);
+  const first = text.trimStart().charAt(0);
+  const guarded = "=+-@".includes(first) && first !== "" ? `'${text}` : text;
+  return /[",\r\n]/.test(guarded) ? `"${guarded.replaceAll('"', '""')}"` : guarded;
+}
+var csvRow = (cells) => `${cells.map(csvCell).join(",")}\r
+`;
+function exportHeader(format) {
+  return format === "csv" ? csvRow(EXPORT_COLUMNS) : "";
+}
+function exportRow(format, log) {
+  if (format === "jsonl") {
+    const ordered = {};
+    for (const column of EXPORT_COLUMNS)
+      ordered[column] = log[column];
+    return `${JSON.stringify(ordered)}
+`;
+  }
+  return csvRow(EXPORT_COLUMNS.map((column) => log[column]));
+}
+var EXPORT_CONTENT_TYPE = {
+  csv: "text/csv; charset=utf-8",
+  jsonl: "application/x-ndjson"
+};
+function exportFilename(format, now) {
+  const stamp = new Date(now).toISOString().replaceAll(/[:.]/g, "-");
+  return `omnigateway-logs-${stamp}.${format}`;
+}
+var formatSchema = exports_external.enum(["csv", "jsonl"]);
+async function* exportLogs(store, input2, scope = ALL) {
+  const { format: requested, ...filters } = input2;
+  const format = parseOrThrow(formatSchema, requested ?? "csv");
+  if (input2.since === undefined || input2.since === "") {
+    throw new GatewayError("BAD_REQUEST", "since: required for export");
+  }
+  if (input2.until === undefined || input2.until === "") {
+    throw new GatewayError("BAD_REQUEST", "until: required for export");
+  }
+  const base = toQuery({ ...filters, limit: EXPORT_BATCH, cursor: undefined }, scope);
+  if (readsNothing(scope)) {
+    yield exportHeader(format);
+    return;
+  }
+  let page = await store.usage.page(base);
+  yield exportHeader(format);
+  for (;; ) {
+    for (const log of page.logs)
+      yield exportRow(format, log);
+    if (page.next === null)
+      return;
+    page = await store.usage.page({ ...base, cursor: page.next });
+  }
+}
 // packages/control/src/modelLimits.ts
 function narrower(a, b) {
   const context = [a.contextWindow, b.contextWindow].filter((n) => n !== undefined);
@@ -38845,7 +39313,7 @@ var CAPABILITIES = [
   "provider"
 ];
 var ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
-var idSchema = exports_external.string().regex(ID_PATTERN, "id must match /^[a-z][a-z0-9-]{0,31}$/");
+var idSchema2 = exports_external.string().regex(ID_PATTERN, "id must match /^[a-z][a-z0-9-]{0,31}$/");
 var entrySchema = exports_external.string().min(1).refine((p) => !p.startsWith("/") && !p.split("/").includes(".."), {
   message: "entry must be a relative path with no '..' segment"
 });
@@ -38869,7 +39337,7 @@ var navSchema = exports_external.object({
 }).strict();
 var ORIGIN_CAPABILITIES = ["net:outbound", "provider"];
 var manifestSchema = exports_external.object({
-  id: idSchema,
+  id: idSchema2,
   name: exports_external.string().min(1).max(64),
   version: exports_external.string().min(1).max(32),
   api: exports_external.number().int().nonnegative(),
@@ -39433,26 +39901,6 @@ function readProviders(pluginId, manifest, definition) {
   }
   return declared.map((entry) => validateRegistration(pluginId, entry, manifest.origins));
 }
-// packages/control/src/principal.ts
-var ALL = { kind: "all" };
-var NONE2 = { kind: "none" };
-function scopeOf(principal) {
-  switch (principal.kind) {
-    case "admin":
-    case "viewer":
-      return ALL;
-    case "client":
-      return principal.apiKeyId === "" ? NONE2 : { kind: "key", apiKeyId: principal.apiKeyId };
-    case "machine":
-      return NONE2;
-  }
-}
-function scopeKey(scope) {
-  return scope.kind === "key" ? scope.apiKeyId : undefined;
-}
-function readsNothing(scope) {
-  return scope.kind === "none" || scope.kind === "key" && scope.apiKeyId === "";
-}
 // packages/control/src/quota/headroom.ts
 function usedRatioOf(used, limit) {
   if (limit === null || limit <= 0)
@@ -39596,6 +40044,9 @@ async function accountQuotaHistory(deps, input2) {
 var CONCURRENCY = 4;
 var RATE_LIMIT_COOLDOWN_MS = 180000;
 var COOLDOWN_PREFIX = "quota:cooldown:";
+var PROBE_LOCK_PREFIX = "quota:probe:";
+var PROBE_LOCK_TTL_MS = 60000;
+var PROBE_LOCK_WAIT_MS = 30000;
 async function probe(deps, credential) {
   if (credential.authType !== "oauth")
     return null;
@@ -39626,39 +40077,148 @@ async function probe(deps, credential) {
   });
   return rows;
 }
-async function poll(deps) {
-  const logger2 = deps.logger ?? noopLogger;
-  const _now = deps.now();
-  const eligible2 = (await deps.store.credentials.list()).filter((c) => c.enabled && c.authType === "oauth" && deps.providers[c.provider]?.usage !== undefined);
-  const cooling = await Promise.all(eligible2.map((c) => deps.coord.kv.get(COOLDOWN_PREFIX + c.id)));
-  const credentials = eligible2.filter((_, index) => cooling[index] === null);
-  let written = 0;
+async function inOrder(items, job) {
+  const results = new Array(items.length).fill(undefined);
   let next = 0;
   const worker = async () => {
-    while (next < credentials.length) {
-      const credential = credentials[next++];
-      if (credential === undefined)
+    while (next < items.length) {
+      const index = next++;
+      const item = items[index];
+      if (item === undefined)
         return;
-      try {
-        if (await probe(deps, credential) !== null)
-          written += 1;
-      } catch (error62) {
-        const rateLimited = error62 instanceof GatewayError && error62.code === "RATE_LIMIT";
-        if (rateLimited) {
-          await deps.coord.kv.set(COOLDOWN_PREFIX + credential.id, "1", RATE_LIMIT_COOLDOWN_MS);
-        }
-        logger2.warn(rateLimited ? "quota probe rate limited" : "quota probe failed", {
-          provider: credential.provider,
-          credentialId: credential.id,
-          code: error62 instanceof GatewayError ? error62.code : "INTERNAL",
-          ...rateLimited ? { retryAfterMs: RATE_LIMIT_COOLDOWN_MS } : {},
-          reason: describeError(error62, "unknown")
-        });
+      results[index] = await job(item);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, items.length) }, () => worker()));
+  return results;
+}
+function quotaOps(deps) {
+  const logger2 = deps.logger ?? noopLogger;
+  const inFlight = new Map;
+  async function coordinated(credential, fallback, fn) {
+    try {
+      return await fn();
+    } catch (error62) {
+      logger2.warn("quota probe coordination unavailable", {
+        provider: credential.provider,
+        credentialId: credential.id,
+        coordFallback: true,
+        reason: describeError(error62, "unknown")
+      });
+      return fallback;
+    }
+  }
+  function reportFailure(credential, error62) {
+    const rateLimited = error62 instanceof GatewayError && error62.code === "RATE_LIMIT";
+    logger2.warn(rateLimited ? "quota probe rate limited" : "quota probe failed", {
+      provider: credential.provider,
+      credentialId: credential.id,
+      code: error62 instanceof GatewayError ? error62.code : "INTERNAL",
+      ...rateLimited ? { retryAfterMs: RATE_LIMIT_COOLDOWN_MS } : {},
+      reason: describeError(error62, "unknown")
+    });
+    return error62 instanceof GatewayError ? error62.code : "INTERNAL";
+  }
+  async function runProbe(credential) {
+    const credentialId = credential.id;
+    try {
+      const rows = await probe(deps, credential);
+      if (rows === null)
+        return { outcome: { kind: "noData", credentialId }, wrote: false };
+      return { outcome: { kind: "refreshed", credentialId, windows: rows.length }, wrote: true };
+    } catch (error62) {
+      if (error62 instanceof GatewayError && error62.code === "RATE_LIMIT") {
+        await coordinated(credential, undefined, () => deps.coord.kv.set(COOLDOWN_PREFIX + credentialId, "1", RATE_LIMIT_COOLDOWN_MS));
+      }
+      return {
+        outcome: { kind: "failed", credentialId, code: reportFailure(credential, error62) },
+        wrote: false
+      };
+    }
+  }
+  async function runGuarded(credential, startedAt) {
+    const credentialId = credential.id;
+    let entered = false;
+    const body2 = async () => {
+      entered = true;
+      const rows = (await deps.store.credentials.listQuota()).filter((row) => row.credentialId === credentialId);
+      if (rows.some((row) => row.observedAt >= startedAt)) {
+        return { outcome: { kind: "coalesced", credentialId, windows: rows.length }, wrote: false };
       }
+      return runProbe(credential);
+    };
+    try {
+      return await deps.coord.mutex.withLock(PROBE_LOCK_PREFIX + credentialId, PROBE_LOCK_TTL_MS, PROBE_LOCK_WAIT_MS, body2);
+    } catch (error62) {
+      if (entered)
+        return { outcome: { kind: "failed", credentialId, code: "INTERNAL" }, wrote: false };
+      logger2.warn("quota probe lock unavailable", {
+        provider: credential.provider,
+        credentialId,
+        coordFallback: true,
+        reason: describeError(error62, "unknown")
+      });
+      return runProbe(credential);
+    }
+  }
+  function attempt(credential) {
+    const credentialId = credential.id;
+    if (!credential.enabled) {
+      return Promise.resolve({ outcome: { kind: "disabled", credentialId }, wrote: false });
+    }
+    if (credential.authType !== "oauth" || deps.providers[credential.provider]?.usage === undefined) {
+      return Promise.resolve({ outcome: { kind: "unsupported", credentialId }, wrote: false });
+    }
+    const running = inFlight.get(credentialId);
+    if (running !== undefined) {
+      return running.then((shared) => shared.outcome.kind === "refreshed" ? {
+        outcome: {
+          kind: "coalesced",
+          credentialId,
+          windows: shared.outcome.windows
+        },
+        wrote: false
+      } : { outcome: shared.outcome, wrote: false });
+    }
+    const startedAt = deps.now();
+    const started = (async () => {
+      const cooling = await coordinated(credential, null, () => deps.coord.kv.get(COOLDOWN_PREFIX + credentialId));
+      if (cooling !== null) {
+        return { outcome: { kind: "cooldown", credentialId }, wrote: false };
+      }
+      return runGuarded(credential, startedAt);
+    })();
+    inFlight.set(credentialId, started);
+    return started.finally(() => {
+      inFlight.delete(credentialId);
+    });
+  }
+  return {
+    async poll() {
+      const credentials = await deps.store.credentials.list();
+      const attempts = await inOrder(credentials, attempt);
+      return attempts.filter((a) => a?.wrote === true).length;
+    },
+    async refresh(request2) {
+      if (request2.kind === "one") {
+        const credentialId = request2.credentialId.trim();
+        if (credentialId === "")
+          throw new GatewayError("BAD_REQUEST", "no such credential");
+        const credential = await deps.store.credentials.get(credentialId);
+        if (credential === null)
+          throw new GatewayError("BAD_REQUEST", "no such credential");
+        return { outcomes: [(await attempt(credential)).outcome] };
+      }
+      const credentials = await deps.store.credentials.list();
+      const attempts = await inOrder(credentials, attempt);
+      const outcomes = [];
+      for (const [index, credential] of credentials.entries()) {
+        const result = attempts[index];
+        outcomes.push(result?.outcome ?? { kind: "failed", credentialId: credential.id, code: "INTERNAL" });
+      }
+      return { outcomes };
     }
   };
-  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, credentials.length) }, () => worker()));
-  return written;
 }
 // packages/control/src/settings.ts
 async function getSettings(store) {
@@ -39864,41 +40424,6 @@ function readFrom(path, offset) {
     closeSync(fd);
   }
 }
-// packages/control/src/usage.ts
-var MAX_LOG_LIMIT = 500;
-var DEFAULT_LOG_LIMIT = 100;
-async function queryUsage(deps, input2, scope = ALL) {
-  const grain = parseOrThrow(grainSchema, input2.grain ?? "raw");
-  const groupBy = requireDimension(grain, parseOrThrow(dimensionSchema, input2.groupBy ?? "model"));
-  const splitBy = input2.splitBy === undefined ? undefined : requireDimension(grain, parseOrThrow(dimensionSchema, input2.splitBy));
-  if (scope.kind !== "all") {
-    for (const dimension of [groupBy, splitBy]) {
-      if (dimension === "credential") {
-        throw new GatewayError("BAD_REQUEST", "this dimension is not available on this surface");
-      }
-    }
-  }
-  if (readsNothing(scope))
-    return [];
-  const apiKeyId = scopeKey(scope);
-  return deps.store.usage.aggregate({
-    grain,
-    groupBy,
-    ...splitBy === undefined ? {} : { splitBy },
-    ...apiKeyId === undefined ? {} : { apiKeyId },
-    since: optionalNumber(input2.since, 0),
-    until: optionalNumber(input2.until, deps.now())
-  });
-}
-function logLimit(requested) {
-  const value = optionalNumber(requested, DEFAULT_LOG_LIMIT);
-  return Math.floor(Math.min(Math.max(1, value), MAX_LOG_LIMIT));
-}
-async function recentLogs(store, requested, scope = ALL) {
-  if (readsNothing(scope))
-    return [];
-  return store.usage.recent(logLimit(requested), scopeKey(scope));
-}
 // packages/plugin-api/src/events.ts
 var WINDOW_MS2 = {
   "1m": 60000,
@@ -55834,6 +56359,7 @@ function createQuiesceLatch() {
 }
 
 // apps/gateway/src/routes/admin.ts
+var EXPORT_ENCODER = new TextEncoder;
 function adminRoutes(deps) {
   const logger2 = deps.logger ?? noopLogger;
   const reportedCatalogProblems = new Set;
@@ -55924,6 +56450,17 @@ function adminRoutes(deps) {
       until: query.until,
       credentialId: query.credentialId
     });
+  }).post("/api/credentials/quota/refresh", async ({ request: request2 }) => {
+    await requireAdmin(request2, deps.admin);
+    const quota = deps.quota;
+    if (quota === undefined) {
+      throw new GatewayError("INTERNAL", "quota refresh is not available on this process");
+    }
+    const result = await quota.refresh(parseOrThrow(quotaRefreshSchema, await readJson(request2)));
+    if (result.outcomes.some((o) => o.kind === "refreshed" || o.kind === "coalesced")) {
+      changed("res:quota");
+    }
+    return result;
   }).patch("/api/credentials/:id", async ({ request: request2, params }) => {
     await requireAdmin(request2, deps.admin);
     await patchCredential(deps, params.id, await readJson(request2));
@@ -56066,7 +56603,33 @@ function adminRoutes(deps) {
     };
   }).get("/api/logs", async ({ request: request2, query }) => {
     await requireReader(request2, deps.admin);
-    return { logs: await recentLogs(deps.store, query.limit) };
+    return pageLogs(deps.store, query);
+  }).get("/api/logs/export", async ({ request: request2, query }) => {
+    await requireReader(request2, deps.admin);
+    const format = query.format === "jsonl" ? "jsonl" : "csv";
+    const rows = exportLogs(deps.store, query);
+    const head = await rows.next();
+    const body2 = new ReadableStream({
+      start(controller) {
+        if (head.done !== true)
+          controller.enqueue(EXPORT_ENCODER.encode(head.value));
+      },
+      async pull(controller) {
+        const next = await rows.next();
+        if (next.done === true)
+          controller.close();
+        else
+          controller.enqueue(EXPORT_ENCODER.encode(next.value));
+      },
+      cancel: (reason) => void rows.return(reason)
+    });
+    return new Response(body2, {
+      headers: {
+        "content-type": EXPORT_CONTENT_TYPE[format],
+        "content-disposition": `attachment; filename="${exportFilename(format, deps.now())}"`,
+        "cache-control": "no-store"
+      }
+    });
   }).get("/api/requests/:id/body", async ({ request: request2, params }) => {
     await requireAdmin(request2, deps.admin);
     return readRequestBody(deps.store, params.id);
@@ -56154,8 +56717,19 @@ function clientRoutes(deps) {
     }, scopeOf({ kind: "client", apiKeyId }));
   }).get("/api/client/logs", async ({ request: request2, query }) => {
     const apiKeyId = await requireClient(request2, deps.admin);
-    const rows = await recentLogs(deps.store, logLimit(query.limit), scopeOf({ kind: "client", apiKeyId }));
-    return { logs: rows.map(toClientLog) };
+    const page = await pageLogs(deps.store, {
+      limit: query.limit,
+      cursor: query.cursor,
+      since: query.since,
+      until: query.until,
+      state: query.state,
+      failed: query.failed,
+      provider: query.provider,
+      requestedModel: query.requestedModel,
+      resolvedModel: query.resolvedModel,
+      errorCode: query.errorCode
+    }, scopeOf({ kind: "client", apiKeyId }));
+    return { logs: page.logs.map(toClientLog), nextCursor: page.nextCursor };
   }).get("/api/client/quota", async ({ request: request2 }) => {
     await requireClient(request2, deps.admin);
     return { accounts: await accountQuota({ store: deps.store, now }) };
@@ -61720,7 +62294,7 @@ function createRing(limits = DEFAULT_RING_LIMITS) {
 }
 
 // apps/gateway/src/version.ts
-var VERSION = "0.11.4";
+var VERSION = "0.12.0";
 
 // apps/gateway/src/app.ts
 var ADMIN_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
@@ -61878,6 +62452,7 @@ function createApp(deps) {
     broadcaster,
     nodeId,
     consoleFleet,
+    ...deps.quota === undefined ? {} : { quota: deps.quota },
     ...deps.console === undefined ? {} : { console: deps.console }
   })).use(clientRoutes({
     store: deps.store,
@@ -62962,12 +63537,13 @@ async function startQuotaPoller(deps) {
   const { quotaPollIntervalMs } = await deps.store.config.getSettings();
   if (quotaPollIntervalMs <= 0)
     return () => {};
+  const quota = deps.quota ?? quotaOps(deps);
   let running = false;
   const pass = () => {
     if (running)
       return;
     running = true;
-    underLease(deps.lease, "quota-poll", 2 * quotaPollIntervalMs, () => poll(deps).then()).catch((error62) => {
+    underLease(deps.lease, "quota-poll", 2 * quotaPollIntervalMs, () => quota.poll().then()).catch((error62) => {
       logger2.error("quota poll failed", {
         reason: describeError(error62, "unknown")
       });
@@ -63591,6 +64167,7 @@ async function main() {
   const coord = shared ?? memoryCoord({ now });
   const lease = { coord, nodeId };
   const refresh = createRefresher({ store, providers: OAUTH_PROVIDERS, http, now, logger: logger2, coord });
+  const quota = quotaOps({ store, coord, providers: OAUTH_PROVIDERS, http, refresh, now, logger: logger2 });
   const staticDir = dashboardDir();
   logger2.info(existsSync2(staticDir) ? "dashboard directory resolved" : "dashboard directory absent", {
     path: staticDir
@@ -63650,6 +64227,7 @@ async function main() {
     http,
     now,
     refresh,
+    quota,
     staticDir,
     logger: logger2,
     console: console2,
@@ -63698,6 +64276,7 @@ async function main() {
     providers: OAUTH_PROVIDERS,
     http,
     refresh,
+    quota,
     now,
     logger: logger2,
     broadcaster