@trycua/cua 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import { Container, CuaConfig, type CuaLike, type FleetLike, type FleetPool, PoolOptions, ReadinessProbe, RegistrySecret, type ResolvedImage, SandboxSpec } from "./native/index.js";
+export * from "./native/index.js";
+export { connectMcp, mcpHeaders, type McpEndpointConfig } from "./mcp.js";
+/**
+ * The qualified refs (`local:box`, `cloud:box`) a `CuaError.AmbiguousSandbox`
+ * lists: a bare sandbox name that matches sandboxes in more than one
+ * location. Empty for any other error.
+ */
+export declare function ambiguousCandidates(error: unknown): string[];
+/**
+ * The link to a `CuaError`'s entry (cause and fix) on the errors
+ * reference; `undefined` for any other value. Every `CuaError` also carries
+ * it as `docUrl`.
+ */
+export declare function cuaErrorDocUrl(error: unknown): string | undefined;
+/**
+ * An SDK runtime in this process (no I/O until the first call). Fleet uses
+ * `CUA_CLIENT_ID`/`CUA_CLIENT_SECRET` (or `FLEETS_TOKEN`); pass
+ * `fleetFromSession: true` to fall back to the `cua auth login` session.
+ */
+export declare function embedded(config?: Partial<CuaConfig>): CuaLike;
+/** A client of a running `cua daemon` (socket path or loopback URL). */
+export declare function connect(address?: string, token?: string): CuaLike;
+/** An image tier: `slim`, `full` (the default), or on macOS `xcode` / `xcode-<X.Y>`. */
+export type ImageTier = "slim" | "full" | "xcode" | `xcode-${string}`;
+/** Options for `Image.linux()` / `windows()` / `macos()`. */
+export interface ImageOptions {
+    version?: string;
+    tier?: ImageTier;
+}
+/**
+ * Canonical images: `Image.linux()` is `ghcr.io/trycua/linux:24.04`
+ * (`CUA_IMAGE_LINUX` overrides it), `Image.windows()`
+ * `ghcr.io/trycua/windows:2022`, `Image.macos()` `ghcr.io/trycua/macos:26`.
+ * These are the full tier (dev tooling); `{ tier: "slim" }` is the minimal
+ * image CI runs and, on macOS, `{ tier: "xcode" }` adds a pinned Xcode.
+ * `Image.omarchy()` is `ghcr.io/trycua/omarchy:edge`, an amd64 VM. Images CI
+ * has not published yet throw `ImageNotPublished`; pass the reference to
+ * `fromRegistry` to use one anyway.
+ * `Image.resolve(ref, backend)` is the one resolver: the digest-pinned
+ * variant a backend runs (rootfs, the `-disk` containerDisk, Lume).
+ */
+export declare const Image: {
+    linux: (version?: string | ImageOptions, tier?: ImageTier) => string;
+    windows: (version?: string | ImageOptions, tier?: ImageTier) => string;
+    macos: (version?: string | ImageOptions, tier?: ImageTier) => string;
+    /** Omarchy (Arch Linux, Hyprland) with cua-spacesd: an amd64 VM. */
+    omarchy: (channel?: string) => string;
+    fromRegistry: (reference: string) => string;
+    resolve: (reference: string, backend?: string, arch?: string) => ResolvedImage;
+};
+/** Ready once a TCP connect to the declared `service` succeeds. */
+export declare function tcp(service: string): ReadinessProbe;
+/** Ready once `GET path` on the declared `service` returns 2xx. */
+export declare function http(service: string, path?: string): ReadinessProbe;
+/**
+ * A sidecar container, addressed by name on every runtime: the sandbox
+ * reaches it at its `name` (and on `localhost` where they share a network
+ * namespace), it reaches the sandbox at `main`, and `services` may name its
+ * ports. Local containers (with `runtime: "runc"`) and every cloud sandbox;
+ * local VM sandboxes refuse sidecars. With sidecars the service names
+ * `main`, `sidecars` and `sc` are reserved.
+ *
+ * ```ts
+ * SandboxCreateOptions.create({ image: "python:3.12-slim",
+ *   sidecars: [sidecar("redis:7-alpine", { ports: [6379] })],
+ *   services: new Map([["db", 6379]]) })
+ * ```
+ */
+export declare function sidecar(image: string, opts?: {
+    command?: string[];
+    env?: Record<string, string>;
+    ports?: number[];
+    name?: string;
+}): Container;
+/**
+ * Credentials for a private registry image (`registrySecret` on
+ * `SandboxCreateOptions`). Locally they authenticate the pull; in the cloud
+ * the SDK stores them as the sandbox's registry pull secret. Never logged.
+ */
+export declare const registrySecret: {
+    /** A user name and password (or token). */
+    basic: (username: string, password: string, registry?: string) => RegistrySecret;
+    /** Read from environment variables at create time. */
+    fromEnv: (usernameVar?: string, passwordVar?: string, registry?: string) => RegistrySecret;
+    /** A private Amazon ECR image: a login token from the AWS CLI. */
+    awsEcr: (region?: string) => RegistrySecret;
+};
+type StringMap = Record<string, string> | Map<string, string>;
+type PortMap = Record<string, number> | Map<string, number>;
+/**
+ * What a sandbox runs: the one model behind `Sandbox.create`, managed pools
+ * and `fleet.apply(name, spec, options)`. `env` and `services` take plain
+ * objects too. Unset fields keep Fleet's defaults (and are not compared by
+ * `fleet.checkPoolSpec`).
+ *
+ * ```ts
+ * const spec = sandboxSpec("python:3.12-slim", {
+ *   command: ["python", "-m", "srv"], services: { mcp: 8765 }, readiness: http("mcp", "/health") })
+ * await c.fleet().apply("my-pool", spec, poolOptions({ warm: true, idleTtlSeconds: 3600 }))
+ * ```
+ */
+export declare function sandboxSpec(image: string, opts?: Partial<Omit<SandboxSpec, "image" | "env" | "services">> & {
+    env?: StringMap;
+    services?: PortMap;
+}): SandboxSpec;
+/** How a pool keeps capacity for a `SandboxSpec` (warm floor, size, TTLs, runtime). */
+export declare function poolOptions(opts?: Partial<PoolOptions>): PoolOptions;
+/**
+ * `Pool.apply(fleet, name, spec, options)`: the one pool writer, the same
+ * call as `fleet.apply`. Named pools are compared against a spec with
+ * `fleet.checkPoolSpec` (raises `CuaError.PoolSpecMismatch` with a diff) and
+ * updated with `fleet.applyPoolTemplate`; `fleet.exportPool(name).terraform`
+ * prints the equivalent `fleets_pool` block.
+ */
+export declare const Pool: {
+    apply: (fleet: FleetLike, name: string, spec: SandboxSpec, options?: PoolOptions) => Promise<FleetPool>;
+};

