cartethyia 2.7.4 → 2.7.5

package/src/console/observability/logs.ts

@@ -23,7 +23,7 @@ import {
 } from "../../observability/log-ring";
 import { consoleSseResponse, createConsoleSseStream } from "./sse";
 
-export interface LogsConfig {
+interface LogsConfig {
   readonly accessResolver: ConsoleAccessResolver;
   readonly auditSink?: AuditSink;
 }

package/src/console/observability/sse.ts

@@ -5,14 +5,14 @@
  * the shared `buildSseEventFrame` core so the two layers cannot drift.
  */
 
-export interface SseSender {
+interface SseSender {
   send(event: string, data: unknown): void;
 }
 
 /** Register endpoint-specific SSE subscriptions; return their teardown callback. */
-export type SseSetup = (sender: SseSender) => () => void;
+type SseSetup = (sender: SseSender) => () => void;
 
-import { buildSseEventFrame as formatSseFrame } from "../../protocol/sse-frame";
+import { TEXT_ENCODER, buildSseEventFrame as formatSseFrame } from "../../protocol/sse-frame";
 
 export { formatSseFrame };
 
@@ -22,38 +22,82 @@ export { formatSseFrame };
  */
 const SSE_HEARTBEAT_MS = 25_000;
 
+/**
+ * Hard cap on one stream's lifetime. A tab that is abandoned but never
+ * unloads (a backgrounded browser window, a parked laptop) would otherwise
+ * hold its subscription and timers forever; the client reconnects on close,
+ * so this only forces a refresh. 45 minutes is far longer than any live view
+ * needs in one stretch.
+ */
+const SSE_MAX_LIFETIME_MS = 45 * 60_000;
+
+/**
+ * Idle timeout: if no *data* frame is sent for this long, the stream sends a
+ * terminal `close` event and closes. Heartbeats deliberately do not count —
+ * they are there to keep proxies alive, not to prove someone is reading, so
+ * they must not defeat the abandoned-tab cutoff.
+ */
+const SSE_IDLE_TIMEOUT_MS = 5 * 60_000;
+
+/** Watchdog cadence; the two cutoffs above are checked on this tick. */
+const SSE_WATCHDOG_MS = 30_000;
+
+/** Frame sent when the server cuts the stream (idle or max lifetime). */
+function closeFrame(reason: string): Uint8Array {
+  return TEXT_ENCODER.encode(formatSseFrame("close", JSON.stringify({ reason })));
+}
+
 /**
  * Console SSE response stream with uniform JSON event encoding, heartbeat,
- * and abort/cancel cleanup. The setup callback runs synchronously at stream
- * start so the initial snapshot is enqueued before the first read.
+ * idle/max-lifetime cutoff, and abort/cancel cleanup. The setup callback runs
+ * synchronously at stream start so the initial snapshot is enqueued before the
+ * first read.
+ *
+ * The encoder is the module-level shared `TextEncoder` from the frame module:
+ * allocating one per stream (let alone per send) is unnecessary garbage for a
+ * hot path that encodes a frame every few hundred milliseconds per connection.
  */
 export function createConsoleSseStream(
   signal: AbortSignal,
   setup: SseSetup,
 ): ReadableStream<Uint8Array> {
-  const encoder = new TextEncoder();
   let cleanupSubscription: (() => void) | undefined;
   let heartbeat: ReturnType<typeof setInterval> | undefined;
+  let watchdog: ReturnType<typeof setInterval> | undefined;
   let close: (() => void) | undefined;
 
   return new ReadableStream<Uint8Array>({
     start(controller) {
       let closed = false;
+      const startedAt = Date.now();
+      let lastDataAt = startedAt;
       const sender: SseSender = {
         send(event, data) {
           if (closed) return;
           try {
-            controller.enqueue(encoder.encode(formatSseFrame(event, JSON.stringify(data))));
+            lastDataAt = Date.now();
+            controller.enqueue(TEXT_ENCODER.encode(formatSseFrame(event, JSON.stringify(data))));
           } catch {
             close?.();
           }
         },
       };
 
+      const terminate = (reason: string): void => {
+        if (closed) return;
+        try {
+          controller.enqueue(closeFrame(reason));
+        } catch {
+          // Fall through to close regardless.
+        }
+        close?.();
+      };
+
       close = () => {
         if (closed) return;
         closed = true;
         clearInterval(heartbeat);
+        clearInterval(watchdog);
         cleanupSubscription?.();
         try {
           controller.close();
@@ -70,12 +114,22 @@ export function createConsoleSseStream(
       heartbeat = setInterval(() => {
         if (closed) return;
         try {
-          controller.enqueue(encoder.encode(": ping\n\n"));
+          controller.enqueue(TEXT_ENCODER.encode(": ping\n\n"));
         } catch {
           close?.();
         }
       }, SSE_HEARTBEAT_MS);
 
+      watchdog = setInterval(() => {
+        if (closed) return;
+        const now = Date.now();
+        if (now - lastDataAt > SSE_IDLE_TIMEOUT_MS) {
+          terminate("idle");
+        } else if (now - startedAt > SSE_MAX_LIFETIME_MS) {
+          terminate("max_lifetime");
+        }
+      }, SSE_WATCHDOG_MS);
+
       signal.addEventListener("abort", close, { once: true });
     },
     cancel() {

package/src/console/observability/store.ts

@@ -184,6 +184,14 @@ async function resolveProxyLabel(
 }
 const HEALTH_WINDOW_MS = 24 * 3_600_000;
 const TOP_N = 50;
+/**
+ * TTL for the usage analytics read-through (summary, chart, breakdown, totals).
+ * The dashboard polls these every 5–10s; a 30s TTL means the heavy telemetry
+ * window scans run once per 30s and the polls in between are answered from
+ * Redis (or the in-process fallback) with a `304`. Health stays on the
+ * default 10s — it feeds the live status tile.
+ */
+const USAGE_READ_THROUGH_TTL_SECONDS = 30;
 
 /**
  * Nearest-rank percentile over a sorted array — kept for the JS-side
@@ -197,7 +205,7 @@ function percentile(sorted: readonly number[], fraction: number): number {
   return Math.round(sorted[index] ?? 0);
 }
 
-export interface UsagePerformanceSummary {
+interface UsagePerformanceSummary {
   avgResolveMs: number;
   avgDurationMs: number;
   latencyP50Ms: number;
@@ -389,6 +397,7 @@ export class DrizzleObservabilityStore implements ObservabilityStore {
   async usage(tenantId: string, period: string): Promise<CachedResult<UsageResponse>> {
     return this.readThroughWithEtag(this.usageCacheKey(tenantId, period, "usage"), () =>
       this.computeUsage(tenantId, period),
+    USAGE_READ_THROUGH_TTL_SECONDS,
     );
   }
 
@@ -405,8 +414,12 @@ export class DrizzleObservabilityStore implements ObservabilityStore {
    * configured — and returns the strong validator alongside it, so a repeated
    * poll can be answered with a `304` instead of the whole payload.
    */
-  private readThroughWithEtag<T>(key: string, compute: () => Promise<T>): Promise<CachedResult<T>> {
-    return cachedReadWithEtag(this.redis, key, compute);
+  private readThroughWithEtag<T>(
+    key: string,
+    compute: () => Promise<T>,
+    ttlSeconds?: number,
+  ): Promise<CachedResult<T>> {
+    return cachedReadWithEtag(this.redis, key, compute, ttlSeconds);
   }
 
   private async computeUsage(tenantId: string, period: string): Promise<UsageResponse> {
@@ -459,6 +472,7 @@ export class DrizzleObservabilityStore implements ObservabilityStore {
   async usageSummary(tenantId: string, period: string): Promise<CachedResult<UsageSummaryResponse>> {
     return this.readThroughWithEtag(this.usageCacheKey(tenantId, period, "summary"), () =>
       this.computeSummary(tenantId, period),
+    USAGE_READ_THROUGH_TTL_SECONDS,
     );
   }
 
@@ -499,6 +513,7 @@ export class DrizzleObservabilityStore implements ObservabilityStore {
   async usageChart(tenantId: string, period: string): Promise<CachedResult<UsageChartResponse>> {
     return this.readThroughWithEtag(this.usageCacheKey(tenantId, period, "chart"), () =>
       this.computeChart(tenantId, period),
+    USAGE_READ_THROUGH_TTL_SECONDS,
     );
   }
 
@@ -522,7 +537,7 @@ export class DrizzleObservabilityStore implements ObservabilityStore {
         input: bucket.inputTokens,
         // `cached` is the cached share of the prompt: the SQL reader sums
         // cached_input_tokens, which is the same number the old JS loop used.
-        cached: bucket.inputTokens,
+        cached: bucket.cachedInputTokens,
         output: bucket.outputTokens,
       });
     }
@@ -546,6 +561,7 @@ export class DrizzleObservabilityStore implements ObservabilityStore {
   ): Promise<CachedResult<UsageByResponse>> {
     return this.readThroughWithEtag(this.usageCacheKey(tenantId, `${dimension}:${period}`, "by"), () =>
       this.computeBy(tenantId, dimension, period),
+    USAGE_READ_THROUGH_TTL_SECONDS,
     );
   }
 

package/src/console/providers/catalog/catalog-projections.ts

@@ -23,7 +23,7 @@ import type { ProviderRecord } from "./contracts";
  * purpose: the projection should not be able to reach a loader, so the type
  * cannot drift into "call something expensive to answer a boolean".
  */
-export interface ProviderDiscoveryLookup {
+interface ProviderDiscoveryLookup {
   hasModelDiscovery(providerId: string): boolean;
 }
 

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

@@ -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
@@ -653,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;
@@ -800,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";
@@ -25,7 +27,6 @@ import type { OAuthLoginField } from "../../../providers/authentication/oauth-fl
 import { providerCredentialHint, providerCredentialUrl, providerDisplayName, providerHasAdapterUserAgent, providerOperatorNotice, providerServiceKinds, type CompatibilityProfile } from "../../../providers/provider-metadata";
 import type { AccountHealthEventRecord } from "../../../providers/operations/account-health-service";
 import { healthEventBuffer } from "../../../persistence/health-event-flush";
-import { materializeBuddyDeviceBinding } from "../../../providers/integrations/buddy/buddy-identity";
 import { CREDENTIAL_MODES, PROVIDER_READ_SCOPES, PROVIDER_WRITE_SCOPES, type BuddyGrowthTaskLedgerEntry } from "./contracts";
 import { enqueueCheckin } from "../../../workers/daily-checkin";
 import {
@@ -129,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
@@ -233,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,
@@ -694,7 +768,7 @@ 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];
                 // Buddy providers bind a per-account device identity
                 // (qimei36) that is normally derived from the INTERNAL account
@@ -707,13 +781,17 @@ export function createProviderCatalogOperations(config: ProviderCatalogConfig) {
                   account.providerId === "cbcn" ||
                   account.providerId === "workbuddy" ||
                   account.providerId === "workbuddycn"
-                    ? materializeBuddyDeviceBinding(account.id, authState)
+                    // 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

@@ -151,12 +151,36 @@ const usageMatrixQuery = t.Object({
   days: t.Optional(t.Integer({ minimum: 1, maximum: 366 })),
 });
 export function createProviderCatalogRoutes(config: ProviderCatalogConfig): AnyElysia {
-  const factory = createProviderCatalogOperations(config);
-  const modelFactory = createModelCatalogOperations(config);
+  // 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",