withruntime 0.33.3 → 0.35.0

package/dist/products/desktops.js

@@ -0,0 +1,27 @@
+import { enc, resource } from "./resources.js";
+/** A wait ends at its target or at one of these, with the desktop's error. */
+const SETTLED = ["failed", "deleted"];
+export function desktops(t) {
+    return {
+        ...resource(t, "desktops", SETTLED),
+        /** The screen as PNG (or JPEG) bytes. A write: it runs in the desktop's
+         * sandbox and wakes a paused one, so a read-only key is refused it. */
+        screenshot(id, shot = {}, options) {
+            return t.bytes({
+                method: "POST",
+                path: `/v1/desktops/${enc(id)}:screenshot`,
+                body: shot,
+                ...options,
+            });
+        },
+        /** Move, click, drag, scroll, type, press keys, open a URL or launch a program. */
+        act(id, step, options) {
+            return t.json({
+                method: "POST",
+                path: `/v1/desktops/${enc(id)}:act`,
+                body: step,
+                ...options,
+            });
+        },
+    };
+}

package/dist/products/functions.d.ts

@@ -0,0 +1,2 @@
+export { functions } from "./apps.js";
+export type { CreateFunction, RuntimeFunction, UpdateFunction } from "./apps.js";

package/dist/products/functions.js

@@ -0,0 +1,5 @@
+/* runtime.functions: Apps whose copies all sleep when idle, on the same
+ * calls under /v1/functions (apps.ts holds both kinds). A private beta
+ * (PRODUCT_BETAS): an account outside it is refused with product_in_beta
+ * until Functions launches. */
+export { functions } from "./apps.js";

package/dist/products/index.d.ts

@@ -27,7 +27,10 @@ import { agents } from "./agents.js";
 import { builds } from "./builds.js";
 import { ci } from "./ci.js";
 import { containers } from "./containers.js";
+import { browsers } from "./browsers.js";
+import { desktops } from "./desktops.js";
 import { apps } from "./apps.js";
