@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/sandbox-json-transport.js

@@ -0,0 +1,324 @@
+/**
+ * JSON transport for structured data across the QuickJS boundary.
+ *
+ * The wrapper marshals a value handle-by-handle: every object node costs four
+ * `evalCode` compilations inside the guest plus a `newFunction` allocation, and
+ * every property crosses as its own descriptor. Measured on this repo's engine
+ * that is ~150 µs per object node out of the guest and ~400 µs per object node
+ * into it — a Code node handed 5 000 rows spent 1.9 s reading them and another
+ * 0.8 s handing them back, before running a line of its own.
+ *
+ * Both directions carry JSON-shaped data, so the fast path is to move one
+ * string: the guest builds its answer with `JSON.stringify` and the host parses
+ * it, and the host encodes its globals here for the init prelude to parse.
+ * Measured on the same shapes, 20–25× either way.
+ *
+ * Two kinds of value would lose by that trade, and both ride *beside* the JSON
+ * in a sidecar the marshaler moves in one piece — a typed array (base64 inside
+ * the guest costs more than the marshal it replaces) and a string past
+ * {@link SIDECAR_STRING_THRESHOLD} (escaping a megabyte to unescape it again is
+ * two passes the primitive path never makes). A {@link JSON_SIDECAR_MARKER}
+ * holds its place by index.
+ *
+ * What JSON alone still cannot carry is carried by markers, so the round trip
+ * keeps the types the structured path preserved:
+ *
+ * - **dates** — an ISO string under {@link JSON_DATE_MARKER}, revived as a
+ *   `Date`. A `state.lastRun` that survives a Code node's invocations stays a
+ *   `Date` rather than degrading to a string on its first round trip.
+ * - **non-finite numbers** — `NaN` and the infinities under {@link
+ *   JSON_NUMBER_MARKER}. `JSON.stringify` writes them as `null`.
+ * - **undefined** — {@link JSON_UNDEFINED_MARKER}, so a property whose value is
+ *   `undefined` keeps its key. `JSON.stringify` drops it.
+ *
+ * Anything else — a function, a symbol, a bigint, a `Map`, a class instance —
+ * makes the encoder refuse that value, and its caller falls back to the
+ * wrapper's own marshaling, which is slow but total. The fast path never has to
+ * guess.
+ *
+ * A **cycle** is the one thing neither path carries: the wrapper's marshaler
+ * recurses until the runtime aborts with `list_empty(&rt->gc_obj_list)`, which
+ * kills the run with an assertion instead of an answer. So a cyclic global is
+ * refused by name, and a cyclic result becomes `String(value)` — the fallback
+ * `serializeResult` already documents for a value `JSON.stringify` rejects.
+ *
+ * Browser-safe: nothing here imports a Node builtin.
+ */
+import { encodeBase64, SANDBOX_BYTES_MARKER, SANDBOX_SERIALIZE_MAX_DEPTH } from "./sandbox-bytes.js";
+import { isObjectLike } from "./utils/type-guards.js";
+/** Marker key carrying an ISO timestamp for a `Date`. */
+export const JSON_DATE_MARKER = "__nodetool_sandbox_date__";
+/** Marker key carrying `"NaN"`, `"Infinity"`, or `"-Infinity"`. */
+export const JSON_NUMBER_MARKER = "__nodetool_sandbox_number__";
+/** Marker key standing in for an `undefined` property value. */
+export const JSON_UNDEFINED_MARKER = "__nodetool_sandbox_undefined__";
+/** Marker key carrying an index into the payload's sidecar. */
+export const JSON_SIDECAR_MARKER = "__nodetool_sandbox_side__";
+/**
+ * Strings at least this long travel in the sidecar rather than inside the JSON.
+ * Below it the escape/unescape pass is noise next to the run's fixed cost; a
+ * megabyte of text is where it stops being.
+ */
+export const SIDECAR_STRING_THRESHOLD = 8192;
+/** The global the guest parks its encoder on. */
+export const GUEST_MARSHAL_GLOBAL = "__nodetool_marshal__";
+/** The global carrying the host's encoded globals for the prelude to read. */
+export const GUEST_GLOBALS_JSON_BINDING = "__nodetool_globals_json__";
+/** The global carrying the sidecar those encoded globals index into. */
+export const GUEST_GLOBALS_SIDECAR_BINDING = "__nodetool_globals_side__";
+// ---------------------------------------------------------------------------
+// Host → guest
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Returned in place of a value that has no JSON representation. */
+const UNREPRESENTABLE = Symbol("unrepresentable");
+/**
+ * Returned in place of a value that refers back to itself. It is reported apart
+ * from {@link UNREPRESENTABLE} because the fallback does not cover it: the
+ * wrapper's own marshaler recurses until the runtime aborts, so a caller has to
+ * refuse a cycle rather than hand it over.
+ */
+const CYCLIC = Symbol("cyclic");
+function toJsonTree(value, sidecar, seen, depth) {
+    if (value === null)
+        return null;
+    if (value === undefined)
+        return { [JSON_UNDEFINED_MARKER]: true };
+    switch (typeof value) {
+        case "boolean":
+            return value;
+        case "string":
+            return value.length >= SIDECAR_STRING_THRESHOLD
+                ? { [JSON_SIDECAR_MARKER]: sidecar.push(value) - 1 }
+                : value;
+        case "number":
+            return Number.isFinite(value)
+                ? value
+                : { [JSON_NUMBER_MARKER]: String(value) };
+        case "function":
+        case "symbol":
+        case "bigint":
+            return UNREPRESENTABLE;
+        default:
+            break;
+    }
+    if (depth >= SANDBOX_SERIALIZE_MAX_DEPTH)
+        return UNREPRESENTABLE;
+    if (seen.has(value))
+        return CYCLIC;
+    if (value instanceof Date) {
+        return { [JSON_DATE_MARKER]: value.toISOString() };
+    }
+    if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+        // Bytes cannot ride the sidecar into the guest: a host `Uint8Array` arrives
+        // there as a numeric-keyed object, which is the whole reason the base64
+        // marker exists.
+        const view = value;
+        return {
+            [SANDBOX_BYTES_MARKER]: encodeBase64(new Uint8Array(view.buffer, view.byteOffset, view.byteLength))
+        };
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const out = new Array(value.length);
+            for (let i = 0; i < value.length; i++) {
+                const encoded = toJsonTree(value[i], sidecar, seen, depth + 1);
+                if (encoded === UNREPRESENTABLE || encoded === CYCLIC)
+                    return encoded;
+                out[i] = encoded;
+            }
+            return out;
+        }
+        if (!isPlainObject(value))
+            return UNREPRESENTABLE;
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            const encoded = toJsonTree(entry, sidecar, seen, depth + 1);
+            if (encoded === UNREPRESENTABLE || encoded === CYCLIC)
+                return encoded;
+            out[key] = encoded;
+        }
+        return out;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/**
+ * Encode a batch of named host values for the guest to `JSON.parse` and revive.
+ *
+ * One batch means one sidecar and one parse. An entry holding something JSON
+ * plus the markers cannot carry is reported in `skipped` instead of failing the
+ * batch, so one exotic global costs only itself; an entry that refers back to
+ * itself is reported in `cyclic`, which no path can carry.
+ */
+export function encodeHostRecord(values) {
+    const sidecar = [];
+    const skipped = [];
+    const cyclic = [];
+    const tree = {};
+    for (const [name, value] of Object.entries(values)) {
+        const encoded = toJsonTree(value, sidecar, new Set(), 0);
+        if (encoded === CYCLIC) {
+            cyclic.push(name);
+            continue;
+        }
+        if (encoded === UNREPRESENTABLE) {
+            skipped.push(name);
+            continue;
+        }
+        tree[name] = encoded;
+    }
+    return { json: JSON.stringify(tree), sidecar, skipped, cyclic };
+}
+// ---------------------------------------------------------------------------
+// Guest → host
+// ---------------------------------------------------------------------------
+function reviveHostTree(value, sidecar) {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            value[i] = reviveHostTree(value[i], sidecar);
+        }
+        return value;
+    }
+    if (!isObjectLike(value))
+        return value;
+    const sideIndex = value[JSON_SIDECAR_MARKER];
+    if (typeof sideIndex === "number")
+        return sidecar[sideIndex];
+    const iso = value[JSON_DATE_MARKER];
+    if (typeof iso === "string")
+        return new Date(iso);
+    const nonFinite = value[JSON_NUMBER_MARKER];
+    if (typeof nonFinite === "string")
+        return Number(nonFinite);
+    if (value[JSON_UNDEFINED_MARKER] === true)
+        return undefined;
+    for (const key of Object.keys(value)) {
+        value[key] = reviveHostTree(value[key], sidecar);
+    }
+    return value;
+}
+/**
+ * Decode what the guest's encoder produced: either a JSON string plus the
+ * sidecar its markers index, or a value the guest handed over as-is (a
+ * primitive, or something `JSON.stringify` refused) under `raw`.
+ *
+ * The guest owns this string, so a body that overwrites the encoder can hand
+ * back nonsense. That is not an escalation — the guest owned its own result
+ * either way — so a payload that will not parse decodes as `undefined` rather
+ * than failing the run.
+ */
+export function decodeGuestPayload(payload) {
+    if (!isObjectLike(payload))
+        return payload;
+    const json = payload.j;
+    if (typeof json !== "string") {
+        return "raw" in payload ? payload.raw : undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+    const sidecar = Array.isArray(payload.b) ? payload.b : [];
+    if (!isObjectLike(parsed))
+        return undefined;
+    const revived = reviveHostTree(parsed, sidecar);
+    return isObjectLike(revived) ? revived.v : undefined;
+}
+// ---------------------------------------------------------------------------
+// Guest-side sources
+// ---------------------------------------------------------------------------
+/**
+ * The guest half, spliced into the init prelude: the encoder the entry module
+ * and the sync extractor call, and the parse of whatever globals the host
+ * encoded.
+ *
+ * `__bytesMarker` and `fromBase64` are defined earlier in the prelude, so this
+ * source has to follow them.
+ */
+export const GUEST_JSON_TRANSPORT_SOURCE = `
+const __ntSide = [];
+globalThis.${GUEST_MARSHAL_GLOBAL} = (value) => {
+  // A primitive already crosses as a primitive — stringifying a megabyte of
+  // text only to parse it back on the host is the one trade JSON loses.
+  if (value === null || (typeof value !== "object" && typeof value !== "string")) {
+    return { raw: value };
+  }
+  __ntSide.length = 0;
+  let json;
+  try {
+    json = JSON.stringify({ v: value }, function (key, encoded) {
+      const raw = this[key];
+      if (typeof raw === "string") {
+        return raw.length >= ${SIDECAR_STRING_THRESHOLD}
+          ? { ${JSON.stringify(JSON_SIDECAR_MARKER)}: __ntSide.push(raw) - 1 }
+          : raw;
+      }
+      if (typeof raw === "number" && !Number.isFinite(raw)) {
+        return { ${JSON.stringify(JSON_NUMBER_MARKER)}: String(raw) };
+      }
+      if (raw instanceof Date) {
+        return { ${JSON.stringify(JSON_DATE_MARKER)}: raw.toISOString() };
+      }
+      if (ArrayBuffer.isView(raw) && !(raw instanceof DataView)) {
+        return {
+          ${JSON.stringify(JSON_SIDECAR_MARKER)}: __ntSide.push(
+            raw instanceof Uint8Array
+              ? raw
+              : new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)
+          ) - 1
+        };
+      }
+      if (raw === undefined && encoded === undefined) {
+        return { ${JSON.stringify(JSON_UNDEFINED_MARKER)}: true };
+      }
+      return encoded;
+    });
+  } catch (e) {
+    // A cycle (or a bigint) has no JSON form, and handing the value to the
+    // wrapper's marshaler instead recurses until the runtime aborts. String()
+    // is what serializeResult falls back to for the same values.
+    __ntSide.length = 0;
+    return { raw: String(value) };
+  }
+  // An empty sidecar is left off: an empty array still costs the wrapper a
+  // whole object node to marshal, which is most of a small payload's cost.
+  return __ntSide.length === 0 ? { j: json } : { j: json, b: __ntSide.slice() };
+};
+const __ntReviveHost = (value, side) => {
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) value[i] = __ntReviveHost(value[i], side);
+    return value;
+  }
+  if (!value || typeof value !== "object") return value;
+  const index = value[${JSON.stringify(JSON_SIDECAR_MARKER)}];
+  if (typeof index === "number") return side[index];
+  const bytes = value[__bytesMarker];
+  if (typeof bytes === "string") return globalThis.fromBase64(bytes);
+  const iso = value[${JSON.stringify(JSON_DATE_MARKER)}];
+  if (typeof iso === "string") return new Date(iso);
+  const num = value[${JSON.stringify(JSON_NUMBER_MARKER)}];
+  if (typeof num === "string") return Number(num);
+  if (value[${JSON.stringify(JSON_UNDEFINED_MARKER)}] === true) return undefined;
+  for (const key of Object.keys(value)) value[key] = __ntReviveHost(value[key], side);
+  return value;
+};
+if (typeof globalThis.${GUEST_GLOBALS_JSON_BINDING} === "string") {
+  const __ntHostSide = globalThis.${GUEST_GLOBALS_SIDECAR_BINDING} || [];
+  const __ntGlobals = JSON.parse(globalThis.${GUEST_GLOBALS_JSON_BINDING});
+  delete globalThis.${GUEST_GLOBALS_JSON_BINDING};
+  delete globalThis.${GUEST_GLOBALS_SIDECAR_BINDING};
+  for (const __ntKey of Object.keys(__ntGlobals)) {
+    globalThis[__ntKey] = __ntReviveHost(__ntGlobals[__ntKey], __ntHostSide);
+  }
+}
+`;
+//# sourceMappingURL=sandbox-json-transport.js.map

package/dist/sandbox-json-transport.js.map

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

package/dist/sandbox-media-handle.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Per-run media handles: the currency media transforms trade in instead of
+ * bytes.
+ *
+ * The guest is a courier. In the shape that motivated this — generate two
+ * images, combine them — it never reads a pixel; it only carries each result
+ * to the next host call. Carrying them *as bytes* meant every hop paid a
+ * guest→host copy plus a base64 round trip back, so the guest briefly held
+ * ~2.3× each payload. A chain of three ops on one 1024² image moved the same
+ * image across the boundary six times, and a large enough run leaked enough
+ * engine handles to abort the runtime at teardown — after it had already
+ * computed the answer.
+ *
+ * A handle is plain data (so it crosses as a small object, no marker, no
+ * base64) naming bytes the host holds for the life of the run. `image.*`,
+ * `audio.*`, and `video.*` accept one anywhere they accept bytes and return
+ * one from every transform, so intermediates never enter the guest.
+ *
+ * Intermediates stay in memory rather than becoming assets: a three-op chain
+ * should not write three rows to storage. `media.toImage/toAudio/toVideo` (or
+ * the matching namespace's `toAsset`) explicitly promotes a result.
+ */
+export declare const SANDBOX_MEDIA_HANDLE = "__nodetool_sandbox_media__";
+/** The scheme a handle's `uri` carries, so it reads as a locator in logs. */
+export declare const SANDBOX_MEDIA_SCHEME = "sandbox://media/";
+/**
+ * Total bytes one run may hold in its media store.
+ *
+ * There are per-call ceilings already (`MAX_IMAGE_INPUT_BYTES` 25 MB,
+ * `MAX_MEDIA_REF_BYTES` 16 MB) but nothing bounded the aggregate. A run could
+ * make fifty individually legal calls and die anyway, with an Emscripten
+ * assertion as the only explanation. The store is where an aggregate is
+ * finally countable, so this is the limit that replaces that failure with a
+ * sentence naming what was exceeded.
+ */
+export declare const MAX_RUN_MEDIA_BYTES: number;
+export type SandboxMediaType = "image" | "audio" | "video";
+/** What a handle looks like to the guest. */
+interface SandboxMediaHandle {
+    [SANDBOX_MEDIA_HANDLE]: string;
+    type: SandboxMediaType;
+    uri: string;
+    mimeType: string;
+    byteLength: number;
+    width?: number;
+    height?: number;
+}
+/** Metadata a producer knows and the guest can read without a round trip. */
+export interface SandboxMediaMeta {
+    type?: SandboxMediaType;
+    mimeType?: string;
+    width?: number;
+    height?: number;
+}
+interface SandboxMediaEntry {
+    bytes: Uint8Array;
+    type: SandboxMediaType;
+    mimeType: string;
+}
+export interface SandboxMediaStore {
+    /** Store bytes and return the handle naming them. */
+    put(bytes: Uint8Array, meta?: SandboxMediaMeta): SandboxMediaHandle;
+    /** The bytes behind a handle, or undefined if the value is not one. */
+    resolve(value: unknown, expectedType?: SandboxMediaType): Uint8Array | undefined;
+    /** The bytes and media metadata behind a handle. */
+    entry(value: unknown, expectedType?: SandboxMediaType): SandboxMediaEntry | undefined;
+    /** Whether a value is a handle into *this* store. */
+    isHandle(value: unknown): boolean;
+    /** Bytes currently held, for the budget check and for tests. */
+    totalBytes(): number;
+    /** Drop everything; called when the run ends. */
+    clear(): void;
+}
+/** Whether a value carries the handle marker, whoever minted it. */
+export declare function isSandboxMediaHandle(value: unknown): boolean;
+export declare function createSandboxMediaStore(limitBytes?: number): SandboxMediaStore;
+export {};
+//# sourceMappingURL=sandbox-media-handle.d.ts.map

package/dist/sandbox-media-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-media-handle.d.ts","sourceRoot":"","sources":["../src/sandbox-media-handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,eAAO,MAAM,oBAAoB,+BAA+B,CAAC;AAEjE,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAEvD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,QAAoB,CAAC;AAErD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAE3D,6CAA6C;AAC7C,UAAU,kBAAkB;IAC1B,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,iBAAiB;IACzB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,kBAAkB,CAAC;IACpE,uEAAuE;IACvE,OAAO,CACL,KAAK,EAAE,OAAO,EACd,YAAY,CAAC,EAAE,gBAAgB,GAC9B,UAAU,GAAG,SAAS,CAAC;IAC1B,oDAAoD;IACpD,KAAK,CACH,KAAK,EAAE,OAAO,EACd,YAAY,CAAC,EAAE,gBAAgB,GAC9B,iBAAiB,GAAG,SAAS,CAAC;IACjC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAClC,gEAAgE;IAChE,UAAU,IAAI,MAAM,CAAC;IACrB,iDAAiD;IACjD,KAAK,IAAI,IAAI,CAAC;CACf;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK5D;AAED,wBAAgB,uBAAuB,CACrC,UAAU,GAAE,MAA4B,GACvC,iBAAiB,CAyFnB"}

package/dist/sandbox-media-handle.js

@@ -0,0 +1,114 @@
+/**
+ * Per-run media handles: the currency media transforms trade in instead of
+ * bytes.
+ *
+ * The guest is a courier. In the shape that motivated this — generate two
+ * images, combine them — it never reads a pixel; it only carries each result
+ * to the next host call. Carrying them *as bytes* meant every hop paid a
+ * guest→host copy plus a base64 round trip back, so the guest briefly held
+ * ~2.3× each payload. A chain of three ops on one 1024² image moved the same
+ * image across the boundary six times, and a large enough run leaked enough
+ * engine handles to abort the runtime at teardown — after it had already
+ * computed the answer.
+ *
+ * A handle is plain data (so it crosses as a small object, no marker, no
+ * base64) naming bytes the host holds for the life of the run. `image.*`,
+ * `audio.*`, and `video.*` accept one anywhere they accept bytes and return
+ * one from every transform, so intermediates never enter the guest.
+ *
+ * Intermediates stay in memory rather than becoming assets: a three-op chain
+ * should not write three rows to storage. `media.toImage/toAudio/toVideo` (or
+ * the matching namespace's `toAsset`) explicitly promotes a result.
+ */
+/** Marks an object as a handle into this run's media store. */
+import { isObjectLike, isString } from "./utils/type-guards.js";
+export const SANDBOX_MEDIA_HANDLE = "__nodetool_sandbox_media__";
+/** The scheme a handle's `uri` carries, so it reads as a locator in logs. */
+export const SANDBOX_MEDIA_SCHEME = "sandbox://media/";
+/**
+ * Total bytes one run may hold in its media store.
+ *
+ * There are per-call ceilings already (`MAX_IMAGE_INPUT_BYTES` 25 MB,
+ * `MAX_MEDIA_REF_BYTES` 16 MB) but nothing bounded the aggregate. A run could
+ * make fifty individually legal calls and die anyway, with an Emscripten
+ * assertion as the only explanation. The store is where an aggregate is
+ * finally countable, so this is the limit that replaces that failure with a
+ * sentence naming what was exceeded.
+ */
+export const MAX_RUN_MEDIA_BYTES = 256 * 1024 * 1024;
+/** Whether a value carries the handle marker, whoever minted it. */
+export function isSandboxMediaHandle(value) {
+    return (isObjectLike(value) &&
+        isString(value[SANDBOX_MEDIA_HANDLE]));
+}
+export function createSandboxMediaStore(limitBytes = MAX_RUN_MEDIA_BYTES) {
+    const entries = new Map();
+    let held = 0;
+    let counter = 0;
+    return {
+        put(bytes, meta = {}) {
+            if (held + bytes.length > limitBytes) {
+                throw new Error(`This run has moved ${held + bytes.length} bytes of media, over the ` +
+                    `${limitBytes} byte limit for one run. Process fewer or smaller ` +
+                    `files per action, or save intermediate results as assets and ` +
+                    `reload them in a later action.`);
+            }
+            const id = `m${++counter}`;
+            const type = meta.type ?? "image";
+            const mimeType = meta.mimeType ??
+                (type === "audio"
+                    ? "audio/wav"
+                    : type === "video"
+                        ? "video/mp4"
+                        : "image/png");
+            entries.set(id, { bytes, type, mimeType });
+            held += bytes.length;
+            const handle = {
+                [SANDBOX_MEDIA_HANDLE]: id,
+                type,
+                uri: `${SANDBOX_MEDIA_SCHEME}${id}`,
+                mimeType,
+                byteLength: bytes.length
+            };
+            if (meta.width !== undefined)
+                handle.width = meta.width;
+            if (meta.height !== undefined)
+                handle.height = meta.height;
+            return handle;
+        },
+        entry(value, expectedType) {
+            if (!isSandboxMediaHandle(value))
+                return undefined;
+            const id = value[SANDBOX_MEDIA_HANDLE];
+            const entry = entries.get(id);
+            if (!entry) {
+                // A handle from another run, or one used after its run ended. Say so
+                // rather than falling through to "expected image bytes", which would
+                // send the reader looking at the wrong thing.
+                throw new Error(`${SANDBOX_MEDIA_SCHEME}${id} is not available in this run. A media ` +
+                    `handle only lives for the action that produced it — save it as an ` +
+                    `asset to carry it further.`);
+            }
+            if (expectedType && entry.type !== expectedType) {
+                const article = expectedType === "audio" || expectedType === "image" ? "an" : "a";
+                throw new Error(`Expected ${article} ${expectedType} handle, but ${SANDBOX_MEDIA_SCHEME}${id} ` +
+                    `contains ${entry.type}.`);
+            }
+            return entry;
+        },
+        resolve(value, expectedType) {
+            return this.entry(value, expectedType)?.bytes;
+        },
+        isHandle(value) {
+            if (!isSandboxMediaHandle(value))
+                return false;
+            return entries.has(value[SANDBOX_MEDIA_HANDLE]);
+        },
+        totalBytes: () => held,
+        clear() {
+            entries.clear();
+            held = 0;
+        }
+    };
+}
+//# sourceMappingURL=sandbox-media-handle.js.map

package/dist/sandbox-media-handle.js.map

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