@maci0/dsh-google-vertex 0.0.0-stage → 0.12.5

package/lib/auth.js

@@ -0,0 +1,246 @@
+/**
+ * Service-account authentication for Google APIs: read one credentials file,
+ * sign a JWT with its private key, trade it for an OAuth access token, and
+ * cache that token until shortly before it expires.
+ *
+ * The harness credential plane stores API keys, while a Vertex deployment
+ * typically holds a service-account JSON instead: the file is the credential.
+ * That is why this module exists rather than a credential reference: nothing in
+ * the harness can turn an RSA key into a bearer token on the request path.
+ *
+ * Everything here is pure enough to test without a network: the token endpoint
+ * transport and the clock are injectable. The scope every request needs and the
+ * early-refresh margin are fixed, because nothing has ever needed to vary them:
+ * one Vertex route and one margin are what this plugin talks to.
+ *
+ * @module dsh-google-vertex/auth
+ */
+import { createSign } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+/** Scope every Vertex AI request needs; the token carries nothing narrower. */
+export const CLOUD_PLATFORM_SCOPE = 'https://www.googleapis.com/auth/cloud-platform';
+/** Token endpoint a service-account file names; this is the public default. */
+const DEFAULT_TOKEN_URI = 'https://oauth2.googleapis.com/token';
+/** Assertion lifetime Google accepts; the token endpoint caps it at one hour. */
+const ASSERTION_LIFETIME_SECONDS = 3600;
+/**
+ * Refresh this long before the reported expiry so a request cannot start with a
+ * token that dies in flight.
+ */
+const DEFAULT_REFRESH_MARGIN_MS = 5 * 60 * 1000;
+/** An auth failure the adapter reports as `AUTH` or `TRANSPORT`. */
+export class VertexAuthError extends Error {
+    /** Provider-neutral failure code the adapter forwards. */
+    code;
+    /**
+     * @param code - whether the failure is a credential problem or a transport one.
+     * @param message - operator-facing detail.
+     */
+    constructor(code, message) {
+        super(message);
+        this.name = 'VertexAuthError';
+        this.code = code;
+    }
+}
+/**
+ * Expand a leading `~` to the process home directory.
+ *
+ * The path arrives from configuration, which is written by a human the same way
+ * a shell is: `~/.secrets/vertex.json` means the home directory, not a literal
+ * directory named `~`.
+ * @param path - configured path, possibly home-relative.
+ * @returns an absolute path.
+ */
+export function expandHome(path) {
+    if (path === '~')
+        return homedir();
+    if (path.startsWith('~/'))
+        return join(homedir(), path.slice(2));
+    return isAbsolute(path) ? path : join(process.cwd(), path);
+}
+/**
+ * Parse a service-account document, refusing one this module cannot sign with.
+ *
+ * `name` is the path the text came from, so the failure tells an operator which
+ * file to fix rather than only which field is wrong.
+ * @param raw - the file's text.
+ * @param name - source path used in failure messages.
+ * @returns the parsed account.
+ * @throws {Error} when the document is not JSON or lacks a signing key.
+ */
+export function parseServiceAccount(raw, name) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`google-vertex: service account file ${name} is not valid JSON`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`google-vertex: service account file ${name} must contain a JSON object`);
+    }
+    const account = parsed;
+    const clientEmail = account['client_email'];
+    const privateKey = account['private_key'];
+    if (typeof clientEmail !== 'string' || clientEmail.length === 0) {
+        throw new Error(`google-vertex: service account file ${name} has no "client_email"`);
+    }
+    if (typeof privateKey !== 'string' || !privateKey.includes('BEGIN PRIVATE KEY')) {
+        throw new Error(`google-vertex: service account file ${name} has no usable "private_key"`);
+    }
+    const keyId = account['private_key_id'];
+    const projectId = account['project_id'];
+    const tokenUri = account['token_uri'];
+    return {
+        client_email: clientEmail,
+        private_key: privateKey,
+        ...typeof keyId === 'string' && keyId.length > 0 ? { private_key_id: keyId } : {},
+        ...typeof projectId === 'string' && projectId.length > 0 ? { project_id: projectId } : {},
+        ...typeof tokenUri === 'string' && tokenUri.length > 0 ? { token_uri: tokenUri } : {},
+    };
+}
+/**
+ * Read and parse one service-account file.
+ *
+ * Read synchronously on purpose: this runs once at plugin mount, where a typo'd
+ * path must fail loudly and immediately rather than as an opaque transport error
+ * on the first message.
+ * @param path - configured path, possibly home-relative.
+ * @returns the parsed account.
+ * @throws {Error} when the file is unreadable or unusable.
+ */
+export function loadServiceAccount(path) {
+    const resolved = expandHome(path);
+    let raw;
+    try {
+        raw = readFileSync(resolved, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`google-vertex: cannot read service account file ${resolved}`
+            + `: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parseServiceAccount(raw, resolved);
+}
+/** base64url of one JSON value, the JWT segment encoding. */
+function base64urlJson(value) {
+    return Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+}
+/**
+ * Sign the JWT-bearer assertion for one service account.
+ * @param account - the credentials to sign with.
+ * @param nowSeconds - current time from the injected clock.
+ * @param scope - OAuth scope the token is requested for.
+ * @returns the signed assertion.
+ */
+export function signedAssertion(account, nowSeconds, scope) {
+    const header = {
+        alg: 'RS256',
+        typ: 'JWT',
+        ...account.private_key_id === undefined ? {} : { kid: account.private_key_id },
+    };
+    const claims = {
+        iss: account.client_email,
+        scope,
+        aud: account.token_uri ?? DEFAULT_TOKEN_URI,
+        iat: nowSeconds,
+        exp: nowSeconds + ASSERTION_LIFETIME_SECONDS,
+    };
+    const signingInput = `${base64urlJson(header)}.${base64urlJson(claims)}`;
+    const signer = createSign('RSA-SHA256');
+    signer.update(signingInput);
+    const signature = signer.sign(account.private_key, 'base64url');
+    return `${signingInput}.${signature}`;
+}
+/**
+ * Access tokens for one service account, refreshed on demand.
+ *
+ * Concurrent callers share one mint in flight, so a first turn with parallel
+ * requests does not sign one assertion per request.
+ */
+export class ServiceAccountTokens {
+    #account;
+    #fetch;
+    #now;
+    #cached;
+    #pending;
+    /**
+     * @param account - the parsed service-account credentials.
+     * @param options - injectable transport and clock.
+     */
+    constructor(account, options = {}) {
+        this.#account = account;
+        this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.#now = options.now ?? (() => Date.now());
+    }
+    /**
+     * A currently valid access token, minting one when the cache is cold or stale.
+     * @param signal - cancellation for the first caller's mint; waiters attached
+     *   to an in-flight mint are cancelled only by that mint, which is the
+     *   accepted ceiling of sharing one token (a per-caller mint would remove it).
+     * @returns the bearer token.
+     * @throws {VertexAuthError} `AUTH` for a refused credential, `TRANSPORT` when
+     *   the token endpoint could not be reached or answered unusably.
+     */
+    async get(signal) {
+        const cached = this.#cached;
+        if (cached !== undefined && this.#now() < cached.expiresAt - DEFAULT_REFRESH_MARGIN_MS)
+            return cached.value;
+        const pending = this.#pending ?? this.#mint(signal);
+        this.#pending = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            if (this.#pending === pending)
+                this.#pending = undefined;
+        }
+    }
+    /** Mint one token and cache it. */
+    async #mint(signal) {
+        const nowSeconds = Math.floor(this.#now() / 1000);
+        const assertion = signedAssertion(this.#account, nowSeconds, CLOUD_PLATFORM_SCOPE);
+        const tokenUri = this.#account.token_uri ?? DEFAULT_TOKEN_URI;
+        let response;
+        try {
+            response = await this.#fetch(tokenUri, {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({
+                    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+                    assertion,
+                }).toString(),
+                ...signal === undefined ? {} : { signal },
+            });
+        }
+        catch (error) {
+            if (signal?.aborted === true) {
+                throw new VertexAuthError('TRANSPORT', 'google-vertex: token request aborted');
+            }
+            throw new VertexAuthError('TRANSPORT', `google-vertex: token endpoint unreachable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const text = await response.text().catch(() => '');
+        if (!response.ok) {
+            throw new VertexAuthError(response.status === 408 || response.status === 429 || response.status >= 500 ? 'TRANSPORT' : 'AUTH', `google-vertex: token endpoint failed (HTTP ${response.status})`
+                + `${text.length > 0 ? `: ${text.slice(0, 300)}` : ''}`);
+        }
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            throw new VertexAuthError('TRANSPORT', 'google-vertex: token endpoint answered with a non-JSON body');
+        }
+        const fields = (typeof payload === 'object' && payload !== null ? payload : {});
+        const token = fields['access_token'];
+        if (typeof token !== 'string' || token.length === 0) {
+            throw new VertexAuthError('TRANSPORT', `google-vertex: token endpoint answered without an access_token`);
+        }
+        const expiresIn = typeof fields['expires_in'] === 'number' && fields['expires_in'] > 0
+            ? fields['expires_in']
+            : ASSERTION_LIFETIME_SECONDS;
+        this.#cached = { value: token, expiresAt: this.#now() + expiresIn * 1000 };
+        return token;
+    }
+}

