@byok-sdk/keys 0.3.9 → 0.4.0

package/dist/bin/pi-provider-launcher.js

@@ -4,6 +4,7 @@ import { promises, mkdirSync, existsSync, chmodSync } from 'fs';
 import os from 'os';
 import path2, { dirname } from 'path';
 import { z } from 'zod';
+import { createHash } from 'crypto';
 import { createRequire } from 'module';
 
 // src/errors.ts
@@ -71,16 +72,291 @@ function assertSecretNamespace(value) {
   return normalized;
 }
 
+// src/provider-catalog.ts
+function openAiCompatible(display_name, base_url, api_key_env) {
+  return {
+    display_name,
+    base_url,
+    adapter: "openai_compatible",
+    auth_mode: "bearer",
+    api_key_env
+  };
+}
+function anthropicMessages(display_name, base_url, api_key_env) {
+  return {
+    display_name,
+    base_url,
+    adapter: "anthropic",
+    auth_mode: "x_api_key",
+    api_key_env
+  };
+}
+var MODEL_PROVIDER_VENDORS = {
+  "ant-ling": openAiCompatible("Ant Ling", "https://api.ant-ling.com/v1", "ANT_LING_API_KEY"),
+  baseten: openAiCompatible("Baseten", "https://inference.baseten.co/v1", "BASETEN_API_KEY"),
+  cerebras: openAiCompatible("Cerebras", "https://api.cerebras.ai/v1", "CEREBRAS_API_KEY"),
+  deepseek: openAiCompatible("DeepSeek", "https://api.deepseek.com", "DEEPSEEK_API_KEY"),
+  groq: openAiCompatible("Groq", "https://api.groq.com/openai/v1", "GROQ_API_KEY"),
+  huggingface: openAiCompatible("Hugging Face", "https://router.huggingface.co/v1", "HF_TOKEN"),
+  moonshotai: openAiCompatible("Moonshot AI", "https://api.moonshot.ai/v1", "MOONSHOT_API_KEY"),
+  "moonshotai-cn": openAiCompatible("Moonshot AI CN", "https://api.moonshot.cn/v1", "MOONSHOT_API_KEY"),
+  nvidia: openAiCompatible("NVIDIA", "https://integrate.api.nvidia.com/v1", "NVIDIA_API_KEY"),
+  openai: openAiCompatible("OpenAI", "https://api.openai.com/v1", "OPENAI_API_KEY"),
+  openrouter: openAiCompatible("OpenRouter", "https://openrouter.ai/api/v1", "OPENROUTER_API_KEY"),
+  "qwen-token-plan": openAiCompatible(
+    "Qwen Token Plan",
+    "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
+    "QWEN_TOKEN_PLAN_API_KEY"
+  ),
+  "qwen-token-plan-cn": openAiCompatible(
+    "Qwen Token Plan CN",
+    "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
+    "QWEN_TOKEN_PLAN_CN_API_KEY"
+  ),
+  together: openAiCompatible("Together", "https://api.together.ai/v1", "TOGETHER_API_KEY"),
+  xai: openAiCompatible("xAI", "https://api.x.ai/v1", "XAI_API_KEY"),
+  xiaomi: openAiCompatible("Xiaomi", "https://api.xiaomimimo.com/v1", "XIAOMI_API_KEY"),
+  "xiaomi-token-plan-ams": openAiCompatible(
+    "Xiaomi Token Plan AMS",
+    "https://token-plan-ams.xiaomimimo.com/v1",
+    "XIAOMI_TOKEN_PLAN_AMS_API_KEY"
+  ),
+  "xiaomi-token-plan-cn": openAiCompatible(
+    "Xiaomi Token Plan CN",
+    "https://token-plan-cn.xiaomimimo.com/v1",
+    "XIAOMI_TOKEN_PLAN_CN_API_KEY"
+  ),
+  "xiaomi-token-plan-sgp": openAiCompatible(
+    "Xiaomi Token Plan SGP",
+    "https://token-plan-sgp.xiaomimimo.com/v1",
+    "XIAOMI_TOKEN_PLAN_SGP_API_KEY"
+  ),
+  zai: openAiCompatible("Z.AI", "https://api.z.ai/api/coding/paas/v4", "ZAI_API_KEY"),
+  "zai-coding-cn": openAiCompatible(
+    "Z.AI Coding CN",
+    "https://open.bigmodel.cn/api/coding/paas/v4",
+    "ZAI_CODING_CN_API_KEY"
+  ),
+  anthropic: anthropicMessages("Anthropic", "https://api.anthropic.com/v1", "ANTHROPIC_API_KEY"),
+  fireworks: anthropicMessages("Fireworks", "https://api.fireworks.ai/inference/v1", "FIREWORKS_API_KEY"),
+  "kimi-coding": anthropicMessages("Kimi For Coding", "https://api.kimi.com/coding/v1", "KIMI_API_KEY"),
+  minimax: anthropicMessages("MiniMax", "https://api.minimax.io/anthropic/v1", "MINIMAX_API_KEY"),
+  "minimax-cn": anthropicMessages("MiniMax CN", "https://api.minimaxi.com/anthropic/v1", "MINIMAX_CN_API_KEY"),
+  "vercel-ai-gateway": anthropicMessages(
+    "Vercel AI Gateway",
+    "https://ai-gateway.vercel.sh/v1",
+    "AI_GATEWAY_API_KEY"
+  )
+};
+var MODEL_PROVIDER_VENDOR_IDS = Object.keys(
+  MODEL_PROVIDER_VENDORS
+);
+function modelProviderVendor(kind) {
+  return Object.hasOwn(MODEL_PROVIDER_VENDORS, kind) ? MODEL_PROVIDER_VENDORS[kind] : void 0;
+}
+
+// src/url.ts
+function normalizeProviderUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ByokKeysError(
+      "PROVIDER_URL_INVALID",
+      "Provider base URL must be absolute"
+    );
+  }
+  if (url.username || url.password || url.hash || url.search || url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) {
+    throw new ByokKeysError(
+      "PROVIDER_URL_INVALID",
+      "Provider URL requires HTTPS; HTTP is allowed only for localhost"
+    );
+  }
+  if (isPrivateNetworkLiteral(url.hostname) && !isLoopbackHost(url.hostname)) {
+    throw new ByokKeysError(
+      "PROVIDER_URL_INVALID",
+      "Private-network provider IPs are not allowed"
+    );
+  }
+  return url.toString().replace(/\/$/u, "");
+}
+function isLoopbackHost(hostname) {
+  const value = hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+  return value === "localhost" || value === "127.0.0.1" || value === "::1";
+}
+function isPrivateNetworkLiteral(hostname) {
+  const value = hostname.toLowerCase().replace(/^\[|\]$/gu, "");
+  if (value.includes(":")) return true;
+  const parts = value.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return false;
+  }
+  return parts[0] === 10 || parts[0] === 127 || parts[0] === 169 && parts[1] === 254 || parts[0] === 172 && (parts[1] ?? 0) >= 16 && (parts[1] ?? 0) <= 31 || parts[0] === 192 && parts[1] === 168;
+}
+
+// src/provider-profile.ts
+var PROVIDER_PROFILE_REF_PATTERN = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/u;
+var ProviderProfileRefSchema = z.string().min(1).max(64).regex(
+  PROVIDER_PROFILE_REF_PATTERN,
+  "provider profile refs must be lowercase portable identifiers"
+);
+var MODEL_PROVIDER_KINDS = [
+  ...MODEL_PROVIDER_VENDOR_IDS,
+  "custom"
+];
+var PROVIDER_MODEL_CAPABILITIES = ["image-input"];
+var ProviderModelCapabilitySchema = z.enum(PROVIDER_MODEL_CAPABILITIES);
+var PROVIDER_AUTH_MODES = ["bearer", "x_api_key", "none"];
+var MODEL_PROVIDER_ADAPTERS = ["openai_compatible", "anthropic"];
+function boundedString(field, maximumLength) {
+  return z.string().superRefine((value, ctx) => {
+    if (value.trim().length === 0 || value.length > maximumLength || /[\u0000\r\n]/u.test(value)) {
+      ctx.addIssue({
+        code: "custom",
+        message: `Provider ${field} is invalid`
+      });
+    }
+  }).transform((value) => value.trim());
+}
+function isoTimestamp(field) {
+  return boundedString(field, 64).superRefine((value, ctx) => {
+    if (!Number.isFinite(Date.parse(value))) {
+      ctx.addIssue({
+        code: "custom",
+        message: `Provider ${field} must be an ISO timestamp`
+      });
+    }
+  });
+}
+var providerBaseUrl = z.string().superRefine((value, ctx) => {
+  try {
+    normalizeProviderUrl(value);
+  } catch (error) {
+    ctx.addIssue({
+      code: "custom",
+      message: error instanceof Error ? error.message : "Provider base URL is invalid",
+      params: {
+        byokCode: error instanceof ByokKeysError ? error.code : "PROVIDER_URL_INVALID"
+      }
+    });
+  }
+}).transform((value) => normalizeProviderUrl(value));
+var ModelProviderProfileSchema = z.object({
+  adapter: z.enum(MODEL_PROVIDER_ADAPTERS),
+  auth_mode: z.enum(PROVIDER_AUTH_MODES),
+  base_url: providerBaseUrl,
+  capabilities: z.array(ProviderModelCapabilitySchema).max(8),
+  created_at: isoTimestamp("created_at"),
+  display_name: boundedString("display_name", 100),
+  enabled: z.boolean(),
+  kind: z.literal("model"),
+  model: boundedString("model", 160),
+  profile_ref: ProviderProfileRefSchema,
+  provider_kind: z.enum(MODEL_PROVIDER_KINDS),
+  updated_at: isoTimestamp("updated_at")
+}).superRefine((profile, ctx) => {
+  if (new Set(profile.capabilities).size !== profile.capabilities.length) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Provider capabilities cannot repeat",
+      path: ["capabilities"]
+    });
+  }
+  if (profile.adapter === "anthropic" && profile.auth_mode !== "x_api_key") {
+    ctx.addIssue({
+      code: "custom",
+      message: "Anthropic requires x_api_key authentication",
+      path: ["auth_mode"]
+    });
+  }
+  if (profile.adapter === "openai_compatible" && profile.auth_mode === "x_api_key") {
+    ctx.addIssue({
+      code: "custom",
+      message: "OpenAI-compatible providers support bearer or no authentication",
+      path: ["auth_mode"]
+    });
+  }
+  const vendor = modelProviderVendor(profile.provider_kind);
+  if (vendor !== void 0 && vendor.adapter !== profile.adapter) {
+    ctx.addIssue({
+      code: "custom",
+      message: `Provider kind ${profile.provider_kind} speaks the ${vendor.adapter} adapter`,
+      path: ["adapter"]
+    });
+  }
+  if (Date.parse(profile.updated_at) < Date.parse(profile.created_at)) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Provider updated_at cannot precede created_at",
+      path: ["updated_at"]
+    });
+  }
+});
+function exactProviderProfileBinding(profileInput, requiredCapabilities = profileInput.capabilities) {
+  const profile = parseModelProviderProfile(profileInput);
+  const revision = Date.parse(profile.updated_at);
+  if (!Number.isSafeInteger(revision) || revision < 0) {
+    throw new ByokKeysError(
+      "PROVIDER_PROFILE_INVALID",
+      "Provider updated_at cannot be represented as a canonical revision"
+    );
+  }
+  const normalizedCapabilities = [...profile.capabilities].sort();
+  const canonical = JSON.stringify({
+    adapter: profile.adapter,
+    auth_mode: profile.auth_mode,
+    base_url: profile.base_url,
+    capabilities: normalizedCapabilities,
+    kind: profile.kind,
+    model: profile.model,
+    profile_ref: profile.profile_ref,
+    provider_kind: profile.provider_kind
+  });
+  return {
+    profileRef: profile.profile_ref,
+    profileRevision: String(revision),
+    profileHash: `sha256:${createHash("sha256").update(canonical).digest("hex")}`,
+    modelId: profile.model,
+    requiredCapabilities: [...requiredCapabilities]
+  };
+}
+function assertExactProviderProfileBinding(profile, expected) {
+  if (new Set(expected.requiredCapabilities).size !== expected.requiredCapabilities.length) {
+    throw new Error("provider profile required capabilities must be unique");
+  }
+  const actual = exactProviderProfileBinding(profile, expected.requiredCapabilities);
+  if (actual.profileRef !== expected.profileRef) throw new Error("provider profile ref mismatch");
+  if (actual.profileRevision !== expected.profileRevision) throw new Error("provider profile revision mismatch");
+  if (actual.profileHash !== expected.profileHash) throw new Error("provider profile hash mismatch");
+  if (actual.modelId !== expected.modelId) throw new Error("provider profile model mismatch");
+  const supported = new Set(profile.capabilities);
+  const unsupported = expected.requiredCapabilities.find((capability) => !supported.has(capability));
+  if (unsupported !== void 0) throw new Error(`provider profile does not support required capability ${unsupported}`);
+}
+function parseModelProviderProfile(value) {
+  const result = ModelProviderProfileSchema.safeParse(value);
+  if (result.success) return result.data;
+  const issue = result.error.issues[0];
+  const params = issue?.params;
+  throw new ByokKeysError(
+    params?.byokCode ?? "PROVIDER_PROFILE_INVALID",
+    issue?.message ?? "Provider profile is invalid",
+    { cause: result.error }
+  );
+}
+
 // src/secret-store.ts
 var DEFAULT_SECRET_SERVICE_PREFIX = "com.byok.keys";
