@elizaos/agent 0.25.9 → 2.0.0-alpha.151

package/packages/shared/src/contracts/apps.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Shared app manager contracts.
+ */
+export type AppSessionMode = "viewer" | "spectate-and-steer" | "external";
+export type AppSessionFeature = "commands" | "telemetry" | "pause" | "resume" | "suggestions";
+export type AppSessionControlAction = "pause" | "resume";
+export type AppRunViewerAttachment = "attached" | "detached" | "unavailable";
+export type AppRunHealthState = "healthy" | "degraded" | "offline";
+export type AppRunCapabilityAvailability = "available" | "unavailable" | "unknown";
+export type AppRunEventKind = "launch" | "refresh" | "attach" | "detach" | "stop" | "status" | "summary" | "health";
+export type AppRunEventSeverity = "info" | "warning" | "error";
+export type AppSessionJsonValue = string | number | boolean | null | AppSessionJsonValue[] | {
+    [key: string]: AppSessionJsonValue;
+};
+export interface AppViewerAuthMessage {
+    type: string;
+    authToken?: string;
+    characterId?: string;
+    sessionToken?: string;
+    agentId?: string;
+    followEntity?: string;
+}
+export interface AppSessionRecommendation {
+    id: string;
+    label: string;
+    type?: string;
+    reason?: string | null;
+    priority?: number | null;
+    command?: string | null;
+}
+export interface AppSessionActivityItem {
+    id: string;
+    type: string;
+    message: string;
+    timestamp?: number | null;
+    severity?: "info" | "warning" | "error";
+}
+export interface AppViewerConfig {
+    url: string;
+    embedParams?: Record<string, string>;
+    postMessageAuth?: boolean;
+    sandbox?: string;
+    authMessage?: AppViewerAuthMessage;
+}
+export interface AppSessionConfig {
+    mode: AppSessionMode;
+    features?: AppSessionFeature[];
+}
+export interface AppSessionState {
+    sessionId: string;
+    appName: string;
+    mode: AppSessionMode;
+    status: string;
+    displayName?: string;
+    agentId?: string;
+    characterId?: string;
+    followEntity?: string;
+    canSendCommands?: boolean;
+    controls?: AppSessionControlAction[];
+    summary?: string | null;
+    goalLabel?: string | null;
+    suggestedPrompts?: string[];
+    recommendations?: AppSessionRecommendation[];
+    activity?: AppSessionActivityItem[];
+    telemetry?: Record<string, AppSessionJsonValue> | null;
+}
+export interface AppSessionActionResult {
+    success: boolean;
+    message: string;
+    session?: AppSessionState | null;
+}
+export interface AppRunHealth {
+    state: AppRunHealthState;
+    message: string | null;
+}
+export interface AppRunHealthFacet {
+    state: AppRunHealthState | "unknown";
+    message: string | null;
+}
+export interface AppRunHealthDetails {
+    checkedAt: string | null;
+    auth: AppRunHealthFacet;
+    runtime: AppRunHealthFacet;
+    viewer: AppRunHealthFacet;
+    chat: AppRunHealthFacet;
+    control: AppRunHealthFacet;
+    message: string | null;
+}
+export interface AppRunEvent {
+    eventId: string;
+    kind: AppRunEventKind;
+    severity: AppRunEventSeverity;
+    message: string;
+    createdAt: string;
+    status?: string | null;
+    details?: Record<string, AppSessionJsonValue> | null;
+}
+export interface AppRunAwaySummary {
+    generatedAt: string;
+    message: string;
+    eventCount: number;
+    since: string | null;
+    until: string | null;
+}
+export interface AppRunSummary {
+    runId: string;
+    appName: string;
+    displayName: string;
+    pluginName: string;
+    launchType: string;
+    launchUrl: string | null;
+    viewer: AppViewerConfig | null;
+    session: AppSessionState | null;
+    characterId: string | null;
+    agentId: string | null;
+    status: string;
+    summary: string | null;
+    startedAt: string;
+    updatedAt: string;
+    lastHeartbeatAt: string | null;
+    supportsBackground: boolean;
+    supportsViewerDetach: boolean;
+    chatAvailability: AppRunCapabilityAvailability;
+    controlAvailability: AppRunCapabilityAvailability;
+    viewerAttachment: AppRunViewerAttachment;
+    recentEvents: AppRunEvent[];
+    awaySummary: AppRunAwaySummary | null;
+    health: AppRunHealth;
+    healthDetails: AppRunHealthDetails;
+}
+export interface AppRunActionResult {
+    success: boolean;
+    message: string;
+    run?: AppRunSummary | null;
+}
+export type AppLaunchDiagnosticSeverity = "info" | "warning" | "error";
+export interface AppLaunchDiagnostic {
+    code: string;
+    severity: AppLaunchDiagnosticSeverity;
+    message: string;
+}
+export interface AppLaunchPreparation {
+    diagnostics?: AppLaunchDiagnostic[];
+    launchUrl?: string | null;
+    viewer?: Omit<AppViewerConfig, "authMessage"> | null;
+}
+export interface AppLaunchResult {
+    pluginInstalled: boolean;
+    needsRestart: boolean;
+    displayName: string;
+    launchType: string;
+    launchUrl: string | null;
+    viewer: AppViewerConfig | null;
+    session: AppSessionState | null;
+    run: AppRunSummary | null;
+    diagnostics?: AppLaunchDiagnostic[];
+}
+export interface InstalledAppInfo {
+    name: string;
+    displayName: string;
+    pluginName: string;
+    version: string;
+    installedAt: string;
+}
+export interface ElizaCuratedAppDefinition {
+    slug: string;
+    canonicalName: string;
+    aliases: string[];
+}
+export interface AppStopResult {
+    success: boolean;
+    appName: string;
+    runId: string | null;
+    stoppedAt: string;
+    pluginUninstalled: boolean;
+    needsRestart: boolean;
+    stopScope: "plugin-uninstalled" | "viewer-session" | "no-op";
+    message: string;
+}
+export declare const ELIZA_CURATED_APP_DEFINITIONS: readonly ElizaCuratedAppDefinition[];
+export declare function packageNameToAppRouteSlug(packageName: string): string | null;
+export declare function packageNameToAppDisplayName(packageName: string): string;
+export declare function hasAppInterface(value: {
+    kind?: string | null;
+    appMeta?: unknown;
+} | null | undefined): boolean;
+export declare function getElizaCuratedAppDefinition(value: string): ElizaCuratedAppDefinition | null;
+export declare function normalizeElizaCuratedAppName(value: string): string | null;
+export declare function isElizaCuratedAppName(value: string): boolean;
+/**
+ * Register an additional curated app definition at runtime.
+ * Plugins should call this during initialization to add their app to the
+ * curated catalog.
+ */
+export declare function registerCuratedApp(def: ElizaCuratedAppDefinition): void;
+/**
+ * Get all curated app definitions: hardcoded list merged with
+ * runtime-registered apps. Runtime registrations with the same slug
+ * override hardcoded entries.
+ */
+export declare function getCuratedAppDefinitions(): ElizaCuratedAppDefinition[];
+export declare function getElizaCuratedAppCatalogOrder(value: string): number;
+export declare function getElizaCuratedAppLookupNames(value: string): string[];
+//# sourceMappingURL=apps.d.ts.map

