@gajae-code/ai 0.12.8 → 0.12.11

package/src/stream.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { $credentialEnv, $env, $pickCredentialEnv, extractHttpStatusFromError } from "@gajae-code/utils";
-import { assertManagedAttempt } from "./utils/fallback-transport";
+import { assertManagedAttempt, classifyFallbackTrigger, type TransportFailureFacts } from "./utils/fallback-transport";
 
 const managedAttemptValidated = Symbol("managedAttemptValidated");
 
@@ -396,13 +396,61 @@ function extractStatusFromAssistantError(message: AssistantMessage): number | un
 	return extractHttpStatusFromError({ message: message.errorMessage });
 }
 
-function createAssistantAuthError(message: AssistantMessage): Error & { status?: number } {
-	const error: Error & { status?: number } = new Error(message.errorMessage ?? "Provider authentication failed");
+function createAssistantAuthError(
+	message: AssistantMessage,
+): Error & { status?: number; transportFailure?: TransportFailureFacts } {
+	const error: Error & { status?: number; transportFailure?: TransportFailureFacts } = new Error(
+		message.errorMessage ?? "Provider authentication failed",
+	);
 	const status = extractStatusFromAssistantError(message);
 	if (status !== undefined) error.status = status;
+	// Preserve the structured facts. Without this the callback receives a
+	// status-only error and every downstream `auth` consumer loses the provider
+	// code it needs to tell a credential problem from a plain `forbidden`.
+	if (message.transportFailure) error.transportFailure = message.transportFailure;
 	return error;
 }
 
+/**
+ * Unwraps a nested `error.transportFailure` carrier.
+ *
+ * `transportFailureFacts` dereferences `value`, `value.response`, `value.error`
+ * and the captured response, but NOT `value.transportFailure` — and that is the
+ * shape this repository actually throws for transport errors. Reading the
+ * carrier here keeps the shared extractor untouched (its ten production call
+ * sites and its idempotence invariant stay as they are) while still letting the
+ * auth veto below see the provider code.
+ */
+function carriedTransportFailure(candidate: unknown): unknown {
+	if (!candidate || typeof candidate !== "object") return undefined;
+	const carried = (candidate as { transportFailure?: unknown }).transportFailure;
+	return carried && typeof carried === "object" ? carried : undefined;
+}
+
+/** Auth-relevant facts for a thrown error or an assistant error, carrier first. */
+function authFailureFacts(candidate: unknown): unknown {
+	return carriedTransportFailure(candidate) ?? candidate;
+}
+
+/**
+ * Whether this failure is a credential problem worth retrying with a different
+ * credential.
+ *
+ * Consulted by BOTH capture exits below, and it is the ONLY auth predicate they
+ * use. Gating on HTTP 401 alone would contradict the classifier: a typed
+ * provider code is supposed to win over the status, so `403 + invalid_api_key`
+ * must be captured and `401 + forbidden` must not. A `forbidden` failure is an
+ * authorization or configuration defect — handing it to `onAuthError` lets the
+ * gateway and SDK consumers invalidate a perfectly healthy credential.
+ */
+function shouldCaptureAuthFailure(candidate: unknown, statusHint: number | undefined): boolean {
+	const trigger = classifyFallbackTrigger(authFailureFacts(candidate));
+	// Typed auth facts are authoritative and already encode code-over-status.
+	if (trigger.class === "auth") return trigger.authDisposition !== "forbidden";
+	// Nothing classifiable: keep the historical bare-401 admission.
+	return statusHint === 401;
+}
+
 function emitBufferedEvents(stream: AssistantMessageEventStream, events: AssistantMessageEvent[]): void {
 	for (const event of events) {
 		stream.push(event);
@@ -447,7 +495,9 @@ export function streamSimple<TApi extends Api>(
 						!emittedReplayUnsafeEvent &&
 						captureAuthFailure &&
 						event.type === "error" &&
-						extractStatusFromAssistantError(event.error) === 401
+						// L0 gate, event exit. Classification decides; a typed
+						// `forbidden` never becomes an auth retry.
+						shouldCaptureAuthFailure(event.error, extractStatusFromAssistantError(event.error))
 					) {
 						return { error: createAssistantAuthError(event.error), bufferedEvents, terminalEvent: event };
 					}
@@ -459,7 +509,12 @@ export function streamSimple<TApi extends Api>(
 				flushBuffered();
 				if (!outer.done) outer.end(await inner.result());
 			} catch (error) {
-				if (!emittedReplayUnsafeEvent && captureAuthFailure && extractHttpStatusFromError(error) === 401) {
+				if (
+					!emittedReplayUnsafeEvent &&
+					captureAuthFailure &&
+					// L0 gate, throw exit: same rule, carrier-aware.
+					shouldCaptureAuthFailure(error, extractHttpStatusFromError(error))
+				) {
 					return { error, bufferedEvents };
 				}
 				flushBuffered();

package/src/types.ts

@@ -990,6 +990,19 @@ export interface ModelRequestTransform {
 	extraBody?: Record<string, unknown>;
 }
 
+export interface ModelCost {
+	input: number; // $/million tokens
+	output: number; // $/million tokens
+	cacheRead: number; // $/million tokens
+	cacheWrite: number; // $/million tokens
+}
+
+export interface LongContextPricing {
+	/** Input-token count above which the long-context rates apply to the full request. */
+	threshold: number;
+	cost: ModelCost;
+}
+
 export interface Model<TApi extends Api = any> {
 	id: string;
 	name: string;
@@ -1006,12 +1019,9 @@ export interface Model<TApi extends Api = any> {
 	 * provider/id heuristics.
 	 */
 	output?: ("text" | "image")[];
-	cost: {
-		input: number; // $/million tokens
-		output: number; // $/million tokens
-		cacheRead: number; // $/million tokens
-		cacheWrite: number; // $/million tokens
-	};
+	cost: ModelCost;
+	/** Optional long-context rates selected from the request's total input-token count. */
+	longContextPricing?: LongContextPricing;
 	/** Premium Copilot requests charged per user-initiated request (defaults to 1). */
 	premiumMultiplier?: number;
 	contextWindow: number;

package/src/utils/fallback-transport.ts

@@ -1,8 +1,25 @@
 export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "unknown" | "other";
 
+/**
+ * Refinement of an `auth` trigger.
+ *
+ * The transport deliberately collapses HTTP 401 and 403 into a single `auth`
+ * class, but the two demand opposite handling: a credential problem may be
+ * recoverable by trying a different stored credential, whereas a plain
+ * `forbidden` is an authorization or configuration defect that rotation would
+ * only hide — it would cycle and block every otherwise-healthy credential.
+ *
+ * This is a refinement rather than a new {@link FallbackTriggerClass} member so
+ * every existing `trigger.class === "auth"` consumer keeps compiling and keeps
+ * its current behavior until it explicitly opts into the distinction.
+ */
+export type AuthDisposition = "credential" | "forbidden";
+
 export interface FallbackTrigger {
 	class: FallbackTriggerClass;
 	retryAfterMs?: number;
+	/** Present only when `class === "auth"`. */
+	authDisposition?: AuthDisposition;
 }
 
 /** Stable code for streams that time out before producing semantic progress. */
@@ -158,7 +175,13 @@ export function transportFailureFacts(
 		finiteStatus(propertyOf(value, "status")) ??
 		finiteStatus(propertyOf(response, "status")) ??
 		finiteStatus(propertyOf(capturedResponse, "status"));
-	const anthropicErrorType = stringValue(propertyOf(nestedError, "type")) ?? stringValue(propertyOf(value, "type"));
+	// `anthropicErrorType` is also read from its own key so re-normalizing an
+	// already-built facts object (which consumers do deliberately) preserves it
+	// instead of silently dropping the Anthropic code on the second pass.
+	const anthropicErrorType =
+		stringValue(propertyOf(nestedError, "type")) ??
+		stringValue(propertyOf(value, "anthropicErrorType")) ??
+		stringValue(propertyOf(value, "type"));
 	const openaiErrorCode =
 		stringValue(propertyOf(value, "openaiErrorCode")) ?? stringValue(propertyOf(nestedError, "code"));
 	const providerCode =
@@ -229,17 +252,50 @@ function isQuotaCode(code: string | undefined): boolean {
 	);
 }
 
-function isAuthCode(code: string | undefined): boolean {
+const FORBIDDEN_AUTH_CODE = "forbidden";
+
+/** Auth codes that name a credential problem rather than an authorization one. */
+function isCredentialAuthCode(code: string | undefined): boolean {
 	return (
 		code === "authentication_error" ||
 		code === "invalid_api_key" ||
 		code === "invalid_token" ||
 		code === "token_expired" ||
-		code === "unauthorized" ||
-		code === "forbidden"
+		code === "unauthorized"
 	);
 }
 
+function isAuthCode(code: string | undefined): boolean {
+	return isCredentialAuthCode(code) || code === FORBIDDEN_AUTH_CODE;
+}
+
+/**
+ * Resolves the {@link AuthDisposition} for an `auth` trigger.
+ *
+ * Precedence is explicit and ordered by specificity rather than by field,
+ * because transport facts can carry a first-party typed code and a
+ * `providerCode` that disagree:
+ *
+ * 1. A code naming a concrete credential fault (`invalid_api_key`,
+ *    `authentication_error`, …) wins, from whichever field it arrives in: it is
+ *    a specific diagnosis, while `forbidden` is the generic bucket this
+ *    refinement exists to distrust.
+ * 2. Otherwise a `forbidden` code in any field is terminal, so
+ *    `{status: 401, providerCode: "forbidden"}` does not mutate credentials.
+ * 3. Otherwise the HTTP status decides, and an unknown-status `auth` defaults to
+ *    `credential` because that is the classification the pre-refinement code
+ *    already produced.
+ *
+ * Trigger-class selection deliberately keeps its single-code precedence
+ * (`openaiErrorCode ?? anthropicErrorType ?? providerCode`); only this auth
+ * refinement reads every code field.
+ */
+function resolveAuthDisposition(codes: readonly (string | undefined)[], status: number | undefined): AuthDisposition {
+	if (codes.some(code => isCredentialAuthCode(code))) return "credential";
+	if (codes.some(code => code === FORBIDDEN_AUTH_CODE)) return "forbidden";
+	return status === 403 ? "forbidden" : "credential";
+}
+
 function isRateLimitCode(code: string | undefined): boolean {
 	return (
 		code === "rate_limit" ||
@@ -259,7 +315,10 @@ export function classifyFallbackTrigger(
 	const retryAfterMs =
 		parseRetryAfterMilliseconds(headers?.get("retry-after-ms") ?? null) ??
 		parseRetryAfterSeconds(headers?.get("retry-after") ?? null);
-	const code = (facts.openaiErrorCode ?? facts.anthropicErrorType ?? facts.providerCode)?.toLowerCase();
+	const codes = [facts.openaiErrorCode, facts.anthropicErrorType, facts.providerCode].map(value =>
+		value?.toLowerCase(),
+	);
+	const code = codes[0] ?? codes[1] ?? codes[2];
 	const triggerClass: FallbackTriggerClass =
 		code === STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE
 			? "server"
@@ -272,5 +331,19 @@ export function classifyFallbackTrigger(
 						: facts.status !== undefined && facts.status >= 500 && facts.status <= 599
 							? "server"
 							: "other";
-	return retryAfterMs === undefined ? { class: triggerClass } : { class: triggerClass, retryAfterMs };
+	const trigger: FallbackTrigger = { class: triggerClass };
+	if (retryAfterMs !== undefined) trigger.retryAfterMs = retryAfterMs;
+	if (triggerClass === "auth") trigger.authDisposition = resolveAuthDisposition(codes, facts.status);
+	return trigger;
+}
+
+/**
+ * True when a failure is an `auth` failure that must NOT rotate credentials.
+ *
+ * Callers that mutate credential state on auth failures should consult this
+ * first so a plain `forbidden` cannot block otherwise-healthy credentials.
+ */
+export function isForbiddenAuthFailure(errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown): boolean {
+	const trigger = classifyFallbackTrigger(errorOrFacts);
+	return trigger.class === "auth" && trigger.authDisposition === "forbidden";
 }

package/src/utils/idle-iterator.ts

@@ -3,9 +3,11 @@ import { STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE } from "./fallback-transport";
 
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 120_000;
 const DEFAULT_STREAM_FIRST_EVENT_TIMEOUT_MS = 100_000;
+const ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS = 600_000;
 const KIMI_CODE_FIRST_EVENT_TIMEOUT_MS = 300_000;
 
 export function getProviderFirstEventTimeoutFallbackMs(provider: string): number | undefined {
+	if (provider === "alibaba-token-plan") return ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS;
 	return provider === "kimi-code" ? KIMI_CODE_FIRST_EVENT_TIMEOUT_MS : undefined;
 }
 

package/src/utils/oauth/anthropic.ts

@@ -1,7 +1,7 @@
 /**
  * Anthropic OAuth flow (Anthropic model Pro/Max)
  */
-import { OAuthCallbackFlow } from "./callback-server";
+import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "./callback-server";
 import { generatePKCE } from "./pkce";
 import type { OAuthController, OAuthCredentials } from "./types";
 
@@ -11,6 +11,17 @@ const AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
 const TOKEN_URL = "https://api.anthropic.com/v1/oauth/token";
 const CALLBACK_PORT = 54545;
 const CALLBACK_PATH = "/callback";
+/**
+ * Redirect target for the paste-a-code login. Anthropic renders the
+ * authorization code on this page instead of redirecting into this machine, so
+ * a gjc running over SSH, in a container, or on a headless box can be paired
+ * from a browser that has no route back to `localhost:54545`.
+ *
+ * Deliberately a hard-coded constant rather than an env/config override: this
+ * is where the authorization code is delivered, so making it injectable would
+ * turn any writable environment into an auth-code exfiltration channel.
+ */
+export const ANTHROPIC_MANUAL_REDIRECT_URI = "https://platform.claude.com/oauth/code/callback";
 const SCOPES = "org:create_api_key user:profile user:inference";
 
 function formatErrorDetails(error: unknown): string {
@@ -91,12 +102,30 @@ function extractAccountFromTokenResponse(data: AnthropicTokenResponse): {
 	};
 }
 
+export interface AnthropicOAuthFlowOptions {
+	/**
+	 * Pair by pasting the code Anthropic displays instead of waiting on a local
+	 * `localhost:54545` callback. Use when the browser completing the login has
+	 * no network route back to the machine running gjc.
+	 */
+	manualCode?: boolean;
+}
+
 export class AnthropicOAuthFlow extends OAuthCallbackFlow {
 	#verifier: string = "";
 	#challenge: string = "";
-
-	constructor(ctrl: OAuthController) {
-		super(ctrl, CALLBACK_PORT, CALLBACK_PATH);
+	readonly #manualCode: boolean;
+
+	constructor(ctrl: OAuthController, options: AnthropicOAuthFlowOptions = {}) {
+		const manualCode = options.manualCode === true;
+		const flowOptions: OAuthCallbackFlowOptions = {
+			preferredPort: CALLBACK_PORT,
+			callbackPath: CALLBACK_PATH,
+			redirectUri: manualCode ? ANTHROPIC_MANUAL_REDIRECT_URI : undefined,
+			skipCallbackServer: manualCode,
+		};
+		super(ctrl, flowOptions);
+		this.#manualCode = manualCode;
 	}
 
 	async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
@@ -118,8 +147,9 @@ export class AnthropicOAuthFlow extends OAuthCallbackFlow {
 
 		return {
 			url,
-			instructions:
-				"Complete login in your browser. If the browser cannot reach this machine, paste the final redirect URL or authorization code when prompted.",
+			instructions: this.#manualCode
+				? "Complete login in your browser. Anthropic will show an authorization code — paste it here."
+				: "Complete login in your browser. If the browser cannot reach this machine, paste the final redirect URL or authorization code when prompted. To pair by code instead, cancel this login and run /login anthropic --manual.",
 		};
 	}
 
@@ -167,8 +197,11 @@ export class AnthropicOAuthFlow extends OAuthCallbackFlow {
 /**
  * Login with Anthropic OAuth
  */
-export async function loginAnthropic(ctrl: OAuthController): Promise<OAuthCredentials> {
-	const flow = new AnthropicOAuthFlow(ctrl);
+export async function loginAnthropic(
+	ctrl: OAuthController,
+	options: AnthropicOAuthFlowOptions = {},
+): Promise<OAuthCredentials> {
+	const flow = new AnthropicOAuthFlow(ctrl, options);
 	return flow.login();
 }
 

package/src/utils/oauth/callback-server.ts

@@ -4,6 +4,8 @@
  * Handles:
  * - Port allocation (tries expected port, falls back to random)
  * - Callback server setup and request handling
+ * - Opting out of the local listener entirely (`skipCallbackServer`) for
+ *   providers that redirect somewhere this process cannot observe
  * - Common OAuth flow logic
  *
  * Providers extend this and implement:
@@ -27,6 +29,13 @@ export interface OAuthCallbackFlowOptions {
 	callbackBindHostname?: string;
 	/** Exact redirect URI advertised to the provider; disables port fallback. */
 	redirectUri?: string;
+	/**
+	 * Do not bind a local listener at all. The provider redirects somewhere this
+	 * process cannot observe (a hosted "copy this code" page, a custom protocol),
+	 * so the code arrives by paste instead. Requires both `redirectUri` and an
+	 * `onManualCodeInput` handler on the controller.
+	 */
+	skipCallbackServer?: boolean;
 }
 
 /**
@@ -39,6 +48,7 @@ export abstract class OAuthCallbackFlow {
 	callbackHostname: string;
 	callbackBindHostname: string;
 	redirectUri?: string;
+	readonly #skipCallbackServer: boolean;
 	#callbackResolve?: (result: CallbackResult) => void;
 	#callbackReject?: (error: string) => void;
 
@@ -53,6 +63,7 @@ export abstract class OAuthCallbackFlow {
 			this.callbackPath = callbackPath;
 			this.callbackHostname = DEFAULT_HOSTNAME;
 			this.callbackBindHostname = DEFAULT_HOSTNAME;
+			this.#skipCallbackServer = false;
 			return;
 		}
 
@@ -61,6 +72,7 @@ export abstract class OAuthCallbackFlow {
 		this.callbackHostname = preferredPortOrOptions.callbackHostname ?? DEFAULT_HOSTNAME;
 		this.callbackBindHostname = preferredPortOrOptions.callbackBindHostname ?? this.callbackHostname;
 		this.redirectUri = preferredPortOrOptions.redirectUri;
+		this.#skipCallbackServer = preferredPortOrOptions.skipCallbackServer === true;
 	}
 
 	/**
@@ -95,6 +107,13 @@ export abstract class OAuthCallbackFlow {
 	 * Execute the OAuth login flow.
 	 */
 	async login(): Promise<OAuthCredentials> {
+		if (this.#skipCallbackServer && !this.ctrl.onManualCodeInput) {
+			// Fail before a browser is opened: without a listener and without a paste
+			// handler the flow can only sit until the 5-minute timeout.
+			throw new Error(
+				"OAuth flow is configured without a local callback server, but no manual authorization-code handler was provided",
+			);
+		}
 		const state = this.generateState();
 
 		// Start callback server first to get actual redirect URI
@@ -106,7 +125,11 @@ export abstract class OAuthCallbackFlow {
 
 			// Notify controller that auth is ready
 			this.ctrl.onAuth?.({ url: authUrl, instructions });
-			this.ctrl.onProgress?.("Waiting for browser authentication...");
+			this.ctrl.onProgress?.(
+				this.#skipCallbackServer
+					? "Waiting for the authorization code..."
+					: "Waiting for browser authentication...",
+			);
 
 			// Wait for callback or manual input
 			const { code } = await this.#waitForCallback(state);
@@ -115,14 +138,23 @@ export abstract class OAuthCallbackFlow {
 
 			return await this.exchangeToken(code, state, redirectUri);
 		} finally {
-			server.stop();
+			server?.stop();
 		}
 	}
 
 	/**
 	 * Start callback server, trying preferred port first, falling back to random.
+	 * Returns no server when the flow opted out of the local listener.
 	 */
-	async #startCallbackServer(expectedState: string): Promise<{ server: Bun.Server<unknown>; redirectUri: string }> {
+	async #startCallbackServer(
+		expectedState: string,
+	): Promise<{ server: Bun.Server<unknown> | undefined; redirectUri: string }> {
+		if (this.#skipCallbackServer) {
+			if (!this.redirectUri) {
+				throw new Error("OAuth flow skips the local callback server but no redirect URI was configured");
+			}
+			return { server: undefined, redirectUri: this.redirectUri };
+		}
 		try {
 			const server = this.#createServer(this.preferredPort, expectedState);
 			if (this.redirectUri) {
@@ -216,30 +248,46 @@ export abstract class OAuthCallbackFlow {
 			this.#callbackResolve = resolve;
 			this.#callbackReject = reject;
 
-			signal.addEventListener("abort", () => {
+			const cancel = () => {
 				this.#callbackResolve = undefined;
 				this.#callbackReject = undefined;
 				reject(new Error(`OAuth callback cancelled: ${signal.reason}`));
-			});
+			};
+			// A signal that aborted before the listener was attached never fires the
+			// event. Without a local listener to fall back on there would be nothing
+			// left to settle this promise, so check the current state too.
+			if (signal.aborted) {
+				cancel();
+				return;
+			}
+			signal.addEventListener("abort", cancel);
 		});
 
+		const parseManualInput = (input: string): CallbackResult | null => {
+			const parsed = parseCallbackInput(input);
+			if (!parsed.code) return null;
+			if (expectedState && parsed.state && parsed.state !== expectedState) return null;
+			return { code: parsed.code, state: parsed.state ?? "" };
+		};
+
 		// Manual input race (if supported)
 		if (this.ctrl.onManualCodeInput) {
 			const requestManualInput = this.ctrl.onManualCodeInput;
 			const manualPromise = (async (): Promise<CallbackResult> => {
 				while (true) {
-					const result = await Promise.race([
-						callbackPromise,
-						requestManualInput()
-							.then((input): CallbackResult | null => {
-								const parsed = parseCallbackInput(input);
-								if (!parsed.code) return null;
-								if (expectedState && parsed.state && parsed.state !== expectedState) return null;
-								return { code: parsed.code, state: parsed.state ?? "" };
-							})
-							.catch((): CallbackResult | null => null),
-					]);
+					const attempt = requestManualInput().then(parseManualInput);
+					// The losing branch of the race can still reject long after the login
+					// settled (the pending prompt is cleared on teardown); keep that from
+					// surfacing as an unhandled rejection.
+					attempt.catch(() => undefined);
+					// A rejection that arrives first is a cancellation — the prompt was
+					// cleared or superseded — not a bad value. Re-prompting would spin
+					// forever, and with no local listener nothing else can settle this.
+					const result = await Promise.race([callbackPromise, attempt]);
 					if (result) return result;
+					// Yield to the macrotask queue so a handler that immediately resolves
+					// unusable values cannot starve the abort/timeout timer.
+					await Bun.sleep(0);
 				}
 			})();
 

package/src/utils/oauth/types.ts

@@ -82,6 +82,18 @@ export interface OAuthProviderInfo {
 	available: boolean;
 }
 
+/** Per-login switches that change how the authorization code is delivered. */
+export interface OAuthLoginOptions {
+	/**
+	 * Pair by pasting the authorization code the provider displays instead of
+	 * waiting on a local loopback callback. Set when the browser completing the
+	 * login has no network route back to the machine running gjc (SSH, remote
+	 * container, headless host). Providers without a paste-a-code redirect
+	 * ignore it.
+	 */
+	manualCode?: boolean;
+}
+
 export interface OAuthController {
 	onAuth?(info: OAuthAuthInfo): void;
 	onProgress?(message: string): void;