@skaile/forge-settings 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,118 @@
+/**
+ * Which registry providers a harness can run against, and which of
+ * them a session on it will use.
+ *
+ * One rule, applied identically by the settings dialog and the spawner, so the
+ * dialog never promises a provider the spawner will not deliver.
+ *
+ * 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.
+ *
+ * Browser-safe on purpose — no `node:` imports.
+ */
+
+/** How many registry entries a harness can run at once (`@skaile/workspaces` `HarnessInfo.providerPlurality`). */
+export type HarnessProviderPlurality = "registry" | "credentials-n" | "single";
+
+/** The slice of a harness the rule reads. `GET /api/agents` rows satisfy it. */
+export interface HarnessProviderInfo {
+  id: string;
+  /** Wire surfaces the harness speaks. Absent: every `llm` entry is eligible. */
+  surfaces?: readonly string[];
+  /** Absent means `"single"`. */
+  providerPlurality?: HarnessProviderPlurality;
+}
+
+/** The slice of a registry entry the rule reads. `GET /api/providers` rows satisfy it. */
+export interface HarnessProviderCandidate {
+  id: string;
+  /** Absent means `llm`. */
+  kind?: string;
+  /** Wire protocol of an `llm` entry. */
+  surface?: string;
+  /** Absent means enabled. */
+  enabled?: boolean;
+}
+
+/**
+ * - `chosen`: the stored pick, narrowed to what is still eligible, is used.
+ * - `auto`: nothing usable picked; the only eligible entry — or, for a multi
+ *   harness, every eligible entry — is used.
+ * - `none-eligible`: no entry fits; the harness runs on its native login.
+ * - `needs-choice`: a single-provider harness with several eligible entries and
+ *   no usable pick — the harness is not usable until one is chosen.
+ */
+export type HarnessProviderState = "chosen" | "auto" | "none-eligible" | "needs-choice";
+
+export interface HarnessProviderResolution<
+  C extends HarnessProviderCandidate = HarnessProviderCandidate,
+> {
+  /** Eligible candidates, in candidate (registry) order. */
+  eligible: C[];
+  /** Ids the session uses, in registry order; empty for `none-eligible` and `needs-choice`. */
+  selected: string[];
+  state: HarnessProviderState;
+  /** The harness can run several providers at once. */
+  multiple: boolean;
+  /** Stored pick ids that are no longer eligible, deduplicated, in stored order. */
+  stale: string[];
+}
+
+/** Whether `candidate` is an enabled `llm` entry on a surface `harness` speaks. */
+export function isProviderEligibleForHarness(
+  harness: HarnessProviderInfo,
+  candidate: HarnessProviderCandidate,
+): boolean {
+  if ((candidate.kind ?? "llm") !== "llm") return false;
+  if (candidate.enabled === false) return false;
+  if (!harness.surfaces) return true;
+  return candidate.surface !== undefined && harness.surfaces.includes(candidate.surface);
+}
+
+/**
+ * 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]`).
+ */
+export function resolveHarnessProviders<C extends HarnessProviderCandidate>(
+  harness: HarnessProviderInfo,
+  candidates: readonly C[],
+  selection: readonly string[] | undefined,
+): HarnessProviderResolution<C> {
+  const multiple =
+    harness.providerPlurality === "registry" || harness.providerPlurality === "credentials-n";
+  const eligible = candidates.filter((candidate) =>
+    isProviderEligibleForHarness(harness, candidate),
+  );
+  const eligibleIds = new Set(eligible.map((candidate) => candidate.id));
+  const picked = new Set(selection ?? []);
+  const stale = [...picked].filter((id) => !eligibleIds.has(id));
+  const usable = eligible
+    .filter((candidate) => picked.has(candidate.id))
+    .map((candidate) => candidate.id);
+
+  if (usable.length > 0) {
+    return {
+      eligible,
+      selected: multiple ? usable : usable.slice(0, 1),
+      state: "chosen",
+      multiple,
+      stale,
+    };
+  }
+  if (eligible.length === 0) {
+    return { eligible, selected: [], state: "none-eligible", multiple, stale };
+  }
+  if (eligible.length === 1 || multiple) {
+    return {
+      eligible,
+      selected: eligible.map((candidate) => candidate.id),
+      state: "auto",
+      multiple,
+      stale,
+    };
+  }
+  return { eligible, selected: [], state: "needs-choice", multiple, stale };
+}

