@skaile/forge-settings 1.3.3 → 1.4.0

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

@@ -8,12 +8,13 @@
  * What lives here, so hosts only read and write their own storage:
  *
  * - {@link validateHarnessSettingsPatch} — the rule set for a harness settings
- *   write (`harness`, `harnessModels`, `harnessProviders`, `enabledHarnesses`,
- *   `lock*`), as a pure function over the request body and the stored state.
+ *   write (`harness`, `harnessModels`, `harnessRoles`, `harnessProviders`,
+ *   `enabledHarnesses`, `lock*`), as a pure function over the request body and
+ *   the stored state.
  * - {@link resolveLockFlags} — the admin lock flags in force. Locks are
  *   `settings.json` fields only; there is no environment override.
- * - {@link applyHarnessLayers} — which harness, model and provider pick a
- *   session starts with, given the settings layers the host read.
+ * - {@link applyHarnessLayers} — which harness, model, roles and provider pick
+ *   a session starts with, given the settings layers the host read.
  * - {@link enabledHarnessIds} / {@link buildHarnessRows} — the harness catalog
  *   `GET /api/agents` serves.
  *
@@ -22,11 +23,18 @@
 
 import type { HarnessDetection } from "@skaile/workspaces/sdk/bridge";
 import type { HarnessInfo } from "@skaile/workspaces/types";
+import {
+  type HarnessProviderBlock,
+  type HarnessProviderCandidate,
+  harnessProviderBlock,
+} from "../shared/harness-providers";
 import {
   DEFAULT_ENABLED_HARNESSES,
   HARNESS_LABELS,
+  harnessRoleIds,
   isExperimentalHarness,
 } from "../shared/harnesses";
+import type { DataZoneRule } from "../shared/provider-registry";
 import type { SkaileSettings } from "../shared/settings-types";
 
 /** The slice of {@link SkaileSettings} that selects, configures and locks harnesses. */
@@ -34,6 +42,7 @@ export type HarnessSettings = Pick<
   SkaileSettings,
   | "harness"
   | "harnessModels"
+  | "harnessRoles"
   | "harnessProviders"
   | "enabledHarnesses"
   | "lockHarness"
@@ -99,29 +108,65 @@ export type HarnessRow = HarnessInfo & {
   enabled: boolean;
   /** What `detectHarnesses()` found on this host: installed, version, login. */
   detection: HarnessDetection;
+  /** The role ids the harness takes ({@link harnessRoleIds}); empty for a one-model harness. */
+  roles: string[];
+  /** The role → model selector assignments of `s.harnessRoles` for this harness (pass effective settings). */
+  roleAssignments: Record<string, string>;
+  /**
+   * Registry entries on a surface the harness speaks that the host's
+   * data-zone rule keeps out, by entry id (reason `blocked-by-rule`, with the
+   * message a table shows on the box it cannot tick). Empty without
+   * `providers` or under the rule `any`.
+   */
+  blockedProviders: Record<string, HarnessProviderBlock>;
 };
 
