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

package/src/cloud/clack-observer.ts

@@ -0,0 +1,189 @@
+/**
+ * `@clack/prompts`-backed implementation of `CloudSetupObserver`.
+ *
+ * Used by the CLI first-time-setup flow. Wraps a lazily-loaded clack module
+ * (so packaged desktop builds that never run interactive setup don't
+ * pay the dep cost) and renders every observer event as a spinner update,
+ * `log.info` / `log.warn`, or `confirm` / `select` prompt.
+ *
+ * @module cloud/clack-observer
+ */
+import { logger } from "@elizaos/core";
+import type {
+  CloudSetupObserver,
+  ConfirmPrompt,
+  ProvisionSuccessInfo,
+  SelectChoicePrompt,
+} from "./setup-observer.js";
+
+/** Lazy-loaded @clack/prompts module type. */
+type ClackModule = typeof import("@clack/prompts");
+
+interface ClackSpinner {
+  start(message?: string): void;
+  stop(message?: string): void;
+  message(message?: string): void;
+}
+
+/**
+ * Observer that drives a clack CLI session. One instance per setup run
+ * — internal spinner state is reused across the auth + provisioning phases
+ * so we don't stack overlapping spinners.
+ */
+export class ClackObserver implements CloudSetupObserver {
+  private spinner: ClackSpinner | null = null;
+
+  constructor(private readonly clack: ClackModule) {}
+
+  // ── Spinner helpers ──────────────────────────────────────────────────
+  private ensureSpinner(): ClackSpinner {
+    if (!this.spinner) {
+      this.spinner = this.clack.spinner();
+    }
+    return this.spinner;
+  }
+
+  private stopSpinner(message: string): void {
+    if (this.spinner) {
+      this.spinner.stop(message);
+      this.spinner = null;
+    } else {
+      // No active spinner — render the line as a log.info so the
+      // message isn't lost.
+      this.clack.log.info(message);
+    }
+  }
+
+  // ── Availability ─────────────────────────────────────────────────────
+  onAvailabilityChecked(result: { ok: boolean; reason?: string }): void {
+    if (!result.ok && result.reason) {
+      this.clack.log.warn(result.reason);
+    }
+  }
+
+  // ── Auth ─────────────────────────────────────────────────────────────
+  onAuthStart(loginUrl: string): void {
+    const spinner = this.ensureSpinner();
+    spinner.start("Connecting to Eliza Cloud...");
+    // The auth flow's first callback fires when we have the login URL.
+    spinner.stop("Opening your browser to log in...");
+    this.spinner = null;
+    this.clack.log.info(`If the browser didn't open, visit:\n  ${loginUrl}`);
+    const polling = this.ensureSpinner();
+    polling.start("Waiting for login in browser...");
+  }
+
+  onAuthBrowserOpenFailed(loginUrl: string, error: Error): void {
+    // Previously swallowed at debug-level. Now visible: the user may have
+    // missed the URL printed by onAuthStart, so re-emit it here with the
+    // explicit "couldn't open browser" framing.
+    this.clack.log.warn(
+      `Could not open browser automatically (${error.message}). Visit this URL to continue:\n  ${loginUrl}`,
+    );
+  }
+
+  onAuthPollStatus(status: string): void {
+    if (status === "pending") {
+      this.ensureSpinner().message("Waiting for login in browser...");
+    }
+  }
+
+  onAuthSuccess(): void {
+    this.stopSpinner("✓ Logged in to Eliza Cloud!");
+  }
+
+  onAuthFailure(message: string): void {
+    this.stopSpinner(message);
+  }
+
+  // ── Provisioning ─────────────────────────────────────────────────────
+  onProvisionStart(_agentName: string): void {
+    const spinner = this.ensureSpinner();
+    spinner.start("Creating your cloud agent...");
+  }
+
+  onProvisionStatus(status: string): void {
+    const spinner = this.ensureSpinner();
+    switch (status) {
+      case "created":
+        spinner.message("Agent created! Provisioning cloud environment...");
+        break;
+      case "queued":
+        spinner.message("Queued — waiting for available slot...");
+        break;
+      case "provisioning":
+        spinner.message("Provisioning cloud environment...");
+        break;
+      default:
+        spinner.message(`Status: ${status}...`);
+    }
+  }
+
+  onProvisionTimeout(_agentId: string, lastStatus: string): void {
+    this.stopSpinner(
+      `Provisioning timed out (last status: ${lastStatus}). The agent may still be starting up.`,
+    );
+  }
+
+  onProvisionFailure(reason: string): void {
+    this.stopSpinner(reason);
+  }
+
+  onProvisionSuccess(result: ProvisionSuccessInfo): void {
+    this.stopSpinner(`☁️  Cloud agent "${result.agentId}" is running!`);
+  }
+
+  // ── Generic ──────────────────────────────────────────────────────────
+  onNotice(message: string): void {
+    this.clack.log.warn(message);
+  }
+
+  onFatalError(error: Error, context: string): void {
+    logger.error(`[cloud-setup] ${context}: ${error.message}`);
+    this.clack.log.error(`${context}: ${error.message}`);
+  }
+
+  // ── Prompts ──────────────────────────────────────────────────────────
+  async confirm(prompt: ConfirmPrompt): Promise<boolean | null> {
+    const args: {
+      message: string;
+      initialValue?: boolean;
+      active?: string;
+      inactive?: string;
+    } = { message: prompt.message };
+
+    if (prompt.defaultValue !== undefined) args.initialValue = prompt.defaultValue;
+    if (prompt.activeLabel !== undefined) args.active = prompt.activeLabel;
+    if (prompt.inactiveLabel !== undefined) args.inactive = prompt.inactiveLabel;
+
+    const result = await this.clack.confirm(args);
+    if (this.clack.isCancel(result)) return null;
+    return result;
+  }
+
+  async selectChoice<T extends string>(
+    prompt: SelectChoicePrompt<T>,
+  ): Promise<T | null> {
+    // Clack's `Option<Value>` is a conditional type that for `Value extends
+    // Primitive` makes `label` optional. TS can't narrow the conditional
+    // for an unresolved generic `T extends string`, so we describe the
+    // option shape via Parameters of clack's `select` and let inference
+    // pick it up. No `as unknown as` escape — the parameter type IS the
+    // right type, we just have to address it positionally.
+    type SelectOpts = Parameters<typeof this.clack.select<T>>[0];
+    const options = prompt.options.map((option) => {
+      const out = {
+        label: option.label,
+        value: option.value,
+        ...(option.hint !== undefined ? { hint: option.hint } : {}),
+      };
+      return out;
+    }) as SelectOpts["options"];
+    const result = await this.clack.select<T>({
+      message: prompt.message,
+      options,
+    });
+    if (this.clack.isCancel(result)) return null;
+    return result;
+  }
+}