package/lib/client.js

@@ -0,0 +1,206 @@
+/**
+ * dsh-google-vertex browser half: the plugin's configuration page on the
+ * Plugins page, under the bundle's `google-vertex` row, and the Refresh control
+ * that lives on it.
+ *
+ * The Gemini adapter on the host half discovers its catalog at runtime behind a
+ * five-minute cache, so a model Google published a minute ago is invisible to
+ * the model picker until that cache expires. This half has exactly one way to
+ * reach the host process (a write to the `google-vertex` settings namespace
+ * the host half registers), so the button writes the current time there. The
+ * host's change hook drops both cached catalogs, and the settings commit also
+ * makes the model picker re-read the catalog from the host. No restart, no
+ * harness change.
+ *
+ * The page contract takes `summary` (the one-liner the page prints under the
+ * row's module) and `page` (the controls); the page draws the title and the
+ * crumb itself, so this half draws neither. `plugins.row.config` is keyed by
+ * `<package name>#<row id>`, which is the key below.
+ *
+ * This file is plain JavaScript on purpose. The client module system serves a
+ * package's `exports["./client"]` artifact as a lazy-CJS factory registered on
+ * `window.__ModuleLoader__`, and that is the whole format: an out-of-tree
+ * plugin can author it directly instead of reproducing the repository's tsdown
+ * client preset. `react` is provided by the module system; nothing else is
+ * required here.
+ */
+
+window.__ModuleLoader__.load({
+  id: '@maci0/dsh-google-vertex',
+
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const React = require('react')
+
+    /** Settings namespace shared with the host half. */
+    const NAMESPACE = 'google-vertex'
+
+    /** Locale namespace for this plugin's copy. */
+    const LOCALE_NS = 'google-vertex'
+
+    /** The Plugins-page slot this card occupies. */
+    const SLOT = 'plugins.row.config'
+
+    /**
+     * The slot's key: the bundle's package name and the row id its patch
+     * declares (`rowConfigKey` in the page's own contract). A deployment that
+     * installs this package under another name shows no configure control,
+     * which is the whole trace of a mismatch.
+     */
+    const ENTRY_KEY = '@maci0/dsh-google-vertex#google-vertex'
+
+    /** Every class is `gv-`-prefixed: the sheet lands in the page's own document. */
+    const CSS = [
+      '.gv-page{display:flex;flex-direction:column;gap:10px}',
+      '.gv-hint{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}',
+      '.gv-row{display:flex;align-items:center;flex-wrap:wrap;gap:10px}',
+      '.gv-action{appearance:none;font:inherit;font-size:13px;line-height:1.5;padding:5px 14px;cursor:pointer;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-4);border:1px solid var(--dsw-alias-border-l2);border-radius:999px}',
+      '.gv-action:disabled{cursor:default;opacity:.5}',
+      '.gv-status{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}',
+      '.gv-error{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-error)}',
+    ].join('')
+
+    // Appended while the factory materializes: the module system claims the tag
+    // for this package and disposes it on unload. Guarded because the node unit
+    // tests evaluate this file without a DOM.
+    if (typeof document !== 'undefined') {
+      const style = document.createElement('style')
+      style.textContent = CSS
+      document.head.append(style)
+    }
+
+    const en = {
+      summary: 'Google-hosted Claude and Gemini models, discovered from Vertex at runtime.',
+      refresh: 'Refresh models',
+      hint: 'Re-reads the catalog from Vertex, then refreshes the model picker. No restart.',
+      lastRefresh: 'Last manual refresh: {at}',
+      never: 'No manual refresh yet.',
+      refused: 'The Host refused the refresh. Try again.',
+      readOnly: 'Settings are not persisted in this deployment, so this control cannot reach the host. Restart dsh web to re-discover.',
+    }
+
+    const zh = {
+      summary: '由 Vertex 托管的 Claude 与 Gemini 模型，运行时动态发现。',
+      refresh: '刷新模型',
+      hint: '从 Vertex 重新读取模型目录，并刷新模型选择器。无需重启。',
+      lastRefresh: '上次手动刷新：{at}',
+      never: '尚未手动刷新。',
+      refused: 'Host 拒绝了刷新，请重试。',
+      readOnly: '此部署不持久化设置，该控件无法通知宿主进程。请重启 dsh web 以重新发现。',
+    }
+
+    /**
+     * Bind one scope to a React subscription.
+     * @param scope - a scope bound to the google-vertex settings namespace.
+     * @returns a hook reading that scope's current snapshot.
+     */
+    function useScope(scope) {
+      const subscribe = (listener) => scope.subscribe(listener)
+      const getSnapshot = () => scope.getSnapshot()
+      return () => React.useSyncExternalStore(subscribe, getSnapshot)
+    }
+
+    /**
+     * Read a snapshot's value. A namespace the deployment does not serve reports
+     * no value, which the card renders as nothing at all.
+     * @param snapshot - the settings scope snapshot.
+     * @returns the stored value object, or `undefined` when unreadable.
+     */
+    function valueOf(snapshot) {
+      if (snapshot.status !== 'ready') return undefined
+      return snapshot.value !== null && typeof snapshot.value === 'object' ? snapshot.value : {}
+    }
+
+    /**
+     * Build the card component over one bound settings scope.
+     * @param scope - the scope bound to the google-vertex namespace.
+     * @param t - translate function bound to this plugin's locale namespace.
+     * @returns the component the page renders in either view.
+     */
+    function createCard(scope, t) {
+      const useSettings = useScope(scope)
+
+      return function GoogleVertexCard({ view }) {
+        const snapshot = useSettings()
+        const [error, setError] = React.useState(null)
+
+        const value = valueOf(snapshot)
+        // A namespace this deployment does not serve renders no trace of itself.
+        if (value === undefined) return null
+        if (view === 'summary') return t('summary')
+
+        const refresh = () => {
+          setError(null)
+          new Promise((resolve) => { resolve(scope.set('revalidatedAt', new Date().toISOString())) }).then((accepted) => {
+            if (accepted === false) setError(t('refused'))
+          }).catch((cause) => {
+            setError(cause instanceof Error ? cause.message : String(cause))
+          })
+        }
+
+        const stamp = typeof value.revalidatedAt === 'string' && value.revalidatedAt.length > 0
+          ? new Date(value.revalidatedAt)
+          : undefined
+        const last = stamp !== undefined && !Number.isNaN(stamp.getTime())
+          ? t('lastRefresh', { at: stamp.toLocaleString() })
+          : t('never')
+
+        return React.createElement(
+          'div',
+          { className: 'gv-page' },
+          React.createElement('p', { className: 'gv-hint' }, t('hint')),
+          React.createElement(
+            'div',
+            { className: 'gv-row' },
+            React.createElement(
+              'button',
+              {
+                type: 'button',
+                className: 'gv-action',
+                disabled: !snapshot.writable,
+                onClick: refresh,
+              },
+              t('refresh'),
+            ),
+            React.createElement(
+              'span',
+              { className: 'gv-status' },
+              snapshot.writable ? last : t('readOnly'),
+            ),
+          ),
+          error === null ? null : React.createElement('p', { className: 'gv-error' }, error),
+        )
+      }
+    }
+
+    /**
+     * Mount the card: this plugin's row configuration on the Plugins page.
+     * @param ctx - the browser plugin context.
+     */
+    function apply(ctx) {
+      const t = ctx.locale.bind(LOCALE_NS)
+      ctx.effect(
+        () => ctx.locale.register(LOCALE_NS, { en, zh }),
+        'dsh-google-vertex: locale dictionary',
+      )
+
+      const scope = ctx.configForms.get(NAMESPACE)
+      const Card = createCard(scope, t)
+
+      // The page declares the slot; injecting waits for it to exist, so this
+      // registration does not depend on plugin load order.
+      ctx.slots.inject(SLOT, () => ctx.slots.register({
+        name: SLOT,
+        key: ENTRY_KEY,
+        locale: LOCALE_NS,
+      }, Card))
+    }
+
+    exports.apply = apply
+    exports.inject = ['slots', 'configForms', 'locale']
+    return module.exports
+  },
+})

