@pipelex/sdk 0.40.0 → 0.42.0

package/README.md

@@ -72,6 +72,23 @@ const saved = await client.start({ method_id: "mt_abc123@3", inputs: {} });
 console.log(saved.method_version); // 3
 ```
 
+### A start you can retry: `idempotencyKey`
+
+`start` and `startAndWaitForResult` take an optional `idempotencyKey`, sent as the `Idempotency-Key` header of `POST /v1/start`. The hosted API binds the key to the run the first request starts, so the same start sent again under the same key is answered with that run and starts nothing: a start whose answer was lost can be sent again without paying for a second run. Generate one key per run, and keep it with the options, unchanged, across that start's retries:
+
+```ts
+import { runMayHaveStartedOf } from "@pipelex/sdk";
+
+const options = { method_id: "mt_abc123", inputs, idempotencyKey: crypto.randomUUID() };
+const ack = await client.start(options).catch((err: unknown) => {
+  // The run may exist: under the same key, the same start is answered with it.
+  if (runMayHaveStartedOf(err)) return client.start(options);
+  throw err;
+});
+```
+
+A key is 1 to 255 visible ASCII characters; a key reused with other options is refused with a `409` `conflict`, and one whose earlier start is still being handled with a retryable `409` `idempotency_key_in_use` ([`docs/errors.md`](./docs/errors.md#a-starts-idempotency-key--idempotencykey)). A bare runner ignores the header.
+
 ### Checking a model reference
 
 `checkModelReference` asks the runner whether a reference a method's `model` field could name resolves, as what kind and to which model (`GET /v1/models/check`, served by `pipelex-api` from pipelex 0.78.0). A reference that resolves nowhere is a verdict, not an error, and narrowing on `kind` types its `matches`:
@@ -102,6 +119,8 @@ const client = new PipelexApiClient({ apiKey: process.env.PIPELEX_API_KEY });
 
 const me = await client.getMe(); // GET /v1/me
 const page = await client.listMethods(); // GET /v1/methods — one page: { items, nextCursor }
+// Only the methods never published. A filtered page can be empty and still carry a nextCursor.
+const drafts = await client.listMethods({ published: false });
 for await (const method of client.iterateMethods()) {
   // follows the cursor for callers that genuinely want the whole catalog
 }
@@ -134,7 +153,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. 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)).
+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)), unless the start carried an `idempotencyKey`, in which case sending it again unchanged recovers the run ([above](#a-start-you-can-retry-idempotencykey)).
 
 ```ts
 import { errorVerdictOf } from "@pipelex/sdk";

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.40.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.42.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

@@ -105,8 +105,37 @@ export interface PipelexHostedRunExtensions {
 }
 /** `execute()` options — the protocol's run arguments plus the Pipelex API and hosted extensions. */
 export type PipelexRunOptions = RunOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions;
