agent-relay-server 0.88.0 → 0.88.2

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.88.0",
+    "version": "0.88.2",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",
@@ -1161,6 +1161,64 @@
         ]
       }
     },
+    "/api/provider-quota-leases/acquire": {
+      "post": {
+        "operationId": "postProviderQuotaPublisherLeaseAcquireRoute",
+        "summary": "Acquire provider quota publisher lease",
+        "tags": [
+          "Agents"
+        ],
+        "description": "Runner-scoped election endpoint. Grants or renews the single publisher lease for one `(provider, accountKey)` when no non-expired holder exists, or returns the current holder and retry delay. The provider token must be allowed to act as the supplied `sourceAgentId`.",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/provider-quota-leases/release": {
+      "post": {
+        "operationId": "postProviderQuotaPublisherLeaseReleaseRoute",
+        "summary": "Release provider quota publisher lease",
+        "tags": [
+          "Agents"
+        ],
+        "description": "Releases a provider quota publisher lease only when `provider`, `accountKey`, `sourceAgentId`, and `leaseToken` all match the current runner holder.",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/orchestrators/{id}/provider-quota-leases/acquire": {
       "post": {
         "operationId": "postProviderQuotaLeaseAcquireRoute",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.88.0",
+  "version": "0.88.2",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.66",
+    "agent-relay-sdk": "0.2.67",
     "ajv": "^8.20.0"
   },
   "scripts": {

package/src/db/provider-quotas.ts

@@ -45,6 +45,10 @@ type ProviderQuotaSnapshotRow = {
   last_error?: string | null;
 };
 
+type StoredQuotaState = QuotaState & {
+  _windowUpdatedAt?: Record<string, number>;
+};
+
 function cleanKey(value: string): string {
   return value.trim();
 }
@@ -185,6 +189,118 @@ function quotaFingerprint(quota: QuotaState): string {
   })).sort((a, b) => a.name.localeCompare(b.name) || a.unit.localeCompare(b.unit)));
 }
 
