@skaile/forge-settings 1.3.3 → 2.0.0

package/src/runtime/{server → workspaces}/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,18 +23,26 @@
 
 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 { SkaileSettings } from "../shared/settings-types";
+import type { AIProviderDataZoneRule } from "../shared/provider-registry";
+import type { SkaileSettings } from "./settings-types";
 
 /** The slice of {@link SkaileSettings} that selects, configures and locks harnesses. */
 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?: AIProviderDataZoneRule;
+}
+
 /**
  * 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/workspaces/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `@skaile/forge-settings/workspaces` — the Skaile Workspaces integration:
+ * the Workspaces `settings.json` document (`SkaileSettings`, defaults, legacy
+ * migrations), harness settings, project-registry model resolution with the
+ * Workspaces keyring location, and the address of a running Workspaces model
+ * endpoint.
+ *
+ * The only entry that needs the optional peer `@skaile/workspaces`; the generic
+ * entries (`/server`, `/vue`, `/nuxt`, `/ai-sdk`, `/editor`) never import it.
+ */
+
+export * from "./harness-settings";
+export * from "./language-model";
+export * from "./model-endpoint";
+export * from "./provider-settings";
+export * from "./settings-defaults";
+export type { DomainConfig, SkaileSettings } from "./settings-types";

package/src/runtime/workspaces/language-model.ts

@@ -0,0 +1,82 @@
+/**
+ * Project-oriented model resolution for a Skaile Workspaces host: load the
+ * project's merged provider registry once (user + workspace layers + catalog),
+ * keep the forge keyring where Workspaces hosts always kept it, and delegate to
+ * the generic `resolveRegistryLanguageModel` (`@skaile/forge-settings/ai-sdk`).
+ */
+
+import { join } from "node:path";
+import type { MergedAIProviderRegistry } from "@skaile/provider-registry";
+import { loadMergedProviderRegistry } from "@skaile/workspaces/sdk/bridge";
+import { globalSkaileDir } from "@skaile/workspaces/sdk/core";
+import {
+  type ResolvedLanguageModel,
+  type ResolveRegistryLanguageModelOptions,
+  resolveRegistryLanguageModel,
+} from "../ai-sdk";
+import { ModelResolutionError } from "../model/errors";
+
+/**
+ * The forge keyring of a Workspaces host: `FORGE_CREDENTIAL_STORE` of `env`
+ * when set, else `<skaile home>/forge-credentials.json`, beside the user's
+ * `settings.json` (follows `$SKAILE_HOME`). Generic entries never assume this
+ * home; a Workspaces host passes it as the store `path` (or pins it into
+ * `FORGE_CREDENTIAL_STORE`).
+ */
+export function workspaceCredentialStorePath(
+  env?: Readonly<Record<string, string | undefined>>,
+): string {
+  return env?.FORGE_CREDENTIAL_STORE || join(globalSkaileDir(), "forge-credentials.json");
+}
+
+/**
+ * The merged provider registry of `projectDir` — the user layer, the
+ * project's `.skaile/providers.yml` and the catalog presets they name.
+ *
+ * @throws {ModelResolutionError} `registry_invalid` on any error diagnostic.
+ */
+export function loadWorkspaceProviderRegistry(projectDir: string): MergedAIProviderRegistry {
+  const { merged, diagnostics } = loadMergedProviderRegistry({ projectDir });
+  const errors = diagnostics
+    .filter((d) => d.severity === "error")
+    .map((d) => (d.path ? `${d.path}: ${d.message}` : d.message));
+  if (errors.length > 0) {
+    throw new ModelResolutionError("registry_invalid", `providers registry: ${errors.join("; ")}`);
+  }
+  return merged;
+}
+
+/** Options for {@link resolveWorkspaceLanguageModel}. */
+export interface ResolveWorkspaceLanguageModelOptions
+  extends Omit<ResolveRegistryLanguageModelOptions, "registry"> {
+  /** Workspace whose `.skaile/providers.yml` is the workspace layer. */
+  projectDir: string;
+  /**
+   * An already merged (e.g. transform-proxy-routed) registry. When set,
+   * `projectDir` is not read for providers; the selector, the policy check
+   * and the model all resolve against this registry.
+   */
+  registry?: MergedAIProviderRegistry;
+}
+
+/**
+ * The AI SDK model for `selector`, resolved against the registry of
+ * `projectDir` (read once) or the given `registry`.
+ *
+ * `keyring:` references read the store at `path`, else the environment's
+ * `FORGE_CREDENTIAL_STORE`, else {@link workspaceCredentialStorePath}.
+ *
+ * @throws {ModelResolutionError} `registry_invalid` (only when read from disk),
+ *   plus every failure of `resolveRegistryLanguageModel`.
+ */
+export async function resolveWorkspaceLanguageModel(
+  selector: string,
+  options: ResolveWorkspaceLanguageModelOptions,
+): Promise<ResolvedLanguageModel> {
+  const { projectDir, registry, ...rest } = options;
+  return resolveRegistryLanguageModel(selector, {
+    ...rest,
+    registry: registry ?? loadWorkspaceProviderRegistry(projectDir),
+    path: options.path ?? workspaceCredentialStorePath(options.env),
+  });
+}

