@skaile/forge-settings 0.0.0-stage → 1.0.0

package/dist/runtime/shared/provider-registry.d.ts

@@ -0,0 +1,255 @@
+/**
+ * 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).
+ */
+/** What an entry produces. `stt`/`tts` use the reduced voice record. */
+export declare const AI_PROVIDER_KINDS: readonly ["llm", "stt", "tts", "embed"];
+/** Union of {@link AI_PROVIDER_KINDS}. */
+export type AIProviderKind = (typeof AI_PROVIDER_KINDS)[number];
+/** Kinds that use the voice subset of the record. */
+export declare const AI_PROVIDER_VOICE_KINDS: readonly ["stt", "tts"];
+/** 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 declare const AI_PROVIDER_SURFACES: readonly ["anthropic-messages", "openai-completions", "openai-responses", "openai-codex-responses", "azure-openai-responses", "bedrock-converse-stream", "google-generative-ai", "google-vertex"];
+/** 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 declare const AI_PROVIDER_TRANSPORTS: readonly ["direct", "bedrock", "vertex", "foundry", "azure-openai"];
+/** Union of {@link AI_PROVIDER_TRANSPORTS}. */
+export type AIProviderTransport = (typeof AI_PROVIDER_TRANSPORTS)[number];
+/** How the credential is presented. */
+export declare const AI_PROVIDER_CREDENTIAL_KINDS: readonly ["api_key_header", "bearer", "sigv4", "google_adc", "azure_entra", "oauth", "command", "none"];
+/** Union of {@link AI_PROVIDER_CREDENTIAL_KINDS}. */
+export type AIProviderCredentialKind = (typeof AI_PROVIDER_CREDENTIAL_KINDS)[number];
+/** `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;
+/**
+ * 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 declare function isMergedRegistry(registry: AIProviderRegistryView): registry is MergedAIProviderRegistry;
+/** `enabled` defaults to `true`. */
+export declare function isEntryEnabled(entry: AIProviderEntry): boolean;
+/** Entries in registry order, as `[id, entry]` pairs. Both registry shapes accepted. */
+export declare function registryEntries(registry: AIProviderRegistryView): Array<[string, AIProviderEntry]>;
+/**
+ * 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 declare function entriesOfKind<K extends AIProviderKind>(registry: AIProviderRegistryView, kind: K): Array<[string, K extends AIProviderVoiceKind ? AIProviderVoiceEntry : AIProviderLlmEntry]>;
+/** Whether an entry uses the reduced voice record. Narrows `params` into view. */
+export declare function isVoiceEntry(entry: AIProviderEntry): entry is AIProviderVoiceEntry;
+/**
+ * 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 declare const VOICE_OVERRIDE_PARAM: {
+    readonly stt: "language";
+    readonly tts: "voice_id";
+};
+/** The settings field carrying each kind's {@link VOICE_OVERRIDE_PARAM} override. */
+export declare const VOICE_OVERRIDE_SETTING: {
+    readonly stt: "sttLanguage";
+    readonly tts: "ttsVoice";
+};
+/**
+ * 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 declare function selectVoiceEntryId(ids: readonly string[], wanted?: string): string | undefined;
+/** 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 declare function parseCredentialRef(ref: string): AIProviderCredentialRef | undefined;
+/** Render a parsed reference back to its `<form>:<body>` string. */
+export declare function formatCredentialRef(ref: AIProviderCredentialRef): string;
+/** The reference forms, spelled the way a credential editor offers them. */
+export declare const CREDENTIAL_REF_FORMS: readonly ["env:NAME", "keyring:service/account", "cmd:<shell command>", "platform:<configId>"];
+/** What a credential editor tells a user who typed something that is not a reference. */
+export declare const CREDENTIAL_REF_GUIDANCE: string;
+/**
+ * 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 declare function validateCredentialRef(value: string): string | undefined;

package/dist/runtime/shared/provider-registry.js

@@ -0,0 +1,112 @@
+export const AI_PROVIDER_KINDS = ["llm", "stt", "tts", "embed"];
+export const AI_PROVIDER_VOICE_KINDS = ["stt", "tts"];
+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"
+];
+export const AI_PROVIDER_TRANSPORTS = [
+  "direct",
+  "bedrock",
+  "vertex",
+  "foundry",
+  "azure-openai"
+];
+export const AI_PROVIDER_CREDENTIAL_KINDS = [
+  "api_key_header",
+  "bearer",
+  "sigv4",
+  "google_adc",
+  "azure_entra",
+  "oauth",
+  "command",
+  "none"
+];
+export function isMergedRegistry(registry) {
+  return Array.isArray(registry.order);
+}
+export function isEntryEnabled(entry) {
+  return entry.enabled !== false;
+}
+export function registryEntries(registry) {
+  if (isMergedRegistry(registry)) {
+    return registry.order.filter((id) => registry.providers[id] !== void 0).map((id) => [id, registry.providers[id]]);
+  }
+  return Object.entries(registry);
+}
+export function entriesOfKind(registry, kind) {
+  return registryEntries(registry).filter(
+    ([, entry]) => entry.kind === kind && isEntryEnabled(entry)
+  );
+}
+export function isVoiceEntry(entry) {
+  return entry.kind === "stt" || entry.kind === "tts";
+}
+export const VOICE_OVERRIDE_PARAM = { stt: "language", tts: "voice_id" };
+export const VOICE_OVERRIDE_SETTING = { stt: "sttLanguage", tts: "ttsVoice" };
+export function selectVoiceEntryId(ids, wanted) {
+  const trimmed = wanted?.trim();
+  if (trimmed && ids.includes(trimmed)) return trimmed;
+  return ids[0];
+}
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const CREDENTIAL_REF = /^(env|cmd|platform|keyring):([\s\S]+)$/;
+export function parseCredentialRef(ref) {
+  const match = CREDENTIAL_REF.exec(ref.trim());
+  if (!match) return void 0;
+  const body = match[2].trim();
+  if (body === "") return void 0;
+  switch (match[1]) {
+    case "env":
+      return ENV_NAME.test(body) ? { form: "env", name: body } : void 0;
+    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 void 0;
+      return { form: "keyring", service: body.slice(0, slash), account: body.slice(slash + 1) };
+    }
+    default:
+      return void 0;
+  }
+}
+export function formatCredentialRef(ref) {
+  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}`;
+  }
+}
+export const CREDENTIAL_REF_FORMS = [
+  "env:NAME",
+  "keyring:service/account",
+  "cmd:<shell command>",
+  "platform:<configId>"
+];
+export const CREDENTIAL_REF_GUIDANCE = `Enter a reference, not a key \u2014 ${CREDENTIAL_REF_FORMS.join(
+  " \xB7 "
+)}.`;
+export function validateCredentialRef(value) {
+  const trimmed = value.trim();
+  if (trimmed === "" || parseCredentialRef(trimmed)) return void 0;
+  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/dist/runtime/shared/settings-types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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/dist/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/dist/runtime/vue/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@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.js";
+export * from "../shared/harness-providers.js";
+export * from "../shared/harnesses.js";
+export * from "../shared/provider-registry.js";
+export * from "./settings-modal-scope.js";
+export * from "./useProvidersPanel.js";

package/dist/runtime/vue/index.js

@@ -0,0 +1,6 @@
+export * from "../shared/env-vars.js";
+export * from "../shared/harness-providers.js";
+export * from "../shared/harnesses.js";
+export * from "../shared/provider-registry.js";
+export * from "./settings-modal-scope.js";
+export * from "./useProvidersPanel.js";

package/dist/runtime/vue/settings-modal-scope.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The tier a settings modal edits, and the URLs of its routes.
+ *
+ * The URL protocol is the host's: every field names a route the host serves,
+ * and no component builds a URL from an id or a slug. `ForgeProvidersPanel`
+ * takes the `providers*` / `environmentUrl` / `providersLayer` fields of this
+ * record as its props; the rest belong to the host's own modal tabs (harness,
+ * voice, workspace), which stay in the host.
+ */
+/** Which settings tier a modal edits. */
+export type SettingsModalSettingsScope = "instance" | "workspace";
+/**
+ * The tier the modal edits: the instance (app-wide defaults) or one
+ * workspace. The caller owns every route: the modal never builds a URL from an
+ * id or slug.
+ */
+export interface SettingsModalScope {
+    /** Dialog header text, e.g. the workspace name. */
+    label: string;
+    /**
+     * `"instance"`: the Harness tab edits the instance defaults
+     * (`PUT /api/settings?scope=instance`); `"workspace"`: it edits this
+     * workspace's overrides through {@link settingsUrl}.
+     */
+    settingsScope: SettingsModalSettingsScope;
+    /**
+     * `GET`/`PUT` endpoint of this scope's settings: `/api/settings` for the
+     * instance, the workspace's override row (`{ harness, model }`) otherwise.
+     */
+    settingsUrl: string;
+    /** Base URL for the Workspace + Connectors tabs' config API calls. */
+    workspaceApiBaseUrl: string;
+    /** `GET` model catalog of this scope's registry, queried with `?harness=<id>`. */
+    modelsUrl: string;
+    /** Provider registry write base: `PUT|DELETE <url>/:id`, `GET <url>/detected`. */
+    providersWriteUrl: string;
+    /**
+     * `GET` endpoint of this scope's `.env` layer, which the Providers tab reads and
+     * writes. Defaults to the instance layer, `/api/settings/env`.
+     */
+    environmentUrl?: string;
+    /**
+     * `GET` endpoint listing registry entries with their credential status
+     * resolved against this scope's environment. Defaults to `/api/providers`.
+     */
+    providersUrl?: string;
+    /**
+     * The registry document the Providers tab edits, when it differs from
+     * {@link settingsScope}. A single-workspace app keeps instance settings but
+     * writes the workspace registry over a user-level one: `"workspace"` there
+     * makes the lower document's entries inherited and patchable.
+     */
+    providersLayer?: SettingsModalSettingsScope;
+    /** Workspace name for workspace-scope copy (the harness-change confirm); defaults to {@link label}. */
+    workspaceName?: string;
+    /** The caller may read but not write this scope (e.g. a `readonly` user, another owner's workspace). */
+    readOnly?: boolean;
+}
+/** Default `GET` route of the merged provider list. */
+export declare const DEFAULT_PROVIDERS_URL = "/api/providers";
+/** Default `GET`/`PUT` route of the instance `.env` layer. */
+export declare const DEFAULT_ENVIRONMENT_URL = "/api/settings/env";

package/dist/runtime/vue/settings-modal-scope.js

@@ -0,0 +1,2 @@
+export const DEFAULT_PROVIDERS_URL = "/api/providers";
+export const DEFAULT_ENVIRONMENT_URL = "/api/settings/env";