+/** The registry entries {@link buildHarnessRows} checks against the host's data-zone rule. */
+export interface HarnessRowProviders {
+  /** `GET /api/providers` rows (or any {@link HarnessProviderCandidate}s), in registry order. */
+  candidates: readonly HarnessProviderCandidate[];
+  /** The host's data-zone rule. Absent: `any`. */
+  dataZoneRule?: DataZoneRule;
+}
+
 /**
  * The rows of `GET /api/agents`: one per harness, in `harnesses` order. Hosts
  * filter to `enabled` unless the request asked for all (`?all=1`).
  * `surfaces` and `providerPlurality` ride along from {@link HarnessInfo} so the
- * Harness tab can offer each harness only the providers it can use.
+ * Harness tab can offer each harness only the providers it can use; `roles`
+ * and `roleAssignments` drive the "Roles" badge and the models-per-task panel.
  * `detections` is the host's `detectHarnesses()` answer; a harness it does not
  * mention (or every harness, when it is omitted) reports `{ status: "unknown" }`.
+ * `providers`, when given, fills each row's `blockedProviders`.
  */
 export function buildHarnessRows(
   harnesses: HarnessInfo[],
-  s: Pick<HarnessSettings, "enabledHarnesses">,
+  s: Pick<HarnessSettings, "enabledHarnesses" | "harnessRoles">,
   detections: readonly HarnessDetection[] = [],
+  providers?: HarnessRowProviders,
 ): HarnessRow[] {
   const enabled = new Set(enabledHarnessIds(s));
-  return harnesses.map((info) => ({
-    ...info,
-    label: HARNESS_LABELS[info.id] ?? info.name,
-    experimental: isExperimentalHarness(info.id),
-    enabled: enabled.has(info.id),
-    detection: detections.find((d) => d.id === info.id) ?? { id: info.id, status: "unknown" },
-  }));
+  return harnesses.map((info) => {
+    const roles = harnessRoleIds(info.id);
+    const stored = stringEntries(s.harnessRoles?.[info.id]);
+    const roleAssignments: Record<string, string> = {};
+    for (const role of roles) if (stored[role]) roleAssignments[role] = stored[role];
+    const blockedProviders: Record<string, HarnessProviderBlock> = {};
+    for (const candidate of providers?.candidates ?? []) {
+      const block = harnessProviderBlock(info, candidate, providers?.dataZoneRule);
+      if (block) blockedProviders[candidate.id] = block;
+    }
+    return {
+      ...info,
+      label: HARNESS_LABELS[info.id] ?? info.name,
+      experimental: isExperimentalHarness(info.id),
+      enabled: enabled.has(info.id),
+      detection: detections.find((d) => d.id === info.id) ?? { id: info.id, status: "unknown" },
+      roles,
+      roleAssignments,
+      blockedProviders,
+    };
+  });
 }
 
 // ── validateHarnessSettingsPatch ────────────────────────────────────────────
@@ -180,6 +225,28 @@ function sameIdLists(a: Record<string, string[]>, b: Record<string, string[]>):
   );
 }
 
+/** The non-empty role maps of a stored `harnessRoles` value. */
+function roleMaps(value: unknown): Record<string, Record<string, string>> {
+  const maps: Record<string, Record<string, string>> = {};
+  if (!isObject(value)) return maps;
+  for (const [harnessId, roles] of Object.entries(value)) {
+    const entries = stringEntries(roles);
+    if (Object.keys(entries).length) maps[harnessId] = entries;
+  }
+  return maps;
+}
+
+function sameRoleMaps(
+  a: Record<string, Record<string, string>>,
+  b: Record<string, Record<string, string>>,
+): boolean {
+  const keys = Object.keys(a);
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every((key) => b[key] !== undefined && sameEntries(a[key]!, b[key]))
+  );
+}
+
 /** What {@link validateHarnessSettingsPatch} hands back for a valid body. */
 export type HarnessSettingsPatch = {
   /**
@@ -188,9 +255,9 @@ export type HarnessSettingsPatch = {
    */
   patch: Partial<HarnessSettings>;
   /**
-   * Whether the effective `harness`, `harnessModels`, `harnessProviders` or
-   * `enabledHarnesses` changed, i.e. whether running sessions now run on stale
-   * defaults and the host should stop them.
+   * Whether the effective `harness`, `harnessModels`, `harnessRoles`,
+   * `harnessProviders` or `enabledHarnesses` changed, i.e. whether running
+   * sessions now run on stale defaults and the host should stop them.
    */
   sessionAffecting: boolean;
 };
