@pipelex/sdk 0.58.0 → 0.60.0

package/README.md

@@ -177,7 +177,6 @@ const copy = await client.copyMethod(
   { idempotencyKey: crypto.randomUUID() },
 );
 if (copy.outcome === "copied") console.log(copy.method.copied_from); // the original it names
-const copies = await client.listMethodCopies(created.method_id); // where the copies went
 
 // The organization's files, newest first: uploads, test files and the files runs made. Each row's
 // `uri` goes into a run's inputs as any address does. A filtered page can be empty and still carry
@@ -285,7 +284,7 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/method-trees.md`](./docs/method-trees.md) | A method's tree: the four forms a run, a validation, a save and the crate routes take it in (a directory on disk among them), how it travels inline or by hash and what is uploaded, the files a step reads, the template check's warnings and which step reads which file of the tree, the deployment's limits, the read's listing with its links, `writeMethodTree`, and `MethodFileTransferError` |
 | [`docs/files.md`](./docs/files.md) | An organization's files: `listFiles` and `iterateFiles`, the row, the whole record and its provenance, the query and its repeated filters, paging through filtered pages, one file and its uses, the records of an address, the rename rule, links that name the file, a zip of files and its caps, a run's files, the copy into a method's draft, and an upload recorded as a method's test file with the refusals that come with it |
 | [`docs/method-examples.md`](./docs/method-examples.md) | A method's saved examples: the create, the paged list and its iterator, the edit that raises the input revision, the latest-run write and its `recorded` or `stale` verdict, the build assistant's save and its `kept` or `created` verdict, how an integer past `Number.MAX_SAFE_INTEGER` in the inputs stays exact, and what is refused before sending |
-| [`docs/method-copy.md`](./docs/method-copy.md) | Copying a method into another organization or duplicating it: what a copy holds and the stored files it copies, the `copied` or `refused` verdict, every refusal, the copy's idempotency key, the copies a method lists, and `copied_from` |
+| [`docs/method-copy.md`](./docs/method-copy.md) | Copying a method into another organization or duplicating it: what a copy holds and the stored files it copies, the `copied` or `refused` verdict, every refusal, the copy's idempotency key, and `copied_from` |
 | [`docs/organization-branding.md`](./docs/organization-branding.md) | An organization's logos and colours: `getBranding`, which every member and API key reads, `updateOrganizationBranding`, an admin's write that sets, clears or keeps each key, and how a refused logo or colour names its slot in `errors` so a settings screen shows the sentence under it |
 | [`docs/exact-integers.md`](./docs/exact-integers.md) | Which reads keep an integer past `Number.MAX_SAFE_INTEGER` exact, as a `bigint` (a run's inputs and outputs, an example's inputs), how a request body writes it back with its digits, and `parseExactJson` and `stringifyExactJson` for code showing such data as JSON text |
 | [`docs/crate-routes.md`](./docs/crate-routes.md) | `resolve`, `codegen` and `pipeIo` — the method's tree as the protocol's `files` map, with its dependencies, the normalized crate, the stamped types, and a method's I/O artifacts without a validation — and the offline `runCodegenCheck` that guards a committed tree |

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

@@ -1,9 +1,10 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
 import type { CodegenRequest, CodegenResponse, CrateRouteOptions, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidateSource, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
 import { type GetRunResultOptions, type RunProgress, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
-import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodCopiesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodCopyInput, MethodCopyPage, MethodCopyResult, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
+import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodCopyInput, MethodCopyResult, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { MethodTreeForms, MethodTreeLimits } from "./method-trees.js";
 import type { AppInfo } from "./user-agent.js";
+import type { WebhookDeliveryDetail, WebhookDeliveryList, WebhookReplayAccepted, WebhookReplayOptions, WebhookSecret, WebhookSecretRotateOptions } from "./webhooks.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
 import type { PrepareInputsRequest, PreparedInputs } from "./prepare-inputs.js";
 import type { BulkResolveStorageUrlsInput, BulkResolvedStorageUrls, DownloadArtifactsRequest, DownloadArtifactsResult, FetchArtifactOptions, ResolvedArtifact } from "./artifacts.js";
@@ -37,6 +38,27 @@ export interface PipelexApiRunExtensions {
      * An empty string is treated as absent and is not sent.
      */
     method_ref?: string | null;
+    /**
+     * Webhook URLs to call once the run has ended, each with a signed `run.finished` event whose
+     * `data` is the run's status read, so a caller learns of the end without polling. Read the call
+     * with `verifyWebhook`, then fetch the results with the event's `pipeline_run_id`; see
+     * `docs/webhooks.md`.
+     *
+     * A layer-2 extension: the hosted API and a self-hosted runner both take it on `start` and
+     * `execute`, and each holds the URLs to its own rules, which this client does not restate. The
+     * hosted API takes at most 5 HTTPS URLs of at most 2,048 characters, none repeated, and refuses a
+     * URL whose host resolves to a private, loopback, link-local or metadata address with a `422`
+     * `request.invalid` naming it as `callback_urls.<index>`; a deployment that does not deliver
+     * caller webhooks refuses the list with a `422` `request.unsupported`. A self-hosted runner
+     * whose operator configured no signing secret refuses it with a `422`
+     * `pipelex.webhook.secret_not_configured`. The start's acknowledgement and every read of the run
+     * list the URLs redacted, as `callback_urls`.
+     *
+     * Not a run source: a run still needs something to run. A value that is not an array of strings
+     * is a `RequestArgumentError` before anything is sent, and an empty array is treated as absent
+     * and is not sent.
+     */
+    callback_urls?: readonly string[] | null;
 }
 /**
  * The hosted API's own run arguments — the layer-3 extensions this client adds
@@ -262,7 +284,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `url` is a fully resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose errors then say whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start` and `copyMethod` pass one.
+     * `Idempotency-Key` header; only `start`, `copyMethod`, `rotateWebhookSecret` and
+     * `replayRunWebhookDelivery` pass one.
      */
     private requestRaw;
     /**
@@ -592,10 +615,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * The mapping is what makes their no-verdict arms usable: a crate route answers `422`
      * for a request it cannot act on (a pipe selection `pipe-io` refuses; an unknown
-     * `kind`/`target`, or a `pipe_ref` on the concept-set-wide `types` kind, on `codegen`)
-     * and `501` for the reserved registry-form `method_ref` (the address form is resolved
-     * server-side as of pipelex-api 0.21.0). A caller branches on `ApiResponseError.status`,
-     * never on a message.
+     * `kind`/`target`, or a `pipe_ref` on the concept-set-wide `types` kind, on `codegen`;
+     * the reserved registry-form `method_ref`, coded `request.unsupported`, on all three, the
+     * address form being resolved server-side as of pipelex-api 0.21.0). A caller branches on
+     * the problem's `code`, never on a message.
      *
      * All of these are static and inference-free, so they default to the management-call
      * timeout. The internal raise is `crateRequestTimeoutMs`'s: the fetch-sized budget a
@@ -682,7 +705,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * protocol's `files` map or as a `directory`, `tree` or `contents` the client sends
      * inline when small and by hash otherwise (see {@link CrateRequestBase}); an
      * address-form `method_ref` (server-resolved, pipelex-api >= 0.21.0; the registry form
-     * stays a `501`); or a hosted `method_id` (platform-resolved — see
+     * is a `422` `request.unsupported`); or a hosted `method_id` (platform-resolved — see
      * {@link PipelexHostedToolingExtensions}). An empty map or string is absent.
      *
      * `options.signal` stops the call between the steps a `directory`, `tree` or `contents`
@@ -707,7 +730,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Same 200-verdict discipline and same three-form closure selector as
      * {@link resolve}. Only a no-verdict condition throws `ApiResponseError`: an
      * unknown `kind`/`target`, a `pipe_ref` on the concept-set-wide `types` kind, or
-     * a malformed selector is a 422; a registry-form `method_ref` is a `501`.
+     * a malformed selector is a 422, and so is a registry-form `method_ref`, coded
+     * `request.unsupported`.
      */
     codegen(request: CodegenRequest, options?: CrateRouteOptions): Promise<CodegenResponse>;
     /**
@@ -738,9 +762,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Only a no-verdict condition throws `ApiResponseError`: a malformed selector and an
      * over-limit file are `422` problems; a selection the route refuses is a `422` whose
      * `code` is `request.pipe_not_found` (an unknown `pipe_ref`), `request.pipe_unspecified`
-     * (no entry pipe) or `request.pipe_ambiguous` (an ambiguous code, several entry pipes), the
-     * candidates in its `params`; a registry-form `method_ref` is a `501`; a pipe whose
-     * artifacts cannot be derived is a `500`.
+     * (no entry pipe, or several bundles' `main_pipe` declarations) or `request.pipe_ambiguous`
+     * (an ambiguous bare code), the candidates in its `params`; a registry-form `method_ref` is a
+     * `422` `request.unsupported`; 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,
@@ -1324,26 +1348,6 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * an `ApiResponseError` too.
      */
     copyMethod(methodId: string, input: MethodCopyInput, options?: MethodCopyRequestOptions): Promise<MethodCopyResult>;
