ubume 0.1.0

package/src/core/process/processValidation.ts

@@ -0,0 +1,111 @@
+import { existsSync } from "fs";
+import { isAbsolute, resolve } from "path";
+
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+const BARE_EXECUTABLE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SHELL_METACHARACTER_PATTERN = /[;&|<>`$]/;
+const WINDOWS_BATCH_METACHARACTER_PATTERN = /[;&|<>`$^%!]/;
+
+export interface ExecutableValidationOptions {
+  label: string;
+  cwd?: string;
+  requireExistingPath?: boolean;
+  allowBareExecutable?: boolean;
+}
+
+function stripBalancedWrappingQuotes(value: string): string {
+  if (value.length < 2) return value;
+  const first = value[0];
+  const last = value[value.length - 1];
+  if ((first === `"` && last === `"`) || (first === `'` && last === `'`)) {
+    return value.slice(1, -1).trim();
+  }
+  return value;
+}
+
+function looksLikePath(value: string): boolean {
+  return /[\\/]/.test(value) || /^[A-Za-z]:/.test(value);
+}
+
+function isWindowsAbsolutePath(value: string): boolean {
+  return /^[A-Za-z]:[\\/]/.test(value);
+}
+
+function hasWindowsBatchExtension(value: string): boolean {
+  return /\.(?:cmd|bat)$/i.test(value);
+}
+
+function validateCommonExecutableSyntax(value: string, label: string): void {
+  if (!value) {
+    throw new Error(`${label} is empty.`);
+  }
+  if (CONTROL_CHARACTER_PATTERN.test(value)) {
+    throw new Error(`${label} contains control characters and cannot be used as an executable.`);
+  }
+  if (value.includes(`"`) || value.includes(`'`)) {
+    throw new Error(`${label} must be a command/path only, without embedded quotes.`);
+  }
+  if (SHELL_METACHARACTER_PATTERN.test(value)) {
+    throw new Error(`${label} contains shell metacharacters and cannot be used as an executable.`);
+  }
+}
+
+export function normalizeExecutableValue(
+  rawValue: string,
+  options: ExecutableValidationOptions,
+): string {
+  const allowBareExecutable = options.allowBareExecutable ?? true;
+  const requireExistingPath = options.requireExistingPath ?? false;
+  const cwd = options.cwd ?? process.cwd();
+  const trimmed = stripBalancedWrappingQuotes(rawValue.trim());
+
+  validateCommonExecutableSyntax(trimmed, options.label);
+
+  if (!looksLikePath(trimmed)) {
+    if (!allowBareExecutable) {
+      throw new Error(`${options.label} must be an executable path.`);
+    }
+    if (!BARE_EXECUTABLE_PATTERN.test(trimmed)) {
+      throw new Error(`${options.label} must be a single executable name without arguments.`);
+    }
+    return trimmed;
+  }
+
+  const normalized = isAbsolute(trimmed) || isWindowsAbsolutePath(trimmed) ? trimmed : resolve(cwd, trimmed);
+  validateCommonExecutableSyntax(normalized, options.label);
+
+  if (requireExistingPath && !existsSync(normalized)) {
+    throw new Error(
+      `${options.label} path does not exist: "${normalized}"\n` +
+      `Check the path is correct and the file is accessible, or unset ${options.label}.`,
+    );
+  }
+
+  return normalized;
+}
+
+export function validateExecutableForSpawn(
+  executable: string,
+  options: ExecutableValidationOptions,
+): string {
+  return normalizeExecutableValue(executable, {
+    ...options,
+    requireExistingPath: options.requireExistingPath ?? false,
+  });
+}
+
+export function validateWindowsBatchExecutableForCmd(
+  executable: string,
+  label: string,
+): void {
+  if (!hasWindowsBatchExtension(executable)) return;
+  if (WINDOWS_BATCH_METACHARACTER_PATTERN.test(executable)) {
+    throw new Error(`${label} contains characters that are unsafe for cmd.exe batch launch.`);
+  }
+}
+
+export function validateWindowsBatchArgumentForCmd(argument: string, label: string): void {
+  if (WINDOWS_BATCH_METACHARACTER_PATTERN.test(argument)) {
+    throw new Error(`${label} contains characters that are unsafe for cmd.exe batch launch.`);
+  }
+}

package/src/core/providerLauncher/launcher.ts

