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

package/lib/index.js

@@ -0,0 +1,196 @@
+/**
+ * dsh-google-vertex: use Google-hosted models from Vertex AI inside DeepSeek
+ * Harness, authenticated with a service-account file.
+ *
+ * Two capabilities, one configuration row: an `ctx.llm` provider adapter for
+ * Vertex's Anthropic publisher endpoint (Claude) and one for its Google
+ * publisher endpoint (Gemini). Registering them makes both routes selectable in
+ * the Web client's model picker, because `buildModelCatalog()` enumerates
+ * `ctx.llm.listProviders()` and asks each adapter for `listModels()` /
+ * `resolveModel()`.
+ *
+ * A third: the `google-vertex` settings namespace. The Gemini adapter discovers
+ * its catalog at runtime behind a five-minute cache, and a browser half has no
+ * other way to reach this process, so the namespace's one write (the Refresh
+ * control on this plugin's row page under Plugins) is what drops that cache
+ * on demand.
+ *
+ * The credential is the service-account JSON itself: a path in configuration,
+ * or `GOOGLE_APPLICATION_CREDENTIALS` in the launch environment. Nothing is
+ * copied into the harness credential store, and the file is read once at mount
+ * so a typo fails loudly instead of on the first message.
+ *
+ * @module dsh-google-vertex
+ */
+import Schema from '@deepseek-ai/schemastery';
+import { GoogleVertexAnthropicAdapter } from './adapter.js';
+import { loadServiceAccount } from './auth.js';
+import { ServiceAccountTokens } from './auth.js';
+import { fetchGeminiModels } from './discovery.js';
+import { DEFAULT_GEMINI_CONTEXT_WINDOW, DEFAULT_GEMINI_MAX_TOKENS, DEFAULT_GEMINI_MODELS } from './gemini.js';
+import { GoogleVertexGeminiAdapter } from './gemini_adapter.js';
+import { DEFAULT_LOCATION, DEFAULT_STREAM_IDLE_TIMEOUT_MS, MAX_TIMER_DELAY_MS } from './wire.js';
+/** Plugin name as it appears in the loader. */
+export const name = 'google-vertex';
+/** The `ctx.llm` route serving Google-hosted Anthropic (Claude) models. */
+export const PROVIDER = 'google-vertex-anthropic';
+/** The `ctx.llm` route serving Gemini models. */
+export const GEMINI_PROVIDER = 'google-vertex-gemini';
+/**
+ * Settings namespace the browser half's card edits: the join key between the
+ * two halves. The card registers into `plugins.row.config` under this namespace,
+ * and the settings tab pairs the two without knowing what the namespace means.
+ */
+export const GOOGLE_VERTEX_SETTINGS_NAMESPACE = 'google-vertex';
+/** The one service this plugin needs mounted. */
+export const inject = ['llm'];
+/**
+ * Claude models Vertex serves, in picker order. Ids are the provider's own
+ * aliases, which track the newest dated release of each family and need no
+ * edit when Vertex promotes one; the catalog is overridable from configuration
+ * for a deployment that pins dated versions or uses a different listing.
+ */
+export const DEFAULT_MODELS = [
+    { id: 'claude-opus-4-6', name: 'Claude Opus 4.6 (Vertex)' },
+    { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6 (Vertex)' },
+    { id: 'claude-opus-4-5', name: 'Claude Opus 4.5 (Vertex)' },
+    { id: 'claude-sonnet-4-5', name: 'Claude Sonnet 4.5 (Vertex)' },
+    { id: 'claude-haiku-4-5', name: 'Claude Haiku 4.5 (Vertex)' },
+];
+/** Context capacity reported for every Claude model; every listed family serves 200k. */
+export const DEFAULT_CONTEXT_WINDOW = 200_000;
+/**
+ * Output cap used when a caller omits one. Well under the models' 64k ceiling:
+ * an agent turn rarely needs more, and the harness enforces its own budget.
+ */
+export const DEFAULT_MAX_TOKENS = 32_000;
+/**
+ * Row schema: defaults live here, so a deployment only states what it changes.
+ *
+ * `serviceAccountFile`, `project`, `models`, and `geminiModels` carry no
+ * `.default()`: the first two fall back to the environment, and an omitted
+ * catalog materializes empty, which `resolveConfig` treats exactly like an
+ * absent one and replaces with the built-in list.
+ *
+ * `revalidatedAt` is volatile (the only kind of field the settings document
+ * accepts) and carries no default: absence means "never refreshed manually".
+ */
+export const Config = Schema.object({
+    serviceAccountFile: Schema.string(),
+    project: Schema.string(),
+    location: Schema.string().default(DEFAULT_LOCATION),
+    models: Schema.array(Schema.string()),
+    geminiModels: Schema.array(Schema.string()),
+    contextWindow: Schema.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
+    maxTokens: Schema.number().step(1).min(1).default(DEFAULT_MAX_TOKENS),
+    streamIdleTimeoutMs: Schema.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+    revalidatedAt: Schema.string().volatile(),
+});
+/**
+ * Validate and normalize one configuration row.
+ *
+ * Invalid values throw rather than being silently defaulted: a typo'd path or
+ * project would otherwise present as an opaque provider error mid-turn.
+ * @param config - raw row values, as a profile patch or an unwrapped row.
+ * @param env - environment consulted for the credential and region defaults.
+ * @returns the resolved adapter configuration.
+ */
+export function resolveConfig(config = {}, env = process.env) {
+    // The exported schema is the one source of the numeric defaults and bounds.
+    // The credential path, the project, and the region keep their environment
+    // fallbacks, so they are read off the raw row instead.
+    const filled = Config(config);
+    const serviceAccountFile = filled.serviceAccountFile ?? env['GOOGLE_APPLICATION_CREDENTIALS'];
+    if (serviceAccountFile === undefined || serviceAccountFile.trim().length === 0) {
+        throw new Error('google-vertex: no service account configured: set serviceAccountFile in this plugin\'s row,'
+            + ' or export GOOGLE_APPLICATION_CREDENTIALS to a service-account JSON path');
+    }
+    const serviceAccount = loadServiceAccount(serviceAccountFile);
+    const project = filled.project
+        ?? env['GOOGLE_CLOUD_PROJECT']
+        ?? env['GCLOUD_PROJECT']
+        ?? serviceAccount.project_id;
+    if (project === undefined || project.trim().length === 0) {
+        throw new Error(`google-vertex: no project configured: set project in this plugin's row, or export`
+            + ` GOOGLE_CLOUD_PROJECT, or use a service-account file that carries "project_id"`);
+    }
+    const location = config.location ?? env['GOOGLE_CLOUD_LOCATION'] ?? DEFAULT_LOCATION;
+    if (location.trim().length === 0 || !/^[a-z0-9-]+$/.test(location)) {
+        throw new Error(`google-vertex: location "${location}" is not a valid Vertex region`);
+    }
+    const ids = filled.models === undefined || filled.models.length === 0
+        ? DEFAULT_MODELS
+        : filled.models.map(id => ({ id, name: id }));
+    for (const model of ids) {
+        if (model.id.trim().length === 0)
+            throw new Error('google-vertex: model ids must be non-empty strings');
+    }
+    const geminiIds = filled.geminiModels === undefined || filled.geminiModels.length === 0
+        ? DEFAULT_GEMINI_MODELS.map(model => model.id)
+        : filled.geminiModels;
+    const geminiModels = geminiIds.map((id) => {
+        if (id.trim().length === 0)
+            throw new Error('google-vertex: geminiModels ids must be non-empty strings');
+        // A configured id keeps the built-in entry's wording when it is one of them;
+        // every model serves the same capacities, which live on the wire config.
+        return DEFAULT_GEMINI_MODELS.find(model => model.id === id) ?? { id, name: id };
+    });
+    const streamIdleTimeoutMs = filled.streamIdleTimeoutMs;
+    return {
+        serviceAccountFile,
+        anthropic: {
+            serviceAccount,
+            project,
+            location,
+            models: ids,
+            contextWindow: filled.contextWindow,
+            maxTokens: filled.maxTokens,
+            streamIdleTimeoutMs,
+        },
+        gemini: {
+            serviceAccount,
+            project,
+            location,
+            models: geminiModels,
+            maxTokens: DEFAULT_GEMINI_MAX_TOKENS,
+            streamIdleTimeoutMs,
+        },
+    };
+}
+/**
+ * Mount both adapters.
+ * @param ctx - host context; `ctx.llm` must be mounted (`inject` guarantees it).
+ * @param config - this plugin's row, as the schema emits it.
+ */
+export function apply(ctx, config) {
+    // The volatile stamp stays a live reference: the schema refuses one, and the
+    // host never reads the value, so the plain row is what gets resolved.
+    const { revalidatedAt: _revalidation, ...row } = config;
+    const resolved = resolveConfig(row);
+    const { anthropic, gemini } = resolved;
+    // Only the Gemini route discovers: Vertex has no Anthropic listing endpoint,
+    // so the Claude catalog is the configured (or built-in) list itself. A
+    // configured `geminiModels` is likewise served as written, never replaced by
+    // the discovered catalog.
+    const fetchFn = (input, init) => globalThis.fetch(input, init);
+    const tokenSource = new ServiceAccountTokens(anthropic.serviceAccount, { fetch: fetchFn });
+    const pinnedGemini = row.geminiModels !== undefined && row.geminiModels.length > 0;
+    const discoverGemini = pinnedGemini
+        ? undefined
+        : () => fetchGeminiModels(gemini.location, tokenSource, fetchFn, AbortSignal.timeout(Math.ceil(gemini.streamIdleTimeoutMs)));
+    const anthropicAdapter = new GoogleVertexAnthropicAdapter(anthropic);
+    const geminiAdapter = new GoogleVertexGeminiAdapter(gemini, discoverGemini === undefined ? {} : { discover: discoverGemini });
+    ctx.llm.registerAdapter([PROVIDER], anthropicAdapter);
+    ctx.llm.registerAdapter([GEMINI_PROVIDER], geminiAdapter);
+    // A profile edit of `revalidatedAt` drops both cached catalogs.
+    if (typeof ctx.on === 'function') {
+        ctx.on('loader/volatile-update', () => {
+            anthropicAdapter.invalidateModels();
+            geminiAdapter.invalidateModels();
+        });
+    }
+    ctx.logger.info(`google-vertex: providers "${PROVIDER}" and "${GEMINI_PROVIDER}" registered for project ${anthropic.project}`
+        + ` (location ${anthropic.location}, credentials ${resolved.serviceAccountFile})`
+        + `. Claude: ${anthropic.models.map(model => model.id).join(', ')}`
+        + `. Gemini: ${gemini.models.map(model => model.id).join(', ')}${pinnedGemini ? '' : ' (+ live discovery)'}`);
+}

package/lib/types/adapter.d.ts

@@ -0,0 +1,219 @@
+/**
+ * The machinery both Vertex publisher adapters share, plus the Claude route's
+ * own adapter: one metadata face the harness calls on every dispatch, and one
+ * streaming pipeline carrying the per-read idle watchdog, the token mint, the
+ * fetch, the refusal classification, the SSE loop, and the single-terminal-chunk
+ * guarantee.
+ *
+ * Two things separate the Claude route from the pi-ai-backed `google-vertex`
+ * route the harness already ships. Its credential is a service-account file,
+ * turned into a bearer token per request by {@link ServiceAccountTokens} rather
+ * than typed in as an API key. And its models are Claude, which Vertex serves
+ * through `publishers/anthropic`, a path and body the Gemini protocol cannot
+ * express.
+ *
+ * Both routes are text-only: `inputModalities: ['text']` makes `LlmRuntime`
+ * project images and files to placeholder text before dispatch, which is honest
+ * about what these adapters send.
+ *
+ * The two routes differ in exactly three things: how a request is addressed
+ * and built, what the provider's payloads mean, and what a body that ends
+ * without a terminal event should be called. Each is an injected callback;
+ * everything else lives here once.
+ *
+ * @module dsh-google-vertex/adapter
+ */
+import type { FetchLike, ServiceAccount } from './auth.ts';
+import type { GenerateOptions, LlmAdapterLike, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, StreamChunk } from './host.ts';
+/** One advertised model. */
+export interface VertexModel {
+    readonly id: string;
+    readonly name: string;
+}
+/**
+ * The token source the adapter asks for a bearer token before each request.
+ * Structural so a test can answer with a fixed token; {@link ServiceAccountTokens}
+ * is the production implementation.
+ */
+export interface TokenProvider {
+    get(signal?: AbortSignal): Promise<string>;
+}
+/**
+ * Configuration every Vertex adapter row carries. The Claude route adds only
+ * its context window; the model capacities of a Gemini route live on the
+ * catalog entries, which is why `models` is typed loosely here.
+ */
+interface VertexAdapterConfig {
+    readonly serviceAccount: ServiceAccount;
+    readonly project: string;
+    readonly location: string;
+    readonly models: readonly VertexModel[];
+    /** Output cap applied when a caller omits `maxTokens`. */
+    readonly maxTokens: number;
+    /** Bound on the interval between two stream reads, in milliseconds. */
+    readonly streamIdleTimeoutMs: number;
+}
+/** Resolved adapter configuration for the Claude route. */
+export interface VertexAnthropicConfig extends VertexAdapterConfig {
+    /** Maximum combined request and response context reported for every model. */
+    readonly contextWindow: number;
+}
+/**
+ * What separates one publisher route from the other, as one parameter set: the
+ * display name, the description wording, and the capacities `resolveModel`
+ * reports for a model id.
+ */
+interface AdapterMetadata<C extends VertexAdapterConfig> {
+    /** Display name the model picker shows for this route. */
+    readonly providerName: string;
+    /** Context window and output cap reported for every model on this route. */
+    readonly capacity: {
+        contextWindow: number;
+        defaultMaxTokens: number;
+    };
+    /** Model description reported for this route, project and region included. */
+    readonly describe: (config: C) => string;
+}
+/**
+ * One provider translator, as the shared pump reads it.
+ *
+ * `handle` is the only method that can emit a terminal chunk: an Anthropic
+ * `message_stop` and a Gemini in-band error both do. `terminal` then reports
+ * that it, or the watchdog, already ended the turn, so the pump never adds a
+ * second finish. A route whose terminal event is not the only way a body ends
+ * (Gemini streams whole chunks and simply stops) narrows the truncation
+ * question with `sawFinish`: did the provider itself report that the turn was
+ * complete? A stream that ends without one is truncated. When absent, the pump
+ * falls back to `terminal`.
+ */
+interface StreamTranslatorLike {
+    handle(event: Record<string, unknown>): Iterable<StreamChunk>;
+    readonly terminal: boolean;
+    readonly sawFinish?: boolean;
+    /** Terminal chunks a provider that closes its body with data needs. */
+    finish?(): Iterable<StreamChunk>;
+}
+/** Everything one streaming call varies between the two publisher routes. */
+interface StreamPumpOptions {
+    /** The request URL for the chosen model. */
+    readonly endpoint: (model: string, config: VertexAdapterConfig) => string;
+    /** The request body for the chosen model. */
+    readonly body: (options: GenerateOptions, config: VertexAdapterConfig) => unknown;
+    /** Failure named when the body ended without the provider's finish. */
+    readonly truncatedMessage: (model: string) => string;
+}
+/**
+ * One streaming completion, shared by both publisher routes.
+ *
+ * The bearer token is minted before the request, so a credentials failure is
+ * reported as a terminal finish rather than as a thrown error escaping the
+ * generator; `LlmRuntime` would turn a throw into a finish too, but would code
+ * it `UNKNOWN` and lose the `AUTH` versus `TRANSPORT` classification.
+ *
+ * Every read is bounded by `streamIdleTimeoutMs`: a provider that stops sending
+ * is a terminal `TIMEOUT` rather than a turn that never ends. The watchdog owns
+ * its own controller so the stalled read can be torn down; the caller's signal
+ * is combined with it when present. The token mint is armed and cleared with
+ * the same bound, because it is a network call too.
+ *
+ * Exactly one terminal chunk leaves this stream. A body that ended without the
+ * provider's terminal event is a truncated response, unless the watchdog or the
+ * caller ended the turn, which is the more specific account of the same missing
+ * event.
+ * @param config - the resolved configuration this adapter serves.
+ * @param options - the harness request.
+ * @param fetch - transport, already defaulted by the adapter.
+ * @param tokens - token source, already defaulted by the adapter.
+ * @param makeTranslator - builds this route's payload translator for one model.
+ * @param pump - this route's endpoint, body, and terminal wording.
+ * @yields every chunk the provider's stream completes.
+ */
+export declare function streamVertex(config: VertexAdapterConfig, options: GenerateOptions, fetch: FetchLike, tokens: TokenProvider, makeTranslator: (model: string) => StreamTranslatorLike, pump: StreamPumpOptions): AsyncGenerator<StreamChunk>;
+/**
+ * Duck-typed base for both Vertex publisher adapters.
+ *
+ * `LlmRuntime` reaches adapters through plain method calls, so these objects
+ * need no harness base class; the plugin's only runtime `@deepseek-ai/*`
+ * dependency is `@deepseek-ai/dsh-llm`'s pure `attributionHeaders()` helper.
+ * The metadata face below is identical for both routes, so it is written once
+ * and parameterized by {@link AdapterMetadata}.
+ */
+export declare abstract class VertexPublisherAdapter<C extends VertexAdapterConfig> implements LlmAdapterLike {
+    #private;
+    /** The config this adapter serves, for the stream pipeline below. */
+    protected readonly config: C;
+    /** The transport this adapter was built with. */
+    protected readonly fetch: FetchLike;
+    /** The token source this adapter asks before each request. */
+    protected readonly tokens: TokenProvider;
+    /**
+     * @param metadata - display name, capacities, and description text.
+     * @param config - the resolved configuration this adapter serves.
+     * @param options - transport, token-source, and discovery overrides.
+     */
+    constructor(metadata: AdapterMetadata<C>, config: C, options?: {
+        fetch?: FetchLike;
+        tokens?: TokenProvider;
+        discover?: () => Promise<readonly VertexModel[]>;
+    });
+    /** {@inheritDoc LlmAdapterLike.providerInfo} */
+    providerInfo(provider: string): LlmProviderInfo;
+    /**
+     * No provider-owned retry policy: Vertex's own 429s carry a quota code the
+     * harness already classifies, and a per-request backoff belongs to the
+     * harness defaults.
+     *
+     * This and {@link imageRequestPricing} exist because `LlmRuntime` calls them
+     * on every dispatch; a duck-typed adapter must supply them or the first
+     * registration throws.
+     */
+    providerRetryPolicy(_provider: string): undefined;
+    /** No route charges visual tokens: these adapters are text-only. */
+    imageRequestPricing(_provider: string, _model: string): undefined;
+    /**
+     * The current model catalog, fetched from the provider when discovery is
+     * configured, falling back to the static catalog on failure.
+     *
+     * The result is cached with a five-minute TTL so the model picker does
+     * not make a network call on every open.
+     */
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * Drop the cached catalog, so the next `listModels` re-discovers from the
+     * provider. Both adapters answer the plugin's manual refresh with this.
+     */
+    invalidateModels(): void;
+    /** {@inheritDoc LlmAdapterLike.resolveModel} */
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /** {@inheritDoc LlmAdapterLike.prepareCall} */
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    /** Stream one completion through this route's publisher endpoint. */
+    abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/**
+ * Duck-typed adapter over Vertex's Anthropic publisher endpoint.
+ *
+ * The route is text-only and declares no server-executed tools, and every
+ * Claude family in the default catalog serves the same 200k context, so a
+ * model's capacities are the configured pair rather than a per-model entry.
+ */
+export declare class GoogleVertexAnthropicAdapter extends VertexPublisherAdapter<VertexAnthropicConfig> {
+    /**
+     * @param config - the resolved configuration this adapter serves.
+     * @param options - transport, token-source, and discovery overrides for tests.
+     */
+    constructor(config: VertexAnthropicConfig, options?: {
+        fetch?: FetchLike;
+        tokens?: TokenProvider;
+        discover?: () => Promise<readonly VertexModel[]>;
+    });
+    /**
+     * Stream one completion through `:streamRawPredict`.
+     *
+     * The shared pump owns the watchdog, the token mint, the SSE loop, and the
+     * single terminal chunk; `message_stop` closes the turn mid-body, so this
+     * route's finish rides that event.
+     */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+export {};

package/lib/types/auth.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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
+ */
+/** Scope every Vertex AI request needs; the token carries nothing narrower. */
+export declare const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+/** Injectable transport, so tests never touch the network. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** The fields of a service-account JSON this module reads. */
+export interface ServiceAccount {
+    readonly client_email: string;
+    readonly private_key: string;
+    readonly private_key_id?: string;
+    readonly project_id?: string;
+    readonly token_uri?: string;
+}
+/** An auth failure the adapter reports as `AUTH` or `TRANSPORT`. */
+export declare class VertexAuthError extends Error {
+    /** Provider-neutral failure code the adapter forwards. */
+    readonly code: 'AUTH' | 'TRANSPORT';
+    /**
+     * @param code - whether the failure is a credential problem or a transport one.
+     * @param message - operator-facing detail.
+     */
+    constructor(code: 'AUTH' | 'TRANSPORT', message: string);
+}
+/**
+ * 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 declare function expandHome(path: string): string;
+/**
+ * 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 declare function parseServiceAccount(raw: string, name: string): ServiceAccount;
+/**
+ * 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 declare function loadServiceAccount(path: string): ServiceAccount;
+/**
+ * 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 declare function signedAssertion(account: ServiceAccount, nowSeconds: number, scope: string): string;
+/** Options for {@link ServiceAccountTokens}. */
+interface TokenSourceOptions {
+    /** Transport; defaults to the process `fetch`. */
+    fetch?: FetchLike;
+    /** Clock in milliseconds; defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * 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 declare class ServiceAccountTokens {
+    #private;
+    /**
+     * @param account - the parsed service-account credentials.
+     * @param options - injectable transport and clock.
+     */
+    constructor(account: ServiceAccount, options?: TokenSourceOptions);
+    /**
+     * 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.
+     */
+    get(signal?: AbortSignal): Promise<string>;
+}
+export {};

package/lib/types/discovery.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 type { FetchLike } from './auth.ts';
+import type { TokenProvider, VertexModel } from './adapter.ts';
+/** How long a cached model list stays valid, in milliseconds. */
+export declare const DEFAULT_CACHE_TTL_MS: number;
+/**
+ * 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 declare function fetchGeminiModels(location: string, tokens: TokenProvider, fetchFn: FetchLike, signal?: AbortSignal): Promise<readonly VertexModel[]>;
+/**
+ * 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 declare class ModelCache {
+    #private;
+    /**
+     * @param fallback - static default returned when the fetch fails or is not
+     *   attempted.
+     */
+    constructor(fallback: readonly VertexModel[]);
+    /**
+     * 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.
+     */
+    get(fetchFn?: () => Promise<readonly VertexModel[]>): Promise<readonly VertexModel[]>;
+    /** Force the next `get` to re-fetch. */
+    invalidate(): void;
+}