@elizaos/autonomous 2.0.0-alpha.10

package/src/cloud/bridge-client.ts

@@ -0,0 +1,307 @@
+/**
+ * HTTP client for the Eliza Cloud Milady Sandbox API.
+ */
+
+export interface CloudAgent {
+  id: string;
+  agentName: string;
+  status: string;
+  databaseStatus: string;
+  bridgeUrl?: string;
+  lastBackupAt?: string;
+  lastHeartbeatAt?: string;
+  errorMessage?: string;
+  errorCount?: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CloudAgentCreateParams {
+  agentName: string;
+  agentConfig?: Record<string, unknown>;
+  environmentVars?: Record<string, string>;
+}
+
+export interface ProvisionInfo {
+  id: string;
+  agentName: string;
+  status: string;
+  bridgeUrl?: string;
+  healthUrl?: string;
+}
+
+export interface BackupInfo {
+  id: string;
+  snapshotType: string;
+  sizeBytes: number | null;
+  createdAt: string;
+}
+
+export type ChatChannelType =
+  | "DM"
+  | "GROUP"
+  | "VOICE_DM"
+  | "VOICE_GROUP"
+  | "API";
+
+interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+
+function isRedirectResponse(response: Response): boolean {
+  return response.status >= 300 && response.status < 400;
+}
+
+export class ElizaCloudClient {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor(baseUrl: string, apiKey: string) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+  }
+
+  async listAgents(): Promise<CloudAgent[]> {
+    const res = await this.request<CloudAgent[]>(
+      "GET",
+      "/api/v1/milady/agents",
+    );
+    return res.data ?? [];
+  }
+
+  async createAgent(params: CloudAgentCreateParams): Promise<CloudAgent> {
+    const res = await this.request<CloudAgent>(
+      "POST",
+      "/api/v1/milady/agents",
+      params,
+    );
+    if (!res.success || !res.data)
+      throw new Error(res.error ?? "Failed to create cloud agent");
+    return res.data;
+  }
+
+  async getAgent(agentId: string): Promise<CloudAgent> {
+    const res = await this.request<CloudAgent>(
+      "GET",
+      `/api/v1/milady/agents/${agentId}`,
+    );
+    if (!res.success || !res.data)
+      throw new Error(res.error ?? "Agent not found");
+    return res.data;
+  }
+
+  async deleteAgent(agentId: string): Promise<void> {
+    const res = await this.request<void>(
+      "DELETE",
+      `/api/v1/milady/agents/${agentId}`,
+    );
+    if (!res.success) throw new Error(res.error ?? "Failed to delete agent");
+  }
+
+  async provision(agentId: string): Promise<ProvisionInfo> {
+    const res = await this.request<ProvisionInfo>(
+      "POST",
+      `/api/v1/milady/agents/${agentId}/provision`,
+    );
+    if (!res.success || !res.data)
+      throw new Error(res.error ?? "Failed to provision sandbox");
+    return res.data;
+  }
+
+  async sendMessage(
+    agentId: string,
+    text: string,
+    roomId = "web-chat",
+    channelType: ChatChannelType = "DM",
+  ): Promise<string> {
+    const url = `${this.baseUrl}/api/v1/milady/agents/${agentId}/bridge`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Api-Key": this.apiKey },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: crypto.randomUUID(),
+        method: "message.send",
+        params: { text, roomId, channelType },
+      }),
+      redirect: "manual",
+      signal: AbortSignal.timeout(60_000),
+    });
+
+    if (isRedirectResponse(response)) {
+      throw new Error(
+        "Bridge request was redirected; redirects are not allowed",
+      );
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      throw new Error(
+        `Bridge request failed: HTTP ${response.status} ${errorText.slice(0, 200)}`,
+      );
+    }
+
+    const rpc = (await response.json()) as {
+      result?: { text?: string };
+      error?: { code: number; message: string };
+    };
+
+    if (rpc.error) throw new Error(rpc.error.message);
+    return rpc.result?.text ?? "(no response)";
+  }
+
+  async *sendMessageStream(
+    agentId: string,
+    text: string,
+    roomId = "web-chat",
+    channelType: ChatChannelType = "DM",
+  ): AsyncGenerator<{ type: string; data: Record<string, unknown> }> {
+    const url = `${this.baseUrl}/api/v1/milady/agents/${agentId}/stream`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Api-Key": this.apiKey },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: crypto.randomUUID(),
+        method: "message.send",
+        params: { text, roomId, channelType },
+      }),
+      redirect: "manual",
+    });
+
+    if (isRedirectResponse(response)) {
+      throw new Error(
+        "Stream request was redirected; redirects are not allowed",
+      );
+    }
+
+    if (!response.ok || !response.body) {
+      throw new Error(`Stream request failed: HTTP ${response.status}`);
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop() ?? "";
+
+      for (const part of parts) {
+        if (!part.trim()) continue;
+        let eventType = "message";
+        let eventData = "";
+
+        for (const line of part.split("\n")) {
+          if (line.startsWith("event: ")) eventType = line.slice(7).trim();
+          else if (line.startsWith("data: ")) eventData = line.slice(6);
+        }
+
+        if (eventData) {
+          let data: Record<string, unknown>;
+          try {
+            data = JSON.parse(eventData) as Record<string, unknown>;
+          } catch {
+            continue;
+          }
+          yield { type: eventType, data };
+        }
+      }
+    }
+  }
+
+  async snapshot(agentId: string): Promise<BackupInfo> {
+    const res = await this.request<BackupInfo>(
+      "POST",
+      `/api/v1/milady/agents/${agentId}/snapshot`,
+    );
+    if (!res.success || !res.data)
+      throw new Error(res.error ?? "Snapshot failed");
+    return res.data;
+  }
+
+  async listBackups(agentId: string): Promise<BackupInfo[]> {
+    const res = await this.request<BackupInfo[]>(
+      "GET",
+      `/api/v1/milady/agents/${agentId}/backups`,
+    );
+    return res.data ?? [];
+  }
+
+  async restore(agentId: string, backupId?: string): Promise<void> {
+    const res = await this.request<void>(
+      "POST",
+      `/api/v1/milady/agents/${agentId}/restore`,
+      backupId ? { backupId } : {},
+    );
+    if (!res.success) throw new Error(res.error ?? "Restore failed");
+  }
+
+  async heartbeat(agentId: string): Promise<boolean> {
+    const url = `${this.baseUrl}/api/v1/milady/agents/${agentId}/bridge`;
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Api-Key": this.apiKey,
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", method: "heartbeat" }),
+        redirect: "manual",
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (isRedirectResponse(response)) return false;
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<ApiResponse<T>> {
+    const headers: Record<string, string> = { "X-Api-Key": this.apiKey };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      redirect: "manual",
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    if (isRedirectResponse(response)) {
+      return {
+        success: false,
+        error: "Cloud API request was redirected; redirects are not allowed",
+      };
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      let parsed: Record<string, unknown> = {};
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        /* plain text */
+      }
+      return {
+        success: false,
+        error:
+          (parsed.error as string) ??
+          `HTTP ${response.status}: ${text.slice(0, 200)}`,
+      };
+    }
+
+    return (await response.json()) as ApiResponse<T>;
+  }
+}

