assistant-ui 0.0.124 → 0.0.126

package/dist/lib/cloud-remote.js

@@ -0,0 +1,74 @@
+import { validateCloudUrl } from "./cloud-url.js";
+//#region src/lib/cloud-remote.ts
+const CLOUD_CLI_RUN_PATH = "/api/cli/run";
+const SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+const joinCloudArgs = (args) => args.map((arg) => SAFE.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`).join(" ");
+const parseCloudCliResponse = (value) => {
+	if (!value || typeof value !== "object") return null;
+	const body = value;
+	const exitCode = body["exitCode"];
+	if (typeof exitCode !== "number" || !Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) return null;
+	for (const key of ["stdout", "stderr"]) if (body[key] !== void 0 && typeof body[key] !== "string") return null;
+	const actions = body["actions"];
+	if (actions !== void 0 && !(Array.isArray(actions) && actions.every((action) => !!action && typeof action === "object" && typeof action.type === "string"))) return null;
+	return body;
+};
+const cliVersion = "0.0.126";
+const sendCloudCommand = async (cloudUrl, args, accessToken) => {
+	const url = `${validateCloudUrl(cloudUrl)}${CLOUD_CLI_RUN_PATH}`;
+	let response;
+	try {
+		response = await fetch(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...accessToken ? { Authorization: `Bearer ${accessToken}` } : {}
+			},
+			body: JSON.stringify({
+				command: joinCloudArgs(args),
+				client: {
+					name: "assistant-ui",
+					version: cliVersion,
+					platform: `${process.platform}-${process.arch}`
+				}
+			}),
+			redirect: "error",
+			signal: AbortSignal.timeout(6e4)
+		});
+	} catch (error) {
+		const cause = error.cause;
+		throw new Error(`Could not reach ${url}: ${cause?.message || cause?.code || error.message}`);
+	}
+	const body = parseCloudCliResponse(await response.json().catch(() => null));
+	if (!body) throw new Error(`Unexpected response from ${url} (${response.status} ${response.statusText}).`);
+	return body;
+};
+const ACTION_HANDLERS = {};
+const runCloudCommand = async (args, deps) => {
+	let response;
+	try {
+		response = await (deps.send ?? sendCloudCommand)(deps.cloudUrl, args, await deps.accessToken().catch((error) => {
+			deps.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+			return null;
+		}));
+	} catch (error) {
+		deps.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	const unknown = response.actions?.find((action) => !Object.hasOwn(ACTION_HANDLERS, action.type));
+	if (unknown) {
+		deps.stderr(`This command needs a newer assistant-ui (unsupported action "${unknown.type}"). Update the CLI and try again.\n`);
+		return 1;
+	}
+	if (response.stdout) deps.stdout(response.stdout);
+	if (response.stderr) deps.stderr(response.stderr);
+	for (const action of response.actions ?? []) {
+		const code = await ACTION_HANDLERS[action.type](action);
+		if (code !== 0) return code;
+	}
+	return response.exitCode;
+};
+//#endregion
+export { CLOUD_CLI_RUN_PATH, joinCloudArgs, parseCloudCliResponse, runCloudCommand, sendCloudCommand };
+
+//# sourceMappingURL=cloud-remote.js.map

package/dist/lib/cloud-remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-remote.js","names":[],"sources":["../../src/lib/cloud-remote.ts"],"sourcesContent":["import { validateCloudUrl } from \"./cloud-url\";\n\nexport const CLOUD_CLI_RUN_PATH = \"/api/cli/run\";\n\nexport type CloudCliAction = { type: string; [key: string]: unknown };\n\nexport type CloudCliResponse = {\n  stdout?: string;\n  stderr?: string;\n  exitCode: number;\n  actions?: CloudCliAction[];\n};\n\nconst SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;\n\nexport const joinCloudArgs = (args: readonly string[]): string =>\n  args\n    .map((arg) => (SAFE.test(arg) ? arg : `'${arg.replaceAll(\"'\", `'\\\\''`)}'`))\n    .join(\" \");\n\nexport const parseCloudCliResponse = (\n  value: unknown,\n): CloudCliResponse | null => {\n  if (!value || typeof value !== \"object\") return null;\n  const body = value as Record<string, unknown>;\n  const exitCode = body[\"exitCode\"];\n  if (\n    typeof exitCode !== \"number\" ||\n    !Number.isInteger(exitCode) ||\n    exitCode < 0 ||\n    exitCode > 255\n  ) {\n    return null;\n  }\n  for (const key of [\"stdout\", \"stderr\"]) {\n    if (body[key] !== undefined && typeof body[key] !== \"string\") return null;\n  }\n  const actions = body[\"actions\"];\n  if (\n    actions !== undefined &&\n    !(\n      Array.isArray(actions) &&\n      actions.every(\n        (action) =>\n          !!action &&\n          typeof action === \"object\" &&\n          typeof (action as CloudCliAction).type === \"string\",\n      )\n    )\n  ) {\n    return null;\n  }\n  return body as CloudCliResponse;\n};\n\nconst cliVersion: string =\n  typeof __AUI_PACKAGE_VERSION__ === \"string\"\n    ? __AUI_PACKAGE_VERSION__\n    : \"0.0.0\";\n\nexport const sendCloudCommand = async (\n  cloudUrl: string,\n  args: readonly string[],\n  accessToken: string | null,\n): Promise<CloudCliResponse> => {\n  const url = `${validateCloudUrl(cloudUrl)}${CLOUD_CLI_RUN_PATH}`;\n  let response: Response;\n  try {\n    response = await fetch(url, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}),\n      },\n      body: JSON.stringify({\n        command: joinCloudArgs(args),\n        client: {\n          name: \"assistant-ui\",\n          version: cliVersion,\n          platform: `${process.platform}-${process.arch}`,\n        },\n      }),\n      redirect: \"error\",\n      signal: AbortSignal.timeout(60_000),\n    });\n  } catch (error) {\n    const cause = (error as Error).cause as NodeJS.ErrnoException | undefined;\n    throw new Error(\n      `Could not reach ${url}: ${cause?.message || cause?.code || (error as Error).message}`,\n    );\n  }\n  const body = parseCloudCliResponse(await response.json().catch(() => null));\n  if (!body) {\n    throw new Error(\n      `Unexpected response from ${url} (${response.status} ${response.statusText}).`,\n    );\n  }\n  return body;\n};\n\n// A response naming an action this client lacks fails before printing, so the\n// server can roll a new action out behind the client version it is sent.\nconst ACTION_HANDLERS: Record<\n  string,\n  (action: CloudCliAction) => Promise<number>\n> = {};\n\nexport const runCloudCommand = async (\n  args: readonly string[],\n  deps: {\n    cloudUrl: string;\n    accessToken: () => Promise<string | null>;\n    stdout: (text: string) => void;\n    stderr: (text: string) => void;\n    send?: typeof sendCloudCommand;\n  },\n): Promise<number> => {\n  let response: CloudCliResponse;\n  try {\n    response = await (deps.send ?? sendCloudCommand)(\n      deps.cloudUrl,\n      args,\n      await deps.accessToken().catch((error: unknown) => {\n        deps.stderr(\n          `${error instanceof Error ? error.message : String(error)}\\n`,\n        );\n        return null;\n      }),\n    );\n  } catch (error) {\n    deps.stderr(`${error instanceof Error ? error.message : String(error)}\\n`);\n    return 1;\n  }\n  const unknown = response.actions?.find(\n    (action) => !Object.hasOwn(ACTION_HANDLERS, action.type),\n  );\n  if (unknown) {\n    deps.stderr(\n      `This command needs a newer assistant-ui (unsupported action \"${unknown.type}\"). Update the CLI and try again.\\n`,\n    );\n    return 1;\n  }\n  if (response.stdout) deps.stdout(response.stdout);\n  if (response.stderr) deps.stderr(response.stderr);\n  for (const action of response.actions ?? []) {\n    const code = await ACTION_HANDLERS[action.type]!(action);\n    if (code !== 0) return code;\n  }\n  return response.exitCode;\n};\n"],"mappings":";;AAEA,MAAa,qBAAqB;AAWlC,MAAM,OAAO;AAEb,MAAa,iBAAiB,SAC5B,KACG,KAAK,QAAS,KAAK,KAAK,GAAG,IAAI,MAAM,IAAI,IAAI,WAAW,KAAK,OAAO,EAAE,EAAG,CAAC,CAC1E,KAAK,GAAG;AAEb,MAAa,yBACX,UAC4B;CAC5B,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU,OAAO;CAChD,MAAM,OAAO;CACb,MAAM,WAAW,KAAK;CACtB,IACE,OAAO,aAAa,YACpB,CAAC,OAAO,UAAU,QAAQ,KAC1B,WAAW,KACX,WAAW,KAEX,OAAO;CAET,KAAK,MAAM,OAAO,CAAC,UAAU,QAAQ,GACnC,IAAI,KAAK,SAAS,KAAA,KAAa,OAAO,KAAK,SAAS,UAAU,OAAO;CAEvE,MAAM,UAAU,KAAK;CACrB,IACE,YAAY,KAAA,KACZ,EACE,MAAM,QAAQ,OAAO,KACrB,QAAQ,OACL,WACC,CAAC,CAAC,UACF,OAAO,WAAW,YAClB,OAAQ,OAA0B,SAAS,QAC/C,IAGF,OAAO;CAET,OAAO;AACT;AAEA,MAAM,aAAA;AAKN,MAAa,mBAAmB,OAC9B,UACA,MACA,gBAC8B;CAC9B,MAAM,MAAM,GAAG,iBAAiB,QAAQ,IAAI;CAC5C,IAAI;CACJ,IAAI;EACF,WAAW,MAAM,MAAM,KAAK;GAC1B,QAAQ;GACR,SAAS;IACP,gBAAgB;IAChB,GAAI,cAAc,EAAE,eAAe,UAAU,cAAc,IAAI,CAAC;GAClE;GACA,MAAM,KAAK,UAAU;IACnB,SAAS,cAAc,IAAI;IAC3B,QAAQ;KACN,MAAM;KACN,SAAS;KACT,UAAU,GAAG,QAAQ,SAAS,GAAG,QAAQ;IAC3C;GACF,CAAC;GACD,UAAU;GACV,QAAQ,YAAY,QAAQ,GAAM;EACpC,CAAC;CACH,SAAS,OAAO;EACd,MAAM,QAAS,MAAgB;EAC/B,MAAM,IAAI,MACR,mBAAmB,IAAI,IAAI,OAAO,WAAW,OAAO,QAAS,MAAgB,SAC/E;CACF;CACA,MAAM,OAAO,sBAAsB,MAAM,SAAS,KAAK,CAAC,CAAC,YAAY,IAAI,CAAC;CAC1E,IAAI,CAAC,MACH,MAAM,IAAI,MACR,4BAA4B,IAAI,IAAI,SAAS,OAAO,GAAG,SAAS,WAAW,GAC7E;CAEF,OAAO;AACT;AAIA,MAAM,kBAGF,CAAC;AAEL,MAAa,kBAAkB,OAC7B,MACA,SAOoB;CACpB,IAAI;CACJ,IAAI;EACF,WAAW,OAAO,KAAK,QAAQ,iBAAA,CAC7B,KAAK,UACL,MACA,MAAM,KAAK,YAAY,CAAC,CAAC,OAAO,UAAmB;GACjD,KAAK,OACH,GAAG,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,GAC5D;GACA,OAAO;EACT,CAAC,CACH;CACF,SAAS,OAAO;EACd,KAAK,OAAO,GAAG,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,GAAG;EACzE,OAAO;CACT;CACA,MAAM,UAAU,SAAS,SAAS,MAC/B,WAAW,CAAC,OAAO,OAAO,iBAAiB,OAAO,IAAI,CACzD;CACA,IAAI,SAAS;EACX,KAAK,OACH,gEAAgE,QAAQ,KAAK,oCAC/E;EACA,OAAO;CACT;CACA,IAAI,SAAS,QAAQ,KAAK,OAAO,SAAS,MAAM;CAChD,IAAI,SAAS,QAAQ,KAAK,OAAO,SAAS,MAAM;CAChD,KAAK,MAAM,UAAU,SAAS,WAAW,CAAC,GAAG;EAC3C,MAAM,OAAO,MAAM,gBAAgB,OAAO,KAAK,CAAE,MAAM;EACvD,IAAI,SAAS,GAAG,OAAO;CACzB;CACA,OAAO,SAAS;AAClB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-ui",
-  "version": "0.0.124",
+  "version": "0.0.126",
   "description": "CLI for assistant-ui",
   "keywords": [
     "cli",
@@ -39,20 +39,20 @@
     "glob": "^13.0.6",
     "jscodeshift": "^17.4.0",
     "jsonc-parser": "^3.3.1",
-    "react": "^19.3.0",
+    "react": "^19.3.1",
     "semver": "^7.8.5",
-    "statewire": "^0.19.4"
+    "statewire": "^0.20.0"
   },
   "devDependencies": {
-    "@assistant-ui/x-buildutils": "0.0.30",
+    "@assistant-ui/x-buildutils": "0.0.31",
     "@types/cli-progress": "^3.11.6",
     "@types/cross-spawn": "^6.0.6",
     "@types/debug": "^4.1.13",
     "@types/jscodeshift": "^17.3.0",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "@types/semver": "^7.8.0",
-    "@vitest/coverage-v8": "^5.0.3",
-    "vitest": "^5.0.3"
+    "@vitest/coverage-v8": "^5.0.5",
+    "vitest": "^5.0.5"
   },
   "publishConfig": {
     "access": "public",

package/src/codemods/v0-12/__tests__/primitive-if-to-aui-if.test.ts

@@ -969,7 +969,7 @@ function MyComponent() {
   });
 });
 
