@visual-z/xeno 0.1.4 → 0.2.0

package/src/runtime/model-config.ts

@@ -0,0 +1,232 @@
+/** Config parsing owns provider wire vocabulary; identity/filter policy lives in core. */
+import { mergeCatalogs, modelEnabled } from "../core/catalog-merge.ts";
+import { modelKey } from "../core/session-position.ts";
+import { THINKING_LEVELS } from "../core/thinking.ts";
+import { SOURCE_PROVIDERS } from "./model-data.ts";
+import { DEFAULT_COMPAT, type ModelSpec, type Effort } from "./model.ts";
+import { isProviderApi, SDK_APIS } from "./provider-protocols.ts";
+import { providerAccess, setProviderAccess, type ProviderAccess } from "./provider-access.ts";
+
+function object(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function own(value: Record<string, unknown>, key: string): boolean { return Object.hasOwn(value, key); }
+function positive(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value > 0; }
+function nonnegative(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+function error(path: string, message: string): never { throw new Error(`${path}: ${message}`); }
+function strings(value: unknown, path: string): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || !value.every(x => typeof x === "string")) error(path, "must be an array of strings");
+  return value as string[];
+}
+function stringMap(value: unknown, path: string, nullable = false): Record<string, string | null> | undefined {
+  if (value === undefined) return undefined;
+  if (!object(value) || !Object.values(value).every(x => typeof x === "string" || (nullable && x === null))) error(path, "must contain string values" + (nullable ? " or null" : ""));
+  return Object.fromEntries(Object.entries(value as Record<string, string | null>).map(([key, v]) => [key, typeof v === "string" ? configValue(v) : v]));
+}
+/** OpenCode's env reference and Pi's interpolation share one resolver. No implicit uppercase lookup. */
+function configValue(value: string): string { return value.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, "$${$1}"); }
+const RESERVED_BODY = ["model", "modelId", "messages", "system", "systemInstruction", "system_instruction", "instructions", "input", "contents", "context", "tools", "toolConfig", "stream", "previous_response_id", "store", "conversation", "conversation_id", "sessionId", "session_id", "httpOptions", "http_options", "headers", "apiKey", "authToken", "baseUrl", "baseURL", "fetch", "abortSignal", "signal", "onPayload", "onResponse"];
+const REQUEST_OPTIONS = ["temperature", "samplingParams", "cacheRetention", "timeoutMs", "maxRetryDelayMs", "metadata"];
+
+function payloadPatch(value: unknown, path: string): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined;
+  if (!object(value)) error(path, "must be an object");
+  for (const [key, child] of Object.entries(value)) {
+    if (RESERVED_BODY.includes(key)) error(`${path}.${key}`, "is owned by the log projection and request adapter");
+    if ((key === "config" || key === "options") && !object(child)) error(`${path}.${key}`, "must be an object");
+    if (object(child)) payloadPatch(child, `${path}.${key}`);
+  }
+  return value;
+}
+
+function accessPatch(raw: Record<string, unknown>, path: string, parent: ProviderAccess = {}): ProviderAccess {
+  if (raw["options"] !== undefined && !object(raw["options"])) error(`${path}.options`, "must be an object");
+  const options = object(raw["options"]) ? raw["options"] : {};
+  const apiKey = own(raw, "apiKey") ? raw["apiKey"] : options["apiKey"];
+  if (apiKey !== undefined && (typeof apiKey !== "string" || !apiKey.length)) error(`${path}.apiKey`, "must be a non-empty string; use auth: false for a keyless endpoint");
+  const auth = raw["auth"];
+  if (auth !== undefined && auth !== false && auth !== "ambient") error(`${path}.auth`, "must be false or ambient");
+  const authHeader = raw["authHeader"];
+  if (authHeader !== undefined && typeof authHeader !== "boolean" && (typeof authHeader !== "string" || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(authHeader))) error(`${path}.authHeader`, "must be a boolean or header name");
+  const headers = stringMap(raw["headers"] ?? options["headers"] ?? raw["defaultHeaders"], `${path}.headers`, true);
+  if (headers && Object.keys(headers).some(key => !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(key))) error(`${path}.headers`, "contains an invalid header name");
+  const env = stringMap(raw["env"], `${path}.env`) as Record<string, string> | undefined;
+  if (env && Object.keys(env).some(key => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))) error(`${path}.env`, "contains an invalid variable name");
+  const body = payloadPatch(raw["body"] ?? raw["extraBody"] ?? options["body"] ?? options["extraBody"], `${path}.body`);
+  const requestOptions = Object.fromEntries(Object.entries(options).filter(([key]) => !["apiKey", "baseURL", "baseUrl", "headers", "body", "extraBody"].includes(key)));
+  for (const key of Object.keys(requestOptions)) {
+    if (!REQUEST_OPTIONS.includes(key)) error(`${path}.options.${key}`, "is not a configurable request option; use env for native cloud settings or body for API parameters");
+  }
+  payloadPatch(requestOptions["samplingParams"], `${path}.options.samplingParams`);
+  for (const key of ["temperature", "timeoutMs", "maxRetryDelayMs"]) if (requestOptions[key] !== undefined && !nonnegative(requestOptions[key])) error(`${path}.options.${key}`, "must be a finite nonnegative number");
+  if (requestOptions["cacheRetention"] !== undefined && !["none", "short", "long"].includes(String(requestOptions["cacheRetention"]))) error(`${path}.options.cacheRetention`, "must be none, short or long");
+  stringMap(requestOptions["metadata"], `${path}.options.metadata`);
+  return { ...parent,
+    ...(typeof apiKey === "string" ? { apiKey: configValue(apiKey) } : {}),
+    ...(auth === false || auth === "ambient" ? { auth } : {}),
+    ...(typeof authHeader === "boolean" || typeof authHeader === "string" ? { authHeader } : {}),
+    ...(headers ? { headers: { ...parent.headers, ...headers } } : {}),
+    ...(env ? { env: { ...parent.env, ...env } } : {}),
+    ...(object(body) ? { body: { ...parent.body, ...body } } : {}),
+    ...(Object.keys(requestOptions).length ? { options: { ...parent.options, ...requestOptions } } : {}) };
+}
+
+function modelPatch(raw: Record<string, unknown>, base: ModelSpec | undefined, provider: string, id: string, path: string, partial: boolean): ModelSpec {
+  const options = object(raw["options"]) ? raw["options"] : {};
+  const endpoint = raw["baseUrl"] ?? raw["baseURL"] ?? options["baseURL"] ?? options["baseUrl"];
+  if (raw["npm"] !== undefined && (typeof raw["npm"] !== "string" || !SDK_APIS[raw["npm"]]) && raw["api"] === undefined) error(`${path}.npm`, "unsupported SDK; select a supported api explicitly");
+  const api = raw["api"] ?? (typeof raw["npm"] === "string" ? SDK_APIS[raw["npm"]] : undefined) ?? base?.api ?? SOURCE_PROVIDERS[provider]?.api;
+  if (!isProviderApi(api)) error(`${path}.api`, "unknown or missing protocol");
+  if (endpoint !== undefined && typeof endpoint !== "string") error(`${path}.baseUrl`, "must be a string");
+  const spec: ModelSpec = { ...(base ?? {}), provider, id, name: base?.name ?? id, api,
+    reasoning: base?.reasoning ?? false, ...(partial ? {} : { driver: "pi" }),
+    ...(typeof endpoint === "string" ? { baseUrl: configValue(endpoint) } : base?.baseUrl !== undefined ? {} : SOURCE_PROVIDERS[provider]?.baseUrl ? { baseUrl: SOURCE_PROVIDERS[provider].baseUrl } : {}) };
+  if (raw["api"] !== undefined && raw["api"] !== base?.api) { delete spec.compat; delete spec.nativeCompat; delete spec.thinkingLevelMap; }
+  if (typeof raw["name"] === "string" && raw["name"].length) spec.name = raw["name"];
+  if (own(raw, "reasoning")) { if (typeof raw["reasoning"] !== "boolean") error(`${path}.reasoning`, "must be boolean"); spec.reasoning = raw["reasoning"]; }
+  const limit = object(raw["limit"]) ? raw["limit"] : {};
+  for (const [key, value] of [["contextWindow", raw["contextWindow"] ?? limit["context"]], ["maxTokens", raw["maxTokens"] ?? limit["output"]]] as const) {
+    if (value !== undefined) { if (!positive(value)) error(`${path}.${key}`, "must be a finite positive number"); spec[key] = value; }
+  }
+  if (own(raw, "input")) {
+    if (!Array.isArray(raw["input"]) || !raw["input"].every(x => x === "text" || x === "image")) error(`${path}.input`, "must contain only text or image");
+    spec.input = raw["input"] as ("text" | "image")[];
+  }
+  if (raw["credentialEnv"] !== undefined) {
+    const names = strings(raw["credentialEnv"], `${path}.credentialEnv`)!;
+    if (names.some(name => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))) error(`${path}.credentialEnv`, "must contain variable names");
+    spec.credentialEnv = names;
+  }
+  const price = raw["price"] ?? raw["cost"];
+  if (price !== undefined) {
+    if (!object(price) || !nonnegative(price["input"]) || !nonnegative(price["output"]) || ["cacheRead", "cacheWrite"].some(k => own(price, k) && !nonnegative(price[k]))) error(`${path}.price`, "requires finite nonnegative input/output and optional cache prices");
+    spec.price = { input: price["input"], output: price["output"],
+      ...(nonnegative(price["cacheRead"]) ? { cacheRead: price["cacheRead"] } : {}),
+      ...(nonnegative(price["cacheWrite"]) ? { cacheWrite: price["cacheWrite"] } : {}) };
+  }
+  if (raw["cache"] !== undefined) { if (raw["cache"] !== "explicit" && raw["cache"] !== "automatic") error(`${path}.cache`, "must be explicit or automatic"); spec.cache = raw["cache"]; }
+  if (raw["rates"] !== undefined) {
+    const rates = raw["rates"];
+    if (!object(rates) || !nonnegative(rates["read"]) || !nonnegative(rates["write"])) error(`${path}.rates`, "requires finite nonnegative read/write");
+    spec.rates = { read: rates["read"], write: rates["write"] };
+  }
+  if (raw["thinkingLevelMap"] !== undefined) {
+    const map = raw["thinkingLevelMap"];
+    if (!object(map) || !Object.entries(map).every(([key, value]) => (THINKING_LEVELS as readonly string[]).includes(key) && (value === null || typeof value === "string"))) error(`${path}.thinkingLevelMap`, "requires supported effort keys and string/null values");
+    spec.thinkingLevelMap = map as Partial<Record<Effort, string | null>>;
+  }
+  for (const key of ["compat", "nativeCompat", "samplingParams"] as const) {
+    const value = raw[key];
+    if (value !== undefined) {
+      if (!object(value)) error(`${path}.${key}`, "must be an object");
+      if (key === "samplingParams") payloadPatch(value, `${path}.${key}`);
+      else for (const [field, flag] of Object.entries(value)) {
+        if (/^(supports|requires)/.test(field) && typeof flag !== "boolean") error(`${path}.${key}.${field}`, "must be boolean");
+        if (field === "maxTokensField" && flag !== "max_tokens" && flag !== "max_completion_tokens") error(`${path}.${key}.${field}`, "must be max_tokens or max_completion_tokens");
+      }
+      if (key === "compat") {
+        spec.nativeCompat = { ...spec.nativeCompat, ...value };
+        spec.compat = { ...DEFAULT_COMPAT, ...base?.compat, ...value } as NonNullable<ModelSpec["compat"]>;
+      } else spec[key] = { ...spec[key], ...value };
+    }
+  }
+  if (raw["driver"] === "pi") spec.driver = "pi";
+  if (typeof raw["wireId"] === "string") spec.wireId = raw["wireId"];
+  return spec;
+}
+
+export function parseModelConfiguration(json: unknown, builtin: readonly ModelSpec[] = []): { models: ModelSpec[]; errors: string[] } {
+  let models = [...builtin];
+  const errors: string[] = [];
+  const report = (err: unknown) => errors.push(err instanceof Error ? err.message : "invalid model configuration");
+  if (!Array.isArray(json) && !object(json)) return { models, errors: ["user catalog must be an array or an object with models/providers/provider"] };
+  const root = object(json) ? json : {};
+  const rows = Array.isArray(json) ? json : root["models"];
+  if (rows !== undefined && !Array.isArray(rows)) errors.push("user catalog .models is not an array");
+  const indexed = new Map(models.map(model => [modelKey(model), model]));
+  if (Array.isArray(rows)) for (const [i, row] of rows.entries()) {
+    const path = `models[${i}]` + (object(row) && typeof row["id"] === "string" ? ` (${row["id"]})` : "");
+    try {
+      if (!object(row)) error(path, "must be an object");
+      if (typeof row["id"] !== "string" || !row["id"].length) error(path, "has no id");
+      if (typeof row["provider"] !== "string" || !row["provider"].length) error(path, "has no provider");
+      const id = row["id"], provider = row["provider"];
+      if (row["disabled"] === true || row["enabled"] === false) { indexed.delete(modelKey({ provider, id })); continue; }
+      const previous = indexed.get(modelKey({ provider, id }));
+      const model = modelPatch(row, previous, provider, id, path, true);
+      const access = accessPatch(row, path, previous ? providerAccess(previous) : {});
+      if (Object.keys(access).length) { model.driver = "pi"; setProviderAccess(model, access); }
+      indexed.set(modelKey(model), model);
+    } catch (err) {
+      report(err);
+      if (object(row) && typeof row["id"] === "string" && typeof row["provider"] === "string") {
+        const key = modelKey({ id: row["id"], provider: row["provider"] });
+        const previous = indexed.get(key);
+        if (previous) { const copy = { ...previous }; setProviderAccess(copy, { invalid: `${path}: invalid model configuration` }); indexed.set(key, copy); }
+      }
+    }
+  }
+  models = [...indexed.values()];
+  for (const groupKey of ["providers", "provider"] as const) {
+    const providers = root[groupKey];
+    if (providers === undefined) continue;
+    if (!object(providers)) { errors.push(`${groupKey}: must be an object`); continue; }
+    for (const [provider, config] of Object.entries(providers)) {
+      const path = `${groupKey}.${provider}`;
+      try {
+        if (!object(config)) error(path, "must be an object");
+        if (config["disabled"] === true || config["enabled"] === false) { models = models.filter(model => model.provider !== provider); continue; }
+        const access = accessPatch(config, path);
+        const allow = strings(config["allowlist"] ?? config["whitelist"], `${path}.allowlist`);
+        const deny = strings(config["denylist"] ?? config["blacklist"], `${path}.denylist`);
+        const peers: ModelSpec[] = [];
+        const defaults = { ...config }; delete defaults["name"];
+        for (const previous of models.filter(model => model.provider === provider)) {
+          const next = modelPatch(defaults, previous, provider, previous.id, path, false);
+          setProviderAccess(next, accessPatch(config, path, providerAccess(previous))); peers.push(next);
+        }
+        const definitions = config["models"];
+        if (definitions !== undefined && !Array.isArray(definitions) && !object(definitions)) error(`${path}.models`, "must be an array or object");
+        const additions: [string | undefined, unknown][] = Array.isArray(definitions) ? definitions.map(row => [undefined, row]) : object(definitions) ? Object.entries(definitions) : [];
+        const patches = config["modelOverrides"];
+        if (patches !== undefined && !object(patches)) error(`${path}.modelOverrides`, "must be an object");
+        const entries = [...additions.map(([id, row]) => ({ id, row, override: false })), ...Object.entries(object(patches) ? patches : {}).map(([id, row]) => ({ id, row, override: true }))];
+        for (const [index, entry] of entries.entries()) {
+          const label = `${path}.${entry.override ? "modelOverrides" : "models"}.${entry.id ?? index}`;
+          try {
+            if (!object(entry.row)) error(label, "must be an object");
+            const id = entry.id ?? entry.row["id"];
+            if (typeof id !== "string" || !id.length) error(label, "has no id");
+            if (entry.row["disabled"] === true || entry.row["enabled"] === false) { const at = peers.findIndex(model => model.id === id); if (at >= 0) peers.splice(at, 1); continue; }
+            const base = peers.find(model => model.id === id);
+            if (entry.override && !base) error(label, "cannot override an unknown model");
+            const inherited = base ?? modelPatch(defaults, undefined, provider, id, path, false);
+            const model = modelPatch(entry.row, inherited, provider, id, label, false);
+            if (entry.id && typeof entry.row["id"] === "string" && entry.row["id"] !== id) model.wireId = entry.row["id"];
+            setProviderAccess(model, accessPatch(entry.row, label, base ? providerAccess(base) : access));
+            const at = peers.findIndex(candidate => candidate.id === id);
+            if (at < 0) peers.push(model); else peers[at] = model;
+          } catch (err) {
+            report(err);
+            const id = entry.id ?? (object(entry.row) ? entry.row["id"] : undefined);
+            const at = peers.findIndex(model => model.id === id);
+            if (at >= 0) { const copy = { ...peers[at]! }; setProviderAccess(copy, { invalid: `${label}: invalid model configuration` }); peers[at] = copy; }
+          }
+        }
+        models = mergeCatalogs(models.filter(model => model.provider !== provider), peers.filter(model => modelEnabled(model.id, allow, deny)));
+      } catch (err) {
+        report(err);
+        // An invalid explicit provider config must not silently use a different credential/endpoint.
+        models = models.map(model => {
+          if (model.provider !== provider) return model;
+          const copy = { ...model }; setProviderAccess(copy, { invalid: `${path}: invalid provider configuration` }); return copy;
+        });
+      }
+    }
+  }
+  try {
+    const enabled = strings(root["enabled_providers"], "enabled_providers");
+    const disabled = strings(root["disabled_providers"], "disabled_providers");
+    models = models.filter(model => modelEnabled(model.provider, enabled, disabled));
+  } catch (err) { report(err); }
+  return { models, errors };
+}

package/src/runtime/model-data.LICENSE

@@ -0,0 +1,27 @@
+The generated model catalog contains data adapted from:
+
+Pi (https://github.com/earendil-works/pi)
+Copyright (c) 2025 Mario Zechner
+
+Models.dev (https://github.com/anomalyco/models.dev)
+Copyright (c) 2025 models.dev
+
+Both sources are distributed under the following MIT License:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.