@centerforagenticai/pi-multi-account 0.1.2 → 0.1.5

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Global Anthropic and OpenAI Codex multi-account OAuth routing for Pi.",
   "type": "module",
   "bin": {

package/packages/pi-anthropic-oauth/src/stream.ts

@@ -221,10 +221,18 @@ export function streamAnthropicOAuth(
       // which throws under fine-grained-tool-streaming (input may be invalid
       // mid-flight) and aborts the turn. The raw stream yields the same
       // RawMessageStreamEvents; tool args are already parsed leniently below.
+      // A finite non-negative integer request-local maxRetries bounds the SDK's
+      // own retries (0 sends exactly once); any other value keeps the SDK default.
+      const maxRetries = options?.maxRetries;
       const { data: anthropicStream, response: httpResponse } =
         await client.messages
           .create(params, {
             signal: options?.signal,
+            ...(Number.isFinite(maxRetries) &&
+            Number.isInteger(maxRetries) &&
+            (maxRetries ?? -1) >= 0
+              ? { maxRetries }
+              : {}),
           })
           .withResponse();
 

package/src/anthropic-adaptive-stream.ts

@@ -24,8 +24,9 @@
  * Provenance: pi-anthropic-oauth@0.2.4-intel.2, private pin
  * 99ac00f290efbcb93e7f23e6b7482d8727367aa7, upstream baseline
  * 53266ecb51b6d1890ef3f7251a64cb1d71d96099, source src/stream.ts.
- * Local delta: adaptive thinking emits type=adaptive and mapped output effort,
- * without budget_tokens; all other request and response behavior is unchanged.
+ * Local delta: adaptive thinking emits type=adaptive and mapped output effort
+ * without budget_tokens; request-local retry/timeout options reach the SDK; and
+ * refusal or unknown stop reasons retain bounded, structured error details.
  */
 
 import { Anthropic } from "@anthropic-ai/sdk";
@@ -41,6 +42,8 @@ import {
   type SimpleStreamOptions,
   type StopReason,
 } from "@earendil-works/pi-ai";
+import { sanitizeDiagnosticText } from "./diagnostics.js";
+import type { ProviderErrorCode } from "./error-classification.js";
 type IndexedBlock =
   | ({ type: "text"; text: string } & { index: number })
   | ({ type: "thinking"; thinking: string; thinkingSignature?: string } & {
@@ -95,18 +98,51 @@ const REQUIRED_BETAS = [
   "interleaved-thinking-2025-05-14",
 ] as const;
 
-function mapStopReason(reason: string | null | undefined): StopReason {
+type StopReasonResult = Readonly<{
+  stopReason: StopReason;
+  errorMessage?: string;
+  code?: Extract<ProviderErrorCode, "refusal" | "unknown_stop">;
+}>;
+
+function mapStopReason(
+  reason: string | null | undefined,
+  stopDetails?: unknown,
+): StopReasonResult {
   switch (reason) {
     case "end_turn":
     case "pause_turn":
     case "stop_sequence":
-      return "stop";
+      return { stopReason: "stop" };
     case "max_tokens":
-      return "length";
+      return { stopReason: "length" };
     case "tool_use":
-      return "toolUse";
-    default:
-      return "error";
+      return { stopReason: "toolUse" };
+    case "refusal": {
+      const explanation =
+        typeof stopDetails === "object" &&
+        stopDetails !== null &&
+        typeof (stopDetails as { explanation?: unknown }).explanation === "string"
+          ? sanitizeDiagnosticText(
+              (stopDetails as { explanation: string }).explanation,
+            )
+          : "";
+      return {
+        stopReason: "error",
+        errorMessage:
+          explanation || "The model refused to complete the request",
+        code: "refusal",
+      };
+    }
+    default: {
+      const boundedReason = sanitizeDiagnosticText(reason ?? "unknown");
+      return {
+        stopReason: "error",
+        errorMessage: sanitizeDiagnosticText(
+          `Provider stopped with: ${boundedReason}`,
+        ),
+        code: "unknown_stop",
+      };
+    }
   }
 }
 
@@ -163,7 +199,7 @@ export function streamAnthropicAdaptive(
   const stream = createAssistantMessageEventStream();
 
   void (async () => {
-    const output: AssistantMessage = {
+    const output: AssistantMessage & { code?: ProviderErrorCode } = {
       role: "assistant",
       content: [],
       api: model.api,
@@ -276,10 +312,24 @@ export function streamAnthropicAdaptive(
       // which throws under fine-grained-tool-streaming (input may be invalid
       // mid-flight) and aborts the turn. The raw stream yields the same
       // RawMessageStreamEvents; tool args are already parsed leniently below.
+      const maxRetries = options?.maxRetries;
+      const timeoutMs = options?.timeoutMs;
       const { data: anthropicStream, response: httpResponse } =
         await client.messages
           .create(params, {
             signal: options?.signal,
+            ...(Number.isFinite(maxRetries) &&
+            Number.isInteger(maxRetries) &&
+            (maxRetries ?? -1) >= 0
+              ? { maxRetries }
+              : {}),
+            // Any finite positive timeout is honored; the SDK timer takes whole
+            // milliseconds, so a fractional value is floored to at least 1.
+            ...(typeof timeoutMs === "number" &&
+            Number.isFinite(timeoutMs) &&
+            timeoutMs > 0
+              ? { timeout: Math.max(1, Math.floor(timeoutMs)) }
+              : {}),
           })
           .withResponse();
 
@@ -474,7 +524,19 @@ export function streamAnthropicAdaptive(
         }
 
         if (event.type === "message_delta") {
-          output.stopReason = mapStopReason(event.delta.stop_reason);
+          const rawStopReason = event.delta.stop_reason;
+          const mapped = mapStopReason(
+            rawStopReason,
+            (event.delta as { stop_details?: unknown }).stop_details,
+          );
+          output.stopReason = mapped.stopReason;
+          if (typeof rawStopReason === "string") {
+            output.rawStopReason = sanitizeDiagnosticText(rawStopReason);
+          }
+          if (mapped.errorMessage !== undefined) {
+            output.errorMessage = mapped.errorMessage;
+          }
+          if (mapped.code !== undefined) output.code = mapped.code;
           output.usage.input =
             (event.usage as { input_tokens?: number }).input_tokens ||
             output.usage.input;
@@ -505,11 +567,15 @@ export function streamAnthropicAdaptive(
       }
 
       if (options?.signal?.aborted) throw new Error("Request aborted");
-      stream.push({
-        type: "done",
-        reason: output.stopReason as "stop" | "length" | "toolUse",
-        message: output,
-      });
+      if (output.stopReason === "error") {
+        stream.push({ type: "error", reason: "error", error: output });
+      } else {
+        stream.push({
+          type: "done",
+          reason: output.stopReason as "stop" | "length" | "toolUse",
+          message: output,
+        });
+      }
       stream.end();
     } catch (error) {
       for (const block of output.content as Array<{

package/src/anthropic-alias-stream.ts

@@ -13,6 +13,7 @@ import {
   sanitizeDiagnosticText,
   sanitizeHeaderValue,
 } from "./diagnostics.js";
+import { hostFinalStopMessage } from "./host-final-stop-message.js";
 
 export const ANTHROPIC_ALIAS_API = "hypha-anthropic-oauth" as const;
 
@@ -53,12 +54,19 @@ function withAliasAttribution(
   };
 }
 
+/**
+ * Bounds an upstream error and, for a structured refusal or unknown stop,
+ * publishes the shared host-final message. A direct alias turn reaches the
+ * host's retry and compaction predicates without the unified provider, so
+ * provider-authored stop wording must not make the host resend the request.
+ */
 function sanitizeUpstreamError(message: AssistantMessage): AssistantMessage {
   if (message.errorMessage === undefined) return message;
-  return {
+  const sanitized: AssistantMessage = {
     ...message,
     errorMessage: sanitizeDiagnosticText(message.errorMessage),
   };
+  return { ...sanitized, ...hostFinalStopMessage(sanitized) };
 }
 
 function withAliasEvent(

package/src/codex-adapter.ts

@@ -193,14 +193,81 @@ function withAliasEvent(
   }
 }
 
+/**
+ * One attributed, sanitized error terminal for an upstream that failed before
+ * producing a stream (a synchronous throw, a rejected setup, or a throwing
+ * iterator). The shape matches the host's own setup-error terminal: no content,
+ * zero usage, no diagnostics. Only the bounded, redacted error text survives.
+ * A failure after the caller's signal fired is a cancellation: it ends as
+ * `aborted`, matching the maintained stream, so it never cools the account.
+ */
+function aliasSetupErrorMessage(
+  error: unknown,
+  aliasModel: Model<Api>,
+  aborted: boolean,
+): AssistantMessage & { stopReason: "error" | "aborted" } {
+  let detail: string;
+  try {
+    detail = error instanceof Error ? error.message : String(error);
+  } catch {
+    detail = "Codex alias stream setup failed";
+  }
+  return {
+    role: "assistant",
+    content: [],
+    api: aliasModel.api,
+    provider: aliasModel.provider,
+    model: aliasModel.id,
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: aborted ? "aborted" : "error",
+    errorMessage: sanitizeDiagnosticText(detail),
+    timestamp: Date.now(),
+  };
+}
+
+function isTerminalEvent(event: AssistantMessageEvent): boolean {
+  return event.type === "done" || event.type === "error";
+}
+
+/**
+ * Forwards upstream events with alias attribution. Every failure mode ends in
+ * exactly one terminal: a rejected setup or a throwing iterator before any
+ * terminal becomes one attributed error event, and the attributed stream always
+ * ends, so no failure escapes as an unhandled rejection or a hang.
+ */
 function reattributeStream(
-  upstream: AssistantMessageEventStream,
+  upstream: AssistantMessageEventStream | PromiseLike<AssistantMessageEventStream>,
   aliasModel: Model<Api>,
+  signal: AbortSignal | undefined,
 ): AssistantMessageEventStream {
   const attributed = createAssistantMessageEventStream();
   void (async () => {
-    for await (const event of upstream) {
-      attributed.push(withAliasEvent(event, aliasModel));
+    let sawTerminal = false;
+    try {
+      for await (const event of await upstream) {
+        if (sawTerminal) continue;
+        if (isTerminalEvent(event)) sawTerminal = true;
+        attributed.push(withAliasEvent(event, aliasModel));
+      }
+    } catch (error) {
+      if (!sawTerminal) {
+        sawTerminal = true;
+        const message = aliasSetupErrorMessage(
+          error,
+          aliasModel,
+          signal?.aborted === true,
+        );
+        attributed.push({ type: "error", reason: message.stopReason, error: message });
+      }
+    } finally {
+      attributed.end();
     }
   })();
   return attributed;
@@ -235,9 +302,33 @@ function normalizeAliasContext(
 }
 
 /**
- * Wraps the exact maintained stream without replacing transport or OAuth. Pi's
+ * Temporary containment for the Pi 0.99 Codex WebSocket failure: a WebSocket
+ * error leaves the session in a state where the next Codex turn crashes with
+ * "Cannot read properties of undefined (reading 'length')". Routes this
+ * extension owns always request SSE. The base `openai-codex` provider is never
+ * touched; only options on calls we already route are adjusted. Remove once the
+ * WebSocket path is fixed upstream.
+ */
+export const CODEX_FORCED_TRANSPORT = "sse" as const;
+
+/** Returns options with Codex transport pinned to SSE, and whether a value was overridden. */
+export function forceCodexSseOptions<T extends SimpleStreamOptions>(
+  options: T | undefined,
+): { options: T; overridden: boolean } {
+  if (options?.transport === CODEX_FORCED_TRANSPORT) {
+    return { options, overridden: false };
+  }
+  return {
+    options: { ...(options ?? {}), transport: CODEX_FORCED_TRANSPORT } as T,
+    overridden: true,
+  };
+}
+
+/**
+ * Wraps the exact maintained stream without replacing OAuth. Pi's
  * alias-resolved apiKey and every other option field are forwarded unchanged;
- * only model/context identity and callback attribution are adapted.
+ * model/context identity and callback attribution are adapted, and transport
+ * is pinned to SSE (see {@link CODEX_FORCED_TRANSPORT}).
  */
 export function createCodexAliasStream(
   maintainedStream: NonNullable<ProviderConfig["streamSimple"]>,
@@ -251,12 +342,12 @@ export function createCodexAliasStream(
     };
     const upstreamContext = normalizeAliasContext(context, aliasModel);
 
-    let upstreamOptions = options;
+    let upstreamOptions = forceCodexSseOptions(options).options;
     if (options?.onPayload || options?.onResponse) {
       const aliasOnPayload = options.onPayload;
       const aliasOnResponse = options.onResponse;
       upstreamOptions = {
-        ...options,
+        ...upstreamOptions,
         ...(aliasOnPayload
           ? {
               onPayload: (payload: unknown) =>
@@ -272,10 +363,17 @@ export function createCodexAliasStream(
       };
     }
 
-    return reattributeStream(
-      upstream(upstreamModel, upstreamContext, upstreamOptions),
-      aliasModel,
-    );
+    // Defensive only under the live host: its `lazyApi` stream catches a setup
+    // throw first and returns its own setup-error terminal. A non-lazy upstream
+    // (plain Node) can still throw synchronously; convert that into the same
+    // single attributed, sanitized terminal as any other failure (UPSTREAM.md).
+    let upstreamStream: ReturnType<CodexUpstreamStream>;
+    try {
+      upstreamStream = upstream(upstreamModel, upstreamContext, upstreamOptions);
+    } catch (error) {
+      upstreamStream = Promise.reject(error) as unknown as ReturnType<CodexUpstreamStream>;
+    }
+    return reattributeStream(upstreamStream, aliasModel, options?.signal);
   };
   return aliasStream as unknown as NonNullable<ProviderConfig["streamSimple"]>;
 }

package/src/config.ts

@@ -29,6 +29,7 @@ import {
 } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join } from "node:path";
+import { sanitizeDiagnosticText } from "./diagnostics.js";
 import { PROJECT_KEY_PATTERN } from "./project-identity.js";
 import {
 	AccountRateHistoryError,
@@ -167,6 +168,15 @@ export interface CrossFamilyChain {
 	readonly to: AllowedFamily;
 }
 
+/** One exact, directional model-substitution egress authorization. */
+export interface ModelFallbackEgressAuthorization {
+	readonly sourceModelId: string;
+	readonly destinationModelId: string;
+}
+
+/** Exact source unified model id -> ordered exact fallback model ids. */
+export type ModelFallbackMap = Readonly<Record<string, readonly string[]>>;
+
 export interface MultiAccountConfig {
 	readonly accountLimit: number;
 	readonly sameFamilyFailover: boolean;
@@ -238,6 +248,10 @@ export interface MultiAccountConfig {
 	 */
 	readonly preferredModels: Readonly<Record<string, readonly string[]>>;
 	readonly tierModelMap: TierModelMap;
+	/** Explicit ordered fallback policy. Absent or empty disables model substitution. */
+	readonly modelFallbacks?: ModelFallbackMap;
+	/** Directional authorization required in addition to policy for cross-vendor edges. */
+	readonly modelFallbackEgress?: readonly ModelFallbackEgressAuthorization[];
 	/**
 	 * How close to expiry a credential may get before routing prefers a fresher
 	 * same-family account, in milliseconds. Pre-emption avoids spending a turn to
@@ -284,6 +298,8 @@ export const DEFAULT_CONFIG: MultiAccountConfig = {
 	accountRateHistory: {},
 	preferredModels: {},
 	tierModelMap: Object.freeze({}),
+	modelFallbacks: Object.freeze({}),
+	modelFallbackEgress: Object.freeze([]),
 	// Comfortably longer than a turn, short enough that accounts are not retired
 	// while they still have useful life.
 	preemptiveExpiryWindowMs: 120_000,
@@ -309,6 +325,8 @@ const CONFIG_KEYS = new Set<keyof MultiAccountConfig>([
 	"accountRateHistory",
 	"preferredModels",
 	"tierModelMap",
+	"modelFallbacks",
+	"modelFallbackEgress",
 	"preemptiveExpiryWindowMs",
 	"usageFetchEnabled",
 ]);
@@ -689,6 +707,135 @@ function isValidTierModelId(value: unknown): value is string {
 	);
 }
 
+export const MAX_MODEL_FALLBACK_SOURCES = 128;
+export const MAX_MODEL_FALLBACK_DESTINATIONS = 16;
+export const MAX_MODEL_FALLBACK_EDGES = 256;
+/**
+ * Exact catalog ids: managed wire ids, OpenRouter `vendor/model[:variant]`
+ * slugs, and the `~vendor/...` and `@cf/...` forms in the pinned catalog.
+ */
+const MODEL_FALLBACK_ID_PATTERN = /^[A-Za-z0-9~@][A-Za-z0-9._:/@~-]{0,255}$/;
+
+/**
+ * A fallback id may later appear in routing diagnostics, so it is accepted only
+ * when the shared diagnostic sanitizer would leave it byte-for-byte unchanged.
+ * Anything the sanitizer would redact anywhere in the string (credential
+ * prefixes, JWTs, token/canary shapes, long opaque runs) is rejected here, and
+ * the rejection message never echoes the value.
+ */
+function isValidModelFallbackId(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		MODEL_FALLBACK_ID_PATTERN.test(value) &&
+		sanitizeDiagnosticText(value) === value
+	);
+}
+
+function invalidModelFallbackId(field: string): ConfigValidationError {
+	return new ConfigValidationError(
+		`${field} must use an exact, non-credential model id of at most 256 characters.`,
+	);
+}
+
+function parseModelFallbacks(value: unknown): ModelFallbackMap {
+	if (value === undefined) return DEFAULT_CONFIG.modelFallbacks ?? Object.freeze({});
+	if (!isPlainObject(value)) {
+		throw new ConfigValidationError("modelFallbacks must be a plain JSON object.");
+	}
+	const entries = Object.entries(value);
+	if (entries.length > MAX_MODEL_FALLBACK_SOURCES) {
+		throw new ConfigValidationError(
+			`modelFallbacks must contain at most ${MAX_MODEL_FALLBACK_SOURCES} sources.`,
+		);
+	}
+	const parsed = Object.create(null) as Record<string, readonly string[]>;
+	for (const [sourceModelId, rawDestinations] of entries) {
+		if (!isValidModelFallbackId(sourceModelId)) {
+			throw invalidModelFallbackId("modelFallbacks source ids");
+		}
+		if (!Array.isArray(rawDestinations) || rawDestinations.length === 0) {
+			throw new ConfigValidationError(
+				"modelFallbacks values must be non-empty arrays of model ids.",
+			);
+		}
+		if (rawDestinations.length > MAX_MODEL_FALLBACK_DESTINATIONS) {
+			throw new ConfigValidationError(
+				`modelFallbacks may contain at most ${MAX_MODEL_FALLBACK_DESTINATIONS} destinations per source.`,
+			);
+		}
+		const destinations: string[] = [];
+		const seen = new Set<string>();
+		for (const destinationModelId of rawDestinations) {
+			if (!isValidModelFallbackId(destinationModelId)) {
+				throw invalidModelFallbackId("modelFallbacks destination ids");
+			}
+			if (destinationModelId === sourceModelId) {
+				throw new ConfigValidationError(
+					"modelFallbacks cannot list the source model as its own destination.",
+				);
+			}
+			if (seen.has(destinationModelId)) {
+				throw new ConfigValidationError(
+					"modelFallbacks cannot contain duplicate destinations for one source.",
+				);
+			}
+			seen.add(destinationModelId);
+			destinations.push(destinationModelId);
+		}
+		parsed[sourceModelId] = Object.freeze(destinations);
+	}
+	return Object.freeze(parsed);
+}
+
+function parseModelFallbackEgress(
+	value: unknown,
+): readonly ModelFallbackEgressAuthorization[] {
+	if (value === undefined) return DEFAULT_CONFIG.modelFallbackEgress ?? Object.freeze([]);
+	if (!Array.isArray(value)) {
+		throw new ConfigValidationError("modelFallbackEgress must be an array.");
+	}
+	if (value.length > MAX_MODEL_FALLBACK_EDGES) {
+		throw new ConfigValidationError(
+			`modelFallbackEgress must contain at most ${MAX_MODEL_FALLBACK_EDGES} edges.`,
+		);
+	}
+	const parsed: ModelFallbackEgressAuthorization[] = [];
+	const seen = new Set<string>();
+	for (const candidate of value) {
+		if (!isPlainObject(candidate)) {
+			throw new ConfigValidationError("modelFallbackEgress entries must be plain objects.");
+		}
+		const unknownKeys = Object.keys(candidate).filter(
+			(key) => key !== "sourceModelId" && key !== "destinationModelId",
+		);
+		if (unknownKeys.length > 0) {
+			throw new ConfigValidationError(
+				"modelFallbackEgress entries contain an unsupported field.",
+			);
+		}
+		const sourceModelId = candidate["sourceModelId"];
+		const destinationModelId = candidate["destinationModelId"];
+		if (!isValidModelFallbackId(sourceModelId)) {
+			throw invalidModelFallbackId("modelFallbackEgress sourceModelId");
+		}
+		if (!isValidModelFallbackId(destinationModelId)) {
+			throw invalidModelFallbackId("modelFallbackEgress destinationModelId");
+		}
+		if (sourceModelId === destinationModelId) {
+			throw new ConfigValidationError(
+				"modelFallbackEgress cannot authorize a model to itself.",
+			);
+		}
+		const key = `${sourceModelId}\u0000${destinationModelId}`;
+		if (seen.has(key)) {
+			throw new ConfigValidationError("modelFallbackEgress cannot contain duplicate edges.");
+		}
+		seen.add(key);
+		parsed.push(Object.freeze({ sourceModelId, destinationModelId }));
+	}
+	return Object.freeze(parsed);
+}
+
 export function parseTierModelMap(value: unknown): TierModelMap {
 	if (value === undefined) return DEFAULT_CONFIG.tierModelMap;
 	if (!isRecord(value)) {
@@ -1119,6 +1266,8 @@ export function parseConfig(value: unknown): MultiAccountConfig {
 	const accountRateHistory = parseAccountRateHistory(value["accountRateHistory"]);
 	const preferredModels = parsePreferredModels(value["preferredModels"]);
 	const tierModelMap = parseTierModelMap(value["tierModelMap"]);
+	const modelFallbacks = parseModelFallbacks(value["modelFallbacks"]);
+	const modelFallbackEgress = parseModelFallbackEgress(value["modelFallbackEgress"]);
 	const preemptiveExpiryWindowMs =
 		value["preemptiveExpiryWindowMs"] ??
 		DEFAULT_CONFIG.preemptiveExpiryWindowMs;
@@ -1206,6 +1355,8 @@ export function parseConfig(value: unknown): MultiAccountConfig {
 		accountRateHistory,
 		preferredModels,
 		tierModelMap,
+		modelFallbacks,
+		modelFallbackEgress,
 		preemptiveExpiryWindowMs,
 		usageFetchEnabled,
 	};

package/src/error-classification.ts

@@ -13,6 +13,8 @@ export const PROVIDER_ERROR_CODES = [
 	"model_not_found",
 	"unsupported_api_version",
 	"invalid_request",
+	"refusal",
+	"unknown_stop",
 ] as const;
 export type ProviderErrorCode = (typeof PROVIDER_ERROR_CODES)[number];
 
@@ -50,10 +52,12 @@ export type FailureCategory =
 
 export interface FailureClassification {
 	readonly category: FailureCategory;
+	readonly kind?: "refusal" | "unknown-stop";
 	readonly accountAction:
 		| "cooldown-and-route"
 		| "invalidate-and-route"
-		| "route-without-retry";
+		| "route-without-retry"
+		| "retain-account";
 	readonly cooldownReason?: CooldownReason;
 	readonly serverHint?: NumericServerHint;
 }
@@ -248,6 +252,14 @@ export function classifyFailure(
 		return { category: "config", accountAction: "route-without-retry" };
 	}
 
+	if (signal.code === "refusal" || signal.code === "unknown_stop") {
+		return {
+			category: "unknown",
+			kind: signal.code === "refusal" ? "refusal" : "unknown-stop",
+			accountAction: "retain-account",
+		};
+	}
+
 	if (isTransportFailure(signal)) {
 		return cooldown("transport", "transport", signal);
 	}