package/packages/shared/src/contracts/apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../../../../../shared/src/contracts/apps.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,188 @@
+/**
+ * Shared app manager contracts.
+ */
+function packageNameToBasename(packageName) {
+    return packageName
+        .trim()
+        .replace(/^@[^/]+\//, "")
+        .trim();
+}
+export const ELIZA_CURATED_APP_DEFINITIONS = [
+    {
+        slug: "companion",
+        canonicalName: "@elizaos/app-companion",
+        aliases: [],
+    },
+    {
+        slug: "hyperscape",
+        canonicalName: "@hyperscape/plugin-hyperscape",
+        aliases: ["@elizaos/app-hyperscape"],
+    },
+    {
+        slug: "babylon",
+        canonicalName: "@elizaos/app-babylon",
+        aliases: [],
+    },
+    {
+        slug: "2004scape",
+        canonicalName: "@elizaos/app-2004scape",
+        aliases: [],
+    },
+    {
+        slug: "scape",
+        canonicalName: "@elizaos/app-scape",
+        aliases: [],
+    },
+    {
+        slug: "defense-of-the-agents",
+        canonicalName: "@elizaos/app-defense-of-the-agents",
+        aliases: [],
+    },
+    {
+        slug: "vincent",
+        canonicalName: "@elizaos/app-vincent",
+        aliases: [],
+    },
+    {
+        slug: "shopify",
+        canonicalName: "@elizaos/app-shopify",
+        aliases: ["@elizaos/plugin-shopify"],
+    },
+    {
+        slug: "clawville",
+        canonicalName: "@clawville/app-clawville",
+        aliases: [],
+    },
+];
+function getElizaCuratedAppMatchKeys(definition) {
+    const keys = new Set([
+        definition.slug.trim().toLowerCase(),
+        definition.canonicalName.trim().toLowerCase(),
+    ]);
+    for (const alias of definition.aliases) {
+        const trimmed = alias.trim().toLowerCase();
+        if (!trimmed)
+            continue;
+        keys.add(trimmed);
+        const routeSlug = packageNameToAppRouteSlug(alias)?.trim().toLowerCase();
+        if (routeSlug) {
+            keys.add(routeSlug);
+        }
+    }
+    const canonicalRouteSlug = packageNameToAppRouteSlug(definition.canonicalName)
+        ?.trim()
+        .toLowerCase();
+    if (canonicalRouteSlug) {
+        keys.add(canonicalRouteSlug);
+    }
+    return Array.from(keys);
+}
+const ELIZA_CURATED_APP_DEFINITION_BY_KEY = new Map(ELIZA_CURATED_APP_DEFINITIONS.flatMap((definition) => getElizaCuratedAppMatchKeys(definition).map((key) => [key, definition])));
+export function packageNameToAppRouteSlug(packageName) {
+    const basename = packageNameToBasename(packageName);
+    if (!basename)
+        return null;
+    const withoutPrefix = basename.replace(/^(app|plugin)-/, "").trim();
+    return withoutPrefix || basename;
+}
+export function packageNameToAppDisplayName(packageName) {
+    const slug = packageNameToAppRouteSlug(packageName) ??
+        packageNameToBasename(packageName) ??
+        packageName.trim();
+    return slug
+        .split(/[^a-zA-Z0-9]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+export function hasAppInterface(value) {
+    return Boolean(value && (value.kind === "app" || value.appMeta));
+}
+export function getElizaCuratedAppDefinition(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const directMatch = ELIZA_CURATED_APP_DEFINITION_BY_KEY.get(trimmed.toLowerCase());
+    if (directMatch) {
+        return directMatch;
+    }
+    const routeSlug = packageNameToAppRouteSlug(trimmed)?.trim().toLowerCase();
+    if (!routeSlug) {
+        return null;
+    }
+    return ELIZA_CURATED_APP_DEFINITION_BY_KEY.get(routeSlug) ?? null;
+}
+export function normalizeElizaCuratedAppName(value) {
+    return getElizaCuratedAppDefinition(value)?.canonicalName ?? null;
+}
+export function isElizaCuratedAppName(value) {
+    return normalizeElizaCuratedAppName(value) !== null;
+}
+// ---------------------------------------------------------------------------
+// Curated app registry — allows plugins to register additional curated app
+// definitions at runtime without modifying the hardcoded list.
+// ---------------------------------------------------------------------------
+const _registeredCuratedApps = [];
+/**
+ * Register an additional curated app definition at runtime.
+ * Plugins should call this during initialization to add their app to the
+ * curated catalog.
+ */
+export function registerCuratedApp(def) {
+    const existing = _registeredCuratedApps.findIndex((d) => d.slug === def.slug);
+    if (existing >= 0) {
+        _registeredCuratedApps[existing] = def;
+    }
+    else {
+        _registeredCuratedApps.push(def);
+    }
+    // Rebuild the lookup map so runtime-registered apps are discoverable
+    _rebuildCuratedAppLookup();
+}
+/**
+ * Get all curated app definitions: hardcoded list merged with
+ * runtime-registered apps. Runtime registrations with the same slug
+ * override hardcoded entries.
+ */
+export function getCuratedAppDefinitions() {
+    const merged = new Map();
+    for (const def of ELIZA_CURATED_APP_DEFINITIONS) {
+        merged.set(def.slug, def);
+    }
+    for (const def of _registeredCuratedApps) {
+        merged.set(def.slug, def);
+    }
+    return Array.from(merged.values());
+}
+function _rebuildCuratedAppLookup() {
+    // Add registered apps to the mutable lookup map
+    for (const def of _registeredCuratedApps) {
+        for (const key of getElizaCuratedAppMatchKeys(def)) {
+            ELIZA_CURATED_APP_DEFINITION_BY_KEY.set(key, def);
+        }
+    }
+}
+export function getElizaCuratedAppCatalogOrder(value) {
+    const canonicalName = normalizeElizaCuratedAppName(value);
+    if (!canonicalName) {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    const index = ELIZA_CURATED_APP_DEFINITIONS.findIndex((definition) => definition.canonicalName === canonicalName);
+    return index >= 0 ? index : Number.MAX_SAFE_INTEGER;
+}
+export function getElizaCuratedAppLookupNames(value) {
+    const definition = getElizaCuratedAppDefinition(value);
+    if (!definition) {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : [];
+    }
+    return Array.from(new Set([
+        definition.canonicalName,
+        ...definition.aliases,
+        definition.slug,
+        ...definition.aliases
+            .map((alias) => packageNameToAppRouteSlug(alias))
+            .filter((alias) => Boolean(alias)),
+        packageNameToAppRouteSlug(definition.canonicalName) ?? definition.slug,
+    ]));
+}

package/packages/shared/src/contracts/awareness.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Self-Awareness System v1 — shared contracts.
+ *
+ * @architecture Layered lazy-load + declarative AwarenessContributor
+ * @see docs/plans/2026-03-01-self-awareness-design.md
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+export declare const SELF_STATUS_SCHEMA_VERSION = 1;
+/** Max chars for a single contributor summary line. */
+export declare const SUMMARY_CHAR_LIMIT = 80;
+/** Max total chars for the composed Layer 1 output (~300 tokens). */
+export declare const SUMMARY_TOTAL_CHAR_LIMIT = 1200;
+/** Default cache TTL in ms (1 minute). */
+export declare const DEFAULT_CACHE_TTL_MS = 60000;
+export type AwarenessInvalidationEvent = "permission-changed" | "plugin-changed" | "wallet-updated" | "provider-changed" | "config-changed" | "runtime-restarted" | "opinion-updated";
+export interface AwarenessContributor {
+    /** Unique identifier, e.g. "wallet", "permissions". */
+    id: string;
+    /** Sort priority (lower = higher in output).
+     *  10=runtime, 20=permissions, 30=wallet, 40=provider,
+     *  50=pluginHealth, 60=connectors, 70=cloud, 80=features */
+    position: number;
+    /** Layer 1 summary — injected every LLM turn.
+     *  MUST return plain text, never secrets/keys/tokens.
+     *  MUST be <= SUMMARY_CHAR_LIMIT chars. Return "" if nothing to show. */
+    summary: (runtime: IAgentRuntime) => Promise<string>;
+    /** Layer 2 detail — called via GET_SELF_STATUS action.
+     *  "brief" ~= 200 tokens, "full" ~= 2000 tokens. */
+    detail?: (runtime: IAgentRuntime, level: "brief" | "full") => Promise<string>;
+    /** Cache TTL in ms. Default DEFAULT_CACHE_TTL_MS. */
+    cacheTtl?: number;
+    /** Events that proactively clear the cache (don't wait for TTL). */
+    invalidateOn?: AwarenessInvalidationEvent[];
+    /** Only built-in contributors set trusted=true.
+     *  Untrusted contributor output is sanitized before injection. */
+    trusted?: boolean;
+}
+//# sourceMappingURL=awareness.d.ts.map

package/packages/shared/src/contracts/awareness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awareness.d.ts","sourceRoot":"","sources":["../../../../../../shared/src/contracts/awareness.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,uDAAuD;AACvD,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,MAAM,MAAM,0BAA0B,GAClC,oBAAoB,GACpB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,GACnB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IAEX;;gEAE4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IAEjB;;6EAEyE;IACzE,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAErD;wDACoD;IACpD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9E,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oEAAoE;IACpE,YAAY,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAE5C;sEACkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

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

@@ -0,0 +1,7 @@
+export const SELF_STATUS_SCHEMA_VERSION = 1;
+/** Max chars for a single contributor summary line. */
+export const SUMMARY_CHAR_LIMIT = 80;
+/** Max total chars for the composed Layer 1 output (~300 tokens). */
+export const SUMMARY_TOTAL_CHAR_LIMIT = 1200;
+/** Default cache TTL in ms (1 minute). */
+export const DEFAULT_CACHE_TTL_MS = 60_000;

package/packages/shared/src/contracts/cloud-topology.d.ts

@@ -0,0 +1,13 @@
+export type ElizaCloudService = "inference" | "tts" | "media" | "embeddings" | "rpc";
+export type ResolvedElizaCloudTopology = {
+    linked: boolean;
+    provider: "elizacloud" | null;
+    runtime: "cloud" | "local";
+    services: Record<ElizaCloudService, boolean>;
+    shouldLoadPlugin: boolean;
+};
+export declare function isElizaCloudLinkedInConfig(config: Record<string, unknown> | null | undefined): boolean;
+export declare function resolveElizaCloudTopology(config: Record<string, unknown> | null | undefined): ResolvedElizaCloudTopology;
+export declare function isElizaCloudServiceSelectedInConfig(config: Record<string, unknown> | null | undefined, service: ElizaCloudService): boolean;
+export declare function shouldLoadElizaCloudPluginInConfig(config: Record<string, unknown> | null | undefined): boolean;
+//# sourceMappingURL=cloud-topology.d.ts.map

package/packages/shared/src/contracts/cloud-topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-topology.d.ts","sourceRoot":"","sources":["../../../../../../shared/src/contracts/cloud-topology.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,KAAK,GACL,OAAO,GACP,YAAY,GACZ,KAAK,CAAC;AAEV,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;IAC7C,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAiCF,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GACjD,OAAO,CAST;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GACjD,0BAA0B,CA8C5B;AAED,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAET;AAED,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GACjD,OAAO,CAET"}

package/packages/shared/src/contracts/cloud-topology.js

@@ -0,0 +1,73 @@
+import { normalizeOnboardingProviderId, resolveDeploymentTargetInConfig, resolveLinkedAccountsInConfig, resolveServiceRoutingInConfig, } from "./onboarding.js";
+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;
+}
+export function isElizaCloudLinkedInConfig(config) {
+    const linkedAccounts = resolveLinkedAccountsInConfig(config);
+    const linkedCloudAccount = linkedAccounts?.elizacloud;
+    if (linkedCloudAccount?.status === "linked") {
+        return true;
+    }
+    const cloud = asConfigRecord(config?.cloud);
+    return Boolean(normalizeSecretString(cloud?.apiKey));
+}
+export function resolveElizaCloudTopology(config) {
+    const deploymentTarget = resolveDeploymentTargetInConfig(config);
+    const routing = resolveServiceRoutingInConfig(config);
+    const provider = (normalizeOnboardingProviderId(routing?.llmText?.backend) === "elizacloud"
+        ? "elizacloud"
+        : null) ??
+        (deploymentTarget.provider === "elizacloud" ? "elizacloud" : null);
+    const runtime = deploymentTarget.runtime === "cloud" ? "cloud" : "local";
+    const resolvedServices = {
+        inference: Boolean(routing?.llmText?.transport === "cloud-proxy" &&
+            normalizeOnboardingProviderId(routing.llmText.backend) ===
+                "elizacloud"),
+        tts: Boolean(routing?.tts?.transport === "cloud-proxy" &&
+            normalizeOnboardingProviderId(routing.tts.backend) === "elizacloud"),
+        media: Boolean(routing?.media?.transport === "cloud-proxy" &&
+            normalizeOnboardingProviderId(routing.media.backend) === "elizacloud"),
+        embeddings: Boolean(routing?.embeddings?.transport === "cloud-proxy" &&
+            normalizeOnboardingProviderId(routing.embeddings.backend) ===
+                "elizacloud"),
+        rpc: Boolean(routing?.rpc?.transport === "cloud-proxy" &&
+            normalizeOnboardingProviderId(routing.rpc.backend) === "elizacloud"),
+    };
+    const cloudDeploymentSelected = deploymentTarget.runtime === "cloud" &&
+        deploymentTarget.provider === "elizacloud";
+    return {
+        linked: isElizaCloudLinkedInConfig(config),
+        provider: provider === "elizacloud" ? "elizacloud" : null,
+        runtime,
+        services: resolvedServices,
+        shouldLoadPlugin: cloudDeploymentSelected ||
+            Object.values(resolvedServices).some(Boolean),
+    };
+}
+export function isElizaCloudServiceSelectedInConfig(config, service) {
+    return resolveElizaCloudTopology(config).services[service];
+}
+export function shouldLoadElizaCloudPluginInConfig(config) {
+    return resolveElizaCloudTopology(config).shouldLoadPlugin;
+}