beachside 0.8.0 → 0.9.0

package/README.md

@@ -6,17 +6,25 @@ Install `beachside @beachside/daytona` (or `beachside @beachside/e2b`).
 
 ```ts
 import { Beachside } from "beachside";
-import { daytona } from "@beachside/daytona";
+import { daytonaAdapter } from "@beachside/daytona";
 
-const beachside = await Beachside.connect(daytona({ apiKey: process.env.DAYTONA_API_KEY!, target: "us" }));
+const beachside = await Beachside.connect({
+  adapter: daytonaAdapter,
+  credentials: { apiKey: process.env.DAYTONA_API_KEY! },
+  config: { target: "us" },
+});
 await beachside.close();
 ```
 
 ```ts
 import { Beachside, Image } from "beachside";
-import { daytona } from "@beachside/daytona";
+import { daytonaAdapter } from "@beachside/daytona";
 
-const beachside = await Beachside.connect(daytona({ apiKey: process.env.DAYTONA_API_KEY!, target: "us" }));
+const beachside = await Beachside.connect({
+  adapter: daytonaAdapter,
+  credentials: { apiKey: process.env.DAYTONA_API_KEY! },
+  config: { target: "us" },
+});
 try {
   const box = await beachside.sandboxes.create({ environment: Image.prepared("your-snapshot-id") });
   try {

package/dist/file-transfer.d.ts

@@ -22,7 +22,13 @@ export declare class FilesystemError extends BeachsideError {
 }
 export declare function filesystemError(error: unknown): Error;
 export declare function byteLimit(value: number | undefined, defaultValue?: number): number | undefined;
+/**
+ * The effective limit of one buffered adapter read or write: the caller's optional `maxBytes`
+ * guard, bounded by the adapter's own buffered limit. Larger files use the adapter's streams.
+ */
 export declare function bufferedLimit(value: number | undefined, adapterLimit: number): number;
+/** The error for a file larger than an adapter without file streams can move in one call. */
+export declare function adapterFileLimit(adapterLimit: number, code: "CAPACITY" | "OUTPUT_CAPACITY"): BeachsideError;
 export declare function streamFile(read: (ctx: ReadContext) => Promise<ReadableStream<Uint8Array>>, closed: AbortSignal, options: FileStreamOptions, defaults: TransferPolicy): AsyncIterable<Uint8Array>;
 export declare function writeStream(write: (bytes: AsyncIterable<Uint8Array>, ctx: FileTransferContext) => Promise<{
     bytesWritten: number;

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export declare const Beachside: {
     connect: typeof connectDirect;
 };
 export { Image, outputText, BeachsideError, UnsupportedFeatureError, OutcomeUnknownError, WaitAbortedError, NonzeroExitError, NoExitCodeError, } from "./resource.js";
-export type { ImageInput, PreparedImage, ImageBuildResult, CreateInput, NetworkPolicy, ExecInput, ExecOutput, OutputPreview, DirectBeachsideClient, DirectSandboxHandle, SandboxHandle, SnapshotHandle, ImageHandle, VolumeHandle, ReadOptions, OperationHandle, RecoveryReference, BeachsideClient, } from "./resource.js";
+export type { ImageInput, PreparedImage, ImageBuildResult, CreateInput, NetworkPolicy, ExecInput, ExecStdinStream, ExecOutput, OutputPreview, DirectBeachsideClient, DirectSandboxHandle, SandboxHandle, SnapshotHandle, ImageHandle, VolumeHandle, ReadOptions, OperationHandle, RecoveryReference, BeachsideClient, } from "./resource.js";
 export { ResourceReference, ResourceKind, validateResourceReference, assertResourceScope, assertResourceIdentity, SnapshotRequest, SnapshotRequirements, Preserve, } from "@beachside/adapter";
 export type { Support, Capabilities, DirectCapabilities, OperationOutcome, SnapshotPlan, SnapshotProfile, SandboxState, SandboxReference, SuspendResult, ResumeResult, RenewRequest, RenewResult, Preview, Fact, Deadline, ResourceMinimums, SandboxResources, CreatePlan, } from "@beachside/adapter";
 export { AdapterSnapshot, AdapterVolume, AdapterImage } from "./resources.js";

package/dist/index.js

@@ -26,6 +26,97 @@ var Image = {
     return { kind: "oci", value };
   }
 };
+function isStdinStream(value) {
+  return value instanceof ReadableStream || value !== null && typeof value === "object" && !(value instanceof Uint8Array) && Symbol.asyncIterator in value;
+}
+function stdinNeedsStream(stdin) {
+  if (stdin === undefined)
+    return false;
+  if (isStdinStream(stdin))
+    return true;
+  if (stdin instanceof Uint8Array)
+    return stdin.byteLength > MAX_EXEC_STDIN_BYTES;
+  return stdin.length * 3 > MAX_EXEC_STDIN_BYTES && utf8Bytes(stdin) > MAX_EXEC_STDIN_BYTES;
+}
+function utf8Bytes(text) {
+  return new TextEncoder().encode(text).byteLength;
+}
+function streamedStdin(stdin) {
+  if (stdin === undefined || !stdinNeedsStream(stdin))
+    return;
+  if (stdin instanceof ReadableStream)
+    return readableSource(stdin);
+  if (isStdinStream(stdin))
+    return iterableSource(stdin);
+  let bytes = stdin instanceof Uint8Array ? Uint8Array.from(stdin) : new TextEncoder().encode(stdin);
+  return {
+    async next() {
+      const chunk = bytes;
+      bytes = null;
+      return chunk;
+    },
+    cancel() {
+      bytes = null;
+    }
+  };
+}
+function stdinChunk(value) {
+  if (!(value instanceof Uint8Array))
+    throw new BeachsideError("INVALID_ARGUMENT", "Expected stdin stream byte chunks");
+  return value;
+}
+function readableSource(stream) {
+  let reader;
+  let cancelled = false;
+  return {
+    async next() {
+      if (cancelled)
+        return null;
+      reader ??= stream.getReader();
+      const part = await reader.read();
+      if (!part.done)
+        return stdinChunk(part.value);
+      cancelled = true;
+      reader.releaseLock();
+      return null;
+    },
+    cancel() {
+      if (cancelled)
+        return;
+      cancelled = true;
+      if (!reader) {
+        stream.cancel().catch(() => {
+          return;
+        });
+        return;
+      }
+      const owned = reader;
+      owned.cancel().catch(() => {
+        return;
+      }).finally(() => owned.releaseLock());
+    }
+  };
+}
+function iterableSource(iterable) {
+  const iterator = iterable[Symbol.asyncIterator]();
+  let cancelled = false;
+  return {
+    async next() {
+      if (cancelled)
+        return null;
+      const part = await iterator.next();
+      return part.done ? null : stdinChunk(part.value);
+    },
+    cancel() {
+      if (cancelled)
+        return;
+      cancelled = true;
+      Promise.resolve().then(() => iterator.return?.()).catch(() => {
+        return;
+      });
+    }
+  };
+}
 var ExecStdinInput = z.union([
   z.string().max(MAX_EXEC_STDIN_BYTES).transform((value) => ({ kind: "text", value })),
   z.instanceof(Uint8Array).refine((value) => value.byteLength <= MAX_EXEC_STDIN_BYTES).transform((value) => ({ kind: "bytes", value }))
@@ -229,6 +320,8 @@ function validateExec(input, options = {}) {
   if (options.allowStdin === false && !isArgumentArray(input) && request?.stdin !== undefined)
     throw new BeachsideError("INVALID_ARGUMENT", "stdin is available only for finite exec input");
   let stdin;
+  if (request?.stdin !== undefined && isStdinStream(request.stdin))
+    throw new BeachsideError("INVALID_ARGUMENT", "Streamed stdin is available through exec(), not as finite input");
   if (request?.stdin !== undefined) {
     const parsedInput = ExecStdinInput.safeParse(request.stdin);
     if (!parsedInput.success)
@@ -418,10 +511,12 @@ class FilesystemError extends BeachsideError {
   }
 }
 function filesystemError(error) {
-  if (error instanceof AdapterFilesystemError)
-    return new FilesystemError(error.code, error.message, error.details);
-  if (error instanceof AdapterError)
-    return new BeachsideError(error.code, error.message);
+  if (error instanceof AdapterError) {
+    const mapped = error instanceof AdapterFilesystemError ? new FilesystemError(error.code, error.message, error.details) : new BeachsideError(error.code, error.message);
+    if (error.cause !== undefined)
+      mapped.cause = error.cause;
+    return mapped;
+  }
   return error instanceof Error ? error : new Error("Filesystem operation failed", { cause: error });
 }
 function byteLimit(value, defaultValue) {
@@ -431,10 +526,12 @@ function byteLimit(value, defaultValue) {
   return limit;
 }
 function bufferedLimit(value, adapterLimit) {
-  const limit = byteLimit(value, 1048576);
-  if (limit > 16777216)
-    throw new BeachsideError("INVALID_ARGUMENT", "Buffered file limit exceeds 16 MiB; use streams");
-  return Math.min(limit, byteLimit(adapterLimit));
+  const limit = byteLimit(value);
+  const adapter = byteLimit(adapterLimit);
+  return limit === undefined ? adapter : Math.min(limit, adapter);
+}
+function adapterFileLimit(adapterLimit, code) {
+  return new BeachsideError(code, `File exceeds this adapter's ${adapterLimit}-byte file limit; it has no file streams`, code === "OUTPUT_CAPACITY" ? "unknown" : "none");
 }
 
 class Transfer {
@@ -892,7 +989,7 @@ function certifiedRecoveryAvailable(reference) {
 // package.json
 var package_default = {
   name: "beachside",
-  version: "0.8.0",
+  version: "0.9.0",
   private: false,
   type: "module",
   files: [
@@ -2597,9 +2694,15 @@ async function callbackExec(client, sandbox, controlActive, input, options) {
   const callback = options.onOutput;
   if (typeof callback !== "function")
     throw new BeachsideError("INVALID_ARGUMENT", "Expected execution output callback");
-  const request = validateExec(input);
-  if (!Array.isArray(input) && "deadlineSeconds" in input && input.deadlineSeconds !== undefined)
+  const object = Array.isArray(input) || !("command" in input) ? undefined : input;
+  const streamed = streamedStdin(object?.stdin);
+  const request = validateExec(streamed && object ? { ...object, stdin: undefined } : input);
+  const deadlineSeconds = object?.deadlineSeconds;
+  const localDeadline = streamed ? deadlineSeconds ?? request.deadlineSeconds : undefined;
+  if (!streamed && deadlineSeconds !== undefined)
     throw new BeachsideError("UNSUPPORTED", "Callback execution cannot map deadlineSeconds on the process transport; use signal to bound local observation");
+  if (streamed && client.session.processes?.supports?.stdin !== "bytes")
+    throw new BeachsideError("UNSUPPORTED", "Streamed stdin and stdin over 1 MiB need incremental process stdin, which this adapter lacks");
   const maxOutputBytes = client.session.supports.exec?.maxOutputBytes;
   if (maxOutputBytes !== undefined && request.maxOutputBytes > maxOutputBytes)
     throw new BeachsideError("UNSUPPORTED", "Requested execution output limit is unsupported");
@@ -2610,7 +2713,7 @@ async function callbackExec(client, sandbox, controlActive, input, options) {
     cwd: request.cwd,
     env: request.env,
     output: { mode: "stream" },
-    stdin: request.stdin === undefined ? "closed" : "pipe"
+    stdin: request.stdin === undefined && !streamed ? "closed" : "pipe"
   }, options, controlActive, { maxBytes: request.maxOutputBytes });
   const observation = new AbortController;
   const signal = AbortSignal.any([
@@ -2654,20 +2757,58 @@ async function callbackExec(client, sandbox, controlActive, input, options) {
       await raceAbort(Promise.resolve().then(invoke), signal);
     }
   })().catch(stop);
+  const source = streamed ?? (request.stdin === undefined ? undefined : (() => {
+    let bytes = request.stdin;
+    return {
+      async next() {
+        const chunk = bytes;
+        bytes = null;
+        return chunk;
+      },
+      cancel() {
+        bytes = null;
+      }
+    };
+  })());
+  let delivered = false;
   const delivery = (async () => {
-    if (request.stdin !== undefined) {
-      for (let offset = 0;offset < request.stdin.length; offset += 65536) {
+    if (source === undefined)
+      return;
+    for (let chunk = await source.next();chunk; chunk = await source.next())
+      for (let offset = 0;offset < chunk.length; offset += 65536) {
         if (signal.aborted)
           throw signal.reason;
-        await process.write(request.stdin.subarray(offset, offset + 65536), { signal });
+        if (streamed && exit)
+          return;
+        await process.write(chunk.subarray(offset, offset + 65536), { signal });
       }
-      if (signal.aborted)
-        throw signal.reason;
-      await process.closeStdin({ signal });
-    }
-  })().catch(stop);
+    if (signal.aborted)
+      throw signal.reason;
+    delivered = true;
+    await process.closeStdin({ signal });
+  })().then(() => {
+    return;
+  }, (error) => {
+    if (streamed && exit)
+      return;
+    stop(error);
+  });
+  const deadline = localDeadline === undefined ? undefined : setTimeout(() => {
+    initiatingFailure ??= {
+      error: new BeachsideError("TIMEOUT", `Execution exceeded deadlineSeconds (${localDeadline}); termination was requested`, "possible")
+    };
+    observation.abort();
+    process.terminate({ signal: AbortSignal.timeout(30000) }).catch(() => {
+      return;
+    });
+  }, localDeadline * 1000);
   try {
-    await Promise.all([delivery, output, waiting, raceAbort(capture, signal)]);
+    await Promise.all([
+      streamed ? Promise.race([delivery, waiting]) : delivery,
+      output,
+      waiting,
+      raceAbort(capture, signal)
+    ]);
     if (captured.exitCode !== exit.exitCode)
       throw new BeachsideError("INVALID_RESPONSE", "Execution capture conflicts with confirmed exit", "possible");
     return checkExec(captured);
@@ -2691,6 +2832,9 @@ async function callbackExec(client, sandbox, controlActive, input, options) {
       context2.output = captured;
     throw context2;
   } finally {
+    clearTimeout(deadline);
+    if (!delivered)
+      source?.cancel();
     await process.detach();
   }
 }
@@ -3292,7 +3436,7 @@ function fileOptions(options) {
 function fileReadLimit(maxBytes) {
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
     throw new BeachsideError("INVALID_ARGUMENT", "Adapter file limit is invalid", "none");
-  return Math.min(maxBytes, 1048576);
+  return maxBytes;
 }
 function abortWaiting(ref, reason, outcome) {
   throw new WaitAbortedError(ref, reason, outcome ?? acknowledgedLifecycleOutcome(ref));
@@ -3948,10 +4092,13 @@ class AdapterSandbox {
     });
   }
   async exec(input, options = {}) {
-    if (options.onOutput !== undefined) {
+    const streamed = !Array.isArray(input) && "command" in input && stdinNeedsStream(input.stdin);
+    if (options.onOutput !== undefined || streamed) {
       this.client.ensureOpen();
       const control = processControl(this.client, this.id);
-      return callbackExec(this.client, sandboxInput(this.id, this.reference), () => control.active, input, options);
+      return callbackExec(this.client, sandboxInput(this.id, this.reference), () => control.active, input, options.onOutput ? options : { ...options, onOutput: () => {
+        return;
+      } });
     }
     return waitFor(this.client.telemetry, await internalMethod(this.submitExec)(input, options), options);
   }
@@ -4140,12 +4287,38 @@ class AdapterSandbox {
   }
   async readFile(path, options = {}) {
     this.client.ensureOpen();
-    if (!this.client.session.files?.read)
+    const files = this.client.session.files;
+    if (!files?.read)
       unsupported("readFile");
     validateFilePath(path);
-    const maxBytes = bufferedLimit(options.maxBytes, this.client.session.files.maxBytes);
-    const read = this.client.session.files.read.bind(this.client.session.files);
-    return readFileBytes((context2) => read({ sandbox: sandboxInput(this.id, this.reference), path, maxBytes }, context2), maxBytes, this.client.signal, options);
+    const guard = byteLimit(options.maxBytes);
+    const maxBytes = bufferedLimit(guard, files.maxBytes);
+    const read = files.read.bind(files);
+    try {
+      return await readFileBytes((context2) => read({ sandbox: sandboxInput(this.id, this.reference), path, maxBytes }, context2), maxBytes, this.client.signal, options);
+    } catch (error) {
+      const adapterBound = guard === undefined || guard > files.maxBytes;
+      if (!(error instanceof BeachsideError) || error.code !== "OUTPUT_CAPACITY" || !adapterBound)
+        throw error;
+      if (!files.readStream)
+        throw adapterFileLimit(files.maxBytes, "OUTPUT_CAPACITY");
+    }
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of this.readFileStream(path, {
+      signal: options.signal,
+      maxBytes: guard
+    })) {
+      chunks.push(chunk);
+      total += chunk.byteLength;
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return bytes;
   }
   async writeFile(path, bytes, options = {}) {
     if (!this.supports("writeFile"))
@@ -4153,10 +4326,13 @@ class AdapterSandbox {
     validateFilePath(path);
     if (!(bytes instanceof Uint8Array))
       throw new BeachsideError("INVALID_ARGUMENT", "Expected byte buffer");
-    const limit2 = bufferedLimit(options.maxBytes, this.client.session.files.maxBytes);
-    if (bytes.length > limit2)
+    const files = this.client.session.files;
+    const guard = byteLimit(options.maxBytes);
+    if (guard !== undefined && bytes.length > guard)
       throw new BeachsideError("CAPACITY", "File exceeds byte limit");
-    if (bytes.length > 1048576 && this.client.session.files?.writeStream) {
+    if (bytes.length > files.maxBytes && !files.writeStream)
+      throw adapterFileLimit(files.maxBytes, "CAPACITY");
+    if ((bytes.length > 1048576 || bytes.length > files.maxBytes) && files.writeStream) {
       const payload2 = Uint8Array.from(bytes);
       async function* chunks() {
         yield payload2;
@@ -5030,6 +5206,8 @@ class AdapterDirectClient {
   }
 }
 async function connectDirect(options, observability = {}) {
+  if (options instanceof Function || "adapter" in options && options.adapter instanceof Function)
+    throw new BeachsideError("INVALID_ARGUMENT", "Expected an adapter definition, got a function: pass the definition (`adapter: vercelAdapter`) or call the provider factory (`Beachside.connect(vercel({ ... }))`)", "none");
   const cleanup = z8.strictObject({ storage: z8.enum(["require-durable", "allow-unconfirmed"]).optional() }).optional().safeParse(("bound" in options ? observability : options).cleanup);
   if (!cleanup.success)
     throw new BeachsideError("INVALID_ARGUMENT", "Invalid cleanup configuration", "none");

package/dist/resource.d.ts

@@ -58,12 +58,31 @@ export type ExecInput = {
     command: ExecCommand;
     cwd?: string;
     env?: Record<string, string>;
-    /** Finite stdin bytes; strings encode as UTF-8 and supplied input ends with guest EOF. */
-    stdin?: string | Uint8Array;
+    /**
+     * Command input, ending with guest EOF. Strings encode as UTF-8. A stream (`AsyncIterable` or
+     * `ReadableStream` of bytes) is sent as it arrives, with no size limit, while the command runs;
+     * streams and input over 1 MiB need an adapter with incremental process stdin.
+     */
+    stdin?: string | Uint8Array | ExecStdinStream;
     /** Provider-specific execution/observation limit (default 300), not a total wait budget. Use the call signal to bound local waiting. */
     deadlineSeconds?: number;
     maxOutputBytes?: number;
 };
+/** Streamed command input: any async iterable or web stream of byte chunks. */
+export type ExecStdinStream = AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>;
+export declare function isStdinStream(value: ExecInput["stdin"]): value is ExecStdinStream;
+/** Whether stdin must travel incrementally: a stream, or bytes or text over the finite bound. */
+export declare function stdinNeedsStream(stdin: ExecInput["stdin"]): boolean;
+/**
+ * Input that must travel incrementally, read one chunk at a time. `cancel` stops the source when
+ * the command no longer needs it, releasing a web stream's reader even while a read is pending.
+ */
+export type StdinSource = {
+    next(): Promise<Uint8Array | null>;
+    cancel(): void;
+};
+/** The streamed source for `stdin`, or undefined for finite input that fits the bound. */
+export declare function streamedStdin(stdin: ExecInput["stdin"]): StdinSource | undefined;
 export type ValidatedExecInput = Required<Pick<ExecInput, "command" | "deadlineSeconds" | "maxOutputBytes">> & Omit<ExecInput, "stdin"> & {
     stdin?: Uint8Array;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beachside",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "files": [
@@ -19,14 +19,14 @@
     "build": "rm -rf dist && bun build src/index.ts --target node --format esm --splitting --outdir dist --external @beachside/adapter --external zod --external @opentelemetry/api && tsc -p tsconfig.json --noEmit false --declaration --emitDeclarationOnly --outDir dist && bun ../../scripts/rewrite-declarations.mjs"
   },
   "dependencies": {
-    "@beachside/adapter": "0.8.0",
+    "@beachside/adapter": "0.9.0",
     "zod": "4.6.5",
     "@opentelemetry/api": "1.9.1"
   },
   "devDependencies": {
     "@beachside-internal/provider-fake": "0.0.0",
-    "@beachside/daytona": "0.8.0",
-    "@beachside/e2b": "0.8.0"
+    "@beachside/daytona": "0.9.0",
+    "@beachside/e2b": "0.9.0"
   },
   "license": "Apache-2.0",
   "repository": {