package/src/runtime/workspaces/model-endpoint.ts

@@ -0,0 +1,100 @@
+/**
+ * Where a running `skaile serve --model-endpoint` can be reached: the
+ * OpenAI-compatible URL and its bearer token.
+ *
+ * Read-only: the runner writes, owns and removes `.skaile/model-endpoint.json`;
+ * this module only reads what the host points it at. No directory climbing, no
+ * working-directory lookup, and the token never appears in an error.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isPlainObject } from "../shared/guards";
+
+/** Env var names the runner hands its endpoint URL and token through. */
+export const WORKSPACE_MODEL_ENDPOINT_URL_ENV = "SKAILE_MODEL_ENDPOINT_URL";
+export const WORKSPACE_MODEL_ENDPOINT_TOKEN_ENV = "SKAILE_MODEL_ENDPOINT_TOKEN";
+
+/** Address of a Workspaces model endpoint. `token` is a secret. */
+export interface WorkspaceModelEndpoint {
+  /** `http(s)://<host>:<port>/v1`. */
+  url: string;
+  /** Bearer token; never log it. */
+  token: string;
+}
+
+/** Options for {@link readWorkspaceModelEndpoint}. */
+export interface ReadWorkspaceModelEndpointOptions {
+  /** Environment snapshot the URL/token pair is read from. */
+  env: Record<string, string | undefined>;
+  /** Project whose `.skaile/model-endpoint.json` is read when the env pair is absent. */
+  projectDir?: string;
+}
+
+const PREFIX = "Skaile model endpoint configuration";
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The endpoint address, or `null` when none is configured.
+ *
+ * 1. `SKAILE_MODEL_ENDPOINT_URL` + `SKAILE_MODEL_ENDPOINT_TOKEN` in `env` win.
+ *    Both must be set and the URL must be HTTP(S); one without the other is a
+ *    configuration error, not an absence.
+ * 2. Otherwise, only when `projectDir` is given, `<projectDir>/.skaile/model-endpoint.json`
+ *    (`{ url, token, pid }`). A missing file is `null`.
+ *
+ * @throws Error a malformed or incomplete configuration; the message names the
+ *   source and the problem, never the token.
+ */
+export async function readWorkspaceModelEndpoint(
+  options: ReadWorkspaceModelEndpointOptions,
+): Promise<WorkspaceModelEndpoint | null> {
+  const envUrl = options.env[WORKSPACE_MODEL_ENDPOINT_URL_ENV]?.trim() ?? "";
+  const envToken = options.env[WORKSPACE_MODEL_ENDPOINT_TOKEN_ENV]?.trim() ?? "";
+  if (envUrl || envToken) {
+    if (!envUrl || !envToken) {
+      throw new Error(
+        `${PREFIX}: ${WORKSPACE_MODEL_ENDPOINT_URL_ENV} and ${WORKSPACE_MODEL_ENDPOINT_TOKEN_ENV} must be set together`,
+      );
+    }
+    if (!isHttpUrl(envUrl)) {
+      throw new Error(`${PREFIX}: ${WORKSPACE_MODEL_ENDPOINT_URL_ENV} is not an http(s) URL`);
+    }
+    return { url: envUrl, token: envToken };
+  }
+
+  if (options.projectDir === undefined) return null;
+  const file = join(options.projectDir, ".skaile", "model-endpoint.json");
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new Error(`${PREFIX}: ${file} could not be read`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    // The parser's message can quote the file's content, i.e. the token.
+    throw new Error(`${PREFIX}: ${file} is not valid JSON`);
+  }
+  const record = isPlainObject(parsed) ? parsed : {};
+  const url = typeof record.url === "string" ? record.url.trim() : "";
+  const token = typeof record.token === "string" ? record.token.trim() : "";
+  if (!url || !token) {
+    throw new Error(`${PREFIX}: ${file} needs a non-empty "url" and "token"`);
+  }
+  if (!isHttpUrl(url)) {
+    throw new Error(`${PREFIX}: ${file} "url" is not an http(s) URL`);
+  }
+  return { url, token };
+}

package/src/runtime/workspaces/provider-settings.ts

