@superatomai/sdk-node 0.0.94-dsp → 0.0.96-dsp

package/dist/index.d.mts

@@ -1463,10 +1463,12 @@ declare const MessageSchema: z.ZodObject<{
     from: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodString>;
+        parcels: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     to: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodString>;
+        parcels: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     payload: z.ZodUnknown;
 }, z.core.$strip>;
@@ -1477,10 +1479,12 @@ declare const IncomingMessageSchema: z.ZodObject<{
     from: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodString>;
+        parcels: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     to: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodString>;
+        parcels: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     payload: z.ZodUnknown;
 }, z.core.$strip>;
@@ -4836,6 +4840,8 @@ interface ParcelRef {
 interface ParcelFileRef extends ParcelRef {
     name?: string;
     contentType: string;
+    /** The file's bytes as base64, when storage was down and they travel in the message instead. */
+    data?: string;
 }
 interface ParcelClientOptions {
     apiUrl: string;
@@ -4854,6 +4860,8 @@ declare class ParcelClient {
     constructor(opts: ParcelClientOptions);
     private url;
     private call;
+    /** The receipt the bytes would get, without storing them. */
+    refFor(bytes: Uint8Array, ext: string): ParcelRef;
     /** Stores the bytes and returns the receipt for them. */
     upload(bytes: Uint8Array, ext?: string, contentType?: string): Promise<ParcelRef>;
     /** The bytes behind a receipt, checked against its hash. */
@@ -4872,7 +4880,11 @@ declare class ParcelFile {
     readonly size: number;
     readonly contentType: string;
     constructor(ref: ParcelFileRef, client: ParcelClient | null);
-    /** The file's bytes, checked against their hash. Throws if they cannot be fetched. */
+    /**
+     * The file's bytes, checked against their hash — from the message itself when
+     * it carried them (storage was down), otherwise from storage. Throws if they
+     * cannot be fetched.
+     */
     download(): Promise<Uint8Array>;
     toJSON(): {
         __parcelFile: ParcelFileRef;
@@ -6061,6 +6073,8 @@ declare class SuperatomSDK {
     private parcelClient;
     private outgoing;
     private incoming;
+    /** The client sockets that said they read parcels; only they get large JSON as parcels or parts. */
+    private parcelReaders;
     constructor(config: SuperatomSDKConfig);
     /**
      * Initialize PromptLoader and load prompts into memory

package/dist/index.d.ts

@@ -1463,10 +1463,12 @@ declare const MessageSchema: z.ZodObject<{
     from: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodString>;
+        parcels: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     to: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodString>;
+        parcels: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     payload: z.ZodUnknown;
 }, z.core.$strip>;
@@ -1477,10 +1479,12 @@ declare const IncomingMessageSchema: z.ZodObject<{
     from: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodString>;
+        parcels: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     to: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodString>;
+        parcels: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     payload: z.ZodUnknown;
 }, z.core.$strip>;
@@ -4836,6 +4840,8 @@ interface ParcelRef {
 interface ParcelFileRef extends ParcelRef {
     name?: string;
     contentType: string;
+    /** The file's bytes as base64, when storage was down and they travel in the message instead. */
+    data?: string;
 }
 interface ParcelClientOptions {
     apiUrl: string;
@@ -4854,6 +4860,8 @@ declare class ParcelClient {
     constructor(opts: ParcelClientOptions);
     private url;
     private call;
+    /** The receipt the bytes would get, without storing them. */
+    refFor(bytes: Uint8Array, ext: string): ParcelRef;
     /** Stores the bytes and returns the receipt for them. */
     upload(bytes: Uint8Array, ext?: string, contentType?: string): Promise<ParcelRef>;
     /** The bytes behind a receipt, checked against its hash. */
@@ -4872,7 +4880,11 @@ declare class ParcelFile {
     readonly size: number;
     readonly contentType: string;
     constructor(ref: ParcelFileRef, client: ParcelClient | null);
-    /** The file's bytes, checked against their hash. Throws if they cannot be fetched. */
+    /**
+     * The file's bytes, checked against their hash — from the message itself when
+     * it carried them (storage was down), otherwise from storage. Throws if they
+     * cannot be fetched.
+     */
     download(): Promise<Uint8Array>;
     toJSON(): {
         __parcelFile: ParcelFileRef;
@@ -6061,6 +6073,8 @@ declare class SuperatomSDK {
     private parcelClient;
     private outgoing;
     private incoming;
+    /** The client sockets that said they read parcels; only they get large JSON as parcels or parts. */
+    private parcelReaders;
     constructor(config: SuperatomSDKConfig);
     /**
      * Initialize PromptLoader and load prompts into memory

package/dist/index.js

@@ -348,7 +348,9 @@ var UsersDataSchema = import_zod3.z.object({
 });
 var MessageParticipantSchema = import_zod3.z.object({
   id: import_zod3.z.string().optional(),
-  type: import_zod3.z.string().optional()
+  type: import_zod3.z.string().optional(),
+  /** On `from`: the sending client reads parcels and parts (see parcels/ParcelReaders). */
+  parcels: import_zod3.z.boolean().optional()
 });
 var MessageSchema = import_zod3.z.object({
   id: import_zod3.z.string().optional(),
@@ -28370,12 +28372,19 @@ var import_crypto7 = require("crypto");
 var PARCEL_THRESHOLD_BYTES = 256 * 1024;
 var MAX_INLINE_BYTES = 900 * 1024;
 var MAX_PARCEL_BYTES = 95 * 1024 * 1024;
+var PART_BYTES = 600 * 1024;
+var PART_WAIT_MS = 6e4;
 var NEVER_PARCEL = /* @__PURE__ */ new Set(["PING", "PONG", "BUNDLE_CHUNK", "BUNDLE_CSS_CHUNK"]);
 var RETRY_DELAYS_MS = [500, 1500];
 var REQUEST_TIMEOUT_MS = 6e4;
 var MAX_DEPTH = 32;
 var PARCEL_FIELD = "__parcel";
 var FILE_FIELD = "__parcelFile";
+var PART_FIELD = "__parcelPart";
+var partOf = (payload) => {
+  const p = payload?.[PART_FIELD];
+  return p && typeof p.id === "string" && typeof p.data === "string" && Number.isInteger(p.total) && Number.isInteger(p.index) && p.total > 0 && p.index >= 0 && p.index < p.total ? p : null;
+};
 var isRef = (ref) => !!ref && typeof ref === "object" && typeof ref.projectId === "string" && typeof ref.hash === "string" && typeof ref.ext === "string" && typeof ref.size === "number";
 function parcelRefOf(payload) {
   const ref = payload?.[PARCEL_FIELD];
@@ -28430,12 +28439,16 @@ var ParcelClient = class {
     }
     return res;
   }
+  /** The receipt the bytes would get, without storing them. */
+  refFor(bytes, ext) {
+    return { projectId: this.opts.projectId, hash: sha256Hex(bytes), ext, size: bytes.byteLength };
+  }
   /** Stores the bytes and returns the receipt for them. */
   async upload(bytes, ext = "json", contentType = "application/json") {
     if (bytes.byteLength > MAX_PARCEL_BYTES) {
       throw new Error(`Parcel too large (${bytes.byteLength} bytes, limit ${MAX_PARCEL_BYTES})`);
     }
-    const ref = { projectId: this.opts.projectId, hash: sha256Hex(bytes), ext, size: bytes.byteLength };
+    const ref = this.refFor(bytes, ext);
     await withRetries(
       "upload",
       () => this.call(this.url(ref), { method: "PUT", headers: { "Content-Type": contentType }, body: bytes })
@@ -28462,8 +28475,17 @@ var ParcelFile = class {
     this.size = ref.size;
     this.contentType = ref.contentType;
   }
-  /** The file's bytes, checked against their hash. Throws if they cannot be fetched. */
+  /**
+   * The file's bytes, checked against their hash — from the message itself when
+   * it carried them (storage was down), otherwise from storage. Throws if they
+   * cannot be fetched.
+   */
   async download() {
+    if (typeof this.ref.data === "string") {
+      const bytes = new Uint8Array(Buffer.from(this.ref.data, "base64"));
+      if (sha256Hex(bytes) !== this.ref.hash) throw new Error("File content does not match its hash");
+      return bytes;
+    }
     if (!this.client) throw new Error("Cannot download files: SA_API_URL or the API key is not set");
     return this.client.download(this.ref);
   }
@@ -28492,28 +28514,55 @@ function hasFileRef(value, depth = 0) {
   return false;
 }
 var extOf = (name) => typeof name === "string" && /\.([a-z0-9]{1,10})$/i.exec(name)?.[1]?.toLowerCase() || "bin";
-async function uploadFiles(value, client, parent, depth = 0) {
+async function uploadFiles(value, client, storage, parent, depth = 0) {
   if (isBinary(value)) {
     const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
     const name = parent?.name ?? parent?.fileName;
     const contentType = String(parent?.contentType ?? parent?.mimeType ?? "application/octet-stream");
-    const ref = await client.upload(bytes, extOf(name), contentType);
-    const fileRef = { ...ref, contentType, ...typeof name === "string" ? { name } : {} };
+    const named = typeof name === "string" ? { name } : {};
+    if (!storage.down) {
+      try {
+        const ref = await client.upload(bytes, extOf(name), contentType);
+        const fileRef2 = { ...ref, contentType, ...named };
+        return { [FILE_FIELD]: fileRef2 };
+      } catch (err) {
+        if (bytes.byteLength > MAX_PARCEL_BYTES) throw err;
+        storage.down = true;
+        logger.warn(`[parcels] file upload failed, sending it in the message instead: ${err?.message ?? err}`);
+      }
+    }
+    const fileRef = {
+      ...client.refFor(bytes, extOf(name)),
+      contentType,
+      ...named,
+      data: Buffer.from(bytes).toString("base64")
+    };
     return { [FILE_FIELD]: fileRef };
   }
   if (depth >= MAX_DEPTH) return value;
   if (Array.isArray(value)) {
     const out = [];
-    for (const v of value) out.push(await uploadFiles(v, client, void 0, depth + 1));
+    for (const v of value) out.push(await uploadFiles(v, client, storage, void 0, depth + 1));
     return out;
   }
   if (isPlain(value)) {
     const out = {};
-    for (const [k, v] of Object.entries(value)) out[k] = await uploadFiles(v, client, value, depth + 1);
+    for (const [k, v] of Object.entries(value)) out[k] = await uploadFiles(v, client, storage, value, depth + 1);
     return out;
   }
   return value;
 }
+function splitPayload(payload) {
+  const bytes = Buffer.from(JSON.stringify(payload ?? null), "utf8");
+  const total = Math.max(1, Math.ceil(bytes.byteLength / PART_BYTES));
+  const id = (0, import_crypto7.randomUUID)();
+  return Array.from({ length: total }, (_, index) => ({
+    id,
+    index,
+    total,
+    data: bytes.subarray(index * PART_BYTES, (index + 1) * PART_BYTES).toString("base64")
+  }));
+}
 function toFileHandles(value, client, depth = 0) {
   const ref = fileRefOf(value);
   if (ref) return new ParcelFile(ref, client);
@@ -28534,6 +28583,26 @@ var recipientOf = (message) => {
   const id = message.to?.id;
   return typeof id === "string" ? id : "";
 };
+var MAX_READERS = 1e4;
+var ParcelReaders = class {
+  constructor(max = MAX_READERS) {
+    this.max = max;
+    this.ids = /* @__PURE__ */ new Set();
+  }
+  /** Notes what a received message says about its sender. */
+  noteSender(message) {
+    const from = message?.from;
+    if (typeof from?.id !== "string" || !from.id) return;
+    this.ids.delete(from.id);
+    if (from.parcels !== true) return;
+    this.ids.add(from.id);
+    if (this.ids.size > this.max) this.ids.delete(this.ids.values().next().value);
+  }
+  /** Whether the message is addressed to a socket that said it reads parcels. */
+  reads(message) {
+    return this.ids.has(recipientOf(message));
+  }
+};
 var InOrder = class {
   /** `onIdle` runs each time the last waiting task finishes. */
   constructor(onIdle) {
@@ -28555,15 +28624,19 @@ var InOrder = class {
   }
 };
 var OutgoingParcels = class {
-  constructor(client, jsonParcels, deliver, threshold = PARCEL_THRESHOLD_BYTES) {
+  constructor(client, jsonParcels, deliver, readers = null, threshold = PARCEL_THRESHOLD_BYTES) {
     this.client = client;
     this.jsonParcels = jsonParcels;
     this.deliver = deliver;
+    this.readers = readers;
     this.threshold = threshold;
     /** Only recipients with something waiting; a queue is dropped once it empties. */
     this.queues = /* @__PURE__ */ new Map();
     this.warnedNoClient = false;
   }
+  readsParcels(message) {
+    return this.readers ? this.readers.reads(message) : true;
+  }
   /**
    * Same contract as the SDK's `send`: never throws, returns whether the message
    * went out (or, for a queued one, was accepted).
@@ -28583,7 +28656,7 @@ var OutgoingParcels = class {
       files = false;
     }
     if (!files) {
-      if (!this.jsonParcels || !this.client) return this.now(message);
+      if (!this.jsonParcels || !this.client || !this.readsParcels(message)) return this.now(message);
       let wire;
       try {
         wire = JSON.stringify(message);
@@ -28593,8 +28666,7 @@ var OutgoingParcels = class {
       if (Buffer.byteLength(wire, "utf8") < this.threshold) return this.now(message, wire);
     }
     this.queueFor(message).run(async () => {
-      const out = await this.prepare(message, files);
-      this.deliver(out.message, out.wire);
+      for (const out of await this.prepare(message, files)) this.deliver(out.message, out.wire);
     });
     return true;
   }
@@ -28619,44 +28691,66 @@ var OutgoingParcels = class {
   async idle() {
     await Promise.all(Array.from(this.queues.values(), (queue) => queue.idle()));
   }
+  /**
+   * What actually goes on the socket for this message: usually one message (as
+   * is, or as a parcel receipt); several parts when storage is down and the
+   * message is too large for the relay.
+   */
   async prepare(message, files) {
     let current = message;
+    const storage = { down: false };
     if (files) {
-      const started2 = Date.now();
+      const started = Date.now();
       try {
-        current = { ...message, payload: await uploadFiles(message.payload, this.client) };
-        logger.info(`[parcels] ${message.type} ${message.id ?? ""}: file(s) uploaded (${Date.now() - started2}ms)`);
+        current = { ...message, payload: await uploadFiles(message.payload, this.client, storage) };
+        if (!storage.down) logger.info(`[parcels] ${message.type} ${message.id ?? ""}: file(s) uploaded (${Date.now() - started}ms)`);
       } catch (err) {
-        const reason = err?.message ?? String(err);
-        logger.error(`[parcels] file upload failed for ${message.type}, sending an error instead: ${reason}`);
-        return { message: asError(message, `Could not send a file: ${reason}`) };
+        const reason2 = err?.message ?? String(err);
+        logger.error(`[parcels] file upload failed for ${message.type}, sending an error instead: ${reason2}`);
+        return [{ message: asError(message, `Could not send a file: ${reason2}`) }];
       }
     }
     let wire;
     try {
       wire = JSON.stringify(current);
     } catch {
-      return { message: current };
+      return [{ message: current }];
     }
     const size = Buffer.byteLength(wire, "utf8");
-    if (!this.jsonParcels || size < this.threshold) return { message: current, wire };
-    const started = Date.now();
-    try {
-      const bytes = Buffer.from(JSON.stringify(current.payload ?? null), "utf8");
-      const ref = await this.client.upload(bytes);
-      logger.info(
-        `[parcels] ${message.type} ${message.id ?? ""} \u2192 parcel ${ref.hash.slice(0, 12)} (${ref.size} bytes, ${Date.now() - started}ms)`
-      );
-      return { message: { ...current, payload: { [PARCEL_FIELD]: ref } } };
-    } catch (err) {
-      const reason = err?.message ?? String(err);
-      if (size <= MAX_INLINE_BYTES) {
-        logger.warn(`[parcels] upload failed for ${message.type}, sending inline (${size} bytes): ${reason}`);
-        return { message: current, wire };
+    if (size < this.threshold) return [{ message: current, wire }];
+    if (!this.readsParcels(message)) {
+      if (size > MAX_INLINE_BYTES) {
+        logger.warn(`[parcels] ${message.type} (${size} bytes) is for a client that doesn't read parcels \u2014 sent inline; the relay may refuse it`);
+      }
+      return [{ message: current, wire }];
+    }
+    let reason = "large-JSON parcels are off";
+    if (this.jsonParcels && !storage.down) {
+      const started = Date.now();
+      try {
+        const bytes = Buffer.from(JSON.stringify(current.payload ?? null), "utf8");
+        const ref = await this.client.upload(bytes);
+        logger.info(
+          `[parcels] ${message.type} ${message.id ?? ""} \u2192 parcel ${ref.hash.slice(0, 12)} (${ref.size} bytes, ${Date.now() - started}ms)`
+        );
+        return [{ message: { ...current, payload: { [PARCEL_FIELD]: ref } } }];
+      } catch (err) {
+        reason = err?.message ?? String(err);
       }
-      logger.error(`[parcels] upload failed for ${message.type} (${size} bytes), sending an error instead: ${reason}`);
-      return { message: asError(message, `The message was too large to deliver (${size} bytes): ${reason}`) };
+    } else if (storage.down) {
+      reason = "storage is down";
+    }
+    if (size <= MAX_INLINE_BYTES) {
+      if (this.jsonParcels) logger.warn(`[parcels] ${message.type} not stored (${reason}), sending inline (${size} bytes)`);
+      return [{ message: current, wire }];
+    }
+    if (size > MAX_PARCEL_BYTES) {
+      logger.error(`[parcels] ${message.type} (${size} bytes) is too large to send`);
+      return [{ message: asError(message, `The message was too large to deliver (${size} bytes): ${reason}`) }];
     }
+    const parts = splitPayload(current.payload);
+    logger.warn(`[parcels] ${message.type} not stored (${reason}), sending in ${parts.length} parts (${size} bytes)`);
+    return parts.map((part) => ({ message: { ...current, payload: { [PART_FIELD]: part } } }));
   }
 };
 var IncomingParcels = class {
@@ -28664,12 +28758,22 @@ var IncomingParcels = class {
     this.client = client;
     this.dispatch = dispatch;
     this.queue = new InOrder();
+    /** Split messages still waiting for parts, by part id. */
+    this.partial = /* @__PURE__ */ new Map();
+    /** Split messages already rebuilt, so a second copy of their parts is ignored. */
+    this.rebuilt = /* @__PURE__ */ new Set();
   }
   /**
    * `raw` is the message's text when it is at hand: a message that never
    * mentions a file placeholder is not searched for one.
    */
   receive(message, raw) {
+    const part = partOf(message?.payload);
+    if (part) {
+      const whole = this.collect(message, part);
+      if (whole) this.receive(whole);
+      return;
+    }
     const ref = parcelRefOf(message?.payload);
     if (!ref) {
       const withFiles = raw === void 0 || raw.includes(FILE_FIELD) ? this.withFiles(message) : message;
@@ -28685,6 +28789,38 @@ var IncomingParcels = class {
   idle() {
     return this.queue.idle();
   }
+  /**
+   * Holds one part; once all of them are here, the original message (envelope
+   * from the last part, payload rebuilt). Null while parts are still missing.
+   */
+  collect(message, part) {
+    if (this.rebuilt.has(part.id)) return null;
+    let entry = this.partial.get(part.id);
+    if (!entry) {
+      const timer = setTimeout(() => {
+        this.partial.delete(part.id);
+        logger.warn(`[parcels] ${message.type}: gave up waiting for the rest of a split message (${part.id})`);
+      }, PART_WAIT_MS).unref();
+      entry = { parts: new Array(part.total), got: 0, timer };
+      this.partial.set(part.id, entry);
+    }
+    if (entry.parts.length !== part.total || entry.parts[part.index] !== void 0) return null;
+    entry.parts[part.index] = part.data;
+    if (++entry.got < part.total) return null;
+    clearTimeout(entry.timer);
+    this.partial.delete(part.id);
+    this.rebuilt.add(part.id);
+    setTimeout(() => this.rebuilt.delete(part.id), PART_WAIT_MS).unref();
+    try {
+      const bytes = Buffer.concat(entry.parts.map((data) => Buffer.from(data, "base64")));
+      logger.info(`[parcels] ${message.type} ${message.id ?? ""} rebuilt from ${part.total} parts (${bytes.byteLength} bytes)`);
+      return { ...message, payload: JSON.parse(bytes.toString("utf8")) };
+    } catch (err) {
+      const reason = err?.message ?? String(err);
+      logger.error(`[parcels] could not rebuild a split ${message.type}: ${reason}`);
+      return asError(message, `Could not rebuild the message: ${reason}`);
+    }
+  }
   withFiles(message) {
     try {
       return hasFileRef(message.payload) ? { ...message, payload: toFileHandles(message.payload, this.client) } : message;
@@ -30048,6 +30184,8 @@ var SuperatomSDK = class {
     // since an outage of unknown length shouldn't grow this without limit.
     this.pendingOutbox = [];
     this.MAX_OUTBOX_SIZE = 50;
+    /** The client sockets that said they read parcels; only they get large JSON as parcels or parts. */
+    this.parcelReaders = new ParcelReaders();
     /**
      * The dashboard contract, as registered by the browser bundle that holds it.
      *
@@ -30074,7 +30212,8 @@ var SuperatomSDK = class {
     this.outgoing = new OutgoingParcels(
       this.parcelClient,
       jsonParcels,
-      (message, wire) => this.deliver(message, wire)
+      (message, wire) => this.deliver(message, wire),
+      this.parcelReaders
     );
     this.incoming = new IncomingParcels(this.parcelClient, (parsed) => this.dispatchMessage(parsed));
     this.anthropicApiKey = config2.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY || "";
@@ -30241,6 +30380,7 @@ var SuperatomSDK = class {
       logger.error("Failed to parse incoming message:", error);
       return;
     }
+    this.parcelReaders.noteSender(parsed);
     this.incoming.receive(parsed, data);
   }
   /** Routes one parsed message — everything `handleMessage` did after parsing. */

package/dist/index.mjs

@@ -6,7 +6,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/index.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 
 // src/websocket.ts
 import WebSocket from "ws";
@@ -228,7 +228,9 @@ var UsersDataSchema = z3.object({
 });
 var MessageParticipantSchema = z3.object({
   id: z3.string().optional(),
-  type: z3.string().optional()
+  type: z3.string().optional(),
+  /** On `from`: the sending client reads parcels and parts (see parcels/ParcelReaders). */
+  parcels: z3.boolean().optional()
 });
 var MessageSchema = z3.object({
   id: z3.string().optional(),
@@ -28246,16 +28248,23 @@ var ReportManager = class {
 };
 
 // src/parcels/index.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
 var PARCEL_THRESHOLD_BYTES = 256 * 1024;
 var MAX_INLINE_BYTES = 900 * 1024;
 var MAX_PARCEL_BYTES = 95 * 1024 * 1024;
+var PART_BYTES = 600 * 1024;
+var PART_WAIT_MS = 6e4;
 var NEVER_PARCEL = /* @__PURE__ */ new Set(["PING", "PONG", "BUNDLE_CHUNK", "BUNDLE_CSS_CHUNK"]);
 var RETRY_DELAYS_MS = [500, 1500];
 var REQUEST_TIMEOUT_MS = 6e4;
 var MAX_DEPTH = 32;
 var PARCEL_FIELD = "__parcel";
 var FILE_FIELD = "__parcelFile";
+var PART_FIELD = "__parcelPart";
+var partOf = (payload) => {
+  const p = payload?.[PART_FIELD];
+  return p && typeof p.id === "string" && typeof p.data === "string" && Number.isInteger(p.total) && Number.isInteger(p.index) && p.total > 0 && p.index >= 0 && p.index < p.total ? p : null;
+};
 var isRef = (ref) => !!ref && typeof ref === "object" && typeof ref.projectId === "string" && typeof ref.hash === "string" && typeof ref.ext === "string" && typeof ref.size === "number";
 function parcelRefOf(payload) {
   const ref = payload?.[PARCEL_FIELD];
@@ -28310,12 +28319,16 @@ var ParcelClient = class {
     }
     return res;
   }
+  /** The receipt the bytes would get, without storing them. */
+  refFor(bytes, ext) {
+    return { projectId: this.opts.projectId, hash: sha256Hex(bytes), ext, size: bytes.byteLength };
+  }
   /** Stores the bytes and returns the receipt for them. */
   async upload(bytes, ext = "json", contentType = "application/json") {
     if (bytes.byteLength > MAX_PARCEL_BYTES) {
       throw new Error(`Parcel too large (${bytes.byteLength} bytes, limit ${MAX_PARCEL_BYTES})`);
     }
-    const ref = { projectId: this.opts.projectId, hash: sha256Hex(bytes), ext, size: bytes.byteLength };
+    const ref = this.refFor(bytes, ext);
     await withRetries(
       "upload",
       () => this.call(this.url(ref), { method: "PUT", headers: { "Content-Type": contentType }, body: bytes })
@@ -28342,8 +28355,17 @@ var ParcelFile = class {
     this.size = ref.size;
     this.contentType = ref.contentType;
   }
-  /** The file's bytes, checked against their hash. Throws if they cannot be fetched. */
+  /**
+   * The file's bytes, checked against their hash — from the message itself when
+   * it carried them (storage was down), otherwise from storage. Throws if they
+   * cannot be fetched.
+   */
   async download() {
+    if (typeof this.ref.data === "string") {
+      const bytes = new Uint8Array(Buffer.from(this.ref.data, "base64"));
+      if (sha256Hex(bytes) !== this.ref.hash) throw new Error("File content does not match its hash");
+      return bytes;
+    }
     if (!this.client) throw new Error("Cannot download files: SA_API_URL or the API key is not set");
     return this.client.download(this.ref);
   }
@@ -28372,28 +28394,55 @@ function hasFileRef(value, depth = 0) {
   return false;
 }
 var extOf = (name) => typeof name === "string" && /\.([a-z0-9]{1,10})$/i.exec(name)?.[1]?.toLowerCase() || "bin";
-async function uploadFiles(value, client, parent, depth = 0) {
+async function uploadFiles(value, client, storage, parent, depth = 0) {
   if (isBinary(value)) {
     const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
     const name = parent?.name ?? parent?.fileName;
     const contentType = String(parent?.contentType ?? parent?.mimeType ?? "application/octet-stream");
-    const ref = await client.upload(bytes, extOf(name), contentType);
-    const fileRef = { ...ref, contentType, ...typeof name === "string" ? { name } : {} };
+    const named = typeof name === "string" ? { name } : {};
+    if (!storage.down) {
+      try {
+        const ref = await client.upload(bytes, extOf(name), contentType);
+        const fileRef2 = { ...ref, contentType, ...named };
+        return { [FILE_FIELD]: fileRef2 };
+      } catch (err) {
+        if (bytes.byteLength > MAX_PARCEL_BYTES) throw err;
+        storage.down = true;
+        logger.warn(`[parcels] file upload failed, sending it in the message instead: ${err?.message ?? err}`);
+      }
+    }
+    const fileRef = {
+      ...client.refFor(bytes, extOf(name)),
+      contentType,
+      ...named,
+      data: Buffer.from(bytes).toString("base64")
+    };
     return { [FILE_FIELD]: fileRef };
   }
   if (depth >= MAX_DEPTH) return value;
   if (Array.isArray(value)) {
     const out = [];
-    for (const v of value) out.push(await uploadFiles(v, client, void 0, depth + 1));
+    for (const v of value) out.push(await uploadFiles(v, client, storage, void 0, depth + 1));
     return out;
   }
   if (isPlain(value)) {
     const out = {};
-    for (const [k, v] of Object.entries(value)) out[k] = await uploadFiles(v, client, value, depth + 1);
+    for (const [k, v] of Object.entries(value)) out[k] = await uploadFiles(v, client, storage, value, depth + 1);
     return out;
   }
   return value;
 }
+function splitPayload(payload) {
+  const bytes = Buffer.from(JSON.stringify(payload ?? null), "utf8");
+  const total = Math.max(1, Math.ceil(bytes.byteLength / PART_BYTES));
+  const id = randomUUID3();
+  return Array.from({ length: total }, (_, index) => ({
+    id,
+    index,
+    total,
+    data: bytes.subarray(index * PART_BYTES, (index + 1) * PART_BYTES).toString("base64")
+  }));
+}
 function toFileHandles(value, client, depth = 0) {
   const ref = fileRefOf(value);
   if (ref) return new ParcelFile(ref, client);
@@ -28414,6 +28463,26 @@ var recipientOf = (message) => {
   const id = message.to?.id;
   return typeof id === "string" ? id : "";
 };
+var MAX_READERS = 1e4;
+var ParcelReaders = class {
+  constructor(max = MAX_READERS) {
+    this.max = max;
+    this.ids = /* @__PURE__ */ new Set();
+  }
+  /** Notes what a received message says about its sender. */
+  noteSender(message) {
+    const from = message?.from;
+    if (typeof from?.id !== "string" || !from.id) return;
+    this.ids.delete(from.id);
+    if (from.parcels !== true) return;
+    this.ids.add(from.id);
+    if (this.ids.size > this.max) this.ids.delete(this.ids.values().next().value);
+  }
+  /** Whether the message is addressed to a socket that said it reads parcels. */
+  reads(message) {
+    return this.ids.has(recipientOf(message));
+  }
+};
 var InOrder = class {
   /** `onIdle` runs each time the last waiting task finishes. */
   constructor(onIdle) {
@@ -28435,15 +28504,19 @@ var InOrder = class {
   }
 };
 var OutgoingParcels = class {
-  constructor(client, jsonParcels, deliver, threshold = PARCEL_THRESHOLD_BYTES) {
+  constructor(client, jsonParcels, deliver, readers = null, threshold = PARCEL_THRESHOLD_BYTES) {
     this.client = client;
     this.jsonParcels = jsonParcels;
     this.deliver = deliver;
+    this.readers = readers;
     this.threshold = threshold;
     /** Only recipients with something waiting; a queue is dropped once it empties. */
     this.queues = /* @__PURE__ */ new Map();
     this.warnedNoClient = false;
   }
+  readsParcels(message) {
+    return this.readers ? this.readers.reads(message) : true;
+  }
   /**
    * Same contract as the SDK's `send`: never throws, returns whether the message
    * went out (or, for a queued one, was accepted).
@@ -28463,7 +28536,7 @@ var OutgoingParcels = class {
       files = false;
     }
     if (!files) {
-      if (!this.jsonParcels || !this.client) return this.now(message);
+      if (!this.jsonParcels || !this.client || !this.readsParcels(message)) return this.now(message);
       let wire;
       try {
         wire = JSON.stringify(message);
@@ -28473,8 +28546,7 @@ var OutgoingParcels = class {
       if (Buffer.byteLength(wire, "utf8") < this.threshold) return this.now(message, wire);
     }
     this.queueFor(message).run(async () => {
-      const out = await this.prepare(message, files);
-      this.deliver(out.message, out.wire);
+      for (const out of await this.prepare(message, files)) this.deliver(out.message, out.wire);
     });
     return true;
   }
@@ -28499,44 +28571,66 @@ var OutgoingParcels = class {
   async idle() {
     await Promise.all(Array.from(this.queues.values(), (queue) => queue.idle()));
   }
+  /**
+   * What actually goes on the socket for this message: usually one message (as
+   * is, or as a parcel receipt); several parts when storage is down and the
+   * message is too large for the relay.
+   */
   async prepare(message, files) {
     let current = message;
+    const storage = { down: false };
     if (files) {
-      const started2 = Date.now();
+      const started = Date.now();
       try {
-        current = { ...message, payload: await uploadFiles(message.payload, this.client) };
-        logger.info(`[parcels] ${message.type} ${message.id ?? ""}: file(s) uploaded (${Date.now() - started2}ms)`);
+        current = { ...message, payload: await uploadFiles(message.payload, this.client, storage) };
+        if (!storage.down) logger.info(`[parcels] ${message.type} ${message.id ?? ""}: file(s) uploaded (${Date.now() - started}ms)`);
       } catch (err) {
-        const reason = err?.message ?? String(err);
-        logger.error(`[parcels] file upload failed for ${message.type}, sending an error instead: ${reason}`);
-        return { message: asError(message, `Could not send a file: ${reason}`) };
+        const reason2 = err?.message ?? String(err);
+        logger.error(`[parcels] file upload failed for ${message.type}, sending an error instead: ${reason2}`);
+        return [{ message: asError(message, `Could not send a file: ${reason2}`) }];
       }
     }
     let wire;
     try {
       wire = JSON.stringify(current);
     } catch {
-      return { message: current };
+      return [{ message: current }];
     }
     const size = Buffer.byteLength(wire, "utf8");
-    if (!this.jsonParcels || size < this.threshold) return { message: current, wire };
-    const started = Date.now();
-    try {
-      const bytes = Buffer.from(JSON.stringify(current.payload ?? null), "utf8");
-      const ref = await this.client.upload(bytes);
-      logger.info(
-        `[parcels] ${message.type} ${message.id ?? ""} \u2192 parcel ${ref.hash.slice(0, 12)} (${ref.size} bytes, ${Date.now() - started}ms)`
-      );
-      return { message: { ...current, payload: { [PARCEL_FIELD]: ref } } };
-    } catch (err) {
-      const reason = err?.message ?? String(err);
-      if (size <= MAX_INLINE_BYTES) {
-        logger.warn(`[parcels] upload failed for ${message.type}, sending inline (${size} bytes): ${reason}`);
-        return { message: current, wire };
+    if (size < this.threshold) return [{ message: current, wire }];
+    if (!this.readsParcels(message)) {
+      if (size > MAX_INLINE_BYTES) {
+        logger.warn(`[parcels] ${message.type} (${size} bytes) is for a client that doesn't read parcels \u2014 sent inline; the relay may refuse it`);
+      }
+      return [{ message: current, wire }];
+    }
+    let reason = "large-JSON parcels are off";
+    if (this.jsonParcels && !storage.down) {
+      const started = Date.now();
+      try {
+        const bytes = Buffer.from(JSON.stringify(current.payload ?? null), "utf8");
+        const ref = await this.client.upload(bytes);
+        logger.info(
+          `[parcels] ${message.type} ${message.id ?? ""} \u2192 parcel ${ref.hash.slice(0, 12)} (${ref.size} bytes, ${Date.now() - started}ms)`
+        );
+        return [{ message: { ...current, payload: { [PARCEL_FIELD]: ref } } }];
+      } catch (err) {
+        reason = err?.message ?? String(err);
       }
-      logger.error(`[parcels] upload failed for ${message.type} (${size} bytes), sending an error instead: ${reason}`);
-      return { message: asError(message, `The message was too large to deliver (${size} bytes): ${reason}`) };
+    } else if (storage.down) {
+      reason = "storage is down";
+    }
+    if (size <= MAX_INLINE_BYTES) {
+      if (this.jsonParcels) logger.warn(`[parcels] ${message.type} not stored (${reason}), sending inline (${size} bytes)`);
+      return [{ message: current, wire }];
+    }
+    if (size > MAX_PARCEL_BYTES) {
+      logger.error(`[parcels] ${message.type} (${size} bytes) is too large to send`);
+      return [{ message: asError(message, `The message was too large to deliver (${size} bytes): ${reason}`) }];
     }
+    const parts = splitPayload(current.payload);
+    logger.warn(`[parcels] ${message.type} not stored (${reason}), sending in ${parts.length} parts (${size} bytes)`);
+    return parts.map((part) => ({ message: { ...current, payload: { [PART_FIELD]: part } } }));
   }
 };
 var IncomingParcels = class {
@@ -28544,12 +28638,22 @@ var IncomingParcels = class {
     this.client = client;
     this.dispatch = dispatch;
     this.queue = new InOrder();
+    /** Split messages still waiting for parts, by part id. */
+    this.partial = /* @__PURE__ */ new Map();
+    /** Split messages already rebuilt, so a second copy of their parts is ignored. */
+    this.rebuilt = /* @__PURE__ */ new Set();
   }
   /**
    * `raw` is the message's text when it is at hand: a message that never
    * mentions a file placeholder is not searched for one.
    */
   receive(message, raw) {
+    const part = partOf(message?.payload);
+    if (part) {
+      const whole = this.collect(message, part);
+      if (whole) this.receive(whole);
+      return;
+    }
     const ref = parcelRefOf(message?.payload);
     if (!ref) {
       const withFiles = raw === void 0 || raw.includes(FILE_FIELD) ? this.withFiles(message) : message;
@@ -28565,6 +28669,38 @@ var IncomingParcels = class {
   idle() {
     return this.queue.idle();
   }
+  /**
+   * Holds one part; once all of them are here, the original message (envelope
+   * from the last part, payload rebuilt). Null while parts are still missing.
+   */
+  collect(message, part) {
+    if (this.rebuilt.has(part.id)) return null;
+    let entry = this.partial.get(part.id);
+    if (!entry) {
+      const timer = setTimeout(() => {
+        this.partial.delete(part.id);
+        logger.warn(`[parcels] ${message.type}: gave up waiting for the rest of a split message (${part.id})`);
+      }, PART_WAIT_MS).unref();
+      entry = { parts: new Array(part.total), got: 0, timer };
+      this.partial.set(part.id, entry);
+    }
+    if (entry.parts.length !== part.total || entry.parts[part.index] !== void 0) return null;
+    entry.parts[part.index] = part.data;
+    if (++entry.got < part.total) return null;
+    clearTimeout(entry.timer);
+    this.partial.delete(part.id);
+    this.rebuilt.add(part.id);
+    setTimeout(() => this.rebuilt.delete(part.id), PART_WAIT_MS).unref();
+    try {
+      const bytes = Buffer.concat(entry.parts.map((data) => Buffer.from(data, "base64")));
+      logger.info(`[parcels] ${message.type} ${message.id ?? ""} rebuilt from ${part.total} parts (${bytes.byteLength} bytes)`);
+      return { ...message, payload: JSON.parse(bytes.toString("utf8")) };
+    } catch (err) {
+      const reason = err?.message ?? String(err);
+      logger.error(`[parcels] could not rebuild a split ${message.type}: ${reason}`);
+      return asError(message, `Could not rebuild the message: ${reason}`);
+    }
+  }
   withFiles(message) {
     try {
       return hasFileRef(message.payload) ? { ...message, payload: toFileHandles(message.payload, this.client) } : message;
@@ -29928,6 +30064,8 @@ var SuperatomSDK = class {
     // since an outage of unknown length shouldn't grow this without limit.
     this.pendingOutbox = [];
     this.MAX_OUTBOX_SIZE = 50;
+    /** The client sockets that said they read parcels; only they get large JSON as parcels or parts. */
+    this.parcelReaders = new ParcelReaders();
     /**
      * The dashboard contract, as registered by the browser bundle that holds it.
      *
@@ -29954,7 +30092,8 @@ var SuperatomSDK = class {
     this.outgoing = new OutgoingParcels(
       this.parcelClient,
       jsonParcels,
-      (message, wire) => this.deliver(message, wire)
+      (message, wire) => this.deliver(message, wire),
+      this.parcelReaders
     );
     this.incoming = new IncomingParcels(this.parcelClient, (parsed) => this.dispatchMessage(parsed));
     this.anthropicApiKey = config2.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY || "";
@@ -30121,6 +30260,7 @@ var SuperatomSDK = class {
       logger.error("Failed to parse incoming message:", error);
       return;
     }
+    this.parcelReaders.noteSender(parsed);
     this.incoming.receive(parsed, data);
   }
   /** Routes one parsed message — everything `handleMessage` did after parsing. */
@@ -30592,7 +30732,7 @@ var SuperatomSDK = class {
       waiters.push(finish);
       this.registryWaiters.set(resType, waiters);
       const sent = this.send({
-        id: `${reqType.toLowerCase()}_${randomUUID3()}`,
+        id: `${reqType.toLowerCase()}_${randomUUID4()}`,
         type: reqType,
         from: { type: this.type },
         to: { type: "runtime" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superatomai/sdk-node",
-  "version": "0.0.94-dsp",
+  "version": "0.0.96-dsp",
   "description": "Node.js TypeScript SDK for Superatom",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",