@vertesia/client 1.3.0 → 1.4.0-dev.20260615.042033Z

package/lib/store/signed-url.js

@@ -0,0 +1,153 @@
+/**
+ * Helpers for transferring file content to/from cloud-storage signed URLs
+ * (GCS, S3, Azure Blob) with retry + backoff on transient failures.
+ *
+ * Signed-URL transfers go straight to the storage backend and therefore bypass
+ * the Vertesia API client (`AbstractFetchClient`), which means they normally get
+ * none of its retry policy. A single transient `503 Service Unavailable` from the
+ * storage backend would otherwise fail the whole upload/download. This helper
+ * restores retry behaviour for those storage hops.
+ *
+ * Note on streamed bodies: a `ReadableStream` body cannot be replayed once it has
+ * been consumed, so it is buffered into memory before the first attempt to make
+ * retries safe. Callers transferring very large streams should be aware of this
+ * memory cost.
+ */
+/** HTTP statuses that storage backends return for transient, retryable conditions. */
+const DEFAULT_RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+const DEFAULT_ATTEMPTS = 4;
+const DEFAULT_BASE_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 8_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function retryAfterMs(res) {
+    const header = res.headers.get('retry-after');
+    if (!header) {
+        return undefined;
+    }
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1000;
+    }
+    const date = Date.parse(header);
+    if (!Number.isNaN(date)) {
+        return Math.max(0, date - Date.now());
+    }
+    return undefined;
+}
+function backoffMs(attempt, baseDelayMs, maxDelayMs, res) {
+    const retryAfter = res ? retryAfterMs(res) : undefined;
+    if (retryAfter !== undefined) {
+        return Math.min(maxDelayMs, retryAfter);
+    }
+    // Exponential backoff with full jitter.
+    const capped = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+    return Math.floor(Math.random() * capped);
+}
+const textEncoder = new TextEncoder();
+/**
+ * Normalize one `ReadableStream` chunk to a byte-backed `BlobPart`.
+ *
+ * A web stream produced from a Node `Readable.from(<string>)` (e.g. via
+ * `Readable.toWeb`, which `NodeStreamSource` uses) yields *string* chunks. Buffering
+ * such a stream with `new Response(stream).blob()` throws under undici with
+ * "TypeError: Received non-Uint8Array chunk", which breaks every signed-URL upload of
+ * a text/JSON body (extracted text previews, agent artifacts, tool storage). Encoding
+ * chunks ourselves keeps both string and binary bodies uploadable.
+ */
+function chunkToBlobPart(chunk) {
+    if (typeof chunk === 'string') {
+        return textEncoder.encode(chunk);
+    }
+    if (chunk instanceof Blob) {
+        return chunk;
+    }
+    if (chunk instanceof ArrayBuffer) {
+        return new Uint8Array(chunk);
+    }
+    // Covers Uint8Array and every other typed-array / DataView view.
+    if (ArrayBuffer.isView(chunk)) {
+        return new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    }
+    // Fail loud rather than uploading e.g. "[object Object]" from an accidental
+    // object-mode stream — silently corrupting the stored content is worse than a clear error.
+    throw new TypeError(`Unsupported signed-URL upload chunk of type "${typeof chunk}"; ` +
+        `body streams must yield string or binary (Uint8Array/ArrayBuffer/DataView/Blob) chunks.`);
+}
+/**
+ * Buffer a `ReadableStream` body into a `Blob` so the request can be safely
+ * replayed across retries. Other body types (`Blob`/`File`, `ArrayBuffer`,
+ * typed arrays, strings, `URLSearchParams`) are already replayable and pass
+ * through unchanged.
+ *
+ * The stream is drained manually (rather than `new Response(stream).blob()`) so that
+ * string chunks are encoded to bytes — see {@link chunkToBlobPart}.
+ */
+async function toReplayableBody(body) {
+    if (body == null) {
+        return undefined;
+    }
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+        const reader = body.getReader();
+        const parts = [];
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                // Normalize every chunk (a stray null/undefined is rejected by
+                // chunkToBlobPart) so a malformed stream fails loudly instead of
+                // silently uploading a truncated body.
+                parts.push(chunkToBlobPart(value));
+            }
+        }
+        catch (err) {
+            // Signal the producer to stop and release its resources before propagating.
+            await reader.cancel(err).catch(() => undefined);
+            throw err;
+        }
+        finally {
+            reader.releaseLock();
+        }
+        return new Blob(parts);
+    }
+    return body;
+}
+/**
+ * `fetch()` a cloud-storage signed URL, retrying transient failures (connection
+ * errors and retryable HTTP statuses) with exponential backoff. Honors a
+ * `Retry-After` response header when present.
+ *
+ * The returned `Response` is only guaranteed to be retried while it carries a
+ * retryable status; a non-retryable error response (e.g. 403, 404) is returned
+ * as-is for the caller to handle.
+ */
+export async function fetchSignedUrl(url, options = {}) {
+    const { method = 'GET', headers, attempts = DEFAULT_ATTEMPTS, baseDelayMs = DEFAULT_BASE_DELAY_MS, maxDelayMs = DEFAULT_MAX_DELAY_MS, retryableStatuses = DEFAULT_RETRYABLE_STATUSES, } = options;
+    const body = await toReplayableBody(options.body);
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const isLastAttempt = attempt === attempts - 1;
+        try {
+            const res = await fetch(url, { method, headers, body });
+            if (res.ok || !retryableStatuses.has(res.status) || isLastAttempt) {
+                return res;
+            }
+            // Retryable status: drain the body so the connection can be reused, then back off.
+            await res.body?.cancel().catch(() => undefined);
+            await sleep(backoffMs(attempt, baseDelayMs, maxDelayMs, res));
+        }
+        catch (err) {
+            lastError = err;
+            if (isLastAttempt) {
+                throw err;
+            }
+            await sleep(backoffMs(attempt, baseDelayMs, maxDelayMs));
+        }
+    }
+    // Unreachable: the loop always returns a Response or throws on the last attempt.
+    throw lastError instanceof Error ? lastError : new Error(`Failed to fetch signed URL: ${url}`);
+}
+//# sourceMappingURL=signed-url.js.map

