@theokit/sdk 4.12.2 → 4.13.0

package/dist/models.js

@@ -1,3 +1,116 @@
+import { statSync, readFileSync, unlinkSync, mkdirSync, writeFileSync, renameSync } 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
+var REGISTRY = /* @__PURE__ */ new Map();
+var ALIASES = /* @__PURE__ */ new Map();
+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));
+var modelInfoIndex = /* @__PURE__ */ new Map();
+function getCatalogModelInfo(key) {
+  ensureModelIndexLoaded();
+  return modelInfoIndex.get(key);
+}
+function patchModelInfo(key, model) {
+  ensureModelIndexLoaded();
+  modelInfoIndex.set(key, model);
+}
+var _modelIndexLoaded = false;
+function ensureModelIndexLoaded() {
+  if (_modelIndexLoaded) return;
+  _modelIndexLoaded = true;
+  const catalog = loadProviderCatalog();
+  for (const entry of Object.values(catalog)) {
+    indexEntryModels(entry);
+  }
+}
+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;
+}
+
 // src/internal/llm/model-capabilities.ts
 var CONSERVATIVE_DEFAULTS = {
   supportsVision: false,
@@ -7,268 +120,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 +210,208 @@ 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/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");
+  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;
+  }
+}
+function patchIndexFromApiJson(raw) {
+  if (typeof raw !== "object" || raw === null) return 0;
+  let patched = 0;
+  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;
+    for (const [modelId, rawModel] of Object.entries(models)) {
+      const parsed = catalogModelSchema.safeParse(rawModel);
+      if (!parsed.success) continue;
+      patchModelInfo(`${profile.name}/${modelId}`, parsed.data);
+      patched++;
+    }
+  }
+  return patched;
+}
+function loadCacheIntoIndex(url = DEFAULT_URL) {
+  const path = cachePathFor(url);
+  let body;
+  try {
+    body = readFileSync(path, "utf-8");
+  } catch {
+    return 0;
+  }
+  try {
+    return patchIndexFromApiJson(JSON.parse(body));
+  } catch {
+    try {
+      unlinkSync(path);
+    } catch {
+    }
+    process.stderr.write(`[theokit-sdk] WARN: corrupt models-dev cache deleted (${path})
+`);
+    return 0;
+  }
+}
+async function refreshModelCatalog(opts = {}) {
+  if (process.env.THEOKIT_DISABLE_MODELS_FETCH !== void 0) {
+    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})
+`
+    );
+  }
+  return { source: "network", models: patchIndexFromApiJson(JSON.parse(body)) };
+}
+function getModelInfo(modelId) {
+  return getCatalogModelInfo(modelId);
+}
+
+export { getModelInfo, humanizeModelName, parseModelId, refreshModelCatalog, resolveModelCapabilities, toModelOption };
 //# sourceMappingURL=models.js.map
 //# sourceMappingURL=models.js.map