@elizaos/plugin-elizacloud 2.0.0-alpha.7 → 2.0.0-beta.1

package/src/cloud/cloud-manager.ts

@@ -0,0 +1,163 @@
+/**
+ * Top-level orchestrator for cloud integration.
+ * Manages client, proxy, backup scheduler, and connection monitor lifecycle.
+ */
+
+import { logger } from "@elizaos/core";
+import type { CloudConfig } from "../lib/config-like.js";
+import { BackupScheduler } from "./backup.js";
+import { normalizeCloudSiteUrl } from "./base-url.js";
+import { ElizaCloudClient } from "./bridge-client.js";
+import { CloudRuntimeProxy } from "./cloud-proxy.js";
+import { ConnectionMonitor } from "./reconnect.js";
+import { validateCloudBaseUrl } from "./validate-url.js";
+
+export type CloudConnectionStatus =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "error";
+
+export interface CloudManagerCallbacks {
+  onStatusChange?: (status: CloudConnectionStatus) => void;
+}
+
+export class CloudManager {
+  private client: ElizaCloudClient | null = null;
+  private proxy: CloudRuntimeProxy | null = null;
+  private backupScheduler: BackupScheduler | null = null;
+  private connectionMonitor: ConnectionMonitor | null = null;
+  private status: CloudConnectionStatus = "disconnected";
+  private activeAgentId: string | null = null;
+
+  constructor(
+    private cloudConfig: CloudConfig,
+    private callbacks: CloudManagerCallbacks = {},
+  ) {}
+
+  async init(): Promise<void> {
+    const rawUrl = normalizeCloudSiteUrl(this.cloudConfig.baseUrl);
+    const apiKey = this.cloudConfig.apiKey;
+    if (!apiKey)
+      throw new Error(
+        "Cloud API key is not configured. Run cloud login first.",
+      );
+
+    const urlError = await validateCloudBaseUrl(rawUrl);
+    if (urlError) {
+      throw new Error(urlError);
+    }
+
+    // rawUrl is already normalized above — don't re-normalize, which would
+    // re-read ELIZAOS_CLOUD_BASE_URL and could produce a different URL than
+    // the one we just validated.
+    this.client = new ElizaCloudClient(rawUrl, apiKey);
+    logger.info(`[cloud-manager] Client initialised (baseUrl=${rawUrl})`);
+  }
+
+  async connect(agentId: string): Promise<CloudRuntimeProxy> {
+    if (!this.client) await this.init();
+    if (!this.client) throw new Error("Cloud client failed to initialise");
+
+    this.setStatus("connecting");
+    this.activeAgentId = agentId;
+
+    try {
+      await this.client.provision(agentId);
+      const agent = await this.client.getAgent(agentId);
+
+      this.proxy = new CloudRuntimeProxy(this.client, agentId, agent.agentName);
+
+      this.backupScheduler = new BackupScheduler(
+        this.client,
+        agentId,
+        this.cloudConfig.backup?.autoBackupIntervalMs ?? 60_000,
+      );
+      this.backupScheduler.start();
+
+      this.connectionMonitor = new ConnectionMonitor(
+        this.client,
+        agentId,
+        {
+          onDisconnect: () => this.setStatus("reconnecting"),
+          onReconnect: () => this.setStatus("connected"),
+          onStatusChange: (s) => {
+            if (s === "connected") this.setStatus("connected");
+            else if (s === "reconnecting") this.setStatus("reconnecting");
+            else this.setStatus("error");
+          },
+        },
+        this.cloudConfig.bridge?.heartbeatIntervalMs ?? 30_000,
+      );
+      this.connectionMonitor.start();
+
+      this.setStatus("connected");
+      logger.info(
+        `[cloud-manager] Connected to cloud agent (agentId=${agentId}, agentName=${agent.agentName})`,
+      );
+      return this.proxy;
+    } catch (err) {
+      this.setStatus("error");
+      if (this.backupScheduler) {
+        this.backupScheduler.stop();
+        this.backupScheduler = null;
+      }
+      if (this.connectionMonitor) {
+        this.connectionMonitor.stop();
+        this.connectionMonitor = null;
+      }
+      this.proxy = null;
+      this.activeAgentId = null;
+      this.setStatus("disconnected");
+      throw err;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.backupScheduler) {
+      await this.backupScheduler.finalSnapshot();
+      this.backupScheduler.stop();
+      this.backupScheduler = null;
+    }
+    if (this.connectionMonitor) {
+      this.connectionMonitor.stop();
+      this.connectionMonitor = null;
+    }
+    this.proxy = null;
+    this.activeAgentId = null;
+    this.setStatus("disconnected");
+  }
+
+  async replaceApiKey(apiKey: string): Promise<void> {
+    await this.disconnect();
+    this.cloudConfig = {
+      ...this.cloudConfig,
+      apiKey,
+    };
+    this.client = null;
+    await this.init();
+  }
+
+  getProxy(): CloudRuntimeProxy | null {
+    return this.proxy;
+  }
+  getClient(): ElizaCloudClient | null {
+    return this.client;
+  }
+  getActiveAgentId(): string | null {
+    return this.activeAgentId;
+  }
+  getStatus(): CloudConnectionStatus {
+    return this.status;
+  }
+  isEnabled(): boolean {
+    return Boolean(this.cloudConfig.enabled && this.cloudConfig.apiKey);
+  }
+
+  private setStatus(status: CloudConnectionStatus): void {
+    if (this.status === status) return;
+    this.status = status;
+    this.callbacks.onStatusChange?.(status);
+  }
+}

