@desplega.ai/agent-swarm 1.159.0 → 1.161.0

package/src/utils/credentials.ts

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import { deriveDefaultRoute, routeCredentialStatus } from "@desplega/model-routing";
 import { type ModelFamily, modelFamilyOf, windowForModelFamily } from "./model-rate-limit-windows";
 
 /** Env vars that may contain comma-separated credential pools */
@@ -113,8 +114,12 @@ export interface CredentialSelection {
   modelBlockedIndices?: number[];
   /** ISO of the earliest reset among modelBlockedIndices, or null/undefined when none. */
   earliestModelResetAt?: string | null;
+  /** Indices excluded because the key's subscription plan cannot run the requested model. */
+  seatBlockedIndices?: number[];
   /** Subscription plan id detected on the credential (`SUBSCRIPTION_PLANS`), reported with its usage. */
   plan?: string | null;
+  /** `authFailureFence` from `GET /api/keys/available`, read before the task (Codex pool only). */
+  authFailureFence?: number;
 }
 
 const MODEL_LABELS: Record<ModelFamily, string> = {
@@ -126,33 +131,49 @@ const MODEL_LABELS: Record<ModelFamily, string> = {
 
 /**
  * Thrown by `resolveCredentialPools` at task admission (`enforceModelCapacity`)
- * when every key for a pool is either key-wide rate-limited or blocked by the
- * requested model's weekly window, and `MODEL_WINDOW_EXHAUSTED_POLICY` is
- * `fail` (the default). The caller must not spawn the CLI on this error — see
- * `spawnProviderProcess` in `src/commands/runner.ts`. Taskless configuration
- * loads never throw it.
+ * when no key for a pool can run the requested model: every key is key-wide
+ * rate-limited, blocked by the model's weekly window, or on a subscription
+ * seat that cannot run the model (`seatBlockedCount`). A window block throws
+ * only when `MODEL_WINDOW_EXHAUSTED_POLICY` is `fail` (the default); a seat
+ * block never resets, so it throws under every policy. The caller must not
+ * spawn the CLI on this error — see `spawnProviderProcess` in
+ * `src/commands/runner.ts`. Taskless configuration loads never throw it.
  */
 export class ModelWindowExhaustedError extends Error {
   readonly model: ModelFamily;
   readonly window: string;
   readonly earliestResetAt: string | null;
   readonly keyType: string;
+  readonly seatBlockedCount: number;
+  readonly modelBlockedCount: number;
 
   constructor(opts: {
     model: ModelFamily;
     window: string;
     earliestResetAt: string | null;
     keyType: string;
+    seatBlockedCount?: number;
+    modelBlockedCount?: number;
   }) {
     const modelLabel = MODEL_LABELS[opts.model];
+    const seatBlockedCount = opts.seatBlockedCount ?? 0;
+    const modelBlockedCount = opts.modelBlockedCount ?? 0;
+    const windowClause =
+      modelBlockedCount > 0 && opts.earliestResetAt
+        ? `${modelBlockedCount} keys have the ${modelLabel} window exhausted until ${opts.earliestResetAt}`
+        : `${modelBlockedCount} keys have the ${modelLabel} window exhausted`;
     super(
-      `No ${opts.keyType} key has ${modelLabel} capacity until ${opts.earliestResetAt ?? "unknown"}. Re-dispatch with another model or modelTier.`,
+      seatBlockedCount > 0
+        ? `No ${opts.keyType} key can run ${modelLabel}: ${seatBlockedCount} keys are on a seat without ${modelLabel}, ${windowClause}. Re-dispatch with another model or modelTier.`
+        : `No ${opts.keyType} key has ${modelLabel} capacity until ${opts.earliestResetAt ?? "unknown"}. Re-dispatch with another model or modelTier.`,
     );
     this.name = "ModelWindowExhaustedError";
     this.model = opts.model;
     this.window = opts.window;
     this.earliestResetAt = opts.earliestResetAt;
     this.keyType = opts.keyType;
+    this.seatBlockedCount = seatBlockedCount;
+    this.modelBlockedCount = modelBlockedCount;
   }
 }
 
@@ -173,6 +194,15 @@ function isJsonObject(value: string): boolean {
  * Falls back to random selection from all credentials if no available indices match.
  * A JSON object value (the CODEX_OAUTH blob) is always one credential.
  */
+function splitCredentialPool(value: string): string[] {
+  return isJsonObject(value)
+    ? [value.trim()]
+    : value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+
 export function selectCredential(
   value: string,
   availableIndices?: number[],
@@ -183,12 +213,7 @@ export function selectCredential(
   // handed out fragments such as `"accountId":"..."}` as the selected credential
   // and stamped `965"}` as the key suffix on task records. Codex pools live in
   // config-store slots (codex_oauth_<n>), resolved by the runner instead.
-  const credentials = isJsonObject(value)
-    ? [value.trim()]
-    : value
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean);
+  const credentials = splitCredentialPool(value);
   if (credentials.length <= 1) {
     const selected = value.trim();
     const isRateLimitFallback = availableIndices !== undefined && availableIndices.length === 0;
@@ -247,17 +272,27 @@ export function selectRandomCredential(value: string): {
   return { selected: result.selected, index: result.index, total: result.total };
 }
 
+export const CLAUDE_CREDENTIALS_HINT =
+  "Set CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY, or route Claude Code through a gateway (ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY), Microsoft Foundry (CLAUDE_CODE_USE_FOUNDRY), Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK), or Google Vertex AI (CLAUDE_CODE_USE_VERTEX).";
+
+const CLAUDE_CREDENTIAL_TYPE_BY_PROVIDER: Record<string, string> = {
+  "claude-subscription": "oauth",
+  anthropic: "api_key",
+  "anthropic-gateway": "gateway",
+};
+
 /**
- * Validate that at least one Claude credential is available.
- * Priority: CLAUDE_CODE_OAUTH_TOKEN > ANTHROPIC_API_KEY.
- * Returns the credential type found, or throws if neither is set.
+ * Validate that the claude harness has a usable default route (see
+ * `deriveDefaultRoute` in @desplega/model-routing for the precedence).
+ * Returns the credential type found ("oauth", "api_key", "gateway", "foundry",
+ * "bedrock", "vertex"), or throws with what is missing.
  */
-export function validateClaudeCredentials(
-  env: Record<string, string | undefined>,
-): "oauth" | "api_key" {
-  if (env.CLAUDE_CODE_OAUTH_TOKEN) return "oauth";
-  if (env.ANTHROPIC_API_KEY) return "api_key";
-  throw new Error("No Claude credentials found. Set CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.");
+export function validateClaudeCredentials(env: Record<string, string | undefined>): string {
+  const route = deriveDefaultRoute("claude", env);
+  if (!route) throw new Error(`No Claude credentials found. ${CLAUDE_CREDENTIALS_HINT}`);
+  const status = routeCredentialStatus(route, env);
+  if (!status.ready) throw new Error(`No Claude credentials found. ${status.hint}`);
+  return CLAUDE_CREDENTIAL_TYPE_BY_PROVIDER[route.provider] ?? route.provider;
 }
 
 /**
@@ -283,6 +318,8 @@ export interface AvailabilityInfo {
   availableIndices: number[];
   modelBlockedIndices?: number[];
   earliestModelResetAt?: string | null;
+  /** Indices excluded because the key's subscription plan cannot run the model. */
+  seatBlockedIndices?: number[];
 }
 
 /**
@@ -315,11 +352,13 @@ async function fetchAvailableIndices(
             availableIndices: number[];
             modelBlockedIndices?: number[];
             earliestModelResetAt?: string | null;
+            seatBlockedIndices?: number[];
           };
           availableIndicesMap[envVar] = {
             availableIndices: data.availableIndices,
             modelBlockedIndices: data.modelBlockedIndices,
             earliestModelResetAt: data.earliestModelResetAt,
+            seatBlockedIndices: data.seatBlockedIndices,
           };
           if (data.availableIndices.length < totalKeys) {
             console.log(
@@ -374,7 +413,9 @@ export async function resolveCredentialPools(
     localBlocks?: Map<string, number>;
     /**
      * Set only at task admission (`spawnProviderProcess`). When true, an
-     * exhausted model window fails fast with `ModelWindowExhaustedError`.
+     * exhausted model window, or a pool where every remaining key is on a
+     * seat that cannot run the model, fails fast with
+     * `ModelWindowExhaustedError`.
      * Taskless configuration loads (worker boot, credential recovery,
      * periodic reconciliation) leave it unset: they still pick a key, so an
      * exhausted default model never blocks boot or config refresh, and the
@@ -413,32 +454,43 @@ export async function resolveCredentialPools(
         modelBlockedCount += beforeCount - available.length;
       }
 
-      // Every key is either key-wide rate-limited or blocked by this
-      // model's weekly window, and at least one is blocked specifically by
-      // the model (not just legacy key-wide rate limiting) — the picker
-      // can't make progress for this model on this pool. Default policy
-      // fails fast instead of looping the worker through the same
-      // exhausted key every few minutes.
-      if (
-        opts?.enforceModelCapacity &&
-        window &&
-        modelFamily &&
-        available &&
-        available.length === 0 &&
-        modelBlockedCount > 0
-      ) {
+      const seatBlockedIndices = info?.seatBlockedIndices ?? [];
+      const seatBlockedCount = seatBlockedIndices.length;
+      let seatFallbackIndices: number[] | undefined;
+
+      // Every key is key-wide rate-limited, blocked by this model's weekly
+      // window, or on a seat that cannot run the model, and at least one is
+      // blocked specifically for the model (not just legacy key-wide rate
+      // limiting) — the picker can't make progress for this model on this
+      // pool. Default policy fails fast instead of looping the worker
+      // through the same exhausted key every few minutes. A seat block is a
+      // plan fact with no window and no reset, so the fallback pick excludes
+      // seat-blocked keys: a pick from them is a guaranteed failure. It fails
+      // only when every key is seat-blocked.
+      if (opts?.enforceModelCapacity && modelFamily && available && available.length === 0) {
         const policy = (env.MODEL_WINDOW_EXHAUSTED_POLICY ?? "fail").trim().toLowerCase();
-        if (policy !== "fallback") {
+        const windowExhausted =
+          window !== undefined && modelBlockedCount > 0 && policy !== "fallback";
+        if (seatBlockedCount > 0) {
+          seatFallbackIndices = splitCredentialPool(val)
+            .map((_, i) => i)
+            .filter((i) => !seatBlockedIndices.includes(i));
+        }
+        if (windowExhausted || seatFallbackIndices?.length === 0) {
           throw new ModelWindowExhaustedError({
             model: modelFamily,
-            window,
+            window: window ?? "",
             earliestResetAt: info?.earliestModelResetAt ?? null,
             keyType: envVar,
+            seatBlockedCount,
+            modelBlockedCount,
           });
         }
       }
 
-      const result = selectCredential(val, available, envVar);
+      const result = seatFallbackIndices
+        ? { ...selectCredential(val, seatFallbackIndices, envVar), isRateLimitFallback: true }
+        : selectCredential(val, available, envVar);
       env[envVar] = result.selected;
       const availInfo = available ? ` (${available.length} available of ${result.total})` : "";
       console.log(
@@ -448,6 +500,7 @@ export async function resolveCredentialPools(
         ...result,
         modelBlockedIndices: info?.modelBlockedIndices,
         earliestModelResetAt: info?.earliestModelResetAt,
+        seatBlockedIndices: info?.seatBlockedIndices,
       });
     }
   }

package/src/utils/dsh-usage.ts

@@ -0,0 +1,53 @@
+/**
+ * dsh `status.step_end.usage` normalization, shared by the worker adapter
+ * (session cost row) and the dashboard log parser (turn summary row) so both
+ * surfaces count the same tokens. Pure, no imports: `apps/ui` bundles it.
+ *
+ * dsh counts are disjoint and `totalTokens` is always their sum:
+ * `inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens` on both
+ * routes (pi-ai `parseChunkUsage` for OpenRouter, `dsh-llm-deepseek` for the
+ * direct API). Reasoning is folded into `outputTokens`, not added on top.
+ *
+ * The cache buckets can go missing while `totalTokens` keeps them: dsh omits a
+ * zero cache field, and when a step is retried `dsh-headless` sums an optional
+ * bucket only if every attempt reported it. A failed attempt reports zeroed
+ * usage, so the step's `cacheReadTokens` disappears and only `totalTokens`
+ * still carries it. The missing remainder is derived from `totalTokens`.
+ */
+export interface DshStepUsage {
+  /** Prompt tokens not served from cache. */
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  /** Subset of `output`; only some routes report it. */
+  reasoning: number;
+}
+
+function count(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/** Normalizes one `step_end.usage` object; `null` when the step reported none. */
+export function normalizeDshStepUsage(usage: unknown): DshStepUsage | null {
+  if (!usage || typeof usage !== "object") return null;
+  const u = usage as Record<string, unknown>;
+  const input = count(u.inputTokens);
+  const output = count(u.outputTokens);
+  const cacheWrite = count(u.cacheWriteTokens);
+  const cacheRead =
+    typeof u.cacheReadTokens === "number"
+      ? count(u.cacheReadTokens)
+      : Math.max(0, count(u.totalTokens) - input - output - cacheWrite);
+  return { input, output, cacheRead, cacheWrite, reasoning: count(u.reasoningTokens) };
+}
+
+export function addDshStepUsage(acc: DshStepUsage | undefined, step: DshStepUsage): DshStepUsage {
+  return {
+    input: (acc?.input ?? 0) + step.input,
+    output: (acc?.output ?? 0) + step.output,
+    cacheRead: (acc?.cacheRead ?? 0) + step.cacheRead,
+    cacheWrite: (acc?.cacheWrite ?? 0) + step.cacheWrite,
+    reasoning: (acc?.reasoning ?? 0) + step.reasoning,
+  };
+}

package/src/utils/error-tracker.ts

@@ -95,6 +95,51 @@ export function parseRateLimitWindowTelemetry(
   }
 }
 
+/**
+ * `rate_limit_info` fields that describe the seat's billing state (the
+ * `credits_required` payload). `scrubSecrets` does not match them, so they
+ * are dropped structurally before a log egress.
+ */
+const SEAT_PAYLOAD_FIELDS = [
+  "overageDisabledReason",
+  "canUserPurchaseCredits",
+  "hasChargeableSavedPaymentMethod",
+] as const;
+
+/**
+ * Returns a `rate_limit_event` message without the seat billing fields of
+ * its `rate_limit_info`. Any other message is returned unchanged. Error
+ * tracking reads the original message; only log egress uses the result.
+ */
+export function redactRateLimitEvent<T>(message: T): T {
+  if (!message || typeof message !== "object") return message;
+  const json = message as Record<string, unknown>;
+  if (json.type !== "rate_limit_event") return message;
+  const info = json.rate_limit_info;
+  if (!info || typeof info !== "object") return message;
+  if (!SEAT_PAYLOAD_FIELDS.some((field) => field in info)) return message;
+  const redactedInfo = { ...(info as Record<string, unknown>) };
+  for (const field of SEAT_PAYLOAD_FIELDS) delete redactedInfo[field];
+  return { ...json, rate_limit_info: redactedInfo } as T;
+}
+
+/**
+ * Line form of `redactRateLimitEvent` for the CLI's stream-json output. A
+ * line that is not a `rate_limit_event` with seat billing fields is returned
+ * byte for byte.
+ */
+export function redactRateLimitEventLine(line: string): string {
+  if (!line.includes('"rate_limit_event"')) return line;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return line;
+  }
+  const redacted = redactRateLimitEvent(parsed);
+  return redacted === parsed ? line : JSON.stringify(redacted);
+}
+
 /**
  * Maximum cooldown horizon for a rate-limit reset. A weekly OAuth limit resets
  * up to ~7 days out, so the cap must be at least that or a weekly-limited key
@@ -186,6 +231,14 @@ export class SessionErrorTracker {
   private modelRateLimit:
     | { window: string; model: ModelFamily; resetAtMs: number; observedAt: string }
     | undefined;
+  /**
+   * Stashed `credits_required` rejection: the key's seat cannot run the
+   * session's model (e.g. "Fable 5.1 requires usage credits"). A seat fact,
+   * not a rate limit, so it never lands in `keyWideRejections`.
+   */
+  private creditsRequired:
+    | { observedAt: string; resetsAtMs?: number; overageDisabledReason?: string }
+    | undefined;
   private rateLimitWindows: RateLimitWindowTelemetry = {};
 
   /** Record an error from an assistant message with message.error field */
@@ -265,6 +318,21 @@ export class SessionErrorTracker {
         return;
       }
 
+      // Checked before the resetsAt validation: the observed event carries a
+      // resetsAt, but this branch must not depend on it.
+      if (info.errorCode === "credits_required") {
+        this.creditsRequired = {
+          observedAt,
+          resetsAtMs:
+            typeof info.resetsAt === "number" && Number.isFinite(info.resetsAt)
+              ? info.resetsAt * 1000
+              : undefined,
+          overageDisabledReason:
+            typeof info.overageDisabledReason === "string" ? info.overageDisabledReason : undefined,
+        };
+        return;
+      }
+
       const resetsAtSec = info.resetsAt;
       if (typeof resetsAtSec !== "number" || !Number.isFinite(resetsAtSec) || resetsAtSec <= 0) {
         console.warn(
@@ -344,6 +412,18 @@ export class SessionErrorTracker {
     };
   }
 
+  /**
+   * Returns the stashed `credits_required` rejection, or undefined if none was
+   * seen in this session. It never sets the key-wide reset time.
+   */
+  getCreditsRequired(): { observedAt: string; overageDisabledReason?: string } | undefined {
+    if (!this.creditsRequired) return undefined;
+    return {
+      observedAt: this.creditsRequired.observedAt,
+      overageDisabledReason: this.creditsRequired.overageDisabledReason,
+    };
+  }
+
   hasErrors(): boolean {
     return this.errors.length > 0;
   }

package/src/utils/harness-cli-version.ts

@@ -1,12 +1,13 @@
 /**
- * The worker's harness CLI version (`claude --version` / `codex --version`),
+ * The worker's harness CLI version (`claude --version`, `codex --version`, or `pi --version`),
  * reported on register and used to key harness_model_support rows. Worker-safe
  * (no DB). Probed once per process; null when the CLI is missing or silent.
+ * An unprobed harness returns a blank string to clear stale registration data.
  */
 import { isUnknownModelError } from "./harness-model-error";
 import { scrubSecrets } from "./secret-scrubber";
 
-const CLI_BINARY: Record<string, string> = { claude: "claude", codex: "codex" };
+const CLI_BINARY: Record<string, string> = { claude: "claude", codex: "codex", pi: "pi" };
 const PROBE_TIMEOUT_MS = 10_000;
 const VERSION_RE = /\d+\.\d+\.\d+(?:[-+][\w.]+)?/;
 
@@ -18,7 +19,7 @@ export function parseCliVersion(output: string): string | null {
 
 export function probeHarnessCliVersion(harness: string): Promise<string | null> {
   const binary = CLI_BINARY[harness];
-  if (!binary) return Promise.resolve(null);
+  if (!binary) return Promise.resolve("");
   let pending = probed.get(harness);
   if (!pending) {
     pending = (async () => {
@@ -66,7 +67,8 @@ export async function reportHarnessModelOutcome(opts: {
   failureReason?: string;
   fetchImpl?: typeof fetch;
 }): Promise<void> {
-  if (!opts.model || !CLI_BINARY[opts.harness]) return;
+  // Only harnesses with verified unknown-model error classification report outcomes.
+  if (!opts.model || (opts.harness !== "claude" && opts.harness !== "codex")) return;
   const cliVersion = await cachedHarnessCliVersion(opts.harness);
   if (!cliVersion) return;
   const status =

package/src/utils/internal-ai/complete-structured.ts

@@ -192,6 +192,17 @@ export async function defaultSpawnClaudeCli(
   }
 }
 
+/** Parsed output plus the model string that produced it. */
+export interface CompleteStructuredResult<TData> {
+  data: TData;
+  /**
+   * Model that served the call, as resolved from the credential
+   * (`provider/model-id`, or the `claude -p` alias such as `haiku`). Lets
+   * callers record which judge produced the output.
+   */
+  model: string;
+}
+
 /**
  * Run a structured-output completion. Returns the parsed object on success,
  * `null` on auth-missing or exhausted retries (errors logged, never thrown).
@@ -199,6 +210,18 @@ export async function defaultSpawnClaudeCli(
 export async function completeStructured<TZod extends z.ZodTypeAny>(
   opts: CompleteStructuredOptions<TZod>,
 ): Promise<z.infer<TZod> | null> {
+  const result = await completeStructuredWithModel(opts);
+  return result ? result.data : null;
+}
+
+/**
+ * Same as {@link completeStructured}, but also reports the model that served
+ * the call. Use it when the output must be attributable (e.g. `llm` memory
+ * ratings record their judge).
+ */
+export async function completeStructuredWithModel<TZod extends z.ZodTypeAny>(
+  opts: CompleteStructuredOptions<TZod>,
+): Promise<CompleteStructuredResult<z.infer<TZod>> | null> {
   const retries = opts.retries ?? 3;
   const callerTag = opts.callerTag ?? "<unset>";
 
@@ -254,7 +277,7 @@ export async function completeStructured<TZod extends z.ZodTypeAny>(
         }
         const validated = opts.zodSchema.safeParse(parsedJson);
         if (validated.success) {
-          return validated.data;
+          return { data: validated.data, model: cred.modelDefault };
         }
         lastErr = validated.error;
       } catch (err) {
@@ -343,7 +366,7 @@ export async function completeStructured<TZod extends z.ZodTypeAny>(
           if (parsedText !== undefined) {
             const validatedText = opts.zodSchema.safeParse(parsedText);
             if (validatedText.success) {
-              return validatedText.data;
+              return { data: validatedText.data, model: cred.modelDefault };
             }
           }
         }
@@ -354,7 +377,7 @@ export async function completeStructured<TZod extends z.ZodTypeAny>(
 
       const validated = opts.zodSchema.safeParse(toolCall.arguments);
       if (validated.success) {
-        return validated.data;
+        return { data: validated.data, model: cred.modelDefault };
       }
       userPrompt = `${userPrompt}\n\nThe ${opts.toolName} arguments did not validate: ${validated.error.message}. Please retry with correct arguments.`;
       lastErr = validated.error;

package/src/utils/internal-ai/credentials.ts

@@ -15,6 +15,7 @@
  * Worker-safe: uses fetch() only, no bun:sqlite import.
  */
 
+import { isFirstPartyAnthropicUrl } from "@desplega/model-routing";
 import {
   InMemoryCredentialStore,
   type OAuthCredential,
@@ -24,7 +25,7 @@ import { registerBunOAuthFlows } from "@earendil-works/pi-ai/bun-oauth";
 import { getEnvApiKey } from "@earendil-works/pi-ai/compat";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
 import { getValidCodexOAuth, persistCodexOAuth } from "../../providers/codex-oauth/storage.js";
-import { type CredentialKind, DEFAULT_MODEL, resolveModelString } from "./models.js";
+import { type CredentialKind, DEFAULT_MODEL, resolveRaterModelString } from "./models.js";
 
 registerBunOAuthFlows();
 
@@ -69,6 +70,12 @@ const resolveOAuthApiKey: OAuthApiKeyResolver = async (providerId, credentials)
   };
 };
 
+/**
+ * `modelDefault` is the session-summary / `llm` memory-rater model for the
+ * credential kind (`resolveRaterModelString`: `MEMORY_RATER_MODEL` env, else
+ * the pinned `MEMORY_RATER_DEFAULT_MODEL`). It is not the general
+ * `DEFAULT_MODEL`; callers that want that (workflow LLM nodes) read it directly.
+ */
 export type ResolvedCredential =
   | {
       kind: "openrouter" | "anthropic" | "openai" | "openai-codex";
@@ -107,7 +114,8 @@ export interface ResolveCredentialOptions {
  *
  * Precedence (top wins):
  *   1. `env.OPENROUTER_API_KEY` (via pi-ai `getEnvApiKey("openrouter")`)
- *   2. `env.ANTHROPIC_API_KEY`  (via pi-ai `getEnvApiKey("anthropic")`)
+ *   2. `env.ANTHROPIC_API_KEY`  (via pi-ai `getEnvApiKey("anthropic")`), unless
+ *      `ANTHROPIC_BASE_URL` points at a gateway (the key is the gateway's)
  *   3. `env.OPENAI_API_KEY`     (via pi-ai `getEnvApiKey("openai")`)
  *   4. codex OAuth (only when `apiUrl && apiKey` are provided)
  *   5. `env.CLAUDE_CODE_OAUTH_TOKEN` → claude-cli fallback
@@ -128,17 +136,23 @@ export async function resolveCredential(
     return {
       kind: "openrouter",
       apiKey: openrouterKey,
-      modelDefault: resolveModelString("openrouter"),
+      modelDefault: resolveRaterModelString("openrouter"),
     };
   }
 
-  // 2. Anthropic.
-  const anthropicKey = env.ANTHROPIC_API_KEY ?? getEnvKey("anthropic");
+  // 2. Anthropic. pi-ai sends this key to api.anthropic.com, so skip it when
+  // ANTHROPIC_BASE_URL names a gateway: the key belongs to the gateway (#1800).
+  const anthropicBaseUrl = env.ANTHROPIC_BASE_URL?.trim();
+  const anthropicKeyIsForGateway =
+    Boolean(anthropicBaseUrl) && !isFirstPartyAnthropicUrl(anthropicBaseUrl ?? "");
+  const anthropicKey = anthropicKeyIsForGateway
+    ? undefined
+    : (env.ANTHROPIC_API_KEY ?? getEnvKey("anthropic"));
   if (anthropicKey) {
     return {
       kind: "anthropic",
       apiKey: anthropicKey,
-      modelDefault: resolveModelString("anthropic"),
+      modelDefault: resolveRaterModelString("anthropic"),
     };
   }
 
@@ -148,7 +162,7 @@ export async function resolveCredential(
     return {
       kind: "openai",
       apiKey: openaiKey,
-      modelDefault: resolveModelString("openai"),
+      modelDefault: resolveRaterModelString("openai"),
     };
   }
 
@@ -190,7 +204,7 @@ export async function resolveCredential(
           return {
             kind: "openai-codex",
             apiKey: oauthResult.apiKey,
-            modelDefault: resolveModelString("openai-codex"),
+            modelDefault: resolveRaterModelString("openai-codex"),
           };
         }
       }
@@ -210,7 +224,7 @@ export async function resolveCredential(
   if (env.AGENT_SWARM_CLAUDE_OAUTH_TOKEN || env.CLAUDE_CODE_OAUTH_TOKEN) {
     return {
       kind: "claude-cli",
-      modelDefault: resolveModelString("claude-cli"),
+      modelDefault: resolveRaterModelString("claude-cli"),
     };
   }
 

package/src/utils/internal-ai/index.ts

@@ -14,7 +14,9 @@
 
 export {
   type CompleteStructuredOptions,
+  type CompleteStructuredResult,
   completeStructured,
+  completeStructuredWithModel,
 } from "./complete-structured.js";
 export {
   type CredentialKind,
@@ -23,9 +25,14 @@ export {
   type ResolvedCredential,
   resolveCredential,
 } from "./credentials.js";
-export { parseModelStr, resolveModelString } from "./models.js";
+export {
+  MEMORY_RATER_DEFAULT_MODEL,
+  parseModelStr,
+  resolveRaterModelString,
+} from "./models.js";
 export {
   type SummarizeSessionOptions,
+  type SummarizeSessionResult,
   summarizeSession,
   summaryToolSchema,
 } from "./summarize-session.js";