@theokit/sdk 4.12.2 → 4.13.1

package/dist/models.js

@@ -1,3 +1,187 @@
+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';
+import { createHash, randomBytes } from 'crypto';
+import { homedir } from 'os';
+
+// src/internal/providers/catalog-loader.ts
+var MODALITIES = ["text", "audio", "image", "video", "pdf"];
+var costSchema = z.object({
+  /** USD per 1M tokens (models.dev convention). */
+  input: z.number().nonnegative(),
+  output: z.number().nonnegative(),
+  cache_read: z.number().nonnegative().optional(),
+  cache_write: z.number().nonnegative().optional()
+}).loose();
+var limitSchema = z.object({
+  context: z.number().positive(),
+  input: z.number().positive().optional(),
+  output: z.number().positive().optional()
+}).loose();
+var modalitiesSchema = z.object({
+  input: z.array(z.enum(MODALITIES)).optional(),
+  output: z.array(z.enum(MODALITIES)).optional()
+}).loose();
+var catalogModelSchema = z.object({
+  name: z.string().optional(),
+  release_date: z.string().optional(),
+  attachment: z.boolean().optional(),
+  reasoning: z.boolean().optional(),
+  temperature: z.boolean().optional(),
+  tool_call: z.boolean().optional(),
+  /** theokit extension — maps to ModelCapabilities.supportsStructuredOutput. */
+  structured_output: z.boolean().optional(),
+  /** theokit extension — maps to ModelCapabilities.supportsCacheControl. */
+  cache_control: z.boolean().optional(),
+  cost: costSchema.optional(),
+  limit: limitSchema.optional(),
+  modalities: modalitiesSchema.optional(),
+  status: z.enum(["alpha", "beta", "deprecated"]).optional()
+}).loose();
+
+// src/internal/providers/registry.ts
+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);
+}
+
+// src/internal/providers/catalog-loader.ts
+var __dirname_resolved = dirname(fileURLToPath(import.meta.url));
+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();
+  const existing = modelInfoIndex.get(key);
+  modelInfoIndex.set(key, existing === void 0 ? model : { ...existing, ...model });
+  patchedModelKeys.add(key);
+}
+function ensureModelIndexLoaded() {
+  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) {
+  if (entry.models === void 0 || typeof entry.models !== "object") return;
+  for (const [modelId, raw] of Object.entries(entry.models)) {
+    const parsed = catalogModelSchema.safeParse(raw);
+    if (!parsed.success) {
+      process.stderr.write(
+        `[theokit-sdk] WARN: Skipping malformed catalog model "${entry.id}/${modelId}": ${parsed.error.issues[0]?.message ?? "invalid"}
+`
+      );
+      continue;
+    }
+    modelInfoIndex.set(`${entry.id}/${modelId}`, parsed.data);
+    for (const alias of entry.aliases ?? []) {
+      const key = `${alias}/${modelId}`;
+      if (!modelInfoIndex.has(key)) modelInfoIndex.set(key, parsed.data);
+    }
+  }
+}
+function validateEntry(raw) {
+  if (typeof raw.id !== "string" || typeof raw.displayName !== "string" || typeof raw.apiMode !== "string" || typeof raw.authType !== "string" || typeof raw.baseUrl !== "string" || !Array.isArray(raw.envVars) || !Array.isArray(raw.fallbackModels) || raw.capabilities == null || typeof raw.capabilities !== "object") {
+    return null;
+  }
+  return raw;
+}
+function loadProviderCatalog(opts) {
+  const catalogPath = join(__dirname_resolved, "provider-catalog.json");
+  const rawText = readFileSync(catalogPath, "utf-8");
+  let entries = JSON.parse(rawText);
+  const result = {};
+  for (const raw of entries) {
+    const validated = validateEntry(raw);
+    if (validated === null) {
+      process.stderr.write(
+        `[theokit-sdk] WARN: Skipping malformed catalog entry: ${JSON.stringify(raw).slice(0, 100)}
+`
+      );
+      continue;
+    }
+    result[validated.id] = validated;
+  }
+  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 = {
   supportsVision: false,
@@ -7,268 +191,25 @@ var CONSERVATIVE_DEFAULTS = {
   maxContextTokens: 4096,
   maxOutputTokens: 4096
 };
-var EXACT = /* @__PURE__ */ new Map([
-  // OpenAI family
-  [
-    "openai/gpt-4o",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: true,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 128e3,
-      maxOutputTokens: 16384
-    }
-  ],
-  [
-    "openai/gpt-4o-mini",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: true,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 128e3,
-      maxOutputTokens: 16384
-    }
-  ],
-  [
-    "openai/gpt-4-turbo",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 128e3,
-      maxOutputTokens: 4096
-    }
-  ],
-  [
-    "openai/o1",
-    {
-      supportsVision: false,
-      supportsStructuredOutput: true,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 1e5
-    }
-  ],
-  [
-    "openai/o3",
-    {
-      supportsVision: false,
-      supportsStructuredOutput: true,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 1e5
-    }
-  ],
-  [
-    // GPT-4.1 — 1M-context flagship; multimodal + structured output (RADAR #92.a).
-    "openai/gpt-4.1",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: true,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 1047576,
-      maxOutputTokens: 32768
-    }
-  ],
-  // Anthropic family
-  [
-    "anthropic/claude-opus-4",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 32e3
-    }
-  ],
-  [
-    "anthropic/claude-sonnet-4",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 16e3
-    }
-  ],
-  [
-    "anthropic/claude-3-5-sonnet",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 8192
-    }
-  ],
-  [
-    "anthropic/claude-3-5-sonnet-latest",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 8192
-    }
-  ],
-  [
-    "anthropic/claude-3-5-haiku-latest",
-    {
-      supportsVision: false,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 8192
-    }
-  ],
-  [
-    "anthropic/claude-3-haiku",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 4096
-    }
-  ],
-  [
-    "anthropic/claude-3-opus",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 4096
-    }
-  ],
-  // Dot-form OpenRouter slugs theocode uses (RADAR #92.a). These are the same
-  // models as their dash-form siblings above; capability parity is intentional.
-  // Without these entries the dotted slugs fall through to the 4096 default
-  // (`anthropic/claude-3.5-sonnet` ≠ `anthropic/claude-3-5-sonnet`).
-  [
-    "anthropic/claude-opus-4.1",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 32e3
-    }
-  ],
-  [
-    "anthropic/claude-sonnet-4.5",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 16e3
-    }
-  ],
-  [
-    "anthropic/claude-3.5-sonnet",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: true,
-      maxContextTokens: 2e5,
-      maxOutputTokens: 8192
-    }
-  ],
-  // Cheap OpenRouter slugs (RADAR #92.a) — previously fell to the 4096
-  // CONSERVATIVE default. toolUse on; vision/structuredOutput only for Gemini.
-  [
-    "qwen/qwen3-coder-30b-a3b-instruct",
-    {
-      supportsVision: false,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 16e4,
-      maxOutputTokens: 8e3
-    }
-  ],
-  [
-    "deepseek/deepseek-v4-flash",
-    {
-      supportsVision: false,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 1048576,
-      maxOutputTokens: 8e3
-    }
-  ],
-  [
-    "deepseek/deepseek-v3.2",
-    {
-      supportsVision: false,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 131072,
-      maxOutputTokens: 8e3
-    }
-  ],
-  [
-    "z-ai/glm-4.7-flash",
-    {
-      supportsVision: false,
-      supportsStructuredOutput: false,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 202752,
-      maxOutputTokens: 8e3
-    }
-  ],
-  [
-    "google/gemini-2.5-flash-lite",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: true,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 1048576,
-      maxOutputTokens: 8e3
-    }
-  ],
-  [
-    "google/gemini-2.5-pro",
-    {
-      supportsVision: true,
-      supportsStructuredOutput: true,
-      supportsToolUse: true,
-      supportsCacheControl: false,
-      maxContextTokens: 1048576,
-      maxOutputTokens: 8e3
-    }
-  ]
-]);
 var ROUTING_PREFIXES = ["openrouter/", "vertex/", "bedrock/"];
