@skaile/forge-settings 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.3.0
+
+- Model roles (`/server` and `/vue`, browser-safe): `MODEL_ROLE_KINDS` (`chat`, `decision`, `image`, `tts`, `stt`), `ModelRoleDefinition`, `STANDARD_MODEL_ROLES` (`decision`, `image`, `tts`, `stt`), `validateModelRoleAssignments` (issues keyed by role id), `resolveModelRole` and `modelRoleAliases` (feeds `resolveRegistryLanguageModel({ roles })`). A dangling assignment throws `ModelResolutionError` (`unknown_selector`). omp naming: `decision` = `judge`, `tts` = `speech`, `stt` = `dictation`.
+- `/vue`: `ProvidersPanelClient` and `urlProvidersClient`. `<ForgeProvidersPanel>` takes an optional `client` prop (the URL props build the same client as before, so existing hosts need no change; they become optional when `client` is set) and, with a client, a per-provider Test button.
+- `/nuxt`: registers `<ForgeModelRolesPanel>` (provider and model select per enabled role, `status` slot, emits `update:assignments`, never writes).
+
+## 1.2.2
+
+- Accepts `@skaile/workspaces` ^8.0.0. The only 8.0.0 break is the renamed managed-codex start, which this package does not touch; the provider registry, catalog and model-discovery APIs it uses are unchanged.
+
 ## 1.2.1
 
 - First release published by CI (`publish.yml`, npm trusted publishing). No code change.

package/README.md

@@ -5,8 +5,8 @@ Provider and settings operations for Skaile forge apps, without the app's databa
 | Entry | Contents | Peers it needs |
 |---|---|---|
 | `/server` | registry layers and writes, credential store, `.env` layers, provider inventory and discovery, harness settings rules, credential policy | none |
-| `/vue` | `useProvidersPanel`, `SettingsModalScope`, browser-safe registry/env/harness vocabulary | `vue` |
-| `/nuxt` | Nuxt module registering `<ForgeProvidersPanel>` | `nuxt`, `@nuxt/ui` |
+| `/vue` | `useProvidersPanel`, `urlProvidersClient`, `SettingsModalScope`, model-role helpers, browser-safe registry/env/harness vocabulary | `vue` |
+| `/nuxt` | Nuxt module registering `<ForgeProvidersPanel>` and `<ForgeModelRolesPanel>` | `nuxt`, `@nuxt/ui` |
 | `/ai-sdk` | AI SDK `LanguageModel` of a registry selector | `ai` + the `@ai-sdk/*` provider the surface needs |
 | `/editor` | the editor's `ModelProvider` over a registry | `@skaile/forge-editor`, `@ai-sdk/openai-compatible` |
 
@@ -84,6 +84,33 @@ modules: ['@nuxt/ui', '@skaile/forge-settings/nuxt']
 
 The panel (`PUT|DELETE <writeUrl>/:id`, `GET <writeUrl>/detected`, `GET <providersUrl>`, `GET|PUT <environmentUrl>`) reads and writes only the routes you give it. The host serves them with the `/server` operations and decides who may call them. `SettingsModalScope` documents the same URL fields for hosts that compose a larger modal.
 
