Merge pull request #7832 from elizaOS/codex/capability-cloud-readiness-20260520

fix(agent): wait for cloud capability readiness

Author: lalalune

packages/agent/src/services/remote-capability-cloud-sandbox.cloud-smoke.test.ts

@@ -12,6 +12,7 @@ import {
 import {
   installRemoteCapabilityEndpoint,
   provisionCloudCapabilitySandbox,
+  waitForCloudCapabilityEndpointAvailability,
 } from "./remote-capability-cloud-sandbox.ts";
 import { assertRemoteCapabilityEndpointConformance } from "./remote-capability-endpoint-conformance.ts";
 import {
@@ -32,8 +33,12 @@ const cloudProvisionTimeoutMs = readPositiveIntegerEnv(
   "ELIZA_REMOTE_CAPABILITY_CLOUD_PROVISION_TIMEOUT_MS",
   600_000,
 );
+const cloudAvailabilityTimeoutMs = readPositiveIntegerEnv(
+  "ELIZA_REMOTE_CAPABILITY_CLOUD_AVAILABILITY_TIMEOUT_MS",
+  300_000,
+);
 const cloudLiveTestTimeoutMs = Math.max(
-  cloudProvisionTimeoutMs + 120_000,
+  cloudProvisionTimeoutMs + cloudAvailabilityTimeoutMs + 120_000,
   720_000,
 );
 const registeredPluginNames: string[] = [];
@@ -77,6 +82,19 @@ describe("cloud capability sandbox live smoke", () => {
         });
         agentId = provisioned.agentId;
 
+        await waitForCloudCapabilityEndpointAvailability({
+          endpoint: provisioned.endpoint,
+          timeoutMs: cloudAvailabilityTimeoutMs,
+          pollIntervalMs: 5_000,
+          requestTimeoutMs: 60_000,
+          onProgress: (detail) => {
+            console.log(`[cloud-capability-live] availability: ${detail}`);
+          },
+        });
+        console.log(
+          `[cloud-capability-live] availability: endpoint ${provisioned.endpoint.id} reports plugin capability.`,
+        );
+
         installRemoteCapabilityEndpoint(runtime, {
           enabled: true,
           endpoints: [provisioned.endpoint],

packages/agent/src/services/remote-capability-cloud-sandbox.test.ts

@@ -8,6 +8,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   connectCloudCapabilitySandbox,
   provisionCloudCapabilitySandbox,
+  waitForCloudCapabilityEndpointAvailability,
 } from "./remote-capability-cloud-sandbox.ts";
 import type { RemoteCapabilityRouterService } from "./remote-capability-router.ts";
 
@@ -151,6 +152,69 @@ describe("cloud capability sandbox provisioner", () => {
     });
   });
 
+  it("waits until a cloud capability endpoint reports plugin availability", async () => {
+    const progress: string[] = [];
+    const fetchMock = vi.fn(async () => {
+      const attempt = fetchMock.mock.calls.length;
+      if (attempt === 1) {
+        return jsonResponse({
+          available: false,
+          capabilities: { plugin: false },
+        });
+      }
+      return jsonResponse({ available: true, capabilities: { plugin: true } });
+    });
+
+    await expect(
+      waitForCloudCapabilityEndpointAvailability({
+        endpoint: {
+          id: "cloud-capability",
+          baseUrl: "https://capability.example.test",
+          token: "capability-token",
+        },
+        timeoutMs: 1_000,
+        pollIntervalMs: 1,
+        requestTimeoutMs: 1_000,
+        fetch: fetchMock as unknown as typeof fetch,
+        onProgress: (detail) => progress.push(detail),
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[0]?.[0]).toEqual(
+      new URL("https://capability.example.test/v1/capabilities"),
+    );
+    expect(fetchMock.mock.calls[0]?.[1]).toMatchObject({
+      method: "GET",
+      headers: {
+        accept: "application/json",
+        authorization: "Bearer capability-token",
+      },
+    });
+    expect(progress[0]).toContain("unexpected availability payload");
+  });
+
+  it("reports the last readiness failure when cloud availability never starts", async () => {
+    const fetchMock = vi.fn(async () =>
+      jsonResponse({ error: "not ready" }, 503),
+    );
+
+    await expect(
+      waitForCloudCapabilityEndpointAvailability({
+        endpoint: {
+          id: "cloud-capability",
+          baseUrl: "https://capability.example.test",
+        },
+        timeoutMs: 1,
+        pollIntervalMs: 1,
+        requestTimeoutMs: 1_000,
+        fetch: fetchMock as unknown as typeof fetch,
+      }),
+    ).rejects.toThrow(
+      'Cloud capability endpoint cloud-capability did not report plugin availability within 1ms. Last error: HTTP 503: {"error":"not ready"}',
+    );
+  });
+
   it("fails when provisioning completes without an endpoint", async () => {
     const fetchMock = vi.fn(async (url: string | URL) => {
       const href = String(url);

packages/agent/src/services/remote-capability-cloud-sandbox.ts

@@ -34,6 +34,15 @@ export type CloudCapabilitySandboxProvisionResult = {
   jobId?: string;
 };
 
+export type WaitForCloudCapabilityEndpointAvailabilityOptions = {
+  endpoint: RemoteCapabilityEndpointConfig;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  requestTimeoutMs?: number;
+  fetch?: typeof fetch;
+  onProgress?: (detail: string) => void;
+};
+
 export type ConnectCloudCapabilitySandboxOptions =
   CloudCapabilitySandboxProvisionOptions & {
     unloadMissing?: boolean;
@@ -246,6 +255,99 @@ export async function connectCloudCapabilitySandbox(
   };
 }
 
+export async function waitForCloudCapabilityEndpointAvailability(
+  options: WaitForCloudCapabilityEndpointAvailabilityOptions,
+): Promise<void> {
+  const request = options.fetch ?? fetch;
+  const timeoutMs = options.timeoutMs ?? 120_000;
+  const pollIntervalMs = options.pollIntervalMs ?? 5_000;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 60_000;
+  const deadline = Date.now() + timeoutMs;
+  let lastError = "availability was not checked";
+
+  while (Date.now() < deadline) {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
+      try {
+        const response = await request(
+          new URL("/v1/capabilities", options.endpoint.baseUrl),
+          {
+            method: "GET",
+            headers: {
+              accept: "application/json",
+              ...(options.endpoint.token
+                ? { authorization: `Bearer ${options.endpoint.token}` }
+                : {}),
+            },
+            signal: controller.signal,
+          },
+        );
+        const text = await response.text();
+        if (!response.ok) {
+          lastError = `HTTP ${response.status}: ${text.slice(0, 500)}`;
+        } else {
+          const availability = JSON.parse(text) as {
+            available?: unknown;
+            capabilities?: { plugin?: unknown };
+          };
+          if (
+            availability.available === true &&
+            availability.capabilities?.plugin === true
+          ) {
+            return;
+          }
+          lastError = `unexpected availability payload: ${text.slice(0, 500)}`;
+        }
+      } finally {
+        clearTimeout(timeout);
+      }
+    } catch (error) {
+      lastError = describeAvailabilityError(error);
+    }
+    options.onProgress?.(
+      `waiting for endpoint ${options.endpoint.id}: ${lastError}`,
+    );
+    await sleep(pollIntervalMs);
+  }
+
+  throw new Error(
+    `Cloud capability endpoint ${options.endpoint.id} did not report plugin availability within ${timeoutMs}ms. Last error: ${lastError}`,
+  );
+}
+
+function describeAvailabilityError(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  const cause = (error as Error & { cause?: unknown }).cause;
+  if (cause instanceof Error) {
+    return `${error.message}: ${cause.message}`;
+  }
+  if (cause && typeof cause === "object") {
+    const detail = cause as {
+      code?: unknown;
+      errno?: unknown;
+      syscall?: unknown;
+      hostname?: unknown;
+      address?: unknown;
+      port?: unknown;
+    };
+    const parts = [
+      detail.code,
+      detail.errno,
+      detail.syscall,
+      detail.hostname,
+      detail.address,
+      detail.port,
+    ]
+      .filter((value) => typeof value === "string" || typeof value === "number")
+      .map(String);
+    if (parts.length > 0) {
+      return `${error.message}: ${parts.join(" ")}`;
+    }
+  }
+  return error.message;
+}
+
 export {
   buildRemoteCapabilityEndpointTrustPolicy as buildEndpointTrustPolicy,
   installRemoteCapabilityEndpoint,