@skaile/forge-settings 1.2.2 → 1.3.1

package/src/runtime/shared/model-roles.ts

@@ -0,0 +1,283 @@
+/**
+ * Model roles: the named purposes a host app picks a model (or voice provider)
+ * for: "the assistant", "the decision model", "speech to text".
+ *
+ * A role is a host-declared slot; the assignment (role id to selector) is host
+ * state, stored wherever the host keeps settings. This module is the catalogue,
+ * the validation of assignments against a provider registry and the resolution
+ * of one role. Browser-safe: no `node:` imports, so a settings page and the
+ * server validate with the same code.
+ */
+
+import { ModelResolutionError } from "../model/errors";
+import {
+  type AIProviderEntry,
+  type AIProviderRegistryView,
+  isEntryEnabled,
+  isMergedRegistry,
+} from "./provider-registry";
+
+/**
+ * What a role assigns, by kind. The registry kinds are `llm | stt | tts |
+ * embed` (see `AIProviderKind`); a role kind maps onto them:
+ *
+ * - `chat`, `decision` and `image` assign a selector `<entryId>/<modelId>` on
+ *   an enabled `llm` registry entry. `image` offers every model of the `llm`
+ *   entries, because model discovery carries no modality.
+ * - `tts` and `stt` assign the *id* of an enabled voice entry of that kind
+ *   (the same ids `selectVoiceEntryId` chooses between).
+ *
+ * Naming against omp's model roles: `decision` is omp's `judge`, `tts` its
+ * `speech`, `stt` its `dictation`.
+ */
+export const MODEL_ROLE_KINDS = ["chat", "decision", "image", "tts", "stt"] as const;
+
+export type ModelRoleKind = (typeof MODEL_ROLE_KINDS)[number];
+
+/** One role a host declares. `enabled: false` hides it and refuses assignments. */
+export interface ModelRoleDefinition {
+  /** Stable key, used in assignments and as the `@role` alias. */
+  id: string;
+  kind: ModelRoleKind;
+  /** Short name a person reads. */
+  label: string;
+  /** What the role is used for. */
+  description: string;
+  enabled: boolean;
+}
+
+/**
+ * Role id to selector: `<entryId>/<modelId>` for `chat`, `decision` and
+ * `image` roles, an entry id for `tts` and `stt` roles. An empty string or an
+ * absent key means unassigned.
+ */
+export type ModelRoleAssignments = Record<string, string>;
+
+/**
+ * Roles most hosts could want beyond their own chat consumers. Spread them into
+ * the host's role list and flip `enabled` on the ones the app uses:
+ *
+ * ```ts
+ * const roles = STANDARD_MODEL_ROLES.map((role) => ({ ...role, enabled: role.id === "stt" }));
+ * ```
+ */
+export const STANDARD_MODEL_ROLES: readonly ModelRoleDefinition[] = [
+  {
+    id: "decision",
+    kind: "decision",
+    label: "Decision model",
+    description:
+      "A small, fast model for classifying and routing: yes/no checks, picking a branch, tagging.",
+    enabled: true,
+  },
+  {
+    id: "image",
+    kind: "image",
+    label: "Image model",
+    description: "Generates or edits images.",
+    enabled: true,
+  },
+  {
+    id: "tts",
+    kind: "tts",
+    label: "Text to speech",
+    description: "The voice provider that reads text aloud.",
+    enabled: true,
+  },
+  {
+    id: "stt",
+    kind: "stt",
+    label: "Speech to text",
+    description: "The voice provider that transcribes spoken input.",
+    enabled: true,
+  },
+];
+
+/** Why an assignment is refused. */
+export type ModelRoleIssueCode =
+  | "unknown_role"
+  | "disabled_role"
+  | "bad_selector"
+  | "entry_missing"
+  | "entry_disabled"
+  | "entry_wrong_kind";
+
+/** One refused assignment, worded for a person; `role` is the assignment key. */
+export interface ModelRoleIssue {
+  role: string;
+  code: ModelRoleIssueCode;
+  message: string;
+}
+
+/** Whether a role kind assigns a voice entry rather than a model. */
+function isVoiceRoleKind(kind: ModelRoleKind): kind is "tts" | "stt" {
+  return kind === "tts" || kind === "stt";
+}
+
+function entryOf(registry: AIProviderRegistryView, id: string): AIProviderEntry | undefined {
+  const entries = isMergedRegistry(registry) ? registry.providers : registry;
+  return Object.hasOwn(entries, id) ? entries[id] : undefined;
+}
+
+/** `<entryId>/<modelId>` split on the first slash; both parts non-empty. */
+function parseSelector(selector: string): { entryId: string; modelId: string } | undefined {
+  const slash = selector.indexOf("/");
+  if (slash <= 0 || slash === selector.length - 1) return undefined;
+  return { entryId: selector.slice(0, slash), modelId: selector.slice(slash + 1) };
+}
+
+/** The declared role with this id, enabled or not. */
+function findRole(
+  roles: readonly ModelRoleDefinition[],
+  id: string,
+): ModelRoleDefinition | undefined {
+  return roles.find((role) => role.id === id);
+}
+
+/** The issue with one non-empty assignment, if any. */
+function assignmentIssue(
+  role: ModelRoleDefinition | undefined,
+  roleId: string,
+  value: string,
+  registry: AIProviderRegistryView,
+): ModelRoleIssue | undefined {
+  const issue = (code: ModelRoleIssueCode, message: string): ModelRoleIssue => ({
+    role: roleId,
+    code,
+    message,
+  });
+  if (!role) return issue("unknown_role", `Model role '${roleId}' does not exist.`);
+  if (!role.enabled) {
+    return issue("disabled_role", `Model role '${role.label}' (${roleId}) is disabled.`);
+  }
+
+  const voice = isVoiceRoleKind(role.kind);
+  let entryId: string;
+  if (voice) {
+    if (value.includes("/")) {
+      return issue(
+        "bad_selector",
+        `Model role '${role.label}' (${roleId}) takes a provider id, not '${value}'.`,
+      );
+    }
+    entryId = value;
+  } else {
+    const parsed = parseSelector(value);
+    if (!parsed) {
+      return issue(
+        "bad_selector",
+        `Model role '${role.label}' (${roleId}) takes '<provider>/<model>', not '${value}'.`,
+      );
+    }
+    entryId = parsed.entryId;
+  }
+
+  const entry = entryOf(registry, entryId);
+  if (!entry) {
+    return issue(
+      "entry_missing",
+      `Model role '${role.label}' (${roleId}) points at provider '${entryId}', which is not in the registry.`,
+    );
+  }
+  if (!isEntryEnabled(entry)) {
+    return issue(
+      "entry_disabled",
+      `Model role '${role.label}' (${roleId}) points at provider '${entryId}', which is disabled.`,
+    );
+  }
+  const wanted = voice ? role.kind : "llm";
+  if (entry.kind !== wanted) {
+    return issue(
+      "entry_wrong_kind",
+      `Model role '${role.label}' (${roleId}) needs a '${wanted}' provider, but '${entryId}' is '${entry.kind}'.`,
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Check assignments against the declared roles and a registry. Unassigned
+ * values (absent or empty) are skipped. At most one issue per role id; the
+ * host turns them into 400s keyed by role.
+ */
+export function validateModelRoleAssignments(
+  roles: readonly ModelRoleDefinition[],
+  assignments: ModelRoleAssignments,
+  registry: AIProviderRegistryView,
+): ModelRoleIssue[] {
+  const issues: ModelRoleIssue[] = [];
+  for (const [roleId, value] of Object.entries(assignments)) {
+    if (!value) continue;
+    const issue = assignmentIssue(findRole(roles, roleId), roleId, value, registry);
+    if (issue) issues.push(issue);
+  }
+  return issues;
+}
+
+/** What a role points at. */
+export type ResolvedModelRole =
+  | { kind: "model"; selector: string; entryId: string }
+  | { kind: "voice"; entryId: string }
+  | { kind: "unassigned" };
+
+/** Inputs of {@link resolveModelRole}. */
+export interface ResolveModelRoleContext {
+  roles: readonly ModelRoleDefinition[];
+  assignments: ModelRoleAssignments;
+  registry: AIProviderRegistryView;
+}
+
+/**
+ * Resolve one role to the registry entry it points at.
+ *
+ * @throws {ModelResolutionError} `unknown_selector` when the role is not
+ *   declared or is disabled, or when its assignment dangles: the entry is
+ *   gone, disabled, of the wrong kind, or the value is malformed.
+ */
+export function resolveModelRole(
+  roleId: string,
+  context: ResolveModelRoleContext,
+): ResolvedModelRole {
+  const role = findRole(context.roles, roleId);
+  if (!role) {
+    throw new ModelResolutionError("unknown_selector", `Model role '${roleId}' does not exist.`);
+  }
+  if (!role.enabled) {
+    throw new ModelResolutionError(
+      "unknown_selector",
+      `Model role '${role.label}' (${roleId}) is disabled.`,
+    );
+  }
+  const value = Object.hasOwn(context.assignments, roleId) ? context.assignments[roleId] : undefined;
+  if (!value) return { kind: "unassigned" };
+
+  const issue = assignmentIssue(role, roleId, value, context.registry);
+  if (issue) {
+    const providerId = isVoiceRoleKind(role.kind) ? value : parseSelector(value)?.entryId;
+    throw new ModelResolutionError("unknown_selector", issue.message, {
+      ...(providerId !== undefined && entryOf(context.registry, providerId) ? { providerId } : {}),
+    });
+  }
+  if (isVoiceRoleKind(role.kind)) return { kind: "voice", entryId: value };
+  return { kind: "model", selector: value, entryId: value.slice(0, value.indexOf("/")) };
+}
+
+/**
+ * The `roles` map `resolveRegistryLanguageModel(selector, { roles })` accepts,
+ * so a `@role` selector reaches the assigned model: role id to selector for
+ * every enabled, assigned `chat`, `decision` and `image` role. Voice roles,
+ * unassigned and disabled roles, and assignments to undeclared roles are left
+ * out. Assignments are not validated here; see {@link validateModelRoleAssignments}.
+ */
+export function modelRoleAliases(
+  roles: readonly ModelRoleDefinition[],
+  assignments: ModelRoleAssignments,
+): Record<string, string> {
+  const aliases: Record<string, string> = {};
+  for (const role of roles) {
+    if (!role.enabled || isVoiceRoleKind(role.kind)) continue;
+    const value = Object.hasOwn(assignments, role.id) ? assignments[role.id] : undefined;
+    if (value) aliases[role.id] = value;
+  }
+  return aliases;
+}

package/src/runtime/vue/index.ts

@@ -10,6 +10,9 @@
 export * from "../shared/env-vars";
 export * from "../shared/harness-providers";
 export * from "../shared/harnesses";
+export * from "../shared/model-roles";
 export * from "../shared/provider-registry";
+export * from "./model-roles-panel";
+export * from "./providers-client";
 export * from "./settings-modal-scope";
 export * from "./useProvidersPanel";

package/src/runtime/vue/model-roles-panel.ts

@@ -0,0 +1,140 @@
+/**
+ * The model-roles panel's logic: which registry entries a role kind offers,
+ * how an assignment splits into provider and model, and what a row shows.
+ * No Vue, no requests, no `node:` imports; `ForgeModelRolesPanel` renders it.
+ */
+
+import type {
+  ModelRoleAssignments,
+  ModelRoleDefinition,
+  ModelRoleKind,
+} from "../shared/model-roles";
+import type { AIProviderKind } from "../shared/provider-registry";
+import type { ProvidersPanelEntry } from "./providers-panel-model";
+
+/** What the roles panel needs of a providers client; `ProvidersPanelClient` satisfies it. */
+export interface ModelRolesPanelClient {
+  /** Merged registry view including disabled entries. */
+  list(): Promise<ProvidersPanelEntry[]>;
+  /** The models one entry offers. */
+  models(id: string): Promise<ModelRolesModelsResult>;
+}
+
+/** The result of `ModelRolesPanelClient.models`. */
+export interface ModelRolesModelsResult {
+  status: "live" | "static" | "unsupported";
+  models: { id: string; name: string }[];
+  message?: string;
+}
+
+/** One option of a provider or model select. */
+export interface ModelRoleOption {
+  label: string;
+  value: string;
+}
+
+/** The registry entry kind a role kind assigns from. */
+export function roleEntryKind(kind: ModelRoleKind): AIProviderKind {
+  if (kind === "tts") return "tts";
+  if (kind === "stt") return "stt";
+  return "llm";
+}
+
+/** Whether the role assigns an entry id (`tts`, `stt`) rather than a model. */
+export function isVoiceRole(kind: ModelRoleKind): boolean {
+  return kind === "tts" || kind === "stt";
+}
+
+/** The enabled entries of the kind this role assigns from. */
+export function entriesForRole(
+  kind: ModelRoleKind,
+  entries: readonly ProvidersPanelEntry[],
+): ProvidersPanelEntry[] {
+  const wanted = roleEntryKind(kind);
+  return entries.filter((entry) => entry.enabled && entry.kind === wanted);
+}
+
+/** `<entryId>/<modelId>`. */
+export function buildSelector(entryId: string, modelId: string): string {
+  return `${entryId}/${modelId}`;
+}
+
+/** Splits on the first slash (model ids may contain slashes); no slash means no model. */
+export function splitSelector(selector: string): { entryId: string; modelId: string } {
+  const slash = selector.indexOf("/");
+  if (slash < 0) return { entryId: selector, modelId: "" };
+  return { entryId: selector.slice(0, slash), modelId: selector.slice(slash + 1) };
+}
+
+/** The assignment of a role; inherited keys such as `constructor` are not assignments. */
+export function assignmentOf(assignments: ModelRoleAssignments, roleId: string): string | undefined {
+  return Object.hasOwn(assignments, roleId) ? assignments[roleId] : undefined;
+}
+
+/** The assignments with one role set; an empty value unassigns it. Never mutates. */
+export function withAssignment(
+  assignments: ModelRoleAssignments,
+  roleId: string,
+  value: string,
+): ModelRoleAssignments {
+  const next: ModelRoleAssignments = { ...assignments };
+  if (value === "") delete next[roleId];
+  else next[roleId] = value;
+  return next;
+}
+
+/** What one row shows. */
+export interface ModelRoleRowState {
+  /** The provider the row has: the pending pick, else the assignment's. Empty when none. */
+  entryId: string;
+  /** The assigned model id (model roles only). */
+  modelId: string;
+  /** Whether the role has an assignment stored. */
+  assigned: boolean;
+  /** Enabled entries of the role's kind, plus the current one when it is unavailable. */
+  providerOptions: ModelRoleOption[];
+  /** Set when `entryId` is not an enabled entry of the role's kind. */
+  warning?: string;
+}
+
+/**
+ * The state of one row. `pendingEntryId` is a provider picked on a model role
+ * before a model exists: an assignment needs both, so the pick lives in the
+ * panel until the model is chosen.
+ */
+export function modelRoleRowState(
+  role: ModelRoleDefinition,
+  assignment: string | undefined,
+  entries: readonly ProvidersPanelEntry[],
+  pendingEntryId?: string,
+): ModelRoleRowState {
+  const value = assignment ?? "";
+  const voice = isVoiceRole(role.kind);
+  const parsed = voice ? { entryId: value, modelId: "" } : splitSelector(value);
+  const entryId = pendingEntryId ?? parsed.entryId;
+  // A pick on another provider drops the old provider's model.
+  const modelId = entryId === parsed.entryId ? parsed.modelId : "";
+  const offered = entriesForRole(role.kind, entries);
+  const providerOptions = offered.map((entry) => ({ label: entry.name, value: entry.id }));
+  let warning: string | undefined;
+  if (entryId !== "" && !offered.some((entry) => entry.id === entryId)) {
+    providerOptions.push({ label: `${entryId} (unavailable)`, value: entryId });
+    warning = `Provider "${entryId}" is not available`;
+  }
+  return { entryId, modelId, assigned: value !== "", providerOptions, warning };
+}
+
+/** Options of a model select; the current model stays listed when the provider no longer offers it. */
+export function modelOptions(
+  models: readonly { id: string; name: string }[],
+  currentModelId: string,
+): ModelRoleOption[] {
+  const options = models.map((model) => ({
+    label: model.name && model.name !== model.id ? `${model.name} (${model.id})` : model.id,
+    value: model.id,
+  }));
+  if (currentModelId !== "" && !models.some((model) => model.id === currentModelId)) {
+    options.push({ label: `${currentModelId} (not listed)`, value: currentModelId });
+  }
+  return options;
+}

package/src/runtime/vue/providers-client.ts

@@ -0,0 +1,100 @@
+/**
+ * The transport of `ForgeProvidersPanel` (and the models of
+ * `ForgeModelRolesPanel`): one method per call the panels make. The default is
+ * {@link urlProvidersClient}, plain `ofetch` against the routes the panel
+ * always used; a host that backs the same screens with something other than
+ * HTTP routes (server actions, RPC) passes its own client. No Vue, no `node:`.
+ */
+
+import { $fetch } from "ofetch";
+import type { EnvSettingsDocument, EnvSettingsUpdate } from "../shared/env-vars";
+import {
+  DEFAULT_PRESETS_URL,
+  type ProvidersPanelEntry,
+  type ProvidersPanelPreset,
+} from "./providers-panel-model";
+
+/** The models of one provider entry, as `ProvidersPanelClient.models` answers. */
+export interface ProviderModelsResult {
+  /**
+   * `live`: asked the provider's own endpoint; `static`: a fixed list from the
+   * catalog; `unsupported`: the entry cannot list models (free-text entry).
+   */
+  status: "live" | "static" | "unsupported";
+  models: { id: string; name: string }[];
+  /** Why the list is empty or not live. Secret-free. */
+  message?: string;
+}
+
+/** The outcome of one provider credential test. */
+export interface ProvidersPanelTestResult {
+  ok: boolean;
+  /** What the provider answered or why it refused. Secret-free. */
+  message: string;
+}
+
+/** Every call `ForgeProvidersPanel` and `ForgeModelRolesPanel` make. */
+export interface ProvidersPanelClient {
+  /** The merged view, disabled entries included. */
+  list(): Promise<ProvidersPanelEntry[]>;
+  /** Presets whose key is set in the scope's environment. */
+  detected(): Promise<ProvidersPanelPreset[]>;
+  /** The catalog presets. */
+  presets(): Promise<ProvidersPanelPreset[]>;
+  /** Create or change an entry; the body is the registry entry's editable fields. */
+  upsert(id: string, body: Record<string, unknown>): Promise<void>;
+  /** Delete an entry of the scope's own document. */
+  remove(id: string): Promise<void>;
+  /** The scope's `.env` document. */
+  environment(): Promise<EnvSettingsDocument>;
+  /** Write variables to the scope's `.env`. */
+  updateEnvironment(update: EnvSettingsUpdate): Promise<void>;
+  /** The models of one entry. */
+  models(id: string): Promise<ProviderModelsResult>;
+  /** Check that the entry's credential works. */
+  test(id: string): Promise<ProvidersPanelTestResult>;
+}
+
+/** The URLs {@link urlProvidersClient} calls. */
+export interface UrlProvidersClientUrls {
+  /** `GET ${providersUrl}?all=1`: the merged view. */
+  providersUrl: string;
+  /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`; `GET .../:id/models`; `POST .../:id/test`. */
+  providersWriteUrl: string;
+  /** Catalog presets. Default `/api/providers/presets`. */
+  presetsUrl?: string;
+  /** The scope's `.env` route. Omitted, `environment` and `updateEnvironment` reject. */
+  environmentUrl?: string;
+}
+
+/**
+ * The HTTP transport: the requests the panel made before it took a client.
+ * `models` and `test` call routes skaile-forge does not serve; they are for
+ * hosts that do.
+ */
+export function urlProvidersClient(urls: UrlProvidersClientUrls): ProvidersPanelClient {
+  const entryUrl = (id: string) => `${urls.providersWriteUrl}/${encodeURIComponent(id)}`;
+  const environmentUrl = (): string => {
+    if (!urls.environmentUrl) throw new Error("This scope has no environment route.");
+    return urls.environmentUrl;
+  };
+  return {
+    list: () =>
+      $fetch(urls.providersUrl, { query: { all: "1" } }) as Promise<ProvidersPanelEntry[]>,
+    detected: () => $fetch(`${urls.providersWriteUrl}/detected`) as Promise<ProvidersPanelPreset[]>,
+    presets: () =>
+      $fetch(urls.presetsUrl ?? DEFAULT_PRESETS_URL) as Promise<ProvidersPanelPreset[]>,
+    upsert: async (id, body) => {
+      await $fetch(entryUrl(id), { method: "PUT", body });
+    },
+    remove: async (id) => {
+      await $fetch(entryUrl(id), { method: "DELETE" });
+    },
+    environment: async () => (await $fetch(environmentUrl())) as EnvSettingsDocument,
+    updateEnvironment: async (update) => {
+      await $fetch(environmentUrl(), { method: "PUT", body: update });
+    },
+    models: (id) => $fetch(`${entryUrl(id)}/models`) as Promise<ProviderModelsResult>,
+    test: (id) => $fetch(`${entryUrl(id)}/test`, { method: "POST" }) as Promise<ProvidersPanelTestResult>,
+  };
+}

package/src/runtime/vue/providers-panel-model.ts

@@ -11,16 +11,23 @@ import type {
   AIProviderKind,
   AIProviderSurface,
 } from "../shared/provider-registry";
+import type { ProvidersPanelClient } from "./providers-client";
 
 /** Registry document a provider entry is defined in. */
 export type ProvidersPanelLayer = "instance" | "workspace";
 
 /** Props both `ForgeProvidersPanel` variants declare. */
 export interface ProvidersPanelProps {
-  /** `GET` merged view for this scope (`/api/providers` | `/api/workspaces/:id/providers`). */
-  providersUrl: string;
-  /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`. */
-  providersWriteUrl: string;
+  /**
+   * The panel's transport. Without it the panel talks to the URL props below
+   * through {@link urlProvidersClient}; with it the URL props are ignored. An
+   * explicit client also turns on the per-row Test button.
+   */
+  client?: ProvidersPanelClient;
+  /** `GET` merged view for this scope (`/api/providers` | `/api/workspaces/:id/providers`). Required without `client`. */
+  providersUrl?: string;
+  /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`. Required without `client`. */
+  providersWriteUrl?: string;
   /** Catalog preset summaries. Default `/api/providers/presets`. */
   presetsUrl?: string;
   /**
@@ -28,10 +35,21 @@ export interface ProvidersPanelProps {
    * into the panel write through it. Omitted, no key can be entered.
    */
   environmentUrl?: string;
+  /**
+   * Whether the panel reads and writes the scope's environment (key entry,
+   * the environment document). Default: `Boolean(environmentUrl)` without
+   * `client`, `true` with one.
+   */
+  environmentEnabled?: boolean;
   /** The scope's own registry document. */
   layer: ProvidersPanelLayer;
   /** Disables every write (non-admin at instance scope; provider lock). */
   readOnly?: boolean;
+  /**
+   * The line above the provider list. Absent: the panel's own text for
+   * `layer`; a string replaces it; `false` hides it (Add provider stays).
+   */
+  note?: string | false;
 }
 
 /** Emits both variants declare. */
@@ -148,6 +166,18 @@ export const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
 
 export const DEFAULT_PRESETS_URL = "/api/providers/presets";
 
+/** The line `ForgeProvidersPanel` shows above its list; `null` = none. */
+export function providersPanelNote(
+  note: string | false | undefined,
+  layer: ProvidersPanelLayer,
+): string | null {
+  if (note === false) return null;
+  if (note !== undefined) return note;
+  return layer === "workspace"
+    ? "Entries of this workspace's providers.yml can be changed here; instance entries are inherited. Keys stay in the environment; an entry only references them."
+    : "The instance registry, $FORGE_HOME/.skaile/providers.yml. Keys stay in the environment; an entry only references them.";
+}
+
 /** An `env:NAME` credential reference; group 1 is the variable name. */
 export const ENV_REF_PATTERN = /^env:(.+)$/;