package/src/runtime/shared/harnesses.ts

@@ -0,0 +1,34 @@
+/**
+ * Harness catalog vocabulary shared by the server and the settings UI.
+ *
+ * A harness is a coding-agent product; `@skaile/workspaces` 6 names the adapter
+ * that runs it the same way, so these ids are the ids `listHarnesses()` reports
+ * (`--harness <id>`).
+ *
+ * {@link DEFAULT_ENABLED_HARNESSES} are the harnesses an instance offers when
+ * its settings name no `enabledHarnesses`; every other harness is experimental
+ * and must be enabled explicitly.
+ *
+ * Browser-safe on purpose — no `node:` imports.
+ */
+
+/** Display labels keyed by harness id. Unknown ids fall back to the harness's own name. */
+export const HARNESS_LABELS: Record<string, string> = {
+  omp: "oh-my-pi",
+  "claude-sdk": "Claude Code",
+  codex: "Codex",
+  gemini: "Gemini CLI",
+  qwen: "Qwen Code",
+  opencode: "OpenCode",
+  goose: "Goose",
+  continue: "Continue",
+  echo: "Echo (E2E mock)",
+};
+
+/** Harness ids an instance enables when its settings carry no `enabledHarnesses`. */
+export const DEFAULT_ENABLED_HARNESSES = ["omp", "claude-sdk", "codex"] as const;
+
+/** Whether `id` is outside {@link DEFAULT_ENABLED_HARNESSES}, i.e. opt-in only. */
+export function isExperimentalHarness(id: string): boolean {
+  return !(DEFAULT_ENABLED_HARNESSES as readonly string[]).includes(id);
+}

package/src/runtime/shared/provider-registry.ts

