Add cloud package and CLI integration

package.json

@@ -73,9 +73,10 @@
     "web"
   ],
   "bundledDependencies": [
-    "@agent-relay/sdk",
+    "@agent-relay/cloud",
     "@agent-relay/config",
     "@agent-relay/hooks",
+    "@agent-relay/sdk",
     "@agent-relay/telemetry",
     "@agent-relay/trajectory",
     "@agent-relay/user-directory",
@@ -176,9 +177,11 @@
   },
   "homepage": "https://github.com/AgentWorkforce/relay#readme",
   "dependencies": {
+    "@agent-relay/cloud": "3.2.18",
     "@agent-relay/config": "3.2.18",
     "@agent-relay/hooks": "3.2.18",
     "@agent-relay/sdk": "3.2.18",
+    "@aws-sdk/client-s3": "^3.1004.0",
     "@agent-relay/telemetry": "3.2.18",
     "@agent-relay/trajectory": "3.2.18",
     "@agent-relay/user-directory": "3.2.18",
@@ -196,9 +199,11 @@
     "express": "^5.2.1",
     "http-proxy-middleware": "^3.0.5",
     "listr2": "^10.2.1",
+    "ignore": "^7.0.5",
     "pg": "^8.16.3",
     "posthog-node": "^4.0.1",
     "smol-toml": "^1.6.0",
+    "tar": "^7.5.10",
     "ssh2": "^1.17.0",
     "uuid": "^10.0.0",
     "ws": "^8.18.3",
@@ -244,9 +249,10 @@
     "react-dom": "^18.3.1"
   },
   "bundleDependencies": [
-    "@agent-relay/sdk",
+    "@agent-relay/cloud",
     "@agent-relay/config",
     "@agent-relay/hooks",
+    "@agent-relay/sdk",
     "@agent-relay/telemetry",
     "@agent-relay/trajectory",
     "@agent-relay/user-directory",

packages/cloud/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@agent-relay/cloud",
+  "version": "3.2.18",
+  "description": "Cloud SDK for Agent Relay — auth, workflow execution, and provider connections",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@agent-relay/config": "3.2.18",
+    "@aws-sdk/client-s3": "^3.1004.0",
+    "ignore": "^7.0.5",
+    "tar": "^7.5.10"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/cloud"
+  }
+}

packages/cloud/src/api-client.ts