package/src/cloud/cloud-proxy.ts

@@ -0,0 +1,52 @@
+/**
+ * Drop-in replacement for a local AgentRuntime when running in cloud mode.
+ * Routes chat/status calls through the ElizaCloudClient to the remote sandbox.
+ */
+
+import type { ChatChannelType, ElizaCloudClient } from "./bridge-client.js";
+
+export class CloudRuntimeProxy {
+  constructor(
+    private client: ElizaCloudClient,
+    private agentId: string,
+    private _agentName: string,
+  ) {}
+
+  get agentName(): string {
+    return this._agentName;
+  }
+
+  async handleChatMessage(
+    text: string,
+    roomId = "web-chat",
+    channelType: ChatChannelType = "DM",
+  ): Promise<string> {
+    return this.client.sendMessage(this.agentId, text, roomId, channelType);
+  }
+
+  async *handleChatMessageStream(
+    text: string,
+    roomId = "web-chat",
+    channelType: ChatChannelType = "DM",
+  ): AsyncGenerator<string> {
+    for await (const event of this.client.sendMessageStream(
+      this.agentId,
+      text,
+      roomId,
+      channelType,
+    )) {
+      if (event.type === "chunk" && typeof event.data.text === "string") {
+        yield event.data.text;
+      }
+    }
+  }
+
+  async getStatus(): Promise<{ state: string; agentName: string }> {
+    const agent = await this.client.getAgent(this.agentId);
+    return { state: agent.status, agentName: agent.agentName };
+  }
+
+  async isAlive(): Promise<boolean> {
+    return this.client.heartbeat(this.agentId).catch(() => false);
+  }
+}

package/src/cloud/cloud-wallet.ts