+import { functions } from "./functions.js";
 export declare const clientExtensions: {
     images: typeof images;
     volumes: typeof volumes;
@@ -54,7 +57,10 @@ export declare const clientExtensions: {
     builds: typeof builds;
     ci: typeof ci;
     containers: typeof containers;
+    browsers: typeof browsers;
+    desktops: typeof desktops;
     apps: typeof apps;
+    functions: typeof functions;
 };
 export declare const sandboxExtensions: {
     interpreter: typeof sandboxInterpreter;

package/dist/products/index.js

@@ -25,11 +25,14 @@ import { agents } from "./agents.js";
 import { builds } from "./builds.js";
 import { ci } from "./ci.js";
 import { containers } from "./containers.js";
+import { browsers } from "./browsers.js";
+import { desktops } from "./desktops.js";
 // The hub loads this file, so it loads apps.ts and resources.ts too: request
 // builders over Transport whose top level holds only types, functions and
 // imports of files the hub loads, so importing them runs nothing in the hub
 // (agents/hub-sdk-products.test.ts parses every product file the hub loads).
 import { apps } from "./apps.js";
+import { functions } from "./functions.js";
 /* HOW A LANE ADDS A PRODUCT TO THE SDK
  *
  * 1. Write src/products/<name>.ts exporting a factory:
@@ -73,9 +76,14 @@ export const clientExtensions = {
     // CI/CD (beta): the API answers product_in_beta outside its list.
     ci,
     containers,
+    // Browsers and Desktops (beta): the API answers product_in_beta outside its list.
+    browsers,
+    desktops,
     // A private beta (PRODUCT_BETAS): an account outside it is refused with
     // product_in_beta until Apps launches.
     apps,
+    // The same until Functions launches.
+    functions,
 };
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,

package/dist/products/network.d.ts

@@ -2,9 +2,11 @@ import type { Sandbox } from "../sandbox.js";
 import type { RequestOptions, Transport } from "../transport.js";
 /** A sandbox's own network rules. */
 export type NetworkRules = {
-    /** false refuses every outbound connection. */
+    /** false refuses every outbound connection; with `allow`, everything but the
+     * list (allow-list only, stored as `internet: true` with that list). */
     internet: boolean;
-    /** When not empty, only these web destinations are reachable: `example.com`,
+    /** When not empty, only these web destinations are reachable, the internet on
+     * or off: `example.com`,
      * `*.example.com` (subdomains, not the apex), an address or a CIDR range. */
     allow?: string[];
     /** Never reachable. Wins over everything. */

package/dist/products/secrets.d.ts

@@ -171,6 +171,13 @@ export type JobSecret = {
 /** One secret by name, and where its value may go: to sandboxes through the
  * egress proxy (`sandboxes`), into scheduled jobs' environments (`jobs`), or
  * both. */
+/** A page of `secrets.list`: at most `limit` (1 to 100, default 50) secrets,
+ * by name, those named after `after`. The next page's `after` is the last
+ * name of this one; a page shorter than `limit` is the last. */
+export type ListSecrets = {
+    limit?: number;
+    after?: string;
+};
 export type SecretUse = {
     name: string;
     sandboxes: Secret | null;
@@ -219,8 +226,9 @@ export declare function secrets(t: Transport): {
         enforced: boolean;
     }>;
     /** The sandboxes' secrets: names, hosts and placeholders. Never values.
-     * `all()` includes the jobs copies. */
-    list: (options?: RequestOptions) => Promise<Secret[]>;
+     * `list({ limit, after })` gives one page, by name; `all()` includes
+     * the jobs copies. */
+    list: (query?: ListSecrets & RequestOptions) => Promise<Secret[]>;
     /** Every secret by name, with where its value may go. */
     all: (options?: RequestOptions) => Promise<SecretUse[]>;
     /** One secret by name, with where its value may go. */

package/dist/products/secrets.js

@@ -30,11 +30,29 @@ export function secrets(t) {
         }
     }
     const liveCopy = async (name, options) => (await jobCopies(options)).find((s) => s.name === name && s.deletedAt === null);
-    const list = async (options) => (await t.json({
-        method: "GET",
-        path: "/v1/egress-secrets",
-        ...options,
-    })).secrets;
+    /** One page with `limit` or `after`; every secret, page after page, without. */
+    async function list(query = {}) {
+        const { limit, after, ...options } = query;
+        const paged = limit !== undefined || after !== undefined;
+        const all = [];
+        let from = after;
+        for (;;) {
+            const params = {
+                ...(limit === undefined ? {} : { limit }),
+                ...(from === undefined ? {} : { after: from }),
+            };
+            const page = await t.json({
+                method: "GET",
+                path: "/v1/egress-secrets",
+                ...(Object.keys(params).length ? { query: params } : {}),
+                ...options,
+            });
+            all.push(...page.secrets);
+            if (paged || !page.next)
+                return all;
+            from = page.next;
+        }
+    }
     const key = (options, part) => options?.idempotencyKey
         ? { ...options, idempotencyKey: `${options.idempotencyKey}:${part}`.slice(0, 128) }
         : options;
@@ -111,7 +129,8 @@ export function secrets(t) {
                 sandboxes: byName.get(j.name)?.sandboxes ?? null,
                 jobs: j,
             });
-        return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+        // By code point, as the API pages them (`after` compares names so).
+        return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     }
     async function set(name, input, options) {
         const { jobs, value, ...egress } = input;
@@ -178,7 +197,8 @@ export function secrets(t) {
             ...options,
         }),
         /** The sandboxes' secrets: names, hosts and placeholders. Never values.
-         * `all()` includes the jobs copies. */
+         * `list({ limit, after })` gives one page, by name; `all()` includes
+         * the jobs copies. */
         list,
         /** Every secret by name, with where its value may go. */
         all,

package/dist/products/uptime.d.ts

@@ -0,0 +1,97 @@
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type UptimeRegion = "wnam" | "enam" | "sam" | "weur" | "eeur" | "apac" | "oc" | "afr" | "me";
+export type UptimeState = "applying" | "active" | "deleted";
+export type UptimeHealth = "unknown" | "up" | "down";
+export type StatusRange = {
+    low: number;
+    high: number;
+};
+export type UptimeCheck = {
+    id: string;
+    name: string | null;
+    labels: Record<string, string>;
+    /** applying until the probes have it, within a minute; then active. */
+    state: UptimeState;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+    /** `target_refused` while the newest knock found the target on a private
+     * or Runtime address. */
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    url: string;
+    method: "GET" | "HEAD";
+    intervalSeconds: number;
+    timeoutMs: number;
+    regions: UptimeRegion[];
+    confirm: number;
+    statuses: StatusRange[];
+    bodyContains?: string;
+    health: UptimeHealth;
+    healthSince: number | null;
+};
+export type CreateUptimeCheck = {
+    /** https://, http:// or tcp://host:port; its host must resolve to public
+     * addresses (a Runtime App's hostname on 80 or 443 is allowed). */
+    url: string;
+    name?: string;
+    labels?: Record<string, string>;
+    /** Defaults to GET. */
+    method?: "GET" | "HEAD";
+    /** 30 to 3,600 per region; defaults to 60. Regions knock in turn. */
+    intervalSeconds?: number;
+    /** 1 to 30,000; defaults to 10,000. */
+    timeoutMs?: number;
+    /** Defaults to enam, wnam, weur, eeur, apac. */
+    regions?: UptimeRegion[];
+    /** Regions that must fail to call it down; defaults to 2 (1 with one region). */
+    confirm?: number;
+    /** Ranges that pass; defaults to 200 to 399. */
+    statuses?: StatusRange[];
+    /** Text the body must contain; GET only. */
+    bodyContains?: string;
+};
+export type UptimeResult = {
+    region: UptimeRegion;
+    scheduledAt: number;
+    at: number;
+    ms: number;
+    up: boolean;
+    status: number | null;
+    reason: string | null;
+    timing: Record<string, unknown>;
+};
+export type UptimeListQuery = {
+    limit?: number;
+    cursor?: string;
+    name?: string;
+    label?: string[];
+    state?: UptimeState[];
+};
+export type UptimeResultsQuery = {
+    before?: number;
+    limit?: number;
+    region?: UptimeRegion;
+};
+export declare function uptime(t: Transport): {
+    create: (input: CreateUptimeCheck, options?: RequestOptions) => Promise<UptimeCheck>;
+    /** waitFor follows a state for up to 60 seconds; the answer says where it got. */
+    get: (id: string, options?: RequestOptions & {
+        waitFor?: UptimeState;
+        timeoutSeconds?: number;
+    }) => Promise<UptimeCheck>;
+    list: (query?: UptimeListQuery, options?: RequestOptions) => Promise<Page<UptimeCheck>>;
+    update: (id: string, input: {
+        name?: string | null;
+        labels?: Record<string, string>;
+    }, options?: RequestOptions) => Promise<UptimeCheck>;
+    delete: (id: string, options?: RequestOptions) => Promise<UptimeCheck>;
+    /** Knocks, newest first, kept 7 days; pass nextBefore as before for older ones. */
+    results: (id: string, query?: UptimeResultsQuery, options?: RequestOptions) => Promise<{
+        data: UptimeResult[];
+        nextBefore: number | null;
+    }>;
+};

package/dist/products/uptime.js

@@ -0,0 +1,42 @@
+import { Page } from "../page.js";
+const enc = encodeURIComponent;
+export function uptime(t) {
+    const base = "/v1/uptime";
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: base,
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    return {
+        create: (input, options) => t.json({ method: "POST", path: base, body: input, ...options }),
+        /** waitFor follows a state for up to 60 seconds; the answer says where it got. */
+        get: (id, options = {}) => {
+            const { waitFor, timeoutSeconds, ...request } = options;
+            return t.json({
+                method: "GET",
+                path: `${base}/${enc(id)}`,
+                query: { waitFor, timeoutSeconds },
+                ...request,
+            });
+        },
+        list,
+        update: (id, input, options) => t.json({
+            method: "POST",
+            path: `${base}/${enc(id)}:update`,
+            body: input,
+            ...options,
+        }),
+        delete: (id, options) => t.json({ method: "DELETE", path: `${base}/${enc(id)}`, ...options }),
+        /** Knocks, newest first, kept 7 days; pass nextBefore as before for older ones. */
+        results: (id, query = {}, options) => t.json({
+            method: "GET",
+            path: `${base}/${enc(id)}/results`,
+            query,
+            ...options,
+        }),
+    };
+}

package/dist/products/volumes.d.ts

@@ -25,10 +25,14 @@ export type Volume = {
     measuredAt: string | null;
     /** True once a backup of it has been copied off its host and checked. */
     backedUp: boolean;
-    /** Daily backups, how long each is kept, and when the newest was taken. */
+    /** Automatic backups: daily, kept `retentionDays`, or on the volume's own
+     * `schedule` with `keep` counts; `nextAt` is the schedule's next backup. */
     backups: {
         daily: boolean;
         retentionDays: number;
+        schedule?: VolumeBackupSchedule | null;
+        keep?: Required<VolumeBackupKeep> | null;
+        nextAt?: string | null;
         lastReadyAt: string | null;
     };
     /** The backup this volume was restored from, if any. */
@@ -69,6 +73,24 @@ export type VolumeAttachment = {
     changedAt: string;
 };
 export type VolumeBackupState = "pending" | "ready" | "failed" | "deleting" | "deleted";
+/** Back up every N minutes (15 or more, from 1970-01-01 UTC), or on a
+ * five-field cron in UTC such as `"30 2 * * 1-5"` (02:30 on weekdays). */
+export type VolumeBackupSchedule = {
+    everyMinutes: number;
+} | {
+    cron: string;
+};
+/** Which scheduled backups stay: the last N, and the newest in each of the
+ * newest N hours, days, weeks (from Monday), months and years. Any backup a
+ * count keeps is kept; the newest ready backup always is. Missing counts are 0. */
+export type VolumeBackupKeep = {
+    last?: number;
+    hourly?: number;
+    daily?: number;
+    weekly?: number;
+    monthly?: number;
+    yearly?: number;
+};
 /** A point-in-time copy of a volume, kept off its host. */
 export type VolumeBackup = {
     id: string;
@@ -80,25 +102,30 @@ export type VolumeBackup = {
     region: string;
     volumeId: string;
     sizeMiB: number;
-    trigger: "manual" | "daily";
-    retentionDays: number;
+    /** `scheduled`: made on the volume's schedule and kept by its keep counts. */
+    trigger: "manual" | "daily" | "scheduled";
+    /** Null while the volume's keep counts decide. */
+    retentionDays: number | null;
     logicalBytes: number | null;
     storedBytes: number | null;
     meteredBytes: number | null;
     error: string | null;
     /** Why it failed, when a code says it: `backup_stalled` when its copy off
-     * the host never began; back it up again. */
+     * the volume's server had not begun 15 minutes after `createdAt`; back it
+     * up again. */
     errorCode?: string | null;
     createdAt: string;
-    /** When its copy off the volume's server began; null while it waits its
-     * turn behind other copies there. */
+    /** When its copy off the volume's server began; null while it waits,
+     * behind other backups there only (never Runtime's own copies). */
     copyStartedAt?: string | null;
     readyAt: string | null;
-    expiresAt: string;
+    /** Null while the volume's keep counts decide. */
+    expiresAt: string | null;
 };
 /** Persistent disks: create once, attach when creating a sandbox with
  * `volumes: [{ volumeId: v.id, path: "/data" }]`. Backed up off their host
- * daily unless that is turned off; restore one with `create({ fromBackup })`. */
+ * daily, or on a schedule of their own, unless that is turned off; restore
+ * one with `create({ fromBackup })`. */
 export declare function volumes(t: Transport): {
     /** Create and wait (up to 10 s) until it is ready. With `fromBackup`, a
      * restore; it is ready once the backup is downloaded and checked. */
@@ -136,10 +163,15 @@ export declare function volumes(t: Transport): {
     }, options?: RequestOptions & {
         wait?: number;
     }) => Promise<VolumeBackup>;
-    /** Daily backups on or off, and how many days each is kept. */
+    /** Automatic backups on or off, days a daily one is kept, or a schedule
+     * of the volume's own with keep counts:
+     * `setBackupPolicy(id, { schedule: { everyMinutes: 60 }, keep: { hourly: 24, daily: 7 } })`. */
     setBackupPolicy: (id: string, input: {
         daily?: boolean;
         retentionDays?: number;
+        /** Null goes back to daily backups kept `retentionDays`. */
+        schedule?: VolumeBackupSchedule | null;
+        keep?: VolumeBackupKeep;
     }, options?: RequestOptions) => Promise<Volume>;
     /** Backups, newest first; `{ volumeId }` for one volume's. */
     backups: (query?: {

package/dist/products/volumes.js

@@ -2,7 +2,8 @@ import { Page } from "../page.js";
 const enc = encodeURIComponent;
 /** Persistent disks: create once, attach when creating a sandbox with
  * `volumes: [{ volumeId: v.id, path: "/data" }]`. Backed up off their host
- * daily unless that is turned off; restore one with `create({ fromBackup })`. */
+ * daily, or on a schedule of their own, unless that is turned off; restore
+ * one with `create({ fromBackup })`. */
 export function volumes(t) {
     const get = (id, options) => t.json({ method: "GET", path: `/v1/volumes/${enc(id)}`, ...options });
     const list = async (query = {}, options) => {
@@ -83,7 +84,9 @@ export function volumes(t) {
                 ...rest,
             });
         },
-        /** Daily backups on or off, and how many days each is kept. */
+        /** Automatic backups on or off, days a daily one is kept, or a schedule
+         * of the volume's own with keep counts:
+         * `setBackupPolicy(id, { schedule: { everyMinutes: 60 }, keep: { hourly: 24, daily: 7 } })`. */
         setBackupPolicy: (id, input, options) => t.json({
             method: "POST",
             path: `/v1/volumes/${enc(id)}:backup-policy`,

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.33.3";
+export declare const VERSION = "0.35.0";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -47,6 +47,9 @@ export type Call = RequestOptions & {
     /** Seconds the server may hold the answer for a long-running result. */
     wait?: number;
     accept?: string;
+    /** Sent as the Bearer token instead of the client's API key: a webhook
+     * trigger's secret, which is all its calls carry. */
+    bearer?: string;
     /** Whether retrying after an unknown outcome is safe. Default: true for
      * reads and for writes (the key makes them safe); false only for calls
      * the server cannot deduplicate. */

package/dist/transport.js

@@ -1,7 +1,7 @@
 import { ConnectionError, DELIBERATE, errorFor, NOTHING_RAN, RuntimeError, WAITS_FOR_ROOM, } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket, untrustedCertificate } from "./proxy.js";
 import { warningText } from "./product-renames.js";
-export const VERSION = "0.33.3";
+export const VERSION = "0.35.0";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -374,7 +374,7 @@ export class Transport {
         let apiKey;
         try {
             call.signal?.throwIfAborted();
-            apiKey = await untilAborted(this.#key(), call.signal);
+            apiKey = call.bearer ?? (await untilAborted(this.#key(), call.signal));
         }
         catch (cause) {
             if (call.signal?.aborted)

package/dist/types.d.ts

@@ -28,6 +28,9 @@ export type SandboxInfo = {
     idlePauseUnusedOnly?: boolean;
     /** A request (exec, files, terminal, a visit to a shared port) wakes it when paused. */
     autoWake?: boolean;
+    /** Who its commands, processes and terminals run as when one names no
+     * user: "sandbox" (uid 1000) or "root". Absent from APIs before 25 October 2026. */
+    user?: "sandbox" | "root";
     /** Runs until stopped while credit lasts, never paused for idleness or a
      * time limit, and its disk is kept after a stop. */
     persistent?: boolean;
@@ -139,6 +142,11 @@ export type CreateSandbox = {
     idlePauseSeconds?: number;
     /** A request to a paused sandbox wakes it. Default true. */
     autoWake?: boolean;
+    /** "root": its commands, processes and terminals run as root, through the
+     * sandbox's passwordless sudo, unless one says `user: "sandbox"`. Default
+     * "sandbox"; a sandbox made from a snapshot runs as its source did. Files
+     * written through `files` stay the sandbox user's. */
+    user?: "sandbox" | "root";
     /** Keep it running until you stop it, while credit lasts, with no idle
      * pause unless idlePauseSeconds asks for one. Its disk is billed as any
      * sandbox's, and kept after a stop, for restart(), as any sandbox's is.
@@ -224,9 +232,10 @@ export type CommandResult = {
 };
 export type ExecOptions = {
     cwd?: string;
-    /** Who runs it: "sandbox" (the default, uid 1000, HOME=/workspace) or
-     * "root", through the sandbox's passwordless sudo with the same
-     * environment and PATH and HOME=/root: no need to prefix it with sudo. */
+    /** Who runs it: "sandbox" (uid 1000, HOME=/workspace) or "root", through
+     * the sandbox's passwordless sudo with the same environment and PATH and
+     * HOME=/root: no need to prefix it with sudo. Default: the sandbox's own
+     * `user`, the sandbox user unless it was made with "root". */
     user?: "sandbox" | "root";
     /** Merged over the sandbox's environment. Put secrets here, never in the command. */
     env?: Record<string, string>;
@@ -487,6 +496,9 @@ export type SandboxSettings = {
     env?: Record<string, string | null>;
     /** A request to a paused sandbox wakes it. */
     autoWake?: boolean;
+    /** Who later commands, processes and terminals run as when one names no
+     * user; running ones keep theirs. */
+    user?: "sandbox" | "root";
     /** Pause after this many seconds with no activity, counted from now; 0
      * never, otherwise 60 to 86400 (a shorter time is raised to 60). */
     idlePauseSeconds?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.33.3",
+  "version": "0.35.0",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",
@@ -66,6 +66,16 @@
       "import": "./dist/containers/index.js",
       "default": "./dist/containers/index.js"
     },
+    "./browsers": {
+      "types": "./dist/browsers/index.d.ts",
+      "import": "./dist/browsers/index.js",
+      "default": "./dist/browsers/index.js"
+    },
+    "./desktops": {
+      "types": "./dist/desktops/index.d.ts",
+      "import": "./dist/desktops/index.js",
+      "default": "./dist/desktops/index.js"
+    },
     "./builds": {
       "types": "./dist/builds/index.d.ts",
       "import": "./dist/builds/index.js",
@@ -81,6 +91,11 @@
       "import": "./dist/apps/index.js",
       "default": "./dist/apps/index.js"
     },
+    "./functions": {
+      "types": "./dist/functions/index.d.ts",
+      "import": "./dist/functions/index.js",
+      "default": "./dist/functions/index.js"
+    },
     "./e2b": {
       "types": "./dist/e2b/index.d.ts",
       "import": "./dist/e2b/index.js",
@@ -220,6 +235,7 @@
     "ai": "7.0.87",
     "groq-sdk": "1.6.0",
     "openai": "7.23.0",
+    "playwright": "1.63.0",
     "together-ai": "0.55.0",
     "typescript": "^5",
     "zod": "^4.1.8"