package/lib/discovery.js

@@ -0,0 +1,180 @@
+/**
+ * Dynamic model discovery for Vertex AI publisher endpoints.
+ *
+ * Gemini models are fetched from the Vertex Model Garden catalog API
+ * (`publishers/google/models`). Anthropic models have no listing endpoint on
+ * Vertex, so the adapter serves the catalog from configuration instead.
+ *
+ * Results are cached for five minutes so the model picker does not
+ * make a network call on every open.
+ *
+ * @module dsh-google-vertex/discovery
+ */
+import { DEFAULT_GEMINI_MODELS } from './gemini.js';
+import { endpointOrigin } from './wire.js';
+/** How long a cached model list stays valid, in milliseconds. */
+export const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Vertex API version for the model list endpoint. `publishers.models.list`
+ * exists only in v1beta1; v1 serves `get` alone.
+ */
+const API_VERSION = 'v1beta1';
+/** Most catalog pages read before giving up on a misbehaving endpoint. */
+const MAX_PAGES = 10;
+/**
+ * Id segments naming a Gemini variant this text route cannot drive: embedding,
+ * speech, image output, and the Live API.
+ */
+const NON_TEXT_SEGMENTS = new Set(['embedding', 'tts', 'image', 'live', 'audio']);
+/**
+ * Extract the model id from a Vertex resource name.
+ *
+ * A resource name looks like `publishers/google/models/gemini-2.5-pro`: the
+ * model id is the last segment. A name without a `/` is returned as-is.
+ * @param resourceName - the `name` field from the catalog entry.
+ * @returns the bare model id.
+ */
+function modelIdFromResource(resourceName) {
+    const lastSlash = resourceName.lastIndexOf('/');
+    return lastSlash >= 0 ? resourceName.slice(lastSlash + 1) : resourceName;
+}
+/**
+ * True for a Gemini id this route can serve: the publisher catalog also lists
+ * Imagen, Veo, embedding, and speech models.
+ * @param id - bare model id.
+ */
+function isGeminiTextModel(id) {
+    return id.startsWith('gemini-') && !id.split('-').some(segment => NON_TEXT_SEGMENTS.has(segment));
+}
+/**
+ * Build the URL that lists publisher models for one publisher.
+ * @param location - configured Vertex region, or `global`.
+ * @param publisher - publisher name, e.g. `google`.
+ * @returns the absolute list URL.
+ */
+function listModelsUrl(location, publisher) {
+    const origin = endpointOrigin(location);
+    return `${origin}/${API_VERSION}/publishers/${encodeURIComponent(publisher)}/models`;
+}
+/**
+ * Fetch one page of publisher models from the Vertex Model Garden catalog.
+ * @param url - the list endpoint URL, possibly with a pageToken.
+ * @param token - bearer token for authentication.
+ * @param fetchFn - transport.
+ * @param signal - caller cancellation.
+ * @returns the parsed response.
+ */
+async function fetchPage(url, token, fetchFn, signal) {
+    const response = await fetchFn(url, {
+        method: 'GET',
+        headers: {
+            'authorization': `Bearer ${token}`,
+            'accept': 'application/json',
+        },
+        ...signal === undefined ? {} : { signal },
+    });
+    if (!response.ok) {
+        throw new Error(`google-vertex: model list failed (HTTP ${response.status})`);
+    }
+    const body = await response.json();
+    if (typeof body !== 'object' || body === null)
+        return {};
+    return body;
+}
+/**
+ * Fetch the Gemini text models from Vertex's `publishers/google/models` list.
+ *
+ * Follows pagination and keeps `gemini-` ids minus the variants named in
+ * {@link NON_TEXT_SEGMENTS}. A built-in id keeps its built-in name; any other
+ * is named by its id.
+ * @param location - configured Vertex region, or `global`.
+ * @param tokens - token source for bearer authentication.
+ * @param fetchFn - transport.
+ * @param signal - caller cancellation.
+ * @returns model ids and display names, in catalog order.
+ */
+export async function fetchGeminiModels(location, tokens, fetchFn, signal) {
+    const bearer = await tokens.get(signal);
+    const models = [];
+    const url = listModelsUrl(location, 'google');
+    let pageToken;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const pageUrl = pageToken !== undefined ? `${url}?pageToken=${encodeURIComponent(pageToken)}` : url;
+        const response = await fetchPage(pageUrl, bearer, fetchFn, signal);
+        for (const entry of response.publisherModels ?? []) {
+            if (typeof entry.name !== 'string')
+                continue;
+            const id = modelIdFromResource(entry.name);
+            if (!isGeminiTextModel(id))
+                continue;
+            models.push(DEFAULT_GEMINI_MODELS.find(model => model.id === id) ?? { id, name: `${id} (Vertex)` });
+        }
+        pageToken = response.nextPageToken;
+        if (pageToken === undefined || pageToken.length === 0)
+            break;
+    }
+    return models;
+}
+/**
+ * A cached, TTL-bounded model list that falls back to a static default when
+ * the remote fetch fails.
+ *
+ * Only the Gemini adapter fetches: Vertex has no Anthropic model listing
+ * endpoint, so that route serves its configured catalog without one and never
+ * calls this.
+ */
+export class ModelCache {
+    #fallback;
+    #cached;
+    #inflight;
+    /**
+     * @param fallback - static default returned when the fetch fails or is not
+     *   attempted.
+     */
+    constructor(fallback) {
+        this.#fallback = fallback;
+    }
+    /**
+     * Return the cached model list, or fetch a fresh one.
+     *
+     * When a fetch function is provided and the cache is stale, it is called to
+     * produce a fresh list. On failure, the fallback is returned. Concurrent
+     * callers share one in-flight fetch.
+     * @param fetchFn - optional async function that returns a fresh model list.
+     * @returns the model list, from cache, fetch, or fallback.
+     */
+    async get(fetchFn) {
+        // Return cached if still valid.
+        const cached = this.#cached;
+        if (cached !== undefined && Date.now() < cached.expiresAt)
+            return cached.models;
+        // No fetch function means static-only.
+        if (fetchFn === undefined)
+            return this.#fallback;
+        // Share one in-flight fetch.
+        if (this.#inflight !== undefined)
+            return this.#inflight;
+        const operation = fetchFn().then((models) => {
+            if (models.length > 0) {
+                if (this.#inflight === operation)
+                    this.#cached = { models, expiresAt: Date.now() + DEFAULT_CACHE_TTL_MS };
+                return models;
+            }
+            // Empty result: use fallback rather than showing nothing.
+            return this.#fallback;
+        }).catch(() => {
+            // Network failure: serve fallback silently.
+            return this.#cached?.models ?? this.#fallback;
+        }).finally(() => {
+            if (this.#inflight === operation)
+                this.#inflight = undefined;
+        });
+        this.#inflight = operation;
+        return operation;
+    }
+    /** Force the next `get` to re-fetch. */
+    invalidate() {
+        this.#cached = undefined;
+        this.#inflight = undefined;
+    }
+}