@prized/sdk 0.1.0 → 0.1.1

package/dist/cjs/files.js

@@ -9,7 +9,12 @@ const http_js_1 = require("./http.js");
 const outcome_js_1 = require("./outcome.js");
 const shell_js_1 = require("./shell.js");
 const toolbox_js_1 = require("./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. A write's upload sent again (a
+ * staged one is, after a lost answer or a 502, 503 or 504) is sent only
+ * while time is left, so a transfer that timed out is not.
+ */
 exports.FILE_TIMEOUT_MS = 10 * 60_000;
 function byteSize(data) {
     if (typeof data === 'string')
@@ -45,12 +50,16 @@ exports.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. */
@@ -170,9 +179,13 @@ 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; 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;
@@ -184,14 +197,18 @@ class Files {
         const target = (0, shell_js_1.sandboxPath)(path);
         const plan = stagingFor(target);
         if (plan === null)
-            return this.send(target, data, size, target, (0, outcome_js_1.writeEffect)(target));
+            return this.send(target, data, size, target, (0, outcome_js_1.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 ((0, outcome_js_1.mayHaveActed)(error))
                     await this.discard(staging);
                 throw error;
@@ -217,7 +234,7 @@ class Files {
             return { path: clean, size };
         if (result.exitCode === exports.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, (0, outcome_js_1.writeEffect)(clean));
+            const info = await this.send(clean, data, size, clean, (0, outcome_js_1.writeEffect)(clean), 'exec');
             if (mode !== null)
                 await this.chmod(clean, mode);
             return info;
@@ -228,16 +245,20 @@ class Files {
         const denied = /Permission denied|Operation not permitted/.test(result.stderr);
         throw new errors_js_1.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 (0, http_js_1.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: exports.FILE_TIMEOUT_MS,
             deadline: this.toolbox.config.now() + exports.FILE_TIMEOUT_MS,

package/dist/cjs/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,11 @@ 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.
      */
     pollOutageMs?: number;
     /** Sleep seam (tests inject one that never really waits). */
@@ -51,10 +57,10 @@ export interface Config {
 }
 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: long enough to ride out a dropped connection
+ * or an edge that restarts. 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 +69,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;
 /**
@@ -93,8 +102,15 @@ export declare function warmEdge(config: Config): Promise<void>;
  *   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

package/dist/cjs/http.js

@@ -33,7 +33,15 @@ function envApiKey() {
 function isLoopback(hostname) {
     return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
 }
-/** An http(s) origin, trailing slashes and a trailing /api/v1 dropped. */
+/**
+ * https anywhere, plain http only to this machine: the API key rides in
+ * every request's Authorization header. The same rule for the options and
+ * for an edge the API names.
+ */
+function secureEndpoint(url) {
+    return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
+}
+/** An https (or loopback http) origin, trailing slashes and a trailing /api/v1 dropped. */
 function normalizeOrigin(name, raw) {
     let url;
     try {
@@ -45,6 +53,9 @@ function normalizeOrigin(name, raw) {
     if (url.protocol !== 'https:' && url.protocol !== 'http:') {
         throw new errors_js_1.PrizedError('invalid_argument', `${name} must be an http(s) URL`);
     }
+    if (!secureEndpoint(url)) {
+        throw new errors_js_1.PrizedError('invalid_argument', `${name} must use https (plain http only for localhost, 127.0.0.1 or [::1])`);
+    }
     if (url.username || url.password || url.search || url.hash) {
         throw new errors_js_1.PrizedError('invalid_argument', `${name} must not carry credentials, a query or a fragment`);
     }
@@ -69,10 +80,10 @@ function abortableSleep(ms, signal) {
     });
 }
 /**
- * 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: long enough to ride out a dropped connection
+ * or an edge that restarts. The Python SDK's DEFAULT_POLL_OUTAGE.
  */
 exports.DEFAULT_POLL_OUTAGE_MS = 120_000;
 /** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
@@ -116,20 +127,51 @@ function resolveConfig(options = {}) {
         random: options.random ?? Math.random,
     };
 }
+/** Prized's own domain: its API and its edges are hosts under it. */
+const PRIZED_DOMAIN = 'prized.dev';
+function under(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/** A URL's hostname (lowercase, as URL gives it), or '' if it does not parse. */
+function hostOf(raw) {
+    try {
+        return new URL(raw).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Where a toolboxBase may point, given the API's host: the API host itself;
+ * prized.dev's own hosts when the API is one of them; loopback when the API
+ * is. Never a domain guessed from the API host's name (a public suffix such
+ * as co.uk would trust everyone under it). The Python SDK's _trusted_edge.
+ */
+function trustedEdge(edgeHost, apiHost) {
+    if (edgeHost === '' || apiHost === '')
+        return false;
+    if (isLoopback(apiHost) || isLoopback(edgeHost))
+        return isLoopback(apiHost) && isLoopback(edgeHost);
+    return edgeHost === apiHost || (under(apiHost, PRIZED_DOMAIN) && under(edgeHost, PRIZED_DOMAIN));
+}
 /**
  * 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.
  */
 function toolboxBaseFor(config, sandboxId, toolboxBase) {
     const path = `/v1/sandbox/${encodeURIComponent(sandboxId)}`;
     if (config.edgeUrl !== null)
         return `${config.edgeUrl}${path}`;
+    const apiHost = hostOf(config.baseUrl);
     if (toolboxBase) {
         try {
             const url = new URL(toolboxBase);
-            const secure = url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
-            if (secure &&
+            if (secureEndpoint(url) &&
+                trustedEdge(url.hostname, apiHost) &&
                 !url.username &&
                 !url.password &&
                 !url.search &&
@@ -142,7 +184,11 @@ function toolboxBaseFor(config, sandboxId, toolboxBase) {
             // fall through to the default
         }
     }
-    return `${exports.DEFAULT_EDGE_URL}${path}`;
+    // Prized's own edge only for Prized's own API: a key for another
+    // deployment is never sent to it. That deployment names its edge.
+    if (under(apiHost, PRIZED_DOMAIN))
+        return `${exports.DEFAULT_EDGE_URL}${path}`;
+    throw new errors_js_1.PrizedError('edge_unknown', `The API at ${config.baseUrl} named no command endpoint this SDK trusts for ${sandboxId}; pass edgeUrl for that deployment.`, { sandboxId });
 }
 /**
  * The edge this config's sandboxes answer on, before the API has named one:
@@ -239,7 +285,7 @@ function retryable(error, mode, method) {
     // have done a write's work, so a write is left to its caller (a create
     // that may have made a sandbox finds and deletes it). A GET did nothing:
     // a poll that meets one is sent again rather than failing its create.
-    if (error.status === 500 && method === 'GET')
+    if (mode === 'safe' && error.status === 500 && method === 'GET')
         return true;
     return error.status === 429 || error.status === 502 || error.status === 503 || error.status === 504;
 }
@@ -427,8 +473,9 @@ function outcomeOf(error) {
 /**
  * The error a request throws. With an `effect`, it says whether the sandbox
  * acted on the request: by this attempt, or by an earlier one that was sent
- * again (`acted`: only a keyed request, the background start, is sent again
- * after it may have arrived). `cutStatus`: the 2xx whose body broke off.
+ * again (`acted`: only a keyed request, the background start, and a staged
+ * upload are sent again after they may have arrived). `cutStatus`: the 2xx
+ * whose body broke off.
  */
 function raised(failure, outcome, acted, effect, cutStatus = null) {
     if (effect === undefined)
@@ -443,7 +490,8 @@ async function request(config, spec) {
     const timeoutMs = spec.timeoutMs ?? config.requestTimeoutMs;
     const sandboxId = spec.sandboxId ?? null;
     const effect = spec.effect ?? (spec.retry === 'exec' ? (0, outcome_js_1.commandEffect)() : undefined);
-    const unsent = spec.retry === 'exec' ? effect : undefined;
+    // Whether an attempt that was sent again may have reached the sandbox.
+    let acted = false;
     // Names the last attempt's failure, if any, so a call cut short by its
     // deadline still says what it was waiting out (a 503, a rate limit).
     const pastDeadline = (last) => {
@@ -451,9 +499,10 @@ async function request(config, spec) {
         const tail = what === null ? '' : ` The last attempt failed with ${what}.`;
         let error = new errors_js_1.PrizedError('timeout', `The time allowed for this call ran out.${tail}`, { sandboxId, cause: last });
         // A command is sent again only when it provably never arrived, so every
-        // attempt of one cut short this way never reached the sandbox.
-        if (unsent !== undefined)
-            error = (0, outcome_js_1.withOutcome)(error, unsent, 'never');
+        // attempt of one cut short this way never reached the sandbox. A staged
+        // upload's copies may have, unless each provably never arrived.
+        if (effect !== undefined && spec.retry !== 'safe')
+            error = (0, outcome_js_1.withOutcome)(error, effect, spec.retry === 'staged' && acted ? 'maybe' : 'never');
         cutShort.add(error);
         return error;
     };
@@ -462,8 +511,6 @@ async function request(config, spec) {
         return error;
     };
     let last;
-    // Whether an attempt that was sent again may have reached the sandbox.
-    let acted = false;
     // An abort with an `effect` says whether the sandbox may have acted:
     // before an attempt, or while waiting to send one again, nothing was sent
     // that might have, unless an earlier attempt of a keyed request (`acted`)
@@ -500,8 +547,9 @@ async function request(config, spec) {
             // The status came and the body did not: the sandbox acted on it.
             const cut = outcome.status !== null && outcome.status >= 200 && outcome.status < 300;
             const said = cut ? 'did' : unsentAttempt ? 'never' : 'maybe';
-            // A command or upload is sent again only if it never left.
-            const resend = spec.retry === 'safe' || (spec.retry === 'exec' && unsentAttempt);
+            // A command is sent again only if it never left; a staged upload
+            // unless its 2xx came (its bytes are there).
+            const resend = spec.retry === 'safe' || (spec.retry === 'exec' && unsentAttempt) || (spec.retry === 'staged' && !cut);
             if (!resend || attempt >= config.maxRetries)
                 throw raised(failure, said, acted, effect, cut ? outcome.status : null);
             acted = acted || said !== 'never';

package/dist/cjs/index.d.ts

@@ -4,9 +4,9 @@ export { CommandHandle, DEFAULT_EXEC_TIMEOUT_MS, MAX_BLOCKING_EXEC_MS } from './
 export type { CommandStatus, ExecOptions, WaitOptions } from './commands.js';
 export { Files } from './files.js';
 export type { FileData, WriteOptions } from './files.js';
-export { CommandTimeoutError, PrizedError } from './errors.js';
-export type { PrizedErrorInit } from './errors.js';
+export { CommandTimeoutError, OutputReadError, PrizedError } from './errors.js';
+export type { OutputReadErrorInit, PrizedErrorInit } from './errors.js';
 export { DEFAULT_BASE_URL, DEFAULT_EDGE_URL } from './http.js';
 export type { ClientOptions } from './http.js';
-export type { ExecResult, FileInfo, Resources, ResourcesInput, SandboxInfo, SandboxState, Template, WriteInfo, } from './types.js';
+export type { ExecResult, FileInfo, Resources, ResourcesInput, SandboxInfo, SandboxState, Template, TruncatedReason, WriteInfo, } from './types.js';
 export { VERSION } from './version.js';

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.DEFAULT_EDGE_URL = exports.DEFAULT_BASE_URL = exports.PrizedError = exports.CommandTimeoutError = exports.Files = exports.MAX_BLOCKING_EXEC_MS = exports.DEFAULT_EXEC_TIMEOUT_MS = exports.CommandHandle = exports.PREVIEW_KEY_HEADER = exports.DEFAULT_TEMPLATE = exports.Sandbox = void 0;
+exports.VERSION = exports.DEFAULT_EDGE_URL = exports.DEFAULT_BASE_URL = exports.PrizedError = exports.OutputReadError = exports.CommandTimeoutError = exports.Files = exports.MAX_BLOCKING_EXEC_MS = exports.DEFAULT_EXEC_TIMEOUT_MS = exports.CommandHandle = exports.PREVIEW_KEY_HEADER = exports.DEFAULT_TEMPLATE = exports.Sandbox = void 0;
 // Prized Sandboxes (beta) from TypeScript: the public surface.
 var sandbox_js_1 = require("./sandbox.js");
 Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return sandbox_js_1.Sandbox; } });
@@ -14,6 +14,7 @@ var files_js_1 = require("./files.js");
 Object.defineProperty(exports, "Files", { enumerable: true, get: function () { return files_js_1.Files; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "CommandTimeoutError", { enumerable: true, get: function () { return errors_js_1.CommandTimeoutError; } });
+Object.defineProperty(exports, "OutputReadError", { enumerable: true, get: function () { return errors_js_1.OutputReadError; } });
 Object.defineProperty(exports, "PrizedError", { enumerable: true, get: function () { return errors_js_1.PrizedError; } });
 var http_js_1 = require("./http.js");
 Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return http_js_1.DEFAULT_BASE_URL; } });

package/dist/cjs/outcome.d.ts

@@ -30,11 +30,12 @@ export declare function helperEffect(): Effect;
 export type Outcome = 'never' | 'maybe' | 'did' | null;
 /** Whether withOutcome said the sandbox may have acted on the request. */
 export declare function mayHaveActed(error: unknown): error is PrizedError;
-/** `error` with another message (and, given, another status, code, sandbox or cause), every other field kept. */
+/** `error` with another message (and, given, another status, code, sandbox, exit code or cause), every other field kept. */
 export declare function restate(error: PrizedError, message: string, init?: {
     status?: number;
     code?: string;
     sandboxId?: string;
+    exitCode?: number;
     cause?: unknown;
 }): PrizedError;
 /** `error` (same code, status and body), its message saying what it means for `effect`. */

package/dist/cjs/outcome.js

@@ -14,9 +14,11 @@ exports.startAbandoned = startAbandoned;
 exports.runAborted = runAborted;
 exports.pollFailed = pollFailed;
 // What an error says about a command that may have run. A command, a file
-// write, a remove or a signal (`exec` retry mode) is never sent again once it
-// may have reached the sandbox, so its error has to say what the caller cannot
-// see: whether it happened. The Python SDK words these the same (_core.py).
+// write's rename, a remove or a signal (`exec` retry mode) is never sent again
+// once it may have reached the sandbox, so its error has to say what the
+// caller cannot see: whether it happened. A write's staged upload (`staged`)
+// may have been sent again, and its error says whether a copy may have
+// reached the sandbox. The Python SDK words these the same (_core.py).
 const errors_js_1 = require("./errors.js");
 const NOT_SENT_AGAIN = 'It was not sent again';
 function commandEffect() {
@@ -65,7 +67,7 @@ const acted = new WeakSet();
 function mayHaveActed(error) {
     return error instanceof errors_js_1.PrizedError && acted.has(error);
 }
-/** `error` with another message (and, given, another status, code, sandbox or cause), every other field kept. */
+/** `error` with another message (and, given, another status, code, sandbox, exit code or cause), every other field kept. */
 function restate(error, message, init = {}) {
     return new errors_js_1.PrizedError(init.code ?? error.code, message, {
         status: init.status ?? error.status,
@@ -73,6 +75,7 @@ function restate(error, message, init = {}) {
         sandboxId: error.sandboxId ?? init.sandboxId ?? null,
         body: error.body,
         retryAfter: error.retryAfter,
+        exitCode: init.exitCode ?? error.exitCode,
         cause: 'cause' in init ? init.cause : error.cause,
     });
 }

package/dist/cjs/output.d.ts

@@ -1,5 +1,5 @@
 import { type Toolbox } from './toolbox.js';
-import type { ExecResult } from './types.js';
+import type { ExecResult, TruncatedReason } from './types.js';
 export declare const OUTPUT_DIR = "/home/prized/.prized/exec";
 export declare const OUTPUT_ID_RE: RegExp;
 /** Each stream of a fullOutput command keeps at most this many bytes: one download. */
@@ -22,17 +22,22 @@ export declare const RUN_SCRIPT = "eval \"${PRIZED_EXEC_SCRIPT:?}\"";
  * Nothing is assigned before it runs but the positional parameters, so every
  * variable the caller's env sets reaches it unchanged, PATH included; and
  * every step holds under an errexit the env may switch on (SHELLOPTS). As in
- * a plain exec, the readers stop 5 s after the command ends if a process it
+ * a plain exec, the relays stop 5 s after the command ends if a process it
  * left running still holds its output, keeping what came through. A command
- * a signal ends exits 128+n, as a background command does. Without tee,
- * setsid or a directory to write to, the command runs as a plain exec.
+ * a signal ends exits 128+n, as a background command does. A reader that
+ * could not write its file (failedLines) sends the output to the files API
+ * whatever its size, with the marker saying which. Without /bin/sh, setsid,
+ * cat or a directory to write to, the command runs as a plain exec.
  */
 export declare function captureScript(id: string): string;
 /**
  * What a fullOutput command left when the script could not print it (its
  * time limit, or a signal, ended the script): the marker line, or `gone`,
  * with the directory removed, when there is nothing to read (it was never
- * made, or its output was already printed back).
+ * made, or its output was already printed back). A failed write is read from
+ * the reader's flag, before the size, which is final once the flag is there
+ * (the script's wait for the reader's exit status went with the script); a
+ * reader killed, or one that could not make its flag, is not seen here.
  */
 export declare function collectScript(id: string): string;
 /**
@@ -41,11 +46,17 @@ export declare function collectScript(id: string): string;
  * answer to remove its own.
  */
 export declare function removeOutputScript(id: string): string;
-/** The marker's byte counts (a stream cut at FULL_OUTPUT_BYTES reads more), `gone`, or null for no marker. */
-export declare function parseMarker(stdout: string, id: string): {
+/** What the marker line says: each stream's byte count (one cut at FULL_OUTPUT_BYTES reads more), and whether its reader failed to write it. */
+export interface Marker {
     out: number;
     err: number;
-} | 'gone' | null;
+    outFailed: boolean;
+    errFailed: boolean;
+}
+/** The marker (one without failure flags, as an earlier SDK's collect printed, has none), `gone`, or null for no marker. */
+export declare function parseMarker(stdout: string, id: string): Marker | 'gone' | null;
+/** Why the read-back output is cut, if it is: a failed write first, since it is the one the caller cannot foresee. */
+export declare function markerTruncation(marker: Marker): TruncatedReason | null;
 /**
  * A blocking exec that keeps the whole output (up to FULL_OUTPUT_BYTES of
  * each stream). The result is a plain exec's, timeouts included: the caller