openmausbot 0.1.91 → 0.1.93

package/dist-server/server/memory-upkeep.js

@@ -25,7 +25,7 @@ import { mergeTopicText } from "./memory-topics.js";
 import { applyMoves, MAX_MOVES, organizeCandidates, organizePrompt, parseMoves } from "./memory-organize.js";
 import { recordMemoryChange } from "./memory-journal.js";
 import { applyTidy, contradictionCandidates, contradictionPrompt, parseContradictions, planChanges, planTidy } from "./memory-tidy.js";
-import { ensureWorkspace, listMemoryTopics, memoryDate, memoryEntry, memoryTopicIndex, updateMemory, workspaceDir, writeMemoryFile, writeMemoryTopic } from "./workspace.js";
+import { ensureWorkspace, listMemoryTopics, memoryDate, memoryEntry, memoryTopicIndex, readMemoryText, updateMemory, workspaceDir, writeMemoryFile, writeMemoryTopic } from "./workspace.js";
 export const CAPTURE_MAX_TURNS = 6;
 export const MODEL_TIMEOUT_MS = 60_000;
 export const TIDY_CHECK_MS = 10 * 60_000;
@@ -36,7 +36,7 @@ export const ARCHIVE_TOPIC = "archive.md";
 export const TOPIC_MAX_BYTES = 64 * 1024;
 /** On unless switched off: every bot keeps its memory in shape by default. */
 export function upkeepEnabled(bot) {
-    return Boolean(bot) && bot.memoryUpkeep !== false;
+    return Boolean(bot) && bot.memoryUpkeep !== false && bot.memoryEnabled !== false;
 }
 /** How many "this entry is core" judgements are remembered per bot. */
 const MAX_CORE = 500;