-describe("condition precedence", () => {
+describe("condition semantics", () => {
   const compileCondition = (jsx: string) => {
     const output = applyTransform(`
 import { MessagePrimitive, ComposerPrimitive } from "@assistant-ui/react";
@@ -982,6 +982,40 @@ const view = ${jsx};
     ) => boolean;
   };
 
+  it.each(["hasBranches", "lastOrHover"])(
+    "keeps %s={false} unconditional",
+    (filter) => {
+      const condition = compileCondition(
+        `<MessagePrimitive.If ${filter}={false} />`,
+      );
+
+      for (const branchCount of [1, 2]) {
+        for (const isLast of [false, true]) {
+          for (const isHovering of [false, true]) {
+            expect(
+              condition({ message: { branchCount, isLast, isHovering } }),
+            ).toBe(true);
+          }
+        }
+      }
+    },
+  );
+
+  it.each(["hasBranches", "lastOrHover"])(
+    "keeps the role filter when %s={false}",
+    (filter) => {
+      const condition = compileCondition(
+        `<MessagePrimitive.If ${filter}={false} assistant />`,
+      );
+      const message = { branchCount: 1, isLast: false, isHovering: false };
+
+      expect(condition({ message: { ...message, role: "assistant" } })).toBe(
+        true,
+      );
+      expect(condition({ message: { ...message, role: "user" } })).toBe(false);
+    },
+  );
+
   it.each([
     {
       jsx: "<MessagePrimitive.If speaking={false} />",

package/src/codemods/v0-12/primitive-if-to-aui-if.ts

@@ -42,8 +42,8 @@ const messagePropMap: Record<
     expression: `s.message.role ${v === false ? "!==" : "==="} "system"`,
     negated: false,
   }),
-  hasBranches: () => ({
-    expression: "s.message.branchCount >= 2",
+  hasBranches: (v) => ({
+    expression: v === false ? "true" : "s.message.branchCount >= 2",
     negated: false,
   }),
   copied: (v) => ({
@@ -54,8 +54,9 @@ const messagePropMap: Record<
     expression: "s.message.isLast",
     negated: v === false,
   }),
-  lastOrHover: () => ({
-    expression: "s.message.isHovering || s.message.isLast",
+  lastOrHover: (v) => ({
+    expression:
+      v === false ? "true" : "s.message.isHovering || s.message.isLast",
     negated: false,
   }),
   speaking: (v) => ({

package/src/commands/cloud.test.ts

@@ -9,6 +9,9 @@ const {
   fetchProjects,
   createProject,
   cloudAccessToken,
+  savedCloudAccessToken,
+  runCloudCommand,
+  loginToCloud,
   provisionCloudHarness,
   scaffold,
   select,
@@ -18,6 +21,9 @@ const {
   fetchProjects: vi.fn(),
   createProject: vi.fn(),
   cloudAccessToken: vi.fn(),
+  savedCloudAccessToken: vi.fn(),
+  runCloudCommand: vi.fn(),
+  loginToCloud: vi.fn(),
   provisionCloudHarness: vi.fn(),
   scaffold: vi.fn(),
   select: vi.fn(),
@@ -33,6 +39,12 @@ vi.mock("aui-auth/accounts", async (importOriginal) => ({
 vi.mock("../lib/cloud-auth", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../lib/cloud-auth")>()),
   cloudAccessToken,
+  savedCloudAccessToken,
+  loginToCloud,
+}));
+vi.mock("../lib/cloud-remote", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/cloud-remote")>()),
+  runCloudCommand,
 }));
 vi.mock("../lib/cloud-provision", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../lib/cloud-provision")>()),
@@ -236,3 +248,49 @@ describe("cloud setup", () => {
     ]);
   });
 });
+
+describe("cloud remote forwarding", () => {
+  const forwarded = async (argv: string[]) => {
+    runCloudCommand.mockClear();
+    runCloudCommand.mockResolvedValue(4);
+    await cloud.parseAsync(argv, { from: "user" });
+    return runCloudCommand.mock.calls.map(([args]) => args);
+  };
+
+  it("forwards help, unknown subcommands and their flags verbatim", async () => {
+    for (const argv of [
+      [],
+      ["help"],
+      ["--help"],
+      ["-h"],
+      ["help", "projects"],
+      ["projects", "list", "--org", "acme", "--json"],
+      ["whoami", "--version"],
+      ["--org=acme", "projects"],
+    ]) {
+      await expect(forwarded(argv)).resolves.toEqual([argv]);
+    }
+    expect(process.exitCode).toBe(4);
+    process.exitCode = undefined;
+  });
+
+  it("keeps login local", async () => {
+    loginToCloud.mockResolvedValue(undefined);
+    await expect(forwarded(["login", "--no-open"])).resolves.toEqual([]);
+    expect(loginToCloud).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ noOpen: true }),
+    );
+  });
+
+  it("sends the saved login without starting a new one", async () => {
+    savedCloudAccessToken.mockResolvedValue(null);
+    runCloudCommand.mockImplementationOnce(async (_args, options) => {
+      await expect(options.accessToken()).resolves.toBeNull();
+      return 0;
+    });
+    await cloud.parseAsync(["whoami"], { from: "user" });
+    expect(savedCloudAccessToken).toHaveBeenCalled();
+    expect(cloudAccessToken).not.toHaveBeenCalled();
+  });
+});

package/src/commands/cloud.ts

@@ -15,8 +15,10 @@ import {
   cloudAuthConfig,
   loginToCloud,
   logoutFromCloud,
+  savedCloudAccessToken,
   validateCloudUrl,
 } from "../lib/cloud-auth";
+import { runCloudCommand } from "../lib/cloud-remote";
 import {
   readCloudProjectConfig,
   mergeCloudEnvironment,
@@ -370,9 +372,24 @@ export const setupCloud = async (
   );
 };
 
+const DEFAULT_CLOUD_URL = "https://cloud.assistant-ui.com";
+
 export const cloud = new Command()
   .name("cloud")
-  .description("sign in and set up a multiplayer Assistant Cloud chat")
+  .description("manage Assistant Cloud (run `assistant-ui cloud help`)")
+  .helpOption(false)
+  .helpCommand(false)
+  .argument("[command...]")
+  .allowUnknownOption()
+  .allowExcessArguments()
+  .action(async (args: string[]) => {
+    process.exitCode = await runCloudCommand(args, {
+      cloudUrl: process.env.ASSISTANT_UI_CLOUD_URL ?? DEFAULT_CLOUD_URL,
+      accessToken: () => savedCloudAccessToken(cloudAuthConfig()),
+      stdout: (text) => process.stdout.write(text),
+      stderr: (text) => process.stderr.write(text),
+    });
+  })
   .addCommand(
     new Command("login")
       .description("sign in to Assistant Cloud using your browser")
@@ -418,7 +435,7 @@ export const cloud = new Command()
       .option(
         "--api-url <url>",
         "Assistant Cloud management URL",
-        process.env.ASSISTANT_UI_CLOUD_URL ?? "https://cloud.assistant-ui.com",
+        process.env.ASSISTANT_UI_CLOUD_URL ?? DEFAULT_CLOUD_URL,
       )
       .option(
         "--access-code <code>",

package/src/commands/info.ts

@@ -38,6 +38,8 @@ const ASSISTANT_UI_PACKAGES = [
   "@assistant-ui/react-lexical",
   "@assistant-ui/react-syntax-highlighter",
   "@assistant-ui/react-hook-form",
+  "safe-content-frame",
+  "tw-shimmer",
   // Observability & DevTools
   "@assistant-ui/react-o11y",
   "@assistant-ui/react-devtools",
@@ -50,6 +52,7 @@ const ECOSYSTEM_PACKAGES = [
   "next",
   "vite",
   "expo",
+  "tailwindcss",
   "ai",
   "zod",
   "zustand",
@@ -112,6 +115,24 @@ function getAssistantUiPackageNames(
   return [...new Set([...ASSISTANT_UI_PACKAGES, ...declaredPackages])];
 }
 
+// Adapters peer on the provider SDK they wrap, so the installed packages
+// name the upstream versions a bug report needs.
+function getEcosystemPackageNames(
+  packages: PackageInfo[],
+  cwd: string,
+): string[] {
+  const upstreamPeers = packages
+    .flatMap((pkg) => Object.keys(getPeerDeps(pkg.name, cwd) ?? {}))
+    .filter(
+      (name) =>
+        !name.startsWith("@assistant-ui/") &&
+        !ASSISTANT_UI_PACKAGES.includes(name),
+    )
+    .sort();
+
+  return [...new Set([...ECOSYSTEM_PACKAGES, ...upstreamPeers])];
+}
+
 function getSpecifiedRange(
   pkg: string,
   projectPkg: Record<string, unknown>,
@@ -312,7 +333,11 @@ async function collectInfo(
     cwd,
     projectPkg,
   );
-  const ecosystem = collectPackages(ECOSYSTEM_PACKAGES, cwd, projectPkg);
+  const ecosystem = collectPackages(
+    getEcosystemPackageNames(packages, cwd),
+    cwd,
+    projectPkg,
+  );
   const warnings = collectWarnings(packages, cwd, projectPkg);
 
   return {

package/src/lib/cloud-auth.ts

@@ -230,16 +230,11 @@ export const loginToCloud = async (
   }
 };
 
-export const cloudAccessToken = async (
+export const savedCloudAccessToken = async (
   config: CloudAuthConfig,
-  options: {
-    noOpen?: boolean;
-    setupUrl?: string;
-    print?: (text: string) => void;
-  } = {},
-): Promise<string> => {
+): Promise<string | null> => {
   const saved = await readCloudCredentials(config);
-  if (!saved) return (await loginToCloud(config, options)).tokens.accessToken;
+  if (!saved) return null;
   const login = createDeviceLogin({
     issuer: config.issuer,
     clientId: config.clientId,
@@ -259,6 +254,17 @@ export const cloudAccessToken = async (
   }
 };
 
+export const cloudAccessToken = async (
+  config: CloudAuthConfig,
+  options: {
+    noOpen?: boolean;
+    setupUrl?: string;
+    print?: (text: string) => void;
+  } = {},
+): Promise<string> =>
+  (await savedCloudAccessToken(config)) ??
+  (await loginToCloud(config, options)).tokens.accessToken;
+
 export const logoutFromCloud = async (
   config: CloudAuthConfig,
 ): Promise<void> => {

package/src/lib/cloud-remote.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  joinCloudArgs,
+  parseCloudCliResponse,
+  runCloudCommand,
+  sendCloudCommand,
+  type CloudCliResponse,
+} from "./cloud-remote";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+const harness = (reply: CloudCliResponse, token: string | null = "token") => {
+  const output = { stdout: "", stderr: "" };
+  const send = vi.fn(async () => reply);
+  return {
+    output,
+    send,
+    run: (args: string[]) =>
+      runCloudCommand(args, {
+        cloudUrl: "https://cloud.example.com",
+        accessToken: async () => token,
+        stdout: (text) => {
+          output.stdout += text;
+        },
+        stderr: (text) => {
+          output.stderr += text;
+        },
+        send,
+      }),
+  };
+};
+
+describe("cloud remote commands", () => {
+  it("quotes arguments so a POSIX shell split gives them back", () => {
+    expect(
+      joinCloudArgs(["projects", "list", "--org", "my org", "it's", ""]),
+    ).toBe(`projects list --org 'my org' 'it'\\''s' ''`);
+  });
+
+  it("prints the envelope and exits with its code", async () => {
+    const { run, send, output } = harness({
+      stdout: "out\n",
+      stderr: "err\n",
+      exitCode: 3,
+    });
+    await expect(run(["whoami"])).resolves.toBe(3);
+    expect(send).toHaveBeenCalledWith(
+      "https://cloud.example.com",
+      ["whoami"],
+      "token",
+    );
+    expect(output).toEqual({ stdout: "out\n", stderr: "err\n" });
+  });
+
+  it("fails an action it does not know before printing anything", async () => {
+    const { run, output } = harness({
+      stdout: "uploading\n",
+      exitCode: 0,
+      actions: [{ type: "upload", arg: 2 }],
+    });
+    await expect(run(["files", "push", "a.txt"])).resolves.toBe(1);
+    expect(output.stdout).toBe("");
+    expect(output.stderr).toMatch(/newer assistant-ui.*"upload"/);
+  });
+
+  it("prints a failed request as one line and exits 1", async () => {
+    const { run, send, output } = harness({ exitCode: 0 });
+    send.mockRejectedValueOnce(new Error("Could not reach the cloud"));
+    await expect(run(["whoami"])).resolves.toBe(1);
+    expect(output.stderr).toBe("Could not reach the cloud\n");
+  });
+
+  it("sends anonymously when the saved login cannot be read", async () => {
+    const output = { stdout: "", stderr: "" };
+    const send = vi.fn(async () => ({ stdout: "help\n", exitCode: 0 }));
+    await expect(
+      runCloudCommand(["help"], {
+        cloudUrl: "https://cloud.example.com",
+        accessToken: async () => {
+          throw new Error("Invalid saved login.");
+        },
+        stdout: (text) => {
+          output.stdout += text;
+        },
+        stderr: (text) => {
+          output.stderr += text;
+        },
+        send,
+      }),
+    ).resolves.toBe(0);
+    expect(send).toHaveBeenCalledWith(
+      "https://cloud.example.com",
+      ["help"],
+      null,
+    );
+    expect(output).toEqual({
+      stdout: "help\n",
+      stderr: "Invalid saved login.\n",
+    });
+  });
+
+  it("accepts only a well-formed envelope", () => {
+    expect(parseCloudCliResponse({ stdout: "x", exitCode: 0 })).toEqual({
+      stdout: "x",
+      exitCode: 0,
+    });
+    for (const bad of [
+      null,
+      "text",
+      { stdout: "x" },
+      { exitCode: 1.5 },
+      { exitCode: 256 },
+      { exitCode: -1 },
+      { exitCode: 0, stderr: 3 },
+      { exitCode: 0, actions: [{}] },
+    ]) {
+      expect(parseCloudCliResponse(bad)).toBeNull();
+    }
+  });
+
+  it("posts the command string, client and bearer token", async () => {
+    const fetchMock = vi.fn(async () =>
+      Response.json({ stdout: "ok\n", exitCode: 0 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    await expect(
+      sendCloudCommand("https://cloud.example.com/", ["help", "a b"], "tok"),
+    ).resolves.toEqual({ stdout: "ok\n", exitCode: 0 });
+    const [url, init] = fetchMock.mock.calls[0] as unknown as [
+      string,
+      RequestInit,
+    ];
+    expect(url).toBe("https://cloud.example.com/api/cli/run");
+    expect(init.headers).toMatchObject({ Authorization: "Bearer tok" });
+    expect(JSON.parse(init.body as string)).toMatchObject({
+      command: "help 'a b'",
+      client: { name: "assistant-ui" },
+    });
+  });
+
+  it("sends no Authorization header when signed out and rejects a non-envelope", async () => {
+    const fetchMock = vi.fn(
+      async () => new Response("<html>", { status: 502 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    await expect(
+      sendCloudCommand("https://cloud.example.com", ["help"], null),
+    ).rejects.toThrow(/Unexpected response .*502/);
+    const init = (
+      fetchMock.mock.calls[0] as unknown as [string, RequestInit]
+    )[1];
+    expect(init.headers).not.toHaveProperty("Authorization");
+  });
+});