+function capsFromCatalog(m) {
+  return {
+    supportsVision: m.modalities?.input?.includes("image") ?? m.attachment ?? false,
+    supportsStructuredOutput: m.structured_output ?? false,
+    supportsToolUse: m.tool_call ?? false,
+    supportsCacheControl: m.cache_control ?? false,
+    maxContextTokens: m.limit?.context ?? CONSERVATIVE_DEFAULTS.maxContextTokens,
+    maxOutputTokens: m.limit?.output ?? CONSERVATIVE_DEFAULTS.maxOutputTokens
+  };
+}
 function resolveModelCapabilities(modelId) {
   const bare = stripVariantSuffix(stripRoutingPrefix(modelId));
-  const exact = EXACT.get(bare);
-  if (exact !== void 0) return exact;
+  const fromIndex = getCatalogModelInfo(bare);
+  if (fromIndex !== void 0) return capsFromCatalog(fromIndex);
   const withVendor = inferVendorPrefix(bare);
   if (withVendor !== bare) {
-    const vendored = EXACT.get(withVendor);
-    if (vendored !== void 0) return vendored;
+    const vendored = getCatalogModelInfo(withVendor);
+    if (vendored !== void 0) return capsFromCatalog(vendored);
   }
   return CONSERVATIVE_DEFAULTS;
 }
@@ -340,6 +281,759 @@ function toModelOption(modelId) {
   };
 }
 
