@pipelex/sdk 0.32.0 → 0.34.0

package/dist/cli/source.js

@@ -0,0 +1,71 @@
+/**
+ * The method as each route names it, and the one pipe I/O call that checks it.
+ *
+ * A bundle read from disk travels to the pipe I/O route as `files`, each file under its name in the
+ * bundle, and to the run as `mthds_contents`, in the same order. An address travels as
+ * `method_ref` and a catalog id as `method_id`, both resolved by the server.
+ */
+import { CommandError, EXIT_FAILED, untilInterrupted } from "./io.js";
+import { loadFailureLines, METHOD_DOES_NOT_LOAD_SENTENCE } from "./present.js";
+export function crateSelector(source) {
+    switch (source.kind) {
+        case "bundle":
+            return { files: source.files.map((file) => ({ content: file.content, source: file.name })) };
+        case "address":
+            return { method_ref: source.methodRef };
+        case "catalog":
+            return { method_id: source.methodId };
+    }
+}
+/** The method as the run routes name it. */
+export function runSelector(source) {
+    switch (source.kind) {
+        case "bundle":
+            return { mthds_contents: source.files.map((file) => file.content) };
+        case "address":
+            return { method_ref: source.methodRef };
+        case "catalog":
+            return { method_id: source.methodId };
+    }
+}
+/**
+ * Ask `POST /v1/pipe-io` for the pipe the method and `--pipe` select, which spends no inference:
+ * the same selection the run's input preparation makes.
+ *
+ * @throws {CommandError} When the method does not load, or the answer does not describe the pipe
+ *   it selected. A refusal of the request itself propagates as the SDK's `ApiResponseError`.
+ * @throws {Interrupted} When the person interrupts the wait.
+ */
+export async function describePipe(client, source, pipe, interrupt) {
+    const request = {
+        ...crateSelector(source),
+        ...(pipe === undefined ? {} : { pipe_ref: pipe }),
+    };
+    const answer = await untilInterrupted(() => client.pipeIo(request), interrupt);
+    if (!isPlainObject(answer) || typeof answer.is_valid !== "boolean") {
+        throw new CommandError("the API's pipe I/O answer says neither that the method loads nor why it does not.", {
+            exitCode: EXIT_FAILED,
+        });
+    }
+    if (!answer.is_valid) {
+        throw new CommandError(METHOD_DOES_NOT_LOAD_SENTENCE, {
+            exitCode: EXIT_FAILED,
+            details: loadFailureLines(answer.validation_errors, answer.message),
+        });
+    }
+    const report = answer;
+    const pipeRef = report.pipe_ref;
+    const inputForm = report.input_form;
+    if (typeof pipeRef !== "string" ||
+        !isPlainObject(inputForm) ||
+        !isPlainObject(inputForm[pipeRef])) {
+        throw new CommandError("the API's pipe I/O answer does not describe the pipe it selected.", {
+            exitCode: EXIT_FAILED,
+        });
+    }
+    return { report, pipeRef, descriptor: inputForm[pipeRef] };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=source.js.map

package/dist/cli/source.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * The `pipelex-sdk` executable, which `package.json` declares as the package's one `bin`, so that
+ * `npx @pipelex/sdk run …` runs it. It hands the command the real process — its arguments, its
+ * environment, its streams and Ctrl-C — and exits with the command's code (`docs/cli.md`).
+ *
+ * It uses no top-level `await`, as no module of `dist/` does, so that the package stays loadable
+ * through `require(ESM)` (`docs/architecture.md`, "Module format & packaging").
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * The `pipelex-sdk` executable, which `package.json` declares as the package's one `bin`, so that
+ * `npx @pipelex/sdk run …` runs it. It hands the command the real process — its arguments, its
+ * environment, its streams and Ctrl-C — and exits with the command's code (`docs/cli.md`).
+ *
+ * It uses no top-level `await`, as no module of `dist/` does, so that the package stays loadable
+ * through `require(ESM)` (`docs/architecture.md`, "Module format & packaging").
+ */
+import process from "node:process";
+import { EXIT_INTERRUPTED, ignoreClosedPipe } from "./cli/io.js";
+import { runCommand } from "./cli/main.js";
+const interrupt = new AbortController();
+// Once: a second Ctrl-C finds no handler and ends the process the default way.
+process.once("SIGINT", () => interrupt.abort());
+// A reader that stops early (`| head`, `2>&1 | head -1`) closes the pipe on either stream.
+ignoreClosedPipe(process.stdout);
+ignoreClosedPipe(process.stderr);
+void runCommand(process.argv.slice(2), {
+    env: process.env,
+    readStdin: async () => {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        return Buffer.concat(chunks);
+    },
+    writeStdout: (text) => {
+        process.stdout.write(text);
+    },
+    writeStderr: (text) => {
+        process.stderr.write(text);
+    },
+    interrupt: interrupt.signal,
+}).then(exitWhenFlushed);
+/**
+ * Exit once both streams have flushed, rather than when the event loop empties: a request the
+ * command stopped waiting for on Ctrl-C, such as the start of a run, would otherwise hold the
+ * process open until the API answers it.
+ *
+ * After Ctrl-C, the process ends by the signal itself rather than by `process.exit(130)`, which a
+ * POSIX shell reports as the same status, 130: Node's exit waits for its worker threads, and one
+ * can be blocked for good in a read the command stopped waiting for, such as `--inputs` naming a
+ * named pipe no one writes to, or `/dev/stdin` on a terminal. Ending by the signal also tells a
+ * calling shell loop that the person interrupted. Windows has no such signal to end by, and exits
+ * with 130.
+ */
+async function exitWhenFlushed(code) {
+    await flush(process.stdout);
+    await flush(process.stderr);
+    if (code === EXIT_INTERRUPTED && interrupt.signal.aborted && process.platform !== "win32") {
+        // The once-only handler is gone, so SIGINT has its default action again: ending the process.
+        process.kill(process.pid, "SIGINT");
+    }
+    process.exit(code);
+}
+function flush(stream) {
+    return new Promise((resolve) => {
+        if (stream.destroyed || !stream.writable) {
+            resolve();
+            return;
+        }
+        stream.write("", () => resolve());
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAEH,OAAO,OAAO,MAAM,cAAc,CAAC;AAGnC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,MAAM,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;AACxC,+EAA+E;AAC/E,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;AAEhD,2FAA2F;AAC3F,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AACjC,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAEjC,KAAK,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACrC,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,SAAS,EAAE,KAAK,IAAI,EAAE;QACpB,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;QACtE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE;QACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE;QACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,SAAS,EAAE,SAAS,CAAC,MAAM;CAC5B,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,eAAe,CAAC,IAAY;IACzC,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,IAAI,KAAK,gBAAgB,IAAI,SAAS,CAAC,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1F,6FAA6F;QAC7F,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,SAAS,KAAK,CAAC,MAAgB;IAC7B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzC,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
 import type { CodegenRequest, CodegenResponse, DictPipeOutput, FormatResponse, LintResponse, MthdsFileItem, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
-import { type GetRunResultOptions, type RunRead, type RunResults, type RunResultState, type WaitForResultOptions } from "./runs.js";
+import { type GetRunResultOptions, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
 import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, InvoiceView, Membership, MembershipsResponse, ListMethodsQuery, MethodData, MethodDeletionAccepted, MethodPage, MethodSummary, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { AppInfo } from "./user-agent.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
@@ -120,7 +120,8 @@ export interface PipelexApiClientOptions {
      * `{ name: "acme-invoicer", version: "1.4.0" }` →
      * `acme-invoicer/1.4.0 pipelex-sdk-js/<v> node/<v> (<os>; <arch>)`. Validated at
      * construction: a field that is not an RFC 9110 token throws a `TypeError`. See
-     * the workspace spec `docs/specs/client-identification.md`.
+     * the spec `conformance/specs/client-identification.md`, in the `conformance` repository
+     * beside the specs' tests.
      */
     appInfo?: AppInfo;
 }
@@ -155,14 +156,6 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * resolved absolute URL.
      */
     private requestRaw;
-    /**
-     * Issue a request and parse the JSON body, throwing a plain `Error` on a non-2xx
-     * response. Used only by `health` — the origin-level liveness probe, which sits
-     * outside `/v1` and outside the RFC 7807 error taxonomy the `/v1` routes share.
-     * Every `/v1` route goes through a helper that maps its problem body to the typed
-     * `ApiResponseError` instead.
-     */
-    private requestJson;
     /**
      * Issue a Pipelex-product request (`/v1/me`, `/v1/methods`, `/v1/billing/*`,
      * …) and parse its JSON body, mapping a non-2xx response to the typed
@@ -172,7 +165,65 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * timeout, not the blocking-execute ceiling.
      */
     private requestProduct;
+    /**
+     * A product request whose answer is an object the SDK or its caller reads before anything else
+     * — a bulk resolution's `items`, a run record's `error`, an upload grant's `url`. Unlike
+     * `requestProduct`, an empty
+     * 2xx is no answer here: it and a body that is not a JSON object throw the `ApiResponseError`
+     * of an answer the SDK cannot read (see `readObjectAnswerAt`).
+     */
+    private requestProductObject;
+    /**
+     * A methods-catalog route answering one stored method (`getMethod`, `createMethod`,
+     * `updateMethod`), parsed into the public shape. A stored `mthds` that is neither a string nor
+     * absent (`null` stays "no source", which `getMethodClosure` reports), and a stored `python`
+     * the SDK cannot parse, are an answer it cannot read, so each throws an `ApiResponseError` built
+     * from that answer, the latter with `mthds`'s refusal as `cause`: `runtime`, not retryable,
+     * since no change to the call fixes it.
+     */
+    private requestMethodData;
+    /**
+     * One page of a cursor-paged product route (`listMethods`, `listRuns`), read as the platform
+     * always serializes it: `items` an array, `next_cursor` a string or `null`. A page breaking
+     * either is an answer the SDK cannot read, so it throws the `ApiResponseError` `unreadableAnswer`
+     * builds, `runtime` and not retryable, rather than handing the iterators a page they cannot
+     * walk: `items` that is not iterable, or a missing cursor that is neither the end nor a next
+     * page, which `iterateRuns` would follow forever.
+     */
+    private requestPage;
+    /** Issue a product request and return its 2xx answer, a non-2xx thrown as `ApiResponseError`. */
+    private requestProductAnswer;
     private throwApiResponseError;
+    /** The JSON body of a `/v1` route's 2xx answer; see `readAnswerAt`. */
+    private readAnswer;
+    /** The JSON object body of a `/v1` route's 2xx answer; see `readObjectAnswerAt`. */
+    private readObjectAnswer;
+    /**
+     * The JSON body of a 2xx answer, naming the route by its `path` from the origin as a refusal
+     * does. A body that is not UTF-8, or not JSON, an empty one included, is an answer the SDK
+     * cannot read, so it throws the `ApiResponseError` `unreadableAnswer` builds, with the parse
+     * failure as `cause`.
+     * The one place a success body is parsed.
+     */
+    private readAnswerAt;
+    /**
+     * The JSON body of a 2xx answer from a route that answers an object, read as `readAnswerAt`
+     * 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`.
+     */
+    private readObjectAnswerAt;
+    /**
+     * The `ApiResponseError` of a 2xx answer the SDK cannot read, its message
+     * `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.
+     */
+    private unreadableAnswer;
+    /**
+     * Throw the `ApiResponseError` of a non-2xx answer, naming the route by its `path` from the
+     * origin (`/v1/...`, or `/health` for the liveness probe).
+     */
+    private throwApiResponseErrorAt;
     /**
      * Translate a "route absent" 404 (a bare pipelex-api with no platform block)
      * into a clear `RunLifecycleUnavailableError`. The platform's own 404s (run
@@ -187,6 +238,16 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * hints) beats a generic parse failure on an unexpected body shape.
      */
     private throwIfExecuteDegraded;
+    /**
+     * The origin-level liveness probe — `GET /health`, which sits at the origin, NOT under the
+     * `/v1` prefix. A bare runner serves it; a hosted origin answers `/v1/health` instead, so
+     * there this throws.
+     *
+     * It goes through the same transport as every route: an unreachable origin is an
+     * `ApiUnreachableError`, and a non-2xx answer an `ApiResponseError` whose verdict the SDK's
+     * fallback reads from the status, since the probe answers no problem document. So is a 2xx
+     * whose body is not a JSON object, such as a gateway's HTML page: `runtime`, not retryable.
+     */
     health(): Promise<Record<string, unknown>>;
     /**
      * Execute a method synchronously and wait for its completion —
@@ -442,8 +503,10 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * 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. Throws `RunLifecycleUnavailableError`
-     * when the lifecycle routes are absent (a bare runner).
+     * 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).
      */
     getRunStatus(runId: string, options?: {
         signal?: AbortSignal;
@@ -477,8 +540,18 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * Whether the configured server serves the durable run lifecycle, decided
      * via the `GET /v1/version` handshake and cached for the client's lifetime. A
      * bare `pipelex-api` runner has no run store; anything else is assumed hosted.
-     * When the handshake itself fails, assume hosted (the SDK default) and let the
-     * start call surface the real error.
+     *
+     * The rule, the one the Python SDK follows: an answer that is not a usable
+     * version means assume hosted (the SDK default), and let the start surface the
+     * real error; no answer at all propagates, uncached. An answer is anything the
+     * server sent back: a non-2xx status, a body that is not JSON, not UTF-8 or no
+     * version, and a body that arrived but could not be decoded, such as a broken
+     * gzip stream, which `requestRaw` reports as an `ApiUnreachableError` carrying
+     * the decompressor's code (see `isUndecodableBody`).
+     *
+     * @throws {ApiUnreachableError} The handshake got no answer. Nothing is cached,
+     *   so the next call asks again, and no start is sent to a host that did not
+     *   answer: sending it would wait a second time for the same silence.
      */
     private supportsRunLifecycle;
     /**
@@ -488,8 +561,19 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      *   path that survives the gateway's ~30s synchronous ceiling.
      * - **Bare runner** (no run store): the blocking `POST /v1/execute`, which
      *   has no gateway cap off-platform and returns the native `pipe_output`.
+     *
+     * `pollOptions` are the wait's options, plus `onStarted`, called once with the
+     * start acknowledgement as soon as the durable run exists, so the caller holds
+     * the run's id while it waits; never on the blocking path, which has none to
+     * give; and `onStarting`, called right before each request that may create a
+     * run, so the caller knows until then that none exists (see
+     * `StartAndWaitForResultOptions`).
+     *
+     * `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.
      */
-    startAndWaitForResult(options: PipelexStartOptions, pollOptions?: WaitForResultOptions): Promise<RunResults>;
+    startAndWaitForResult(options: PipelexStartOptions, pollOptions?: StartAndWaitForResultOptions): Promise<RunResults>;
     /** The authenticated user's profile — `GET /v1/me`. */
     getMe(): Promise<UserProfile>;
     /**
@@ -668,7 +752,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * paths it sits at, errors as values. See `docs/artifact-download.md`.
      */
     downloadArtifacts(request: DownloadArtifactsRequest): Promise<DownloadArtifactsResult>;
-    /** Upload a base64 file — `POST /v1/upload`. */
+    /**
+     * Upload a base64 file — `POST /v1/upload`. An answer with no non-empty string `uri` names no
+     * stored file, so it is an answer the SDK cannot read: an `ApiResponseError`, `runtime` and
+     * not retryable, which `uploadFile` wraps as an `UploadTransportError` with code `unexpected`.
+     */
     upload(input: UploadInput): Promise<UploadedFile>;
     /**
      * Request a grant to upload one file straight to storage — `POST /v1/upload/grant`.
@@ -771,7 +859,8 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      *
      * The ONLY call that returns `mthds_contents` (what the run actually
      * executed) and `inputs`. Kept off the status read, which pollers hit every
-     * few seconds.
+     * few seconds. A failed run's stored report, `error`, is checked field by
+     * field (see `RunErrorReport`).
      */
     getRunDetail(runId: string): Promise<RunDetail>;
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
@@ -789,3 +878,22 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      */
     private executeBlocking;
 }
+/**
+ * Whether a request that failed `elapsedMs` after it was sent was cut off by the hosted gateway's
+ * ~30-second limit on a request it waits on, rather than refused.
+ *
+ * It is when, after at least ~28 seconds, the failure is a `503` or `504` answer, or the client's
+ * own time limit (`ApiUnreachableError` with the code `ABORT_TIMEOUT`). A fast `503` is the API
+ * saying the request was not handled, and any other unreachable host is never the gateway's
+ * cut-off, however long it took. The fetch API cannot say whether `ABORT_TIMEOUT` ran out before
+ * the connection was made, so it is read as the gateway's; with Node's own dispatcher it never
+ * does past the threshold, since undici gives up a connection that does not come after ten
+ * seconds (`UND_ERR_CONNECT_TIMEOUT`), the TLS handshake included. The Python SDK's
+ * `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.
+ */
+export declare function isGatewayCutOff(error: unknown, elapsedMs: number): boolean;