+function quotaWindowKey(window: QuotaState["windows"][number]): string {
+  return `${window.name}:${window.unit}`;
+}
+
+function publicQuotaState(quota: StoredQuotaState): QuotaState {
+  return {
+    windows: quota.windows.map((window) => ({ ...window })),
+    source: quota.source,
+    updatedAt: quota.updatedAt,
+  };
+}
+
+function parseStoredQuotaState(value: string, fallback: QuotaState): StoredQuotaState {
+  const quota = parseJson<StoredQuotaState>(value, fallback);
+  return {
+    ...publicQuotaState(quota),
+    ...(quota._windowUpdatedAt && typeof quota._windowUpdatedAt === "object" ? { _windowUpdatedAt: quota._windowUpdatedAt } : {}),
+  };
+}
+
+function storedQuotaWindowSampleTimes(quota: StoredQuotaState): Map<string, number> {
+  const times = new Map<string, number>();
+  const rawTimes = quota._windowUpdatedAt && typeof quota._windowUpdatedAt === "object" ? quota._windowUpdatedAt : {};
+  for (const window of quota.windows) {
+    const key = quotaWindowKey(window);
+    const value = rawTimes[key];
+    if (typeof value === "number" && Number.isFinite(value)) times.set(key, value);
+  }
+  return times;
+}
+
+function quotaWithWindowSampleTimes(quota: QuotaState, times: Map<string, number>): StoredQuotaState {
+  const windowUpdatedAt: Record<string, number> = {};
+  for (const window of quota.windows) {
+    const timestamp = times.get(quotaWindowKey(window));
+    if (timestamp !== undefined) windowUpdatedAt[quotaWindowKey(window)] = timestamp;
+  }
+  return Object.keys(windowUpdatedAt).length > 0
+    ? { ...quota, _windowUpdatedAt: windowUpdatedAt }
+    : quota;
+}
+
+function quotaWindowSampleTimes(provider: string, accountKey: string, fallback?: StoredQuotaState): Map<string, number> {
+  const times = new Map<string, number>();
+  const storedTimes = fallback ? storedQuotaWindowSampleTimes(fallback) : new Map<string, number>();
+  for (const [key, timestamp] of storedTimes) times.set(key, timestamp);
+  const rows = getDb().query(`
+    SELECT quota_state FROM quota_snapshots
+    WHERE provider = ? AND account_key = ? AND unavailable = 0
+    ORDER BY captured_at DESC, id DESC
+  `).all(provider, accountKey) as Array<{ quota_state: string }>;
+  for (const row of rows) {
+    const quota = parseJson<QuotaState>(row.quota_state, { windows: [], source: "probe", updatedAt: 0 });
+    for (const window of quota.windows) {
+      const key = quotaWindowKey(window);
+      if (storedTimes.has(key)) continue;
+      times.set(key, Math.max(times.get(key) ?? 0, quota.updatedAt));
+    }
+  }
+  if (fallback) {
+    for (const window of fallback.windows) {
+      const key = quotaWindowKey(window);
+      if (!times.has(key)) times.set(key, fallback.updatedAt);
+    }
+  }
+  return times;
+}
+
+function mergeQuotaWindows(existing: StoredQuotaState | undefined, incoming: QuotaState, provider: string, accountKey: string): {
+  quota: StoredQuotaState;
+  acceptedIncomingWindow: boolean;
+} {
+  if (!existing) {
+    const times = new Map(incoming.windows.map((window) => [quotaWindowKey(window), incoming.updatedAt]));
+    return { quota: quotaWithWindowSampleTimes(incoming, times), acceptedIncomingWindow: true };
+  }
+  const existingTimes = quotaWindowSampleTimes(provider, accountKey, existing);
+  const incomingByKey = new Map(incoming.windows.map((window) => [quotaWindowKey(window), window]));
+  const mergedTimes = new Map<string, number>();
+  let acceptedIncomingWindow = false;
+  let updatedAt = existing.updatedAt;
+  let source = existing.source;
+  const windows = existing.windows.map((window) => {
+    const key = quotaWindowKey(window);
+    const incomingWindow = incomingByKey.get(key);
+    const existingUpdatedAt = existingTimes.get(key) ?? existing.updatedAt;
+    if (!incomingWindow) {
+      mergedTimes.set(key, existingUpdatedAt);
+      return window;
+    }
+    if (incoming.updatedAt < existingUpdatedAt) {
+      mergedTimes.set(key, existingUpdatedAt);
+      return window;
+    }
+    acceptedIncomingWindow = true;
+    updatedAt = Math.max(updatedAt, incoming.updatedAt);
+    source = incoming.source;
+    mergedTimes.set(key, incoming.updatedAt);
+    return incomingWindow;
+  });
+  const existingKeys = new Set(existing.windows.map(quotaWindowKey));
+  for (const window of incoming.windows) {
+    if (existingKeys.has(quotaWindowKey(window))) continue;
+    acceptedIncomingWindow = true;
+    windows.push(window);
+    updatedAt = Math.max(updatedAt, incoming.updatedAt);
+    source = incoming.source;
+    mergedTimes.set(quotaWindowKey(window), incoming.updatedAt);
+  }
+  return { quota: quotaWithWindowSampleTimes({ windows, source, updatedAt }, mergedTimes), acceptedIncomingWindow };
+}
+
 function rowToSnapshot(row: ProviderQuotaSnapshotRow): ProviderQuotaSnapshot {
   const base = {
     provider: row.provider,
@@ -199,14 +315,14 @@ function rowToSnapshot(row: ProviderQuotaSnapshotRow): ProviderQuotaSnapshot {
   }
   return {
     ...base,
-    quota: parseJson<QuotaState>(row.quota_state, { windows: [], source: "probe", updatedAt: row.captured_at }),
+    quota: publicQuotaState(parseStoredQuotaState(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;
-  const quota = row.quota_state ? parseJson<QuotaState>(row.quota_state, { windows: [], source: "probe", updatedAt: lastUpdatedAt ?? row.last_attempt_at }) : undefined;
+  const quota = row.quota_state ? publicQuotaState(parseStoredQuotaState(row.quota_state, { windows: [], source: "probe", updatedAt: lastUpdatedAt ?? row.last_attempt_at })) : undefined;
   return {
     provider: row.provider,
     accountKey: row.account_key,
@@ -263,12 +379,14 @@ export function upsertProviderQuota(input: ProviderQuotaUpdateInput, now = Date.
   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 existingQuota = existing?.quota_state ? parseStoredQuotaState(existing.quota_state, { windows: [], source: "probe", updatedAt: existing.last_updated_at ?? 0 }) : undefined;
+  const mergedQuota = input.quota ? mergeQuotaWindows(existingQuota, input.quota, provider, accountKey) : undefined;
+  const lastUpdatedAt = mergedQuota ? mergedQuota.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;
+  const quotaState = mergedQuota ? JSON.stringify(mergedQuota.quota) : existing?.quota_state ?? null;
 
   getDb().query(`
     INSERT INTO provider_quotas (
@@ -295,19 +413,20 @@ export function upsertProviderQuota(input: ProviderQuotaUpdateInput, now = Date.
     now,
   );
 
-  if (input.quota && latestSnapshotFingerprint(provider, accountKey) !== quotaFingerprint(input.quota)) {
-    recordProviderQuotaSnapshot({ provider, accountKey, quota: input.quota, sourceAgentId: input.sourceAgentId }, now);
+  const snapshotQuota = mergedQuota?.acceptedIncomingWindow ? publicQuotaState(mergedQuota.quota) : undefined;
+  if (snapshotQuota && latestSnapshotFingerprint(provider, accountKey) !== quotaFingerprint(snapshotQuota)) {
+    recordProviderQuotaSnapshot({ provider, accountKey, quota: snapshotQuota, sourceAgentId: input.sourceAgentId }, now);
   } else if (!input.quota && input.lastError?.type === "unavailable" && !latestSnapshotIsUnavailable(provider, accountKey)) {
     // #609 — the provider couldn't be collected (orchestrator skip, #601). Record one explicit gap
     // marker on the transition into unavailable (deduped while it stays unavailable) so history shows
     // an honest gap rather than a silent absence; the next successful poll closes the gap.
     recordProviderQuotaUnavailable({ provider, accountKey, error: input.lastError, sourceAgentId: input.sourceAgentId }, now);
   }
-  if (hasFreshSuccessfulProviderQuota(input, now)) {
+  if (hasFreshSuccessfulProviderQuota(input, now) && mergedQuota?.acceptedIncomingWindow) {
     const quotaAdvisoryState = providerQuotaAdvisoryHandler?.({
       provider,
       accountKey,
-      previousQuota: existing?.quota_state ? parseJson<QuotaState>(existing.quota_state, { windows: [], source: "probe", updatedAt: 0 }) : undefined,
+      previousQuota: existingQuota ? publicQuotaState(existingQuota) : undefined,
       quota: input.quota,
       sourceAgentIds,
       previousAdvisoryState: existing?.quota_advisory_state,

package/src/routes/index.ts

@@ -6,7 +6,7 @@ import { deleteMyAvatar, deleteUserAvatarById, getMe, getUserAvatar, getUsers, h
 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, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, postProviderQuotaRoute } from "./provider-quotas";
+import { getProviderQuotasRoute, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, postProviderQuotaPublisherLeaseAcquireRoute, postProviderQuotaPublisherLeaseReleaseRoute, postProviderQuotaRoute } from "./provider-quotas";
 import { getProviderQuotaConfigRoute, getProviderQuotaConfigsRoute, putProviderQuotaConfigRoute } from "./provider-quota-config";
 import { getTeamsConfigRoute, putTeamsConfigRoute } from "./teams-config";
 import { deleteConfigKey, getConfigKey, getConfigKeyHistory, getConfigNamespace, putConfigKey } from "./config";
@@ -112,6 +112,8 @@ const routes: Route[] = [
   route("POST", "/api/route", postRouteAdvice),
   route("GET", "/api/provider-quotas", getProviderQuotasRoute),
   route("POST", "/api/provider-quotas", postProviderQuotaRoute),
+  route("POST", "/api/provider-quota-leases/acquire", postProviderQuotaPublisherLeaseAcquireRoute),
+  route("POST", "/api/provider-quota-leases/release", postProviderQuotaPublisherLeaseReleaseRoute),
   route("POST", "/api/orchestrators/:id/provider-quota-leases/acquire", postProviderQuotaLeaseAcquireRoute),
   route("POST", "/api/orchestrators/:id/provider-quota-leases/release", postProviderQuotaLeaseReleaseRoute),
   route("GET", "/api/agents/spawn/directories", getHostDirectories),

package/src/routes/provider-quotas.ts

@@ -66,6 +66,56 @@ function cleanLeaseBody(body: unknown): {
   return { provider, accountKey, ...(leaseToken ? { leaseToken } : {}), ttlMs };
 }
 
+function cleanPublisherLeaseBody(body: unknown): {
+  provider: string;
+  accountKey: string;
+  sourceAgentId: string;
+  leaseToken?: string;
+  ttlMs: number;
+} | string {
+  const input = cleanLeaseBody(body);
+  if (typeof input === "string") return input;
+  if (!isRecord(body)) return "JSON object body required";
+  const sourceAgentId = cleanString(body.sourceAgentId, "sourceAgentId", { required: true, max: 200 })!;
+  return { ...input, sourceAgentId };
+}
+
+const runnerLeaseHolderId = (sourceAgentId: string) => `runner:${sourceAgentId}`;
+
+export const postProviderQuotaPublisherLeaseAcquireRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const input = cleanPublisherLeaseBody(parsed.body);
+  if (typeof input === "string") return error(input);
+  const denied = authorizeRoute(req, { scope: "quota:write", resource: { agentId: input.sourceAgentId } });
+  if (denied) return denied;
+  return json(acquireProviderQuotaLease({
+    provider: input.provider,
+    accountKey: input.accountKey,
+    orchestratorId: runnerLeaseHolderId(input.sourceAgentId),
+    leaseToken: input.leaseToken,
+    ttlMs: input.ttlMs,
+  }));
+};
+
+export const postProviderQuotaPublisherLeaseReleaseRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const input = cleanPublisherLeaseBody(parsed.body);
+  if (typeof input === "string") return error(input);
+  if (!input.leaseToken) return error("leaseToken required");
+  const denied = authorizeRoute(req, { scope: "quota:write", resource: { agentId: input.sourceAgentId } });
+  if (denied) return denied;
+  return json({
+    released: releaseProviderQuotaLease({
+      provider: input.provider,
+      accountKey: input.accountKey,
+      orchestratorId: runnerLeaseHolderId(input.sourceAgentId),
+      leaseToken: input.leaseToken,
+    }),
+  });
+};
+
 export const postProviderQuotaLeaseAcquireRoute: Handler = async (req, params) => {
   const orch = getOrchestrator(params.id!);
   if (!orch) return error("orchestrator not found", 404);

package/src/security.ts

@@ -195,6 +195,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/maintenance")) return "system:admin";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
+  if (pathname === "/api/provider-quota-leases/acquire" || pathname === "/api/provider-quota-leases/release") return "quota:write";
+  if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
   if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
@@ -277,6 +279,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-quota-leases/acquire" || pathname === "/api/provider-quota-leases/release") return "quota:write";
   if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
   // Per-provider quota config (#605): reads are agent:read (the orchestrator
   // collector reads its config each tick); writes are settings:write:provider.