@elizaos/agent 0.25.9 → 2.0.0-alpha.151

package/packages/shared/src/contracts/onboarding.js

@@ -0,0 +1,1020 @@
+/**
+ * Shared onboarding contracts.
+ */
+import { isTruthyEnvValue } from "../env-utils.impl.js";
+import { normalizeDeploymentTargetConfig, normalizeLinkedAccountsConfig, normalizeServiceRoutingConfig, } from "./service-routing.js";
+export const CHARACTER_LANGUAGES = [
+    "en",
+    "zh-CN",
+    "ko",
+    "es",
+    "pt",
+    "vi",
+    "tl",
+];
+export const SUBSCRIPTION_PROVIDER_SELECTIONS = [
+    {
+        id: "anthropic-subscription",
+        storedProvider: "anthropic-subscription",
+        family: "anthropic",
+        labelKey: "providerswitcher.claudeSubscription",
+    },
+    {
+        id: "openai-subscription",
+        storedProvider: "openai-codex",
+        family: "openai",
+        labelKey: "providerswitcher.chatgptSubscription",
+    },
+];
+// TODO: These hardcoded provider entries should eventually be populated by
+// plugins at runtime via a registry pattern. Each LLM plugin would call
+// registerProviderOption() during initialization to add itself to the catalog.
+// The hardcoded entries below serve as defaults until all plugins are migrated.
+export const ONBOARDING_PROVIDER_CATALOG = [
+    {
+        id: "elizacloud",
+        name: "Eliza Cloud",
+        envKey: null,
+        pluginName: "@elizaos/plugin-elizacloud",
+        keyPrefix: null,
+        description: "Managed hosting for Eliza agents and bundled infrastructure.",
+        family: "elizacloud",
+        authMode: "cloud",
+        group: "cloud",
+        order: 10,
+        recommended: true,
+    },
+    {
+        id: "anthropic-subscription",
+        name: "Claude Subscription",
+        envKey: null,
+        pluginName: "@elizaos/plugin-anthropic",
+        keyPrefix: null,
+        description: "Powers task agents via Claude Code CLI. For the main agent, use Eliza Cloud or a direct API key.",
+        family: "anthropic",
+        authMode: "subscription",
+        group: "subscription",
+        order: 20,
+        recommended: true,
+        labelKey: "providerswitcher.claudeSubscription",
+        storedProvider: "anthropic-subscription",
+    },
+    {
+        id: "openai-subscription",
+        name: "ChatGPT Subscription",
+        envKey: null,
+        pluginName: "@elizaos/plugin-openai",
+        keyPrefix: null,
+        description: "Use your ChatGPT Plus or Pro subscription via OAuth.",
+        family: "openai",
+        authMode: "subscription",
+        group: "subscription",
+        order: 30,
+        recommended: true,
+        labelKey: "providerswitcher.chatgptSubscription",
+        storedProvider: "openai-codex",
+    },
+    {
+        id: "anthropic",
+        name: "Anthropic",
+        envKey: "ANTHROPIC_API_KEY",
+        pluginName: "@elizaos/plugin-anthropic",
+        keyPrefix: "sk-ant-",
+        description: "Claude models via API key.",
+        family: "anthropic",
+        authMode: "api-key",
+        group: "local",
+        order: 50,
+    },
+    {
+        id: "openai",
+        name: "OpenAI",
+        envKey: "OPENAI_API_KEY",
+        pluginName: "@elizaos/plugin-openai",
+        keyPrefix: "sk-",
+        description: "GPT models via API key.",
+        family: "openai",
+        authMode: "api-key",
+        group: "local",
+        order: 60,
+    },
+    {
+        id: "openrouter",
+        name: "OpenRouter",
+        envKey: "OPENROUTER_API_KEY",
+        pluginName: "@elizaos/plugin-openrouter",
+        keyPrefix: "sk-or-",
+        description: "Access multiple models via one API key.",
+        family: "openrouter",
+        authMode: "api-key",
+        group: "local",
+        order: 70,
+        supportsPrimaryModelOverride: true,
+    },
+    {
+        id: "gemini",
+        name: "Gemini",
+        envKey: "GOOGLE_GENERATIVE_AI_API_KEY",
+        pluginName: "@elizaos/plugin-google-genai",
+        keyPrefix: null,
+        description: "Google's Gemini models.",
+        family: "gemini",
+        authMode: "api-key",
+        group: "local",
+        order: 80,
+    },
+    {
+        id: "grok",
+        name: "xAI (Grok)",
+        envKey: "XAI_API_KEY",
+        pluginName: "@elizaos/plugin-xai",
+        keyPrefix: "xai-",
+        description: "xAI's Grok models.",
+        family: "grok",
+        authMode: "api-key",
+        group: "local",
+        order: 90,
+    },
+    {
+        id: "groq",
+        name: "Groq",
+        envKey: "GROQ_API_KEY",
+        pluginName: "@elizaos/plugin-groq",
+        keyPrefix: "gsk_",
+        description: "Fast inference.",
+        family: "groq",
+        authMode: "api-key",
+        group: "local",
+        order: 100,
+    },
+    {
+        id: "deepseek",
+        name: "DeepSeek",
+        envKey: "DEEPSEEK_API_KEY",
+        pluginName: "@elizaos/plugin-deepseek",
+        keyPrefix: "sk-",
+        description: "DeepSeek models.",
+        family: "deepseek",
+        authMode: "api-key",
+        group: "local",
+        order: 110,
+    },
+    {
+        id: "mistral",
+        name: "Mistral",
+        envKey: "MISTRAL_API_KEY",
+        pluginName: "@elizaos/plugin-mistral",
+        keyPrefix: null,
+        description: "Mistral AI models.",
+        family: "mistral",
+        authMode: "api-key",
+        group: "local",
+        order: 120,
+    },
+    {
+        id: "together",
+        name: "Together AI",
+        envKey: "TOGETHER_API_KEY",
+        pluginName: "@elizaos/plugin-together",
+        keyPrefix: null,
+        description: "Open-source model hosting.",
+        family: "together",
+        authMode: "api-key",
+        group: "local",
+        order: 130,
+    },
+    {
+        id: "ollama",
+        name: "Ollama",
+        envKey: null,
+        pluginName: "@elizaos/plugin-ollama",
+        keyPrefix: null,
+        description: "Local models, no API key needed.",
+        family: "ollama",
+        authMode: "local",
+        group: "local",
+        order: 140,
+    },
+    {
+        id: "zai",
+        name: "z.ai",
+        envKey: "ZAI_API_KEY",
+        pluginName: "@homunculuslabs/plugin-zai",
+        keyPrefix: null,
+        description: "GLM models via z.ai Coding Plan.",
+        family: "zai",
+        authMode: "api-key",
+        group: "local",
+        order: 150,
+    },
+];
+export const ONBOARDING_CLOUD_PROVIDER_OPTIONS = [
+    {
+        id: "elizacloud",
+        name: "Eliza Cloud",
+        description: "Managed cloud infrastructure. Wallets, LLMs, and RPCs included.",
+    },
+];
+function pickOnboardingCloudModelPreferences(value) {
+    return {
+        ...(value.nanoModel ? { nanoModel: value.nanoModel } : {}),
+        ...(value.smallModel ? { smallModel: value.smallModel } : {}),
+        ...(value.mediumModel ? { mediumModel: value.mediumModel } : {}),
+        ...(value.largeModel ? { largeModel: value.largeModel } : {}),
+        ...(value.megaModel ? { megaModel: value.megaModel } : {}),
+        ...(value.responseHandlerModel
+            ? { responseHandlerModel: value.responseHandlerModel }
+            : {}),
+        ...(value.shouldRespondModel
+            ? { shouldRespondModel: value.shouldRespondModel }
+            : {}),
+        ...(value.actionPlannerModel
+            ? { actionPlannerModel: value.actionPlannerModel }
+            : {}),
+        ...(value.plannerModel ? { plannerModel: value.plannerModel } : {}),
+        ...(value.responseModel ? { responseModel: value.responseModel } : {}),
+        ...(value.mediaDescriptionModel
+            ? { mediaDescriptionModel: value.mediaDescriptionModel }
+            : {}),
+    };
+}
+function readOnboardingCloudModelPreferences(source) {
+    if (!source) {
+        return {};
+    }
+    return pickOnboardingCloudModelPreferences({
+        nanoModel: readConfigString(source, "nanoModel"),
+        smallModel: readConfigString(source, "smallModel"),
+        mediumModel: readConfigString(source, "mediumModel"),
+        largeModel: readConfigString(source, "largeModel"),
+        megaModel: readConfigString(source, "megaModel"),
+        responseHandlerModel: readConfigString(source, "responseHandlerModel"),
+        shouldRespondModel: readConfigString(source, "shouldRespondModel"),
+        actionPlannerModel: readConfigString(source, "actionPlannerModel"),
+        plannerModel: readConfigString(source, "plannerModel"),
+        responseModel: readConfigString(source, "responseModel"),
+        mediaDescriptionModel: readConfigString(source, "mediaDescriptionModel"),
+    });
+}
+const ONBOARDING_PROVIDER_ALIASES = {
+    "openai-codex": "openai-subscription",
+    "openai-subscription": "openai-subscription",
+    "anthropic-subscription": "anthropic-subscription",
+    google: "gemini",
+    "google-genai": "gemini",
+    gemini: "gemini",
+    xai: "grok",
+    grok: "grok",
+    "together-ai": "together",
+    together: "together",
+    "z.ai": "zai",
+    zai: "zai",
+};
+export function isSubscriptionProviderSelectionId(value) {
+    return SUBSCRIPTION_PROVIDER_SELECTIONS.some((provider) => provider.id === value);
+}
+export function normalizeSubscriptionProviderSelectionId(value) {
+    if (value === "anthropic-subscription")
+        return "anthropic-subscription";
+    if (value === "openai-subscription" || value === "openai-codex") {
+        return "openai-subscription";
+    }
+    return null;
+}
+export function getStoredSubscriptionProvider(selectionId) {
+    return selectionId === "anthropic-subscription"
+        ? "anthropic-subscription"
+        : "openai-codex";
+}
+export function getSubscriptionProviderFamily(selectionId) {
+    return selectionId === "anthropic-subscription" ? "anthropic" : "openai";
+}
+export function requiresAdditionalRuntimeProvider(providerId) {
+    return normalizeOnboardingProviderId(providerId) === "anthropic-subscription";
+}
+export function normalizeOnboardingProviderId(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const candidates = Array.from(new Set([
+        trimmed,
+        trimmed.replace(/^@[^/]+\//, ""),
+        trimmed.replace(/^@[^/]+\//, "").replace(/^plugin-/, ""),
+    ]));
+    for (const candidate of candidates) {
+        const directMatch = ONBOARDING_PROVIDER_CATALOG.find((provider) => provider.id === candidate);
+        if (directMatch) {
+            return directMatch.id;
+        }
+        const alias = ONBOARDING_PROVIDER_ALIASES[candidate];
+        if (alias) {
+            return alias;
+        }
+    }
+    for (const candidate of candidates) {
+        const pluginMatches = ONBOARDING_PROVIDER_CATALOG.filter((provider) => provider.pluginName.toLowerCase() === candidate);
+        if (pluginMatches.length === 0) {
+            continue;
+        }
+        // Some plugin packages back both subscription and API-key flows.
+        // Prefer the concrete API-key provider unless the caller explicitly
+        // passed a subscription id/alias above.
+        const preferredMatch = pluginMatches.find((provider) => provider.authMode === "api-key") ??
+            pluginMatches[0];
+        return preferredMatch.id;
+    }
+    return null;
+}
+export function getOnboardingProviderOption(providerId) {
+    const normalized = normalizeOnboardingProviderId(providerId);
+    if (!normalized)
+        return null;
+    return (ONBOARDING_PROVIDER_CATALOG.find((provider) => provider.id === normalized) ?? null);
+}
+export function getOnboardingProviderFamily(providerId) {
+    return getOnboardingProviderOption(providerId)?.family ?? null;
+}
+export function getStoredOnboardingProviderId(providerId) {
+    const provider = getOnboardingProviderOption(providerId);
+    if (!provider)
+        return null;
+    return provider.storedProvider ?? provider.id;
+}
+export function sortOnboardingProviders(providers) {
+    return [...providers].sort((left, right) => {
+        const recommendedDelta = Number(Boolean(right.recommended)) - Number(Boolean(left.recommended));
+        if (recommendedDelta !== 0) {
+            return recommendedDelta;
+        }
+        return left.order - right.order;
+    });
+}
+export function isCloudManagedConnection(connection) {
+    return connection?.kind === "cloud-managed";
+}
+export function isRemoteProviderConnection(connection) {
+    return connection?.kind === "remote-provider";
+}
+export function isLocalProviderConnection(connection) {
+    return connection?.kind === "local-provider";
+}
+export function isOnboardingConnectionComplete(connection) {
+    if (isLocalProviderConnection(connection)) {
+        return true;
+    }
+    if (isRemoteProviderConnection(connection)) {
+        return Boolean(connection.remoteApiBase.trim());
+    }
+    if (isCloudManagedConnection(connection)) {
+        // Cloud OAuth sessions have no apiKey — inference access is provided by
+        // the cloud session token. The connection is complete when models are
+        // selected, regardless of whether an explicit API key is present.
+        return Boolean(connection.smallModel?.trim() && connection.largeModel?.trim());
+    }
+    return false;
+}
+const REDACTED_SECRET = "[REDACTED]";
+function asConfigRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function readConfigString(source, key) {
+    const value = source?.[key];
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function normalizeSecretString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.toUpperCase() === REDACTED_SECRET) {
+        return undefined;
+    }
+    return trimmed;
+}
+function readOnboardingEnvContainer(config) {
+    const env = asConfigRecord(config?.env);
+    return {
+        env,
+        vars: asConfigRecord(env?.vars),
+    };
+}
+export function readOnboardingEnvString(config, key) {
+    const { env, vars } = readOnboardingEnvContainer(config);
+    return readConfigString(vars, key) ?? readConfigString(env, key);
+}
+export function readOnboardingEnvSecret(config, key) {
+    return normalizeSecretString(readOnboardingEnvString(config, key));
+}
+/** Alias to keep call-sites unchanged. */
+const _isTruthyEnvFlag = isTruthyEnvValue;
+export function getOnboardingProviderSignalEnvKeys(providerId) {
+    if (providerId === "ollama") {
+        return ["OLLAMA_BASE_URL"];
+    }
+    const provider = getOnboardingProviderOption(providerId);
+    return provider?.envKey ? [provider.envKey] : [];
+}
+function readPrimaryModelFromConfig(config) {
+    const agents = asConfigRecord(config?.agents);
+    const defaults = asConfigRecord(agents?.defaults);
+    const model = asConfigRecord(defaults?.model);
+    return readConfigString(model, "primary");
+}
+export function hasExplicitCanonicalRuntimeConfig(config) {
+    const root = asConfigRecord(config);
+    return Boolean(root &&
+        (Object.hasOwn(root, "deploymentTarget") ||
+            Object.hasOwn(root, "linkedAccounts") ||
+            Object.hasOwn(root, "serviceRouting")));
+}
+function buildElizaCloudTextRoute(args) {
+    return {
+        backend: "elizacloud",
+        transport: "cloud-proxy",
+        accountId: "elizacloud",
+        ...pickOnboardingCloudModelPreferences(args),
+    };
+}
+const LEGACY_CLOUD_ROUTING_KEYS = [
+    "enabled",
+    "provider",
+    "remoteApiBase",
+    "remoteAccessToken",
+    "inferenceMode",
+    "runtime",
+];
+const LEGACY_CLOUD_SERVICE_KEYS = [
+    "inference",
+    "tts",
+    "media",
+    "embeddings",
+    "rpc",
+];
+function resolveLegacyDeploymentTargetInConfig(config) {
+    const cloud = asConfigRecord(config?.cloud);
+    const remoteApiBase = readConfigString(cloud, "remoteApiBase");
+    if (remoteApiBase) {
+        return {
+            runtime: "remote",
+            provider: "remote",
+            remoteApiBase,
+            ...(normalizeSecretString(cloud?.remoteAccessToken)
+                ? {
+                    remoteAccessToken: normalizeSecretString(cloud?.remoteAccessToken),
+                }
+                : {}),
+        };
+    }
+    const cloudProvider = normalizeOnboardingProviderId(readConfigString(cloud, "provider"));
+    const cloudRuntime = readConfigString(cloud, "runtime");
+    const cloudAgentId = readConfigString(cloud, "agentId");
+    if (cloudRuntime === "cloud" &&
+        cloudProvider === "elizacloud" &&
+        cloudAgentId) {
+        return { runtime: "cloud", provider: "elizacloud" };
+    }
+    return { runtime: "local" };
+}
+function resolveLegacyServiceRoutingInConfig(config) {
+    const root = asConfigRecord(config);
+    const explicit = normalizeServiceRoutingConfig(root?.serviceRouting) ?? {};
+    const next = { ...explicit };
+    const deploymentTarget = normalizeDeploymentTargetConfig(root?.deploymentTarget) ??
+        resolveLegacyDeploymentTargetInConfig(config);
+    const cloud = asConfigRecord(config?.cloud);
+    const cloudServices = asConfigRecord(cloud?.services);
+    const models = asConfigRecord(config?.models);
+    if (!next.llmText) {
+        if (deploymentTarget.runtime === "remote" && deploymentTarget.remoteApiBase) {
+            const remotePrimaryModel = readPrimaryModelFromConfig(config);
+            next.llmText = {
+                backend: "remote",
+                transport: "remote",
+                remoteApiBase: deploymentTarget.remoteApiBase,
+                ...(remotePrimaryModel ? { primaryModel: remotePrimaryModel } : {}),
+            };
+        }
+        else if (inferLegacyCloudInferenceSelection(config)) {
+            next.llmText = buildElizaCloudTextRoute({
+                smallModel: readConfigString(models, "small"),
+                largeModel: readConfigString(models, "large"),
+            });
+        }
+        else {
+            const localProvider = resolveConfiguredLocalProviderFromSignals(config);
+            const primaryModel = readPrimaryModelFromConfig(config);
+            if (localProvider) {
+                next.llmText = {
+                    backend: localProvider,
+                    transport: "direct",
+                    ...(primaryModel ? { primaryModel } : {}),
+                };
+            }
+        }
+    }
+    const legacyCloudServices = [
+        [
+            "tts",
+            typeof cloudServices?.tts === "boolean" ? cloudServices.tts : undefined,
+        ],
+        [
+            "media",
+            typeof cloudServices?.media === "boolean"
+                ? cloudServices.media
+                : undefined,
+        ],
+        [
+            "embeddings",
+            typeof cloudServices?.embeddings === "boolean"
+                ? cloudServices.embeddings
+                : undefined,
+        ],
+        [
+            "rpc",
+            typeof cloudServices?.rpc === "boolean" ? cloudServices.rpc : undefined,
+        ],
+    ];
+    for (const [capability, legacyValue] of legacyCloudServices) {
+        if (next[capability]) {
+            continue;
+        }
+        if (legacyValue !== true) {
+            continue;
+        }
+        next[capability] = {
+            backend: "elizacloud",
+            transport: "cloud-proxy",
+            accountId: "elizacloud",
+        };
+    }
+    return Object.keys(next).length > 0 ? next : null;
+}
+function pruneLegacyCloudRoutingFields(config) {
+    const root = asConfigRecord(config);
+    const cloud = asConfigRecord(root?.cloud);
+    if (!root || !cloud) {
+        return;
+    }
+    for (const key of LEGACY_CLOUD_ROUTING_KEYS) {
+        delete cloud[key];
+    }
+    const services = asConfigRecord(cloud.services);
+    if (services) {
+        for (const key of LEGACY_CLOUD_SERVICE_KEYS) {
+            delete services[key];
+        }
+        if (Object.keys(services).length === 0) {
+            delete cloud.services;
+        }
+        else {
+            cloud.services = services;
+        }
+    }
+    if (Object.keys(cloud).length === 0) {
+        delete root.cloud;
+    }
+    else {
+        root.cloud = cloud;
+    }
+}
+export function migrateLegacyRuntimeConfig(config) {
+    const root = asConfigRecord(config);
+    if (!root) {
+        return config;
+    }
+    const deploymentTarget = normalizeDeploymentTargetConfig(root.deploymentTarget) ??
+        resolveLegacyDeploymentTargetInConfig(root);
+    if (deploymentTarget.runtime === "local" &&
+        !Object.hasOwn(root, "deploymentTarget")) {
+        // Keep local default implicit to avoid churn in brand-new configs.
+    }
+    else {
+        root.deploymentTarget = deploymentTarget;
+    }
+    const linkedAccounts = resolveLinkedAccountsInConfig(root);
+    if (linkedAccounts) {
+        root.linkedAccounts = linkedAccounts;
+    }
+    else {
+        delete root.linkedAccounts;
+    }
+    const serviceRouting = normalizeServiceRoutingConfig(root.serviceRouting) ??
+        resolveLegacyServiceRoutingInConfig(root);
+    if (serviceRouting) {
+        root.serviceRouting = serviceRouting;
+    }
+    else {
+        delete root.serviceRouting;
+    }
+    if (Object.hasOwn(root, "connection")) {
+        delete root.connection;
+    }
+    pruneLegacyCloudRoutingFields(root);
+    return config;
+}
+export function resolveLinkedAccountsInConfig(config) {
+    const root = asConfigRecord(config);
+    const explicit = normalizeLinkedAccountsConfig(root?.linkedAccounts) ?? {};
+    const next = { ...explicit };
+    const cloud = asConfigRecord(config?.cloud);
+    const hasCloudKey = Boolean(normalizeSecretString(cloud?.apiKey));
+    const existingCloudAccount = next.elizacloud;
+    if (hasCloudKey && (!existingCloudAccount || !existingCloudAccount.status)) {
+        next.elizacloud = {
+            ...existingCloudAccount,
+            status: "linked",
+            source: existingCloudAccount?.source ?? "api-key",
+        };
+    }
+    return Object.keys(next).length > 0 ? next : null;
+}
+export function resolveDeploymentTargetInConfig(config) {
+    const root = asConfigRecord(config);
+    const explicit = normalizeDeploymentTargetConfig(root?.deploymentTarget);
+    if (explicit) {
+        return explicit;
+    }
+    return { runtime: "local" };
+}
+export function resolveServiceRoutingInConfig(config) {
+    const root = asConfigRecord(config);
+    const explicit = normalizeServiceRoutingConfig(root?.serviceRouting) ?? {};
+    const next = { ...explicit };
+    const deploymentTarget = resolveDeploymentTargetInConfig(config);
+    if (!next.llmText) {
+        if (deploymentTarget.runtime === "remote" && deploymentTarget.remoteApiBase) {
+            const remotePrimaryModel = readPrimaryModelFromConfig(config);
+            next.llmText = {
+                backend: "remote",
+                transport: "remote",
+                remoteApiBase: deploymentTarget.remoteApiBase,
+                ...(remotePrimaryModel ? { primaryModel: remotePrimaryModel } : {}),
+            };
+        }
+        else {
+            const localProvider = resolveConfiguredLocalProviderFromSignals(config);
+            const primaryModel = readPrimaryModelFromConfig(config);
+            if (localProvider) {
+                next.llmText = {
+                    backend: localProvider,
+                    transport: "direct",
+                    ...(primaryModel ? { primaryModel } : {}),
+                };
+            }
+        }
+    }
+    return Object.keys(next).length > 0 ? next : null;
+}
+function deriveOnboardingConnectionFromRuntimeConfig(config) {
+    const routing = resolveServiceRoutingInConfig(config);
+    const deploymentTarget = resolveDeploymentTargetInConfig(config);
+    const llmText = routing?.llmText;
+    const backend = normalizeOnboardingProviderId(llmText?.backend);
+    const localProviderOption = backend
+        ? getOnboardingProviderOption(backend)
+        : null;
+    const routeApiKey = localProviderOption?.envKey != null
+        ? readOnboardingEnvSecret(config, localProviderOption.envKey)
+        : undefined;
+    if (llmText?.transport === "cloud-proxy" && backend === "elizacloud") {
+        return {
+            kind: "cloud-managed",
+            cloudProvider: "elizacloud",
+            ...pickOnboardingCloudModelPreferences(llmText),
+        };
+    }
+    if (llmText?.transport === "remote") {
+        const remoteApiBase = llmText.remoteApiBase ?? deploymentTarget.remoteApiBase;
+        if (!remoteApiBase) {
+            return null;
+        }
+        return {
+            kind: "remote-provider",
+            remoteApiBase,
+            ...(deploymentTarget.remoteAccessToken
+                ? { remoteAccessToken: deploymentTarget.remoteAccessToken }
+                : {}),
+            ...(backend && backend !== "elizacloud" ? { provider: backend } : {}),
+            ...(routeApiKey ? { apiKey: routeApiKey } : {}),
+            ...(llmText.primaryModel ? { primaryModel: llmText.primaryModel } : {}),
+        };
+    }
+    if (backend && backend !== "elizacloud") {
+        return {
+            kind: "local-provider",
+            provider: backend,
+            ...(routeApiKey ? { apiKey: routeApiKey } : {}),
+            ...(llmText?.primaryModel ? { primaryModel: llmText.primaryModel } : {}),
+        };
+    }
+    if (deploymentTarget.runtime === "remote" &&
+        deploymentTarget.remoteApiBase?.trim()) {
+        return {
+            kind: "remote-provider",
+            remoteApiBase: deploymentTarget.remoteApiBase,
+            ...(deploymentTarget.remoteAccessToken
+                ? { remoteAccessToken: deploymentTarget.remoteAccessToken }
+                : {}),
+        };
+    }
+    return null;
+}
+function resolveConfiguredLocalProviderFromSignals(config) {
+    const agents = asConfigRecord(config?.agents);
+    const defaults = asConfigRecord(agents?.defaults);
+    const storedSubscriptionProvider = normalizeOnboardingProviderId(readConfigString(defaults, "subscriptionProvider"));
+    if (storedSubscriptionProvider &&
+        storedSubscriptionProvider !== "elizacloud" &&
+        !requiresAdditionalRuntimeProvider(storedSubscriptionProvider)) {
+        return storedSubscriptionProvider;
+    }
+    for (const provider of ONBOARDING_PROVIDER_CATALOG) {
+        if (provider.id === "elizacloud") {
+            continue;
+        }
+        const providerId = provider.id;
+        const detected = getOnboardingProviderSignalEnvKeys(providerId).some((key) => Boolean(readOnboardingEnvString(config, key)));
+        if (detected) {
+            return providerId;
+        }
+    }
+    return null;
+}
+export function normalizePersistedOnboardingConnection(value) {
+    const connection = asConfigRecord(value);
+    if (!connection) {
+        return null;
+    }
+    if (connection.kind === "cloud-managed") {
+        return {
+            kind: "cloud-managed",
+            cloudProvider: "elizacloud",
+            apiKey: normalizeSecretString(connection.apiKey),
+            ...readOnboardingCloudModelPreferences(connection),
+        };
+    }
+    if (connection.kind === "local-provider") {
+        const provider = normalizeOnboardingProviderId(connection.provider);
+        if (!provider || provider === "elizacloud") {
+            return null;
+        }
+        return {
+            kind: "local-provider",
+            provider,
+            apiKey: normalizeSecretString(connection.apiKey),
+            primaryModel: readConfigString(connection, "primaryModel"),
+        };
+    }
+    if (connection.kind === "remote-provider") {
+        const remoteApiBase = readConfigString(connection, "remoteApiBase");
+        const provider = normalizeOnboardingProviderId(connection.provider);
+        if (!remoteApiBase) {
+            return null;
+        }
+        return {
+            kind: "remote-provider",
+            remoteApiBase,
+            remoteAccessToken: normalizeSecretString(connection.remoteAccessToken),
+            provider: provider && provider !== "elizacloud" ? provider : undefined,
+            apiKey: normalizeSecretString(connection.apiKey),
+            primaryModel: readConfigString(connection, "primaryModel"),
+        };
+    }
+    return null;
+}
+export function normalizeOnboardingCredentialInputs(value) {
+    const inputs = asConfigRecord(value);
+    if (!inputs) {
+        return null;
+    }
+    const llmApiKey = normalizeSecretString(inputs.llmApiKey);
+    const cloudApiKey = normalizeSecretString(inputs.cloudApiKey);
+    if (!llmApiKey && !cloudApiKey) {
+        return null;
+    }
+    return {
+        ...(llmApiKey ? { llmApiKey } : {}),
+        ...(cloudApiKey ? { cloudApiKey } : {}),
+    };
+}
+export function deriveOnboardingCredentialPersistencePlan(args) {
+    const credentialInputs = normalizeOnboardingCredentialInputs(args.credentialInputs);
+    const deploymentTarget = normalizeDeploymentTargetConfig(args.deploymentTarget);
+    const serviceRouting = normalizeServiceRoutingConfig(args.serviceRouting);
+    const llmRoute = serviceRouting?.llmText;
+    const cloudApiKey = credentialInputs?.cloudApiKey;
+    const llmApiKey = credentialInputs?.llmApiKey;
+    if (llmRoute?.transport === "cloud-proxy" &&
+        normalizeOnboardingProviderId(llmRoute.backend) === "elizacloud" &&
+        cloudApiKey) {
+        return {
+            llmSelection: {
+                backend: "elizacloud",
+                transport: "cloud-proxy",
+                apiKey: cloudApiKey,
+                ...pickOnboardingCloudModelPreferences(llmRoute),
+            },
+            cloudApiKey,
+        };
+    }
+    if (llmRoute?.transport === "direct" && llmApiKey) {
+        const provider = normalizeOnboardingProviderId(llmRoute.backend);
+        if (provider && provider !== "elizacloud") {
+            return {
+                llmSelection: {
+                    backend: provider,
+                    transport: "direct",
+                    apiKey: llmApiKey,
+                    ...(llmRoute.primaryModel
+                        ? { primaryModel: llmRoute.primaryModel }
+                        : {}),
+                },
+                ...(cloudApiKey ? { cloudApiKey } : {}),
+            };
+        }
+    }
+    if (llmRoute?.transport === "remote" && llmApiKey) {
+        const provider = normalizeOnboardingProviderId(llmRoute.backend);
+        const remoteApiBase = llmRoute.remoteApiBase ?? deploymentTarget?.remoteApiBase;
+        if (provider && provider !== "elizacloud" && remoteApiBase) {
+            return {
+                llmSelection: {
+                    backend: provider,
+                    transport: "remote",
+                    remoteApiBase,
+                    ...(deploymentTarget?.remoteAccessToken
+                        ? { remoteAccessToken: deploymentTarget.remoteAccessToken }
+                        : {}),
+                    apiKey: llmApiKey,
+                    ...(llmRoute.primaryModel
+                        ? { primaryModel: llmRoute.primaryModel }
+                        : {}),
+                },
+                ...(cloudApiKey ? { cloudApiKey } : {}),
+            };
+        }
+    }
+    return {
+        llmSelection: null,
+        ...(cloudApiKey ? { cloudApiKey } : {}),
+    };
+}
+export function stripOnboardingConnectionSecrets(connection) {
+    if (connection.kind === "cloud-managed") {
+        return {
+            kind: "cloud-managed",
+            cloudProvider: "elizacloud",
+            ...pickOnboardingCloudModelPreferences(connection),
+        };
+    }
+    if (connection.kind === "local-provider") {
+        return {
+            kind: "local-provider",
+            provider: connection.provider,
+            primaryModel: connection.primaryModel,
+        };
+    }
+    return {
+        kind: "remote-provider",
+        remoteApiBase: connection.remoteApiBase,
+        provider: connection.provider,
+        primaryModel: connection.primaryModel,
+    };
+}
+export function inferCompatibilityOnboardingConnection(config) {
+    const cloud = asConfigRecord(config?.cloud);
+    const models = asConfigRecord(config?.models);
+    const remoteApiBase = readConfigString(cloud, "remoteApiBase");
+    const remoteAccessToken = normalizeSecretString(cloud?.remoteAccessToken);
+    const localProvider = resolveConfiguredLocalProviderFromSignals(config);
+    const primaryModel = readPrimaryModelFromConfig(config);
+    const localProviderOption = getOnboardingProviderOption(localProvider);
+    const localApiKey = localProviderOption?.envKey != null
+        ? readOnboardingEnvSecret(config, localProviderOption.envKey)
+        : undefined;
+    if (remoteApiBase) {
+        return {
+            kind: "remote-provider",
+            remoteApiBase,
+            remoteAccessToken,
+            provider: localProvider ?? undefined,
+            apiKey: localApiKey,
+            primaryModel,
+        };
+    }
+    const cloudProvider = normalizeOnboardingProviderId(readConfigString(cloud, "provider"));
+    const cloudApiKey = normalizeSecretString(cloud?.apiKey);
+    const nanoModel = readConfigString(models, "nano");
+    const smallModel = readConfigString(models, "small");
+    const mediumModel = readConfigString(models, "medium");
+    const largeModel = readConfigString(models, "large");
+    const megaModel = readConfigString(models, "mega");
+    const cloudExplicitlyDisabled = cloud?.enabled === false;
+    if (!cloudExplicitlyDisabled &&
+        (cloud?.enabled === true ||
+            cloudProvider === "elizacloud" ||
+            readConfigString(cloud, "inferenceMode") === "cloud" ||
+            nanoModel ||
+            smallModel ||
+            mediumModel ||
+            largeModel ||
+            megaModel)) {
+        return {
+            kind: "cloud-managed",
+            cloudProvider: "elizacloud",
+            apiKey: cloudApiKey,
+            nanoModel,
+            smallModel,
+            mediumModel,
+            largeModel,
+            megaModel,
+        };
+    }
+    if (!localProvider) {
+        return null;
+    }
+    return {
+        kind: "local-provider",
+        provider: localProvider,
+        apiKey: localApiKey,
+        primaryModel,
+    };
+}
+export function inferOnboardingConnectionFromConfig(config) {
+    return deriveOnboardingConnectionFromRuntimeConfig(config);
+}
+function inferLegacyCloudInferenceSelection(config) {
+    const cloud = asConfigRecord(config?.cloud);
+    if (cloud?.enabled === false) {
+        return false;
+    }
+    const services = asConfigRecord(cloud?.services);
+    const inferenceMode = readConfigString(cloud, "inferenceMode");
+    if (inferenceMode === "byok" ||
+        inferenceMode === "local" ||
+        services?.inference === false) {
+        return false;
+    }
+    const cloudProvider = normalizeOnboardingProviderId(readConfigString(cloud, "provider"));
+    const models = asConfigRecord(config?.models);
+    const nanoModel = readConfigString(models, "nano");
+    const smallModel = readConfigString(models, "small");
+    const mediumModel = readConfigString(models, "medium");
+    const largeModel = readConfigString(models, "large");
+    const megaModel = readConfigString(models, "mega");
+    return Boolean(cloud?.enabled === true ||
+        cloudProvider === "elizacloud" ||
+        inferenceMode === "cloud" ||
+        nanoModel ||
+        smallModel ||
+        mediumModel ||
+        largeModel ||
+        megaModel);
+}
+export function isCloudInferenceSelectedInConfig(config) {
+    const routing = resolveServiceRoutingInConfig(config);
+    const llmText = routing?.llmText;
+    return Boolean(llmText?.transport === "cloud-proxy" &&
+        normalizeOnboardingProviderId(llmText.backend) === "elizacloud");
+}
+// ---------------------------------------------------------------------------
+// Provider option registry — allows plugins to register additional providers
+// at runtime without modifying the hardcoded ONBOARDING_PROVIDER_CATALOG.
+// ---------------------------------------------------------------------------
+const _registeredProviderOptions = [];
+/**
+ * Register an additional provider option at runtime.
+ * Plugins should call this during initialization to add themselves to the
+ * onboarding provider catalog.
+ */
+export function registerProviderOption(option) {
+    const existing = _registeredProviderOptions.findIndex((o) => o.id === option.id);
+    if (existing >= 0) {
+        _registeredProviderOptions[existing] = option;
+    }
+    else {
+        _registeredProviderOptions.push(option);
+    }
+}
+/**
+ * Get all provider options: hardcoded catalog merged with runtime-registered
+ * providers. Runtime registrations override hardcoded entries with the same id.
+ */
+export function getProviderOptions() {
+    const merged = new Map();
+    for (const option of ONBOARDING_PROVIDER_CATALOG) {
+        merged.set(option.id, option);
+    }
+    for (const option of _registeredProviderOptions) {
+        merged.set(option.id, option);
+    }
+    return Array.from(merged.values());
+}