@skaile/forge-settings 1.3.2 → 1.4.0

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

@@ -0,0 +1,172 @@
+/**
+ * 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.
+ *
+ * Browser-safe on purpose — no `node:` imports.
+ */
+
+import {
+  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
+ * first. A preset this table does not name is `transfer`.
+ */
+export const PRESET_DATA_ZONES: Readonly<Record<string, DataZone>> = {
+  anthropic: "transfer",
+  openai: "transfer",
+  google: "transfer",
+  groq: "transfer",
+  deepseek: "transfer",
+  openrouter: "transfer",
+  mistral: "eu",
+  xai: "transfer",
+  together: "transfer",
+  fireworks: "transfer",
+  bedrock: "eu_option",
+  vertex: "eu_option",
+  "azure-openai": "eu_option",
+  foundry: "eu_option",
+  ollama: "local",
+  lmstudio: "local",
+  vllm: "local",
+  litellm: "transfer",
+  deepgram: "transfer",
+  elevenlabs: "transfer",
+};
+
+/** What a provider row's zone chip says. */
+export const DATA_ZONE_LABELS: Readonly<Record<DataZone, string>> = {
+  eu: "EU",
+  eu_option: "EU option",
+  transfer: "Transfer",
+  local: "Local",
+};
+
+/** 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>> = {
+  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 {@link DATA_ZONE_RULES}. */
+export function isDataZoneRule(value: unknown): value is DataZoneRule {
+  return typeof value === "string" && (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 {
+  return presetId !== undefined && Object.hasOwn(PRESET_DATA_ZONES, presetId)
+    ? PRESET_DATA_ZONES[presetId]
+    : undefined;
+}
+
+/**
+ * Where an entry processes data: its own `data_zone`, else the zone of the
+ * 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 {
+  return entry.data_zone ?? presetDataZone(entry.preset) ?? "transfer";
+}
+
+/**
+ * Whether `rule` allows an entry in `zone`: `any` allows all; `eu` allows
+ * `eu` and `local`; `eu_options` additionally allows `eu_option` when
+ * `euProcessing` is `true`.
+ */
+export function dataZoneAllows(
+  rule: DataZoneRule,
+  zone: DataZone,
+  euProcessing: boolean | undefined,
+): boolean {
+  if (rule === "any") return true;
+  if (zone === "eu" || zone === "local") return true;
+  return rule === "eu_options" && zone === "eu_option" && euProcessing === true;
+}
+
+/** Whether `rule` allows `entry` ({@link dataZoneAllows} over {@link entryDataZone}). */
+export function entryAllowedByDataZone(
+  entry: { data_zone?: DataZone; preset?: string; eu_processing?: boolean },
+  rule: DataZoneRule,
+): boolean {
+  return dataZoneAllows(rule, entryDataZone(entry), entry.eu_processing);
+}
+
+/**
+ * Why `rule` keeps an entry in `zone` out, naming the rule, or `undefined`
+ * when the rule allows it. Secret-free, safe to render.
+ */
+export function dataZoneRefusal(
+  rule: DataZoneRule,
+  zone: DataZone,
+  euProcessing: boolean | undefined,
+): string | undefined {
+  if (dataZoneAllows(rule, zone, euProcessing)) return undefined;
+  const why =
+    zone === "eu_option" && rule === "eu_options"
+      ? "EU processing is not on for this account"
+      : `this provider is ${DATA_ZONE_LABELS[zone]}`;
+  return `Blocked by the data-zone rule "${DATA_ZONE_RULE_LABELS[rule]}": ${why}.`;
+}
+
+/**
+ * The registry with only the entries `rule` allows, every kind alike
+ * (`llm`, `embed`, `stt`, `tts`). Order is kept; the input is not mutated. A
+ * merged registry comes back merged, its `order`, `origin` and `locked`
+ * narrowed to the kept entries.
+ */
+export function filterRegistryByDataZone(
+  registry: AIProviderRegistry,
+  rule: DataZoneRule,
+): AIProviderRegistry;
+export function filterRegistryByDataZone(
+  registry: MergedAIProviderRegistry,
+  rule: DataZoneRule,
+): MergedAIProviderRegistry;
+export function filterRegistryByDataZone(
+  registry: AIProviderRegistryView,
+  rule: DataZoneRule,
+): AIProviderRegistryView;
+export function filterRegistryByDataZone(
+  registry: AIProviderRegistryView,
+  rule: DataZoneRule,
+): AIProviderRegistryView {
+  const entries = isMergedRegistry(registry) ? registry.providers : registry;
+  const providers: AIProviderRegistry = {};
+  for (const [id, entry] of Object.entries(entries)) {
+    if (entryAllowedByDataZone(entry, rule)) providers[id] = entry;
+  }
+  if (!isMergedRegistry(registry)) return providers;
+  const kept = (id: string) => Object.hasOwn(providers, id);
+  return {
+    ...registry,
+    providers,
+    order: registry.order.filter(kept),
+    origin: Object.fromEntries(Object.entries(registry.origin).filter(([id]) => kept(id))),
+    locked: registry.locked.filter(kept),
+  };
+}

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

@@ -8,10 +8,15 @@
  * Eligibility is by wire surface, never by vendor name: an entry is eligible
  * for a harness when it is an enabled `llm` entry whose `surface` the harness
  * declares. A harness that declares no surfaces accepts every `llm` entry.
+ * A host's data-zone rule then keeps out the entries outside it: such an
+ * entry is reported as `blocked-by-rule`, never eligible and never chosen.
  *
  * Browser-safe on purpose — no `node:` imports.
  */
 
+import { DATA_ZONE_RULE_LABELS, dataZoneRefusal, presetDataZone } from "./data-zone";
+import type { DataZone, DataZoneRule } from "./provider-registry";
+
 /** How many registry entries a harness can run at once (`@skaile/workspaces` `HarnessInfo.providerPlurality`). */
 export type HarnessProviderPlurality = "registry" | "credentials-n" | "single";
 
@@ -33,6 +38,35 @@ export interface HarnessProviderCandidate {
   surface?: string;
   /** Absent means enabled. */
   enabled?: boolean;
+  /** 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;
+  /** The account's EU-processing setting is on. */
+  euProcessing?: boolean;
+}
+
+/** Why an entry on a surface the harness speaks still cannot be used. */
+export type HarnessProviderBlockReason = "blocked-by-rule";
+
+/** One entry the harness could speak to that the host's rule keeps out. */
+export interface HarnessProviderBlock {
+  id: string;
+  reason: HarnessProviderBlockReason;
+  /** The rule in force. */
+  rule: DataZoneRule;
+  /** The rule's label ("EU only"). */
+  ruleLabel: string;
+  /** The entry's effective zone. */
+  zone: DataZone;
+  /** What a settings table shows on the box it cannot tick. Secret-free. */
+  message: string;
+}
+
+/** What {@link resolveHarnessProviders} applies beyond the surface rule. */
+export interface HarnessProviderOptions {
+  /** The host's data-zone rule. Absent: `any`. */
+  dataZoneRule?: DataZoneRule;
 }
 
 /**
@@ -55,8 +89,10 @@ export interface HarnessProviderResolution<
   state: HarnessProviderState;
   /** The harness can run several providers at once. */
   multiple: boolean;
-  /** Stored pick ids that are no longer eligible, deduplicated, in stored order. */
+  /** Stored pick ids that are no longer eligible (blocked ones included), deduplicated, in stored order. */
   stale: string[];
+  /** Candidates on a surface the harness speaks that the data-zone rule keeps out, in registry order. */
+  blocked: HarnessProviderBlock[];
 }
 
 /** Whether `candidate` is an enabled `llm` entry on a surface `harness` speaks. */
@@ -70,22 +106,55 @@ export function isProviderEligibleForHarness(
   return candidate.surface !== undefined && harness.surfaces.includes(candidate.surface);
 }
 
+/**
+ * Why the data-zone rule keeps `candidate` out of `harness`, or `undefined`
+ * when it does not: the candidate must be otherwise eligible
+ * ({@link isProviderEligibleForHarness}) and outside `rule`.
+ */
+export function harnessProviderBlock(
+  harness: HarnessProviderInfo,
+  candidate: HarnessProviderCandidate,
+  rule: DataZoneRule | undefined,
+): HarnessProviderBlock | undefined {
+  if (!rule || rule === "any" || !isProviderEligibleForHarness(harness, candidate)) {
+    return undefined;
+  }
+  const zone = candidate.dataZone ?? presetDataZone(candidate.preset) ?? "transfer";
+  const message = dataZoneRefusal(rule, zone, candidate.euProcessing);
+  if (!message) return undefined;
+  return {
+    id: candidate.id,
+    reason: "blocked-by-rule",
+    rule,
+    ruleLabel: DATA_ZONE_RULE_LABELS[rule],
+    zone,
+    message,
+  };
+}
+
 /**
  * Resolve the providers a harness runs against.
  *
  * @param candidates Registry entries in registry order.
  * @param selection The stored per-harness pick (`SkaileSettings.harnessProviders[harness.id]`).
+ * @param options.dataZoneRule The host's data-zone rule: entries outside it are
+ *   `blocked`, never eligible, never auto-chosen; a stored pick of one is `stale`.
  */
 export function resolveHarnessProviders<C extends HarnessProviderCandidate>(
   harness: HarnessProviderInfo,
   candidates: readonly C[],
   selection: readonly string[] | undefined,
+  options: HarnessProviderOptions = {},
 ): HarnessProviderResolution<C> {
   const multiple =
     harness.providerPlurality === "registry" || harness.providerPlurality === "credentials-n";
-  const eligible = candidates.filter((candidate) =>
-    isProviderEligibleForHarness(harness, candidate),
-  );
+  const blocked: HarnessProviderBlock[] = [];
+  const eligible = candidates.filter((candidate) => {
+    if (!isProviderEligibleForHarness(harness, candidate)) return false;
+    const block = harnessProviderBlock(harness, candidate, options.dataZoneRule);
+    if (block) blocked.push(block);
+    return !block;
+  });
   const eligibleIds = new Set(eligible.map((candidate) => candidate.id));
   const picked = new Set(selection ?? []);
   const stale = [...picked].filter((id) => !eligibleIds.has(id));
@@ -100,10 +169,11 @@ export function resolveHarnessProviders<C extends HarnessProviderCandidate>(
       state: "chosen",
       multiple,
       stale,
+      blocked,
     };
   }
   if (eligible.length === 0) {
-    return { eligible, selected: [], state: "none-eligible", multiple, stale };
+    return { eligible, selected: [], state: "none-eligible", multiple, stale, blocked };
   }
   if (eligible.length === 1 || multiple) {
     return {
@@ -112,7 +182,8 @@ export function resolveHarnessProviders<C extends HarnessProviderCandidate>(
       state: "auto",
       multiple,
       stale,
+      blocked,
     };
   }
-  return { eligible, selected: [], state: "needs-choice", multiple, stale };
+  return { eligible, selected: [], state: "needs-choice", multiple, stale, blocked };
 }

package/src/runtime/shared/harnesses.ts

@@ -32,3 +32,28 @@ export const DEFAULT_ENABLED_HARNESSES = ["omp", "claude-sdk", "codex"] as const
 export function isExperimentalHarness(id: string): boolean {
   return !(DEFAULT_ENABLED_HARNESSES as readonly string[]).includes(id);
 }
+
+/**
+ * The model roles ("models per task") each multi-model harness renders, keyed by
+ * harness id. A harness absent here runs one model and takes no roles.
+ */
+export const HARNESS_ROLES: Readonly<Record<string, readonly string[]>> = {
+  omp: [
+    "default",
+    "smol",
+    "slow",
+    "vision",
+    "plan",
+    "designer",
+    "commit",
+    "tiny",
+    "task",
+    "advisor",
+  ],
+  continue: ["chat", "edit", "apply", "autocomplete", "embed", "rerank", "summarize"],
+};
+
+/** The role ids `harnessId` supports ({@link HARNESS_ROLES}); empty for a one-model harness. */
+export function harnessRoleIds(harnessId: string): string[] {
+  return [...(HARNESS_ROLES[harnessId] ?? [])];
+}