@pipelex/sdk 0.37.0 → 0.39.0

package/README.md

@@ -134,7 +134,7 @@ try {
 
 ### Errors
 
-Every error the SDK throws carries a verdict: `retryable`, whether asking again can succeed, and `errorDomain`, who can fix the failure (`input` for the caller, `config` for a change to the environment such as the credential, the plan or the base URL, `runtime` for nobody beforehand). Both are always decided, and `errorVerdictOf` reads them from anything a `catch` holds, returning `undefined` for what is not an SDK error, such as a bug in the calling code or your own abort. "Retryable" means a retry can succeed, not that it is safe: a start answered with a `500` may already have created a run.
+Every error the SDK throws carries a verdict: `retryable`, whether asking again can succeed, and `errorDomain`, who can fix the failure (`input` for the caller, `config` for a change to the environment such as the credential, the plan or the base URL, `runtime` for nobody beforehand). Both are always decided, and `errorVerdictOf` reads them from anything a `catch` holds, returning `undefined` for what is not an SDK error, such as a bug in the calling code or your own abort. A failed `start` or blocking `execute` also says whether it may have created a run anyway, as `runMayHaveStarted`, read with `runMayHaveStartedOf`: when it is `true`, `retryable` is `false`, since asking again could start a second paid run, and the person should look the run up in the run history first ([`docs/errors.md`](./docs/errors.md#a-failed-run-start--runmayhavestarted)).
 
 ```ts
 import { errorVerdictOf } from "@pipelex/sdk";
@@ -152,7 +152,7 @@ try {
 
 A refused request throws an `ApiResponseError` carrying every member of the server's RFC 9457 problem document. **Branch on `errorDomain` and `type`**, as the hosted-envelope spec says, never on the HTTP status or the message: `errorDomain` is the verdict's domain and `type` is the stable URI of the error class, the same on every occurrence. The verdict is the server's when it sent a valid one, and otherwise the SDK's fallback, read from the status, except that an `input` or `config` domain the server sent without `retryable` is not retryable; `problemDocument` keeps what the server sent. `userAction` gives the next step, and `requestId` — from the body, or the `X-Request-ID` header — is the id to hand to support. `code` (the platform's native code, one-to-one with `type`) and `errorType` (the runner's exception class name) are each surface's finer code, and a client of that surface may branch on it too: on the platform's own refusals `code` and `type` read the same answer, `MethodErrorCode` naming the codes a method caller branches on, while a refusal the platform relays from the runner carries the runner's `type` and `errorType` and no `code`. `errors` carries the platform's field-level failures.
 
-On the hosted API, a run that ends without completing throws a `RunFailedError` from `waitForResult`, `startAndWaitForResult` and `downloadArtifacts`, and comes back as the `failed` arm of `getRunResult`. (Against a bare `pipelex-api` runner, `startAndWaitForResult` runs the method with the blocking `execute`, so a failed run there throws the runner's `ApiResponseError`, whose problem members carry the same classification.) Its `status` is the run's terminal status and its `error` is the run's stored error report, checked field by field and typed as `RunErrorReport`: the reason in `message`, `error_domain`, `type_uri` and `retryable` to branch on, `user_action` as the next step, and the inference details. It is `null` when the run ended without a report, and the error's own verdict comes from it: the report's domain, and retryable only when the report says so. The report is the runner's VERBOSE one, provider text included, so what a person sees is your presentation:
+On the hosted API, a run that ends without completing throws a `RunFailedError` from `waitForResult`, `startAndWaitForResult` and `downloadArtifacts`, and comes back as the `failed` arm of `getRunResult`. (Against a bare `pipelex-api` runner, `startAndWaitForResult` runs the method with the blocking `execute`, so a failed run there throws the runner's `ApiResponseError`, whose problem members carry the same classification.) Its `status` is the run's terminal status and its `error` is the run's stored error report, checked field by field and typed as `RunErrorReport`: the reason in `message`, `error_domain`, `type_uri` and `retryable` to branch on, `user_action` as the next step, and the provider's answer in `provider_metadata`'s `status_code` and `retry_after_seconds`. It is `null` when the run ended without a report, and the error's own verdict comes from it: the report's domain, and retryable only when the report says so. The platform serves the runner's STRICT projection of the report: `message` is the author's copy when `caller_facing_message` is `true` and `An internal error occurred.` otherwise, `user_action` comes only with caller-facing copy, and the model, the provider and the provider's own text are left out, so `message` can be shown as it comes and what a person sees is still your presentation:
 
 ```ts
 import { RunFailedError } from "@pipelex/sdk";
@@ -216,8 +216,8 @@ These pages ship inside the published package, so a reader who has only installe
 ## Develop
 
 ```bash
-make install    # Install dependencies
-make check      # Lint + format check + typecheck + build + depcruise (alias: make c)
+make install    # Install the dependencies from the lockfile (npm ci, which never rewrites it)
+make check      # Lockfile check + lint + format check + typecheck + build + depcruise (alias: make c)
 make test       # Run the test suite (alias: make t)
 make all        # Clean, check, and test
 ```

package/dist/cli/run.js

@@ -8,7 +8,7 @@
  * as soon as the run exists; and the main output reaches stdout once the run completes, however
  * long that takes.
  */
-import { ApiResponseError, ApiUnreachableError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, isGatewayCutOff, renderInputsTemplate, } from "../index.js";
+import { MissingMainStuffError, RunFailedError, renderInputsTemplate, runMayHaveStartedOf, } from "../index.js";
 import { parseFlags } from "./args.js";
 import { readBundle } from "./bundle.js";
 import { makeClient, readPollInterval } from "./environment.js";
@@ -75,7 +75,7 @@ export async function runCommandRun(args, io) {
                 onStarting: () => {
                     // Only once a request that may create a run is about to leave: an interrupt before
                     // it, during the version handshake included, starts nothing, and the command says so.
-                    stage = { kind: "starting", since: performance.now() };
+                    stage = { kind: "starting" };
                 },
                 onStarted: (ack) => {
                     if (io.interrupt.aborted)
@@ -122,120 +122,17 @@ function waitedOnRun(stage, error) {
         return undefined;
     return stage.runId;
 }
-/**
- * Whether a transport failure proves the request never left, so that no run was created by it: it
- * names a step of the connection's set-up, which no request follows. That is the name lookup or
- * the connection itself failing (the system calls `getaddrinfo` and `connect`: an unknown host, a
- * refused connection, no route to the host or the network, the system's connect time limit),
- * undici's own connect time limit, which covers the TLS handshake, and a server certificate the
- * TLS handshake refused. Several addresses each failing so, which Node reports together as an
- * `AggregateError`, prove it too. A host that drops packets is a connection that never comes:
- * undici gives it up after ten seconds (`UND_ERR_CONNECT_TIMEOUT`), before the time limit of any
- * request the command sends, as the Python command meets httpx's connect timeout first and reads
- * it the same way.
- *
- * Anything else may have come once the request had left, the Python command reading the same
- * failures the same way. A reset (`ECONNRESET`) comes from a `read` whether the connection dropped
- * during the TLS handshake or after the request, and so does an `EHOSTUNREACH` met once connected,
- * so neither proves anything; nor does another TLS failure, which may come after the handshake;
- * nor does the SDK's own time limit (`ABORT_TIMEOUT`), which fetch cannot place before or after
- * the connection was made. Every request the command sends has a limit longer than undici's
- * connect limit, so with Node's own dispatcher it runs out only once the request has left.
- */
-function provesNothingSent(error) {
-    // The SDK keeps fetch's own failure as `cause`, and undici gives the transport's under it.
-    const fetchFailure = error.cause;
-    return fetchFailure instanceof Error && isConnectionSetupFailure(fetchFailure.cause);
-}
-function isConnectionSetupFailure(failure) {
-    if (failure instanceof AggregateError) {
-        return failure.errors.length > 0 && failure.errors.every(isConnectionSetupFailure);
-    }
-    if (typeof failure !== "object" || failure === null)
-        return false;
-    const { code, syscall } = failure;
-    if (typeof code === "string" && CONNECTION_SETUP_CODES.has(code))
-        return true;
-    return typeof syscall === "string" && CONNECTION_SETUP_CALLS.has(syscall);
-}
-/** The system calls that resolve the host's name and open the connection. */
-const CONNECTION_SETUP_CALLS = new Set(["getaddrinfo", "connect"]);
-/**
- * The codes only a step of the connection's set-up gives: the name lookup's and the connect call's
- * own (set even where Node reports several addresses together, without a system call), undici's
- * connect time limit, Node's limit on one attempt among several addresses, Node's own check of the
- * host's name, and every code Node gives a server certificate the TLS handshake refused.
- */
-const CONNECTION_SETUP_CODES = new Set([
-    "ECONNREFUSED",
-    "ENOTFOUND",
-    "EAI_AGAIN",
-    "UND_ERR_CONNECT_TIMEOUT",
-    "ERR_SOCKET_CONNECTION_TIMEOUT",
-    "ERR_TLS_CERT_ALTNAME_INVALID",
-    "ERR_TLS_CERT_ALTNAME_FORMAT",
-    // Node names the verdicts of OpenSSL's certificate check from a fixed table, the "X509 certificate
-    // error codes" of its `tls` docs, and gives every other verdict, such as an unhandled critical
-    // extension or a CA certificate that may not sign certificates, the code `UNSPECIFIED`. The
-    // error carries nothing else that marks it, so these codes are the mark: the table as Node 24
-    // compiles it, in its order, then its default. The Python command reads every
-    // `ssl.SSLCertVerificationError` the same way.
-    "UNABLE_TO_GET_ISSUER_CERT",
-    "UNABLE_TO_GET_CRL",
-    "UNABLE_TO_DECRYPT_CERT_SIGNATURE",
-    "UNABLE_TO_DECRYPT_CRL_SIGNATURE",
-    "UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY",
-    "CERT_SIGNATURE_FAILURE",
-    "CRL_SIGNATURE_FAILURE",
-    "CERT_NOT_YET_VALID",
-    "CERT_HAS_EXPIRED",
-    "CRL_NOT_YET_VALID",
-    "CRL_HAS_EXPIRED",
-    "ERROR_IN_CERT_NOT_BEFORE_FIELD",
-    "ERROR_IN_CERT_NOT_AFTER_FIELD",
-    "ERROR_IN_CRL_LAST_UPDATE_FIELD",
-    "ERROR_IN_CRL_NEXT_UPDATE_FIELD",
-    "OUT_OF_MEM",
-    "DEPTH_ZERO_SELF_SIGNED_CERT",
-    "SELF_SIGNED_CERT_IN_CHAIN",
-    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
-    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
-    "CERT_CHAIN_TOO_LONG",
-    "CERT_REVOKED",
-    "INVALID_CA",
-    "PATH_LENGTH_EXCEEDED",
-    "INVALID_PURPOSE",
-    "CERT_UNTRUSTED",
-    "CERT_REJECTED",
-    "HOSTNAME_MISMATCH",
-    "UNSPECIFIED",
-]);
 /**
  * Whether a failure met once a request that may create a run was sent, and before the API named
- * the run, leaves it unknown whether one was created: its answer was lost to a time limit, a
- * connection that closed once the request had left or a gateway that cut the request off, or it
- * came back unreadable, or a gateway answered that it lost or never got the server's answer
- * (`502`, `504`, RFC 9110). A gateway cuts a request off at ~30 seconds, whether a blocking
- * execute or a start the server is still handling, such as one fetching a `method_ref`'s package:
- * the SDK's `isGatewayCutOff` tells it, past its threshold, from the time since `onStarting`. Any
- * other answer from the API, a `503` that came back before that saying the request was not handled
- * included, and a failure that proves nothing was sent, say no run was created.
+ * the run, leaves it unknown whether one was created. The SDK decides it on the error it raises
+ * (`runMayHaveStarted`): its answer was lost to a time limit, a connection that closed once the
+ * request had left or a gateway that cut the request off, it came back unreadable, or the server
+ * or a gateway failed while handling it. A failure that proves nothing was sent, and an answer
+ * refusing the request before anything ran, say no run was created.
  */
 function mayHaveStarted(stage, error) {
-    if (stage.kind !== "starting")
-        return false;
-    if (error instanceof PipelineExecuteTimeoutError)
-        return true;
-    if (error instanceof ApiUnreachableError)
-        return !provesNothingSent(error);
-    if (!(error instanceof ApiResponseError))
-        return false;
-    if (error.status >= 200 && error.status < 300)
-        return true;
-    return (GATEWAY_LOST_ANSWER.has(error.status) || isGatewayCutOff(error, performance.now() - stage.since));
+    return stage.kind === "starting" && runMayHaveStartedOf(error);
 }
-/** The gateway statuses that say the server's answer was lost or never came (RFC 9110). */
-const GATEWAY_LOST_ANSWER = new Set([502, 504]);
 /** The line under a failure that leaves it unknown whether a run was created. */
 export const RUN_MAY_HAVE_STARTED_LINE = "A run may have started on the server without the command learning of it, so check before starting it again.";
 /** The line under a failure met while waiting on a run that exists. */

package/dist/cli/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"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"}

package/dist/cli/script.d.ts

@@ -15,7 +15,7 @@ import type { CommandIO } from "./io.js";
  * update notice and npm 12's run notices off the script's stderr, which carries the command's
  * own lines, while npm's warnings and errors still print.
  */
-export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.37.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.39.0";
 export declare const SCRIPT_WRITER = "@pipelex/sdk";
 export declare const SCRIPT_NEEDS = "Node 22.12 or later";
 /** Run `pipelex-sdk script` and return its exit code. */

package/dist/client.d.ts

@@ -161,7 +161,8 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * 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`).
      */
     private requestRaw;
     /**
@@ -230,6 +231,7 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * `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.
      */
     private unreadableAnswer;
     /**
@@ -249,6 +251,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * 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.
      */
     private throwIfExecuteDegraded;
     /**
@@ -538,12 +545,17 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * 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).
      */
     getRunStatus(runId: string, options?: {
         signal?: AbortSignal;
@@ -609,6 +621,13 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * `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.
      */
     startAndWaitForResult(options: PipelexStartOptions, pollOptions?: StartAndWaitForResultOptions): Promise<RunResults>;
     /** The authenticated user's profile — `GET /v1/me`. */
@@ -956,6 +975,9 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * 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`.
+     *
+     * With `allowUploads: false` it uploads nothing and reads no file: a value that
+     * would need an upload throws `UploadNotAllowedError`, naming the input.
      */
     prepareInputs(request: PrepareInputsRequest): Promise<PreparedInputs>;
     /**
@@ -1050,8 +1072,9 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
  * `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 declare function isGatewayCutOff(error: unknown, elapsedMs: number): boolean;