@skaile/forge-settings 0.0.0-stage → 1.0.0

package/dist/runtime/server/env-layers.js

@@ -0,0 +1,185 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AI_PROVIDER_PRESETS } from "@skaile/workspaces/sdk/bridge";
+import { parseCredentialRef, registryEntries } from "../shared/provider-registry.js";
+import {
+  ENV_LAYER_ORDER,
+  validateEnvVarName
+} from "../shared/env-vars.js";
+export * from "../shared/env-vars.js";
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*=(.*)$/;
+const NEEDS_QUOTES = /[\s#"'=\\]/;
+function parseValue(raw) {
+  const value = raw.trim();
+  if (value.startsWith('"')) {
+    for (let i = 1; i < value.length; i++) {
+      if (value[i] === "\\") {
+        i++;
+        continue;
+      }
+      if (value[i] === '"') {
+        return value.slice(1, i).replace(/\\([nr"\\])/g, (_, ch) => ch === "n" ? "\n" : ch === "r" ? "\r" : ch);
+      }
+    }
+    return value;
+  }
+  if (value.startsWith("'")) {
+    const end = value.indexOf("'", 1);
+    return end === -1 ? value : value.slice(1, end);
+  }
+  const comment = value.search(/\s#/);
+  return (comment === -1 ? value : value.slice(0, comment)).trim();
+}
+export function parseDotenv(text) {
+  const env = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = ASSIGNMENT.exec(line);
+    if (match) env[match[1]] = parseValue(match[2]);
+  }
+  return env;
+}
+export function readDotenvFile(path) {
+  try {
+    return parseDotenv(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function serializeValue(value) {
+  if (!NEEDS_QUOTES.test(value)) return value;
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+  return `"${escaped}"`;
+}
+function readTextIfExists(path) {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return "";
+    throw err;
+  }
+}
+function writeFileAtomic(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tmp, content, { mode: 384 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+  chmodSync(path, 384);
+}
+export function updateDotenvFile(path, patch) {
+  const text = readTextIfExists(path);
+  const lines = text === "" ? [] : text.replace(/\r?\n$/, "").split("\n");
+  const written = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const line of lines) {
+    const key = ASSIGNMENT.exec(line)?.[1];
+    if (key === void 0 || !Object.hasOwn(patch, key)) {
+      out.push(line);
+      continue;
+    }
+    if (written.has(key)) continue;
+    written.add(key);
+    const value = patch[key];
+    if (value === null) continue;
+    const prefix = /^\s*export\s/.test(line) ? "export " : "";
+    out.push(`${prefix}${key}=${serializeValue(value)}`);
+  }
+  for (const [key, value] of Object.entries(patch)) {
+    if (written.has(key) || value === null) continue;
+    out.push(`${key}=${serializeValue(value)}`);
+  }
+  writeFileAtomic(path, out.length > 0 ? `${out.join("\n")}
+` : "");
+}
+const DOTENV_IGNORE_LINES = {
+  ".env": true,
+  "/.env": true,
+  "*.env": true,
+  ".env*": true
+};
+export function ensureDotenvIgnored(dir) {
+  const path = join(dir, ".gitignore");
+  const text = readTextIfExists(path);
+  if (text.split(/\r?\n/).some((line) => DOTENV_IGNORE_LINES[line.trim()])) return;
+  const separator = text !== "" && !text.endsWith("\n") ? "\n" : "";
+  writeFileSync(path, `${text}${separator}.env
+`);
+}
+export function buildEnvSettingsDocument(input) {
+  const { layers } = input;
+  const referencedBy = /* @__PURE__ */ new Map();
+  for (const [id, entry] of registryEntries(input.registry)) {
+    const ref = entry.credential?.ref;
+    const parsed = ref ? parseCredentialRef(ref) : void 0;
+    if (parsed?.form !== "env") continue;
+    const ids = referencedBy.get(parsed.name) ?? [];
+    ids.push(id);
+    referencedBy.set(parsed.name, ids);
+  }
+  const names = new Set(referencedBy.keys());
+  for (const layer of ["instance", "workspace"]) {
+    for (const name of Object.keys(layers[layer] ?? {})) names.add(name);
+  }
+  for (const preset of Object.values(AI_PROVIDER_PRESETS)) {
+    const name = preset.credential.env;
+    if (name && ENV_LAYER_ORDER.some((layer) => layers[layer]?.[name])) names.add(name);
+  }
+  const vars = [];
+  const missing = [];
+  for (const name of [...names].sort()) {
+    const refs = [...referencedBy.get(name) ?? []].sort();
+    const defining = ENV_LAYER_ORDER.filter((layer) => {
+      const value2 = layers[layer]?.[name];
+      return value2 !== void 0 && value2 !== "";
+    });
+    const source = defining.at(-1);
+    if (source === void 0) {
+      if (refs.length > 0) missing.push({ name, referencedBy: refs });
+      continue;
+    }
+    const value = layers[source]?.[name] ?? "";
+    vars.push({
+      name,
+      hint: value.length >= 8 ? value.slice(-4) : "",
+      length: value.length,
+      source,
+      shadows: defining.slice(0, -1),
+      referencedBy: refs
+    });
+  }
+  return { scope: input.scope, editable: input.editable, layer: input.scope, vars, missing };
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function validateEnvSettingsUpdate(body) {
+  if (!isPlainObject(body)) return "Body must be an object with `set` and/or `unset`";
+  const set = {};
+  if (body.set !== void 0) {
+    if (!isPlainObject(body.set)) return "`set` must be an object of variable names to values";
+    for (const [name, value] of Object.entries(body.set)) {
+      const refusal = validateEnvVarName(name);
+      if (refusal) return refusal;
+      if (typeof value !== "string") return `Value of "${name}" must be a string`;
+      if (/[\r\n]/.test(value)) return `Value of "${name}" must be a single line`;
+      set[name] = value;
+    }
+  }
+  const unset = [];
+  if (body.unset !== void 0) {
+    if (!Array.isArray(body.unset)) return "`unset` must be an array of variable names";
+    for (const name of body.unset) {
+      if (typeof name !== "string") return "`unset` must be an array of variable names";
+      const refusal = validateEnvVarName(name);
+      if (refusal) return refusal;
+      if (Object.hasOwn(set, name)) return `"${name}" cannot be both set and unset`;
+      if (!unset.includes(name)) unset.push(name);
+    }
+  }
+  if (Object.keys(set).length === 0 && unset.length === 0) return "Nothing to change";
+  return { set, unset };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * .env file loading utilities for forge apps.
+ *
+ * Nuxt's built-in dotenv only injects NUXT_* variables into runtime config.
+ * API keys and provider preferences (ANTHROPIC_API_KEY, PREFERRED_PROVIDER,
+ * PREFERRED_MODEL, etc.) are plain env vars read directly via process.env, so
+ * forge apps need to load them explicitly at server startup.
+ *
+ * Usage pattern (in a Nitro plugin named 00.env-load.ts):
+ *
+ *   import { injectEnvFiles } from '@skaile/forge-settings/server'
+ *   injectEnvFiles([appRoot])
+ *
+ * ~/.env is always included as the lowest-priority source automatically.
+ */
+/**
+ * Parse the `.env` file in the given directory (see `parseDotenv` for the
+ * syntax). Returns an empty object if the file does not exist or cannot be read.
+ */
+export declare function loadEnvFile(dir: string): Record<string, string>;
+/**
+ * Load `.env` files and inject missing keys into process.env.
+ *
+ * Directories are merged in order — later directories take precedence.
+ * `~/.env` is always prepended as the lowest-priority source.
+ * Real environment variables (already in process.env) are never overwritten.
+ *
+ * @param appDirs - App-specific directories to scan (e.g. app root, project root)
+ */
+export declare function injectEnvFiles(appDirs: string[]): void;

package/dist/runtime/server/env.js

@@ -0,0 +1,15 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { readDotenvFile } from "./env-layers.js";
+export function loadEnvFile(dir) {
+  return readDotenvFile(path.join(dir, ".env"));
+}
+export function injectEnvFiles(appDirs) {
+  const merged = {};
+  for (const dir of [homedir(), ...appDirs]) {
+    Object.assign(merged, loadEnvFile(dir));
+  }
+  for (const [k, v] of Object.entries(merged)) {
+    if (!process.env[k] && v) process.env[k] = v;
+  }
+}

package/dist/runtime/server/harness-settings.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Harness settings — the one implementation both forge hosts share.
+ *
+ * A harness is a coding-agent product; `@skaile/workspaces` 6 names the adapter
+ * that runs it the same way (`listHarnesses()`), and the selecting settings key
+ * is `harness`.
+ *
+ * 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.
+ * - {@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 enabledHarnessIds} / {@link buildHarnessRows} — the harness catalog
+ *   `GET /api/agents` serves.
+ *
+ * Pure functions over plain values: no Node built-ins, no environment, no file access.
+ */
+import type { HarnessInfo } from "@skaile/workspaces/types";
+import type { SkaileSettings } from "../shared/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">;
+/** One lock flag and where its value comes from. */
+export type LockFlagStatus = {
+    value: boolean;
+    source: "settings" | "default";
+};
+/** The admin lock flags in force on an instance. */
+export type LockFlags = {
+    harness: LockFlagStatus;
+    provider: LockFlagStatus;
+    model: LockFlagStatus;
+    audio: LockFlagStatus;
+};
+/**
+ * The lock flags a stored settings document carries: a boolean `lock*` field is
+ * `{ value, source: "settings" }`, anything else `{ value: false, source:
+ * "default" }`. Pass the instance settings (locks describe the instance, not a
+ * workspace or a user).
+ */
+export declare function resolveLockFlags(stored: Partial<HarnessSettings> | null | undefined): LockFlags;
+/**
+ * The harness ids this instance offers: its `enabledHarnesses`, else
+ * {@link DEFAULT_ENABLED_HARNESSES}. A missing or empty list means the default
+ * set.
+ */
+export declare function enabledHarnessIds(s: Pick<HarnessSettings, "enabledHarnesses">): string[];
+/** A `GET /api/agents` row: the harness's own info plus how this instance presents it. */
+export type HarnessRow = HarnessInfo & {
+    /** Display label ({@link HARNESS_LABELS}, else the harness's own `name`). */
+    label: string;
+    /** Outside {@link DEFAULT_ENABLED_HARNESSES}: opt-in only. */
+    experimental: boolean;
+    /** Whether the instance's `enabledHarnesses` offers it. */
+    enabled: boolean;
+};
+/**
+ * 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.
+ */
+export declare function buildHarnessRows(harnesses: HarnessInfo[], s: Pick<HarnessSettings, "enabledHarnesses">): HarnessRow[];
+/** What {@link validateHarnessSettingsPatch} hands back for a valid body. */
+export type HarnessSettingsPatch = {
+    /**
+     * The fields to write; a key whose value is `undefined` is removed from the
+     * stored document. Only fields that carry something to write appear.
+     */
+    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.
+     */
+    sessionAffecting: boolean;
+};
+/**
+ * Validate the harness part of a settings write and compute what to store.
+ * Keys outside the harness set are ignored — the host validates its own.
+ *
+ * - `model`: refused — the model is set per harness (`harnessModels`).
+ * - `harness`: a catalog harness id that is enabled; empty/null removes it
+ *   (→ `"omp"`). The body key `driver` (the pre-6.0 spelling) is an alias for
+ *   one major: it is validated the same way and stored as `harness`. When both
+ *   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.
+ * - `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
+ *   kept), a harness whose array ends up empty is removed from the map, and the
+ *   key appears in `patch` only when the map changed. Ids are not checked
+ *   against the registry — a pick that is no longer eligible is shown as stale
+ *   in the modal.
+ * - `enabledHarnesses`: catalog ids, always including the resulting `harness`.
+ * - `lockHarness` / `lockProvider` / `lockModel` / `lockAudio`: booleans,
+ *   written only when they differ from `ctx.locks`.
+ *
+ * `ctx.locks` is used only to skip no-op lock writes; it is **not** enforced
+ * here. Whether the caller may write at all (admin, instance scope) and
+ * whether a locked field may be overridden is the host's decision, made before
+ * this runs.
+ *
+ * @param body the request body, untrusted.
+ * @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`).
+ * @returns the patch, or the error message of the first violated rule (a
+ * string, mirroring `validateEnvSettingsUpdate`; hosts answer 400 with it).
+ */
+export declare function validateHarnessSettingsPatch(body: unknown, ctx: {
+    catalog: Iterable<string>;
+    current: HarnessSettings;
+    locks: LockFlags;
+}): HarnessSettingsPatch | string;
+/** One settings layer's say in which harness, model 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>;
+    harnessProviders?: Record<string, string[]>;
+};
+/**
+ * Resolve the harness, model 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
+ * layer that sets a field wins. A locked field (`locks.harness` → `harness`,
+ * `locks.model` → `model`, `locks.provider` → `providers`) ignores every later
+ * layer: layer 0's value is the answer, even when it is unset.
+ *
+ * "Sets" means a non-empty `harness`/`model` string or a non-empty provider
+ * array; `""` and `[]` inherit. A layer's model is `layer.model`, else
+ * `layer.harnessModels[harness]`; its providers are
+ * `layer.harnessProviders[harness]` — both keyed by the *resolved* harness, so
+ * a pick stored for another harness never applies.
+ *
+ * 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;
+    providers: string[] | undefined;
+};

package/dist/runtime/server/harness-settings.js

@@ -0,0 +1,166 @@
+import {
+  DEFAULT_ENABLED_HARNESSES,
+  HARNESS_LABELS,
+  isExperimentalHarness
+} from "../shared/harnesses.js";
+const LOCK_FIELDS = [
+  ["lockHarness", "harness"],
+  ["lockProvider", "provider"],
+  ["lockModel", "model"],
+  ["lockAudio", "audio"]
+];
+export function resolveLockFlags(stored) {
+  const flag = (value) => typeof value === "boolean" ? { value, source: "settings" } : { value: false, source: "default" };
+  return {
+    harness: flag(stored?.lockHarness),
+    provider: flag(stored?.lockProvider),
+    model: flag(stored?.lockModel),
+    audio: flag(stored?.lockAudio)
+  };
+}
+export function enabledHarnessIds(s) {
+  return s.enabledHarnesses?.length ? s.enabledHarnesses : [...DEFAULT_ENABLED_HARNESSES];
+}
+export function buildHarnessRows(harnesses, s) {
+  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)
+  }));
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const nonEmpty = (value) => typeof value === "string" && value ? value : void 0;
+function isModelSelector(value) {
+  const slash = value.indexOf("/");
+  return slash > 0 && slash < value.length - 1;
+}
+function stringEntries(value) {
+  const entries = {};
+  if (!isObject(value)) return entries;
+  for (const [id, entry] of Object.entries(value))
+    if (typeof entry === "string" && entry) entries[id] = entry;
+  return entries;
+}
+function sameEntries(a, b) {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
+}
+function idLists(value) {
+  const lists = {};
+  if (!isObject(value)) return lists;
+  for (const [harnessId, ids] of Object.entries(value)) {
+    if (!Array.isArray(ids)) continue;
+    const kept = [
+      ...new Set(ids.filter((id) => typeof id === "string" && id !== ""))
+    ];
+    if (kept.length) lists[harnessId] = kept;
+  }
+  return lists;
+}
+function sameIdLists(a, b) {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every(
+    (key) => b[key] !== void 0 && a[key].length === b[key].length && a[key].every((id, i) => id === b[key][i])
+  );
+}
+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";
+  const { current, locks } = ctx;
+  const catalog = new Set(ctx.catalog);
+  const patch = {};
+  let sessionAffecting = false;
+  const currentHarness = nonEmpty(current.harness) ?? "omp";
+  let nextHarness = currentHarness;
+  const harnessKey = "harness" in body ? "harness" : "driver" in body ? "driver" : void 0;
+  if (harnessKey) {
+    const raw = body[harnessKey];
+    if (raw !== null && raw !== void 0 && typeof raw !== "string")
+      return `${harnessKey} must be a string`;
+    const value = typeof raw === "string" ? raw.trim() : "";
+    if (value && !catalog.has(value)) return `Unknown harness "${value}"`;
+    patch.harness = value || void 0;
+    nextHarness = value || "omp";
+    if (nextHarness !== currentHarness) sessionAffecting = true;
+  }
+  if ("harnessModels" in body) {
+    const raw = body.harnessModels;
+    if (!isObject(raw)) return "harnessModels must be an object";
+    const currentModels = stringEntries(current.harnessModels);
+    const nextModels = { ...currentModels };
+    for (const [id, entry] of Object.entries(raw)) {
+      if (!catalog.has(id)) return `harnessModels: unknown harness "${id}"`;
+      if (typeof entry !== "string") return `harnessModels.${id} must be a string`;
+      const value = entry.trim();
+      if (!value) {
+        delete nextModels[id];
+        continue;
+      }
+      if (!isModelSelector(value))
+        return `harnessModels.${id} must be a "providerId/modelId" selector`;
+      nextModels[id] = value;
+    }
+    patch.harnessModels = Object.keys(nextModels).length ? nextModels : void 0;
+    if (!sameEntries(currentModels, nextModels)) sessionAffecting = true;
+  }
+  if ("harnessProviders" in body) {
+    const raw = body.harnessProviders;
+    if (!isObject(raw)) return "harnessProviders must be an object";
+    for (const [id, ids] of Object.entries(raw)) {
+      if (!Array.isArray(ids) || !ids.every((entry) => typeof entry === "string")) {
+        return `harnessProviders.${id} must be an array of provider ids`;
+      }
+    }
+    const next = idLists(raw);
+    if (!sameIdLists(idLists(current.harnessProviders), next)) {
+      patch.harnessProviders = Object.keys(next).length ? next : void 0;
+      sessionAffecting = true;
+    }
+  }
+  if ("enabledHarnesses" in body) {
+    const raw = body.enabledHarnesses;
+    if (!Array.isArray(raw) || !raw.every((id) => typeof id === "string")) {
+      return "enabledHarnesses must be an array of harness ids";
+    }
+    const unknownId = raw.find((id) => !catalog.has(id));
+    if (unknownId !== void 0) return `enabledHarnesses: unknown harness "${unknownId}"`;
+    const enabled = [...new Set(raw)];
+    if (!enabled.includes(nextHarness))
+      return `enabledHarnesses must include the active harness "${nextHarness}"`;
+    patch.enabledHarnesses = enabled;
+    const before = enabledHarnessIds(current);
+    if (enabled.length !== before.length || enabled.some((id) => !before.includes(id)))
+      sessionAffecting = true;
+  } else if (harnessKey && !enabledHarnessIds(current).includes(nextHarness)) {
+    return `Harness "${nextHarness}" is not enabled`;
+  }
+  for (const [field, lock] of LOCK_FIELDS) {
+    const wanted = body[field];
+    if (wanted === void 0) continue;
+    if (typeof wanted !== "boolean") return `${field} must be a boolean`;
+    if (wanted !== locks[lock].value) patch[field] = wanted;
+  }
+  return { patch, sessionAffecting };
+}
+export function applyHarnessLayers(layers, locks) {
+  const pick = (locked, read) => {
+    if (locked) return layers[0] ? read(layers[0]) : void 0;
+    for (let i = layers.length - 1; i >= 0; i--) {
+      const value = read(layers[i]);
+      if (value !== void 0) return value;
+    }
+    return void 0;
+  };
+  const harness = pick(locks.harness.value, (layer) => nonEmpty(layer.harness));
+  const model = pick(
+    locks.model.value,
+    (layer) => nonEmpty(layer.model) ?? (harness === void 0 ? void 0 : nonEmpty(layer.harnessModels?.[harness]))
+  );
+  const providers = pick(locks.provider.value, (layer) => {
+    const ids = harness === void 0 ? void 0 : layer.harnessProviders?.[harness];
+    return ids?.length ? ids : void 0;
+  });
+  return { harness, model, providers };
+}

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

@@ -0,0 +1,23 @@
+/**
+ * `@skaile/forge-settings/server` — provider and settings operations for a
+ * host server: the registry vocabulary and layer editing, the credential
+ * store, env layers, harness settings, model discovery.
+ *
+ * Imports no Vue, no editor, no AI SDK and no agent session code. Storage,
+ * authentication and workspace permissions stay with the host.
+ */
+export * from "../shared/harness-providers.js";
+export * from "../shared/harnesses.js";
+export * from "../shared/provider-registry.js";
+export type { DomainConfig, SkaileSettings } from "../shared/settings-types.js";
+export * from "./credential-policy.js";
+export * from "./credential-store.js";
+export * from "./env.js";
+export * from "./env-layers.js";
+export * from "./harness-settings.js";
+export * from "./provider-discovery.js";
+export * from "./provider-layers.js";
+export * from "./provider-service.js";
+export * from "./provider-settings.js";
+export * from "./provider-write.js";
+export * from "./settings-defaults.js";

package/dist/runtime/server/index.js

@@ -0,0 +1,14 @@
+export * from "../shared/harness-providers.js";
+export * from "../shared/harnesses.js";
+export * from "../shared/provider-registry.js";
+export * from "./credential-policy.js";
+export * from "./credential-store.js";
+export * from "./env.js";
+export * from "./env-layers.js";
+export * from "./harness-settings.js";
+export * from "./provider-discovery.js";
+export * from "./provider-layers.js";
+export * from "./provider-service.js";
+export * from "./provider-settings.js";
+export * from "./provider-write.js";
+export * from "./settings-defaults.js";

package/dist/runtime/server/provider-discovery.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Live model discovery for one registry entry.
+ *
+ * `listAIProviderModels` (provider-service) answers from the registry's own
+ * `model_map`; this module asks the provider's REST API. The two are different
+ * facts and the result says which one it is:
+ *
+ * - `live` — the provider answered; `models` is its list.
+ * - `static` — the live request failed or the entry has no key, and `models` is
+ *   the offline catalog of its preset. It is a fallback, never a live answer.
+ * - `unsupported` — the entry has no catalog preset, so there is nothing to ask;
+ *   a host lets the admin type a model id.
+ * - `error` — nothing usable. The message is scrubbed.
+ *
+ * The error text is built here, never forwarded: a remote response body is
+ * never part of it, and every secret this call resolved (or the host names in
+ * `redact`) is removed from whatever text remains before it leaves the module.
+ *
+ * The credential policy (see `credential-policy.ts`) is applied to the entry
+ * before its credential is resolved, and `env:` references read from the
+ * explicit `env` only.
+ */
+import type { AIProviderRegistryView } from "../shared/provider-registry.js";
+import { type CredentialPolicy } from "./credential-policy.js";
+/** One model a provider offers. */
+export interface DiscoveredModel {
+    id: string;
+    name: string;
+}
+/** Outcome of {@link discoverProviderModels}. */
+export type ModelDiscoveryResult = {
+    status: "live";
+    providerId: string;
+    models: DiscoveredModel[];
+} | {
+    status: "static";
+    providerId: string;
+    models: DiscoveredModel[];
+    /** Why the live request did not produce the list. Scrubbed. */
+    reason: string;
+} | {
+    status: "unsupported";
+    providerId: string;
+    reason: string;
+} | {
+    status: "error";
+    providerId: string;
+    error: string;
+};
+/** Options for {@link discoverProviderModels}. */
+export interface DiscoverProviderModelsOptions {
+    /** Environment `env:` references and base-URL variables are read from. Required: no ambient process. */
+    env: Record<string, string | undefined>;
+    /** Which credential references may be resolved. Absent: no restriction. */
+    policy?: CredentialPolicy;
+    /** Extra strings to remove from error text, besides the secrets this call resolves. */
+    redact?: readonly string[];
+    /** Local encrypted store for `keyring:` references. */
+    key?: string;
+    path?: string;
+}
+/**
+ * Remove every occurrence of each secret (verbatim, URL-encoded and
+ * base64-encoded) from `text`, then cap its length.
+ */
+export declare function scrubSecrets(text: string, secrets: readonly (string | undefined)[]): string;
+/**
+ * Ask one registry entry's provider for its models.
+ *
+ * Never throws for a provider-side failure: that is the `error` / `static`
+ * result. A host maps `error` to its own status.
+ */
+export declare function discoverProviderModels(providerId: string, registry: AIProviderRegistryView, options: DiscoverProviderModelsOptions): Promise<ModelDiscoveryResult>;