-export { humanizeModelName, parseModelId, resolveModelCapabilities, toModelOption };
+// src/errors.ts
+var TheokitAgentError = class extends Error {
+  name = "TheokitAgentError";
+  isRetryable;
+  code;
+  protoErrorCode;
+  metadata;
+  constructor(message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.isRetryable = options.isRetryable ?? false;
+    if (options.code !== void 0) this.code = options.code;
+    if (options.protoErrorCode !== void 0) this.protoErrorCode = options.protoErrorCode;
+    if (options.metadata !== void 0) this.metadata = options.metadata;
+  }
+};
+var ConfigurationError = class extends TheokitAgentError {
+  name = "ConfigurationError";
+  constructor(message, options = {}) {
+    super(message, { ...options, isRetryable: false });
+  }
+};
+function isTransientError(err) {
+  return err instanceof TheokitAgentError && err.isRetryable === true;
+}
+
+// src/internal/runtime/retry/with-retry.ts
+function defaultSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("withRetry: aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal?.reason instanceof Error ? signal.reason : new Error("withRetry: aborted"));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function resolveRetryOptions(options) {
+  const retries = options?.retries ?? 3;
+  if (!Number.isInteger(retries) || retries < 0) {
+    throw new ConfigurationError(
+      `withRetry: retries must be a non-negative integer, got ${retries}`,
+      { code: "invalid_retry_config" }
+    );
+  }
+  return {
+    retries,
+    isRetryable: options?.isRetryable ?? isTransientError,
+    initialDelayMs: options?.initialDelayMs ?? 100,
+    maxDelayMs: options?.maxDelayMs ?? 3e4,
+    backoffMultiplier: options?.backoffMultiplier ?? 2,
+    rng: options?.rng ?? Math.random,
+    sleep: options?.sleep ?? defaultSleep,
+    signal: options?.signal
+  };
+}
+function backoffMs(cfg, attempt) {
+  const ceiling = Math.min(cfg.maxDelayMs, cfg.initialDelayMs * cfg.backoffMultiplier ** attempt);
+  return Math.floor(cfg.rng() * ceiling);
+}
+async function withRetry(fn, options) {
+  const cfg = resolveRetryOptions(options);
+  let attempt = 0;
+  for (; ; ) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= cfg.retries || !cfg.isRetryable(err)) throw err;
+      await cfg.sleep(backoffMs(cfg, attempt), cfg.signal);
+      attempt += 1;
+    }
+  }
+}
+
+// src/retry.ts
+var Retry = class {
+  constructor() {
+  }
+  static create(fn, options) {
+    return withRetry(fn, options);
+  }
+};
+
+// 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 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`);
+}
+function writeCacheAtomic(path, body) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${randomBytes(6).toString("hex")}`;
+  try {
+    writeFileSync(tmp, body);
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    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 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;
+      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) {
+  const path = cachePathFor(url);
+  let body;
+  try {
+    body = readFileSync(path, "utf-8");
+  } catch {
+    return 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    try {
+      unlinkSync(path);
+    } catch {
+    }
+    process.stderr.write(`[theokit-sdk] WARN: corrupt models-dev cache deleted (${path})
+`);
+    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 = {}) {
+  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;
+  const path = cachePathFor(url);
+  const now = opts.deps?.now ?? (() => Date.now());
+  if (opts.force !== true) {
+    try {
+      const age = now() - statSync(path).mtimeMs;
+      if (age < TTL_MS) {
+        return { source: "cache", models: loadCacheIntoIndex(url) };
+      }
+    } catch {
+    }
+  }
+  const fetchImpl = opts.deps?.fetch ?? fetch;
+  let body;
+  try {
+    const res = await Retry.create(
+      async () => {
+        const r = await fetchImpl(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        return r;
+      },
+      // 2 transient retries with backoff (OpenCode does the same); every error here is worth one more try —
+      // the whole call is already fail-closed at the caller.
+      { retries: 2, isRetryable: () => true, initialDelayMs: 200 }
+    );
+    body = await res.text();
+    JSON.parse(body);
+  } catch (err) {
+    process.stderr.write(
+      `[theokit-sdk] WARN: models-dev refresh failed (${err.message}) \u2014 serving existing data
+`
+    );
+    return { source: "cache", models: loadCacheIntoIndex(url) };
+  }
+  try {
+    writeCacheAtomic(path, body);
+  } catch (err) {
+    process.stderr.write(
+      `[theokit-sdk] WARN: models-dev cache write failed (${err.message})
+`
+    );
+  }
+  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);
+}
+
+export { getModelInfo, humanizeModelName, parseModelId, refreshModelCatalog, resolveModelCapabilities, toModelOption };
 //# sourceMappingURL=models.js.map
 //# sourceMappingURL=models.js.map