@skaile/forge-settings 0.0.0-stage → 1.0.1

package/src/runtime/editor/index.ts

@@ -0,0 +1,146 @@
+/**
+ * `@skaile/forge-settings/editor` — the editor's `models` port over a provider
+ * registry.
+ *
+ * `@skaile/forge-editor`'s AI routes ask the host's `ModelProvider`
+ * (`listModels` / `languageModel`) before their own runtime-config presets.
+ * This adapter answers from the host's registry: only `llm` entries on the
+ * `openai-completions` surface are offered, because the editor's transport is a
+ * chat-completions client (`@ai-sdk/openai-compatible`). A profile's id is the
+ * registry selector `<providerId>/<modelId>`, which `languageModel` receives
+ * back as `{ preset: id }`.
+ *
+ * The registry and the credential environment are supplied by the host on every
+ * call, so provider edits apply without a restart and nothing reads the ambient
+ * process. Failures are typed ({@link ModelResolutionError}); the host maps
+ * them to HTTP in `onFailure`.
+ *
+ * `@skaile/forge-editor` is an optional peer of this entry only, for its
+ * `ModelProvider` contract (types). `@ai-sdk/openai-compatible` builds the model.
+ */
+
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import type { ModelProfile, ModelRef } from "@skaile/forge-editor/ai";
+import type { ModelProvider } from "@skaile/forge-editor/server";
+import { ModelResolutionError, assertEntryAllowed } from "../model/errors";
+import { type CredentialPolicy, entryPolicyRefusal } from "../server/credential-policy";
+import { resolveEntryCredential } from "../server/credential-store";
+import { listAIProviderModels } from "../server/provider-service";
+import {
+  type AIProviderLlmEntry,
+  type AIProviderRegistryView,
+  entriesOfKind,
+} from "../shared/provider-registry";
+
+export { ModelResolutionError } from "../model/errors";
+export type { ModelResolutionCode } from "../model/errors";
+
+/** The editor can only speak chat completions. */
+const EDITOR_SURFACE = "openai-completions";
+
+/** Policy for an editor model call; see `CredentialPolicy`. */
+export interface EditorModelPolicyOptions {
+  /** Which credential references may be resolved; refused entries are not offered. */
+  policy?: CredentialPolicy;
+}
+
+/** The chat-completions entries (with an endpoint) of `registry`, by id. */
+function editorEntries(registry: AIProviderRegistryView): Map<string, AIProviderLlmEntry> {
+  const entries = new Map<string, AIProviderLlmEntry>();
+  for (const [id, entry] of entriesOfKind(registry, "llm")) {
+    if (entry.surface === EDITOR_SURFACE && entry.base_url) entries.set(id, entry);
+  }
+  return entries;
+}
+
+/**
+ * The registry's chat-completions models as editor model profiles, in registry
+ * order. With a policy, entries it refuses are left out.
+ */
+export function editorModelProfiles(
+  registry: AIProviderRegistryView,
+  options: EditorModelPolicyOptions = {},
+): ModelProfile[] {
+  const entries = editorEntries(registry);
+  const allowed = (providerId: string) => {
+    const entry = entries.get(providerId);
+    return entry !== undefined && !entryPolicyRefusal(entry, options.policy);
+  };
+  return listAIProviderModels(registry)
+    .filter((model) => allowed(model.providerId))
+    .map((model) => ({
+      id: model.id,
+      label: `${model.providerId} · ${model.modelId}`,
+      endpoint: entries.get(model.providerId)!.base_url!,
+      model: model.providerModelId,
+      source: "preset" as const,
+    }));
+}
+
+/**
+ * The language model of selector `ref.preset`, or `null` when the registry does
+ * not serve it (a browser-defined `{ endpoint, model, apiKey }` reference is the
+ * editor's own to resolve).
+ *
+ * @throws {ModelResolutionError} `policy_refused` when the policy refuses the
+ *   entry (checked before its credential is read); `unresolved` when its
+ *   credential reference does not resolve. Neither message carries a secret.
+ */
+export function editorLanguageModel(
+  registry: AIProviderRegistryView,
+  env: Record<string, string | undefined>,
+  ref: ModelRef,
+  options: EditorModelPolicyOptions = {},
+) {
+  if (!("preset" in ref)) return null;
+  const model = listAIProviderModels(registry).find((candidate) => candidate.id === ref.preset);
+  const entry = model && editorEntries(registry).get(model.providerId);
+  if (!model || !entry) return null;
+  assertEntryAllowed(entry, model.providerId, options.policy);
+  const credential = resolveEntryCredential(entry, {
+    env,
+    ...(options.policy ? { policy: options.policy } : {}),
+  });
+  if (credential.error && !credential.value) {
+    throw new ModelResolutionError(
+      "unresolved",
+      `provider '${model.providerId}': ${credential.error}`,
+      { providerId: model.providerId },
+    );
+  }
+  return createOpenAICompatible({
+    name: model.providerId,
+    baseURL: entry.base_url!,
+    ...(credential.value ? { apiKey: credential.value } : {}),
+    ...(entry.headers ? { headers: entry.headers } : {}),
+  }).chatModel(model.providerModelId);
+}
+
+/** Options for {@link createEditorModelProvider}. */
+export interface EditorModelProviderOptions extends EditorModelPolicyOptions {
+  /** The registry to serve, read on every call. */
+  registry: () => AIProviderRegistryView | Promise<AIProviderRegistryView>;
+  /** The environment `env:` references resolve against, read on every call. */
+  env: () => Record<string, string | undefined> | Promise<Record<string, string | undefined>>;
+  /** Turn a typed failure into the host's own error (e.g. its HTTP error). Default: rethrow as is. */
+  onFailure?: (error: ModelResolutionError) => Error;
+}
+
+/** The editor's `models` port over the host's registry. */
+export function createEditorModelProvider(options: EditorModelProviderOptions): ModelProvider {
+  return {
+    async languageModel(ref) {
+      try {
+        return editorLanguageModel(await options.registry(), await options.env(), ref, options);
+      } catch (error) {
+        if (error instanceof ModelResolutionError && options.onFailure)
+          throw options.onFailure(error);
+        throw error;
+      }
+    },
+    async listModels() {
+      const profiles = editorModelProfiles(await options.registry(), options);
+      return profiles.length > 0 ? profiles : null;
+    },
+  };
+}