package/dist/index.js

@@ -0,0 +1,207 @@
+/**
+ * The cua SDK for Node: a generated binding over the Rust `cua-sdk` crate.
+ *
+ * ```ts
+ * import { embedded, SandboxCreateOptions, http } from "@trycua/cua"
+ * const cua = embedded()
+ * const sb = await cua.sandboxes().create(SandboxCreateOptions.create({
+ *   on: "local",                                // or "cloud"; kind / runtime: "auto" by default
+ *   image: "python:3.12-slim",
+ *   command: ["python", "-m", "my_mcp", "--port", "8765"],
+ *   services: new Map([["mcp", 8765]]),
+ *   waitFor: [http("mcp", "/health")],
+ * }))
+ * const r = await sb.service("mcp").request("POST", "/mcp", body, undefined, headers)
+ * const url = await sb.service("mcp").url()           // usable from this machine
+ * const share = await sb.publicUrl("mcp", 3600, undefined)  // shareable, expires
+ * ```
+ *
+ * The same objects work against a running `cua daemon` (`connect()`).
+ * Browser builds use `@trycua/cua/browser` (env over gRPC-Web + Fleet).
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { Container, Cua, CuaConfig, CuaError, CuaError_Tags, PoolOptions, ReadinessProbe, RegistrySecret, SandboxSpec, ambiguousSandboxCandidates, canonicalImageTier, errorDocUrl, omarchyImage, resolveImage, cuaSdkVersion, telemetrySetSurface, } from "./native/index.js";
+export * from "./native/index.js";
+export { connectMcp, mcpHeaders } from "./mcp.js";
+// Usage telemetry (anonymous, content-free; https://cua.ai/docs/cua-sdk/concepts/telemetry)
+// attributes events to this binding. It sends nothing by itself; off with
+// DO_NOT_TRACK=1, CUA_TELEMETRY=0 or `telemetrySetEnabled(false)`.
+try {
+    telemetrySetSurface("sdk_typescript", cuaSdkVersion());
+}
+catch {
+    // Telemetry never fails an import.
+}
+/**
+ * The qualified refs (`local:box`, `cloud:box`) a `CuaError.AmbiguousSandbox`
+ * lists: a bare sandbox name that matches sandboxes in more than one
+ * location. Empty for any other error.
+ */
+export function ambiguousCandidates(error) {
+    if (!CuaError.AmbiguousSandbox.instanceOf(error))
+        return [];
+    return ambiguousSandboxCandidates(String(error.message ?? error));
+}
+/**
+ * The link to a `CuaError`'s entry (cause and fix) on the errors
+ * reference; `undefined` for any other value. Every `CuaError` also carries
+ * it as `docUrl`.
+ */
+export function cuaErrorDocUrl(error) {
+    if (!CuaError.instanceOf(error))
+        return undefined;
+    return errorDocUrl(String(error.tag ?? ""));
+}
+// `docUrl` on every CuaError variant (a getter on each variant class).
+for (const tag of Object.values(CuaError_Tags)) {
+    const variant = CuaError[tag];
+    if (variant && !Object.prototype.hasOwnProperty.call(variant.prototype, "docUrl")) {
+        Object.defineProperty(variant.prototype, "docUrl", {
+            get() {
+                return errorDocUrl(String(this.tag ?? ""));
+            },
+            configurable: true,
+        });
+    }
+}
+/**
+ * Points `CUA_BIN` at the CLI of the matching `@trycua/cua-<platform>`
+ * package, so the SDK can start the cua daemon (which serves local public
+ * URLs) on demand. An explicit `CUA_BIN` wins.
+ */
+function defaultCuaBin() {
+    if (process.env.CUA_BIN)
+        return;
+    const arch = process.arch;
+    const triple = process.platform === "linux"
+        ? `linux-${arch}-gnu`
+        : process.platform === "win32"
+            ? `win32-${arch}-msvc`
+            : `${process.platform}-${arch}`;
+    try {
+        const require = createRequire(import.meta.url);
+        const exe = process.platform === "win32" ? "cua.exe" : "cua";
+        const bin = join(dirname(require.resolve(`@trycua/cua-${triple}/package.json`)), exe);
+        if (existsSync(bin))
+            process.env.CUA_BIN = bin;
+    }
+    catch {
+        // No platform package: the SDK looks for `cua` on PATH.
+    }
+}
+/**
+ * An SDK runtime in this process (no I/O until the first call). Fleet uses
+ * `CUA_CLIENT_ID`/`CUA_CLIENT_SECRET` (or `FLEETS_TOKEN`); pass
+ * `fleetFromSession: true` to fall back to the `cua auth login` session.
+ */
+export function embedded(config = {}) {
+    defaultCuaBin();
+    return Cua.embedded(CuaConfig.create(config));
+}
+/** A client of a running `cua daemon` (socket path or loopback URL). */
+export function connect(address, token) {
+    return Cua.connect(address, token);
+}
+function tierImage(os, version, tier) {
+    const o = typeof version === "object" ? version : { version, tier };
+    return canonicalImageTier(os, o.version, o.tier);
+}
+/**
+ * Canonical images: `Image.linux()` is `ghcr.io/trycua/linux:24.04`
+ * (`CUA_IMAGE_LINUX` overrides it), `Image.windows()`
+ * `ghcr.io/trycua/windows:2022`, `Image.macos()` `ghcr.io/trycua/macos:26`.
+ * These are the full tier (dev tooling); `{ tier: "slim" }` is the minimal
+ * image CI runs and, on macOS, `{ tier: "xcode" }` adds a pinned Xcode.
+ * `Image.omarchy()` is `ghcr.io/trycua/omarchy:edge`, an amd64 VM. Images CI
+ * has not published yet throw `ImageNotPublished`; pass the reference to
+ * `fromRegistry` to use one anyway.
+ * `Image.resolve(ref, backend)` is the one resolver: the digest-pinned
+ * variant a backend runs (rootfs, the `-disk` containerDisk, Lume).
+ */
+export const Image = {
+    linux: (version, tier) => tierImage("linux", version, tier),
+    windows: (version, tier) => tierImage("windows", version, tier),
+    macos: (version, tier) => tierImage("macos", version, tier),
+    /** Omarchy (Arch Linux, Hyprland) with cua-spacesd: an amd64 VM. */
+    omarchy: (channel) => omarchyImage(channel),
+    // Literal: `ubuntu:24.04` is docker.io/library/ubuntu:24.04.
+    fromRegistry: (reference) => reference,
+    resolve: (reference, backend = "local", arch) => resolveImage(reference, backend, arch),
+};
+/** Ready once a TCP connect to the declared `service` succeeds. */
+export function tcp(service) {
+    return ReadinessProbe.create({ service });
+}
+/** Ready once `GET path` on the declared `service` returns 2xx. */
+export function http(service, path = "/") {
+    return ReadinessProbe.create({ service, httpPath: path });
+}
+/**
+ * A sidecar container, addressed by name on every runtime: the sandbox
+ * reaches it at its `name` (and on `localhost` where they share a network
+ * namespace), it reaches the sandbox at `main`, and `services` may name its
+ * ports. Local containers (with `runtime: "runc"`) and every cloud sandbox;
+ * local VM sandboxes refuse sidecars. With sidecars the service names
+ * `main`, `sidecars` and `sc` are reserved.
+ *
+ * ```ts
+ * SandboxCreateOptions.create({ image: "python:3.12-slim",
+ *   sidecars: [sidecar("redis:7-alpine", { ports: [6379] })],
+ *   services: new Map([["db", 6379]]) })
+ * ```
+ */
+export function sidecar(image, opts = {}) {
+    return Container.create({
+        image,
+        env: new Map(Object.entries(opts.env ?? {})),
+        ports: opts.ports ?? [],
+        ...(opts.command ? { command: opts.command } : {}),
+        ...(opts.name ? { name: opts.name } : {}),
+    });
+}
+/**
+ * Credentials for a private registry image (`registrySecret` on
+ * `SandboxCreateOptions`). Locally they authenticate the pull; in the cloud
+ * the SDK stores them as the sandbox's registry pull secret. Never logged.
+ */
+export const registrySecret = {
+    /** A user name and password (or token). */
+    basic: (username, password, registry) => new RegistrySecret.Basic({ username, password, ...(registry ? { registry } : {}) }),
+    /** Read from environment variables at create time. */
+    fromEnv: (usernameVar = "CUA_REGISTRY_USERNAME", passwordVar = "CUA_REGISTRY_PASSWORD", registry) => new RegistrySecret.FromEnv({ usernameVar, passwordVar, ...(registry ? { registry } : {}) }),
+    /** A private Amazon ECR image: a login token from the AWS CLI. */
+    awsEcr: (region) => new RegistrySecret.AwsEcr(region ? { region } : {}),
+};
+const toMap = (m) => m instanceof Map ? new Map(m) : new Map(Object.entries(m ?? {}));
+/**
+ * What a sandbox runs: the one model behind `Sandbox.create`, managed pools
+ * and `fleet.apply(name, spec, options)`. `env` and `services` take plain
+ * objects too. Unset fields keep Fleet's defaults (and are not compared by
+ * `fleet.checkPoolSpec`).
+ *
+ * ```ts
+ * const spec = sandboxSpec("python:3.12-slim", {
+ *   command: ["python", "-m", "srv"], services: { mcp: 8765 }, readiness: http("mcp", "/health") })
+ * await c.fleet().apply("my-pool", spec, poolOptions({ warm: true, idleTtlSeconds: 3600 }))
+ * ```
+ */
+export function sandboxSpec(image, opts = {}) {
+    const { env, services, ...rest } = opts;
+    return SandboxSpec.create({ ...rest, image, env: toMap(env), services: toMap(services) });
+}
+/** How a pool keeps capacity for a `SandboxSpec` (warm floor, size, TTLs, runtime). */
+export function poolOptions(opts = {}) {
+    return PoolOptions.create(opts);
+}
+/**
+ * `Pool.apply(fleet, name, spec, options)`: the one pool writer, the same
+ * call as `fleet.apply`. Named pools are compared against a spec with
+ * `fleet.checkPoolSpec` (raises `CuaError.PoolSpecMismatch` with a diff) and
+ * updated with `fleet.applyPoolTemplate`; `fleet.exportPool(name).terraform`
+ * prints the equivalent `fleets_pool` block.
+ */
+export const Pool = {
+    apply: (fleet, name, spec, options = poolOptions()) => fleet.apply(name, spec, options),
+};

