@gaunt-sloth/core 2.0.0-alpha.4 → 2.0.0-alpha.40

package/dist/providers/modelDiscovery.d.ts

@@ -24,6 +24,7 @@
  * `{ providerId, model }` maps directly onto a `RawGthConfig.llm`.
  */
 import { type ConfigType } from '#src/config.js';
+import type { MissingProviderKeyDetails } from '#src/config/providerKeys.js';
 /**
  * Provider identifiers understood by model discovery. These match the provider
  * factory module names (`#src/providers/<id>.js`) and {@link LLMConfig.type},
@@ -49,10 +50,14 @@ export interface ModelInfo {
  *   Covers openai, openrouter, groq, deepseek, xai and ollama (local).
  * - `anthropic` — Anthropic's native `GET /v1/models`
  *   (`{ data: [{ type, id, display_name }] }`) with `x-api-key` auth.
- * - `none`     — no cheap live endpoint; stay on the curated list
- *   (google-genai, vertexai).
+ * - `google`   — Google AI Studio's native ListModels
+ *   (`GET /v1beta/models` → `{ models: [{ name, supportedGenerationMethods }] }`)
+ *   with `x-goog-api-key` auth. Chat capability is decided by a data-driven
+ *   `supportedGenerationMethods` check rather than a name regex (google-genai).
+ * - `none`     — no cheap live endpoint; stay on the curated list (vertexai,
+ *   which authenticates via gcloud ADC rather than an API key).
  */
-export type DiscoveryKind = 'openai' | 'anthropic' | 'none';
+export type DiscoveryKind = 'openai' | 'anthropic' | 'google' | 'none';
 /**
  * Per-provider live-discovery adapter. Bundled on the {@link ProviderDescriptor}
  * so {@link discoverModels} can be fully data-driven.
@@ -112,6 +117,13 @@ export declare const DEFAULT_OLLAMA_HOST = "http://127.0.0.1:11434";
  * Provider registry. The curated `preferredModels` are the models we have
  * tested with Gaunt Sloth's agent loop; defaults mirror the `init` templates in
  * each `#src/providers/<id>.js` factory.
+ *
+ * CFG-22 (2026-07-24): the CLOUD curated lists were trimmed to 1-2 current-gen ids/provider
+ * (head-first = the runtime default via getCuratedFallbackModel). Every surviving cloud id was live
+ * tool-call-validated with a `gth eval` identity matrix (a marker-read that proves a real tool
+ * call), with two exceptions: vertexai (no ADC here → mirrors the google-genai head) and ollama
+ * (local ids, out of the cloud-trim scope — kept as-is, validated against the local daemon if
+ * present). A dead id was caught and dropped: groq's qwen 404'd (`model_not_found`).
  */
 export declare const PROVIDER_DESCRIPTORS: readonly ProviderDescriptor[];
 /**
@@ -140,6 +152,30 @@ export interface DetectedProvider {
  * @returns the matching env var name, or undefined when none is set.
  */
 export declare function findApiKeyEnvVar(descriptor: ProviderDescriptor): string | undefined;
+/**
+ * Decide whether an LLM spec has **no resolvable API key at all** for its provider, and if so
+ * report which provider and which variable names would have supplied one.
+ *
+ * This is the classifier the config loader uses to tell a missing secret apart from a provider
+ * that broke for some other reason, and it answers that question from the ENVIRONMENT rather than
+ * from the text of whatever error a provider SDK happened to throw. Message-sniffing would be
+ * wrong on both sides: SDK wording is not ours to depend on, and several providers word the same
+ * failure differently (some name the variable, some do not).
+ *
+ * Returns `undefined` — meaning "not a missing-key failure" — when any of these hold:
+ * - the provider is unknown here, or authenticates outside an env-var key (vertexai via ADC,
+ *   ollama locally), so there is no key to be missing;
+ * - the config carries an inline `llm.apiKey`;
+ * - the config names an `llm.apiKeyEnvironmentVariable` that IS set;
+ * - any variable the provider accepts is set.
+ *
+ * The last two matter for correctness, not tidiness: classifying a provider outage as a missing
+ * key when a key was in fact present would defeat the whole distinction.
+ */
+export declare function findMissingProviderKey(providerType: string | undefined, llmConfig: {
+    apiKey?: unknown;
+    apiKeyEnvironmentVariable?: unknown;
+} | undefined): MissingProviderKeyDetails | undefined;
 /**
  * Build the {@link ModelInfo} list for a provider given the descriptor and an
  * optional set of model ids known to actually exist (e.g. from a live
@@ -148,9 +184,83 @@ export declare function findApiKeyEnvVar(descriptor: ProviderDescriptor): string
  * - When `discoveredModels` is omitted, the curated `preferredModels` are
  *   returned, all flagged ⭐ preferred.
  * - When provided, every discovered model is listed; those that also appear in
- *   the curated `preferredModels` are flagged ⭐ preferred.
+ *   the curated `preferredModels` are flagged ⭐ preferred. The list is ordered
+ *   **preferred first** (in curated order, so the recommended default sits on top
+ *   and is pre-selected), then every other discovered model **alphabetically** —
+ *   so a large catalog (e.g. OpenRouter's 200+ models) is navigable instead of
+ *   arriving in the endpoint's arbitrary order.
  */
 export declare function buildModelList(descriptor: ProviderDescriptor, discoveredModels?: string[]): ModelInfo[];
