@sayknow-cli/ai 0.3.9 → 0.3.10

package/dist/types/auth-storage.d.ts

@@ -323,7 +323,14 @@ type AuthApiKeyOptions = {
      * stranding the caller for `timeoutMs * (maxRetries + 1)`.
      */
     signal?: AbortSignal;
+    /** Pin selection to one stored credential instead of using round-robin/ranking. */
+    credentialSelector?: AuthCredentialSelector;
 };
+export type AuthCredentialSelectorKind = "id" | "email" | "account" | "project";
+export interface AuthCredentialSelector {
+    kind: AuthCredentialSelectorKind;
+    value: string;
+}
 /**
  * Refreshed OAuth access plus identity metadata returned by
  * {@link AuthStorage.getOAuthAccess}. Callers that authenticate via a bearer
@@ -390,6 +397,15 @@ export declare class AuthStorage {
      * Used for CLI --api-key flag.
      */
     setRuntimeApiKey(provider: string, apiKey: string): void;
+    /**
+     * Pin credential selection for a provider (not persisted to disk).
+     * Used for CLI --credential.
+     */
+    setRuntimeCredentialSelector(provider: string, selector: AuthCredentialSelector): void;
+    /**
+     * Remove a runtime credential selector.
+     */
+    removeRuntimeCredentialSelector(provider: string): void;
     /**
      * Remove a runtime API key override.
      */

package/dist/types/types.d.ts

@@ -84,7 +84,7 @@ export type CacheRetention = "none" | "short" | "long";
  *
  * The unscoped values (`"auto"`, `"default"`, `"flex"`, `"scale"`,
  * `"priority"`) are passed through to providers that understand them
- * (OpenAI's `service_tier` field directly; Anthropic translates
+ * (OpenAI and DeepInfra's `service_tier` field directly; Anthropic translates
  * `"priority"` into `speed: "fast"` on supported Opus models).
  *
  * The scoped values target a specific provider family and behave as the
@@ -105,10 +105,9 @@ export type ResolvedServiceTier = Exclude<ServiceTier, "openai-only" | "claude-o
  */
 export declare function resolveServiceTier(serviceTier: ServiceTier | null | undefined, provider: Provider | undefined): ResolvedServiceTier | undefined;
 /**
- * True when the (possibly scoped) tier should be sent as OpenAI's
- * `service_tier` request field for the given provider. OpenAI accepts
- * `flex`, `scale`, and `priority`; DeepInfra accepts `priority`.
- * Unsupported tiers (`"auto"`, `"default"`) and scope mismatches return false.
+ * True when the (possibly scoped) tier should be sent as an OpenAI-compatible
+ * `service_tier` request field for providers that support it. Unsupported tiers
+ * (`"auto"`, `"default"`) and scope mismatches all return false.
  */
 export declare function shouldSendServiceTier(serviceTier: ServiceTier | null | undefined, provider: Provider | undefined): boolean;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/ai",
-	"version": "0.3.9",
+	"version": "0.3.10",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@sayknow-cli/utils": "0.3.9",
+		"@sayknow-cli/utils": "0.3.10",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-storage.ts

@@ -493,7 +493,16 @@ type AuthApiKeyOptions = {
 	 * stranding the caller for `timeoutMs * (maxRetries + 1)`.
 	 */
 	signal?: AbortSignal;
+	/** Pin selection to one stored credential instead of using round-robin/ranking. */
+	credentialSelector?: AuthCredentialSelector;
 };
+export type AuthCredentialSelectorKind = "id" | "email" | "account" | "project";
+
+export interface AuthCredentialSelector {
+	kind: AuthCredentialSelectorKind;
+	value: string;
+}
+
 type OAuthResolutionResult = { apiKey: string; credential: OAuthCredential };
 
 /**
@@ -696,6 +705,7 @@ export class AuthStorage {
 	#data: Map<string, StoredCredential[]> = new Map();
 	#runtimeOverrides: Map<string, string> = new Map();
 	#configOverrides: Map<string, string> = new Map();
+	#runtimeCredentialSelectors: Map<string, AuthCredentialSelector> = new Map();
 	/** Tracks next credential index per provider:type key for round-robin distribution (non-session use). */
 	#providerRoundRobinIndex: Map<string, number> = new Map();
 	/** Tracks the last used credential per provider for a session (used for rate-limit switching). */
@@ -846,6 +856,23 @@ export class AuthStorage {
 		this.#runtimeOverrides.set(provider, apiKey);
 	}
 
+	/**
+	 * Pin credential selection for a provider (not persisted to disk).
+	 * Used for CLI --credential.
+	 */
+	setRuntimeCredentialSelector(provider: string, selector: AuthCredentialSelector): void {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		this.#assertCredentialSelectorUsable(storageProvider, selector);
+		this.#runtimeCredentialSelectors.set(storageProvider, selector);
+	}
+
+	/**
+	 * Remove a runtime credential selector.
+	 */
+	removeRuntimeCredentialSelector(provider: string): void {
+		this.#runtimeCredentialSelectors.delete(resolveOAuthStorageProvider(provider));
+	}
+
 	/**
 	 * Remove a runtime API key override.
 	 */
@@ -1122,6 +1149,72 @@ export class AuthStorage {
 		}
 	}
 