package/src/runtime/model/errors.ts

@@ -0,0 +1,52 @@
+import { type CredentialPolicy, entryPolicyRefusal } from "../server/credential-policy";
+import type { AIProviderEntry } from "../shared/provider-registry";
+
+/**
+ * A model could not be resolved. Framework-free: the host decides which HTTP
+ * status (or tool error) each `code` becomes.
+ *
+ * `message` never carries a secret. `providerId` names the registry entry the
+ * selector routed to, when it got that far.
+ */
+export type ModelResolutionCode =
+  /** The registry has error diagnostics, so no selector can be trusted. */
+  | "registry_invalid"
+  /** No registry entry serves the selector. */
+  | "unknown_selector"
+  /** The host's credential policy refuses the entry; nothing was resolved. */
+  | "policy_refused"
+  /** The entry's credential, endpoint or provider SDK could not be resolved. */
+  | "unresolved";
+
+export class ModelResolutionError extends Error {
+  readonly code: ModelResolutionCode;
+  readonly providerId?: string;
+  constructor(
+    code: ModelResolutionCode,
+    message: string,
+    options: { providerId?: string; cause?: unknown } = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "ModelResolutionError";
+    this.code = code;
+    if (options.providerId !== undefined) this.providerId = options.providerId;
+  }
+}
+
+/**
+ * Throw `policy_refused` when `policy` refuses `entry`; no policy refuses
+ * nothing. The one place a model adapter turns a policy refusal into an error,
+ * so every adapter words it the same way. Nothing is resolved.
+ */
+export function assertEntryAllowed(
+  entry: AIProviderEntry,
+  providerId: string,
+  policy?: CredentialPolicy,
+): void {
+  const refusal = entryPolicyRefusal(entry, policy);
+  if (refusal) {
+    throw new ModelResolutionError("policy_refused", `provider '${providerId}': ${refusal}`, {
+      providerId,
+    });
+  }
+}

package/src/runtime/server/credential-policy.ts