package/src/cloud/cloud-api-key.ts

@@ -0,0 +1,80 @@
+/**
+ * Cloud API key + base URL resolution.
+ *
+ * Resolves the Eliza Cloud API key and base URL from (in priority order):
+ *   1. Explicit `config.cloud.apiKey` / `config.cloud.baseUrl`
+ *   2. Runtime settings + character secrets (`ELIZAOS_CLOUD_API_KEY`)
+ *   3. Process env (`ELIZAOS_CLOUD_API_KEY`, `ELIZAOS_CLOUD_BASE_URL`)
+ *
+ * Previously these helpers lived in `packages/agent/src/api/wallet-rpc.ts`
+ * because the wallet uses Cloud RPC proxies. They are NOT wallet-specific —
+ * cloud auth is consumed by cloud-status, cloud-billing, cloud-compat,
+ * health, x-relay, and travel-provider-relay routes. Hosting them under
+ * `cloud/` matches their actual ownership.
+ */
+
+import type { ElizaConfig } from "../lib/config-like";
+
+export const DEFAULT_CLOUD_API_BASE_URL = "https://elizacloud.ai/api/v1";
+
+export type CloudApiKeyRuntimeLike = {
+  getSetting?: (key: string) => unknown;
+  character?: {
+    secrets?: Record<string, unknown>;
+  } | null;
+} | null;
+
+export function normalizeCloudSecret(
+  value: string | null | undefined,
+): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function resolveRuntimeCloudApiKey(
+  runtime?: CloudApiKeyRuntimeLike,
+): string | null {
+  const fromSetting = runtime?.getSetting?.("ELIZAOS_CLOUD_API_KEY");
+  if (typeof fromSetting === "string") {
+    return normalizeCloudSecret(fromSetting);
+  }
+
+  const fromSecrets = runtime?.character?.secrets?.ELIZAOS_CLOUD_API_KEY;
+  return typeof fromSecrets === "string"
+    ? normalizeCloudSecret(fromSecrets)
+    : null;
+}
+
+export function resolveCloudApiBaseUrl(
+  rawBaseUrl?: string | null,
+): string | null {
+  const candidate =
+    normalizeCloudSecret(rawBaseUrl ?? process.env.ELIZAOS_CLOUD_BASE_URL) ??
+    DEFAULT_CLOUD_API_BASE_URL;
+  try {
+    const parsed = new URL(candidate);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return null;
+    }
+    parsed.hash = "";
+    parsed.search = "";
+    const normalizedBase = parsed.toString().replace(/\/+$/, "");
+    return normalizedBase.endsWith("/api/v1")
+      ? normalizedBase
+      : `${normalizedBase}/api/v1`;
+  } catch {
+    return null;
+  }
+}
+
+export function resolveCloudApiKey(
+  config?: Pick<ElizaConfig, "cloud"> | null,
+  runtime?: CloudApiKeyRuntimeLike,
+): string | null {
+  return normalizeCloudSecret(
+    config?.cloud?.apiKey ??
+      resolveRuntimeCloudApiKey(runtime) ??
+      process.env.ELIZAOS_CLOUD_API_KEY,
+  );
+}

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);
+  }
+}