cartethyia 2.7.3 → 2.7.5

package/src/console/providers/catalog/contracts.ts

@@ -123,42 +123,42 @@ const ADAPTER_OWNED: Record<string, true> = {
 export function validateCompatibilityProfile(profile: CompatibilityProfile): void {
   if (profile.cli_identity !== undefined) {
     if (typeof profile.cli_identity !== "boolean") {
-      throw new GatewayError("invalid_request", 400, "cli_identity must be boolean");
+      throw new GatewayError("invalid_request", 400, "cli_identity must be boolean (request {requestId}). Check the shape of what you sent — then resend 🪞");
     }
   }
   if (profile.gateway_user_agent !== undefined) {
     if (typeof profile.gateway_user_agent !== "boolean") {
-      throw new GatewayError("invalid_request", 400, "gateway_user_agent must be boolean");
+      throw new GatewayError("invalid_request", 400, "gateway_user_agent must be boolean (request {requestId}). Check the shape of what you sent — then resend 🪞");
     }
   }
   if (profile.extra_headers) {
     for (const [rawName, rawValue] of Object.entries(profile.extra_headers)) {
       const name = rawName.toLowerCase();
       if (name.length < 1 || name.length > 64 || !TOKEN_REGEX.test(name)) {
-        throw new GatewayError("invalid_request", 400, `invalid header name ${rawName}`);
+        throw new GatewayError("invalid_request", 400, `invalid header name ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`);
       }
       if (isProtectedHeader(name, ADAPTER_OWNED)) {
         throw new GatewayError(
           "invalid_request",
           400,
-          `header ${rawName} is not allowed as custom header`,
+          `header ${rawName} is not allowed as custom header (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
       if (typeof rawValue !== "string") {
         throw new GatewayError(
           "invalid_request",
           400,
-          `header value for ${rawName} must be string`,
+          `header value for ${rawName} must be string (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
       if (Buffer.byteLength(rawValue, "utf8") > 4096) {
-        throw new GatewayError("invalid_request", 400, `header value for ${rawName} exceeds 4KiB`);
+        throw new GatewayError("invalid_request", 400, `header value for ${rawName} exceeds 4KiB (request {requestId}). We love long reads, but not that long 📚`);
       }
       if (/[\r\n\x00-\x1f\x7f]/.test(rawValue)) {
         throw new GatewayError(
           "invalid_request",
           400,
-          `header value for ${rawName} contains control characters`,
+          `header value for ${rawName} contains control characters (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
     }
@@ -166,9 +166,9 @@ export function validateCompatibilityProfile(profile: CompatibilityProfile): voi
   if (profile.extra_query_params) {
     for (const [k, v] of Object.entries(profile.extra_query_params)) {
       if (typeof v !== "string")
-        throw new GatewayError("invalid_request", 400, `query param ${k} must be string`);
+        throw new GatewayError("invalid_request", 400, `query param ${k} must be string (request {requestId}). Check the shape of what you sent — then resend 🪞`);
       if (/[\r\n]/.test(k) || /[\r\n]/.test(v))
-        throw new GatewayError("invalid_request", 400, `query param contains CRLF`);
+        throw new GatewayError("invalid_request", 400, `query param contains CRLF (request {requestId}). Check the shape of what you sent — then resend 🪞`);
     }
   }
   if (profile.endpoint_paths_by_wire_family) {
@@ -177,56 +177,56 @@ export function validateCompatibilityProfile(profile: CompatibilityProfile): voi
         throw new GatewayError(
           "invalid_request",
           400,
-          `endpoint_paths_by_wire_family: unknown wire family ${wf}`,
+          `endpoint_paths_by_wire_family: unknown wire family ${wf} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
       if (typeof path !== "string") {
         throw new GatewayError(
           "invalid_request",
           400,
-          `endpoint_paths_by_wire_family.${wf} must be string`,
+          `endpoint_paths_by_wire_family.${wf} must be string (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
       if (path.length === 0 || path.length > 256) {
         throw new GatewayError(
           "invalid_request",
           400,
-          `endpoint_paths_by_wire_family.${wf} path length must be 1-256 chars`,
+          `endpoint_paths_by_wire_family.${wf} path length must be 1-256 chars (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
       if (!path.startsWith("/")) {
         throw new GatewayError(
           "invalid_request",
           400,
-          `endpoint_paths_by_wire_family.${wf} path must start with /`,
+          `endpoint_paths_by_wire_family.${wf} path must start with / (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
       if (/[\s\r\n\x00-\x1f\x7f]/.test(path)) {
         throw new GatewayError(
           "invalid_request",
           400,
-          `endpoint_paths_by_wire_family.${wf} path contains invalid characters`,
+          `endpoint_paths_by_wire_family.${wf} path contains invalid characters (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
     }
   }
   if (profile.model_wire_families) {
     if (!Array.isArray(profile.model_wire_families)) {
-      throw new GatewayError("invalid_request", 400, "model_wire_families must be an array");
+      throw new GatewayError("invalid_request", 400, "model_wire_families must be an array (request {requestId}). Check the shape of what you sent — then resend 🪞");
     }
     for (const rule of profile.model_wire_families) {
       if (typeof rule?.pattern !== "string" || rule.pattern.length === 0) {
         throw new GatewayError(
           "invalid_request",
           400,
-          "model_wire_families[].pattern must be a non-empty string",
+          "model_wire_families[].pattern must be a non-empty string (request {requestId}). Check the shape of what you sent — then resend 🪞",
         );
       }
       if (rule.pattern.length > 256) {
         throw new GatewayError(
           "invalid_request",
           400,
-          "model_wire_families[].pattern must be at most 256 chars",
+          "model_wire_families[].pattern must be at most 256 chars (request {requestId}). Check the shape of what you sent — then resend 🪞",
         );
       }
       try {
@@ -235,14 +235,14 @@ export function validateCompatibilityProfile(profile: CompatibilityProfile): voi
         throw new GatewayError(
           "invalid_request",
           400,
-          `model_wire_families[].pattern ${rule.pattern} is not a valid regular expression`,
+          `model_wire_families[].pattern ${rule.pattern} is not a valid regular expression (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
       if (!isWireFamily(rule.wire_family)) {
         throw new GatewayError(
           "invalid_request",
           400,
-          `model_wire_families[].wire_family: unknown wire family ${String(rule.wire_family)}`,
+          `model_wire_families[].wire_family: unknown wire family ${String(rule.wire_family)} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         );
       }
     }
@@ -251,10 +251,10 @@ export function validateCompatibilityProfile(profile: CompatibilityProfile): voi
     profile.streaming_usage_mode &&
     !["include_usage", "none"].includes(profile.streaming_usage_mode)
   ) {
-    throw new GatewayError("invalid_request", 400, "invalid streaming_usage_mode");
+    throw new GatewayError("invalid_request", 400, "invalid streaming_usage_mode (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   if (profile.structured_output && typeof profile.structured_output.enabled !== "boolean") {
-    throw new GatewayError("invalid_request", 400, "structured_output.enabled must be boolean");
+    throw new GatewayError("invalid_request", 400, "structured_output.enabled must be boolean (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   // If any field is present but has no runtime reader, our current reader set covers all fields above.
   const allowed: Record<string, true> = {
@@ -281,7 +281,7 @@ export function validateCompatibilityProfile(profile: CompatibilityProfile): voi
       throw new GatewayError(
         "invalid_request",
         400,
-        `unknown compatibility_profile field ${k} has no runtime reader`,
+        `unknown compatibility_profile field ${k} has no runtime reader (request {requestId}). Check the shape of what you sent — then resend 🪞`,
       );
     }
   }
@@ -508,6 +508,13 @@ export interface ProviderAccountResponse {
   label: string;
   credentialKind: CredentialKind;
   credentialMode?: CredentialMode;
+  /**
+   * Which sign-in family issued this credential, read from the account's
+   * `auth_state` (e.g. `social`/`oidc`/`api_key` for Kiro). Surfaced so the
+   * console can badge an account by how it logged in without shipping the
+   * whole auth state to the browser.
+   */
+  authMethod?: string;
   tokenExpiresAt?: string;
   /**
    * Who issued this credential, read from the JWT `iss` claim at registration
@@ -539,6 +546,27 @@ export interface ProviderAccountResponse {
   staticToken?: boolean;
   /** Stable list position within this provider; the console's "Added" order. */
   sortIndex: number;
+  /**
+   * Row flavor. `"pool"` marks a pool-as-account entity (see
+   * `provider_pool_accounts`): it is an account-equivalent for an
+   * ip-scoped, credential-less provider, resolves no credential, and is
+   * owned by its pool. Absent means a real `provider_accounts` row.
+   */
+  kind?: "pool";
+  /** The owning pool row (present for `kind: "pool"`). */
+  networkPoolId?: string;
+  /**
+   * Provider-scoped rate-limit markers on the owning pool, when this is a
+   * pool-as-account row. Mirrors `NetworkPoolResponse.providerCooldowns`: a
+   * 429 cooldown refills, a block means the upstream retired the egress
+   * address. Absent for real accounts and for pools with no markers.
+   */
+  providerCooldowns?: Array<{
+    providerId: string;
+    until: string;
+    reason: string;
+    blocked: boolean;
+  }>;
 }
 /**
  * Plaintext export of one account's decrypted provider tokens.
@@ -632,6 +660,18 @@ export interface ProviderResponse {
   isBuiltIn: boolean;
   /** True when this tenant has any persisted account for the provider. */
   configured?: boolean;
+  /**
+   * Number of provider accounts this tenant has for the provider. Present on
+   * list items (the Providers page overview); absent elsewhere.
+   */
+  accountCount?: number;
+  /**
+   * Accounts whose status is not disabled/revoked — an account parked by the
+   * health machine (`cooldown`) still counts. Present on list items.
+   */
+  activeAccountCount?: number;
+  /** Enabled model rows the tenant can see for the provider. Present on list items. */
+  modelCount?: number;
   /** `false` only for a genuinely credential-less provider (OpenCode Free) —
    * the dashboard hides account creation for it since none is usable. */
   requiresAccount: boolean;
@@ -779,6 +819,26 @@ export interface ProviderCatalogStore {
   syncModels(tenantId: string, providerId: string): Promise<{ synced: number }>;
   listAccounts(tenantId: string, providerId: string): Promise<readonly ProviderAccountResponse[]>;
   listAllAccounts(tenantId: string): Promise<readonly ProviderAccountResponse[]>;
+  /**
+   * Provider-id + status only, for every account the tenant can see. Much
+   * cheaper than `listAllAccounts` (which also fetches today/lifetime usage,
+   * inflight, pool rows): used by the provider list's "configured" marker and
+   * the flat model picker's active-account counts, neither of which reads
+   * usage.
+   */
+  listAllAccountSummaries(tenantId: string): Promise<readonly { providerId: string; status: string }[]>;
+  /**
+   * Per-provider account totals for the tenant, from one grouped read. Used by
+   * the provider list overview (`accountCount` / `activeAccountCount`).
+   */
+  providerAccountCounts(
+    tenantId: string,
+  ): Promise<readonly { providerId: string; total: number; active: number }[]>;
+  /**
+   * Per-provider enabled model-row counts for the tenant, from one grouped read.
+   * Used by the provider list overview (`modelCount`).
+   */
+  providerModelCounts(tenantId: string): Promise<readonly { providerId: string; count: number }[]>;
   /**
    * Non-secret upstream auth configuration for the given owned accounts,
    * keyed by account id. Used by the account-export route so a re-import can

package/src/console/providers/catalog/model-operations.ts

@@ -62,7 +62,7 @@ export function createModelCatalogOperations(config: ProviderCatalogConfig) {
       const a = requireTenantAnyScope(access, MODEL_READ_SCOPES);
       const [providers, allAccounts] = await Promise.all([
         config.store.list(a.tenantId),
-        config.store.listAllAccounts(a.tenantId),
+        config.store.listAllAccountSummaries(a.tenantId),
       ]);
       const accountsByProvider = new Map<string, number>();
       for (const account of allAccounts) {

package/src/console/providers/catalog/provider-operations.ts

@@ -16,6 +16,8 @@ import {
   requireGlobalAdmin,
   requireTenantAnyScope,
 } from "../../shared/errors";
+import { cachedReadWithEtag, conditionalResponse } from "../../shared/read-through-cache";
+import type { RedisClient } from "../../../persistence/redis";
 import type { AccessDecision } from "../../../security/access-control";
 import type { ProviderUsageDayRow } from "../../../observability/event-query";
 import { isBundledProviderId } from "../../../providers/provider-contracts";
@@ -128,7 +130,22 @@ export interface ProviderCatalogConfig {
   readonly auditSink?: AuditSink;
   /** Registry-backed OAuth login clients; used to compute `oauthFlows` on responses. */
   readonly providerRegistry: ProviderRegistry;
-  readonly snapshotInvalidator?: { invalidate(): Promise<number> };
+  /**
+   * Shared Redis client for the provider-list read-through cache. Omitted in
+   * lite mode / tests, where `cachedReadWithEtag` falls back to its bounded
+   * in-process TTL store; the ETag/304 semantics are identical either way.
+   */
+  readonly redis?: RedisClient | undefined;
+  /**
+   * Drops the cached route snapshot after a catalog write. `currentRevision`
+   * (when the host exposes it) is folded into the provider-list cache key, so
+   * every mutation that already bumps the snapshot — provider, account, and
+   * model writes — rotates the cached overview without a per-path delete.
+   */
+  readonly snapshotInvalidator?: {
+    invalidate(): Promise<number>;
+    currentRevision?(): number;
+  };
   /**
    * Re-applies one provider's BYOK adapter registration after a create/update
    * so a custom provider is dispatchable without a restart. Optional: tests
@@ -232,23 +249,81 @@ function toProviderLoginField(field: OAuthLoginField): ProviderLoginField {
       : { options: field.options.map((option) => ({ value: option.value, label: option.label })) }),
   };
 }
+/** Provider-list cache TTL: short enough that a 60s poll re-checks the DB
+ * occasionally, long enough that a warm page does zero per-card work. */
+const PROVIDER_LIST_CACHE_TTL_SECONDS = 20;
+
+/** Cache key namespace + shape version for the provider-list overview. */
+const PROVIDER_LIST_CACHE_SHAPE = "providers:v1:list";
+
+/** Version of the read-through cache backend, so a bump is a key rotation. */
+const PROVIDER_LIST_CACHE_REVISION = 1;
+
+/** The list projection shared by `listProviders` and its cached wrapper. */
+async function computeProviderList(
+  config: ProviderCatalogConfig,
+  tenantId: string,
+): Promise<ProviderResponse[]> {
+  const [records, accountCounts, modelCounts] = await Promise.all([
+    config.store.list(tenantId),
+    config.store.providerAccountCounts(tenantId),
+    config.store.providerModelCounts(tenantId),
+  ]);
+  const accountsByProvider = new Map(accountCounts.map((row) => [row.providerId, row]));
+  const modelsByProvider = new Map(modelCounts.map((row) => [row.providerId, row.count]));
+  return Promise.all(
+    records.map((r) => {
+      const counts = accountsByProvider.get(r.providerId);
+      return attachProviderCapabilities(
+        {
+          ...sanitizeProviderResponse(r),
+          // A provider with no persisted accounts is not "configured"; the
+          // count fields are still present (zero) so the card renders the
+          // empty state instead of a loading placeholder.
+          configured: counts !== undefined,
+          accountCount: counts?.total ?? 0,
+          activeAccountCount: counts?.active ?? 0,
+          modelCount: modelsByProvider.get(r.providerId) ?? 0,
+        },
+        config.providerRegistry,
+      );
+    }),
+  );
+}
+
 export function createProviderCatalogOperations(config: ProviderCatalogConfig) {
   const operations = {
     async listProviders(access: AccessDecision | undefined): Promise<ProviderResponse[]> {
       const a = requireTenantAnyScope(access, PROVIDER_READ_SCOPES);
-      const [records, accounts] = await Promise.all([
-        config.store.list(a.tenantId),
-        config.store.listAllAccounts(a.tenantId),
-      ]);
-      const configured = new Set(accounts.map((account) => account.providerId));
-      return Promise.all(
-        records.map((r) =>
-          attachProviderCapabilities(
-            { ...sanitizeProviderResponse(r), configured: configured.has(r.providerId) },
-            config.providerRegistry,
-          ),
-        ),
+      return computeProviderList(config, a.tenantId);
+    },
+    /**
+     * The full provider list with overview counts, served through the
+     * read-through cache (P-04). A repeated poll answers `304` with the ETag
+     * instead of recomputing the two grouped count queries.
+     *
+     * Returning a `Response` rather than a plain array is what makes the ETag
+     * conditional branch possible: a `304` has no body to serialize. The cache
+     * key is tenant-scoped and carries the routing revision, so a provider /
+     * account / model mutation that bumps the snapshot rotates the key and the
+     * next read recomputes fresh counts.
+     */
+    async listProvidersCached(
+      access: AccessDecision | undefined,
+      ifNoneMatch: string | null,
+    ): Promise<Response> {
+      const a = requireTenantAnyScope(access, PROVIDER_READ_SCOPES);
+      const revision = config.snapshotInvalidator?.currentRevision?.() ?? 0;
+      const key =
+        `cartethyia:${PROVIDER_LIST_CACHE_SHAPE}:v${PROVIDER_LIST_CACHE_REVISION}:` +
+        `${a.tenantId}:${revision}`;
+      const result = await cachedReadWithEtag(
+        config.redis,
+        key,
+        () => computeProviderList(config, a.tenantId),
+        PROVIDER_LIST_CACHE_TTL_SECONDS,
       );
+      return conditionalResponse(ifNoneMatch, result, result.value);
     },
     async getProviderDetail(
         access: AccessDecision | undefined,
@@ -693,12 +768,30 @@ export function createProviderCatalogOperations(config: ProviderCatalogConfig) {
               // Non-secret auth state is part of the credential export: without
               // it a re-import loses the upstream user id and region that Trae
               // refresh and dispatch are addressed by.
-              ...(() => {
+              ...(await (async () => {
                 const authState = authStates[account.id];
-                return authState !== undefined && Object.keys(authState).length > 0
-                  ? { authState }
+                // Buddy providers bind a per-account device identity
+                // (qimei36) that is normally derived from the INTERNAL account
+                // id. Export must materialize that raw binding into the
+                // exported auth state — otherwise a re-import mints a new
+                // account id, the derived binding changes, and the upstream
+                // channel check (11128) rejects the imported account.
+                const materialized =
+                  account.providerId === "cb" ||
+                  account.providerId === "cbcn" ||
+                  account.providerId === "workbuddy" ||
+                  account.providerId === "workbuddycn"
+                    // dynamic-import: B-02 lazy graph — buddy device-binding materializer, buddy-family only.
+                    // The buddy-identity graph is lazy-loaded: the device-binding
+                    // materializer only runs for buddy-family accounts (B-02).
+                    ? (await import("../../../providers/integrations/buddy/buddy-identity"))
+                        .materializeBuddyDeviceBinding(account.id, authState)
+                    : undefined;
+                const effectiveAuthState = materialized ?? authState;
+                return effectiveAuthState !== undefined && Object.keys(effectiveAuthState).length > 0
+                  ? { authState: effectiveAuthState }
                   : {};
-              })(),
+              })()),
               ...(account.inflight === undefined ? {} : { inflight: account.inflight }),
               createdAt: account.createdAt,
               ...(account.cooldownUntil ? { cooldownUntil: account.cooldownUntil } : {}),

package/src/console/providers/catalog/routes.ts

@@ -1,6 +1,6 @@
 import { consoleErrorHandler } from "../../shared/errors";
 import { literalUnion } from "../../shared/elysia-schema";
-import { Elysia, t } from "elysia";
+import { Elysia, t, type AnyElysia } from "elysia";
 import { SERVICE_KINDS, WIRE_FAMILIES } from "../../../protocol/canonical-model";
 import { PROBE_REASONING_EFFORTS } from "../../../providers/discovery/discovery-types";
 import {
@@ -150,13 +150,37 @@ const bulkDeleteModelsBody = t.Object({
 const usageMatrixQuery = t.Object({
   days: t.Optional(t.Integer({ minimum: 1, maximum: 366 })),
 });
-export function createProviderCatalogRoutes(config: ProviderCatalogConfig): Elysia {
-  const factory = createProviderCatalogOperations(config);
-  const modelFactory = createModelCatalogOperations(config);
+export function createProviderCatalogRoutes(config: ProviderCatalogConfig): AnyElysia {
+  // One provider-list cache revision shared by both operation factories. Every
+  // provider/account/model mutation already funnels through the snapshot
+  // invalidator; wrapping it here means any of those writes bumps the revision
+  // folded into the provider-list cache key, so the cached overview (P-04)
+  // recomputes on the next read without a per-path cache delete. The revision
+  // stays per route-group, so a mutation handled by a peer process still
+  // converges when its own entry's TTL lapses.
+  const underlyingInvalidator = config.snapshotInvalidator;
+  let providerListCacheRevision = 0;
+  const catalogSnapshotInvalidator = underlyingInvalidator
+    ? {
+        invalidate: async () => {
+          providerListCacheRevision += 1;
+          return underlyingInvalidator.invalidate();
+        },
+        currentRevision: () => providerListCacheRevision,
+      }
+    : undefined;
+  const effectiveConfig = catalogSnapshotInvalidator
+    ? { ...config, snapshotInvalidator: catalogSnapshotInvalidator }
+    : config;
+  const factory = createProviderCatalogOperations(effectiveConfig);
+  const modelFactory = createModelCatalogOperations(effectiveConfig);
   return new Elysia({ prefix: "/providers" })
     .error(consoleErrorHandler("Provider catalog operation failed"))
     .get("/", async ({ request }) => {
-      return await factory.listProviders(config.accessResolver(request));
+      return await factory.listProvidersCached(
+        config.accessResolver(request),
+        request.headers.get("if-none-match"),
+      );
 })
     .patch(
       "/platform/global/:providerId",
@@ -394,5 +418,5 @@ export function createProviderCatalogRoutes(config: ProviderCatalogConfig): Elys
           body.accountIds,
         );
 },
-    ) as unknown as Elysia;
+    );
 }