@@ -0,0 +1,220 @@
+import { spawn, type ChildProcess } from "child_process";
+import { accessSync, constants, existsSync } from "fs";
+import { delimiter, join } from "path";
+import { buildSpawnSpec } from "../executables/executableResolver.js";
+import { normalizeExecutableValue } from "../process/processValidation.js";
+import type { ProviderConfig, ProviderLaunchCommand } from "./types.js";
+
+export interface ProviderLaunchSpec {
+  executable: string;
+  args: string[];
+  cwd: string;
+}
+
+export type ProviderLaunchResult =
+  | { status: "completed"; exitCode: number | null; signal: NodeJS.Signals | null; message: string }
+  | { status: "disabled"; message: string }
+  | { status: "missing-command"; message: string }
+  | { status: "spawn-error"; message: string; errorCode?: string };
+
+interface RawModeStream {
+  isRaw?: boolean;
+  setRawMode?: (enabled: boolean) => unknown;
+}
+
+export interface LaunchProviderCliOptions {
+  cwd: string;
+  stdin?: RawModeStream | null;
+  beforeLaunch?: () => void;
+  afterLaunch?: () => void;
+  spawnImpl?: typeof spawn;
+  commandExists?: (executable: string) => Promise<boolean> | boolean;
+}
+
+function formatCommand(command: ProviderLaunchCommand): string {
+  return [command.executable, ...command.args].join(" ");
+}
+
+export function buildProviderLaunchSpec(provider: ProviderConfig, cwd: string): ProviderLaunchSpec | ProviderLaunchResult {
+  if (!provider.enabled) {
+    return {
+      status: "disabled",
+      message: `${provider.displayName} is disabled. Configure a command in Ubume's provider settings before launching it.`,
+    };
+  }
+
+  if (!provider.launchCommand?.executable.trim()) {
+    return {
+      status: "missing-command",
+      message: `${provider.displayName} does not have a launch command configured.`,
+    };
+  }
+
+  try {
+    return {
+      executable: normalizeExecutableValue(provider.launchCommand.executable, {
+        label: `${provider.displayName} launch command`,
+        cwd,
+      }),
+      args: provider.launchCommand.args,
+      cwd,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid launch command.";
+    return {
+      status: "spawn-error",
+      message: `${provider.displayName} has an unsafe launch command. ${message}`,
+    };
+  }
+}
+
+function setRawMode(stdin: RawModeStream | null | undefined, enabled: boolean): void {
+  try {
+    stdin?.setRawMode?.(enabled);
+  } catch {
+    // Some test streams and redirected terminals do not support raw-mode changes.
+  }
+}
+
+function executableLooksLikePath(executable: string): boolean {
+  return /[\\/]/.test(executable) || /^[A-Za-z]:/.test(executable);
+}
+
+function canAccessExecutable(path: string): boolean {
+  try {
+    if (process.platform === "win32") {
+      return existsSync(path);
+    }
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getPathExecutableCandidates(executable: string): string[] {
+  if (process.platform !== "win32" || /\.[A-Za-z0-9_-]+$/.test(executable)) {
+    return [executable];
+  }
+
+  const pathExt = process.env.PATHEXT?.split(";").filter(Boolean) ?? [".COM", ".EXE", ".BAT", ".CMD"];
+  return [executable, ...pathExt.map((ext) => `${executable}${ext.toLowerCase()}`)];
+}
+
+export async function commandExistsOnPath(executable: string): Promise<boolean> {
+  let candidate: string;
+  try {
+    candidate = normalizeExecutableValue(executable, {
+      label: "Provider launch command",
+      allowBareExecutable: true,
+    });
+  } catch {
+    return false;
+  }
+
+  const trimmed = candidate.trim();
+  if (executableLooksLikePath(trimmed)) {
+    return canAccessExecutable(trimmed);
+  }
+
+  const pathEntries = process.env.PATH?.split(delimiter).filter(Boolean) ?? [];
+  for (const dir of pathEntries) {
+    for (const name of getPathExecutableCandidates(trimmed)) {
+      if (canAccessExecutable(join(dir, name))) return true;
+    }
+  }
+  return false;
+}
+
+function formatSpawnError(provider: ProviderConfig, executable: string, error: NodeJS.ErrnoException): ProviderLaunchResult {
+  if (error.code === "ENOENT") {
+    return {
+      status: "missing-command",
+      message: `${provider.displayName} could not be launched because \`${executable}\` is not installed or not available on PATH.`,
+    };
+  }
+
+  if (error.code === "EACCES" || error.code === "EPERM") {
+    return {
+      status: "spawn-error",
+      errorCode: error.code,
+      message: `${provider.displayName} could not be launched because permission was denied for \`${executable}\`.`,
+    };
+  }
+
+  return {
+    status: "spawn-error",
+    errorCode: error.code,
+    message: `${provider.displayName} could not be launched. ${error.message}`,
+  };
+}
+
+export async function launchProviderCli(
+  provider: ProviderConfig,
+  options: LaunchProviderCliOptions,
+): Promise<ProviderLaunchResult> {
+  const spec = buildProviderLaunchSpec(provider, options.cwd);
+  if ("status" in spec) return spec;
+
+  const spawnImpl = options.spawnImpl ?? spawn;
+  const commandExists = options.commandExists ?? commandExistsOnPath;
+  const available = await commandExists(spec.executable);
+  if (!available) {
+    return {
+      status: "missing-command",
+      message: `${provider.displayName} could not be launched because \`${spec.executable}\` is not installed or not available on PATH.`,
+    };
+  }
+
+  const wasRaw = Boolean(options.stdin?.isRaw);
+  options.beforeLaunch?.();
+  setRawMode(options.stdin, false);
+
+  try {
+    return await new Promise<ProviderLaunchResult>((resolve) => {
+      let child: ChildProcess;
+      try {
+        const spawnSpec = buildSpawnSpec(spec.executable, spec.args);
+        if (!spawnSpec.executable) {
+          resolve({ status: "spawn-error", message: "Executable path is empty after resolution." });
+          return;
+        }
+        child = spawnImpl(spawnSpec.executable, spawnSpec.args, {
+          cwd: spec.cwd,
+          shell: false,
+          stdio: "inherit",
+        });
+      } catch (error) {
+        resolve(formatSpawnError(provider, spec.executable, error as NodeJS.ErrnoException));
+        return;
+      }
+
+      child.once("error", (error: NodeJS.ErrnoException) => {
+        resolve(formatSpawnError(provider, spec.executable, error));
+      });
+
+      child.once("close", (exitCode, signal) => {
+        resolve({
+          status: "completed",
+          exitCode,
+          signal,
+          message: `${provider.displayName} launch finished${exitCode === null ? "" : ` with exit code ${exitCode}`}.`,
+        });
+      });
+    });
+  } finally {
+    if (wasRaw) {
+      setRawMode(options.stdin, true);
+    }
+    options.afterLaunch?.();
+  }
+}
+
+export function describeProviderLaunch(provider: ProviderConfig): string {
+  if (!provider.enabled) {
+    return `${provider.displayName} is disabled.`;
+  }
+  return provider.launchCommand
+    ? `${provider.displayName}: ${formatCommand(provider.launchCommand)}`
+    : `${provider.displayName} has no launch command configured.`;
+}

package/src/core/providerLauncher/registry.ts

@@ -0,0 +1,354 @@
+import type {
+  ProviderConfig,
+  ProviderId,
+  ProviderBackendType,
+  ProviderLaunchCommand,
+  ProviderWorkspaceConfig,
+  ProviderWorkspaceOverride,
+} from "./types.js";
+import { DEFAULT_MODEL } from "../../config/settings.js";
+import { isLocalDevChannel } from "../version/channel.js";
+import {
+  getDefaultRouteModel,
+  getProviderRouteSetupMessage,
+  getProviderRuntime,
+  isProviderRoutableInUbume,
+  isProviderRouteConfigured,
+} from "../providerRuntime/registry.js";
+import { normalizeGeminiModelId } from "../providerRuntime/models.js";
+import { ANTIGRAVITY_DEFAULT_MODEL_ID } from "../providerRuntime/antigravity.js";
+import { discoverMistralVibeModels } from "../providerRuntime/mistralVibe.js";
+import { setLocalProviderConfig } from "../providerRuntime/local.js";
+import { CODEXA_NATIVE_MODEL_ID, discoverCodexaNativeModels } from "../providerRuntime/codexaNative.js";
+import { CODEXA_CUPY_MODEL_ID, discoverCodexaCupyModels } from "../providerRuntime/codexaCupy.js";
+import { formatContextLength, resolveModelContextLengthCached } from "../providerRuntime/contextMetadata.js";
+import { resolveModelCapabilityProfileCached } from "../providerRuntime/capabilityProfile.js";
+
+// Google/Gemini remains a recognized legacy config value so existing workspace
+// files can be migrated, but it is no longer a selectable Ubume provider.
+const ALL_PROVIDER_ORDER: readonly ProviderId[] = ["openai", "anthropic", "mistral", "codexa-native", "codexa-cupy", "local", "antigravity"];
+const KNOWN_PROVIDER_IDS: readonly ProviderId[] = ["openai", "anthropic", "google", "mistral", "local", "codexa-native", "codexa-cupy", "antigravity"];
+
+export function getProviderOrder(env: NodeJS.ProcessEnv = process.env): readonly ProviderId[] {
+  if (isLocalDevChannel(env)) {
+    return ALL_PROVIDER_ORDER;
+  }
+  return ALL_PROVIDER_ORDER.filter((id) => id !== "codexa-native" && id !== "codexa-cupy");
+}
+
+const DEFAULT_PROVIDER_ID: ProviderId = "openai";
+
+type ProviderDefault = Omit<ProviderConfig, "currentModel" | "enabled" | "statusLabel" | "launchCommand" | "isDefault"> & {
+  currentModel: (activeModel: string) => string;
+  enabled: boolean;
+  launchCommand: ProviderLaunchCommand | null;
+};
+
+const DEFAULT_PROVIDERS: Record<ProviderId, ProviderDefault> = {
+  openai: {
+    id: "openai",
+    displayName: "OpenAI",
+    currentModel: (activeModel) => activeModel,
+    backendType: "codex-cli-auth",
+    routeMode: "in-ubume",
+    enabled: true,
+    launchCommand: { executable: "codex", args: [] },
+    isActiveRoute: false,
+    routeUnavailableReason: null,
+  },
+  anthropic: {
+    id: "anthropic",
+    displayName: "Anthropic",
+    currentModel: () => "Claude Code default",
+    backendType: "claude-code-auth",
+    routeMode: "in-ubume",
+    enabled: true,
+    launchCommand: { executable: "claude", args: [] },
+    isActiveRoute: false,
+    routeUnavailableReason: null,
+  },
+  google: {
+    id: "google",
+    displayName: "Google",
+    currentModel: () => "gemini-3-flash-preview",
+    backendType: "gemini-cli-auth",
+    routeMode: "in-ubume",
+    enabled: true,
+    launchCommand: { executable: "gemini", args: [] },
+    isActiveRoute: false,
+    routeUnavailableReason: null,
+  },
+  local: {
+    id: "local",
+    displayName: "Local",
+    currentModel: () => "Local default",
+    backendType: "local-openai-compatible",
+    routeMode: "in-ubume",
+    enabled: false,
+    launchCommand: null,
+    isActiveRoute: false,
+    routeUnavailableReason: "Local provider unavailable. Start LM Studio, load a model, and enable the local server.",
+  },
+  "codexa-native": {
+    id: "codexa-native",
+    displayName: "ubume-PyTorch",
+    currentModel: () => CODEXA_NATIVE_MODEL_ID,
+    backendType: "codexa-native-pytorch",
+    routeMode: "in-ubume",
+    enabled: false,
+    launchCommand: null,
+    isActiveRoute: false,
+    routeUnavailableReason: "Codexa Native is only available on ubume-dev.",
+  },
+  "codexa-cupy": {
+    id: "codexa-cupy",
+    displayName: "CuPy",
+    currentModel: () => CODEXA_CUPY_MODEL_ID,
+    backendType: "codexa-cupy",
+    routeMode: "in-ubume",
+    enabled: false,
+    launchCommand: null,
+    isActiveRoute: false,
+    routeUnavailableReason: "CuPy is only available on ubume-dev.",
+  },
+  mistral: {
+    id: "mistral",
+    displayName: "Mistral Vibe CLI",
+    currentModel: () => "Vibe default",
+    backendType: "mistral-vibe-cli-auth",
+    routeMode: "in-ubume",
+    enabled: true,
+    launchCommand: { executable: "vibe", args: [] },
+    isActiveRoute: false,
+    routeUnavailableReason: null,
+  },
+  antigravity: {
+    id: "antigravity",
+    displayName: "Antigravity",
+    currentModel: () => ANTIGRAVITY_DEFAULT_MODEL_ID,
+    backendType: "antigravity-cli-auth",
+    routeMode: "in-ubume",
+    enabled: true,
+    launchCommand: { executable: "agy", args: [] },
+    isActiveRoute: false,
+    routeUnavailableReason: null,
+  },
+};
+
+function isProviderId(value: unknown): value is ProviderId {
+  return typeof value === "string" && KNOWN_PROVIDER_IDS.includes(value as ProviderId);
+}
+
+function normalizeLaunchCommand(value: ProviderWorkspaceOverride["command"] | undefined): ProviderLaunchCommand | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value === "string") {
+    const executable = value.trim();
+    return executable ? { executable, args: [] } : null;
+  }
+  if (typeof value.executable !== "string") return undefined;
+  const executable = value.executable.trim();
+  if (!executable) return null;
+  return {
+    executable,
+    args: Array.isArray(value.args)
+      ? value.args.filter((arg): arg is string => typeof arg === "string")
+      : [],
+  };
+}
+
+function applyOverride(
+  provider: ProviderConfig,
+  override: ProviderWorkspaceOverride | undefined,
+): ProviderConfig {
+  if (!override) return provider;
+
+  const launchCommand = normalizeLaunchCommand(override.command);
+  const hasConfiguredCommand = launchCommand !== undefined;
+  const nextCommand = hasConfiguredCommand ? launchCommand : provider.launchCommand;
+  const nextEnabled = typeof override.enabled === "boolean"
+    ? provider.id === "local" ? provider.enabled && override.enabled : override.enabled
+    : provider.enabled;
+
+  const overrideModel = typeof override.currentModel === "string" && override.currentModel.trim()
+    ? override.currentModel.trim()
+    : null;
+
+  return {
+    ...provider,
+    currentModel: overrideModel && provider.id !== "local"
+      ? provider.id === "google" ? normalizeGeminiModelId(overrideModel) : overrideModel
+      : provider.currentModel,
+    enabled: nextEnabled,
+    launchCommand: nextCommand,
+    statusLabel: !nextEnabled
+      ? "Disabled"
+      : provider.routeMode === "launch-only"
+        ? provider.statusLabel
+        : (provider.routeUnavailableReason ? "Needs config" : "Enabled"),
+  };
+}
+
+export function getDefaultProviderId(
+  config: ProviderWorkspaceConfig | null | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): ProviderId {
+  const providerId = config?.workspaceDefaultProviderId;
+  const isAvailable = isProviderId(providerId)
+    && providerId !== "google"
+    && (providerId !== "codexa-native" || isLocalDevChannel(env));
+  return isAvailable ? providerId : DEFAULT_PROVIDER_ID;
+}
+
+export function getActiveRouteProviderId(
+  config: ProviderWorkspaceConfig | null | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): ProviderId {
+  const providerId = config?.activeRoute?.providerId;
+  return isProviderId(providerId) && providerId !== "google" && isProviderRoutableInUbume(providerId, env)
+    ? providerId
+    : DEFAULT_PROVIDER_ID;
+}
+
+export function buildProviderRegistry(options: {
+  activeModel: string;
+  workspaceRoot?: string;
+  workspaceConfig?: ProviderWorkspaceConfig | null;
+  diagnostics?: Record<string, Record<string, string | number | boolean | null>>;
+  routeErrors?: Record<string, string>;
+  env?: NodeJS.ProcessEnv;
+}): ProviderConfig[] {
+  const env = options.env ?? process.env;
+  const defaultProviderId = getDefaultProviderId(options.workspaceConfig, env);
+  const activeRouteProviderId = getActiveRouteProviderId(options.workspaceConfig, env);
+  const providerOrder = getProviderOrder(env);
+
+  return providerOrder.map((id) => {
+    if (id === "local") {
+      setLocalProviderConfig(options.workspaceConfig?.providers?.local);
+    }
+    const defaults = DEFAULT_PROVIDERS[id];
+    const runtime = getProviderRuntime(id);
+    const discovery = id === "mistral"
+      ? discoverMistralVibeModels(options.workspaceRoot ?? process.cwd())
+      : id === "codexa-native"
+      ? discoverCodexaNativeModels(undefined, env)
+      : id === "codexa-cupy"
+      ? discoverCodexaCupyModels(undefined, env)
+      : runtime.discoverModels();
+
+    const activeRoute = options.workspaceConfig?.activeRoute;
+    const isThisActive = activeRoute?.providerId === id;
+
+    let currentModelLabel = isThisActive && activeRoute
+      ? activeRoute.modelId
+      : getDefaultRouteModel(id, id === "openai" ? DEFAULT_MODEL : defaults.currentModel(options.activeModel));
+
+    if (id === "google") {
+      const hasGoogleOverride = options.workspaceConfig?.providers?.google?.currentModel !== undefined;
+      const geminiRoute = isThisActive || !hasGoogleOverride ? activeRoute : null;
+      const selection = geminiRoute?.modelSelection;
+      if (selection) {
+        if (selection.kind === "auto") {
+          currentModelLabel = `Auto (${selection.family === "gemini-3" ? "Gemini 3" : "Gemini 2.5"})`;
+        } else {
+          currentModelLabel = normalizeGeminiModelId(selection.modelId);
+        }
+      } else {
+        currentModelLabel = normalizeGeminiModelId(currentModelLabel);
+      }
+    }
+
+    if (id === "local") {
+      const selectedModel = typeof discovery.diagnostics?.selectedModel === "string" && discovery.diagnostics.selectedModel.trim()
+        ? discovery.diagnostics.selectedModel.trim()
+        : discovery.models[0]?.modelId;
+      if (selectedModel) {
+        currentModelLabel = selectedModel;
+      }
+    }
+
+    if (id === "mistral") {
+      currentModelLabel = discovery.models[0]?.modelId ?? "Vibe default";
+    }
+
+    const rawMetadataForModel = discovery.models.find((model) => model.modelId === currentModelLabel)?.raw;
+    const contextMetadata = resolveModelContextLengthCached({
+      providerId: id,
+      modelId: currentModelLabel,
+      providerConfig: options.workspaceConfig?.providers?.[id],
+      rawMetadata: rawMetadataForModel,
+    });
+    const contextSource = contextMetadata.source === "known-registry" ? "registry" : contextMetadata.source;
+    const capabilityProfile = resolveModelCapabilityProfileCached({
+      providerId: id,
+      modelId: currentModelLabel,
+      providerConfig: options.workspaceConfig?.providers?.[id],
+      rawMetadata: rawMetadataForModel,
+    });
+
+    const routeUnavailableReason: string | null = runtime.routeAvailable
+      ? (isProviderRouteConfigured(id, env)
+          ? null
+          : (options.routeErrors?.[id]
+            ?? discovery.message
+            ?? getProviderRouteSetupMessage(id)))
+      : runtime.routeStatus;
+
+    const enabled = id === "codexa-native" || id === "codexa-cupy"
+      ? isLocalDevChannel(env)
+      : id === "local"
+      ? discovery.status === "ready"
+      : defaults.enabled;
+
+    const availabilityStatus = options.diagnostics?.[id]?.availabilityStatus;
+    const statusLabel = id === "mistral"
+      ? availabilityStatus === "checking"
+        ? "Checking"
+        : availabilityStatus === "unavailable"
+          ? "Missing"
+          : routeUnavailableReason
+            ? "Needs config"
+            : "Enabled"
+      : id === "local"
+      ? (discovery.status === "ready" ? "Enabled" : "Disabled")
+      : !enabled
+        ? "Disabled"
+        : routeUnavailableReason
+          ? "Needs config"
+          : "Enabled";
+
+    const provider: ProviderConfig = {
+      id,
+      displayName: defaults.displayName,
+      currentModel: currentModelLabel,
+      contextLengthLabel: formatContextLength(contextMetadata.contextLength),
+      contextLengthSource: contextSource,
+      capabilityProfile,
+      // Keep the provider's stable backend identity even when discovery reports
+      // missing local model files. Availability is represented separately by
+      // statusLabel and routeUnavailableReason.
+      backendType: id === "codexa-native" || id === "codexa-cupy"
+        ? defaults.backendType
+        : discovery.backendKind as ProviderBackendType,
+      routeMode: runtime.routeAvailable ? "in-ubume" : "launch-only",
+      enabled,
+      statusLabel,
+      launchCommand: defaults.launchCommand ? { ...defaults.launchCommand, args: [...defaults.launchCommand.args] } : null,
+      isDefault: id === defaultProviderId,
+      isActiveRoute: id === activeRouteProviderId,
+      routeUnavailableReason,
+      routeDiagnostics: options.diagnostics?.[id],
+    };
+
+    return applyOverride(provider, options.workspaceConfig?.providers?.[id]);
+  });
+}
+
+export function findProvider(providers: readonly ProviderConfig[], providerId: ProviderId): ProviderConfig | null {
+  return providers.find((provider) => provider.id === providerId) ?? null;
+}
+
+export function isKnownProviderId(value: string): value is ProviderId {
+  return isProviderId(value);
+}