@sayknow-cli/ai 0.3.16 → 0.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/ai",
-	"version": "0.3.16",
+	"version": "0.4.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -27,7 +27,7 @@
 		"api"
 	],
 	"main": "./src/index.ts",
-	"types": "./dist/types/index.d.ts",
+	"types": "./src/index.ts",
 	"bin": {
 		"pi-ai": "./src/cli.ts"
 	},
@@ -57,88 +57,87 @@
 	"files": [
 		"src",
 		"README.md",
-		"CHANGELOG.md",
-		"dist/types"
+		"CHANGELOG.md"
 	],
 	"exports": {
 		".": {
-			"types": "./dist/types/index.d.ts",
+			"types": "./src/index.ts",
 			"import": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./dist/types/*.d.ts",
+			"types": "./src/*.ts",
 			"import": "./src/*.ts"
 		},
 		"./auth-broker": {
-			"types": "./dist/types/auth-broker/index.d.ts",
+			"types": "./src/auth-broker/index.ts",
 			"import": "./src/auth-broker/index.ts"
 		},
 		"./auth-broker/*": {
-			"types": "./dist/types/auth-broker/*.d.ts",
+			"types": "./src/auth-broker/*.ts",
 			"import": "./src/auth-broker/*.ts"
 		},
 		"./auth-gateway": {
-			"types": "./dist/types/auth-gateway/index.d.ts",
+			"types": "./src/auth-gateway/index.ts",
 			"import": "./src/auth-gateway/index.ts"
 		},
 		"./auth-gateway/*": {
-			"types": "./dist/types/auth-gateway/*.d.ts",
+			"types": "./src/auth-gateway/*.ts",
 			"import": "./src/auth-gateway/*.ts"
 		},
 		"./models.json": {
-			"types": "./dist/types/models.json.d.d.ts",
+			"types": "./src/models.json.d.ts",
 			"import": "./src/models.json"
 		},
 		"./provider-models": {
-			"types": "./dist/types/provider-models/index.d.ts",
+			"types": "./src/provider-models/index.ts",
 			"import": "./src/provider-models/index.ts"
 		},
 		"./provider-models/*": {
-			"types": "./dist/types/provider-models/*.d.ts",
+			"types": "./src/provider-models/*.ts",
 			"import": "./src/provider-models/*.ts"
 		},
 		"./providers/*": {
-			"types": "./dist/types/providers/*.d.ts",
+			"types": "./src/providers/*.ts",
 			"import": "./src/providers/*.ts"
 		},
 		"./providers/cursor/gen/*": {
-			"types": "./dist/types/providers/cursor/gen/*.d.ts",
+			"types": "./src/providers/cursor/gen/*.ts",
 			"import": "./src/providers/cursor/gen/*.ts"
 		},
 		"./providers/openai-codex/*": {
-			"types": "./dist/types/providers/openai-codex/*.d.ts",
+			"types": "./src/providers/openai-codex/*.ts",
 			"import": "./src/providers/openai-codex/*.ts"
 		},
 		"./usage/*": {
-			"types": "./dist/types/usage/*.d.ts",
+			"types": "./src/usage/*.ts",
 			"import": "./src/usage/*.ts"
 		},
 		"./utils/*": {
-			"types": "./dist/types/utils/*.d.ts",
+			"types": "./src/utils/*.ts",
 			"import": "./src/utils/*.ts"
 		},
 		"./utils/discovery": {
-			"types": "./dist/types/utils/discovery/index.d.ts",
+			"types": "./src/utils/discovery/index.ts",
 			"import": "./src/utils/discovery/index.ts"
 		},
 		"./utils/discovery/*": {
-			"types": "./dist/types/utils/discovery/*.d.ts",
+			"types": "./src/utils/discovery/*.ts",
 			"import": "./src/utils/discovery/*.ts"
 		},
 		"./utils/oauth": {
-			"types": "./dist/types/utils/oauth/index.d.ts",
+			"types": "./src/utils/oauth/index.ts",
 			"import": "./src/utils/oauth/index.ts"
 		},
 		"./utils/oauth/*": {
-			"types": "./dist/types/utils/oauth/*.d.ts",
+			"types": "./src/utils/oauth/*.ts",
 			"import": "./src/utils/oauth/*.ts"
 		},
 		"./utils/schema": {
-			"types": "./dist/types/utils/schema/index.d.ts",
+			"types": "./src/utils/schema/index.ts",
 			"import": "./src/utils/schema/index.ts"
 		},
 		"./utils/schema/*": {
-			"types": "./dist/types/utils/schema/*.d.ts",
+			"types": "./src/utils/schema/*.ts",
 			"import": "./src/utils/schema/*.ts"
 		},
 		"./*.js": "./src/*.ts"

package/src/auth-gateway/server.ts

@@ -17,6 +17,7 @@
  *   POST /v1/messages                      → Anthropic messages in/out
  *   POST /v1/responses                     → OpenAI Responses in/out
  */
+
 import { logger } from "@sayknow-cli/utils";
 import type { AuthStorage } from "../auth-storage";
 import { Effort } from "../model-thinking";
@@ -26,6 +27,7 @@ import * as openaiResponses from "../providers/openai-responses-server";
 import * as piNative from "../providers/pi-native-server";
 import { streamSimple } from "../stream";
 import type { Api, AssistantMessageEventStream, Context, Model, SimpleStreamOptions } from "../types";
+import { beginAttempt, classifyFallbackTrigger } from "../utils/fallback-transport";
 import { parseBind } from "../utils/parse-bind";
 import {
 	captureRequestHeaders,
@@ -260,6 +262,90 @@ async function refreshGatewayApiKeyAfterAuthError(
 	return storage.getApiKey(provider, undefined, { modelId: model.id, signal });
 }
 
+/**
+ * Records a managed gateway failure against the credential selected for this
+ * request. This deliberately never returns a replacement key: the outer
+ * fallback controller owns the next attempt and is the only component allowed
+ * to make another upstream request.
+ */
+async function markManagedGatewayCredentialFailure(
+	storage: AuthStorage,
+	model: Model<Api>,
+	apiKey: string,
+	error: unknown,
+	signal: AbortSignal,
+	format: string,
+	peer: string,
+): Promise<void> {
+	const trigger = classifyFallbackTrigger(error);
+	try {
+		if (trigger.class === "auth") {
+			await storage.invalidateCredentialMatching(model.provider, apiKey, signal);
+		} else if (trigger.class === "quota" || trigger.class === "rate_limit") {
+			await storage.markUsageLimitReached(model.provider, undefined, {
+				retryAfterMs: trigger.retryAfterMs,
+				signal,
+			});
+		} else {
+			return;
+		}
+		logger.debug("auth-gateway recorded managed credential failure", {
+			format,
+			provider: model.provider,
+			peer,
+			trigger: trigger.class,
+		});
+	} catch (markError) {
+		// Credential bookkeeping must not replace the upstream failure returned to
+		// the fallback controller.
+		logger.warn("auth-gateway failed to record managed credential failure", {
+			format,
+			provider: model.provider,
+			peer,
+			error: markError instanceof Error ? markError.message : String(markError),
+		});
+	}
+}
+
+function observeManagedGatewayFailure(
+	events: AssistantMessageEventStream,
+	markFailure: (error: unknown) => Promise<void>,
+): AssistantMessageEventStream {
+	let marked = false;
+	const markOnce = async (error: unknown): Promise<void> => {
+		if (marked) return;
+		marked = true;
+		await markFailure(error);
+	};
+	async function* observed() {
+		try {
+			for await (const event of events) {
+				if (event.type === "error") {
+					await markOnce(event.error.transportFailure ?? { kind: "transport", status: event.error.errorStatus });
+				}
+				yield event;
+			}
+		} catch (error) {
+			await markOnce(error);
+			throw error;
+		}
+	}
+	const result = observed() as unknown as AssistantMessageEventStream;
+	result.result = async () => {
+		try {
+			const message = await events.result();
+			if (message.stopReason === "error") {
+				await markOnce(message.transportFailure ?? { kind: "transport", status: message.errorStatus });
+			}
+			return message;
+		} catch (error) {
+			await markOnce(error);
+			throw error;
+		}
+	};
+	return result;
+}
+
 function clientClosedResponse(route: { module: FormatModule }): Response {
 	return route.module.formatError(499, "request_aborted", "client closed request");
 }
@@ -361,17 +447,21 @@ async function handleFormatEndpoint(
 
 	const streamOpts = buildStreamOptions(parsed, model.api, controller.signal);
 	streamOpts.apiKey = apiKey;
-	streamOpts.onAuthError = (provider, oldKey, error) =>
-		refreshGatewayApiKeyAfterAuthError(
-			bootOpts.storage,
-			model,
-			provider,
-			oldKey,
-			error,
-			controller.signal,
-			route.label,
-			peer,
-		);
+	if (streamOpts.fallbackManaged) {
+		streamOpts.fallbackAttempt = beginAttempt(model.id, "auth-gateway");
+	} else {
+		streamOpts.onAuthError = (provider, oldKey, error) =>
+			refreshGatewayApiKeyAfterAuthError(
+				bootOpts.storage,
+				model,
+				provider,
+				oldKey,
+				error,
+				controller.signal,
+				route.label,
+				peer,
+			);
+	}
 
 	logger.info("auth-gateway request", {
 		format: route.label,
@@ -387,10 +477,34 @@ async function handleFormatEndpoint(
 		if (controller.signal.aborted) return clientClosedResponse(route);
 		events = streamSimple(model, parsed.context, streamOpts);
 	} catch (error) {
+		if (streamOpts.fallbackManaged) {
+			await markManagedGatewayCredentialFailure(
+				bootOpts.storage,
+				model,
+				apiKey,
+				error,
+				controller.signal,
+				route.label,
+				peer,
+			);
+		}
 		const classified = classifyGatewayError(error);
 		logger.warn("auth-gateway streamSimple threw", { format: route.label, error: classified.message, peer });
 		return route.module.formatError(classified.status, classified.type, classified.message);
 	}
+	if (streamOpts.fallbackManaged) {
+		events = observeManagedGatewayFailure(events, error =>
+			markManagedGatewayCredentialFailure(
+				bootOpts.storage,
+				model,
+				apiKey,
+				error,
+				controller.signal,
+				route.label,
+				peer,
+			),
+		);
+	}
 
 	if (!parsed.stream) {
 		try {
@@ -509,17 +623,21 @@ async function handlePiNative(bootOpts: AuthGatewayBootOptions, req: Request, pe
 	// only inject server-controlled fields. The OpenAI code backend temperature/topP strip
 	// matches `buildStreamOptions` — OpenAI code backend rejects them with a 400.
 	const streamOpts: SimpleStreamOptions = { ...parsed.options, apiKey, signal: controller.signal };
-	streamOpts.onAuthError = (provider, oldKey, error) =>
-		refreshGatewayApiKeyAfterAuthError(
-			bootOpts.storage,
-			model,
-			provider,
-			oldKey,
-			error,
-			controller.signal,
-			"pi-native",
-			peer,
-		);
+	if (streamOpts.fallbackManaged) {
+		streamOpts.fallbackAttempt = beginAttempt(model.id, "auth-gateway-pi-native");
+	} else {
+		streamOpts.onAuthError = (provider, oldKey, error) =>
+			refreshGatewayApiKeyAfterAuthError(
+				bootOpts.storage,
+				model,
+				provider,
+				oldKey,
+				error,
+				controller.signal,
+				"pi-native",
+				peer,
+			);
+	}
 	if (model.api === "openai-codex-responses") {
 		delete streamOpts.temperature;
 		delete streamOpts.topP;
@@ -547,10 +665,34 @@ async function handlePiNative(bootOpts: AuthGatewayBootOptions, req: Request, pe
 		if (controller.signal.aborted) return aborted();
 		events = streamSimple(model, parsed.context, streamOpts);
 	} catch (error) {
+		if (streamOpts.fallbackManaged) {
+			await markManagedGatewayCredentialFailure(
+				bootOpts.storage,
+				model,
+				apiKey,
+				error,
+				controller.signal,
+				"pi-native",
+				peer,
+			);
+		}
 		const classified = classifyGatewayError(error);
 		logger.warn("auth-gateway streamSimple threw", { format: "pi-native", error: classified.message, peer });
 		return piNative.formatError(classified.status, classified.type, classified.message);
 	}
+	if (streamOpts.fallbackManaged) {
+		events = observeManagedGatewayFailure(events, error =>
+			markManagedGatewayCredentialFailure(
+				bootOpts.storage,
+				model,
+				apiKey,
+				error,
+				controller.signal,
+				"pi-native",
+				peer,
+			),
+		);
+	}
 
 	if (!parsed.stream) {
 		try {

package/src/auth-storage.ts

@@ -775,7 +775,9 @@ export class AuthStorage {
 	 */
 	static async create(dbPath: string, options: AuthStorageOptions = {}): Promise<AuthStorage> {
 		const store = await SqliteAuthCredentialStore.open(dbPath);
-		return new AuthStorage(store, options);
+		const storage = new AuthStorage(store, options);
+		await storage.reload();
+		return storage;
 	}
 
 	/**
@@ -854,6 +856,7 @@ export class AuthStorage {
 	 */
 	setRuntimeApiKey(provider: string, apiKey: string): void {
 		this.#runtimeOverrides.set(provider, apiKey);
+		this.#bumpGeneration("set-runtime-api-key");
 	}
 
 	/**
@@ -877,7 +880,12 @@ export class AuthStorage {
 	 * Remove a runtime API key override.
 	 */
 	removeRuntimeApiKey(provider: string): void {
-		this.#runtimeOverrides.delete(provider);
+		if (this.#runtimeOverrides.delete(provider)) this.#bumpGeneration("remove-runtime-api-key");
+	}
+
+	/** Whether a provider is currently authenticated by a runtime API-key override. */
+	hasRuntimeApiKey(provider: string): boolean {
+		return Boolean(this.#runtimeOverrides.get(provider));
 	}
 
 	/**
@@ -892,13 +900,14 @@ export class AuthStorage {
 	 */
 	setConfigApiKey(provider: string, apiKey: string): void {
 		this.#configOverrides.set(provider, apiKey);
+		this.#bumpGeneration("set-config-api-key");
 	}
 
 	/**
 	 * Remove a single config-sourced API key override.
 	 */
 	removeConfigApiKey(provider: string): void {
-		this.#configOverrides.delete(provider);
+		if (this.#configOverrides.delete(provider)) this.#bumpGeneration("remove-config-api-key");
 	}
 
 	/**
@@ -906,7 +915,9 @@ export class AuthStorage {
 	 * re-parsing `models.yml` so removed entries actually disappear.
 	 */
 	clearConfigApiKeys(): void {
+		if (this.#configOverrides.size === 0) return;
 		this.#configOverrides.clear();
+		this.#bumpGeneration("clear-config-api-keys");
 	}
 
 	/**
@@ -2067,7 +2078,11 @@ export class AuthStorage {
 		});
 	}
 
-	async #fetchUsageUncached(request: UsageRequestDescriptor, timeoutMs?: number): Promise<UsageReport | null> {
+	async #fetchUsageUncached(
+		request: UsageRequestDescriptor,
+		timeoutMs?: number,
+		logDetails: boolean = true,
+	): Promise<UsageReport | null> {
 		const resolver = this.#usageProviderResolver;
 		if (!resolver) return null;
 
@@ -2105,10 +2120,12 @@ export class AuthStorage {
 						credential: refreshedCredential,
 					};
 				} catch (error) {
-					this.#usageLogger?.debug("Usage credential refresh failed, using original credential", {
-						provider: request.provider,
-						error: String(error),
-					});
+					if (logDetails) {
+						this.#usageLogger?.debug("Usage credential refresh failed, using original credential", {
+							provider: request.provider,
+							error: String(error),
+						});
+					}
 				}
 			}
 		}
@@ -2118,18 +2135,24 @@ export class AuthStorage {
 		try {
 			return await providerImpl.fetchUsage(params, {
 				fetch: this.#usageFetch,
-				logger: this.#usageLogger,
+				logger: logDetails ? this.#usageLogger : undefined,
 			});
 		} catch (error) {
-			logger.debug("AuthStorage usage fetch failed", {
-				provider: request.provider,
-				error: String(error),
-			});
+			if (logDetails) {
+				logger.debug("AuthStorage usage fetch failed", {
+					provider: request.provider,
+					error: String(error),
+				});
+			}
 			return null;
 		}
 	}
 
-	async #fetchUsageCached(request: UsageRequestDescriptor, timeoutMs?: number): Promise<UsageReport | null> {
+	async #fetchUsageCached(
+		request: UsageRequestDescriptor,
+		timeoutMs?: number,
+		logDetails: boolean = true,
+	): Promise<UsageReport | null> {
 		const cacheKey = this.#buildUsageReportCacheKey(request);
 		const now = Date.now();
 		const cached = this.#usageCache.get<UsageReport | null>(cacheKey);
@@ -2142,7 +2165,7 @@ export class AuthStorage {
 		if (inFlight) return inFlight;
 
 		const promise = (async () => {
-			const report = await this.#fetchUsageUncached(request, timeoutMs);
+			const report = await this.#fetchUsageUncached(request, timeoutMs, logDetails);
 			const ttlJitter = USAGE_REPORT_TTL_MS * (Math.random() * 0.5 - 0.25);
 			if (report !== null) {
 				// Success: stagger per-credential cache expiry so all accounts don't
@@ -2385,6 +2408,8 @@ export class AuthStorage {
 		baseUrlResolver?: (provider: Provider) => string | undefined;
 		/** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
 		signal?: AbortSignal;
+		/** Disable provider/account/error logging for secret-safe control surfaces. */
+		logDetails?: boolean;
 	}): Promise<UsageReport[] | null> {
 		// Caller override > store-level hook > local per-credential fan-out.
 		// `RemoteAuthCredentialStore` implements the store hook so a gateway
@@ -2413,9 +2438,11 @@ export class AuthStorage {
 		const requests = this.#collectUsageRequests(options);
 		if (requests.length === 0) return [];
 
-		this.#usageLogger?.debug("Usage fetch requested", {
-			providers: [...new Set(requests.map(request => request.provider))].sort(),
-		});
+		if (options?.logDetails !== false) {
+			this.#usageLogger?.debug("Usage fetch requested", {
+				providers: [...new Set(requests.map(request => request.provider))].sort(),
+			});
+		}
 
 		// Per-credential caching with jitter lives in #fetchUsageCached, so we
 		// don't store the aggregated result here — doing so locks the widget to
@@ -2428,39 +2455,45 @@ export class AuthStorage {
 		if (inFlight) return inFlight;
 
 		const promise = (async () => {
-			for (const request of requests) {
-				this.#usageLogger?.debug("Usage fetch queued", {
-					provider: request.provider,
-					credentialType: request.credential.type,
-					baseUrl: request.baseUrl,
-					accountId: request.credential.accountId,
-					email: request.credential.email,
-				});
+			if (options?.logDetails !== false) {
+				for (const request of requests) {
+					this.#usageLogger?.debug("Usage fetch queued", {
+						provider: request.provider,
+						credentialType: request.credential.type,
+						baseUrl: request.baseUrl,
+						accountId: request.credential.accountId,
+						email: request.credential.email,
+					});
+				}
 			}
 
 			const results = await Promise.all(
-				requests.map(request => this.#fetchUsageCached(request, this.#usageRequestTimeoutMs)),
+				requests.map(request =>
+					this.#fetchUsageCached(request, this.#usageRequestTimeoutMs, options?.logDetails !== false),
+				),
 			);
 			const reports = results.filter((report): report is UsageReport => report !== null);
 			const deduped = this.#dedupeUsageReports(reports);
 			// no outer cache write — see comment above.
 			const resolved = deduped;
-			this.#usageLogger?.debug("Usage fetch resolved", {
-				reports: resolved.map(report => {
-					const accountLabel =
-						this.#getUsageReportMetadataValue(report, "email") ??
-						this.#getUsageReportMetadataValue(report, "accountId") ??
-						this.#getUsageReportMetadataValue(report, "account") ??
-						this.#getUsageReportMetadataValue(report, "user") ??
-						this.#getUsageReportMetadataValue(report, "username") ??
-						this.#getUsageReportScopeAccountId(report);
-					return {
-						provider: report.provider,
-						limits: report.limits.length,
-						account: accountLabel,
-					};
-				}),
-			});
+			if (options?.logDetails !== false) {
+				this.#usageLogger?.debug("Usage fetch resolved", {
+					reports: resolved.map(report => {
+						const accountLabel =
+							this.#getUsageReportMetadataValue(report, "email") ??
+							this.#getUsageReportMetadataValue(report, "accountId") ??
+							this.#getUsageReportMetadataValue(report, "account") ??
+							this.#getUsageReportMetadataValue(report, "user") ??
+							this.#getUsageReportMetadataValue(report, "username") ??
+							this.#getUsageReportScopeAccountId(report);
+						return {
+							provider: report.provider,
+							limits: report.limits.length,
+							account: accountLabel,
+						};
+					}),
+				});
+			}
 			return resolved;
 		})().finally(() => {
 			this.#usageReportsInFlight.delete(cacheKey);

package/src/context-cap-policy.ts

@@ -0,0 +1,59 @@
+import type { Api, Model } from "./types";
+
+export interface CodexGpt56ContextCapPolicy {
+	fallback: number;
+	ceiling: number;
+}
+
+export const CODEX_GPT_5_6_CONTEXT_CAP: CodexGpt56ContextCapPolicy = {
+	fallback: 272_000,
+	ceiling: 272_000,
+};
+
+const CODEX_GPT_5_6_MODEL_IDS: ReadonlySet<string> = new Set([
+	"gpt-5.6",
+	"gpt-5.6-sol",
+	"gpt-5.6-terra",
+	"gpt-5.6-luna",
+]);
+
+export function isCodexProductTransport(model: Pick<Model<Api>, "api" | "provider">): boolean {
+	return model.provider === "openai-codex" || model.api === "openai-codex-responses";
+}
+
+export function isCodexGpt56Tier(model: Pick<Model<Api>, "id">): boolean {
+	return CODEX_GPT_5_6_MODEL_IDS.has(model.id.toLowerCase());
+}
+
+export function resolveCodexGpt56DiscoveryContext(
+	model: Pick<Model<Api>, "api" | "id" | "provider">,
+	rawContextWindow: unknown,
+	policy: CodexGpt56ContextCapPolicy = CODEX_GPT_5_6_CONTEXT_CAP,
+): number {
+	const observed = isPositiveFiniteNumber(rawContextWindow) ? rawContextWindow : policy.fallback;
+	if (!isCodexGpt56Tier(model) || !isCodexProductTransport(model)) {
+		return observed;
+	}
+	return Math.min(observed, policy.ceiling);
+}
+
+export function applyFinalCodexGpt56ContextCap<TApi extends Api>(
+	models: readonly Model<TApi>[],
+	policy: CodexGpt56ContextCapPolicy = CODEX_GPT_5_6_CONTEXT_CAP,
+): Model<TApi>[] {
+	return models.map(model => {
+		if (
+			!isCodexGpt56Tier(model as Model<Api>) ||
+			!isCodexProductTransport(model as Model<Api>) ||
+			!isPositiveFiniteNumber(model.contextWindow) ||
+			model.contextWindow <= policy.ceiling
+		) {
+			return model;
+		}
+		return { ...model, contextWindow: policy.ceiling };
+	});
+}
+
+function isPositiveFiniteNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./auth-broker";
 export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } from "./auth-gateway/server";
 export * from "./auth-gateway/types";
 export * from "./auth-storage";
+export * from "./context-cap-policy";
 export * from "./model-cache";
 export * from "./model-manager";
 export * from "./model-thinking";
@@ -41,6 +42,7 @@ export * from "./usage/zai";
 export * from "./utils/anthropic-auth";
 export * from "./utils/discovery";
 export * from "./utils/event-stream";
+export * from "./utils/fallback-transport";
 export * from "./utils/h2-fetch";
 export * from "./utils/oauth";
 export type {