@prized/sdk 0.1.0 → 0.1.2

package/dist/esm/files.js

@@ -1,10 +1,16 @@
 // sandbox.files: read, write, list, remove, upload, download.
 import { PrizedError } from './errors.js';
-import { request } from './http.js';
+import { request, timing } from './http.js';
 import { mayHaveActed, removeEffect, withOutcome, writeEffect } from './outcome.js';
 import { existsScript, listScript, removeScript, sandboxPath, shellQuote, WORKSPACE_DIR } from './shell.js';
 import { helperExec, MAX_FILE_BYTES, rawExec } from './toolbox.js';
-/** The sandbox's file transfers take at most this long, retries included. */
+/**
+ * The sandbox's file transfers take at most this long, retries included:
+ * the edge's own limit on one transfer. An attempt that moves no bytes for
+ * timing.transferStallMs (2 minutes) is given up; a download, or a write's
+ * staged upload, is then sent again (as after a lost answer or a 502, 503 or
+ * 504) while time is left.
+ */
 export const FILE_TIMEOUT_MS = 10 * 60_000;
 function byteSize(data) {
     if (typeof data === 'string')
@@ -40,12 +46,16 @@ export const EXIT_TARGET_NOT_REGULAR = 48;
 const DISCARD_MS = 10_000;
 /** A write's own commands: a rename, a chmod or an rm. */
 const WRITE_COMMAND_MS = 60_000;
-/** For the staged upload: the target is changed only by the command that follows it. */
+/**
+ * For the staged upload: the target is changed only by the command that
+ * follows it. The upload may have been sent again, so it says only what to
+ * do (langchain-prized's staged_upload_effect words it the same).
+ */
 function stagedEffect(path) {
     return {
         maybe: `${path} was not changed (its new bytes may have reached the sandbox, but were not put in place)`,
         did: `${path} was not changed yet`,
-        check: 'It was not sent again: write it again.',
+        check: 'Write it again.',
     };
 }
 /** For the command that puts the staged upload in place: a 2xx proves it ran, not how it ended. */
@@ -154,6 +164,7 @@ export class Files {
             retry: 'safe',
             read: 'bytes',
             timeoutMs: FILE_TIMEOUT_MS,
+            stallMs: timing.transferStallMs,
             deadline: this.toolbox.config.now() + FILE_TIMEOUT_MS,
             sandboxId: this.toolbox.sandboxId,
         });
@@ -165,9 +176,13 @@ export class Files {
      * A file that is replaced keeps its mode, so a script made executable
      * stays executable; a new file gets the sandbox's default (0600 in
      * prized-base-v1 and prized-agent-v1). `mode` sets the permission bits either way.