-    /**
-     * One page of the copies made of a method, in the order of the copies' ids, which says nothing
-     * of when each was made — `GET /v1/methods/{id}/copies`.
-     *
-     * Each row is the `MethodCopyMarker` the original keeps of a copy: the copy's id, the
-     * destination's id, the member who made it and when. The destination is named by its id alone,
-     * never its name, so a surface shows a destination's name only from the reader's own
-     * memberships, and a copy in an organization the reader does not belong to stays a bare id. A
-     * marker stays when its copy is erased, and the copy then reads as not found. Pass the page's
-     * `nextCursor` back as `cursor` to continue; `null` is the last page. A method never copied,
-     * and a copy itself, answer an empty page. The listing is open to every member of the method's
-     * organization, a runner included, as every read of a method is.
-     *
-     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404`
-     * `pipelex.catalog.not_found` for an unknown method, `409` `pipelex.catalog.being_deleted`, and
-     * `422` `request.invalid` for a cursor the listing did not issue for this method or a `limit`
-     * outside 1 to 100. A page whose `items` is not an array or whose `next_cursor` is neither a
-     * string nor `null` is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
-     */
-    listMethodCopies(methodId: string, query?: ListMethodCopiesQuery): Promise<MethodCopyPage>;
     /**
      * Erase a method and everything it produced — `DELETE /v1/methods/{id}`.
      *
@@ -1557,6 +1561,31 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * the write may have landed or not: the same input sent again is safe.
      */
     updateOrganizationBranding(orgId: string, input: OrganizationBrandingUpdate): Promise<OrganizationBranding>;