+Without URLs, pass `:client` (a `ProvidersPanelClient`: `list`, `detected`, `presets`, `upsert`, `remove`, `environment`, `updateEnvironment`, `models`, `test`) and the panel talks through it; the URL props then become optional. A passed client also turns on the per-provider Test button. `urlProvidersClient({ providersUrl, providersWriteUrl, … })` is the client the URL props build; its `models(id)` and `test(id)` call `GET|POST <writeUrl>/:id/models|test`, routes only a host that wants those features serves.
+
+## Model roles
+
+A *model role* is a named purpose a host picks a model for. The host declares roles and stores the assignments (role id to selector); this package supplies the vocabulary, validation, resolution and a picker.
+
+| Kind | Assigns | Registry entry |
+|---|---|---|
+| `chat`, `decision`, `image` | `<entryId>/<modelId>` | enabled `llm` entry (`image` offers every model; discovery carries no modality) |
+| `tts`, `stt` | the voice entry id | enabled entry of that kind |
+
+omp names: `decision` = `judge`, `tts` = `speech`, `stt` = `dictation`.
+
+```ts
+import { STANDARD_MODEL_ROLES, validateModelRoleAssignments, resolveModelRole, modelRoleAliases } from '@skaile/forge-settings/server' // or /vue
+
+const roles = [
+  { id: 'assistant', kind: 'chat', label: 'Assistant', description: 'The in-app chat.', enabled: true },
+  ...STANDARD_MODEL_ROLES.map((role) => ({ ...role, enabled: false })), // decision, image, tts, stt: flip what the app uses
+]
+validateModelRoleAssignments(roles, assignments, registry) // [{ role, code, message }]: one issue per role id, host turns them into 400s
+resolveModelRole('assistant', { roles, assignments, registry }) // { kind: 'model', selector, entryId } | { kind: 'voice', entryId } | { kind: 'unassigned' }
+resolveRegistryLanguageModel('@assistant', { roles: modelRoleAliases(roles, assignments) })
+```
+
+A dangling assignment throws `ModelResolutionError` (`unknown_selector`). `<ForgeModelRolesPanel :roles :assignments :client :read-only @update:assignments>` renders one row per enabled role (provider select, model select from `client.models`, free text when the provider cannot list models, Clear, a `status` slot per row). It never writes; the host saves the emitted assignments.
+
 ## Development
 
 ```

package/dist/module.d.mts

@@ -1,10 +1,12 @@
 import { NuxtModule } from '@nuxt/schema';
 
-/** `@skaile/forge-settings/nuxt` has no options: it registers one component. */
+/** `@skaile/forge-settings/nuxt` has no options: it registers two components. */
 type ForgeSettingsOptions = Record<string, never>;
 /**
  * Nuxt module registering `<ForgeProvidersPanel>`, the narrow provider
- * settings surface (registry editor, detected-in-environment adds, key entry).
+ * settings surface (registry editor, detected-in-environment adds, key entry),
+ * and `<ForgeModelRolesPanel>`, the per-role provider and model picker. The
+ * roles panel never writes: the host saves the assignments it emits.
  *
  * It installs no server route, no auto-import and no authorization: the host
  * serves the panel's routes with `@skaile/forge-settings/server` and decides who

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@skaile/forge-settings",
   "configKey": "forgeSettings",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -17,6 +17,11 @@ const forgeSettingsModule = defineNuxtModule({
       filePath: resolve("./runtime/components/ForgeProvidersPanel.vue"),
       global: false
     });
+    addComponent({
+      name: "ForgeModelRolesPanel",
+      filePath: resolve("./runtime/components/ForgeModelRolesPanel.vue"),
+      global: false
+    });
   }
 });
 

package/dist/runtime/components/ForgeModelRolesPanel.d.vue.ts

@@ -0,0 +1,34 @@
+import type { ModelRoleAssignments, ModelRoleDefinition } from "../shared/model-roles.js";
+import { type ModelRolesPanelClient } from "../vue/model-roles-panel.js";
+type __VLS_Props = {
+    /** Every role the host declares; only `enabled` ones are rendered. */
+    roles: ModelRoleDefinition[];
+    /** Role id to selector (`<entryId>/<modelId>`, or an entry id for `tts` / `stt`). */
+    assignments: ModelRoleAssignments;
+    /** Reads the registry and its models; a `ProvidersPanelClient` fits. */
+    client: ModelRolesPanelClient;
+    /** Disables every change. */
+    readOnly?: boolean;
+};
+type __VLS_Slots = {
+    /** Under a role's row: availability or check text the host knows. */
+    status?(props: {
+        role: ModelRoleDefinition;
+    }): unknown;
+};
+/** Reloads the registry and the models of every shown provider. */
+declare function refresh(): Promise<void>;
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {
+    refresh: typeof refresh;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    "update:assignments": (assignments: ModelRoleAssignments) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:assignments"?: ((assignments: ModelRoleAssignments) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/ForgeModelRolesPanel.vue

@@ -0,0 +1,250 @@
+<template>
+  <div data-testid="model-roles-panel" class="space-y-3">
+    <p v-if="loadError" data-testid="model-roles-error" class="text-sm text-error-500">{{ loadError }}</p>
+    <div v-else-if="loading && !loaded" class="text-xs text-foreground-subtle py-2 text-center">
+      Loading providers…
+    </div>
+    <div v-else-if="rows.length === 0" class="text-xs text-foreground-subtle py-2 text-center">
+      No model roles are enabled.
+    </div>
+
+    <div
+      v-for="row in rows"
+      :key="row.role.id"
+      :data-testid="`model-role-${row.role.id}`"
+      class="p-3 rounded-lg border border-surface-border space-y-2"
+    >
+      <div class="flex items-start gap-2">
+        <div class="flex-1 min-w-0">
+          <p class="text-sm font-medium text-foreground">{{ row.role.label }}</p>
+          <p class="text-xs text-foreground-muted leading-relaxed">{{ row.role.description }}</p>
+        </div>
+        <UBadge
+          v-if="!row.state.assigned"
+          size="sm"
+          variant="subtle"
+          color="neutral"
+          :data-testid="`model-role-unassigned-${row.role.id}`"
+        >Not assigned</UBadge>
+      </div>
+
+      <div class="flex items-start gap-2 flex-wrap">
+        <USelect
+          :model-value="row.state.entryId || void 0"
+          :items="row.state.providerOptions"
+          placeholder="Choose a provider"
+          :disabled="props.readOnly"
+          :data-testid="`model-role-provider-${row.role.id}`"
+          class="min-w-[12rem] bg-surface-ground border-surface-border text-foreground text-xs"
+          @update:model-value="onProvider(row.role, String($event ?? ''))"
+        />
+
+        <template v-if="!row.voice">
+          <USelect
+            v-if="row.modelChoices"
+            :model-value="row.state.modelId || void 0"
+            :items="row.modelChoices"
+            placeholder="Choose a model"
+            :disabled="props.readOnly"
+            :data-testid="`model-role-model-${row.role.id}`"
+            class="min-w-[16rem] bg-surface-ground border-surface-border text-foreground text-xs font-mono"
+            @update:model-value="onModel(row.role, String($event ?? ''))"
+          />
+          <UInput
+            v-else
+            :model-value="drafts[row.role.id] ?? row.state.modelId"
+            placeholder="Model id"
+            :disabled="props.readOnly || !row.state.entryId || row.modelsLoading"
+            :data-testid="`model-role-model-${row.role.id}`"
+            class="min-w-[16rem] bg-surface-ground border-surface-border text-foreground text-xs font-mono"
+            @update:model-value="drafts[row.role.id] = String($event ?? '')"
+            @blur="commitDraft(row.role)"
+            @keydown.enter="commitDraft(row.role)"
+          />
+        </template>
+
+        <UButton
+          v-if="!props.readOnly && (row.state.assigned || row.state.entryId)"
+          size="sm"
+          variant="ghost"
+          :aria-label="`Clear ${row.role.label}`"
+          :data-testid="`model-role-clear-${row.role.id}`"
+          @click="clear(row.role)"
+        >
+          <Icon name="lucide:x" class="mr-1.5 w-3.5 h-3.5" />Clear
+        </UButton>
+      </div>
+
+      <p
+        v-if="row.state.warning"
+        :data-testid="`model-role-warning-${row.role.id}`"
+        class="text-xs text-amber-600 dark:text-amber-400"
+      >{{ row.state.warning }}</p>
+      <p
+        v-if="row.modelsLoading"
+        class="text-xs text-foreground-subtle italic"
+      >Loading models…</p>
+      <p
+        v-else-if="row.modelsHint"
+        :data-testid="`model-role-hint-${row.role.id}`"
+        class="text-xs text-foreground-subtle italic"
+      >{{ row.modelsHint }}</p>
+
+      <slot name="status" :role="row.role" />
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed, onMounted, reactive, ref, watch } from "vue";
+import {
+  assignmentOf,
+  buildSelector,
+  isVoiceRole,
+  modelOptions,
+  modelRoleRowState,
+  withAssignment
+} from "../vue/model-roles-panel";
+const props = defineProps({
+  roles: { type: Array, required: true },
+  assignments: { type: Object, required: true },
+  client: { type: Object, required: true },
+  readOnly: { type: Boolean, required: false }
+});
+const emit = defineEmits(["update:assignments"]);
+defineSlots();
+const entries = ref([]);
+const loading = ref(false);
+const loaded = ref(false);
+const loadError = ref(null);
+const modelsCache = reactive({});
+const pending = reactive({});
+const drafts = reactive({});
+function errorMessage(error) {
+  return error instanceof Error && error.message ? error.message : "The request failed.";
+}
+async function loadEntries() {
+  loading.value = true;
+  loadError.value = null;
+  try {
+    entries.value = await props.client.list();
+    loaded.value = true;
+  } catch (error) {
+    loadError.value = errorMessage(error);
+  } finally {
+    loading.value = false;
+  }
+}
+const modelsRequest = {};
+let requestCounter = 0;
+async function loadModels(entryId) {
+  const request = ++requestCounter;
+  modelsRequest[entryId] = request;
+  modelsCache[entryId] = { loading: true };
+  try {
+    const result = await props.client.models(entryId);
+    if (modelsRequest[entryId] !== request) return;
+    modelsCache[entryId] = { loading: false, result };
+  } catch (error) {
+    if (modelsRequest[entryId] !== request) return;
+    modelsCache[entryId] = { loading: false, error: errorMessage(error) };
+  }
+}
+async function refresh() {
+  for (const key of Object.keys(modelsRequest)) delete modelsRequest[key];
+  for (const key of Object.keys(modelsCache)) delete modelsCache[key];
+  await loadEntries();
+  loadModelsForRows();
+}
+const rows = computed(
+  () => props.roles.filter((role) => role.enabled).map((role) => {
+    const voice = isVoiceRole(role.kind);
+    const state = modelRoleRowState(role, assignmentOf(props.assignments, role.id), entries.value, pending[role.id]);
+    const cache = state.entryId ? modelsCache[state.entryId] : void 0;
+    const result = cache?.result;
+    const listed = result && result.status !== "unsupported";
+    let modelsHint;
+    if (!voice && cache && !cache.loading && !listed) {
+      modelsHint = cache.error ?? result?.message ?? "This provider does not list models; enter the model id.";
+    } else if (!voice && result?.status === "static") {
+      modelsHint = result.message;
+    }
+    return {
+      role,
+      voice,
+      state,
+      modelChoices: listed ? modelOptions(result.models, state.modelId) : null,
+      modelsLoading: cache?.loading ?? false,
+      modelsHint
+    };
+  })
+);
+function loadModelsForRows() {
+  for (const row of rows.value) {
+    const id = row.state.entryId;
+    if (row.voice || !id || row.state.warning || modelsCache[id]) continue;
+    void loadModels(id);
+  }
+}
+function emitAssignments(roleId, value) {
+  emit("update:assignments", withAssignment(props.assignments, roleId, value));
+}
+function onProvider(role, entryId) {
+  if (props.readOnly) return;
+  delete drafts[role.id];
+  if (isVoiceRole(role.kind)) {
+    emitAssignments(role.id, entryId);
+    return;
+  }
+  if (entryId === "") delete pending[role.id];
+  else pending[role.id] = entryId;
+  if (assignmentOf(props.assignments, role.id)) emitAssignments(role.id, "");
+}
+function onModel(role, modelId) {
+  if (props.readOnly) return;
+  const entryId = rows.value.find((row) => row.role.id === role.id)?.state.entryId ?? "";
+  delete drafts[role.id];
+  if (!entryId || modelId === "") return;
+  delete pending[role.id];
+  emitAssignments(role.id, buildSelector(entryId, modelId));
+}
+function commitDraft(role) {
+  const draft = drafts[role.id];
+  if (draft === void 0) return;
+  const modelId = draft.trim();
+  const row = rows.value.find((candidate) => candidate.role.id === role.id);
+  if (!row || modelId === row.state.modelId) {
+    delete drafts[role.id];
+    return;
+  }
+  if (modelId === "") {
+    delete drafts[role.id];
+    if (assignmentOf(props.assignments, role.id)) {
+      pending[role.id] = row.state.entryId;
+      emitAssignments(role.id, "");
+    }
+    return;
+  }
+  onModel(role, modelId);
+}
+function clear(role) {
+  if (props.readOnly) return;
+  delete pending[role.id];
+  delete drafts[role.id];
+  if (assignmentOf(props.assignments, role.id)) emitAssignments(role.id, "");
+}
+watch(
+  () => props.assignments,
+  (assignments) => {
+    for (const roleId of Object.keys(pending)) {
+      if (assignmentOf(assignments, roleId)) delete pending[roleId];
+    }
+  }
+);
+watch(rows, loadModelsForRows);
+onMounted(async () => {
+  await loadEntries();
+  loadModelsForRows();
+});
+defineExpose({ refresh });
+</script>

package/dist/runtime/components/ForgeModelRolesPanel.vue.d.ts

@@ -0,0 +1,34 @@
+import type { ModelRoleAssignments, ModelRoleDefinition } from "../shared/model-roles.js";
+import { type ModelRolesPanelClient } from "../vue/model-roles-panel.js";
+type __VLS_Props = {
+    /** Every role the host declares; only `enabled` ones are rendered. */
+    roles: ModelRoleDefinition[];
+    /** Role id to selector (`<entryId>/<modelId>`, or an entry id for `tts` / `stt`). */
+    assignments: ModelRoleAssignments;
+    /** Reads the registry and its models; a `ProvidersPanelClient` fits. */
+    client: ModelRolesPanelClient;
+    /** Disables every change. */
+    readOnly?: boolean;
+};
+type __VLS_Slots = {
+    /** Under a role's row: availability or check text the host knows. */
+    status?(props: {
+        role: ModelRoleDefinition;
+    }): unknown;
+};
+/** Reloads the registry and the models of every shown provider. */
+declare function refresh(): Promise<void>;
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {
+    refresh: typeof refresh;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    "update:assignments": (assignments: ModelRoleAssignments) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:assignments"?: ((assignments: ModelRoleAssignments) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/ForgeProvidersPanel.d.vue.ts

@@ -1,13 +1,21 @@
+import type { ProvidersPanelClient } from "../vue/providers-client.js";
 import { type ProvidersPanelLayer } from "../vue/useProvidersPanel.js";
 type __VLS_Props = {
-    /** `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 calls the URL props below
+     * (`urlProvidersClient`); with it they are ignored and every row offers a 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;
     /** The scope's `.env` route: hand-entered keys. Omitted, key entry is hidden. */
     environmentUrl?: string;