+/**
+ * The single fallback source of truth for a provider's default model id (CFG-14).
+ *
+ * Returns the top curated ⭐ `preferredModels` entry for the provider — the one
+ * id that provider factories fall back to when a config carries no `model`, and
+ * the id first-run writes when live discovery is impossible. Centralising it here
+ * means the fallback lives in exactly ONE place (the curated registry above)
+ * instead of being duplicated as a literal in every `providers/<id>.ts`.
+ *
+ * Every registered provider is required to carry at least one curated model, so
+ * this always resolves for a known id; it throws for an unknown provider or a
+ * provider whose `preferredModels` is empty (a developer error — the invariant
+ * that the fallback source is complete would otherwise fail silently).
+ *
+ * @returns the curated default model id (always defined for a known provider).
+ */
+export declare function getCuratedFallbackModel(providerId: ProviderId): string;
+/**
+ * Build the minimal `.gsloth.config.json` body an `init` template writes for a
+ * provider (CFG-14). When `model` is omitted, the `model` key is left OUT of the
+ * config entirely, so the provider factory resolves it at run time from
+ * {@link getCuratedFallbackModel} — the single curated source that tracks the
+ * installed version, rather than a literal frozen into the user's file that 404s
+ * once the model is retired.
+ *
+ * A `$schema` pointer ({@link CONFIG_SCHEMA_POINTER}) is written first so editors offer
+ * autocomplete/validation against the shipped JSON Schema (GS2-1). `$schema` is a known,
+ * runtime-ignored config field (see the zod schema), so it never affects loading.
+ */
+export declare function buildInitConfigContent(providerId: ProviderId, model?: string): string;
+/**
+ * CFG-21 — the timeout for the *interactive* first-run model fetch. The dialog is
+ * blocking on a human who just picked a provider, so it can afford to wait a lot
+ * longer than the background probes for a large cloud catalog (OpenRouter ~300
+ * models) to arrive over a cold connection, rather than losing the 2s race and
+ * silently dropping to a 3-item curated stub. Threaded per-call so ONLY the dialog
+ * uses it — `detectProviders` / `resolveInitModel` stay on the short
+ * {@link DISCOVERY_TIMEOUT_MS} probe (a long global would hang the *provider* step
+ * whenever the local Ollama daemon is down).
+ */
+export declare const INTERACTIVE_MODEL_FETCH_TIMEOUT_MS = 12000;
+/**
+ * Provenance of a returned model list (CFG-21). Distinguishes the three outcomes so
+ * an interactive caller can tell an honest "couldn't reach the provider" degrade
+ * apart from a by-design curated list:
+ *
+ * - `live`     — a successful, non-empty live `/v1/models` query.
+ * - `fallback` — a live query WAS attempted (key present / ollama probed) but
+ *   failed: network error/timeout, non-2xx, or an empty/malformed payload. THIS is
+ *   the "couldn't reach" case the first-run dialog surfaces.
+ * - `curated`  — no live query was attempted, by design: a `kind:'none'` provider
+ *   (vertexai) or a cloud provider with no API key present. The
+ *   curated catalog is the expected result here, NOT a degrade, so the dialog must
+ *   NOT show a "couldn't reach" notice for it.
+ */
+export type ModelDiscoveryStatus = 'live' | 'fallback' | 'curated';
+/** Per-call discovery options (CFG-21). */
+export interface ModelDiscoveryOptions {
+    /**
+     * Live-fetch timeout in ms. Defaults to the short {@link DISCOVERY_TIMEOUT_MS} so
+     * every existing caller is unchanged; the interactive first-run dialog passes the
+     * generous {@link INTERACTIVE_MODEL_FETCH_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
+}
+/** A model list plus its {@link ModelDiscoveryStatus} provenance (CFG-21). */
+export interface ModelDiscoveryResult {
+    models: ModelInfo[];
+    status: ModelDiscoveryStatus;
+}
 /**
  * Discover the models for a single provider.
  *
@@ -158,6 +268,9 @@ export declare function buildModelList(descriptor: ProviderDescriptor, discovere
  * - `kind: 'openai' | 'anthropic'` → fetches the models endpoint with a short
  *   timeout, parses `data[].id`, applies the chat-only `filter`, and overlays
  *   the ⭐ preferred flags via `buildModelList(descriptor, liveIds)`.
+ * - `kind: 'google'` → fetches the native ListModels endpoint, parses
+ *   `models[].name` keeping only `generateContent`-capable entries and stripping
+ *   the `models/` prefix, then overlays the ⭐ preferred flags likewise.
  *
  * Best-effort: any error / non-2xx / malformed / empty payload falls back to
  * the curated list. This function NEVER throws — a bad key must degrade to the
@@ -167,15 +280,49 @@ export declare function buildModelList(descriptor: ProviderDescriptor, discovere
  * the curated catalog is returned directly. Ollama (no key, local daemon) is
  * always probed.
  */
-export declare function discoverModels(providerId: ProviderId): Promise<ModelInfo[]>;
+export declare function discoverModels(providerId: ProviderId, options?: ModelDiscoveryOptions): Promise<ModelInfo[]>;
 /**
  * List the models for a single provider.
  *
  * Live-discovers from the provider's models endpoint where possible (with a
  * curated fallback); returns the curated set for `kind: 'none'` providers. Does
  * not require the provider to be "available".
+ *
+ * `options.timeoutMs` (CFG-21) overrides the default short live-fetch timeout; the
+ * bare `listModels(providerId)` call is unchanged.
+ */
+export declare function listModels(providerId: ProviderId, options?: ModelDiscoveryOptions): Promise<ModelInfo[]>;
+/**
+ * CFG-21 — like {@link discoverModels} but also returns the model list's
+ * {@link ModelDiscoveryStatus} provenance, so an interactive caller (the first-run
+ * dialog) can tell an honest "couldn't reach the provider" degrade (`fallback`)
+ * apart from a by-design curated list (`curated`) and a real live catalog (`live`).
+ * Kept as a separate export so `listModels` / `discoverModels` keep their existing
+ * `(providerId) => ModelInfo[]` signatures other callers rely on.
+ *
+ * Never throws for a discovery failure (that degrades to `fallback`); it only
+ * throws for an unknown provider id, mirroring {@link discoverModels}.
+ */
+export declare function discoverModelsWithProvenance(providerId: ProviderId, options?: ModelDiscoveryOptions): Promise<ModelDiscoveryResult>;
+/**
+ * Resolve the model id that `init` should bake into a generated config for a
+ * provider (CFG-14) — the safeguard against writing a speculative id that 404s
+ * once the model is retired.
+ *
+ * - **Live discovery possible** (a key / running daemon and a responding
+ *   `/v1/models` endpoint): returns a *verified-present* id — the highest-ranked
+ *   curated ⭐ id that is actually in the live list (matched tolerant of an
+ *   `:latest` suffix), or, when no curated id is live, the first live id.
+ * - **Live discovery impossible** (`kind: 'none'`, no key, offline, empty
+ *   catalog): returns `undefined`. This is the ONLY speculative path, and it
+ *   deliberately declines to invent a literal: the caller OMITS `model` so the
+ *   provider factory falls back to {@link getCuratedFallbackModel} at run time
+ *   (a single curated source that upgrades with the installed version).
+ *
+ * Never throws — a bad key or network error degrades to `undefined`, mirroring
+ * {@link discoverModels}.
  */
-export declare function listModels(providerId: ProviderId): Promise<ModelInfo[]>;
+export declare function resolveInitModel(providerId: ProviderId): Promise<string | undefined>;
 /**
  * Detect every known provider on this machine and list its models.
  *