@skaile/forge-settings 0.0.0-stage → 1.0.1

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/providers-panel-model.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The providers panel's vocabulary: the types the panel and its composable
+ * share, the constants of its form, and the pure reference / error helpers.
+ * No Vue, no requests — testable on their own. The public types and constants
+ * are re-exported by `useProvidersPanel`; the rest is internal to the package.
+ */
+import type { EnvLayerId } from "../shared/env-vars.js";
+import type { AIProviderCredentialKind, AIProviderKind, AIProviderSurface } from "../shared/provider-registry.js";
+/** Registry document a provider entry is defined in. */
+export type ProvidersPanelLayer = "instance" | "workspace";
+/** Props both `ForgeProvidersPanel` variants declare. */
+export interface ProvidersPanelProps {
+    /** `GET` merged view for this scope (`/api/providers` | `/api/workspaces/:id/providers`). */
+    providersUrl: string;
+    /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`. */
+    providersWriteUrl: string;
+    /** Catalog preset summaries. Default `/api/providers/presets`. */
+    presetsUrl?: string;
+    /**
+     * The scope's `.env` route. `GET` on load and after every write; keys typed
+     * into the panel write through it. Omitted, no key can be entered.
+     */
+    environmentUrl?: string;
+    /** The scope's own registry document. */
+    layer: ProvidersPanelLayer;
+    /** Disables every write (non-admin at instance scope; provider lock). */
+    readOnly?: boolean;
+}
+/** Emits both variants declare. */
+export type ProvidersPanelEmit = (event: "changed") => void;
+/** One entry of `GET ${providersUrl}?all=1`. */
+export interface ProvidersPanelEntry {
+    id: string;
+    /** The entry's label, else its id. */
+    name: string;
+    kind: AIProviderKind;
+    /** Whether the credential reference resolved on the server. */
+    configured: boolean;
+    /** Why it did not resolve. Secret-free. */
+    error?: string;
+    credentialRef?: string;
+    credentialKind?: AIProviderCredentialKind;
+    hasEnvKey: boolean;
+    envKeyName?: string;
+    baseUrl?: string;
+    preset?: string;
+    surface?: AIProviderSurface;
+    enabled: boolean;
+    locked: boolean;
+    /** Registry documents holding the id, lowest first: `["instance"]`, `["workspace"]` or both. */
+    layers: ProvidersPanelLayer[];
+    /** The scope's own document's values for the editable fields the dialog does not show. */
+    layerFields?: Record<string, unknown>;
+}
+/** One catalog preset, as `GET /api/providers/presets` and `.../detected` list it. */
+export interface ProvidersPanelPreset {
+    id: string;
+    label: string;
+    kind: AIProviderKind;
+    surface?: AIProviderSurface;
+    base_url?: string;
+    base_url_env?: string;
+    credential: {
+        kind: AIProviderCredentialKind;
+        env?: string;
+    };
+}
+/** Where a row's entry lives relative to the scope's own document. */
+export type ProvidersPanelRowState = "own" | "inherited" | "patched";
+/** One entry of a row's credential select. */
+export interface ProvidersPanelCredentialOption {
+    /** An env var NAME, a literal non-env ref, {@link CREDENTIAL_ENTER_KEY} or {@link CREDENTIAL_OTHER_REF}. */
+    value: string;
+    /** `NAME ••••hint` | `NAME (not set)` | the literal ref | `Enter a key…` | `Other reference…`. */
+    label: string;
+    defined?: boolean;
+    hint?: string;
+    source?: EnvLayerId;
+    action?: "enter-key" | "other-ref";
+}
+/** A table row: the entry plus what the panel derives for it. */
+export interface ProvidersPanelRow extends ProvidersPanelEntry {
+    /** Own entry, an inherited one, or an inherited one this scope patched. */
+    state: ProvidersPanelRowState;
+    /** `instance` | `workspace` | `instance · overridden here`. */
+    badge: string;
+    /** Set on inherited rows. */
+    inheritedNote?: string;
+    /** Edit/Delete offered: the scope's document defines it and the panel is writable. */
+    editable: boolean;
+    /** Reset offered: a patched row of a writable panel. */
+    canReset: boolean;
+    /** The enabled switch is live. */
+    canToggle: boolean;
+    /** The entry takes a credential (its kind is not `none`). */
+    needsCredential: boolean;
+    /** The credential picker is live. */
+    canEditCredential: boolean;
+    /** The select's model: the env var NAME of an `env:` ref, else the literal ref, else `""`. */
+    credentialValue: string;
+    credentialOptions: ProvidersPanelCredentialOption[];
+    /** The preset it inherits, else its surface, else its kind. */
+    origin: string;
+    /** `configured · <source>`, `missing <VAR>`, the resolver's reason, or `No credential needed.`. */
+    status: string;
+    /** Which other layer defines or overrides the credential; see the panel contract. */
+    overrideNotices: string[];
+}
+/** The add/edit dialog's fields. */
+export interface ProvidersPanelForm {
+    /** A preset id, or {@link CUSTOM_PRESET}. */
+    preset: string;
+    id: string;
+    /** Custom entries only. */
+    surface: string;
+    /** Empty: the preset's endpoint. */
+    baseUrl: string;
+    /** Adding only: the `env:` variable the credential references. */
+    envName: string;
+    /** Adding only, "Set value now": written to the scope's `.env`, never to the provider route. */
+    secret: string;
+}
+/** The preset select's value for an entry that names no preset. */
+export declare const CUSTOM_PRESET = "__custom__";
+/** Credential select value: open the inline key editor. */
+export declare const CREDENTIAL_ENTER_KEY = "__enter_key__";
+/** Credential select value: open the inline reference editor. */
+export declare const CREDENTIAL_OTHER_REF = "__other_ref__";
+/** Registry ids the write routes accept (`isSafeProviderId` upstream). */
+export declare const PROVIDER_ID_PATTERN: RegExp;
+export declare const DEFAULT_PRESETS_URL = "/api/providers/presets";
+/** An `env:NAME` credential reference; group 1 is the variable name. */
+export declare const ENV_REF_PATTERN: RegExp;
+/** The credential kind a written reference gets when the row states none. */
+export declare const FALLBACK_CREDENTIAL_KIND: AIProviderCredentialKind;
+export declare const ENV_SOURCE_LABEL: Record<EnvLayerId, string>;
+export declare const OVERRIDES_INSTANCE_NOTICE = "Entering a key here stores it in this workspace's .env and overrides that value for this workspace.";
+/**
+ * The server's refusal for a failed request, else `fallback`. A registry
+ * rejection (`400` with `data.diagnostics`) reads as its diagnostics' messages.
+ */
+export declare function requestErrorMessage(err: unknown, fallback: string): string;
+/** The variable name of an `env:NAME` reference. */
+export declare function envNameOfRef(ref: string | undefined): string | undefined;
+/** `configured · …` for a reference that is not an env var. */
+export declare function nonEnvSourceLabel(ref: string): string | undefined;
+export declare const EMPTY_FORM: Readonly<ProvidersPanelForm>;

package/dist/runtime/vue/providers-panel-model.js

@@ -0,0 +1,37 @@
+export const CUSTOM_PRESET = "__custom__";
+export const CREDENTIAL_ENTER_KEY = "__enter_key__";
+export const CREDENTIAL_OTHER_REF = "__other_ref__";
+export const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+export const DEFAULT_PRESETS_URL = "/api/providers/presets";
+export const ENV_REF_PATTERN = /^env:(.+)$/;
+export const FALLBACK_CREDENTIAL_KIND = "api_key_header";
+export const ENV_SOURCE_LABEL = {
+  instance: "instance .env",
+  workspace: "workspace .env",
+  process: "boot environment"
+};
+export const OVERRIDES_INSTANCE_NOTICE = "Entering a key here stores it in this workspace's .env and overrides that value for this workspace.";
+export function requestErrorMessage(err, fallback) {
+  const e = err;
+  const details = (e?.data?.data?.diagnostics ?? []).map((d) => d.message).filter((m) => typeof m === "string" && m !== "");
+  if (details.length > 0) return details.join("; ");
+  const message = e?.data?.statusMessage ?? e?.statusMessage;
+  return typeof message === "string" && message ? message : fallback;
+}
+export function envNameOfRef(ref) {
+  return ref ? ENV_REF_PATTERN.exec(ref)?.[1] : void 0;
+}
+export function nonEnvSourceLabel(ref) {
+  if (ref.startsWith("keyring:")) return "keyring";
+  if (ref.startsWith("cmd:")) return "runtime-owned (cmd)";
+  if (ref.startsWith("platform:")) return "control-plane-owned (platform)";
+  return void 0;
+}
+export const EMPTY_FORM = {
+  preset: "",
+  id: "",
+  surface: "",
+  baseUrl: "",
+  envName: "",
+  secret: ""
+};