@@ -63,7 +63,7 @@ function saveState(state) {
 }
 function readRaw(botId, relative) {
     try {
-        return readFileSync(join(workspaceDir(botId), relative), "utf8");
+        return readMemoryText(join(workspaceDir(botId), relative));
     }
     catch {
         return null;
@@ -103,6 +103,7 @@ export function createMemoryUpkeep(deps) {
         void promise.finally(() => inflight.delete(promise)).catch(() => undefined);
         return promise;
     };
+    const writing = deps.writing ?? ((_botId, write) => write());
     async function capture(batch) {
         const bot = deps.bot(batch.botId);
         const at = now().getTime();
@@ -138,54 +139,57 @@ export function createMemoryUpkeep(deps) {
         // From here to the journal rows there is no await, so no write interleaves.
         if (!upkeepEnabled(deps.bot(bot.id)))
             return off;
-        const before = readRaw(bot.id, "MEMORY.md");
-        const parsed = parseCandidates(answer, today);
-        const fresh = newCandidates(parsed, before ?? "");
-        const source = `${deps.sourceLabel(bot.id, batch.threadId)} (noticed)`;
-        let added = 0;
-        let full = false;
-        const byTopic = new Map();
-        for (const candidate of fresh) {
-            if (candidate.topic) {
-                byTopic.set(candidate.topic, [...(byTopic.get(candidate.topic) ?? []), candidate]);
-                continue;
-            }
-            const result = updateMemory(bot.id, { action: "append", text: candidate.text, ...(candidate.until ? { until: candidate.until } : {}) }, { source, now: now() });
-            if (result.ok)
-                added += 1;
-            else if (result.code === "over-budget")
-                full = true;
-        }
-        if (added)
-            recordMemoryChange(bot.id, { path: "MEMORY.md", actor: "upkeep", via: "capture", threadId: batch.threadId, before, after: readRaw(bot.id, "MEMORY.md") });
-        // Detail goes to a topic file the bot keeps for that subject, created
-        // with a header (title and other words for it) the first time.
-        const existing = new Map(listMemoryTopics(bot.id).map((topic) => [topic.name.toLowerCase(), topic.name]));
-        let topics = 0;
-        for (const [wanted, candidates] of byTopic) {
-            const name = existing.get(wanted) ?? wanted;
-            const path = `memory/${name}`;
-            const current = readRaw(bot.id, path);
-            if (current !== null && Buffer.byteLength(current, "utf8") > TOPIC_MAX_BYTES)
-                continue;
-            const seen = notebookIdentities(current ?? "");
-            const lines = candidates
-                .filter((candidate) => !seen.has(factIdentity(candidate.text)))
-                .map((candidate) => memoryEntry(candidate.text, { source, now: now(), ...(candidate.until ? { until: candidate.until } : {}) }));
-            if (!lines.length)
-                continue;
-            const title = name.replace(/\.md$/, "").replace(/-/g, " ");
-            const aliases = [...new Set(candidates.flatMap((candidate) => candidate.topicAliases ?? []))];
-            try {
-                writeMemoryTopic(bot.id, name, mergeTopicText(current, { title, aliases, lines }));
+        const { parsed, added, topics, full } = writing(bot.id, () => {
+            const before = readRaw(bot.id, "MEMORY.md");
+            const parsed = parseCandidates(answer, today);
+            const fresh = newCandidates(parsed, before ?? "");
+            const source = `${deps.sourceLabel(bot.id, batch.threadId)} (noticed)`;
+            let added = 0;
+            let full = false;
+            const byTopic = new Map();
+            for (const candidate of fresh) {
+                if (candidate.topic) {
+                    byTopic.set(candidate.topic, [...(byTopic.get(candidate.topic) ?? []), candidate]);
+                    continue;
+                }
+                const result = updateMemory(bot.id, { action: "append", text: candidate.text, ...(candidate.until ? { until: candidate.until } : {}) }, { source, now: now() });
+                if (result.ok)
+                    added += 1;
+                else if (result.code === "over-budget")
+                    full = true;
             }
-            catch {
-                continue;
+            if (added)
+                recordMemoryChange(bot.id, { path: "MEMORY.md", actor: "upkeep", via: "capture", threadId: batch.threadId, before, after: readRaw(bot.id, "MEMORY.md") });
+            // Detail goes to a topic file the bot keeps for that subject, created
+            // with a header (title and other words for it) the first time.
+            const existing = new Map(listMemoryTopics(bot.id).map((topic) => [topic.name.toLowerCase(), topic.name]));
+            let topics = 0;
+            for (const [wanted, candidates] of byTopic) {
+                const name = existing.get(wanted) ?? wanted;
+                const path = `memory/${name}`;
+                const current = readRaw(bot.id, path);
+                if (current !== null && Buffer.byteLength(current, "utf8") > TOPIC_MAX_BYTES)
+                    continue;
+                const seen = notebookIdentities(current ?? "");
+                const lines = candidates
+                    .filter((candidate) => !seen.has(factIdentity(candidate.text)))
+                    .map((candidate) => memoryEntry(candidate.text, { source, now: now(), ...(candidate.until ? { until: candidate.until } : {}) }));
+                if (!lines.length)
+                    continue;
+                const title = name.replace(/\.md$/, "").replace(/-/g, " ");
+                const aliases = [...new Set(candidates.flatMap((candidate) => candidate.topicAliases ?? []))];
+                try {
+                    writeMemoryTopic(bot.id, name, mergeTopicText(current, { title, aliases, lines }));
+                }
+                catch {
+                    continue;
+                }
+                recordMemoryChange(bot.id, { path, actor: "upkeep", via: "capture", threadId: batch.threadId, before: current, after: readRaw(bot.id, path) });
+                existing.set(name.toLowerCase(), name);
+                topics += lines.length;
             }
-            recordMemoryChange(bot.id, { path, actor: "upkeep", via: "capture", threadId: batch.threadId, before: current, after: readRaw(bot.id, path) });
-            existing.set(name.toLowerCase(), name);
-            topics += lines.length;
-        }
+            return { parsed, added, topics, full };
+        });
         // Only the owner's own words reach About me: on a shared workspace
         // another person's facts are not the owner's profile. Every parsed fact
         // counts, not only new ones — the bot may already have noted it in its
@@ -245,37 +249,39 @@ export function createMemoryUpkeep(deps) {
         saveState(saved);
         if (!moves.length)
             return 0;
-        const { byTopic } = applyMoves(before, moves);
-        const written = new Set();
-        const existing = new Map(listMemoryTopics(botId).map((topic) => [topic.name.toLowerCase(), topic.name]));
-        let count = 0;
-        for (const [wanted, group] of byTopic) {
-            const name = existing.get(wanted) ?? wanted;
-            const path = `memory/${name}`;
-            const current = readRaw(botId, path);
-            const seen = notebookIdentities(current ?? "");
-            const lines = group.lines.filter((line) => !seen.has(lineFactIdentity(line)));
-            if (lines.length) {
-                try {
-                    writeMemoryTopic(botId, name, mergeTopicText(current, { title: name.replace(/\.md$/, "").replace(/-/g, " "), aliases: group.aliases, lines }));
+        return writing(botId, () => {
+            const { byTopic } = applyMoves(before, moves);
+            const written = new Set();
+            const existing = new Map(listMemoryTopics(botId).map((topic) => [topic.name.toLowerCase(), topic.name]));
+            let count = 0;
+            for (const [wanted, group] of byTopic) {
+                const name = existing.get(wanted) ?? wanted;
+                const path = `memory/${name}`;
+                const current = readRaw(botId, path);
+                const seen = notebookIdentities(current ?? "");
+                const lines = group.lines.filter((line) => !seen.has(lineFactIdentity(line)));
+                if (lines.length) {
+                    try {
+                        writeMemoryTopic(botId, name, mergeTopicText(current, { title: name.replace(/\.md$/, "").replace(/-/g, " "), aliases: group.aliases, lines }));
+                    }
+                    catch (error) {
+                        log(`memory upkeep: could not write ${path}; kept its entries in MEMORY.md: ${error.message}`);
+                        continue;
+                    }
+                    recordMemoryChange(botId, { path, actor: "upkeep", via: "organize", before: current, after: readRaw(botId, path) });
                 }
-                catch (error) {
-                    log(`memory upkeep: could not write ${path}; kept its entries in MEMORY.md: ${error.message}`);
-                    continue;
-                }
-                recordMemoryChange(botId, { path, actor: "upkeep", via: "organize", before: current, after: readRaw(botId, path) });
+                existing.set(name.toLowerCase(), name);
+                written.add(wanted);
+                count += group.lines.length;
             }
-            existing.set(name.toLowerCase(), name);
-            written.add(wanted);
-            count += group.lines.length;
-        }
-        if (!written.size)
-            return 0;
-        const { text } = applyMoves(before, moves.filter((move) => written.has(move.topic)));
-        writeMemoryFile(botId, text);
-        recordMemoryChange(botId, { path: "MEMORY.md", actor: "upkeep", via: "organize", before, after: readRaw(botId, "MEMORY.md") });
-        log(`memory upkeep: moved ${count} entr${count === 1 ? "y" : "ies"} from MEMORY.md into topic files for ${deps.bot(botId)?.name ?? botId}`);
-        return count;
+            if (!written.size)
+                return 0;
+            const { text } = applyMoves(before, moves.filter((move) => written.has(move.topic)));
+            writeMemoryFile(botId, text);
+            recordMemoryChange(botId, { path: "MEMORY.md", actor: "upkeep", via: "organize", before, after: readRaw(botId, "MEMORY.md") });
+            log(`memory upkeep: moved ${count} entr${count === 1 ? "y" : "ies"} from MEMORY.md into topic files for ${deps.bot(botId)?.name ?? botId}`);
+            return count;
+        });
     }
     function appendArchive(botId, archived) {
         const archivePath = `memory/${ARCHIVE_TOPIC}`;
@@ -330,9 +336,11 @@ export function createMemoryUpkeep(deps) {
             // The archive is written first: a line is never out of MEMORY.md
             // before it is in the archive, and the newest journal row — the one a
             // person undoes — is MEMORY.md, whose undo brings the line back.
-            if (archived.length)
-                appendArchive(botId, archived);
-            writeMemoryFile(botId, text);
+            writing(botId, () => {
+                if (archived.length)
+                    appendArchive(botId, archived);
+                writeMemoryFile(botId, text);
+            });
             recordMemoryChange(botId, { path: "MEMORY.md", actor: "upkeep", via: "tidy", before, after: readRaw(botId, "MEMORY.md") });
         }
         // Topic files get the two steps that need no model: expired lines to the
@@ -350,9 +358,11 @@ export function createMemoryUpkeep(deps) {
             if (!planChanges(topicPlan))
                 continue;
             const tidied = applyTidy(topicBefore, topicPlan, today);
-            if (tidied.archived.length)
-                appendArchive(botId, tidied.archived);
-            writeMemoryTopic(botId, topic.name, tidied.text);
+            writing(botId, () => {
+                if (tidied.archived.length)
+                    appendArchive(botId, tidied.archived);
+                writeMemoryTopic(botId, topic.name, tidied.text);
+            });
             recordMemoryChange(botId, { path, actor: "upkeep", via: "tidy", before: topicBefore, after: readRaw(botId, path) });
             topicExpired += topicPlan.expired.length;
             topicDuplicates += topicPlan.duplicates.length;

package/dist-server/server/model-catalog/catalog.js

@@ -0,0 +1,374 @@
+/*! Adapted from anomalyco/opencode@2fa3363c924c5c3e367b84a87ae478296a0ed59b
+ * packages/core/src/models-dev.ts:160-258, MIT; modified.
+ *
+ * MIT License
+ *
+ * Copyright (c) 2025 opencode
+ *
+ * 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.
+ */
+// The model provider catalog: load it, keep it fresh, merge in the presets.
+//
+// Kept from OpenCode's models-dev.ts: a cache file refreshed from
+// models.dev/api.json with a 10 s timeout, written through a temp file and a
+// rename; a corrupt cache is deleted; a snapshot bundled with the app; a
+// forced refresh skips the freshness check; failures are logged and never
+// surface; one switch turns fetching off.
+//
+// Changed for OpenMausBot:
+// - plain Node instead of Effect; one server process owns DATA_DIR, so a
+//   single in-flight promise stands in for OpenCode's cross-process flock;
+// - data counts as fresh for 24 hours, and a refresh runs only when asked
+//   (Settings or the model picker opening), not on a timer;
+// - If-None-Match with the stored ETag, a 20 MB cap, redirects refused;
+// - every source is trimmed and brace-filtered (trim.ts) before use;
+// - the source is the newest of: our cache, OpenCode's own cache
+//   (~/.cache/opencode/models.json, read only), the bundled snapshot. On a tie
+//   that order decides, so a newer snapshot beats an older cache;
+// - switched off by OMB_DISABLE_MODEL_CATALOG_FETCH=1, and by the caller on
+//   managed or hosted installs.
+//
+// This list is never the last word on what a key can use: the provider's own
+// /models, called with the key, is. The catalog supplies names, key variable
+// names, base URLs and the capability flags used to pick recommended models.
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeFileAtomic } from "../atomic.js";
+import { OPENAI_COMPATIBLE_NPM, PROVIDER_PRESETS } from "./presets.js";
+import { MODEL_CATALOG_SCHEMA, catalogStats, packCatalog, trimModelsDevCatalog, unpackCatalog, } from "./trim.js";
+export const MODELS_DEV_URL = "https://models.dev/api.json";
+export const CATALOG_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+export const CATALOG_FETCH_TIMEOUT_MS = 10_000;
+export const CATALOG_MAX_BYTES = 20 * 1024 * 1024;
+export const CATALOG_DISABLE_ENV = "OMB_DISABLE_MODEL_CATALOG_FETCH";
+export const SNAPSHOT_FILE = "models-dev.snapshot.json";
+/** Our cache, under providers/ so backups and Move to Cloud leave it out. */
+export function modelCatalogCachePath(dataDir) {
+    return join(dataDir, "providers", "model-providers", "models-dev.json");
+}
+/** Where OpenCode keeps models.dev (xdg-basedir's cache dir, on every OS). */
+export function openCodeCatalogCachePath(env = process.env) {
+    return join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "opencode", "models.json");
+}
+/** The snapshot sits beside this module in a checkout, and under
+ * model-catalog/ beside the bundled server (scripts/bundle-server.mjs). */
+function readBundledSnapshot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const path of [join(here, SNAPSHOT_FILE), join(here, "model-catalog", SNAPSHOT_FILE)]) {
+        if (existsSync(path))
+            return readFileSync(path, "utf8");
+    }
+    return undefined;
+}
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/u;
+// An ETag is echoed back in a request header: keep only a plain, short one.
+const safeEtag = (value) => typeof value === "string" && value.length <= 256 && !CONTROL.test(value) ? value : undefined;
+const time = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? undefined : parsed;
+};
+const message = (error) => error instanceof Error ? error.message : String(error);
+export class ModelCatalogStore {
+    options;
+    cachePath;
+    memo;
+    inflight;
+    constructor(options) {
+        this.options = options;
+        this.cachePath = modelCatalogCachePath(options.dataDir);
+    }
+    get now() {
+        return (this.options.now ?? Date.now)();
+    }
+    log(text) {
+        (this.options.log ?? ((line) => console.warn(line)))(`[model-catalog] ${text}`);
+    }
+    get fetchDisabled() {
+        return Boolean(this.options.fetchDisabled) || (this.options.env ?? process.env)[CATALOG_DISABLE_ENV] === "1";
+    }
+    /** The newest usable catalog. Never throws; worst case an empty catalog. */
+    get() {
+        if (this.memo)
+            return this.memo;
+        const candidates = [this.ownCache(), this.openCodeCache(), this.snapshot()]
+            .filter((candidate) => candidate !== undefined);
+        // Stable sort: on equal times the listed order (cache, OpenCode, snapshot) wins.
+        candidates.sort((a, b) => b.updatedAt - a.updatedAt);
+        for (const candidate of candidates) {
+            let drops = 0;
+            const providers = trimModelsDevCatalog(candidate.providers(), { onDrop: () => { drops += 1; } });
+            if (!Object.keys(providers).length) {
+                this.log(`the ${candidate.origin} catalog held no usable providers; trying the next one`);
+                continue;
+            }
+            if (drops)
+                this.log(`left out ${drops} ${candidate.origin} catalog entries that were malformed or contained { or }`);
+            this.memo = { origin: candidate.origin, updatedAt: new Date(candidate.updatedAt).toISOString(), providers };
+            return this.memo;
+        }
+        this.memo = { origin: "empty", updatedAt: new Date(0).toISOString(), providers: trimModelsDevCatalog(undefined) };
+        return this.memo;
+    }
+    /** Refresh from models.dev unless the cache is under 24 hours old (or
+     * `force`). Concurrent calls share one request. Never throws. */
+    refresh(options = {}) {
+        if (this.fetchDisabled)
+            return Promise.resolve("disabled");
+        this.inflight ??= this.fetchAndStore(Boolean(options.force)).finally(() => {
+            this.inflight = undefined;
+        });
+        return this.inflight;
+    }
+    readDocument() {
+        if (!existsSync(this.cachePath))
+            return undefined;
+        try {
+            if (statSync(this.cachePath).size > (this.options.maxBytes ?? CATALOG_MAX_BYTES))
+                throw new Error("too large");
+            const doc = JSON.parse(readFileSync(this.cachePath, "utf8"));
+            const updatedAt = time(doc?.updatedAt);
+            if (doc?.schema !== MODEL_CATALOG_SCHEMA || updatedAt === undefined || !doc.providers)
+                throw new Error("unrecognised format");
+            return { doc, updatedAt };
+        }
+        catch (error) {
+            // As OpenCode does, drop a cache we cannot read; the next refresh rewrites it.
+            this.log(`removed an unreadable catalog cache (${message(error)})`);
+            try {
+                rmSync(this.cachePath, { force: true });
+            }
+            catch { /* best effort */ }
+            return undefined;
+        }
+    }
+    ownCache() {
+        const cached = this.readDocument();
+        return cached && { origin: "cache", updatedAt: cached.updatedAt, providers: () => unpackCatalog(cached.doc.providers) };
+    }
+    openCodeCache() {
+        const path = this.options.openCodeCachePath === undefined
+            ? openCodeCatalogCachePath(this.options.env ?? process.env)
+            : this.options.openCodeCachePath;
+        if (!path)
+            return undefined;
+        try {
+            const stat = statSync(path);
+            if (!stat.isFile() || stat.size > (this.options.maxBytes ?? CATALOG_MAX_BYTES))
+                return undefined;
+            // Read only if chosen: it is models.dev's full 5 MB catalog.
+            return { origin: "opencode", updatedAt: stat.mtimeMs, providers: () => {
+                    try {
+                        return JSON.parse(readFileSync(path, "utf8"));
+                    }
+                    catch {
+                        return undefined;
+                    }
+                } };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    snapshot() {
+        try {
+            const text = (this.options.readSnapshot ?? readBundledSnapshot)();
+            if (text === undefined) {
+                this.log("the bundled catalog snapshot is missing");
+                return undefined;
+            }
+            const doc = JSON.parse(text);
+            const updatedAt = time(doc?.updatedAt);
+            if (doc?.schema !== MODEL_CATALOG_SCHEMA || updatedAt === undefined)
+                throw new Error("unrecognised format");
+            return { origin: "snapshot", updatedAt, providers: () => unpackCatalog(doc.providers) };
+        }
+        catch (error) {
+            this.log(`could not read the bundled catalog snapshot (${message(error)})`);
+            return undefined;
+        }
+    }
+    async fetchAndStore(force) {
+        const cached = this.readDocument();
+        const age = cached ? this.now - cached.updatedAt : Infinity;
+        // A cache stamped in the future (clock moved back) counts as stale.
+        if (!force && age >= 0 && age < CATALOG_MAX_AGE_MS)
+            return "fresh";
+        try {
+            const etag = cached ? safeEtag(cached.doc.source?.etag) : undefined;
+            const response = await this.download(etag);
+            if (response.status === 304) {
+                if (!cached)
+                    throw new Error("models.dev answered 304 without a cached copy");
+                this.write({ ...cached.doc, updatedAt: new Date(this.now).toISOString() });
+                this.memo = undefined;
+                return "not-modified";
+            }
+            let raw;
+            try {
+                raw = JSON.parse(response.text);
+            }
+            catch {
+                throw new Error("models.dev returned invalid JSON");
+            }
+            let drops = 0;
+            const providers = trimModelsDevCatalog(raw, { onDrop: () => { drops += 1; } });
+            // Never replace a good cache with an empty one.
+            if (!Object.keys(providers).length)
+                throw new Error("models.dev returned no usable providers");
+            this.write({
+                schema: MODEL_CATALOG_SCHEMA,
+                updatedAt: new Date(this.now).toISOString(),
+                source: { name: "models.dev", url: MODELS_DEV_URL, license: "MIT", ...(response.etag ? { etag: response.etag } : {}) },
+                providers: packCatalog(providers),
+            });
+            this.memo = undefined;
+            const stats = catalogStats(providers);
+            this.log(`updated from models.dev: ${stats.providers} providers, ${stats.models} models` +
+                (drops ? `; left out ${drops} entries that were malformed or contained { or }` : ""));
+            return "updated";
+        }
+        catch (error) {
+            this.log(`could not refresh from models.dev (${message(error)}); keeping the current catalog`);
+            return "failed";
+        }
+    }
+    write(doc) {
+        mkdirSync(dirname(this.cachePath), { recursive: true });
+        writeFileAtomic(this.cachePath, JSON.stringify(doc));
+    }
+    async download(etag) {
+        const maxBytes = this.options.maxBytes ?? CATALOG_MAX_BYTES;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.options.timeoutMs ?? CATALOG_FETCH_TIMEOUT_MS);
+        try {
+            const response = await (this.options.fetch ?? fetch)(MODELS_DEV_URL, {
+                headers: { accept: "application/json", "user-agent": "OpenMausBot", ...(etag ? { "if-none-match": etag } : {}) },
+                // Nothing secret is sent, but the catalog comes from models.dev only.
+                redirect: "error",
+                signal: controller.signal,
+            });
+            if (response.status === 304 && etag) {
+                void response.body?.cancel().catch(() => { });
+                return { status: 304 };
+            }
+            if (response.status !== 200) {
+                void response.body?.cancel().catch(() => { });
+                throw new Error(`models.dev returned HTTP ${response.status}`);
+            }
+            const declared = Number(response.headers.get("content-length"));
+            if (Number.isFinite(declared) && declared > maxBytes) {
+                void response.body?.cancel().catch(() => { });
+                throw new Error(`models.dev sent more than ${maxBytes} bytes`);
+            }
+            // The timer also covers reading the body.
+            const text = await readCapped(response, maxBytes);
+            return { status: 200, text, etag: safeEtag(response.headers.get("etag")) };
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw new Error("models.dev did not answer in time");
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+async function readCapped(response, maxBytes) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let total = 0;
+    let text = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => { });
+            throw new Error(`models.dev sent more than ${maxBytes} bytes`);
+        }
+        text += decoder.decode(value, { stream: true });
+    }
+    return text + decoder.decode();
+}
+/** The SDK package for a preset's pinned `api`. models.dev's `npm` describes
+ * models.dev's `api` (or, when it lists none, the SDK's own default address,
+ * which the preset pins too), so it is kept only when that is the address the
+ * preset pins. Otherwise the pinned address is OpenAI-compatible by definition. */
+function presetNpm(preset, provider) {
+    if (preset.npm)
+        return preset.npm;
+    if (!provider?.npm)
+        return undefined;
+    return provider.api === undefined || provider.api === preset.api ? provider.npm : OPENAI_COMPATIBLE_NPM;
+}
+/** The catalog merged with the presets: recommended rows first, in their
+ * order, then every other provider by name. Presets whose provider the
+ * catalog lacks (or dropped) are still listed. */
+export function catalogEntries(catalog, presets = PROVIDER_PRESETS) {
+    const entries = [];
+    const covered = new Set();
+    for (const preset of presets) {
+        const provider = preset.catalogId ? catalog.providers[preset.catalogId] : undefined;
+        if (provider)
+            covered.add(provider.id);
+        const entry = {
+            id: preset.id,
+            label: preset.label,
+            env: provider?.env ?? (preset.env ? [preset.env] : []),
+            api: preset.api,
+            modelCount: provider ? Object.keys(provider.models).length : 0,
+            preset,
+        };
+        if (provider)
+            entry.catalogId = provider.id;
+        const npm = presetNpm(preset, provider);
+        if (npm)
+            entry.npm = npm;
+        const doc = preset.doc ?? provider?.doc;
+        if (doc)
+            entry.doc = doc;
+        if (preset.recommended !== undefined)
+            entry.recommended = preset.recommended;
+        entries.push(entry);
+    }
+    for (const provider of Object.values(catalog.providers)) {
+        if (covered.has(provider.id) || presets.some((preset) => preset.id === provider.id))
+            continue;
+        const entry = { id: provider.id, catalogId: provider.id, label: provider.name, env: provider.env, modelCount: Object.keys(provider.models).length };
+        if (provider.npm)
+            entry.npm = provider.npm;
+        if (provider.api)
+            entry.api = provider.api;
+        if (provider.doc)
+            entry.doc = provider.doc;
+        entries.push(entry);
+    }
+    return entries.sort((a, b) => (a.recommended ?? Infinity) - (b.recommended ?? Infinity) ||
+        a.label.localeCompare(b.label, "en", { sensitivity: "base" }) ||
+        a.id.localeCompare(b.id));
+}