@pipelex/sdk 0.38.0 → 0.40.0

package/dist/client.js

@@ -2,12 +2,13 @@
 // source combinations are legal is an invariant of `RunRequest` itself, so this
 // client and the MTHDS runners cannot disagree about what they reject.
 import { assertExclusiveRunSources, hasBundlePayload, parseMethodFiles, serializeMethodFiles, } from "mthds/protocol";
-import { assertArtifactSelection, assertWaitOptions, pollUntilResult, selectionIncludesMainStuff, throwIfAborted, } from "./runs.js";
+import { assertArtifactSelection, assertWaitOptions, pollUntilResult, readRunDegradation, selectionIncludesMainStuff, throwIfAborted, } from "./runs.js";
 import { ApiResponseError, ApiUnreachableError, EmptyMethodSourceError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, PipelineRequestError, RequestArgumentError, RunLifecycleUnavailableError, RunStillRunningError, } from "./errors.js";
 import { isPlainObject, isValidationItem, readFieldError, readMigration, readProviderMetadata, readRunErrorReport, } from "./error-models.js";
 import { methodSourceToContents } from "./method-source.js";
 import { buildUserAgent } from "./user-agent.js";
 import { uploadFile as uploadFileImpl } from "./upload.js";
+import { encodeBundleResources, hasBundleResources } from "./bundle-resources.js";
 import { prepareInputs as prepareInputsImpl } from "./prepare-inputs.js";
 import { downloadArtifacts as downloadArtifactsImpl, fetchArtifact as fetchArtifactImpl, resolveArtifacts as resolveArtifactsImpl, } from "./artifacts.js";
 import { PipelexExecuteResult, resultsFromExecute } from "./execute-result.js";
@@ -29,6 +30,7 @@ const MAX_PAGES = 10_000;
 /** Decoders of an answer's bytes: the strict one tells a body that is not UTF-8. */
 const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true });
 const LENIENT_UTF8 = new TextDecoder("utf-8");
+const STARTS_RUN = Object.freeze({ mayStartRun: true });
 /** Hosted default — the client composes every endpoint as `{base}/v1/{endpoint}`. */
 export const DEFAULT_API_BASE_URL = "https://api.pipelex.com";
 // The client composes every endpoint from one origin (PIPELEX_BASE_URL): `{base}/v1/{endpoint}`.