-/** `start()` / `startAndWaitForResult()` options — the same, for the durable path. */
-export type PipelexStartOptions = StartOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions;
+/**
+ * What a run start sends beside its body: the request's own headers, which no run argument
+ * reaches. Each is camelCase, since none of them is a wire field of the run request.
+ */
+export interface PipelexStartRequestOptions {
+    /**
+     * The start's idempotency key, sent as the `Idempotency-Key` header of `POST /v1/start`, and
+     * not sent at all when absent or `null`. Generate one per run the caller means to start (a
+     * `crypto.randomUUID()` is a good key), and keep it, with every other option unchanged, across
+     * that start's retries.
+     *
+     * The hosted API binds the key to the run the first request starts, before it dispatches it, so
+     * the same start sent again under the same key is answered with that run's acknowledgement and
+     * starts nothing, whatever became of the first attempt, for 24 hours. A failed start whose
+     * `runMayHaveStarted` is true can therefore be sent again unchanged, and recovers the run instead
+     * of paying for a second one. The same key with a different body is refused (`409` `conflict`),
+     * as is a key whose earlier request is still being handled (`409` `idempotency_key_in_use`,
+     * retryable: send it again under the same key in a few seconds); see `docs/errors.md`. A bare
+     * runner ignores the header.
+     *
+     * A key is 1 to 255 visible ASCII characters (`!` to `~`, so no space); anything else, an empty
+     * string included, is a `RequestArgumentError` before any request is sent, since a start sent
+     * without the key the caller asked for would lose the protection silently.
+     */
+    idempotencyKey?: string | null;
+}
+/**
+ * `start()` / `startAndWaitForResult()` options — the same, for the durable path, plus the start
+ * request's own `idempotencyKey`.
+ */
+export type PipelexStartOptions = StartOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions & PipelexStartRequestOptions;
 /**
  * The method selector `validate()` takes in place of inline contents — declared
  * beside the other wire shapes in `./models.js` and re-exported here, the import
@@ -205,6 +234,8 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
      * resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
+     * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
+     * `Idempotency-Key` header; only `start` passes one.
      */
     private requestRaw;
     /**
@@ -337,6 +368,13 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * durable — poll `getRunStatus` / `getRunResult`. A `method_ref` run's ack
      * additionally carries `method_provenance` — the address, the tag, and the
      * commit SHA that was actually fetched.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header, and nothing
+     * is sent without it: the hosted API answers the same start sent again under the
+     * same key with the run the first one started, so a failure whose
+     * `runMayHaveStarted` is true can be retried unchanged (see
+     * `PipelexStartRequestOptions`). A malformed key is a `RequestArgumentError`
+     * before anything is sent.
      */
     start(options: PipelexStartOptions): Promise<PipelexRunResultStart>;
     /**
@@ -687,6 +725,12 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * 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.
+     *
+     * `options.idempotencyKey` rides the durable start, so a call that failed while its start may
+     * have created a run can be made again with the same options and the same key: the hosted API
+     * answers the start with the run the first call started, and the wait follows it. The blocking
+     * execute of a bare runner carries no key, a bare runner having no idempotency to honour it. A
+     * malformed key is refused before the version handshake.
      */
     startAndWaitForResult(options: PipelexStartOptions, pollOptions?: StartAndWaitForResultOptions): Promise<RunResults>;
     /** The authenticated user's profile — `GET /v1/me`. */
@@ -705,7 +749,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * Rows are `MethodSummary`: no `mthds`, no `python`, no `updated_at`. Reach
      * for `getMethod(id)` when you need a method's source.
      *
-     * `q` is applied server-side over the whole catalog, not over the page.
+     * `q` is applied server-side over the whole catalog, not over the page, and so is
+     * `published` (`true` for the methods with a published version, `false` for those never
+     * published). Each row carries the method's publish state (`latest_version`,
+     * `latest_published`, `draft_digest`). Both filters run after the index read, so a page can
+     * come back empty and still carry a `nextCursor`: keep following it until it is `null`.
      */
     listMethods(query?: ListMethodsQuery): Promise<MethodPage>;
     /**
@@ -726,6 +774,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * TRUNCATED list with no error — precisely the bug paging was introduced to
      * remove. If you truly want an array, `Array.fromAsync` makes that your
      * explicit choice.
+     *
+     * It keeps going **through an empty page that carries a cursor**: under `q` or `published`
+     * such a page means "nothing matched in the slice just read", not "done". It stops on a
+     * `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real catalog reaches.
      */
     iterateMethods(query?: Omit<ListMethodsQuery, "cursor">): AsyncGenerator<MethodSummary, void, undefined>;
     /**
@@ -1065,6 +1118,13 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * conditions, so a bounded page genuinely reads less. They are INSTANTS,
      * not days — see `ListRunsQuery`.
      *
+     * `createdBy: "me"` keeps the caller's own runs and `status` the runs in any of the given
+     * statuses, sent as `created_by=me` and one repeated `status=` parameter per status. Both are
+     * filters applied after the index read, so a filtered page can hold fewer runs than `limit`,
+     * or none, and still carry a `nextCursor`: an empty page is not the end, a `null` cursor is.
+     * An empty `status` list, or a name that is no `RunStatus`, is a `RequestArgumentError`
+     * before any request.
+     *
      * Takes a bare catalog id: the history files the runs of every version and
      * of the draft together under it, so `mt_…@3` names no history of its own
      * and the platform refuses it with a `400`. Strip a suffix with
@@ -1094,6 +1154,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * when to stop, and only one page is ever in memory. If you truly want an
      * array, `Array.fromAsync` makes that your explicit choice.
      *
+     * It keeps going **through an empty page that carries a cursor**: under `createdBy` or
+     * `status` such a page means "nothing matched in the slice just read", not "done". It stops on
+     * a `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real history reaches.
+     *
      * Takes a bare catalog id, as `listRuns` does.
      */
     iterateRuns(methodId: string, query?: Omit<ListRunsQuery, "cursor">): AsyncGenerator<RunHistoryItem, void, undefined>;

