cartethyia 2.7.3 → 2.7.5

package/src/transport/request/state.ts

@@ -156,10 +156,9 @@ export interface ProxyRequestState {
    */
   extendDeadline(ms: number): void;
   cleanup(): void;
-  addCleanup(cleanup: () => void): void;
 }
 
-export interface RequestTracker {
+interface RequestTracker {
   track(id: string): void;
   untrack(id: string): void;
 }
@@ -191,15 +190,12 @@ function subscribeInFlightSnapshot(
   store: { inFlightSnapshot(): InFlightSnapshot },
   listener: (snapshot: InFlightSnapshot) => void,
 ): () => void {
-  const timers = new Set<ReturnType<typeof setTimeout>>();
   const push = (): void => listener(store.inFlightSnapshot());
   push();
   const handle = setInterval(push, 1_000);
   (handle as unknown as { unref?: () => void })?.unref?.();
   return () => {
     clearInterval(handle);
-    for (const t of timers) clearTimeout(t);
-    timers.clear();
   };
 }
 
@@ -259,7 +255,7 @@ export class ProxyRequestStateStore {
       try {
         if (controller && !controller.signal.aborted) {
           controller.abort(
-            new GatewayError("deadline_exceeded", 504, "in-flight request exceeded its deadline"),
+            new GatewayError("deadline_exceeded", 504, "in-flight request exceeded its deadline (request {requestId}). Some things just take longer 🐢"),
           );
         }
       } catch {
@@ -292,7 +288,7 @@ export class ProxyRequestStateStore {
     const abortReason =
       reason instanceof Error || reason instanceof DOMException
         ? reason
-        : new GatewayError("shutting_down", 503, "The gateway is shutting down, so this request cannot be served. Retry against a live instance.");
+        : new GatewayError("shutting_down", 503, "The gateway is shutting down, so this request cannot be served (request {requestId}). Retry against a live instance. Maintenance mode — back in a minute 🧘");
     for (const controller of controllers) {
       try {
         if (!controller.signal.aborted) controller.abort(abortReason);
@@ -319,7 +315,6 @@ export class ProxyRequestStateStore {
     else request.signal.addEventListener("abort", onAbort, { once: true });
     let cleaned = false;
     let providerFlightStarted = false;
-    const cleanups: Array<() => void> = [];
     const armDeadline = (ms: number): void => {
       clearTimeout(timer);
       timer = setTimeout(() => {
@@ -330,7 +325,7 @@ export class ProxyRequestStateStore {
           new GatewayError(
             "deadline_exceeded",
             504,
-            "request deadline exceeded",
+            "request deadline exceeded (request {requestId}). Some things just take longer 🐢",
             {},
             "cartethyia",
           ),
@@ -393,22 +388,12 @@ export class ProxyRequestStateStore {
           request.signal.removeEventListener("abort", onAbort);
         } catch {
         }
-        for (const cleanup of cleanups.splice(0)) {
-          try {
-            cleanup();
-          } catch {
-          }
-        }
         try {
           abortController.abort(new DOMException("request complete", "AbortError"));
         } catch {
         }
         this.states.delete(request);
       },
-      addCleanup: (cleanup) => {
-        if (cleaned) cleanup();
-        else cleanups.push(cleanup);
-      },
     };
     this.liveControllers.set(state.requestId, abortController);
     this.tracker?.track(state.requestId);
@@ -418,7 +403,7 @@ export class ProxyRequestStateStore {
   require(request: Request): ProxyRequestState {
     const state = this.states.get(request);
     if (!state)
-      throw new GatewayError("admission_unavailable", 503, "The request was never registered, so it cannot be served. Resend the request.");
+      throw new GatewayError("route_unavailable", 503, "The request was never registered, so it cannot be served (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");
     return state;
   }
 

package/src/transport/request/system-prompt-injection.ts

@@ -8,8 +8,9 @@
  * injection (Claude identity/billing prepend, buddy fixed system turn,
  * antigravity identity) happens later, in the adapters, and is untouched.
  *
- * Resolution is most-specific-wins: model > provider > global, where a
- * provider either follows the tenant's global prompt or carries a custom one.
+ * Resolution is most-specific-wins: alias/combo (when the caller's requested
+ * name matches one) > model > provider > global. A scope either references a
+ * named preset, carries a custom setting, or follows the global prompt.
  * Failure is non-fatal — an unusable configuration must not fail a
  * dispatchable request.
  */
@@ -17,6 +18,7 @@ import type { CanonicalRequest } from "../../protocol/canonical-model";
 import type { ServiceKind } from "../../protocol/canonical-model";
 import type {
   PromptSetting,
+  ScopePromptRef,
   TenantSystemPrompts,
 } from "../../console/system-prompt/contracts";
 import {
@@ -28,28 +30,89 @@ export interface SystemPromptRoute {
   readonly providerId: string;
   readonly modelId: string;
   readonly serviceKind: ServiceKind;
+  /** The model name the client asked for (pre-alias/combo resolution), when
+   * it differs from the resolved `modelId` — lets a combo/alias carry its
+   * own injection reference. */
+  readonly requestedModel?: string;
+}
+
+/**
+ * Resolves one scope reference to a concrete prompt setting. Returns
+ * `undefined` when the scope has nothing to say (no entry, preset
+ * missing/disabled, custom disabled). `undefined` here means "skip this
+ * scope" — the caller decides the final global fallback.
+ *
+ * `global` is itself a `ScopePromptRef | null`, so the `{ kind: "global" }`
+ * marker resolves through the global ref — which may be a preset, a custom
+ * setting, or `null` (nothing). An explicit `{ kind: "off" }` is handled by
+ * the caller before this function runs.
+ */
+function resolveRef(
+  prompts: TenantSystemPrompts,
+  ref: ScopePromptRef | undefined,
+): PromptSetting | undefined {
+  if (ref === undefined || ref.kind === "off" || ref.kind === "global") return undefined;
+  if (ref.kind === "preset") {
+    const preset = prompts.presets[ref.presetId];
+    if (preset === undefined || !preset.enabled) return undefined;
+    return { enabled: true, mode: preset.mode, text: preset.text };
+  }
+  return ref.setting.enabled ? ref.setting : undefined;
+}
+
+/**
+ * Whether a scope entry explicitly stops injection. An explicit `off` is
+ * terminal — it does NOT fall through to the global prompt.
+ */
+function isExplicitOff(ref: ScopePromptRef | undefined): boolean {
+  return ref?.kind === "off";
 }
 
 /**
  * Resolves the effective prompt for a route: the most-specific enabled scope
- * wins. A provider scope honours its `followGlobal` toggle; model scope is
- * always explicit. Returns `undefined` when nothing applies.
+ * wins. Alias/combo scopes (keyed by the requested name) beat the model scope;
+ * a provider scope honours its reference; model scope is always explicit. An
+ * explicit `off` at any scope stops injection for that request — it does not
+ * fall through to the global prompt. Returns `undefined` when nothing applies.
  */
 export function resolveTenantSystemPrompt(
   prompts: TenantSystemPrompts | undefined,
-  route: Pick<SystemPromptRoute, "providerId" | "modelId">,
+  route: Pick<SystemPromptRoute, "providerId" | "modelId" | "requestedModel">,
 ): PromptSetting | undefined {
   if (prompts === undefined) return undefined;
+  const global = prompts.global;
+
+  const requested = route.requestedModel;
+  if (requested !== undefined && requested.length > 0 && requested !== route.modelId) {
+    const aliasRef = prompts.aliases[requested];
+    if (aliasRef !== undefined) {
+      if (isExplicitOff(aliasRef)) return undefined;
+      const aliasSetting = resolveRef(prompts, aliasRef);
+      if (aliasSetting !== undefined) return aliasSetting;
+    }
+    const comboRef = prompts.combos[requested];
+    if (comboRef !== undefined) {
+      if (isExplicitOff(comboRef)) return undefined;
+      const comboSetting = resolveRef(prompts, comboRef);
+      if (comboSetting !== undefined) return comboSetting;
+    }
+  }
+
   const model = prompts.models[systemPromptModelKey(route.providerId, route.modelId)];
-  if (model !== undefined && model.enabled) return model;
+  if (model !== undefined) {
+    if (isExplicitOff(model)) return undefined;
+    const modelSetting = resolveRef(prompts, model);
+    if (modelSetting !== undefined) return modelSetting;
+  }
+
   const provider = prompts.providers[route.providerId];
   if (provider !== undefined) {
-    if (provider.followGlobal) {
-      return prompts.global !== null && prompts.global.enabled ? prompts.global : undefined;
-    }
-    if (provider.setting !== undefined && provider.setting.enabled) return provider.setting;
+    if (isExplicitOff(provider)) return undefined;
+    const providerSetting = resolveRef(prompts, provider);
+    if (providerSetting !== undefined) return providerSetting;
   }
-  return prompts.global !== null && prompts.global.enabled ? prompts.global : undefined;
+
+  return resolveRef(prompts, global ?? undefined);
 }
 
 /** Marker text guard so retries never double-inject. */

package/src/transport/request/tenant-preferences.ts

@@ -107,6 +107,27 @@ export async function resolveTenantImageClampMaxBytes(
   }
 }
 
+/**
+ * The tenant's ordered vision-handoff model list, or `[]` when none is
+ * configured (legacy `[image]` placeholder behavior). Read through the shared
+ * revision-keyed preference reader; a settings outage yields an empty list,
+ * which is the safe direction (handoff is an upgrade, never a prerequisite).
+ */
+export async function resolveTenantVisionHandoffModels(
+  db: CartethyiaDatabase,
+  tenantId: string | undefined,
+): Promise<readonly string[]> {
+  if (tenantId === undefined) return [];
+  try {
+    const prefs = await preferencesReaderFor(db).readPreferences(tenantId);
+    const models = prefs?.visionHandoffModels;
+    if (!Array.isArray(models)) return [];
+    return models.filter((model): model is string => typeof model === "string" && model.trim().length > 0);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Applies request shaping owned by tenant preferences and deployment config:
  * thinking normalization and the Responses reasoning summary override.
@@ -133,6 +154,7 @@ export async function applyTenantPreferences(
       providerId: candidate.provider_id,
       modelId: candidate.model_id,
       serviceKind: candidate.service_kind ?? "llm",
+      requestedModel: prepared.plan?.requested_model ?? candidate.model_id,
     });
     if (prefs) {
       // When the routed model is Responses (codex/openai/muse-spark) and the

package/src/transport/routing/candidate-index.ts

@@ -2,7 +2,7 @@
 import type { RouteCandidate, RouteSnapshot } from "./route-model";
 
 /** One parsed model reference: `provider/model` or a bare `model`. */
-export interface ParsedModel {
+interface ParsedModel {
   readonly providerId: string | null;
   readonly modelId: string;
 }
@@ -24,7 +24,7 @@ export function parseModelReference(model: string): ParsedModel {
  * candidates cost K×C `candidateMatches` calls (each re-parsing the model
  * string), repeated on every request.
  */
-export interface RouteCandidateIndex {
+interface RouteCandidateIndex {
   /** Candidates keyed by `provider_id/model_id`, snapshot order preserved. */
   readonly qualified: ReadonlyMap<string, readonly RouteCandidate[]>;
   /** Candidates keyed by bare `model_id`, snapshot order preserved. */

package/src/transport/routing/round-robin.ts

@@ -23,7 +23,7 @@ export class RoundRobinState {
  * combinations would retain one entry forever. 1000 is far above the working
  * set of any real catalog, so eviction only ever targets genuinely cold keys.
  */
-export const MAX_ROUND_ROBIN_ENTRIES = 1000;
+const MAX_ROUND_ROBIN_ENTRIES = 1000;
 
 /**
  * Creates the bounded LRU map the router keeps round-robin state in.

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

@@ -10,6 +10,7 @@ import {
   networkPools,
   poolRoutingSettings,
   providerAccounts,
+  providerPoolAccounts,
   providerRoutingSettings,
   providers,
   tenantDisabledModels,
@@ -19,12 +20,12 @@ import {
 import { DEFAULT_PROVIDER_MAX_INFLIGHT } from "../../persistence/schema";
 import { resolveTenantOverride } from "../../persistence/tenant-scope";
 import {
-  type RouteCandidate,
   type ComboDefinition,
   type PoolRoutingSetting,
   type ProviderRoutingMap,
   type RouteSnapshot,
   type SnapshotBuilder,
+  type RoutedCandidate,
 } from "./route-model";
 import { DEFAULT_PROXY_SKIP_PROVIDER_IDS } from "../../providers/provider-metadata";
 import { buildClaudeCliUserAgent } from "../../providers/operations/custom-cli-headers";
@@ -83,18 +84,6 @@ export function cliMappingSourceKeys(toolId: string, sourceModel: string): reado
  * — `RoutingEngine.plan()` filters candidates by the requesting tenant.
  */
 
-type RouteCandidateWithHealth = RouteCandidate & {
-  health_status?: "cooldown" | "model_cooldown" | "disabled";
-  cooldown_kind?: "hard" | "soft";
-  /**
-   * Epoch milliseconds at which this candidate's cooling window ends, when one
-   * is in force. Routing-internal: it is what lets `plan()` report a real reset
-   * on the all-accounts-cooling answer, and it never reaches a client verbatim —
-   * only the derived `retry-after` does.
-   */
-  cooldown_until?: number;
-};
-
 const HARD_COOLDOWN_CATEGORIES: Readonly<Record<string, true>> = {
   quota_exhausted: true,
   policy_blocked: true,
@@ -245,6 +234,7 @@ interface MergedModelRow {
   providerId: string;
   modelId: string;
   wireFamily: WireFamily;
+  dialect?: string | null;
   serviceKind: ServiceKind;
   endpointPath: string;
   modalities: unknown;
@@ -269,6 +259,7 @@ function mergeModelCatalog(
       providerId: row.providerId,
       modelId: row.modelId,
       wireFamily: row.wireFamily as WireFamily,
+      ...(row.dialect === null ? {} : { dialect: row.dialect }),
       serviceKind: row.serviceKind as ServiceKind,
       endpointPath: row.endpointPath,
       modalities: row.modalities,
@@ -308,6 +299,7 @@ const MODEL_COLUMNS = {
   providerId: models.providerId,
   modelId: models.modelId,
   wireFamily: models.wireFamily,
+  dialect: models.dialect,
   serviceKind: models.serviceKind,
   endpointPath: models.endpointPath,
   modalities: models.modalities,
@@ -372,6 +364,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 +417,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 +430,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 +504,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> = {};
@@ -643,7 +669,7 @@ class RouteCatalogRepository {
       accountsByProvider.set(account.providerId, list);
     }
 
-    const candidates: RouteCandidateWithHealth[] = [];
+    const candidates: RoutedCandidate[] = [];
     for (const model of mergedModelRows) {
       const providerTenantId = providerTenantById.get(model.providerId);
       if (providerTenantId === undefined) continue;
@@ -657,19 +683,83 @@ 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: RoutedCandidate = {
+                provider_id: model.providerId,
+                model_id: model.modelId,
+                wire_family: model.wireFamily as WireFamily,
+                ...(model.dialect == null ? {} : { dialect: model.dialect }),
+                service_kind: model.serviceKind,
+                endpoint: model.endpointPath,
+                ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
+                capability_profile: capabilityProfile,
+                tenant_id: tenantOwnerId,
+                ...(model.freeTier === true ? { free_tier: true } : {}),
+                // 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) {
-              const tenantCandidate: RouteCandidateWithHealth = {
+              const tenantCandidate: RoutedCandidate = {
                 provider_id: model.providerId,
                 model_id: model.modelId,
                 wire_family: model.wireFamily as WireFamily,
+                ...(model.dialect == null ? {} : { dialect: model.dialect }),
                 service_kind: model.serviceKind,
                 endpoint: model.endpointPath,
                 ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
                 capability_profile: capabilityProfile,
                 tenant_id: tId,
+                ...(model.freeTier === true ? { free_tier: true } : {}),
                 // Public credential-less candidates have no account to own them.
                 owner_tenant_id: null,
                 requires_account: false as const,
@@ -689,15 +779,17 @@ class RouteCatalogRepository {
         const networkPools = providerRequiresAccount
           ? undefined
           : resolveNetworkPools(model.providerId, providerTenantId);
-        const candidate: RouteCandidateWithHealth = {
+        const candidate: RoutedCandidate = {
           provider_id: model.providerId,
           model_id: model.modelId,
           wire_family: model.wireFamily as WireFamily,
+          ...(model.dialect == null ? {} : { dialect: model.dialect }),
           service_kind: model.serviceKind,
           endpoint: model.endpointPath,
           ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
           capability_profile: capabilityProfile,
           tenant_id: providerTenantId,
+          ...(model.freeTier === true ? { free_tier: true } : {}),
           // Public credential-less candidates have no account to own them.
           owner_tenant_id: null,
           ...(providerRequiresAccount
@@ -731,15 +823,17 @@ class RouteCatalogRepository {
         }
         const networkPools = resolveNetworkPools(model.providerId, rowTenantId);
         const routeUserAgent = resolveUserAgent(model.providerId, rowTenantId);
-        const candidate: RouteCandidateWithHealth = {
+        const candidate: RoutedCandidate = {
           provider_id: model.providerId,
           model_id: model.modelId,
           wire_family: model.wireFamily as WireFamily,
+          ...(model.dialect == null ? {} : { dialect: model.dialect }),
           service_kind: model.serviceKind,
           endpoint: model.endpointPath,
           ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
           capability_profile: capabilityProfile,
           ...(routeUserAgent === undefined ? {} : { user_agent: routeUserAgent }),
+          ...(model.freeTier === true ? { free_tier: true } : {}),
           tenant_id: rowTenantId,
           provider_account_id: account.id,
           // The account's owning tenant (null = shared pool-wide) — the bucket