@@ -0,0 +1,169 @@
+import { REFRESH_WINDOW_MS } from "./types.js";
+
+export type CloudApiClientOptions = {
+  apiUrl: string;
+  accessToken: string;
+  refreshToken: string;
+  accessTokenExpiresAt: string;
+  refreshTokenExpiresAt?: string;
+};
+
+export type CloudApiClientSnapshot = {
+  apiUrl: string;
+  accessToken: string;
+  refreshToken: string;
+  accessTokenExpiresAt: string;
+  refreshTokenExpiresAt?: string;
+};
+
+function trimLeadingSlash(p: string): string {
+  return p.replace(/^\/+/, "");
+}
+
+function withTrailingSlash(p: string): string {
+  return p.endsWith("/") ? p : `${p}/`;
+}
+
+export function buildApiUrl(apiUrl: string, p: string): URL {
+  return new URL(trimLeadingSlash(p), withTrailingSlash(apiUrl));
+}
+
+export class CloudApiClient {
+  private accessToken: string;
+  private refreshToken: string;
+  private accessTokenExpiresAt: string;
+  private refreshTokenExpiresAt?: string;
+  private refreshPromise: Promise<void> | null = null;
+
+  constructor(private readonly options: CloudApiClientOptions) {
+    this.accessToken = options.accessToken;
+    this.refreshToken = options.refreshToken;
+    this.accessTokenExpiresAt = options.accessTokenExpiresAt;
+    this.refreshTokenExpiresAt = options.refreshTokenExpiresAt;
+  }
+
+  static fromEnv(env: NodeJS.ProcessEnv): CloudApiClient | null {
+    const apiUrl = env.CLOUD_API_URL?.trim();
+    const accessToken = env.CLOUD_API_ACCESS_TOKEN?.trim();
+    const refreshToken = env.CLOUD_API_REFRESH_TOKEN?.trim();
+    const accessTokenExpiresAt = env.CLOUD_API_ACCESS_TOKEN_EXPIRES_AT?.trim();
+    const refreshTokenExpiresAt = env.CLOUD_API_REFRESH_TOKEN_EXPIRES_AT?.trim();
+
+    if (!apiUrl || !accessToken || !refreshToken || !accessTokenExpiresAt) {
+      return null;
+    }
+
+    return new CloudApiClient({
+      apiUrl,
+      accessToken,
+      refreshToken,
+      accessTokenExpiresAt,
+      refreshTokenExpiresAt,
+    });
+  }
+
+  snapshot(): CloudApiClientSnapshot {
+    return {
+      apiUrl: this.options.apiUrl,
+      accessToken: this.accessToken,
+      refreshToken: this.refreshToken,
+      accessTokenExpiresAt: this.accessTokenExpiresAt,
+      ...(this.refreshTokenExpiresAt ? { refreshTokenExpiresAt: this.refreshTokenExpiresAt } : {}),
+    };
+  }
+
+  async fetch(p: string, init: RequestInit = {}): Promise<Response> {
+    await this.refresh();
+
+    const response = await fetch(buildApiUrl(this.options.apiUrl, p), {
+      ...init,
+      headers: this.buildHeaders(init.headers),
+    });
+
+    if (response.status !== 401) {
+      return response;
+    }
+
+    await this.refresh(true);
+
+    return fetch(buildApiUrl(this.options.apiUrl, p), {
+      ...init,
+      headers: this.buildHeaders(init.headers),
+    });
+  }
+
+  async revoke(): Promise<void> {
+    const response = await fetch(buildApiUrl(this.options.apiUrl, "/api/v1/auth/token/revoke"), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ token: this.refreshToken }),
+    });
+
+    if (!response.ok && response.status !== 404) {
+      throw new Error(`Failed to revoke API token: ${response.status} ${response.statusText}`);
+    }
+  }
+
+  private async refresh(force = false): Promise<void> {
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
+
+    if (!force && !this.shouldRefresh()) {
+      return;
+    }
+
+    this.refreshPromise = this.doRefresh().finally(() => {
+      this.refreshPromise = null;
+    });
+
+    return this.refreshPromise;
+  }
+
+  private async doRefresh(): Promise<void> {
+    const response = await fetch(buildApiUrl(this.options.apiUrl, "/api/v1/auth/token/refresh"), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ refreshToken: this.refreshToken }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to refresh API token: ${response.status} ${response.statusText}`);
+    }
+
+    const payload = (await response.json()) as {
+      accessToken?: string;
+      accessTokenExpiresAt?: string;
+      refreshToken?: string;
+      refreshTokenExpiresAt?: string;
+    };
+
+    if (!payload.accessToken || !payload.accessTokenExpiresAt || !payload.refreshToken) {
+      throw new Error("Refresh response missing token fields");
+    }
+
+    this.accessToken = payload.accessToken;
+    this.accessTokenExpiresAt = payload.accessTokenExpiresAt;
+    this.refreshToken = payload.refreshToken;
+    this.refreshTokenExpiresAt = payload.refreshTokenExpiresAt;
+  }
+
+  private buildHeaders(headers: HeadersInit | undefined): Headers {
+    const merged = new Headers(headers);
+    merged.set("Authorization", `Bearer ${this.accessToken}`);
+    return merged;
+  }
+
+  private shouldRefresh(): boolean {
+    const expiresAt = Date.parse(this.accessTokenExpiresAt);
+    if (Number.isNaN(expiresAt)) {
+      return true;
+    }
+
+    return expiresAt - Date.now() <= REFRESH_WINDOW_MS;
+  }
+}