package/lib/store/signed-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-url.js","sourceRoot":"","sources":["../../src/store/signed-url.ts"],"names":[],"mappings":"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"}

package/lib/store/stream-termination.d.ts

@@ -0,0 +1,4 @@
+import { type AgentMessage, type CompactMessage } from '@vertesia/common';
+export declare function shouldCloseAgentRunStream(message: AgentMessage, rootRunId: string): boolean;
+export declare function shouldCloseCompactRunStream(message: CompactMessage, rootRunId: string): boolean;
+//# sourceMappingURL=stream-termination.d.ts.map

package/lib/store/stream-termination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-termination.d.ts","sourceRoot":"","sources":["../../src/store/stream-termination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAoB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAiB5F,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAU3F;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAU/F"}

package/lib/store/stream-termination.js

@@ -0,0 +1,31 @@
+import { AgentMessageType } from '@vertesia/common';
+function readProcessRunId(details) {
+    if (!details || typeof details !== 'object') {
+        return undefined;
+    }
+    const value = details.process_run_id;
+    return typeof value === 'string' ? value : undefined;
+}
+function isRootProcessMessage(details, rootRunId) {
+    const processRunId = readProcessRunId(details);
+    return !processRunId || processRunId === rootRunId;
+}
+export function shouldCloseAgentRunStream(message, rootRunId) {
+    if (message.type === AgentMessageType.TERMINATED) {
+        return isRootProcessMessage(message.details, rootRunId);
+    }
+    if (message.type === AgentMessageType.COMPLETE && (message.workstream_id ?? 'main') === 'main') {
+        return isRootProcessMessage(message.details, rootRunId);
+    }
+    return false;
+}
+export function shouldCloseCompactRunStream(message, rootRunId) {
+    if (message.t === AgentMessageType.TERMINATED) {
+        return isRootProcessMessage(message.d, rootRunId);
+    }
+    if (message.t === AgentMessageType.COMPLETE && (message.w ?? 'main') === 'main') {
+        return isRootProcessMessage(message.d, rootRunId);
+    }
+    return false;
+}
+//# sourceMappingURL=stream-termination.js.map

package/lib/store/stream-termination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-termination.js","sourceRoot":"","sources":["../../src/store/stream-termination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,gBAAgB,EAAuB,MAAM,kBAAkB,CAAC;AAI5F,SAAS,gBAAgB,CAAC,OAAuB;IAC7C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,KAAK,GAAI,OAAwC,CAAC,cAAc,CAAC;IACvE,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC;AAED,SAAS,oBAAoB,CAAC,OAAuB,EAAE,SAAiB;IACpE,MAAM,YAAY,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC/C,OAAO,CAAC,YAAY,IAAI,YAAY,KAAK,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,OAAqB,EAAE,SAAiB;IAC9E,IAAI,OAAO,CAAC,IAAI,KAAK,gBAAgB,CAAC,UAAU,EAAE,CAAC;QAC/C,OAAO,oBAAoB,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,gBAAgB,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,aAAa,IAAI,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;QAC7F,OAAO,oBAAoB,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,OAAuB,EAAE,SAAiB;IAClF,IAAI,OAAO,CAAC,CAAC,KAAK,gBAAgB,CAAC,UAAU,EAAE,CAAC;QAC5C,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,OAAO,CAAC,CAAC,KAAK,gBAAgB,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;QAC9E,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/lib/{types/store → store}/version.d.ts

@@ -1,2 +1,3 @@
 export declare const VERSION = "20260319";
 export declare const VERSION_HEADER = "x-api-version";
+//# sourceMappingURL=version.d.ts.map

package/lib/store/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/store/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,aAAa,CAAC;AAClC,eAAO,MAAM,cAAc,kBAAkB,CAAC"}

package/lib/store/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/store/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,yFAAyF;AAC5H,MAAM,CAAC,MAAM,cAAc,GAAG,eAAe,CAAC"}