@skaile/forge-settings 0.0.0-stage → 1.0.0

package/src/runtime/server/provider-service.ts

@@ -0,0 +1,244 @@
+/**
+ * The provider inventory a forge app shows and selects from.
+ *
+ * Every fact here comes out of the AI provider registry the session was handed:
+ * which providers exist, whether one serves chat or speech, where it points,
+ * which credential reference backs it and whether that reference resolves.
+ * forge-settings owns no provider list and no provider-type table any more — an
+ * entry's `kind` is the discriminator, and the registry is the list.
+ *
+ * What forge deliberately does not do here:
+ *
+ *   - **Endpoint probing.** "Does this endpoint accept this key" is the
+ *     runtime's `skaile providers test` / the catalog's entry probe, which
+ *     knows every surface's shape. {@link testAIProviderCredential} answers the
+ *     question forge owns: does the credential reference resolve, and where
+ *     from. That is the failure mode a settings modal must explain.
+ *   - **Live model discovery.** Model lists come from the entry's own
+ *     `model_map`/`capabilities`; harness-backed discovery is
+ *     `listModelsForHarness(harnessId, registry)` in the runtime.
+ */
+
+import type {
+  AIProviderCapabilities,
+  AIProviderCredentialKind,
+  AIProviderKind,
+  AIProviderRegistryView,
+  AIProviderSurface,
+  AIProviderVoiceParams,
+} from "../shared/provider-registry";
+import {
+  entriesOfKind,
+  isEntryEnabled,
+  isVoiceEntry,
+  parseCredentialRef,
+  registryEntries,
+} from "../shared/provider-registry";
+import {
+  type CredentialSource,
+  type CredentialStoreOptions,
+  resolveEntryCredential,
+} from "./credential-store";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** One registry entry, as a settings UI needs to see it. */
+export interface ProviderInfo {
+  /** Registry id — the left half of a `"<providerId>/<modelId>"` selector. */
+  id: string;
+  /** Display name: the entry's `label`, else its id. */
+  name: string;
+  /** What the entry produces. Replaces forge's old llm/stt/tts guesswork. */
+  kind: AIProviderKind;
+  /** Whether the entry's credential resolved to a value in this process. */
+  configured: boolean;
+  /** Which reference form answered — `ambient` means a cloud SDK chain signs. */
+  source: CredentialSource;
+  /** Why the credential did not resolve. Secret-free, safe to render. */
+  error?: string;
+  /** The entry's `credential.ref`. A reference, never a secret. */
+  credentialRef?: string;
+  /** How the credential is presented on the wire. */
+  credentialKind?: AIProviderCredentialKind;
+  /**
+   * Whether the entry's reference is an `env:` one. The variable is shared by
+   * every user of the server, so a settings UI names it rather than pretending
+   * the value behind it is the user's to change.
+   */
+  hasEnvKey: boolean;
+  /** Name of that environment variable, when {@link hasEnvKey}. */
+  envKeyName?: string;
+  /** Endpoint the entry pins, when it pins one. */
+  baseUrl?: string;
+  /** Catalog preset the entry inherits from, when it names one. */
+  preset?: string;
+  /** Wire protocol of an `llm`/`embed` entry (its own or its preset's). */
+  surface?: AIProviderSurface;
+  /** The entry's `enabled` flag; `false` only in a listing with `includeDisabled`. */
+  enabled: boolean;
+  /**
+   * Voice parameters a `kind: stt|tts` entry declares — Deepgram
+   * `{model, language}`, ElevenLabs `{voice_id, output_format}`. A settings UI
+   * shows these as the defaults a per-request override replaces; `llm`/`embed`
+   * entries never carry them.
+   */
+  params?: AIProviderVoiceParams;
+  /** Frozen by the control plane: a lower layer cannot change or disable it. */
+  locked: boolean;
+}
+
+/** One selectable model of one provider. */
+export interface ModelInfo {
+  /** The selector to store in `settings.model`: `"<providerId>/<modelId>"`. */
+  id: string;
+  /** Display name — the logical model id. */
+  name: string;
+  /** Registry id of the entry serving the model. */
+  providerId: string;
+  /** Logical id: the `model_map` key. */
+  modelId: string;
+  /** Provider-side id the logical id maps to. */
+  providerModelId: string;
+  /** Capability facts the entry declares for this model, when any. */
+  capabilities?: AIProviderCapabilities;
+}
+
+/** Result of resolving one entry's credential on demand. */
+export interface ProviderTestResult {
+  /** Whether the credential resolved to a usable value. */
+  ok: boolean;
+  /** Registry id that was tested. */
+  provider: string;
+  /** Which reference form answered. */
+  source: CredentialSource;
+  /** Why it did not resolve. Secret-free. */
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Inventory
+// ---------------------------------------------------------------------------
+
+/** What {@link listAIProviders} resolves credentials against, and which entries it lists. */
+export interface ListAIProvidersOptions extends CredentialStoreOptions {
+  /** List `enabled: false` entries too (a registry editor's view). Default `false`. */
+  includeDisabled?: boolean;
+}
+
+/**
+ * Describe every enabled registry entry, in registry order — every entry with
+ * `includeDisabled`.
+ *
+ * Unconfigured entries are included: an entry whose `env:` variable is missing
+ * is exactly what the user has to see and fix, and hiding it (the pre-5.0.0
+ * behaviour, which filtered on "has a key") turned a typo into an empty list.
+ */
+export function listAIProviders(
+  registry: AIProviderRegistryView,
+  options: ListAIProvidersOptions = {},
+): ProviderInfo[] {
+  const providers: ProviderInfo[] = [];
+  for (const [id, entry] of registryEntries(registry)) {
+    const enabled = isEntryEnabled(entry);
+    if (!enabled && !options.includeDisabled) continue;
+    const resolved = resolveEntryCredential(entry, options);
+    const ref = entry.credential?.ref;
+    const parsed = ref ? parseCredentialRef(ref) : undefined;
+    providers.push({
+      id,
+      name: entry.label?.trim() || id,
+      kind: entry.kind,
+      // No error means usable: a value resolved, none is needed (`kind: none`),
+      // or an ambient cloud chain signs the request.
+      configured: resolved.error === undefined,
+      source: resolved.source,
+      ...(resolved.error ? { error: resolved.error } : {}),
+      ...(ref ? { credentialRef: ref } : {}),
+      ...(entry.credential ? { credentialKind: entry.credential.kind } : {}),
+      hasEnvKey: parsed?.form === "env",
+      ...(parsed?.form === "env" ? { envKeyName: parsed.name } : {}),
+      ...(entry.base_url ? { baseUrl: entry.base_url } : {}),
+      ...(entry.preset ? { preset: entry.preset } : {}),
+      ...(!isVoiceEntry(entry) && entry.surface ? { surface: entry.surface } : {}),
+      enabled,
+      ...(isVoiceEntry(entry) && entry.params ? { params: entry.params } : {}),
+      locked: entry.locked === true,
+    });
+  }
+  return providers;
+}
+
+/**
+ * List the models the registry declares, as `"<providerId>/<modelId>"`
+ * selectors.
+ *
+ * Sourced from each `llm`/`embed` entry's `model_map` (plus any id that only
+ * appears in `capabilities`) — the same two tables the runtime's model-reference
+ * resolver reads, so a selector built from this list always resolves.
+ *
+ * @param providerId - Restrict to one entry; omit for every enabled entry.
+ */
+export function listAIProviderModels(
+  registry: AIProviderRegistryView,
+  providerId?: string,
+): ModelInfo[] {
+  const models: ModelInfo[] = [];
+  for (const kind of ["llm", "embed"] as const) {
+    for (const [id, entry] of entriesOfKind(registry, kind)) {
+      if (providerId && id !== providerId) continue;
+      const logicalIds = new Set([
+        ...Object.keys(entry.model_map ?? {}),
+        ...Object.keys(entry.capabilities ?? {}),
+      ]);
+      for (const modelId of logicalIds) {
+        const capabilities = entry.capabilities?.[modelId];
+        models.push({
+          id: `${id}/${modelId}`,
+          name: modelId,
+          providerId: id,
+          modelId,
+          providerModelId: entry.model_map?.[modelId] ?? modelId,
+          ...(capabilities ? { capabilities } : {}),
+        });
+      }
+    }
+  }
+  return models;
+}
+
+/**
+ * Resolve one entry's credential and report the outcome.
+ *
+ * This is the check behind a settings modal's per-provider indicator: it proves
+ * the reference points at something this server can read, and names the layer
+ * that owns it when it does not (`cmd:` in the spawned runtime, `platform:` in
+ * the control plane).
+ */
+export function testAIProviderCredential(
+  providerId: string,
+  registry: AIProviderRegistryView,
+  options: CredentialStoreOptions = {},
+): ProviderTestResult {
+  const match = registryEntries(registry).find(([id]) => id === providerId);
+  if (!match) {
+    return {
+      ok: false,
+      provider: providerId,
+      source: "none",
+      error: `'${providerId}' is not an entry in this registry`,
+    };
+  }
+  const [, entry] = match;
+  if (!isEntryEnabled(entry)) {
+    return { ok: false, provider: providerId, source: "none", error: "entry is disabled" };
+  }
+  const resolved = resolveEntryCredential(entry, options);
+  return {
+    ok: resolved.error === undefined,
+    provider: providerId,
+    source: resolved.source,
+    ...(resolved.error ? { error: resolved.error } : {}),
+  };
+}

package/src/runtime/server/provider-settings.ts

@@ -0,0 +1,192 @@
+/**
+ * Where a forge app's settings meet the AI provider registry.
+ *
+ * Two jobs:
+ *
+ *   1. **Migration.** A `settings.json` written before the 5.0.0 registry migration holds
+ *      `provider` + a free-text `model`, and an `apiKeys` map of secrets. On
+ *      first load the pair collapses into one `"<providerId>/<modelId>"`
+ *      selector, and the `apiKeys` map is dropped with a warning — a plaintext
+ *      key is never auto-written anywhere; the user moves it into `.env`.
+ *   2. **Voice selection.** `sttProvider`/`ttsProvider` are registry ids of
+ *      `kind: stt|tts` entries; the endpoint and the voice parameters live on
+ *      the entry, and `sttLanguage`/`ttsVoice` are per-request overrides of two
+ *      of those parameters. Resolving all of that used to be three apps'
+ *      worth of hardcoded endpoints and voice ids.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type {
+  AIProviderVoiceEntry,
+  AIProviderVoiceKind,
+  AIProviderVoiceParams,
+  AIProviderRegistryView,
+} from "../shared/provider-registry";
+import {
+  entriesOfKind,
+  selectVoiceEntryId,
+  VOICE_OVERRIDE_PARAM,
+} from "../shared/provider-registry";
+import type { SkaileSettings } from "../shared/settings-types";
+
+/** What {@link migrateLegacyProviderSettings} did to one settings file. */
+export interface LegacySettingsMigration {
+  /** The file that was inspected. */
+  path: string;
+  /** Whether the file was rewritten. */
+  changed: boolean;
+  /** The selector `provider` + `model` collapsed into, when that happened. */
+  model?: string;
+  /** Everything dropped or left untouched, and why. Secret-free. */
+  warnings: string[];
+}
+
+/**
+ * Migrate one legacy `settings.json` in place. Idempotent: a file with no
+ * legacy `provider` and no `apiKeys` is left byte-identical.
+ *
+ * An `apiKeys` map is removed from the file and never stored anywhere else:
+ * the registry holds references only, and a plaintext key has no safe
+ * automatic destination. Each non-empty entry is reported through `warnings`
+ * (without the key) so the user can move it into `.env`.
+ *
+ * @param settingsPath - Absolute path to a `settings.json`.
+ */
+export function migrateLegacyProviderSettings(settingsPath: string): LegacySettingsMigration {
+  const result: LegacySettingsMigration = {
+    path: settingsPath,
+    changed: false,
+    warnings: [],
+  };
+  if (!existsSync(settingsPath)) return result;
+
+  let settings: Record<string, unknown>;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8")) as Record<string, unknown>;
+  } catch (err) {
+    result.warnings.push(`${settingsPath} is not valid JSON (${(err as Error).message})`);
+    return result;
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    result.warnings.push(`${settingsPath} does not contain a settings object`);
+    return result;
+  }
+
+  // ── provider + free-text model → one selector ───────────────────────────
+  const legacyProvider = typeof settings.provider === "string" ? settings.provider.trim() : "";
+  if (legacyProvider) {
+    const model = typeof settings.model === "string" ? settings.model.trim() : "";
+    if (model && !model.includes("/")) {
+      settings.model = `${legacyProvider}/${model}`;
+      result.model = settings.model as string;
+    } else if (!model) {
+      result.warnings.push(
+        `provider '${legacyProvider}' had no model to namespace — the session now resolves ` +
+          "its model through the registry's own order",
+      );
+    }
+    delete settings.provider;
+    result.changed = true;
+  }
+
+  // ── apiKeys map → dropped, never stored ─────────────────────────────────
+  if ("apiKeys" in settings) {
+    const apiKeys = settings.apiKeys;
+    const hasSecret =
+      typeof apiKeys === "object" &&
+      apiKeys !== null &&
+      Object.values(apiKeys).some((value) => typeof value === "string" && value !== "");
+    if (hasSecret) {
+      result.warnings.push(
+        "apiKeys found in settings: move each key into .env and reference it from providers.yml (skaile providers add)",
+      );
+    }
+    delete settings.apiKeys;
+    result.changed = true;
+  }
+
+  if (result.changed) {
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+  }
+  return result;
+}
+
+// ── Voice selection ────────────────────────────────────────────────────────
+
+/** Settings fields that name a voice entry and override its parameters. */
+export type VoiceSettings = Pick<
+  SkaileSettings,
+  "sttProvider" | "ttsProvider" | "sttLanguage" | "ttsVoice"
+>;
+
+/** The `kind: stt|tts` entry a request runs against, with its parameters resolved. */
+export interface VoiceProviderSelection {
+  /** Registry id of the entry. */
+  providerId: string;
+  entry: AIProviderVoiceEntry;
+  /** Endpoint from the entry; absent when the entry inherits its preset's default. */
+  baseUrl?: string;
+  /**
+   * The entry's `params` with overrides applied — Deepgram `{model, language}`,
+   * ElevenLabs `{voice_id, output_format}`. This is the only place a forge app
+   * should read voice defaults from.
+   */
+  params: AIProviderVoiceParams;
+  /** True when settings named no usable entry and registry order decided. */
+  fallback: boolean;
+  /** Non-fatal notes, e.g. settings naming an entry the registry does not have. */
+  warnings: string[];
+}
+
+/**
+ * Resolve which registry entry serves speech-to-text or text-to-speech.
+ *
+ * Selection is `settings.sttProvider`/`settings.ttsProvider`, falling back to
+ * the first enabled entry of that kind in registry order when the setting is
+ * absent or names an entry that is gone — a missing setting must not silence an
+ * app that has a perfectly good entry configured.
+ *
+ * Parameter precedence, lowest first: the entry's `params`, then the settings
+ * overrides (`sttLanguage` → `language`, `ttsVoice` → `voice_id`), then
+ * `overrides` from the request. The per-request override is the contract
+ * forge-concept already honoured and the other apps silently dropped.
+ *
+ * @returns The selection, or `undefined` when the registry has no enabled entry
+ *          of that kind.
+ */
+export function resolveVoiceProvider(
+  registry: AIProviderRegistryView,
+  kind: AIProviderVoiceKind,
+  settings: VoiceSettings = {},
+  overrides: AIProviderVoiceParams = {},
+): VoiceProviderSelection | undefined {
+  const candidates = entriesOfKind(registry, kind);
+  if (candidates.length === 0) return undefined;
+
+  const warnings: string[] = [];
+  const wanted = (kind === "stt" ? settings.sttProvider : settings.ttsProvider)?.trim();
+  const ids = candidates.map(([id]) => id);
+  // `candidates` is non-empty, so the shared rule always names one of these ids.
+  const providerId = selectVoiceEntryId(ids, wanted) as string;
+  const entry = candidates[ids.indexOf(providerId)][1];
+  if (wanted && wanted !== providerId) {
+    warnings.push(
+      `settings name '${wanted}' for ${kind}, which is not an enabled ${kind} entry — ` +
+        `using '${providerId}' instead`,
+    );
+  }
+  const fallback = wanted !== providerId;
+
+  const settingsOverride: AIProviderVoiceParams = {};
+  const override = (kind === "stt" ? settings.sttLanguage : settings.ttsVoice)?.trim();
+  if (override) settingsOverride[VOICE_OVERRIDE_PARAM[kind]] = override;
+
+  return {
+    providerId,
+    entry,
+    ...(entry.base_url ? { baseUrl: entry.base_url } : {}),
+    params: { ...entry.params, ...settingsOverride, ...overrides },
+    fallback,
+    warnings,
+  };
+}