package/dist/client.js

@@ -2,7 +2,7 @@
 // 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, readRunDegradation, selectionIncludesMainStuff, throwIfAborted, } from "./runs.js";
+import { assertArtifactSelection, assertWaitOptions, pollUntilResult, readRunDegradation, RUN_STATUSES, runStatusFilter, 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";
@@ -13,20 +13,69 @@ 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";
 import { MAX_TIMER_DELAY_MS, isTimerDelay } from "./timers.js";
-// A pure RUNAWAY guard on `iterateMethods`, deliberately not a coverage limit.
+// A pure RUNAWAY guard on the paged-list iterators (`iterateMethods`,
+// `iterateRuns`), deliberately not a coverage limit.
 //
 // It counts TOTAL pages, not empty ones. An earlier version capped consecutive
 // empty pages, which is the wrong axis: an empty page whose cursor ADVANCED is
-// real progress through the index — the platform applies `q` as a post-read
-// filter over a bounded slice per request, so a sparse match legitimately
-// yields runs of empty pages — and capping them turns a valid sparse search
-// into a thrown error. The stuck case is already caught by the no-progress
-// check (the server handing back the cursor we sent).
+// real progress through the index — the platform applies the list filters
+// (`q` and `published` on methods, `createdBy` and `status` on runs) after a
+// bounded read per request, so a sparse match legitimately yields runs of
+// empty pages — and capping them turns a valid sparse search into a thrown
+// error. The stuck case is already caught by the no-progress check (the
+// server handing back the cursor we sent).
 //
-// At the platform's 200-row maximum page size this is 2,000,000 methods, so it
+// At the platform's 200-row maximum page size this is 2,000,000 rows, so it
 // cannot fire on real data; it exists only so a server minting fresh cursors
 // forever cannot hang a caller indefinitely.
 const MAX_PAGES = 10_000;
+/**
+ * Follow a paged list's cursor until the server says there is no more, yielding every row —
+ * the one loop behind `iterateMethods` and `iterateRuns`, so the two cannot drift apart.
+ *
+ * It yields lazily: a caller that breaks early stops the requests. It stops when `nextCursor`
+ * is `null`, the normal end, and when the server hands back the cursor it was just sent, which
+ * is no progress and would repeat rows already yielded. It keeps going through an EMPTY page
+ * that carries a cursor, since a filtered page can hold no row and still not be the end; past
+ * `MAX_PAGES` pages it throws `PagingNotTerminatingError` rather than return a truncated list.
+ */
+async function* followCursor(route, readPage) {
+    let cursor;
+    let pages = 0;
+    for (;;) {
+        const page = await readPage(cursor);
+        // Checked BEFORE yielding: a server handing back the very cursor we sent
+        // has not advanced, so this page repeats rows already emitted — yielding
+        // first and stopping after would silently double-count them for anyone
+        // aggregating the stream (summing cost, counting runs). Cannot fire on the
+        // first request, where `cursor` is undefined.
+        if (cursor !== undefined && page.nextCursor === cursor)
+            return;
+        for (const item of page.items)
+            yield item;
+        // `nextCursor === null` is the NORMAL end of the list, and that page is
+        // real data, so it has to be emitted before this fires.
+        if (page.nextCursor === null)
+            return;
+        // An EMPTY page is NOT the end, and treating it as one was a bug. The
+        // platform filters after a bounded index read per request, so a sparse
+        // match legitimately returns `{items: [], nextCursor: "…"}` — "nothing
+        // matched in the slice I just read, keep going". Returning here dropped
+        // every later match silently, which is the exact truncation this
+        // pagination work exists to remove.
+        pages += 1;
+        if (pages >= MAX_PAGES) {
+            // THROW, do not return. A caller that asked for every row and got a
+            // partial answer with no error is back to the original bug one layer
+            // up; an error is the only honest response to a server that will not
+            // finish. Unreachable on real data — see MAX_PAGES. It also bounds a
+            // cursor that CYCLES (`c1 → c2 → c1`), which the adjacent check misses.
+            throw new PagingNotTerminatingError(`${route} did not terminate after ${MAX_PAGES} pages; refusing to keep paging. ` +
+                `This is a server-side fault, not a coverage limit.`, MAX_PAGES);
+        }
+        cursor = page.nextCursor;
+    }
+}
 /** 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");
@@ -139,7 +188,7 @@ export class PipelexApiClient {
      * no request path can miss the `User-Agent` or the bearer. Requests to third
      * parties (presigned object-store URLs) never go through here.
      */
-    requestHeaders(hasBody) {
+    requestHeaders(hasBody, idempotencyKey) {
         const headers = { Accept: "application/json" };
         if (this.userAgent !== undefined) {
             headers["User-Agent"] = this.userAgent;
@@ -150,6 +199,9 @@ export class PipelexApiClient {
         if (hasBody) {
             headers["Content-Type"] = "application/json";
         }
+        if (idempotencyKey !== undefined) {
+            headers[IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
+        }
         return headers;
     }
     /**
@@ -159,10 +211,12 @@ export class PipelexApiClient {
      * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
      * resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
+     * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
+     * `Idempotency-Key` header; only `start` passes one.
      */
     async requestRaw(method, url, options = {}) {
         const hasBody = options.body !== undefined;
-        const headers = this.requestHeaders(hasBody);
+        const headers = this.requestHeaders(hasBody, options.idempotencyKey);
         const timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
         // A longer delay overflows the timer, which then fires at once as a false timeout.
         if (!isTimerDelay(timeoutMs)) {
@@ -526,8 +580,16 @@ export class PipelexApiClient {
      * durable — poll `getRunStatus` / `getRunResult`. A `method_ref` run's ack
      * additionally carries `method_provenance` — the address, the tag, and the
      * commit SHA that was actually fetched.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header, and nothing
+     * is sent without it: the hosted API answers the same start sent again under the
+     * same key with the run the first one started, so a failure whose
+     * `runMayHaveStarted` is true can be retried unchanged (see
+     * `PipelexStartRequestOptions`). A malformed key is a `RequestArgumentError`
+     * before anything is sent.
      */
     async start(options) {
+        const idempotencyKey = idempotencyKeyOf(options);
         const extensions = buildExtensions(options.extra);
         const api = buildApiRunExtensions(options);
         const hosted = buildHostedRunExtensions(options);
@@ -578,6 +640,7 @@ export class PipelexApiClient {
         const res = await this.requestRaw("POST", url, {
             body: request,
             timeoutMs: needsLongCeiling ? DEFAULT_REQUEST_TIMEOUT_MS : POLL_REQUEST_TIMEOUT_MS,
+            idempotencyKey,
             ...STARTS_RUN,
         });
         // A bare runner with no run store 404s here just as it does on the result
@@ -1178,10 +1241,18 @@ export class PipelexApiClient {
      * 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.
+     *
+     * `options.idempotencyKey` rides the durable start, so a call that failed while its start may
+     * have created a run can be made again with the same options and the same key: the hosted API
+     * answers the start with the run the first call started, and the wait follows it. The blocking
+     * execute of a bare runner carries no key, a bare runner having no idempotency to honour it. A
+     * malformed key is refused before the version handshake.
      */
     async startAndWaitForResult(options, pollOptions) {
         // Before the run starts: a refusal after it would carry no run id to re-poll by.
         assertWaitOptions(pollOptions);
+        // Before the handshake too: a key the start would refuse is the caller's to fix, whatever runs.
+        idempotencyKeyOf(options);
         const { onStarted, onStarting, ...waitOptions } = pollOptions ?? {};
         const hosted = await this.supportsRunLifecycle();
         // The handshake may have outlasted the caller's patience: an abort that landed during it
@@ -1237,16 +1308,23 @@ export class PipelexApiClient {
      * Rows are `MethodSummary`: no `mthds`, no `python`, no `updated_at`. Reach
      * for `getMethod(id)` when you need a method's source.
      *
-     * `q` is applied server-side over the whole catalog, not over the page.
+     * `q` is applied server-side over the whole catalog, not over the page, and so is
+     * `published` (`true` for the methods with a published version, `false` for those never
+     * published). Each row carries the method's publish state (`latest_version`,
+     * `latest_published`, `draft_digest`). Both filters run after the index read, so a page can
+     * come back empty and still carry a `nextCursor`: keep following it until it is `null`.
      */
     async listMethods(query = {}) {
         const params = new URLSearchParams();
         // `!== undefined`, not truthiness — mirroring `listRuns`. Omission means
         // "the caller did not ask"; an explicit empty string is bad input and the
         // API should say so, rather than being silently dropped into an unfiltered
-        // query that returns everything and reads as working.
+        // query that returns everything and reads as working. `published: false`
+        // is a filter of its own, never omission.
         if (query.q !== undefined)
             params.set("q", query.q);
+        if (query.published !== undefined)
+            params.set("published", String(query.published));
         if (query.limit !== undefined)
             params.set("limit", String(query.limit));
         if (query.cursor !== undefined)
@@ -1272,43 +1350,14 @@ export class PipelexApiClient {
      * TRUNCATED list with no error — precisely the bug paging was introduced to
      * remove. If you truly want an array, `Array.fromAsync` makes that your
      * explicit choice.
+     *
+     * It keeps going **through an empty page that carries a cursor**: under `q` or `published`
+     * such a page means "nothing matched in the slice just read", not "done". It stops on a
+     * `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real catalog reaches.
      */
     async *iterateMethods(query = {}) {
-        let cursor;
-        let pages = 0;
-        for (;;) {
-            const page = await this.listMethods({ ...query, cursor });
-            // Checked BEFORE yielding: a server handing back the very cursor we sent
-            // has not advanced, so this page repeats rows already emitted. Cannot
-            // fire on the first request, where `cursor` is undefined.
-            if (cursor !== undefined && page.nextCursor === cursor)
-                return;
-            for (const method of page.items)
-                yield method;
-            // `nextCursor === null` is the NORMAL end of the catalog, and that page
-            // is real data, so it has to be emitted before this fires.
-            if (page.nextCursor === null)
-                return;
-            // An EMPTY page is NOT the end, and treating it as one was a bug. The
-            // platform applies `q` as a post-read filter over a bounded number of
-            // index pages per request, so a sparse match legitimately returns
-            // `{items: [], nextCursor: "…"}` — "nothing matched in the slice I just
-            // read, keep going". Returning here dropped every later match silently,
-            // which is the exact truncation this pagination work exists to remove.
-            // (`iterateRuns` can stop on an empty page because its date bounds are
-            // index KEY conditions, so a run page is never empty-with-a-cursor. The
-            // difference is the server, not the client.)
-            pages += 1;
-            if (pages >= MAX_PAGES) {
-                // THROW, do not return. A caller that asked for every method and got a
-                // partial answer with no error is back to the original bug one layer
-                // up; an error is the only honest response to a server that will not
-                // finish. Unreachable on real data — see MAX_PAGES.
-                throw new PagingNotTerminatingError(`listMethods did not terminate after ${MAX_PAGES} pages; refusing to keep paging. ` +
-                    `This is a server-side fault, not a coverage limit.`, MAX_PAGES);
-            }
-            cursor = page.nextCursor;
-        }
+        yield* followCursor("listMethods", (cursor) => this.listMethods({ ...query, cursor }));
     }
     /**
      * Read one method — `GET /v1/methods/{id}`: its identity, its draft (`mthds`, `python`,
@@ -1739,6 +1788,13 @@ export class PipelexApiClient {
      * conditions, so a bounded page genuinely reads less. They are INSTANTS,
      * not days — see `ListRunsQuery`.
      *
+     * `createdBy: "me"` keeps the caller's own runs and `status` the runs in any of the given
+     * statuses, sent as `created_by=me` and one repeated `status=` parameter per status. Both are
+     * filters applied after the index read, so a filtered page can hold fewer runs than `limit`,
+     * or none, and still carry a `nextCursor`: an empty page is not the end, a `null` cursor is.
+     * An empty `status` list, or a name that is no `RunStatus`, is a `RequestArgumentError`
+     * before any request.
+     *
      * Takes a bare catalog id: the history files the runs of every version and
      * of the draft together under it, so `mt_…@3` names no history of its own
      * and the platform refuses it with a `400`. Strip a suffix with
@@ -1756,6 +1812,10 @@ export class PipelexApiClient {
             params.set("created_from", query.createdFrom);
         if (query.createdTo !== undefined)
             params.set("created_to", query.createdTo);
+        if (query.createdBy !== undefined)
+            params.set("created_by", query.createdBy);
+        for (const status of runStatusFilter(query.status) ?? [])
+            params.append("status", status);
         if (query.limit !== undefined)
             params.set("limit", String(query.limit));
         if (query.cursor !== undefined)
@@ -1785,33 +1845,15 @@ export class PipelexApiClient {
      * when to stop, and only one page is ever in memory. If you truly want an
      * array, `Array.fromAsync` makes that your explicit choice.
      *
+     * It keeps going **through an empty page that carries a cursor**: under `createdBy` or
+     * `status` such a page means "nothing matched in the slice just read", not "done". It stops on
+     * a `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real history reaches.
+     *
      * Takes a bare catalog id, as `listRuns` does.
      */
     async *iterateRuns(methodId, query = {}) {
-        let cursor;
-        for (;;) {
-            const page = await this.listRuns(methodId, { ...query, cursor });
-            // Checked BEFORE yielding. A server handing back the very cursor we sent
-            // has not advanced, so this page repeats rows already emitted — yielding
-            // first and stopping after would silently double-count them for anyone
-            // aggregating the stream (summing cost, counting runs). Cannot fire on
-            // the first request, where `cursor` is undefined.
-            if (cursor !== undefined && page.nextCursor === cursor)
-                return;
-            for (const run of page.items)
-                yield run;
-            // Checked AFTER: `nextCursor === null` is the NORMAL end of the history
-            // and that page is real data, so it has to be emitted first. The empty
-            // page catches a server that keeps minting fresh cursors while returning
-            // nothing, which would otherwise spin forever yielding nothing.
-            //
-            // Neither of these is a page cap. Both fire only on a server that is not
-            // making progress, so neither can truncate a healthy stream the way a
-            // `maxPages` limit silently did.
-            if (page.nextCursor === null || page.items.length === 0)
-                return;
-            cursor = page.nextCursor;
-        }
+        yield* followCursor("listRuns", (cursor) => this.listRuns(methodId, { ...query, cursor }));
     }
     /**
      * The whole record for one run — `GET /v1/runs/{id}`.
@@ -2170,6 +2212,55 @@ function nonEmptyFiles(files) {
 function nonEmptyString(value) {
     return value != null && value.length > 0 ? value : undefined;
 }
+/** The request header the hosted API reads a run start's idempotency key from. */
+const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/**
+ * The longest idempotency key a start sends. It is room for any generated key, and keeps the
+ * hosted API's stored record of the key far inside its store's limit, which a longer key could
+ * exceed, so that the start would run without the protection the key was sent for.
+ */
+const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/**
+ * Visible ASCII, `!` to `~`: what a header value carries unchanged through every proxy and both
+ * SDKs' transports, where fetch refuses a line break, httpx a character outside ASCII, and a space
+ * at either end is trimmed on the way.
+ */
+const VISIBLE_ASCII = /^[\x21-\x7E]+$/;
+/**
+ * The idempotency key a start sends, or `undefined` when the options carry none (absent or
+ * `null`). A key that is not a string of 1 to 255 visible ASCII characters is refused with a
+ * `RequestArgumentError` rather than dropped, an empty one included, since a start sent without
+ * the key its caller gave would lose the protection the caller asked for without a word. The
+ * message never quotes the key, which a caller may derive from something private. The Python SDK
+ * holds a key to the same rule, in the same words.
+ */
+function idempotencyKeyOf(options) {
+    const key = options.idempotencyKey;
+    if (key == null)
+        return undefined;
+    const fault = idempotencyKeyFault(key);
+    if (fault !== undefined) {
+        throw new RequestArgumentError(`The idempotency key must be 1 to ${MAX_IDEMPOTENCY_KEY_LENGTH} visible ASCII characters ` +
+            `(\`!\` to \`~\`), and this one ${fault}. Leave it out to start the run without one.`);
+    }
+    return key;
+}
+/**
+ * What is wrong with an idempotency key, or `undefined` when it is a valid one. The characters are
+ * checked before the length, which then counts ASCII characters alone, so the two SDKs, which
+ * count a character outside ASCII differently, word every refusal alike.
+ */
+function idempotencyKeyFault(key) {
+    if (typeof key !== "string")
+        return "is not a string";
+    if (key.length === 0)
+        return "is empty";
+    if (!VISIBLE_ASCII.test(key))
+        return "holds a character outside visible ASCII";
+    if (key.length > MAX_IDEMPOTENCY_KEY_LENGTH)
+        return `is ${key.length} characters long`;
+    return undefined;
+}
 function withValidateMarkdownRender(render) {
     const formats = new Set(render ?? []);
     formats.add(VALIDATE_MARKDOWN_RENDER_FORMAT);
@@ -2284,16 +2375,6 @@ function parseRetryAfter(headers) {
     const seconds = Number(raw);
     return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
 }
-const KNOWN_RUN_STATUSES = [
-    "PENDING",
-    "STARTED",
-    "RUNNING",
-    "COMPLETED",
-    "FAILED",
-    "CANCELLED",
-    "TERMINATED",
-    "TIMED_OUT",
-];
 /** The response header the platform and the runner stamp the request's correlation id on. */
 const REQUEST_ID_HEADER = "x-request-id";
 /**
@@ -2342,7 +2423,7 @@ function withCheckedDegradation(run) {
     return { ...run, degradation: readRunDegradation(run.degradation) };
 }
 function knownRunStatus(value) {
-    return typeof value === "string" && KNOWN_RUN_STATUSES.includes(value)
+    return typeof value === "string" && RUN_STATUSES.includes(value)
         ? value
         : undefined;
 }