+    /**
+     * The organization's webhook signing secret — `GET /v1/organizations/{org_id}/webhook-secret`:
+     * the `whsec_` secret every caller webhook of the organization is signed with, which a receiver
+     * hands to `verifyWebhook`. The platform generates it on this first read when the organization
+     * has none. Treat the answer as a credential: never log or cache it.
+     *
+     * An admin's route, from a web session only: the hosted gateway refuses an API key on it. Throws
+     * `ApiResponseError`: `403` `auth.forbidden` whose `params.requirement` names `admin` for any
+     * other role, `403` `pipelex.org.mismatch` for an organization other than the caller's active
+     * one, and `404` `pipelex.org.not_found` for one with no record.
+     */
+    getWebhookSecret(orgId: string): Promise<WebhookSecret>;
+    /**
+     * Rotate the organization's webhook signing secret — `POST
+     * /v1/organizations/{org_id}/webhook-secret/rotate`: a new secret is current at once, and the
+     * one it replaces keeps signing beside it for 24 hours, then is dropped, so a receiver has a day
+     * to take the new one. An organization with no secret yet gets its first. Answers the new secret,
+     * as `getWebhookSecret` does, with its guards and refusals.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header. The answer carries a secret,
+     * so the platform never replays it: the same key sent again is refused `409`
+     * `request.already_executed` and rotates nothing more, and the secret is then read with
+     * `getWebhookSecret`. A malformed key is a `RequestArgumentError` before anything is sent.
+     */
+    rotateWebhookSecret(orgId: string, options?: WebhookSecretRotateOptions): Promise<WebhookSecret>;
     /** The active org's subscription state — `GET /v1/billing/subscription`. */
     getSubscription(): Promise<SubscriptionResponse>;
     /** Available plans (with `is_current`) — `GET /v1/billing/plans`. */
@@ -2066,6 +2095,65 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * string nor `null`, is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
      */
     listRunFiles(runId: string, query?: ListRunFilesQuery): Promise<RunFilesPage>;
