@fonlan/dsh-model-parameters 0.1.0

package/lib/index.js

@@ -0,0 +1,637 @@
+import z from "@deepseek-ai/schemastery";
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+//#region src/shared/config.ts
+/**
+* Plugin configuration and shared constants for @fonlan/dsh-model-parameters.
+*
+* The plugin owns the `model-parameters` settings namespace (stored in
+* settings.yaml) and OBSERVES the `llm-pi-ai` namespace: whenever provider
+* models are written there with missing capability fields (which is the norm
+* for a freshly synced gateway), it patches the missing fields from the cached
+* models.dev catalog.
+*/
+/** This plugin's own settings namespace. */
+const PLUGIN_NS = "model-parameters";
+/** The namespace whose models this plugin completes: pi-ai provider profiles. */
+const TARGET_NS = "llm-pi-ai";
+/** models.dev catalog endpoint. */
+const CATALOG_URL = "https://models.dev/api.json";
+/** Default provider ids treated as first-party vendors (tie-break for id collisions). */
+const DEFAULT_OFFICIAL_PROVIDERS = [
+	"deepseek",
+	"openai",
+	"anthropic",
+	"google",
+	"xai",
+	"moonshotai",
+	"zai",
+	"zhipuai",
+	"minimax",
+	"stepfun",
+	"xiaomi",
+	"meta",
+	"cohere",
+	"nvidia",
+	"alibaba"
+];
+/**
+* dsh pi-ai only accepts these request modalities; models.dev may also list
+* pdf/audio/video, which must be filtered out before writing (schema rejects
+* unknown modality values).
+*/
+const ACCEPTED_INPUT_MODALITIES = ["text", "image"];
+/**
+* Valid `reasoningEfforts` keys in pi-ai, in escalation order. models.dev
+* effort values like `default`/`none`/empty are filtered out; only values in
+* this set are written.
+*/
+const REASONING_LEVELS = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+];
+const Config = z.object({
+	enabled: z.boolean().default(true),
+	ttlDays: z.number().min(1).max(90).default(7),
+	fillName: z.boolean().default(true),
+	fillContext: z.boolean().default(true),
+	fillMaxTokens: z.boolean().default(true),
+	fillReasoning: z.boolean().default(true),
+	fillInput: z.boolean().default(true),
+	providerMap: z.dict(z.string()).default({}),
+	officialProviders: z.array(z.string()).default([...DEFAULT_OFFICIAL_PROVIDERS])
+});
+const DEFAULT_CONFIG = {
+	enabled: true,
+	ttlDays: 7,
+	fillName: true,
+	fillContext: true,
+	fillMaxTokens: true,
+	fillReasoning: true,
+	fillInput: true,
+	providerMap: {},
+	officialProviders: [...DEFAULT_OFFICIAL_PROVIDERS]
+};
+//#endregion
+//#region src/server/catalog.ts
+/**
+* models.dev catalog: fetch, disk cache, lazy TTL refresh, and id matching.
+*
+* The catalog is flattened into a list of entries keyed by provider, then
+* indexed by the last path segment of the model id (case-insensitive) so a
+* synced bare id like `qwen3.7-max` can resolve `Qwen/Qwen3.7-Max` wherever
+* models.dev carries it.
+*
+* Collisions are real: the same bare id appears under dozens of providers with
+* different limits. Resolution is deterministic and provider-aware:
+*   1. the models.dev provider mapped for the dsh provider (providerMap
+*      override, then same provider id);
+*   2. an exact full-id match (the dsh model id already carries a vendor/);
+*   3. first-party vendor list position (officialProviders);
+*   4. entry completeness (both context and output limits known);
+*   5. alphabetical provider id (stable last resort).
+*/
+const DAY_MS = 864e5;
+const FETCH_TIMEOUT_MS = 2e4;
+function strippedId(id) {
+	return (id.split("/").pop() ?? id).toLowerCase();
+}
+function isOfficial(provider, official) {
+	const index = official.indexOf(provider);
+	return index === -1 ? official.length : index;
+}
+function completeness(entry) {
+	return entry.context !== void 0 && entry.output !== void 0 ? 0 : 1;
+}
+var CatalogManager = class {
+	logger;
+	snapshot = {
+		entries: [],
+		providers: 0,
+		fetchedAt: 0
+	};
+	loaded = false;
+	inflight = null;
+	dir;
+	cachePath;
+	constructor(logger, dataDir) {
+		this.logger = logger;
+		this.dir = dataDir ?? join(homedir(), ".dsh", "model-parameters");
+		this.cachePath = join(this.dir, "catalog.json");
+	}
+	/** The current snapshot (empty until the first load/fetch completes). */
+	snapshotOf() {
+		return this.snapshot;
+	}
+	/**
+	* Load the disk cache once, then fetch when stale (or `force`). A failed
+	* fetch keeps the last good cache; with no cache at all the snapshot stays
+	* empty and the caller simply fills nothing. Concurrent callers share one
+	* in-flight refresh.
+	* @returns true when the snapshot may have changed.
+	*/
+	async ensureFresh(config, force = false) {
+		if (!this.loaded) {
+			await this.loadCache();
+			this.loaded = true;
+		}
+		const stale = Date.now() - this.snapshot.fetchedAt >= config.ttlDays * DAY_MS;
+		if (!force && !stale) return false;
+		if (this.inflight !== null) {
+			await this.inflight;
+			return true;
+		}
+		this.inflight = this.fetchAndPersist().catch((error) => {
+			this.logger.warn(`model-parameters: catalog fetch failed (${error instanceof Error ? error.message : String(error)}); using cached copy`);
+		}).finally(() => {
+			this.inflight = null;
+		});
+		await this.inflight;
+		return true;
+	}
+	/** Force a fetch now; never throws (falls back to cache or keeps empty). */
+	async refresh(ttlDays) {
+		return this.ensureFresh({ ttlDays }, true);
+	}
+	/**
+	* Resolve one dsh model id to the best catalog entry for its provider.
+	* @param modelId - the model id stored in the dsh provider profile.
+	* @param dshProvider - the dsh provider route id.
+	* @param config - plugin config (providerMap + officialProviders).
+	*/
+	resolve(modelId, dshProvider, config) {
+		const mapped = config.providerMap[dshProvider];
+		const candidates = this.candidatesFor(modelId);
+		if (candidates.length === 0) return void 0;
+		const official = config.officialProviders;
+		const score = (entry) => {
+			return [
+				entry.provider === mapped || entry.provider === dshProvider ? 0 : 1,
+				modelId.includes("/") && strippedId(entry.id) === modelId.toLowerCase() ? 0 : 1,
+				isOfficial(entry.provider, official),
+				completeness(entry)
+			];
+		};
+		candidates.sort((a, b) => {
+			const sa = score(a);
+			const sb = score(b);
+			for (let i = 0; i < sa.length; i++) if (sa[i] !== sb[i]) return sa[i] - sb[i];
+			if (a.provider !== b.provider) return a.provider < b.provider ? -1 : 1;
+			return a.id < b.id ? -1 : 1;
+		});
+		return candidates[0];
+	}
+	/**
+	* All entries whose stripped id matches, plus any whose full id matches
+	* exactly (a dsh model id may already carry a vendor/ prefix that models.dev
+	* keys verbatim).
+	*/
+	candidatesFor(modelId) {
+		const stripped = strippedId(modelId);
+		const out = [];
+		for (const entry of this.snapshot.entries) if (strippedId(entry.id) === stripped) out.push(entry);
+		else if (modelId.includes("/") && entry.id.toLowerCase() === modelId.toLowerCase()) out.push(entry);
+		return out;
+	}
+	async loadCache() {
+		try {
+			const raw = await readFile(this.cachePath, "utf8");
+			const doc = JSON.parse(raw);
+			if (typeof doc.fetchedAt !== "number" || typeof doc.body !== "object" || doc.body === null) {
+				this.logger.warn("model-parameters: catalog cache is malformed; ignoring");
+				return;
+			}
+			this.snapshot = this.buildSnapshot(doc.body, doc.fetchedAt);
+			this.logger.info(`model-parameters: loaded ${this.snapshot.entries.length} catalog entries from cache (fetched ${new Date(doc.fetchedAt).toISOString()})`);
+		} catch (error) {
+			if (error.code !== "ENOENT") this.logger.warn(`model-parameters: catalog cache read failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	async fetchAndPersist() {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+		let response;
+		try {
+			response = await fetch(CATALOG_URL, {
+				signal: controller.signal,
+				headers: { accept: "application/json" }
+			});
+		} finally {
+			clearTimeout(timer);
+		}
+		if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+		const body = await response.json();
+		const fetchedAt = Date.now();
+		this.snapshot = this.buildSnapshot(body, fetchedAt);
+		await mkdir(this.dir, { recursive: true });
+		const doc = {
+			fetchedAt,
+			body
+		};
+		await writeFile(this.cachePath, JSON.stringify(doc), "utf8");
+		this.logger.info(`model-parameters: catalog refreshed from models.dev (${this.snapshot.providers} providers, ${this.snapshot.entries.length} models)`);
+	}
+	buildSnapshot(body, fetchedAt) {
+		const entries = [];
+		for (const [provider, raw] of Object.entries(body)) {
+			if (typeof raw !== "object" || raw === null) continue;
+			const models = raw.models;
+			if (typeof models !== "object" || models === null) continue;
+			for (const [id, rawModel] of Object.entries(models)) {
+				if (typeof rawModel !== "object" || rawModel === null) continue;
+				const model = rawModel;
+				const limit = typeof model.limit === "object" && model.limit !== null ? model.limit : {};
+				const entry = {
+					provider,
+					id
+				};
+				if (typeof model.name === "string" && model.name.length > 0) entry.name = model.name;
+				if (typeof limit.context === "number") entry.context = limit.context;
+				if (typeof limit.output === "number") entry.output = limit.output;
+				if (typeof model.reasoning === "boolean") entry.reasoning = model.reasoning;
+				const effortValues = [];
+				if (Array.isArray(model.reasoning_options)) {
+					for (const option of model.reasoning_options) if (typeof option === "object" && option !== null && option.type === "effort") {
+						const values = option.values;
+						if (Array.isArray(values)) {
+							for (const value of values) if (typeof value === "string") effortValues.push(value);
+						}
+					}
+				}
+				if (effortValues.length > 0) entry.effortValues = effortValues;
+				const modalities = typeof model.modalities === "object" && model.modalities !== null ? model.modalities : {};
+				if (Array.isArray(modalities.input)) {
+					const input = modalities.input.filter((value) => typeof value === "string");
+					if (input.length > 0) entry.input = input;
+				}
+				entries.push(entry);
+			}
+		}
+		return {
+			entries,
+			providers: Object.keys(body).length,
+			fetchedAt
+		};
+	}
+};
+/**
+* Build the dsh `reasoningEfforts` identity dict from models.dev effort
+* values, filtered to the levels dsh accepts. Returns undefined when nothing
+* valid is offered (or the model does not state reasoning).
+*/
+function identityReasoningEfforts(entry) {
+	if (entry.reasoning === false) return void 0;
+	if (entry.effortValues === void 0 || entry.effortValues.length === 0) return void 0;
+	const efforts = {};
+	for (const value of entry.effortValues) if (REASONING_LEVELS.includes(value)) efforts[value] = value;
+	return Object.keys(efforts).length > 0 ? efforts : void 0;
+}
+/**
+* The dsh-writable input modality list for one entry: models.dev values
+* intersected with what pi-ai accepts. Returns undefined when nothing is
+* accepted (writing an empty list is semantically "keep defaults", so absent
+* is the honest fill).
+*/
+function acceptedInputModalities(entry) {
+	if (entry.input === void 0 || entry.input.length === 0) return void 0;
+	const accepted = entry.input.filter((value) => ACCEPTED_INPUT_MODALITIES.includes(value));
+	return accepted.length > 0 ? accepted : void 0;
+}
+//#endregion
+//#region src/server/service.ts
+const TARGET = settingsNamespace(TARGET_NS);
+const OWN = settingsNamespace(PLUGIN_NS);
+var ModelParametersService = class {
+	ctx;
+	/**
+	* The settings service value captured from the inject callback. The plugin
+	* itself declares `inject: []` (settings is optional — headless profiles
+	* have no settings service), so `this.ctx.settings` is never resolvable:
+	* the context proxy only walks ancestor fibers, and the provider lives on
+	* a sibling fiber. The injected child ctx itself is only valid while its
+	* fiber is active — the provider can be reloaded (and every dependent
+	* fiber torn down) while an async reconcile is in flight — so all reads
+	* and writes go through the captured service value, which is a plain
+	* object and never walks the fiber chain.
+	*/
+	settings;
+	scope;
+	lastReport = null;
+	catalog;
+	reconciling = null;
+	constructor(ctx) {
+		this.ctx = ctx;
+		this.catalog = new CatalogManager(ctx.logger);
+	}
+	start() {
+		this.ctx.inject(["settings"], (sctx) => {
+			this.settings = sctx.settings;
+			this.scope = this.settings.register(OWN, Config);
+			this.reconcile();
+		});
+		this.ctx.on("settings/updated", (ns) => {
+			if (ns !== TARGET) return;
+			this.reconcile();
+		});
+	}
+	stop() {
+		this.scope = void 0;
+		this.settings = void 0;
+	}
+	config() {
+		if (this.scope !== void 0) try {
+			return this.scope.get();
+		} catch {}
+		return {
+			...DEFAULT_CONFIG,
+			providerMap: {},
+			officialProviders: [...DEFAULT_CONFIG.officialProviders]
+		};
+	}
+	catalogSnapshot() {
+		return this.catalog.snapshotOf();
+	}
+	report() {
+		return this.lastReport;
+	}
+	/** Force a catalog refresh, then reconcile and report. */
+	async refreshAndReconcile() {
+		await this.catalog.refresh(this.config().ttlDays);
+		await this.reconcile();
+	}
+	/** Update plugin config toggles from the settings page. */
+	async updateConfig(patch) {
+		if (this.scope === void 0) throw new Error("model-parameters: settings service is not available in this profile");
+		const current = this.config();
+		await this.scope.update({
+			...current,
+			...patch
+		});
+	}
+	/**
+	* Fill missing fields on every provider model from the catalog. Serialized:
+	* concurrent triggers (event + backfill) coalesce into one run. Fill-only
+	* guarantees termination: after a write the fields are present, so the next
+	* event produces no ops.
+	*/
+	async reconcile() {
+		if (this.reconciling !== null) return this.reconciling;
+		this.reconciling = this.runReconcile().finally(() => {
+			this.reconciling = null;
+		});
+		return this.reconciling;
+	}
+	async runReconcile() {
+		const config = this.config();
+		if (!config.enabled) return;
+		const settings = this.settings;
+		if (settings === void 0) return;
+		try {
+			await this.catalog.ensureFresh(config);
+		} catch (error) {
+			this.ctx.logger.warn(`model-parameters: reconcile skipped, catalog unavailable: ${error instanceof Error ? error.message : String(error)}`);
+			return;
+		}
+		const section = settings.describe({ redactSecrets: false }).find((candidate) => candidate.ns === TARGET)?.user;
+		if (section === void 0 || typeof section !== "object" || section.providers === void 0) return;
+		const ops = [];
+		const report = {
+			at: Date.now(),
+			filled: 0,
+			touched: 0,
+			unmatched: []
+		};
+		for (const [providerId, profile] of Object.entries(section.providers)) {
+			if (typeof profile !== "object" || profile === null) continue;
+			const models = profile.models;
+			if (!Array.isArray(models) || models.length === 0) continue;
+			const nextModels = [];
+			let changed = false;
+			for (const model of models) {
+				const next = this.fillModel(model, providerId, config, report);
+				if (next !== model) changed = true;
+				nextModels.push(next);
+			}
+			if (changed) {
+				ops.push({
+					op: "set",
+					path: [
+						"providers",
+						providerId,
+						"models"
+					],
+					value: nextModels
+				});
+				report.touched++;
+			}
+		}
+		if (ops.length > 0) try {
+			await settings.mutate(TARGET, ops);
+		} catch (error) {
+			this.ctx.logger.warn(`model-parameters: reconcile persist failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		this.lastReport = report;
+		if (report.filled > 0 || report.unmatched.length > 0) this.ctx.logger.info(`model-parameters: reconcile filled ${report.filled} fields across ${report.touched} providers; ${report.unmatched.length} unmatched (${report.unmatched.slice(0, 5).join(", ")}${report.unmatched.length > 5 ? ", …" : ""})`);
+	}
+	/** Fill one model entry (fill-only), returning the same object when untouched. */
+	fillModel(model, providerId, config, report) {
+		const entry = this.catalog.resolve(model.id, providerId, config);
+		if (entry === void 0) {
+			report.unmatched.push(`${providerId}/${model.id}`);
+			return model;
+		}
+		const next = { ...model };
+		let filledFields = 0;
+		if (config.fillName && next.name === void 0) {
+			const name = catalogName(entry);
+			if (name !== void 0) {
+				next.name = name;
+				filledFields++;
+			}
+		}
+		if (config.fillContext && next.contextWindow === void 0 && entry.context !== void 0 && entry.context > 0) {
+			next.contextWindow = entry.context;
+			filledFields++;
+		}
+		if (config.fillMaxTokens && next.maxTokens === void 0 && entry.output !== void 0 && entry.output > 0) {
+			next.maxTokens = entry.output;
+			filledFields++;
+		}
+		if (config.fillReasoning && next.reasoningEfforts === void 0) {
+			const efforts = identityReasoningEfforts(entry);
+			if (efforts !== void 0) {
+				next.reasoningEfforts = efforts;
+				filledFields++;
+			}
+		}
+		if (config.fillInput && next.input === void 0) {
+			const input = acceptedInputModalities(entry);
+			if (input !== void 0) {
+				next.input = input;
+				filledFields++;
+			}
+		}
+		if (filledFields === 0) return model;
+		report.filled += filledFields;
+		return next;
+	}
+};
+function catalogName(entry) {
+	return entry.name !== void 0 && entry.name.length > 0 ? entry.name : void 0;
+}
+//#endregion
+//#region src/server/rpc.ts
+const API_PREFIX = "/plugins/@fonlan/dsh-model-parameters/api";
+function header(headers, name) {
+	const value = headers[name];
+	return typeof value === "string" ? value : void 0;
+}
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	const parts = hostname.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255);
+}
+function isTrustedApiRequest(req, trustedHosts) {
+	const host = header(req.headers, "host");
+	if (host === void 0) return false;
+	let hostUrl;
+	try {
+		hostUrl = new URL(`http://${host}`);
+	} catch {
+		return false;
+	}
+	if (!isLoopbackHostname(hostUrl.hostname) && !trustedHosts.includes(hostUrl.host) && !trustedHosts.includes(hostUrl.hostname)) return false;
+	if (header(req.headers, "sec-fetch-site") === "cross-site") return false;
+	const origin = header(req.headers, "origin");
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+function trustedHostsOf(ctx) {
+	for (const entry of ctx.get("loader")?.entries?.() ?? []) if (entry.options?.name === "connection") return entry.options.config?.trustedHosts ?? [];
+	return [];
+}
+function writeJson(res, body) {
+	res.writeHead(200, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store"
+	});
+	res.end(JSON.stringify(body));
+}
+function writeError(res, code, message, status = 400) {
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-store"
+	});
+	res.end(JSON.stringify({
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	}));
+}
+async function readJsonBody(req) {
+	const chunks = [];
+	for await (const chunk of req) chunks.push(chunk);
+	const raw = Buffer.concat(chunks).toString("utf8");
+	if (raw.trim() === "") return {};
+	try {
+		const parsed = JSON.parse(raw);
+		return typeof parsed === "object" && parsed !== null ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+function registerApiRoutes(ctx, service) {
+	const fence = (req) => isTrustedApiRequest(req, trustedHostsOf(ctx));
+	const disposers = [];
+	const route = (name, handler) => {
+		disposers.push(ctx.webServer.register({
+			kind: "prefix",
+			path: `${API_PREFIX}/${name}`,
+			handler: async (req, res) => {
+				if (!fence(req)) {
+					writeError(res, "forbidden", "forbidden", 403);
+					return;
+				}
+				if (req.method !== "POST" && req.method !== "GET") {
+					writeError(res, "method", "method not allowed", 405);
+					return;
+				}
+				const payload = await readJsonBody(req);
+				try {
+					writeJson(res, {
+						ok: true,
+						value: await handler(payload)
+					});
+				} catch (error) {
+					writeError(res, "error", error instanceof Error ? error.message : String(error));
+				}
+			}
+		}));
+	};
+	route("state", async () => stateOf(service));
+	route("refresh", async () => {
+		await service.refreshAndReconcile();
+		return stateOf(service);
+	});
+	route("reconcile", async () => {
+		await service.reconcile();
+		return stateOf(service);
+	});
+	route("set-config", async (payload) => {
+		const patch = payload.patch;
+		if (typeof patch !== "object" || patch === null) throw new Error("patch must be an object");
+		await service.updateConfig(patch);
+		return stateOf(service);
+	});
+	return () => {
+		for (const dispose of disposers) dispose();
+	};
+}
+/**
+* The settings-page view. Deliberately ships only catalog COUNTS — the full
+* entries array (thousands of models) must never cross the wire or render.
+*/
+function stateOf(service) {
+	const config = service.config();
+	const snapshot = service.catalogSnapshot();
+	return {
+		config,
+		catalog: {
+			entries: snapshot.entries.length,
+			providers: snapshot.providers,
+			fetchedAt: snapshot.fetchedAt,
+			fresh: snapshot.fetchedAt > 0 && Date.now() - snapshot.fetchedAt < config.ttlDays * 24 * 60 * 60 * 1e3,
+			ttlDays: config.ttlDays
+		},
+		report: service.report()
+	};
+}
+//#endregion
+//#region src/index.ts
+const name = "@fonlan/dsh-model-parameters";
+const inject = [];
+function apply(ctx) {
+	const service = new ModelParametersService(ctx);
+	ctx.effect(() => {
+		service.start();
+		return () => service.stop();
+	}, "model-parameters: service");
+	ctx.inject(["webServer"], (sctx) => {
+		sctx.effect(() => registerApiRoutes(sctx, service), "model-parameters: api routes");
+	});
+}
+//#endregion
+export { CatalogManager, Config, acceptedInputModalities, apply, identityReasoningEfforts, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fonlan/dsh-model-parameters host half.
+ *
+ * Watches the `llm-pi-ai` settings namespace: whenever provider models are
+ * written there with missing display name / context window / max output
+ * tokens / reasoning efforts / input modalities (the norm for a freshly
+ * synced gateway), it fills the missing fields from a cached models.dev
+ * catalog (TTL-refreshed), and serves the fenced JSON API the web settings
+ * page calls. The plugin's own toggles live in the `model-parameters`
+ * settings namespace (settings.yaml).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './shared/config.js';
+import { CatalogManager, acceptedInputModalities, identityReasoningEfforts, type CatalogEntry, type CatalogSnapshot } from './server/catalog.js';
+export declare const name = "@fonlan/dsh-model-parameters";
+export declare const inject: string[];
+export { Config };
+export { CatalogManager, acceptedInputModalities, identityReasoningEfforts };
+export type { CatalogEntry, CatalogSnapshot };
+export declare function apply(ctx: Context): void;