@elizaos/agent 2.0.0-alpha.98 → 2.0.0-beta.2

package/packages/agent/src/api/wallet-routes.js

@@ -1,8 +1,12 @@
 import { logger } from "@elizaos/core";
-import { normalizeWalletRpcSelections, } from "../contracts/wallet";
-import { createIntegrationTelemetrySpan } from "../diagnostics/integration-observability";
-import { fetchEvmBalances, fetchSolanaBalances, fetchSolanaNativeBalanceViaRpc, generateWalletForChain, getWalletAddresses, importWallet, validatePrivateKey, } from "./wallet";
-import { applyWalletRpcConfigUpdate, getStoredWalletRpcSelections, resolveWalletRpcReadiness, } from "./wallet-rpc";
+import { ElizaCloudClient, getOrCreateClientAddressKey, normalizeCloudSiteUrl, persistCloudWalletCache, provisionCloudWalletsBestEffort, resolveCloudApiKey, } from "@elizaos/plugin-elizacloud";
+import { normalizeWalletRpcSelections, } from "@elizaos/shared";
+import { isCloudWalletEnabled } from "../config/feature-flags.js";
+import { createIntegrationTelemetrySpan } from "../diagnostics/integration-observability.js";
+import { persistConfigEnv } from "./config-env.js";
+import { fetchEvmBalances, fetchSolanaBalances, fetchSolanaNativeBalanceViaRpc, generateWalletForChain, getWalletAddresses, importWallet, setSolanaWalletEnv, validatePrivateKey, } from "./wallet.js";
+import { resolveWalletCapabilityStatus } from "./wallet-capability.js";
+import { applyWalletRpcConfigUpdate, getStoredWalletRpcSelections, resolveWalletNetworkMode, resolveWalletRpcReadiness, } from "./wallet-rpc.js";
 const WALLET_CONFIG_COMPAT_KEYS = new Set([
     "ALCHEMY_API_KEY",
     "INFURA_API_KEY",
@@ -25,6 +29,9 @@ function resolveWalletConfigUpdateRequest(body, currentSelections) {
     if (record.selections &&
         typeof record.selections === "object" &&
         !Array.isArray(record.selections)) {
+        const walletNetwork = record.walletNetwork === "testnet" || record.walletNetwork === "mainnet"
+            ? record.walletNetwork
+            : undefined;
         const credentials = record.credentials &&
             typeof record.credentials === "object" &&
             !Array.isArray(record.credentials)
@@ -32,6 +39,7 @@ function resolveWalletConfigUpdateRequest(body, currentSelections) {
             : undefined;
         return {
             selections: normalizeWalletRpcSelections(record.selections),
+            walletNetwork,
             credentials: credentials,
         };
     }
@@ -41,6 +49,9 @@ function resolveWalletConfigUpdateRequest(body, currentSelections) {
     }
     return {
         selections: currentSelections,
+        walletNetwork: record.walletNetwork === "testnet" || record.walletNetwork === "mainnet"
+            ? record.walletNetwork
+            : undefined,
         credentials: compatCredentials,
     };
 }
@@ -53,8 +64,145 @@ export const DEFAULT_WALLET_ROUTE_DEPENDENCIES = {
     importWallet,
     generateWalletForChain,
 };
+function readCloudWalletCache(config) {
+    const wallet = config.wallet;
+    if (!wallet || typeof wallet !== "object")
+        return {};
+    const cloud = wallet.cloud;
+    if (!cloud || typeof cloud !== "object")
+        return {};
+    return cloud;
+}
+function readPrimaryMap(config) {
+    const wallet = config.wallet;
+    const raw = wallet && typeof wallet === "object"
+        ? wallet.primary
+        : undefined;
+    const out = { evm: "local", solana: "local" };
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const record = raw;
+        if (record.evm === "cloud" || record.evm === "local")
+            out.evm = record.evm;
+        if (record.solana === "cloud" || record.solana === "local") {
+            out.solana = record.solana;
+        }
+    }
+    return out;
+}
+function coerceCloudProvider(value) {
+    return value === "privy" || value === "steward" ? value : "privy";
+}
+/**
+ * Build the dual-wallet `{ wallets[], primary }` block. Returns `null`
+ * when the cloud-wallet flag is off so callers can omit both fields and
+ * preserve the pre-flag response shape exactly.
+ */
+function buildDualWalletShape(config, addresses) {
+    if (!isCloudWalletEnabled())
+        return null;
+    const primary = readPrimaryMap(config);
+    const wallets = [];
+    if (addresses.evmAddress) {
+        wallets.push({
+            source: "local",
+            chain: "evm",
+            address: addresses.evmAddress,
+            provider: "local",
+            primary: primary.evm === "local",
+        });
+    }
+    if (addresses.solanaAddress) {
+        wallets.push({
+            source: "local",
+            chain: "solana",
+            address: addresses.solanaAddress,
+            provider: "local",
+            primary: primary.solana === "local",
+        });
+    }
+    const cloud = readCloudWalletCache(config);
+    for (const chain of ["evm", "solana"]) {
+        const descriptor = cloud[chain];
+        const address = descriptor?.walletAddress;
+        if (typeof address === "string" && address.length > 0) {
+            wallets.push({
+                source: "cloud",
+                chain,
+                address,
+                provider: coerceCloudProvider(descriptor?.walletProvider),
+                primary: primary[chain] === "cloud",
+            });
+        }
+    }
+    return { wallets, primary };
+}
+function readCloudWalletAddress(descriptor) {
+    if (typeof descriptor?.walletAddress !== "string")
+        return null;
+    const trimmed = descriptor.walletAddress.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function readCachedCloudWalletDescriptor(config, chain) {
+    const descriptor = readCloudWalletCache(config)[chain];
+    const walletAddress = readCloudWalletAddress(descriptor);
+    if (!walletAddress)
+        return null;
+    return {
+        agentWalletId: typeof descriptor?.agentWalletId === "string" &&
+            descriptor.agentWalletId.trim().length > 0
+            ? descriptor.agentWalletId
+            : `cached-${chain}`,
+        walletAddress,
+        walletProvider: coerceCloudProvider(descriptor?.walletProvider),
+        chainType: chain,
+        balance: descriptor?.balance ?? undefined,
+    };
+}
+function readCachedCloudWalletDescriptors(config) {
+    const evm = readCachedCloudWalletDescriptor(config, "evm");
+    const solana = readCachedCloudWalletDescriptor(config, "solana");
+    return {
+        ...(evm ? { evm } : {}),
+        ...(solana ? { solana } : {}),
+    };
+}
+function resolvePrimaryWalletAddresses(config, addresses) {
+    const primary = readPrimaryMap(config);
+    const cloud = readCloudWalletCache(config);
+    return {
+        evmAddress: primary.evm === "cloud"
+            ? readCloudWalletAddress(cloud.evm)
+            : addresses.evmAddress,
+        solanaAddress: primary.solana === "cloud"
+            ? readCloudWalletAddress(cloud.solana)
+            : addresses.solanaAddress,
+    };
+}
+function persistPrimarySelection(config, chain, source) {
+    if (!config.wallet) {
+        config.wallet = {};
+    }
+    const wallet = config.wallet;
+    const primary = { ...(wallet.primary ?? {}) };
+    primary[chain] = source;
+    wallet.primary = primary;
+    config.wallet = wallet;
+}
+async function triggerWalletRuntimeReload(ctx, reason) {
+    const restarted = ctx.restartRuntime
+        ? await ctx.restartRuntime(reason)
+        : false;
+    if (!restarted) {
+        ctx.scheduleRuntimeRestart?.(reason);
+    }
+    return restarted;
+}
+const LOCAL_WALLET_SOURCE_ENV_KEYS = {
+    evm: "WALLET_SOURCE_EVM",
+    solana: "WALLET_SOURCE_SOLANA",
+};
 export async function handleWalletRoutes(ctx) {
-    const { req, res, method, pathname, config, saveConfig, ensureWalletKeysInEnvAndConfig, resolveWalletExportRejection, readJsonBody, json, error, } = ctx;
+    const { req, res, method, pathname, config, saveConfig, readJsonBody, json, error, } = ctx;
     const deps = ctx.deps ?? DEFAULT_WALLET_ROUTE_DEPENDENCIES;
     // GET /api/wallet/addresses
     if (method === "GET" && pathname === "/api/wallet/addresses") {
@@ -139,6 +287,10 @@ export async function handleWalletRoutes(ctx) {
             const detection = deps.validatePrivateKey(body.privateKey.trim());
             chain = detection.chain;
         }
+        // When steward is configured, warn that keys should be imported via vault
+        const stewardWarning = process.env.STEWARD_API_URL?.trim()
+            ? "Steward vault is configured. Consider importing keys directly into the vault instead of storing plaintext keys locally."
+            : undefined;
         const result = deps.importWallet(chain, body.privateKey.trim());
         if (!result.success) {
             error(res, result.error ?? "Import failed", 422);
@@ -148,16 +300,37 @@ export async function handleWalletRoutes(ctx) {
             config.env = {};
         const envKey = chain === "evm" ? "EVM_PRIVATE_KEY" : "SOLANA_PRIVATE_KEY";
         config.env[envKey] = process.env[envKey] ?? "";
+        persistPrimarySelection(config, chain, "local");
+        let configSaveWarning;
         try {
             saveConfig(config);
         }
         catch (err) {
-            logger.warn(`[api] Config save failed: ${err instanceof Error ? err.message : err}`);
+            const msg = `Config save failed: ${String(err)}`;
+            logger.warn(`[api] ${msg}`);
+            configSaveWarning = msg;
+        }
+        const warnings = [];
+        if (configSaveWarning)
+            warnings.push(configSaveWarning);
+        if (stewardWarning)
+            warnings.push(stewardWarning);
+        const walletSourceEnvKey = LOCAL_WALLET_SOURCE_ENV_KEYS[chain];
+        process.env[walletSourceEnvKey] = "local";
+        try {
+            await persistConfigEnv(walletSourceEnvKey, "local");
         }
+        catch (err) {
+            error(res, `Failed to persist ${walletSourceEnvKey}: ${String(err)}`, 500);
+            return true;
+        }
+        const restarted = await triggerWalletRuntimeReload(ctx, "Wallet configuration updated");
         json(res, {
             ok: true,
             chain,
             address: result.address,
+            restarting: restarted,
+            ...(warnings.length > 0 ? { warnings } : {}),
         });
         return true;
     }
@@ -168,49 +341,189 @@ export async function handleWalletRoutes(ctx) {
             return true;
         const chain = body.chain;
         const validChains = ["evm", "solana", "both"];
+        const requestedSource = body.source === "local" || body.source === "steward"
+            ? body.source
+            : undefined;
         if (chain && !validChains.includes(chain)) {
             error(res, `Unsupported chain: ${chain}. Must be "evm", "solana", or "both".`);
             return true;
         }
+        if (typeof body.source === "string" &&
+            requestedSource !== "local" &&
+            requestedSource !== "steward") {
+            error(res, `Unsupported source: ${body.source}. Must be "local" or "steward".`);
+            return true;
+        }
         const targetChain = (chain ?? "both");
+        // ── Steward-first: delegate wallet generation to steward ──────────
+        const stewardApiUrl = process.env.STEWARD_API_URL?.trim();
+        if (stewardApiUrl && requestedSource !== "local") {
+            try {
+                const agentId = process.env.STEWARD_AGENT_ID?.trim() ||
+                    process.env.ELIZA_STEWARD_AGENT_ID?.trim() ||
+                    null;
+                if (!agentId) {
+                    error(res, "Steward is configured but no agent ID is set (STEWARD_AGENT_ID).", 500);
+                    return true;
+                }
+                // Build auth headers
+                const headers = {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                };
+                const bearerToken = process.env.STEWARD_AGENT_TOKEN?.trim();
+                const apiKey = process.env.STEWARD_API_KEY?.trim();
+                const tenantId = process.env.STEWARD_TENANT_ID?.trim();
+                if (bearerToken) {
+                    headers.Authorization = `Bearer ${bearerToken}`;
+                }
+                else if (apiKey) {
+                    headers["X-Steward-Key"] = apiKey;
+                }
+                if (tenantId) {
+                    headers["X-Steward-Tenant"] = tenantId;
+                }
+                // Check if agent already exists (has wallets)
+                let agentEvm = null;
+                let agentSolana = null;
+                let agentExists = false;
+                try {
+                    const agentRes = await fetch(`${stewardApiUrl}/agents/${encodeURIComponent(agentId)}`, { headers: { ...headers }, signal: AbortSignal.timeout(15_000) });
+                    if (agentRes.ok) {
+                        agentExists = true;
+                        const agentBody = (await agentRes.json());
+                        const agent = agentBody.data ?? agentBody;
+                        agentEvm =
+                            agent?.walletAddresses?.evm?.trim() ||
+                                agent?.walletAddress?.trim() ||
+                                null;
+                        agentSolana = agent?.walletAddresses?.solana?.trim() || null;
+                    }
+                }
+                catch {
+                    // agent doesn't exist or fetch failed — will try to create
+                }
+                // If agent doesn't exist, create it (steward auto-generates wallets)
+                if (!agentExists) {
+                    const createRes = await fetch(`${stewardApiUrl}/agents`, {
+                        method: "POST",
+                        headers,
+                        body: JSON.stringify({ id: agentId, name: agentId }),
+                        signal: AbortSignal.timeout(15_000),
+                    });
+                    if (!createRes.ok) {
+                        const errText = await createRes.text().catch(() => "Unknown error");
+                        error(res, `Steward agent creation failed: ${errText}`, 502);
+                        return true;
+                    }
+                    const createBody = (await createRes.json());
+                    const created = createBody.data ?? createBody;
+                    agentEvm =
+                        created?.walletAddresses?.evm?.trim() ||
+                            created?.walletAddress?.trim() ||
+                            null;
+                    agentSolana = created?.walletAddresses?.solana?.trim() || null;
+                    logger.info(`[wallet] Created steward agent "${agentId}" with wallets`);
+                }
+                // Cache steward addresses in env for synchronous access
+                const generated = [];
+                if (agentEvm && (targetChain === "both" || targetChain === "evm")) {
+                    process.env.STEWARD_EVM_ADDRESS = agentEvm;
+                    generated.push({ chain: "evm", address: agentEvm });
+                    logger.info(`[wallet] Steward EVM wallet: ${agentEvm}`);
+                }
+                if (agentSolana &&
+                    (targetChain === "both" || targetChain === "solana")) {
+                    process.env.STEWARD_SOLANA_ADDRESS = agentSolana;
+                    generated.push({ chain: "solana", address: agentSolana });
+                    logger.info(`[wallet] Steward Solana wallet: ${agentSolana}`);
+                }
+                json(res, {
+                    ok: true,
+                    wallets: generated,
+                    source: "steward",
+                });
+                return true;
+            }
+            catch (err) {
+                logger.warn(`[wallet] Steward wallet generation failed, falling back to local: ${err}`);
+                // Fall through to local generation
+            }
+        }
+        // ── Legacy local key generation (fallback) ────────────────────────
         if (!config.env)
             config.env = {};
         const generated = [];
+        const generatedChains = [];
         if (targetChain === "both" || targetChain === "evm") {
             const result = deps.generateWalletForChain("evm");
             process.env.EVM_PRIVATE_KEY = result.privateKey;
             config.env.EVM_PRIVATE_KEY =
                 result.privateKey;
+            persistPrimarySelection(config, "evm", "local");
+            generatedChains.push("evm");
             generated.push({ chain: "evm", address: result.address });
             logger.info(`[eliza-api] Generated EVM wallet: ${result.address}`);
         }
         if (targetChain === "both" || targetChain === "solana") {
             const result = deps.generateWalletForChain("solana");
-            process.env.SOLANA_PRIVATE_KEY = result.privateKey;
+            setSolanaWalletEnv(result.privateKey);
             config.env.SOLANA_PRIVATE_KEY =
                 result.privateKey;
+            persistPrimarySelection(config, "solana", "local");
+            generatedChains.push("solana");
             generated.push({ chain: "solana", address: result.address });
             logger.info(`[eliza-api] Generated Solana wallet: ${result.address}`);
         }
+        let configSaveWarning;
         try {
             saveConfig(config);
         }
         catch (err) {
-            logger.warn(`[api] Config save failed: ${err instanceof Error ? err.message : err}`);
+            const msg = `Config save failed: ${String(err)}`;
+            logger.warn(`[api] ${msg}`);
+            configSaveWarning = msg;
+        }
+        for (const chainName of generatedChains) {
+            const walletSourceEnvKey = LOCAL_WALLET_SOURCE_ENV_KEYS[chainName];
+            process.env[walletSourceEnvKey] = "local";
+            try {
+                await persistConfigEnv(walletSourceEnvKey, "local");
+            }
+            catch (err) {
+                error(res, `Failed to persist ${walletSourceEnvKey}: ${String(err)}`, 500);
+                return true;
+            }
         }
-        json(res, { ok: true, wallets: generated });
+        const restarted = await triggerWalletRuntimeReload(ctx, "Wallet configuration updated");
+        json(res, {
+            ok: true,
+            wallets: generated,
+            source: "local",
+            restarting: restarted,
+            ...(configSaveWarning ? { warnings: [configSaveWarning] } : {}),
+        });
         return true;
     }
     // GET /api/wallet/config
     if (method === "GET" && pathname === "/api/wallet/config") {
         const addresses = deps.getWalletAddresses();
+        const primary = readPrimaryMap(config);
+        const primaryAddresses = resolvePrimaryWalletAddresses(config, addresses);
         const rpcReadiness = resolveWalletRpcReadiness(config);
+        const localSolanaSignerAvailable = Boolean(process.env.SOLANA_PRIVATE_KEY?.trim());
+        const capability = resolveWalletCapabilityStatus({
+            config,
+            runtime: ctx.runtime ?? null,
+            getWalletAddresses: () => primaryAddresses,
+        });
         const alchemyKeySet = Boolean(process.env.ALCHEMY_API_KEY?.trim());
         const ankrKeySet = Boolean(process.env.ANKR_API_KEY?.trim());
         const nodeRealSet = Boolean(process.env.NODEREAL_BSC_RPC_URL?.trim());
         const quickNodeSet = Boolean(process.env.QUICKNODE_BSC_RPC_URL?.trim());
         const configStatus = {
             selectedRpcProviders: rpcReadiness.selectedRpcProviders,
+            walletNetwork: resolveWalletNetworkMode(config),
             legacyCustomChains: rpcReadiness.legacyCustomChains,
             alchemyKeySet,
             infuraKeySet: Boolean(process.env.INFURA_API_KEY?.trim()),
@@ -236,57 +549,300 @@ export async function handleWalletRoutes(ctx) {
                 "BSC",
                 "Avalanche",
             ],
-            evmAddress: addresses.evmAddress,
-            solanaAddress: addresses.solanaAddress,
+            evmAddress: primaryAddresses.evmAddress,
+            solanaAddress: primaryAddresses.solanaAddress,
+            walletSource: capability.walletSource,
+            automationMode: capability.automationMode,
+            pluginEvmLoaded: capability.pluginEvmLoaded,
+            pluginEvmRequired: capability.pluginEvmRequired,
+            executionReady: capability.executionReady,
+            executionBlockedReason: capability.executionBlockedReason,
+            evmSigningCapability: capability.evmSigningCapability,
+            evmSigningReason: capability.evmSigningReason,
+            solanaSigningAvailable: primaryAddresses.solanaAddress
+                ? localSolanaSignerAvailable || primary.solana === "cloud"
+                : false,
         };
-        json(res, configStatus);
+        const dual = buildDualWalletShape(config, addresses);
+        if (dual) {
+            json(res, {
+                ...configStatus,
+                wallets: dual.wallets,
+                primary: dual.primary,
+            });
+        }
+        else {
+            json(res, configStatus);
+        }
         return true;
     }
-    // PUT /api/wallet/config
-    if (method === "PUT" && pathname === "/api/wallet/config") {
+    // POST /api/wallet/primary — flag-gated (404 when ENABLE_CLOUD_WALLET is off).
+    // Body: { chain: "evm"|"solana", source: "local"|"cloud" }
+    if (method === "POST" && pathname === "/api/wallet/primary") {
+        if (!isCloudWalletEnabled()) {
+            error(res, "Not found", 404);
+            return true;
+        }
         const body = await readJsonBody(req, res);
         if (!body)
             return true;
-        const updateRequest = resolveWalletConfigUpdateRequest(body, getStoredWalletRpcSelections(config));
-        if (!updateRequest) {
-            error(res, "Invalid wallet config update");
+        const chainRaw = typeof body.chain === "string" ? body.chain : "";
+        const sourceRaw = typeof body.source === "string" ? body.source : "";
+        if (chainRaw !== "evm" && chainRaw !== "solana") {
+            error(res, "chain must be 'evm' or 'solana'");
             return true;
         }
-        applyWalletRpcConfigUpdate(config, updateRequest);
-        ensureWalletKeysInEnvAndConfig(config);
+        if (sourceRaw !== "local" && sourceRaw !== "cloud") {
+            error(res, "source must be 'local' or 'cloud'");
+            return true;
+        }
+        const chain = chainRaw;
+        const source = sourceRaw;
+        const previousPrimary = readPrimaryMap(config)[chain];
+        persistPrimarySelection(config, chain, source);
+        let configSaveWarning;
         try {
             saveConfig(config);
         }
         catch (err) {
-            logger.warn(`[api] Config save failed: ${err instanceof Error ? err.message : err}`);
+            configSaveWarning = `Config save failed: ${String(err)}`;
+            logger.warn(`[api] ${configSaveWarning}`);
+        }
+        const envKey = chain === "evm" ? "WALLET_SOURCE_EVM" : "WALLET_SOURCE_SOLANA";
+        try {
+            await persistConfigEnv(envKey, source);
         }
-        json(res, { ok: true });
-        ctx.scheduleRuntimeRestart?.("Wallet configuration updated");
+        catch (err) {
+            error(res, `Failed to persist ${envKey}: ${String(err)}`, 500);
+            return true;
+        }
+        const restarted = previousPrimary === source
+            ? false
+            : await triggerWalletRuntimeReload(ctx, "primary-changed");
+        json(res, {
+            ok: true,
+            chain,
+            source,
+            restarting: restarted,
+            ...(configSaveWarning ? { warnings: [configSaveWarning] } : {}),
+        });
         return true;
     }
-    // POST /api/wallet/export
-    if (method === "POST" && pathname === "/api/wallet/export") {
+    // POST /api/wallet/refresh-cloud — flag-gated.
+    // Re-queries the Eliza Cloud bridge for per-chain wallet descriptors and
+    // refreshes `config.wallet.cloud.*`. Provision is best-effort so one bad
+    // chain does not discard the other imported wallet(s). This is a refresh
+    // operation, so we re-fetch all chains to pick up any upstream changes
+    // (address rotation, migration, etc.), not just new chains.
+    if (method === "POST" && pathname === "/api/wallet/refresh-cloud") {
+        if (!isCloudWalletEnabled()) {
+            error(res, "Not found", 404);
+            return true;
+        }
+        const cloud = config.cloud;
+        const apiKey = resolveCloudApiKey(config, ctx.runtime) ?? "";
+        const baseUrl = cloud?.baseUrl
+            ? normalizeCloudSiteUrl(cloud.baseUrl)
+            : "https://www.elizacloud.ai";
+        if (!apiKey) {
+            error(res, "Cloud not linked — sign in to Eliza Cloud first", 400);
+            return true;
+        }
+        const agentEntry = config.agents?.list?.[0];
+        const agentId = agentEntry?.id ??
+            ctx.runtime?.agentId ??
+            null;
+        if (!agentId) {
+            error(res, "No agent configured", 400);
+            return true;
+        }
+        try {
+            const { address: clientAddress } = await getOrCreateClientAddressKey();
+            const bridge = new ElizaCloudClient(baseUrl, apiKey);
+            const cachedDescriptors = readCachedCloudWalletDescriptors(config);
+            const chainsToProvision = ["evm", "solana"].filter((chain) => !cachedDescriptors[chain]);
+            const descriptors = { ...cachedDescriptors };
+            const warnings = [];
+            const previousPrimary = readPrimaryMap(config);
+            const previousEvmAddress = readCloudWalletAddress(cachedDescriptors.evm);
+            const previousSolanaAddress = readCloudWalletAddress(cachedDescriptors.solana);
+            if (chainsToProvision.length > 0) {
+                const provisionResult = await provisionCloudWalletsBestEffort(bridge, {
+                    agentId,
+                    clientAddress,
+                    chains: chainsToProvision,
+                });
+                Object.assign(descriptors, provisionResult.descriptors);
+                for (const [index, failure] of provisionResult.failures.entries()) {
+                    const cached = cachedDescriptors[failure.chain];
+                    if (cached) {
+                        descriptors[failure.chain] = cached;
+                        const detail = failure.error instanceof Error
+                            ? failure.error.message
+                            : String(failure.error);
+                        warnings.push(`Reused cached ${failure.chain} cloud wallet after refresh failed: ${detail}`);
+                        continue;
+                    }
+                    warnings.push(provisionResult.warnings[index] ??
+                        `Cloud ${failure.chain} wallet import failed`);
+                }
+            }
+            if (!descriptors.evm && !descriptors.solana) {
+                throw new Error(warnings[0] ?? "Failed to provision any cloud wallet descriptors");
+            }
+            persistCloudWalletCache(config, descriptors);
+            process.env.ENABLE_CLOUD_WALLET = "1";
+            await persistConfigEnv("ENABLE_CLOUD_WALLET", "1");
+            const cloudConfig = { ...(cloud ?? {}) };
+            cloudConfig.clientAddressPublicKey = clientAddress;
+            config.cloud = cloudConfig;
+            if (descriptors.evm?.walletAddress) {
+                process.env.ELIZA_CLOUD_EVM_ADDRESS = descriptors.evm.walletAddress;
+                await persistConfigEnv("ELIZA_CLOUD_EVM_ADDRESS", descriptors.evm.walletAddress);
+                process.env.ENABLE_EVM_PLUGIN = "1";
+                await persistConfigEnv("ENABLE_EVM_PLUGIN", "1");
+                process.env.WALLET_SOURCE_EVM = "cloud";
+                await persistConfigEnv("WALLET_SOURCE_EVM", "cloud");
+                persistPrimarySelection(config, "evm", "cloud");
+            }
+            if (descriptors.solana?.walletAddress) {
+                process.env.ELIZA_CLOUD_SOLANA_ADDRESS =
+                    descriptors.solana.walletAddress;
+                await persistConfigEnv("ELIZA_CLOUD_SOLANA_ADDRESS", descriptors.solana.walletAddress);
+                process.env.WALLET_SOURCE_SOLANA = "cloud";
+                await persistConfigEnv("WALLET_SOURCE_SOLANA", "cloud");
+                persistPrimarySelection(config, "solana", "cloud");
+            }
+            let configSaveWarning;
+            try {
+                saveConfig(config);
+            }
+            catch (err) {
+                configSaveWarning = `Config save failed: ${String(err)}`;
+                logger.warn(`[api] ${configSaveWarning}`);
+            }
+            const responseWarnings = [...warnings];
+            if (configSaveWarning) {
+                responseWarnings.push(configSaveWarning);
+            }
+            const nextPrimary = readPrimaryMap(config);
+            const nextEvmAddress = descriptors.evm?.walletAddress ?? null;
+            const nextSolanaAddress = descriptors.solana?.walletAddress ?? null;
+            const walletBindingChanged = previousPrimary.evm !== nextPrimary.evm ||
+                previousPrimary.solana !== nextPrimary.solana ||
+                previousEvmAddress !== nextEvmAddress ||
+                previousSolanaAddress !== nextSolanaAddress;
+            const restarted = walletBindingChanged
+                ? await triggerWalletRuntimeReload(ctx, "cloud-refreshed")
+                : false;
+            json(res, {
+                ok: true,
+                restarting: restarted,
+                wallets: {
+                    evm: descriptors.evm
+                        ? {
+                            address: descriptors.evm.walletAddress,
+                            provider: descriptors.evm.walletProvider,
+                        }
+                        : null,
+                    solana: descriptors.solana
+                        ? {
+                            address: descriptors.solana.walletAddress,
+                            provider: descriptors.solana.walletProvider,
+                        }
+                        : null,
+                },
+                ...(responseWarnings.length > 0 ? { warnings: responseWarnings } : {}),
+            });
+        }
+        catch (err) {
+            logger.warn(`[api] cloud wallet refresh failed: ${String(err)}`);
+            error(res, `Cloud wallet refresh failed: ${String(err)}`, 502);
+        }
+        return true;
+    }
+    // PUT /api/wallet/config
+    if (method === "PUT" && pathname === "/api/wallet/config") {
         const body = await readJsonBody(req, res);
         if (!body)
             return true;
-        const rejection = resolveWalletExportRejection(req, body);
-        if (rejection) {
-            error(res, rejection.reason, rejection.status);
+        const updateRequest = resolveWalletConfigUpdateRequest(body, getStoredWalletRpcSelections(config));
+        if (!updateRequest) {
+            error(res, "Invalid wallet config update");
             return true;
         }
-        const evmKey = process.env.EVM_PRIVATE_KEY ?? null;
-        const solanaKey = process.env.SOLANA_PRIVATE_KEY ?? null;
-        const addresses = deps.getWalletAddresses();
-        logger.warn("[wallet] Private keys exported via API");
+        applyWalletRpcConfigUpdate(config, updateRequest);
+        const selectedProviders = normalizeWalletRpcSelections(updateRequest.selections);
+        const shouldEnableCloudWallet = Object.values(selectedProviders).every((provider) => provider === "eliza-cloud");
+        if (shouldEnableCloudWallet) {
+            process.env.ENABLE_CLOUD_WALLET = "1";
+            try {
+                await persistConfigEnv("ENABLE_CLOUD_WALLET", "1");
+            }
+            catch (err) {
+                error(res, `Failed to persist ENABLE_CLOUD_WALLET: ${String(err)}`, 500);
+                return true;
+            }
+        }
+        let configSaveWarning;
+        try {
+            saveConfig(config);
+        }
+        catch (err) {
+            const msg = `Config save failed: ${String(err)}`;
+            logger.warn(`[api] ${msg}`);
+            configSaveWarning = msg;
+        }
         json(res, {
-            evm: evmKey
-                ? { privateKey: evmKey, address: addresses.evmAddress }
-                : null,
-            solana: solanaKey
-                ? { privateKey: solanaKey, address: addresses.solanaAddress }
-                : null,
+            ok: true,
+            ...(configSaveWarning ? { warnings: [configSaveWarning] } : {}),
         });
         return true;
     }
+    // GET /api/wallet/approvals/stream — SSE stub until Steward approval wiring lands.
+    if (method === "GET" && pathname === "/api/wallet/approvals/stream") {
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache, no-transform");
+        res.setHeader("Connection", "keep-alive");
+        res.setHeader("X-Accel-Buffering", "no");
+        const writeSse = (event, data) => {
+            res.write(`event: ${event}\n`);
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        };
+        writeSse("wallet_approvals", {
+            ok: true,
+            approvals: [],
+            note: "Approval stream placeholder — connect Steward decision bridge when available.",
+        });
+        const ping = setInterval(() => {
+            try {
+                writeSse("ping", { t: Date.now() });
+            }
+            catch {
+                clearInterval(ping);
+            }
+        }, 15_000);
+        req.on("close", () => {
+            clearInterval(ping);
+            try {
+                res.end();
+            }
+            catch {
+                /* ignore */
+            }
+        });
+        return true;
+    }
+    const approvalDecision = /^\/api\/wallet\/approvals\/([^/]+)\/decision$/.exec(pathname);
+    if (method === "POST" && approvalDecision) {
+        error(res, "Wallet approval decisions are not wired to Steward in this build.", 501);
+        return true;
+    }
+    // POST /api/wallet/export — removed (no plaintext key export from the agent API).
+    if (method === "POST" && pathname === "/api/wallet/export") {
+        error(res, "Private key export has been removed. Use Steward or OS-backed custody flows.", 410);
+        return true;
+    }
     return false;
 }