+    /** Key entry and the environment disclosure. Default: `Boolean(environmentUrl)` without `client`, `true` with one. */
+    environmentEnabled?: boolean;
     /** Edit/Delete are offered only for entries this layer defines. */
     layer: ProvidersPanelLayer;
     /** Disables add, edit and delete. */
@@ -17,5 +25,7 @@ declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {
     changed: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onChanged?: (() => any) | undefined;
-}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+}>, {
+    environmentEnabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/runtime/components/ForgeProvidersPanel.vue

@@ -168,6 +168,11 @@
                 :data-testid="`provider-override-notice-${row.id}`"
                 class="text-foreground-subtle"
               >{{ notice }}</p>
+              <p
+                v-if="testResults[row.id]"
+                :data-testid="`provider-test-result-${row.id}`"
+                :class="testResults[row.id]?.ok ? 'text-success-500' : 'text-error-500'"
+              >{{ testResults[row.id]?.message }}</p>
               <p
                 v-if="rowError?.id === row.id"
                 :data-testid="`provider-row-error-${row.id}`"
@@ -185,6 +190,17 @@
             </td>
             <td class="px-3 py-2">
               <div class="flex items-center justify-end gap-1">
+                <UButton
+                  v-if="canTest"
+                  size="sm"
+                  variant="ghost"
+                  :loading="testBusy === row.id"
+                  :disabled="testBusy !== null"
+                  :data-testid="`provider-test-${row.id}`"
+                  @click="testProvider(row)"
+                >
+                  <Icon name="lucide:plug-zap" class="mr-1.5 w-3.5 h-3.5" />Test
+                </UButton>
                 <UButton
                   v-if="row.canReset"
                   size="sm"
@@ -376,10 +392,12 @@
 <script setup>
 import { useProvidersPanel } from "../vue/useProvidersPanel";
 const props = defineProps({
-  providersUrl: { type: String, required: true },
-  providersWriteUrl: { type: String, required: true },
+  client: { type: Object, required: false },
+  providersUrl: { type: String, required: false },
+  providersWriteUrl: { type: String, required: false },
   presetsUrl: { type: String, required: false },
   environmentUrl: { type: String, required: false },
+  environmentEnabled: { type: Boolean, required: false, default: void 0 },
   layer: { type: String, required: true },
   readOnly: { type: Boolean, required: false }
 });
@@ -403,6 +421,10 @@ const {
   showCredentialFields,
   rowBusy,
   rowError,
+  canTest,
+  testBusy,
+  testResults,
+  testProvider,
   onCredentialSelect,
   setEnabled,
   resetPatch,

package/dist/runtime/components/ForgeProvidersPanel.vue.d.ts

@@ -1,13 +1,21 @@
+import type { ProvidersPanelClient } from "../vue/providers-client.js";
 import { type ProvidersPanelLayer } from "../vue/useProvidersPanel.js";
 type __VLS_Props = {
-    /** `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 calls the URL props below
+     * (`urlProvidersClient`); with it they are ignored and every row offers a 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;
     /** The scope's `.env` route: hand-entered keys. Omitted, key entry is hidden. */
     environmentUrl?: string;
+    /** Key entry and the environment disclosure. Default: `Boolean(environmentUrl)` without `client`, `true` with one. */
+    environmentEnabled?: boolean;
     /** Edit/Delete are offered only for entries this layer defines. */
     layer: ProvidersPanelLayer;
     /** Disables add, edit and delete. */
@@ -17,5 +25,7 @@ declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {
     changed: () => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onChanged?: (() => any) | undefined;
-}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+}>, {
+    environmentEnabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/runtime/server/index.d.ts

@@ -8,6 +8,7 @@
  */
 export * from "../shared/harness-providers.js";
 export * from "../shared/harnesses.js";
+export * from "../shared/model-roles.js";
 export * from "../shared/provider-registry.js";
 export type { DomainConfig, SkaileSettings } from "../shared/settings-types.js";
 export * from "./credential-policy.js";

package/dist/runtime/server/index.js

@@ -1,5 +1,6 @@
 export * from "../shared/harness-providers.js";
 export * from "../shared/harnesses.js";
+export * from "../shared/model-roles.js";
 export * from "../shared/provider-registry.js";
 export * from "./credential-policy.js";
 export * from "./credential-store.js";

package/dist/runtime/shared/model-roles.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 { type AIProviderRegistryView } from "./provider-registry.js";
+/**
+ * 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 declare const MODEL_ROLE_KINDS: readonly ["chat", "decision", "image", "tts", "stt"];
+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 declare const STANDARD_MODEL_ROLES: readonly ModelRoleDefinition[];
+/** 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;
+}
+/**
+ * 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 declare function validateModelRoleAssignments(roles: readonly ModelRoleDefinition[], assignments: ModelRoleAssignments, registry: AIProviderRegistryView): ModelRoleIssue[];
+/** 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 declare function resolveModelRole(roleId: string, context: ResolveModelRoleContext): ResolvedModelRole;
+/**
+ * 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 declare function modelRoleAliases(roles: readonly ModelRoleDefinition[], assignments: ModelRoleAssignments): Record<string, string>;