@instruments/materialgraph 0.28.0 → 0.30.0

package/run-types.d.ts

@@ -1,8 +1,8 @@
 /**
- * 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` (`create_public_run`, `get_public_run`,
+ * Hand-mirrored wire types for the MaterialGraph workflow Run + source-material
+ * surface. Like {@link ./types.ts}, these interfaces carry NO runtime
+ * dependency on any `@materialgraph/*` package — they mirror the shapes in
+ * `apps/web/public/openapi.yaml` (`create_public_run`, `get_public_run`,
  * `list_public_run_events`, `upload_source_material`).
  *
  * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
@@ -10,7 +10,7 @@
  * unknown keys pass through untouched.
  */
 import type { BatchId, RunId, SourceFileId } from "./identifiers.js";
-import type { JsonValue, OpenEnum } from "./types.js";
+import type { 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
@@ -26,30 +26,14 @@ export type FileInput = Blob | {
     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.
+ * Input for {@link MaterialGraphClient.uploadSourceMaterial}: 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}.
  */
-export type UploadSourceMaterialFilesInput = {
+export type UploadSourceMaterialInput = {
     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 type 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 type SourceMaterialReceiptFile = {
     /** The stored file id (`smf_…`). Opaque — the prefix is a reading aid, not a contract. */
@@ -74,185 +58,6 @@ export type SourceMaterialBatchReceipt = {
     batchId: BatchId;
     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 type 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;
-};
-/** Who a comment is from, as you SUBMIT it. Not the API principal posting it. */
-export type SourceMaterialCommentAuthorInput = {
-    /** Trimmed, 1–160 characters. Longer or blank is refused by the server. */
-    name: string;
-    /**
-     * Their practice or team; `null` for a note carrying no organisation.
-     * Trimmed, 1–160 characters when present. Nullable, not optional.
-     */
-    organisation: string | null;
-};
-/**
- * Who a comment is from, as you READ IT BACK.
- *
- * `attribution` is the honesty field: nothing verified this name. Render it as
- * "recorded as from X", never as a statement X signed — the identity that IS
- * verified is {@link SourceMaterialCommentReply.recordedBy}.
- */
-export type SourceMaterialCommentAuthor = {
-    /**
-     * How the name got here. `reported` means a caller typed it. {@link OpenEnum}
-     * keeps a newer server value type-checking; treat anything unfamiliar as
-     * unverified.
-     */
-    attribution: OpenEnum<"reported">;
-} & SourceMaterialCommentAuthorInput;
-/** The authenticated principal that recorded a comment. */
-export type SourceMaterialCommentRecorder = {
-    /**
-     * The principal that wrote the row. Comments can only be posted against a
-     * batch the poster owns, so on every comment you can read this is your own.
-     */
-    principalId: string;
-};
-/**
- * One reply on a source-material file. A reply carries no replies of its own:
- * threads are one level deep because the database makes a reply-to-reply
- * unstorable, and this type says so rather than implying a tree.
- */
-export type SourceMaterialCommentReply = {
-    /** The stored comment id (`smc_…`). Opaque. */
-    commentId: string;
-    author: SourceMaterialCommentAuthor;
-    /** Who recorded it — the audit answer behind the reported name. */
-    recordedBy: SourceMaterialCommentRecorder;
-    body: string;
-    /** ISO-8601 timestamp of the posting. */
-    createdAt: string;
-};
-/** One root remark with the replies that answer it. */
-export type SourceMaterialComment = {
-    /** ALWAYS an array. `[]` means nobody answered — never a missing field. */
-    replies: SourceMaterialCommentReply[];
-} & SourceMaterialCommentReply;
-/** The `200` body of `GET …/sources/{sourceId}/comments`. */
-export type SourceMaterialCommentThread = {
-    /** The file the thread hangs off (`smf_…`). Opaque. */
-    sourceId: string;
-    /**
-     * The thread, oldest root first. ALWAYS an array; `[]` means the file is
-     * yours and nobody has commented on it.
-     */
-    comments: SourceMaterialComment[];
-    /**
-     * `true` when the file holds more comment rows than one read inlines (500),
-     * so `comments` is the oldest of them rather than all of them.
-     */
-    truncated: boolean;
-};
-/** The body of `POST …/sources/{sourceId}/comments`. */
-export type PostSourceMaterialCommentInput = {
-    author: SourceMaterialCommentAuthorInput;
-    /** Trimmed, 1–4000 characters. */
-    body: string;
-    /**
-     * The root comment being answered, or absent for a new remark. Must be a ROOT
-     * comment on the same file: replying to a reply is a 400.
-     */
-    parentCommentId?: string | null;
-    /**
-     * Your own token for this one intended remark, 1–200 characters. Send it and
-     * a retry after a network timeout returns the comment you already posted
-     * rather than a permanent duplicate. Scoped to the file.
-     */
-    idempotencyKey?: string | null;
-};
-/** A comment the server just stored, as a root. */
-export type StoredSourceMaterialRootComment = {
-    kind: "root";
-} & SourceMaterialComment;
-/** A comment the server just stored, as a reply to a root. */
-export type StoredSourceMaterialReplyComment = {
-    kind: "reply";
-    /** The root this answers. Present because a reply always has one. */
-    parentCommentId: string;
-} & SourceMaterialCommentReply;
-/**
- * What a POST returns, discriminated on `kind`. Switch on it: a `root` carries
- * an empty `replies`, a `reply` carries `parentCommentId` and no `replies` at
- * all, because it can never have any.
- */
-export type StoredSourceMaterialComment = StoredSourceMaterialRootComment | StoredSourceMaterialReplyComment;
-/** The `201` body of `POST …/sources/{sourceId}/comments`. */
-export type PostSourceMaterialCommentResult = {
-    /** The file the comment hangs off (`smf_…`). Opaque. */
-    sourceId: string;
-    comment: StoredSourceMaterialComment;
-};
-/** One file as `GET /api/v1/source-material/{batchId}` returns it. */
-export type SourceMaterialBatchFile = {
-    /** 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 argument about this file, oldest root first. ALWAYS an array; `[]` means
-     * nobody has commented, which is a state to draw rather than an absence to
-     * guess at.
-     */
-    comments: SourceMaterialComment[];
-    /**
-     * `true` when this file holds more comment rows than one read inlines (500),
-     * so `comments` is the oldest of them. `false` on a file whose whole thread
-     * you have, including one nobody has commented on.
-     */
-    commentsTruncated: boolean;
-} & SourceMaterialReceiptFile;
-/**
- * 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 type SourceMaterialBatchDetail = {
-    /** The stored batch id (`smb_…`). Opaque. */
-    batchId: BatchId;
-    /** ISO-8601 timestamp of the upload. */
-    createdAt: string;
-    sources: SourceMaterialBatchFile[];
-};
-/**
- * Still carried on {@link PublicRun.capabilityKind}, so a Run created before
- * MG-2252 reads back as `"agent"`. The rest of the public capability manifest
- * shape retired with `GET /api/v1/capabilities`.
- */
-export type CapabilityKind = OpenEnum<"agent" | "tool" | "workflow">;
-/** What `POST /api/v1/runs` admits: never an agent since MG-2252. */
-export type CreatableCapabilityKind = "tool" | "workflow";
 export type PublicRunStatus = OpenEnum<"queued" | "claimed" | "running" | "suspended" | "succeeded" | "failed" | "canceled">;
 export type PublicRunFailure = {
     code: string;
@@ -272,8 +77,8 @@ export type PublicRunArtifactRef = {
 export type PublicRun = {
     /** Opaque — round-trip verbatim into every other Run call. */
     id: RunId;
-    capabilityKind: CapabilityKind;
-    capabilityId: string;
+    /** The workflow this Run belongs to, e.g. `curate-collection`: the id its path names. */
+    workflowId: string;
     clientReference: string | null;
     /** `suspended` is a QUESTION, not a failure — see `suspensionStepId`. */
     status: PublicRunStatus;
@@ -300,12 +105,14 @@ export type PublicRun = {
     createdAt: string;
     updatedAt: string;
 };
-/** Body for `POST /api/v1/runs` ({@link MaterialGraphClient.createRun}). */
+/**
+ * Body for `POST /api/v1/workflows/{workflowId}/runs`
+ * ({@link WorkflowsClient.start}). The workflow is named by the path, never the
+ * body.
+ */
 export type CreatePublicRunRequest = {
-    capabilityKind: CreatableCapabilityKind;
-    capabilityId: string;
-    /** The capability input, validated server-side against its live input schema. */
-    inputJson: unknown;
+    /** The workflow input, validated server-side against its live input schema. */
+    inputJson: Record<string, unknown>;
     /**
      * Stable caller key making Run creation idempotent across retries. Supply it:
      * without one, a retried POST starts a SECOND Run rather than replaying the
@@ -315,14 +122,14 @@ export type CreatePublicRunRequest = {
     /** Free-form caller correlation reference, echoed back on the Run. */
     clientReference?: string;
 };
-/** The `POST /api/v1/runs` response (`200` replay or `202` accepted). */
+/** The start response (`200` replay or `202` accepted). */
 export type CreatePublicRunResponse = {
     accepted: boolean;
     replayed: boolean;
     workflowRunId: string;
     run: PublicRun;
 };
-/** The `GET /api/v1/runs/{runId}` response envelope. */
+/** The `GET /api/v1/workflows/{workflowId}/runs/{runId}` response envelope. */
 export type PublicRunResponse = {
     run: PublicRun;
 };
@@ -338,14 +145,14 @@ export type RunEvent = {
 };
 /** 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}. */
+/** Options for {@link WorkflowsClient.streamRunEvents}. */
 export type 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}. */
+/** Options for {@link WorkflowsClient.drainRunEvents}. */
 export type DrainRunEventsOptions = {
     /** Resume after this sequence (exclusive). */
     after?: number;

package/runs.d.ts

@@ -1,70 +1,22 @@
 import type { HttpTransport } from "./http-transport.js";
-import type { CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PostSourceMaterialCommentInput, PostSourceMaterialCommentResult, PublicRunResponse, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, SourceMaterialCommentThread, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
+import type { CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, RunEvent, SourceMaterialBatchReceipt, StreamRunEventsOptions, 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.
+ * Each entry of `{ files }` becomes one part of the repeatable multipart
+ * `files` field.
  */
 export declare const 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 const getSourceMaterialBatch: (transport: HttpTransport, batchId: string, signal?: AbortSignal) => Promise<SourceMaterialBatchDetail>;
-/**
- * Read one file's comment thread
- * (`GET /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
- *
- * The remarks people left on one uploaded file, oldest root first, each root
- * carrying the replies that answer it. `comments` is always an array — `[]`
- * means the file is yours and nobody has said anything about it.
- *
- * Author names are REPORTED, never verified: each carries
- * `author.attribution: "reported"` plus the principal that recorded it in
- * `recordedBy`. Render "recorded as from X", not "X said".
- *
- * `truncated` is `true` when the file holds more rows than one read inlines.
- *
- * A file that is not in that batch, or a batch you do not own, raises the same
- * 404 as a file that never existed.
- */
-export declare const listSourceMaterialComments: (transport: HttpTransport, batchId: string, sourceId: string, signal?: AbortSignal) => Promise<SourceMaterialCommentThread>;
-/**
- * Add one remark to a file's thread
- * (`POST /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
- *
- * `author` is who the comment is FROM — usually the client or a colleague, not
- * the key posting it — so it is stored and read back as reported attribution.
- * Pass `parentCommentId` to answer a ROOT comment on the same file; anything
- * deeper is a 400, because threads are one level deep.
- *
- * Pass `idempotencyKey` and a retry after a network timeout returns the comment
- * you already posted rather than a permanent duplicate.
- *
- * The result is discriminated on `kind`: switch on it rather than reaching for
- * `replies`, which a `reply` does not have.
- */
-export declare const postSourceMaterialComment: (transport: HttpTransport, batchId: string, sourceId: string, input: PostSourceMaterialCommentInput, signal?: AbortSignal) => Promise<PostSourceMaterialCommentResult>;
-/** Start an asynchronous capability Run (`POST /api/v1/runs`). */
-export declare const createRun: (transport: HttpTransport, body: CreatePublicRunRequest, signal?: AbortSignal) => Promise<CreatePublicRunResponse>;
-/** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
-export declare const getRun: (transport: HttpTransport, runId: string, signal?: AbortSignal) => Promise<PublicRunResponse>;
+/** Start an asynchronous Run of one workflow (`POST /api/v1/workflows/{workflowId}/runs`). */
+export declare const startWorkflowRun: (transport: HttpTransport, workflowId: string, body: CreatePublicRunRequest, signal?: AbortSignal) => Promise<CreatePublicRunResponse>;
+/** Get a Run's current state (`GET /api/v1/workflows/{workflowId}/runs/{runId}`). */
+export declare const getWorkflowRun: (transport: HttpTransport, workflowId: string, 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
+ * /api/v1/workflows/{workflowId}/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>;
+export declare function streamRunEvents(transport: HttpTransport, workflowId: string, 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
@@ -80,4 +32,4 @@ export declare function streamRunEvents(transport: HttpTransport, runId: string,
  * failure (a real 4xx/5xx or transport error) still propagates, keeping the
  * fail-fast surface for genuine upstream problems.
  */
-export declare const drainRunEvents: (transport: HttpTransport, runId: string, options: DrainRunEventsOptions) => Promise<RunEvent[]>;
+export declare const drainRunEvents: (transport: HttpTransport, workflowId: string, runId: string, options: DrainRunEventsOptions) => Promise<RunEvent[]>;

package/runs.js

@@ -1,13 +1,13 @@
 /**
- * The Run + source-material namespace — the agentic half of the SDK. These
+ * The workflow Run + source-material calls — the agentic half of the SDK. These
  * functions take the shared {@link HttpTransport} and speak the hosted Run
- * lifecycle: upload source material, create/read Runs, and stream (or drain)
- * their events. Box's proxy routes are thin wrappers over exactly these calls.
+ * lifecycle: upload source material, start and read a workflow's Runs, and
+ * stream (or drain) their events. `mg.workflows` and `uploadSourceMaterial`
+ * are thin wrappers over exactly these calls.
  */
 import { MaterialGraphError } from "./errors.js";
 import { findSdkOperation, operationPath } from "./operations.js";
 import { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
-import { checkPostSourceMaterialCommentResult, checkSourceMaterialBatchDetail, checkSourceMaterialCommentThread, } from "./source-material-validation.js";
 import { readSseFrames } from "./sse.js";
 const runOperation = (operationId) => {
     const match = findSdkOperation(operationId);
@@ -43,22 +43,13 @@ const appendFile = (form, field, input) => {
 };
 /**
  * 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.
+ * Each entry of `{ files }` becomes one part of the repeatable multipart
+ * `files` field.
  */
 export const uploadSourceMaterial = async (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);
-        }
+    for (const file of input.files) {
+        appendFile(form, "files", file);
     }
     const url = transport.buildUrl(operationPath(runOperation("upload_source_material")));
     // No Content-Type header: fetch sets multipart/form-data with the boundary.
@@ -71,93 +62,15 @@ export const uploadSourceMaterial = async (transport, input, 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 const getSourceMaterialBatch = async (transport, batchId, signal) => {
-    const body = await transport.requestJson(runOperation("get_source_material_batch"), {
-        pathParams: { batchId },
-        signal,
-    });
-    return checkSourceMaterialBatchDetail(body, batchId);
-};
-/**
- * Read one file's comment thread
- * (`GET /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
- *
- * The remarks people left on one uploaded file, oldest root first, each root
- * carrying the replies that answer it. `comments` is always an array — `[]`
- * means the file is yours and nobody has said anything about it.
- *
- * Author names are REPORTED, never verified: each carries
- * `author.attribution: "reported"` plus the principal that recorded it in
- * `recordedBy`. Render "recorded as from X", not "X said".
- *
- * `truncated` is `true` when the file holds more rows than one read inlines.
- *
- * A file that is not in that batch, or a batch you do not own, raises the same
- * 404 as a file that never existed.
- */
-export const listSourceMaterialComments = async (transport, batchId, sourceId, signal) => {
-    const body = await transport.requestJson(runOperation("list_source_material_comments"), {
-        pathParams: { batchId, sourceId },
-        signal,
-    });
-    return checkSourceMaterialCommentThread(body, sourceId);
-};
-/**
- * Add one remark to a file's thread
- * (`POST /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
- *
- * `author` is who the comment is FROM — usually the client or a colleague, not
- * the key posting it — so it is stored and read back as reported attribution.
- * Pass `parentCommentId` to answer a ROOT comment on the same file; anything
- * deeper is a 400, because threads are one level deep.
- *
- * Pass `idempotencyKey` and a retry after a network timeout returns the comment
- * you already posted rather than a permanent duplicate.
- *
- * The result is discriminated on `kind`: switch on it rather than reaching for
- * `replies`, which a `reply` does not have.
- */
-export const postSourceMaterialComment = async (transport, batchId, sourceId, input, signal) => {
-    const body = await transport.requestJson(runOperation("post_source_material_comment"), {
-        // Built key by key rather than spread: `parentCommentId` and
-        // `idempotencyKey` are forwarded only when PRESENT, so a caller that
-        // omits them sends a body byte-identical to one that never knew about
-        // them.
-        body: {
-            author: input.author,
-            body: input.body,
-            ...(input.parentCommentId === undefined
-                ? {}
-                : { parentCommentId: input.parentCommentId }),
-            ...(input.idempotencyKey === undefined
-                ? {}
-                : { idempotencyKey: input.idempotencyKey }),
-        },
-        pathParams: { batchId, sourceId },
-        signal,
-    });
-    return checkPostSourceMaterialCommentResult(body, sourceId);
-};
-/** Start an asynchronous capability Run (`POST /api/v1/runs`). */
-export const createRun = async (transport, body, signal) => await transport.requestJson(runOperation("create_public_run"), {
+/** Start an asynchronous Run of one workflow (`POST /api/v1/workflows/{workflowId}/runs`). */
+export const startWorkflowRun = async (transport, workflowId, body, signal) => await transport.requestJson(runOperation("create_public_run"), {
     body,
+    pathParams: { workflowId },
     signal,
 });
-/** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
-export const getRun = async (transport, runId, signal) => await transport.requestJson(runOperation("get_public_run"), {
-    pathParams: { runId },
+/** Get a Run's current state (`GET /api/v1/workflows/{workflowId}/runs/{runId}`). */
+export const getWorkflowRun = async (transport, workflowId, runId, signal) => await transport.requestJson(runOperation("get_public_run"), {
+    pathParams: { runId, workflowId },
     signal,
 });
 /** Decode one SSE `data:` frame into a {@link RunEvent}, or `null` when unusable. */
@@ -183,13 +96,13 @@ const decodeRunEvent = (data) => {
 };
 /**
  * Stream ordered Run events as an async iterator (`GET
- * /api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or
+ * /api/v1/workflows/{workflowId}/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 = {}) {
+export async function* streamRunEvents(transport, workflowId, runId, options = {}) {
     const body = await transport.openStream(runOperation("list_public_run_events"), {
-        pathParams: { runId },
+        pathParams: { runId, workflowId },
         ...(options.after === undefined
             ? {}
             : { query: { after: options.after } }),
@@ -219,14 +132,14 @@ export async function* streamRunEvents(transport, runId, options = {}) {
  * failure (a real 4xx/5xx or transport error) still propagates, keeping the
  * fail-fast surface for genuine upstream problems.
  */
-export const drainRunEvents = async (transport, runId, options) => {
+export const drainRunEvents = async (transport, workflowId, runId, options) => {
     const collected = [];
     const controller = new AbortController();
     const timer = setTimeout(() => {
         controller.abort();
     }, options.deadlineMs);
     try {
-        for await (const event of streamRunEvents(transport, runId, {
+        for await (const event of streamRunEvents(transport, workflowId, runId, {
             after: options.after,
             signal: controller.signal,
         })) {