cartethyia 2.7.2 → 2.7.4

package/src/transport/routing/route-catalog.ts

@@ -10,6 +10,7 @@ import {
   networkPools,
   poolRoutingSettings,
   providerAccounts,
+  providerPoolAccounts,
   providerRoutingSettings,
   providers,
   tenantDisabledModels,
@@ -372,6 +373,17 @@ const POOL_COLUMNS = {
   weight: networkPools.weight,
 } as const;
 
+const POOL_ACCOUNT_COLUMNS = {
+  id: providerPoolAccounts.id,
+  tenantId: providerPoolAccounts.tenantId,
+  networkPoolId: providerPoolAccounts.networkPoolId,
+  providerId: providerPoolAccounts.providerId,
+  label: providerPoolAccounts.label,
+  status: providerPoolAccounts.status,
+  cooldownUntil: providerPoolAccounts.cooldownUntil,
+  lastErrorCategory: providerPoolAccounts.lastErrorCategory,
+} as const;
+
 const DISABLED_MODEL_COLUMNS = {
   tenantId: tenantDisabledModels.tenantId,
   providerId: tenantDisabledModels.providerId,
@@ -414,7 +426,7 @@ class RouteCatalogRepository {
   constructor(private readonly db: CartethyiaDatabase) {}
 
   async loadRouteCatalogSnapshot(tenantId?: string): Promise<RouteCatalogSnapshotResult> {
-    const [providerRows, modelRows, accountRows, aliasRows, comboRows, routingRows, poolRows, disabledModelRows, cliMappingRows, cliMappingSettingRows, poolSettingRows, settingsRows] =
+    const [providerRows, modelRows, accountRows, aliasRows, comboRows, routingRows, poolRows, poolAccountRows, disabledModelRows, cliMappingRows, cliMappingSettingRows, poolSettingRows, settingsRows] =
       await Promise.all([
         this.db.select(PROVIDER_COLUMNS).from(providers).where(eq(providers.enabled, true)),
         this.db.select(MODEL_COLUMNS).from(models),
@@ -427,6 +439,7 @@ class RouteCatalogRepository {
         this.db.select(COMBO_COLUMNS).from(modelCombos),
         this.db.select(ROUTING_COLUMNS).from(providerRoutingSettings),
         this.db.select(POOL_COLUMNS).from(networkPools),
+        this.db.select(POOL_ACCOUNT_COLUMNS).from(providerPoolAccounts),
         this.db.select(DISABLED_MODEL_COLUMNS).from(tenantDisabledModels),
         this.db.select(CLI_MAPPING_COLUMNS).from(cliToolMappings),
         this.db.select(CLI_MAPPING_SETTING_COLUMNS).from(cliToolSettings),
@@ -500,6 +513,28 @@ class RouteCatalogRepository {
       activePoolsByTenant.set(pool.tenantId, list);
     }
 
+    // Pool-as-account rows, grouped by tenant: one per (pool × ip-scoped
+    // provider). For a credential-less ip-scoped provider these are the
+    // account-equivalent routing entities — a spent egress is excluded from
+    // the plan exactly like a cooling account, and the candidate carries the
+    // pool-account's health (see the public-candidate fan-out below).
+    const poolAccountsByTenant = new Map<
+      string,
+      Array<{
+        id: string;
+        networkPoolId: string;
+        providerId: string;
+        status: string;
+        cooldownUntil: Date | null;
+        lastErrorCategory: string | null;
+      }>
+    >();
+    for (const poolAccount of poolAccountRows) {
+      const list = poolAccountsByTenant.get(poolAccount.tenantId) ?? [];
+      list.push(poolAccount);
+      poolAccountsByTenant.set(poolAccount.tenantId, list);
+    }
+
     // Per-tenant pool selection strategy; an absent row reads as the
     // `least_loaded` default at selection time.
     const poolRouting: Record<string, PoolRoutingSetting> = {};
@@ -657,7 +692,67 @@ class RouteCatalogRepository {
       if (accounts.length === 0) {
         const providerRequiresAccount = requiresAccountById.get(model.providerId) ?? true;
         if (!providerRequiresAccount) {
-          // Public models inherit active pools for each tenant that has active pools
+          // Public models inherit active pools for each tenant that has active pools.
+          // When the provider is ip-scoped (limits follow the egress address), the
+          // tenant's pool-account rows are the account-equivalent routing entities:
+          // one candidate per pool, carrying that pool-account's health, so a spent
+          // egress is excluded from the plan exactly like a cooling account.
+          const ownedTenantIds = [...poolAccountsByTenant.keys()].filter((tid) =>
+            (poolAccountsByTenant.get(tid) ?? []).some((pa) => pa.providerId === model.providerId),
+          );
+          let emittedPoolAccount = false;
+          for (const tenantOwnerId of ownedTenantIds) {
+            const poolAccounts = poolAccountsByTenant.get(tenantOwnerId) ?? [];
+            const tenantPoolAccounts = new Map<string, typeof poolAccounts>();
+            for (const pa of poolAccounts) {
+              if (pa.providerId !== model.providerId) continue;
+              const list = tenantPoolAccounts.get(pa.networkPoolId) ?? [];
+              list.push(pa);
+              tenantPoolAccounts.set(pa.networkPoolId, list);
+            }
+            if (tenantPoolAccounts.size === 0) continue;
+            for (const [poolId, pas] of tenantPoolAccounts) {
+              const first = pas[0];
+              if (!first) continue;
+              const tenantPools = resolveNetworkPools(model.providerId, tenantOwnerId);
+              if (!tenantPools) continue;
+              emittedPoolAccount = true;
+              const tenantCandidate: RouteCandidateWithHealth = {
+                provider_id: model.providerId,
+                model_id: model.modelId,
+                wire_family: model.wireFamily as WireFamily,
+                service_kind: model.serviceKind,
+                endpoint: model.endpointPath,
+                ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
+                capability_profile: capabilityProfile,
+                tenant_id: tenantOwnerId,
+                // Public credential-less candidates have no account to own them.
+                owner_tenant_id: null,
+                requires_account: false as const,
+                network_pool_ids: [poolId],
+                network_pool_required: true,
+                network_pool_limits: tenantPools.limits,
+                network_pool_weights: tenantPools.weights,
+                ...(tenantPools.routing ? { network_pool_routing: tenantPools.routing } : {}),
+                ...providerLimitFor(model.providerId, tenantOwnerId),
+                ...(first.status === "disabled"
+                  ? { health_status: "disabled" as const }
+                  : first.status === "cooldown"
+                    ? {
+                        health_status: "cooldown" as const,
+                        cooldown_kind: hardCooldownCategory(first.lastErrorCategory) ? "hard" : "soft",
+                        ...(first.cooldownUntil && first.cooldownUntil.getTime() > Date.now()
+                          ? { cooldown_until: first.cooldownUntil.getTime() }
+                          : {}),
+                      }
+                    : {}),
+              };
+              if (tenantId === undefined || tenantId === tenantOwnerId) {
+                candidates.push(tenantCandidate);
+              }
+            }
+          }
+          if (emittedPoolAccount) continue;
           for (const tId of configuredPoolTenants) {
             const tenantPools = resolveNetworkPools(model.providerId, tId);
             if (tenantPools) {
@@ -670,6 +765,8 @@ class RouteCatalogRepository {
                 ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
                 capability_profile: capabilityProfile,
                 tenant_id: tId,
+                // Public credential-less candidates have no account to own them.
+                owner_tenant_id: null,
                 requires_account: false as const,
                 network_pool_ids: tenantPools.ids,
                 network_pool_required: true,
@@ -696,6 +793,8 @@ class RouteCatalogRepository {
           ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
           capability_profile: capabilityProfile,
           tenant_id: providerTenantId,
+          // Public credential-less candidates have no account to own them.
+          owner_tenant_id: null,
           ...(providerRequiresAccount
             ? { health_status: "disabled" as const }
             : { requires_account: false as const }),
@@ -738,6 +837,9 @@ class RouteCatalogRepository {
           ...(routeUserAgent === undefined ? {} : { user_agent: routeUserAgent }),
           tenant_id: rowTenantId,
           provider_account_id: account.id,
+          // The account's owning tenant (null = shared pool-wide) — the bucket
+          // key for admission, distinct from the requesting tenant.
+          owner_tenant_id: account.tenantId ?? null,
           // The plan gate is per (account, model): the model may be refused on
           // a free plan and the account may be on one. Both ride here because
           // `plan()` sees the candidate and nothing else.

package/src/transport/routing/route-model.ts

@@ -1,6 +1,9 @@
 // Routing contracts and snapshots.
 import { GatewayError } from "../../protocol/gateway-error";
 import { type ServiceKind, type WireFamily } from "../../protocol/canonical-model";
+import type { CallerIdentity } from "../../security/access-control";
+
+export type { CallerIdentity };
 
 
 export type RoutingRevision = number;
@@ -57,6 +60,14 @@ export interface RouteCandidate {
   readonly network_pool_provider_limit?: number;
   /** `null`/`undefined` = globally routable; a tenant id = routable only for that tenant's requests (BYOK). */
   readonly tenant_id?: string | null;
+  /**
+   * The tenant that owns this candidate's account (`provider_accounts.tenant_id`),
+   * or null for a shared pool-wide account. Distinct from `tenant_id` (the
+   * requesting tenant). Used to scope the admission bucket: a shared account
+   * is one bucket across tenants; a tenant-owned account is scoped to its
+   * owner so two tenants cannot drain each other's ceiling.
+   */
+  readonly owner_tenant_id?: string | null;
   /** `false` only for a genuinely credential-less provider (e.g. OpenCode
    * Free) dispatched with zero `provider_accounts` rows — the handler skips
    * `resolveCredentialForAccount` and dispatches with a `"none"` credential.
@@ -80,6 +91,11 @@ export interface RouteCandidate {
    * "free": guessing free here would defeat the gate it exists to serve.
    */
   readonly account_plan?: string | null;
+  /** Usage-floor ceiling from Routing Strategy; read live at plan time. */
+  readonly usage_floor?: number;
+  readonly usage_floor_unit?: "credit" | "percent";
+  /** Live quota windows (cache) the floor check evaluates. */
+  readonly quota_windows?: readonly unknown[];
 }
 
 /**
@@ -163,6 +179,16 @@ export interface PoolRoutingSetting {
 export interface RouteContinuationAffinity {
   readonly providerId: string;
   readonly providerAccountId: string;
+  /**
+   * True when the request's tool-result ids are all already answered by the
+   * conversation history (a replay), so no call is still owed to the pinned
+   * account. In that case, if the pinned account is no longer routable for
+   * the requested model, the request may safely rebase to a fresh Run on an
+   * eligible account instead of being refused — the recorded exchange travels
+   * as history. When false, the pin is a hard constraint: a live pending call
+   * must reach the exact account that owns it.
+   */
+  readonly rebaseable: boolean;
 }
 
 export interface RoutePlan {
@@ -171,6 +197,33 @@ export interface RoutePlan {
   readonly requested_model: string;
   readonly resolved_model: string;
   readonly provider_id: string;
+  /**
+   * The system decision behind each candidate, keyed by the candidate's
+   * admission bucket. Written once at plan time; every later layer (dispatch,
+   * telemetry) reads this instead of re-deriving its own ordering.
+   */
+  readonly decisions: ReadonlyMap<string, RoutingDecision>;
+}
+
+/** How eligible a candidate is and why — written once, read by every layer. */
+export const ROUTING_RANK = {
+  FRESH: 0,
+  SLOW: 1,
+  COOLING: 2,
+  SATURATED: 3,
+} as const;
+export type RoutingRank = (typeof ROUTING_RANK)[keyof typeof ROUTING_RANK];
+
+export interface RoutingDecision {
+  readonly eligible: boolean;
+  readonly rank: RoutingRank;
+  readonly reason: string;
+  readonly health_status?: string;
+  readonly cooldown_until?: number;
+  readonly floor_blocked?: boolean;
+  readonly plan_gate_blocked?: boolean;
+  readonly capability_blocked?: boolean;
+  readonly saturated?: boolean;
 }
 
 import type { ComboStrategy, PoolRoutingStrategy, ProviderRoutingStrategy } from "../../persistence/schema";
@@ -305,7 +358,7 @@ export function ambiguousModelError(bare: string, owners: string[]): GatewayErro
   return new GatewayError(
     "ambiguous_model",
     400,
-    `'${bare}' matches more than one provider (${owners.join(", ")}). Qualify it as '${owners[0]}/${bare}', or add an alias to pick one.`,
+    `'${bare}' matches more than one provider (${owners.join(", ")}). Qualify it as '${owners[0]}/${bare}', or add an alias to pick one. Too popular for its own good — qualify it 🧩`,
     {
       model: bare,
       owners,
@@ -327,7 +380,7 @@ export function modelNotFoundError(requested: string, resolved: readonly string[
     404,
     `'${requested}' is not routed${
       targets.length > 0 ? ` — it resolved to ${hint}, which no account serves` : ""
-    }. Enable the model on an account, or point the alias at one that exists.`,
+    } (request {requestId}). Enable the model on an account, or point the alias at one that exists. Try another model — this one's off the menu 📚`,
     {
       model: requested,
       ...(targets.length > 0 ? { resolved_models: targets } : {}),
@@ -339,7 +392,7 @@ export function capabilityUnsupportedError(capability: string): GatewayError {
   return new GatewayError(
     "capability_unsupported",
     400,
-    `No account serving this model supports ${capability}. Drop the ${capability} part of the request, or route to a model that accepts it.`,
+    `No account serving this model supports ${capability} (request {requestId}). Drop the ${capability} part of the request, or route to a model that accepts it. Know your tools — this one just isn't in the box 🧰`,
     { capability },
   );
 }
@@ -371,8 +424,8 @@ export function capacityExhaustedError(context?: {
     "provider_capacity_exhausted",
     429,
     onlyOne
-      ? "The only account routing this model is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add another account."
-      : "Every account is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add an account.",
+      ? "The only account routing this model is at its concurrency limit (request {requestId}). Retry shortly; if it persists, raise the provider's max-inflight or add another account. Even the machine needs a rest — chill 🦋"
+      : "Every account is at its concurrency limit (request {requestId}). Retry shortly; if it persists, raise the provider's max-inflight or add an account. Even the machine needs a rest — chill 🦋",
     {
       ...(context?.providerId !== undefined ? { providerId: context.providerId } : {}),
       ...(context?.model !== undefined ? { model: context.model } : {}),
@@ -403,7 +456,7 @@ export function accountsUnavailableError(
   return new GatewayError(
     "accounts_unavailable",
     503,
-    `No account in the pool can serve '${requested}' right now (${explainEligibilityReasons(distinct)}). Add an account, or wait for an operator to re-enable one.`,
+    `No account in the pool can serve '${requested}' right now (request {requestId}) (${explainEligibilityReasons(distinct)}). Add an account, or wait for an operator to re-enable one. Every account is on a coffee break — try later ☕️`,
     { model: requested, reasons: distinct, candidate_count: reasons.length, gateway_hint: "no_healthy_account" },
   );
 }
@@ -439,7 +492,7 @@ export function accountsRateLimitedError(
   return new GatewayError(
     "accounts_rate_limited",
     429,
-    `Every account serving '${requested}'${routeNote} is cooling down after hitting upstream limits. The request is fine — retry once the cooldown resets.`,
+    `Every account serving '${requested}'${routeNote} is cooling down after hitting upstream limits (request {requestId}). The request is fine — retry once the cooldown resets. They're resting up 🌸`,
     {
       model: requested,
       routed_model: routed,