@instruments/materialgraph 0.1.0 → 0.3.0

package/run-types.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Hand-mirrored wire types for the MaterialGraph public Run + source-material
+ * surface (spec 0.7.0). Like {@link ./types.ts}, these interfaces carry NO
+ * runtime dependency on any `@materialgraph/*` package — they mirror the shapes
+ * in `apps/web/public/openapi.yaml` (`list_public_capabilities`,
+ * `create_public_run`, `get_public_run`, `list_public_run_events`,
+ * `resume_public_run`, `cancel_public_run`, `upload_source_material`).
+ *
+ * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
+ * so a new server value still type-checks, and objects are read structurally —
+ * unknown keys pass through untouched.
+ */
+import type { JsonValue, OpenEnum } from "./types.js";
+/**
+ * A file to upload. Two forms so the SDK is ergonomic on BOTH Node route
+ * handlers and modern runtimes: pass a platform `Blob`/`File` directly, or the
+ * bytes plus a filename. The SDK builds the multipart body internally — callers
+ * never touch `FormData` or wrestle a `string`-typed binary field.
+ */
+export type FileInput = Blob | {
+    /** Raw file bytes. */
+    data: Uint8Array | ArrayBuffer;
+    /** Filename recorded on the multipart part (drives the stored receipt filename). */
+    filename: string;
+    /** Optional MIME type; the server re-validates by magic bytes regardless. */
+    contentType?: string;
+};
+/**
+ * A heterogeneous pile of source files (multipart field `files`, repeatable):
+ * any mix of PDF, plain-text/markdown, and images (≥1, ≤16). The server
+ * classifies each file and assigns its receipt {@link SourceMaterialReceiptFile.role};
+ * the caller no longer pre-sorts a brief from its references.
+ */
+export interface UploadSourceMaterialFilesInput {
+    files: FileInput[];
+}
+/**
+ * The legacy pre-classified shape — a single PDF `brief` plus optional image
+ * `references` (multipart fields `brief` + `references`). Still accepted by the
+ * server, folded into the pile. Prefer {@link UploadSourceMaterialFilesInput}.
+ */
+export interface UploadSourceMaterialLegacyInput {
+    /** The single PDF brief for the batch (multipart field `brief`). */
+    brief: FileInput;
+    /** Up to 12 reference images (multipart field `references`, repeatable). */
+    references?: FileInput[];
+}
+/**
+ * Input for {@link MaterialGraphClient.uploadSourceMaterial} — either the
+ * pile-of-files shape or the legacy brief+references shape.
+ */
+export type UploadSourceMaterialInput = UploadSourceMaterialFilesInput | UploadSourceMaterialLegacyInput;
+/** One stored file in an upload receipt. */
+export interface SourceMaterialReceiptFile {
+    /** The stored file id (`smf_…`). */
+    sourceId: string;
+    /**
+     * The pipeline-assigned role. The vocabulary grows over time; {@link OpenEnum}
+     * keeps a newer server value type-checking. `unclassified` is a legitimate
+     * terminal value when the pipeline could not place the file.
+     */
+    role: OpenEnum<"brief" | "reference_image" | "document" | "document_image" | "inspiration_image" | "unclassified">;
+    filename: string;
+    mediaType: string;
+    /** Lowercase hex SHA-256 of the stored bytes. */
+    sha256: string;
+    bytes: number;
+    /** PDF page count; null for images. */
+    pages: number | null;
+}
+/** The `201` receipt from `POST /api/v1/source-material`. */
+export interface SourceMaterialBatchReceipt {
+    /** The stored batch id (`smb_…`). */
+    batchId: string;
+    sources: SourceMaterialReceiptFile[];
+}
+/**
+ * One analysis computed over an uploaded image's bytes.
+ *
+ * Analyses are CONTENT-ADDRESSED: keyed by the file's SHA-256, not by the
+ * upload or the uploading key. Re-uploading an image someone has already
+ * analysed therefore returns that analysis immediately, with no work. That
+ * sharing is by design and discloses nothing — you only ever see analyses of
+ * images you hold yourself.
+ */
+export interface SourceImageAnalysis {
+    /** The kind of read. {@link OpenEnum} keeps a newer server value type-checking. */
+    kind: OpenEnum<"scene_match">;
+    /** The model version that produced {@link SourceImageAnalysis.result}. */
+    model: string;
+    /**
+     * `failed` analyses are RETURNED, not hidden — so "we looked and it did not
+     * work" is distinguishable from "nobody has looked yet", which is an empty
+     * {@link SourceMaterialBatchFile.analyses}.
+     */
+    status: OpenEnum<"ok" | "failed">;
+    /**
+     * The payload verbatim, or the failure record when `status` is `failed`. For
+     * `scene_match`: the detected regions with their candidate variant ids and
+     * scores. The interior shape belongs to the producing model and may gain
+     * fields, so it is typed as JSON rather than pinned here.
+     */
+    result: Record<string, JsonValue>;
+    /** ISO-8601 timestamp of the most recent analysis. */
+    analysedAt: string;
+}
+/** One file as `GET /api/v1/source-material/{batchId}` returns it. */
+export interface SourceMaterialBatchFile extends SourceMaterialReceiptFile {
+    /** Fetchable URL for the stored bytes. */
+    url: string;
+    /**
+     * ALWAYS an array. `[]` means nothing has been computed yet — never a missing
+     * field. Preprocessing is triggered manually today; when it becomes automatic
+     * only the trigger changes and this contract does not.
+     */
+    analyses: SourceImageAnalysis[];
+}
+/**
+ * The `200` body of `GET /api/v1/source-material/{batchId}` — the batch, every
+ * file it holds, and the analyses computed over each file's bytes.
+ */
+export interface SourceMaterialBatchDetail {
+    /** The stored batch id (`smb_…`). */
+    batchId: string;
+    /** ISO-8601 timestamp of the upload. */
+    createdAt: string;
+    sources: SourceMaterialBatchFile[];
+}
+export type CapabilityKind = OpenEnum<"agent" | "tool" | "workflow">;
+export type CapabilityExposure = OpenEnum<"public" | "partner" | "internal">;
+export type CapabilityScope = OpenEnum<"mg:read" | "mg:write" | "mg:ingest" | "mg:admin">;
+export type CapabilitySideEffectClass = OpenEnum<"read_only" | "browser_local" | "external_read" | "writes_proposed" | "writes_persisted" | "planned_only">;
+export interface CapabilityRetryPolicy {
+    maxAttempts: number;
+    backoff: OpenEnum<"none" | "fixed" | "exponential">;
+}
+export interface CapabilityInvokeLink {
+    href: string;
+    method: OpenEnum<"GET" | "POST">;
+}
+/** One invocable capability from the governed public manifest. */
+export interface PublicCapabilityMetadata {
+    publicId: string;
+    runtimeId: string;
+    kind: CapabilityKind;
+    exposure: CapabilityExposure;
+    name: string;
+    description: string;
+    schemas: {
+        input: Record<string, unknown>;
+        output: Record<string, unknown>;
+    };
+    sideEffectClass: CapabilitySideEffectClass;
+    scopes: CapabilityScope[];
+    timeoutMs: number;
+    retryPolicy: CapabilityRetryPolicy;
+    tags: string[];
+    links: {
+        invoke: CapabilityInvokeLink;
+    };
+}
+/** The `GET /api/v1/capabilities` response envelope. */
+export interface CapabilityManifestResponse {
+    capabilities: PublicCapabilityMetadata[];
+}
+export type PublicRunStatus = OpenEnum<"queued" | "claimed" | "running" | "suspended" | "succeeded" | "failed" | "canceled">;
+export interface PublicRunFailure {
+    code: string;
+    message: string;
+    retryable: boolean;
+    detail?: Record<string, unknown>;
+}
+export interface PublicRunArtifactRef {
+    kind: string;
+    ref: string;
+}
+/**
+ * The caller-owned, redacted Run ledger record. Prompts, raw model messages,
+ * reasoning, credentials, provider payloads, and source-document contents are
+ * never returned — inputs and outputs are the `redacted*Json` projections.
+ */
+export interface PublicRun {
+    id: string;
+    capabilityKind: CapabilityKind;
+    capabilityId: string;
+    clientReference: string | null;
+    status: PublicRunStatus;
+    redactedInputJson: Record<string, unknown>;
+    redactedOutputJson: Record<string, unknown> | null;
+    usageJson: Record<string, unknown> | null;
+    artifactRefs: PublicRunArtifactRef[] | null;
+    failureJson: PublicRunFailure | null;
+    suspensionStepId: string | null;
+    eventCursor: number;
+    attempts: number;
+    startedAt: string | null;
+    cancellationRequestedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Body for `POST /api/v1/runs` ({@link MaterialGraphClient.createRun}). */
+export interface CreatePublicRunRequest {
+    capabilityKind: CapabilityKind;
+    capabilityId: string;
+    /** The capability input, validated server-side against its live input schema. */
+    inputJson: unknown;
+    /** Stable caller key making Run creation idempotent across retries. */
+    idempotencyKey?: string;
+    /** Free-form caller correlation reference, echoed back on the Run. */
+    clientReference?: string;
+}
+/** The `POST /api/v1/runs` response (`200` replay or `202` accepted). */
+export interface CreatePublicRunResponse {
+    accepted: boolean;
+    replayed: boolean;
+    workflowRunId: string;
+    run: PublicRun;
+}
+/** The `GET /api/v1/runs/{runId}` and resume/cancel response envelope. */
+export interface PublicRunResponse {
+    run: PublicRun;
+}
+/** Body for `POST /api/v1/runs/{runId}/resume`. */
+export interface ResumePublicRunRequest {
+    /** The resume payload, validated against the suspended step's resume schema. */
+    resumeData: unknown;
+}
+/**
+ * One redacted Run event, decoded from an SSE `data:` frame. The stream yields
+ * these in ascending {@link RunEvent.sequence} order. `payloadJson` is read
+ * structurally; use {@link parseRunEvent} to narrow the composition family.
+ */
+export interface RunEvent {
+    sequence: number;
+    type: string;
+    payloadJson: unknown;
+}
+/** Run event types that close the stream — a terminal event ends a drain. */
+export declare const TERMINAL_RUN_EVENT_TYPES: ReadonlySet<string>;
+/** Options for {@link MaterialGraphClient.streamRunEvents}. */
+export interface StreamRunEventsOptions {
+    /** Resume the stream after this sequence (exclusive). Omitted starts at 0. */
+    after?: number;
+    /** Abort the stream; iteration stops cleanly. */
+    signal?: AbortSignal;
+}
+/** Options for {@link MaterialGraphClient.drainRunEvents}. */
+export interface DrainRunEventsOptions {
+    /** Resume after this sequence (exclusive). */
+    after?: number;
+    /** Stop collecting after this many milliseconds even without a terminal event. */
+    deadlineMs: number;
+}
+/** Options for {@link MaterialGraphClient.resumeRun}. */
+export interface ResumeRunOptions {
+    /**
+     * The step the caller believes is suspended. When it mismatches the run
+     * doc's live `suspensionStepId` the API answers RFC-7807 409 (MG-608) —
+     * which is what stops a stale client resuming a step the run has already
+     * moved past. Omitted, the resume is unguarded, exactly as before.
+     */
+    stepId?: string;
+    /** Abort the request. */
+    signal?: AbortSignal;
+}

package/run-types.js

@@ -0,0 +1,6 @@
+/** Run event types that close the stream — a terminal event ends a drain. */
+export const TERMINAL_RUN_EVENT_TYPES = new Set([
+    "succeeded",
+    "failed",
+    "canceled",
+]);

package/runs.d.ts

@@ -0,0 +1,84 @@
+import { HttpTransport } from "./http-transport.js";
+import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
+import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
+/**
+ * Upload one atomic source-material batch (`POST /api/v1/source-material`).
+ * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
+ * the legacy `{ brief, references }` shape (→ `brief` + repeatable `references`
+ * fields). Both wire to multipart the server accepts.
+ */
+export declare function uploadSourceMaterial(transport: HttpTransport, input: UploadSourceMaterialInput, signal?: AbortSignal): Promise<SourceMaterialBatchReceipt>;
+/**
+ * Read back one uploaded batch (`GET /api/v1/source-material/{batchId}`): every
+ * file with a fetchable `url`, and every analysis computed over its bytes
+ * inlined as `analyses` — always an array, `[]` when nothing has been computed.
+ *
+ * A batch you do not own is indistinguishable from one that does not exist:
+ * both raise a 404, never a 403, so batch ids cannot be probed for existence.
+ *
+ * The body is VALIDATED, not trusted: `checkSourceMaterialBatchDetail` mirrors
+ * the server's Zod contract so a malformed response fails here with a path into
+ * the payload rather than as an undefined three frames away in caller code.
+ */
+export declare function getSourceMaterialBatch(transport: HttpTransport, batchId: string, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
+/** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
+export declare function capabilities(transport: HttpTransport, signal?: AbortSignal): Promise<CapabilityManifestResponse>;
+/** Start an asynchronous capability Run (`POST /api/v1/runs`). */
+export declare function createRun(transport: HttpTransport, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
+/** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
+export declare function getRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
+/**
+ * Export a completed compose Run's scheme as a finish schedule — one row per
+ * slot, every attribute value carrying its source and verification state
+ * (`GET /api/v1/runs/{runId}/schedule`).
+ *
+ * The `.xlsx` form of the same export is deliberately NOT an SDK method: this
+ * transport parses every response as text/JSON and has no binary read path, so
+ * a bytes-returning method would mean a second transport surface for one file.
+ * Fetch `GET /api/v1/runs/{runId}/schedule.xlsx` directly with the same bearer
+ * key when you want the workbook.
+ */
+export declare function getRunSchedule(transport: HttpTransport, runId: string, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
+/**
+ * Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`).
+ *
+ * The third argument takes either an `AbortSignal` (legacy) or
+ * {@link ResumeRunOptions}.
+ *
+ * `stepId` is forwarded whenever it is PRESENT — `!== undefined`, not truthy.
+ * An empty string is a present-but-malformed value and must reach the server
+ * so its schema rejects it; treating it as absent would silently downgrade a
+ * guarded resume into an unguarded one, which is the exact failure this guard
+ * exists to prevent.
+ *
+ * Omitting it sends a body byte-identical to what this sent before. Note the
+ * wire cannot distinguish `{ stepId: undefined }` from no key at all —
+ * `JSON.stringify` drops both — so the distinction here is construction
+ * intent, kept so the serialised body is provably unchanged for old callers.
+ */
+export declare function resumeRun(transport: HttpTransport, runId: string, resumeData: unknown, signalOrOptions?: AbortSignal | ResumeRunOptions): Promise<PublicRunResponse>;
+/** Request durable Run cancellation (`POST /api/v1/runs/{runId}/cancel`). */
+export declare function cancelRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
+/**
+ * Stream ordered Run events as an async iterator (`GET
+ * /api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or
+ * `signal` aborts. One connection is bounded server-side (~25s or a terminal
+ * event); pass `after` to resume from the last observed sequence.
+ */
+export declare function streamRunEvents(transport: HttpTransport, runId: string, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent, void, unknown>;
+/**
+ * Collect Run events until a terminal event, the deadline, or the stream ends —
+ * the bounded events-log pattern the console uses. A single pass over
+ * {@link streamRunEvents}; the deadline is enforced by aborting the stream.
+ *
+ * The deadline abort is this drain's OWN, expected termination — not a failure.
+ * Where it lands decides how {@link streamRunEvents} surfaces it: mid-read it
+ * ends the iterator cleanly, but while the underlying `fetch` is still pending —
+ * the common case for a poll whose upstream has flushed no bytes yet (no new
+ * events after the cursor, so no immediate SSE frame) — it rejects with an
+ * `aborted` {@link MaterialGraphError}. Both mean the same thing here, so the
+ * self-inflicted abort is swallowed and the collected events returned. Any other
+ * failure (a real 4xx/5xx or transport error) still propagates, keeping the
+ * fail-fast surface for genuine upstream problems.
+ */
+export declare function drainRunEvents(transport: HttpTransport, runId: string, options: DrainRunEventsOptions): Promise<RunEvent[]>;

package/runs.js

@@ -0,0 +1,253 @@
+/**
+ * The Run + source-material namespace — the agentic half of the SDK. These
+ * functions take the shared {@link HttpTransport} and speak the hosted Run
+ * lifecycle: upload source material, list capabilities, create/read/resume/
+ * cancel Runs, and stream (or drain) their events. Box's proxy routes are thin
+ * wrappers over exactly these calls.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { HttpTransport } from "./http-transport.js";
+import { findSdkOperation, operationPath } from "./operations.js";
+import { checkSourceMaterialBatchDetail } from "./source-material-validation.js";
+import { readSseFrames } from "./sse.js";
+import { TERMINAL_RUN_EVENT_TYPES, } from "./run-types.js";
+function runOperation(operationId) {
+    const match = findSdkOperation(operationId);
+    if (!match)
+        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
+    return match;
+}
+/** Build a `Blob` from raw bytes, normalising to an ArrayBuffer-backed view. */
+function bytesToBlob(input) {
+    const type = input.contentType ? { type: input.contentType } : {};
+    if (input.data instanceof ArrayBuffer)
+        return new Blob([input.data], type);
+    // A Uint8Array may be SharedArrayBuffer-backed; copy into a fresh view so the
+    // Blob part is unambiguously ArrayBuffer-backed (no cast needed).
+    const copy = new Uint8Array(input.data.byteLength);
+    copy.set(input.data);
+    return new Blob([copy], type);
+}
+/** Append one file to the multipart body, from either input form. */
+function appendFile(form, field, input) {
+    if (input instanceof Blob) {
+        if (input instanceof File)
+            form.append(field, input, input.name);
+        else
+            form.append(field, input);
+        return;
+    }
+    form.append(field, bytesToBlob(input), input.filename);
+}
+/**
+ * Upload one atomic source-material batch (`POST /api/v1/source-material`).
+ * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
+ * the legacy `{ brief, references }` shape (→ `brief` + repeatable `references`
+ * fields). Both wire to multipart the server accepts.
+ */
+export async function uploadSourceMaterial(transport, input, signal) {
+    const form = new FormData();
+    if ("files" in input) {
+        for (const file of input.files)
+            appendFile(form, "files", file);
+    }
+    else {
+        appendFile(form, "brief", input.brief);
+        for (const reference of input.references ?? [])
+            appendFile(form, "references", reference);
+    }
+    const url = transport.buildUrl(operationPath(runOperation("upload_source_material")));
+    // No Content-Type header: fetch sets multipart/form-data with the boundary.
+    const { parsed } = await transport.send({
+        method: "POST",
+        url,
+        headers: transport.authHeaders(),
+        body: form,
+        signal,
+    });
+    return parsed;
+}
+/**
+ * Read back one uploaded batch (`GET /api/v1/source-material/{batchId}`): every
+ * file with a fetchable `url`, and every analysis computed over its bytes
+ * inlined as `analyses` — always an array, `[]` when nothing has been computed.
+ *
+ * A batch you do not own is indistinguishable from one that does not exist:
+ * both raise a 404, never a 403, so batch ids cannot be probed for existence.
+ *
+ * The body is VALIDATED, not trusted: `checkSourceMaterialBatchDetail` mirrors
+ * the server's Zod contract so a malformed response fails here with a path into
+ * the payload rather than as an undefined three frames away in caller code.
+ */
+export async function getSourceMaterialBatch(transport, batchId, signal) {
+    const body = await transport.requestJson(runOperation("get_source_material_batch"), {
+        pathParams: { batchId },
+        signal,
+    });
+    return checkSourceMaterialBatchDetail(body, batchId);
+}
+/** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
+export function capabilities(transport, signal) {
+    return transport.requestJson(runOperation("list_public_capabilities"), {
+        signal,
+    });
+}
+/** Start an asynchronous capability Run (`POST /api/v1/runs`). */
+export function createRun(transport, body, signal) {
+    return transport.requestJson(runOperation("create_public_run"), {
+        body,
+        signal,
+    });
+}
+/** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
+export function getRun(transport, runId, signal) {
+    return transport.requestJson(runOperation("get_public_run"), {
+        pathParams: { runId },
+        signal,
+    });
+}
+/**
+ * Export a completed compose Run's scheme as a finish schedule — one row per
+ * slot, every attribute value carrying its source and verification state
+ * (`GET /api/v1/runs/{runId}/schedule`).
+ *
+ * The `.xlsx` form of the same export is deliberately NOT an SDK method: this
+ * transport parses every response as text/JSON and has no binary read path, so
+ * a bytes-returning method would mean a second transport surface for one file.
+ * Fetch `GET /api/v1/runs/{runId}/schedule.xlsx` directly with the same bearer
+ * key when you want the workbook.
+ */
+export function getRunSchedule(transport, runId, options = {}) {
+    return transport.requestJson(runOperation("get_run_finish_schedule"), {
+        pathParams: { runId },
+        ...(options.schemeId ? { query: { schemeId: options.schemeId } } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
+/**
+ * Normalise `resumeRun`'s overloaded third argument.
+ *
+ * A bare `AbortSignal` stays supported because it is the published shape:
+ * reordering that parameter would break any consumer passing it positionally,
+ * and this ships with no version bump.
+ *
+ * Discriminated on `instanceof AbortSignal`, NOT on the presence of `stepId`.
+ * `{ signal }` with no `stepId` is a perfectly valid options object, and a
+ * key-presence test would misread it as a signal and silently drop the abort.
+ */
+function resumeOptions(value) {
+    if (value === undefined)
+        return {};
+    return value instanceof AbortSignal ? { signal: value } : value;
+}
+/**
+ * Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`).
+ *
+ * The third argument takes either an `AbortSignal` (legacy) or
+ * {@link ResumeRunOptions}.
+ *
+ * `stepId` is forwarded whenever it is PRESENT — `!== undefined`, not truthy.
+ * An empty string is a present-but-malformed value and must reach the server
+ * so its schema rejects it; treating it as absent would silently downgrade a
+ * guarded resume into an unguarded one, which is the exact failure this guard
+ * exists to prevent.
+ *
+ * Omitting it sends a body byte-identical to what this sent before. Note the
+ * wire cannot distinguish `{ stepId: undefined }` from no key at all —
+ * `JSON.stringify` drops both — so the distinction here is construction
+ * intent, kept so the serialised body is provably unchanged for old callers.
+ */
+export function resumeRun(transport, runId, resumeData, signalOrOptions) {
+    const { stepId, signal } = resumeOptions(signalOrOptions);
+    return transport.requestJson(runOperation("resume_public_run"), {
+        body: { resumeData, ...(stepId !== undefined ? { stepId } : {}) },
+        pathParams: { runId },
+        signal,
+    });
+}
+/** Request durable Run cancellation (`POST /api/v1/runs/{runId}/cancel`). */
+export function cancelRun(transport, runId, signal) {
+    return transport.requestJson(runOperation("cancel_public_run"), {
+        body: {},
+        pathParams: { runId },
+        signal,
+    });
+}
+/** Decode one SSE `data:` frame into a {@link RunEvent}, or `null` when unusable. */
+function decodeRunEvent(data) {
+    if (data.length === 0)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch (cause) {
+        throw MaterialGraphError.unexpected(`MaterialGraph run-event stream sent an unparseable data frame: ${String(cause)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const record = parsed;
+    if (typeof record.sequence !== "number" || typeof record.type !== "string")
+        return null;
+    return parsed;
+}
+/**
+ * Stream ordered Run events as an async iterator (`GET
+ * /api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or
+ * `signal` aborts. One connection is bounded server-side (~25s or a terminal
+ * event); pass `after` to resume from the last observed sequence.
+ */
+export async function* streamRunEvents(transport, runId, options = {}) {
+    const body = await transport.openStream(runOperation("list_public_run_events"), {
+        pathParams: { runId },
+        ...(options.after === undefined ? {} : { query: { after: options.after } }),
+        ...(options.signal ? { signal: options.signal } : {}),
+        accept: "text/event-stream",
+        subject: "run-event stream",
+    });
+    for await (const frame of readSseFrames(body, options.signal)) {
+        const event = decodeRunEvent(frame.data);
+        if (event)
+            yield event;
+    }
+}
+/**
+ * Collect Run events until a terminal event, the deadline, or the stream ends —
+ * the bounded events-log pattern the console uses. A single pass over
+ * {@link streamRunEvents}; the deadline is enforced by aborting the stream.
+ *
+ * The deadline abort is this drain's OWN, expected termination — not a failure.
+ * Where it lands decides how {@link streamRunEvents} surfaces it: mid-read it
+ * ends the iterator cleanly, but while the underlying `fetch` is still pending —
+ * the common case for a poll whose upstream has flushed no bytes yet (no new
+ * events after the cursor, so no immediate SSE frame) — it rejects with an
+ * `aborted` {@link MaterialGraphError}. Both mean the same thing here, so the
+ * self-inflicted abort is swallowed and the collected events returned. Any other
+ * failure (a real 4xx/5xx or transport error) still propagates, keeping the
+ * fail-fast surface for genuine upstream problems.
+ */
+export async function drainRunEvents(transport, runId, options) {
+    const collected = [];
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.deadlineMs);
+    try {
+        for await (const event of streamRunEvents(transport, runId, {
+            after: options.after,
+            signal: controller.signal,
+        })) {
+            collected.push(event);
+            if (TERMINAL_RUN_EVENT_TYPES.has(event.type))
+                break;
+        }
+    }
+    catch (error) {
+        const causedByDeadline = controller.signal.aborted && error instanceof MaterialGraphError && error.kind === "aborted";
+        if (!causedByDeadline)
+            throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+    }
+    return collected;
+}