@srouterhq/server 0.0.0-stage → 0.9.0

package/dist/services/cooldown-probe.js

@@ -0,0 +1,181 @@
+// cooldown-probe — probe-based early recovery for benched keys.
+//
+// Cooldowns are deliberately pessimistic: a transient 429 benches a model+key
+// for 90s, the escalation ladder for up to a day, and an upstream 401 for the
+// whole 5-minute health cycle. When the provider recovers sooner (a per-minute
+// window rolled over, a provider incident ended, a key was un-revoked), that
+// capacity sits idle until the timer runs out. This job periodically issues the
+// same cheap validateKey call the health checker uses against keys sitting in a
+// HEURISTIC cooldown, and clears those cooldowns early when the probe passes.
+//
+// What it will never do:
+//   - probe a cooldown backed by an authoritative retry time (explicit
+//     Retry-After, daily-quota reset) or a credit/tier bench — those are
+//     provider-stated facts, filtered out at the query (getProbeableCooldowns);
+//   - extend a cooldown: a failed probe only schedules the next probe further
+//     out (exponential backoff), the bench itself is untouched;
+//   - feed the health checker's consecutive-failure counter (probeKeyValidity
+//     is side-effect-free by design);
+//   - thundering-herd providers after a restart: a key's first sighting only
+//     schedules a jittered probe, and each pass probes at most a handful of
+//     keys.
+//
+// The probe unit is the KEY, not the model: validateKey exercises the
+// credential, so one pass/fail is the same evidence for every heuristic
+// cooldown that key holds, and probing per key is what keeps probe traffic
+// bounded no matter how many models are benched on it.
+//
+// Kill switch: COOLDOWN_PROBE_DISABLED=1 (same convention as
+// CATALOG_SYNC_DISABLED). Per-pass probe budget: COOLDOWN_PROBE_MAX_PER_PASS.
+import { getProbeableCooldowns, clearCooldownEarly, } from './ratelimit.js';
+import { probeKeyValidity } from './health.js';
+import { providerLog } from '../lib/server-logs.js';
+// How often the scanner wakes up to look at the cooldown table. Scanning is one
+// cheap indexed SELECT; actual probes are gated far harder below.
+const SCAN_INTERVAL_MS = 60 * 1000;
+// A cooldown only becomes probe-ripe after this fraction of its bench has been
+// served. Probing a seconds-old cooldown would mostly re-confirm the failure
+// that caused it; by half-time a transient condition has had a real chance to
+// clear, and long escalated benches still recover hours early.
+const MIN_ELAPSED_FRACTION = 0.5;
+// Not worth probing a cooldown that is about to expire on its own — the probe
+// would cost a validate call to save less than a scan interval of idle time.
+const MIN_REMAINING_MS = 60 * 1000;
+// Failed-probe backoff per key: 2m, 4m, 8m, capped at 15m. Keys that stay bad
+// converge to one validate call per 15 minutes — a third of what the 5-minute
+// health pass already sends them.
+const PROBE_BACKOFF_BASE_MS = 2 * 60 * 1000;
+const PROBE_BACKOFF_MAX_MS = 15 * 60 * 1000;
+// Stagger window for a key's FIRST probe after it is sighted (covers the
+// restart case, where every persisted cooldown is sighted at once).
+const FIRST_PROBE_STAGGER_MS = 45 * 1000;
+const DEFAULT_MAX_PROBES_PER_PASS = 3;
+/** Per-pass probe budget. Tunable for large key fleets; 0 or a bad value falls
+ *  back to the default (mirrors HEALTH_CHECK_CONCURRENCY). */
+function getMaxProbesPerPass() {
+    const raw = process.env.COOLDOWN_PROBE_MAX_PER_PASS;
+    if (raw !== undefined && raw.trim() !== '') {
+        const n = Number(raw);
+        if (Number.isInteger(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_MAX_PROBES_PER_PASS;
+}
+// keyId -> probe pacing. In-memory only, like the escalation ladder: a restart
+// forgetting the backoff is fine because first-sighting staggering re-spaces
+// the probes anyway.
+const keyState = new Map();
+/** True when this cooldown has served enough of its bench to be worth probing. */
+function isRipe(cooldown, now) {
+    if (cooldown.expiresAtMs - now < MIN_REMAINING_MS)
+        return false;
+    // Rows persisted before the provenance migration have no start time; treat
+    // them as old enough rather than never probing them.
+    if (cooldown.setAtMs == null)
+        return true;
+    const duration = cooldown.expiresAtMs - cooldown.setAtMs;
+    return now - cooldown.setAtMs >= duration * MIN_ELAPSED_FRACTION;
+}
+/**
+ * One probe pass: find ripe heuristic cooldowns, probe up to maxProbes of their
+ * keys (respecting per-key backoff), and clear every heuristic cooldown on a
+ * key whose probe passed. Exported for tests; production runs it on the
+ * scheduler via startCooldownProbe.
+ */
+export async function runCooldownProbePass(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const probe = opts.probe ?? probeKeyValidity;
+    const jitter = opts.jitter ?? Math.random;
+    const maxProbes = opts.maxProbes ?? getMaxProbesPerPass();
+    const all = getProbeableCooldowns(now);
+    // Drop pacing state for keys with no probeable cooldowns left (expired,
+    // cleared, or re-benched as authoritative) so old backoff cannot delay a
+    // future, unrelated bench.
+    const keysWithCooldowns = new Set(all.map(c => c.keyId));
+    for (const keyId of [...keyState.keys()]) {
+        if (!keysWithCooldowns.has(keyId))
+            keyState.delete(keyId);
+    }
+    const ripeByKey = new Map();
+    for (const cooldown of all) {
+        if (!isRipe(cooldown, now))
+            continue;
+        const list = ripeByKey.get(cooldown.keyId) ?? [];
+        list.push(cooldown);
+        ripeByKey.set(cooldown.keyId, list);
+    }
+    const probedKeyIds = [];
+    let clearedCooldowns = 0;
+    for (const [keyId, cooldownsForKey] of ripeByKey) {
+        if (probedKeyIds.length >= maxProbes)
+            break;
+        let state = keyState.get(keyId);
+        if (!state) {
+            // First sighting: schedule, don't probe. This is the restart stagger —
+            // a boot with dozens of persisted cooldowns spreads its first probes
+            // across the jitter window instead of validating everything at once.
+            state = { failures: 0, nextProbeAtMs: now + Math.floor(jitter() * FIRST_PROBE_STAGGER_MS) };
+            keyState.set(keyId, state);
+            continue;
+        }
+        if (now < state.nextProbeAtMs)
+            continue;
+        probedKeyIds.push(keyId);
+        const outcome = await probe(keyId);
+        if (outcome === 'valid') {
+            for (const cooldown of cooldownsForKey) {
+                clearCooldownEarly(cooldown.platform, cooldown.modelId, cooldown.keyId);
+                clearedCooldowns++;
+            }
+            keyState.delete(keyId);
+            // Structured so the dashboard log viewer can filter recoveries by
+            // provider; providerLog still writes the same line to stdout.
+            providerLog('info', `[CooldownProbe] key ${keyId} validated — cleared ${cooldownsForKey.length} cooldown(s) early ` +
+                `(${cooldownsForKey.map(c => `${c.platform}/${c.modelId}`).join(', ')})`, { provider: cooldownsForKey[0]?.platform, event: 'cooldown_recovered' });
+        }
+        else {
+            // Failed or inconclusive: the bench stays EXACTLY as it was — a probe
+            // must never extend a cooldown — and this key backs off before the next
+            // attempt so probes cannot burn quota against a provider that is down.
+            state.failures++;
+            const backoff = Math.min(PROBE_BACKOFF_BASE_MS * 2 ** (state.failures - 1), PROBE_BACKOFF_MAX_MS);
+            state.nextProbeAtMs = now + backoff;
+        }
+    }
+    return { probedKeyIds, clearedCooldowns };
+}
+// Overlap guard, same shape as checkAllKeys: a slow provider validate must not
+// let the next scheduled pass stack a second set of probes on top.
+let passInFlight = null;
+function runGuardedPass() {
+    if (passInFlight)
+        return passInFlight;
+    passInFlight = runCooldownProbePass().finally(() => {
+        passInFlight = null;
+    });
+    return passInFlight;
+}
+let cancelProbeJob = null;
+export function startCooldownProbe(scheduler) {
+    if (cancelProbeJob)
+        return;
+    if (process.env.COOLDOWN_PROBE_DISABLED === '1') {
+        console.log('[CooldownProbe] disabled via COOLDOWN_PROBE_DISABLED=1');
+        return;
+    }
+    console.log(`[CooldownProbe] starting cooldown-probe recovery (scan every ${SCAN_INTERVAL_MS / 1000}s)`);
+    cancelProbeJob = scheduler.every(SCAN_INTERVAL_MS, async () => {
+        await runGuardedPass().catch(err => console.error('[CooldownProbe] pass failed:', err));
+    }, { name: 'cooldown-probe' });
+}
+export function stopCooldownProbe() {
+    if (cancelProbeJob) {
+        cancelProbeJob();
+        cancelProbeJob = null;
+    }
+}
+/** Test seam: drop all per-key probe pacing state. */
+export function resetCooldownProbeState() {
+    keyState.clear();
+}
+//# sourceMappingURL=cooldown-probe.js.map

package/dist/services/cooldown-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cooldown-probe.js","sourceRoot":"","sources":["../../src/services/cooldown-probe.ts"],"names":[],"mappings":"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"}

package/dist/services/custom-endpoint.d.ts

@@ -0,0 +1,58 @@
+import type { Db } from '../db/types.js';
+export interface ResolvedEndpointKey {
+    keyId: number;
+    /** Plaintext of the key now bound to this endpoint — for masking in responses. */
+    storedKey: string;
+    /** True when this call added a credential rather than updating one. */
+    created: boolean;
+}
+/**
+ * Resolve the api_keys row a custom-endpoint registration should bind to,
+ * creating or updating it as needed. Never destroys a stored credential:
+ *  - no key submitted        → reuse the endpoint's first key (label refresh only)
+ *  - a key already on record  → update that row (label / re-enable)
+ *  - a new key, placeholder-only endpoint → replace the placeholder in place
+ *  - a new key, endpoint already has one → INSERT a second credential (#619)
+ *
+ * `pinnedKeyId` lets a caller that already knows WHICH credential of the pool
+ * it is acting for name it — the bulk registration of discovered models (#488)
+ * comes back holding the key row the user fetched the list with. It only
+ * applies when that row really serves this base_url and no new secret was
+ * submitted; a new secret still goes through the rules above.
+ */
+export declare function resolveCustomEndpointKey(db: Db, baseUrl: string, providedKey: string | undefined, label: string | undefined, pinnedKeyId?: number): ResolvedEndpointKey;
+/** True when this endpoint already stores this exact secret. Lets a caller tell
+ *  a genuinely new credential from a re-submit of one already in the pool, which
+ *  `resolveCustomEndpointKey` deliberately treats the same way. */
+export declare function endpointHasCredential(db: Db, baseUrl: string, secret: string): boolean;
+/**
+ * Every api_keys id that serves the SAME custom endpoint as `keyId` — i.e. the
+ * credential pool a model bound to `keyId` may rotate across. Falls back to the
+ * key itself when the row is gone or carries no base_url.
+ */
+export declare function customEndpointKeyIds(db: Db, keyId: number): Set<number>;
+/**
+ * The other key still serving this endpoint once `keyId` is gone, or null when
+ * it was the last one. Used to re-home an endpoint's models instead of deleting
+ * them with the key.
+ */
+export declare function siblingEndpointKeyId(db: Db, keyId: number, baseUrl: string | null): number | null;
+export interface CustomEndpointCredential {
+    keyId: number;
+    baseUrl: string;
+    /** Decrypted secret, or null when the row's ciphertext cannot be decrypted. */
+    apiKey: string | null;
+}
+/**
+ * Every ENABLED custom endpoint, one entry per distinct base_url, carrying its
+ * first stored credential. Used by the scheduled model sync (#674/#663/#656)
+ * to refresh model lists unattended: the manual route asks the operator for a
+ * key mid-typing, but a scheduled pass can only use what the endpoint already
+ * has on record.
+ *
+ * Disabled keys are excluded: turning an endpoint off means "stop using this",
+ * so an unattended pass must not keep polling it and registering new (enabled)
+ * model rows behind the operator's back.
+ */
+export declare function listCustomEndpoints(db: Db): CustomEndpointCredential[];
+//# sourceMappingURL=custom-endpoint.d.ts.map

package/dist/services/custom-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-endpoint.d.ts","sourceRoot":"","sources":["../../src/services/custom-endpoint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAwBzC,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;CAClB;AAgDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,WAAW,CAAC,EAAE,MAAM,GACnB,mBAAmB,CAmCrB;AAED;;mEAEmE;AACnE,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAQjG;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,EAAE,GAAG,wBAAwB,EAAE,CAsBtE"}

package/dist/services/custom-endpoint.js

@@ -0,0 +1,167 @@
+import { encrypt, decrypt } from '../lib/crypto.js';
+// ── Custom OpenAI-compatible endpoints: keys per endpoint ────────────────────
+// A custom endpoint is identified by its base_url and can hold SEVERAL
+// credentials — relay services routinely hand out one key per plan/group, and
+// pooling them is the whole point of adding more than one (#619). Registration
+// therefore matches on (base_url, secret), never on base_url alone: a new
+// secret for a known endpoint INSERTs, it does not overwrite the key already
+// stored. Models still bind to one api_keys row via key_id (#212); the router
+// treats every key sharing that row's base_url as an alternative for the same
+// model, so the binding names the ENDPOINT and the pool rotates underneath it.
+// Stored for endpoints that need no credential (llama.cpp / LM Studio / vLLM
+// with auth off). It is a placeholder, not a secret, so a real key may replace
+// it in place instead of piling up a second row.
+const NO_KEY = 'no-key';
+function endpointKeyRows(db, baseUrl) {
+    return db.prepare(`
+    SELECT id, encrypted_key, iv, auth_tag
+      FROM api_keys
+     WHERE platform = 'custom' AND base_url = ?
+     ORDER BY id
+  `).all(baseUrl);
+}
+function plaintextOf(row) {
+    try {
+        return decrypt(row.encrypted_key, row.iv, row.auth_tag);
+    }
+    catch {
+        return null;
+    }
+}
+function touch(db, id, label) {
+    db.prepare("UPDATE api_keys SET label = COALESCE(?, label), status = 'unknown', enabled = 1 WHERE id = ?")
+        .run(label ?? null, id);
+}
+/**
+ * The name a custom endpoint takes when the operator did not give it one: its
+ * host and port. Every endpoint used to default to the literal 'Custom', so the
+ * panels that identify a key by label alone (analytics, cooldowns, quota
+ * signals) showed a column of identical rows once you ran more than one relay
+ * (#705). The host is what actually tells two endpoints apart.
+ */
+function defaultCustomEndpointLabel(baseUrl) {
+    try {
+        return new URL(baseUrl).host || 'Custom';
+    }
+    catch {
+        return 'Custom';
+    }
+}
+function insertKey(db, baseUrl, secret, label) {
+    const { encrypted, iv, authTag } = encrypt(secret);
+    const r = db.prepare(`
+    INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled, base_url)
+    VALUES ('custom', ?, ?, ?, ?, 'unknown', 1, ?)
+  `).run(label ?? defaultCustomEndpointLabel(baseUrl), encrypted, iv, authTag, baseUrl);
+    return { keyId: Number(r.lastInsertRowid), storedKey: secret, created: true };
+}
+/**
+ * Resolve the api_keys row a custom-endpoint registration should bind to,
+ * creating or updating it as needed. Never destroys a stored credential:
+ *  - no key submitted        → reuse the endpoint's first key (label refresh only)
+ *  - a key already on record  → update that row (label / re-enable)
+ *  - a new key, placeholder-only endpoint → replace the placeholder in place
+ *  - a new key, endpoint already has one → INSERT a second credential (#619)
+ *
+ * `pinnedKeyId` lets a caller that already knows WHICH credential of the pool
+ * it is acting for name it — the bulk registration of discovered models (#488)
+ * comes back holding the key row the user fetched the list with. It only
+ * applies when that row really serves this base_url and no new secret was
+ * submitted; a new secret still goes through the rules above.
+ */
+export function resolveCustomEndpointKey(db, baseUrl, providedKey, label, pinnedKeyId) {
+    const rows = endpointKeyRows(db, baseUrl);
+    const stored = rows.map(row => ({ row, secret: plaintextOf(row) }));
+    if (!providedKey) {
+        const pinned = pinnedKeyId === undefined
+            ? undefined
+            : stored.find(s => s.row.id === pinnedKeyId);
+        const first = pinned ?? stored[0];
+        if (!first)
+            return insertKey(db, baseUrl, NO_KEY, label);
+        touch(db, first.row.id, label);
+        return { keyId: first.row.id, storedKey: first.secret ?? NO_KEY, created: false };
+    }
+    const same = stored.find(s => s.secret === providedKey);
+    if (same) {
+        touch(db, same.row.id, label);
+        return { keyId: same.row.id, storedKey: providedKey, created: false };
+    }
+    // Only placeholders on record: the endpoint was registered without auth and
+    // is being given a key now, so upgrade rather than leave a dead sentinel row.
+    if (stored.length > 0 && stored.every(s => s.secret === NO_KEY)) {
+        const target = stored[0].row;
+        const { encrypted, iv, authTag } = encrypt(providedKey);
+        db.prepare(`
+      UPDATE api_keys
+         SET label = COALESCE(?, label), encrypted_key = ?, iv = ?, auth_tag = ?,
+             status = 'unknown', enabled = 1
+       WHERE id = ?
+    `).run(label ?? null, encrypted, iv, authTag, target.id);
+        return { keyId: target.id, storedKey: providedKey, created: false };
+    }
+    return insertKey(db, baseUrl, providedKey, label);
+}
+/** True when this endpoint already stores this exact secret. Lets a caller tell
+ *  a genuinely new credential from a re-submit of one already in the pool, which
+ *  `resolveCustomEndpointKey` deliberately treats the same way. */
+export function endpointHasCredential(db, baseUrl, secret) {
+    return endpointKeyRows(db, baseUrl).some(row => plaintextOf(row) === secret);
+}
+/**
+ * Every api_keys id that serves the SAME custom endpoint as `keyId` — i.e. the
+ * credential pool a model bound to `keyId` may rotate across. Falls back to the
+ * key itself when the row is gone or carries no base_url.
+ */
+export function customEndpointKeyIds(db, keyId) {
+    const row = db.prepare("SELECT base_url FROM api_keys WHERE id = ?").get(keyId);
+    if (!row?.base_url)
+        return new Set([keyId]);
+    const siblings = db.prepare("SELECT id FROM api_keys WHERE platform = 'custom' AND base_url = ?")
+        .all(row.base_url);
+    return new Set(siblings.map(s => s.id));
+}
+/**
+ * The other key still serving this endpoint once `keyId` is gone, or null when
+ * it was the last one. Used to re-home an endpoint's models instead of deleting
+ * them with the key.
+ */
+export function siblingEndpointKeyId(db, keyId, baseUrl) {
+    if (!baseUrl)
+        return null;
+    const row = db.prepare(`
+    SELECT id FROM api_keys
+     WHERE platform = 'custom' AND base_url = ? AND id != ?
+     ORDER BY id LIMIT 1
+  `).get(baseUrl, keyId);
+    return row?.id ?? null;
+}
+/**
+ * Every ENABLED custom endpoint, one entry per distinct base_url, carrying its
+ * first stored credential. Used by the scheduled model sync (#674/#663/#656)
+ * to refresh model lists unattended: the manual route asks the operator for a
+ * key mid-typing, but a scheduled pass can only use what the endpoint already
+ * has on record.
+ *
+ * Disabled keys are excluded: turning an endpoint off means "stop using this",
+ * so an unattended pass must not keep polling it and registering new (enabled)
+ * model rows behind the operator's back.
+ */
+export function listCustomEndpoints(db) {
+    const rows = db.prepare(`
+    SELECT base_url, id, encrypted_key, iv, auth_tag
+      FROM api_keys
+     WHERE platform = 'custom' AND base_url IS NOT NULL AND enabled = 1
+     ORDER BY base_url, id
+  `).all();
+    const seen = new Set();
+    const out = [];
+    for (const row of rows) {
+        if (seen.has(row.base_url))
+            continue;
+        seen.add(row.base_url);
+        out.push({ keyId: row.id, baseUrl: row.base_url, apiKey: plaintextOf(row) });
+    }
+    return out;
+}
+//# sourceMappingURL=custom-endpoint.js.map

package/dist/services/custom-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-endpoint.js","sourceRoot":"","sources":["../../src/services/custom-endpoint.ts"],"names":[],"mappings":"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"}

package/dist/services/custom-media-register.d.ts

@@ -0,0 +1,22 @@
+import type { Db } from '../db/types.js';
+export type CustomMediaModality = 'image' | 'audio' | 'transcription';
+export interface CustomMediaEntry {
+    modelId: string;
+    displayName: string | null;
+    modality: CustomMediaModality;
+    quotaLabel?: string;
+}
+export interface RegisteredCustomMediaModel {
+    modelDbId: number;
+    model: string;
+    modality: CustomMediaModality;
+    created: boolean;
+}
+/**
+ * Upsert one media model row against an ALREADY-resolved endpoint key, inside
+ * the caller's transaction. media_models identity is (platform, model_id) with
+ * no endpoint_scope — a model already on this endpoint keeps the key it has;
+ * only a move to a different endpoint re-binds it (#619 semantics).
+ */
+export declare function registerCustomMediaModel(db: Db, keyId: number, entry: CustomMediaEntry): RegisteredCustomMediaModel;
+//# sourceMappingURL=custom-media-register.d.ts.map

package/dist/services/custom-media-register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-media-register.d.ts","sourceRoot":"","sources":["../../src/services/custom-media-register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAUzC,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,GAAG,eAAe,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,gBAAgB,GACtB,0BAA0B,CAuC5B"}

package/dist/services/custom-media-register.js

@@ -0,0 +1,45 @@
+import { customEndpointKeyIds } from './custom-endpoint.js';
+/**
+ * Upsert one media model row against an ALREADY-resolved endpoint key, inside
+ * the caller's transaction. media_models identity is (platform, model_id) with
+ * no endpoint_scope — a model already on this endpoint keeps the key it has;
+ * only a move to a different endpoint re-binds it (#619 semantics).
+ */
+export function registerCustomMediaModel(db, keyId, entry) {
+    const endpointKeyIds = customEndpointKeyIds(db, keyId);
+    const modelId = entry.modelId;
+    const quotaLabel = entry.quotaLabel?.trim() || 'custom endpoint';
+    const existingModel = db.prepare(`
+    SELECT id, modality, priority, key_id
+      FROM media_models
+     WHERE platform = 'custom' AND model_id = ?
+     LIMIT 1
+  `).get(modelId);
+    const bindKeyId = existingModel?.key_id != null && endpointKeyIds.has(existingModel.key_id)
+        ? existingModel.key_id
+        : keyId;
+    const priority = existingModel && existingModel.modality === entry.modality
+        ? existingModel.priority
+        : db.prepare('SELECT COALESCE(MAX(priority), 0) AS maxPriority FROM media_models WHERE modality = ?')
+            .get(entry.modality).maxPriority + 1;
+    if (existingModel) {
+        db.prepare(`
+      UPDATE media_models
+         SET display_name = COALESCE(?, display_name),
+             modality = ?,
+             priority = ?,
+             enabled = 1,
+             quota_label = ?,
+             key_id = ?
+       WHERE id = ?
+    `).run(entry.displayName, entry.modality, priority, quotaLabel, bindKeyId, existingModel.id);
+        return { modelDbId: existingModel.id, model: modelId, modality: entry.modality, created: false };
+    }
+    const model = db.prepare(`
+    INSERT INTO media_models
+      (platform, model_id, display_name, modality, priority, enabled, quota_label, key_id)
+    VALUES ('custom', ?, ?, ?, ?, 1, ?, ?)
+  `).run(modelId, entry.displayName ?? modelId, entry.modality, priority, quotaLabel, bindKeyId);
+    return { modelDbId: Number(model.lastInsertRowid), model: modelId, modality: entry.modality, created: true };
+}
+//# sourceMappingURL=custom-media-register.js.map

package/dist/services/custom-media-register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-media-register.js","sourceRoot":"","sources":["../../src/services/custom-media-register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAyB5D;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,EAAM,EACN,KAAa,EACb,KAAuB;IAEvB,MAAM,cAAc,GAAG,oBAAoB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,iBAAiB,CAAC;IAEjE,MAAM,aAAa,GAAG,EAAE,CAAC,OAAO,CAAC;;;;;GAKhC,CAAC,CAAC,GAAG,CAAC,OAAO,CAA0F,CAAC;IACzG,MAAM,SAAS,GAAG,aAAa,EAAE,MAAM,IAAI,IAAI,IAAI,cAAc,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC;QACzF,CAAC,CAAC,aAAa,CAAC,MAAM;QACtB,CAAC,CAAC,KAAK,CAAC;IACV,MAAM,QAAQ,GAAG,aAAa,IAAI,aAAa,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;QACzE,CAAC,CAAC,aAAa,CAAC,QAAQ;QACxB,CAAC,CAAE,EAAE,CAAC,OAAO,CAAC,uFAAuF,CAAC;aACnG,GAAG,CAAC,KAAK,CAAC,QAAQ,CAA6B,CAAC,WAAW,GAAG,CAAC,CAAC;IAErE,IAAI,aAAa,EAAE,CAAC;QAClB,EAAE,CAAC,OAAO,CAAC;;;;;;;;;KASV,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;QAC7F,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACnG,CAAC;IAED,MAAM,KAAK,GAAG,EAAE,CAAC,OAAO,CAAC;;;;GAIxB,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,WAAW,IAAI,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAC/F,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC/G,CAAC"}

package/dist/services/custom-model-register.d.ts

@@ -0,0 +1,50 @@
+import type { Db } from '../db/types.js';
+/** One model to register against a custom endpoint (POST /custom body entry). */
+export interface CustomModelEntry {
+    modelId: string;
+    displayName: string | null;
+    supportsTools?: boolean;
+    supportsVision?: boolean;
+}
+export interface RegisteredCustomModel {
+    modelDbId: number;
+    model: string;
+    displayName: string;
+    supportsTools: boolean;
+    supportsVision: boolean;
+    created: boolean;
+}
+export interface RegisterCustomModelsResult {
+    keyId: number;
+    /** The credential this registration bound to, for masking in responses. */
+    storedKey: string;
+    registered: RegisteredCustomModel[];
+}
+/**
+ * Register (or re-register) models against a custom endpoint inside one
+ * transaction.
+ *
+ * Key rows are matched on (base_url, secret): a new secret for a known
+ * endpoint is a SECOND credential for it, not a replacement (#619), and a
+ * new base_url is a separate provider (#212). Identity is per endpoint
+ * (#651): the same model id on a DIFFERENT relay is a separate row with its
+ * own enabled flag, ranks and stats, instead of silently rebinding the other
+ * endpoint's row. A model already on THIS endpoint keeps the key it has, so
+ * adding a second credential doesn't re-bind it (#619).
+ *
+ * Capability flags: an unset flag binds NULL so COALESCE picks the insert
+ * default (tools 1, vision 0) on a new row and preserves the existing value
+ * on re-registration (#470). An omitted display name binds NULL the same way
+ * — it falls back to the model id on a new row and leaves a name already on
+ * the row alone, so the bulk re-registration behind "Fetch models" (which
+ * posts bare ids) can't wipe names the operator set.
+ */
+export declare function registerCustomModels(db: Db, baseUrl: string, providedKey: string | undefined, label: string | undefined, pinnedKeyId: number | undefined, entries: CustomModelEntry[]): RegisterCustomModelsResult;
+/**
+ * The registration loop itself, against an ALREADY-resolved endpoint key and
+ * inside the caller's transaction. Split out from registerCustomModels so the
+ * bulk key importer (#382) — which resolves its own key and owns a wider
+ * transaction — shares this exact write path instead of keeping a second copy.
+ */
+export declare function registerCustomChatModels(db: Db, baseUrl: string, keyId: number, entries: CustomModelEntry[]): RegisteredCustomModel[];
+//# sourceMappingURL=custom-model-register.d.ts.map

package/dist/services/custom-model-register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-model-register.d.ts","sourceRoot":"","sources":["../../src/services/custom-model-register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAgBzC,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,qBAAqB,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,gBAAgB,EAAE,GAC1B,0BAA0B,CAM5B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EAAE,GAC1B,qBAAqB,EAAE,CAyEzB"}