package/src/cloud/cloud-manager.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Tests for cloud/cloud-manager.ts — the top-level orchestrator.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// Must mock before importing CloudManager, and use factory functions
+// that return class-like constructors so `new` works.
+vi.mock("./bridge-client", () => {
+  return {
+    ElizaCloudClient: class MockElizaCloudClient {
+      _baseUrl: string;
+      _apiKey: string;
+      provision = vi.fn().mockResolvedValue({ id: "a1", status: "running" });
+      getAgent = vi.fn().mockResolvedValue({
+        id: "a1",
+        agentName: "TestBot",
+        status: "running",
+      });
+      snapshot = vi.fn().mockResolvedValue({ id: "bk-1" });
+      heartbeat = vi.fn().mockResolvedValue(true);
+      constructor(baseUrl: string, apiKey: string) {
+        this._baseUrl = baseUrl;
+        this._apiKey = apiKey;
+      }
+    },
+  };
+});
+
+vi.mock("./cloud-proxy", () => {
+  return {
+    CloudRuntimeProxy: class MockProxy {
+      agentName: string;
+      constructor(_client: unknown, _id: string, name: string) {
+        this.agentName = name;
+      }
+    },
+  };
+});
+
+vi.mock("./backup", () => {
+  return {
+    BackupScheduler: class MockBackup {
+      start = vi.fn();
+      stop = vi.fn();
+      finalSnapshot = vi.fn().mockResolvedValue(undefined);
+    },
+  };
+});
+
+vi.mock("./reconnect", () => {
+  return {
+    ConnectionMonitor: class MockMonitor {
+      start = vi.fn();
+      stop = vi.fn();
+    },
+  };
+});
+
+vi.mock("./validate-url", () => {
+  return {
+    validateCloudBaseUrl: vi.fn().mockResolvedValue(null),
+  };
+});
+
+import type { CloudConfig } from "../config/types.milady";
+import { CloudManager } from "./cloud-manager";
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+function cfg(overrides: Partial<CloudConfig> = {}): CloudConfig {
+  return {
+    enabled: true,
+    apiKey: "eliza_testkey",
+    baseUrl: "https://test.elizacloud.ai",
+    ...overrides,
+  };
+}
+
+describe("CloudManager", () => {
+  describe("init", () => {
+    it("creates client from config", async () => {
+      const mgr = new CloudManager(cfg());
+      await mgr.init();
+      expect(mgr.getClient()).not.toBeNull();
+    });
+
+    it("throws when apiKey is missing", async () => {
+      const mgr = new CloudManager(cfg({ apiKey: undefined }));
+      await expect(mgr.init()).rejects.toThrow(
+        "Cloud API key is not configured",
+      );
+    });
+
+    it("strips /api/v1 suffix from baseUrl", async () => {
+      const mgr = new CloudManager(
+        cfg({ baseUrl: "https://test.elizacloud.ai/api/v1" }),
+      );
+      await mgr.init();
+      expect((mgr.getClient() as unknown as Record<string, string>)._baseUrl).toBe(
+        "https://test.elizacloud.ai",
+      );
+    });
+
+    it("strips trailing slashes", async () => {
+      const mgr = new CloudManager(
+        cfg({ baseUrl: "https://test.elizacloud.ai///" }),
+      );
+      await mgr.init();
+      expect((mgr.getClient() as unknown as Record<string, string>)._baseUrl).toBe(
+        "https://test.elizacloud.ai",
+      );
+    });
+
+    it("defaults to elizacloud.ai when no baseUrl", async () => {
+      const mgr = new CloudManager(cfg({ baseUrl: undefined }));
+      await mgr.init();
+      expect((mgr.getClient() as unknown as Record<string, string>)._baseUrl).toBe(
+        "https://www.elizacloud.ai",
+      );
+    });
+  });
+
+  describe("connect", () => {
+    it("provisions and returns proxy", async () => {
+      const mgr = new CloudManager(cfg());
+      const proxy = await mgr.connect("agent-123");
+      expect(proxy.agentName).toBe("TestBot");
+      expect(mgr.getActiveAgentId()).toBe("agent-123");
+      expect(mgr.getStatus()).toBe("connected");
+      expect(mgr.getProxy()).not.toBeNull();
+    });
+
+    it("auto-inits if client not ready", async () => {
+      const mgr = new CloudManager(cfg());
+      expect(mgr.getClient()).toBeNull();
+      await mgr.connect("agent-123");
+      expect(mgr.getClient()).not.toBeNull();
+    });
+
+    it("fires status callbacks", async () => {
+      const statuses: string[] = [];
+      const mgr = new CloudManager(cfg(), {
+        onStatusChange: (s) => statuses.push(s),
+      });
+      await mgr.connect("agent-123");
+      expect(statuses).toContain("connecting");
+      expect(statuses).toContain("connected");
+    });
+
+    it("resets status and state on connection failure", async () => {
+      const mgr = new CloudManager(cfg());
+      await mgr.init();
+
+      const state = mgr as unknown as {
+        client: { provision: (...args: unknown[]) => Promise<unknown> };
+      };
+      state.client.provision = vi.fn(async () => {
+        throw new Error("provision failed");
+      });
+
+      await expect(mgr.connect("agent-123")).rejects.toThrow(
+        "provision failed",
+      );
+      expect(mgr.getStatus()).toBe("disconnected");
+      expect(mgr.getActiveAgentId()).toBeNull();
+      expect(mgr.getProxy()).toBeNull();
+    });
+  });
+
+  describe("disconnect", () => {
+    it("clears proxy and resets state", async () => {
+      const mgr = new CloudManager(cfg());
+      await mgr.connect("agent-123");
+      await mgr.disconnect();
+      expect(mgr.getProxy()).toBeNull();
+      expect(mgr.getActiveAgentId()).toBeNull();
+      expect(mgr.getStatus()).toBe("disconnected");
+    });
+
+    it("fires disconnected callback", async () => {
+      const statuses: string[] = [];
+      const mgr = new CloudManager(cfg(), {
+        onStatusChange: (s) => statuses.push(s),
+      });
+      await mgr.connect("agent-123");
+      statuses.length = 0;
+      await mgr.disconnect();
+      expect(statuses).toContain("disconnected");
+    });
+  });
+
+  describe("isEnabled", () => {
+    it("true when enabled + apiKey", () => {
+      expect(new CloudManager(cfg()).isEnabled()).toBe(true);
+    });
+    it("false when not enabled", () => {
+      expect(new CloudManager(cfg({ enabled: false })).isEnabled()).toBe(false);
+    });
+    it("false when no apiKey", () => {
+      expect(new CloudManager(cfg({ apiKey: undefined })).isEnabled()).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("initial state", () => {
+    it("proxy is null", () => {
+      expect(new CloudManager(cfg()).getProxy()).toBeNull();
+    });
+    it("client is null", () => {
+      expect(new CloudManager(cfg()).getClient()).toBeNull();
+    });
+    it("agentId is null", () => {
+      expect(new CloudManager(cfg()).getActiveAgentId()).toBeNull();
+    });
+    it("status is disconnected", () => {
+      expect(new CloudManager(cfg()).getStatus()).toBe("disconnected");
+    });
+  });
+});

package/src/cloud/cloud-manager.ts

@@ -0,0 +1,151 @@
+/**
+ * Top-level orchestrator for cloud integration.
+ * Manages client, proxy, backup scheduler, and connection monitor lifecycle.
+ */
+
+import { logger } from "@elizaos/core";
+import type { CloudConfig } from "../config/types.milady";
+import { BackupScheduler } from "./backup";
+import { normalizeCloudSiteUrl } from "./base-url";
+import { ElizaCloudClient } from "./bridge-client";
+import { CloudRuntimeProxy } from "./cloud-proxy";
+import { ConnectionMonitor } from "./reconnect";
+import { validateCloudBaseUrl } from "./validate-url";
+
+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);
+    }
+
+    const siteUrl = normalizeCloudSiteUrl(rawUrl);
+    this.client = new ElizaCloudClient(siteUrl, apiKey);
+    logger.info(`[cloud-manager] Client initialised (baseUrl=${siteUrl})`);
+  }
+
+  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");
+  }
+
+  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);
+  }
+}