@@ -0,0 +1,341 @@
+/**
+ * Cloud wallet provisioning + client-address key management.
+ *
+ * Gated by ENABLE_CLOUD_WALLET. Every export short-circuits when the flag
+ * is off so no cloud code paths run in legacy builds.
+ *
+ * Responsibilities:
+ *   1. Generate + persist ELIZA_CLOUD_CLIENT_ADDRESS_KEY (the local secp256k1
+ *      key whose address ties this install to cloud-custodied wallets).
+ *   2. Provision EVM + Solana cloud wallets for an agent, guarded by a
+ *      single-flight mutex keyed on (agentId, chainType) to prevent duplicate
+ *      provision under concurrent cloud-login triggers.
+ *   3. Write the resulting descriptors into the in-memory config under
+ *      wallet.cloud.{evm,solana}; caller persists via saveConfig().
+ */
+
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import type {
+  CloudBridgeError,
+  CloudChainType,
+  CloudWalletDescriptor,
+  CloudWalletProvider,
+} from "./bridge-client.js";
+import { persistConfigEnv } from "../lib/config-env";
+import { isCloudWalletEnabled } from "../lib/feature-flags";
+
+export const ELIZA_CLOUD_CLIENT_ADDRESS_KEY_ENV =
+  "ELIZA_CLOUD_CLIENT_ADDRESS_KEY";
+
+export class CloudWalletFlagDisabledError extends Error {
+  constructor() {
+    super("ENABLE_CLOUD_WALLET is off; cloud wallet code paths are inactive");
+    this.name = "CloudWalletFlagDisabledError";
+  }
+}
+
+function ensureFlag(): void {
+  if (!isCloudWalletEnabled()) {
+    throw new CloudWalletFlagDisabledError();
+  }
+}
+
+/**
+ * Normalize a hex private key to the 0x-prefixed form viem expects.
+ */
+function normalizePrivateKey(raw: string): `0x${string}` {
+  const trimmed = raw.trim();
+  const hex = trimmed.startsWith("0x") ? trimmed.slice(2) : trimmed;
+  if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
+    throw new Error(
+      `Malformed ${ELIZA_CLOUD_CLIENT_ADDRESS_KEY_ENV}: expected 32-byte hex`,
+    );
+  }
+  return `0x${hex.toLowerCase()}`;
+}
+
+export interface GetOrCreateKeyOptions {
+  /** Override state dir for config.env persistence. Used by tests. */
+  stateDir?: string;
+}
+
+export interface CloudWalletProvisionBridge {
+  getAgentWallet(
+    agentId: string,
+    chain: CloudChainType,
+  ): Promise<CloudWalletDescriptor>;
+  provisionWallet(input: {
+    chainType: CloudChainType;
+    clientAddress: string;
+  }): Promise<{
+    walletId: string;
+    address: string;
+    chainType: CloudChainType;
+    provider: CloudWalletProvider;
+  }>;
+}
+
+/**
+ * Read or mint the local client-address secp256k1 key.
+ *
+ * Priority:
+ *   1. process.env[ELIZA_CLOUD_CLIENT_ADDRESS_KEY] — respected as-is.
+ *   2. Generate a fresh key, write to `process.env` AND disk (`config.env`)
+ *      so it survives restart.
+ *
+ * The key is in `BLOCKED_STARTUP_ENV_KEYS` so it never syncs into
+ * `eliza.json` — `config.env` is the designated disk home for it.
+ */
+export async function getOrCreateClientAddressKey(
+  opts: GetOrCreateKeyOptions = {},
+): Promise<{
+  privateKey: `0x${string}`;
+  address: `0x${string}`;
+  minted: boolean;
+}> {
+  ensureFlag();
+
+  const existing = process.env[ELIZA_CLOUD_CLIENT_ADDRESS_KEY_ENV];
+  if (existing && existing.trim().length > 0) {
+    const privateKey = normalizePrivateKey(existing);
+    const account = privateKeyToAccount(privateKey);
+    return { privateKey, address: account.address, minted: false };
+  }
+
+  const privateKey = generatePrivateKey();
+  const account = privateKeyToAccount(privateKey);
+
+  process.env[ELIZA_CLOUD_CLIENT_ADDRESS_KEY_ENV] = privateKey;
+  await persistConfigEnv(ELIZA_CLOUD_CLIENT_ADDRESS_KEY_ENV, privateKey, {
+    stateDir: opts.stateDir,
+  });
+
+  return { privateKey, address: account.address, minted: true };
+}
+
+// ---------------------------------------------------------------------------
+// Single-flight provisioning
+// ---------------------------------------------------------------------------
+
+const inflight = new Map<string, Promise<CloudWalletDescriptor>>();
+
+function inflightKey(agentId: string, chain: CloudChainType): string {
+  return `${agentId}::${chain}`;
+}
+
+async function provisionOne(
+  bridge: CloudWalletProvisionBridge,
+  agentId: string,
+  chain: CloudChainType,
+  clientAddress: string,
+): Promise<CloudWalletDescriptor> {
+  try {
+    return await bridge.getAgentWallet(agentId, chain);
+  } catch (error) {
+    if (!isMissingCloudWalletError(error, chain)) {
+      throw error;
+    }
+  }
+
+  const provisioned = await bridge.provisionWallet({
+    chainType: chain,
+    clientAddress,
+  });
+
+  return {
+    agentWalletId: provisioned.walletId,
+    walletAddress: provisioned.address,
+    walletProvider: provisioned.provider,
+    chainType: chain,
+  };
+}
+
+function isMissingCloudWalletError(
+  error: unknown,
+  chain: CloudChainType,
+): boolean {
+  if (
+    error instanceof Error &&
+    new RegExp(`no cloud ${chain} wallet provisioned`, "i").test(error.message)
+  ) {
+    return true;
+  }
+
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    error.name === "CloudBridgeError" &&
+    typeof (error as CloudBridgeError).status === "number" &&
+    (error as CloudBridgeError).status === 404
+  );
+}
+
+export interface ProvisionOptions {
+  agentId: string;
+  clientAddress: string;
+  chains?: CloudChainType[];
+}
+
+export interface CloudWalletDescriptors {
+  evm: CloudWalletDescriptor;
+  solana: CloudWalletDescriptor;
+}
+
+export interface CloudWalletProvisionFailure {
+  chain: CloudChainType;
+  error: unknown;
+}
+
+export interface CloudWalletProvisionResult {
+  descriptors: Partial<CloudWalletDescriptors>;
+  failures: CloudWalletProvisionFailure[];
+  warnings: string[];
+}
+
+function formatProvisionWarning(chain: CloudChainType, error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return `Cloud ${chain} wallet import failed: ${message}`;
+}
+
+/**
+ * Provision EVM + Solana cloud wallets idempotently.
+ *
+ * Concurrent callers for the same (agentId, chain) share a single in-flight
+ * promise so we never send duplicate provision requests.
+ */
+export async function provisionCloudWalletsBestEffort(
+  bridge: CloudWalletProvisionBridge,
+  opts: ProvisionOptions,
+): Promise<CloudWalletProvisionResult> {
+  ensureFlag();
+
+  const chains: CloudChainType[] = opts.chains ?? ["evm", "solana"];
+
+  const results = await Promise.all(
+    chains.map((chain) => {
+      const key = inflightKey(opts.agentId, chain);
+      const pending = inflight.get(key);
+      if (pending) {
+        return pending.then(
+          (descriptor) =>
+            ({
+              chain,
+              ok: true as const,
+              descriptor,
+            }) as const,
+          (error) =>
+            ({
+              chain,
+              ok: false as const,
+              error,
+            }) as const,
+        );
+      }
+
+      const p = provisionOne(
+        bridge,
+        opts.agentId,
+        chain,
+        opts.clientAddress,
+      ).finally(() => {
+        inflight.delete(key);
+      });
+      inflight.set(key, p);
+      return p.then(
+        (descriptor) =>
+          ({
+            chain,
+            ok: true as const,
+            descriptor,
+          }) as const,
+        (error) =>
+          ({
+            chain,
+            ok: false as const,
+            error,
+          }) as const,
+      );
+    }),
+  );
+
+  const out: Partial<CloudWalletDescriptors> = {};
+  const failures: CloudWalletProvisionFailure[] = [];
+  for (const result of results) {
+    if ("descriptor" in result) {
+      out[result.chain] = result.descriptor;
+      continue;
+    }
+    failures.push({ chain: result.chain, error: result.error });
+  }
+
+  return {
+    descriptors: out,
+    failures,
+    warnings: failures.map(({ chain, error }) =>
+      formatProvisionWarning(chain, error),
+    ),
+  };
+}
+
+export async function provisionCloudWallets(
+  bridge: CloudWalletProvisionBridge,
+  opts: ProvisionOptions,
+): Promise<Partial<CloudWalletDescriptors>> {
+  const result = await provisionCloudWalletsBestEffort(bridge, opts);
+  if (
+    result.failures.length > 0 &&
+    Object.keys(result.descriptors).length === 0
+  ) {
+    const firstFailure = result.failures[0];
+    if (firstFailure?.error instanceof Error) {
+      throw firstFailure.error;
+    }
+    throw new Error(result.warnings[0] ?? "Failed to provision cloud wallets");
+  }
+
+  return result.descriptors;
+}
+
+// ---------------------------------------------------------------------------
+// Config cache write
+// ---------------------------------------------------------------------------
+
+export interface CloudWalletCacheTarget {
+  wallet?: {
+    cloud?: Partial<Record<CloudChainType, CloudWalletDescriptor>>;
+    [k: string]: unknown;
+  };
+  [k: string]: unknown;
+}
+
+/**
+ * Write the descriptors into the provided config object under
+ * `wallet.cloud.{evm,solana}`. Caller is responsible for persisting
+ * (state.saveConfig()).
+ */
+export function persistCloudWalletCache(
+  config: CloudWalletCacheTarget,
+  descriptors: Partial<CloudWalletDescriptors>,
+): void {
+  ensureFlag();
+
+  const wallet = (config.wallet ?? {}) as NonNullable<
+    CloudWalletCacheTarget["wallet"]
+  >;
+  const cloud = { ...(wallet.cloud ?? {}) };
+  if (descriptors.evm) cloud.evm = descriptors.evm;
+  if (descriptors.solana) cloud.solana = descriptors.solana;
+  wallet.cloud = cloud;
+  config.wallet = wallet;
+}
+
+// ---------------------------------------------------------------------------
+// Test hooks
+// ---------------------------------------------------------------------------
+
+/** @internal — exposed for tests to reset state between cases. */
+export function __resetCloudWalletModuleForTests(): void {
+  inflight.clear();
+  delete process.env[ELIZA_CLOUD_CLIENT_ADDRESS_KEY_ENV];
+}

