agent-relay-server 0.76.0 → 0.77.1

package/src/db/migrations.ts

@@ -17,6 +17,7 @@ import { matchAgents } from "../agent-ref";
 import { getDb } from "./connection.ts";
 import { ensureContinuationArchiveSearchSchema } from "./continuation-archives.ts";
 import { normalizeReactionEmoji } from "./mappers.ts";
+import { normalizeProviderQuotaAccountKeys } from "./provider-quotas.ts";
 import { projectRootsMissingIssueRepo, setProjectIssueRepo } from "./projects.ts";
 import { repoFromGitRemote } from "../services/git-remote.ts";
 import type {
@@ -602,14 +603,105 @@ export function applyMigrations(): void {
   getDb().run(`
     CREATE TABLE IF NOT EXISTS quota_snapshots (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
-      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      provider TEXT NOT NULL,
+      account_key TEXT NOT NULL,
+      agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL,
       windows TEXT NOT NULL,
       source TEXT NOT NULL,
       quota_state TEXT NOT NULL,
       captured_at INTEGER NOT NULL
     )
   `);
+  const quotaSnapshotCols = (getDb().query("PRAGMA table_info(quota_snapshots)").all() as Array<{ name: string }>).map((col) => col.name);
+  if (!quotaSnapshotCols.includes("provider") || !quotaSnapshotCols.includes("account_key")) {
+    getDb().run("ALTER TABLE quota_snapshots RENAME TO quota_snapshots_legacy_agent");
+    getDb().run(`
+      CREATE TABLE quota_snapshots (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        provider TEXT NOT NULL,
+        account_key TEXT NOT NULL,
+        agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL,
+        windows TEXT NOT NULL,
+        source TEXT NOT NULL,
+        quota_state TEXT NOT NULL,
+        captured_at INTEGER NOT NULL
+      )
+    `);
+    getDb().run(`
+      INSERT INTO quota_snapshots (id, provider, account_key, agent_id, windows, source, quota_state, captured_at)
+      SELECT
+        qs.id,
+        CASE
+          WHEN json_extract(a.meta, '$.provider') IS NOT NULL THEN lower(json_extract(a.meta, '$.provider'))
+          WHEN a.tags LIKE '%"codex"%' OR lower(a.id) LIKE '%codex%' OR lower(a.name) LIKE '%codex%' THEN 'codex'
+          ELSE 'claude'
+        END,
+        coalesce(
+          nullif(json_extract(a.meta, '$.accountKey'), ''),
+          nullif(json_extract(a.meta, '$.accountId'), ''),
+          nullif(json_extract(a.meta, '$.orgId'), ''),
+          'host:' || coalesce(a.machine, a.rig, 'unknown')
+        ),
+        qs.agent_id,
+        qs.windows,
+        qs.source,
+        qs.quota_state,
+        qs.captured_at
+      FROM quota_snapshots_legacy_agent qs
+      LEFT JOIN agents a ON a.id = qs.agent_id
+    `);
+    getDb().run("DROP TABLE quota_snapshots_legacy_agent");
+  }
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS provider_quotas (
+      provider TEXT NOT NULL,
+      account_key TEXT NOT NULL,
+      quota_state TEXT,
+      source_agent_ids TEXT NOT NULL DEFAULT '[]',
+      last_updated_at INTEGER,
+      last_attempt_at INTEGER NOT NULL,
+      last_error TEXT,
+      updated_at INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (provider, account_key)
+    )
+  `);
+  getDb().run(`
+    INSERT INTO provider_quotas (
+      provider, account_key, quota_state, source_agent_ids, last_updated_at,
+      last_attempt_at, last_error, updated_at, created_at
+    )
+    SELECT
+      CASE
+        WHEN json_extract(meta, '$.provider') IS NOT NULL THEN lower(json_extract(meta, '$.provider'))
+        WHEN tags LIKE '%"codex"%' OR lower(id) LIKE '%codex%' OR lower(name) LIKE '%codex%' THEN 'codex'
+        ELSE 'claude'
+      END AS provider,
+      coalesce(
+        nullif(json_extract(meta, '$.accountKey'), ''),
+        nullif(json_extract(meta, '$.accountId'), ''),
+        nullif(json_extract(meta, '$.orgId'), ''),
+        'host:' || coalesce(machine, rig, 'unknown')
+      ) AS account_key,
+      quota_state,
+      json_array(id),
+      coalesce(json_extract(quota_state, '$.updatedAt'), last_seen),
+      coalesce(json_extract(quota_state, '$.updatedAt'), last_seen),
+      NULL,
+      last_seen,
+      created_at
+    FROM agents
+    WHERE quota_state IS NOT NULL
+    ON CONFLICT(provider, account_key) DO UPDATE SET
+      quota_state = excluded.quota_state,
+      source_agent_ids = excluded.source_agent_ids,
+      last_updated_at = max(coalesce(provider_quotas.last_updated_at, 0), coalesce(excluded.last_updated_at, 0)),
+      last_attempt_at = max(provider_quotas.last_attempt_at, excluded.last_attempt_at),
+      updated_at = max(provider_quotas.updated_at, excluded.updated_at)
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_quota_snapshots_account_time ON quota_snapshots(provider, account_key, captured_at DESC)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_quota_snapshots_agent_time ON quota_snapshots(agent_id, captured_at DESC)");
+  normalizeProviderQuotaAccountKeys();
 
   getDb().run(`
     CREATE TABLE IF NOT EXISTS memories (

package/src/db/provider-quotas.ts

@@ -0,0 +1,358 @@
+import { DAY_MS } from "../config";
+import { parseJson } from "../utils";
+import { getDb } from "./connection.ts";
+import { parseStringArray } from "./shared.ts";
+import type { AgentCard, ProviderQuotaError, ProviderQuotaMatrix, ProviderQuotaRecord, ProviderQuotaSnapshot, ProviderQuotaUpdateInput, QuotaState } from "../types";
+
+const PROVIDER_QUOTA_STALE_AFTER_MS = 10 * 60_000;
+
+type ProviderQuotaRow = {
+  provider: string;
+  account_key: string;
+  quota_state?: string | null;
+  source_agent_ids?: string | null;
+  last_updated_at?: number | null;
+  last_attempt_at: number;
+  last_error?: string | null;
+  updated_at: number;
+  created_at: number;
+};
+
+type ProviderQuotaSnapshotRow = {
+  provider: string;
+  account_key: string;
+  agent_id?: string | null;
+  quota_state: string;
+  captured_at: number;
+};
+
+function cleanKey(value: string): string {
+  return value.trim();
+}
+
+function normalizeProvider(value: string): string {
+  return cleanKey(value).toLowerCase();
+}
+
+function canonicalProviderQuotaAccountKey(provider: string, value: string): string {
+  const accountKey = cleanKey(value);
+  const legacySuffix = `:${normalizeProvider(provider)}`;
+  return accountKey.startsWith("host:") && accountKey.endsWith(legacySuffix)
+    ? accountKey.slice(0, -legacySuffix.length)
+    : accountKey;
+}
+
+function sourceAgentHost(sourceAgentId: string | undefined): string | undefined {
+  if (!sourceAgentId) return undefined;
+  const row = getDb().query("SELECT machine, rig FROM agents WHERE id = ?").get(sourceAgentId) as { machine?: string | null; rig?: string | null } | undefined;
+  const host = row?.machine ?? row?.rig ?? undefined;
+  return host?.trim() || undefined;
+}
+
+function hostFromAccountKey(accountKey: string): string | undefined {
+  if (!accountKey.startsWith("host:")) return undefined;
+  const host = accountKey.slice("host:".length);
+  return host && !host.includes(":") ? host : undefined;
+}
+
+function normalizeSourceAgentIds(value: unknown): string[] {
+  return [...new Set(parseStringArray(typeof value === "string" ? value : JSON.stringify(value ?? [])).filter(Boolean))];
+}
+
+function quotaRowsForProvider(provider: string): ProviderQuotaRow[] {
+  return getDb().query("SELECT * FROM provider_quotas WHERE provider = ?").all(provider) as ProviderQuotaRow[];
+}
+
+function supersededAccountKeys(provider: string, accountKey: string, rawAccountKey: string, sourceAgentId: string | undefined): string[] {
+  const candidates = new Set<string>();
+  if (rawAccountKey && rawAccountKey !== accountKey) candidates.add(rawAccountKey);
+  const host = hostFromAccountKey(accountKey) ?? sourceAgentHost(sourceAgentId);
+  if (host) {
+    candidates.add(`host:${host}:${provider}`);
+    if (accountKey !== `host:${host}`) candidates.add(`host:${host}`);
+  }
+  if (sourceAgentId) {
+    for (const row of quotaRowsForProvider(provider)) {
+      if (row.account_key === accountKey) continue;
+      if (!normalizeSourceAgentIds(row.source_agent_ids).includes(sourceAgentId)) continue;
+      candidates.add(row.account_key);
+    }
+  }
+  candidates.delete(accountKey);
+  return [...candidates];
+}
+
+function newestQuotaState(rows: ProviderQuotaRow[]): string | null {
+  const row = rows
+    .filter((candidate) => candidate.quota_state)
+    .sort((a, b) => (b.last_updated_at ?? 0) - (a.last_updated_at ?? 0))[0];
+  return row?.quota_state ?? null;
+}
+
+function newestLastError(rows: ProviderQuotaRow[]): string | null {
+  const row = rows
+    .filter((candidate) => candidate.last_error)
+    .sort((a, b) => b.last_attempt_at - a.last_attempt_at)[0];
+  return row?.last_error ?? null;
+}
+
+function mergeProviderQuotaRows(provider: string, accountKey: string, oldAccountKeys: string[], now: number): number {
+  const keys = [...new Set(oldAccountKeys.filter((key) => key && key !== accountKey))];
+  if (keys.length === 0) return 0;
+  const placeholders = [accountKey, ...keys].map(() => "?").join(", ");
+  const rows = getDb().query(`SELECT * FROM provider_quotas WHERE provider = ? AND account_key IN (${placeholders})`).all(provider, accountKey, ...keys) as ProviderQuotaRow[];
+  const oldRows = rows.filter((row) => row.account_key !== accountKey);
+  if (oldRows.length === 0) return 0;
+
+  const sourceAgentIds = [...new Set(rows.flatMap((row) => normalizeSourceAgentIds(row.source_agent_ids)))];
+  const quotaState = newestQuotaState(rows);
+  const lastUpdatedAt = rows.reduce<number | undefined>((latest, row) => {
+    if (row.last_updated_at === null || row.last_updated_at === undefined) return latest;
+    return latest === undefined ? row.last_updated_at : Math.max(latest, row.last_updated_at);
+  }, undefined);
+  const lastAttemptAt = rows.reduce((latest, row) => Math.max(latest, row.last_attempt_at), 0);
+  const updatedAt = Math.max(now, ...rows.map((row) => row.updated_at));
+  const createdAt = Math.min(...rows.map((row) => row.created_at));
+
+  getDb().query(`
+    INSERT INTO provider_quotas (
+      provider, account_key, quota_state, source_agent_ids, last_updated_at,
+      last_attempt_at, last_error, updated_at, created_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(provider, account_key) DO UPDATE SET
+      quota_state = excluded.quota_state,
+      source_agent_ids = excluded.source_agent_ids,
+      last_updated_at = excluded.last_updated_at,
+      last_attempt_at = excluded.last_attempt_at,
+      last_error = excluded.last_error,
+      updated_at = excluded.updated_at
+  `).run(
+    provider,
+    accountKey,
+    quotaState,
+    JSON.stringify(sourceAgentIds),
+    lastUpdatedAt ?? null,
+    lastAttemptAt || now,
+    newestLastError(rows),
+    updatedAt,
+    createdAt,
+  );
+
+  const oldPlaceholders = keys.map(() => "?").join(", ");
+  getDb().query(`UPDATE quota_snapshots SET account_key = ? WHERE provider = ? AND account_key IN (${oldPlaceholders})`).run(accountKey, provider, ...keys);
+  const result = getDb().query(`DELETE FROM provider_quotas WHERE provider = ? AND account_key IN (${oldPlaceholders})`).run(provider, ...keys);
+  return result.changes;
+}
+
+function quotaFingerprint(quota: QuotaState): string {
+  return JSON.stringify(quota.windows.map((window) => ({
+    name: window.name,
+    unit: window.unit,
+    utilization: window.utilization,
+  })).sort((a, b) => a.name.localeCompare(b.name) || a.unit.localeCompare(b.unit)));
+}
+
+function rowToSnapshot(row: ProviderQuotaSnapshotRow): ProviderQuotaSnapshot {
+  return {
+    provider: row.provider,
+    accountKey: row.account_key,
+    capturedAt: row.captured_at,
+    ...(row.agent_id ? { sourceAgentId: row.agent_id } : {}),
+    quota: parseJson<QuotaState>(row.quota_state, { windows: [], source: "probe", updatedAt: row.captured_at }),
+  };
+}
+
+function rowToRecord(row: ProviderQuotaRow, history: ProviderQuotaSnapshot[], now: number): ProviderQuotaRecord {
+  const lastError = parseJson<ProviderQuotaError | undefined>(row.last_error, undefined);
+  const lastUpdatedAt = row.last_updated_at ?? undefined;
+  return {
+    provider: row.provider,
+    accountKey: row.account_key,
+    ...(row.quota_state ? { quota: parseJson<QuotaState>(row.quota_state, { windows: [], source: "probe", updatedAt: lastUpdatedAt ?? row.last_attempt_at }) } : {}),
+    sourceAgentIds: normalizeSourceAgentIds(row.source_agent_ids),
+    ...(lastUpdatedAt !== undefined ? { lastUpdatedAt } : {}),
+    lastAttemptAt: row.last_attempt_at,
+    ...(lastError ? { lastError } : {}),
+    stale: lastUpdatedAt === undefined || now - lastUpdatedAt > PROVIDER_QUOTA_STALE_AFTER_MS,
+    history,
+  };
+}
+
+function latestSnapshotFingerprint(provider: string, accountKey: string): string | undefined {
+  const row = getDb().query(`
+    SELECT quota_state FROM quota_snapshots
+    WHERE provider = ? AND account_key = ?
+    ORDER BY captured_at DESC, id DESC
+    LIMIT 1
+  `).get(provider, accountKey) as { quota_state: string } | undefined;
+  return row ? quotaFingerprint(parseJson<QuotaState>(row.quota_state, { windows: [], source: "probe", updatedAt: 0 })) : undefined;
+}
+
+function providerQuotaIdentityForAgent(agent: Pick<AgentCard, "id" | "name" | "tags" | "machine" | "rig" | "meta">): { provider: string; accountKey: string } {
+  const meta = agent.meta ?? {};
+  const provider = typeof meta.provider === "string" && meta.provider.trim()
+    ? meta.provider
+    : agent.tags.includes("codex") || agent.id.toLowerCase().includes("codex") || agent.name.toLowerCase().includes("codex")
+      ? "codex"
+      : "claude";
+  const accountKey = typeof meta.accountKey === "string" && meta.accountKey.trim()
+    ? meta.accountKey
+    : typeof meta.accountId === "string" && meta.accountId.trim()
+      ? meta.accountId
+      : typeof meta.orgId === "string" && meta.orgId.trim()
+        ? meta.orgId
+        : `host:${agent.machine ?? agent.rig ?? "unknown"}`;
+  return { provider: normalizeProvider(provider), accountKey: cleanKey(accountKey) };
+}
+
+export function upsertProviderQuota(input: ProviderQuotaUpdateInput, now = Date.now()): ProviderQuotaRecord {
+  const provider = normalizeProvider(input.provider);
+  const rawAccountKey = cleanKey(input.accountKey);
+  const accountKey = canonicalProviderQuotaAccountKey(provider, rawAccountKey);
+  if (!provider) throw new Error("provider required");
+  if (!accountKey) throw new Error("accountKey required");
+  mergeProviderQuotaRows(provider, accountKey, supersededAccountKeys(provider, accountKey, rawAccountKey, input.sourceAgentId), now);
+  const existing = getDb().query("SELECT * FROM provider_quotas WHERE provider = ? AND account_key = ?").get(provider, accountKey) as ProviderQuotaRow | undefined;
+  const sourceAgentIds = normalizeSourceAgentIds(existing?.source_agent_ids);
+  if (input.sourceAgentId && !sourceAgentIds.includes(input.sourceAgentId)) sourceAgentIds.push(input.sourceAgentId);
+  const lastUpdatedAt = input.quota ? input.quota.updatedAt : existing?.last_updated_at ?? undefined;
+  const lastAttemptAt = input.lastAttemptAt ?? input.quota?.updatedAt ?? now;
+  const lastError = input.lastError === undefined
+    ? input.quota ? null : existing?.last_error ?? null
+    : input.lastError;
+  const quotaState = input.quota ? JSON.stringify(input.quota) : existing?.quota_state ?? null;
+
+  getDb().query(`
+    INSERT INTO provider_quotas (
+      provider, account_key, quota_state, source_agent_ids, last_updated_at,
+      last_attempt_at, last_error, updated_at, created_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(provider, account_key) DO UPDATE SET
+      quota_state = excluded.quota_state,
+      source_agent_ids = excluded.source_agent_ids,
+      last_updated_at = excluded.last_updated_at,
+      last_attempt_at = excluded.last_attempt_at,
+      last_error = excluded.last_error,
+      updated_at = excluded.updated_at
+  `).run(
+    provider,
+    accountKey,
+    quotaState,
+    JSON.stringify(sourceAgentIds),
+    lastUpdatedAt ?? null,
+    lastAttemptAt,
+    lastError ? JSON.stringify(lastError) : null,
+    now,
+    now,
+  );
+
+  if (input.quota && latestSnapshotFingerprint(provider, accountKey) !== quotaFingerprint(input.quota)) {
+    recordProviderQuotaSnapshot({ provider, accountKey, quota: input.quota, sourceAgentId: input.sourceAgentId }, now);
+  }
+  pruneProviderQuotaRecords(provider, undefined, now - DAY_MS);
+
+  return listProviderQuotas({ provider, accountKey, historyLimit: 24, now }).quotas[0]!;
+}
+
+function recordProviderQuotaSnapshot(input: { provider: string; accountKey: string; quota: QuotaState; sourceAgentId?: string }, now: number): void {
+  const sourceAgentId = input.sourceAgentId && getDb().query("SELECT 1 FROM agents WHERE id = ?").get(input.sourceAgentId)
+    ? input.sourceAgentId
+    : undefined;
+  getDb().query(`
+    INSERT INTO quota_snapshots (provider, account_key, agent_id, windows, source, quota_state, captured_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    input.provider,
+    input.accountKey,
+    sourceAgentId ?? null,
+    JSON.stringify(input.quota.windows),
+    input.quota.source,
+    JSON.stringify(input.quota),
+    now,
+  );
+  pruneProviderQuotaSnapshots(input.provider, input.accountKey, now - DAY_MS);
+}
+
+function pruneProviderQuotaSnapshots(provider?: string, accountKey?: string, olderThan = Date.now() - DAY_MS): number {
+  const result = provider && accountKey
+    ? getDb().query("DELETE FROM quota_snapshots WHERE provider = ? AND account_key = ? AND captured_at < ?").run(provider, accountKey, olderThan)
+    : getDb().query("DELETE FROM quota_snapshots WHERE captured_at < ?").run(olderThan);
+  return result.changes;
+}
+
+function pruneProviderQuotaRecords(provider?: string, accountKey?: string, olderThan = Date.now() - DAY_MS): number {
+  const result = provider && accountKey
+    ? getDb().query("DELETE FROM provider_quotas WHERE provider = ? AND account_key = ? AND updated_at < ?").run(provider, accountKey, olderThan)
+    : provider
+      ? getDb().query("DELETE FROM provider_quotas WHERE provider = ? AND updated_at < ?").run(provider, olderThan)
+      : getDb().query("DELETE FROM provider_quotas WHERE updated_at < ?").run(olderThan);
+  return result.changes;
+}
+
+export function normalizeProviderQuotaAccountKeys(now = Date.now()): number {
+  let changes = 0;
+  for (const row of getDb().query("SELECT * FROM provider_quotas").all() as ProviderQuotaRow[]) {
+    let accountKey = canonicalProviderQuotaAccountKey(row.provider, row.account_key);
+    if (accountKey.startsWith("credential:")) {
+      const sourceAgentId = normalizeSourceAgentIds(row.source_agent_ids)[0];
+      const host = sourceAgentHost(sourceAgentId);
+      if (host) accountKey = `host:${host}`;
+    }
+    if (accountKey !== row.account_key) {
+      changes += mergeProviderQuotaRows(row.provider, accountKey, [row.account_key], now);
+    }
+  }
+  changes += pruneProviderQuotaRecords(undefined, undefined, now - DAY_MS);
+  return changes;
+}
+
+function listProviderQuotaSnapshots(provider: string, accountKey: string, options: { since?: number; limit?: number } = {}): ProviderQuotaSnapshot[] {
+  const limit = Math.max(1, Math.min(options.limit ?? 288, 1000));
+  const params: any[] = [normalizeProvider(provider), cleanKey(accountKey)];
+  let sql = "SELECT * FROM quota_snapshots WHERE provider = ? AND account_key = ?";
+  if (options.since !== undefined) {
+    sql += " AND captured_at >= ?";
+    params.push(options.since);
+  }
+  sql += " ORDER BY captured_at ASC, id ASC LIMIT ?";
+  params.push(limit);
+  return (getDb().query(sql).all(...params) as ProviderQuotaSnapshotRow[]).map(rowToSnapshot);
+}
+
+export function listAgentQuotaSnapshotsFromProviderStore(agent: AgentCard, options: { since?: number; limit?: number } = {}) {
+  const identity = providerQuotaIdentityForAgent(agent);
+  return listProviderQuotaSnapshots(identity.provider, identity.accountKey, options).map((snapshot) => ({
+    agentId: agent.id,
+    capturedAt: snapshot.capturedAt,
+    windows: snapshot.quota.windows,
+    source: snapshot.quota.source,
+    updatedAt: snapshot.quota.updatedAt,
+  }));
+}
+
+export function listProviderQuotas(options: { provider?: string; accountKey?: string; since?: number; historyLimit?: number; now?: number } = {}): ProviderQuotaMatrix {
+  const historyLimit = Math.max(0, Math.min(options.historyLimit ?? 24, 288));
+  const now = options.now ?? Date.now();
+  const params: any[] = [];
+  let sql = "SELECT * FROM provider_quotas WHERE 1=1";
+  if (options.provider) {
+    sql += " AND provider = ?";
+    params.push(normalizeProvider(options.provider));
+  }
+  if (options.accountKey) {
+    sql += " AND account_key = ?";
+    params.push(cleanKey(options.accountKey));
+  }
+  sql += " ORDER BY provider ASC, account_key ASC";
+  const rows = getDb().query(sql).all(...params) as ProviderQuotaRow[];
+  return {
+    staleAfterMs: PROVIDER_QUOTA_STALE_AFTER_MS,
+    quotas: rows.map((row) => rowToRecord(
+      row,
+      historyLimit > 0 ? listProviderQuotaSnapshots(row.provider, row.account_key, { since: options.since, limit: historyLimit }) : [],
+      now,
+    )),
+  };
+}

package/src/db/schema.ts

@@ -292,7 +292,9 @@ export function initDb(path: string = "agent-relay.db"): Database {
 
     CREATE TABLE IF NOT EXISTS quota_snapshots (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
-      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      provider TEXT NOT NULL,
+      account_key TEXT NOT NULL,
+      agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL,
       windows TEXT NOT NULL,
       source TEXT NOT NULL,
       quota_state TEXT NOT NULL,
@@ -300,6 +302,19 @@ export function initDb(path: string = "agent-relay.db"): Database {
     );
     CREATE INDEX IF NOT EXISTS idx_quota_snapshots_agent_time ON quota_snapshots(agent_id, captured_at DESC);
 
+    CREATE TABLE IF NOT EXISTS provider_quotas (
+      provider TEXT NOT NULL,
+      account_key TEXT NOT NULL,
+      quota_state TEXT,
+      source_agent_ids TEXT NOT NULL DEFAULT '[]',
+      last_updated_at INTEGER,
+      last_attempt_at INTEGER NOT NULL,
+      last_error TEXT,
+      updated_at INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (provider, account_key)
+    );
+
     CREATE TABLE IF NOT EXISTS agent_continuations (
       agent_id TEXT PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
       objective TEXT NOT NULL,

package/src/quota.ts

@@ -1,5 +1,5 @@
 import { isRecord } from "agent-relay-sdk";
-import type { QuotaState, QuotaWindowName, QuotaSource, QuotaUnit } from "./types";
+import type { ProviderQuotaError, QuotaState, QuotaWindowName, QuotaSource, QuotaUnit } from "./types";
 
 const QUOTA_SOURCES = new Set<QuotaSource>(["header", "probe", "ingest"]);
 const QUOTA_UNITS = new Set<QuotaUnit>(["tokens", "requests", "%"]);
@@ -38,3 +38,16 @@ export function quotaStateFromUnknown(value: unknown): QuotaState | undefined {
   if (windows.length === 0) return undefined;
   return { windows, source, updatedAt };
 }
+
+export function providerQuotaErrorFromUnknown(value: unknown): ProviderQuotaError | undefined {
+  if (!isRecord(value)) return undefined;
+  const type = typeof value.type === "string" && value.type.trim() ? value.type.trim() : undefined;
+  const message = typeof value.message === "string" && value.message.trim() ? value.message.trim() : undefined;
+  if (!type || !message) return undefined;
+  const retryAfterMs = numberValue(value.retryAfterMs);
+  return {
+    type,
+    message,
+    ...(retryAfterMs !== undefined && retryAfterMs >= 0 ? { retryAfterMs } : {}),
+  };
+}

package/src/routes/index.ts

@@ -5,6 +5,7 @@ import { deleteAgentTerminalSession, postAgentAction, postAgentPermissionDecisio
 import { deleteArtifactById, getArtifactById, getArtifactContent, getArtifacts, headArtifactContent, postArtifact } from "./artifacts";
 import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomations, patchAutomation, postAutomation, postAutomationRun } from "./automations";
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
+import { getProviderQuotasRoute, postProviderQuotaRoute } from "./provider-quotas";
 import { deleteConfigKey, getConfigKey, getConfigKeyHistory, getConfigNamespace, putConfigKey } from "./config";
 import { deleteInboxDraftRoute, getChatHistoryImportsRoute, getInboxStateRoute, patchInboxThreadState, postChatHistoryImportRoute, putInboxDraft } from "./inbox";
 import { deleteMemoryRoute, getMemories, getMemoryBrokerInfo, getMemoryById, getMemoryStats, patchMemory, postMemory, postMemoryInject, postMemorySearch } from "./memory";
@@ -87,6 +88,8 @@ const routes: Route[] = [
   route("GET", "/api/agents", getAgents),
   route("GET", "/api/agents/find", findAgents),
   route("POST", "/api/route", postRouteAdvice),
+  route("GET", "/api/provider-quotas", getProviderQuotasRoute),
+  route("POST", "/api/provider-quotas", postProviderQuotaRoute),
   route("GET", "/api/agents/spawn/directories", getHostDirectories),
   route("GET", "/api/agents/:id/chat", getAgentChatHistory),
   route("GET", "/api/agents/:id/context-snapshots", getAgentContextSnapshots),

package/src/routes/provider-quotas.ts

@@ -0,0 +1,48 @@
+import { isRecord } from "agent-relay-sdk";
+import { listProviderQuotas, upsertProviderQuota } from "../db";
+import { quotaStateFromUnknown, providerQuotaErrorFromUnknown } from "../quota";
+import { cleanString } from "../validation";
+import { error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
+import type { ProviderQuotaUpdateInput } from "../types";
+
+function cleanProviderQuotaUpdate(body: unknown): ProviderQuotaUpdateInput | string {
+  if (!isRecord(body)) return "JSON object body required";
+  const provider = cleanString(body.provider, "provider", { required: true, max: 80 })!;
+  const accountKey = cleanString(body.accountKey, "accountKey", { required: true, max: 240 })!;
+  const quota = quotaStateFromUnknown(body.quota);
+  const lastAttemptAt = typeof body.lastAttemptAt === "number" && Number.isFinite(body.lastAttemptAt) ? body.lastAttemptAt : undefined;
+  const lastError = body.lastError === null ? null : providerQuotaErrorFromUnknown(body.lastError);
+  if (!quota && lastError === undefined) return "quota or lastError required";
+  const sourceAgentId = cleanString(body.sourceAgentId, "sourceAgentId", { max: 200 });
+  return {
+    provider,
+    accountKey,
+    ...(quota ? { quota } : {}),
+    ...(lastAttemptAt !== undefined ? { lastAttemptAt } : {}),
+    ...(lastError !== undefined ? { lastError } : {}),
+    ...(sourceAgentId ? { sourceAgentId } : {}),
+  };
+}
+
+export const getProviderQuotasRoute: Handler = (req) => {
+  const url = new URL(req.url);
+  const historyLimit = parseQueryInt(url.searchParams.get("historyLimit") ?? url.searchParams.get("limit"), { min: 0, max: 288, clamp: true });
+  if (Number.isNaN(historyLimit)) return error("historyLimit must be an integer between 0 and 288");
+  const sinceRaw = url.searchParams.get("since");
+  const since = sinceRaw ? Number(sinceRaw) : undefined;
+  if (sinceRaw && (!Number.isFinite(since) || since! < 0)) return error("since must be a positive timestamp");
+  return json(listProviderQuotas({
+    provider: url.searchParams.get("provider") ?? undefined,
+    accountKey: url.searchParams.get("accountKey") ?? undefined,
+    since,
+    historyLimit: historyLimit ?? undefined,
+  }));
+};
+
+export const postProviderQuotaRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const input = cleanProviderQuotaUpdate(parsed.body);
+  if (typeof input === "string") return error(input);
+  return json(upsertProviderQuota(input), 201);
+};

package/src/security.ts

@@ -274,6 +274,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   // Spawn requires the spawn capability (see requiredScopeFor above) — matches the in-service gate.
   if (pathname === "/api/agents/spawn") return "command:spawn";
   if (pathname.startsWith("/api/agents")) return method === "GET" ? "agent:read" : "agent:write";
+  if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
   if (pathname.startsWith("/api/messages") || pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";

package/src/token-db.ts

@@ -78,7 +78,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Agent",
     description: "Coding-agent runtime access for messages, commands, tasks, and scoped memory reads.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
     ttlSeconds: 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -88,7 +88,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Child Agent",
     description: "Delegated child-agent runtime access, constrained to its parent and spawn request.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
     constraints: { canDelegate: false },
     ttlSeconds: 2 * 60 * 60,
     builtIn: true,
@@ -99,7 +99,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Interactive Agent",
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,