@skaile/forge-settings 1.4.0 → 2.0.0

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

@@ -9,15 +9,15 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import {
-  type AIProviderRegistryPatch,
-  PROVIDERS_FILENAME,
-  saveProviderRegistryFile,
-} from "@skaile/workspaces/core";
-import { AI_PROVIDER_PRESETS, type AIProviderPreset } from "@skaile/workspaces/sdk/bridge";
+import type { AIProviderRegistryPatch } from "@skaile/provider-registry";
+import { AI_PROVIDER_PRESETS, type AIProviderPreset } from "@skaile/provider-registry/catalog";
+import { saveProviderRegistryFile } from "@skaile/provider-registry/files";
 import { parse as parseYaml } from "yaml";
 import { isPlainObject } from "../shared/guards";
 
+/** A layer document's file name, as every registry host spells it. */
+const PROVIDERS_FILENAME = "providers.yml";
+
 /** The `.yaml` spelling of {@link PROVIDERS_FILENAME}. */
 const PROVIDERS_FILENAME_ALIAS = "providers.yaml";
 

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

@@ -23,12 +23,12 @@ import { entryDataZone } from "../shared/data-zone";
 import type {
   AIProviderCapabilities,
   AIProviderCredentialKind,
+  AIProviderDataZone,
   AIProviderKind,
   AIProviderRegistryView,
   AIProviderSurface,
   AIProviderTransport,
   AIProviderVoiceParams,
-  DataZone,
 } from "../shared/provider-registry";
 import {
   entriesOfKind,
@@ -100,7 +100,7 @@ export interface ProviderInfo {
   /** Frozen by the control plane: a lower layer cannot change or disable it. */
   locked: boolean;
   /** Where the entry processes data: its `data_zone`, else its preset's, else `transfer`. */
-  dataZone: DataZone;
+  dataZone: AIProviderDataZone;
   /** The entry's `eu_processing` switch (an `eu_option` entry counts as EU only with it on). */
   euProcessing: boolean;
   /**

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

@@ -28,17 +28,17 @@ import {
   type AIProviderRegistryLayer,
   type AIProviderRegistryPatch,
   isSafeProviderId,
-  loadProviderRegistryFile,
   mergeRegistries,
   parseCredentialRef,
   validateMergedRegistry,
   validateRegistry,
-} from "@skaile/workspaces/core";
+} from "@skaile/provider-registry";
 import {
   AI_PROVIDER_PRESETS,
   type AIProviderPreset,
   expandPreset,
-} from "@skaile/workspaces/sdk/bridge";
+} from "@skaile/provider-registry/catalog";
+import { loadProviderRegistryFile } from "@skaile/provider-registry/files";
 import { isDataZone } from "../shared/data-zone";
 import { isPlainObject } from "../shared/guards";
 import { missingRequiredParams } from "../shared/provider-accounts";

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

@@ -0,0 +1,110 @@
+/**
+ * Voice selection: which `kind: stt|tts` registry entry serves a request and
+ * with which parameters.
+ *
+ * `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 type {
+  AIProviderRegistryView,
+  AIProviderVoiceEntry,
+  AIProviderVoiceKind,
+  AIProviderVoiceParams,
+} from "../shared/provider-registry";
+import {
+  entriesOfKind,
+  selectVoiceEntryId,
+  VOICE_OVERRIDE_PARAM,
+} from "../shared/provider-registry";
+
+/**
+ * Settings fields that name a voice entry and override its parameters — the
+ * same field names as the Workspaces `settings.json` document, so a
+ * `SkaileSettings` (`@skaile/forge-settings/workspaces`) can be passed as is.
+ */
+export interface VoiceSettings {
+  /** Registry id of the `kind: stt` entry. */
+  sttProvider?: string;
+  /** Registry id of the `kind: tts` entry. */
+  ttsProvider?: string;
+  /** Overrides the stt entry's `language` parameter. */
+  sttLanguage?: string;
+  /** Overrides the tts entry's `voice_id` parameter. */
+  ttsVoice?: string;
+}
+
+/** 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,
+  };
+}

package/src/runtime/shared/data-zone.ts

@@ -2,34 +2,36 @@
  * Data zones: where a provider entry processes data, and which entries a
  * host's data-zone rule ("Where may AI process data?") keeps.
  *
- * `@skaile/workspaces` 9.1 owns this (`entryDataZone`,
- * `entryAllowedByDataZone`, `filterRegistryByDataZone` in
- * `bridge/src/provider-catalog.ts`, the `data_zone` of each catalog preset).
- * forge-settings mirrors it here so the settings panel and a host on an older
- * SDK apply the same rule in the browser and on the server. Semantics match
- * upstream exactly; {@link PRESET_DATA_ZONES} is a copy of the catalog's
- * column, and the SDK catalog is its source.
+ * `@skaile/provider-registry` owns the vocabulary (`AI_PROVIDER_DATA_ZONES`,
+ * `AI_PROVIDER_DATA_ZONE_RULES`, re-exported by `./provider-registry`) and the
+ * catalog's `data_zone` column with `entryDataZone`, `entryAllowedByDataZone`
+ * and `filterRegistryByDataZone` in its `/catalog` entry. forge-settings keeps
+ * the browser-side view here so the settings panel does not ship the catalog
+ * (and its generated model table) to the browser: the same semantics, plus
+ * labels, refusal wording and a filter that keeps a merged registry merged.
+ * {@link PRESET_DATA_ZONES} is a copy of the catalog's column; a test holds it
+ * equal to `@skaile/provider-registry/catalog`.
  *
  * Browser-safe on purpose — no `node:` imports.
  */
 
 import {
+  AI_PROVIDER_DATA_ZONE_RULES,
+  AI_PROVIDER_DATA_ZONES,
+  type AIProviderDataZone,
+  type AIProviderDataZoneRule,
   type AIProviderRegistry,
   type AIProviderRegistryView,
-  DATA_ZONE_RULES,
-  DATA_ZONES,
-  type DataZone,
-  type DataZoneRule,
   isMergedRegistry,
   type MergedAIProviderRegistry,
 } from "./provider-registry";
 
 /**
  * The `data_zone` of each catalog preset, by preset id. Copied from
- * `@skaile/workspaces/bridge`'s `AI_PROVIDER_PRESETS` (9.1); change it there
+ * `@skaile/provider-registry/catalog`'s `AI_PROVIDER_PRESETS`; change it there
  * first. A preset this table does not name is `transfer`.
  */
-export const PRESET_DATA_ZONES: Readonly<Record<string, DataZone>> = {
+export const PRESET_DATA_ZONES: Readonly<Record<string, AIProviderDataZone>> = {
   anthropic: "transfer",
   openai: "transfer",
   google: "transfer",
@@ -53,7 +55,7 @@ export const PRESET_DATA_ZONES: Readonly<Record<string, DataZone>> = {
 };
 
 /** What a provider row's zone chip says. */
-export const DATA_ZONE_LABELS: Readonly<Record<DataZone, string>> = {
+export const DATA_ZONE_LABELS: Readonly<Record<AIProviderDataZone, string>> = {
   eu: "EU",
   eu_option: "EU option",
   transfer: "Transfer",
@@ -61,24 +63,26 @@ export const DATA_ZONE_LABELS: Readonly<Record<DataZone, string>> = {
 };
 
 /** What a host calls each rule when it names the rule that keeps an entry out. */
-export const DATA_ZONE_RULE_LABELS: Readonly<Record<DataZoneRule, string>> = {
+export const DATA_ZONE_RULE_LABELS: Readonly<Record<AIProviderDataZoneRule, string>> = {
   any: "Anywhere",
   eu_options: "EU, or EU option with EU processing on",
   eu: "EU only",
 };
 
-/** Whether `value` is one of {@link DATA_ZONES}. */
-export function isDataZone(value: unknown): value is DataZone {
-  return typeof value === "string" && (DATA_ZONES as readonly string[]).includes(value);
+/** Whether `value` is one of `AI_PROVIDER_DATA_ZONES`. */
+export function isDataZone(value: unknown): value is AIProviderDataZone {
+  return typeof value === "string" && (AI_PROVIDER_DATA_ZONES as readonly string[]).includes(value);
 }
 
-/** Whether `value` is one of {@link DATA_ZONE_RULES}. */
-export function isDataZoneRule(value: unknown): value is DataZoneRule {
-  return typeof value === "string" && (DATA_ZONE_RULES as readonly string[]).includes(value);
+/** Whether `value` is one of `AI_PROVIDER_DATA_ZONE_RULES`. */
+export function isDataZoneRule(value: unknown): value is AIProviderDataZoneRule {
+  return (
+    typeof value === "string" && (AI_PROVIDER_DATA_ZONE_RULES as readonly string[]).includes(value)
+  );
 }
 
 /** The zone of catalog preset `presetId`, or `undefined` for an id the catalog does not name. */
-export function presetDataZone(presetId: string | undefined): DataZone | undefined {
+export function presetDataZone(presetId: string | undefined): AIProviderDataZone | undefined {
   return presetId !== undefined && Object.hasOwn(PRESET_DATA_ZONES, presetId)
     ? PRESET_DATA_ZONES[presetId]
     : undefined;
@@ -89,7 +93,10 @@ export function presetDataZone(presetId: string | undefined): DataZone | undefin
  * catalog preset it names, else `transfer` (an unknown endpoint is assumed to
  * leave the EU).
  */
-export function entryDataZone(entry: { data_zone?: DataZone; preset?: string }): DataZone {
+export function entryDataZone(entry: {
+  data_zone?: AIProviderDataZone;
+  preset?: string;
+}): AIProviderDataZone {
   return entry.data_zone ?? presetDataZone(entry.preset) ?? "transfer";
 }
 
@@ -99,8 +106,8 @@ export function entryDataZone(entry: { data_zone?: DataZone; preset?: string }):
  * `euProcessing` is `true`.
  */
 export function dataZoneAllows(
-  rule: DataZoneRule,
-  zone: DataZone,
+  rule: AIProviderDataZoneRule,
+  zone: AIProviderDataZone,
   euProcessing: boolean | undefined,
 ): boolean {
   if (rule === "any") return true;
@@ -110,8 +117,8 @@ export function dataZoneAllows(
 
 /** Whether `rule` allows `entry` ({@link dataZoneAllows} over {@link entryDataZone}). */
 export function entryAllowedByDataZone(
-  entry: { data_zone?: DataZone; preset?: string; eu_processing?: boolean },
-  rule: DataZoneRule,
+  entry: { data_zone?: AIProviderDataZone; preset?: string; eu_processing?: boolean },
+  rule: AIProviderDataZoneRule,
 ): boolean {
   return dataZoneAllows(rule, entryDataZone(entry), entry.eu_processing);
 }
@@ -121,8 +128,8 @@ export function entryAllowedByDataZone(
  * when the rule allows it. Secret-free, safe to render.
  */
 export function dataZoneRefusal(
-  rule: DataZoneRule,
-  zone: DataZone,
+  rule: AIProviderDataZoneRule,
+  zone: AIProviderDataZone,
   euProcessing: boolean | undefined,
 ): string | undefined {
   if (dataZoneAllows(rule, zone, euProcessing)) return undefined;
@@ -141,19 +148,19 @@ export function dataZoneRefusal(
  */
 export function filterRegistryByDataZone(
   registry: AIProviderRegistry,
-  rule: DataZoneRule,
+  rule: AIProviderDataZoneRule,
 ): AIProviderRegistry;
 export function filterRegistryByDataZone(
   registry: MergedAIProviderRegistry,
-  rule: DataZoneRule,
+  rule: AIProviderDataZoneRule,
 ): MergedAIProviderRegistry;
 export function filterRegistryByDataZone(
   registry: AIProviderRegistryView,
-  rule: DataZoneRule,
+  rule: AIProviderDataZoneRule,
 ): AIProviderRegistryView;
 export function filterRegistryByDataZone(
   registry: AIProviderRegistryView,
-  rule: DataZoneRule,
+  rule: AIProviderDataZoneRule,
 ): AIProviderRegistryView {
   const entries = isMergedRegistry(registry) ? registry.providers : registry;
   const providers: AIProviderRegistry = {};

package/src/runtime/shared/harness-providers.ts

@@ -15,9 +15,9 @@
  */
 
 import { DATA_ZONE_RULE_LABELS, dataZoneRefusal, presetDataZone } from "./data-zone";
-import type { DataZone, DataZoneRule } from "./provider-registry";
+import type { AIProviderDataZone, AIProviderDataZoneRule } from "./provider-registry";
 
-/** How many registry entries a harness can run at once (`@skaile/workspaces` `HarnessInfo.providerPlurality`). */
+/** How many registry entries a harness can run at once (`HarnessInfo.providerPlurality` of a Workspaces harness). */
 export type HarnessProviderPlurality = "registry" | "credentials-n" | "single";
 
 /** The slice of a harness the rule reads. `GET /api/agents` rows satisfy it. */
@@ -41,7 +41,7 @@ export interface HarnessProviderCandidate {
   /** Catalog preset; gives the zone when {@link dataZone} is absent. */
   preset?: string;
   /** Effective data zone (`GET /api/providers` rows carry it). Absent: the preset's, else `transfer`. */
-  dataZone?: DataZone;
+  dataZone?: AIProviderDataZone;
   /** The account's EU-processing setting is on. */
   euProcessing?: boolean;
 }
@@ -54,11 +54,11 @@ export interface HarnessProviderBlock {
   id: string;
   reason: HarnessProviderBlockReason;
   /** The rule in force. */
-  rule: DataZoneRule;
+  rule: AIProviderDataZoneRule;
   /** The rule's label ("EU only"). */
   ruleLabel: string;
   /** The entry's effective zone. */
-  zone: DataZone;
+  zone: AIProviderDataZone;
   /** What a settings table shows on the box it cannot tick. Secret-free. */
   message: string;
 }
@@ -66,7 +66,7 @@ export interface HarnessProviderBlock {
 /** What {@link resolveHarnessProviders} applies beyond the surface rule. */
 export interface HarnessProviderOptions {
   /** The host's data-zone rule. Absent: `any`. */
-  dataZoneRule?: DataZoneRule;
+  dataZoneRule?: AIProviderDataZoneRule;
 }
 
 /**
@@ -114,7 +114,7 @@ export function isProviderEligibleForHarness(
 export function harnessProviderBlock(
   harness: HarnessProviderInfo,
   candidate: HarnessProviderCandidate,
-  rule: DataZoneRule | undefined,
+  rule: AIProviderDataZoneRule | undefined,
 ): HarnessProviderBlock | undefined {
   if (!rule || rule === "any" || !isProviderEligibleForHarness(harness, candidate)) {
     return undefined;

package/src/runtime/shared/provider-accounts.ts

@@ -6,7 +6,7 @@
  *
  * Pure and browser-safe: the settings panel and the server's write gate read
  * the same rules. The facts come from the catalog preset
- * (`@skaile/workspaces`' `AIProviderPreset`): its `credential.kind`, its
+ * (`@skaile/provider-registry/catalog`'s `AIProviderPreset`): its `credential.kind`, its
  * `transport`, its default `params` and its `required_params`. The catalog
  * names no list of accepted sign-in kinds, so they are derived here from those
  * facts.