@sayknow-cli/ai 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-06-23
+
+### Changed
+
+- Reworked the unofficial, opt-in `glm-zcode` provider to mirror how the ZCode desktop app actually reaches GLM: after the ZCode OAuth handshake it now auto-provisions a real Z.AI API key and calls `api.z.ai/api/anthropic` directly, instead of the `zcode.z.ai` coding-plan gateway that required an Aliyun captcha and a ZCode-JWT-bound plan entitlement. Requests also carry ZCode client source headers (`User-Agent: ZCode/<ver>`, `X-ZCode-Agent: glm`, plus platform/locale/timezone), so Z.AI recognizes the caller as the ZCode client (#1013, #1016, #1017).
+
+## [0.7.0] - 2026-06-22
+
+### Added
+
+- Added the bundled `google-gemini-cli/gemini-3.5-flash` model entry so Gemini CLI users can select the model from the static registry (#965).
+
 ## [0.6.4] - 2026-06-20
 
 ### Fixed

package/dist/types/auth-broker/client.d.ts

@@ -1,5 +1,5 @@
 import type { AuthCredential } from "../auth-storage";
-import type { CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse } from "./types";
+import type { CredentialDisableResponse, CredentialIfAbsentUploadResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse } from "./types";
 export interface AuthBrokerClientOptions {
     /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
     url: string;
@@ -63,4 +63,5 @@ export declare class AuthBrokerClient {
     refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
     uploadCredential(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialUploadResponse>;
+    uploadCredentialIfAbsent(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialIfAbsentUploadResponse>;
 }

package/dist/types/auth-broker/remote-store.d.ts

@@ -1,4 +1,4 @@
-import { type AuthCredential, type AuthCredentialStore, type OAuthCredential, type StoredAuthCredential } from "../auth-storage";
+import { type AuthCredential, type AuthCredentialIfAbsentResult, type AuthCredentialStore, type OAuthCredential, type StoredAuthCredential } from "../auth-storage";
 import type { Provider } from "../types";
 import type { UsageReport } from "../usage";
 import type { OAuthCredentials } from "../utils/oauth/types";
@@ -44,6 +44,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     }): Promise<void>;
     replaceAuthCredentialsForProvider(_provider: string, _credentials: AuthCredential[]): StoredAuthCredential[];
     upsertAuthCredentialForProvider(_provider: string, _credential: AuthCredential): StoredAuthCredential[];
+    upsertAuthCredentialForProviderIfAbsent(_provider: string, _credential: AuthCredential): AuthCredentialIfAbsentResult;
     deleteAuthCredentialsForProvider(_provider: string, _disabledCause: string): void;
     /**
      * Upsert a single credential through the broker. The broker server is the
@@ -53,6 +54,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      * any concurrent peer (refresh, generation bump) stays in sync.
      */
     upsertAuthCredentialRemote(provider: string, credential: AuthCredential): Promise<StoredAuthCredential[]>;
+    upsertAuthCredentialRemoteIfAbsent(provider: string, credential: AuthCredential): Promise<AuthCredentialIfAbsentResult>;
     /**
      * Replace-all semantics: disable every active credential for the provider,
      * then upload each of the new credentials. Used by API-key login so a new

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

@@ -5,7 +5,7 @@
  * clients use `access` tokens directly and call back to the broker when a
  * credential expires or a 401 surfaces on a supposedly-fresh credential.
  */
-import type { AuthCredential, AuthCredentialSnapshot, AuthCredentialSnapshotEntry } from "../auth-storage";
+import type { AuthCredential, AuthCredentialIfAbsentReason, AuthCredentialSnapshot, AuthCredentialSnapshotEntry } from "../auth-storage";
 import type { UsageReport } from "../usage";
 /** GET /v1/healthz response body. */
 export interface HealthzResponse {
@@ -56,6 +56,11 @@ export interface CredentialUploadRequest {
 export interface CredentialUploadResponse {
     entries: AuthCredentialSnapshotEntry[];
 }
+export interface CredentialIfAbsentUploadResponse {
+    inserted: boolean;
+    reason: AuthCredentialIfAbsentReason;
+    entries: AuthCredentialSnapshotEntry[];
+}
 /**
  * SSE event kinds emitted on `GET /v1/snapshot/stream`. The same value is set
  * as the SSE `event:` name (load-bearing for clients) **and** embedded as a

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -410,3 +410,33 @@ export declare const credentialUploadResponseSchema: z.ZodObject<{
         identityKey: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+export declare const credentialIfAbsentUploadResponseSchema: z.ZodObject<{
+    inserted: z.ZodBoolean;
+    reason: z.ZodEnum<{
+        inserted: "inserted";
+        "skipped-existing": "skipped-existing";
+        "skipped-existing-config": "skipped-existing-config";
+        "skipped-existing-env": "skipped-existing-env";
+        "skipped-existing-fallback": "skipped-existing-fallback";
+        "skipped-existing-runtime": "skipped-existing-runtime";
+        "skipped-invalid": "skipped-invalid";
+    }>;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            access: z.ZodString;
+            expires: z.ZodNumber;
+            enterpriseUrl: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            accountId: z.ZodOptional<z.ZodString>;
+            refresh: z.ZodLiteral<"__remote__">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"api_key">;
+            key: z.ZodString;
+        }, z.core.$strict>], "type">;
+        identityKey: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;

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

@@ -102,6 +102,19 @@ export interface AuthCredentialSnapshotEntry {
     credential: SnapshotCredential;
     identityKey: string | null;
 }
+export type AuthCredentialIfAbsentReason = "inserted" | "skipped-existing" | "skipped-existing-runtime" | "skipped-existing-config" | "skipped-existing-env" | "skipped-existing-fallback" | "skipped-invalid";
+export interface AuthCredentialIfAbsentResult {
+    inserted: boolean;
+    reason: AuthCredentialIfAbsentReason;
+    provider: string;
+    entries: StoredAuthCredential[];
+}
+export interface AuthCredentialIfAbsentSnapshotResult {
+    inserted: boolean;
+    reason: AuthCredentialIfAbsentReason;
+    provider: string;
+    entries: AuthCredentialSnapshotEntry[];
+}
 /**
  * Wire-shaped snapshot exported by {@link AuthStorage.exportSnapshot} and
  * served by the auth-broker server on `GET /v1/snapshot`.
@@ -128,6 +141,7 @@ export interface AuthCredentialStore {
     tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string): boolean;
     replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
     upsertAuthCredentialForProvider(provider: string, credential: AuthCredential): StoredAuthCredential[];
+    upsertAuthCredentialForProviderIfAbsent(provider: string, credential: AuthCredential): AuthCredentialIfAbsentResult;
     deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
     getCache(key: string, options?: {
         includeExpired?: boolean;
@@ -201,6 +215,7 @@ export interface AuthCredentialStore {
      * post-write read path is consistent.
      */
     upsertAuthCredentialRemote?(provider: string, credential: AuthCredential): Promise<StoredAuthCredential[]>;
+    upsertAuthCredentialRemoteIfAbsent?(provider: string, credential: AuthCredential): Promise<AuthCredentialIfAbsentResult>;
     /**
      * Optional async write hook for replace-all semantics (e.g. API-key login
      * overwriting any previous keys for the same provider). When present,
@@ -417,6 +432,7 @@ export declare class AuthStorage {
      * Set credential for a provider.
      */
     set(provider: string, credential: AuthCredentialEntry): Promise<void>;
+    importCredentialIfAbsent(provider: string, credential: AuthCredential): Promise<AuthCredentialIfAbsentSnapshotResult>;
     /**
      * Remove credential for a provider.
      */
@@ -615,6 +631,7 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     listAuthCredentials(provider?: string): StoredAuthCredential[];
     replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
     upsertAuthCredentialForProvider(provider: string, credential: AuthCredential): StoredAuthCredential[];
+    upsertAuthCredentialForProviderIfAbsent(provider: string, credential: AuthCredential): AuthCredentialIfAbsentResult;
     updateAuthCredential(id: number, credential: AuthCredential): void;
     deleteAuthCredential(id: number, disabledCause: string): void;
     /**

package/dist/types/provider-models/special.d.ts

@@ -14,3 +14,6 @@ export declare function cursorModelManagerOptions(config?: CursorModelManagerCon
 export interface ZaiModelManagerConfig {
 }
 export declare function zaiModelManagerOptions(_config?: ZaiModelManagerConfig): ModelManagerOptions<"anthropic-messages">;
+export interface GlmZcodeModelManagerConfig {
+}
+export declare function glmZcodeModelManagerOptions(_config?: GlmZcodeModelManagerConfig): ModelManagerOptions<"anthropic-messages">;

package/dist/types/providers/anthropic.d.ts

@@ -9,9 +9,24 @@ export type AnthropicHeaderOptions = {
     stream?: boolean;
     modelHeaders?: Record<string, string>;
     isCloudflareAiGateway?: boolean;
+    /**
+     * Attach ZCode client "source" headers (User-Agent: ZCode/<ver>, X-Title,
+     * X-ZCode-Agent: glm, X-Platform, etc.) so api.z.ai recognizes the caller as
+     * the ZCode client, exactly like ZCode's `buildZCodeSourceHeaders` does for
+     * GLM providers. glm-zcode only.
+     */
+    zcodeSourceHeaders?: boolean;
 };
 export declare function normalizeAnthropicBaseUrl(baseUrl?: string): string | undefined;
 export declare function buildBetaHeader(baseBetas: string[], extraBetas: string[]): string;
+/**
+ * Replicates ZCode's `buildZCodeSourceHeaders()` + GLM `X-ZCode-Agent` tag
+ * (host bundle `Bl` / `buildConnectivitySourceHeaders` for GLM providers), so
+ * api.z.ai sees skc's glm-zcode requests as the ZCode client. Dynamic values
+ * (platform/arch, locale, timezone, OS version) are resolved at runtime exactly
+ * as ZCode does; printable-ASCII-only and conditionally omitted when empty.
+ */
+export declare function buildZCodeSourceHeaders(): Record<string, string>;
 export declare function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<string, string>;
 type AnthropicCacheControl = {
     type: "ephemeral";

package/dist/types/types.d.ts

@@ -48,7 +48,7 @@ export interface ThinkingConfig {
     /** Provider-specific transport used to encode the selected effort. */
     mode: ThinkingControlMode;
 }
-export type KnownProvider = "alibaba-coding-plan" | "amazon-bedrock" | "azure-openai" | "anthropic" | "google" | "google-gemini-cli" | "google-antigravity" | "google-vertex" | "openai" | "openai-codex" | "kimi-code" | "minimax-code" | "minimax-code-cn" | "github-copilot" | "fireworks" | "firepass" | "gitlab-duo" | "cursor" | "deepseek" | "xai" | "groq" | "cerebras" | "openrouter" | "kilo" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "opencode-go" | "opencode-zen" | "synthetic" | "cloudflare-ai-gateway" | "huggingface" | "litellm" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "qianfan" | "qwen-portal" | "together" | "venice" | "vllm" | "xiaomi" | "xiaomi-token-plan-sgp" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-cn" | "zenmux" | "lm-studio";
+export type KnownProvider = "alibaba-coding-plan" | "amazon-bedrock" | "azure-openai" | "anthropic" | "google" | "google-gemini-cli" | "google-antigravity" | "google-vertex" | "openai" | "openai-codex" | "kimi-code" | "minimax-code" | "minimax-code-cn" | "github-copilot" | "fireworks" | "firepass" | "gitlab-duo" | "cursor" | "deepseek" | "xai" | "groq" | "cerebras" | "openrouter" | "kilo" | "vercel-ai-gateway" | "zai" | "glm-zcode" | "mistral" | "minimax" | "opencode-go" | "opencode-zen" | "synthetic" | "cloudflare-ai-gateway" | "huggingface" | "litellm" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "qianfan" | "qwen-portal" | "together" | "venice" | "vllm" | "xiaomi" | "xiaomi-token-plan-sgp" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-cn" | "zenmux" | "lm-studio";
 export type Provider = KnownProvider | string;
 import type { Effort } from "./model-thinking";
 /** Token budgets for each thinking level (token-based providers only) */

package/dist/types/utils/oauth/glm-zcode.d.ts

@@ -0,0 +1,71 @@
+/**
+ * GLM ZCode OAuth flow (UNOFFICIAL, opt-in).
+ *
+ * Replicates how the ZCode desktop app turns a Z.AI login into usable GLM model
+ * access. This is NOT an official Z.AI OAuth client: it reuses ZCode's authorize
+ * page, broker, and a custom-protocol redirect. It may break at any time and may
+ * violate ZCode/Z.AI Terms of Service. Endpoints/client id are overridable via
+ * `ZCODE_OAUTH_*` environment variables.
+ *
+ * Verified end-to-end against the ZCode host bundle (`resolveZaiApiKey` /
+ * `resolveBizApiKey`) and live traffic:
+ *   1. Authorize: GET {authorize}?redirect_uri=zcode://oauth/callback&response_type=code&client_id=...&state=...
+ *      (custom-protocol redirect → a CLI cannot catch it, so the user pastes the code/redirect URL)
+ *   2. Broker:    POST {broker} { provider:"zai", code, redirect_uri, state }
+ *                  → { data: { token: <ZCode JWT>, zai: { access_token: <upstream Z.AI token> } } }
+ *   3. Business:  POST {z/login} { token: <upstream Z.AI token> } → { data: { access_token: <business token> } }
+ *   4. Provision: with the business token, GET getCustomerInfo → default org/project,
+ *      GET/POST .../api_keys (find/create a key named "zcode-api-key"),
+ *      GET .../api_keys/copy/{id} → secretKey ⇒ a real Z.AI API key "{id}.{secret}".
+ *
+ * Credential mapping:
+ *   - `access`  = the provisioned **Z.AI API key** ("{id}.{secret}"). Model requests go to
+ *                 `https://api.z.ai/api/anthropic/v1/messages` with `Authorization: Bearer <key>`
+ *                 (exactly like a dashboard key) — NO zcode.z.ai gateway, NO captcha.
+ *   - `refresh` = the upstream Z.AI OAuth access token (used to re-provision the key).
+ * The API key is long-lived, so `expires` is set far in the future.
+ *
+ * This provider must NEVER force `isOAuth=true`: the key is a plain Z.AI API key, and
+ * api.z.ai is not api.anthropic.com, so the Anthropic path already emits a plain bearer.
+ */
+import { OAuthCallbackFlow } from "./callback-server";
+import type { OAuthController, OAuthCredentials } from "./types";
+export declare const GLM_ZCODE_REFRESH_SKEW_MS: number;
+/** Default endpoints / client id. Override via the matching `ZCODE_OAUTH_*` env vars. */
+export declare const GLM_ZCODE_OAUTH_AUTHORIZE_URL = "https://chat.z.ai/api/oauth/authorize";
+export declare const GLM_ZCODE_OAUTH_CLIENT_ID = "client_P8X5CMWmlaRO9gyO-KSqtg";
+export declare const GLM_ZCODE_OAUTH_REDIRECT_URI = "zcode://oauth/callback";
+export declare const GLM_ZCODE_OAUTH_BROKER_TOKEN_URL = "https://zcode.z.ai/api/v1/oauth/token";
+export declare const GLM_ZCODE_ZAI_LOGIN_URL = "https://api.z.ai/api/auth/z/login";
+export declare const GLM_ZCODE_USERINFO_URL = "https://chat.z.ai/api/oauth/userinfo";
+/** Z.AI business API base (customer/org/project/api-key management). */
+export declare const GLM_ZCODE_ZAI_API_BASE = "https://api.z.ai";
+/** Model API base — the provisioned key is used here, exactly like a dashboard key. */
+export declare const GLM_ZCODE_ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic";
+type FetchImpl = typeof globalThis.fetch;
+/** Configured whenever a client id is available; the real ZCode client id ships as default. */
+export declare function isGlmZcodeOAuthConfigured(): boolean;
+export interface GlmZcodeOAuthFlowOptions {
+    fetch?: FetchImpl;
+}
+export declare class GlmZcodeOAuthFlow extends OAuthCallbackFlow {
+    #private;
+    constructor(ctrl: OAuthController, options?: GlmZcodeOAuthFlowOptions);
+    generateAuthUrl(state: string, redirectUri: string): Promise<{
+        url: string;
+        instructions?: string;
+    }>;
+    exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials>;
+}
+export declare function loginGlmZcode(ctrl: OAuthController, options?: GlmZcodeOAuthFlowOptions): Promise<OAuthCredentials>;
+export interface GlmZcodeRefreshOptions {
+    signal?: AbortSignal;
+    fetch?: FetchImpl;
+}
+/**
+ * Re-provision the Z.AI API key from the stored upstream token. The key itself is
+ * long-lived, so this is rarely needed; if the upstream token has expired it fails
+ * loudly and the user must re-login.
+ */
+export declare function refreshGlmZcodeToken(credentials: OAuthCredentials, options?: AbortSignal | GlmZcodeRefreshOptions): Promise<OAuthCredentials>;
+export {};

package/dist/types/utils/oauth/types.d.ts

@@ -7,7 +7,7 @@ export type OAuthCredentials = {
     email?: string;
     accountId?: string;
 };
-export type OAuthProvider = "alibaba-coding-plan" | "anthropic" | "cerebras" | "cloudflare-ai-gateway" | "cursor" | "deepseek" | "fireworks" | "firepass" | "github-copilot" | "google-gemini-cli" | "google-antigravity" | "gitlab-duo" | "huggingface" | "kimi-code" | "kilo" | "kagi" | "litellm" | "lm-studio" | "minimax-code" | "minimax-code-cn" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "openai-codex" | "openai-codex-device" | "opencode-go" | "opencode-zen" | "parallel" | "perplexity" | "qianfan" | "qwen-portal" | "synthetic" | "tavily" | "together" | "venice" | "vercel-ai-gateway" | "vllm" | "xai" | "xiaomi" | "xiaomi-token-plan-sgp" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-cn" | "zenmux" | "zai";
+export type OAuthProvider = "alibaba-coding-plan" | "anthropic" | "cerebras" | "cloudflare-ai-gateway" | "cursor" | "deepseek" | "fireworks" | "firepass" | "github-copilot" | "google-gemini-cli" | "google-antigravity" | "gitlab-duo" | "huggingface" | "kimi-code" | "kilo" | "kagi" | "litellm" | "lm-studio" | "minimax-code" | "minimax-code-cn" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "openai-codex" | "openai-codex-device" | "opencode-go" | "opencode-zen" | "parallel" | "perplexity" | "qianfan" | "qwen-portal" | "synthetic" | "tavily" | "together" | "venice" | "vercel-ai-gateway" | "vllm" | "xai" | "glm-zcode" | "xiaomi" | "xiaomi-token-plan-sgp" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-cn" | "zenmux" | "zai";
 export type OAuthProviderId = OAuthProvider | (string & {});
 export type OAuthPrompt = {
     message: string;

package/package.json

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

package/src/auth-broker/client.ts

@@ -11,6 +11,7 @@ import type { AuthCredential } from "../auth-storage";
 import type {
 	CredentialDisableRequest,
 	CredentialDisableResponse,
+	CredentialIfAbsentUploadResponse,
 	CredentialRefreshResponse,
 	CredentialUploadRequest,
 	CredentialUploadResponse,
@@ -21,6 +22,7 @@ import type {
 } from "./types";
 import {
 	credentialDisableResponseSchema,
+	credentialIfAbsentUploadResponseSchema,
 	credentialRefreshResponseSchema,
 	credentialUploadResponseSchema,
 	healthzResponseSchema,
@@ -262,6 +264,19 @@ export class AuthBrokerClient {
 		}) as Promise<CredentialUploadResponse>;
 	}
 
+	async uploadCredentialIfAbsent(
+		provider: string,
+		credential: AuthCredential,
+		signal?: AbortSignal,
+	): Promise<CredentialIfAbsentUploadResponse> {
+		const body: CredentialUploadRequest = { provider, credential };
+		return this.#request("POST", "/v1/credential/if-absent", {
+			body,
+			schema: credentialIfAbsentUploadResponseSchema,
+			signal,
+		}) as Promise<CredentialIfAbsentUploadResponse>;
+	}
+
 	async #request<TSchema extends ZodType>(
 		method: "GET" | "POST",
 		path: string,

package/src/auth-broker/remote-store.ts

@@ -11,6 +11,7 @@ import { scheduler } from "node:timers/promises";
 import { logger } from "@sayknow-cli/utils";
 import {
 	type AuthCredential,
+	type AuthCredentialIfAbsentResult,
 	type AuthCredentialSnapshotEntry,
 	type AuthCredentialStore,
 	type OAuthCredential,
@@ -308,6 +309,15 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		);
 	}
 
+	upsertAuthCredentialForProviderIfAbsent(
+		_provider: string,
+		_credential: AuthCredential,
+	): AuthCredentialIfAbsentResult {
+		throw new Error(
+			"RemoteAuthCredentialStore is read-only on the client. Use `skc auth-broker login <provider>` to mutate credentials.",
+		);
+	}
+
 	deleteAuthCredentialsForProvider(_provider: string, _disabledCause: string): void {
 		throw new Error(
 			"RemoteAuthCredentialStore is read-only on the client. Use `skc auth-broker logout <provider>` to mutate credentials.",
@@ -328,6 +338,16 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		return this.listAuthCredentials(provider);
 	}
 
+	async upsertAuthCredentialRemoteIfAbsent(
+		provider: string,
+		credential: AuthCredential,
+	): Promise<AuthCredentialIfAbsentResult> {
+		const { inserted, reason, entries } = await this.#client.uploadCredentialIfAbsent(provider, credential);
+		this.#applyProviderEntries(provider, entries);
+		this.#maybeRefreshSnapshot("upload-if-absent");
+		return { inserted, reason, provider, entries: this.listAuthCredentials(provider) };
+	}
+
 	/**
 	 * Replace-all semantics: disable every active credential for the provider,
 	 * then upload each of the new credentials. Used by API-key login so a new

package/src/auth-broker/server.ts

@@ -15,6 +15,7 @@ import { parseBind } from "../utils/parse-bind";
 import { AuthBrokerRefresher, type AuthBrokerRefresherSchedule } from "./refresher";
 import type {
 	CredentialDisableResponse,
+	CredentialIfAbsentUploadResponse,
 	CredentialRefreshResponse,
 	CredentialUploadResponse,
 	HealthzResponse,
@@ -592,6 +593,32 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 					const response: CredentialDisableResponse = { ok: true };
 					return json(200, response);
 				}
+				if (req.method === "POST" && pathname === "/v1/credential/if-absent") {
+					const parsed = await parseBody(req, credentialUploadRequestSchema);
+					if (!parsed.ok) return parsed.response;
+					const { provider, credential } = parsed.data;
+					try {
+						const result = await opts.storage.importCredentialIfAbsent(provider, credential);
+						logger.info("auth-broker credential import-if-absent", {
+							provider,
+							type: credential.type,
+							inserted: result.inserted,
+							reason: result.reason,
+							providerTotal: result.entries.length,
+							peer,
+						});
+						const response: CredentialIfAbsentUploadResponse = {
+							inserted: result.inserted,
+							reason: result.reason,
+							entries: result.entries,
+						};
+						return json(200, response);
+					} catch (error) {
+						const message = error instanceof Error ? error.message : String(error);
+						logger.warn("auth-broker upload-if-absent failed", { provider, type: credential.type, peer });
+						return json(500, { error: message });
+					}
+				}
 				if (req.method === "POST" && pathname === "/v1/credential") {
 					const parsed = await parseBody(req, credentialUploadRequestSchema);
 					if (!parsed.ok) return parsed.response;

package/src/auth-broker/types.ts

@@ -6,7 +6,12 @@
  * credential expires or a 401 surfaces on a supposedly-fresh credential.
  */
 
-import type { AuthCredential, AuthCredentialSnapshot, AuthCredentialSnapshotEntry } from "../auth-storage";
+import type {
+	AuthCredential,
+	AuthCredentialIfAbsentReason,
+	AuthCredentialSnapshot,
+	AuthCredentialSnapshotEntry,
+} from "../auth-storage";
 import type { UsageReport } from "../usage";
 
 /** GET /v1/healthz response body. */
@@ -68,6 +73,12 @@ export interface CredentialUploadResponse {
 	entries: AuthCredentialSnapshotEntry[];
 }
 
+export interface CredentialIfAbsentUploadResponse {
+	inserted: boolean;
+	reason: AuthCredentialIfAbsentReason;
+	entries: AuthCredentialSnapshotEntry[];
+}
+
 /**
  * SSE event kinds emitted on `GET /v1/snapshot/stream`. The same value is set
  * as the SSE `event:` name (load-bearing for clients) **and** embedded as a

package/src/auth-broker/wire-schemas.ts

@@ -185,6 +185,15 @@ export const credentialDisableResponseSchema = z
 	.strict();
 
 // ─── Upload ────────────────────────────────────────────────────────────────
+const credentialIfAbsentReasonSchema = z.enum([
+	"inserted",
+	"skipped-existing",
+	"skipped-existing-runtime",
+	"skipped-existing-config",
+	"skipped-existing-env",
+	"skipped-existing-fallback",
+	"skipped-invalid",
+]);
 
 export const credentialUploadRequestSchema = z
 	.object({
@@ -198,3 +207,11 @@ export const credentialUploadResponseSchema = z
 		entries: z.array(credentialSnapshotEntrySchema),
 	})
 	.strict();
+
+export const credentialIfAbsentUploadResponseSchema = z
+	.object({
+		inserted: z.boolean(),
+		reason: credentialIfAbsentReasonSchema,
+		entries: z.array(credentialSnapshotEntrySchema),
+	})
+	.strict();