+	#formatCredentialSelector(selector: AuthCredentialSelector): string {
+		return `${selector.kind}:${selector.value}`;
+	}
+
+	#credentialMatchesSelector(entry: StoredCredential, selector: AuthCredentialSelector): boolean {
+		switch (selector.kind) {
+			case "id":
+				return String(entry.id) === selector.value;
+			case "email":
+				return (
+					entry.credential.type === "oauth" &&
+					typeof entry.credential.email === "string" &&
+					entry.credential.email.toLowerCase() === selector.value.toLowerCase()
+				);
+			case "account":
+				return entry.credential.type === "oauth" && entry.credential.accountId === selector.value;
+			case "project":
+				return entry.credential.type === "oauth" && entry.credential.projectId === selector.value;
+		}
+	}
+
+	#findCredentialBySelector(
+		provider: string,
+		selector: AuthCredentialSelector,
+	): ({ index: number } & StoredCredential) | undefined {
+		const stored = this.#getStoredCredentials(provider);
+		for (let index = 0; index < stored.length; index++) {
+			const entry = stored[index];
+			if (entry && this.#credentialMatchesSelector(entry, selector)) return { ...entry, index };
+		}
+		return undefined;
+	}
+
+	#getCredentialSelector(provider: string, options?: AuthApiKeyOptions): AuthCredentialSelector | undefined {
+		return options?.credentialSelector ?? this.#runtimeCredentialSelectors.get(resolveOAuthStorageProvider(provider));
+	}
+
+	#assertCredentialSelectorUsable(provider: string, selector: AuthCredentialSelector): void {
+		if (this.#runtimeOverrides.has(provider)) {
+			throw new Error(
+				`Credential selector ${this.#formatCredentialSelector(selector)} cannot be used for ${provider} while a runtime API key override is active`,
+			);
+		}
+		if (this.#configOverrides.has(provider)) {
+			throw new Error(
+				`Credential selector ${this.#formatCredentialSelector(selector)} cannot be used for ${provider} while a config API key override is active`,
+			);
+		}
+		if (!this.#findCredentialBySelector(provider, selector)) {
+			throw new Error(`No credential found for ${provider} matching ${this.#formatCredentialSelector(selector)}`);
+		}
+	}
+
+	#resolveSelectedStoredCredential(
+		provider: string,
+		options?: AuthApiKeyOptions,
+	): ({ index: number } & StoredCredential) | undefined {
+		const selector = this.#getCredentialSelector(provider, options);
+		if (!selector) return undefined;
+		this.#assertCredentialSelectorUsable(resolveOAuthStorageProvider(provider), selector);
+		const selected = this.#findCredentialBySelector(provider, selector);
+		if (!selected) {
+			throw new Error(`No credential found for ${provider} matching ${this.#formatCredentialSelector(selector)}`);
+		}
+		return selected;
+	}
 	/**
 	 * Selects a credential of the specified type for a provider.
 	 * Returns both the credential and its index in the original array (for updates/removal).
@@ -2734,17 +2827,28 @@ export class AuthStorage {
 		sessionId?: string,
 		options?: AuthApiKeyOptions,
 	): Promise<OAuthResolutionResult | undefined> {
-		const credentials = this.#getCredentialsForProvider(provider)
-			.map((credential, index) => ({ credential, index }))
-			.filter((entry): entry is { credential: OAuthCredential; index: number } => entry.credential.type === "oauth");
+		const selectedCredential = this.#resolveSelectedStoredCredential(provider, options);
+		const selectedOAuthCredential =
+			selectedCredential?.credential.type === "oauth"
+				? { credential: selectedCredential.credential, index: selectedCredential.index }
+				: undefined;
+		if (selectedCredential && !selectedOAuthCredential) return undefined;
+		const credentials = selectedOAuthCredential
+			? [selectedOAuthCredential]
+			: this.#getCredentialsForProvider(provider)
+					.map((credential, index) => ({ credential, index }))
+					.filter(
+						(entry): entry is { credential: OAuthCredential; index: number } => entry.credential.type === "oauth",
+					);
 
 		if (credentials.length === 0) return undefined;
 
 		const providerKey = this.#getProviderTypeKey(provider, "oauth");
-		const order = this.#getCredentialOrder(providerKey, sessionId, credentials.length);
+		const order = selectedCredential ? [0] : this.#getCredentialOrder(providerKey, sessionId, credentials.length);
 		const strategy = this.#rankingStrategyResolver?.(provider);
 		const requiresProModel = requiresOpenAICodexProModel(provider, options?.modelId);
-		const checkUsage = strategy !== undefined && (credentials.length > 1 || requiresProModel);
+		const checkUsage =
+			strategy !== undefined && (selectedCredential !== undefined || credentials.length > 1 || requiresProModel);
 		const sessionCredential = this.#getSessionCredential(provider, sessionId);
 		const sessionPreferredIndex = sessionCredential?.type === "oauth" ? sessionCredential.index : undefined;
 		// Skip ranking only when the session already has a working preferred credential — re-ranking
@@ -2753,7 +2857,7 @@ export class AuthStorage {
 		// with the most headroom proactively and fall back intelligently when rate-limited.
 		const sessionPreferredIsAvailable =
 			sessionPreferredIndex !== undefined && !this.#isCredentialBlocked(providerKey, sessionPreferredIndex);
-		const shouldRank = checkUsage && (!sessionPreferredIsAvailable || requiresProModel);
+		const shouldRank = !selectedCredential && checkUsage && (!sessionPreferredIsAvailable || requiresProModel);
 		const candidates = shouldRank
 			? await this.#rankOAuthSelections({ providerKey, provider, order, credentials, options, strategy: strategy! })
 			: order
@@ -2761,7 +2865,7 @@ export class AuthStorage {
 					.filter((selection): selection is { credential: OAuthCredential; index: number } => Boolean(selection))
 					.map(selection => ({ selection, usage: null, usageChecked: false }));
 
-		if (sessionPreferredIndex !== undefined && !requiresProModel) {
+		if (!selectedCredential && sessionPreferredIndex !== undefined && !requiresProModel) {
 			const sessionPreferredCandidate = candidates.findIndex(
 				candidate =>
 					!this.#isCredentialBlocked(providerKey, candidate.selection.index) &&
@@ -3118,7 +3222,10 @@ export class AuthStorage {
 					await this.reload();
 					return this.#resolveOAuthSelection(provider, sessionId, options);
 				}
-				if (this.#getCredentialsForProvider(provider).some(credential => credential.type === "oauth")) {
+				if (
+					!this.#getCredentialSelector(provider, options) &&
+					this.#getCredentialsForProvider(provider).some(credential => credential.type === "oauth")
+				) {
 					return this.#resolveOAuthSelection(provider, sessionId, options);
 				}
 			} else {
@@ -3126,6 +3233,12 @@ export class AuthStorage {
 				this.#markCredentialBlocked(providerKey, selection.index, Date.now() + 5 * 60 * 1000);
 			}
 		}
+		if (this.#getCredentialSelector(provider, options)) {
+			const selector = this.#getCredentialSelector(provider, options);
+			throw new Error(
+				`Selected credential for ${provider} (${selector ? this.#formatCredentialSelector(selector) : "unknown"}) is unavailable`,
+			);
+		}
 
 		return undefined;
 	}
@@ -3184,6 +3297,8 @@ export class AuthStorage {
 	 * 6. Fallback resolver (models.yml custom providers, last-resort)
 	 */
 	async getApiKey(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined> {
+		const selectedCredential = this.#resolveSelectedStoredCredential(provider, options);
+
 		// Runtime override takes highest priority
 		const runtimeKey = this.#runtimeOverrides.get(provider);
 		if (runtimeKey) {
@@ -3200,10 +3315,17 @@ export class AuthStorage {
 			return configKey;
 		}
 
-		const apiKeySelection = this.#selectCredentialByType(provider, "api_key", sessionId);
-		if (apiKeySelection) {
-			this.#recordSessionCredential(provider, sessionId, "api_key", apiKeySelection.index);
-			return this.#configValueResolver(apiKeySelection.credential.key);
+		if (selectedCredential?.credential.type === "api_key") {
+			this.#recordSessionCredential(provider, sessionId, "api_key", selectedCredential.index);
+			return this.#configValueResolver(selectedCredential.credential.key);
+		}
+
+		if (!selectedCredential) {
+			const apiKeySelection = this.#selectCredentialByType(provider, "api_key", sessionId);
+			if (apiKeySelection) {
+				this.#recordSessionCredential(provider, sessionId, "api_key", apiKeySelection.index);
+				return this.#configValueResolver(apiKeySelection.credential.key);
+			}
 		}
 
 		const oauthResolved = await this.#resolveOAuthSelection(provider, sessionId, options);