-var MODEL_PROVIDER_SECRET_NAMES = {
-  anthropic: "model-anthropic-api-key",
-  custom: "model-custom-api-key",
-  deepseek: "model-deepseek-api-key",
-  openai: "model-openai-api-key"
-};
-function modelProviderSecretName(providerId) {
-  return MODEL_PROVIDER_SECRET_NAMES[providerId];
+function modelProviderSecretName(profileRef) {
+  const parsed = ProviderProfileRefSchema.safeParse(profileRef);
+  if (!parsed.success) {
+    throw new ByokKeysError(
+      "PROVIDER_PROFILE_INVALID",
+      "Provider profile ref must be a lowercase portable identifier",
+      { cause: parsed.error }
+    );
+  }
+  return assertSecretName(`model-${parsed.data}-api-key`);
 }
 function decodeStrictBase64Utf8(encoded) {
   if (encoded.length % 4 !== 0) return void 0;
@@ -266,11 +542,11 @@ function assertKeychainPath(keychainPath) {
 
 // src/pi-provider-projection.ts
 var PI_PROJECTED_KEY_ENV = "PI_PROVIDER_API_KEY";
-function piProjectionProviderId(profileProviderId) {
-  return `byok-sdk-${profileProviderId}`;
+function piProjectionProviderId(profileRef) {
+  return `byok-sdk-${profileRef}`;
 }
 function buildPiProviderProjection(profile) {
-  const projectedProviderId = piProjectionProviderId(profile.provider_id);
+  const projectedProviderId = piProjectionProviderId(profile.profile_ref);
   return {
     providers: {
       [projectedProviderId]: {
@@ -281,7 +557,11 @@ function buildPiProviderProjection(profile) {
         models: [
           {
             id: profile.model,
-            name: profile.display_name
+            name: profile.display_name,
+            input: [
+              "text",
+              ...profile.capabilities.includes("image-input") ? ["image"] : []
+            ]
           }
         ]
       }
@@ -314,139 +594,12 @@ function buildPiProviderArgs(profile, delegatedArgs) {
   return [
     ...delegatedArgs,
     "--provider",
-    piProjectionProviderId(profile.provider_id),
+    piProjectionProviderId(profile.profile_ref),
     "--model",
     profile.model
   ];
 }
 
-// src/url.ts
-function normalizeProviderUrl(value) {
-  let url;
-  try {
-    url = new URL(value);
-  } catch {
-    throw new ByokKeysError(
-      "PROVIDER_URL_INVALID",
-      "Provider base URL must be absolute"
-    );
-  }
-  if (url.username || url.password || url.hash || url.search || url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) {
-    throw new ByokKeysError(
-      "PROVIDER_URL_INVALID",
-      "Provider URL requires HTTPS; HTTP is allowed only for localhost"
-    );
-  }
-  if (isPrivateNetworkLiteral(url.hostname) && !isLoopbackHost(url.hostname)) {
-    throw new ByokKeysError(
-      "PROVIDER_URL_INVALID",
-      "Private-network provider IPs are not allowed"
-    );
-  }
-  return url.toString().replace(/\/$/u, "");
-}
-function isLoopbackHost(hostname) {
-  const value = hostname.toLowerCase().replace(/^\[|\]$/gu, "");
-  return value === "localhost" || value === "127.0.0.1" || value === "::1";
-}
-function isPrivateNetworkLiteral(hostname) {
-  const value = hostname.toLowerCase().replace(/^\[|\]$/gu, "");
-  if (value.includes(":")) return true;
-  const parts = value.split(".").map(Number);
-  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
-    return false;
-  }
-  return parts[0] === 10 || parts[0] === 127 || parts[0] === 169 && parts[1] === 254 || parts[0] === 172 && (parts[1] ?? 0) >= 16 && (parts[1] ?? 0) <= 31 || parts[0] === 192 && parts[1] === 168;
-}
-
-// src/provider-profile.ts
-var MODEL_PROVIDER_IDS = [
-  "openai",
-  "deepseek",
-  "anthropic",
-  "custom"
-];
-var PROVIDER_AUTH_MODES = ["bearer", "x_api_key", "none"];
-var MODEL_PROVIDER_ADAPTERS = ["openai_compatible", "anthropic"];
-function boundedString(field, maximumLength) {
-  return z.string().superRefine((value, ctx) => {
-    if (value.trim().length === 0 || value.length > maximumLength || /[\u0000\r\n]/u.test(value)) {
-      ctx.addIssue({
-        code: "custom",
-        message: `Provider ${field} is invalid`
-      });
-    }
-  }).transform((value) => value.trim());
-}
-function isoTimestamp(field) {
-  return boundedString(field, 64).superRefine((value, ctx) => {
-    if (!Number.isFinite(Date.parse(value))) {
-      ctx.addIssue({
-        code: "custom",
-        message: `Provider ${field} must be an ISO timestamp`
-      });
-    }
-  });
-}
-var providerBaseUrl = z.string().superRefine((value, ctx) => {
-  try {
-    normalizeProviderUrl(value);
-  } catch (error) {
-    ctx.addIssue({
-      code: "custom",
-      message: error instanceof Error ? error.message : "Provider base URL is invalid",
-      params: {
-        byokCode: error instanceof ByokKeysError ? error.code : "PROVIDER_URL_INVALID"
-      }
-    });
-  }
-}).transform((value) => normalizeProviderUrl(value));
-var ModelProviderProfileSchema = z.object({
-  adapter: z.enum(MODEL_PROVIDER_ADAPTERS),
-  auth_mode: z.enum(PROVIDER_AUTH_MODES),
-  base_url: providerBaseUrl,
-  created_at: isoTimestamp("created_at"),
-  display_name: boundedString("display_name", 100),
-  enabled: z.boolean(),
-  kind: z.literal("model"),
-  model: boundedString("model", 160),
-  provider_id: z.enum(MODEL_PROVIDER_IDS),
-  updated_at: isoTimestamp("updated_at")
-}).superRefine((profile, ctx) => {
-  if (profile.adapter === "anthropic" && profile.auth_mode !== "x_api_key") {
-    ctx.addIssue({
-      code: "custom",
-      message: "Anthropic requires x_api_key authentication",
-      path: ["auth_mode"]
-    });
-  }
-  if (profile.adapter === "openai_compatible" && profile.auth_mode === "x_api_key") {
-    ctx.addIssue({
-      code: "custom",
-      message: "OpenAI-compatible providers support bearer or no authentication",
-      path: ["auth_mode"]
-    });
-  }
-  if (Date.parse(profile.updated_at) < Date.parse(profile.created_at)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Provider updated_at cannot precede created_at",
-      path: ["updated_at"]
-    });
-  }
-});
-function parseModelProviderProfile(value) {
-  const result = ModelProviderProfileSchema.safeParse(value);
-  if (result.success) return result.data;
-  const issue = result.error.issues[0];
-  const params = issue?.params;
-  throw new ByokKeysError(
-    params?.byokCode ?? "PROVIDER_PROFILE_INVALID",
-    issue?.message ?? "Provider profile is invalid",
-    { cause: result.error }
-  );
-}
-
 // src/pi-provider-launcher-core.ts
 var PI_CHILD_BASE_ENV_NAMES = [
   "PATH",
@@ -480,15 +633,17 @@ var PI_CHILD_WINDOWS_ENV_NAMES = [
 ];
 function parsePiProviderLauncherOptions(args) {
   const separator = args.indexOf("--");
-  if (separator < 0) throw new Error("launcher arguments must end with -- <pi args>");
-  const ownArgs = args.slice(0, separator);
-  const piArgs = args.slice(separator + 1);
-  if (piArgs.length === 0) throw new Error("launcher requires Pi arguments after --");
+  const ownArgs = separator < 0 ? args : args.slice(0, separator);
+  const piArgs = separator < 0 ? [] : args.slice(separator + 1);
   const allowedFlags = /* @__PURE__ */ new Set([
     "--pi-bin",
     "--profile-db",
     "--provider",
     "--model",
+    "--profile-revision",
+    "--profile-hash",
+    "--required-capabilities",
+    "--validate-only",
     "--session-dir",
     "--secret-service-prefix",
     "--macos-keychain-path"
@@ -512,9 +667,10 @@ function parsePiProviderLauncherOptions(args) {
     if (value === void 0) throw new Error(`${flag} requires a value`);
     return value;
   };
-  const rawProviderId = required("--provider");
-  if (!MODEL_PROVIDER_IDS.includes(rawProviderId)) {
-    throw new Error(`provider ${rawProviderId} is not configured by @byok-sdk/keys`);
+  const rawProfileRef = required("--provider");
+  const profileRef = ProviderProfileRefSchema.safeParse(rawProfileRef);
+  if (!profileRef.success) {
+    throw new Error(`provider profile ref ${rawProfileRef} is not a valid @byok-sdk/keys identifier`);
   }
   const modelId = required("--model");
   if (modelId.length > 160) throw new Error("--model exceeds 160 characters");
@@ -528,11 +684,54 @@ function parsePiProviderLauncherOptions(args) {
   if (macosKeychainPath !== void 0 && !path2.posix.isAbsolute(macosKeychainPath)) {
     throw new Error("--macos-keychain-path must be an absolute path");
   }
+  const validateOnly = values.get("--validate-only") === "true";
+  if (values.has("--validate-only") && !["true", "false"].includes(values.get("--validate-only"))) {
+    throw new Error("--validate-only must be true or false");
+  }
+  if (!validateOnly && piArgs.length === 0) {
+    throw new Error("launcher requires Pi arguments after --");
+  }
+  const exactValues = [
+    values.get("--profile-revision"),
+    values.get("--profile-hash"),
+    values.get("--required-capabilities")
+  ];
+  if (exactValues.some((value) => value !== void 0) && exactValues.some((value) => value === void 0)) {
+    throw new Error("exact provider binding requires revision, hash, and required capabilities together");
+  }
+  let expectedBinding;
+  if (exactValues[0] !== void 0) {
+    if (!/^(?:0|[1-9][0-9]{0,19})$/u.test(exactValues[0])) {
+      throw new Error("--profile-revision must be canonical decimal");
+    }
+    if (!/^sha256:[0-9a-f]{64}$/u.test(exactValues[1])) {
+      throw new Error("--profile-hash must be lowercase sha256");
+    }
+    let capabilities;
+    try {
+      capabilities = JSON.parse(exactValues[2]);
+    } catch {
+      throw new Error("--required-capabilities must be a JSON array");
+    }
+    const parsedCapabilities = ProviderModelCapabilitySchema.array().max(8).safeParse(capabilities);
+    if (!parsedCapabilities.success || new Set(parsedCapabilities.data).size !== parsedCapabilities.data.length) {
+      throw new Error("--required-capabilities must contain unique supported capabilities");
+    }
+    expectedBinding = {
+      profileRef: profileRef.data,
+      profileRevision: exactValues[0],
+      profileHash: exactValues[1],
+      modelId,
+      requiredCapabilities: parsedCapabilities.data
+    };
+  }
   return {
     piBin: required("--pi-bin"),
     profileDbPath,
-    providerId: rawProviderId,
+    profileRef: profileRef.data,
     modelId,
+    ...expectedBinding === void 0 ? {} : { expectedBinding },
+    validateOnly,
     sessionDir,
     ...secretServicePrefix ? { secretServicePrefix } : {},
     ...macosKeychainPath !== void 0 ? { macosKeychainPath } : {},
@@ -548,11 +747,11 @@ async function resolvePiProviderSecret(profile, createStore) {
       `${secrets.providerLabel} is unavailable`
     );
   }
-  const secret = await secrets.get(modelProviderSecretName(profile.provider_id));
+  const secret = await secrets.get(modelProviderSecretName(profile.profile_ref));
   if (!secret) {
     throw new ByokKeysError(
       "PROVIDER_SECRET_MISSING",
-      `${profile.provider_id} provider requires a secret in ${secrets.providerLabel}`
+      `${profile.profile_ref} provider profile requires a secret in ${secrets.providerLabel}`
     );
   }
   return secret;
@@ -596,10 +795,10 @@ async function ensurePiSessionDirectory(sessionDir) {
 }
 
 // src/profile-store.ts
-function providerNotConfigured(providerId) {
+function providerNotConfigured(profileRef) {
   return new ByokKeysError(
     "PROVIDER_NOT_CONFIGURED",
-    `${providerId} model provider is not configured`
+    `${profileRef} model provider is not configured`
   );
 }
 function closeSqliteDatabaseAfterInitializationFailure(database, initializationError, message, close = (handle) => handle.close()) {
@@ -666,20 +865,40 @@ function secureSqliteFilePermissions(databasePath) {
 }
 
 // src/sqlite-profile-store.ts
+function sqlList(values) {
+  return values.map((value) => `'${value}'`).join(", ");
+}
 var SCHEMA = `
 CREATE TABLE IF NOT EXISTS provider_profile (
-  provider_id  TEXT PRIMARY KEY CHECK (provider_id IN ('openai', 'deepseek', 'anthropic', 'custom')),
-  kind         TEXT NOT NULL CHECK (kind = 'model'),
-  adapter      TEXT NOT NULL CHECK (adapter IN ('openai_compatible', 'anthropic')),
-  display_name TEXT NOT NULL,
-  base_url     TEXT NOT NULL,
-  auth_mode    TEXT NOT NULL CHECK (auth_mode IN ('bearer', 'x_api_key', 'none')),
-  model        TEXT NOT NULL,
-  enabled      INTEGER NOT NULL CHECK (enabled IN (0, 1)),
-  created_at   TEXT NOT NULL,
-  updated_at   TEXT NOT NULL
+  profile_ref   TEXT PRIMARY KEY,
+  provider_kind TEXT NOT NULL CHECK (provider_kind IN (${sqlList(MODEL_PROVIDER_KINDS)})),
+  kind          TEXT NOT NULL CHECK (kind = 'model'),
+  adapter       TEXT NOT NULL CHECK (adapter IN (${sqlList(MODEL_PROVIDER_ADAPTERS)})),
+  display_name  TEXT NOT NULL,
+  base_url      TEXT NOT NULL,
+  auth_mode     TEXT NOT NULL CHECK (auth_mode IN (${sqlList(PROVIDER_AUTH_MODES)})),
+  model         TEXT NOT NULL,
+  capabilities  TEXT NOT NULL,
+  enabled       INTEGER NOT NULL CHECK (enabled IN (0, 1)),
+  created_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL
 );
 `;
+function normalizeTableDdl(sql) {
+  return sql.replace(/\bIF\s+NOT\s+EXISTS\b/giu, "").replace(/\s+/gu, " ").trim().replace(/;$/u, "").trim();
+}
+function assertProviderProfileSchemaIsCurrent(database, path4) {
+  const row = database.prepare(
+    "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'provider_profile'"
+  ).get();
+  const stored = row?.sql;
+  if (typeof stored !== "string") return;
+  if (normalizeTableDdl(stored) === normalizeTableDdl(SCHEMA)) return;
+  throw new ByokKeysError(
+    "PROVIDER_STORE_SCHEMA_STALE",
+    `Provider profile store at ${path4} was created by a different @byok-sdk/keys schema; recreate the store file to continue`
+  );
+}
 var ENABLED_INDEX = `
 CREATE UNIQUE INDEX IF NOT EXISTS provider_profile_one_enabled
 ON provider_profile(kind)
@@ -696,6 +915,7 @@ var SqliteProviderProfileStore = class {
       try {
         this.#database.exec(SCHEMA);
         this.#database.exec(ENABLED_INDEX);
+        assertProviderProfileSchemaIsCurrent(this.#database, options.path);
         secureSqliteFilePermissions(options.path);
       } catch (error) {
         closeSqliteDatabaseAfterInitializationFailure(
@@ -704,6 +924,16 @@ var SqliteProviderProfileStore = class {
           "SqliteProviderProfileStore initialization failed and its native handle could not be closed"
         );
       }
+    } else {
+      try {
+        assertProviderProfileSchemaIsCurrent(this.#database, options.path);
+      } catch (error) {
+        closeSqliteDatabaseAfterInitializationFailure(
+          this.#database,
+          error,
+          "SqliteProviderProfileStore read-only schema check failed and its native handle could not be closed"
+        );
+      }
     }
   }
   /**
@@ -717,12 +947,12 @@ var SqliteProviderProfileStore = class {
     this.#closed = true;
     this.#database.close();
   }
-  async delete(providerId) {
-    const result = this.#database.prepare("DELETE FROM provider_profile WHERE provider_id = ?").run(providerId);
+  async delete(profileRef) {
+    const result = this.#database.prepare("DELETE FROM provider_profile WHERE profile_ref = ?").run(profileRef);
     return Number(result.changes) === 1;
   }
-  async get(providerId) {
-    const row = this.#database.prepare("SELECT * FROM provider_profile WHERE provider_id = ?").get(providerId);
+  async get(profileRef) {
+    const row = this.#database.prepare("SELECT * FROM provider_profile WHERE profile_ref = ?").get(profileRef);
     return row === void 0 ? void 0 : parseRow(row);
   }
   async getEnabled() {
@@ -730,11 +960,11 @@ var SqliteProviderProfileStore = class {
     return row === void 0 ? void 0 : parseRow(row);
   }
   async list() {
-    const rows = this.#database.prepare("SELECT * FROM provider_profile ORDER BY provider_id ASC").all();
+    const rows = this.#database.prepare("SELECT * FROM provider_profile ORDER BY profile_ref ASC").all();
     return rows.map(parseRow);
   }
   async save(profile) {
-    const existing = await this.get(profile.provider_id);
+    const existing = await this.get(profile.profile_ref);
     const validated = parseModelProviderProfile({
       ...profile,
       created_at: existing?.created_at ?? profile.created_at
@@ -742,40 +972,44 @@ var SqliteProviderProfileStore = class {
     this.#transaction(() => {
       if (validated.enabled) {
         this.#database.prepare(
-          "UPDATE provider_profile SET enabled = 0 WHERE provider_id <> ?"
-        ).run(validated.provider_id);
+          "UPDATE provider_profile SET enabled = 0 WHERE profile_ref <> ?"
+        ).run(validated.profile_ref);
       }
       this.#database.prepare(
         `INSERT INTO provider_profile (
-             provider_id, kind, adapter, display_name, base_url,
-             auth_mode, model, enabled, created_at, updated_at
-           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-           ON CONFLICT(provider_id) DO UPDATE SET
+             profile_ref, provider_kind, kind, adapter, display_name, base_url,
+             auth_mode, model, capabilities, enabled, created_at, updated_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(profile_ref) DO UPDATE SET
+             provider_kind = excluded.provider_kind,
              adapter = excluded.adapter,
              display_name = excluded.display_name,
              base_url = excluded.base_url,
              auth_mode = excluded.auth_mode,
              model = excluded.model,
+             capabilities = excluded.capabilities,
              enabled = excluded.enabled,
              updated_at = excluded.updated_at`
       ).run(
-        validated.provider_id,
+        validated.profile_ref,
+        validated.provider_kind,
         validated.kind,
         validated.adapter,
         validated.display_name,
         validated.base_url,
         validated.auth_mode,
         validated.model,
+        JSON.stringify(validated.capabilities),
         validated.enabled ? 1 : 0,
         validated.created_at,
         validated.updated_at
       );
     });
-    return await this.get(validated.provider_id);
+    return await this.get(validated.profile_ref);
   }
-  async setEnabled(providerId) {
-    const existing = await this.get(providerId);
-    if (existing === void 0) throw providerNotConfigured(providerId);
+  async setEnabled(profileRef) {
+    const existing = await this.get(profileRef);
+    if (existing === void 0) throw providerNotConfigured(profileRef);
     return this.save({ ...existing, enabled: true });
   }
   /** `BEGIN IMMEDIATE` / `COMMIT` / `ROLLBACK`, per `providers.ts:1252-1263`. */
@@ -791,8 +1025,19 @@ var SqliteProviderProfileStore = class {
   }
 };
 function parseRow(row) {
+  let capabilities;
+  try {
+    capabilities = JSON.parse(row.capabilities);
+  } catch (cause) {
+    throw new ByokKeysError(
+      "PROVIDER_PROFILE_INVALID",
+      "Provider profile capabilities column is not valid JSON",
+      { cause }
+    );
+  }
   return parseModelProviderProfile({
     ...row,
+    capabilities,
     enabled: row.enabled === 1
   });
 }
@@ -1100,15 +1345,19 @@ async function run(options) {
   });
   let projectionDir;
   try {
-    const profile = await profiles.get(options.providerId);
+    const profile = await profiles.get(options.profileRef);
     if (profile === void 0) {
-      throw new Error(`provider ${options.providerId} is not configured`);
+      throw new Error(`provider profile ${options.profileRef} is not configured`);
     }
     if (profile.model !== options.modelId) {
       throw new Error(
         `selected model ${options.modelId} does not match configured provider model ${profile.model}`
       );
     }
+    if (options.expectedBinding !== void 0) {
+      assertExactProviderProfileBinding(profile, options.expectedBinding);
+    }
+    if (options.validateOnly) return 0;
     const secret = await resolvePiProviderSecret(
       profile,
       () => createSecretStore(