@@ -155,7 +157,8 @@ export class PipelexApiClient {
      * DNS/connect/TLS/timeout failures as `ApiUnreachableError`; a caller-driven
      * abort (Ctrl-C / agent walk-away) propagates as-is so the poll loop can stop
      * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
-     * resolved absolute URL.
+     * resolved absolute URL. `mayStartRun` marks a request that may create a run,
+     * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
      */
     async requestRaw(method, url, options = {}) {
         const hasBody = options.body !== undefined;
@@ -203,7 +206,7 @@ export class PipelexApiClient {
             // is classified from the controller rather than from `err`: a browser errors a
             // body stream cut short by that abort with a generic AbortError instead.
             const code = extractNetworkErrorCode(controller.signal.aborted ? controller.signal.reason : err);
-            throw new ApiUnreachableError(`Could not reach Pipelex API at ${this.baseUrl} (${code ?? "network error"})`, this.baseUrl, code, { cause: err });
+            throw new ApiUnreachableError(`Could not reach Pipelex API at ${this.baseUrl} (${code ?? "network error"})`, this.baseUrl, code, { cause: err, mayStartRun: options.mayStartRun === true });
         }
         finally {
             clearTimeout(timer);
@@ -306,16 +309,16 @@ export class PipelexApiClient {
         }
         return res;
     }
-    throwApiResponseError(method, endpoint, res) {
-        this.throwApiResponseErrorAt(method, `/${API_PREFIX}/${endpoint}`, res);
+    throwApiResponseError(method, endpoint, res, run = {}) {
+        this.throwApiResponseErrorAt(method, `/${API_PREFIX}/${endpoint}`, res, run);
     }
     /** The JSON body of a `/v1` route's 2xx answer; see `readAnswerAt`. */
     readAnswer(method, endpoint, res) {
         return this.readAnswerAt(method, `/${API_PREFIX}/${endpoint}`, res);
     }
     /** The JSON object body of a `/v1` route's 2xx answer; see `readObjectAnswerAt`. */
-    readObjectAnswer(method, endpoint, res) {
-        return this.readObjectAnswerAt(method, `/${API_PREFIX}/${endpoint}`, res);
+    readObjectAnswer(method, endpoint, res, run = {}) {
+        return this.readObjectAnswerAt(method, `/${API_PREFIX}/${endpoint}`, res, run);
     }
     /**
      * The JSON body of a 2xx answer, naming the route by its `path` from the origin as a refusal
@@ -324,14 +327,15 @@ export class PipelexApiClient {
      * failure as `cause`.
      * The one place a success body is parsed.
      */
-    readAnswerAt(method, path, res) {
-        if (!res.utf8)
-            throw this.unreadableAnswer(method, path, res, "a body that is not UTF-8");
+    readAnswerAt(method, path, res, run = {}) {
+        if (!res.utf8) {
+            throw this.unreadableAnswer(method, path, res, "a body that is not UTF-8", undefined, run);
+        }
         try {
             return JSON.parse(res.body);
         }
         catch (err) {
-            throw this.unreadableAnswer(method, path, res, res.body ? "a body that is not JSON" : "an empty body where JSON was expected", err);
+            throw this.unreadableAnswer(method, path, res, res.body ? "a body that is not JSON" : "an empty body where JSON was expected", err, run);
         }
     }
     /**
@@ -339,10 +343,10 @@ export class PipelexApiClient {
      * reads it. A body that is JSON but not an object — `null`, a number, a string, an array — is
      * an answer the SDK cannot read either, and throws the same `ApiResponseError`, with no `cause`.
      */
-    readObjectAnswerAt(method, path, res) {
-        const answer = this.readAnswerAt(method, path, res);
+    readObjectAnswerAt(method, path, res, run = {}) {
+        const answer = this.readAnswerAt(method, path, res, run);
         if (!isPlainObject(answer)) {
-            throw this.unreadableAnswer(method, path, res, "a body that is not an object");
+            throw this.unreadableAnswer(method, path, res, "a body that is not an object", undefined, run);
         }
         return answer;
     }
@@ -351,20 +355,29 @@ export class PipelexApiClient {
      * `API <method> <path> answered <status> with <what>`: the answer's status, its raw text as
      * `responseBody`, no problem member but the `X-Request-ID` header, the failure that made it
      * unreadable as `cause`, and the verdict the fallback gives a 2xx, `runtime` and not retryable.
+     * On a request that may create a run, the run may have started: the server accepted it.
      */
-    unreadableAnswer(method, path, res, what, cause) {
-        return new ApiResponseError(`API ${method} ${path} answered ${res.status} with ${what}`, this.baseUrl, res.status, res.statusText, res.body, undefined, undefined, undefined, undefined, { cause, problem: { requestId: nonEmptyHeader(res.headers, REQUEST_ID_HEADER) } });
+    unreadableAnswer(method, path, res, what, cause, run = {}) {
+        return new ApiResponseError(`API ${method} ${path} answered ${res.status} with ${what}`, this.baseUrl, res.status, res.statusText, res.body, undefined, undefined, undefined, undefined, {
+            cause,
+            problem: { requestId: nonEmptyHeader(res.headers, REQUEST_ID_HEADER) },
+            mayStartRun: run.mayStartRun === true,
+        });
     }
     /**
      * Throw the `ApiResponseError` of a non-2xx answer, naming the route by its `path` from the
      * origin (`/v1/...`, or `/health` for the liveness probe).
      */
-    throwApiResponseErrorAt(method, path, res) {
+    throwApiResponseErrorAt(method, path, res, run = {}) {
         const { errorType, serverMessage, validationErrors, code, problem, document } = parseErrorBody(res.body);
         // The body's `request_id` wins; the header is the fallback for a response whose body
         // carries none (a gateway error page, a non-problem body).
         const requestId = problem.requestId ?? nonEmptyHeader(res.headers, REQUEST_ID_HEADER);
-        throw new ApiResponseError(`API ${method} ${path} failed (${res.status}): ${serverMessage ?? (res.body || res.statusText)}`, this.baseUrl, res.status, res.statusText, res.body, errorType, serverMessage, validationErrors, code, { problem: { ...problem, requestId }, problemDocument: document });
+        throw new ApiResponseError(`API ${method} ${path} failed (${res.status}): ${serverMessage ?? (res.body || res.statusText)}`, this.baseUrl, res.status, res.statusText, res.body, errorType, serverMessage, validationErrors, code, {
+            problem: { ...problem, requestId },
+            problemDocument: document,
+            mayStartRun: run.mayStartRun === true,
+        });
     }
     /**
      * Translate a "route absent" 404 (a bare pipelex-api with no platform block)
@@ -386,23 +399,21 @@ export class PipelexApiClient {
      * error. Hosted does not emit 202 today, but the protocol permits it;
      * raising a typed error (with the `pipeline_run_id` + `Location` + `Retry-After`
      * hints) beats a generic parse failure on an unexpected body shape.
+     *
+     * The 202 must name the run it accepted, as `start`'s acknowledgement must: one whose body is
+     * not JSON, or names no run (an empty id included), leaves the caller a run it cannot follow, so it is an answer the
+     * SDK cannot read, which may have started a run, never a `RunStillRunningError` without an id.
+     * The Python SDK reads the same answers the same way.
      */
     throwIfExecuteDegraded(res) {
         if (res.status !== 202)
             return;
-        let runId = "";
-        try {
-            const parsed = JSON.parse(res.body);
-            if (parsed && typeof parsed === "object") {
-                const candidate = parsed.pipeline_run_id;
-                if (typeof candidate === "string")
-                    runId = candidate;
-            }
-        }
-        catch {
-            // Non-JSON 202 body — keep runId empty; the error message covers it.
+        const ack = this.readObjectAnswer("POST", "execute", res, STARTS_RUN);
+        const runId = ack.pipeline_run_id;
+        if (typeof runId !== "string" || runId === "") {
+            throw this.unreadableAnswer("POST", `/${API_PREFIX}/execute`, res, "a body that is not the answer the route returns", undefined, STARTS_RUN);
         }
-        throw new RunStillRunningError(`execute() was accepted asynchronously (202): run ${runId || "<unknown>"} is still ` +
+        throw new RunStillRunningError(`execute() was accepted asynchronously (202): run ${runId} is still ` +
             "running server-side. Poll its results (hosted) or use start().", runId, parseRetryAfter(res.headers), res.headers.get("location"));
     }
     // ── Health ────────────────────────────────────────────────────────
@@ -454,6 +465,9 @@ export class PipelexApiClient {
         assertRunSourcesExclusive(options);
         assertMethodRefPairsWithNothing(options);
         assertLinkageMethodIdIsBare(options);
+        assertResourcesAccompanyABundle(options);
+        // No await when there are none: a request without them leaves on the tick it always did.
+        const resources = options.resources == null ? undefined : await encodeBundleResources(options.resources);
         const request = {
             pipe_code: options.pipe_code,
             mthds_contents: options.mthds_contents,
@@ -463,6 +477,7 @@ export class PipelexApiClient {
             dynamic_output_concept_ref: options.dynamic_output_concept_ref,
             files: nonEmptyFiles(options.files),
             bundle_b64: nonEmptyString(options.bundle_b64),
+            resources,
             ...api,
             ...hosted,
             ...extensions,
@@ -472,14 +487,19 @@ export class PipelexApiClient {
         try {
             const res = await this.requestRaw("POST", this.url("execute"), {
                 body: request,
+                ...STARTS_RUN,
             });
             this.throwIfExecuteDegraded(res);
             if (res.status < 200 || res.status >= 300) {
-                this.throwApiResponseError("POST", "execute", res);
+                this.throwApiResponseError("POST", "execute", res, STARTS_RUN);
             }
             // Wrap the base result in the enriched subtype (adds the `.main_stuff` accessor; the
             // `main_stuff_name` extension + working memory ride `pipe_output`).
-            return new PipelexExecuteResult(this.readObjectAnswer("POST", "execute", res));
+            const answer = this.readObjectAnswer("POST", "execute", res, STARTS_RUN);
+            if (!isCompletedRunAnswer(answer)) {
+                throw this.unreadableAnswer("POST", `/${API_PREFIX}/execute`, res, "a body that is not the answer the route returns", undefined, STARTS_RUN);
+            }
+            return new PipelexExecuteResult(answer);
         }
         catch (err) {
             if (err instanceof RunStillRunningError)
@@ -522,6 +542,9 @@ export class PipelexApiClient {
         assertRunSourcesExclusive(options);
         assertMethodRefPairsWithNothing(options);
         assertLinkageMethodIdIsBare(options);
+        assertResourcesAccompanyABundle(options);
+        // No await when there are none: a request without them leaves on the tick it always did.
+        const resources = options.resources == null ? undefined : await encodeBundleResources(options.resources);
         // `?? undefined` so JSON.stringify drops absent fields from the wire body.
         const request = {
             pipe_code: options.pipe_code ?? undefined,
@@ -532,6 +555,7 @@ export class PipelexApiClient {
             dynamic_output_concept_ref: options.dynamic_output_concept_ref ?? undefined,
             files: nonEmptyFiles(options.files),
             bundle_b64: nonEmptyString(options.bundle_b64),
+            resources,
             ...api,
             ...hosted,
             ...extensions,
@@ -539,29 +563,38 @@ export class PipelexApiClient {
         const url = this.url("start");
         // `start` returns a 202 fast, so the poll timeout normally fits — with
         // exceptions that get the blocking-execute ceiling instead. A method bundle,
-        // inline as `mthds_contents` or in `files`/`bundle_b64`, can make the
-        // request *body* multi-megabyte, and the whole upload is
-        // charged against this budget — the same payload must not time out on the
-        // durable path yet succeed on the fallback. And a `method_ref` start makes
-        // the server FETCH the package before the ack (provenance rides the 202),
-        // whose clone timeout runs well past 30s on a cold cache — aborting it here
-        // would surface as `ApiUnreachableError`, blaming the network for a healthy
-        // server that is still cloning.
+        // inline as `mthds_contents` or in `files`/`bundle_b64`, or the files its
+        // steps read (`resources`), can make the request *body* multi-megabyte, and
+        // the whole upload is charged against this budget — the same payload must
+        // not time out on the durable path yet succeed on the fallback. And a
+        // `method_ref` start makes the server FETCH the package before the ack
+        // (provenance rides the 202), whose clone timeout runs well past 30s on a
+        // cold cache — aborting it here would surface as `ApiUnreachableError`,
+        // blaming the network for a healthy server that is still cloning.
         const needsLongCeiling = hasBundlePayload(options) ||
             (options.mthds_contents?.length ?? 0) > 0 ||
+            resources !== undefined ||
             nonEmptyString(options.method_ref) !== undefined;
         const res = await this.requestRaw("POST", url, {
             body: request,
             timeoutMs: needsLongCeiling ? DEFAULT_REQUEST_TIMEOUT_MS : POLL_REQUEST_TIMEOUT_MS,
+            ...STARTS_RUN,
         });
         // A bare runner with no run store 404s here just as it does on the result
         // routes — surface the same clear `RunLifecycleUnavailableError` (and let
         // `startAndWaitForResult` fall back to the blocking `execute`).
         this.throwIfLifecycleUnavailable(res, url);
         if (res.status < 200 || res.status >= 300) {
-            this.throwApiResponseError("POST", "start", res);
+            this.throwApiResponseError("POST", "start", res, STARTS_RUN);
+        }
+        const ack = this.readObjectAnswer("POST", "start", res, STARTS_RUN);
+        // The acknowledgement's one job is to name the run: without its id, the run the server
+        // accepted is lost to the caller, as surely as behind a body that is not JSON, and an empty id
+        // names no run either. Worded as the Python SDK words an answer its model refuses.
+        if (typeof ack.pipeline_run_id !== "string" || ack.pipeline_run_id === "") {
+            throw this.unreadableAnswer("POST", `/${API_PREFIX}/start`, res, "a body that is not the answer the route returns", undefined, STARTS_RUN);
         }
-        return this.readObjectAnswer("POST", "start", res);
+        return ack;
     }
     /**
      * Parse, validate, and dry-run an MTHDS bundle — `POST /v1/validate`.
@@ -622,6 +655,15 @@ export class PipelexApiClient {
      * the field regardless — which is why `PipelexValidationReport.input_form` is typed
      * optional rather than required.
      *
+     * `options.resources` sends the files the bundle's steps read, such as a
+     * `PipeDocGen` step's `template_file`, keyed by the path the step names, each as
+     * its bytes (see {@link ValidateOptions}). A step whose template file was not sent
+     * is an `is_valid: false` verdict saying so, and a template check's findings in an
+     * office template file ride the valid arm's `warnings`. A key no step names, or
+     * files over the server's limits, are no-verdict refusals: a `422`
+     * `BundleResourceNotNamedError`, a `413` `PayloadTooLarge` or
+     * `BundleResourcesTooLargeError`.
+     *
      * A `{ method_ref }` source makes the server clone a repository before it
      * validates anything, and it needs no special budget here: this route already
      * defaults to the 20-minute execute ceiling, which clears the internal
@@ -659,6 +701,9 @@ export class PipelexApiClient {
                 throw new RequestArgumentError("mthds_sources labels inline mthds_contents; a method_ref / method_id validation gets " +
                     "its source labels from the package's (or the stored method's) real file names.");
             }
+            if (methodRef !== undefined && hasBundleResources(options.resources)) {
+                throw new RequestArgumentError("resources accompany inline mthds_contents; a method_ref's files are the package's own.");
+            }
             if (methodRef !== undefined)
                 body.method_ref = methodRef;
             if (methodId !== undefined)
@@ -668,6 +713,11 @@ export class PipelexApiClient {
         if (views !== undefined) {
             body.views = views;
         }
+        // No await when there are none: a request without them leaves on the tick it always did.
+        const resources = options.resources == null ? undefined : await encodeBundleResources(options.resources);
+        if (resources !== undefined) {
+            body.resources = resources;
+        }
         const res = await this.requestRaw("POST", this.url("validate"), {
             body,
             timeoutMs: options.timeoutMs,
@@ -696,6 +746,7 @@ export class PipelexApiClient {
             ? files.map((file, index) => file.uri ?? `inline://file-${index + 1}.mthds`)
             : undefined;
         return this.validate(mthdsContents, options.allowSignatures ?? false, mthdsSources, options.render, options.views, {
+            resources: options.resources,
             timeoutMs: options.timeoutMs,
             signal: options.signal,
         });
@@ -770,10 +821,11 @@ export class PipelexApiClient {
      * never on a message.
      *
      * All of these are static and inference-free, so they default to the management-call
-     * timeout. The one internal raise is the fetch-sized budget `crateRequestTimeoutMs`
-     * gives a crate route whose closure is a `method_ref`, because the server may clone a
-     * repository before it answers; it is matched to what the server does, not a
-     * caller-facing parameter.
+     * timeout. The internal raises are `crateRequestTimeoutMs`'s: the fetch-sized budget a
+     * crate route gets when its closure is a `method_ref`, because the server may clone a
+     * repository before it answers, and the execute ceiling it gets when the request
+     * carries `resources`, whose upload alone can outlast the default. Each is matched to
+     * what the request costs, not a caller-facing parameter.
      *
      * **These routes deliberately expose no `timeoutMs` / `signal`, and that is not an
      * oversight to be "fixed" per route.** Automated reviewers have proposed adding them
@@ -784,8 +836,11 @@ export class PipelexApiClient {
      *    ceiling and takes caller transport options; every extension route rides the
      *    static core. Giving one static route an override while its siblings lack one is
      *    the inconsistency.
-     * 2. The input is **bounded server-side** — the runner's `pipelex_api/limits.py` caps a request
-     *    at 16 `.mthds` files of 1 MiB each — and none of these routes runs inference.
+     * 2. The input is **bounded server-side** — the runner's `pipelex_api/limits.py` caps the
+     *    `.mthds` files of a request and the files sent with them in `resources`, each by a
+     *    count, a size per file and, for `resources`, a total, all configurable per
+     *    deployment — and none of these routes runs inference. The upload those limits allow
+     *    is what `crateRequestTimeoutMs` budgets for, not the server's work.
      * 3. On the hosted path an override would be **inert**: the gateway caps responses at
      *    ~30s (see `POLL_REQUEST_TIMEOUT_MS` above), so raising `timeoutMs` would still be
      *    cut off upstream, just with a less honest error.
@@ -907,7 +962,7 @@ export class PipelexApiClient {
      * see {@link PipelexHostedToolingExtensions}).
      */
     async resolve(request) {
-        return this.requestExtension("resolve", request, {
+        return this.requestExtension("resolve", await wireCrateRequest(request), {
             timeoutMs: crateRequestTimeoutMs(request),
         });
     }
@@ -927,7 +982,7 @@ export class PipelexApiClient {
      * a malformed selector is a 422; a registry-form `method_ref` is a `501`.
      */
     async codegen(request) {
-        return this.requestExtension("codegen", request, {
+        return this.requestExtension("codegen", await wireCrateRequest(request), {
             timeoutMs: crateRequestTimeoutMs(request),
         });
     }
@@ -947,8 +1002,14 @@ export class PipelexApiClient {
      * describes every pipe instead, and never refuses for want of an entry pipe.
      * `include_files: true` echoes the resolved closure's `.mthds` files as `files`.
      *
+     * Beside inline `files`, `resources` sends the files the closure's steps read, such as a
+     * `PipeDocGen` step's `template_file`, keyed by the path the step names, each as its bytes;
+     * a step whose template file was not sent makes the closure invalid. `resolve` and `codegen`
+     * take it too (see {@link CrateRequestBase}).
+     *
      * Same 200-verdict discipline and same three-form closure selector as {@link resolve}
-     * (the request is posted verbatim, and the selector XOR is the server's to enforce).
+     * (the request is posted as given, its `resources` encoded to base64, and the selector XOR
+     * and the `resources` pairing are the server's to enforce).
      * Only a no-verdict condition throws `ApiResponseError`: a malformed selector and an
      * over-limit file are `ValidationError` `422`s; a selection the route refuses is a
      * `422` whose `errorType` is `EntryPipeNotFoundError` (an unknown `pipe_ref`, no entry
@@ -956,13 +1017,14 @@ export class PipelexApiClient {
      * candidates in its `serverMessage`; a registry-form `method_ref` is a `501`; a pipe
      * whose artifacts cannot be derived is a `500`.
      *
-     * A `method_ref` gets the fetch-sized budget, as on the other crate routes. On the
-     * hosted API the gateway caps a request at about 30 seconds whatever the client
-     * allows, so a cold `method_ref` clone can answer a `502` that a retry clears once the
-     * runner has cached the clone.
+     * A `method_ref` gets the fetch-sized budget, as on the other crate routes, and a
+     * request carrying `resources` the execute ceiling, since their upload alone can
+     * outlast the default. On the hosted API the gateway caps a request at about 30
+     * seconds whatever the client allows, so a cold `method_ref` clone can answer a `502`
+     * that a retry clears once the runner has cached the clone.
      */
     async pipeIo(request) {
-        return this.requestExtension("pipe-io", request, {
+        return this.requestExtension("pipe-io", await wireCrateRequest(request), {
             timeoutMs: crateRequestTimeoutMs(request),
         });
     }
@@ -971,12 +1033,17 @@ export class PipelexApiClient {
      * Fetch a run's status by bare id — `GET /v1/runs/{pipeline_run_id}/status`.
      *
      * Self-healing: a finished-but-unrecorded run resolves to its true terminal
-     * status on read. `degraded: true` means Temporal was unreachable and
-     * `status` is the last-known value; `retry_after_seconds` carries the
-     * server's backoff hint when present. A failed run's stored report, `error`,
-     * is checked field by field (see `RunErrorReport`). Throws
-     * `RunLifecycleUnavailableError` when the lifecycle routes are absent (a bare
-     * runner).
+     * status on read. `degraded: true` means the read is not a plain fresh reading,
+     * and `degradation.reason` says why (see `DegradationReason`):
+     * `status_unavailable` when the platform could not reach the workflow engine
+     * and `status` is the last one recorded, `workflow_task_failing` when `status`
+     * is live and the run is stuck, its workflow task failing until the platform
+     * ends it at `degradation.ends_at`. `retry_after_seconds` carries the server's
+     * `Retry-After` hint when present, and `request_id` the id to quote to support.
+     * A failed run's stored report, `error`, and the `degradation` are each
+     * checked field by field (see `RunErrorReport` and `RunDegradation`), so
+     * neither ever fails the read. Throws `RunLifecycleUnavailableError` when the
+     * lifecycle routes are absent (a bare runner).
      */
     async getRunStatus(runId, options = {}) {
         const endpoint = `${RUNS}/${encodeURIComponent(runId)}/status`;
@@ -989,7 +1056,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("GET", endpoint, res);
         }
-        const run = withCheckedReport(this.readObjectAnswer("GET", endpoint, res));
+        const run = withCheckedDegradation(withCheckedReport(this.readObjectAnswer("GET", endpoint, res)));
         const retryAfter = parseRetryAfter(res.headers);
         return retryAfter !== null ? { ...run, retry_after_seconds: retryAfter } : run;
     }
@@ -1104,6 +1171,13 @@ export class PipelexApiClient {
      * `pollOptions.signal` is also read before the run is created: a caller that aborts while the
      * version handshake is in flight gets its abort, and neither the start nor the blocking execute
      * is sent. Once one of them is sent, the abort stops only the wait.
+     *
+     * An error from the start, or from the blocking execute, says whether that request may still
+     * have started a run whose id never reached the caller (`runMayHaveStarted`); when it may have,
+     * it is not retryable, since calling this method again could pay for the run twice: look the run
+     * up in the run history first. An error from the wait, once `onStarted` has named the run,
+     * started nothing, so its `runMayHaveStarted` is false, and its `retryable` is about waiting
+     * again on that id with `waitForResult`, never about calling this method again.
      */
     async startAndWaitForResult(options, pollOptions) {
         // Before the run starts: a refusal after it would carry no run id to re-poll by.
@@ -1622,7 +1696,8 @@ export class PipelexApiClient {
      * Name the method exactly one of three ways, all server-resolved through the
      * one `pipeIo` call this composes:
      *
-     * - `files` — the inline MTHDS closure;
+     * - `files` — the inline MTHDS closure, with the `resources` its steps read
+     *   (a `PipeDocGen` step's `template_file`), keyed by the path a step names;
      * - `method_ref` — a published method's address, fetched by the runner;
      * - `method_id` — a stored method's catalog id, resolved by the platform
      *   (hosted only; requires an API key).
@@ -1632,6 +1707,12 @@ export class PipelexApiClient {
      * answers with, which states the kind of every input at every depth, so a file
      * position is a fact of the method, never a guess from the value's shape. It
      * needs an API serving `POST /v1/pipe-io`. See `docs/input-preparation.md`.
+     *
+     * A value at a file input that cannot be a file, such as a number or a
+     * `data:` URL that does not decode, throws `InvalidInputValueError`, naming the
+     * input. With `allowUploads: false` it uploads nothing and reads no file: a
+     * value that would need an upload throws `UploadNotAllowedError`, naming the
+     * input too.
      */
     async prepareInputs(request) {
         return prepareInputsImpl(this, request);
@@ -1770,6 +1851,8 @@ export class PipelexApiClient {
             // this path runs the same method as the durable one, or it runs nothing.
             files: options.files ?? undefined,
             bundle_b64: options.bundle_b64 ?? undefined,
+            // And so must the files its steps read, or the same method fails to load here.
+            resources: options.resources ?? undefined,
             method_ref: options.method_ref ?? undefined,
             method_id: options.method_id ?? undefined,
             extra: options.extra ?? undefined,
@@ -1850,12 +1933,13 @@ const PROTOCOL_REQUEST_KEYS = [
     "files",
     "bundle_b64",
 ];
-// The PIPELEX API's own request fields — the layer-2 extension the runner
-// resolves itself (`method_ref`, a run source in its own right). Reserved on
-// `extra` for the same reason the protocol fields are: `extra` merges last, so
-// a smuggled copy would overwrite the validated named option and bypass the
-// selector-exclusivity checks.
-const PIPELEX_API_REQUEST_KEYS = ["method_ref"];
+// The PIPELEX API's own request fields — the layer-2 extensions the runner
+// reads itself (`method_ref`, a run source in its own right, and `resources`,
+// the files the bundle's steps read). Reserved on `extra` for the same reason
+// the protocol fields are: `extra` merges last, so a smuggled copy would
+// overwrite the validated named option and bypass the selector-exclusivity and
+// path checks.
+const PIPELEX_API_REQUEST_KEYS = ["method_ref", "resources"];
 // The HOSTED API's own request fields — the layer-3 extensions this client
 // names itself. Reserved on `extra` for the same reason the protocol fields
 // are: `extra` merges last, so a smuggled copy would overwrite the validated
@@ -1918,10 +2002,20 @@ function buildExtensions(extra) {
 const METHOD_REF_FETCH_TIMEOUT_MS = 180_000; // 3 min — covers the server's clone + resolve
 /**
  * The internal request budget for a crate route's `CrateRequestBase` closure
- * (`resolve`, `codegen`, `pipeIo`): the static-route default, unless the closure
- * is a `method_ref` the server may have to fetch first.
+ * (`resolve`, `codegen`, `pipeIo`): the static-route default, unless the request
+ * is one the default would cut short through no fault of the server's.
+ *
+ * - **`resources`** make the request *body* as large as the runner's limits allow,
+ *   about 13 MiB of base64 by default, and the whole upload is charged against
+ *   this budget. They get the execute ceiling `start` gives a request carrying
+ *   them, and `validate` carries them under by default, so the same bundle and
+ *   files never time out on one route yet go through on another.
+ * - **A `method_ref`** may make the server clone a repository first, which gets
+ *   the fetch-sized budget.
  */
 function crateRequestTimeoutMs(request) {
+    if (hasBundleResources(request.resources))
+        return DEFAULT_REQUEST_TIMEOUT_MS;
     return nonEmptyString(request.method_ref) !== undefined ? METHOD_REF_FETCH_TIMEOUT_MS : undefined;
 }
 /**
@@ -2027,6 +2121,43 @@ function assertLinkageMethodIdIsBare(options) {
         "that did not. Send the bare id (parseMethodSelector(...).method_id), or drop the inline " +
         "source to run the version the selector names.");
 }
+/**
+ * Enforce the run routes' `resources` pairing, mirroring the runner's own `422`s
+ * so an illegal pairing fails before anything is encoded or sent. The files a
+ * bundle's steps read accompany that bundle: inline `mthds_contents` or a method
+ * bundle. Beside a `method_ref` they are refused, a published package's files
+ * being its own, and so they are with no source at all, where no step could read
+ * them. A hosted `method_id` without an inline source is left to the server: the
+ * platform resolves it into the bundle the runner then reads them with.
+ *
+ * Presence follows the other pairing checks: `resources` counts when it carries a
+ * file, `mthds_contents` when non-empty, a bundle when `hasBundlePayload` says so.
+ */
+function assertResourcesAccompanyABundle(options) {
+    if (!hasBundleResources(options.resources))
+        return;
+    if (nonEmptyString(options.method_ref) !== undefined) {
+        throw new RequestArgumentError("resources accompany inline mthds_contents or a method bundle; a method_ref's files are the package's own.");
+    }
+    const hasInlineSource = (options.mthds_contents != null && options.mthds_contents.length > 0) ||
+        hasBundlePayload(options);
+    if (!hasInlineSource && nonEmptyString(options.method_id) === undefined) {
+        throw new RequestArgumentError("resources accompany the bundle whose steps read them: send them with mthds_contents or a method bundle.");
+    }
+}
+/**
+ * A crate request as the wire takes it: the request as given, its `resources`
+ * encoded into the base64 map, the key left off when there is nothing to send.
+ * A request that carries no `resources` key is posted untouched.
+ */
+async function wireCrateRequest(request) {
+    if (typeof request !== "object" || request === null || !("resources" in request)) {
+        return request;
+    }
+    const { resources, ...rest } = request;
+    const encoded = await encodeBundleResources(resources);
+    return encoded === undefined ? rest : { ...rest, resources: encoded };
+}
 /**
  * Normalize a bundle encoding for the wire: an empty map / string is NOT a
  * runnable bundle, so it must not be sent (the runner rejects a zero-file
@@ -2063,9 +2194,10 @@ const GATEWAY_TIMEOUT_THRESHOLD_MS = 28_000;
  * `is_gateway_cut_off` reads the same failures, its `ABORT_TIMEOUT` being httpx's read or write
  * timeout.
  *
- * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. A caller timing
- * a request that may create a run, such as `start` from `startAndWaitForResult`'s `onStarting`,
- * reads it to know the server may still be handling the request the gateway gave up on.
+ * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. Whether a
+ * failed `start` or `execute` may have started a run needs no timing: the error says it as
+ * `runMayHaveStarted`, which reads every `503` but the platform's coded one as a run that may
+ * have started, however quickly it came back.
  */
 export function isGatewayCutOff(error, elapsedMs) {
     if (elapsedMs < GATEWAY_TIMEOUT_THRESHOLD_MS)
@@ -2125,6 +2257,25 @@ function isMissingRoute404(body) {
         return true;
     return !("code" in parsed);
 }
+/**
+ * Whether a 2xx answer to `execute` is the completed run the route returns, as far as the SDK reads
+ * it: a string `pipeline_run_id`, and a `pipe_output` object whose `working_memory` carries its
+ * `root` and `aliases` objects and whose own `pipeline_run_id` is a string, the envelope the Python
+ * SDK's model of the answer requires. Anything less is an answer the SDK cannot read, rather than
+ * a result that fails with a bare `TypeError` once its output is lifted. The stuffs inside `root`,
+ * which the Python model also checks, are left to the read of the main stuff, whose
+ * `MissingMainStuffError` names the run.
+ */
+function isCompletedRunAnswer(answer) {
+    const { pipeline_run_id: runId, pipe_output: pipeOutput } = answer;
+    if (typeof runId !== "string" || !isPlainObject(pipeOutput))
+        return false;
+    const workingMemory = pipeOutput["working_memory"];
+    return (typeof pipeOutput["pipeline_run_id"] === "string" &&
+        isPlainObject(workingMemory) &&
+        isPlainObject(workingMemory["root"]) &&
+        isPlainObject(workingMemory["aliases"]));
+}
 /** Parse the `Retry-After` header (seconds form, which the platform uses). */
 function parseRetryAfter(headers) {
     const raw = headers.get("retry-after");
@@ -2181,6 +2332,15 @@ function withCheckedReport(record) {
         return record;
     return { ...record, error: readRunErrorReport(record.error) };
 }
+/**
+ * A status read with its `degradation` checked by `readRunDegradation`. Only when the read carries
+ * the key, so a platform that predates it still leaves it absent; `degraded` is left as sent.
+ */
+function withCheckedDegradation(run) {
+    if (!Object.hasOwn(run, "degradation"))
+        return run;
+    return { ...run, degradation: readRunDegradation(run.degradation) };
+}
 function knownRunStatus(value) {
     return typeof value === "string" && KNOWN_RUN_STATUSES.includes(value)
         ? value