package/src/cloud/index.ts

@@ -0,0 +1,28 @@
+export {
+  type CloudLoginOptions,
+  type CloudLoginResult,
+  cloudLogin,
+} from "./auth.js";
+export { BackupScheduler } from "./backup.js";
+export {
+  normalizeCloudSiteUrl,
+  resolveCloudApiBaseUrl,
+} from "./base-url.js";
+export {
+  type BackupInfo,
+  type CloudAgent,
+  type CloudAgentCreateParams,
+  ElizaCloudClient,
+  type ProvisionInfo,
+} from "./bridge-client.js";
+export {
+  type CloudConnectionStatus,
+  CloudManager,
+  type CloudManagerCallbacks,
+} from "./cloud-manager.js";
+export { CloudRuntimeProxy } from "./cloud-proxy.js";
+export {
+  ConnectionMonitor,
+  type ConnectionMonitorCallbacks,
+} from "./reconnect.js";
+export { validateCloudBaseUrl } from "./validate-url.js";

package/src/cloud/reconnect.ts

@@ -0,0 +1,111 @@
+/**
+ * Heartbeat monitor with auto-reconnect via exponential backoff.
+ */
+
+import { logger } from "@elizaos/core";
+import type { ElizaCloudClient } from "./bridge-client.js";
+
+export interface ConnectionMonitorCallbacks {
+  onDisconnect: () => void;
+  onReconnect: () => void;
+  onStatusChange?: (
+    status: "connected" | "reconnecting" | "disconnected",
+  ) => void;
+}
+
+export class ConnectionMonitor {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private consecutiveFailures = 0;
+  private reconnecting = false;
+
+  constructor(
+    private client: ElizaCloudClient,
+    private agentId: string,
+    private callbacks: ConnectionMonitorCallbacks,
+    private heartbeatIntervalMs: number = 30_000,
+    private maxFailures: number = 3,
+  ) {}
+
+  start(): void {
+    if (this.timer) return;
+    logger.info(
+      `[cloud-monitor] Starting connection monitor (interval: ${this.heartbeatIntervalMs}ms, maxFailures: ${this.maxFailures})`,
+    );
+    this.consecutiveFailures = 0;
+    this.timer = setInterval(() => {
+      this.tick();
+    }, this.heartbeatIntervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.consecutiveFailures = 0;
+    this.reconnecting = false;
+    logger.info("[cloud-monitor] Connection monitor stopped");
+  }
+
+  isMonitoring(): boolean {
+    return this.timer !== null;
+  }
+
+  private async tick(): Promise<void> {
+    if (this.reconnecting) return;
+
+    const alive = await this.client.heartbeat(this.agentId).catch(() => false);
+
+    if (alive) {
+      if (this.consecutiveFailures > 0) {
+        this.consecutiveFailures = 0;
+        this.callbacks.onStatusChange?.("connected");
+      }
+      return;
+    }
+
+    this.consecutiveFailures++;
+    logger.warn(
+      `[cloud-monitor] Heartbeat failed (${this.consecutiveFailures}/${this.maxFailures})`,
+    );
+
+    if (this.consecutiveFailures >= this.maxFailures) {
+      // Don't emit "disconnected" here — attemptReconnect() will emit
+      // "reconnecting" first, and only emits "disconnected" if all
+      // retry attempts fail. This avoids a misleading disconnected→
+      // reconnecting flicker for callers.
+      this.callbacks.onDisconnect();
+      await this.attemptReconnect();
+    }
+  }
+
+  private async attemptReconnect(): Promise<void> {
+    this.reconnecting = true;
+    this.callbacks.onStatusChange?.("reconnecting");
+
+    let delay = 3_000;
+    for (let attempt = 1; attempt <= 10; attempt++) {
+      logger.info(`[cloud-monitor] Reconnect attempt ${attempt}/10...`);
+      const ok = await this.client
+        .provision(this.agentId)
+        .then(() => true)
+        .catch(() => false);
+
+      if (ok) {
+        logger.info("[cloud-monitor] Reconnection successful");
+        this.consecutiveFailures = 0;
+        this.reconnecting = false;
+        this.callbacks.onStatusChange?.("connected");
+        this.callbacks.onReconnect();
+        return;
+      }
+
+      await new Promise((r) => setTimeout(r, delay));
+      delay = Math.min(delay * 2, 60_000);
+    }
+
+    logger.error("[cloud-monitor] Failed to reconnect after 10 attempts");
+    this.reconnecting = false;
+    this.callbacks.onStatusChange?.("disconnected");
+  }
+}