@mupt-ai/dari-gateway 0.3.1 → 0.3.2

package/src/self_host/resolve.ts

@@ -58,7 +58,7 @@ export async function resolveSelfHostedRouter(
 ): Promise<ResolvedRouter> {
   const keyIndex = gatewayKeyIndex(deps.gatewayKeys, request.apiKey);
   if (keyIndex === null) {
-    throw new HttpError(401, "Missing or invalid router/API key.", "routing_key_resolution_failed");
+    throw new HttpError(401, "Missing or invalid gateway key.", "authentication_error");
   }
   const router = deps.config.routers[request.routerId];
   if (router === undefined) {
@@ -91,7 +91,10 @@ export async function resolveSelfHostedRouter(
   }
 
   const models = router.models.filter((model) => credentials.get(providerForModel(model.id)) != null);
-  if (models.length === 0) throw unavailableRouterError(request.routerId, exhausted);
+  if (models.length === 0) {
+    const missing = [...credentials].filter(([, credential]) => credential == null).map(([provider]) => provider);
+    throw unavailableRouterError(request.routerId, exhausted, missing);
+  }
 
   const resolved: ResolvedRouter = {
     router_id: request.routerId,
@@ -104,9 +107,8 @@ export async function resolveSelfHostedRouter(
     subscription_credential_ids: {},
     zdr: router.zdr,
     speculative_routing: false,
+    session_pinning: router.sessionPinning,
     primary_retries: router.retries,
-    model_fallback_enabled: router.fallback,
-    fallback_requires_different_provider: router.fallbackRequiresDifferentProvider,
     lease_context_enabled: false,
     routing_strategy: "dari",
     custom_config: null,
@@ -152,7 +154,10 @@ export async function resolveSelfHostedRouter(
 
 // Configured endpoints read their own key variable, or send a placeholder
 // when they take none; known providers use their standard variable.
-async function providerApiKey(deps: SelfHostedResolverDeps, provider: string): Promise<string | undefined> {
+async function providerApiKey(
+  deps: Pick<SelfHostedResolverDeps, "config" | "providerApiKey" | "env">,
+  provider: string,
+): Promise<string | undefined> {
   const endpoint = deps.config.providers[provider];
   if (endpoint === undefined) return (await deps.providerApiKey(provider))?.trim() || undefined;
   if (endpoint.apiKeyEnv === undefined) return "no-key";
@@ -204,23 +209,48 @@ const SUBSCRIPTION_PLAN_NAMES: Record<SubscriptionProvider, string> = {
   meta_muse: "Muse Code",
 };
 
+/**
+ * Providers a router lists that no credential can serve: no API key and no
+ * connected subscription the router allows. Startup uses this, so it counts a
+ * held subscription as connected (the request-time 424 reports holds) and
+ * checks both harnesses, since startup does not know the client.
+ */
+export async function providersWithoutCredentials(
+  deps: Pick<SelfHostedResolverDeps, "subscriptions" | "providerApiKey" | "config" | "env">,
+  router: RouterConfig,
+): Promise<string[]> {
+  const missing: string[] = [];
+  for (const provider of new Set(router.models.map((model) => providerForModel(model.id)))) {
+    const plans = router.subscriptions
+      ? [subscriptionProviderFor(provider, "claude_code"), subscriptionProviderFor(provider, "muse_code")]
+      : [];
+    const connected = plans.some((plan) => plan !== null && deps.subscriptions.list(plan).length > 0);
+    if (connected) continue;
+    const apiKey = await providerApiKey(deps, provider);
+    if (apiKey === undefined) missing.push(provider);
+  }
+  return missing;
+}
+
 function unavailableRouterError(
   routerId: string,
   exhausted: ReadonlySet<SubscriptionProvider>,
+  missing: readonly string[],
 ): HttpError {
+  const missingNote = missing.length > 0 ? ` Missing providers: ${missing.join(", ")}.` : "";
   if (exhausted.size > 0) {
     const plans = [...exhausted]
       .map((provider) => SUBSCRIPTION_PLAN_NAMES[provider])
       .join(" and ");
     return new HttpError(
       424,
-      `Every connected ${plans} subscription is at its usage limit, and no API key can serve router ${routerId} instead.`,
+      `Every connected ${plans} subscription is at its usage limit, and no API key can serve router ${routerId} instead.${missingNote}`,
       "personal_subscription_unavailable",
     );
   }
   return new HttpError(
     424,
-    `No credentials can serve router ${routerId}: set a provider API key or connect a subscription.`,
+    `No credentials can serve router ${routerId}.${missingNote} Set each provider's API key or connect a subscription that can serve it.`,
     "provider_credentials_missing",
   );
 }

package/src/self_host/session_pin_store.ts

@@ -0,0 +1,58 @@
+/**
+ * SQLite storage for session pins: the model and thinking level each session
+ * (and each subagent) of a session-pinning router was routed to on its first
+ * turn. Serving a pin refreshes it at most daily; pins unused for longer than
+ * the retention window are no longer served and are deleted.
+ */
+import type { Database } from "bun:sqlite";
+
+import type { SessionPin, SessionPinKey } from "../platform/platform.js";
+
+const RETENTION_MS = 30 * 24 * 60 * 60_000;
+const REFRESH_MS = 24 * 60 * 60_000;
+
+type PinRow = { model: string; reasoning_effort: SessionPin["reasoningEffort"]; updated_at: number };
+
+export class SessionPinStore {
+  constructor(private readonly db: Database) {
+    db.run(`CREATE TABLE IF NOT EXISTS routing_session_pins (
+      router_id TEXT NOT NULL,
+      pin_key TEXT NOT NULL,
+      model TEXT NOT NULL,
+      reasoning_effort TEXT NOT NULL,
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (router_id, pin_key)
+    )`);
+    db.run("CREATE INDEX IF NOT EXISTS ix_routing_session_pins_updated_at ON routing_session_pins (updated_at)");
+  }
+
+  read(key: SessionPinKey, now: Date = new Date()): SessionPin | null {
+    const row = this.db
+      .query<PinRow, [string, string, number]>(
+        `SELECT model, reasoning_effort, updated_at FROM routing_session_pins
+          WHERE router_id = ? AND pin_key = ? AND updated_at >= ?`,
+      )
+      .get(key.routerId, key.pinKey, now.getTime() - RETENTION_MS);
+    if (row === null) return null;
+    if (row.updated_at < now.getTime() - REFRESH_MS) {
+      this.db
+        .query("UPDATE routing_session_pins SET updated_at = ? WHERE router_id = ? AND pin_key = ?")
+        .run(now.getTime(), key.routerId, key.pinKey);
+    }
+    return { model: row.model, reasoningEffort: row.reasoning_effort };
+  }
+
+  write(write: SessionPinKey & SessionPin, now: Date = new Date()): void {
+    this.db.transaction(() => {
+      this.db
+        .query(`INSERT INTO routing_session_pins (router_id, pin_key, model, reasoning_effort, updated_at)
+          VALUES (?, ?, ?, ?, ?)
+          ON CONFLICT (router_id, pin_key) DO UPDATE SET
+            model = excluded.model,
+            reasoning_effort = excluded.reasoning_effort,
+            updated_at = excluded.updated_at`)
+        .run(write.routerId, write.pinKey, write.model, write.reasoningEffort, now.getTime());
+      this.db.query("DELETE FROM routing_session_pins WHERE updated_at < ?").run(now.getTime() - RETENTION_MS);
+    })();
+  }
+}

package/src/strategies/priority_selector.ts

@@ -7,8 +7,7 @@ const PRIORITY_CONTEXT_WINDOW_CHARS = 1_000_000;
 
 /**
  * Serve the router's first eligible model/thinking-level pair, in the order
- * the router lists them. Provider failures still fall back to the next pair
- * when the router enables model fallback.
+ * the router lists them.
  */
 export function createPrioritySelectorBackend(): SelectorBackend {
   return {

package/src/strategies/route_decision.ts

@@ -15,7 +15,6 @@ import type { ResolvedRouter } from "../types.js";
 
 export type RoutedDecision = {
   decision: RoutingDecision;
-  fallbackDecision?: RoutingDecision;
   run?: SelectorRun;
   details?: Record<string, unknown>;
 };
@@ -81,9 +80,6 @@ export async function routeDecision(
       ? { customRules: custom.rules, defaultTarget: custom.defaultTarget }
       : {}),
     selectorBackend: args.selectorBackend,
-    modelFallbackEnabled: credentials.model_fallback_enabled !== false,
-    fallbackRequiresDifferentProvider:
-      credentials.fallback_requires_different_provider !== false,
     executionProviderForModel: (model) =>
       executionProviderForModel(credentials, model),
     imputeEvalScores: credentials.eval_score_imputation === true,
@@ -99,7 +95,6 @@ export async function routeDecision(
   };
   return {
     decision: run.decision,
-    fallbackDecision: run.fallbackDecision,
     run,
     ...(Object.keys(details).length > 0 ? { details } : {}),
   };

package/src/strategies/routing.ts

@@ -34,7 +34,6 @@ import type {
   ProviderAuth,
   ResolvedRouter,
 } from "../types.js";
-import { deriveFallbackDecision } from "./fallback_decision.js";
 import type { SelectorImage } from "./selector_projection.js";
 
 export function resolveRouter(args: ResolveRouterRequest): Promise<ResolvedRouter> {
@@ -54,7 +53,6 @@ export type SelectorTrace = {
 
 export type SelectorRun = SelectorTrace & {
   decision: RoutingDecision;
-  fallbackDecision?: RoutingDecision;
 };
 
 export type SelectModelArgs = {
@@ -70,8 +68,6 @@ export type SelectModelArgs = {
   customRules?: CustomRouterRule[];
   defaultTarget?: CustomDefaultTarget | null;
   sessionId?: string;
-  modelFallbackEnabled?: boolean;
-  fallbackRequiresDifferentProvider?: boolean;
   executionProviderForModel?: (model: string) => string;
   imputeEvalScores?: boolean;
   imputationReferenceEvals?: RouterEval[];
@@ -171,8 +167,6 @@ export async function selectModel(
     contextWindowChars,
     messages: selectorBackend.prepareMessages?.(safeMessages) ?? safeMessages,
     ...(leaseContextEnabled ? { leaseHistory: args.leaseHistory ?? [] } : {}),
-    modelFallbackEnabled: args.modelFallbackEnabled,
-    fallbackRequiresDifferentProvider: args.fallbackRequiresDifferentProvider,
     imputeEvalScores: args.imputeEvalScores,
     imputationReferenceEvals: args.imputationReferenceEvals,
   });
@@ -285,17 +279,7 @@ function validateSelectorRun(run: SelectorRun, args: SelectModelArgs): SelectorR
       run,
     );
   }
-  const { fallbackDecision: _selectorFallback, ...primaryRun } = run;
-  const fallbackDecision = deriveFallbackDecision({
-    candidates: args.candidates,
-    selected,
-    enabled: args.modelFallbackEnabled,
-    requiresDifferentProvider: args.fallbackRequiresDifferentProvider,
-    providerForModel: args.executionProviderForModel,
-  });
-  return fallbackDecision
-    ? { ...primaryRun, fallbackDecision }
-    : primaryRun;
+  return run;
 }
 
 function requiredSelectorConfig(value: string, label: string): string {

package/src/telemetry/billing_finalization.ts

@@ -14,7 +14,9 @@ export type RoutingBillingProviderAttemptFacts = {
   provider: string;
   model: string;
   provider_key_source: ProviderKeySource;
-  role: "primary" | "fallback";
+  // The control-plane billing contract numbers attempts within a role; every
+  // attempt retries the routed choice, so the role is always primary.
+  role: "primary";
   attempt: number;
   outcome: "completed" | "provider_failed" | "customer_canceled";
   provider_request_id: string | null;
@@ -94,7 +96,6 @@ export function routingBillingProviderAttemptFacts(args: {
   provider: string;
   model: string;
   providerKeySource: ProviderKeySource;
-  role: "primary" | "fallback";
   attempt: number;
   outcome: "completed" | "provider_failed" | "customer_canceled";
   providerMessage: Record<string, unknown> | null;
@@ -129,7 +130,7 @@ export function routingBillingProviderAttemptFacts(args: {
     provider: args.provider,
     model: args.model,
     provider_key_source: args.providerKeySource,
-    role: args.role,
+    role: "primary",
     attempt: args.attempt,
     outcome: args.outcome,
     provider_request_id: providerRequestId(args.providerMessage),

package/src/telemetry/prefix_state.ts

@@ -80,15 +80,10 @@ export function buildCompletedPrefixHit(args: {
 export function leaseCountdownForPrefix(args: {
   served: RoutingDecision | null;
   next: RoutingDecision | null;
-  // True when a completed fallback attempt served this turn. A lease-aware
-  // fallback carries the remaining countdown on the serving decision; an
-  // ordinary fallback has no countdown and ends any primary commitment.
-  fallbackServed?: boolean;
 }): number | null {
-  const granted = args.fallbackServed === true ? args.served : args.next ?? args.served;
+  const granted = args.next ?? args.served;
   const remaining = granted?.leaseTurnsRemaining;
   if (remaining === undefined || remaining === null) return null;
-  if (args.fallbackServed === true) return remaining;
   const servedGrantedPair =
     args.next === null ||
     (args.served !== null &&

package/src/telemetry/report.ts

@@ -62,7 +62,6 @@ import {
   buildCompletedPrefixHit,
   leaseCountdownForPrefix,
   prefixEntryForIngest,
-  reportPendingLease,
   reportPrefixState,
 } from "./prefix_state.js";
 import { subscriptionUsageLimitFromFailure } from "../providers/subscription_limits.js";
@@ -149,7 +148,6 @@ export class RequestReporter {
   private selectorOutputAccepted = false;
   private decision: RoutingDecision | null = null;
   private nextDecision: RoutingDecision | null = null;
-  private fallbackDecision: RoutingDecision | null = null;
   private providerAttempts: ProviderAttemptReport[] = [];
   private billingProviderAttempts: RoutingBillingProviderAttemptFacts[] = [];
   private decisionDetails: Record<string, unknown> = {};
@@ -202,7 +200,6 @@ export class RequestReporter {
     this.selectorOutputAccepted = true;
     this.decision = run.decision;
     this.nextDecision = run.decision;
-    this.fallbackDecision = run.fallbackDecision ?? null;
   }
 
   attachSpeculativeSelectorRun(run: SelectorRun, servingDecision: RoutingDecision): void {
@@ -211,7 +208,6 @@ export class RequestReporter {
     this.selectorOutputAccepted = true;
     this.decision = servingDecision;
     this.nextDecision = run.decision;
-    this.fallbackDecision = run.fallbackDecision ?? null;
   }
 
   // Speculative execution can begin before a selector run; its serving
@@ -221,10 +217,6 @@ export class RequestReporter {
     this.nextDecision = decision;
   }
 
-  attachFallbackDecision(decision: RoutingDecision | undefined): void {
-    this.fallbackDecision = decision ?? null;
-  }
-
   attachServingDecision(decision: RoutingDecision): void {
     this.decision = decision;
   }
@@ -239,10 +231,10 @@ export class RequestReporter {
     return modelCost(attempt ? [...this.billingProviderAttempts, this.billingFacts(attempt)] : this.billingProviderAttempts);
   }
 
-  private billingFacts({ execution, message, role, attempt, billingOutcome }: ProviderAttemptRecord): RoutingBillingProviderAttemptFacts {
+  private billingFacts({ execution, message, attempt, billingOutcome }: ProviderAttemptRecord): RoutingBillingProviderAttemptFacts {
     return routingBillingProviderAttemptFacts({
       provider: execution.provider, model: execution.model,
-      providerKeySource: execution.providerKeySource, role, attempt, outcome: billingOutcome,
+      providerKeySource: execution.providerKeySource, attempt, outcome: billingOutcome,
       providerMessage: message, usage: isRecord(message.usage) ? message.usage : null,
       providerPricingKnown: this.pricingKnown(execution.model),
     });
@@ -388,18 +380,8 @@ export class RequestReporter {
       const decision = this.decision;
       const selectedModel = outcome.providerExecution?.model ?? decision?.selectedModel ?? null;
       const reasoningBucket = decision?.reasoningEffort ?? null;
-      // A completed fallback attempt means the intended pair failed this
-      // turn: the next-turn recommendation and any lease countdown follow the
-      // pair that actually served instead of re-pinning the failed one.
-      const fallbackServed = this.providerAttempts.some(
-        (attempt) => attempt.role === "fallback" && attempt.outcome === "completed",
-      );
-      const nextModel = fallbackServed
-        ? selectedModel
-        : this.nextDecision?.selectedModel ?? selectedModel;
-      const nextReasoningEffort = fallbackServed
-        ? reasoningBucket
-        : this.nextDecision?.reasoningEffort ?? reasoningBucket;
+      const nextModel = this.nextDecision?.selectedModel ?? selectedModel;
+      const nextReasoningEffort = this.nextDecision?.reasoningEffort ?? reasoningBucket;
       const selectedProvider = outcome.providerExecution?.provider ?? (selectedModel
         ? executionProviderForModel(a.credentials, selectedModel)
         : null);
@@ -470,7 +452,6 @@ export class RequestReporter {
               leaseTurnsRemaining: leaseCountdownForPrefix({
                 served: decision ?? null,
                 next: this.nextDecision,
-                fallbackServed,
               }),
               reason: this.nextDecision?.reason ?? decision?.reason ?? null,
               chain: selectedChain,
@@ -506,21 +487,6 @@ export class RequestReporter {
       // resolves this turn's conversation id and next-model prediction.
       // The full report below re-applies the same state idempotently, so a
       // lost or timed-out fast write only degrades to the old ordering.
-      // An ordinary fallback breaks any lease commitment, prefetched ones
-      // included. A lease-aware fallback transfers the active countdown to
-      // the serving pair, so only clear pending state when no countdown was
-      // transferred. The depth fence orders the clear safely against
-      // in-flight prefetch writes.
-      if (!backgroundRequest && fallbackServed && decision?.leaseTurnsRemaining === undefined) {
-        trackBackgroundTelemetry(
-          reportPendingLease({
-            routerId: a.routerId,
-            conversationId: a.conversationId,
-            decidedAtDepth: a.leaseDepth,
-            lease: null,
-          }),
-        );
-      }
       if (prefixEntry !== null || touchedHash !== null) {
         this.prefixStatePromise = reportPrefixState({
           organization_id: a.credentials.organization_id,
@@ -592,13 +558,6 @@ export class RequestReporter {
           strategy: a.strategy,
           selected_reasoning_effort: reasoningBucket,
           next_reasoning_effort: nextReasoningEffort,
-          ...(this.fallbackDecision
-            ? {
-                fallback_model: this.fallbackDecision.selectedModel,
-                fallback_reasoning_effort:
-                  this.fallbackDecision.reasoningEffort,
-              }
-            : {}),
           ...(this.providerAttempts.length > 0
             ? { provider_attempts: this.providerAttempts }
             : {}),
@@ -662,9 +621,6 @@ export class RequestReporter {
           selected_reasoning_effort: reasoningBucket,
           next_model: nextModel,
           next_reasoning_effort: nextReasoningEffort,
-          fallback_model: this.fallbackDecision?.selectedModel ?? null,
-          fallback_reasoning_effort:
-            this.fallbackDecision?.reasoningEffort ?? null,
           provider_key_source: keySource,
           message_count: observability.messageCount,
           tool_count: observability.metadata.declared_tool_counts.total,

package/src/types.ts

@@ -6,6 +6,7 @@ import type {
   RouterEvalScore,
   RouterModelPrice,
   RouterPrefixHit,
+  RoutingDecision,
   RoutingStrategy,
 } from "@mupt-ai/dari-router/policy-engine";
 // The router resolution contract between the gateway runtime and its
@@ -83,6 +84,10 @@ export type PublicEvalCatalogCard = Omit<RouterEval, "scores"> & {
   scores: PublicEvalCatalogScore[];
 };
 
+// A decision as served: session-pinned decisions say so in response headers
+// and Anthropic routing metadata.
+export type ServedDecision = RoutingDecision & { sessionPinned?: boolean };
+
 export type ClientHarness = "claude_code" | "muse_code";
 
 export type ResolvedRouterModelConfig = {
@@ -122,17 +127,18 @@ export type ResolvedRouter = {
   zdr?: boolean;
   allow_long_context?: boolean;
   speculative_routing?: boolean;
+  // Route each session's (and each subagent's) first turn, then serve that
+  // pair for the rest of the session instead of selecting or leasing.
+  session_pinning?: boolean;
   primary_retries?: number;
   // Serve only the requested `dari/model/<id>` at the requested thinking
-  // level: no selector, lease, fallback, or personal subscription the
-  // platform did not supply through resolveProviderCredential, and an error
-  // for anything else, whatever the client sends.
+  // level: no selector, lease, or personal subscription the platform did not
+  // supply through resolveProviderCredential, and an error for anything
+  // else, whatever the client sends.
   strict?: boolean;
   // On strict routers only, allow requested catalog models of these providers.
-  // Requires dari/model/<provider>/<id>; never enables fallback.
+  // Requires dari/model/<provider>/<id>.
   strict_providers?: string[];
-  model_fallback_enabled?: boolean;
-  fallback_requires_different_provider?: boolean;
   evals?: RouterEval[];
   // When true, fill missing eval scores using thinking-level ratios or an
   // explicitly mapped predecessor model.

package/dist/strategies/fallback_decision.d.ts

@@ -1,8 +0,0 @@
-import { type RoutingCandidate, type RoutingDecision } from "@mupt-ai/dari-router/policy-engine";
-export declare function deriveFallbackDecision(args: {
-    candidates: RoutingCandidate[];
-    selected: RoutingCandidate;
-    enabled?: boolean;
-    requiresDifferentProvider?: boolean;
-    providerForModel?: (model: string) => string;
-}): RoutingDecision | undefined;

package/dist/strategies/fallback_decision.js

@@ -1,17 +0,0 @@
-import { providerForModel, } from "@mupt-ai/dari-router/policy-engine";
-export function deriveFallbackDecision(args) {
-    if (!args.enabled)
-        return undefined;
-    const resolveProvider = args.providerForModel ?? providerForModel;
-    const selectedProvider = resolveProvider(args.selected.model);
-    const fallback = args.candidates.find((candidate) => candidate.model !== args.selected.model &&
-        (!args.requiresDifferentProvider ||
-            resolveProvider(candidate.model) !== selectedProvider));
-    return fallback
-        ? {
-            selectedModel: fallback.model,
-            reasoningEffort: fallback.reasoningEffort,
-            reason: "Runtime-selected fallback for the routed primary decision.",
-        }
-        : undefined;
-}

package/src/strategies/fallback_decision.ts

@@ -1,30 +0,0 @@
-import {
-  providerForModel,
-  type RoutingCandidate,
-  type RoutingDecision,
-} from "@mupt-ai/dari-router/policy-engine";
-
-export function deriveFallbackDecision(args: {
-  candidates: RoutingCandidate[];
-  selected: RoutingCandidate;
-  enabled?: boolean;
-  requiresDifferentProvider?: boolean;
-  providerForModel?: (model: string) => string;
-}): RoutingDecision | undefined {
-  if (!args.enabled) return undefined;
-  const resolveProvider = args.providerForModel ?? providerForModel;
-  const selectedProvider = resolveProvider(args.selected.model);
-  const fallback = args.candidates.find(
-    (candidate) =>
-      candidate.model !== args.selected.model &&
-      (!args.requiresDifferentProvider ||
-        resolveProvider(candidate.model) !== selectedProvider),
-  );
-  return fallback
-    ? {
-        selectedModel: fallback.model,
-        reasoningEffort: fallback.reasoningEffort,
-        reason: "Runtime-selected fallback for the routed primary decision.",
-      }
-    : undefined;
-}