@@ -0,0 +1,391 @@
+/**
+ * The AI provider registry vocabulary, as forge-settings speaks it.
+ *
+ * `@skaile/workspaces` owns this schema (`core/src/provider-registry.ts`): the
+ * validator, the layer merge, the catalog presets and the model-reference
+ * resolver live there and are deliberately NOT reimplemented here. What follows
+ * is a *structural* mirror of the record so browser bundles do not import the
+ * workspaces core. Field names, union members and optionality match the
+ * upstream record exactly, so an entry produced by the runtime is assignable to
+ * these types and vice versa.
+ *
+ * Browser-safe on purpose — no `node:` imports — so the settings modal renders
+ * registry entries with the same types the server resolves them with.
+ *
+ * Vocabulary: these are **AI provider** records. They are unrelated to the
+ * platform's connector `ProviderType`/`ProviderLink` (git, SharePoint, Drive).
+ */
+
+// ── Enums ──────────────────────────────────────────────────────────────────
+
+/** What an entry produces. `stt`/`tts` use the reduced voice record. */
+export const AI_PROVIDER_KINDS = ["llm", "stt", "tts", "embed"] as const;
+
+/** Union of {@link AI_PROVIDER_KINDS}. */
+export type AIProviderKind = (typeof AI_PROVIDER_KINDS)[number];
+
+/** Kinds that use the voice subset of the record. */
+export const AI_PROVIDER_VOICE_KINDS = ["stt", "tts"] as const;
+
+/** Union of {@link AI_PROVIDER_VOICE_KINDS}. */
+export type AIProviderVoiceKind = (typeof AI_PROVIDER_VOICE_KINDS)[number];
+
+/** Wire protocol of an `llm`/`embed` entry — omp's `api` values verbatim. */
+export const AI_PROVIDER_SURFACES = [
+  "anthropic-messages",
+  "openai-completions",
+  "openai-responses",
+  "openai-codex-responses",
+  "azure-openai-responses",
+  "bedrock-converse-stream",
+  "google-generative-ai",
+  "google-vertex",
+] as const;
+
+/** Union of {@link AI_PROVIDER_SURFACES}. */
+export type AIProviderSurface = (typeof AI_PROVIDER_SURFACES)[number];
+
+/** How the request reaches the surface — selects the `params` shape. */
+export const AI_PROVIDER_TRANSPORTS = [
+  "direct",
+  "bedrock",
+  "vertex",
+  "foundry",
+  "azure-openai",
+] as const;
+
+/** Union of {@link AI_PROVIDER_TRANSPORTS}. */
+export type AIProviderTransport = (typeof AI_PROVIDER_TRANSPORTS)[number];
+
+/** How the credential is presented. */
+export const AI_PROVIDER_CREDENTIAL_KINDS = [
+  "api_key_header",
+  "bearer",
+  "sigv4",
+  "google_adc",
+  "azure_entra",
+  "oauth",
+  "command",
+  "none",
+] as const;
+
+/** Union of {@link AI_PROVIDER_CREDENTIAL_KINDS}. */
+export type AIProviderCredentialKind = (typeof AI_PROVIDER_CREDENTIAL_KINDS)[number];
+
+// ── Record ─────────────────────────────────────────────────────────────────
+
+/** `transport: bedrock` routing parameters. */
+export interface AIProviderBedrockParams {
+  /** AWS region, e.g. `us-east-1`. */
+  region: string;
+}
+
+/** `transport: vertex` routing parameters. */
+export interface AIProviderVertexParams {
+  /** GCP project id. */
+  project: string;
+  /** Vertex location, e.g. `europe-west4`. */
+  location: string;
+  /** Model publisher; defaults to `google`. */
+  publisher?: string;
+}
+
+/** `transport: foundry` routing parameters. */
+export interface AIProviderFoundryParams {
+  /** Azure AI Foundry resource name. */
+  resource: string;
+}
+
+/** `transport: azure-openai` routing parameters. */
+export interface AIProviderAzureOpenAIParams {
+  /** Azure OpenAI resource name. */
+  resource: string;
+  /** Deployment the request is routed to. */
+  deployment: string;
+  /** `api-version` query value. */
+  api_version: string;
+}
+
+/** Voice parameters, typed per preset: Deepgram `{model, language}`, ElevenLabs `{voice_id, output_format}`. */
+export type AIProviderVoiceParams = Record<string, string | number | boolean>;
+
+/** The `transport` → `params` discriminated union. */
+export type AIProviderTransportSlice =
+  | { transport?: "direct"; params?: Record<string, never> }
+  | { transport: "bedrock"; params: AIProviderBedrockParams }
+  | { transport: "vertex"; params: AIProviderVertexParams }
+  | { transport: "foundry"; params: AIProviderFoundryParams }
+  | { transport: "azure-openai"; params: AIProviderAzureOpenAIParams };
+
+/** Reference to a secret — never the secret itself. See {@link parseCredentialRef}. */
+export interface AIProviderCredential {
+  kind: AIProviderCredentialKind;
+  /**
+   * `env:NAME` · `cmd:<shell>` · `platform:<configId>` · `keyring:<service>/<account>`.
+   * A literal secret here is a validation error, not a warning.
+   */
+  ref?: string;
+}
+
+/** Per-model capability facts, keyed by the logical (`model_map`) id. */
+export interface AIProviderCapabilities {
+  context_window?: number;
+  tools?: boolean;
+  images?: boolean;
+  thinking_max?: number;
+}
+
+/** omp-compatible discovery descriptor. */
+export interface AIProviderDiscovery {
+  type: string;
+  /** Path appended to `base_url` when the surface default does not apply. */
+  path?: string;
+}
+
+/** Fields every entry carries, whatever its `kind`. */
+export interface AIProviderEntryCommon {
+  /** Display name. Never load-bearing. */
+  label?: string;
+  /** Catalog preset this entry inherits from. */
+  preset?: string;
+  /** Literal endpoint; wins over the preset value and the transport derivation. */
+  base_url?: string;
+  /** Static, non-secret request headers. */
+  headers?: Record<string, string>;
+  credential?: AIProviderCredential;
+  /** Default `true`; read it through {@link isEntryEnabled}. */
+  enabled?: boolean;
+  /** Set by the control plane: lower layers cannot override this entry. */
+  locked?: boolean;
+}
+
+/** An `llm`/`embed` entry — the full record. */
+export type AIProviderLlmEntry = AIProviderEntryCommon &
+  AIProviderTransportSlice & {
+    kind: "llm" | "embed";
+    /** Required unless a `preset` supplies it. */
+    surface?: AIProviderSurface;
+    /** Azure's `api-version` lives here. */
+    query_params?: Record<string, string>;
+    /** Logical id → provider-side id. */
+    model_map?: Record<string, string>;
+    /** Keyed by the logical id, i.e. the `model_map` key. */
+    capabilities?: Record<string, AIProviderCapabilities>;
+    discovery?: AIProviderDiscovery;
+  };
+
+/**
+ * An `stt`/`tts` entry — the reduced record. `surface`, `transport`,
+ * `model_map`, `capabilities` and `discovery` are `llm`-only: a TTS voice is
+ * not a wire protocol. The voice defaults forge apps used to hardcode at their
+ * call sites (Deepgram model/language, ElevenLabs voice id/output format) live
+ * in `params`.
+ */
+export type AIProviderVoiceEntry = AIProviderEntryCommon & {
+  kind: AIProviderVoiceKind;
+  params?: AIProviderVoiceParams;
+};
+
+/** One registry entry. */
+export type AIProviderEntry = AIProviderLlmEntry | AIProviderVoiceEntry;
+
+/** Entry id → entry. Iteration order is registry order. */
+export type AIProviderRegistry = Record<string, AIProviderEntry>;
+
+/** Configuration layers, lowest precedence first. */
+export type AIProviderLayerId = "catalog" | "user" | "workspace" | "runtime" | "session";
+
+/** The merged, layered view the runtime hands to a session. */
+export interface MergedAIProviderRegistry {
+  version: 1;
+  providers: AIProviderRegistry;
+  /** Registry order: highest-precedence layer first, document order within a layer. */
+  order: string[];
+  /** Highest-precedence layer that contributed to each entry. */
+  origin: Record<string, AIProviderLayerId>;
+  /** Entries frozen by `locked: true`. */
+  locked: string[];
+}
+
+/** Either shape a consumer may be handed. */
+export type AIProviderRegistryView = AIProviderRegistry | MergedAIProviderRegistry;
+
+// ── Reading a registry ─────────────────────────────────────────────────────
+
+/**
+ * Whether a view is the layered shape rather than a bare entry map.
+ *
+ * Exported because anything that *rebuilds* a registry (rather than just
+ * reading it) has to put the entries back in the shape it was handed.
+ */
+export function isMergedRegistry(
+  registry: AIProviderRegistryView,
+): registry is MergedAIProviderRegistry {
+  return Array.isArray((registry as MergedAIProviderRegistry).order);
+}
+
+/** `enabled` defaults to `true`. */
+export function isEntryEnabled(entry: AIProviderEntry): boolean {
+  return entry.enabled !== false;
+}
+
+/** Entries in registry order, as `[id, entry]` pairs. Both registry shapes accepted. */
+export function registryEntries(
+  registry: AIProviderRegistryView,
+): Array<[string, AIProviderEntry]> {
+  if (isMergedRegistry(registry)) {
+    return registry.order
+      .filter((id) => registry.providers[id] !== undefined)
+      .map((id) => [id, registry.providers[id]] as [string, AIProviderEntry]);
+  }
+  return Object.entries(registry);
+}
+
+/**
+ * Enabled entries of one `kind`, in registry order.
+ *
+ * This is the replacement for every hardcoded provider-id list in the forge
+ * apps: which providers exist, and whether one does speech or chat, is a fact
+ * of the registry record, not of an app-local table.
+ */
+export function entriesOfKind<K extends AIProviderKind>(
+  registry: AIProviderRegistryView,
+  kind: K,
+): Array<[string, K extends AIProviderVoiceKind ? AIProviderVoiceEntry : AIProviderLlmEntry]> {
+  return registryEntries(registry).filter(
+    ([, entry]) => entry.kind === kind && isEntryEnabled(entry),
+  ) as Array<[string, K extends AIProviderVoiceKind ? AIProviderVoiceEntry : AIProviderLlmEntry]>;
+}
+
+/** Whether an entry uses the reduced voice record. Narrows `params` into view. */
+export function isVoiceEntry(entry: AIProviderEntry): entry is AIProviderVoiceEntry {
+  return entry.kind === "stt" || entry.kind === "tts";
+}
+
+// ── Voice selection ────────────────────────────────────────────────────────
+
+/**
+ * The one `params` key a settings override replaces, per voice kind.
+ *
+ * Shared so the server's `resolveVoiceProvider` and a settings UI cannot
+ * disagree about which parameter the user is allowed to override — the rest of
+ * an entry's `params` are registry facts.
+ */
+export const VOICE_OVERRIDE_PARAM = { stt: "language", tts: "voice_id" } as const;
+
+/** The settings field carrying each kind's {@link VOICE_OVERRIDE_PARAM} override. */
+export const VOICE_OVERRIDE_SETTING = { stt: "sttLanguage", tts: "ttsVoice" } as const;
+
+/**
+ * Pick which voice entry serves a kind, given the ids on offer in registry
+ * order and the id the settings name.
+ *
+ * A setting naming an entry the registry no longer has falls back to the first
+ * one rather than silencing the app. Both the server resolver and the settings
+ * modal go through this, so what the modal shows is what the request will use.
+ *
+ * @returns The chosen id, or `undefined` when no entry of that kind exists.
+ */
+export function selectVoiceEntryId(ids: readonly string[], wanted?: string): string | undefined {
+  const trimmed = wanted?.trim();
+  if (trimmed && ids.includes(trimmed)) return trimmed;
+  return ids[0];
+}
+
+// ── Credential references ──────────────────────────────────────────────────
+
+/** POSIX environment variable name. */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The four reference forms. */
+const CREDENTIAL_REF = /^(env|cmd|platform|keyring):([\s\S]+)$/;
+
+/** A parsed `credential.ref`. */
+export type AIProviderCredentialRef =
+  | { form: "env"; name: string }
+  | { form: "cmd"; command: string }
+  | { form: "platform"; configId: string }
+  | { form: "keyring"; service: string; account: string };
+
+/**
+ * Parse a `credential.ref`.
+ *
+ * Returns `undefined` for anything that is not one of the four reference forms
+ * — which, in a registry entry or a credential editor, means someone typed a
+ * literal secret.
+ */
+export function parseCredentialRef(ref: string): AIProviderCredentialRef | undefined {
+  const match = CREDENTIAL_REF.exec(ref.trim());
+  if (!match) return undefined;
+  const body = match[2].trim();
+  if (body === "") return undefined;
+  switch (match[1]) {
+    case "env":
+      return ENV_NAME.test(body) ? { form: "env", name: body } : undefined;
+    case "cmd":
+      return { form: "cmd", command: body };
+    case "platform":
+      return { form: "platform", configId: body };
+    case "keyring": {
+      const slash = body.indexOf("/");
+      if (slash <= 0 || slash === body.length - 1) return undefined;
+      return { form: "keyring", service: body.slice(0, slash), account: body.slice(slash + 1) };
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** Render a parsed reference back to its `<form>:<body>` string. */
+export function formatCredentialRef(ref: AIProviderCredentialRef): string {
+  switch (ref.form) {
+    case "env":
+      return `env:${ref.name}`;
+    case "cmd":
+      return `cmd:${ref.command}`;
+    case "platform":
+      return `platform:${ref.configId}`;
+    case "keyring":
+      return `keyring:${ref.service}/${ref.account}`;
+  }
+}
+
+/** The reference forms, spelled the way a credential editor offers them. */
+export const CREDENTIAL_REF_FORMS = [
+  "env:NAME",
+  "keyring:service/account",
+  "cmd:<shell command>",
+  "platform:<configId>",
+] as const;
+
+/** What a credential editor tells a user who typed something that is not a reference. */
+export const CREDENTIAL_REF_GUIDANCE = `Enter a reference, not a key — ${CREDENTIAL_REF_FORMS.join(
+  " · ",
+)}.`;
+
+/**
+ * Check what a credential editor holds.
+ *
+ * An empty field is valid: it means "no override, use the entry's own
+ * reference". Anything else must parse as one of the four forms — a pasted
+ * secret does not, and that is the case this exists for.
+ *
+ * The message never echoes the value: a user who pasted a live key must not
+ * see it rendered back into the page (or into a screenshot of it).
+ *
+ * @returns The refusal to show, or `undefined` when the field is acceptable.
+ */
+export function validateCredentialRef(value: string): string | undefined {
+  const trimmed = value.trim();
+  if (trimmed === "" || parseCredentialRef(trimmed)) return undefined;
+  // `cmd:` and `platform:` take any non-empty body, so a prefix with nothing
+  // usable behind it does not match at all and lands in the default.
+  switch (CREDENTIAL_REF.exec(trimmed)?.[1]) {
+    case "env":
+      return "An env: reference takes a variable name such as env:ANTHROPIC_API_KEY.";
+    case "keyring":
+      return "A keyring: reference takes <service>/<account>, such as keyring:forge/anthropic.";
+    default:
+      return `A credential is stored as a reference, never as a key. ${CREDENTIAL_REF_GUIDANCE}`;
+  }
+}

package/src/runtime/shared/settings-types.ts

@@ -0,0 +1,87 @@
+/**
+ * The settings document type forge apps 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.
+ */
+
+import type { SkaileSettings as CoreSettings } from "@skaile/workspaces/sdk/core";
+
+/** Skill domain enablement configuration for a forge app installation. */
+export interface DomainConfig {
+  /** Domain identifiers that are active for this installation. */
+  enabled: string[];
+  /** Domain shown by default for users with multi-domain access. */
+  default: string;
+}
+
+/**
+ * Full settings type for forge apps.
+ *
+ * Extends the core personal settings with forge-app-specific fields. The core
+ * type's legacy `apiKeys` field is deliberately omitted: a provider is selected
+ * as part of `model`, and a credential is a reference held by the registry
+ * entry, never a settings value.
+ */
+export interface SkaileSettings extends Omit<CoreSettings, "apiKeys"> {
+  /**
+   * Model selection as `"<providerId>/<modelId>"`, where `providerId` is a
+   * registry entry id. A bare model id and an `@role` alias also resolve — the
+   * runtime does that against the session's registry.
+   */
+  model?: string;
+  /** Registry id of the `kind: stt` entry that transcribes speech. */
+  sttProvider?: string;
+  /** Registry id of the `kind: tts` entry that synthesizes speech. */
+  ttsProvider?: string;
+  /**
+   * Per-request override of the STT entry's `params.language`. Absent means the
+   * entry's own parameter wins — the endpoint's defaults are registry facts, not
+   * app settings.
+   */
+  sttLanguage?: string;
+  /** Per-request override of the TTS entry's `params.voice_id`. */
+  ttsVoice?: string;
+  /**
+   * Per-harness default model selector (`"<providerId>/<modelId>"`), keyed by
+   * harness id. Picked when a session starts on that harness without an
+   * explicit model. The default harness itself is the workspaces settings key
+   * `harness`, which selects a harness by id.
+   */
+  harnessModels?: Record<string, string>;
+  /**
+   * Per-harness provider pick: registry entry ids, keyed by harness id. Narrowed
+   * to the entries still eligible for that harness (enabled `llm` entries on a
+   * surface the harness speaks) by `resolveHarnessProviders`; absent or empty
+   * means "no pick" — the only eligible entry (or, for a multi-provider
+   * harness, all of them) is used automatically.
+   */
+  harnessProviders?: Record<string, string[]>;
+  /**
+   * Instance allow-list of harness ids the harness picker offers. Absent means
+   * `DEFAULT_ENABLED_HARNESSES`.
+   */
+  enabledHarnesses?: string[];
+  /**
+   * Admin locks, instance `settings.json` only (there is no environment
+   * override): when true, the instance's harness / provider pick / model /
+   * audio choice applies to every workspace and user. Read through
+   * `resolveLockFlags`.
+   */
+  lockHarness?: boolean;
+  lockProvider?: boolean;
+  lockModel?: boolean;
+  lockAudio?: boolean;
+  /** Active skill domain configuration. */
+  domains?: DomainConfig;
+  /** Optional display name for the agent shown in the UI. */
+  agentName?: string;
+  /** Optional user-supplied addendum materialized into the agent's system prompt. */
+  systemPromptExtension?: string;
+  /**
+   * When true the onboarding wizard has been completed (or skipped).
+   * Absent / false on a fresh install — triggers the first-run wizard.
+   */
+  hasCompletedOnboarding?: boolean;
+}

package/src/runtime/shims-vue.d.ts

@@ -0,0 +1,8 @@
+// Ambient module declaration so `tsc --noEmit` resolves `*.vue` imports.
+// Runtime resolution is handled by Vite / @vitejs/plugin-vue at build time.
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  // biome-ignore lint/suspicious/noExplicitAny: catch-all for SFC components
+  const component: DefineComponent<object, object, any>;
+  export default component;
+}

package/src/runtime/vue/index.ts

@@ -0,0 +1,15 @@
+/**
+ * `@skaile/forge-settings/vue` — browser-safe settings UI logic: the
+ * providers-panel composable, the modal scope contract and the registry /
+ * harness vocabulary the UI renders. No `node:` imports.
+ *
+ * `ForgeProvidersPanel` itself is registered as a component by
+ * `@skaile/forge-settings/nuxt`.
+ */
+
+export * from "../shared/env-vars";
+export * from "../shared/harness-providers";
+export * from "../shared/harnesses";
+export * from "../shared/provider-registry";
+export * from "./settings-modal-scope";
+export * from "./useProvidersPanel";