@theokit/sdk 4.13.0 → 4.13.1

package/dist/models.js

@@ -1,4 +1,4 @@
-import { statSync, readFileSync, unlinkSync, mkdirSync, writeFileSync, renameSync } from 'fs';
+import { statSync, readFileSync, unlinkSync, mkdirSync, writeFileSync, renameSync, chmodSync, openSync, fsyncSync, closeSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { z } from 'zod';
@@ -41,8 +41,34 @@ var catalogModelSchema = z.object({
 }).loose();
 
 // src/internal/providers/registry.ts
-var REGISTRY = /* @__PURE__ */ new Map();
-var ALIASES = /* @__PURE__ */ new Map();
+function globalSingleton(key, create) {
+  const g = globalThis;
+  const sym = Symbol.for(key);
+  if (g[sym] === void 0) g[sym] = create();
+  return g[sym];
+}
+var REGISTRY = globalSingleton(
+  "theokit-sdk.providers.registry",
+  () => /* @__PURE__ */ new Map()
+);
+var ALIASES = globalSingleton("theokit-sdk.providers.aliases", () => /* @__PURE__ */ new Map());
+function registerProvider(profile) {
+  if (REGISTRY.has(profile.name)) {
+    process.stderr.write(`[theokit-sdk] Provider "${profile.name}" overridden by user plugin.
+`);
+  }
+  REGISTRY.set(profile.name, profile);
+  for (const alias of profile.aliases ?? []) {
+    const previous = ALIASES.get(alias);
+    if (previous !== void 0 && previous !== profile.name) {
+      process.stderr.write(
+        `[theokit-sdk] Alias "${alias}" collision: was "${previous}", now "${profile.name}".
+`
+      );
+    }
+    ALIASES.set(alias, profile.name);
+  }
+}
 function getProviderProfile(name) {
   const canonical = ALIASES.get(name) ?? name;
   return REGISTRY.get(canonical);
@@ -50,22 +76,46 @@ function getProviderProfile(name) {
 
 // src/internal/providers/catalog-loader.ts
 var __dirname_resolved = dirname(fileURLToPath(import.meta.url));
-var modelInfoIndex = /* @__PURE__ */ new Map();
+function globalSingleton2(key, create) {
+  const g = globalThis;
+  const sym = Symbol.for(key);
+  if (g[sym] === void 0) g[sym] = create();
+  return g[sym];
+}
+var modelInfoIndex = globalSingleton2(
+  "theokit-sdk.providers.model-info-index",
+  () => /* @__PURE__ */ new Map()
+);
+var patchedModelKeys = globalSingleton2(
+  "theokit-sdk.providers.model-info-patched",
+  () => /* @__PURE__ */ new Set()
+);
+var indexState = globalSingleton2("theokit-sdk.providers.model-info-loaded", () => ({
+  loaded: false
+}));
 function getCatalogModelInfo(key) {
   ensureModelIndexLoaded();
   return modelInfoIndex.get(key);
 }
 function patchModelInfo(key, model) {
   ensureModelIndexLoaded();
-  modelInfoIndex.set(key, model);
+  const existing = modelInfoIndex.get(key);
+  modelInfoIndex.set(key, existing === void 0 ? model : { ...existing, ...model });
+  patchedModelKeys.add(key);
 }
-var _modelIndexLoaded = false;
 function ensureModelIndexLoaded() {
-  if (_modelIndexLoaded) return;
-  _modelIndexLoaded = true;
-  const catalog = loadProviderCatalog();
-  for (const entry of Object.values(catalog)) {
-    indexEntryModels(entry);
+  if (indexState.loaded) return;
+  indexState.loaded = true;
+  try {
+    const catalog = loadProviderCatalog();
+    for (const entry of Object.values(catalog)) {
+      indexEntryModels(entry);
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[theokit-sdk] WARN: provider catalog unavailable (${err.message}) \u2014 per-model data disabled
+`
+    );
   }
 }
 function indexEntryModels(entry) {
@@ -110,6 +160,27 @@ function loadProviderCatalog(opts) {
   }
   return result;
 }
+function registerCatalogProviders(opts) {
+  const catalog = loadProviderCatalog();
+  for (const entry of Object.values(catalog)) {
+    if (getProviderProfile(entry.id) !== void 0) continue;
+    if (entry.aliases?.some((a) => getProviderProfile(a) !== void 0)) continue;
+    const profile = {
+      name: entry.id,
+      apiMode: entry.apiMode,
+      authType: entry.authType,
+      baseUrl: entry.baseUrl,
+      envVars: entry.envVars,
+      fallbackModels: entry.fallbackModels,
+      displayName: entry.displayName,
+      aliases: entry.aliases,
+      modelsUrl: entry.modelsUrl,
+      hostname: entry.hostname,
+      extraHeaders: entry.extraHeaders
+    };
+    registerProvider(profile);
+  }
+}
 
 // src/internal/llm/model-capabilities.ts
 var CONSERVATIVE_DEFAULTS = {
@@ -299,12 +370,502 @@ var Retry = class {
   }
 };
 
+// src/internal/providers/builtin/anthropic.ts
+var ANTHROPIC = {
+  name: "anthropic",
+  apiMode: "anthropic_messages",
+  envVars: ["ANTHROPIC_API_KEY"],
+  authType: "api_key",
+  baseUrl: "https://api.anthropic.com",
+  modelsUrl: "https://api.anthropic.com/v1/models",
+  hostname: "api.anthropic.com",
+  fallbackModels: ["claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5-20251001"]
+};
+
+// src/internal/providers/builtin/bedrock.ts
+var BEDROCK = {
+  name: "bedrock",
+  apiMode: "bedrock_anthropic",
+  envVars: ["AWS_BEARER_TOKEN_BEDROCK"],
+  authType: "aws_bearer",
+  baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
+  modelsUrl: void 0,
+  hostname: "bedrock-runtime.amazonaws.com",
+  fallbackModels: [
+    "bedrock/us.anthropic.claude-sonnet-4-5-v1:0",
+    "bedrock/us.anthropic.claude-opus-4-7-v1:0",
+    "bedrock/global.anthropic.claude-haiku-4-5-v1:0"
+  ]
+};
+
+// src/internal/providers/builtin/gemini.ts
+var GEMINI = {
+  name: "gemini",
+  apiMode: "chat_completions",
+  envVars: ["OPENROUTER_API_KEY"],
+  authType: "api_key",
+  baseUrl: "https://openrouter.ai/api",
+  hostname: "openrouter.ai",
+  fallbackModels: ["google/gemini-2.0-flash-001"]
+};
+
+// src/internal/providers/builtin/llamacpp.ts
+var LLAMACPP = {
+  name: "llamacpp",
+  aliases: ["llama-cpp", "llama.cpp"],
+  apiMode: "chat_completions",
+  envVars: ["LLAMACPP_API_KEY"],
+  authType: "none",
+  baseUrl: "http://localhost:8080",
+  modelsUrl: "http://localhost:8080/v1/models",
+  hostname: "localhost",
+  fallbackModels: ["loaded-model"]
+};
+
+// src/internal/providers/builtin/lmstudio.ts
+var LMSTUDIO = {
+  name: "lmstudio",
+  aliases: ["lm-studio", "lm_studio"],
+  apiMode: "chat_completions",
+  envVars: ["LMSTUDIO_API_KEY"],
+  authType: "none",
+  baseUrl: "http://localhost:1234",
+  modelsUrl: "http://localhost:1234/v1/models",
+  hostname: "localhost",
+  fallbackModels: ["loaded-model"]
+};
+
+// src/internal/providers/builtin/ollama.ts
+var OLLAMA = {
+  name: "ollama",
+  apiMode: "chat_completions",
+  envVars: ["OLLAMA_API_KEY"],
+  authType: "none",
+  baseUrl: "http://localhost:11434",
+  modelsUrl: "http://localhost:11434/v1/models",
+  hostname: "localhost",
+  fallbackModels: ["llama3.2", "qwen2.5", "mistral"]
+};
+
+// src/internal/providers/builtin/openai.ts
+var OPENAI = {
+  name: "openai",
+  apiMode: "chat_completions",
+  envVars: ["OPENAI_API_KEY"],
+  authType: "api_key",
+  baseUrl: "https://api.openai.com",
+  modelsUrl: "https://api.openai.com/v1/models",
+  hostname: "api.openai.com",
+  fallbackModels: ["gpt-4o", "gpt-4o-mini"]
+};
+function credentialHome(config, env = {}) {
+  const override = config.homeEnvVar !== void 0 ? env[config.homeEnvVar]?.trim() : void 0;
+  return override !== void 0 && override.length > 0 ? override : join(config.home, config.dirName);
+}
+function authFilePath(config, env = {}) {
+  return join(credentialHome(config, env), config.fileName);
+}
+var CredentialError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CredentialError";
+  }
+};
+var apiFileSchema = z.object({
+  type: z.literal("api").optional(),
+  provider: z.string().min(1).optional(),
+  api_key: z.string()
+}).strict();
+var oauthFileSchema = z.object({
+  type: z.literal("oauth"),
+  provider: z.string().min(1),
+  access: z.string().min(1),
+  refresh: z.string().min(1),
+  expires: z.number(),
+  account_id: z.string().optional()
+}).strict();
+var fileSchema = z.union([oauthFileSchema, apiFileSchema]);
+function assertSecureModes(dirPath, path) {
+  const dirMode = statSync(dirPath).mode & 511;
+  if ((dirMode & 18) !== 0) {
+    throw new CredentialError(
+      `${dirPath} is writable by other users (mode ${dirMode.toString(8)}), so the credential file inside it can be replaced. Fix it with:  chmod 700 ${dirPath}`
+    );
+  }
+  const mode = statSync(path).mode & 511;
+  if ((mode & 63) !== 0) {
+    throw new CredentialError(
+      `${path} is readable by other users (mode ${mode.toString(8)}). A credential file must not be. Fix it with:  chmod 600 ${path}`
+    );
+  }
+}
+function describeUnionError(parsed, err, path) {
+  const looksOAuth = typeof parsed === "object" && parsed !== null && parsed.type === "oauth";
+  const specific = looksOAuth ? oauthFileSchema.safeParse(parsed) : apiFileSchema.safeParse(parsed);
+  let issue;
+  if (!specific.success) {
+    issue = specific.error.issues[0];
+  } else if (err instanceof z.ZodError) {
+    issue = err.issues[0];
+  }
+  return new CredentialError(
+    `${path}: ${issue?.message ?? String(err)} [${issue?.path.join(".") || "root"}]`
+  );
+}
+function parseStoredFile(raw, path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CredentialError(
+      `${path} is not valid JSON. Expected:  {"provider": "<name>", "api_key": "..."}`
+    );
+  }
+  try {
+    return fileSchema.parse(parsed);
+  } catch (err) {
+    throw describeUnionError(parsed, err, path);
+  }
+}
+function readAuthFile(config, env = {}) {
+  const path = authFilePath(config, env);
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw new CredentialError(`cannot read ${path}: ${err.message}`);
+  }
+  assertSecureModes(credentialHome(config, env), path);
+  return parseStoredFile(raw, path);
+}
+function readStoredOAuth(config, env = {}) {
+  const stored = readAuthFile(config, env);
+  return stored !== void 0 && stored.type === "oauth" ? stored : void 0;
+}
+function isOAuthWrite(c) {
+  return "type" in c && c.type === "oauth";
+}
+function buildStorePayload(cred) {
+  if (isOAuthWrite(cred)) {
+    if (cred.access.length === 0 || cred.refresh.length === 0) {
+      throw new CredentialError(
+        "refusing to write an oauth credential with an empty access/refresh token"
+      );
+    }
+    return {
+      type: "oauth",
+      provider: cred.provider,
+      access: cred.access,
+      refresh: cred.refresh,
+      expires: cred.expires,
+      ...cred.account_id !== void 0 ? { account_id: cred.account_id } : {}
+    };
+  }
+  if (typeof cred.apiKey !== "string" || cred.apiKey.length === 0) {
+    throw new CredentialError("refusing to write an empty API key");
+  }
+  return { provider: cred.provider, api_key: cred.apiKey };
+}
+function writeCredential(cred, config, env = {}) {
+  const payload = buildStorePayload(cred);
+  const dir = credentialHome(config, env);
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  chmodSync(dir, 448);
+  const path = authFilePath(config, env);
+  const tmp = `${path}.tmp-${randomBytes(8).toString("hex")}`;
+  try {
+    const fd = openSync(tmp, "wx", 384);
+    try {
+      writeFileSync(fd, `${JSON.stringify(payload, null, 2)}
+`);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    chmodSync(tmp, 384);
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw new CredentialError(`cannot write ${path}: ${err.message}`);
+  }
+  return path;
+}
+
+// src/server/auth/errors.ts
+var AuthCallbackError = class extends Error {
+  name = "AuthCallbackError";
+  code;
+  constructor(code, message) {
+    super(message ?? `OAuth callback error: ${code}`);
+    this.code = code;
+  }
+};
+
+// src/internal/auth/oauth-engine.ts
+var REFRESH_SKEW_MS = 6e4;
+function parseTokenResponse(body, now) {
+  const b = body;
+  if (typeof b.access_token !== "string" || b.access_token.length === 0) {
+    throw new AuthCallbackError(
+      "oauth_token_exchange_failed",
+      "token response had no access_token"
+    );
+  }
+  if (typeof b.refresh_token !== "string" || b.refresh_token.length === 0) {
+    throw new AuthCallbackError(
+      "oauth_token_exchange_failed",
+      "token response had no refresh_token"
+    );
+  }
+  const expiresIn = typeof b.expires_in === "number" ? b.expires_in : 3600;
+  return {
+    access: b.access_token,
+    refresh: b.refresh_token,
+    expires: now + expiresIn * 1e3,
+    ...typeof b.account_id === "string" ? { accountId: b.account_id } : {}
+  };
+}
+async function postGrant(config, form, deps) {
+  let res;
+  try {
+    res = await deps.fetch(config.tokenEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: new URLSearchParams(form).toString()
+    });
+  } catch (err) {
+    throw new AuthCallbackError(
+      "oauth_token_exchange_failed",
+      `token endpoint request failed: ${err.message}`
+    );
+  }
+  if (!res.ok) {
+    throw new AuthCallbackError(
+      "oauth_token_exchange_failed",
+      `token endpoint returned HTTP ${res.status}`
+    );
+  }
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    throw new AuthCallbackError("oauth_token_exchange_failed", "token response was not valid JSON");
+  }
+  return parseTokenResponse(json, deps.now());
+}
+function refreshOAuthTokens(config, refresh, deps) {
+  return postGrant(
+    config,
+    { grant_type: "refresh_token", refresh_token: refresh, client_id: config.clientId },
+    deps
+  );
+}
+function persistOAuthTokens(provider, tokens, store, env = {}) {
+  return writeCredential(
+    {
+      type: "oauth",
+      provider,
+      access: tokens.access,
+      refresh: tokens.refresh,
+      expires: tokens.expires,
+      ...tokens.accountId !== void 0 ? { account_id: tokens.accountId } : {}
+    },
+    store,
+    env
+  );
+}
+var inFlightRefresh = /* @__PURE__ */ new Map();
+async function ensureFreshCredential(resolved, opts, deps) {
+  if (resolved.kind !== "oauth") return resolved;
+  const now = deps.now();
+  if (resolved.expiresAt !== void 0 && resolved.expiresAt > now + REFRESH_SKEW_MS) {
+    return resolved;
+  }
+  const env = opts.env ?? {};
+  const path = authFilePath(opts.store, env);
+  let refresh = inFlightRefresh.get(path);
+  if (refresh === void 0) {
+    refresh = (async () => {
+      const stored = readStoredOAuth(opts.store, env);
+      if (stored === void 0) {
+        throw new AuthCallbackError(
+          "oauth_token_exchange_failed",
+          "no stored oauth credential to refresh"
+        );
+      }
+      const fresh2 = await refreshOAuthTokens(opts.config, stored.refresh, deps);
+      const merged = {
+        ...fresh2,
+        accountId: fresh2.accountId ?? stored.account_id
+      };
+      persistOAuthTokens(resolved.provider, merged, opts.store, env);
+      return merged;
+    })();
+    inFlightRefresh.set(path, refresh);
+    refresh.finally(() => inFlightRefresh.delete(path)).catch(() => {
+    });
+  }
+  const fresh = await refresh;
+  return {
+    kind: "oauth",
+    provider: resolved.provider,
+    apiKey: fresh.access,
+    source: resolved.source,
+    inferred: false,
+    expiresAt: fresh.expires
+  };
+}
+
+// src/internal/auth/resolve-credential.ts
+async function resolveOAuth(stored, path, opts, env) {
+  if (stored.provider !== opts.provider) return void 0;
+  const base = {
+    kind: "oauth",
+    provider: opts.provider,
+    apiKey: stored.access,
+    source: path,
+    inferred: false,
+    expiresAt: stored.expires
+  };
+  if (opts.oauth === void 0) return base;
+  const deps = {
+    fetch: opts.deps?.fetch ?? fetch,
+    now: opts.deps?.now ?? (() => Date.now())
+  };
+  return ensureFreshCredential(base, { config: opts.oauth, store: opts.store, env }, deps);
+}
+async function resolveCredential(opts) {
+  const env = opts.env ?? {};
+  const stored = readAuthFile(opts.store, env);
+  if (stored === void 0) return void 0;
+  const path = authFilePath(opts.store, env);
+  if (stored.type === "oauth") {
+    return resolveOAuth(stored, path, opts, env);
+  }
+  if (stored.api_key.length === 0) return void 0;
+  if (stored.provider !== opts.provider) return void 0;
+  return {
+    kind: "api",
+    provider: opts.provider,
+    apiKey: stored.api_key,
+    source: path,
+    inferred: false
+  };
+}
+
+// src/internal/providers/builtin/openai-chatgpt.ts
+var DEFAULT_STORE = {
+  home: homedir(),
+  dirName: ".theokit",
+  fileName: "auth.json",
+  homeEnvVar: "THEOKIT_AUTH_HOME"
+};
+var OPENAI_OAUTH_CONFIG = {
+  provider: "openai",
+  authorizeEndpoint: "https://auth.openai.com/oauth/authorize",
+  tokenEndpoint: "https://auth.openai.com/oauth/token",
+  clientId: "app_EMoamEEZ73f0CkXaXp7hrann",
+  scopes: ["openid", "profile", "email", "offline_access"],
+  redirectUri: "https://auth.openai.com/deviceauth/callback"
+};
+function codexFetch() {
+  return (async (input, init) => {
+    const env = process.env;
+    const resolved = await resolveCredential({
+      provider: "openai",
+      store: DEFAULT_STORE,
+      oauth: OPENAI_OAUTH_CONFIG,
+      env
+    });
+    if (resolved === void 0) {
+      throw new Error(
+        'openai-chatgpt: no ChatGPT credential found \u2014 run the OpenAI device login (e.g. "/login openai") first.'
+      );
+    }
+    const accountId = readStoredOAuth(DEFAULT_STORE, env)?.account_id;
+    const headers = new Headers(init?.headers);
+    headers.set("authorization", `Bearer ${resolved.apiKey}`);
+    if (accountId !== void 0) headers.set("ChatGPT-Account-Id", accountId);
+    return fetch(input, { ...init, headers });
+  });
+}
+var OPENAI_CHATGPT = {
+  name: "openai-chatgpt",
+  apiMode: "responses_api",
+  authType: "oauth_device_code",
+  baseUrl: "https://chatgpt.com/backend-api/codex",
+  envVars: [],
+  fallbackModels: [
+    "openai-chatgpt/gpt-5.4",
+    "openai-chatgpt/gpt-5.4-mini",
+    "openai-chatgpt/gpt-5.5"
+  ],
+  extraHeaders: { originator: "codex_cli_rs" },
+  transform: {
+    // Only `fetch` (async) can await the credential refresh; `headers` is sync and cannot.
+    fetch: () => codexFetch()
+  }
+};
+
+// src/internal/providers/builtin/openrouter.ts
+var OPENROUTER = {
+  name: "openrouter",
+  apiMode: "chat_completions",
+  aliases: ["or"],
+  // Ordered fallback (EC-10): OPENROUTER_API_KEY preferred, OPENAI_API_KEY as compat.
+  envVars: ["OPENROUTER_API_KEY", "OPENAI_API_KEY"],
+  authType: "api_key",
+  baseUrl: "https://openrouter.ai/api",
+  modelsUrl: "https://openrouter.ai/api/v1/models",
+  hostname: "openrouter.ai",
+  fallbackModels: ["openai/gpt-4o-mini", "anthropic/claude-3-haiku"]
+};
+
+// src/internal/providers/builtin/vertex.ts
+var VERTEX = {
+  name: "vertex",
+  apiMode: "anthropic_messages",
+  // sub-dispatched in selectTransport by profile.name
+  envVars: ["GOOGLE_APPLICATION_CREDENTIALS"],
+  authType: "gcp_oauth",
+  baseUrl: "https://us-central1-aiplatform.googleapis.com",
+  modelsUrl: void 0,
+  hostname: "aiplatform.googleapis.com",
+  fallbackModels: [
+    "vertex/anthropic/claude-sonnet-4-5@20250929",
+    "vertex/google/gemini-2.0-flash-001"
+  ]
+};
+
+// src/internal/providers/builtin/index.ts
+var registered = false;
+function registerBuiltins() {
+  if (registered) return;
+  registered = true;
+  registerProvider(ANTHROPIC);
+  registerProvider(OPENAI);
+  registerProvider(OPENAI_CHATGPT);
+  registerProvider(OPENROUTER);
+  registerProvider(GEMINI);
+  registerProvider(OLLAMA);
+  registerProvider(LMSTUDIO);
+  registerProvider(LLAMACPP);
+  registerProvider(BEDROCK);
+  registerProvider(VERTEX);
+  registerCatalogProviders();
+}
+
 // src/internal/providers/catalog-source-models-dev.ts
 var DEFAULT_URL = "https://models.dev/api.json";
 var TTL_MS = 60 * 60 * 1e3;
 var FETCH_TIMEOUT_MS = 1e4;
 function cachePathFor(url) {
-  const dir = join(homedir(), ".theokit", "cache", "models-dev");
+  const base = process.env.THEOKIT_HOME?.trim() || join(homedir(), ".theokit");
+  const dir = join(base, "cache", "models-dev");
   if (url === DEFAULT_URL) return join(dir, "api.json");
   const hash = createHash("sha256").update(url).digest("hex").slice(0, 12);
   return join(dir, `api-${hash}.json`);
@@ -323,21 +884,62 @@ function writeCacheAtomic(path, body) {
     throw err;
   }
 }
+var MODELS_DEV_ID_MAP = {
+  google: "google-gemini",
+  zai: "zhipu",
+  togetherai: "together",
+  "fireworks-ai": "fireworks",
+  "amazon-bedrock": "bedrock",
+  "google-vertex": "vertex"
+};
+var _catalogTargets;
+function catalogTargets() {
+  if (_catalogTargets !== void 0) return _catalogTargets;
+  _catalogTargets = /* @__PURE__ */ new Map();
+  try {
+    for (const entry of Object.values(loadProviderCatalog())) {
+      const keys = [entry.id, ...entry.aliases ?? []];
+      for (const k of keys) {
+        if (!_catalogTargets.has(k)) _catalogTargets.set(k, { keys });
+      }
+    }
+  } catch {
+  }
+  return _catalogTargets;
+}
+function resolvePatchKeys(externalId) {
+  const mapped = MODELS_DEV_ID_MAP[externalId] ?? externalId;
+  const fromCatalog = catalogTargets().get(mapped);
+  if (fromCatalog !== void 0) return fromCatalog.keys;
+  const profile = getProviderProfile(mapped);
+  if (profile !== void 0) return [profile.name, ...profile.aliases ?? []];
+  return void 0;
+}
 function patchIndexFromApiJson(raw) {
   if (typeof raw !== "object" || raw === null) return 0;
   let patched = 0;
+  const skipped = [];
   for (const [providerId, provider] of Object.entries(raw)) {
     const models = provider?.models;
     if (models === void 0 || typeof models !== "object") continue;
-    const profile = getProviderProfile(providerId);
-    if (profile === void 0) continue;
+    const keys = resolvePatchKeys(providerId);
+    if (keys === void 0) {
+      skipped.push(providerId);
+      continue;
+    }
     for (const [modelId, rawModel] of Object.entries(models)) {
       const parsed = catalogModelSchema.safeParse(rawModel);
       if (!parsed.success) continue;
-      patchModelInfo(`${profile.name}/${modelId}`, parsed.data);
+      for (const key of keys) patchModelInfo(`${key}/${modelId}`, parsed.data);
       patched++;
     }
   }
+  if (skipped.length > 0) {
+    process.stderr.write(
+      `[theokit-sdk] WARN: models-dev refresh skipped ${skipped.length} unknown provider(s) (e.g. ${skipped.slice(0, 3).join(", ")})
+`
+    );
+  }
   return patched;
 }
 function loadCacheIntoIndex(url = DEFAULT_URL) {
@@ -348,8 +950,9 @@ function loadCacheIntoIndex(url = DEFAULT_URL) {
   } catch {
     return 0;
   }
+  let parsed;
   try {
-    return patchIndexFromApiJson(JSON.parse(body));
+    parsed = JSON.parse(body);
   } catch {
     try {
       unlinkSync(path);
@@ -359,9 +962,20 @@ function loadCacheIntoIndex(url = DEFAULT_URL) {
 `);
     return 0;
   }
+  try {
+    return patchIndexFromApiJson(parsed);
+  } catch (err) {
+    process.stderr.write(
+      `[theokit-sdk] WARN: models-dev cache patch failed (${err.message})
+`
+    );
+    return 0;
+  }
 }
 async function refreshModelCatalog(opts = {}) {
-  if (process.env.THEOKIT_DISABLE_MODELS_FETCH !== void 0) {
+  registerBuiltins();
+  const kill = process.env.THEOKIT_DISABLE_MODELS_FETCH;
+  if (kill !== void 0 && kill !== "" && kill !== "0" && kill.toLowerCase() !== "false") {
     return { source: "skipped", models: 0 };
   }
   const url = opts.url ?? process.env.THEOKIT_MODELS_URL ?? DEFAULT_URL;
@@ -406,7 +1020,15 @@ async function refreshModelCatalog(opts = {}) {
 `
     );
   }
-  return { source: "network", models: patchIndexFromApiJson(JSON.parse(body)) };
+  try {
+    return { source: "network", models: patchIndexFromApiJson(JSON.parse(body)) };
+  } catch (err) {
+    process.stderr.write(
+      `[theokit-sdk] WARN: models-dev patch failed (${err.message}) \u2014 serving existing data
+`
+    );
+    return { source: "cache", models: 0 };
+  }
 }
 function getModelInfo(modelId) {
   return getCatalogModelInfo(modelId);