@@ -0,0 +1,139 @@
+/**
+ * Credential policy — which references a host lets the credential layer touch.
+ *
+ * A reference names where a secret lives (`env:NAME`, `keyring:s/a`, `cmd:…`,
+ * `platform:…`). A host that stores provider entries an administrator typed,
+ * and runs next to its own secrets (a Directus token, an encryption key), must
+ * decide up front which references may be resolved at all. The decision is
+ * made *before* a reference is read: a refused reference is never resolved,
+ * never looked up in an environment and never passed on to a child process.
+ *
+ * The policy covers every place an entry names an environment variable:
+ *
+ * - `credential.ref` — by form, and for `env:` by variable name;
+ * - `${NAME}` interpolation tokens in `base_url`, `headers` and `query_params`,
+ *   which a spawned runtime expands from its environment. Only bare variable
+ *   names the `envNames` allow-list accepts pass; any other token is refused.
+ *
+ * No policy means no restriction: existing hosts keep their current reference
+ * handling. A policy is opt-in per host and states the host's rule explicitly.
+ */
+
+import type { AIProviderEntry, AIProviderRegistryView } from "../shared/provider-registry";
+import { parseCredentialRef, registryEntries } from "../shared/provider-registry";
+
+/** The four credential reference forms. */
+export type CredentialRefForm = "env" | "cmd" | "platform" | "keyring";
+
+/** A host's rule for which credential references may be resolved. */
+export interface CredentialPolicy {
+  /** Reference forms that may be resolved. Absent: every form. */
+  forms?: readonly CredentialRefForm[];
+  /**
+   * Environment variable names a reference or interpolation token may name:
+   * exact strings, or expressions that must match the whole name. Absent:
+   * any name.
+   */
+  envNames?: ReadonlyArray<string | RegExp>;
+}
+
+/** An entry the policy refused, and why. The reason is secret-free. */
+export interface PolicyRefusal {
+  providerId: string;
+  error: string;
+}
+
+const BARE_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const INTERPOLATION_TOKEN = /\$\{([^}]*)\}/g;
+
+/** Whether `name` passes the policy's `envNames` allow-list. */
+export function isEnvNameAllowed(name: string, policy: CredentialPolicy): boolean {
+  if (!policy.envNames) return true;
+  return policy.envNames.some((rule) => {
+    if (typeof rule === "string") return rule === name;
+    const match = new RegExp(rule.source, rule.flags.replace(/[gy]/g, "")).exec(name);
+    return match !== null && match.index === 0 && match[0] === name;
+  });
+}
+
+/**
+ * The reason a credential reference is refused, or `undefined` when the policy
+ * lets it through. A string that is not a reference is not this function's
+ * concern: it resolves to nothing anyway.
+ */
+export function credentialRefRefusal(ref: string, policy: CredentialPolicy): string | undefined {
+  const parsed = parseCredentialRef(ref);
+  if (!parsed) return undefined;
+  if (policy.forms && !policy.forms.includes(parsed.form)) {
+    return `credential references of the form '${parsed.form}:' are not allowed here`;
+  }
+  if (parsed.form === "env" && !isEnvNameAllowed(parsed.name, policy)) {
+    return `environment variable ${parsed.name} is not allowed here`;
+  }
+  return undefined;
+}
+
+function interpolationRefusal(
+  field: string,
+  value: string,
+  policy: CredentialPolicy,
+): string | undefined {
+  for (const match of value.matchAll(INTERPOLATION_TOKEN)) {
+    const name = match[1]!.trim();
+    if (!BARE_ENV_NAME.test(name) || !isEnvNameAllowed(name, policy)) {
+      return `${field} interpolates '\${${name}}', which is not allowed here`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The reason an entry is refused, or `undefined`: its credential reference and
+ * every environment name it interpolates are checked, nothing is resolved.
+ * Without a policy nothing is refused.
+ */
+export function entryPolicyRefusal(
+  entry: AIProviderEntry,
+  policy?: CredentialPolicy,
+): string | undefined {
+  if (!policy) return undefined;
+  const ref = entry.credential?.ref;
+  if (ref !== undefined) {
+    const refusal = credentialRefRefusal(ref, policy);
+    if (refusal) return refusal;
+  }
+  const fields: Array<[string, unknown]> = [
+    ["base_url", entry.base_url],
+    ...Object.entries(entry.headers ?? {}).map(([name, value]): [string, unknown] => [
+      `headers.${name}`,
+      value,
+    ]),
+    ...Object.entries((entry as { query_params?: Record<string, string> }).query_params ?? {}).map(
+      ([name, value]): [string, unknown] => [`query_params.${name}`, value],
+    ),
+  ];
+  for (const [field, value] of fields) {
+    if (typeof value !== "string") continue;
+    const refusal = interpolationRefusal(field, value, policy);
+    if (refusal) return refusal;
+  }
+  return undefined;
+}
+
+/**
+ * The registry without the entries the policy refuses, as a plain entry map in
+ * registry order, plus what was refused. Nothing is resolved.
+ */
+export function applyCredentialPolicy(
+  registry: AIProviderRegistryView,
+  policy: CredentialPolicy,
+): { registry: Record<string, AIProviderEntry>; refused: PolicyRefusal[] } {
+  const allowed: Record<string, AIProviderEntry> = {};
+  const refused: PolicyRefusal[] = [];
+  for (const [providerId, entry] of registryEntries(registry)) {
+    const error = entryPolicyRefusal(entry, policy);
+    if (error) refused.push({ providerId, error });
+    else allowed[providerId] = entry;
+  }
+  return { registry: allowed, refused };
+}