package/dist/mcp.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP servers inside a sandbox, with the official TypeScript SDK
+ * (`@modelcontextprotocol/client`, an optional peer dependency).
+ *
+ * cua does not implement MCP: `sandbox.mcpConfig(service)` returns the
+ * endpoint URL and the headers its route needs (nothing locally; the Fleet
+ * gateway bearer and claim in the cloud; the daemon bearer through
+ * `cua daemon`), and `connectMcp` hands that to the SDK's streamable-HTTP
+ * transport, so every protocol revision and content block works unchanged.
+ *
+ * ```ts
+ * const client = await connectMcp(await sb.mcpConfig("mcp", undefined))
+ * const result = await client.callTool({ name: "add", arguments: { a: 2, b: 3 } })
+ * ```
+ */
+/** Where an MCP endpoint is: `Sandbox.mcpConfig()` returns one. */
+export interface McpEndpointConfig {
+    url: string;
+    headers: Array<{
+        name: string;
+        value: string;
+    }> | Record<string, string>;
+}
+/** The headers as a plain object. */
+export declare function mcpHeaders(config: McpEndpointConfig): Record<string, string>;
+/**
+ * Connects the official SDK's `Client` to `config` over streamable HTTP.
+ * Fleet bearers are short-lived: fetch a fresh config per connection.
+ */
+export declare function connectMcp(config: McpEndpointConfig, clientInfo?: {
+    name: string;
+    version: string;
+}): Promise<any>;

