@elizaos/shared 2.0.0-beta.1 → 2.0.3-beta.3

package/contracts/first-run-options.js

@@ -0,0 +1,1186 @@
+/**
+ * Shared first-run provider setup contracts.
+ */
+import { isTruthyEnvValue } from "../env-utils.js";
+import { normalizeDeploymentTargetConfig, normalizeLinkedAccountFlagsConfig, 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",
+    },
+    {
+        id: "gemini-subscription",
+        storedProvider: "gemini-cli",
+        family: "gemini",
+        labelKey: "providerswitcher.geminiSubscription",
+    },
+    {
+        id: "zai-coding-subscription",
+        storedProvider: "zai-coding",
+        family: "zai",
+        labelKey: "providerswitcher.zaiCodingPlan",
+    },
+    {
+        id: "kimi-coding-subscription",
+        storedProvider: "kimi-coding",
+        family: "moonshot",
+        labelKey: "providerswitcher.kimiCodingPlan",
+    },
+    {
+        id: "deepseek-coding-subscription",
+        storedProvider: "deepseek-coding",
+        family: "deepseek",
+        labelKey: "providerswitcher.deepseekCodingPlan",
+    },
+];
+export const FIRST_RUN_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: "Powers Codex-backed coding agents through the official Codex surface.",
+        family: "openai",
+        authMode: "subscription",
+        group: "subscription",
+        order: 30,
+        recommended: true,
+        labelKey: "providerswitcher.chatgptSubscription",
+        storedProvider: "openai-codex",
+    },
+    {
+        id: "gemini-subscription",
+        name: "Gemini CLI Subscription",
+        envKey: null,
+        pluginName: "@elizaos/plugin-google-genai",
+        keyPrefix: null,
+        description: "Powers task agents through the authenticated Gemini CLI. No Gemini subscription token is imported into API env vars.",
+        family: "gemini",
+        authMode: "subscription",
+        group: "subscription",
+        order: 35,
+        labelKey: "providerswitcher.geminiSubscription",
+        storedProvider: "gemini-cli",
+    },
+    {
+        id: "zai-coding-subscription",
+        name: "z.ai Coding Plan",
+        envKey: null,
+        pluginName: "@elizaos/plugin-zai",
+        keyPrefix: null,
+        description: "Stores z.ai Coding Plan credentials for the dedicated coding endpoint only, not the general z.ai API key path.",
+        family: "zai",
+        authMode: "subscription",
+        group: "subscription",
+        order: 36,
+        labelKey: "providerswitcher.zaiCodingPlan",
+        storedProvider: "zai-coding",
+    },
+    {
+        id: "kimi-coding-subscription",
+        name: "Kimi Code",
+        envKey: null,
+        pluginName: "@elizaos/plugin-openai",
+        keyPrefix: null,
+        description: "Stores Kimi Code credentials for Kimi's coding endpoint only, not the Moonshot general API key path.",
+        family: "moonshot",
+        authMode: "subscription",
+        group: "subscription",
+        order: 37,
+        labelKey: "providerswitcher.kimiCodingPlan",
+        storedProvider: "kimi-coding",
+    },
+    {
+        id: "deepseek-coding-subscription",
+        name: "DeepSeek Coding Plan",
+        envKey: null,
+        pluginName: "@elizaos/plugin-deepseek",
+        keyPrefix: null,
+        description: "Unavailable until DeepSeek exposes a first-party coding subscription surface that can be integrated without API-key substitution.",
+        family: "deepseek",
+        authMode: "subscription",
+        group: "subscription",
+        order: 38,
+        labelKey: "providerswitcher.deepseekCodingPlan",
+        storedProvider: "deepseek-coding",
+    },
+    {
+        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: "cerebras",
+        name: "Cerebras",
+        envKey: "CEREBRAS_API_KEY",
+        // Cerebras serves an OpenAI-compatible API, so it runs through the
+        // OpenAI plugin's Cerebras mode (CEREBRAS_API_KEY → api.cerebras.ai).
+        pluginName: "@elizaos/plugin-openai",
+        keyPrefix: "csk-",
+        description: "Fast inference for open models via Cerebras.",
+        family: "cerebras",
+        authMode: "api-key",
+        group: "local",
+        order: 105,
+    },
+    {
+        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: "@elizaos/plugin-zai",
+        keyPrefix: null,
+        description: "GLM models via z.ai direct API billing.",
+        family: "zai",
+        authMode: "api-key",
+        group: "local",
+        order: 150,
+    },
+    {
+        id: "nearai",
+        name: "NEAR AI",
+        envKey: "NEARAI_API_KEY",
+        pluginName: "@elizaos/plugin-nearai",
+        keyPrefix: null,
+        description: "TEE-backed private inference via NEAR AI Cloud.",
+        family: "nearai",
+        authMode: "api-key",
+        group: "local",
+        order: 155,
+        supportsPrimaryModelOverride: true,
+    },
+    {
+        id: "moonshot",
+        name: "Kimi / Moonshot",
+        envKey: "MOONSHOT_API_KEY",
+        pluginName: "@elizaos/plugin-openai",
+        keyPrefix: "sk-",
+        description: "Kimi models via Moonshot's OpenAI-compatible API.",
+        family: "moonshot",
+        authMode: "api-key",
+        group: "local",
+        order: 160,
+        supportsPrimaryModelOverride: true,
+    },
+];
+export const DIRECT_ACCOUNT_PROVIDER_BY_FIRST_RUN_PROVIDER = {
+    anthropic: "anthropic-api",
+    openai: "openai-api",
+    deepseek: "deepseek-api",
+    zai: "zai-api",
+    moonshot: "moonshot-api",
+    cerebras: "cerebras-api",
+};
+export const FIRST_RUN_CLOUD_PROVIDER_OPTIONS = [
+    {
+        id: "elizacloud",
+        name: "Eliza Cloud",
+        description: "Managed cloud infrastructure. Wallets, LLMs, and RPCs included.",
+    },
+];
+function pickFirstRunCloudModelPreferences(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 readFirstRunCloudModelPreferences(source) {
+    if (!source) {
+        return {};
+    }
+    return pickFirstRunCloudModelPreferences({
+        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 FIRST_RUN_PROVIDER_ALIASES = {
+    "openai-codex": "openai-subscription",
+    "openai-subscription": "openai-subscription",
+    "anthropic-subscription": "anthropic-subscription",
+    "gemini-cli": "gemini-subscription",
+    "gemini-subscription": "gemini-subscription",
+    "google-subscription": "gemini-subscription",
+    "zai-coding": "zai-coding-subscription",
+    "z.ai-coding": "zai-coding-subscription",
+    "zai-coding-subscription": "zai-coding-subscription",
+    "kimi-coding": "kimi-coding-subscription",
+    "kimi-code": "kimi-coding-subscription",
+    "kimi-coding-subscription": "kimi-coding-subscription",
+    "deepseek-coding": "deepseek-coding-subscription",
+    "deepseek-coding-subscription": "deepseek-coding-subscription",
+    google: "gemini",
+    "google-genai": "gemini",
+    gemini: "gemini",
+    xai: "grok",
+    grok: "grok",
+    "together-ai": "together",
+    together: "together",
+    "near-ai": "nearai",
+    "near-ai-cloud": "nearai",
+    "near.ai": "nearai",
+    nearai: "nearai",
+    "z.ai": "zai",
+    zai: "zai",
+    kimi: "moonshot",
+    moonshot: "moonshot",
+    moonshotai: "moonshot",
+    "moonshot-ai": "moonshot",
+    cerebras: "cerebras",
+    // Tolerate the linked-account form so env/integration callers normalize too.
+    "cerebras-api": "cerebras",
+};
+export function isSubscriptionProviderSelectionId(value) {
+    return SUBSCRIPTION_PROVIDER_SELECTIONS.some((provider) => provider.id === value);
+}
+export function normalizeSubscriptionProviderSelectionId(value) {
+    const normalized = normalizeFirstRunProviderId(value);
+    return isSubscriptionProviderSelectionId(normalized) ? normalized : null;
+}
+export function getStoredSubscriptionProvider(selectionId) {
+    return (SUBSCRIPTION_PROVIDER_SELECTIONS.find((provider) => provider.id === selectionId)?.storedProvider ?? "anthropic-subscription");
+}
+export function getSubscriptionProviderFamily(selectionId) {
+    return (SUBSCRIPTION_PROVIDER_SELECTIONS.find((provider) => provider.id === selectionId)?.family ?? "anthropic");
+}
+export function requiresAdditionalRuntimeProvider(providerId) {
+    const selection = normalizeSubscriptionProviderSelectionId(providerId);
+    return Boolean(selection && selection !== "openai-subscription");
+}
+export function normalizeFirstRunProviderId(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 = FIRST_RUN_PROVIDER_CATALOG.find((provider) => provider.id === candidate);
+        if (directMatch) {
+            return directMatch.id;
+        }
+        const alias = FIRST_RUN_PROVIDER_ALIASES[candidate];
+        if (alias) {
+            return alias;
+        }
+    }
+    for (const candidate of candidates) {
+        const pluginMatches = FIRST_RUN_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];
+        if (!preferredMatch) {
+            continue;
+        }
+        return preferredMatch.id;
+    }
+    return null;
+}
+export function getFirstRunProviderOption(providerId) {
+    const normalized = normalizeFirstRunProviderId(providerId);
+    if (!normalized)
+        return null;
+    return (FIRST_RUN_PROVIDER_CATALOG.find((provider) => provider.id === normalized) ??
+        null);
+}
+export function getFirstRunProviderFamily(providerId) {
+    return getFirstRunProviderOption(providerId)?.family ?? null;
+}
+export function getStoredFirstRunProviderId(providerId) {
+    const provider = getFirstRunProviderOption(providerId);
+    if (!provider)
+        return null;
+    return provider.storedProvider ?? provider.id;
+}
+export function getDirectAccountProviderForFirstRunProvider(providerId) {
+    const normalized = normalizeFirstRunProviderId(providerId);
+    if (!normalized)
+        return null;
+    if (!(normalized in DIRECT_ACCOUNT_PROVIDER_BY_FIRST_RUN_PROVIDER)) {
+        return null;
+    }
+    return DIRECT_ACCOUNT_PROVIDER_BY_FIRST_RUN_PROVIDER[normalized];
+}
+export function sortFirstRunProviders(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 isFirstRunConnectionComplete(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 readFirstRunEnvContainer(config) {
+    const env = asConfigRecord(config?.env);
+    return {
+        env,
+        vars: asConfigRecord(env?.vars),
+    };
+}
+export function readFirstRunEnvString(config, key) {
+    const { env, vars } = readFirstRunEnvContainer(config);
+    return readConfigString(vars, key) ?? readConfigString(env, key);
+}
+export function readFirstRunEnvSecret(config, key) {
+    return normalizeSecretString(readFirstRunEnvString(config, key));
+}
+/** Alias to keep call-sites unchanged. */
+const _isTruthyEnvFlag = isTruthyEnvValue;
+export function getFirstRunProviderSignalEnvKeys(providerId) {
+    if (providerId === "ollama") {
+        return ["OLLAMA_BASE_URL"];
+    }
+    if (providerId === "zai") {
+        return ["ZAI_API_KEY", "Z_AI_API_KEY"];
+    }
+    const provider = getFirstRunProviderOption(providerId);
+    return provider?.envKey ? [provider.envKey] : [];
+}
+function readFirstRunProviderApiKey(config, providerId) {
+    if (!providerId) {
+        return undefined;
+    }
+    const provider = getFirstRunProviderOption(providerId);
+    if (provider?.envKey == null) {
+        return undefined;
+    }
+    const canonical = readFirstRunEnvSecret(config, provider.envKey);
+    if (canonical || providerId !== "zai") {
+        return canonical;
+    }
+    return readFirstRunEnvSecret(config, "Z_AI_API_KEY");
+}
+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",
+        ...pickFirstRunCloudModelPreferences(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 = normalizeFirstRunProviderId(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 = normalizeLinkedAccountFlagsConfig(root?.linkedAccounts) ?? {};
+    const next = { ...explicit };
+    const cloud = asConfigRecord(config?.cloud);
+    const hasCloudKey = Boolean(normalizeSecretString(cloud?.apiKey));
+    const existingCloudAccount = next.elizacloud ?? {};
+    if (hasCloudKey && !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 deriveFirstRunConnectionFromRuntimeConfig(config) {
+    const routing = resolveServiceRoutingInConfig(config);
+    const deploymentTarget = resolveDeploymentTargetInConfig(config);
+    const llmText = routing?.llmText;
+    const backend = normalizeFirstRunProviderId(llmText?.backend);
+    const routeApiKey = readFirstRunProviderApiKey(config, backend);
+    if (llmText?.transport === "cloud-proxy" && backend === "elizacloud") {
+        return {
+            kind: "cloud-managed",
+            cloudProvider: "elizacloud",
+            ...pickFirstRunCloudModelPreferences(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 = normalizeFirstRunProviderId(readConfigString(defaults, "subscriptionProvider"));
+    if (storedSubscriptionProvider &&
+        storedSubscriptionProvider !== "elizacloud" &&
+        !requiresAdditionalRuntimeProvider(storedSubscriptionProvider)) {
+        return storedSubscriptionProvider;
+    }
+    for (const provider of FIRST_RUN_PROVIDER_CATALOG) {
+        if (provider.id === "elizacloud") {
+            continue;
+        }
+        const providerId = provider.id;
+        const detected = getFirstRunProviderSignalEnvKeys(providerId).some((key) => Boolean(readFirstRunEnvString(config, key)));
+        if (detected) {
+            return providerId;
+        }
+    }
+    return null;
+}
+export function normalizePersistedFirstRunConnection(value) {
+    const connection = asConfigRecord(value);
+    if (!connection) {
+        return null;
+    }
+    if (connection.kind === "cloud-managed") {
+        return {
+            kind: "cloud-managed",
+            cloudProvider: "elizacloud",
+            apiKey: normalizeSecretString(connection.apiKey),
+            ...readFirstRunCloudModelPreferences(connection),
+        };
+    }
+    if (connection.kind === "local-provider") {
+        const provider = normalizeFirstRunProviderId(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 = normalizeFirstRunProviderId(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 normalizeFirstRunCredentialInputs(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 deriveFirstRunCredentialPersistencePlan(args) {
+    const credentialInputs = normalizeFirstRunCredentialInputs(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" &&
+        normalizeFirstRunProviderId(llmRoute.backend) === "elizacloud" &&
+        cloudApiKey) {
+        return {
+            llmSelection: {
+                backend: "elizacloud",
+                transport: "cloud-proxy",
+                apiKey: cloudApiKey,
+                ...pickFirstRunCloudModelPreferences(llmRoute),
+            },
+            cloudApiKey,
+        };
+    }
+    if (llmRoute?.transport === "direct" && llmApiKey) {
+        const provider = normalizeFirstRunProviderId(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 = normalizeFirstRunProviderId(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 stripFirstRunConnectionSecrets(connection) {
+    if (connection.kind === "cloud-managed") {
+        return {
+            kind: "cloud-managed",
+            cloudProvider: "elizacloud",
+            ...pickFirstRunCloudModelPreferences(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 inferCompatibilityFirstRunConnection(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 localApiKey = readFirstRunProviderApiKey(config, localProvider);
+    if (remoteApiBase) {
+        return {
+            kind: "remote-provider",
+            remoteApiBase,
+            remoteAccessToken,
+            provider: localProvider ?? undefined,
+            apiKey: localApiKey,
+            primaryModel,
+        };
+    }
+    const cloudProvider = normalizeFirstRunProviderId(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 inferFirstRunConnectionFromConfig(config) {
+    return deriveFirstRunConnectionFromRuntimeConfig(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 = normalizeFirstRunProviderId(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" &&
+        normalizeFirstRunProviderId(llmText.backend) === "elizacloud");
+}
+// ---------------------------------------------------------------------------
+// Provider option registry — allows plugins to register additional providers
+// at runtime without modifying the hardcoded FIRST_RUN_PROVIDER_CATALOG.
+// ---------------------------------------------------------------------------
+const _registeredProviderOptions = [];
+/**
+ * Register an additional provider option at runtime.
+ * Plugins should call this during initialization to add themselves to the
+ * first-run 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 FIRST_RUN_PROVIDER_CATALOG) {
+        merged.set(option.id, option);
+    }
+    for (const option of _registeredProviderOptions) {
+        merged.set(option.id, option);
+    }
+    return Array.from(merged.values());
+}
+//# sourceMappingURL=first-run-options.js.map