@@ -206,6 +273,11 @@ export type HarnessSettingsPatch = {
  *   keys are present `harness` wins.
  * - `harnessModels`: patched per harness id (catalog ids only); a value is a
  *   `providerId/modelId` selector, an empty string removes that harness's entry.
+ * - `harnessRoles`: patched per harness id, then per role. A harness must be in
+ *   the catalog and take roles ({@link harnessRoleIds}); a role must be one of
+ *   its roles; a value is a `providerId/modelId` selector, and one of
+ *   `ctx.runnableModels` when that list is given. An empty string or `null`
+ *   removes the role; `{}` or `null` for a harness removes all its roles.
  * - `harnessProviders`: the registry entry ids picked per harness id. The modal
  *   sends the whole map, so it replaces the stored one: each value must be an
  *   array of strings (empty strings are dropped, duplicates collapse, order is
@@ -226,12 +298,19 @@ export type HarnessSettingsPatch = {
  * @param ctx.catalog valid harness ids (`listHarnesses().map(d => d.id)`).
  * @param ctx.current the stored settings the patch applies to (the instance file).
  * @param ctx.locks the lock flags in force ({@link resolveLockFlags} of `current`).
+ * @param ctx.runnableModels optional: the selectors a session may run; when
+ * given, a `harnessRoles` value outside it is refused.
  * @returns the patch, or the error message of the first violated rule (a
  * string, mirroring `validateEnvSettingsUpdate`; hosts answer 400 with it).
  */
 export function validateHarnessSettingsPatch(
   body: unknown,
-  ctx: { catalog: Iterable<string>; current: HarnessSettings; locks: LockFlags },
+  ctx: {
+    catalog: Iterable<string>;
+    current: HarnessSettings;
+    locks: LockFlags;
+    runnableModels?: Iterable<string>;
+  },
 ): HarnessSettingsPatch | string {
   if (!isObject(body)) return "body must be an object";
   if ("model" in body) return "model is set per harness - use harnessModels";
@@ -291,6 +370,52 @@ export function validateHarnessSettingsPatch(
     }
   }
 
+  if ("harnessRoles" in body) {
+    const raw = body.harnessRoles;
+    if (!isObject(raw)) return "harnessRoles must be an object";
+    const runnable = ctx.runnableModels ? new Set(ctx.runnableModels) : undefined;
+    const currentRoles = roleMaps(current.harnessRoles);
+    const nextRoles: Record<string, Record<string, string>> = {};
+    for (const [id, roles] of Object.entries(currentRoles)) nextRoles[id] = { ...roles };
+    for (const [id, roles] of Object.entries(raw)) {
+      if (!catalog.has(id)) return `harnessRoles: unknown harness "${id}"`;
+      const supported = harnessRoleIds(id);
+      if (!supported.length)
+        return `harnessRoles: harness "${id}" runs one model and takes no roles`;
+      if (roles === null) {
+        delete nextRoles[id];
+        continue;
+      }
+      if (!isObject(roles)) return `harnessRoles.${id} must be an object`;
+      if (!Object.keys(roles).length) {
+        delete nextRoles[id];
+        continue;
+      }
+      const next = { ...nextRoles[id] };
+      for (const [role, entry] of Object.entries(roles)) {
+        if (!supported.includes(role)) return `harnessRoles.${id}: unknown role "${role}"`;
+        if (entry !== null && typeof entry !== "string")
+          return `harnessRoles.${id}.${role} must be a string`;
+        const value = typeof entry === "string" ? entry.trim() : "";
+        if (!value) {
+          delete next[role];
+          continue;
+        }
+        if (!isModelSelector(value))
+          return `harnessRoles.${id}.${role} must be a "providerId/modelId" selector`;
+        if (runnable && !runnable.has(value))
+          return `harnessRoles.${id}.${role}: model "${value}" is not runnable`;
+        next[role] = value;
+      }
+      if (Object.keys(next).length) nextRoles[id] = next;
+      else delete nextRoles[id];
+    }
+    if (!sameRoleMaps(currentRoles, nextRoles)) {
+      patch.harnessRoles = Object.keys(nextRoles).length ? nextRoles : undefined;
+      sessionAffecting = true;
+    }
+  }
+
   if ("enabledHarnesses" in body) {
     const raw = body.enabledHarnesses;
     if (!Array.isArray(raw) || !raw.every((id) => typeof id === "string")) {
@@ -321,18 +446,20 @@ export function validateHarnessSettingsPatch(
 
 // ── applyHarnessLayers ──────────────────────────────────────────────────────
 
-/** One settings layer's say in which harness, model and provider pick a session gets. */
+/** One settings layer's say in which harness, model, roles and provider pick a session gets. */
 export type HarnessLayer = {
   /** The harness id (the workspaces settings key `harness`). */
   harness?: string;
   /** An explicit model selector; wins over this layer's `harnessModels` entry. */
   model?: string;
   harnessModels?: Record<string, string>;
+  /** Role → model selector per harness id; layered per role. */
+  harnessRoles?: Record<string, Record<string, string>>;
   harnessProviders?: Record<string, string[]>;
 };
 
 /**
- * Resolve the harness, model and provider pick a session starts with.
+ * Resolve the harness, model, roles and provider pick a session starts with.
  *
  * `layers[0]` is the instance layer; later layers (workspace file, workspace
  * overrides, chat, …) are more specific and override it per field — the last
@@ -346,12 +473,21 @@ export type HarnessLayer = {
  * `layer.harnessProviders[harness]` — both keyed by the *resolved* harness, so
  * a pick stored for another harness never applies.
  *
+ * `roles` is layered per role of the resolved harness: for each role the last
+ * layer with a non-empty selector wins; `locks.model` freezes it to layer 0's
+ * roles, as it freezes `model`. No role set anywhere → `undefined`.
+ *
  * Fields no layer sets come back `undefined`; the host supplies its defaults.
  */
 export function applyHarnessLayers(
   layers: HarnessLayer[],
   locks: LockFlags,
-): { harness: string | undefined; model: string | undefined; providers: string[] | undefined } {
+): {
+  harness: string | undefined;
+  model: string | undefined;
+  roles: Record<string, string> | undefined;
+  providers: string[] | undefined;
+} {
   /** The layer-0 value when `locked`, else the last layer's non-undefined value. */
   const pick = <T>(
     locked: boolean,
@@ -376,5 +512,13 @@ export function applyHarnessLayers(
     const ids = harness === undefined ? undefined : layer.harnessProviders?.[harness];
     return ids?.length ? ids : undefined;
   });
-  return { harness, model, providers };
+  let roles: Record<string, string> | undefined;
+  if (harness !== undefined) {
+    const merged: Record<string, string> = {};
+    const roleLayers = locks.model.value ? layers.slice(0, 1) : layers;
+    for (const layer of roleLayers)
+      Object.assign(merged, stringEntries(layer.harnessRoles?.[harness]));
+    if (Object.keys(merged).length) roles = merged;
+  }
+  return { harness, model, roles, providers };
 }

package/src/runtime/server/index.ts

@@ -7,9 +7,11 @@
  * authentication and workspace permissions stay with the host.
  */
 
+export * from "../shared/data-zone";
 export * from "../shared/harness-providers";
 export * from "../shared/harnesses";
 export * from "../shared/model-roles";
+export * from "../shared/provider-accounts";
 export * from "../shared/provider-registry";
 export type { DomainConfig, SkaileSettings } from "../shared/settings-types";
 export * from "./credential-policy";

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

@@ -19,17 +19,21 @@
  *     `listModelsForHarness(harnessId, registry)` in the runtime.
  */
 
+import { entryDataZone } from "../shared/data-zone";
 import type {
   AIProviderCapabilities,
   AIProviderCredentialKind,
   AIProviderKind,
   AIProviderRegistryView,
   AIProviderSurface,
+  AIProviderTransport,
   AIProviderVoiceParams,
+  DataZone,
 } from "../shared/provider-registry";
 import {
   entriesOfKind,
   isEntryEnabled,
+  isModelAllowed,
   isVoiceEntry,
   parseCredentialRef,
   registryEntries,
@@ -76,6 +80,14 @@ export interface ProviderInfo {
   preset?: string;
   /** Wire protocol of an `llm`/`embed` entry (its own or its preset's). */
   surface?: AIProviderSurface;
+  /** How requests of an `llm`/`embed` entry reach its surface, when not `direct`. */
+  transport?: AIProviderTransport;
+  /**
+   * Routing parameters of an `llm`/`embed` entry (`resource`, `deployment`,
+   * `api_version`, `region`, `project`, `location`, …), when it has any.
+   * Voice entries carry theirs in {@link params}.
+   */
+  transportParams?: Record<string, string>;
   /** The entry's `enabled` flag; `false` only in a listing with `includeDisabled`. */
   enabled: boolean;
   /**
@@ -87,6 +99,21 @@ export interface ProviderInfo {
   params?: AIProviderVoiceParams;
   /** 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;
+  /** The entry's `eu_processing` switch (an `eu_option` entry counts as EU only with it on). */
+  euProcessing: boolean;
+  /**
+   * The entry's `allowed_models`, when it sets one: the only models it may be
+   * used with (`[]` = none). Absent: every model.
+   */
+  allowedModels?: string[];
+  /**
+   * Logical model ids an `llm`/`embed` entry declares (`model_map` keys, then
+   * ids only `capabilities` names), when it declares any. An entry without
+   * them lists its models through discovery.
+   */
+  modelIds?: string[];
 }
 
 /** One selectable model of one provider. */
@@ -162,21 +189,45 @@ export function listAIProviders(
       ...(entry.base_url ? { baseUrl: entry.base_url } : {}),
       ...(entry.preset ? { preset: entry.preset } : {}),
       ...(!isVoiceEntry(entry) && entry.surface ? { surface: entry.surface } : {}),
+      ...(!isVoiceEntry(entry) && entry.transport && entry.transport !== "direct"
+        ? { transport: entry.transport }
+        : {}),
+      ...(!isVoiceEntry(entry) && entry.params && Object.keys(entry.params).length > 0
+        ? { transportParams: { ...(entry.params as Record<string, string>) } }
+        : {}),
       enabled,
       ...(isVoiceEntry(entry) && entry.params ? { params: entry.params } : {}),
       locked: entry.locked === true,
+      dataZone: entryDataZone(entry),
+      euProcessing: entry.eu_processing === true,
+      ...(!isVoiceEntry(entry) && entry.allowed_models
+        ? { allowedModels: [...entry.allowed_models] }
+        : {}),
+      ...(!isVoiceEntry(entry) ? declaredModelIds(entry) : {}),
     });
   }
   return providers;
 }
 
+/** `{ modelIds }` of an `llm`/`embed` entry that declares models, else `{}`. */
+function declaredModelIds(entry: {
+  model_map?: Record<string, string>;
+  capabilities?: Record<string, unknown>;
+}): { modelIds?: string[] } {
+  const ids = [
+    ...new Set([...Object.keys(entry.model_map ?? {}), ...Object.keys(entry.capabilities ?? {})]),
+  ];
+  return ids.length > 0 ? { modelIds: ids } : {};
+}
+
 /**
  * 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.
+ * resolver reads, so a selector built from this list always resolves. A model
+ * outside the entry's `allowed_models` is left out, as the runtime refuses it.
  *
  * @param providerId - Restrict to one entry; omit for every enabled entry.
  */
@@ -193,6 +244,7 @@ export function listAIProviderModels(
         ...Object.keys(entry.capabilities ?? {}),
       ]);
       for (const modelId of logicalIds) {
+        if (!isModelAllowed(entry, modelId)) continue;
         const capabilities = entry.capabilities?.[modelId];
         models.push({
           id: `${id}/${modelId}`,

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

@@ -39,7 +39,9 @@ import {
   type AIProviderPreset,
   expandPreset,
 } from "@skaile/workspaces/sdk/bridge";
+import { isDataZone } from "../shared/data-zone";
 import { isPlainObject } from "../shared/guards";
+import { missingRequiredParams } from "../shared/provider-accounts";
 import type { AIProviderEntry, AIProviderRegistry } from "../shared/provider-registry";
 import { type CredentialPolicy, entryPolicyRefusal } from "./credential-policy";
 import { catalogPreset, readProviderLayer, writeProviderLayer } from "./provider-layers";
@@ -77,9 +79,8 @@ const PATCH_REFUSAL =
   "A workspace may only patch credential and enabled of an inherited entry; add it as a workspace entry to change anything else.";
 
 /**
- * Entry keys a `PUT` body may set, and that an omitting body removes. `kind`
- * may be set too — an entry without a `preset` (the settings modal's
- * "Custom") has nothing else to supply it — but, omitted, it keeps its
+ * Entry keys a `PUT` body may set, and that an omitting body removes. The
+ * keys of {@link KEPT_BODY_KEYS} may be set too but, omitted, keep their
  * written value like every other key of a stored entry.
  */
 const BODY_KEYS: Record<string, true> = {
@@ -93,6 +94,44 @@ const BODY_KEYS: Record<string, true> = {
   enabled: true,
 };
 
+/**
+ * Keys a `PUT` body may set that an omitting body keeps. `kind`: an entry
+ * without a `preset` (the settings modal's "Custom") has nothing else to
+ * supply it. `params`: transport routing (`resource`, `deployment`,
+ * `api_version`, `region`, …) or voice parameters, which an edit that does
+ * not show them must not drop; `params: {}` removes them. `data_zone`,
+ * `eu_processing`, `allowed_models` ({@link NULLABLE_BODY_KEYS}): the zone
+ * override, the account's EU-processing switch and the model allow-list,
+ * each changed on its own by the settings panel; `null` removes them.
+ */
+const KEPT_BODY_KEYS: Record<string, true> = {
+  kind: true,
+  params: true,
+  data_zone: true,
+  eu_processing: true,
+  allowed_models: true,
+};
+
+/** Kept keys a body removes by sending `null`. */
+const NULLABLE_BODY_KEYS = ["data_zone", "eu_processing", "allowed_models"] as const;
+
+/**
+ * A body's `allowed_models`, normalized (ids trimmed), or the refusal: a list
+ * of distinct, non-empty model ids. `[]` is valid and allows no model.
+ */
+function readAllowedModels(value: unknown): string[] | string {
+  const refusal = "allowed_models must be a list of distinct, non-empty model ids, or null";
+  if (!Array.isArray(value)) return refusal;
+  const ids: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string" || item.trim() === "") return refusal;
+    const id = item.trim();
+    if (ids.includes(id)) return `allowed_models lists '${id}' twice`;
+    ids.push(id);
+  }
+  return ids;
+}
+
 /** Entry fields a higher scope may set on an entry a lower document defines. */
 export const PATCH_KEYS = ["credential", "enabled"] as const;
 
@@ -168,8 +207,29 @@ function readEntryBody(body: unknown): Record<string, unknown> | string {
   ) {
     return PROVIDER_SECRET_REFUSAL;
   }
-  const unknown = Object.keys(body).find((key) => !Object.hasOwn(BODY_KEYS, key) && key !== "kind");
+  const unknown = Object.keys(body).find(
+    (key) => !Object.hasOwn(BODY_KEYS, key) && !Object.hasOwn(KEPT_BODY_KEYS, key),
+  );
   if (unknown) return `'${unknown}' is not a provider entry field`;
+  if (body.params !== undefined && !isPlainObject(body.params)) {
+    return "params must be a map of parameter name to value";
+  }
+  if (body.data_zone !== undefined && body.data_zone !== null && !isDataZone(body.data_zone)) {
+    return "data_zone must be one of eu, eu_option, transfer, local, or null";
+  }
+  if (
+    body.eu_processing !== undefined &&
+    body.eu_processing !== null &&
+    typeof body.eu_processing !== "boolean"
+  ) {
+    return "eu_processing must be true, false or null";
+  }
+  let allowedModels: string[] | undefined;
+  if (body.allowed_models !== undefined && body.allowed_models !== null) {
+    const read = readAllowedModels(body.allowed_models);
+    if (typeof read === "string") return read;
+    allowedModels = read;
+  }
   if (body.preset !== undefined && !catalogPreset(body.preset)) {
     return `Unknown preset '${String(body.preset)}'`;
   }
@@ -179,7 +239,7 @@ function readEntryBody(body: unknown): Record<string, unknown> | string {
     if (ref !== undefined && (typeof ref !== "string" || !parseCredentialRef(ref)))
       return CREDENTIAL_REF_REFUSAL;
   }
-  return body;
+  return allowedModels ? { ...body, allowed_models: allowedModels } : body;
 }
 
 /**
@@ -230,12 +290,40 @@ function isPatchOrAbsent(entry: unknown): boolean {
   );
 }
 
+/** The `preset` the lowest-to-highest lower documents give entry `id`, the last one winning. */
+function lowerPreset(lowerEntries: unknown[]): unknown {
+  let preset: unknown;
+  for (const entry of lowerEntries)
+    if (isPlainObject(entry) && entry.preset !== undefined) preset = entry.preset;
+  return preset;
+}
+
+/**
+ * The required parameters of the entry's catalog preset that neither the
+ * entry nor a lower document's entry under the same id supplies. An entry
+ * without a catalog preset has none here; the SDK's schema checks its
+ * transport's parameters.
+ */
+function missingPresetParams(entry: Record<string, unknown>, lowerEntries: unknown[]): string[] {
+  const preset = catalogPreset(entry.preset ?? lowerPreset(lowerEntries));
+  if (!preset) return [];
+  const params: Record<string, unknown> = {};
+  for (const lower of lowerEntries) {
+    if (isPlainObject(lower) && isPlainObject(lower.params)) Object.assign(params, lower.params);
+  }
+  if (isPlainObject(entry.params)) Object.assign(params, entry.params);
+  return missingRequiredParams(preset, params);
+}
+
 /**
  * Upsert entry `id` in the scope's document.
  *
  * - **Own entry** — the body sets the editable fields (`BODY_KEYS`) — one it
- *   omits is removed — and optionally `kind`; fields it does not set (`kind`,
- *   `transport`, `params`, …) keep their written value.
+ *   omits is removed — and optionally `kind`, `params`, `data_zone`,
+ *   `eu_processing` and `allowed_models`; fields it does not set (`kind`,
+ *   `transport`, `params`, `data_zone`, …) keep their written value,
+ *   `params: {}` removes the parameters and `null` removes `data_zone`,
+ *   `eu_processing` or `allowed_models` (`[]` allows no model).
  * - **Patch** — when a lower document defines `id` and the body holds only
  *   {@link PATCH_KEYS}, the body is merged into the scope's stored entry for
  *   `id` (created when absent), leaving every other stored field alone.
@@ -243,11 +331,16 @@ function isPatchOrAbsent(entry: unknown): boolean {
  * The file and its directory are created when absent; other entries are kept
  * as written.
  *
- * 400: invalid id, secret-bearing or malformed body, a body for an inherited
- * entry that is neither a patch nor over an own full entry, or any error
- * diagnostic for the entry (as `data.diagnostics`; nothing is written). 403:
- * the entry is `locked: true` in some document. 409: the document on disk is
- * not a registry.
+ * 400: invalid id, secret-bearing or malformed body (`data_zone` outside
+ * eu | eu_option | transfer | local, a non-boolean `eu_processing`, an
+ * `allowed_models` that is not a list of distinct non-empty ids), a body for
+ * an inherited entry that is neither a patch nor over an own full entry, a
+ * preset's required parameter left out of `params` (named in the message,
+ * `data.missingParams`), or any error diagnostic for the entry (as
+ * `data.diagnostics`; nothing is written — `params` keys a transport does not
+ * accept are refused this way, by the SDK's schema). 403: the entry is
+ * `locked: true` in some document. 409: the document on disk is not a
+ * registry.
  */
 export function upsertProviderEntry(
   scope: ProviderWriteScope,
@@ -294,6 +387,16 @@ export function upsertProviderEntry(
         )
       : {};
     entry = { ...kept, ...fields };
+    if (isPlainObject(entry.params) && Object.keys(entry.params).length === 0) delete entry.params;
+    for (const key of NULLABLE_BODY_KEYS) if (entry[key] === null) delete entry[key];
+    const missing = missingPresetParams(entry, lowerEntries);
+    if (missing.length > 0) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `Provider '${id}' needs ${missing.map((key) => `params.${key}`).join(", ")} (required by preset '${String(entry.preset ?? lowerPreset(lowerEntries))}')`,
+        data: { missingParams: missing },
+      });
+    }
   }
   const next = { ...providers, [id]: entry };
 
@@ -336,9 +439,15 @@ export interface ProviderPresetSummary {
   label: string;
   kind: AIProviderPreset["kind"];
   surface?: AIProviderPreset["surface"];
+  /** How requests reach the surface; absent = `direct`. Azure transports offer Entra ID sign-in. */
+  transport?: AIProviderPreset["transport"];
   base_url?: string;
   base_url_env?: string;
   credential: { kind: AIProviderPreset["credential"]["kind"]; env?: string };
+  /** Default routing / voice parameters. */
+  params?: Record<string, string>;
+  /** `params` keys an entry naming this preset must supply. */
+  required_params?: string[];
 }
 
 /** Catalog presets (all of them by default), in catalog order. */
@@ -350,9 +459,12 @@ export function providerPresetSummaries(
     label: preset.label,
     kind: preset.kind,
     surface: preset.surface,
+    ...(preset.transport ? { transport: preset.transport } : {}),
     base_url: preset.base_url,
     base_url_env: preset.base_url_env,
     credential: { kind: preset.credential.kind, env: preset.credential.env },
+    ...(preset.params ? { params: { ...preset.params } } : {}),
+    ...(preset.required_params?.length ? { required_params: [...preset.required_params] } : {}),
   }));
 }
 
@@ -385,17 +497,19 @@ export type ProviderLayerName = ProviderWriteScope["name"];
 
 /**
  * The defining document's values for the `PUT`-editable fields a settings UI
- * edit dialog does not show. A `PUT` removes every editable field it omits,
- * so an edit sends these back unchanged instead of dropping them.
+ * edit dialog does not show (or shows only in part, as `params`). A `PUT`
+ * removes every editable field it omits, so an edit sends these back
+ * unchanged instead of dropping them.
  */
 export interface ProviderLayerFields {
   label?: unknown;
   headers?: unknown;
   model_map?: unknown;
   enabled?: unknown;
+  params?: unknown;
 }
 
-const LAYER_FIELD_KEYS = ["label", "headers", "model_map", "enabled"] as const;
+const LAYER_FIELD_KEYS = ["label", "headers", "model_map", "enabled", "params"] as const;
 
 /**
  * Tag each provider view of a scope with every registry document that holds