package/dist/mcp.js

@@ -0,0 +1,41 @@
+/**
+ * MCP servers inside a sandbox, with the official TypeScript SDK
+ * (`@modelcontextprotocol/client`, an optional peer dependency).
+ *
+ * cua does not implement MCP: `sandbox.mcpConfig(service)` returns the
+ * endpoint URL and the headers its route needs (nothing locally; the Fleet
+ * gateway bearer and claim in the cloud; the daemon bearer through
+ * `cua daemon`), and `connectMcp` hands that to the SDK's streamable-HTTP
+ * transport, so every protocol revision and content block works unchanged.
+ *
+ * ```ts
+ * const client = await connectMcp(await sb.mcpConfig("mcp", undefined))
+ * const result = await client.callTool({ name: "add", arguments: { a: 2, b: 3 } })
+ * ```
+ */
+/** The headers as a plain object. */
+export function mcpHeaders(config) {
+    if (Array.isArray(config.headers)) {
+        return Object.fromEntries(config.headers.map((h) => [h.name, h.value]));
+    }
+    return { ...config.headers };
+}
+/**
+ * Connects the official SDK's `Client` to `config` over streamable HTTP.
+ * Fleet bearers are short-lived: fetch a fresh config per connection.
+ */
+export async function connectMcp(config, clientInfo = { name: "cua", version: "0" }) {
+    let sdk;
+    try {
+        sdk = await import("@modelcontextprotocol/client");
+    }
+    catch (error) {
+        throw new Error("connectMcp needs the official MCP SDK: npm install @modelcontextprotocol/client", { cause: error });
+    }
+    const transport = new sdk.StreamableHTTPClientTransport(new URL(config.url), {
+        requestInit: { headers: mcpHeaders(config) },
+    });
+    const client = new sdk.Client(clientInfo);
+    await client.connect(transport);
+    return client;
+}