@pipelex/sdk 0.17.0 → 0.18.0

package/README.md

@@ -10,6 +10,8 @@ Early. `PipelexApiClient` implements the MTHDS protocol-execution routes (`execu
 
 Besides the client, the package exports `runCodegenCheck` — a **pure** offline check that verifies a committed `codegen()` tree still matches its `codegen.lock`. It needs no server, no key, and no client instance, so it fits a CI job. See [`docs/crate-routes.md`](./docs/crate-routes.md#the-offline-check--runcodegencheck).
 
+It also exports `summarizeUsage`, which folds a completed run's usage records into one null-aware summary — total cost, input and output tokens, and a per-pipe rollup — without any I/O. See [`docs/run-usage.md`](./docs/run-usage.md#summarizing-a-run--summarizeusage).
+
 ## Install
 
 ```bash
@@ -32,8 +34,8 @@ const report = await client.validate(["domain = 'demo'"]);
 if (report.is_valid) {
   // Run it and wait for the result (durable start + poll on the hosted API).
   const result = await client.startAndWaitForResult({ pipe_code: "demo.greet" });
-  // Every completed run delivers a resolved `main_stuff` (the full working memory
-  // also rides `pipe_output` on the blocking path).
+  // Every completed run delivers a resolved `main_stuff`, and every named stuff of
+  // the run in `working_memory`.
   console.log(result.main_stuff);
 }
 

package/dist/artifacts.d.ts

@@ -0,0 +1,284 @@
+/**
+ * The artifact stack — the download twin of `prepareInputs`, in layers so each
+ * operation is usable without the next:
+ *
+ * - {@link collectArtifacts} — a pure walk of any JSON value for the strings that
+ *   ARE `pipelex-storage://` references. No network, no key.
+ * - {@link resolveArtifacts} — the platform's bulk resolve route over a whole
+ *   list, chunked at the route's bound, one verdict per reference.
+ * - {@link fetchArtifact} — a bounded `Response` for one reference: resolved
+ *   fresh, timed out, redirects refused, the byte cap enforced mid-stream, no
+ *   credentials forwarded, headers untouched.
+ * - {@link downloadArtifacts} — Node-only: a run's produced files saved under a
+ *   directory by a bounded pool of workers, as a produced verdict.
+ *
+ * A produced file is never embedded in a run's results: the content carries its
+ * durable `pipelex-storage://` reference beside a signed `public_url` that expires
+ * on the provider's schedule. Nothing here reads that embedded link — every link
+ * is minted fresh by the platform, and re-minted when it has expired by the time a
+ * worker reaches it. See `docs/artifact-download.md`.
+ *
+ * `node:fs/promises`, `node:path` and `undici` are imported dynamically, behind
+ * `isNodeRuntime()`, so the module's static import graph stays free of Node
+ * builtins: `collectArtifacts` and `resolveArtifacts` run anywhere, `fetchArtifact`
+ * runs anywhere the global `fetch` does (the dispatcher is a Node refinement), and
+ * only `downloadArtifacts` touches a filesystem.
+ */
+import type { RunResults, RunResultState } from "./runs.js";
+/** The scheme of a durable storage reference. */
+export declare const PIPELEX_STORAGE_SCHEME = "pipelex-storage://";
+/**
+ * How many references one bulk resolve request takes — the route's bound, fixed
+ * by the platform contract rather than configured per deployment. A longer list
+ * is a `422`, so {@link resolveArtifacts} chunks at this size.
+ */
+export declare const BULK_RESOLVE_MAX_URIS = 100;
+/**
+ * The per-file byte cap. An accident guard against filling a disk from a
+ * runaway output, not a judgment about artifact size: a produced file is
+ * server-side, so a caller cannot shrink it the way they can shrink an upload.
+ */
+export declare const DEFAULT_ARTIFACT_MAX_BYTES: number;
+/** The per-file budget for connecting, receiving the headers and reading the body. */
+export declare const DEFAULT_ARTIFACT_TIMEOUT_MS = 120000;
+/** The cap on the bytes one `downloadArtifacts` call writes in total. */
+export declare const DEFAULT_DOWNLOAD_MAX_TOTAL_BYTES: number;
+/** How many artifacts one `downloadArtifacts` call has in flight at once. */
+export declare const DEFAULT_DOWNLOAD_CONCURRENCY = 4;
+/**
+ * Why one reference failed — a value, never a thrown error. `code` is the
+ * resolve route's own per-reference code (`invalid_storage_uri`, `forbidden`)
+ * or one of the fetch boundary's (see `ArtifactFetchError`), plus the download's
+ * own `resolve_failed`, `total_limit_exceeded`, `write_failed` and `aborted`.
+ * `detail` is the sentence a person reads.
+ */
+export interface ArtifactItemError {
+    code: string;
+    detail: string;
+}
+/**
+ * One reference's resolution — the bulk resolve route's item, verbatim. Either
+ * the link fields are set and `error` is null, or `error` is set and the three
+ * link fields are null. A consumer branches on `error`, never on an HTTP status:
+ * the request was a `200` whenever every reference got a verdict.
+ */
+export type ResolvedArtifact = {
+    /** The reference exactly as sent. */
+    uri: string;
+    /** A presigned link, fetchable now and for about fifteen minutes. */
+    url: string;
+    /** UTC expiry of the link, ISO 8601. */
+    expires_at: string;
+    /** The platform's content-type guess from the reference's extension; null when it has none. */
+    content_type: string | null;
+    error: null;
+} | {
+    uri: string;
+    url: null;
+    expires_at: null;
+    content_type: null;
+    error: ArtifactItemError;
+};
+/** The wire request of `POST /v1/resolve-storage-url/bulk` — at most {@link BULK_RESOLVE_MAX_URIS} references. */
+export interface BulkResolveStorageUrlsInput {
+    uris: string[];
+}
+/** The wire response of `POST /v1/resolve-storage-url/bulk` — one item per requested reference, in request order. */
+export interface BulkResolvedStorageUrls {
+    items: ResolvedArtifact[];
+}
+/** The bounds `fetchArtifact` applies. Every one has a safe default. */
+export interface FetchArtifactOptions {
+    /** Refuse (before a byte is written) and cut (mid-stream) a body over this many bytes. Default 1 GiB. */
+    maxBytes?: number;
+    /** Budget for the whole exchange — connect, headers and body. Default 120 s. */
+    timeoutMs?: number;
+    /**
+     * Accept a plain `http:` link. Off by default: a general-purpose library does
+     * not fetch over plain http silently. The local compose stack's object store
+     * hands out such links, which is the case this opts into.
+     */
+    allowHttp?: boolean;
+    /** Cancels the fetch; a body being read is cancelled too. */
+    signal?: AbortSignal;
+}
+/** Which of a run's artifacts `downloadArtifacts` walks for references. */
+export type ArtifactScope = "main_stuff" | "working_memory";
+/** The options shared by both forms of a `downloadArtifacts` request. */
+export interface DownloadArtifactsOptions extends FetchArtifactOptions {
+    /** The directory to save under, created if missing. Files are never overwritten. */
+    dir: string;
+    /**
+     * `main_stuff` (the default) walks the run's main output. `working_memory` is
+     * the opt-in that also brings down the echoed inputs and every intermediate.
+     */
+    scope?: ArtifactScope;
+    /** How many artifacts are in flight at once. Default 4. */
+    concurrency?: number;
+    /**
+     * Cap on the bytes written by the whole call. Default 4 GiB. The item that would
+     * cross it is an item error, and the items not yet started are skipped with the
+     * same reason.
+     */
+    maxTotalBytes?: number;
+}
+/**
+ * What `downloadArtifacts` takes: the options plus exactly one of `run_id` (the
+ * results are re-read, so this works days after the run) or `results` (a
+ * `RunResults` already in hand, read as it is). The type pins the other to
+ * `never`, so naming both is a compile error.
+ */
+export type DownloadArtifactsRequest = DownloadArtifactsOptions & ({
+    run_id: string;
+    results?: never;
+} | {
+    results: RunResults;
+    run_id?: never;
+});
+/**
+ * One reference's outcome in a download verdict — one shape with nullable fields,
+ * like {@link ResolvedArtifact}: either `path` and `size` are set and `error` is
+ * null, or `error` is set and both are null. `content_type` is the platform's
+ * guess from the reference's extension, known before the fetch, on both arms.
+ */
+export type DownloadedArtifact = {
+    uri: string;
+    /** Absolute path of the written file. */
+    path: string;
+    content_type: string | null;
+    /** Bytes written. */
+    size: number;
+    error: null;
+} | {
+    uri: string;
+    path: null;
+    content_type: string | null;
+    size: null;
+    error: ArtifactItemError;
+};
+/**
+ * The produced verdict of `downloadArtifacts`. `artifacts.length` is the count
+ * of references walked, errors included; an empty list over a present scope is
+ * a verdict ("this output references no stored file"), not an error.
+ */
+export interface DownloadArtifactsResult {
+    scope: ArtifactScope;
+    /** One entry per reference, in discovery order. */
+    artifacts: DownloadedArtifact[];
+    /** The absolute paths of the files saved, in the same order. */
+    saved_paths: string[];
+    /** True when every walked reference was saved — vacuously true for an empty walk. */
+    all_saved: boolean;
+    /** Present, and true, only when the caller's `signal` aborted the call. */
+    aborted?: true;
+}
+/**
+ * The client surface the artifact operations need: the raw bulk resolve call and
+ * the single-shot result lookup. Typed as the client's own signatures so
+ * `PipelexApiClient` satisfies it structurally, and so tests inject a fake.
+ */
+export interface ArtifactCapableClient {
+    resolveStorageUrls(input: BulkResolveStorageUrlsInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<BulkResolvedStorageUrls>;
+    getRunResult(runId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RunResultState>;
+}
+/**
+ * Every `pipelex-storage://` reference inside a JSON-shaped value, deduplicated,
+ * in discovery order. A string counts only when it IS a reference — the whole
+ * string, scheme first, with something after the scheme; text that merely
+ * contains one does not. The scheme is unambiguous, so this walk is a contract
+ * rather than a heuristic: the runtime serializes a produced image or document
+ * as content carrying its reference in `url`, beside an expiring `public_url`
+ * this walk ignores. Pure — no network, no key — so a consumer can count or
+ * list a run's produced files without resolving any of them.
+ */
+export declare function collectArtifacts(value: unknown): string[];
+/** A string that is a storage reference: the scheme, then at least one character. */
+export declare function isStorageReference(value: string): boolean;
+/**
+ * The bare filename a storage reference is saved under: the last segment of the
+ * storage key, reduced to a conservative character set so it can never name
+ * anything but a regular file directly inside the target directory. Path
+ * separators are the split point, so no traversal survives; leading dots are
+ * stripped, so no hidden file and no `..`; everything outside `[A-Za-z0-9._-]`
+ * becomes `_`; an empty result falls back to a numbered `artifact-N`. Length is
+ * capped with the extension preserved, and an extension is added from the
+ * content type when the key carries none. A collision on disk is not this
+ * function's concern: `downloadArtifacts` suffixes the stem (`name-1.ext`) on
+ * exclusive creation, so a file is never overwritten.
+ */
+export declare function artifactFilename(uri: string, contentType: string | null | undefined, index: number): string;
+/**
+ * Resolve a list of references through the bulk route, chunked at
+ * {@link BULK_RESOLVE_MAX_URIS} per request, and answer one
+ * {@link ResolvedArtifact} per reference in request order, duplicates included.
+ * Per-reference failure is a value on the item; only what is not about a
+ * reference throws — the route's whole-request refusals as `ApiResponseError`
+ * (a caller with no organization, a malformed request, a signing failure, or a
+ * `404` from a deployment that does not serve the route) and an unreachable
+ * host as `ApiUnreachableError`. An empty list resolves to an empty list with
+ * no request made.
+ */
+export declare function resolveArtifacts(client: Pick<ArtifactCapableClient, "resolveStorageUrls">, uris: string[], options?: {
+    signal?: AbortSignal;
+}): Promise<ResolvedArtifact[]>;
+/**
+ * A bounded `Response` for one reference: the link is minted fresh through the
+ * bulk route, then fetched with `redirect: "manual"` (a presigned link has no
+ * reason to redirect, and one that does is refused rather than followed), no
+ * headers of ours (the link carries its own authorization in the query string,
+ * and nothing must ride along to the object store), a budget covering the
+ * headers and the body, and a byte cap checked against `Content-Length` before
+ * a byte is read and again on every chunk. The status, status text and headers
+ * are the store's own, except that a `Content-Encoding` the fetch already decoded
+ * is dropped with the encoded `Content-Length`: a proxy relaying this response sets its own
+ * `Content-Disposition`, `X-Content-Type-Options`, CSP and caching headers,
+ * because this function does not.
+ *
+ * Only a `2xx` is returned. Anything else is thrown as `ArtifactFetchError`
+ * with a `code` (a redirect, a refused or vanished object, a store fault, a
+ * declared oversize, a timeout, a network fault, an unusable link, or the
+ * route's own per-reference refusal); a body that crosses the cap mid-stream
+ * errors the returned stream with the same error type (`too_large`). The
+ * caller's abort propagates as-is. Whole-request failures of the resolve step
+ * propagate unchanged (`ApiResponseError`, `ApiUnreachableError`).
+ */
+export declare function fetchArtifact(client: Pick<ArtifactCapableClient, "resolveStorageUrls">, uri: string, options?: FetchArtifactOptions): Promise<Response>;
+/** The write side of a streamed download: what {@link writeFully} needs of a `FileHandle`. */
+export interface ChunkWriter {
+    write(buffer: Uint8Array, offset: number, length: number): Promise<{
+        bytesWritten: number;
+    }>;
+}
+/**
+ * Write the whole chunk, looping on short writes. `FileHandle.write()` resolves
+ * with the count it managed, which can fall short of the chunk on a filesystem
+ * under pressure; taking one call as "written" would report a truncated file
+ * as saved.
+ */
+export declare function writeFully(writer: ChunkWriter, chunk: Uint8Array): Promise<void>;
+/**
+ * Save a run's produced files under `dir` — Node-only, like the path-string arm
+ * of `uploadFile`. Takes a `run_id` (the results are re-read, so a run is
+ * downloadable days later) or a `RunResults` in hand; walks the requested scope
+ * with {@link collectArtifacts}; resolves the whole set through the bulk route
+ * ahead of the workers; then a bounded pool of workers each fetch → open with
+ * `wx` → write, re-resolving any link that has expired by the time a worker
+ * reaches it. The embedded `public_url` is never used. Files are named by
+ * {@link artifactFilename} and never overwritten; a failed or aborted download
+ * unlinks its partial file.
+ *
+ * Returns a produced verdict: one entry per reference, errors as values. It
+ * throws only when no verdict can be produced — `RunStillRunningError` or
+ * `RunFailedError` for a run that has not completed, `ScopeUnavailableError`
+ * when the scope's artifact is null or missing, `ArtifactAuthenticationError`
+ * (carrying the verdict so far) when the resolve route refuses the credential,
+ * `ArtifactOperationError` outside Node or for an unusable `dir`, and the
+ * transport and lifecycle errors of the reads it makes (`ApiResponseError` for
+ * a deployment without the bulk route, `RunLifecycleUnavailableError` for a
+ * bare runner asked by id, `ApiUnreachableError`).
+ */
+export declare function downloadArtifacts(client: ArtifactCapableClient, request: DownloadArtifactsRequest): Promise<DownloadArtifactsResult>;