@skaile/forge-settings 1.3.3 → 2.0.0

package/dist/runtime/{server → workspaces}/harness-settings.d.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.
  *
@@ -21,9 +22,11 @@
  */
 import type { HarnessDetection } from "@skaile/workspaces/sdk/bridge";
 import type { HarnessInfo } from "@skaile/workspaces/types";
-import type { SkaileSettings } from "../shared/settings-types.js";
+import { type HarnessProviderBlock, type HarnessProviderCandidate } from "../shared/harness-providers.js";
+import type { AIProviderDataZoneRule } from "../shared/provider-registry.js";
+import type { SkaileSettings } from "./settings-types.js";
 /** The slice of {@link SkaileSettings} that selects, configures and locks harnesses. */
-export type HarnessSettings = Pick<SkaileSettings, "harness" | "harnessModels" | "harnessProviders" | "enabledHarnesses" | "lockHarness" | "lockProvider" | "lockModel" | "lockAudio">;
+export type HarnessSettings = Pick<SkaileSettings, "harness" | "harnessModels" | "harnessRoles" | "harnessProviders" | "enabledHarnesses" | "lockHarness" | "lockProvider" | "lockModel" | "lockAudio">;
 /** One lock flag and where its value comes from. */
 export type LockFlagStatus = {
     value: boolean;
@@ -59,16 +62,36 @@ 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 declare function buildHarnessRows(harnesses: HarnessInfo[], s: Pick<HarnessSettings, "enabledHarnesses">, detections?: readonly HarnessDetection[]): HarnessRow[];
+export declare function buildHarnessRows(harnesses: HarnessInfo[], s: Pick<HarnessSettings, "enabledHarnesses" | "harnessRoles">, detections?: readonly HarnessDetection[], providers?: HarnessRowProviders): HarnessRow[];
 /** What {@link validateHarnessSettingsPatch} hands back for a valid body. */
 export type HarnessSettingsPatch = {
     /**
@@ -77,9 +100,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;
 };
@@ -94,6 +117,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
@@ -114,6 +142,8 @@ 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).
  */
@@ -121,18 +151,21 @@ export declare function validateHarnessSettingsPatch(body: unknown, ctx: {
     catalog: Iterable<string>;
     current: HarnessSettings;
     locks: LockFlags;
+    runnableModels?: Iterable<string>;
 }): HarnessSettingsPatch | string;
-/** 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
@@ -146,10 +179,15 @@ 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 declare function applyHarnessLayers(layers: HarnessLayer[], locks: LockFlags): {
     harness: string | undefined;
     model: string | undefined;
+    roles: Record<string, string> | undefined;
     providers: string[] | undefined;
 };

package/dist/runtime/{server → workspaces}/harness-settings.js

@@ -1,6 +1,10 @@
+import {
+  harnessProviderBlock
+} from "../shared/harness-providers.js";
 import {
   DEFAULT_ENABLED_HARNESSES,
   HARNESS_LABELS,
+  harnessRoleIds,
   isExperimentalHarness
 } from "../shared/harnesses.js";
 const LOCK_FIELDS = [
@@ -21,15 +25,29 @@ export function resolveLockFlags(stored) {
 export function enabledHarnessIds(s) {
   return s.enabledHarnesses?.length ? s.enabledHarnesses : [...DEFAULT_ENABLED_HARNESSES];
 }
-export function buildHarnessRows(harnesses, s, detections = []) {
+export function buildHarnessRows(harnesses, s, detections = [], providers) {
   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 = {};
+    for (const role of roles) if (stored[role]) roleAssignments[role] = stored[role];
+    const blockedProviders = {};
+    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
+    };
+  });
 }
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const nonEmpty = (value) => typeof value === "string" && value ? value : void 0;
@@ -66,6 +84,19 @@ function sameIdLists(a, b) {
     (key) => b[key] !== void 0 && a[key].length === b[key].length && a[key].every((id, i) => id === b[key][i])
   );
 }
+function roleMaps(value) {
+  const maps = {};
+  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, b) {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => b[key] !== void 0 && sameEntries(a[key], b[key]));
+}
 export function validateHarnessSettingsPatch(body, ctx) {
   if (!isObject(body)) return "body must be an object";
   if ("model" in body) return "model is set per harness - use harnessModels";
@@ -120,6 +151,51 @@ export function validateHarnessSettingsPatch(body, ctx) {
       sessionAffecting = true;
     }
   }
+  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) : void 0;
+    const currentRoles = roleMaps(current.harnessRoles);
+    const nextRoles = {};
+    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 : void 0;
+      sessionAffecting = true;
+    }
+  }
   if ("enabledHarnesses" in body) {
     const raw = body.enabledHarnesses;
     if (!Array.isArray(raw) || !raw.every((id) => typeof id === "string")) {
@@ -163,5 +239,13 @@ export function applyHarnessLayers(layers, locks) {
     const ids = harness === void 0 ? void 0 : layer.harnessProviders?.[harness];
     return ids?.length ? ids : void 0;
   });
-  return { harness, model, providers };
+  let roles;
+  if (harness !== void 0) {
+    const merged = {};
+    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/dist/runtime/workspaces/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@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.js";
+export * from "./language-model.js";
+export * from "./model-endpoint.js";
+export * from "./provider-settings.js";
+export * from "./settings-defaults.js";
+export type { DomainConfig, SkaileSettings } from "./settings-types.js";

package/dist/runtime/workspaces/index.js

@@ -0,0 +1,5 @@
+export * from "./harness-settings.js";
+export * from "./language-model.js";
+export * from "./model-endpoint.js";
+export * from "./provider-settings.js";
+export * from "./settings-defaults.js";

package/dist/runtime/workspaces/language-model.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { MergedAIProviderRegistry } from "@skaile/provider-registry";
+import { type ResolvedLanguageModel, type ResolveRegistryLanguageModelOptions } from "../ai-sdk/index.js";
+/**
+ * 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 declare function workspaceCredentialStorePath(env?: Readonly<Record<string, string | undefined>>): string;
+/**
+ * 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 declare function loadWorkspaceProviderRegistry(projectDir: string): MergedAIProviderRegistry;
+/** 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 declare function resolveWorkspaceLanguageModel(selector: string, options: ResolveWorkspaceLanguageModelOptions): Promise<ResolvedLanguageModel>;

package/dist/runtime/workspaces/language-model.js

@@ -0,0 +1,26 @@
+import { join } from "node:path";
+import { loadMergedProviderRegistry } from "@skaile/workspaces/sdk/bridge";
+import { globalSkaileDir } from "@skaile/workspaces/sdk/core";
+import {
+  resolveRegistryLanguageModel
+} from "../ai-sdk/index.js";
+import { ModelResolutionError } from "../model/errors.js";
+export function workspaceCredentialStorePath(env) {
+  return env?.FORGE_CREDENTIAL_STORE || join(globalSkaileDir(), "forge-credentials.json");
+}
+export function loadWorkspaceProviderRegistry(projectDir) {
+  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;
+}
+export async function resolveWorkspaceLanguageModel(selector, options) {
+  const { projectDir, registry, ...rest } = options;
+  return resolveRegistryLanguageModel(selector, {
+    ...rest,
+    registry: registry ?? loadWorkspaceProviderRegistry(projectDir),
+    path: options.path ?? workspaceCredentialStorePath(options.env)
+  });
+}

package/dist/runtime/workspaces/model-endpoint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/** Env var names the runner hands its endpoint URL and token through. */
+export declare const WORKSPACE_MODEL_ENDPOINT_URL_ENV = "SKAILE_MODEL_ENDPOINT_URL";
+export declare 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;
+}
+/**
+ * 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 declare function readWorkspaceModelEndpoint(options: ReadWorkspaceModelEndpointOptions): Promise<WorkspaceModelEndpoint | null>;

package/dist/runtime/workspaces/model-endpoint.js

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isPlainObject } from "../shared/guards.js";
+export const WORKSPACE_MODEL_ENDPOINT_URL_ENV = "SKAILE_MODEL_ENDPOINT_URL";
+export const WORKSPACE_MODEL_ENDPOINT_TOKEN_ENV = "SKAILE_MODEL_ENDPOINT_TOKEN";
+const PREFIX = "Skaile model endpoint configuration";
+function isHttpUrl(value) {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+export async function readWorkspaceModelEndpoint(options) {
+  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 === void 0) return null;
+  const file = join(options.projectDir, ".skaile", "model-endpoint.json");
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new Error(`${PREFIX}: ${file} could not be read`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    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/dist/runtime/workspaces/provider-settings.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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`.
+ */
+/** 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 declare function migrateLegacyProviderSettings(settingsPath: string): LegacySettingsMigration;

package/dist/runtime/{server → workspaces}/provider-settings.js

@@ -1,9 +1,4 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import {
-  entriesOfKind,
-  selectVoiceEntryId,
-  VOICE_OVERRIDE_PARAM
-} from "../shared/provider-registry.js";
 export function migrateLegacyProviderSettings(settingsPath) {
   const result = {
     path: settingsPath,
@@ -53,29 +48,3 @@ export function migrateLegacyProviderSettings(settingsPath) {
   }
   return result;
 }
-export function resolveVoiceProvider(registry, kind, settings = {}, overrides = {}) {
-  const candidates = entriesOfKind(registry, kind);
-  if (candidates.length === 0) return void 0;
-  const warnings = [];
-  const wanted = (kind === "stt" ? settings.sttProvider : settings.ttsProvider)?.trim();
-  const ids = candidates.map(([id]) => id);
-  const providerId = selectVoiceEntryId(ids, wanted);
-  const entry = candidates[ids.indexOf(providerId)][1];
-  if (wanted && wanted !== providerId) {
-    warnings.push(
-      `settings name '${wanted}' for ${kind}, which is not an enabled ${kind} entry \u2014 using '${providerId}' instead`
-    );
-  }
-  const fallback = wanted !== providerId;
-  const settingsOverride = {};
-  const override = (kind === "stt" ? settings.sttLanguage : settings.ttsVoice)?.trim();
-  if (override) settingsOverride[VOICE_OVERRIDE_PARAM[kind]] = override;
-  return {
-    providerId,
-    entry,
-    ...entry.base_url ? { baseUrl: entry.base_url } : {},
-    params: { ...entry.params, ...settingsOverride, ...overrides },
-    fallback,
-    warnings
-  };
-}

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

@@ -4,7 +4,7 @@
  * Storage stays with the host: this module reads and writes nothing except the
  * one `settings.json` {@link migrateLegacyHarnessSettings} is pointed at.
  */
-import type { SkaileSettings } from "../shared/settings-types.js";
+import type { SkaileSettings } from "./settings-types.js";
 /**
  * Merged default settings for forge apps.
  *

package/dist/runtime/{shared → workspaces}/settings-types.d.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";
 /** Skill domain enablement configuration for a forge app installation. */
@@ -55,6 +55,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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/forge-settings",
-  "version": "1.3.3",
+  "version": "2.0.0",
   "description": "Provider and settings operations for Skaile forge apps: provider registry layers, credential store, env layers, model discovery, the providers panel, and editor / AI SDK model adapters.",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -26,6 +26,10 @@
     "./editor": {
       "types": "./dist/runtime/editor/index.d.ts",
       "import": "./dist/runtime/editor/index.js"
+    },
+    "./workspaces": {
+      "types": "./dist/runtime/workspaces/index.d.ts",
+      "import": "./dist/runtime/workspaces/index.js"
     }
   },
   "files": [
@@ -55,7 +59,7 @@
   },
   "dependencies": {
     "@nuxt/kit": "^4.0.0",
-    "@skaile/workspaces": "^9.0.0",
+    "@skaile/provider-registry": "^0.1.0",
     "ofetch": "^1.4.0",
     "yaml": "^2.9.0"
   },
@@ -65,6 +69,7 @@
     "@ai-sdk/openai-compatible": "^3.0.0",
     "@nuxt/ui": "^4.11.1",
     "@skaile/forge-editor": "^6.0.0",
+    "@skaile/workspaces": "^7.8.0 || ^8.0.0 || ^9.0.0 || ^10.0.0",
     "ai": "^7.0.0",
     "nuxt": "^4.0.0",
     "vue": "^3.5.0"
@@ -85,6 +90,9 @@
     "@skaile/forge-editor": {
       "optional": true
     },
+    "@skaile/workspaces": {
+      "optional": true
+    },
     "ai": {
       "optional": true
     },
@@ -102,6 +110,7 @@
     "@nuxt/schema": "^4.0.0",
     "@nuxt/ui": "^4.11.1",
     "@skaile/forge-editor": "^6.4.2",
+    "@skaile/workspaces": "^10.0.0",
     "@types/bun": "^1.2.0",
     "@types/node": "^22.0.0",
     "ai": "^7.0.155",