@instruments/materialgraph 1.4.0 → 2.0.0

package/runs.js

@@ -1,198 +0,0 @@
-/**
- * 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, 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 { readSseFrames } from "./sse.js";
-const hasSourceIdentity = (source) => typeof source === "object" &&
-    source !== null &&
-    "sourceId" in source &&
-    typeof source.sourceId === "string" &&
-    "role" in source &&
-    typeof source.role === "string" &&
-    "filename" in source &&
-    typeof source.filename === "string" &&
-    "mediaType" in source &&
-    typeof source.mediaType === "string";
-const hasSourceMeasurements = (source) => typeof source === "object" &&
-    source !== null &&
-    "sha256" in source &&
-    typeof source.sha256 === "string" &&
-    "bytes" in source &&
-    typeof source.bytes === "number" &&
-    "pages" in source &&
-    (source.pages === null || typeof source.pages === "number");
-const isSourceReceipt = (value) => typeof value === "object" &&
-    value !== null &&
-    "batchId" in value &&
-    typeof value.batchId === "string" &&
-    "sources" in value &&
-    Array.isArray(value.sources) &&
-    value.sources.every((source) => typeof source === "object" &&
-        source !== null &&
-        hasSourceIdentity(source) &&
-        hasSourceMeasurements(source));
-const isRunEvent = (value) => typeof value === "object" &&
-    value !== null &&
-    "sequence" in value &&
-    typeof value.sequence === "number" &&
-    "type" in value &&
-    typeof value.type === "string";
-const runOperation = (operationId) => {
-    const match = findSdkOperation(operationId);
-    if (!match) {
-        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
-    }
-    return { ...match, operationId };
-};
-/** Build a `Blob` from raw bytes, normalizing to an ArrayBuffer-backed view. */
-const bytesToBlob = (input) => {
-    const type = input.contentType !== undefined && 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. */
-const 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`).
- * Each entry of `{ files }` becomes one part of the repeatable multipart
- * `files` field.
- */
-export const uploadSourceMaterial = async (transport, input, signal) => {
-    const form = new FormData();
-    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.
-    const { parsed } = await transport.send({
-        body: form,
-        headers: transport.authHeaders(),
-        method: "POST",
-        signal,
-        url,
-    });
-    if (!isSourceReceipt(parsed)) {
-        throw MaterialGraphError.unexpected("MaterialGraph source-material upload returned an invalid receipt");
-    }
-    return parsed;
-};
-/** 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/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. */
-const 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)}`);
-    }
-    return isRunEvent(parsed) ? parsed : null;
-};
-/**
- * Stream ordered Run events as an async iterator (`GET
- * /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.
- * @yields {RunEvent} Each usable Run event from the stream.
- */
-export const streamRunEvents = async function* streamRunEvents(transport, workflowId, runId, options = {}) {
-    const body = await transport.openStream(runOperation("list_public_run_events"), {
-        pathParams: { runId, workflowId },
-        ...(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 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, workflowId, 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;
-};

package/sse.d.ts

@@ -1,36 +0,0 @@
-/**
- * A minimal, dependency-free Server-Sent Events reader — the primitive behind
- * {@link WorkflowsClient.streamRunEvents}. Hand-rolled (no `eventsource`,
- * no `undici`) so the SDK stays zero-runtime-dep and works unchanged inside
- * Node route handlers, where `fetch` yields a byte `ReadableStream`.
- *
- * The parser follows the WHATWG event-stream tokenizer closely enough for the
- * `/api/v1/workflows/{workflowId}/runs/{runId}/events` contract: `\n`, `\r\n`, and `\r` line endings,
- * multi-line `data:` accumulation, comment (`:`-prefixed) lines, and a single
- * optional leading space after the field colon. Frames split across network
- * chunks are held in an internal buffer until their terminating blank line.
- */
-/** One dispatched SSE frame. `data` is the joined data lines (no trailing newline). */
-export type SseFrame = {
-    id?: string;
-    event?: string;
-    data: string;
-};
-/**
- * A push-based SSE line assembler. Feed it decoded text with {@link push}; it
- * returns any frames completed by that text. Call {@link flush} once the stream
- * ends to dispatch a final frame that had data but no terminating blank line.
- */
-export declare class SseDecoder {
-    #private;
-    push(text: string): SseFrame[];
-    /** Dispatch a trailing frame that had fields but no closing blank line. */
-    flush(): SseFrame[];
-}
-/**
- * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
- * or `signal` aborts (mid-read abort rejections are swallowed once the signal
- * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
- * @yields {SseFrame} Each completed frame containing fields.
- */
-export declare const readSseFrames: (body: ReadableStream<Uint8Array>, signal?: AbortSignal) => AsyncGenerator<SseFrame, void, unknown>;

package/sse.js

@@ -1,167 +0,0 @@
-/**
- * A minimal, dependency-free Server-Sent Events reader — the primitive behind
- * {@link WorkflowsClient.streamRunEvents}. Hand-rolled (no `eventsource`,
- * no `undici`) so the SDK stays zero-runtime-dep and works unchanged inside
- * Node route handlers, where `fetch` yields a byte `ReadableStream`.
- *
- * The parser follows the WHATWG event-stream tokenizer closely enough for the
- * `/api/v1/workflows/{workflowId}/runs/{runId}/events` contract: `\n`, `\r\n`, and `\r` line endings,
- * multi-line `data:` accumulation, comment (`:`-prefixed) lines, and a single
- * optional leading space after the field colon. Frames split across network
- * chunks are held in an internal buffer until their terminating blank line.
- */
-/**
- * A push-based SSE line assembler. Feed it decoded text with {@link push}; it
- * returns any frames completed by that text. Call {@link flush} once the stream
- * ends to dispatch a final frame that had data but no terminating blank line.
- */
-export class SseDecoder {
-    #buffer = "";
-    #dataLines = [];
-    #id;
-    #event;
-    #hasFields = false;
-    push(text) {
-        this.#buffer += text;
-        const frames = [];
-        for (;;) {
-            const lineEnd = this.#nextLineEnd();
-            if (lineEnd === null) {
-                break;
-            }
-            const line = this.#buffer.slice(0, lineEnd.index);
-            this.#buffer = this.#buffer.slice(lineEnd.nextIndex);
-            const frame = this.#consumeLine(line);
-            if (frame) {
-                frames.push(frame);
-            }
-        }
-        return frames;
-    }
-    /** Dispatch a trailing frame that had fields but no closing blank line. */
-    flush() {
-        if (this.#buffer.length > 0) {
-            // At end of stream a deferred trailing CR is a real terminator, not data.
-            const line = this.#buffer.endsWith("\r")
-                ? this.#buffer.slice(0, -1)
-                : this.#buffer;
-            this.#buffer = "";
-            const frame = this.#consumeLine(line);
-            if (frame) {
-                return [frame];
-            }
-        }
-        const frame = this.#dispatch();
-        return frame ? [frame] : [];
-    }
-    /** Locate the next line terminator, deferring a lone trailing `\r` (may be `\r\n`). */
-    #nextLineEnd() {
-        for (let i = 0; i < this.#buffer.length; i += 1) {
-            const char = this.#buffer[i];
-            if (char === "\n") {
-                return { index: i, nextIndex: i + 1 };
-            }
-            if (char === "\r") {
-                if (i === this.#buffer.length - 1) {
-                    return null;
-                }
-                return this.#buffer[i + 1] === "\n"
-                    ? { index: i, nextIndex: i + 2 }
-                    : { index: i, nextIndex: i + 1 };
-            }
-        }
-        return null;
-    }
-    #consumeLine(line) {
-        if (line.length === 0) {
-            return this.#dispatch();
-        }
-        if (line.startsWith(":")) {
-            return undefined;
-        }
-        const colon = line.indexOf(":");
-        const field = colon === -1 ? line : line.slice(0, colon);
-        let value = colon === -1 ? "" : line.slice(colon + 1);
-        if (value.startsWith(" ")) {
-            value = value.slice(1);
-        }
-        if (field === "data") {
-            this.#dataLines.push(value);
-            this.#hasFields = true;
-        }
-        else if (field === "event") {
-            this.#event = value;
-            this.#hasFields = true;
-        }
-        else if (field === "id") {
-            this.#id = value;
-            this.#hasFields = true;
-        }
-        return undefined;
-    }
-    #dispatch() {
-        if (!this.#hasFields) {
-            return undefined;
-        }
-        const frame = { data: this.#dataLines.join("\n") };
-        if (this.#event !== undefined) {
-            frame.event = this.#event;
-        }
-        if (this.#id !== undefined) {
-            frame.id = this.#id;
-        }
-        this.#dataLines = [];
-        this.#event = undefined;
-        this.#id = undefined;
-        this.#hasFields = false;
-        return frame;
-    }
-}
-/**
- * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
- * or `signal` aborts (mid-read abort rejections are swallowed once the signal
- * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
- * @yields {SseFrame} Each completed frame containing fields.
- */
-export const readSseFrames = async function* readSseFrames(body, signal) {
-    const isAborted = () => signal?.aborted === true;
-    const reader = body.getReader();
-    const decoder = new TextDecoder();
-    const sse = new SseDecoder();
-    try {
-        for (;;) {
-            if (isAborted()) {
-                return;
-            }
-            let result;
-            try {
-                result = await reader.read();
-            }
-            catch (error) {
-                if (isAborted()) {
-                    return;
-                }
-                throw error;
-            }
-            if (result.done) {
-                for (const frame of sse.push(decoder.decode())) {
-                    yield frame;
-                }
-                for (const frame of sse.flush()) {
-                    yield frame;
-                }
-                return;
-            }
-            const text = decoder.decode(result.value, { stream: true });
-            for (const frame of sse.push(text)) {
-                if (isAborted()) {
-                    return;
-                }
-                yield frame;
-            }
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-};

package/workflows-client.d.ts

@@ -1,54 +0,0 @@
-import type { HttpTransport } from "./http-transport.js";
-/**
- * The workflow Run surface, namespaced as `mg.workflows`. A Run is the start of
- * one registered Mastra workflow and nothing else: you name the workflow, hand
- * it its input, and follow the Run it returns. Replaces the flat `createRun()`,
- * `run()`, `streamRunEvents()` and `drainRunEvents()` methods, retired with no
- * shim when `/api/v1/runs` moved under `/api/v1/workflows/{workflowId}/runs`.
- *
- * THE QUESTION: "do a whole job for me" — the ASYNC lens. Everything else on
- * the client answers in one round trip; a Run may suspend for human input and
- * finish minutes later. `start()` acknowledges without executing, `run()` polls
- * the ledger, and `streamRunEvents()` follows it live.
- *
- * `workflowId` is the registered workflow's id, such as `edit-collection`. A
- * Run is read under the workflow that started it: asking for it under another
- * workflow's id is a 404.
- *
- * Starting a Run needs the `mg:compose` or `mg:write` scope, plus whatever
- * scope the workflow itself declares.
- */
-import type { RunId } from "./identifiers.js";
-import type { CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, RunEvent, StreamRunEventsOptions } from "./run-types.js";
-export declare class WorkflowsClient {
-    #private;
-    constructor(options: {
-        transport: HttpTransport;
-    });
-    /**
-     * Start an asynchronous Run of `workflowId` (POST
-     * `/api/v1/workflows/{workflowId}/runs`). Pass `idempotencyKey` so a retry
-     * replays rather than duplicates. Follow with {@link streamRunEvents} (live)
-     * or {@link run} (poll).
-     */
-    start(workflowId: string, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
-    /**
-     * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
-     * ledger record. Polling; prefer {@link streamRunEvents} when a human is
-     * waiting.
-     */
-    run(workflowId: string, runId: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
-    /**
-     * Stream ordered Run events as an async iterator (GET
-     * `/api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until
-     * the stream ends or the signal aborts; pass `after` to resume from the last
-     * observed sequence.
-     */
-    streamRunEvents(workflowId: string, runId: RunId, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent>;
-    /**
-     * Collect Run events until a terminal event, the deadline, or the stream
-     * ends — the bounded events-log pattern (a single pass over
-     * {@link streamRunEvents}).
-     */
-    drainRunEvents(workflowId: string, runId: RunId, options: DrainRunEventsOptions): Promise<RunEvent[]>;
-}

package/workflows-client.js

@@ -1,41 +0,0 @@
-import { drainRunEvents, getWorkflowRun, startWorkflowRun, streamRunEvents, } from "./runs.js";
-export class WorkflowsClient {
-    #transport;
-    constructor(options) {
-        this.#transport = options.transport;
-    }
-    /**
-     * Start an asynchronous Run of `workflowId` (POST
-     * `/api/v1/workflows/{workflowId}/runs`). Pass `idempotencyKey` so a retry
-     * replays rather than duplicates. Follow with {@link streamRunEvents} (live)
-     * or {@link run} (poll).
-     */
-    async start(workflowId, body, signal) {
-        return await startWorkflowRun(this.#transport, workflowId, body, signal);
-    }
-    /**
-     * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
-     * ledger record. Polling; prefer {@link streamRunEvents} when a human is
-     * waiting.
-     */
-    async run(workflowId, runId, signal) {
-        return await getWorkflowRun(this.#transport, workflowId, runId, signal);
-    }
-    /**
-     * Stream ordered Run events as an async iterator (GET
-     * `/api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until
-     * the stream ends or the signal aborts; pass `after` to resume from the last
-     * observed sequence.
-     */
-    streamRunEvents(workflowId, runId, options) {
-        return streamRunEvents(this.#transport, workflowId, runId, options);
-    }
-    /**
-     * Collect Run events until a terminal event, the deadline, or the stream
-     * ends — the bounded events-log pattern (a single pass over
-     * {@link streamRunEvents}).
-     */
-    async drainRunEvents(workflowId, runId, options) {
-        return await drainRunEvents(this.#transport, workflowId, runId, options);
-    }
-}