-     * Sent again only if it provably never arrived: a write whose answer was
-     * lost throws, since it may have landed and the sandbox written the file
-     * since (read it back, or write again, as suits the file).
+     * The bytes go up under a temporary name beside the file, sent again if
+     * need be (a lost answer, a 502, 503 or 504, 2 minutes with no bytes
+     * moving; all copies within the transfer's 10 minutes),
+     * and one command that is never sent again puts them in place: a write
+     * whose answer to that command was lost throws, since it may have landed
+     * and the sandbox written the file since (read it back, or write again,
+     * as suits the file).
      */
     async write(path, data, options = {}) {
         const sandboxId = this.toolbox.sandboxId;
@@ -179,14 +194,18 @@ export class Files {
         const target = sandboxPath(path);
         const plan = stagingFor(target);
         if (plan === null)
-            return this.send(target, data, size, target, writeEffect(target));
+            return this.send(target, data, size, target, writeEffect(target), 'exec');
         const { clean, staging } = plan;
         try {
-            await this.send(staging, data, size, clean, stagedEffect(clean));
+            // Every copy to the same fresh name, which only the command below puts in place.
+            await this.send(staging, data, size, clean, stagedEffect(clean), 'staged');
         }
         catch (error) {
             // A 2xx whose body could not be read: the staged bytes are all there.
             if (!landed(error)) {
+                // Removed only if a copy may have landed: a refusal, or copies that
+                // never arrived, left nothing, and a command would wake a sandbox
+                // the edge's refusal left paused.
                 if (mayHaveActed(error))
                     await this.discard(staging);
                 throw error;
@@ -212,7 +231,7 @@ export class Files {
             return { path: clean, size };
         if (result.exitCode === EXIT_TARGET_IS_LINK) {
             // A link: the files API follows it or refuses it, as for any upload.
-            const info = await this.send(clean, data, size, clean, writeEffect(clean));
+            const info = await this.send(clean, data, size, clean, writeEffect(clean), 'exec');
             if (mode !== null)
                 await this.chmod(clean, mode);
             return info;
@@ -223,18 +242,23 @@ export class Files {
         const denied = /Permission denied|Operation not permitted/.test(result.stderr);
         throw new PrizedError(denied ? 'permission_denied' : 'command_failed', `Could not write ${clean}: ${commandDetail(result)}`, { sandboxId });
     }
-    /** One upload to `path`, as the files API takes it; `target` is the file the caller asked for, and `effect` what the upload does to it. */
-    async send(path, data, size, target, effect) {
+    /**
+     * One upload to `path`, as the files API takes it; `target` is the file the
+     * caller asked for, and `effect` what the upload does to it. `exec` for an
+     * upload straight to the file: like a command, a resend after the answer
+     * was lost could overwrite what the sandbox wrote to the path since.
+     * `staged` for one to a fresh name: sent again like a read.
+     */
+    async send(path, data, size, target, effect, retry) {
         const result = await request(this.toolbox.config, {
             method: 'POST',
             url: this.url('upload', path),
             body: data,
             contentType: 'application/octet-stream',
-            // Like a command: a resend after the answer was lost could overwrite
-            // what the sandbox wrote to the path since.
-            retry: 'exec',
+            retry,
             effect,
             timeoutMs: FILE_TIMEOUT_MS,
+            stallMs: timing.transferStallMs,
             deadline: this.toolbox.config.now() + FILE_TIMEOUT_MS,
             sandboxId: this.toolbox.sandboxId,
         });

package/dist/esm/http.d.ts

@@ -6,11 +6,16 @@ export declare const DEFAULT_EDGE_URL = "https://term.prized.dev";
 export interface ClientOptions {
     /** Your API key (`dcp_…`). Default: the `PRIZED_API_KEY` environment variable. */
     apiKey?: string;
-    /** The API origin. Default: `https://api.prized.dev`. */
+    /**
+     * The API origin: https, or plain http only on this machine (`localhost`,
+     * `127.0.0.1`, `[::1]`). Default: `https://api.prized.dev`.
+     */
     baseUrl?: string;
     /**
-     * The origin that serves exec and files. Default: the `toolboxBase` the API
-     * returns for each sandbox (today `https://term.prized.dev`).
+     * The origin that serves exec and files, by the same rule as `baseUrl`.
+     * Default: the `toolboxBase` the API returns for each sandbox (today
+     * `https://term.prized.dev`), on a host trusted beside the API's
+     * (toolboxBaseFor).
      */
     edgeUrl?: string;
     /** A fetch implementation. Default: the global `fetch`. */
@@ -23,10 +28,13 @@ export interface ClientOptions {
      *  the request itself and the API's hold of a create, pause or resume. Default 500. */
     pollIntervalMs?: number;
     /**
-     * How long a streamed or long `exec` keeps polling while its polls fail
-     * (no answer, a 5xx, a rate limit), in ms, before it gives up and stops
-     * the command. Default 120 000. `0` gives up once one poll's retries run
-     * out. `exec` takes it per call too.
+     * How long a wait keeps polling while its polls fail (no answer, a 5xx, a
+     * rate limit), in ms, before it gives up: a streamed or long `exec` then
+     * stops the command, a handle's `wait()` throws. Default 120 000. `0`
+     * gives up once one poll's retries run out. `exec` and `wait()` take it
+     * per call too. The start of a background, streamed or long `exec` is
+     * sent again for as long, so an edge that restarts mid-start does not
+     * cost the command.
      */
     pollOutageMs?: number;
     /** Sleep seam (tests inject one that never really waits). */
@@ -48,13 +56,21 @@ export interface Config {
     sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
     now: () => number;
     random: () => number;
+    /**
+     * Whether an upload's body goes out as a stream the SDK feeds piece by
+     * piece, so a stalled one is seen (RequestSpec.stallMs): Node's own fetch
+     * only, which asks for each piece once the last has gone into the socket.
+     * Elsewhere (another runtime, a fetch you pass) the body goes as it is.
+     */
+    streamBodies: boolean;
 }
 export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
 /**
- * How long a streamed or long exec keeps polling while its polls fail
- * before it stops the command (pollOutageMs): long enough to ride out a
- * dropped connection or an edge that restarts. The Python SDK's
- * DEFAULT_POLL_OUTAGE.
+ * How long a wait (a streamed or long exec, a handle's wait()) keeps polling
+ * while its polls fail before it gives up (pollOutageMs), and a streamed or
+ * long exec stops its command, and how long a start is sent again: long
+ * enough to ride out a dropped connection or an edge that restarts (about
+ * 70 s, the last time it crashed). The Python SDK's DEFAULT_POLL_OUTAGE.
  */
 export declare const DEFAULT_POLL_OUTAGE_MS = 120000;
 /** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
@@ -63,7 +79,10 @@ export declare function resolveConfig(options?: ClientOptions): Config;
 /**
  * Where exec and files go for one sandbox. An explicit edgeUrl wins; else the
  * API's own `toolboxBase` when it has the expected shape (https, or plain
- * http on loopback for local development); else the default edge.
+ * http on loopback for local development, ending /v1/sandbox/<id>) on a host
+ * trusted beside the API's (term.prized.dev beside api.prized.dev; see
+ * trustedEdge); else the default edge, for Prized's own API only. The API key
+ * is never sent anywhere else: discovery is routing, not authority.
  */
 export declare function toolboxBaseFor(config: Config, sandboxId: string, toolboxBase: string | null): string;
 /**
@@ -88,13 +107,20 @@ export declare function warmEdge(config: Config): Promise<void>;
  *   Retries network failures, 429/502/503/504, and everything `exec`
  *   retries (the edge's 500 control_plane_unavailable among them). A GET
  *   retries any 500 too (the API's `internal`).
- * - `exec`: a command, an upload or a remove: what the sandbox does
- *   meanwhile could be undone by a second copy. Retried only when it
+ * - `exec`: a command, an upload, a remove or a label-selected delete:
+ *   a second copy could affect later work. Retried only when it
  *   provably never arrived: a connection that never opened, or an answer
  *   saying so (the edge's rate limit, its lookup failing). A lost answer
  *   is never retried: it may already have run.
+ * - `staged`: a write's upload to a fresh name beside its target, which only
+ *   a command after it puts in place (files.ts). Retried as `safe` (a lost
+ *   answer, a timeout, 429/502/503/504) and `exec` both, a GET's 500 aside:
+ *   every copy writes the same bytes under the same name, which nothing else
+ *   writes, so a second one changes no file of the caller's. A 2xx whose body
+ *   broke off is not sent again: the bytes are there. Its error says whether
+ *   a copy may have reached the sandbox.
  */
-export type RetryMode = 'safe' | 'exec';
+export type RetryMode = 'safe' | 'exec' | 'staged';
 /**
  * Whether a fetch that threw never sent its request: the connection was
  * refused, the name did not resolve, or connecting timed out. Anything else
@@ -123,6 +149,14 @@ export interface RequestSpec {
     sandboxId?: string | null;
     /** How to read a 2xx body. Default `json`. */
     read?: 'json' | 'bytes' | 'none';
+    /**
+     * A file transfer's no-progress bound: an attempt that moves no bytes
+     * either way for this long (a connection dropped without a reset) ends as
+     * a timeout, sent again by `retry`'s rules while `deadline` allows. An
+     * upload's sending is watched only where its body is streamed
+     * (Config.streamBodies); its answer always is.
+     */
+    stallMs?: number;
     /**
      * Told of every attempt that failed (no answer, an error answer, or a 2xx
      * that could not be read), before it is retried or thrown. A create or
@@ -137,6 +171,12 @@ export interface RequestSpec {
      * its error says so too.
      */
     effect?: Effect;
+    /**
+     * An earlier copy of this keyed request may have reached the sandbox (the
+     * background start, sent again through an outage), so its error says so
+     * too.
+     */
+    acted?: boolean;
 }
 export interface HttpResult {
     status: number;
@@ -199,6 +239,25 @@ export declare class Polls {
 }
 /** Delay before retry number `attempt` (0-based): exponential with jitter. */
 export declare function backoffMs(config: Config, attempt: number): number;
+/**
+ * How long a file transfer may move no bytes before the attempt is given up
+ * (sdk/retry-spec.json transferStallMs; the Python SDK's TRANSFER_STALL).
+ * The edge holds a request about 20 s at most before it reads the body (its
+ * admission queue, then waking a paused sandbox), and ends a body that brings
+ * nothing for 60 s itself: kept above that, a stalled copy is over at the
+ * edge before the next one goes to the same staged name, so the two never
+ * race. Once an upload's last byte is handed over, its answer is waited for
+ * that and a second more for every uploadAnswerBytesPerSecond it sent: what
+ * the socket's buffers, or a proxy that takes a whole body before it sends it
+ * on, still hold moves unseen, and must not read as a stall (the Python SDK's
+ * UPLOAD_ANSWER_RATE). Mutable for tests only.
+ */
+export declare const timing: {
+    transferStallMs: number;
+    uploadAnswerBytesPerSecond: number;
+};
+/** A streamed upload goes out this many bytes at a time. */
+export declare const UPLOAD_CHUNK: number;
 /**
  * What an error answer (not a 2xx: request() judges those) says about
  * whether the sandbox acted: `never` for the codes that prove the request