+    /**
+     * A run's caller-webhook deliveries — `GET /v1/runs/{id}/webhook-deliveries`: one per URL the
+     * run registered in `callback_urls`, in their order, once the run has ended, each with its
+     * state and every attempt, its URL redacted. A run that registered none, or has not ended, lists
+     * none. Any member of the organization reads them, by web session or API key.
+     *
+     * Throws `RequestArgumentError` for a run id that is empty, `.` or `..`, or holds a lone
+     * surrogate, before any request. Throws `ApiResponseError`: `404` `run.not_found` for a run that
+     * is not the organization's, exactly as for one that does not exist. An answer whose
+     * `deliveries` is not an array is an answer the SDK cannot read, thrown as an `ApiResponseError`
+     * too.
+     */
+    listRunWebhookDeliveries(runId: string): Promise<WebhookDeliveryList>;
+    /**
+     * One delivery of a run's webhooks, with its event —
+     * `GET /v1/runs/{id}/webhook-deliveries/{delivery_id}`: the body its latest attempt sent, or,
+     * before any attempt, the body its first attempt will send. Every attempt and replay of the
+     * delivery sends that body, only its `attempt` changing, so the event matches what a receiver
+     * logged only once an attempt was made: it then equals, as JSON, the body that attempt brought
+     * the receiver. Compare the two as parsed JSON values, never as text: the read promises the same
+     * value, not the same bytes.
+     * `deliveryId` is the delivery's `delivery_id`, the receiver's `webhook-id`.
+     *
+     * Throws `RequestArgumentError` for an id that is empty, `.` or `..`, or holds a lone surrogate,
+     * before any request. Throws `ApiResponseError`: `404` `run.not_found` for a run the caller
+     * cannot read, and `422` `request.invalid` naming `delivery_id` for a delivery the run does not
+     * have.
+     */
+    getRunWebhookDelivery(runId: string, deliveryId: string): Promise<WebhookDeliveryDetail>;
+    /**
+     * Send a settled delivery again — `POST /v1/runs/{id}/webhook-deliveries/{delivery_id}/replay`:
+     * one new attempt under the same `webhook-id`, with the same `data`, the next `attempt`, a fresh
+     * timestamp, and the signatures of the secrets live when it is sent. A replay the receiver
+     * accepts marks the delivery `delivered`; one it does not leaves its state as it was, and the
+     * attempt is recorded either way. A replay never returns a delivery to `pending`. Anyone who
+     * can read the run asks for one, an API key included, under the organization's replay rate.
+     *
+     * Answers the attempt number the replay is sent under; a replay asked again before it is sent is
+     * that same attempt.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header, and nothing is sent when it
+     * is absent or `null`. The platform stores the replay's answer under the key, so the same replay
+     * sent again under the same key, as after an answer lost to a time limit, gets the stored answer,
+     * naming the same attempt, and the delivery is not sent twice. A key reused for another request
+     * is refused `409` `request.idempotency_conflict`, and one whose earlier request is still being
+     * handled `409` `request.idempotency_key_in_use`, whose `retry` is `yes`: send it again under the
+     * same key after its `retry_after`. See `WebhookReplayOptions`.
+     *
+     * Throws `RequestArgumentError` for an id that is empty, `.` or `..`, or holds a lone surrogate,
+     * or for an idempotency key that is not 1 to 255 visible ASCII characters, before any request.
+     * Throws `ApiResponseError`: `404` `run.not_found` for a run the caller cannot read; `422`
+     * `request.invalid` naming `delivery_id` for a delivery the run does not have; `409`
+     * `pipelex.org.not_manageable` with the reason `webhook_delivery_pending` for a delivery still on
+     * its retry schedule, or `webhook_delivery_attempts_exhausted` for one holding the most attempts
+     * a delivery holds; `429` `account.rate_limited`, with its `retry_after`, past the
+     * organization's replay rate; and a `500` or `503` when the replay could not be queued, which
+     * then counts nothing against the rate.
+     */
+    replayRunWebhookDelivery(runId: string, deliveryId: string, options?: WebhookReplayOptions): Promise<WebhookReplayAccepted>;
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
     updateRun(runId: string, input: UpdateRunInput): Promise<void>;
     /**
@@ -2079,8 +2167,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     /**
      * Blocking `POST /v1/execute` adapted onto `RunResults` — the bare-runner
      * path. Forwards every protocol field PLUS every extension surface: the
-     * runner-resolved `method_ref`, the hosted `method_id`, and the generic
-     * `extra` passthrough. An extension-only call (`{ extra }` with no
+     * runner-resolved `method_ref`, the run's `callback_urls`, the hosted
+     * `method_id`, and the generic `extra` passthrough. An extension-only call (`{ extra }` with no
      * pipe_code/bundle) or a vendor selector riding `extra` must survive this
      * path, not just the durable one — a `method_ref` run must run the same
      * fetched package here, and a hosted `method_id` must reach the server too,

package/dist/client.js

@@ -240,6 +240,10 @@ const ARCHIVE_ID_ARGUMENT = {
     name: "archive_id",
     what: "an archive id, the archive's non-empty `archive_id`",
 };
+const DELIVERY_ID_ARGUMENT = {
+    name: "delivery_id",
+    what: "a delivery id, the delivery's non-empty `delivery_id`",
+};
 /** What the run id of each example write is, as a refusal of it names it. */
 const CREATE_RUN_ID_ARGUMENT = {
     name: "run_id",
@@ -578,7 +582,8 @@ export class PipelexApiClient {
      * `url` is a fully resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose errors then say whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start` and `copyMethod` pass one.
+     * `Idempotency-Key` header; only `start`, `copyMethod`, `rotateWebhookSecret` and
+     * `replayRunWebhookDelivery` pass one.
      */
     async requestRaw(method, url, options = {}) {
         const hasBody = options.body !== undefined;
@@ -1300,10 +1305,10 @@ export class PipelexApiClient {
      *
      * The mapping is what makes their no-verdict arms usable: a crate route answers `422`
      * for a request it cannot act on (a pipe selection `pipe-io` refuses; an unknown
-     * `kind`/`target`, or a `pipe_ref` on the concept-set-wide `types` kind, on `codegen`)
-     * and `501` for the reserved registry-form `method_ref` (the address form is resolved
-     * server-side as of pipelex-api 0.21.0). A caller branches on `ApiResponseError.status`,
-     * never on a message.
+     * `kind`/`target`, or a `pipe_ref` on the concept-set-wide `types` kind, on `codegen`;
+     * the reserved registry-form `method_ref`, coded `request.unsupported`, on all three, the
+     * address form being resolved server-side as of pipelex-api 0.21.0). A caller branches on
+     * the problem's `code`, never on a message.
      *
      * All of these are static and inference-free, so they default to the management-call
      * timeout. The internal raise is `crateRequestTimeoutMs`'s: the fetch-sized budget a
@@ -1425,9 +1430,8 @@ export class PipelexApiClient {
     // unexposed — see their section above for why that blocks nothing. `pipe-io` is
     // newer: a runner serves it from `pipelex-api` v0.33.0, and codes its selection
     // refusals `request.pipe_not_found`, `request.pipe_unspecified` and
-    // `request.pipe_ambiguous`, and a hosted origin
-    // serves it once the platform's proxy and the gateway list it (see
-    // `docs/crate-routes.md`).
+    // `request.pipe_ambiguous` from v0.90.0; the dev plane serves it too, measured on
+    // api-dev.pipelex.com on 2026-10-31 (see `docs/crate-routes.md`).
     //
     // All three are STATIC routes (no dry-run sweep), so like every static sibling they
     // take no `timeoutMs` — see the policy note on `requestExtension` before adding one
@@ -1456,7 +1460,7 @@ export class PipelexApiClient {
      * protocol's `files` map or as a `directory`, `tree` or `contents` the client sends
      * inline when small and by hash otherwise (see {@link CrateRequestBase}); an
      * address-form `method_ref` (server-resolved, pipelex-api >= 0.21.0; the registry form
-     * stays a `501`); or a hosted `method_id` (platform-resolved — see
+     * is a `422` `request.unsupported`); or a hosted `method_id` (platform-resolved — see
      * {@link PipelexHostedToolingExtensions}). An empty map or string is absent.
      *
      * `options.signal` stops the call between the steps a `directory`, `tree` or `contents`
@@ -1483,7 +1487,8 @@ export class PipelexApiClient {
      * Same 200-verdict discipline and same three-form closure selector as
      * {@link resolve}. Only a no-verdict condition throws `ApiResponseError`: an
      * unknown `kind`/`target`, a `pipe_ref` on the concept-set-wide `types` kind, or
-     * a malformed selector is a 422; a registry-form `method_ref` is a `501`.
+     * a malformed selector is a 422, and so is a registry-form `method_ref`, coded
+     * `request.unsupported`.
      */
     async codegen(request, options = {}) {
         return this.crateRequest("codegen", "codegen", request, options);
@@ -1516,9 +1521,9 @@ export class PipelexApiClient {
      * Only a no-verdict condition throws `ApiResponseError`: a malformed selector and an
      * over-limit file are `422` problems; a selection the route refuses is a `422` whose
      * `code` is `request.pipe_not_found` (an unknown `pipe_ref`), `request.pipe_unspecified`
-     * (no entry pipe) or `request.pipe_ambiguous` (an ambiguous code, several entry pipes), the
-     * candidates in its `params`; a registry-form `method_ref` is a `501`; a pipe whose
-     * artifacts cannot be derived is a `500`.
+     * (no entry pipe, or several bundles' `main_pipe` declarations) or `request.pipe_ambiguous`
+     * (an ambiguous bare code), the candidates in its `params`; a registry-form `method_ref` is a
+     * `422` `request.unsupported`; 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,
@@ -2587,30 +2592,6 @@ export class PipelexApiClient {
         }
         return answer;
     }
-    /**
-     * One page of the copies made of a method, in the order of the copies' ids, which says nothing
-     * of when each was made — `GET /v1/methods/{id}/copies`.
-     *
-     * Each row is the `MethodCopyMarker` the original keeps of a copy: the copy's id, the
-     * destination's id, the member who made it and when. The destination is named by its id alone,
-     * never its name, so a surface shows a destination's name only from the reader's own
-     * memberships, and a copy in an organization the reader does not belong to stays a bare id. A
-     * marker stays when its copy is erased, and the copy then reads as not found. Pass the page's
-     * `nextCursor` back as `cursor` to continue; `null` is the last page. A method never copied,
-     * and a copy itself, answer an empty page. The listing is open to every member of the method's
-     * organization, a runner included, as every read of a method is.
-     *
-     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404`
-     * `pipelex.catalog.not_found` for an unknown method, `409` `pipelex.catalog.being_deleted`, and
-     * `422` `request.invalid` for a cursor the listing did not issue for this method or a `limit`
-     * outside 1 to 100. A page whose `items` is not an array or whose `next_cursor` is neither a
-     * string nor `null` is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
-     */
-    async listMethodCopies(methodId, query = {}) {
-        const search = productQuery({ limit: query.limit, cursor: query.cursor });
-        const endpoint = `${methodPath(methodId, "listMethodCopies")}/copies`;
-        return this.requestPage(`${endpoint}${search}`);
-    }
     /**
      * Erase a method and everything it produced — `DELETE /v1/methods/{id}`.
      *
@@ -2939,6 +2920,39 @@ export class PipelexApiClient {
         const segment = idPathSegment(orgId, "updateOrganizationBranding", ORG_ID_ARGUMENT);
         return this.requestProductObject("PATCH", `organizations/${segment}/branding`, input);
     }
+    /**
+     * The organization's webhook signing secret — `GET /v1/organizations/{org_id}/webhook-secret`:
+     * the `whsec_` secret every caller webhook of the organization is signed with, which a receiver
+     * hands to `verifyWebhook`. The platform generates it on this first read when the organization
+     * has none. Treat the answer as a credential: never log or cache it.
+     *
+     * An admin's route, from a web session only: the hosted gateway refuses an API key on it. Throws
+     * `ApiResponseError`: `403` `auth.forbidden` whose `params.requirement` names `admin` for any
+     * other role, `403` `pipelex.org.mismatch` for an organization other than the caller's active
+     * one, and `404` `pipelex.org.not_found` for one with no record.
+     */
+    async getWebhookSecret(orgId) {
+        const segment = idPathSegment(orgId, "getWebhookSecret", ORG_ID_ARGUMENT);
+        return this.requestProductObject("GET", `organizations/${segment}/webhook-secret`);
+    }
+    /**
+     * Rotate the organization's webhook signing secret — `POST
+     * /v1/organizations/{org_id}/webhook-secret/rotate`: a new secret is current at once, and the
+     * one it replaces keeps signing beside it for 24 hours, then is dropped, so a receiver has a day
+     * to take the new one. An organization with no secret yet gets its first. Answers the new secret,
+     * as `getWebhookSecret` does, with its guards and refusals.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header. The answer carries a secret,
+     * so the platform never replays it: the same key sent again is refused `409`
+     * `request.already_executed` and rotates nothing more, and the secret is then read with
+     * `getWebhookSecret`. A malformed key is a `RequestArgumentError` before anything is sent.
+     */
+    async rotateWebhookSecret(orgId, options = {}) {
+        const endpoint = `organizations/${idPathSegment(orgId, "rotateWebhookSecret", ORG_ID_ARGUMENT)}/webhook-secret/rotate`;
+        const idempotencyKey = idempotencyKeyOf(options, "rotate the secret");
+        const res = await this.requestProductAnswer("POST", endpoint, undefined, { idempotencyKey });
+        return this.readObjectAnswer("POST", endpoint, res);
+    }
     /** The active org's subscription state — `GET /v1/billing/subscription`. */
     async getSubscription() {
         return this.requestProduct("GET", "billing/subscription");
@@ -3669,6 +3683,87 @@ export class PipelexApiClient {
         }
         return { ...rest, nextCursor };
     }
+    /**
+     * A run's caller-webhook deliveries — `GET /v1/runs/{id}/webhook-deliveries`: one per URL the
+     * run registered in `callback_urls`, in their order, once the run has ended, each with its
+     * state and every attempt, its URL redacted. A run that registered none, or has not ended, lists
+     * none. Any member of the organization reads them, by web session or API key.
+     *
+     * Throws `RequestArgumentError` for a run id that is empty, `.` or `..`, or holds a lone
+     * surrogate, before any request. Throws `ApiResponseError`: `404` `run.not_found` for a run that
+     * is not the organization's, exactly as for one that does not exist. An answer whose
+     * `deliveries` is not an array is an answer the SDK cannot read, thrown as an `ApiResponseError`
+     * too.
+     */
+    async listRunWebhookDeliveries(runId) {
+        const segment = idPathSegment(runId, "listRunWebhookDeliveries", RUN_ID_ARGUMENT);
+        const endpoint = `runs/${segment}/webhook-deliveries`;
+        const res = await this.requestProductAnswer("GET", endpoint, undefined);
+        const list = this.readObjectAnswer("GET", endpoint, res);
+        if (!Array.isArray(list.deliveries)) {
+            throw this.unreadableAnswer("GET", `/${API_PREFIX}/${endpoint}`, res, "a run's deliveries whose `deliveries` is not an array");
+        }
+        return list;
+    }
+    /**
+     * One delivery of a run's webhooks, with its event —
+     * `GET /v1/runs/{id}/webhook-deliveries/{delivery_id}`: the body its latest attempt sent, or,
+     * before any attempt, the body its first attempt will send. Every attempt and replay of the
+     * delivery sends that body, only its `attempt` changing, so the event matches what a receiver
+     * logged only once an attempt was made: it then equals, as JSON, the body that attempt brought
+     * the receiver. Compare the two as parsed JSON values, never as text: the read promises the same
+     * value, not the same bytes.
+     * `deliveryId` is the delivery's `delivery_id`, the receiver's `webhook-id`.
+     *
+     * Throws `RequestArgumentError` for an id that is empty, `.` or `..`, or holds a lone surrogate,
+     * before any request. Throws `ApiResponseError`: `404` `run.not_found` for a run the caller
+     * cannot read, and `422` `request.invalid` naming `delivery_id` for a delivery the run does not
+     * have.
+     */
+    async getRunWebhookDelivery(runId, deliveryId) {
+        const call = "getRunWebhookDelivery";
+        const run = idPathSegment(runId, call, RUN_ID_ARGUMENT);
+        const delivery = idPathSegment(deliveryId, call, DELIVERY_ID_ARGUMENT);
+        return this.requestProductObject("GET", `runs/${run}/webhook-deliveries/${delivery}`);
+    }
+    /**
+     * Send a settled delivery again — `POST /v1/runs/{id}/webhook-deliveries/{delivery_id}/replay`:
+     * one new attempt under the same `webhook-id`, with the same `data`, the next `attempt`, a fresh
+     * timestamp, and the signatures of the secrets live when it is sent. A replay the receiver
+     * accepts marks the delivery `delivered`; one it does not leaves its state as it was, and the
+     * attempt is recorded either way. A replay never returns a delivery to `pending`. Anyone who
+     * can read the run asks for one, an API key included, under the organization's replay rate.
+     *
+     * Answers the attempt number the replay is sent under; a replay asked again before it is sent is
+     * that same attempt.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header, and nothing is sent when it
+     * is absent or `null`. The platform stores the replay's answer under the key, so the same replay
+     * sent again under the same key, as after an answer lost to a time limit, gets the stored answer,
+     * naming the same attempt, and the delivery is not sent twice. A key reused for another request
+     * is refused `409` `request.idempotency_conflict`, and one whose earlier request is still being
+     * handled `409` `request.idempotency_key_in_use`, whose `retry` is `yes`: send it again under the
+     * same key after its `retry_after`. See `WebhookReplayOptions`.
+     *
+     * Throws `RequestArgumentError` for an id that is empty, `.` or `..`, or holds a lone surrogate,
+     * or for an idempotency key that is not 1 to 255 visible ASCII characters, before any request.
+     * Throws `ApiResponseError`: `404` `run.not_found` for a run the caller cannot read; `422`
+     * `request.invalid` naming `delivery_id` for a delivery the run does not have; `409`
+     * `pipelex.org.not_manageable` with the reason `webhook_delivery_pending` for a delivery still on
+     * its retry schedule, or `webhook_delivery_attempts_exhausted` for one holding the most attempts
+     * a delivery holds; `429` `account.rate_limited`, with its `retry_after`, past the
+     * organization's replay rate; and a `500` or `503` when the replay could not be queued, which
+     * then counts nothing against the rate.
+     */
+    async replayRunWebhookDelivery(runId, deliveryId, options = {}) {
+        const call = "replayRunWebhookDelivery";
+        const run = idPathSegment(runId, call, RUN_ID_ARGUMENT);
+        const delivery = idPathSegment(deliveryId, call, DELIVERY_ID_ARGUMENT);
+        const endpoint = `runs/${run}/webhook-deliveries/${delivery}/replay`;
+        const idempotencyKey = idempotencyKeyOf(options, "replay the delivery");
+        const res = await this.requestProductAnswer("POST", endpoint, undefined, { idempotencyKey });
+        return this.readObjectAnswer("POST", endpoint, res);
+    }
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
     async updateRun(runId, input) {
         const segment = idPathSegment(runId, "updateRun", RUN_ID_ARGUMENT);
@@ -3685,6 +3780,8 @@ export class PipelexApiClient {
         const extensions = buildExtensions(options.extra);
         const api = buildApiRunExtensions(options);
         const hosted = buildHostedRunExtensions(options);
+        // Not a run source, so outside `api`, whose size the precondition below reads.
+        const webhooks = buildCallbackUrls(call, options);
         const forms = protocolTreeForms(call, options);
         const treeForms = treeFormsGiven(forms);
         if (!options.pipe_code &&
@@ -3696,13 +3793,13 @@ export class PipelexApiClient {
         }
         assertMethodRefPairsWithNothing(options, treeForms);
         assertLinkageMethodIdIsBare(options, treeForms);
-        return { forms, extensions, api, hosted };
+        return { forms, extensions, api, hosted, webhooks };
     }
     /**
      * Blocking `POST /v1/execute` adapted onto `RunResults` — the bare-runner
      * path. Forwards every protocol field PLUS every extension surface: the
-     * runner-resolved `method_ref`, the hosted `method_id`, and the generic
-     * `extra` passthrough. An extension-only call (`{ extra }` with no
+     * runner-resolved `method_ref`, the run's `callback_urls`, the hosted
+     * `method_id`, and the generic `extra` passthrough. An extension-only call (`{ extra }` with no
      * pipe_code/bundle) or a vendor selector riding `extra` must survive this
      * path, not just the durable one — a `method_ref` run must run the same
      * fetched package here, and a hosted `method_id` must reach the server too,
@@ -3724,6 +3821,8 @@ export class PipelexApiClient {
             tree: options.tree ?? undefined,
             files: options.files ?? undefined,
             method_ref: options.method_ref ?? undefined,
+            // A runner calls the run's webhooks once the blocking run has ended, as the platform does.
+            callback_urls: options.callback_urls ?? undefined,
             method_id: options.method_id ?? undefined,
             extra: options.extra ?? undefined,
         }, signal, sending);
@@ -3798,12 +3897,12 @@ const PROTOCOL_REQUEST_KEYS = [
     "dynamic_output_concept_ref",
     "files",
 ];
-// The PIPELEX API's own request field — the layer-2 extension the runner reads
-// 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 check.
-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 `callback_urls`, the
+// webhooks to call once the run has ended. 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 its checks.
+const PIPELEX_API_REQUEST_KEYS = ["method_ref", "callback_urls"];
 // 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
@@ -3906,6 +4005,7 @@ function runRequestBody(call, options, files, parts) {
             : options.dynamic_output_concept_ref,
         files: files ?? undefined,
         ...parts.api,
+        ...parts.webhooks,
         ...parts.hosted,
         ...parts.extensions,
     };
@@ -3986,6 +4086,29 @@ function buildApiRunExtensions(options) {
     const methodRef = nonEmptyString(options.method_ref);
     return methodRef === undefined ? {} : { method_ref: methodRef };
 }
+/**
+ * Copy a run's `callback_urls` onto the wire body, `call` naming the caller's method in a refusal.
+ * An absent, `null` or empty list yields an empty object, so the key is not sent, as the platform
+ * treats an empty list as absent. A value that is not an array, or an array holding anything but
+ * strings, is refused before anything is sent; the URLs themselves are the server's to judge,
+ * since the hosted API and a self-hosted runner each hold them to their own rules. The Python SDK
+ * reads the argument the same way.
+ */
+function buildCallbackUrls(call, options) {
+    const urls = options.callback_urls;
+    if (urls == null)
+        return {};
+    if (!Array.isArray(urls)) {
+        throw new RequestArgumentError(`${call}() takes callback_urls as an array of URLs; got ${typeof urls}.`, { problem: argumentInvalidProblem("callback_urls", "not_a_list") });
+    }
+    const copy = [...urls];
+    if (copy.some((url) => typeof url !== "string")) {
+        throw new RequestArgumentError(`${call}() takes each of callback_urls as a string URL.`, {
+            problem: argumentInvalidProblem("callback_urls", "not_a_string"),
+        });
+    }
+    return copy.length === 0 ? {} : { callback_urls: copy };
+}
 /**
  * Copy the hosted API's own run arguments onto the wire body. Named options,
  * not `extra` entries — see `PipelexHostedRunExtensions`.
@@ -4108,9 +4231,9 @@ function nonEmptyString(value) {
 /** The request header the hosted API reads a request'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
+ * The longest idempotency key a request 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.
+ * exceed, so that the request would run without the protection the key was sent for.
  */
 const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
 /**
@@ -4120,13 +4243,14 @@ const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
  */
 const VISIBLE_ASCII = /^[\x21-\x7E]+$/;
 /**
- * The idempotency key a start or a method copy 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 request sent
- * without the key its caller gave would lose the protection the caller asked for without a word.
- * `request` says what the request does, as the refusal's last sentence names it ("start the run",
- * "copy the method"). 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.
+ * The idempotency key a start, a method copy, a secret rotation or a delivery replay 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 request sent without the key its caller gave would lose the
+ * protection the caller asked for without a word. `request` says what the request does, as the
+ * refusal's last sentence names it ("start the run", "copy the method", "rotate the secret",
+ * "replay the delivery"). 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, request = "start the run") {
     const key = options.idempotencyKey;