omnigateway 0.11.4 → 0.12.0

package/bin/omni.js

@@ -37,6 +37,9 @@ var consoleWriter = {
   err: (line) => {
     process.stderr.write(`${line}
 `);
+  },
+  raw: (chunk) => {
+    process.stdout.write(chunk);
   }
 };
 function paint(ctx, tone, text) {
@@ -20929,6 +20932,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);
@@ -20936,7 +20987,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 });
@@ -21980,6 +22033,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
@@ -22284,6 +22388,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);
@@ -23515,6 +23625,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 },
@@ -23530,7 +23748,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(`
@@ -24031,6 +24252,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;
@@ -24225,6 +24451,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),
@@ -31894,6 +32121,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",
@@ -33012,6 +33246,223 @@ async function setKeyExpiry(store, id, input2, now = Date.now()) {
 async function revokeKey(store, id) {
   await store.keys.revoke(id);
 }
+// packages/control/src/principal.ts
+var ALL = { kind: "all" };
+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 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);
@@ -33170,7 +33621,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"
 });
@@ -33194,7 +33645,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(),
@@ -33762,20 +34213,20 @@ async function removePlugin(deps, root, id, options = {}) {
     throw new GatewayError("BAD_REQUEST", `"${id}" is not a valid plugin id`);
   }
   const target = join3(pluginsDir(root), id);
-  const present = deps.fs.isDirectory(target);
+  const present2 = deps.fs.isDirectory(target);
   const purge = options.purge === true;
   if (purge && deps.store === undefined) {
     throw new GatewayError("INTERNAL", "purging a plugin's data needs a database");
   }
   const tables = purge && deps.store !== undefined ? await deps.store.plugins.listTables(id) : [];
-  if (!present && tables.length === 0) {
+  if (!present2 && tables.length === 0) {
     throw new GatewayError("BAD_REQUEST", `no plugin "${id}" installed under ${pluginsDir(root)}`);
   }
-  if (present)
+  if (present2)
     deps.fs.rm(target);
   if (purge && deps.store !== undefined)
     await deps.store.plugins.dropAll(id);
-  return { id, removed: present, droppedTables: tables };
+  return { id, removed: present2, droppedTables: tables };
 }
 function orphanPluginTables(deps, root, store) {
   const installed = listPlugins(deps, root).map((plugin) => plugin.id);
@@ -34147,6 +34598,8 @@ function registerOAuthProvider(id, provider, registry2 = OAUTH_PROVIDERS) {
   }
   registry2[id] = provider;
 }
+// packages/control/src/oauth/lead.ts
+var SCHEDULER_REFRESH_LEAD_MS = 300000;
 // packages/control/src/oauth/refresh.ts
 var REFRESH_LOCK_MS = 30000;
 function createRefresher(deps) {
@@ -34468,14 +34921,6 @@ async function readPluginProviders(plugins, importer, timeoutMs = PLUGIN_IMPORT_
   }
   return { descriptors: descriptors2, oauth, failures };
 }
-// packages/control/src/principal.ts
-var ALL = { kind: "all" };
-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/history.ts
 var DAY_MS3 = 24 * 60 * 60 * 1000;
 var HOUR_MS3 = 3600000;
@@ -34543,6 +34988,186 @@ async function quotaHistory(deps, input2) {
 
 // packages/control/src/quota/clientHistory.ts
 var MAX_SPAN_MS = 16 * 24 * 60 * 60 * 1000;
+// packages/control/src/quota/poll.ts
+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;
+  const provider = deps.providers[credential.provider];
+  if (provider?.usage === undefined)
+    return null;
+  const refreshed = credential.hasRefreshToken && credential.expiresAt !== null && credential.expiresAt - SCHEDULER_REFRESH_LEAD_MS <= deps.now() ? await deps.refresh(credential) : null;
+  const secrets = refreshed === null ? await credential.openForUsage() : { accessToken: refreshed.accessToken };
+  const report = await provider.usage(secrets, { http: deps.http, now: deps.now }, credential.providerData);
+  if (report === null || report.windows.length === 0)
+    return null;
+  const observedAt = deps.now();
+  const rows = report.windows.map((w) => ({
+    credentialId: credential.id,
+    windowType: w.windowType,
+    startsAt: observedAt,
+    used: w.used,
+    limit: w.limit,
+    resetsAt: w.resetsAt,
+    observedAt,
+    windowMs: w.windowMs
+  }));
+  await deps.store.credentials.saveQuota(rows);
+  (deps.logger ?? noopLogger).debug("quota snapshot written", {
+    provider: credential.provider,
+    credentialId: credential.id,
+    count: rows.length
+  });
+  return rows;
+}
+async function inOrder(items, job) {
+  const results = new Array(items.length).fill(undefined);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      const item = items[index];
+      if (item === undefined)
+        return;
+      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 };
+    }
+  };
+}
 // packages/control/src/settings.ts
 async function getSettings(store) {
   return store.config.getSettings();
@@ -34711,41 +35336,6 @@ function fileExists(path) {
     return false;
   }
 }
-// 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));
-}
 // apps/cli/src/args.ts
 import { parseArgs } from "util";
 class UsageError extends Error {
@@ -36734,6 +37324,66 @@ var quota = {
     });
   }
 };
+var OUTCOME_NOTE = {
+  refreshed: "refreshed",
+  coalesced: "refreshed by a concurrent probe",
+  noData: "provider reported nothing",
+  cooldown: "cooling down after a rate limit",
+  unsupported: "no usage endpoint",
+  disabled: "disabled",
+  failed: "failed"
+};
+function unmet(outcome) {
+  return outcome.kind === "failed" || outcome.kind === "cooldown";
+}
+var quotaRefresh = {
+  usage: "quota refresh <id> | --all",
+  summary: "Read provider quota now, for one account or for every account",
+  options: { all: { type: "boolean" } },
+  async run(args, { ctx, writer }) {
+    const all = args.values.all === true;
+    const id = args.positionals[0];
+    if (all === (id !== undefined)) {
+      throw new UsageError("give an account id or --all, not both");
+    }
+    const store = await ctx.store();
+    const credentials = await listCredentials(store);
+    const wanted = id === undefined ? credentials : credentials.filter((c) => c.id === id);
+    const providers = wanted.every((c) => Object.hasOwn(PROVIDER_DESCRIPTORS, c.provider)) ? OAUTH_PROVIDERS : (await connectRegistryFor(ctx.root.root)).providers;
+    const http = nodeHttpClient();
+    const ops = quotaOps({
+      store,
+      coord: memoryCoord({ now: ctx.now }),
+      providers,
+      http,
+      refresh: createRefresher({ store, providers, http, now: ctx.now }),
+      now: ctx.now
+    });
+    note(ctx, writer, id === undefined ? "refreshing every account\u2026" : `refreshing ${id}\u2026`);
+    const result = await ops.refresh(id === undefined ? { kind: "all" } : { kind: "one", credentialId: id });
+    const labels = new Map(credentials.map((c) => [c.id, c.label]));
+    emit(ctx, writer, result, () => {
+      const rows = result.outcomes.map((outcome) => [
+        `${labels.get(outcome.credentialId) ?? outcome.credentialId}`,
+        OUTCOME_NOTE[outcome.kind],
+        outcome.kind === "refreshed" || outcome.kind === "coalesced" ? `${outcome.windows} window${outcome.windows === 1 ? "" : "s"}` : outcome.kind === "failed" ? outcome.code : dash
+      ]);
+      const refreshed = result.outcomes.filter((o) => o.kind === "refreshed" || o.kind === "coalesced").length;
+      const failed = result.outcomes.filter((o) => o.kind === "failed").length;
+      const skipped = result.outcomes.length - refreshed - failed;
+      return [
+        table([{ header: "ACCOUNT" }, { header: "OUTCOME" }, { header: "DETAIL", align: "right" }], rows),
+        "",
+        `refreshed ${refreshed}; failed ${failed}; skipped ${skipped}`
+      ].join(`
+`);
+    });
+    const bad = result.outcomes.filter(unmet);
+    if (bad.length > 0) {
+      throw new CliError(bad.length === result.outcomes.length ? "quota refresh did not run" : `quota refresh did not run for ${bad.length} of ${result.outcomes.length} accounts`);
+    }
+  }
+};
 
 // apps/cli/src/commands/service.ts
 import { existsSync as existsSync5 } from "fs";
@@ -36824,7 +37474,7 @@ function createServiceDeps(input2) {
 }
 
 // apps/cli/src/version.ts
-var VERSION = "0.11.4";
+var VERSION = "0.12.0";
 
 // apps/cli/src/commands/service.ts
 function gatewayArgv(root) {
@@ -37384,12 +38034,44 @@ var usage = {
     });
   }
 };
+var LOG_FILTER_OPTIONS = {
+  since: { type: "string" },
+  until: { type: "string" },
+  state: { type: "string" },
+  failed: { type: "boolean" },
+  provider: { type: "string" },
+  model: { type: "string" },
+  "requested-model": { type: "string" },
+  "resolved-model": { type: "string" },
+  account: { type: "string" },
+  key: { type: "string" },
+  "error-code": { type: "string" }
+};
+function logFilters(values3) {
+  const since = stringFlag(values3, "since");
+  const until = stringFlag(values3, "until");
+  return {
+    ...since === undefined ? {} : { since: instant(since, 0) },
+    ...until === undefined ? {} : { until: instant(until, 0) },
+    state: stringFlag(values3, "state"),
+    ...boolFlag(values3, "failed") ? { failed: "true" } : {},
+    provider: stringFlag(values3, "provider"),
+    model: stringFlag(values3, "model"),
+    requestedModel: stringFlag(values3, "requested-model"),
+    resolvedModel: stringFlag(values3, "resolved-model"),
+    credentialId: stringFlag(values3, "account"),
+    apiKeyId: stringFlag(values3, "key"),
+    errorCode: stringFlag(values3, "error-code")
+  };
+}
 var logs = {
-  usage: "logs [-n N] [--follow] [--service]",
+  usage: "logs [-n N] [--follow] [--cursor C] [filters] [--service]",
   summary: "Show recent requests (--service is an alias for `omni console`)",
   options: {
+    ...LOG_FILTER_OPTIONS,
     number: { type: "string", short: "n" },
     follow: { type: "boolean" },
+    cursor: { type: "string" },
     service: { type: "boolean" },
     system: { type: "boolean" }
   },
@@ -37401,6 +38083,7 @@ var logs = {
       return;
     }
     const store = await ctx.store();
+    const filters = logFilters(args.values);
     const render2 = (rows) => table([
       { header: "AT" },
       { header: "MODEL" },
@@ -37418,18 +38101,66 @@ var logs = {
       formatUsd(row.costUsd),
       String(row.durationMs)
     ]));
-    const first = await recentLogs(store, limit);
-    emit(ctx, writer, { logs: first }, () => first.length === 0 ? "no requests logged yet" : render2(first));
+    const page = await pageLogs(store, {
+      ...filters,
+      limit,
+      cursor: stringFlag(args.values, "cursor")
+    });
+    const first = page.logs;
+    emit(ctx, writer, { logs: first, nextCursor: page.nextCursor }, () => first.length === 0 ? "no requests match" : page.nextCursor === null ? render2(first) : `${render2(first)}
+${paint(ctx, "dim", `older: --cursor ${page.nextCursor}`)}`);
     if (args.values.follow !== true || ctx.json)
       return;
-    let seen = first[0]?.at ?? 0;
+    let seen = first[0] === undefined ? null : cursorOf(first[0]);
     for (;; ) {
       await Bun.sleep(FOLLOW_INTERVAL_MS);
-      const next = (await recentLogs(store, limit)).filter((row) => row.at > seen);
-      if (next.length === 0)
+      const mark = seen;
+      const { rows, skipped } = await newerThan((cursor) => pageLogs(store, { ...filters, limit, cursor }), mark);
+      if (rows.length === 0)
         continue;
-      seen = next[0]?.at ?? seen;
-      writer.out(render2(next.reverse()));
+      const newest = rows[0];
+      if (newest !== undefined)
+        seen = cursorOf(newest);
+      if (skipped) {
+        writer.out(paint(ctx, "dim", `more than ${FOLLOW_MAX_PAGES * limit} requests arrived since the last poll; older ones are not shown`));
+      }
+      writer.out(render2(rows.reverse()));
+    }
+  }
+};
+var cursorOf = (row) => ({ at: row.at, id: row.id });
+var FOLLOW_MAX_PAGES = 10;
+async function newerThan(read, mark) {
+  const rows = [];
+  let cursor;
+  for (let page = 0;page < FOLLOW_MAX_PAGES; page++) {
+    const got = await read(cursor);
+    if (mark === null)
+      return { rows: got.logs, skipped: false };
+    const fresh = got.logs.filter((row) => isAfter(row, mark));
+    rows.push(...fresh);
+    if (fresh.length < got.logs.length || got.nextCursor === null) {
+      return { rows, skipped: false };
+    }
+    cursor = got.nextCursor;
+  }
+  return { rows, skipped: true };
+}
+var isAfter = (row, seen) => row.at > seen.at || row.at === seen.at && row.id > seen.id;
+var logsExport = {
+  usage: "logs export --since T --until T [--format csv|jsonl] [filters]",
+  summary: "Write matching request metadata to stdout as CSV or JSONL",
+  options: {
+    ...LOG_FILTER_OPTIONS,
+    format: { type: "string" }
+  },
+  async run(args, { ctx, writer }) {
+    const store = await ctx.store();
+    for await (const chunk of exportLogs(store, {
+      ...logFilters(args.values),
+      format: stringFlag(args.values, "format") ?? "csv"
+    })) {
+      writer.raw(chunk);
     }
   }
 };
@@ -37447,6 +38178,7 @@ var COMMANDS = {
   usage,
   quota,
   connect,
+  "logs export": logsExport,
   "service install": serviceInstall,
   "service uninstall": serviceUninstall,
   "credentials list": credentialsList,
@@ -37458,6 +38190,7 @@ var COMMANDS = {
   "credentials refresh": credentialsRefresh,
   "credentials add-key": credentialsAddKey,
   "credentials health": credentialsHealth,
+  "quota refresh": quotaRefresh,
   "models list": modelsList,
   "models show": modelsShow,
   "models put": modelsPut,