@@ -0,0 +1,96 @@
+/**
+ * The legacy `settings.json` migration of a Workspaces host.
+ *
+ * A `settings.json` written before the 5.0.0 registry migration holds
+ * `provider` + a free-text `model`, and an `apiKeys` map of secrets. On first
+ * load the pair collapses into one `"<providerId>/<modelId>"` selector, and the
+ * `apiKeys` map is dropped with a warning — a plaintext key is never
+ * auto-written anywhere; the user moves it into `.env`.
+ *
+ * Voice selection over the same settings fields is generic:
+ * `resolveVoiceProvider` in `@skaile/forge-settings/server`.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+/** What {@link migrateLegacyProviderSettings} did to one settings file. */
+export interface LegacySettingsMigration {
+  /** The file that was inspected. */
+  path: string;
+  /** Whether the file was rewritten. */
+  changed: boolean;
+  /** The selector `provider` + `model` collapsed into, when that happened. */
+  model?: string;
+  /** Everything dropped or left untouched, and why. Secret-free. */
+  warnings: string[];
+}
+
+/**
+ * Migrate one legacy `settings.json` in place. Idempotent: a file with no
+ * legacy `provider` and no `apiKeys` is left byte-identical.
+ *
+ * An `apiKeys` map is removed from the file and never stored anywhere else:
+ * the registry holds references only, and a plaintext key has no safe
+ * automatic destination. Each non-empty entry is reported through `warnings`
+ * (without the key) so the user can move it into `.env`.
+ *
+ * @param settingsPath - Absolute path to a `settings.json`.
+ */
+export function migrateLegacyProviderSettings(settingsPath: string): LegacySettingsMigration {
+  const result: LegacySettingsMigration = {
+    path: settingsPath,
+    changed: false,
+    warnings: [],
+  };
+  if (!existsSync(settingsPath)) return result;
+
+  let settings: Record<string, unknown>;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8")) as Record<string, unknown>;
+  } catch (err) {
+    result.warnings.push(`${settingsPath} is not valid JSON (${(err as Error).message})`);
+    return result;
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    result.warnings.push(`${settingsPath} does not contain a settings object`);
+    return result;
+  }
+
+  // ── provider + free-text model → one selector ───────────────────────────
+  const legacyProvider = typeof settings.provider === "string" ? settings.provider.trim() : "";
+  if (legacyProvider) {
+    const model = typeof settings.model === "string" ? settings.model.trim() : "";
+    if (model && !model.includes("/")) {
+      settings.model = `${legacyProvider}/${model}`;
+      result.model = settings.model as string;
+    } else if (!model) {
+      result.warnings.push(
+        `provider '${legacyProvider}' had no model to namespace — the session now resolves ` +
+          "its model through the registry's own order",
+      );
+    }
+    delete settings.provider;
+    result.changed = true;
+  }
+
+  // ── apiKeys map → dropped, never stored ─────────────────────────────────
+  if ("apiKeys" in settings) {
+    const apiKeys = settings.apiKeys;
+    const hasSecret =
+      typeof apiKeys === "object" &&
+      apiKeys !== null &&
+      Object.values(apiKeys).some((value) => typeof value === "string" && value !== "");
+    if (hasSecret) {
+      result.warnings.push(
+        "apiKeys found in settings: move each key into .env and reference it from providers.yml (skaile providers add)",
+      );
+    }
+    delete settings.apiKeys;
+    result.changed = true;
+  }
+
+  if (result.changed) {
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+  }
+  return result;
+}

package/src/runtime/{server → workspaces}/settings-defaults.ts

@@ -7,7 +7,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { SETTINGS_DEFAULTS as CORE_DEFAULTS } from "@skaile/workspaces/sdk/core";
-import type { SkaileSettings } from "../shared/settings-types";
+import type { SkaileSettings } from "./settings-types";
 
 /**
  * App-level defaults merged on top of core defaults.

package/src/runtime/{shared → workspaces}/settings-types.ts

@@ -1,9 +1,9 @@
 /**
- * The settings document type forge apps share.
+ * The settings document type forge apps on Skaile Workspaces share.
  *
- * A leaf module: it imports types only, so the harness and provider settings
- * modules read `SkaileSettings` from here instead of from the broad server
- * entry. Browser-safe.
+ * It extends the Workspaces `settings.json` type, so it lives in the explicit
+ * `@skaile/forge-settings/workspaces` entry: the generic entries never see it.
+ * A leaf module: it imports types only.
  */
 
 import type { SkaileSettings as CoreSettings } from "@skaile/workspaces/sdk/core";
@@ -58,6 +58,13 @@ export interface SkaileSettings extends Omit<CoreSettings, "apiKeys"> {
    * harness, all of them) is used automatically.
    */
   harnessProviders?: Record<string, string[]>;
+  /**
+   * Per-harness model per task ("roles"): role id → model selector
+   * (`"<providerId>/<modelId>"`), keyed by harness id. Only harnesses with
+   * `HARNESS_ROLES` take roles (omp, Continue); hosts pass the session
+   * harness's map to `skaile serve --roles`. Frozen by `lockModel`.
+   */
+  harnessRoles?: Record<string, Record<string, string>>;
   /**
    * Instance allow-list of harness ids the harness picker offers. Absent means
    * `DEFAULT_ENABLED_HARNESSES`.