@elizaos/agent 0.25.9 → 2.0.0-alpha.151

package/packages/agent/src/cli/benchmark.js

@@ -0,0 +1,293 @@
+/**
+ * CLI subcommand for headless benchmark execution.
+ *
+ * Accepts a task as JSON (from --task <file> or stdin), boots the runtime
+ * in headless mode, sends the prompt through handleMessage (the real agent
+ * loop including action selection), captures the response, and writes a
+ * JSON result to stdout.
+ *
+ * Task prompts are augmented with type-aware instructions so the agent
+ * produces thorough, structured responses through its normal flow.
+ *
+ * Server mode (--server) keeps the runtime alive and reads line-delimited
+ * JSON from stdin, writing one result line per task.
+ */
+import crypto from "node:crypto";
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import * as readline from "node:readline";
+import { ChannelType, createMessageMemory, logger, stringToUuid, } from "@elizaos/core";
+// ---------------------------------------------------------------------------
+// Prompt augmentation — steers the agent via the normal message flow
+// ---------------------------------------------------------------------------
+const RESEARCH_AUGMENTATION = "\n\nPlease give a thorough, structured answer with ## headings, bullet points, and a conclusion. Be detailed and comprehensive.";
+const CODING_AUGMENTATION = "\n\nPlease write the complete code implementation directly in your response using ```typescript blocks. Include all imports, types, and error handling. Do not delegate — write the code yourself.";
+const DEFAULT_AUGMENTATION = "\n\nPlease give a detailed, structured answer with headings and bullet points.";
+function detectTaskType(task) {
+    if (task.type)
+        return task.type;
+    if (/\b(implement|build|create|write|code|function|class|module|component|api|endpoint|cli|test suite|refactor|debug|fix.*bug)\b/i.test(task.prompt)) {
+        return "coding";
+    }
+    return "research";
+}
+function augmentPrompt(task) {
+    const taskType = detectTaskType(task);
+    switch (taskType) {
+        case "research":
+            return task.prompt + RESEARCH_AUGMENTATION;
+        case "coding":
+            return task.prompt + CODING_AUGMENTATION;
+        default:
+            return task.prompt + DEFAULT_AUGMENTATION;
+    }
+}
+// ---------------------------------------------------------------------------
+// Task execution — uses handleMessage (the real agent loop)
+// ---------------------------------------------------------------------------
+async function runTask(runtime, task, timeoutMs) {
+    const start = performance.now();
+    const taskType = detectTaskType(task);
+    const userId = crypto.randomUUID();
+    const roomId = stringToUuid(`benchmark-${task.id}`);
+    const worldId = stringToUuid(`benchmark-world-${task.id}`);
+    const messageServerId = stringToUuid(`benchmark-server-${task.id}`);
+    try {
+        await runtime.ensureConnection({
+            entityId: userId,
+            roomId,
+            worldId,
+            userName: "Benchmark",
+            source: "benchmark",
+            channelId: `benchmark-${task.id}`,
+            type: ChannelType.DM,
+            messageServerId,
+            metadata: { ownership: { ownerId: userId } },
+        });
+        const augmentedPrompt = augmentPrompt(task);
+        const message = createMessageMemory({
+            id: crypto.randomUUID(),
+            entityId: userId,
+            roomId,
+            content: {
+                text: augmentedPrompt,
+                source: "benchmark",
+                channelType: ChannelType.DM,
+            },
+        });
+        if (!runtime.messageService) {
+            return {
+                id: task.id,
+                response: "",
+                actions_taken: [taskType],
+                duration_ms: Math.round(performance.now() - start),
+                success: false,
+                error: "runtime.messageService is not available",
+            };
+        }
+        let callbackText = "";
+        let streamText = "";
+        const actionsTaken = [taskType];
+        // Race message handling against the timeout.
+        // Text can arrive via three channels:
+        //   1. callback — action handler results
+        //   2. onStreamChunk — streamed LLM tokens
+        //   3. result.responseContent — final composed response
+        // We capture all three and deduplicate.
+        const result = (await Promise.race([
+            (async () => {
+                const handleResult = await runtime.messageService?.handleMessage(runtime, message, async (content) => {
+                    if (content?.text) {
+                        callbackText += content.text;
+                    }
+                    // Track actions taken
+                    const action = content?.action;
+                    if (typeof action === "string" && !actionsTaken.includes(action)) {
+                        actionsTaken.push(action);
+                    }
+                    return [];
+                }, {
+                    onStreamChunk: async (chunk) => {
+                        if (chunk)
+                            streamText += chunk;
+                    },
+                });
+                return handleResult;
+            })(),
+            new Promise((resolve) => setTimeout(() => resolve("timeout"), timeoutMs)),
+        ]));
+        if (result === "timeout") {
+            const responseText = streamText || callbackText;
+            return {
+                id: task.id,
+                response: responseText,
+                actions_taken: actionsTaken,
+                duration_ms: Math.round(performance.now() - start),
+                success: false,
+                error: `Timeout after ${timeoutMs}ms`,
+            };
+        }
+        // Extract text from all channels, preferring the richest source.
+        // result.responseContent has the final composed text from the LLM.
+        const resultRecord = typeof result === "object" && result !== null
+            ? result
+            : null;
+        const responseContent = resultRecord?.responseContent &&
+            typeof resultRecord.responseContent === "object"
+            ? resultRecord.responseContent
+            : null;
+        const resultText = responseContent && typeof responseContent.text === "string"
+            ? responseContent.text
+            : "";
+        // Also check responseMessages for additional text
+        const responseMessages = Array.isArray(resultRecord?.responseMessages)
+            ? resultRecord.responseMessages
+            : [];
+        const messagesText = responseMessages
+            .map((m) => m.content?.text ?? "")
+            .filter(Boolean)
+            .join("\n");
+        // Pick the best source — longest non-empty wins, since the same
+        // text may appear in multiple channels.
+        const candidates = [
+            resultText,
+            messagesText,
+            streamText,
+            callbackText,
+        ].filter(Boolean);
+        const responseText = candidates.sort((a, b) => b.length - a.length)[0] ?? "";
+        return {
+            id: task.id,
+            response: responseText,
+            actions_taken: actionsTaken,
+            duration_ms: Math.round(performance.now() - start),
+            success: true,
+        };
+    }
+    catch (err) {
+        return {
+            id: task.id,
+            response: "",
+            actions_taken: [taskType],
+            duration_ms: Math.round(performance.now() - start),
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** Parse a JSON string into a BenchmarkTask, throwing on invalid input. */
+function parseTask(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("id" in parsed) ||
+        !("prompt" in parsed)) {
+        throw new Error('Invalid task JSON: must contain at minimum "id" and "prompt" fields');
+    }
+    return parsed;
+}
+/** Write a result as a single JSON line to stdout. */
+function writeResult(result) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+/**
+ * Server mode: read line-delimited JSON tasks from stdin, process each
+ * against the running runtime, and write results to stdout.
+ */
+async function runServerMode(runtime, timeoutMs) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        terminal: false,
+    });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const task = parseTask(trimmed);
+            const result = await runTask(runtime, task, timeoutMs);
+            writeResult(result);
+        }
+        catch (err) {
+            const errorResult = {
+                id: "unknown",
+                response: "",
+                actions_taken: [],
+                duration_ms: 0,
+                success: false,
+                error: `Failed to parse task: ${err instanceof Error ? err.message : String(err)}`,
+            };
+            writeResult(errorResult);
+        }
+    }
+}
+/**
+ * Entry point for the `benchmark` CLI subcommand.
+ */
+export async function runBenchmark(opts) {
+    const timeoutMs = Number.parseInt(opts.timeout, 10);
+    if (Number.isNaN(timeoutMs) || timeoutMs <= 0) {
+        console.error("[benchmark] Invalid timeout value");
+        process.exit(2);
+    }
+    // Suppress noisy runtime logs — benchmark output must be clean JSON on stdout
+    if (!process.env.LOG_LEVEL) {
+        process.env.LOG_LEVEL = "error";
+    }
+    process.env.ELIZA_HEADLESS = "1";
+    const { bootElizaRuntime } = await import("../runtime/eliza.js");
+    let runtime;
+    try {
+        runtime = await bootElizaRuntime();
+    }
+    catch (err) {
+        const errorResult = {
+            id: opts.task ? "file" : "stdin",
+            response: "",
+            actions_taken: [],
+            duration_ms: 0,
+            success: false,
+            error: `Runtime boot failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+        writeResult(errorResult);
+        process.exit(1);
+    }
+    if (opts.server) {
+        await runServerMode(runtime, timeoutMs);
+        logger.info("[benchmark] EOF on stdin, shutting down");
+        process.exit(0);
+    }
+    // Single-task mode
+    let taskJson;
+    if (opts.task) {
+        try {
+            taskJson = readFileSync(opts.task, "utf-8");
+        }
+        catch (err) {
+            console.error(`[benchmark] Failed to read task file: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(2);
+        }
+    }
+    else {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+        }
+        taskJson = Buffer.concat(chunks).toString("utf-8").trim();
+        if (!taskJson) {
+            console.error("[benchmark] No task provided. Use --task <file> or pipe JSON to stdin.");
+            process.exit(2);
+        }
+    }
+    let task;
+    try {
+        task = parseTask(taskJson);
+    }
+    catch (err) {
+        console.error(`[benchmark] Invalid task JSON: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(2);
+    }
+    const result = await runTask(runtime, task, timeoutMs);
+    writeResult(result);
+    process.exit(result.success ? 0 : 1);
+}

package/packages/agent/src/cli/index.d.ts

@@ -0,0 +1,2 @@
+export declare function runAutonomousCli(argv?: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/packages/agent/src/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/cli/index.ts"],"names":[],"mappings":"AA6BA,wBAAsB,gBAAgB,CACpC,IAAI,GAAE,MAAM,EAAiB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA+Cf"}

package/packages/agent/src/cli/index.js

@@ -0,0 +1,70 @@
+import { createRequire } from "node:module";
+import process from "node:process";
+function printHelp() {
+    console.log(`eliza-autonomous
+
+Usage:
+  eliza-autonomous serve
+  eliza-autonomous runtime
+  eliza-autonomous benchmark [options]
+
+Commands:
+  serve      Start the autonomous backend in server-only mode
+  runtime    Boot the runtime without entering the API/CLI wrapper
+  benchmark  Run a benchmark task headlessly against the agent
+
+Benchmark options:
+  --task <path>    Path to task JSON file
+  --server         Keep runtime alive and accept tasks via stdin (line-delimited JSON)
+  --timeout <ms>   Timeout per task in milliseconds (default: 120000)
+`);
+}
+function printVersion() {
+    const require = createRequire(import.meta.url);
+    const pkg = require("../../package.json");
+    console.log(pkg.version);
+}
+export async function runAutonomousCli(argv = process.argv) {
+    const command = argv[2] ?? "serve";
+    if (command === "--version" || command === "-v" || command === "version") {
+        printVersion();
+        return;
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        printHelp();
+        return;
+    }
+    if (command === "runtime") {
+        const { bootElizaRuntime } = await import("../runtime/index.js");
+        await bootElizaRuntime();
+        return;
+    }
+    if (command === "serve" || command === "start") {
+        const { startEliza } = await import("../runtime/index.js");
+        await startEliza({ serverOnly: true });
+        return;
+    }
+    if (command === "benchmark") {
+        const { runBenchmark } = await import("./benchmark.js");
+        // Parse benchmark-specific flags from argv
+        const opts = {
+            task: undefined,
+            server: false,
+            timeout: "120000",
+        };
+        for (let i = 3; i < argv.length; i++) {
+            if (argv[i] === "--task" && argv[i + 1]) {
+                opts.task = argv[++i];
+            }
+            else if (argv[i] === "--server") {
+                opts.server = true;
+            }
+            else if (argv[i] === "--timeout" && argv[i + 1]) {
+                opts.timeout = argv[++i];
+            }
+        }
+        await runBenchmark(opts);
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+}

package/packages/agent/src/cli/parse-duration.d.ts

@@ -0,0 +1,5 @@
+export type DurationMsParseOptions = {
+    defaultUnit?: "ms" | "s" | "m" | "h" | "d";
+};
+export declare function parseDurationMs(raw: string, opts?: DurationMsParseOptions): number;
+//# sourceMappingURL=parse-duration.d.ts.map

package/packages/agent/src/cli/parse-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-duration.d.ts","sourceRoot":"","sources":["../../../../../src/cli/parse-duration.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CAC5C,CAAC;AAEF,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,sBAAsB,GAC5B,MAAM,CAmCR"}

package/packages/agent/src/cli/parse-duration.js

@@ -0,0 +1,27 @@
+export function parseDurationMs(raw, opts) {
+    const trimmed = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (!trimmed) {
+        throw new Error("invalid duration (empty)");
+    }
+    const m = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/.exec(trimmed);
+    if (!m) {
+        throw new Error(`invalid duration: ${raw}`);
+    }
+    const value = Number(m[1]);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`invalid duration: ${raw}`);
+    }
+    const unit = (m[2] ?? opts?.defaultUnit ?? "ms");
+    const multiplier = unit === "ms"
+        ? 1
+        : unit === "s"
+            ? 1000
+            : unit === "m"
+                ? 60_000
+                : unit === "h"
+                    ? 3_600_000
+                    : 86_400_000;
+    return Math.round(value * multiplier);
+}

package/packages/agent/src/cloud/auth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Eliza Cloud login flow — reuses the CLI auth session pattern:
+ * create session, open browser, poll until authenticated, return API key.
+ */
+export interface CloudLoginResult {
+    apiKey: string;
+    keyPrefix: string;
+    expiresAt: string | null;
+}
+export interface CloudLoginOptions {
+    baseUrl?: string;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
+    pollIntervalMs?: number;
+    onBrowserUrl?: (url: string) => void;
+    onPollStatus?: (status: string) => void;
+}
+export declare function cloudLogin(options?: CloudLoginOptions): Promise<CloudLoginResult>;
+//# sourceMappingURL=auth.d.ts.map

package/packages/agent/src/cloud/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../../../src/cloud/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AA2BD,wBAAsB,UAAU,CAC9B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CA0H3B"}

package/packages/agent/src/cloud/auth.js

@@ -0,0 +1,110 @@
+/**
+ * Eliza Cloud login flow — reuses the CLI auth session pattern:
+ * create session, open browser, poll until authenticated, return API key.
+ */
+import crypto from "node:crypto";
+import { logger } from "@elizaos/core";
+import { normalizeCloudSiteUrl } from "./base-url.js";
+import { validateCloudBaseUrl } from "./validate-url.js";
+const DEFAULT_CLOUD_REQUEST_TIMEOUT_MS = 10_000;
+function isRedirectResponse(response) {
+    return response.status >= 300 && response.status < 400;
+}
+function isTimeoutError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === "TimeoutError" || err.name === "AbortError")
+        return true;
+    const msg = err.message.toLowerCase();
+    return msg.includes("timed out") || msg.includes("timeout");
+}
+async function fetchWithTimeout(input, init, timeoutMs) {
+    return fetch(input, {
+        ...init,
+        redirect: "manual",
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+}
+export async function cloudLogin(options = {}) {
+    const baseUrl = normalizeCloudSiteUrl(options.baseUrl);
+    const urlError = await validateCloudBaseUrl(baseUrl);
+    if (urlError) {
+        throw new Error(urlError);
+    }
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_CLOUD_REQUEST_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+    const sessionId = crypto.randomUUID();
+    logger.info("[cloud-auth] Creating auth session...");
+    let createResponse;
+    try {
+        createResponse = await fetchWithTimeout(`${baseUrl}/api/auth/cli-session`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ sessionId }),
+        }, requestTimeoutMs);
+    }
+    catch (err) {
+        if (isTimeoutError(err)) {
+            throw new Error(`Cloud login request timed out while creating session (>${requestTimeoutMs}ms).`);
+        }
+        throw new Error(`Failed to create auth session: ${String(err)}`);
+    }
+    if (!createResponse.ok) {
+        if (isRedirectResponse(createResponse)) {
+            throw new Error("Cloud login request was redirected; redirects are not allowed.");
+        }
+        const errorText = await createResponse.text();
+        throw new Error(`Failed to create auth session (HTTP ${createResponse.status}): ${errorText}`);
+    }
+    const browserUrl = `${baseUrl}/auth/cli-login?session=${encodeURIComponent(sessionId)}`;
+    logger.info(`[cloud-auth] Browser URL: ${browserUrl}`);
+    options.onBrowserUrl?.(browserUrl);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const remainingBeforeSleep = deadline - Date.now();
+        if (remainingBeforeSleep <= 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(pollIntervalMs, remainingBeforeSleep)));
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        let pollResponse;
+        try {
+            pollResponse = await fetchWithTimeout(`${baseUrl}/api/auth/cli-session/${encodeURIComponent(sessionId)}`, {}, Math.min(requestTimeoutMs, remaining));
+        }
+        catch (err) {
+            if (isTimeoutError(err)) {
+                if (remaining <= requestTimeoutMs) {
+                    break;
+                }
+                throw new Error(`Cloud login polling request timed out (>${Math.min(requestTimeoutMs, remaining)}ms).`);
+            }
+            throw new Error(`Cloud login polling failed: ${String(err)}`);
+        }
+        if (!pollResponse.ok) {
+            if (isRedirectResponse(pollResponse)) {
+                throw new Error("Cloud login polling request was redirected; redirects are not allowed.");
+            }
+            if (pollResponse.status === 404) {
+                throw new Error("Auth session expired or not found. Please try again.");
+            }
+            options.onPollStatus?.("error");
+            continue;
+        }
+        const data = (await pollResponse.json());
+        options.onPollStatus?.(data.status);
+        if (data.status === "authenticated" && data.apiKey) {
+            logger.info("[cloud-auth] Authentication complete");
+            return {
+                apiKey: data.apiKey,
+                keyPrefix: data.keyPrefix ?? "",
+                expiresAt: data.expiresAt ?? null,
+            };
+        }
+        if (data.status === "authenticated" && !data.apiKey) {
+            throw new Error("Auth session was completed but the API key was already retrieved. Please try logging in again.");
+        }
+    }
+    throw new Error(`Cloud login timed out. The browser login was not completed within ${Math.round(timeoutMs / 1000)} seconds.`);
+}

package/packages/agent/src/cloud/backup.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Periodic state backup scheduler for cloud sandboxes.
+ * Default interval: 60s. Configurable via cloud.backup.autoBackupIntervalMs.
+ */
+import type { ElizaCloudClient } from "./bridge-client.js";
+export declare class BackupScheduler {
+    private client;
+    private agentId;
+    private intervalMs;
+    private timer;
+    private running;
+    constructor(client: ElizaCloudClient, agentId: string, intervalMs?: number);
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+    finalSnapshot(): Promise<void>;
+}
+//# sourceMappingURL=backup.d.ts.map

package/packages/agent/src/cloud/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../../../../src/cloud/backup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,qBAAa,eAAe;IAKxB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,UAAU;IANpB,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAS;gBAGd,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAe;IAGrC,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI;IAQZ,SAAS,IAAI,OAAO;IAId,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;CAKrC"}

package/packages/agent/src/cloud/backup.js

@@ -0,0 +1,42 @@
+/**
+ * Periodic state backup scheduler for cloud sandboxes.
+ * Default interval: 60s. Configurable via cloud.backup.autoBackupIntervalMs.
+ */
+import { logger } from "@elizaos/core";
+export class BackupScheduler {
+    client;
+    agentId;
+    intervalMs;
+    timer = null;
+    running = false;
+    constructor(client, agentId, intervalMs = 60_000) {
+        this.client = client;
+        this.agentId = agentId;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.running = true;
+        this.timer = setInterval(() => {
+            this.client.snapshot(this.agentId).catch((err) => {
+                logger.warn(`[cloud-backup] Auto-backup failed: ${String(err)}`);
+            });
+        }, this.intervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.running = false;
+    }
+    isRunning() {
+        return this.running;
+    }
+    async finalSnapshot() {
+        await this.client.snapshot(this.agentId).catch((err) => {
+            logger.warn(`[cloud-backup] Final snapshot failed: ${String(err)}`);
+        });
+    }
+}

package/packages/agent/src/cloud/base-url.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeCloudSiteUrl(rawUrl?: string): string;
+export declare function resolveCloudApiBaseUrl(rawUrl?: string): string;
+//# sourceMappingURL=base-url.d.ts.map

package/packages/agent/src/cloud/base-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-url.d.ts","sourceRoot":"","sources":["../../../../../src/cloud/base-url.ts"],"names":[],"mappings":"AA2BA,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CA4B7D;AAED,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/packages/agent/src/cloud/base-url.js

@@ -0,0 +1,52 @@
+const DEFAULT_CLOUD_SITE_URL = "https://www.elizacloud.ai";
+const LEGACY_CLOUD_HOST_ALIASES = new Set([
+    "elizacloud.ai",
+    "www.elizacloud.ai",
+]);
+function isLoopbackHost(hostname) {
+    const normalized = hostname.toLowerCase();
+    return (normalized === "localhost" ||
+        normalized === "::1" ||
+        normalized === "0:0:0:0:0:0:0:1" ||
+        normalized.startsWith("127."));
+}
+function trimApiPath(pathname) {
+    const normalized = pathname.trim().replace(/\/+$/, "");
+    if (!normalized)
+        return "";
+    if (normalized === "/api/v1")
+        return "";
+    if (normalized.endsWith("/api/v1")) {
+        return normalized.slice(0, -"/api/v1".length);
+    }
+    return normalized;
+}
+export function normalizeCloudSiteUrl(rawUrl) {
+    // Allow cloud-provisioned containers to override the base URL via env var
+    const envOverride = process.env.ELIZAOS_CLOUD_BASE_URL?.trim();
+    const candidate = envOverride || rawUrl?.trim() || DEFAULT_CLOUD_SITE_URL;
+    try {
+        const parsed = new URL(candidate);
+        const pathname = trimApiPath(parsed.pathname);
+        const host = parsed.hostname.toLowerCase();
+        const preserveLocalOrigin = isLoopbackHost(host);
+        parsed.hash = "";
+        parsed.search = "";
+        if (!preserveLocalOrigin) {
+            parsed.protocol = "https:";
+            parsed.port = "";
+        }
+        parsed.pathname = pathname;
+        if (LEGACY_CLOUD_HOST_ALIASES.has(host)) {
+            parsed.hostname = "www.elizacloud.ai";
+            parsed.pathname = "";
+        }
+        return parsed.toString().replace(/\/+$/, "");
+    }
+    catch {
+        return candidate.replace(/\/+$/, "");
+    }
+}
+export function resolveCloudApiBaseUrl(rawUrl) {
+    return `${normalizeCloudSiteUrl(rawUrl)}/api/v1`;
+}