smolmachines 1.26.1 → 1.27.2

package/README.md

@@ -87,10 +87,32 @@ try {
 }
 ```
 
-For a local VM whose published service starts through `exec()`, set
-`waitForPorts: false` on creation. The SDK still waits for the guest agent,
-so `exec()` is safe; call `waitUntilReady()` once the service is listening.
-The default keeps waiting for all published ports. This option is local-only.
+Local machines also accept a saved Docker/OCI image archive or an unpacked rootfs
+as `image`. The SDK stages an archive once and reuses its content hash; a
+missing local path fails immediately with the path in the error instead of
+trying to pull it from a registry. Build your image first, then save it:
+
+```sh
+docker save my-agent:latest -o my-agent.tar
+```
+
+```ts
+const m = await Machine.create(
+  { image: './my-agent.tar', network: false },
+  { target: 'local' },
+);
+try {
+  console.log((await m.exec(['sh', '-c', 'pwd'])).stdout);
+} finally {
+  await m.delete();
+}
+```
+
+When a published service starts through `exec()` (local or cloud), set
+`waitForPorts: false` on creation. The SDK waits for the guest agent so
+`exec()` can start the listener; call `waitUntilReady()` once the service is
+listening. The default waits for all published ports. Select
+`{ target: 'cloud' }` to use the same flow on Smol Cloud.
 
 ```ts
 const m = await Machine.create(
@@ -109,10 +131,13 @@ try {
 }
 ```
 
-When reconnecting to clean up a local machine whose published service has
+When reconnecting to a running local machine whose published service has
 stopped, `Machine.connect(name, { target: 'local', waitForPorts: false })`
-attaches after the agent is ready, so `delete()` can run without a listener.
-The default continues waiting for all published ports.
+attaches after the agent is ready, without waiting for the listener. Cloud
+`connect()` normally attaches without waiting; with `waitForPorts: false`, it
+waits for a successful guest-agent command without requiring the port to be
+open. Connect without that flag to inspect or delete a stopped or paused cloud
+machine.
 
 To reach a service **inside** the VM, use the authenticated connect bridge —
 **no Cloudflare/localhost.run tunnel, no public exposure, no egress allow-list.**
@@ -215,6 +240,9 @@ Existing network connections may need to reconnect.
 - `machine.exec(command, opts?)` / `machine.run(image, command, opts?)` → `ExecResult`.
 - `machine.execStream(command, opts?)` → `AsyncGenerator<ExecEvent>`.
 - `machine.readFile(path)` / `machine.writeFile(path, data, mode?)`.
+- `machine.readFileStream(path)` yields `Uint8Array` chunks without buffering
+  the full Cloud download; stopping iteration cancels the response. Local
+  machines currently yield one buffered chunk.
 - `machine.pullImage(image)` / `machine.listImages()`.
 - `machine.branch(name, options?)` / `machine.branchBatch(options)`.
 - `machine.checkpoint(output, { store? })`, `Machine.restoreCheckpoint(...)`,
@@ -332,6 +360,23 @@ const { id } = await base.checkpoint();
 const a = await Machine.restoreCheckpoint(id, "project-a", undefined, { cacheDisk: { cache: "project-a" } });
 ```
 
+## Jobs: long commands that survive a dropped connection (cloud)
+
+`exec` holds one HTTP request open for the whole command, so a network blip or
+a long build can lose it. A job starts the command detached and returns its id
+at once. Its output and exit code stay in the machine, and the machine does not
+auto-stop while it runs:
+
+```ts
+const job = await m.startJob(["make", "test"], { workdir: "/src", timeout: 3600 });
+const done = await job.wait();                  // polls; { state: "exited", exitCode }
+const log = await job.readAll();                // all of stdout, byte-exact
+const page = await job.output({ stream: "stderr", offset: 0 }); // then page.nextOffset
+```
+
+`state` is `"lost"` if the machine stopped under the job. `job.cancel()` stops
+it (exit 143), and `m.job(id)` picks a job up again from another process.
+
 ## Building from source
 
 This package's native core lives alongside it (Rust, `src/*.rs`) and links the

package/dist/assets.d.ts

@@ -1,17 +1,21 @@
 /** Auto-wiring for bundled native assets.
  *
- *  Points the engine at the package's bundled, signed boot helper and hypervisor
- *  libraries so the SDK works on a plain `node` with no manual env setup:
- *    - SMOLVM_BOOT_BINARY → bundled `smol-vmm` helper (handles `_boot-vm`; on
- *      macOS codesigned with `com.apple.security.hypervisor`, so the user's
- *      `node` needs no entitlement).
- *    - SMOLVM_LIB_DIR     → the dir holding libkrun/libkrunfw.
- *    - SMOLVM_AGENT_ROOTFS_TAR → bundled guest rootfs tarball (the engine
- *      extracts it on first use), so a plain `npm i` is fully self-contained.
+ *  Resolves the package's bundled, signed boot helper, hypervisor libraries and
+ *  guest rootfs so the SDK works on a plain `node` with no manual env setup:
+ *    - bootBinary     → bundled `smol-vmm` helper (handles `_boot-vm`; on macOS
+ *      codesigned with `com.apple.security.hypervisor`, so the user's `node`
+ *      needs no entitlement).
+ *    - libDir         → the dir holding libkrun/libkrunfw.
+ *    - agentRootfsTar → bundled guest rootfs tarball (the engine extracts it
+ *      on first use), so a plain `npm i` is fully self-contained.
  *
- *  A user-provided value always wins. Called by `native.ts` right before the
- *  addon loads — i.e. on first LOCAL use, never at import — so importing the
- *  SDK (e.g. for cloud-only use) leaves `process.env` untouched.
+ *  The resolved paths are handed to the engine in-process by
+ *  `configureRuntimeAssets` and are never written to `process.env`: a `smolvm`
+ *  CLI this program spawns must not inherit this package's helper (it exits
+ *  when its parent does) or its libraries. A user-provided SMOLVM_BOOT_BINARY,
+ *  SMOLVM_LIB_DIR or SMOLVM_AGENT_ROOTFS(_TAR) always wins. Called by
+ *  `native.ts` right before the addon loads — i.e. on first LOCAL use, never at
+ *  import.
  */
 /** The per-platform npm package that carries the native addon, boot helper,
  *  hypervisor libraries and guest rootfs for each supported

package/dist/assets.js

@@ -1,18 +1,22 @@
 "use strict";
 /** Auto-wiring for bundled native assets.
  *
- *  Points the engine at the package's bundled, signed boot helper and hypervisor
- *  libraries so the SDK works on a plain `node` with no manual env setup:
- *    - SMOLVM_BOOT_BINARY → bundled `smol-vmm` helper (handles `_boot-vm`; on
- *      macOS codesigned with `com.apple.security.hypervisor`, so the user's
- *      `node` needs no entitlement).
- *    - SMOLVM_LIB_DIR     → the dir holding libkrun/libkrunfw.
- *    - SMOLVM_AGENT_ROOTFS_TAR → bundled guest rootfs tarball (the engine
- *      extracts it on first use), so a plain `npm i` is fully self-contained.
+ *  Resolves the package's bundled, signed boot helper, hypervisor libraries and
+ *  guest rootfs so the SDK works on a plain `node` with no manual env setup:
+ *    - bootBinary     → bundled `smol-vmm` helper (handles `_boot-vm`; on macOS
+ *      codesigned with `com.apple.security.hypervisor`, so the user's `node`
+ *      needs no entitlement).
+ *    - libDir         → the dir holding libkrun/libkrunfw.
+ *    - agentRootfsTar → bundled guest rootfs tarball (the engine extracts it
+ *      on first use), so a plain `npm i` is fully self-contained.
  *
- *  A user-provided value always wins. Called by `native.ts` right before the
- *  addon loads — i.e. on first LOCAL use, never at import — so importing the
- *  SDK (e.g. for cloud-only use) leaves `process.env` untouched.
+ *  The resolved paths are handed to the engine in-process by
+ *  `configureRuntimeAssets` and are never written to `process.env`: a `smolvm`
+ *  CLI this program spawns must not inherit this package's helper (it exits
+ *  when its parent does) or its libraries. A user-provided SMOLVM_BOOT_BINARY,
+ *  SMOLVM_LIB_DIR or SMOLVM_AGENT_ROOTFS(_TAR) always wins. Called by
+ *  `native.ts` right before the addon loads — i.e. on first LOCAL use, never at
+ *  import.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PLATFORM_PACKAGES = void 0;
@@ -77,18 +81,18 @@ function wireBundledAssets() {
         if (!(0, node_fs_1.existsSync)(nativeDir))
             continue;
         const helper = (0, node_path_1.join)(nativeDir, helperName);
+        // Resolved paths are handed to the engine by `configureRuntimeAssets`, never
+        // written to `process.env`: a `smolvm` CLI this program spawns must not
+        // inherit this package's helper, libraries or rootfs.
         if (!assets.bootBinary && (0, node_fs_1.existsSync)(helper)) {
             assets.bootBinary = helper;
-            process.env.SMOLVM_BOOT_BINARY = helper;
         }
         if (!assets.libDir) {
             assets.libDir = nativeDir;
-            process.env.SMOLVM_LIB_DIR = nativeDir;
         }
         const rootfsTar = (0, node_path_1.join)(nativeDir, 'agent-rootfs.tar');
         if (!assets.agentRootfs && !assets.agentRootfsTar && (0, node_fs_1.existsSync)(rootfsTar)) {
             assets.agentRootfsTar = rootfsTar;
-            process.env.SMOLVM_AGENT_ROOTFS_TAR = rootfsTar;
         }
         break;
     }

package/dist/binding.d.ts

@@ -287,6 +287,11 @@ export declare class NapiMachine {
    * for a failed boot. Never throws.
    */
   static checkHost(): HostAvailability
+  /**
+   * Stage a local archive or rootfs directory before creating the machine.
+   * Large archives are hashed off the JavaScript event loop.
+   */
+  static prepareImage(image: string): Promise<string>
   /** Create a new machine. Does not start the VM yet — call `start()`. */
   constructor(config: MachineConfig)
   /**

package/dist/errors.d.ts

@@ -4,9 +4,30 @@
  *  prefixed with a bracketed code, e.g. `"[KVM_UNAVAILABLE] …"`. We parse that
  *  back into a typed hierarchy so callers can branch on `err.code` /`instanceof`.
  */
+/** What the cloud API said about a failed request, beyond its message. */
+export interface CloudErrorDetail {
+    /** HTTP status of the response. */
+    status: number;
+    /** The server's stable problem code, e.g. `machine_interrupted`. */
+    problemCode?: string | undefined;
+    /** Whether sending the same request again can succeed. */
+    retryable: boolean;
+    /** How long the server asked callers to wait before retrying (ms). */
+    retryAfterMs?: number | undefined;
+}
 export declare class SmolError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    /** HTTP status, for an error the cloud API returned. */
+    readonly status?: number | undefined;
+    /** The server's stable problem code, for an error the cloud API returned. */
+    readonly problemCode?: string | undefined;
+    /** Whether sending the same request again can succeed. A command whose
+     *  machine went away (`MACHINE_INTERRUPTED`) is retryable, but it may have
+     *  partly run, so the SDK leaves that retry to the caller. */
+    readonly retryable: boolean;
+    /** How long the server asked callers to wait before retrying (ms). */
+    readonly retryAfterMs?: number | undefined;
+    constructor(code: string, message: string, detail?: CloudErrorDetail);
 }
 /** The active backend can't serve this operation (e.g. volumes on local). */
 export declare class NotSupportedError extends SmolError {

package/dist/errors.js

@@ -9,10 +9,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ExecutionError = exports.InvalidConfigError = exports.NotSupportedError = exports.SmolError = void 0;
 exports.wrapNativeError = wrapNativeError;
 class SmolError extends Error {
-    constructor(code, message) {
+    constructor(code, message, detail) {
         super(message);
         this.name = new.target.name;
         this.code = code;
+        this.status = detail?.status;
+        this.problemCode = detail?.problemCode;
+        this.retryable = detail?.retryable ?? false;
+        this.retryAfterMs = detail?.retryAfterMs;
     }
 }
 exports.SmolError = SmolError;

package/dist/index.d.ts

@@ -16,10 +16,10 @@
  * Runs against the local embedded engine (default, no server) or the smolfleet
  * cloud — same API, backend selected via ConnectOptions / SMOL_CLOUD_TOKEN.
  */
-export { Machine, Episode, CacheDisk } from './machine';
+export { Machine, Episode, CacheDisk, Job } from './machine';
 export { RolloutClient, RolloutError, adapterSha256 } from './rollout';
 export type { BuildRolloutJobOptions, EnsureRolloutExecutorOptions, RolloutBatchItem, RolloutClientOptions, RolloutCompletion, RolloutExecutorInfo, RolloutGenerateResponse, RolloutJob, RolloutPolicyInfo, RolloutPrompt, RolloutSampling, } from './rollout';
 export { SmolError, NotSupportedError, InvalidConfigError, ExecutionError } from './errors';
 export type { CloudCheckpointInfo } from './transport';
 export type { LocalAvailability, LocalUnavailableCode } from './availability';
-export type { MachineConfig, CredentialSpec, CacheDiskRef, CacheDiskInfo, CacheDiskVersion, CreateCacheDiskOptions, PublishedCacheDisk, NetworkPolicy, RestoreCheckpointOptions, MachineState, ResourceSpec, MountSpec, PortSpec, BranchOptions, BranchBatchOptions, CheckpointOptions, ResizeOptions, MachineResources, ForkOptions, ForkBatchOptions, AssignOptions, ExecOptions, ExecResult, MachineUsageReport, ShareLink, PortableCheckpointInfo, MachineUsageTotals, MachineCostBreakdown, ImageInfo, MachineSummary, ListOptions, ExecEvent, ConnectOptions, EgressInterceptor, StartOptions, ResumeOptions, WaitReadyOptions, PortEndpoint, } from './types';
+export type { MachineConfig, CredentialSpec, CacheDiskRef, CacheDiskInfo, CacheDiskVersion, CreateCacheDiskOptions, PublishedCacheDisk, NetworkPolicy, RestoreCheckpointOptions, MachineState, ResourceSpec, MountSpec, PortSpec, BranchOptions, BranchBatchOptions, CheckpointOptions, ResizeOptions, MachineResources, ForkOptions, ForkBatchOptions, AssignOptions, ExecOptions, JobInfo, JobOptions, JobOutput, JobOutputOptions, JobState, JobWaitOptions, ExecResult, MachineUsageReport, ShareLink, PortableCheckpointInfo, MachineUsageTotals, MachineCostBreakdown, ImageInfo, MachineSummary, ListOptions, ExecEvent, ConnectOptions, EgressInterceptor, StartOptions, ResumeOptions, WaitReadyOptions, PortEndpoint, } from './types';

package/dist/index.js

@@ -18,11 +18,12 @@
  * cloud — same API, backend selected via ConnectOptions / SMOL_CLOUD_TOKEN.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExecutionError = exports.InvalidConfigError = exports.NotSupportedError = exports.SmolError = exports.adapterSha256 = exports.RolloutError = exports.RolloutClient = exports.CacheDisk = exports.Episode = exports.Machine = void 0;
+exports.ExecutionError = exports.InvalidConfigError = exports.NotSupportedError = exports.SmolError = exports.adapterSha256 = exports.RolloutError = exports.RolloutClient = exports.Job = exports.CacheDisk = exports.Episode = exports.Machine = void 0;
 var machine_1 = require("./machine");
 Object.defineProperty(exports, "Machine", { enumerable: true, get: function () { return machine_1.Machine; } });
 Object.defineProperty(exports, "Episode", { enumerable: true, get: function () { return machine_1.Episode; } });
 Object.defineProperty(exports, "CacheDisk", { enumerable: true, get: function () { return machine_1.CacheDisk; } });
+Object.defineProperty(exports, "Job", { enumerable: true, get: function () { return machine_1.Job; } });
 var rollout_1 = require("./rollout");
 Object.defineProperty(exports, "RolloutClient", { enumerable: true, get: function () { return rollout_1.RolloutClient; } });
 Object.defineProperty(exports, "RolloutError", { enumerable: true, get: function () { return rollout_1.RolloutError; } });

package/dist/machine.d.ts

@@ -9,14 +9,14 @@
  */
 import { type LocalAvailability } from "./availability";
 import { type CloudCheckpointInfo, type Transport } from "./transport";
-import type { CacheDiskInfo, CreateCacheDiskOptions, PublishedCacheDisk, MachineResources, ResizeOptions, AssignOptions, BranchBatchOptions, BranchOptions, CheckpointOptions, ConnectOptions, ExecEvent, ExecOptions, ExecResult, ForkBatchOptions, ForkOptions, ImageInfo, ListOptions, MachineConfig, MachineSummary, NetworkPolicy, RestoreCheckpointOptions, StartOptions, ResumeOptions, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, WaitReadyOptions } from "./types";
+import type { CacheDiskInfo, CreateCacheDiskOptions, PublishedCacheDisk, MachineResources, ResizeOptions, AssignOptions, BranchBatchOptions, BranchOptions, CheckpointOptions, ConnectOptions, ExecEvent, ExecOptions, ExecResult, ForkBatchOptions, ForkOptions, ImageInfo, JobInfo, JobOptions, JobOutput, JobOutputOptions, JobWaitOptions, ListOptions, MachineConfig, MachineSummary, NetworkPolicy, RestoreCheckpointOptions, StartOptions, ResumeOptions, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, WaitReadyOptions } from "./types";
 export declare class Machine {
     private readonly transport;
     private constructor();
     /**
      * Create and start a machine. By default this waits for the guest agent and
-     * all published ports. On local machines, `waitForPorts: false` returns when
-     * the agent is ready so `exec()` can start a service on a published port.
+     * all published ports. `waitForPorts: false` returns when the agent is
+     * ready so `exec()` can start a service on a published port.
      * A cloud state of `"started"` alone means only that the VM process launched.
      *
      * @param config  machine configuration (a name is generated if omitted; `image`
@@ -29,11 +29,14 @@ export declare class Machine {
      * machine made elsewhere (another process, the console, the REST API).
      *  - local (default): re-opens a persisted machine by NAME, starting it if
      *    stopped — pairs with `Machine.create({ name, … }, …)` + `persistent`.
+     *    A paused machine stays paused; call `resume()` to restore its saved
+     *    execution before running commands.
      *    Set `conn.waitForPorts: false` to attach after agent readiness when a
      *    published service is not listening (for example, to delete it).
      *  - cloud: looks up the machine by id; throws if it doesn't exist.
-     *    This does not wait for readiness; call `waitUntilReady()` before `exec`,
-     *    using a connect endpoint, or expecting the workload to respond.
+     *    This does not wait for readiness by default. With `waitForPorts: false`,
+     *    it waits for the guest agent so `exec()` can start a published service.
+     *    Call `waitUntilReady()` before expecting the published service to respond.
      *
      * @param id    local machine name, or cloud machine id (`mach-…`)
      * @param conn  backend selection (local by default; cloud via `{ target: 'cloud', apiKey }` or `SMOL_CLOUD_TOKEN`)
@@ -98,6 +101,21 @@ export declare class Machine {
      *  namespace, re-deployable anywhere. Distinct from a portable checkpoint,
      *  which also keeps live memory. Cloud only. */
     exportArtifact(): Promise<Record<string, unknown>>;
+    /** Start `command` as a detached job and return at once. Its output and exit
+     *  code are kept in the machine, so the caller can disconnect and come back:
+     *  poll with {@link Job.wait}, read output from an offset with
+     *  {@link Job.output}. The machine does not auto-stop while the job runs.
+     *  A string runs through `sh -c`; the image needs `sh`. Cloud only.
+     *
+     *  Unlike `exec`, a job survives a dropped connection, so prefer it for
+     *  anything that runs longer than a few minutes. */
+    startJob(command: string[] | string, opts?: JobOptions): Promise<Job>;
+    /** This machine's jobs, newest first, as last recorded (up to 100). Use
+     *  {@link Job.info} for a job's live state. Cloud only. */
+    jobs(): Promise<JobInfo[]>;
+    /** A handle to an existing job by id, for example one started by another
+     *  process. Makes no request. Cloud only. */
+    job(id: string): Job;
     /** Whether the machine is READY to do work. `state()` becoming "started"
      *  means only that the VM process launched — the guest is still booting and
      *  is NOT yet usable. `ready` becomes true once the in-VM agent is reachable
@@ -136,6 +154,10 @@ export declare class Machine {
     execStream(command: string[], opts?: ExecOptions): AsyncGenerator<ExecEvent>;
     /** Read a file from the machine. */
     readFile(path: string): Promise<Buffer>;
+    /** Read a file in chunks without buffering the entire Cloud response.
+     * Local machines currently yield one buffered chunk from the native binding.
+     * Stopping iteration early cancels the Cloud HTTP download. */
+    readFileStream(path: string): AsyncGenerator<Uint8Array>;
     /** Write a file into the machine. */
     writeFile(path: string, data: string | Uint8Array, mode?: number): Promise<void>;
     /** Pull an OCI image into the machine's storage. (local) */
@@ -251,6 +273,27 @@ export declare class Machine {
      *  @returns the grader's `ExecResult` (use `.success` for pass/fail, `.stdout` for a score) */
     rewardFork(command: string[], opts?: ExecOptions, name?: string): Promise<ExecResult>;
 }
+/** A detached command in a cloud machine, from {@link Machine.startJob}. */
+export declare class Job {
+    #private;
+    readonly id: string;
+    constructor(transport: Transport, id: string);
+    /** The job's live state. A running job's machine is asked whether it has
+     *  finished; `lost` means the machine stopped or restarted under it. */
+    info(): Promise<JobInfo>;
+    /** A slice of stdout (default) or stderr from `offset`. Pass the returned
+     *  `nextOffset` back to read on; `eof` is true once the job has finished and
+     *  the slice reaches the end. */
+    output(opts?: JobOutputOptions): Promise<JobOutput>;
+    /** Everything written to `stream` so far. On a finished job, that is all
+     *  of it. */
+    readAll(stream?: "stdout" | "stderr"): Promise<Buffer>;
+    /** Stop the job with SIGTERM. It is recorded as exited with code 143. */
+    cancel(): Promise<JobInfo>;
+    /** Poll until the job is no longer running and return its final state:
+     *  `exited` with `exitCode`, or `lost`. */
+    wait(opts?: JobWaitOptions): Promise<JobInfo>;
+}
 /** A leased RL episode: a freshly-provisioned clone plus its lease. Created by
  *  `Machine.assign()`. Always `complete()` it (e.g. in a `finally`) so the clone
  *  is reclaimed — the RL "one clean worker per task, guaranteed reclaimed"

package/dist/machine.js

@@ -19,9 +19,9 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Episode_machine, _Episode_ownerToken, _Episode_leaseTransport, _Episode_completed;
+var _Job_transport, _Episode_machine, _Episode_ownerToken, _Episode_leaseTransport, _Episode_completed;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CacheDisk = exports.Episode = exports.Machine = void 0;
+exports.CacheDisk = exports.Episode = exports.Job = exports.Machine = void 0;
 const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
 const errors_1 = require("./errors");
@@ -57,8 +57,8 @@ class Machine {
     }
     /**
      * Create and start a machine. By default this waits for the guest agent and
-     * all published ports. On local machines, `waitForPorts: false` returns when
-     * the agent is ready so `exec()` can start a service on a published port.
+     * all published ports. `waitForPorts: false` returns when the agent is
+     * ready so `exec()` can start a service on a published port.
      * A cloud state of `"started"` alone means only that the VM process launched.
      *
      * @param config  machine configuration (a name is generated if omitted; `image`
@@ -78,11 +78,14 @@ class Machine {
      * machine made elsewhere (another process, the console, the REST API).
      *  - local (default): re-opens a persisted machine by NAME, starting it if
      *    stopped — pairs with `Machine.create({ name, … }, …)` + `persistent`.
+     *    A paused machine stays paused; call `resume()` to restore its saved
+     *    execution before running commands.
      *    Set `conn.waitForPorts: false` to attach after agent readiness when a
      *    published service is not listening (for example, to delete it).
      *  - cloud: looks up the machine by id; throws if it doesn't exist.
-     *    This does not wait for readiness; call `waitUntilReady()` before `exec`,
-     *    using a connect endpoint, or expecting the workload to respond.
+     *    This does not wait for readiness by default. With `waitForPorts: false`,
+     *    it waits for the guest agent so `exec()` can start a published service.
+     *    Call `waitUntilReady()` before expecting the published service to respond.
      *
      * @param id    local machine name, or cloud machine id (`mach-…`)
      * @param conn  backend selection (local by default; cloud via `{ target: 'cloud', apiKey }` or `SMOL_CLOUD_TOKEN`)
@@ -197,6 +200,34 @@ class Machine {
             throw new errors_1.NotSupportedError("exportArtifact is cloud-only.");
         return this.transport.exportArtifact();
     }
+    /** Start `command` as a detached job and return at once. Its output and exit
+     *  code are kept in the machine, so the caller can disconnect and come back:
+     *  poll with {@link Job.wait}, read output from an offset with
+     *  {@link Job.output}. The machine does not auto-stop while the job runs.
+     *  A string runs through `sh -c`; the image needs `sh`. Cloud only.
+     *
+     *  Unlike `exec`, a job survives a dropped connection, so prefer it for
+     *  anything that runs longer than a few minutes. */
+    async startJob(command, opts = {}) {
+        if (!this.transport.startJob)
+            throw new errors_1.NotSupportedError("startJob is cloud-only.");
+        const info = await this.transport.startJob(command, opts);
+        return new Job(this.transport, info.id);
+    }
+    /** This machine's jobs, newest first, as last recorded (up to 100). Use
+     *  {@link Job.info} for a job's live state. Cloud only. */
+    jobs() {
+        if (!this.transport.listJobs)
+            throw new errors_1.NotSupportedError("jobs is cloud-only.");
+        return this.transport.listJobs();
+    }
+    /** A handle to an existing job by id, for example one started by another
+     *  process. Makes no request. Cloud only. */
+    job(id) {
+        if (!this.transport.getJob)
+            throw new errors_1.NotSupportedError("job is cloud-only.");
+        return new Job(this.transport, id);
+    }
     /** Whether the machine is READY to do work. `state()` becoming "started"
      *  means only that the VM process launched — the guest is still booting and
      *  is NOT yet usable. `ready` becomes true once the in-VM agent is reachable
@@ -262,6 +293,12 @@ class Machine {
     readFile(path) {
         return this.transport.readFile(path);
     }
+    /** Read a file in chunks without buffering the entire Cloud response.
+     * Local machines currently yield one buffered chunk from the native binding.
+     * Stopping iteration early cancels the Cloud HTTP download. */
+    readFileStream(path) {
+        return this.transport.readFileStream(path);
+    }
     /** Write a file into the machine. */
     writeFile(path, data, mode) {
         const buf = typeof data === "string" ? Buffer.from(data) : Buffer.from(data);
@@ -429,6 +466,75 @@ class Machine {
     }
 }
 exports.Machine = Machine;
+/** A detached command in a cloud machine, from {@link Machine.startJob}. */
+class Job {
+    constructor(transport, id) {
+        _Job_transport.set(this, void 0);
+        __classPrivateFieldSet(this, _Job_transport, transport, "f");
+        this.id = id;
+    }
+    /** The job's live state. A running job's machine is asked whether it has
+     *  finished; `lost` means the machine stopped or restarted under it. */
+    info() {
+        return __classPrivateFieldGet(this, _Job_transport, "f").getJob(this.id);
+    }
+    /** A slice of stdout (default) or stderr from `offset`. Pass the returned
+     *  `nextOffset` back to read on; `eof` is true once the job has finished and
+     *  the slice reaches the end. */
+    output(opts = {}) {
+        return __classPrivateFieldGet(this, _Job_transport, "f").jobOutput(this.id, opts);
+    }
+    /** Everything written to `stream` so far. On a finished job, that is all
+     *  of it. */
+    async readAll(stream = "stdout") {
+        const chunks = [];
+        let offset = 0;
+        for (;;) {
+            const out = await this.output({ stream, offset, limit: 1024 * 1024 });
+            chunks.push(out.data);
+            offset = out.nextOffset;
+            if (out.eof || out.data.length === 0)
+                break;
+        }
+        return Buffer.concat(chunks);
+    }
+    /** Stop the job with SIGTERM. It is recorded as exited with code 143. */
+    cancel() {
+        return __classPrivateFieldGet(this, _Job_transport, "f").cancelJob(this.id);
+    }
+    /** Poll until the job is no longer running and return its final state:
+     *  `exited` with `exitCode`, or `lost`. */
+    async wait(opts = {}) {
+        const pollMs = opts.pollMs ?? 1000;
+        const deadline = opts.timeoutMs === undefined ? Infinity : Date.now() + opts.timeoutMs;
+        for (;;) {
+            opts.signal?.throwIfAborted();
+            const info = await this.info();
+            if (info.state !== "running")
+                return info;
+            const left = deadline - Date.now();
+            if (left <= 0) {
+                throw new errors_1.SmolError("TIMEOUT", `job ${this.id} still running after ${opts.timeoutMs}ms`);
+            }
+            await sleep(Math.min(pollMs, left), opts.signal);
+        }
+    }
+}
+exports.Job = Job;
+_Job_transport = new WeakMap();
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
 /** A leased RL episode: a freshly-provisioned clone plus its lease. Created by
  *  `Machine.assign()`. Always `complete()` it (e.g. in a `finally`) so the clone
  *  is reclaimed — the RL "one clean worker per task, guaranteed reclaimed"

package/dist/native.d.ts

@@ -150,6 +150,7 @@ export interface NapiMachine {
 }
 export interface NapiMachineCtor {
     new (config: NativeMachineConfig): NapiMachine;
+    prepareImage(image: string): Promise<string>;
     connect(name: string, interceptorAddress?: string, interceptorToken?: string): NapiMachine;
     list(): Promise<NativeMachineSummary[]>;
     restoreCheckpoint(name: string, artifact: string, keepIdentity?: boolean): NapiMachine;

package/dist/transport.d.ts

@@ -7,7 +7,7 @@
  *  Cloud-only/local-only capability gaps surface as `NotSupportedError`.
  */
 import { type NativeMachineConfig } from "./native";
-import type { CheckpointOptions, CacheDiskInfo, CreateCacheDiskOptions, PublishedCacheDisk, MachineResources, ResizeOptions, ConnectOptions, NetworkPolicy, RestoreCheckpointOptions, ExecEvent, ExecOptions, EgressInterceptor, AssignOptions, ForkBatchOptions, ForkOptions, ImageInfo, ListOptions, MachineConfig, MachineSummary, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, WaitReadyOptions } from "./types";
+import type { CheckpointOptions, JobInfo, JobOptions, JobOutput, JobOutputOptions, CacheDiskInfo, CreateCacheDiskOptions, PublishedCacheDisk, MachineResources, ResizeOptions, ConnectOptions, NetworkPolicy, RestoreCheckpointOptions, ExecEvent, ExecOptions, EgressInterceptor, AssignOptions, ForkBatchOptions, ForkOptions, ImageInfo, ListOptions, MachineConfig, MachineSummary, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, WaitReadyOptions } from "./types";
 /** Raw exec result (the ergonomic wrapper is added in machine.ts). */
 export interface RawExec {
     /** The detached process's pid, for a background exec. */
@@ -31,6 +31,16 @@ export interface Transport {
     logs?(tail: number): Promise<string>;
     /** Cloud only: export the stopped machine as a `.smolmachine` in the registry. */
     exportArtifact?(): Promise<Record<string, unknown>>;
+    /** Cloud only: start a detached job. */
+    startJob?(command: string[] | string, opts: JobOptions): Promise<JobInfo>;
+    /** Cloud only: the machine's jobs, newest first. */
+    listJobs?(): Promise<JobInfo[]>;
+    /** Cloud only: one job's live state. */
+    getJob?(jobId: string): Promise<JobInfo>;
+    /** Cloud only: a slice of a job's stdout or stderr. */
+    jobOutput?(jobId: string, opts: JobOutputOptions): Promise<JobOutput>;
+    /** Cloud only: stop a job with SIGTERM. */
+    cancelJob?(jobId: string): Promise<JobInfo>;
     state(): Promise<string>;
     ready(): Promise<boolean>;
     readyAt(): Promise<string | null>;
@@ -41,6 +51,7 @@ export interface Transport {
     run(image: string, command: string[], opts?: ExecOptions): Promise<RawExec>;
     execStream(command: string[], opts?: ExecOptions): AsyncGenerator<ExecEvent>;
     readFile(path: string): Promise<Buffer>;
+    readFileStream(path: string): AsyncGenerator<Uint8Array>;
     writeFile(path: string, data: Buffer, mode?: number): Promise<void>;
     pullImage(image: string): Promise<ImageInfo>;
     listImages(): Promise<ImageInfo[]>;
@@ -121,6 +132,8 @@ interface CloudConn {
     /** The caller's `fetch` (ConnectOptions.fetch), when it supplied one. */
     fetch?: typeof fetch;
     readResponseBytes?: (response: Response) => Promise<Uint8Array>;
+    /** ConnectOptions.maxRetries, when the caller set it. */
+    maxRetries?: number;
 }
 /** The largest file the cloud's file routes accept. */
 export declare const CLOUD_MAX_FILE_BYTES: number;
@@ -139,6 +152,12 @@ export declare function errorSentence(body: string): string;
  *  files route is a wildcard (`/files/<path>`), so slashes are meaningful while
  *  spaces/?/#/% in a filename must be escaped. */
 export declare function encodePath(p: string): string;
+/** Parse a `Retry-After` header (delta-seconds or an HTTP date) into ms. */
+export declare function retryAfterMs(header: string | null, now?: number): number | undefined;
+/** Whether the SDK may resend a request on its own. A rate-limited request
+ *  never ran, so it is always safe; an unavailable one may have, so only a
+ *  call that is safe to repeat is sent again. */
+export declare function sdkMayRetry(status: number, method: string, idempotent: boolean): boolean;
 /** Does this request target the cloud?
  *
  * Only an EXPLICIT credential may select cloud: `conn.apiKey` and

package/dist/transport.js

@@ -20,6 +20,8 @@ exports.transferTimeoutMs = transferTimeoutMs;
 exports.checkCloudFileSize = checkCloudFileSize;
 exports.errorSentence = errorSentence;
 exports.encodePath = encodePath;
+exports.retryAfterMs = retryAfterMs;
+exports.sdkMayRetry = sdkMayRetry;
 exports.selectsCloud = selectsCloud;
 exports.makeTransport = makeTransport;
 exports.listMachines = listMachines;
@@ -471,6 +473,11 @@ class LocalTransport {
             throw (0, errors_1.wrapNativeError)(e);
         }
     }
+    // The native local binding currently returns a Buffer; keep the same API
+    // across targets until native streaming is available.
+    async *readFileStream(path) {
+        yield await this.readFile(path);
+    }
     async writeFile(path, data, mode) {
         try {
             await this.inner.writeFile(path, data, mode === undefined ? undefined : { mode });
@@ -697,6 +704,7 @@ function cloudConnOf(conn, baseUrl, apiKey) {
         apiKey,
         ...(conn.fetch ? { fetch: conn.fetch } : {}),
         ...(conn.readResponseBytes ? { readResponseBytes: conn.readResponseBytes } : {}),
+        ...(conn.maxRetries !== undefined ? { maxRetries: conn.maxRetries } : {}),
     };
 }
 const DEFAULT_CLOUD_URL = "https://api.smolmachines.com";
@@ -760,7 +768,110 @@ function errorSentence(body) {
 function encodePath(p) {
     return p.split("/").map(encodeURIComponent).join("/");
 }
+/** The typed error for a failed cloud response, carrying what the problem
+ *  body and headers say about retrying. */
+async function cloudError(res, what) {
+    const raw = await res.text().catch(() => "");
+    const text = errorSentence(raw);
+    const problem = problemOf(raw);
+    // Surface the server's correlation id (every response carries `x-request-id`)
+    // in the error message — clients see the error body but not headers, so
+    // without this the id is invisible and support can't correlate the call.
+    const rid = res.headers.get("x-request-id");
+    const code = problem.code === "machine_interrupted"
+        ? "MACHINE_INTERRUPTED"
+        : res.status === 404
+            ? "NOT_FOUND"
+            : res.status === 401
+                ? "UNAUTHORIZED"
+                : "SMOLVM_ERROR";
+    return new errors_1.SmolError(code, `${what} → ${res.status}${text ? `: ${text}` : ""}${rid ? ` [request id: ${rid}]` : ""}`, {
+        status: res.status,
+        problemCode: problem.code,
+        retryable: problem.retryable ?? retryableStatus(res.status),
+        retryAfterMs: retryAfterMs(res.headers.get("retry-after")),
+    });
+}
+/** Retries for a retryable response when the caller sets none. */
+const DEFAULT_CLOUD_RETRIES = 3;
+/** Longest single wait between retries (ms), whatever `Retry-After` asks. */
+const MAX_RETRY_WAIT_MS = 30_000;
+/** Parse a `Retry-After` header (delta-seconds or an HTTP date) into ms. */
+function retryAfterMs(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed) * 1_000;
+    const at = Date.parse(trimmed);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - now);
+}
+/** What a failed response's problem body says, beyond its sentence. */
+function problemOf(body) {
+    try {
+        const parsed = JSON.parse(body.trim());
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const fields = parsed;
+            return {
+                ...(typeof fields.code === "string" ? { code: fields.code } : {}),
+                ...(typeof fields.retryable === "boolean" ? { retryable: fields.retryable } : {}),
+            };
+        }
+    }
+    catch {
+        // Not a problem document.
+    }
+    return {};
+}
+/** Statuses the server uses for "try again": rate limited or briefly unavailable. */
+function retryableStatus(status) {
+    return status === 408 || status === 429 || status === 502 || status === 503 || status === 504;
+}
+/** Whether the SDK may resend a request on its own. A rate-limited request
+ *  never ran, so it is always safe; an unavailable one may have, so only a
+ *  call that is safe to repeat is sent again. */
+function sdkMayRetry(status, method, idempotent) {
+    if (status === 429)
+        return true;
+    if (!retryableStatus(status))
+        return false;
+    return idempotent || method === "GET" || method === "HEAD" || method === "PUT" || method === "DELETE";
+}
 async function cloudFetch(conn, method, path, opts = {}) {
+    const retries = Math.max(0, conn.maxRetries ?? DEFAULT_CLOUD_RETRIES);
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await cloudFetchOnce(conn, method, path, opts);
+        }
+        catch (error) {
+            if (!(error instanceof errors_1.SmolError) ||
+                attempt >= retries ||
+                error.status === undefined ||
+                !sdkMayRetry(error.status, method, opts.idempotent ?? false)) {
+                throw error;
+            }
+            const backoff = 500 * 2 ** attempt;
+            const wait = Math.min(error.retryAfterMs ?? backoff, MAX_RETRY_WAIT_MS);
+            await sleepUnlessAborted(wait, opts.signal);
+        }
+    }
+}
+/** Sleep `ms`, rejecting with the abort reason if `signal` fires first. */
+function sleepUnlessAborted(ms, signal) {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+async function cloudFetchOnce(conn, method, path, opts) {
     const headers = {
         authorization: `Bearer ${conn.apiKey}`,
     };
@@ -803,18 +914,10 @@ async function cloudFetch(conn, method, path, opts = {}) {
         clearTimeout(timer);
         opts.signal?.removeEventListener("abort", onAbort);
     }
-    if (!res.ok) {
-        const text = errorSentence(await res.text().catch(() => ""));
-        // Surface the server's correlation id (every response carries `x-request-id`)
-        // in the error message — clients see the error body but not headers, so
-        // without this the id is invisible and support can't correlate the call.
-        const rid = res.headers.get("x-request-id");
-        throw new errors_1.SmolError(res.status === 404
-            ? "NOT_FOUND"
-            : res.status === 401
-                ? "UNAUTHORIZED"
-                : "SMOLVM_ERROR", `cloud ${method} ${path} → ${res.status}${text ? `: ${text}` : ""}${rid ? ` [request id: ${rid}]` : ""}`);
-    }
+    if (!res.ok)
+        throw await cloudError(res, `cloud ${method} ${path}`);
+    if (opts.accept === "response")
+        return res;
     if (opts.accept === "text")
         return (await res.text());
     if (opts.accept === "bytes") {
@@ -836,11 +939,11 @@ async function cloudFetch(conn, method, path, opts = {}) {
  *  caller keeps polling until this passes or the deadline hits. */
 async function agentReachable(conn, id) {
     try {
-        await cloudFetch(conn, "POST", `/v1/machines/${id}/exec`, {
+        const result = await cloudFetch(conn, "POST", `/v1/machines/${id}/exec`, {
             json: { command: ["sh", "-c", "true"] },
             timeoutMs: 15_000,
         });
-        return true;
+        return result?.exitCode === 0;
     }
     catch {
         return false;
@@ -855,8 +958,10 @@ async function agentReachable(conn, id) {
  *  `started` is NOT yet usable: the guest is still booting, and acting then is
  *  the classic teardown race (works on a slow cold start, times out on a warm
  *  one). Older control planes omit `ready`; there we fall back to the coarse
- *  `started`/`running` state so this never hangs against them. */
-async function waitForReady(conn, id, timeoutMs = 120_000, intervalMs = 1_000) {
+ *  `started`/`running` state so this never hangs against them.
+ *  With `waitForPorts: false`, probe the agent even if ports are published:
+ *  the caller must be able to exec the service before any port can open. */
+async function waitForReady(conn, id, timeoutMs = 120_000, intervalMs = 1_000, waitForPorts = true) {
     const start = Date.now();
     const deadline = start + timeoutMs;
     for (;;) {
@@ -882,8 +987,15 @@ async function waitForReady(conn, id, timeoutMs = 120_000, intervalMs = 1_000) {
         if (state === "stopped" || state === "deleted") {
             throw new errors_1.SmolError("SMOLVM_ERROR", `machine ${id} entered ${state} before becoming ready`);
         }
+        // With deferred ports, even `started` and legacy servers' absent `ready`
+        // are insufficient: only a successful in-guest exec proves agent readiness.
+        if (!waitForPorts && (state === "started" || state === "running")) {
+            if (await agentReachable(conn, id))
+                return;
+        }
         // Back-compat: `ready` absent entirely → old server, gate on state.
-        if (m &&
+        if (waitForPorts &&
+            m &&
             m.ready === undefined &&
             (state === "started" || state === "running"))
             return;
@@ -893,7 +1005,8 @@ async function waitForReady(conn, id, timeoutMs = 120_000, intervalMs = 1_000) {
         // into). After a grace (so `ready` can flip first and this never preempts a
         // machine legitimately about to become ready), confirm the guest agent is
         // reachable directly (a trivial exec) and treat that as ready.
-        if ((state === "started" || state === "running") &&
+        if (waitForPorts &&
+            (state === "started" || state === "running") &&
             !m?.ports?.length &&
             Date.now() - start >= NO_PORT_READY_PROBE_GRACE_MS &&
             (await agentReachable(conn, id)))
@@ -1063,15 +1176,8 @@ class CloudTransport {
                 throw signal.reason;
             throw new errors_1.SmolError("CONNECTION", `cloud exec/stream failed: ${e.message}`);
         }
-        if (!res.ok) {
-            const text = errorSentence(await res.text().catch(() => ""));
-            const rid = res.headers.get("x-request-id");
-            throw new errors_1.SmolError(res.status === 404
-                ? "NOT_FOUND"
-                : res.status === 401
-                    ? "UNAUTHORIZED"
-                    : "SMOLVM_ERROR", `cloud POST /v1/machines/${this.id}/exec/stream → ${res.status}${text ? `: ${text}` : ""}${rid ? ` [request id: ${rid}]` : ""}`);
-        }
+        if (!res.ok)
+            throw await cloudError(res, `cloud POST /v1/machines/${this.id}/exec/stream`);
         if (!res.body)
             throw new errors_1.SmolError("SMOLVM_ERROR", "exec/stream returned no response body");
         // Parse the server's SSE stream: each event is `event: <kind>` + one or more
@@ -1155,6 +1261,51 @@ class CloudTransport {
             timeoutMs: transferTimeoutMs(exports.CLOUD_MAX_FILE_BYTES),
         });
     }
+    async *readFileStream(path) {
+        const route = `/v1/machines/${this.id}/files/${encodePath(path)}`;
+        const res = await cloudFetch(this.conn, "GET", route, {
+            accept: "response",
+            timeoutMs: transferTimeoutMs(exports.CLOUD_MAX_FILE_BYTES),
+        });
+        // A caller-supplied byte reader may transform the response. Honor it just
+        // as readFile does, even when the injected fetch exposes a body stream.
+        if (this.conn.readResponseBytes) {
+            const bytes = await this.conn.readResponseBytes(res);
+            if (bytes.length > 0)
+                yield bytes;
+            return;
+        }
+        if (!res.body)
+            return;
+        const reader = res.body.getReader();
+        try {
+            for (;;) {
+                let timer;
+                let chunk;
+                try {
+                    chunk = await Promise.race([
+                        reader.read(),
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => reject(new errors_1.SmolError("TIMEOUT", `cloud GET ${route} stalled for ${CLOUD_TIMEOUT_MS}ms`)), CLOUD_TIMEOUT_MS);
+                        }),
+                    ]);
+                }
+                finally {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                }
+                if (chunk.done)
+                    return;
+                if (chunk.value.length > 0)
+                    yield chunk.value;
+            }
+        }
+        finally {
+            // `break`, a thrown error, or a stalled read must close the HTTP body.
+            await reader.cancel().catch(() => { });
+            reader.releaseLock();
+        }
+    }
     async writeFile(path, data, mode) {
         checkCloudFileSize(path, data.length);
         await cloudFetch(this.conn, "PUT", `/v1/machines/${this.id}/files/${encodePath(path)}`, {
@@ -1180,13 +1331,16 @@ class CloudTransport {
         throw new errors_1.NotSupportedError("setNetworkPolicy() is local-only.");
     }
     async stop() {
-        await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/stop`);
+        await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/stop`, { idempotent: true });
     }
     async pause() {
         await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/pause`, { timeoutMs: CLOUD_START_TIMEOUT_MS });
     }
     async resume(waitUntilReady = true) {
-        await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/resume`, { timeoutMs: CLOUD_START_TIMEOUT_MS });
+        await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/resume`, {
+            timeoutMs: CLOUD_START_TIMEOUT_MS,
+            idempotent: true,
+        });
         if (waitUntilReady)
             await waitForReady(this.conn, this.id);
     }
@@ -1196,6 +1350,7 @@ class CloudTransport {
         // Resume a stopped machine, then wait for its agent so the handle is usable.
         await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/start`, {
             timeoutMs: CLOUD_START_TIMEOUT_MS,
+            idempotent: true,
         });
         if (waitUntilReady)
             await waitForReady(this.conn, this.id);
@@ -1214,6 +1369,45 @@ class CloudTransport {
             timeoutMs: CLOUD_START_TIMEOUT_MS,
         });
     }
+    async startJob(command, opts) {
+        // Not idempotent: a resend could start the command twice.
+        return cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/jobs`, {
+            json: {
+                command,
+                cwd: opts.workdir,
+                env: opts.env ?? {},
+                timeoutSeconds: opts.timeout,
+                user: opts.user,
+            },
+            timeoutMs: CLOUD_START_TIMEOUT_MS,
+        });
+    }
+    async listJobs() {
+        const out = await cloudFetch(this.conn, "GET", `/v1/machines/${this.id}/jobs`);
+        return out.jobs;
+    }
+    async getJob(jobId) {
+        return cloudFetch(this.conn, "GET", `/v1/machines/${this.id}/jobs/${encodeURIComponent(jobId)}`);
+    }
+    async jobOutput(jobId, opts) {
+        const q = new URLSearchParams({ stream: opts.stream ?? "stdout", offset: String(opts.offset ?? 0) });
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        const out = await cloudFetch(this.conn, "GET", `/v1/machines/${this.id}/jobs/${encodeURIComponent(jobId)}/output?${q}`);
+        const data = out.dataB64 !== undefined ? Buffer.from(out.dataB64, "base64") : Buffer.from(out.data);
+        return {
+            stream: out.stream,
+            offset: out.offset,
+            nextOffset: out.nextOffset,
+            data,
+            text: out.data,
+            eof: out.eof,
+        };
+    }
+    async cancelJob(jobId) {
+        // Cancelling twice is harmless, so a 503 may be resent.
+        return cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/jobs/${encodeURIComponent(jobId)}/cancel`, { idempotent: true });
+    }
     async delete() {
         await cloudFetch(this.conn, "DELETE", `/v1/machines/${this.id}`);
     }
@@ -1481,8 +1675,6 @@ async function makeTransport(config, conn) {
         // run the workload as the image's default user.
         if (config.user !== undefined)
             throw new errors_1.NotSupportedError("user is local-only.");
-        if (config.waitForPorts === false || conn.waitForPorts === false)
-            throw new errors_1.NotSupportedError("waitForPorts: false is local-only.");
         // Cloud is settled: NOW the CLI's stored login may supply the credential
         // and endpoint, which is the reuse `smol auth login` promises.
         const { apiKey: cliKey, endpoint: cliUrl } = cliSession(conn.target);
@@ -1586,7 +1778,7 @@ async function makeTransport(config, conn) {
                 startError = e instanceof Error ? e.message : String(e);
             }
             try {
-                await waitForReady(cloudConn, id);
+                await waitForReady(cloudConn, id, 120_000, 1_000, (config.waitForPorts ?? conn.waitForPorts) !== false);
             }
             catch (e) {
                 if (startError !== undefined && e instanceof errors_1.SmolError)
@@ -1612,6 +1804,9 @@ async function makeTransport(config, conn) {
         // Validate the config before loading the engine, so a config the local
         // target cannot honour fails the same way whether or not it is installed.
         const nativeConfig = toNativeConfig(name, config);
+        if (nativeConfig.image) {
+            nativeConfig.image = await (0, native_1.getNapiMachine)().prepareImage(nativeConfig.image);
+        }
         const inner = new ((0, native_1.getNapiMachine)())(nativeConfig);
         // A detached machine is nobody's to stop on a signal — it was created to
         // survive this process — and its branches inherit that.
@@ -1738,9 +1933,10 @@ async function connectTransport(id, conn) {
             const transport = new LocalTransport(conn.egressInterceptor
                 ? (0, native_1.getNapiMachine)().connect(id, conn.egressInterceptor.address, conn.egressInterceptor.token)
                 : (0, native_1.getNapiMachine)().connect(id), false, conn.egressInterceptor, conn.handleSignals ?? true);
-            // A frozen checkpoint is intentionally not agent-ready; it remains
-            // connectable so callers can fork its retained snapshot.
-            if ((await transport.state()) !== "frozen" && conn.waitForPorts !== false) {
+            // Frozen and durably paused machines are intentionally not agent-ready.
+            // A paused machine must be resumed explicitly before it can serve work.
+            const state = await transport.state();
+            if (state !== "frozen" && state !== "paused" && state !== "pausing" && conn.waitForPorts !== false) {
                 await transport.waitUntilReady();
             }
             return transport;
@@ -1751,8 +1947,6 @@ async function connectTransport(id, conn) {
     }
     if (conn.egressInterceptor)
         throw new errors_1.NotSupportedError("egressInterceptor is local-only.");
-    if (conn.waitForPorts === false)
-        throw new errors_1.NotSupportedError("waitForPorts: false is local-only.");
     // As in makeTransport: the CLI-login fallback applies only once the cloud
     // target is already selected.
     const { apiKey: cliKey, endpoint: cliUrl } = cliSession(conn.target);
@@ -1783,7 +1977,11 @@ async function connectTransport(id, conn) {
             throw e;
         m = hit;
     }
-    return new CloudTransport(cloudConn, m.name ?? id, m.id ?? id);
+    const resolvedId = m.id ?? id;
+    if (conn.waitForPorts === false && m.state !== "frozen") {
+        await waitForReady(cloudConn, resolvedId, 120_000, 1_000, false);
+    }
+    return new CloudTransport(cloudConn, m.name ?? id, resolvedId);
 }
 /** Restore a durable cloud checkpoint into a new machine, then return only once
  * the restored guest is ready. */

package/dist/types.d.ts

@@ -207,11 +207,11 @@ export interface MachineConfig {
      *  allocates the host port; readiness includes that published port accepting
      *  connections. */
     ports?: PortSpec[];
-    /** Locally, return from `Machine.create()` after the guest agent is ready,
-     *  even if a published port is not accepting connections yet. Use this when
-     *  `exec()` starts the service: the default port wait would deadlock before
-     *  `exec()` can run. Call `machine.waitUntilReady()` after starting it.
-     *  Default true; false is local-only and rejected on cloud. */
+    /** Return from `Machine.create()` after the guest agent is ready, even if a
+     *  published port is not accepting connections yet. Use this when `exec()`
+     *  starts the service: the default port wait would deadlock before `exec()`
+     *  can run. Call `machine.waitUntilReady()` after starting it.
+     *  Default true. On cloud, false probes in-guest execution before returning. */
     waitForPorts?: boolean;
     /** Resource allocation. */
     resources?: ResourceSpec;
@@ -497,11 +497,10 @@ export interface PortableCheckpointInfo {
 }
 /** Selects and configures the backend. Local (embedded) is the default. */
 export interface ConnectOptions {
-    /** Locally, allow `Machine.connect()` to return after the guest agent is
-     *  ready even when a published port is not serving. Useful when reconnecting
-     *  to stop or delete a worker whose listener has exited. Default true;
-     *  false is local-only and rejected on cloud. For `create`, put this setting
-     *  on `MachineConfig` instead. */
+    /** On local machines, allow `Machine.connect()` to return without waiting
+     *  for published ports. On cloud, false waits for successful in-guest exec
+     *  without requiring a published listener; the default connection only
+     *  attaches to the existing machine. For `create`, set this on MachineConfig. */
     waitForPorts?: boolean;
     /** Binding for a stopped local machine that requires intercepted egress. */
     egressInterceptor?: EgressInterceptor;
@@ -528,6 +527,12 @@ export interface ConnectOptions {
     /** Cloud only: read a binary response body, for a `fetch` whose responses
      *  lack a working `arrayBuffer()`. */
     readResponseBytes?: (response: Response) => Promise<Uint8Array>;
+    /** Cloud only: how many times a request the server marks retryable is sent
+     *  again, waiting as its `Retry-After` asks. A 429 is retried for any call;
+     *  a 502/503/504 only for calls that are safe to repeat (reads, deletes,
+     *  start/stop/resume), never for exec or create, which could run twice.
+     *  Default 3; 0 turns retries off. */
+    maxRetries?: number;
 }
 /** Per-launch trusted host service. Keep the token out of logs and persistent config. */
 export interface EgressInterceptor {
@@ -597,3 +602,66 @@ export interface PublishedCacheDisk {
     cacheDisk: CacheDiskInfo;
     version: CacheDiskVersion;
 }
+/** Options for {@link Machine.startJob}. Cloud only. */
+export interface JobOptions {
+    /** Environment variables. */
+    env?: Record<string, string>;
+    /** Working directory inside the machine. */
+    workdir?: string;
+    /** Stop the job with SIGTERM after this many **seconds**; it then exits 143. */
+    timeout?: number;
+    /** Run the job as this user: a name from the image or a numeric `uid[:gid]`. */
+    user?: string;
+}
+/** `running`; `exited` (see `exitCode`); or `lost`, when the machine stopped or
+ *  restarted while the job ran, so it never finished. */
+export type JobState = "running" | "exited" | "lost";
+/** A job and what is known about it. */
+export interface JobInfo {
+    id: string;
+    machineId: string;
+    /** The command as it was run (argv). */
+    command: string[];
+    state: JobState;
+    /** Set once `exited`; 143 when the job was cancelled or hit its timeout. */
+    exitCode?: number;
+    createdAt: string;
+    finishedAt?: string;
+    /** Bytes of stdout written so far, when the machine was asked. */
+    stdoutBytes?: number;
+    /** Bytes of stderr written so far, when the machine was asked. */
+    stderrBytes?: number;
+}
+/** Which slice of a job's output to read. */
+export interface JobOutputOptions {
+    /** Default `"stdout"`. */
+    stream?: "stdout" | "stderr";
+    /** Byte offset to start at. Default 0. */
+    offset?: number;
+    /** Most bytes to return. The server defaults to 256 KiB and caps at 1 MiB. */
+    limit?: number;
+}
+/** A slice of a job's stdout or stderr. */
+export interface JobOutput {
+    stream: "stdout" | "stderr";
+    /** Byte offset this slice starts at. */
+    offset: number;
+    /** Byte offset to read from next. */
+    nextOffset: number;
+    /** The slice, byte-exact. */
+    data: Buffer;
+    /** The slice as lossy UTF-8. */
+    text: string;
+    /** True once the job has finished and this slice reaches the end of the
+     *  stream: nothing more will be written. */
+    eof: boolean;
+}
+/** How {@link Job.wait} polls. */
+export interface JobWaitOptions {
+    /** Delay between polls. Default 1000 ms. */
+    pollMs?: number;
+    /** Give up with a `TIMEOUT` error after this long. Default: wait forever. */
+    timeoutMs?: number;
+    /** Stop waiting; rejects with `signal.reason`. The job keeps running. */
+    signal?: AbortSignal;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smolmachines",
-  "version": "1.26.1",
+  "version": "1.27.2",
   "description": "Embed isolated microVM sandboxes directly in your code — no server to run.",
   "license": "Apache-2.0",
   "author": "smol-machines",
@@ -51,8 +51,9 @@
     "test:e2e": "napi build --platform --js binding.js --dts binding.d.ts && tsx test/e2e.ts",
     "test:staged": "tsx test/staged-mount-e2e.ts",
     "test:agent-ready": "tsx test/local-agent-ready.ts",
+    "test:paused-connect": "tsx test/local-paused-connect.ts",
     "gen:openapi": "bash scripts/gen-openapi.sh",
-    "test:cloud": "tsx test/cloud-mock.ts",
+    "test:cloud": "tsx test/cloud-mock.ts && tsx test/cloud-deferred-ports.ts",
     "test:unit": "tsx test/unit.ts"
   },
   "devDependencies": {
@@ -63,8 +64,8 @@
     "typescript": "^5.6.0"
   },
   "optionalDependencies": {
-    "smolmachines-darwin-arm64": "1.26.1",
-    "smolmachines-linux-x64-gnu": "1.26.1",
-    "smolmachines-linux-arm64-gnu": "1.26.1"
+    "smolmachines-darwin-arm64": "1.27.2",
+    "smolmachines-linux-x64-gnu": "1.27.2",
+    "smolmachines-linux-arm64-gnu": "1.27.2"
   }
 }