@mupt-ai/dari-gateway 0.3.1 → 0.3.2

package/src/runtime/harness_identity/extract.ts

@@ -14,11 +14,10 @@ export function chatCompletionsConversationIdentity(
   headers: Headers,
   promptCacheKey?: string,
 ): HarnessConversationIdentity | undefined {
-  // x-session-affinity is the authoritative Chat Completions identity.
-  // Fall back to prompt_cache_key from the request body for callers that
-  // send a stable cache key without the affinity header, so append-only
-  // sessions (growing message history) stay grouped under one conversation.
-  const sessionId = boundedIdentity(
+  // Pi summaries use fresh cache/affinity IDs. Its explicit session header
+  // groups them with the main turns without changing provider cache affinity.
+  // Other callers use x-session-affinity, falling back to prompt_cache_key.
+  const sessionId = boundedIdentity(headers.get("x-pi-session-id"), "x-pi-session-id") ?? boundedIdentity(
     headers.get("x-session-affinity"),
     "x-session-affinity",
   ) ?? boundedIdentity(promptCacheKey, "prompt_cache_key");
@@ -34,6 +33,16 @@ export function chatCompletionsConversationIdentity(
   };
 }
 
+export function piRequestContext(headers: Headers): AgentRequestContext | undefined {
+  if (boundedIdentity(headers.get("x-pi-session-id"), "x-pi-session-id") === undefined) {
+    return undefined;
+  }
+  const kind = headers.get("x-pi-request-kind")?.trim();
+  return {
+    requestClass: kind === "turn" ? "main" : kind === "compaction" ? "compaction" : "unknown",
+  };
+}
+
 // OpenCode names the session behind every request, and a subagent's parent
 // session too. The `dari opencode` plugin adds the request kind and agent,
 // which OpenCode does not send itself. Like Claude Code's headers, these are

package/src/runtime/harness_identity/index.ts

@@ -1,4 +1,5 @@
 export {
+  scopedHarnessAgentId,
   scopedHarnessConversationId,
   scopedHarnessSessionId,
   type HarnessConversationIdentity,
@@ -11,4 +12,5 @@ export {
   codexRequestPurpose,
   codexRequestContext,
   openCodeRequestContext,
+  piRequestContext,
 } from "./extract.js";

package/src/runtime/prepare_routed_completion.ts

@@ -10,7 +10,8 @@ import {
 import { isBackgroundRequest, type InteractionRequest } from "../interaction/types.js";
 import { executionProviderForModel } from "../models/execution_provider.js";
 import { codexModelConfig, subscriptionServes } from "../models/subscriptions.js";
-import { gatewayPlatform, type RequestTags } from "../platform/platform.js";
+import { explicitModelId } from "../protocol/input/router_model.js";
+import { gatewayPlatform, type RequestTags, type SessionPin } from "../platform/platform.js";
 import { resolveRouter } from "../strategies/routing.js";
 import { RequestReporter, type ReportedCandidatePruning } from "../telemetry/report.js";
 import { RoutingBillingFinalization } from "../telemetry/billing_finalization.js";
@@ -20,6 +21,7 @@ import { strictProviderAccess } from "./strict_provider_access.js";
 import type { RoutedRuntimeReporter } from "./runtime_reporter.js";
 import type { RoutedProtocol } from "./routed_protocol.js";
 import {
+  scopedHarnessAgentId,
   scopedHarnessConversationId,
   scopedHarnessSessionId,
   type HarnessConversationIdentity,
@@ -36,6 +38,9 @@ export type PreparedRoutedCompletion = {
   tags: RequestTags;
   harnessConversationIdentity?: HarnessConversationIdentity;
   routing: RoutingContext;
+  // Present when this request is served by session pinning: the session's
+  // pin key and the pair it pinned, null before its first routed turn.
+  sessionPin?: { key: string; pin: SessionPin | null };
   reporter: RoutedRuntimeReporter;
 };
 
@@ -140,6 +145,30 @@ export async function prepareRoutedCompletion(args: {
     receivedAt: args.receivedAt,
   });
   const candidateResolution = routing.candidateResolution;
+  let sessionPin: PreparedRoutedCompletion["sessionPin"];
+  if (
+    credentials.session_pinning === true &&
+    credentials.strict !== true &&
+    !background &&
+    explicitModelId(args.interaction.model) === null
+  ) {
+    // Harness identity keys the main agent and each subagent separately and
+    // survives compaction. Claude Code names its subagents only with gateway
+    // hint headers; without them, and for callers with no harness identity,
+    // each conversation is pinned on its own.
+    const identity = args.harnessConversationIdentity;
+    const unclassifiedClaudeCode = identity?.kind === "claude_code_session"
+      && args.interaction.agentContext?.requestClass === "unknown";
+    const key = identity === undefined || unclassifiedClaudeCode
+      ? routing.conversationId
+      : scopedHarnessAgentId({
+          identity,
+          sourceProtocol: args.interaction.sourceProtocol,
+          scope: harnessScope,
+        });
+    const pin = await gatewayPlatform().readSessionPin({ routerId: canonicalRouterId, pinKey: key });
+    sessionPin = { key, pin };
+  }
   const reporter = new RequestReporter({
     requestId: args.requestId,
     clientRequestId: args.clientRequestId,
@@ -184,12 +213,13 @@ export async function prepareRoutedCompletion(args: {
     tags,
     harnessConversationIdentity: args.harnessConversationIdentity,
     routing,
+    ...(sessionPin === undefined ? {} : { sessionPin }),
     reporter,
   };
 }
 
 // Ask the platform for each enabled model's credential up front, so provider
-// execution and fallback stay synchronous.
+// execution stays synchronous.
 async function withProviderCredentials(
   credentials: ResolvedRouter,
   apiKey: string,

package/src/runtime/routed_runtime.ts

@@ -39,7 +39,6 @@ import { auxiliaryDecision } from "./claude_code/auxiliary_routing.js";
 import { explicitModelDecision, strictModelDecision } from "./explicit_model.js";
 import {
   clearPendingLease,
-  committedLeaseDecision,
   leaseHoldDecision,
   leasePrefetchDue,
   leasedDecision,
@@ -47,6 +46,7 @@ import {
   prefetchNextLease,
   selectorNegotiatesLeases,
 } from "./routing_lease.js";
+import { pinSession, sessionPinHoldDecision, sessionPinnedSelection } from "./session_pin.js";
 import type { RoutedProtocol } from "./routed_protocol.js";
 import {
   createExperimentRoutedRuntimeReporter,
@@ -69,7 +69,6 @@ type SpeculativeExecution = {
 type RuntimeExecutionPlan = {
   primary: ProviderChoice;
   primaryRetries: number;
-  resolveFallback: () => Promise<ProviderChoice | null>;
   reportBarrier?: Promise<unknown>;
   startedCompletion?: StartedCompletion;
   startedStream?: StartedStream;
@@ -137,7 +136,6 @@ export async function runPreparedRoutedCompletion(args: {
       interaction: prepared.interaction,
       primary: plan.primary,
       primaryRetries: plan.primaryRetries,
-      resolveFallback: plan.resolveFallback,
       reporter: prepared.reporter,
       protocol: prepared.protocol,
       startedCompletion: plan.startedCompletion,
@@ -150,7 +148,6 @@ export async function runPreparedRoutedCompletion(args: {
     interaction: prepared.interaction,
     primary: plan.primary,
     primaryRetries: plan.primaryRetries,
-    resolveFallback: plan.resolveFallback,
     reporter: prepared.reporter,
     startedStream: plan.startedStream,
     initialError: plan.initialStreamError,
@@ -191,7 +188,6 @@ export async function runPreparedRoutedInteraction(args: {
     interaction: args.prepared.interaction,
     primary: plan.primary,
     primaryRetries: plan.primaryRetries,
-    resolveFallback: plan.resolveFallback,
     reporter: args.prepared.reporter,
     protocol: args.prepared.protocol,
     startedCompletion: plan.startedCompletion,
@@ -253,8 +249,7 @@ async function prepareRuntimeExecution(args: {
 }): Promise<RuntimeExecutionPlan> {
   const { prepared } = args;
 
-  // A strict router never selects, leases, or falls back: the pinned pair or
-  // an error.
+  // A strict router never selects or leases: the pinned pair or an error.
   if (prepared.credentials.strict === true) {
     const pinned = strictModelDecision(prepared);
     prepared.reporter.attachServingDecision(pinned.decision);
@@ -298,14 +293,20 @@ async function prepareRuntimeExecution(args: {
     return selectedExecutionPlan(prepared, auxiliary);
   }
 
+  // A session-pinning router serves the session's pin, or selects once and
+  // pins the result. Leases and speculation never apply to a pinned session.
+  if (prepared.sessionPin !== undefined && !args.requireSelectorDecision) {
+    return selectedExecutionPlan(
+      prepared,
+      await sessionPinnedDecision(prepared, args.selectorBackend),
+    );
+  }
+
   // Persisted policy leases (negotiated {action, turns}) take precedence.
   // Explicit in-process runs are selector experiments: they must observe the
   // selector and must not consume or prefetch live conversations' leases.
   const held = args.requireSelectorDecision ? null : leaseHoldDecision(prepared);
   if (held) {
-    // Serving-only attach: nextDecision stays unset so if a fallback serves
-    // this turn, execution's attachServingDecision moves both the prefix's
-    // next_model and inherited countdown onto the healthy serving pair.
     prepared.reporter.attachServingDecision(held);
     prepared.reporter.attachDecisionDetails({
       decision_source: "lease_hold",
@@ -324,7 +325,7 @@ async function prepareRuntimeExecution(args: {
     if (leasePrefetchDue(prepared)) {
       trackBackgroundTelemetry(prefetchNextLease(prepared, args.selectorBackend));
     }
-    return selectedExecutionPlan(prepared, committedLeaseDecision(prepared, held));
+    return selectedExecutionPlan(prepared, { decision: held });
   }
   const adopted = args.requireSelectorDecision ? null : pendingLeaseDecision(prepared);
   if (adopted) {
@@ -349,7 +350,7 @@ async function prepareRuntimeExecution(args: {
     // wait elapses, the next lease's own prefetch overwrites the stale rows
     // before its expiry (the menu's shortest lease exceeds the lag).
     await clearPendingLease(prepared);
-    return selectedExecutionPlan(prepared, committedLeaseDecision(prepared, adopted));
+    return selectedExecutionPlan(prepared, { decision: adopted });
   }
 
   // The stateless ten-turn hold covers per-turn policies. A lease-negotiating
@@ -380,7 +381,6 @@ async function prepareRuntimeExecution(args: {
   const primary: ProviderChoice = {
     decision: speculative.decision,
     execution: speculative.execution,
-    role: "primary",
   };
   const selectionPromise = selectDecision(
     prepared,
@@ -390,23 +390,13 @@ async function prepareRuntimeExecution(args: {
   );
   // The execution layer awaits selection as its report barrier only after the
   // provider settles, which can be long after a rejection. Mark the promise
-  // handled now; fallback still consumes the original and its rejection.
+  // handled now; the report barrier still observes the original rejection.
   selectionPromise.catch(() => undefined);
-  let fallbackPromise: Promise<ProviderChoice | null> | null = null;
-  const resolveFallback = (): Promise<ProviderChoice | null> => {
-    fallbackPromise ??= selectionPromise.then((selected) => {
-      const decision = fallbackForPrimary(prepared, primary.decision, selected);
-      if (decision) prepared.reporter.attachFallbackDecision(decision);
-      return decision ? providerChoice(prepared, decision, "fallback") : null;
-    });
-    return fallbackPromise;
-  };
   return {
     primary,
     primaryRetries: configuredPrimaryRetries(
       prepared.credentials.primary_retries,
     ),
-    resolveFallback,
     reportBarrier: selectionPromise,
     startedCompletion:
       speculative.transport === "completion" ? speculative.started : undefined,
@@ -424,20 +414,10 @@ function selectedExecutionPlan(
   selected: RoutedDecision,
 ): RuntimeExecutionPlan {
   return {
-    primary: providerChoice(prepared, selected.decision, "primary"),
+    primary: providerChoice(prepared, selected.decision),
     primaryRetries: configuredPrimaryRetries(
       prepared.credentials.primary_retries,
     ),
-    resolveFallback: async () => {
-      if (!selected.fallbackDecision) return null;
-      const fallbackDecision = selected.decision.leaseTurnsRemaining === undefined
-        ? selected.fallbackDecision
-        : {
-            ...selected.fallbackDecision,
-            leaseTurnsRemaining: selected.decision.leaseTurnsRemaining,
-          };
-      return providerChoice(prepared, fallbackDecision, "fallback");
-    },
   };
 }
 
@@ -503,6 +483,28 @@ async function startSpeculativeExecution(
   }
 }
 
+async function sessionPinnedDecision(
+  prepared: PreparedRoutedCompletion,
+  selectorBackend: SelectorBackend,
+): Promise<RoutedDecision> {
+  const held = sessionPinHoldDecision(prepared);
+  if (held) {
+    prepared.reporter.attachDecision(held);
+    prepared.reporter.attachDecisionDetails({
+      decision_source: "session_pin",
+      session_pin: { model: held.selectedModel, reasoning_effort: held.reasoningEffort },
+    });
+    return { decision: held };
+  }
+  const selected = await selectDecision(prepared, null, selectorBackend);
+  prepared.reporter.attachDecisionDetails({
+    decision_source: "selector",
+    session_pin_established: true,
+  });
+  await pinSession(prepared, selected.decision);
+  return selected;
+}
+
 async function selectDecision(
   prepared: PreparedRoutedCompletion,
   servingDecision: RoutingDecision | null,
@@ -511,7 +513,7 @@ async function selectDecision(
 ): Promise<RoutedDecision> {
   const { credentials, reporter, routing } = prepared;
   try {
-    const routed = await routeDecision({
+    const selected = await routeDecision({
       selectorMessages: routing.selectorMessages,
       selectorImages: routing.selectorImages,
       resolution: routing.candidateResolution,
@@ -521,6 +523,7 @@ async function selectDecision(
       selectorBackend,
       leaseHistory: routing.leaseHistory,
     });
+    const routed = prepared.sessionPin === undefined ? selected : sessionPinnedSelection(selected);
     if (routed.details) reporter.attachDecisionDetails(routed.details);
     if (servingDecision) {
       if (!routed.run) {
@@ -544,7 +547,6 @@ async function selectDecision(
       reporter.attachSelectorRun(routed.run);
     } else {
       reporter.attachDecision(routed.decision);
-      reporter.attachFallbackDecision(routed.fallbackDecision);
     }
     return routed;
   } catch (error) {
@@ -592,35 +594,13 @@ function configuredPrimaryRetries(value: number | undefined): number {
   return Number.isInteger(retries) && retries >= 0 && retries <= 5 ? retries : 1;
 }
 
-function fallbackForPrimary(
-  prepared: PreparedRoutedCompletion,
-  primary: RoutingDecision,
-  selected: RoutedDecision,
-): RoutingDecision | undefined {
-  if (prepared.credentials.model_fallback_enabled === false) return undefined;
-  const fallback = [selected.fallbackDecision, selected.decision].find(
-    (candidate): candidate is RoutingDecision =>
-      candidate !== undefined &&
-      candidate.selectedModel !== primary.selectedModel,
-  );
-  if (!fallback || selected.decision.leaseTurnsRemaining === undefined) {
-    return fallback;
-  }
-  return {
-    ...fallback,
-    leaseTurnsRemaining: selected.decision.leaseTurnsRemaining,
-  };
-}
-
 function providerChoice(
   prepared: PreparedRoutedCompletion,
   decision: RoutingDecision,
-  role: ProviderChoice["role"],
 ): ProviderChoice {
   return {
     decision,
     execution: providerExecution(prepared, decision),
-    role,
   };
 }
 

package/src/runtime/routing_lease.ts

@@ -6,8 +6,6 @@ import {
   type RoutingDecision,
 } from "@mupt-ai/dari-router/policy-engine";
 
-import { deriveFallbackDecision } from "../strategies/fallback_decision.js";
-import { executionProviderForModel } from "../models/execution_provider.js";
 import type { SelectorBackend } from "../strategies/routing.js";
 import {
   routeDecision,
@@ -71,17 +69,7 @@ export function leasedDecision(
   // incumbent cannot hide an available user-owned key behind the lease.
   if (prepared.billable && prepared.credentials.credit_exhausted) return null;
 
-  const fallbackDecision = leaseFallbackDecision({
-    candidates: prepared.routing.candidateResolution.candidates,
-    decision: lease.decision,
-    credentials: prepared.credentials,
-  });
-  // Use attachServingDecision rather than attachDecision so next_model
-  // follows the model that actually serves. When fallback handles a primary
-  // failure, it inherits this countdown and subsequent held turns continue
-  // on the healthy serving pair instead of retrying the failed primary.
   prepared.reporter.attachServingDecision(lease.decision);
-  prepared.reporter.attachFallbackDecision(fallbackDecision);
   prepared.reporter.attachDecisionDetails({
     decision_source: "lease_hold",
     routing_lease: {
@@ -90,49 +78,7 @@ export function leasedDecision(
       turn_in_lease: lease.turnInLease,
     },
   });
-  return { decision: lease.decision, fallbackDecision };
-}
-
-// Wraps a lease-held (or adopted) decision with a runtime-derived fallback so
-// a mid-lease provider failure degrades like any other turn instead of
-// erroring the request. The fallback inherits the remaining commitment so the
-// completed prefix follows the healthy serving pair for the rest of the lease.
-export function committedLeaseDecision(
-  prepared: PreparedRoutedCompletion,
-  decision: RoutingDecision,
-): RoutedDecision {
-  const fallbackDecision = leaseFallbackDecision({
-    candidates: prepared.routing.candidateResolution.candidates,
-    decision,
-    credentials: prepared.credentials,
-  });
-  if (fallbackDecision) prepared.reporter.attachFallbackDecision(fallbackDecision);
-  return fallbackDecision ? { decision, fallbackDecision } : { decision };
-}
-
-export function leaseFallbackDecision(args: {
-  candidates: PreparedRoutedCompletion["routing"]["candidateResolution"]["candidates"];
-  decision: RoutingDecision;
-  credentials: PreparedRoutedCompletion["credentials"];
-}): RoutingDecision | undefined {
-  const fallback = deriveFallbackDecision({
-    candidates: args.candidates,
-    selected: {
-      model: args.decision.selectedModel,
-      reasoningEffort: args.decision.reasoningEffort,
-    },
-    enabled: args.credentials.model_fallback_enabled !== false,
-    requiresDifferentProvider:
-      args.credentials.fallback_requires_different_provider !== false,
-    providerForModel: (model) => executionProviderForModel(args.credentials, model),
-  });
-  if (!fallback || args.decision.leaseTurnsRemaining === undefined) {
-    return fallback;
-  }
-  return {
-    ...fallback,
-    leaseTurnsRemaining: args.decision.leaseTurnsRemaining,
-  };
+  return { decision: lease.decision };
 }
 
 export async function selectorNegotiatesLeases(
@@ -220,7 +166,7 @@ export async function clearPendingLease(
   );
 }
 
-function canServeCommittedPair(
+export function canServeCommittedPair(
   prepared: PreparedRoutedCompletion,
   pair: { model: string; reasoningEffort: string },
 ): boolean {

package/src/runtime/runtime_reporter.ts

@@ -46,7 +46,6 @@ export type ReportableProviderOutcome =
 export type ProviderAttemptReport = {
   model: string;
   reasoning_effort: string;
-  role: "primary" | "fallback";
   attempt: number;
   outcome: "completed" | "error" | "terminal_error" | "canceled";
 };
@@ -65,7 +64,6 @@ export type RoutedRuntimeReporter = {
   attachSelectorRun(run: SelectorRun): void;
   attachSpeculativeSelectorRun(run: SelectorRun, servingDecision: RoutingDecision): void;
   attachDecision(decision: RoutingDecision): void;
-  attachFallbackDecision(decision: RoutingDecision | undefined): void;
   attachServingDecision(decision: RoutingDecision): void;
   recordProviderAttempt(attempt: ProviderAttemptRecord): void;
   modelCost(attempt?: ProviderAttemptRecord): number | null;
@@ -94,7 +92,6 @@ export function createExperimentRoutedRuntimeReporter(): ExperimentRoutedRuntime
     attachSelectorRun() {},
     attachSpeculativeSelectorRun() {},
     attachDecision() {},
-    attachFallbackDecision() {},
     attachServingDecision() {},
     recordProviderAttempt() {},
     modelCost() { return null; },

package/src/runtime/session_pin.ts

@@ -0,0 +1,61 @@
+import type { RoutingDecision } from "@mupt-ai/dari-router/policy-engine";
+
+import { gatewayPlatform } from "../platform/platform.js";
+import type { RoutedDecision } from "../strategies/route_decision.js";
+import type { ServedDecision } from "../types.js";
+import type { PreparedRoutedCompletion } from "./prepare_routed_completion.js";
+import { canServeCommittedPair } from "./routing_lease.js";
+
+// The session's pinned pair, while this request may still serve it. A pin
+// that can no longer serve (model disabled, credits exhausted, image input on
+// a text-only model) falls through to selection, which moves the pin.
+export function sessionPinHoldDecision(
+  prepared: PreparedRoutedCompletion,
+): ServedDecision | null {
+  const pin = prepared.sessionPin?.pin;
+  if (pin === null || pin === undefined) return null;
+  if (!canServeCommittedPair(prepared, pin)) return null;
+  return {
+    selectedModel: pin.model,
+    reasoningEffort: pin.reasoningEffort,
+    reason: `Session pin: ${pin.model}/${pin.reasoningEffort} serves this whole session.`,
+    sessionPinned: true,
+  };
+}
+
+// A pinned session never holds leases: the pin outlives any countdown.
+export function sessionPinnedSelection(routed: RoutedDecision): RoutedDecision {
+  const pinned = (decision: RoutingDecision): ServedDecision => ({ ...unleased(decision), sessionPinned: true });
+  return {
+    ...routed,
+    decision: pinned(routed.decision),
+    ...(routed.run === undefined ? {} : { run: { ...routed.run, decision: pinned(routed.run.decision) } }),
+  };
+}
+
+function unleased(decision: RoutingDecision): RoutingDecision {
+  const { leaseTurnsRemaining: _, ...rest } = decision;
+  return rest;
+}
+
+// A failed write only costs the pin: the next turn selects again.
+export async function pinSession(
+  prepared: PreparedRoutedCompletion,
+  decision: RoutingDecision,
+): Promise<void> {
+  if (prepared.sessionPin === undefined) return;
+  const pin = { model: decision.selectedModel, reasoningEffort: decision.reasoningEffort };
+  try {
+    await gatewayPlatform().writeSessionPin({
+      routerId: prepared.routerId,
+      pinKey: prepared.sessionPin.key,
+      ...pin,
+    });
+  } catch (error) {
+    gatewayPlatform().captureOperationalError(error, {
+      code: "session_pin_write_failed",
+      requestId: prepared.requestId,
+      routerId: prepared.routerId,
+    });
+  }
+}

package/src/self_host/config.ts

@@ -14,8 +14,8 @@ import {
  *       - anthropic/claude-sonnet-5-5
  *       - id: openai/gpt-5.5
  *         thinking: [medium, high]
- *     fallback: true        # retry on the next model when a provider fails
  *     subscriptions: true   # serve with connected Claude Code / ChatGPT plans
+ *     sessionPinning: false # route each session and subagent once, then keep its model
  * providers:                # optional: OpenAI-compatible or self-run endpoints
  *   local:
  *     baseUrl: http://localhost:8000/v1
@@ -44,10 +44,9 @@ export type ProviderEndpointConfig = {
 
 export type RouterConfig = {
   models: RouterModelConfig[];
-  fallback: boolean;
-  fallbackRequiresDifferentProvider: boolean;
   retries: number;
   subscriptions: boolean;
+  sessionPinning: boolean;
   zdr: boolean;
 };
 
@@ -129,11 +128,9 @@ function parseRouter(id: string, raw: unknown): RouterConfig {
   }
   return {
     models,
-    fallback: optionalBoolean(raw.fallback, `routers.${id}.fallback`) ?? true,
-    fallbackRequiresDifferentProvider:
-      optionalBoolean(raw.fallbackRequiresDifferentProvider, `routers.${id}.fallbackRequiresDifferentProvider`) ?? false,
     retries: optionalRetries(raw.retries, `routers.${id}.retries`) ?? 1,
     subscriptions: optionalBoolean(raw.subscriptions, `routers.${id}.subscriptions`) ?? true,
+    sessionPinning: optionalBoolean(raw.sessionPinning, `routers.${id}.sessionPinning`) ?? false,
     zdr: optionalBoolean(raw.zdr, `routers.${id}.zdr`) ?? false,
   };
 }

package/src/self_host/main.ts

@@ -12,8 +12,9 @@ import { createPrioritySelectorBackend } from "../strategies/priority_selector.j
 import type { SelectorBackend } from "../strategies/routing.js";
 import { loadGatewayConfig } from "./config.js";
 import { createSelfHostedPlatform } from "./platform.js";
-import { gatewayKeyIndex } from "./resolve.js";
+import { gatewayKeyIndex, providersWithoutCredentials } from "./resolve.js";
 import { PrefixStore } from "./prefix_store.js";
+import { SessionPinStore } from "./session_pin_store.js";
 import { handleSubscriptionRequest, SubscriptionStore } from "./subscriptions/index.js";
 
 const SUBSCRIPTION_ROUTES = "/v1/organizations/current/credentials";
@@ -27,7 +28,8 @@ const SUBSCRIPTION_ROUTES = "/v1/organizations/current/credentials";
  *   state (default `dari-gateway.db`). It holds subscription tokens.
  * - `DARI_AUTO_ROUTING_API_KEY`: choose among a router's models with Dari
  *   Auto Routing; without it, `dari/routing` serves the first listed model.
- * - `PORT` (default 8080), and each provider's standard API key variable.
+ * - `PORT` (default 8080), `DARI_GATEWAY_HOST` (default 127.0.0.1; the container
+ *   image sets 0.0.0.0), and each provider's standard API key variable.
  */
 export async function startSelfHostedGateway(env: Record<string, string> = process.env as Record<string, string>) {
   const gatewayKeys = (env.DARI_GATEWAY_KEYS ?? "")
@@ -45,21 +47,35 @@ export async function startSelfHostedGateway(env: Record<string, string> = proce
   db.exec("PRAGMA journal_mode = WAL");
   const subscriptions = new SubscriptionStore(db);
   const prefixes = new PrefixStore(db);
+  const sessionPins = new SessionPinStore(db);
   // Pi's provider auth reads each provider's standard key variable, such as
   // OPENAI_API_KEY, from this environment only.
   const piModels = builtinModels({
     authContext: { env: async (name) => env[name], fileExists: async () => false },
   });
 
+  const providerApiKey = async (provider: string) => (await piModels.getAuth(provider))?.auth.apiKey;
   const platform = createSelfHostedPlatform({
     config,
     gatewayKeys,
     subscriptions,
     prefixes,
-    providerApiKey: async (provider) => (await piModels.getAuth(provider))?.auth.apiKey,
+    sessionPins,
+    providerApiKey,
     env,
     fetch,
   });
+  // A model without a credential is dropped at request time, so a missing key
+  // would otherwise surface only as a 424 on the first request.
+  for (const [routerId, router] of Object.entries(config.routers)) {
+    const missing = await providersWithoutCredentials({ config, subscriptions, providerApiKey, env }, router);
+    if (missing.length > 0) {
+      console.warn(
+        "dari-gateway router has providers without credentials; their models are not served",
+        JSON.stringify({ router: routerId, providers: missing }),
+      );
+    }
+  }
   const autoRoutingKey = env.DARI_AUTO_ROUTING_API_KEY?.trim();
   const selectorBackend: SelectorBackend = autoRoutingKey
     ? createAutoRoutingSelectorBackend({
@@ -86,10 +102,13 @@ export async function startSelfHostedGateway(env: Record<string, string> = proce
   };
 
   const port = Number(env.PORT ?? "8080");
-  const server = startServer(port, handler);
+  // Loopback unless DARI_GATEWAY_HOST says otherwise (see the doc comment).
+  const hostname = (env.DARI_GATEWAY_HOST ?? "").trim() || "127.0.0.1";
+  const server = startServer(port, handler, { hostname });
   console.info(
     "dari-gateway listening",
     JSON.stringify({
+      hostname,
       port,
       routers: Object.keys(config.routers),
       auto_routing: autoRoutingKey ? "dari" : "priority",

package/src/self_host/platform.ts

@@ -1,16 +1,18 @@
 import { errorCode } from "../http/errors.js";
 import type { GatewayPlatform } from "../platform/platform.js";
 import type { PrefixStore } from "./prefix_store.js";
+import type { SessionPinStore } from "./session_pin_store.js";
 import { resolveSelfHostedRouter, type SelfHostedResolverDeps } from "./resolve.js";
 import type { SubscriptionStore } from "./subscriptions/index.js";
 
 /**
- * The self-hosted platform: routers from the config file, subscriptions and
- * prefix-cache state in the gateway's SQLite database, and one content-free
+ * The self-hosted platform: routers from the config file, subscriptions,
+ * prefix-cache state, and session pins in the gateway's SQLite database, and one content-free
  * log line per request.
  */
 export function createSelfHostedPlatform(deps: Omit<SelfHostedResolverDeps, "prefixHits"> & {
   prefixes: PrefixStore;
+  sessionPins: SessionPinStore;
   subscriptions: SubscriptionStore;
 }): GatewayPlatform {
   const resolver: SelfHostedResolverDeps = {
@@ -25,6 +27,10 @@ export function createSelfHostedPlatform(deps: Omit<SelfHostedResolverDeps, "pre
     writePendingLease: async (write) => {
       deps.prefixes.writePendingLease(write, deps.config.routers[write.router_id]?.zdr ?? false);
     },
+    readSessionPin: async (key) => deps.sessionPins.read(key),
+    writeSessionPin: async (write) => {
+      deps.sessionPins.write(write);
+    },
     markSubscriptionUnavailable: async (hold) =>
       hold.credentialId !== undefined &&
       deps.subscriptions.markUnavailable(hold.credentialId, hold.limit.resetsAt, hold.limit.reason),