The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(adapter-utils): stream duplex bridge bodies as sequenced chunks with receive-side spill (#12006)
Nicky Leach16b59c9315eb
diff --git a/packages/adapter-utils/src/acpx-engine/execute.test.ts b/packages/adapter-utils/src/acpx-engine/execute.test.tsindex 6f5ae7dff6..217e4f582d 100644--- a/packages/adapter-utils/src/acpx-engine/execute.test.ts+++ b/packages/adapter-utils/src/acpx-engine/execute.test.ts@@ -5763,8 +5763,8 @@ describe("ACPX engine sandbox duplex run-disposition seam (fail-closed)", () =>// Wrap a started real broker in a paperclip bridge handle. The handle exposes// the same run-disposition surface the sandbox bridge exposes, so the seam runs// against the real latch and the real orderly-completion mark.- function bridgeOverBroker(fake: ReturnType<typeof createFakeDuplexChannel>) {- const broker = createDuplexBridgeBroker({+ async function bridgeOverBroker(fake: ReturnType<typeof createFakeDuplexChannel>) {+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),});@@ -5891,7 +5891,7 @@ describe("ACPX engine sandbox duplex run-disposition seam (fail-closed)", () =>it("fails a completed run when the duplex channel was lost before the completion", async () => {const sandbox = await setupRemoteSandbox();const fake = createFakeDuplexChannel();- const { broker, handle, settleRunDisposition } = bridgeOverBroker(fake);+ const { broker, handle, settleRunDisposition } = await bridgeOverBroker(fake);// Latch the loss before the ACP terminal resolves.const runtime = runtimeWithControlledResult(() => fake.emitExit({ exitCode: 1 }));@@ -5912,7 +5912,7 @@ describe("ACPX engine sandbox duplex run-disposition seam (fail-closed)", () =>it("keeps a completed run a success when the channel stays live, and a later teardown loss is benign", async () => {const sandbox = await setupRemoteSandbox();const fake = createFakeDuplexChannel();- const { broker, handle, settleRunDisposition } = bridgeOverBroker(fake);+ const { broker, handle, settleRunDisposition } = await bridgeOverBroker(fake);// No loss before the completion.const runtime = runtimeWithControlledResult();@@ -5932,7 +5932,7 @@ describe("ACPX engine sandbox duplex run-disposition seam (fail-closed)", () =>it("does not let a later completion or activity clear the loss latch", async () => {const sandbox = await setupRemoteSandbox();const fake = createFakeDuplexChannel();- const { broker, handle } = bridgeOverBroker(fake);+ const { broker, handle } = await bridgeOverBroker(fake);// Latch the loss before the ACP terminal resolves.const runtime = runtimeWithControlledResult(() => fake.emitExit({ exitCode: 1 }));@@ -5951,7 +5951,7 @@ describe("ACPX engine sandbox duplex run-disposition seam (fail-closed)", () =>it("marks an orderly completion on a failed terminal so the teardown loss emits no false loss", async () => {const sandbox = await setupRemoteSandbox();const fake = createFakeDuplexChannel();- const { broker, handle, markOrderlyCompletion } = bridgeOverBroker(fake);+ const { broker, handle, markOrderlyCompletion } = await bridgeOverBroker(fake);// The turn fails, and no channel loss ordered before the finalization.const runtime = runtimeWithFailedResult();diff --git a/packages/adapter-utils/src/duplex-body-spool.test.ts b/packages/adapter-utils/src/duplex-body-spool.test.tsnew file mode 100644index 0000000000..37307f2e67--- /dev/null+++ b/packages/adapter-utils/src/duplex-body-spool.test.ts@@ -0,0 +1,306 @@+import { promises as fs } from "node:fs";+import os from "node:os";+import path from "node:path";+import { afterEach, beforeEach, describe, expect, it } from "vitest";++import { DUPLEX_FRAME_VERSION, type DuplexBodyChunkFrame } from "./duplex-frame-codec.js";+import {+ DuplexBodyReceiver,+ type DuplexBodyReceiverConfig,+ splitBodyIntoChunkFrames,+ sweepStaleSpillDirectories,+} from "./duplex-body-spool.js";++// Read the whole reassembled body back, whatever path it took. A memory body+// returns its buffer; a spilled body streams from disk. The test uses this only+// to assert the round-trip content, never on a hot path.+async function readBodyBytes(body: {+ spilled: boolean;+ createReadStream: () => NodeJS.ReadableStream;+}): Promise<Buffer> {+ const chunks: Buffer[] = [];+ for await (const chunk of body.createReadStream()) {+ chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));+ }+ return Buffer.concat(chunks);+}++let spillRoot: string;++beforeEach(async () => {+ spillRoot = await fs.mkdtemp(path.join(os.tmpdir(), "duplex-spool-test-"));+});++afterEach(async () => {+ await fs.rm(spillRoot, { recursive: true, force: true }).catch(() => undefined);+});++function makeReceiver(overrides: DuplexBodyReceiverConfig = {}): Promise<DuplexBodyReceiver> {+ return DuplexBodyReceiver.create({ spillRootDir: spillRoot, ...overrides });+}++const RAW = 8;++// Feed a whole body through a receiver as an envelope plus chunk frames. Return+// the settled body handle. The caller pushes the chunks the split produces.+async function transfer(+ receiver: DuplexBodyReceiver,+ id: string,+ body: Buffer,+): ReturnType<DuplexBodyReceiver["begin"]> {+ const promise = receiver.begin(id, body.length);+ const frames = splitBodyIntoChunkFrames(id, body, DUPLEX_FRAME_VERSION, RAW);+ for (const frame of frames) {+ const result = receiver.pushChunk(frame);+ expect(result.ok).toBe(true);+ }+ return promise;+}++describe("duplex body reassembler — round trip", () => {+ it("reassembles a small body on the memory path", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ const source = Buffer.from("hello duplex body");+ const body = await transfer(receiver, "req-mem", source);+ expect(body.spilled).toBe(false);+ expect(body.byteCount).toBe(source.length);+ expect(body.readMemory().equals(source)).toBe(true);+ expect((await readBodyBytes(body)).equals(source)).toBe(true);+ await body.dispose();+ });++ it("reassembles a large body on the spill path without holding it in memory", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 16, rawChunkBytes: RAW });+ const source = Buffer.from("abcdefghijklmnopqrstuvwxyz0123456789ABCD"); // 40 bytes+ const body = await transfer(receiver, "req-spill", source);+ expect(body.spilled).toBe(true);+ expect(body.byteCount).toBe(source.length);+ // A spilled body never loads the whole body into memory on the receive side.+ expect(() => body.readMemory()).toThrow();+ expect(receiver.spillUsedBytes).toBe(source.length);+ expect(receiver.spillOpenFiles).toBe(1);+ expect((await readBodyBytes(body)).equals(source)).toBe(true);+ await body.dispose();+ // The dispose path unlinks the file and releases the reservation.+ expect(receiver.spillUsedBytes).toBe(0);+ expect(receiver.spillOpenFiles).toBe(0);+ const entries = await fs.readdir(receiver.spillDir);+ expect(entries).toHaveLength(0);+ await receiver.destroy();+ });++ it("completes a zero-length body at once and accepts no chunk", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 16, rawChunkBytes: RAW });+ const body = await receiver.begin("req-zero", 0);+ expect(body.byteCount).toBe(0);+ expect(body.readMemory().length).toBe(0);+ const stray = receiver.pushChunk({+ version: DUPLEX_FRAME_VERSION,+ type: "body_chunk",+ id: "req-zero",+ seq: 0,+ data: Buffer.from("x").toString("base64"),+ });+ expect(stray.ok).toBe(false);+ if (!stray.ok) expect(stray.error.code).toBe("zero_body_has_chunk");+ await body.dispose();+ });+});++describe("duplex body reassembler — rejection matrix", () => {+ function chunk(id: string, seq: number, data: string): DuplexBodyChunkFrame {+ return { version: DUPLEX_FRAME_VERSION, type: "body_chunk", id, seq, data };+ }++ it("rejects a duplicate seq", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ void receiver.begin("d", 16);+ expect(receiver.pushChunk(chunk("d", 0, Buffer.alloc(RAW, 1).toString("base64"))).ok).toBe(true);+ const dup = receiver.pushChunk(chunk("d", 0, Buffer.alloc(RAW, 2).toString("base64")));+ expect(dup.ok).toBe(false);+ if (!dup.ok) expect(dup.error.code).toBe("seq_out_of_order");+ });++ it("rejects a gap in the seq order", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ void receiver.begin("g", 24);+ expect(receiver.pushChunk(chunk("g", 0, Buffer.alloc(RAW, 1).toString("base64"))).ok).toBe(true);+ const gap = receiver.pushChunk(chunk("g", 2, Buffer.alloc(RAW, 2).toString("base64")));+ expect(gap.ok).toBe(false);+ if (!gap.ok) expect(gap.error.code).toBe("seq_out_of_order");+ });++ it("rejects a reordered seq", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ void receiver.begin("r", 24);+ const reorder = receiver.pushChunk(chunk("r", 1, Buffer.alloc(RAW, 1).toString("base64")));+ expect(reorder.ok).toBe(false);+ if (!reorder.ok) expect(reorder.error.code).toBe("seq_out_of_order");+ });++ it("rejects non-canonical base64", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ const begun = receiver.begin("b", 8);+ begun.catch(() => undefined);+ // "AB==" carries non-zero bits in the final sextet, so it decodes to one+ // byte and re-encodes to "AA==". The round-trip mismatch marks it not+ // canonical.+ const bad = receiver.pushChunk(chunk("b", 0, "AB=="));+ expect(bad.ok).toBe(false);+ if (!bad.ok) expect(bad.error.code).toBe("chunk_not_canonical_base64");+ });++ it("rejects a short non-final chunk (truncation)", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ void receiver.begin("t", 24);+ // A non-final chunk must be exactly RAW bytes. A 4-byte chunk that does not+ // complete the 24-byte body is a truncation.+ const truncation = receiver.pushChunk(chunk("t", 0, Buffer.alloc(4, 1).toString("base64")));+ expect(truncation.ok).toBe(false);+ if (!truncation.ok) expect(truncation.error.code).toBe("chunk_wrong_size");+ });++ it("rejects an empty non-final chunk", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ void receiver.begin("e", 16);+ const empty = receiver.pushChunk(chunk("e", 0, ""));+ expect(empty.ok).toBe(false);+ if (!empty.ok) expect(empty.error.code).toBe("empty_chunk");+ });++ it("rejects an overrun past the declared body size", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ // A 12-byte body takes one full RAW chunk, then a final chunk of 4 bytes. A+ // second full RAW chunk overruns the declared size.+ void receiver.begin("o", 12);+ expect(receiver.pushChunk(chunk("o", 0, Buffer.alloc(RAW, 1).toString("base64"))).ok).toBe(true);+ const overrun = receiver.pushChunk(chunk("o", 1, Buffer.alloc(RAW, 2).toString("base64")));+ expect(overrun.ok).toBe(false);+ if (!overrun.ok) expect(overrun.error.code).toBe("body_overrun");+ });++ it("rejects an over-size final chunk", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ void receiver.begin("os", 40);+ const over = receiver.pushChunk(chunk("os", 0, Buffer.alloc(RAW + 4, 1).toString("base64")));+ expect(over.ok).toBe(false);+ if (!over.ok) expect(over.error.code).toBe("chunk_wrong_size");+ });++ it("rejects a chunk that arrives with no matching envelope", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ const orphan = receiver.pushChunk(chunk("missing", 0, Buffer.alloc(RAW, 1).toString("base64")));+ expect(orphan.ok).toBe(false);+ if (!orphan.ok) expect(orphan.error.code).toBe("chunk_without_envelope");+ });++ it("rejects a chunk that arrives after completion", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 1024, rawChunkBytes: RAW });+ const promise = receiver.begin("c", RAW);+ expect(receiver.pushChunk(chunk("c", 0, Buffer.alloc(RAW, 1).toString("base64"))).ok).toBe(true);+ await promise;+ const late = receiver.pushChunk(chunk("c", 1, Buffer.alloc(RAW, 2).toString("base64")));+ expect(late.ok).toBe(false);+ if (!late.ok) expect(late.error.code).toBe("chunk_after_completion");+ });+});++describe("duplex body reassembler — spill caps fail closed", () => {+ it("fails closed when a write exceeds the per-channel byte cap and unlinks the partial file", async () => {+ // A 5-byte cap admits the first RAW=8 chunk write? No: reserve 8 > cap 5, so+ // the first write fails closed. Use a cap that admits one chunk but not two.+ const receiver = await makeReceiver({+ spillThresholdBytes: 4,+ rawChunkBytes: RAW,+ channelSpillByteCap: RAW + 2,+ });+ const promise = receiver.begin("cap", 24);+ expect(receiver.pushChunk({ version: DUPLEX_FRAME_VERSION, type: "body_chunk", id: "cap", seq: 0, data: Buffer.alloc(RAW, 1).toString("base64") }).ok).toBe(true);+ // The second chunk write reserves past the byte cap.+ receiver.pushChunk({ version: DUPLEX_FRAME_VERSION, type: "body_chunk", id: "cap", seq: 1, data: Buffer.alloc(RAW, 2).toString("base64") });+ await expect(promise).rejects.toMatchObject({ code: "spill_cap_exceeded" });+ // The partial file is gone and the reservation released.+ expect(receiver.spillUsedBytes).toBe(0);+ expect(receiver.spillOpenFiles).toBe(0);+ const entries = await fs.readdir(receiver.spillDir);+ expect(entries).toHaveLength(0);+ await receiver.destroy();+ });++ it("fails closed when the open-file cap is reached", async () => {+ const receiver = await makeReceiver({+ spillThresholdBytes: 4,+ rawChunkBytes: RAW,+ channelSpillFileCap: 1,+ });+ // The first spill body claims the one file slot and stays open. The channel+ // dispose rejects this in-flight body, so attach the catch at once.+ const first = receiver.begin("f1", 24);+ first.catch(() => undefined);+ expect(receiver.pushChunk({ version: DUPLEX_FRAME_VERSION, type: "body_chunk", id: "f1", seq: 0, data: Buffer.alloc(RAW, 1).toString("base64") }).ok).toBe(true);+ // The second spill body cannot claim a file slot.+ await expect(receiver.begin("f2", 24)).rejects.toMatchObject({ code: "spill_cap_exceeded" });+ expect(receiver.spillOpenFiles).toBe(1);+ // The dispose of the in-flight first body rejects its begin promise with a+ // terminal channel-closed error and frees the file slot.+ await receiver.disposeBody("f1");+ await expect(first).rejects.toMatchObject({ code: "channel_closed" });+ expect(receiver.spillOpenFiles).toBe(0);+ await receiver.destroy();+ });+});++describe("duplex body reassembler — lifecycle cleanup", () => {+ it("releases the reservation and unlinks the file on channel death", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 4, rawChunkBytes: RAW });+ // The channel death rejects this in-flight body, so attach the catch at once.+ const dying = receiver.begin("death", 24);+ dying.catch(() => undefined);+ expect(receiver.pushChunk({ version: DUPLEX_FRAME_VERSION, type: "body_chunk", id: "death", seq: 0, data: Buffer.alloc(RAW, 1).toString("base64") }).ok).toBe(true);+ // Wait for the write to land, so the file exists before the channel dies.+ await new Promise((resolve) => setTimeout(resolve, 20));+ expect(receiver.spillOpenFiles).toBe(1);+ await receiver.disposeAll();+ await expect(dying).rejects.toMatchObject({ code: "channel_closed" });+ expect(receiver.spillUsedBytes).toBe(0);+ expect(receiver.spillOpenFiles).toBe(0);+ const entries = await fs.readdir(receiver.spillDir);+ expect(entries).toHaveLength(0);+ await receiver.destroy();+ });+});++describe("duplex body reassembler — spill file safety", () => {+ it("creates the spill directory with mode 0700 and each spill file with mode 0600", async () => {+ const receiver = await makeReceiver({ spillThresholdBytes: 4, rawChunkBytes: RAW });+ const dirStat = await fs.stat(receiver.spillDir);+ expect(dirStat.mode & 0o777).toBe(0o700);+ // The final destroy rejects this in-flight body, so attach the catch at once.+ const pending = receiver.begin("mode", 8);+ pending.catch(() => undefined);+ receiver.pushChunk({ version: DUPLEX_FRAME_VERSION, type: "body_chunk", id: "mode", seq: 0, data: Buffer.alloc(RAW, 1).toString("base64") });+ await new Promise((resolve) => setTimeout(resolve, 20));+ const entries = await fs.readdir(receiver.spillDir);+ expect(entries).toHaveLength(1);+ // The file name is random, so no frame id rides the path.+ expect(entries[0]).not.toContain("mode");+ const fileStat = await fs.stat(path.join(receiver.spillDir, entries[0]));+ expect(fileStat.mode & 0o777).toBe(0o600);+ await receiver.destroy();+ });+});++describe("duplex body reassembler — startup sweep", () => {+ it("removes a stale spill directory from a dead process but keeps a live one", async () => {+ const deadPid = 999999; // A pid that is almost never alive.+ const staleDir = path.join(spillRoot, `paperclip-duplex-spill-${deadPid}-stale`);+ await fs.mkdir(staleDir);+ await fs.writeFile(path.join(staleDir, "leftover.body"), "x");+ const liveDir = path.join(spillRoot, `paperclip-duplex-spill-${process.pid}-live`);+ await fs.mkdir(liveDir);+ await sweepStaleSpillDirectories(spillRoot);+ await expect(fs.stat(staleDir)).rejects.toThrow();+ // The sweep keeps a directory that belongs to a live process.+ await expect(fs.stat(liveDir)).resolves.toBeDefined();+ });+});diff --git a/packages/adapter-utils/src/duplex-body-spool.ts b/packages/adapter-utils/src/duplex-body-spool.tsnew file mode 100644index 0000000000..576caca5af--- /dev/null+++ b/packages/adapter-utils/src/duplex-body-spool.ts@@ -0,0 +1,596 @@+/**+ * Receive-side body reassembly and spill for the sandbox duplex channel.+ *+ * The duplex codec splits one request body or one response body into an envelope+ * frame plus a sequence of `body_chunk` frames. This module reassembles those+ * chunks back into one body. The receiver reads `bodyByteCount` from the envelope+ * first, then chooses one of two paths before it reads the first chunk:+ * - memory path: a body at or below the spill threshold stays in a memory+ * buffer.+ * - spill path: a body above the spill threshold streams to a temporary file,+ * so the receiver never holds a whole large body in memory.+ *+ * The spill path bounds the disk a single channel can consume. A per-channel+ * arena caps the bytes on disk and the number of open spill files. The receiver+ * reserves a file slot and reserves bytes before it opens a file and before each+ * write. A reserve that exceeds a cap fails closed: it rejects the body as a+ * resource error and unlinks any partial file.+ *+ * The reassembler treats every frame as untrusted. It rejects a bad chunk as a+ * loud, terminal protocol error: a non-canonical base64 payload, a wrong chunk+ * size, an out-of-order `seq`, a total that does not equal `bodyByteCount`, or a+ * chunk that arrives for a completed or unknown body.+ */++import { randomBytes } from "node:crypto";+import { createReadStream } from "node:fs";+import { promises as fs } from "node:fs";+import type { FileHandle } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { Readable } from "node:stream";++import {+ DUPLEX_BODY_CHUNK_RAW_BYTES,+ type DuplexBodyChunkFrame,+} from "./duplex-frame-codec.js";++/**+ * The default spill threshold, in bytes. A body at or below this size stays in+ * memory. A body above it spills to disk. The value is 1 MiB. It stays+ * injectable so a test can lower it and exercise the spill path.+ */+export const DEFAULT_DUPLEX_BODY_SPILL_THRESHOLD_BYTES = 1024 * 1024;++/**+ * The default per-channel spill byte cap. The receiver keeps at most this many+ * bytes on disk at one time for one channel. The value is 64 MiB. It is about+ * 0.64% of the default 10 GiB sandbox disk and stays far below the security+ * ceiling of 25% of the disk quota. It stays injectable so a test can lower it.+ */+export const DEFAULT_DUPLEX_CHANNEL_SPILL_BYTE_CAP = 64 * 1024 * 1024;++/**+ * The default per-channel open-file cap. The receiver keeps at most this many+ * spill files open at one time for one channel. The value derives from the byte+ * cap and the spill threshold: 64 MiB divided by the 1 MiB spill floor gives 64.+ * It stays injectable so a test can lower it.+ */+export const DEFAULT_DUPLEX_CHANNEL_SPILL_FILE_CAP = 64;++/** The prefix of every spill directory name. The startup sweep matches it. */+const SPILL_DIR_PREFIX = "paperclip-duplex-spill-";++/** The config a caller passes to build a {@link DuplexBodyReceiver}. */+export interface DuplexBodyReceiverConfig {+ /** The spill threshold in bytes. Defaults to {@link DEFAULT_DUPLEX_BODY_SPILL_THRESHOLD_BYTES}. */+ spillThresholdBytes?: number;+ /** The fixed raw chunk size in bytes. Defaults to {@link DUPLEX_BODY_CHUNK_RAW_BYTES}. */+ rawChunkBytes?: number;+ /** The per-channel spill byte cap. Defaults to {@link DEFAULT_DUPLEX_CHANNEL_SPILL_BYTE_CAP}. */+ channelSpillByteCap?: number;+ /** The per-channel open-file cap. Defaults to {@link DEFAULT_DUPLEX_CHANNEL_SPILL_FILE_CAP}. */+ channelSpillFileCap?: number;+ /** The root directory that holds the spill directory. Defaults to the OS temp dir. */+ spillRootDir?: string;+ /** A diagnostic sink for a non-fatal cleanup note. The receiver names no body id here. */+ logger?: (message: string) => void;+}++/** The reason the reassembler rejected a body. Each reason is a terminal protocol error. */+export type DuplexBodyErrorCode =+ | "chunk_without_envelope"+ | "chunk_after_completion"+ | "seq_out_of_order"+ | "chunk_not_canonical_base64"+ | "chunk_wrong_size"+ | "empty_chunk"+ | "body_overrun"+ | "zero_body_has_chunk"+ | "spill_cap_exceeded"+ | "spill_write_failed"+ | "path_escape"+ | "channel_closed";++/** A reassembly error. The receiver returns it; it never leaks a raw path or a raw provider string. */+export class DuplexBodyError extends Error {+ readonly code: DuplexBodyErrorCode;+ constructor(code: DuplexBodyErrorCode, message: string) {+ super(message);+ this.name = "DuplexBodyError";+ this.code = code;+ }+}++/**+ * One reassembled body. The memory path holds the whole body in a buffer. The+ * spill path holds a temporary file. A caller reads the memory buffer, or opens+ * a fresh read stream, then disposes the body once.+ */+export interface ReassembledBody {+ /** The raw byte length of the body. */+ readonly byteCount: number;+ /** True when the body spilled to disk. */+ readonly spilled: boolean;+ /**+ * The whole body as a buffer. The memory path returns it. The spill path+ * throws, because the spill path must never load a whole large body into+ * memory on the receive side. A caller streams a spilled body instead.+ */+ readMemory(): Buffer;+ /** A fresh read stream over the body. The memory path streams one buffer; the spill path streams the file. */+ createReadStream(): Readable;+ /** Release the body. The spill path unlinks the file and releases the reservation exactly once. */+ dispose(): Promise<void>;+}++/**+ * The per-channel arena that bounds the spill disk use. It tracks the bytes on+ * disk and the open files, and it owns the spill directory. It hands out+ * reservations and takes them back. The reservation math is synchronous, so a+ * concurrent reserve never races past a cap.+ */+class SpillArena {+ usedBytes = 0;+ openFiles = 0;+ constructor(+ readonly dir: string,+ private readonly byteCap: number,+ private readonly fileCap: number,+ ) {}++ /** Reserve one open-file slot. Return false when the file cap is already at the limit. */+ reserveFile(): boolean {+ if (this.openFiles >= this.fileCap) return false;+ this.openFiles += 1;+ return true;+ }++ /** Release one open-file slot. */+ releaseFile(): void {+ if (this.openFiles > 0) this.openFiles -= 1;+ }++ /** Reserve `n` bytes of disk. Return false when the byte cap would be exceeded. */+ reserveBytes(n: number): boolean {+ if (this.usedBytes + n > this.byteCap) return false;+ this.usedBytes += n;+ return true;+ }++ /** Release `n` bytes of disk. */+ releaseBytes(n: number): void {+ this.usedBytes -= n;+ if (this.usedBytes < 0) this.usedBytes = 0;+ }+}++/** The internal state of one in-flight body. */+interface ActiveBody {+ bodyByteCount: number;+ nextSeq: number;+ receivedBytes: number;+ spilled: boolean;+ /** Memory-path accumulation. Empty for the spill path. */+ memoryChunks: Buffer[];+ /** The spill file path. Null for the memory path. */+ filePath: string | null;+ /** The open spill file handle. Null for the memory path or before the first write. */+ handle: FileHandle | null;+ /** The bytes this body reserved in the arena. The dispose path releases exactly this many. */+ reservedBytes: number;+ /** True when the body holds an arena file slot that the dispose path must release. */+ holdsFileSlot: boolean;+ /** True once the dispose path ran, so it runs its release once. */+ disposed: boolean;+ /** Resolve the completion promise the caller awaits. */+ resolve: (body: ReassembledBody) => void;+ /** Reject the completion promise on a terminal error. */+ reject: (error: DuplexBodyError) => void;+ /** Serialize the spill writes, so the chunks land on disk in `seq` order. */+ writeChain: Promise<void>;+ /** True once the body settled (resolved or rejected), so a late chunk never double-settles. */+ settled: boolean;+}++/** The synchronous result of one `pushChunk` call. */+export type DuplexBodyPushResult =+ | { ok: true }+ | { ok: false; error: DuplexBodyError };++/**+ * A per-channel receive-side body reassembler. One instance serves one channel.+ * The caller feeds it one envelope per body, then the `body_chunk` frames for+ * that body. The reassembler reassembles the body on the memory path or the+ * spill path and settles one completion promise per body.+ */+export class DuplexBodyReceiver {+ private readonly spillThresholdBytes: number;+ private readonly rawChunkBytes: number;+ private readonly arena: SpillArena;+ private readonly logger?: (message: string) => void;+ private readonly active = new Map<string, ActiveBody>();++ private constructor(arena: SpillArena, config: DuplexBodyReceiverConfig) {+ this.arena = arena;+ this.spillThresholdBytes =+ config.spillThresholdBytes ?? DEFAULT_DUPLEX_BODY_SPILL_THRESHOLD_BYTES;+ this.rawChunkBytes = config.rawChunkBytes ?? DUPLEX_BODY_CHUNK_RAW_BYTES;+ this.logger = config.logger;+ }++ /**+ * Build a receiver. The receiver owns the spill directory. It creates the+ * directory with `mkdtemp` and mode 0700, then sweeps stale spill directories+ * from a prior process. The sweep runs and awaits before the receiver serves a+ * body, so no caller races a half-swept directory.+ */+ static async create(config: DuplexBodyReceiverConfig = {}): Promise<DuplexBodyReceiver> {+ const root = config.spillRootDir ?? os.tmpdir();+ await sweepStaleSpillDirectories(root, config.logger);+ const dir = await fs.mkdtemp(path.join(root, `${SPILL_DIR_PREFIX}${process.pid}-`));+ // `mkdtemp` creates the directory with mode 0700 on a POSIX host by default,+ // but a permissive umask can widen it. Set the mode so the owner alone reads,+ // writes, and lists the spill directory.+ await fs.chmod(dir, 0o700);+ const arena = new SpillArena(+ dir,+ config.channelSpillByteCap ?? DEFAULT_DUPLEX_CHANNEL_SPILL_BYTE_CAP,+ config.channelSpillFileCap ?? DEFAULT_DUPLEX_CHANNEL_SPILL_FILE_CAP,+ );+ return new DuplexBodyReceiver(arena, config);+ }++ /** The spill directory this receiver owns. A test reads it to assert containment and cleanup. */+ get spillDir(): string {+ return this.arena.dir;+ }++ /** The bytes on disk across all in-flight bodies for this channel. A test asserts the reservation. */+ get spillUsedBytes(): number {+ return this.arena.usedBytes;+ }++ /** The open spill files for this channel. A test asserts the file-slot reservation. */+ get spillOpenFiles(): number {+ return this.arena.openFiles;+ }++ /**+ * Begin one body. The caller passes the envelope `id` and `bodyByteCount`. The+ * receiver chooses the memory path or the spill path from `bodyByteCount`+ * before the first chunk arrives. A `bodyByteCount` of 0 completes at once with+ * an empty body and accepts no chunk. The returned promise resolves with the+ * reassembled body, or rejects with a {@link DuplexBodyError} on a terminal+ * protocol or resource error.+ */+ begin(id: string, bodyByteCount: number): Promise<ReassembledBody> {+ return new Promise<ReassembledBody>((resolve, reject) => {+ // A repeated envelope id for an in-flight body is a protocol violation. The+ // caller must not begin the same id twice. Reject the new begin and leave+ // the in-flight body untouched.+ if (this.active.has(id)) {+ reject(new DuplexBodyError("chunk_after_completion", "duplicate body envelope id"));+ return;+ }+ const body: ActiveBody = {+ bodyByteCount,+ nextSeq: 0,+ receivedBytes: 0,+ spilled: bodyByteCount > this.spillThresholdBytes,+ memoryChunks: [],+ filePath: null,+ handle: null,+ reservedBytes: 0,+ holdsFileSlot: false,+ disposed: false,+ resolve,+ reject,+ writeChain: Promise.resolve(),+ settled: false,+ };+ this.active.set(id, body);+ if (bodyByteCount === 0) {+ // The zero-length body completes at once. It accepts no chunk, so the+ // receiver keeps the id in a completed state to reject a stray chunk.+ this.complete(id, body);+ return;+ }+ if (body.spilled) {+ // Reserve one file slot before the receiver opens the spill file. A+ // reserve past the file cap fails closed at once.+ if (!this.arena.reserveFile()) {+ this.settleReject(id, body, new DuplexBodyError("spill_cap_exceeded", "spill file cap reached"));+ return;+ }+ body.holdsFileSlot = true;+ // Open the spill file with a random name and mode 0600. The name never+ // derives from the frame id, so no id rides a path. Verify the resolved+ // path stays inside the spill directory before the receiver writes.+ this.openSpillFile(id, body);+ }+ });+ }++ /**+ * Push one `body_chunk` frame. The receiver validates the chunk against the+ * in-flight body, then appends it on the memory path or the spill path. The+ * return value reports a synchronous validation outcome. A spill write failure+ * or a completion rejects the begin promise instead.+ */+ pushChunk(frame: DuplexBodyChunkFrame): DuplexBodyPushResult {+ const body = this.active.get(frame.id);+ if (!body) {+ return fail("chunk_without_envelope", "body_chunk arrived with no matching envelope");+ }+ if (body.bodyByteCount === 0) {+ return fail("zero_body_has_chunk", "a zero-length body accepts no body_chunk");+ }+ if (body.settled) {+ return fail("chunk_after_completion", "body_chunk arrived after the body completed");+ }+ if (frame.seq !== body.nextSeq) {+ return fail("seq_out_of_order", "body_chunk seq is a duplicate, a gap, or a reorder");+ }+ // Decode the base64 payload and confirm it is canonical. A non-canonical+ // payload re-encodes to a different string, so the round-trip catches it.+ const decoded = Buffer.from(frame.data, "base64");+ if (decoded.toString("base64") !== frame.data) {+ return fail("chunk_not_canonical_base64", "body_chunk data is not canonical base64");+ }+ if (decoded.length === 0) {+ return fail("empty_chunk", "body_chunk is empty");+ }+ const nextReceived = body.receivedBytes + decoded.length;+ if (nextReceived > body.bodyByteCount) {+ return fail("body_overrun", "body_chunk overruns the declared body size");+ }+ const isFinal = nextReceived === body.bodyByteCount;+ if (!isFinal && decoded.length !== this.rawChunkBytes) {+ // A non-final chunk must be exactly the fixed raw slice size. A short+ // non-final chunk is a truncation; an over-size chunk is a framing fault.+ return fail("chunk_wrong_size", "a non-final body_chunk is not the fixed slice size");+ }+ if (decoded.length > this.rawChunkBytes) {+ // The final chunk must also stay within the fixed raw slice size.+ return fail("chunk_wrong_size", "a body_chunk exceeds the fixed slice size");+ }+ body.nextSeq += 1;+ body.receivedBytes = nextReceived;+ if (body.spilled) {+ this.appendSpill(frame.id, body, decoded, isFinal);+ } else {+ body.memoryChunks.push(decoded);+ if (isFinal) this.complete(frame.id, body);+ }+ return { ok: true };+ }++ /**+ * Dispose one body by id, whatever its state. The dispose path unlinks the+ * spill file and releases the arena reservation exactly once. The caller runs+ * it on every settle path and on channel death, so a spill file never lingers.+ */+ async disposeBody(id: string): Promise<void> {+ const body = this.active.get(id);+ if (!body) return;+ this.active.delete(id);+ await this.release(body);+ }++ /**+ * Dispose every in-flight body. The caller runs it on channel death, so a+ * channel that dies mid-body leaves no spill file behind.+ */+ async disposeAll(): Promise<void> {+ const ids = [...this.active.keys()];+ await Promise.all(ids.map((id) => this.disposeBody(id)));+ }++ /**+ * Remove the spill directory this receiver owns. The caller runs it after it+ * disposes every body, on channel shutdown.+ */+ async destroy(): Promise<void> {+ await this.disposeAll();+ await fs.rm(this.arena.dir, { recursive: true, force: true }).catch(() => undefined);+ }++ private openSpillFile(id: string, body: ActiveBody): void {+ const name = `${randomBytes(24).toString("hex")}.body`;+ const filePath = path.join(this.arena.dir, name);+ // Path containment. The resolved file path must stay inside the spill+ // directory. A generated random name never escapes, but the check is defense+ // in depth against a future name scheme.+ const resolvedDir = path.resolve(this.arena.dir);+ const resolvedFile = path.resolve(filePath);+ if (resolvedFile !== path.join(resolvedDir, name) || !resolvedFile.startsWith(resolvedDir + path.sep)) {+ this.settleReject(id, body, new DuplexBodyError("path_escape", "spill path escapes the spill directory"));+ return;+ }+ body.filePath = filePath;+ // Open the file once, exclusive, mode 0600. The write chain appends each+ // chunk in order to this one handle.+ body.writeChain = body.writeChain.then(async () => {+ body.handle = await fs.open(filePath, "wx", 0o600);+ });+ body.writeChain.catch((error) => {+ this.settleReject(id, body, new DuplexBodyError("spill_write_failed", errorText(error)));+ });+ }++ private appendSpill(id: string, body: ActiveBody, decoded: Buffer, isFinal: boolean): void {+ // Reserve the bytes before the write. A reserve past the byte cap fails+ // closed: reject the body and unlink the partial file.+ if (!this.arena.reserveBytes(decoded.length)) {+ this.settleReject(id, body, new DuplexBodyError("spill_cap_exceeded", "spill byte cap reached"));+ return;+ }+ body.reservedBytes += decoded.length;+ body.writeChain = body.writeChain.then(async () => {+ if (body.settled) return;+ if (!body.handle) throw new Error("spill file handle is not open");+ await body.handle.write(decoded);+ if (isFinal) {+ await body.handle.close();+ body.handle = null;+ this.complete(id, body);+ }+ });+ body.writeChain.catch((error) => {+ if (error instanceof DuplexBodyError) return;+ this.settleReject(id, body, new DuplexBodyError("spill_write_failed", errorText(error)));+ });+ }++ private complete(id: string, body: ActiveBody): void {+ if (body.settled) return;+ body.settled = true;+ const receiver = this;+ const handle: ReassembledBody = {+ byteCount: body.bodyByteCount,+ spilled: body.spilled,+ readMemory(): Buffer {+ if (body.spilled) {+ throw new DuplexBodyError("spill_write_failed", "a spilled body has no in-memory buffer");+ }+ return Buffer.concat(body.memoryChunks);+ },+ createReadStream(): Readable {+ if (body.spilled && body.filePath) return createReadStream(body.filePath);+ return Readable.from(Buffer.concat(body.memoryChunks));+ },+ async dispose(): Promise<void> {+ await receiver.disposeBody(id);+ },+ };+ body.resolve(handle);+ }++ private settleReject(id: string, body: ActiveBody, error: DuplexBodyError): void {+ if (body.settled) return;+ body.settled = true;+ // Release the reservation and unlink the partial file before the reject, so+ // a rejected body never keeps a spill file or a reservation. The reject fires+ // after the release, so a caller that awaits the reject sees a clean arena.+ void this.disposeBody(id).finally(() => body.reject(error));+ }++ private async release(body: ActiveBody): Promise<void> {+ if (body.disposed) return;+ body.disposed = true;+ // Wait for the pending writes to settle, so the unlink never races an open+ // handle. Swallow a write error here; the reject path already reported it.+ await body.writeChain.catch(() => undefined);+ if (body.handle) {+ await body.handle.close().catch(() => undefined);+ body.handle = null;+ }+ if (body.filePath) {+ await fs.rm(body.filePath, { force: true }).catch((error) => {+ this.logger?.(`Duplex spill unlink failed: ${errorText(error)}`);+ });+ }+ if (body.reservedBytes > 0) {+ this.arena.releaseBytes(body.reservedBytes);+ body.reservedBytes = 0;+ }+ if (body.holdsFileSlot) {+ this.arena.releaseFile();+ body.holdsFileSlot = false;+ }+ // A body that the channel disposes before it settles must not leave its+ // begin promise pending. Reject it with a terminal channel-closed error, so+ // a caller that awaits the body sees the channel death. A body that already+ // settled keeps its outcome: `complete` resolves it, and `settleReject` sets+ // `settled` before it calls dispose, so this guard never double-settles.+ if (!body.settled) {+ body.settled = true;+ body.reject(+ new DuplexBodyError("channel_closed", "the channel closed before the body completed"),+ );+ }+ }+}++function fail(code: DuplexBodyErrorCode, message: string): DuplexBodyPushResult {+ return { ok: false, error: new DuplexBodyError(code, message) };+}++function errorText(error: unknown): string {+ return error instanceof Error ? error.message : String(error);+}++/**+ * Split a whole body buffer into `body_chunk` frames. The send side reads the+ * source body once, then calls this to build the frames. Each frame carries one+ * raw slice of `rawChunkBytes` as base64 text, except the final frame, which+ * carries the remaining bytes. A zero-length body yields no frame.+ */+export function splitBodyIntoChunkFrames(+ id: string,+ body: Buffer,+ version: number,+ rawChunkBytes: number = DUPLEX_BODY_CHUNK_RAW_BYTES,+): DuplexBodyChunkFrame[] {+ const frames: DuplexBodyChunkFrame[] = [];+ let seq = 0;+ for (let offset = 0; offset < body.length; offset += rawChunkBytes) {+ const slice = body.subarray(offset, offset + rawChunkBytes);+ frames.push({+ version,+ type: "body_chunk",+ id,+ seq,+ data: slice.toString("base64"),+ });+ seq += 1;+ }+ return frames;+}++/**+ * Sweep stale spill directories from a prior process. The receiver runs it at+ * startup, before it serves a body. It removes a spill directory whose embedded+ * pid is not this process and is not a live process, so a crash that left a+ * directory behind does not leak disk. It never removes a directory of a live+ * process, so a concurrent channel keeps its own spill directory.+ */+export async function sweepStaleSpillDirectories(+ root: string,+ logger?: (message: string) => void,+): Promise<void> {+ const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);+ await Promise.all(+ entries.map(async (entry) => {+ if (!entry.isDirectory() || !entry.name.startsWith(SPILL_DIR_PREFIX)) return;+ const pid = parsePidFromSpillDir(entry.name);+ if (pid !== null && pid !== process.pid && isProcessAlive(pid)) return;+ if (pid === process.pid) return;+ await fs.rm(path.join(root, entry.name), { recursive: true, force: true }).catch((error) => {+ logger?.(`Duplex stale spill sweep failed: ${errorText(error)}`);+ });+ }),+ );+}++/** Read the pid segment from a spill directory name, or null when it is absent. */+function parsePidFromSpillDir(name: string): number | null {+ const rest = name.slice(SPILL_DIR_PREFIX.length);+ const dash = rest.indexOf("-");+ const pidText = dash === -1 ? rest : rest.slice(0, dash);+ const pid = Number(pidText);+ return Number.isInteger(pid) && pid > 0 ? pid : null;+}++/** Return true when a process with the pid is alive. A signal 0 probes without a real signal. */+function isProcessAlive(pid: number): boolean {+ try {+ process.kill(pid, 0);+ return true;+ } catch (error) {+ // EPERM means the process exists but this process cannot signal it. ESRCH+ // means no such process. Treat only ESRCH as dead.+ return (error as NodeJS.ErrnoException).code === "EPERM";+ }+}diff --git a/packages/adapter-utils/src/duplex-bridge-broker-byte-ledger.test.ts b/packages/adapter-utils/src/duplex-bridge-broker-byte-ledger.test.tsindex 78780c9ff5..ff901dd1d9 100644--- a/packages/adapter-utils/src/duplex-bridge-broker-byte-ledger.test.ts+++ b/packages/adapter-utils/src/duplex-bridge-broker-byte-ledger.test.ts@@ -16,6 +16,7 @@ import {type DuplexRequestFrame,type DuplexResponseFrame,} from "./duplex-frame-codec.js";+import { splitBodyIntoChunkFrames } from "./duplex-body-spool.js";import type { CommandManagedDuplexChannel } from "./command-managed-runtime.js";/**@@ -35,41 +36,83 @@ interface PendingForward {settled: boolean;}+/**+ * One reassembled response the broker wrote back. The broker writes a response as+ * one envelope frame that carries `bodyByteCount`, then the `body_chunk` frames+ * that carry the body. The harness reassembles the body and exposes it as `body`.+ */+type ReassembledResponse = DuplexResponseFrame & { body: string };++/** One request the harness feeds: the envelope frame plus its raw body text. */+interface RequestInput {+ frame: DuplexRequestFrame;+ bodyText: string;+}+/** The in-memory channel plus the levers a test uses to drive the broker. */interface FakeChannelHarness {channel: CommandManagedDuplexChannel;- feed: (frame: DuplexRequestFrame) => void;+ feed: (input: RequestInput) => void;exit: () => void;- responses: DuplexResponseFrame[];+ responses: ReassembledResponse[];forwards: PendingForward[];resolveForward: (id: string, body?: string) => void;}-/** Build one valid request frame. */-function requestFrame(id: string, method = "POST"): DuplexRequestFrame {+/** Build one valid request: the envelope carries `bodyByteCount`, the body rides body_chunk frames. */+function requestFrame(id: string, method = "POST"): RequestInput {+ const bodyText = JSON.stringify({ id });return {- version: DUPLEX_FRAME_VERSION,- type: "request",- id,- method,- path: `/api/issues/${id}`,- query: "",- headers: { "content-type": "application/json" },- body: JSON.stringify({ id }),+ frame: {+ version: DUPLEX_FRAME_VERSION,+ type: "request",+ id,+ method,+ path: `/api/issues/${id}`,+ query: "",+ headers: { "content-type": "application/json" },+ bodyByteCount: Buffer.byteLength(bodyText, "utf8"),+ },+ bodyText,};}function createFakeChannelHarness(): FakeChannelHarness {- const responses: DuplexResponseFrame[] = [];+ const responses: ReassembledResponse[] = [];const forwards: PendingForward[] = [];const writtenDecoder = new DuplexFrameDecoder();+ const responseAssembly = new Map<+ string,+ { frame: DuplexResponseFrame; received: number; chunks: Buffer[] }+ >();let dataListener: ((chunk: string) => void) | null = null;let exitListener: ((exit: { exitCode: number | null }) => void) | null = null;const channel: CommandManagedDuplexChannel = {write: (data) => {for (const result of writtenDecoder.push(data)) {- if (result.ok && result.frame.type === "response") responses.push(result.frame);+ if (!result.ok) continue;+ const frame = result.frame;+ if (frame.type === "response") {+ if (frame.bodyByteCount === 0) {+ responses.push({ ...frame, body: "" });+ } else {+ responseAssembly.set(frame.id, { frame, received: 0, chunks: [] });+ }+ } else if (frame.type === "body_chunk") {+ const assembly = responseAssembly.get(frame.id);+ if (!assembly) continue;+ const decoded = Buffer.from(frame.data, "base64");+ assembly.received += decoded.length;+ assembly.chunks.push(decoded);+ if (assembly.received >= assembly.frame.bodyByteCount) {+ responseAssembly.delete(frame.id);+ responses.push({+ ...assembly.frame,+ body: Buffer.concat(assembly.chunks).toString("utf8"),+ });+ }+ }}},onData: (listener) => {@@ -84,9 +127,18 @@ function createFakeChannelHarness(): FakeChannelHarness {return {channel,- feed: (frame) => {+ feed: ({ frame, bodyText }) => {if (!dataListener) throw new Error("The broker did not bind the data listener.");dataListener(encodeDuplexFrame(frame));+ if (bodyText.length > 0) {+ for (const chunk of splitBodyIntoChunkFrames(+ frame.id,+ Buffer.from(bodyText, "utf8"),+ DUPLEX_FRAME_VERSION,+ )) {+ dataListener(encodeDuplexFrame(chunk));+ }+ }},exit: () => {if (!exitListener) throw new Error("The broker did not bind the exit listener.");@@ -111,10 +163,12 @@ function controllableForward(harness: FakeChannelHarness) {});}-/** Wait for the microtask queue to drain, so a settled promise runs its handlers. */+/**+ * Wait for the microtasks and one macrotask to settle, so the broker reassembles+ * a request body, dispatches its forward, and runs each settled promise handler.+ */async function flush(): Promise<void> {- await Promise.resolve();- await Promise.resolve();+ await new Promise((resolve) => setTimeout(resolve, 0));}describe("duplex bridge broker aggregate byte ledger", () => {@@ -130,7 +184,7 @@ describe("duplex bridge broker aggregate byte ledger", () => {it("charges request-frame, request-payload, and seen-id tokens, then releases the request tokens on forward settlement", async () => {const harness = createFakeChannelHarness();const ledger = new DuplexAggregateByteLedger({ ceilingBytes: 1_000_000 });- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),duplexAggregateByteLedger: ledger,@@ -139,12 +193,15 @@ describe("duplex bridge broker aggregate byte ledger", () => {broker.start();harness.feed(requestFrame("req-1"));- // The dispatch retains three tokens: the raw frame, the normalized payload,- // and the no-replay set entry.+ // The dispatch retains three tokens at the request envelope: the raw frame, the+ // normalized payload, and the no-replay set entry. The reservation is+ // synchronous, so the charge holds before the body reassembles.expect(ledger.liveTokenCount).toBe(3);expect(ledger.bytesInUse).toBeGreaterThan(0);const chargedInFlight = ledger.bytesInUse;+ // The broker reassembles the request body, then dispatches the forward.+ await flush();harness.resolveForward("req-1");await flush();@@ -164,7 +221,7 @@ describe("duplex bridge broker aggregate byte ledger", () => {it("keeps request tokens charged when the response timer answers before the forward settles, and releases them on settlement", async () => {const harness = createFakeChannelHarness();const ledger = new DuplexAggregateByteLedger({ ceilingBytes: 1_000_000 });- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),// Squeeze the nested budgets so the response timer fires quickly while the@@ -202,7 +259,7 @@ describe("duplex bridge broker aggregate byte ledger", () => {// can size a ceiling one byte below it and force the reservation to fail.const probeHarness = createFakeChannelHarness();const measured = new DuplexAggregateByteLedger({ ceilingBytes: 1_000_000 });- const measuringBroker = createDuplexBridgeBroker({+ const measuringBroker = await createDuplexBridgeBroker({channel: probeHarness.channel,forwardRequest: controllableForward(probeHarness),duplexAggregateByteLedger: measured,@@ -213,7 +270,7 @@ describe("duplex bridge broker aggregate byte ledger", () => {await measuringBroker.close();const ledger = new DuplexAggregateByteLedger({ ceilingBytes: perRequestBytes - 1 });- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),duplexAggregateByteLedger: ledger,@@ -238,7 +295,7 @@ describe("duplex bridge broker aggregate byte ledger", () => {// admitted: raise the ceiling and re-feed.const roomyLedger = new DuplexAggregateByteLedger({ ceilingBytes: 1_000_000 });const roomyHarness = createFakeChannelHarness();- const roomyBroker = createDuplexBridgeBroker({+ const roomyBroker = await createDuplexBridgeBroker({channel: roomyHarness.channel,forwardRequest: controllableForward(roomyHarness),duplexAggregateByteLedger: roomyLedger,@@ -246,13 +303,14 @@ describe("duplex bridge broker aggregate byte ledger", () => {brokers.push(roomyBroker);roomyBroker.start();roomyHarness.feed(requestFrame("req-1"));+ await flush();expect(roomyHarness.forwards.length).toBe(1);});it("releases every retained token on a terminal channel loss", async () => {const harness = createFakeChannelHarness();const ledger = new DuplexAggregateByteLedger({ ceilingBytes: 1_000_000 });- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),duplexAggregateByteLedger: ledger,@@ -262,8 +320,14 @@ describe("duplex bridge broker aggregate byte ledger", () => {harness.feed(requestFrame("req-1"));harness.feed(requestFrame("req-2"));+ // The reservation is synchronous, so both dispatches charge three tokens each+ // at the request envelope, before the bodies reassemble.expect(ledger.liveTokenCount).toBe(6);+ // Let both requests reassemble and start their forwards, so the loss below+ // transfers live forwards to the orphan registry.+ await flush();+// The channel exits mid-flight. The broker latches the loss, transfers the// in-flight forwards to the orphan registry, and releases the seen-id tokens.harness.exit();@@ -294,7 +358,7 @@ describe("duplex bridge broker aggregate byte ledger", () => {},},});- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),duplexAggregateByteLedger: ledger,@@ -303,6 +367,9 @@ describe("duplex bridge broker aggregate byte ledger", () => {broker.start();harness.feed(requestFrame("req-1"));+ // Let the request reassemble and start its forward before the close, so the+ // close orphans a live forward that settles afterward.+ await flush();await broker.close();// The close aborted the in-flight forward and orphaned it. The forward now// settles after the close: its finally owner releases the request tokens once.diff --git a/packages/adapter-utils/src/duplex-bridge-broker.test.ts b/packages/adapter-utils/src/duplex-bridge-broker.test.tsindex 6c87a1ae87..346c0cbf39 100644--- a/packages/adapter-utils/src/duplex-bridge-broker.test.ts+++ b/packages/adapter-utils/src/duplex-bridge-broker.test.ts@@ -14,6 +14,7 @@ import {type DuplexRequestFrame,type DuplexResponseFrame,} from "./duplex-frame-codec.js";+import { splitBodyIntoChunkFrames } from "./duplex-body-spool.js";import {createDuplexTelemetry,DUPLEX_COUNTER_LOSS_TOTAL,@@ -42,13 +43,27 @@ interface PendingForward {settled: boolean;}+/**+ * One reassembled response the broker wrote back. The broker writes a response as+ * one envelope frame that carries `bodyByteCount`, then the `body_chunk` frames+ * that carry the body. The harness reassembles the body and exposes it as `body`,+ * so a test asserts the response the same way it did with the one-frame model.+ */+type ReassembledResponse = DuplexResponseFrame & { body: string };++/** One request the harness feeds: the envelope frame plus its raw body text. */+interface RequestInput {+ frame: DuplexRequestFrame;+ bodyText: string;+}+/** The in-memory channel plus the levers a test uses to drive the broker. */interface FakeChannelHarness {channel: CommandManagedDuplexChannel;- /** Push one request frame into the broker read path. */- feed: (frame: DuplexRequestFrame) => void;- /** The response frames the broker wrote back, in order. */- responses: DuplexResponseFrame[];+ /** Push one request (its envelope frame and its body_chunk frames) into the broker read path. */+ feed: (input: RequestInput) => void;+ /** The reassembled responses the broker wrote back, in order. */+ responses: ReassembledResponse[];/** Every forward call the broker made, in order. */forwards: PendingForward[];/** Resolve the newest unsettled forward for one id with a 200 result. */@@ -57,36 +72,71 @@ interface FakeChannelHarness {resolveAll: () => void;}-/** Build one valid request frame with distinctive, secret-looking fields. */-function requestFrame(id: string, method = "POST"): DuplexRequestFrame {+/**+ * Build one valid request with distinctive, secret-looking fields. The envelope+ * carries `bodyByteCount`, and the harness rides the body on `body_chunk` frames.+ */+function requestFrame(+ id: string,+ method = "POST",+ bodyText: string = JSON.stringify({ secret: "secret-request-body" }),+): RequestInput {return {- version: DUPLEX_FRAME_VERSION,- type: "request",- id,- method,- path: `/api/issues/${id}`,- query: "?secret-query=leak",- headers: { authorization: "Bearer super-secret-provider-token" },- body: JSON.stringify({ secret: "secret-request-body" }),+ frame: {+ version: DUPLEX_FRAME_VERSION,+ type: "request",+ id,+ method,+ path: `/api/issues/${id}`,+ query: "?secret-query=leak",+ headers: { authorization: "Bearer super-secret-provider-token" },+ bodyByteCount: Buffer.byteLength(bodyText, "utf8"),+ },+ bodyText,};}/*** Build the in-memory channel harness. The channel keeps the broker read- * listener, so `feed` pushes an encoded frame into the broker. The channel- * decodes each written frame, so `responses` holds the response frames only.+ * listener, so `feed` pushes the encoded envelope and its body_chunk frames into+ * the broker. The channel decodes each written frame and reassembles a response+ * body, so `responses` holds one reassembled response per delivered request.*/function createFakeChannelHarness(): FakeChannelHarness {- const responses: DuplexResponseFrame[] = [];+ const responses: ReassembledResponse[] = [];const forwards: PendingForward[] = [];const writtenDecoder = new DuplexFrameDecoder();+ // The in-flight response reassembly, keyed by request id.+ const responseAssembly = new Map<+ string,+ { frame: DuplexResponseFrame; received: number; chunks: Buffer[] }+ >();let dataListener: ((chunk: string) => void) | null = null;const channel: CommandManagedDuplexChannel = {write: (data) => {for (const result of writtenDecoder.push(data)) {- if (result.ok && result.frame.type === "response") {- responses.push(result.frame);+ if (!result.ok) continue;+ const frame = result.frame;+ if (frame.type === "response") {+ if (frame.bodyByteCount === 0) {+ responses.push({ ...frame, body: "" });+ } else {+ responseAssembly.set(frame.id, { frame, received: 0, chunks: [] });+ }+ } else if (frame.type === "body_chunk") {+ const assembly = responseAssembly.get(frame.id);+ if (!assembly) continue;+ const decoded = Buffer.from(frame.data, "base64");+ assembly.received += decoded.length;+ assembly.chunks.push(decoded);+ if (assembly.received >= assembly.frame.bodyByteCount) {+ responseAssembly.delete(frame.id);+ responses.push({+ ...assembly.frame,+ body: Buffer.concat(assembly.chunks).toString("utf8"),+ });+ }}}},@@ -100,9 +150,17 @@ function createFakeChannelHarness(): FakeChannelHarness {return {channel,- feed: (frame) => {+ feed: ({ frame, bodyText }) => {if (!dataListener) throw new Error("The broker did not bind the data listener.");dataListener(encodeDuplexFrame(frame));+ if (bodyText.length > 0) {+ const chunks = splitBodyIntoChunkFrames(+ frame.id,+ Buffer.from(bodyText, "utf8"),+ DUPLEX_FRAME_VERSION,+ );+ for (const chunk of chunks) dataListener(encodeDuplexFrame(chunk));+ }},responses,forwards,@@ -134,6 +192,11 @@ function controllableForward(harness: FakeChannelHarness) {});}+/** Flush the microtasks and one macrotask, so the broker dispatches its reassembled forwards. */+async function flush(): Promise<void> {+ await new Promise((resolve) => setTimeout(resolve, 0));+}+/** The telemetry sink capture. It proves the broker records nothing for a refusal. */interface TelemetryCapture {spans: DuplexTelemetrySpanRecord[];@@ -175,11 +238,11 @@ describe("duplex bridge broker request limits", () => {expect(() => assertDuplexBrokerLimits({ maxInFlightRequests: 8, maxLifetimeRequests: 16 })).not.toThrow();});- it("bounds the in-flight forwards and refuses the excess with a retryable terminal response", () => {+ it("bounds the in-flight forwards and refuses the excess with a retryable terminal response", async () => {const harness = createFakeChannelHarness();const { telemetry, capture } = createTelemetryCapture();const maxInFlightRequests = 4;- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),telemetry,@@ -189,10 +252,13 @@ describe("duplex bridge broker request limits", () => {broker.start();// Inject more than the limit of unique valid frames. Every forward hangs, so- // the broker holds the maximum number of in-flight forwards.+ // the broker holds the maximum number of in-flight forwards. The broker gates+ // the in-flight limit at the request envelope, so it refuses the excess at+ // once; it dispatches each accepted forward after it reassembles the body.const total = 10;const ids = Array.from({ length: total }, (_unused, index) => `flight-${index}`);for (const id of ids) harness.feed(requestFrame(id));+ await flush();// The broker forwarded only up to the limit. It refused the rest.expect(harness.forwards).toHaveLength(maxInFlightRequests);@@ -226,7 +292,7 @@ describe("duplex bridge broker request limits", () => {it("frees capacity after a delivered request and forwards a resent refused id (no-replay preserved)", async () => {const harness = createFakeChannelHarness();const maxInFlightRequests = 2;- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),maxInFlightRequests,@@ -234,30 +300,36 @@ describe("duplex bridge broker request limits", () => {brokers.push(broker);broker.start();- // Saturate the in-flight limit with two hung forwards.+ // Saturate the in-flight limit with two hung forwards. The broker reserves the+ // in-flight slot at the request envelope, then dispatches the forward after it+ // reassembles the body.harness.feed(requestFrame("keep-0"));harness.feed(requestFrame("keep-1"));+ await flush();expect(harness.forwards).toHaveLength(2);// A third unique id is refused, retryable. The broker did not forward it and// did not retain its id.harness.feed(requestFrame("resend-me"));+ await flush();expect(harness.forwards).toHaveLength(2);expect(harness.responses).toHaveLength(1);expect(JSON.parse(harness.responses[0].body).retryable).toBe(true);// Free one in-flight slot. The delivered request drains the pending record.harness.resolveForward("keep-0");- await Promise.resolve();+ await flush();// The gateway resends the refused id. Capacity is free now, so the broker// forwards it exactly one time. This proves the refusal did not poison the id.harness.feed(requestFrame("resend-me"));+ await flush();expect(harness.forwards.filter((forward) => forward.id === "resend-me")).toHaveLength(1);// A resend of an already-forwarded id never reaches the forward twice.const forwardedKeep1 = harness.forwards.filter((forward) => forward.id === "keep-1").length;harness.feed(requestFrame("keep-1"));+ await flush();expect(harness.forwards.filter((forward) => forward.id === "keep-1")).toHaveLength(forwardedKeep1);harness.resolveAll();@@ -267,7 +339,7 @@ describe("duplex bridge broker request limits", () => {const harness = createFakeChannelHarness();const { telemetry, capture } = createTelemetryCapture();const maxLifetimeRequests = 3;- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,// Resolve every forward at once, so each dispatched id leaves the in-flight// count but stays in the retained-id set.@@ -285,7 +357,7 @@ describe("duplex bridge broker request limits", () => {const total = 9;for (let index = 0; index < total; index += 1) {harness.feed(requestFrame(`life-${index}`));- await Promise.resolve();+ await flush();}// The broker forwarded only up to the lifetime limit. The retained-id set@@ -304,7 +376,7 @@ describe("duplex bridge broker request limits", () => {// A resend of a refused id stays refused, so the set never grows.harness.feed(requestFrame("life-8"));- await Promise.resolve();+ await flush();expect(harness.forwards).toHaveLength(maxLifetimeRequests);// The telemetry surface stayed on the fixed request span for the delivered@@ -320,9 +392,9 @@ describe("duplex bridge broker request limits", () => {expect(broker.state).toBe("open");});- it("forwards nothing and fails the channel closed under a flood of over-limit ids", () => {+ it("forwards nothing and fails the channel closed under a flood of over-limit ids", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),});@@ -347,9 +419,9 @@ describe("duplex bridge broker request limits", () => {expect(broker.lossRecord?.reason).toBe("protocol_failure");});- it("forwards a maximal-size id exactly once and does not forward a resend (no-replay preserved)", () => {+ it("forwards a maximal-size id exactly once and does not forward a resend (no-replay preserved)", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),});@@ -359,19 +431,21 @@ describe("duplex bridge broker request limits", () => {// An id at the maximum byte size is allowed. The broker forwards it one time.const maxId = "a".repeat(DEFAULT_MAX_DUPLEX_REQUEST_ID_BYTES);harness.feed(requestFrame(maxId));+ await flush();expect(harness.forwards.filter((forward) => forward.id === maxId)).toHaveLength(1);// Deliver the response, then resend the same id. The broker retained the id,// so the resend never reaches the forward a second time.harness.resolveForward(maxId);harness.feed(requestFrame(maxId));+ await flush();expect(harness.forwards.filter((forward) => forward.id === maxId)).toHaveLength(1);expect(broker.state).toBe("open");});it("maps a forward that resolves with the indeterminate marker to a non-retryable response and retains the id", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),});@@ -384,6 +458,7 @@ describe("duplex bridge broker request limits", () => {// non-retryable body, so the gateway maps it to a non-retryable status and a// caller never repeats a possibly-committed mutation.harness.feed(requestFrame("commit-1"));+ await flush();const forward = harness.forwards.find((entry) => entry.id === "commit-1" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");forward.settled = true;@@ -423,7 +498,7 @@ describe("duplex bridge broker request limits", () => {it("maps a forward rejection for a mutating method to a non-retryable indeterminate response and retains the id", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),});@@ -436,6 +511,7 @@ describe("duplex bridge broker request limits", () => {// forward, so a POST must return a non-retryable indeterminate response.// A retryable status would let a caller repeat a committed mutation.harness.feed(requestFrame("mutate-1", "POST"));+ await flush();const forward = harness.forwards.find((entry) => entry.id === "mutate-1" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");forward.settled = true;@@ -465,7 +541,7 @@ describe("duplex bridge broker request limits", () => {it("substitutes a bounded terminal response for an oversized response and keeps the channel open", async () => {const harness = createFakeChannelHarness();const { telemetry, capture } = createTelemetryCapture();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),telemetry,@@ -482,6 +558,7 @@ describe("duplex bridge broker request limits", () => {// host.harness.feed(requestFrame("small-1", "POST"));harness.feed(requestFrame("big-1", "POST"));+ await flush();const smallForward = harness.forwards.find((entry) => entry.id === "small-1" && !entry.settled);if (!smallForward) throw new Error("The broker did not forward the small request.");@@ -542,30 +619,35 @@ describe("duplex bridge broker request limits", () => {it("sends a minimal terminal response when the frame bound rejects the full replacement", async () => {const harness = createFakeChannelHarness();const { telemetry, capture } = createTelemetryCapture();- // The bound accepts a compact request (130 bytes) and the minimal terminal- // response (106 bytes), but rejects the full replacement response (288 bytes).- // This proves the broker never drops the channel or strands the request when- // the configured bound is smaller than the full replacement response.- const broker = createDuplexBridgeBroker({+ // The bound accepts a compact request envelope (128 bytes) and the minimal+ // terminal response envelope (114 bytes), but rejects the full replacement+ // response envelope (193 bytes). This proves the broker never drops the channel+ // or strands the request when the bound is smaller than the full replacement.+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),telemetry,- maxFrameBytes: 200,+ maxFrameBytes: 150,});brokers.push(broker);broker.start();- // A compact request frame fits the bound, so the broker forwards it.+ // A compact request envelope with an empty body fits the bound, so the broker+ // forwards it.harness.feed({- version: DUPLEX_FRAME_VERSION,- type: "request",- id: "big-1",- method: "POST",- path: "/api/issues/big-1",- query: "",- headers: {},- body: JSON.stringify({ go: 1 }),+ frame: {+ version: DUPLEX_FRAME_VERSION,+ type: "request",+ id: "big-1",+ method: "POST",+ path: "/api/issues/big-1",+ query: "",+ headers: {},+ bodyByteCount: 0,+ },+ bodyText: "",});+ await flush();const forward = harness.forwards.find((entry) => entry.id === "big-1" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");@@ -608,29 +690,34 @@ describe("duplex bridge broker request limits", () => {const harness = createFakeChannelHarness();const { telemetry, capture } = createTelemetryCapture();const logs: string[] = [];- // The bound accepts a tiny request (99 bytes) but rejects even the minimal- // terminal response (102 bytes). The broker cannot send any frame for this- // request, so it must keep the channel open and log a clear local error.- const broker = createDuplexBridgeBroker({+ // The bound accepts a tiny request envelope (107 bytes) but rejects even the+ // minimal terminal response envelope (110 bytes). The broker cannot send any+ // frame for this request, so it must keep the channel open and log a clear+ // local error.+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),telemetry,- maxFrameBytes: 100,+ maxFrameBytes: 109,logger: (message) => logs.push(message),});brokers.push(broker);broker.start();harness.feed({- version: DUPLEX_FRAME_VERSION,- type: "request",- id: "x",- method: "GET",- path: "/",- query: "",- headers: {},- body: "",+ frame: {+ version: DUPLEX_FRAME_VERSION,+ type: "request",+ id: "x",+ method: "GET",+ path: "/",+ query: "",+ headers: {},+ bodyByteCount: 0,+ },+ bodyText: "",});+ await flush();const forward = harness.forwards.find((entry) => entry.id === "x" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");@@ -657,7 +744,7 @@ describe("duplex bridge broker request limits", () => {it("completes a request within the bound and delivers the real response", async () => {const harness = createFakeChannelHarness();const { telemetry, capture } = createTelemetryCapture();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),telemetry,@@ -667,6 +754,7 @@ describe("duplex bridge broker request limits", () => {broker.start();harness.feed(requestFrame("ok-1", "POST"));+ await flush();harness.resolveForward("ok-1", JSON.stringify({ ok: true }));await new Promise((resolve) => setTimeout(resolve, 0));@@ -690,7 +778,7 @@ describe("duplex bridge broker request limits", () => {it("maps a forward rejection for a safe method to a retryable response", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),});@@ -701,6 +789,7 @@ describe("duplex bridge broker request limits", () => {// mutation. A forward rejection for a GET stays retryable: the broker// returns a 502 with the completed outcome, so the gateway passes it through.harness.feed(requestFrame("read-1", "GET"));+ await flush();const forward = harness.forwards.find((entry) => entry.id === "read-1" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");forward.settled = true;@@ -719,7 +808,7 @@ describe("duplex bridge broker request limits", () => {it("maps a forward-budget timeout for a safe method to a retryable response", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),// A tiny forward budget aborts the controller before the manual rejection.@@ -732,6 +821,7 @@ describe("duplex bridge broker request limits", () => {// stay retryable: the broker returns a 504 with the completed outcome and no// indeterminate marker, so the gateway does not map it to a terminal 409.harness.feed(requestFrame("read-timeout-1", "GET"));+ await flush();const forward = harness.forwards.find((entry) => entry.id === "read-timeout-1" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");@@ -755,7 +845,7 @@ describe("duplex bridge broker request limits", () => {it("maps a forward-budget timeout for a mutating method to a non-retryable indeterminate response", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),budgets: { forwardTimeoutMs: 5 },@@ -767,6 +857,7 @@ describe("duplex bridge broker request limits", () => {// must keep the terminal contract: a 504 with the indeterminate outcome, so// the gateway maps it to a non-retryable 409 and no caller double-applies it.harness.feed(requestFrame("mutate-timeout-1", "POST"));+ await flush();const forward = harness.forwards.find((entry) => entry.id === "mutate-timeout-1" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");@@ -789,7 +880,7 @@ describe("duplex bridge broker request limits", () => {it("maps a response-budget backstop for a safe method to a retryable response", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),// The forward budget aborts the call, but the forward promise stays@@ -806,6 +897,7 @@ describe("duplex bridge broker request limits", () => {// retryable: a 504 with the completed outcome and no indeterminate marker,// so the gateway does not map it to a terminal 409.harness.feed(requestFrame("read-stall-1", "GET"));+ await flush();const forward = harness.forwards.find((entry) => entry.id === "read-stall-1" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");@@ -826,7 +918,7 @@ describe("duplex bridge broker request limits", () => {it("maps a response-budget backstop for a mutating method to a non-retryable indeterminate response", async () => {const harness = createFakeChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: controllableForward(harness),budgets: { forwardTimeoutMs: 5, responseBudgetMs: 15, gatewayWaitMs: 40 },@@ -839,6 +931,7 @@ describe("duplex bridge broker request limits", () => {// contract: a 504 with the indeterminate outcome, so the gateway maps it to a// non-retryable 409 and no caller double-applies it.harness.feed(requestFrame("mutate-stall-1", "POST"));+ await flush();const forward = harness.forwards.find((entry) => entry.id === "mutate-stall-1" && !entry.settled);if (!forward) throw new Error("The broker did not forward the request.");@@ -897,10 +990,10 @@ describe("duplex bridge broker exit taxonomy", () => {}});- it("records a transport close as a distinct loss, not a process exit", () => {+ it("records a transport close as a distinct loss, not a process exit", async () => {const { telemetry, capture } = createTelemetryCapture();const harness = createExitChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: () =>Promise.resolve({ status: 200, headers: {}, body: "" }),@@ -920,10 +1013,10 @@ describe("duplex bridge broker exit taxonomy", () => {expect(lossCounter?.dimensions.loss_reason).toBe("transport_closed");});- it("records a numeric exit as a process exit", () => {+ it("records a numeric exit as a process exit", async () => {const { telemetry, capture } = createTelemetryCapture();const harness = createExitChannelHarness();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: harness.channel,forwardRequest: () =>Promise.resolve({ status: 200, headers: {}, body: "" }),diff --git a/packages/adapter-utils/src/duplex-bridge-broker.ts b/packages/adapter-utils/src/duplex-bridge-broker.tsindex b7a04021a1..1ae50d92bb 100644--- a/packages/adapter-utils/src/duplex-bridge-broker.ts+++ b/packages/adapter-utils/src/duplex-bridge-broker.ts@@ -48,17 +48,26 @@ import {type ReservationToken,} from "./duplex-aggregate-byte-ledger.js";import {+ DUPLEX_BODY_CHUNK_RAW_BYTES,DEFAULT_MAX_DUPLEX_FRAME_BYTES,DEFAULT_MAX_DUPLEX_REQUEST_ID_BYTES,DUPLEX_FRAME_VERSION,DuplexFrameDecoder,encodeDuplexFrame,encodeDuplexFrameChecked,+ type DuplexBodyChunkFrame,type DuplexFrame,type DuplexRequestFrame,type DuplexResponseFrame,type DuplexResponseOutcome,} from "./duplex-frame-codec.js";+import {+ DuplexBodyError,+ DuplexBodyReceiver,+ splitBodyIntoChunkFrames,+ type DuplexBodyReceiverConfig,+ type ReassembledBody,+} from "./duplex-body-spool.js";import type {DuplexLossReason,DuplexOutcomeValue,@@ -195,12 +204,15 @@ export interface DuplexBrokerForwardResult {/*** The forward handler the broker calls for each request. The handler applies the* real token and the run attribution, then forwards the request on the existing- * API path. The broker aborts `options.signal` when the forward budget ends or a- * loss happens, so a handler that threads the signal into its work stops early.+ * API path. The broker reassembles the request body from the `body_chunk` frames+ * before it calls the handler, so the handler streams the body from+ * `options.body`. The broker aborts `options.signal` when the forward budget ends+ * or a loss happens, so a handler that threads the signal into its work stops+ * early.*/export type DuplexBrokerForwardHandler = (request: DuplexRequestFrame,- options: { signal: AbortSignal },+ options: { signal: AbortSignal; body: ReassembledBody },) => Promise<DuplexBrokerForwardResult>;/** One request record. The broker captures the dispatch-start point for metrics only. */@@ -249,6 +261,14 @@ export interface DuplexBrokerOptions {* {@link DEFAULT_DUPLEX_BROKER_MAX_LIFETIME_REQUESTS}.*/maxLifetimeRequests?: number;+ /**+ * The config for the receive-side request-body reassembler. It sets the spill+ * threshold, the fixed raw chunk size, and the per-channel spill caps. The+ * broker creates one reassembler for the channel. The config stays injectable,+ * so a test lowers the spill threshold and the caps to exercise the spill path+ * and the fail-closed cap behavior without a large body.+ */+ bodyReceiverConfig?: DuplexBodyReceiverConfig;/** The clock the broker reads for the metric timestamps. The default is `Date.now`. */now?: () => number;/** The metrics sink for the per-request dispatch record. */@@ -381,10 +401,24 @@ export function isSafeBridgeMethod(method: string): boolean {interface PendingRequest {controller: AbortController;responded: boolean;- forwardTimer: ReturnType<typeof setTimeout>;+ /**+ * The forward-budget timer. It is `null` while the broker reassembles the+ * request body, and the broker sets it when it starts the forward. So the+ * forward budget bounds the forward call, not the reassembly.+ */+ forwardTimer: ReturnType<typeof setTimeout> | null;+ /**+ * The response-budget backstop timer. The broker starts it at the request+ * envelope, so it bounds the whole request: the body reassembly plus the+ * forward. It answers a request that never completes its reassembly or forward.+ */responseTimer: ReturnType<typeof setTimeout>;/** The point the broker started to dispatch the request. It sets the span latency. */dispatchStartMs: number;+ /** The request method. The response backstop reads it to classify the safe-method retry. */+ method: string;+ /** The reassembled request body, set once reassembly completes. The broker disposes it on settle. */+ reassembled: ReassembledBody | null;/** True once the forward promise settled. The finally owner sets it one time. */forwardSettled: boolean;/**@@ -409,10 +443,14 @@ interface OrphanedForward {}/**- * Create the host duplex bridge broker. The factory asserts the budget order and- * returns a handle. Call `start` to wire the channel and open the broker.+ * Create the host duplex bridge broker. The factory asserts the budget order,+ * creates the receive-side request-body reassembler, and returns a handle. It is+ * asynchronous because the reassembler owns a spill directory it creates with+ * `mkdtemp`. Call `start` to wire the channel and open the broker.*/-export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBridgeBroker {+export async function createDuplexBridgeBroker(+ options: DuplexBrokerOptions,+): Promise<DuplexBridgeBroker> {const budgets: DuplexBrokerBudgets = {...DEFAULT_DUPLEX_BROKER_BUDGETS,...options.budgets,@@ -452,21 +490,50 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrif (ledger && token) ledger.release(token);};// The byte size of the normalized request payload the broker retains across the- // forward. It counts the exact retained scalar and header bytes, so the charge- // matches the retained bytes and never a parsed object graph.+ // forward. It counts the exact retained scalar and header bytes plus the raw body+ // byte count, so the charge matches the reassembled body the broker holds and+ // never a parsed object graph. The body rides `body_chunk` frames, so the+ // envelope carries only `bodyByteCount`; that count is the retained body size.const requestPayloadBytes = (frame: DuplexRequestFrame): number => {let bytes =Buffer.byteLength(frame.id, "utf8") +Buffer.byteLength(frame.method, "utf8") +Buffer.byteLength(frame.path, "utf8") +Buffer.byteLength(frame.query, "utf8") +- Buffer.byteLength(frame.body, "utf8");+ frame.bodyByteCount;for (const [key, value] of Object.entries(frame.headers)) {bytes += Buffer.byteLength(key, "utf8") + Buffer.byteLength(value, "utf8");}return bytes;};+ // The receive-side request-body reassembler. It reassembles each request body+ // from the `body_chunk` frames, on the memory path at or below the spill+ // threshold and on the spill path above it, so the broker never holds a whole+ // large request body in memory. It owns a per-channel spill directory and the+ // spill caps.+ const receiver = await DuplexBodyReceiver.create(options.bodyReceiverConfig ?? {});+ let receiverFinalized = false;+ const finalizeReceiver = (): Promise<void> => {+ // Remove the spill directory and every in-flight body once. The broker calls+ // it on every terminal path: a loss, a normal teardown, and an orderly close.+ if (receiverFinalized) return Promise.resolve();+ receiverFinalized = true;+ return receiver.destroy().catch(() => undefined);+ };+ // The fixed raw slice size for the response `body_chunk` frames. It matches the+ // reassembler config, so a test that lowers the slice size splits both a request+ // body and a response body the same way.+ const rawChunkBytes = options.bodyReceiverConfig?.rawChunkBytes ?? DUPLEX_BODY_CHUNK_RAW_BYTES;+ // The ids the broker is reassembling right now. A `body_chunk` for an id in this+ // set routes to the reassembler. The broker removes an id when the body settles.+ const reassembling = new Set<string>();+ // The ids the broker refused at the envelope, with the raw bytes it still must+ // drain. The sender emits the `body_chunk` frames for a refused request before+ // it learns of the refusal, so the broker drains and drops those chunks instead+ // of treating them as a body_chunk with no envelope.+ const draining = new Map<string, number>();+let state: DuplexBrokerState = "opening";let stopped = false;let started = false;@@ -544,21 +611,33 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrconst clearPending = (): void => {for (const [id, entry] of pending) {- clearTimeout(entry.forwardTimer);+ if (entry.forwardTimer !== null) clearTimeout(entry.forwardTimer);clearTimeout(entry.responseTimer);entry.controller.abort(new Error("Duplex broker stopped."));- // A forward that has not settled still owns its request tokens. Transfer it- // to the orphan registry, so its tokens stay charged until the forward- // finally releases them. The abort only asks the forward to stop; it never- // releases a token by itself.- if (!entry.forwardSettled) {+ if (entry.reassembled !== null) {+ void entry.reassembled.dispose();+ entry.reassembled = null;+ }+ if (entry.forwardSettled) continue;+ if (entry.forwardTimer !== null) {+ // A live forward promise still owns its request tokens. Transfer it to the+ // orphan registry, so its tokens stay charged until the forward finally+ // releases them. The abort only asks the forward to stop; it never releases+ // a token by itself.orphanedForwards.set(id, {controller: entry.controller,releaseForwardTokens: entry.releaseForwardTokens,});+ } else {+ // The request is still reassembling, so no forward promise will settle and+ // release its tokens. Release the request tokens now. The reassembler+ // teardown below rejects the in-flight body and unlinks any spill file.+ entry.releaseForwardTokens();}}pending.clear();+ reassembling.clear();+ draining.clear();// Ask every already-orphaned forward to stop as well. The forward-promise// finally owner releases each orphan token when the forward settles.for (const orphan of orphanedForwards.values()) {@@ -582,6 +661,7 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrclearPending();releaseSeenRequestIdTokens();decoder.dispose();+ void finalizeReceiver();if (state !== "closing") setState("closed");return;}@@ -607,6 +687,7 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrclearPending();releaseSeenRequestIdTokens();decoder.dispose();+ void finalizeReceiver();lossRecord = { reason, message, atMs: now() };setState("lost");// Log the internal reason only. The broker never writes the raw provider@@ -626,31 +707,57 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr}};- // The result of one bounded send. `sent` means the frame went out; `too_large`- // means the encoded frame exceeds the bound and the broker wrote nothing;- // `lost` means the write failed and the broker recorded the channel loss.+ // The result of one bounded send. `sent` means every frame went out; `too_large`+ // means the response envelope exceeds the bound and the broker wrote nothing;+ // `lost` means a write failed and the broker recorded the channel loss.type SendResult = "sent" | "too_large" | "lost";- const trySendFrame = (frame: DuplexFrame): SendResult => {- // Enforce the frame size bound on every broker write. Report a size rejection- // as `too_large` without a channel loss; a broker-built frame over the bound- // is a defect, not a transport failure. A caller decides how to answer the- // request, so no size rejection ever drops the channel.- const encoded = encodeDuplexFrameChecked(frame, maxFrameBytes);- if (!encoded.ok) return "too_large";- return writeLine(encoded.line) ? "sent" : "lost";- };-- const writeFrame = (frame: DuplexFrame): boolean => {- // A control frame and the bounded terminal responses are always small, so the- // size guard is a no-op for them. Drop an oversized frame here without a- // channel loss and report the drop to the caller.- const result = trySendFrame(frame);- if (result === "too_large") {- options.logger?.(`Duplex broker dropped an oversized ${frame.type} frame.`);- return false;+ // Send one full response as a sequence of frames: one envelope frame that+ // carries `bodyByteCount`, then the `body_chunk` frames that carry the body. The+ // envelope is always small. Each `body_chunk` carries one fixed raw slice, so+ // each encoded chunk stays under the frame bound by construction. The result+ // reports `too_large` when the envelope itself exceeds the bound and the broker+ // wrote nothing, `lost` when a write failed and the broker recorded the channel+ // loss, and `sent` when every frame went out.+ const sendResponseFrames = (+ id: string,+ status: number,+ headers: Record<string, string>,+ bodyText: string,+ outcome: DuplexResponseOutcome,+ ): SendResult => {+ const bodyBuffer = Buffer.from(bodyText, "utf8");+ const envelope: DuplexResponseFrame = {+ version: DUPLEX_FRAME_VERSION,+ type: "response",+ id,+ status,+ headers,+ bodyByteCount: bodyBuffer.length,+ outcome,+ };+ // Guard the envelope against the frame bound. The envelope holds no body, so a+ // real bound rejects it only under an extreme small test bound. Report the+ // rejection without a channel loss, so the caller decides how to answer.+ const encodedEnvelope = encodeDuplexFrameChecked(envelope, maxFrameBytes);+ if (!encodedEnvelope.ok) return "too_large";+ const chunkFrames = splitBodyIntoChunkFrames(id, bodyBuffer, DUPLEX_FRAME_VERSION, rawChunkBytes);+ if (!writeLine(encodedEnvelope.line)) return "lost";+ for (const chunk of chunkFrames) {+ const encodedChunk = encodeDuplexFrameChecked(chunk, maxFrameBytes);+ if (!encodedChunk.ok) {+ // A single fixed-size slice never exceeds the bound in a real configuration.+ // A test bound below one chunk can reject it. The envelope already went out+ // with the true `bodyByteCount`, so the broker cannot complete the body+ // within the bound. Log the drop and stop; the gateway ends the request on+ // its wait budget. Report `sent`, because the broker already committed the+ // envelope, so no caller resends a bounded replacement over the same id.+ options.logger?.("Duplex broker dropped an oversized body_chunk frame.");+ return "sent";+ }+ if (!writeLine(encodedChunk.line)) return "lost";}- return result === "sent";+ return "sent";};const sendTerminalIndeterminate = (id: string): void => {@@ -658,42 +765,32 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr// request reached the host and may have changed state, so the response is// non-retryable and carries the `indeterminate` outcome. The broker tries the// full replacement first. When the frame bound rejects even the full- // replacement, the broker sends a minimal replacement that carries only the- // `indeterminate` outcome, so the gateway still ends the request and never- // waits for its full wait budget. When the bound rejects even the minimal- // replacement, the broker logs a clear local error and keeps the channel- // open; it records no channel loss.- const fullReplacement: DuplexResponseFrame = {- version: DUPLEX_FRAME_VERSION,- type: "response",- id,- status: 502,- headers: {- "content-type": "application/json",- "x-paperclip-bridge-outcome": "indeterminate",- },- body: JSON.stringify({- error: "upstream response too large to deliver",- outcome: "indeterminate",- retryable: false,- }),- outcome: "indeterminate",- };- if (trySendFrame(fullReplacement) !== "too_large") return;- // The bound rejects the full replacement. Send a minimal terminal response- // with empty headers and an empty body. The `indeterminate` outcome still- // rides the frame, so the gateway maps the request to a terminal 409.- const minimalReplacement: DuplexResponseFrame = {- version: DUPLEX_FRAME_VERSION,- type: "response",- id,- status: 502,- headers: {},- body: "",+ // replacement envelope, the broker sends a minimal replacement that carries+ // only the `indeterminate` outcome, so the gateway still ends the request and+ // never waits for its full wait budget. When the bound rejects even the+ // minimal replacement envelope, the broker logs a clear local error and keeps+ // the channel open; it records no channel loss.+ const fullBody = JSON.stringify({+ error: "upstream response too large to deliver",outcome: "indeterminate",- };- if (trySendFrame(minimalReplacement) !== "too_large") return;- // The bound rejects even the minimal terminal response. The broker cannot+ retryable: false,+ });+ if (+ sendResponseFrames(+ id,+ 502,+ { "content-type": "application/json", "x-paperclip-bridge-outcome": "indeterminate" },+ fullBody,+ "indeterminate",+ ) !== "too_large"+ ) {+ return;+ }+ // The bound rejects the full replacement envelope. Send a minimal terminal+ // response with empty headers and an empty body. The `indeterminate` outcome+ // still rides the envelope, so the gateway maps the request to a terminal 409.+ if (sendResponseFrames(id, 502, {}, "", "indeterminate") !== "too_large") return;+ // The bound rejects even the minimal terminal envelope. The broker cannot// deliver any frame for this request within the bound. Log a clear local// error and keep the channel open for every other request. The gateway ends// its own outstanding request on its wait budget.@@ -711,40 +808,19 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrconst entry = pending.get(id);if (!entry || entry.responded) return;entry.responded = true;- clearTimeout(entry.forwardTimer);- clearTimeout(entry.responseTimer);- pending.delete(id);- // The response timer, an abort, or a broker loss can answer the gateway before- // the forward promise settles. When the forward has not settled, transfer it to- // the orphan registry so its request tokens stay charged until the forward- // finally releases them. A settled forward already released or will release- // through its finally owner, so it needs no orphan record.- if (!entry.forwardSettled) {- orphanedForwards.set(id, {- controller: entry.controller,- releaseForwardTokens: entry.releaseForwardTokens,- });- }+ settlePendingBookkeeping(id, entry);// Do not write on a lost or closed channel. The gateway answers its own// outstanding request on loss, so a late write would go to a dead channel.if (state !== "open") return;- const frame: DuplexResponseFrame = {- version: DUPLEX_FRAME_VERSION,- type: "response",- id,- status: result.status,- headers: result.headers ?? {},- body: result.body ?? "",- outcome,- };- const encoded = encodeDuplexFrameChecked(frame, maxFrameBytes);- if (!encoded.ok) {- // The host produced a result, but the response frame exceeds the size- // bound. Do not write the oversized frame and do not record a channel loss.- // The request reached the host and may have changed state, so the caller- // must not retry a possible mutation. Send a bounded, non-retryable terminal- // response marked `indeterminate` in its place. Record the request outcome- // as an error, never a loss. The channel stays open for every other request.+ const bodyText = result.body ?? "";+ const bodyByteCount = Buffer.byteLength(bodyText, "utf8");+ // The response body rides `body_chunk` frames, so a large body no longer makes+ // one frame too large. The gateway reassembles a response body in memory,+ // though, so a body over the frame bound would force the gateway to hold an+ // oversized body in memory. Treat a response body over the frame bound like the+ // former oversized case: send a bounded, non-retryable indeterminate terminal+ // response, and record the request outcome as an error, never a loss.+ if (bodyByteCount > maxFrameBytes) {options.telemetry?.recordRequest({latencyMs: now() - entry.dispatchStartMs,outcome: "error",@@ -753,12 +829,14 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrreturn;}// Record the request span for the delivered request. The span carries the- // latency and the outcome only; no route, query, body, or token rides it.+ // latency and the outcome only; no route, query, body, or token rides it. The+ // broker records the span before the writes, so the outcome is recorded even if+ // a later chunk write records a channel loss.options.telemetry?.recordRequest({latencyMs: now() - entry.dispatchStartMs,outcome: telemetryOutcome,});- writeLine(encoded.line);+ sendResponseFrames(id, result.status, result.headers ?? {}, bodyText, outcome);};const respondSaturated = (id: string, retryable: boolean): void => {@@ -768,23 +846,61 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr// it holds only the fixed error shape. The `unavailable` outcome tells the// gateway this is not a delivered host response, so it never counts as one.if (state !== "open") return;- const frame: DuplexResponseFrame = {- version: DUPLEX_FRAME_VERSION,- type: "response",+ sendResponseFrames(id,- status: 503,- headers: {- "content-type": "application/json",- "x-paperclip-bridge-outcome": "unavailable",- },- body: JSON.stringify({+ 503,+ { "content-type": "application/json", "x-paperclip-bridge-outcome": "unavailable" },+ JSON.stringify({error: "Duplex broker capacity limit reached.",outcome: "unavailable",retryable,}),- outcome: "unavailable",- };- writeFrame(frame);+ "unavailable",+ );+ };++ // Release the timers and route the reassembly and ledger resources for one+ // request the broker just answered. The broker calls it exactly once per+ // request, from the response path. It clears both timers and drops the pending+ // record, then it settles the resources by the request phase:+ // - A live forward promise (the response backstop answered while the forward+ // ran) keeps its request tokens and its reassembled body until its finally+ // owner releases and disposes them, so the orphan registry holds it.+ // - A request still reassembling (the backstop answered before the forward+ // started) has no forward promise to settle, so the broker releases its+ // tokens and disposes the in-flight body now.+ // - A settled forward already released and disposed through its finally owner.+ const settlePendingBookkeeping = (id: string, entry: PendingRequest): void => {+ if (entry.forwardTimer !== null) clearTimeout(entry.forwardTimer);+ clearTimeout(entry.responseTimer);+ pending.delete(id);+ if (entry.forwardSettled) return;+ if (entry.forwardTimer !== null) {+ // A live forward still owns its request tokens and streams the reassembled+ // body. Keep both charged until the forward finally owner settles them.+ orphanedForwards.set(id, {+ controller: entry.controller,+ releaseForwardTokens: entry.releaseForwardTokens,+ });+ return;+ }+ // The request is still reassembling, so no forward promise will settle. Release+ // the request tokens and dispose the in-flight body, so no spill file, arena+ // reservation, or ledger token lingers.+ entry.releaseForwardTokens();+ if (reassembling.delete(id)) void receiver.disposeBody(id);+ if (entry.reassembled !== null) {+ void entry.reassembled.dispose();+ entry.reassembled = null;+ }+ };++ // Mark a refused or duplicate request id for chunk draining. The sender emits+ // the `body_chunk` frames for the request before it learns of the refusal, so+ // the broker records the raw byte count it must drain and drop. A request with+ // no body needs no draining, so the broker records only a non-zero count.+ const markDrain = (frame: DuplexRequestFrame): void => {+ if (frame.bodyByteCount > 0) draining.set(frame.id, frame.bodyByteCount);};const respondAggregateExceeded = (id: string): void => {@@ -796,23 +912,17 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr// host response. The refusal is retryable, because the broker did not retain// the id: the aggregate pressure can ease, and a resend can then get through.if (state !== "open") return;- const frame: DuplexResponseFrame = {- version: DUPLEX_FRAME_VERSION,- type: "response",+ sendResponseFrames(id,- status: 503,- headers: {- "content-type": "application/json",- "x-paperclip-bridge-outcome": "unavailable",- },- body: JSON.stringify({+ 503,+ { "content-type": "application/json", "x-paperclip-bridge-outcome": "unavailable" },+ JSON.stringify({error: DUPLEX_CHANNEL_AGGREGATE_BYTES_EXCEEDED,outcome: "unavailable",retryable: true,}),- outcome: "unavailable",- };- writeFrame(frame);+ "unavailable",+ );};const dispatch = (frame: DuplexRequestFrame): void => {@@ -825,13 +935,19 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr// forwards. It answers with the bounded terminal refusal, which carries no// route, query, body, or token, and records no telemetry. The refusal is not// retryable, because a resend of the same over-limit id never gets past this- // bound.+ // bound. It drains the following chunks of the refused body.if (Buffer.byteLength(frame.id, "utf8") > DEFAULT_MAX_DUPLEX_REQUEST_ID_BYTES) {respondSaturated(frame.id, false);+ markDrain(frame);+ return;+ }+ // Forward one id one time. A repeated id never reaches the API twice. The+ // broker already answered the first request, so it answers no second time; it+ // drains the resent body chunks and drops them.+ if (seenRequestIds.has(frame.id)) {+ markDrain(frame);return;}- // Forward one id one time. A repeated id never reaches the API twice.- if (seenRequestIds.has(frame.id)) return;// Bound the retained request-id memory. The broker keeps one id per distinct// dispatched request for the no-replay guarantee, so the set can only grow.// Once the broker reaches the lifetime limit, it refuses each new distinct id@@ -840,6 +956,7 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr// the set never grows past the limit.if (seenRequestIds.size >= limits.maxLifetimeRequests) {respondSaturated(frame.id, false);+ markDrain(frame);return;}// Bound the in-flight request count. Once the broker holds the maximum number@@ -847,9 +964,11 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr// it. The broker does not add the id to the seen set, so the gateway can// resend the request after an in-flight request completes. The refusal is// retryable for that reason. This check bounds the controllers, the timers,- // and the concurrent forwards a provider can force.+ // the concurrent reassemblies, and the concurrent forwards a provider can+ // force.if (pending.size >= limits.maxInFlightRequests) {respondSaturated(frame.id, true);+ markDrain(frame);return;}// Reserve the exact retained bytes against the aggregate ledger before the@@ -868,12 +987,14 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrrequestFrameToken = ledger.reserve("request_frame", rawFrameBytes);if (!requestFrameToken) {respondAggregateExceeded(frame.id);+ markDrain(frame);return;}requestPayloadToken = ledger.reserve("request_payload", requestPayloadBytes(frame));if (!requestPayloadToken) {ledger.release(requestFrameToken);respondAggregateExceeded(frame.id);+ markDrain(frame);return;}const seenEntryBytes =@@ -883,6 +1004,7 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrledger.release(requestFrameToken);ledger.release(requestPayloadToken);respondAggregateExceeded(frame.id);+ markDrain(frame);return;}}@@ -910,83 +1032,123 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBroptions.onRequestRecord?.(record);const controller = new AbortController();- const forwardTimer = setTimeout(() => {- controller.abort(new Error("Duplex broker forward budget exceeded."));- }, budgets.forwardTimeoutMs);- const responseTimer = setTimeout(() => {- // Response-budget backstop. The forward rejection normally answers first,- // well before this deadline. This backstop answers a request whose forward- // rejection handling itself stalls, so the request never strands. One stall- // path is a response whose headers arrive but whose body reader stays- // pending through the budget, so the forward promise never settles.- if (isSafeBridgeMethod(frame.method)) {- // A safe method never changes host state, so a stalled body reader- // cannot leave a mutation half-applied. Keep the request retryable:- // return a 504 with the completed outcome and no indeterminate marker,- // so the gateway passes it through as a retryable status and never maps- // it to a terminal 409.- respond(- frame.id,- {- status: 504,- headers: { "content-type": "application/json" },- body: JSON.stringify({- error: "Duplex broker response budget exceeded.",- retryable: true,- }),- },- "completed",- "error",- );- return;- }- // The method may mutate host state, and the broker cannot prove the host- // applied no mutation once the response budget passes. Return a- // non-retryable 504 and mark the outcome indeterminate, so the gateway- // maps it to a terminal 409 and no caller double-applies the mutation.+ // Start the response-budget backstop at the request envelope, so it bounds the+ // whole request: the body reassembly plus the forward. The forward-budget timer+ // starts later, when the broker starts the forward, so it bounds the forward+ // call alone.+ const responseTimer = setTimeout(() => respondBackstop(frame.id), budgets.responseBudgetMs);+ responseTimer.unref?.();+ const entry: PendingRequest = {+ controller,+ responded: false,+ forwardTimer: null,+ responseTimer,+ dispatchStartMs: record.dispatchStartMs,+ method: frame.method,+ reassembled: null,+ forwardSettled: false,+ releaseForwardTokens,+ };+ pending.set(frame.id, entry);+ // Route the following `body_chunk` frames for this id to the reassembler.+ reassembling.add(frame.id);+ // Reassemble the request body from the `body_chunk` frames, then forward it.+ // The reassembler chooses the memory path or the spill path from the envelope+ // `bodyByteCount`, so the broker never holds a whole large request body in+ // memory. A reassembly error is a terminal protocol failure.+ receiver.begin(frame.id, frame.bodyByteCount).then(+ (body) => onBodyReady(frame, entry, body),+ (error) => onBodyError(frame.id, entry, error),+ );+ };++ const respondBackstop = (id: string): void => {+ // Response-budget backstop. The forward rejection normally answers first, well+ // before this deadline. This backstop answers a request whose body never+ // completes its reassembly, or whose forward rejection handling itself stalls,+ // so the request never strands. One stall path is a response whose headers+ // arrive but whose body reader stays pending through the budget, so the forward+ // promise never settles.+ const entry = pending.get(id);+ if (!entry || entry.responded) return;+ if (isSafeBridgeMethod(entry.method)) {+ // A safe method never changes host state, so a stalled body reader cannot+ // leave a mutation half-applied. Keep the request retryable: return a 504+ // with the completed outcome and no indeterminate marker, so the gateway+ // passes it through as a retryable status and never maps it to a terminal 409.respond(- frame.id,+ id,{status: 504,- headers: {- "content-type": "application/json",- "x-paperclip-bridge-outcome": "indeterminate",- },+ headers: { "content-type": "application/json" },body: JSON.stringify({error: "Duplex broker response budget exceeded.",- outcome: "indeterminate",- retryable: false,+ retryable: true,}),},- "indeterminate",+ "completed","error",);- }, budgets.responseBudgetMs);+ return;+ }+ // The method may mutate host state, and the broker cannot prove the host+ // applied no mutation once the response budget passes. Return a non-retryable+ // 504 and mark the outcome indeterminate, so the gateway maps it to a terminal+ // 409 and no caller double-applies the mutation.+ respond(+ id,+ {+ status: 504,+ headers: {+ "content-type": "application/json",+ "x-paperclip-bridge-outcome": "indeterminate",+ },+ body: JSON.stringify({+ error: "Duplex broker response budget exceeded.",+ outcome: "indeterminate",+ retryable: false,+ }),+ },+ "indeterminate",+ "error",+ );+ };++ // The request body reassembled. Start the forward now, so the forward budget+ // bounds the forward call alone. The broker passes the reassembled body to the+ // forward handler, so the handler streams it to the host API path.+ const onBodyReady = (+ frame: DuplexRequestFrame,+ entry: PendingRequest,+ body: ReassembledBody,+ ): void => {+ reassembling.delete(frame.id);+ if (stopped || state !== "open" || entry.responded) {+ // The channel died, or the response backstop already answered, so no forward+ // runs. Dispose the body and release the request tokens, so no spill file,+ // arena reservation, or ledger token lingers, and drop the request from the+ // pending and orphan maps.+ void body.dispose();+ pending.delete(frame.id);+ orphanedForwards.delete(frame.id);+ entry.releaseForwardTokens();+ return;+ }+ entry.reassembled = body;+ const forwardTimer = setTimeout(() => {+ entry.controller.abort(new Error("Duplex broker forward budget exceeded."));+ }, budgets.forwardTimeoutMs);forwardTimer.unref?.();- responseTimer.unref?.();- pending.set(frame.id, {- controller,- responded: false,- forwardTimer,- responseTimer,- dispatchStartMs: record.dispatchStartMs,- forwardSettled: false,- releaseForwardTokens,- });+ entry.forwardTimer = forwardTimer;- // The forward promise has one cleanup owner. The two settle handlers mark the+ // The forward promise has one cleanup owner. Both settle handlers mark the// forward settled and answer the gateway. The `finally` then releases the- // request tokens exactly one time and removes the request from both the pending- // map and the orphan map. The forward resolves only after the forward and its- // response-body reader both settle, so this owner waits for both.+ // request tokens exactly one time, disposes the reassembled body, and removes+ // the request from the pending map and the orphan map.const markForwardSettled = (): void => {- // Mark the pending entry settled before `respond` runs, so `respond` never- // moves a just-settled forward to the orphan registry. An already-orphaned- // forward needs no flag; its finally owner releases and drains it.- const entry = pending.get(frame.id);- if (entry) entry.forwardSettled = true;+ entry.forwardSettled = true;};- forwardRequest(frame, { signal: controller.signal })+ forwardRequest(frame, { signal: entry.controller.signal, body }).then((result) => {markForwardSettled();@@ -1004,20 +1166,7 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr},(error) => {markForwardSettled();- return handleForwardRejection(error);- },- )- .finally(() => {- pending.delete(frame.id);- orphanedForwards.delete(frame.id);- releaseForwardTokens();- });-- // The forward rejection handler. It classifies the rejection by method safety- // and answers the gateway. The `markForwardSettled` call above runs first, so- // the response never re-orphans a settled forward.- function handleForwardRejection(error: unknown): void {- if (controller.signal.aborted) {+ if (entry.controller.signal.aborted) {// The forward budget aborted the call. A safe method never changes// host state, so a forward timeout stays retryable for it. Return a// 504 with the completed outcome and no indeterminate marker, so the@@ -1103,7 +1252,61 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBr"indeterminate","error",);+ },+ )+ .finally(() => {+ // The single forward cleanup owner. Release the request tokens, dispose the+ // reassembled body, and drop the request from the pending and orphan maps,+ // each exactly one time.+ pending.delete(frame.id);+ orphanedForwards.delete(frame.id);+ entry.releaseForwardTokens();+ if (entry.reassembled !== null) {+ void entry.reassembled.dispose();+ entry.reassembled = null;+ }+ });+ };++ // The request body reassembly failed. A malformed chunk, a size mismatch, an+ // overrun, or a truncation is a terminal protocol failure, so the broker fails+ // the channel closed. A `channel_closed` error is the broker's own teardown of an+ // in-flight body, so it is not a fresh loss.+ const onBodyError = (id: string, entry: PendingRequest, error: unknown): void => {+ reassembling.delete(id);+ // The forward never ran, so release its request tokens and drop the request+ // from the pending and orphan maps. The release is idempotent, so a teardown+ // that already released the tokens keeps the count correct.+ pending.delete(id);+ orphanedForwards.delete(id);+ entry.releaseForwardTokens();+ if (stopped) return;+ if (error instanceof DuplexBodyError && error.code === "channel_closed") return;+ recordLoss("protocol_failure", errorMessage(error));+ };++ // Route one `body_chunk` frame. A chunk for an id under reassembly goes to the+ // reassembler, which validates it and appends it. A chunk for a refused or+ // duplicate id drains against its recorded byte count and drops. A chunk with no+ // matching envelope is a terminal protocol failure.+ const handleBodyChunk = (frame: DuplexBodyChunkFrame): void => {+ if (reassembling.has(frame.id)) {+ const result = receiver.pushChunk(frame);+ if (!result.ok) recordLoss("protocol_failure", result.error.message);+ return;+ }+ const remaining = draining.get(frame.id);+ if (remaining !== undefined) {+ // Drain and drop a chunk of a refused body. The broker does not validate a+ // drained chunk; it only tracks the byte progress, so it stops draining once+ // the refused body ends. A further chunk after that is a chunk with no+ // envelope.+ const next = remaining - Buffer.byteLength(frame.data, "base64");+ if (next > 0) draining.set(frame.id, next);+ else draining.delete(frame.id);+ return;}+ recordLoss("protocol_failure", "body_chunk arrived with no matching envelope");};const handleFrame = (frame: DuplexFrame): void => {@@ -1111,6 +1314,9 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrcase "request":dispatch(frame);return;+ case "body_chunk":+ handleBodyChunk(frame);+ return;case "close":// The gateway asked for an orderly close. The gateway sends this frame on// the agent's orderly completion, so mark the completion on the ordered@@ -1201,6 +1407,9 @@ export function createDuplexBridgeBroker(options: DuplexBrokerOptions): DuplexBrif (closeTimer !== undefined) clearTimeout(closeTimer);recordLoss("close_timeout", errorMessage(error));}+ // Remove the spill directory and every in-flight body. The broker owns the+ // reassembler, so the orderly close cleans it up.+ await finalizeReceiver();})();return closePromise;};diff --git a/packages/adapter-utils/src/duplex-bridge-local-e2e.test.ts b/packages/adapter-utils/src/duplex-bridge-local-e2e.test.tsindex a4e2942c97..91485d7908 100644--- a/packages/adapter-utils/src/duplex-bridge-local-e2e.test.ts+++ b/packages/adapter-utils/src/duplex-bridge-local-e2e.test.ts@@ -4,6 +4,7 @@ import net from "node:net";import { mkdtemp, rm, writeFile } from "node:fs/promises";import os from "node:os";import path from "node:path";+import { Readable } from "node:stream";import { StringDecoder } from "node:string_decoder";import { afterEach, describe, expect, it } from "vitest";@@ -14,6 +15,9 @@ import {} from "./sandbox-callback-bridge.js";import {DuplexFrameDecoder,+ DUPLEX_BODY_CHUNK_RAW_BYTES,+ DUPLEX_FRAME_VERSION,+ encodeDuplexFrame,type DuplexFrame,type DuplexReadyFrame,type DuplexRequestFrame,@@ -23,6 +27,7 @@ import {type DuplexBridgeBroker,type DuplexBrokerForwardResult,} from "./duplex-bridge-broker.js";+import type { ReassembledBody } from "./duplex-body-spool.js";import type { CommandManagedDuplexChannel } from "./command-managed-runtime.js";/**@@ -299,7 +304,7 @@ async function createHarness(options: HarnessOptions = {}): Promise<DuplexE2EHarconst forwardRequest = async (request: DuplexRequestFrame,- opts: { signal: AbortSignal },+ opts: { signal: AbortSignal; body: ReassembledBody },): Promise<DuplexBrokerForwardResult> => {forwardedRequests.push(request);// Keep the real route allowlist on the forward seam. The broker forwards@@ -334,12 +339,16 @@ async function createHarness(options: HarnessOptions = {}): Promise<DuplexE2EHarheaders.set("authorization", `Bearer ${hostApiToken}`);headers.set("x-paperclip-run-id", runId);const target = new URL(`${request.path}${request.query ?? ""}`, api.origin);- const response = await fetch(target, {- method,- headers,- ...(method === "GET" || method === "HEAD" ? {} : { body: request.body }),- signal: opts.signal,- });+ // Stream the reassembled request body to the host, the same as the real+ // forward. A streamed body needs `duplex: "half"`.+ const forwardInit: RequestInit & { duplex?: "half" } = { method, headers, signal: opts.signal };+ if (method !== "GET" && method !== "HEAD") {+ forwardInit.body = Readable.toWeb(+ opts.body.createReadStream(),+ ) as unknown as ReadableStream<Uint8Array>;+ forwardInit.duplex = "half";+ }+ const response = await fetch(target, forwardInit);const body = await response.text();const outHeaders: Record<string, string> = {};response.headers.forEach((value, key) => {@@ -349,7 +358,7 @@ async function createHarness(options: HarnessOptions = {}): Promise<DuplexE2EHarreturn { status: response.status, headers: outHeaders, body };};- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel,forwardRequest,logger: () => undefined,@@ -456,7 +465,7 @@ describe("duplex bridge local end-to-end harness", () => {const ready = harness.observedFrames.find((frame) => frame.type === "ready",) as DuplexReadyFrame;- expect(ready.version).toBe(1);+ expect(ready.version).toBe(2);expect(ready.nonce).toBe(harness.nonce);// READY is liveness only. It carries no address data.expect((ready as unknown as Record<string, unknown>).address).toBeUndefined();@@ -643,4 +652,90 @@ describe("duplex bridge local end-to-end harness", () => {expect(harness.api.listening()).toBe(false);expect(harness.api.openSocketCount()).toBe(0);}, 20000);++ it("fails a request with a local 502 when the host sends a malformed response chunk", async () => {+ const RAW = DUPLEX_BODY_CHUNK_RAW_BYTES;+ // Each case declares one malformed body_chunk a broken or hostile host could+ // send. The gateway must reject it at once with a local 502. It must not grow+ // its response reassembly buffer until the response timeout. `bodyByteCount`+ // sets the declared body size on the response envelope. `data` is the base64+ // payload of the one injected chunk.+ const cases: Array<{ name: string; bodyByteCount: number; data: string; error: string }> = [+ { name: "an empty chunk", bodyByteCount: RAW, data: "", error: "duplex response body_chunk is empty" },+ {+ name: "an undersized non-final chunk",+ bodyByteCount: RAW + 8,+ data: Buffer.alloc(4, 1).toString("base64"),+ error: "duplex response body_chunk has the wrong size",+ },+ {+ name: "an oversized chunk",+ bodyByteCount: RAW + 8,+ data: Buffer.alloc(RAW + 4, 1).toString("base64"),+ error: "duplex response body_chunk has the wrong size",+ },+ {+ name: "an overrun past the declared size",+ bodyByteCount: 10,+ data: Buffer.alloc(200, 1).toString("base64"),+ error: "duplex response body overruns the declared size",+ },+ {+ name: "a non-canonical base64 chunk",+ bodyByteCount: 10,+ data: "AB==",+ error: "duplex response body_chunk is not canonical base64",+ },+ ];++ const harness = await createHarness();+ harnesses.push(harness);+ await harness.waitFor(readyPredicate(harness), "the gateway to become ready");++ // Hold the broker forward open, so only the injected frames answer each+ // request. The gateway reassembles the response body itself, so a raw+ // malformed chunk on its stdin drives the reject path under test.+ harness.setForwardMode("hang");++ for (const testCase of cases) {+ const forwardedBefore = harness.forwardedRequests.length;+ const pendingFetch = fetch(`${harness.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${harness.bridgeToken}` },+ });+ void pendingFetch.catch(() => undefined);+ await harness.waitFor(+ () => harness.forwardedRequests.length > forwardedBefore,+ `the broker to receive the forwarded request for ${testCase.name}`,+ );+ const id = harness.forwardedRequests[harness.forwardedRequests.length - 1].id;++ // Inject the response envelope, then the one malformed body_chunk, straight+ // to the gateway stdin. This bypasses the broker response encoder, so the+ // gateway sees the exact bytes a broken or hostile host could send.+ harness.child.stdin.write(+ encodeDuplexFrame({+ version: DUPLEX_FRAME_VERSION,+ type: "response",+ id,+ status: 200,+ headers: {},+ bodyByteCount: testCase.bodyByteCount,+ outcome: "completed",+ }),+ );+ harness.child.stdin.write(+ encodeDuplexFrame({+ version: DUPLEX_FRAME_VERSION,+ type: "body_chunk",+ id,+ seq: 0,+ data: testCase.data,+ }),+ );++ const response = await pendingFetch;+ expect(response.status).toBe(502);+ await expect(response.json()).resolves.toEqual({ error: testCase.error });+ }+ }, 20000);});diff --git a/packages/adapter-utils/src/duplex-frame-codec.test.ts b/packages/adapter-utils/src/duplex-frame-codec.test.tsindex c19008fb55..0fddd5e3cc 100644--- a/packages/adapter-utils/src/duplex-frame-codec.test.ts+++ b/packages/adapter-utils/src/duplex-frame-codec.test.ts@@ -126,7 +126,7 @@ describe("round-trip", () => {),),);- for (const type of ["request", "response", "ready", "heartbeat", "close", "error"]) {+ for (const type of ["request", "response", "body_chunk", "ready", "heartbeat", "close", "error"]) {expect(types).toContain(type);}});@@ -212,8 +212,8 @@ describe("streaming decoder behavior", () => {method: "POST",path: "/x",query: "",- headers: {},- body: "😀",+ headers: { "x-note": "😀" },+ bodyByteCount: 0,};const bytes = Buffer.from(encodeDuplexFrame(frame), "utf8");// Split inside the four-byte emoji, right before a continuation byte.@@ -275,7 +275,7 @@ describe("request id byte bound", () => {path: "/",query: "",headers: {},- body: "",+ bodyByteCount: 0,});}@@ -314,7 +314,7 @@ describe("request id byte bound", () => {id,status: 200,headers: {},- body: "",+ bodyByteCount: 0,outcome: "completed",}),);@@ -461,8 +461,8 @@ describe("size-checked encode", () => {type: "response",id: "big",status: 200,- headers: {},- body: "x".repeat(2_000),+ headers: { "x-pad": "x".repeat(2_000) },+ bodyByteCount: 0,outcome: "completed",};expect(() => encodeDuplexFrameChecked(frame, 1_000)).not.toThrow();@@ -475,22 +475,25 @@ describe("size-checked encode", () => {// Build a frame whose encoded JSON is exactly N bytes. The guard measures the// JSON without the newline, so N bytes encodes and N+1 bytes fails. This is the// same boundary the decoder applies, so encode and decode agree exactly.- const base: DuplexFrame = {+ // Pad a header value to grow the encoded JSON by an exact byte count. The+ // "x-pad" value adds one byte per character, so the frame lands on an exact+ // size the guard measures without the trailing newline.+ const pad = (n: number): DuplexFrame => ({version: DUPLEX_FRAME_VERSION,type: "response",id: "boundary",status: 200,- headers: {},- body: "",+ headers: { "x-pad": "x".repeat(n) },+ bodyByteCount: 0,outcome: "completed",- };- const baseBytes = Buffer.byteLength(JSON.stringify(base), "utf8");+ });+ const baseBytes = Buffer.byteLength(JSON.stringify(pad(0)), "utf8");const limit = baseBytes + 10;- const atLimit: DuplexFrame = { ...base, body: "x".repeat(10) };+ const atLimit = pad(10);expect(Buffer.byteLength(JSON.stringify(atLimit), "utf8")).toBe(limit);const okResult = encodeDuplexFrameChecked(atLimit, limit);expect(okResult.ok).toBe(true);- const overResult = encodeDuplexFrameChecked({ ...base, body: "x".repeat(11) }, limit);+ const overResult = encodeDuplexFrameChecked(pad(11), limit);expect(overResult.ok).toBe(false);if (!overResult.ok) expect(overResult.error.code).toBe("frame_too_large");});diff --git a/packages/adapter-utils/src/duplex-frame-codec.ts b/packages/adapter-utils/src/duplex-frame-codec.tsindex c1723ad763..1013dbf106 100644--- a/packages/adapter-utils/src/duplex-frame-codec.ts+++ b/packages/adapter-utils/src/duplex-frame-codec.ts@@ -24,7 +24,15 @@ import {} from "./duplex-aggregate-byte-ledger.js";/** The wire version this codec reads and writes. */-export const DUPLEX_FRAME_VERSION = 1;+export const DUPLEX_FRAME_VERSION = 2;++/**+ * The fixed raw byte size of one body slice. The sender splits a body into+ * `body_chunk` frames of this raw size, except the final chunk, which holds the+ * remaining bytes. The base64 text of one full slice is about 349 KiB, so each+ * encoded `body_chunk` frame stays well under {@link DEFAULT_MAX_DUPLEX_FRAME_BYTES}.+ */+export const DUPLEX_BODY_CHUNK_RAW_BYTES = 256 * 1024;/*** The default maximum size of one frame, in bytes. The decoder rejects a longer@@ -54,6 +62,7 @@ const EMPTY = Buffer.alloc(0);export const DUPLEX_FRAME_TYPES = {request: "request",response: "response",+ body_chunk: "body_chunk",ready: "ready",heartbeat: "heartbeat",close: "close",@@ -63,7 +72,12 @@ export const DUPLEX_FRAME_TYPES = {/** The outcome of a response frame. A loss response carries a non-completed outcome. */export type DuplexResponseOutcome = "completed" | "indeterminate" | "unavailable";-/** A request frame. The gateway forwards it to the host API path. */+/**+ * A request envelope frame. The gateway forwards it to the host API path. The+ * envelope carries `bodyByteCount`, the raw byte length of the request body. The+ * body itself rides one or more `body_chunk` frames that share the same `id`. A+ * `bodyByteCount` of 0 means an empty body and no `body_chunk` frame follows.+ */export interface DuplexRequestFrame {version: number;type: "request";@@ -72,20 +86,43 @@ export interface DuplexRequestFrame {path: string;query: string;headers: Record<string, string>;- body: string;+ bodyByteCount: number;}-/** A response frame. The host returns it for one request id. */+/**+ * A response envelope frame. The host returns it for one request id. The+ * envelope carries `bodyByteCount`, the raw byte length of the response body.+ * The body itself rides one or more `body_chunk` frames that share the same+ * `id`. A `bodyByteCount` of 0 means an empty body and no `body_chunk` frame+ * follows.+ */export interface DuplexResponseFrame {version: number;type: "response";id: string;status: number;headers: Record<string, string>;- body: string;+ bodyByteCount: number;outcome: DuplexResponseOutcome;}+/**+ * A body-chunk frame. One frame carries one raw body slice as base64 text in+ * `data`. The frames for one body share the `id` of the envelope. `seq` starts+ * at 0 and increases by one for each next chunk, with no gap and no repeat. Each+ * raw slice is {@link DUPLEX_BODY_CHUNK_RAW_BYTES} bytes, except the final slice,+ * which holds the remaining bytes. The receiver reassembles the slices in `seq`+ * order and stops when the total raw byte count equals the envelope+ * `bodyByteCount`.+ */+export interface DuplexBodyChunkFrame {+ version: number;+ type: "body_chunk";+ id: string;+ seq: number;+ data: string;+}+/*** The READY control frame. The gateway sends it one time after it binds the* host-assigned listener port. READY is a liveness signal, not an address@@ -129,6 +166,7 @@ export interface DuplexErrorFrame {export type DuplexFrame =| DuplexRequestFrame| DuplexResponseFrame+ | DuplexBodyChunkFrame| DuplexReadyFrame| DuplexHeartbeatFrame| DuplexCloseFrame@@ -194,6 +232,11 @@ function idWithinLimit(id: string): boolean {return Buffer.byteLength(id, "utf8") <= DEFAULT_MAX_DUPLEX_REQUEST_ID_BYTES;}+/** Return true when the value is a safe integer that is zero or positive. */+function isSafeNonNegativeInteger(value: unknown): value is number {+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;+}+/*** Encode one frame to a single line of JSON with a trailing newline. `JSON.stringify`* escapes any newline inside a string value, so the returned line holds no@@ -261,6 +304,8 @@ function validateFrame(frame: Record<string, unknown>): DuplexDecodeResult {return validateRequest(frame);case "response":return validateResponse(frame);+ case "body_chunk":+ return validateBodyChunk(frame);case "ready":return validateReady(frame);case "heartbeat":@@ -280,7 +325,7 @@ function validateRequest(frame: Record<string, unknown>): DuplexDecodeResult {typeof frame.method !== "string" ||typeof frame.path !== "string" ||typeof frame.query !== "string" ||- typeof frame.body !== "string" ||+ !isSafeNonNegativeInteger(frame.bodyByteCount) ||!isStringRecord(frame.headers)) {return fail("malformed_frame", "request frame has a missing or wrong-typed field");@@ -298,7 +343,7 @@ function validateResponse(frame: Record<string, unknown>): DuplexDecodeResult {if (typeof frame.id !== "string" ||typeof frame.status !== "number" ||- typeof frame.body !== "string" ||+ !isSafeNonNegativeInteger(frame.bodyByteCount) ||!isStringRecord(frame.headers) ||typeof frame.outcome !== "string" ||!RESPONSE_OUTCOMES.has(frame.outcome)@@ -313,6 +358,29 @@ function validateResponse(frame: Record<string, unknown>): DuplexDecodeResult {return ok(frame as unknown as DuplexResponseFrame);}+/**+ * Validate a `body_chunk` frame at the structural level. The codec is stateless,+ * so it checks only the per-frame shape here:+ * - `id` is a string within {@link DEFAULT_MAX_DUPLEX_REQUEST_ID_BYTES}.+ * - `seq` is a safe integer that is zero or positive.+ * - `data` is a string.+ * The receive-side reassembler owns the stateful checks: the base64 canonical+ * form, the fixed slice size, the `seq` order, and the total against+ * `bodyByteCount`. The codec never decodes `data` here.+ */+function validateBodyChunk(frame: Record<string, unknown>): DuplexDecodeResult {+ if (typeof frame.id !== "string" || typeof frame.data !== "string") {+ return fail("malformed_frame", "body_chunk frame has a missing or wrong-typed field");+ }+ if (!isSafeNonNegativeInteger(frame.seq)) {+ return fail("malformed_frame", "body_chunk frame has a missing or wrong-typed seq");+ }+ if (!idWithinLimit(frame.id)) {+ return fail("id_too_large", "body_chunk frame id exceeds the maximum size");+ }+ return ok(frame as unknown as DuplexBodyChunkFrame);+}+function validateReady(frame: Record<string, unknown>): DuplexDecodeResult {// READY carries a liveness nonce, not an address. The schema is strict: a valid// READY frame holds exactly `version`, `type`, and `nonce`. The decoder rejectsdiff --git a/packages/adapter-utils/src/duplex-frame-vectors.json b/packages/adapter-utils/src/duplex-frame-vectors.jsonindex 5bedc93081..62d43d1c15 100644--- a/packages/adapter-utils/src/duplex-frame-vectors.json+++ b/packages/adapter-utils/src/duplex-frame-vectors.json@@ -1,17 +1,17 @@{- "frameVersion": 1,+ "frameVersion": 2,"defaultMaxFrameBytes": 1000000,"description": "Shared wire-compatibility vectors for the duplex frame codec. Every codec copy decodes the same bytes. bytes is a UTF-8 byte stream; splitByteOffsets cuts it into chunks; expected lists the ordered decode results (frame or protocol-error code).","vectors": [{"name": "valid-request","category": "valid",- "bytes": "{\"version\":1,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"body\":\"\"}\n",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"bodyByteCount\":0}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "request","id": "req-1","method": "GET",@@ -21,7 +21,30 @@"accept": "application/json","content-type": "application/json"},- "body": ""+ "bodyByteCount": 0+ }+ }+ ]+ },+ {+ "name": "valid-request-with-body-count",+ "category": "valid",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-body\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"bodyByteCount\":1048576}\n",+ "roundTrip": true,+ "expected": [+ {+ "frame": {+ "version": 2,+ "type": "request",+ "id": "req-body",+ "method": "GET",+ "path": "/api/issues/PAP-1",+ "query": "expand=comments",+ "headers": {+ "accept": "application/json",+ "content-type": "application/json"+ },+ "bodyByteCount": 1048576}}]@@ -29,19 +52,19 @@{"name": "valid-response-completed","category": "valid",- "bytes": "{\"version\":1,\"type\":\"response\",\"id\":\"req-1\",\"status\":200,\"headers\":{\"content-type\":\"application/json\"},\"body\":\"{\\\"ok\\\":true}\",\"outcome\":\"completed\"}\n",+ "bytes": "{\"version\":2,\"type\":\"response\",\"id\":\"req-1\",\"status\":200,\"headers\":{\"content-type\":\"application/json\"},\"bodyByteCount\":11,\"outcome\":\"completed\"}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "response","id": "req-1","status": 200,"headers": {"content-type": "application/json"},- "body": "{\"ok\":true}",+ "bodyByteCount": 11,"outcome": "completed"}}@@ -50,19 +73,19 @@{"name": "valid-response-indeterminate","category": "valid",- "bytes": "{\"version\":1,\"type\":\"response\",\"id\":\"req-2\",\"status\":409,\"headers\":{\"content-type\":\"application/json\"},\"body\":\"{\\\"error\\\":\\\"outcome_indeterminate\\\"}\",\"outcome\":\"indeterminate\"}\n",+ "bytes": "{\"version\":2,\"type\":\"response\",\"id\":\"req-2\",\"status\":409,\"headers\":{\"content-type\":\"application/json\"},\"bodyByteCount\":33,\"outcome\":\"indeterminate\"}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "response","id": "req-2","status": 409,"headers": {"content-type": "application/json"},- "body": "{\"error\":\"outcome_indeterminate\"}",+ "bodyByteCount": 33,"outcome": "indeterminate"}}@@ -71,78 +94,82 @@{"name": "valid-response-unavailable","category": "valid",- "bytes": "{\"version\":1,\"type\":\"response\",\"id\":\"req-3\",\"status\":503,\"headers\":{\"content-type\":\"application/json\"},\"body\":\"{\\\"error\\\":\\\"bridge_unavailable\\\"}\",\"outcome\":\"unavailable\"}\n",+ "bytes": "{\"version\":2,\"type\":\"response\",\"id\":\"req-3\",\"status\":503,\"headers\":{\"content-type\":\"application/json\"},\"bodyByteCount\":30,\"outcome\":\"unavailable\"}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "response","id": "req-3","status": 503,"headers": {"content-type": "application/json"},- "body": "{\"error\":\"bridge_unavailable\"}",+ "bodyByteCount": 30,"outcome": "unavailable"}}]},{- "name": "valid-ready",+ "name": "valid-body-chunk","category": "valid",- "bytes": "{\"version\":1,\"type\":\"ready\",\"nonce\":\"9f8e7d6c5b4a39281706f5e4d3c2b1a0\"}\n",+ "bytes": "{\"version\":2,\"type\":\"body_chunk\",\"id\":\"req-1\",\"seq\":0,\"data\":\"aGVsbG8gYm9keSBjaHVuaw==\"}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,- "type": "ready",- "nonce": "9f8e7d6c5b4a39281706f5e4d3c2b1a0"+ "version": 2,+ "type": "body_chunk",+ "id": "req-1",+ "seq": 0,+ "data": "aGVsbG8gYm9keSBjaHVuaw=="}}]},{- "name": "invalid-ready-missing-nonce",- "category": "invalid",- "bytes": "{\"version\":1,\"type\":\"ready\"}\n",- "expected": [- {- "error": "malformed_frame"- }- ]- },- {- "name": "invalid-ready-with-address",- "category": "invalid",- "bytes": "{\"version\":1,\"type\":\"ready\",\"nonce\":\"9f8e7d6c5b4a39281706f5e4d3c2b1a0\",\"address\":\"http://127.0.0.1:47215\"}\n",+ "name": "valid-body-chunk-final",+ "category": "valid",+ "bytes": "{\"version\":2,\"type\":\"body_chunk\",\"id\":\"req-1\",\"seq\":7,\"data\":\"dGFpbA==\"}\n",+ "roundTrip": true,"expected": [{- "error": "malformed_frame"+ "frame": {+ "version": 2,+ "type": "body_chunk",+ "id": "req-1",+ "seq": 7,+ "data": "dGFpbA=="+ }}]},{- "name": "invalid-ready-with-port",- "category": "invalid",- "bytes": "{\"version\":1,\"type\":\"ready\",\"nonce\":\"9f8e7d6c5b4a39281706f5e4d3c2b1a0\",\"port\":47215}\n",+ "name": "valid-ready",+ "category": "valid",+ "bytes": "{\"version\":2,\"type\":\"ready\",\"nonce\":\"9f8e7d6c5b4a39281706f5e4d3c2b1a0\"}\n",+ "roundTrip": true,"expected": [{- "error": "malformed_frame"+ "frame": {+ "version": 2,+ "type": "ready",+ "nonce": "9f8e7d6c5b4a39281706f5e4d3c2b1a0"+ }}]},{"name": "valid-heartbeat","category": "valid",- "bytes": "{\"version\":1,\"type\":\"heartbeat\"}\n",+ "bytes": "{\"version\":2,\"type\":\"heartbeat\"}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "heartbeat"}}@@ -151,12 +178,12 @@{"name": "valid-close","category": "valid",- "bytes": "{\"version\":1,\"type\":\"close\"}\n",+ "bytes": "{\"version\":2,\"type\":\"close\"}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "close"}}@@ -165,12 +192,12 @@{"name": "valid-error","category": "valid",- "bytes": "{\"version\":1,\"type\":\"error\",\"code\":\"malformed_frame\",\"message\":\"peer reported a malformed frame\"}\n",+ "bytes": "{\"version\":2,\"type\":\"error\",\"code\":\"malformed_frame\",\"message\":\"peer reported a malformed frame\"}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "error","code": "malformed_frame","message": "peer reported a malformed frame"@@ -178,6 +205,36 @@}]},+ {+ "name": "invalid-ready-missing-nonce",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"ready\"}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-ready-with-address",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"ready\",\"nonce\":\"9f8e7d6c5b4a39281706f5e4d3c2b1a0\",\"address\":\"http://127.0.0.1:47215\"}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-ready-with-port",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"ready\",\"nonce\":\"9f8e7d6c5b4a39281706f5e4d3c2b1a0\",\"port\":47215}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },{"name": "invalid-not-json","category": "invalid",@@ -211,7 +268,7 @@{"name": "invalid-unknown-type","category": "invalid",- "bytes": "{\"version\":1,\"type\":\"teleport\"}\n",+ "bytes": "{\"version\":2,\"type\":\"teleport\"}\n","expected": [{"error": "unknown_type"@@ -221,7 +278,37 @@{"name": "invalid-missing-id","category": "invalid",- "bytes": "{\"version\":1,\"type\":\"request\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"body\":\"\"}\n",+ "bytes": "{\"version\":2,\"type\":\"request\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"bodyByteCount\":0}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-request-body-count-string",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"bodyByteCount\":\"10\"}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-request-body-count-negative",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"bodyByteCount\":-1}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-request-body-count-fractional",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"bodyByteCount\":1.5}\n","expected": [{"error": "malformed_frame"@@ -231,7 +318,47 @@{"name": "invalid-bad-headers","category": "invalid",- "bytes": "{\"version\":1,\"type\":\"response\",\"id\":\"req-1\",\"status\":200,\"headers\":{\"accept\":7},\"body\":\"{\\\"ok\\\":true}\",\"outcome\":\"completed\"}\n",+ "bytes": "{\"version\":2,\"type\":\"response\",\"id\":\"req-1\",\"status\":200,\"headers\":{\"accept\":7},\"bodyByteCount\":10,\"outcome\":\"completed\"}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-body-chunk-negative-seq",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"body_chunk\",\"id\":\"req-1\",\"seq\":-1,\"data\":\"eA==\"}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-body-chunk-fractional-seq",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"body_chunk\",\"id\":\"req-1\",\"seq\":2.5,\"data\":\"eA==\"}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-body-chunk-missing-data",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"body_chunk\",\"id\":\"req-1\",\"seq\":0}\n",+ "expected": [+ {+ "error": "malformed_frame"+ }+ ]+ },+ {+ "name": "invalid-body-chunk-nonstring-data",+ "category": "invalid",+ "bytes": "{\"version\":2,\"type\":\"body_chunk\",\"id\":\"req-1\",\"seq\":0,\"data\":42}\n","expected": [{"error": "malformed_frame"@@ -241,14 +368,14 @@{"name": "partial-request-split","category": "partial",- "bytes": "{\"version\":1,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"body\":\"\"}\n",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"bodyByteCount\":0}\n","splitByteOffsets": [- 98+ 102],"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "request","id": "req-1","method": "GET",@@ -258,7 +385,7 @@"accept": "application/json","content-type": "application/json"},- "body": ""+ "bodyByteCount": 0}}]@@ -266,23 +393,24 @@{"name": "partial-utf8-split","category": "partial",- "bytes": "{\"version\":1,\"type\":\"request\",\"id\":\"req-utf8\",\"method\":\"POST\",\"path\":\"/api/issues/PAP-1/comments\",\"query\":\"\",\"headers\":{\"content-type\":\"application/json\"},\"body\":\"{\\\"text\\\":\\\"héllo 😀 wörld\\\"}\"}\n",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-utf8\",\"method\":\"POST\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"content-type\":\"application/json\",\"x-note\":\"héllo 😀 wörld\"},\"bodyByteCount\":0}\n","splitByteOffsets": [- 177+ 172],"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "request","id": "req-utf8","method": "POST",- "path": "/api/issues/PAP-1/comments",- "query": "",+ "path": "/api/issues/PAP-1",+ "query": "expand=comments","headers": {- "content-type": "application/json"+ "content-type": "application/json",+ "x-note": "héllo 😀 wörld"},- "body": "{\"text\":\"héllo 😀 wörld\"}"+ "bodyByteCount": 0}}]@@ -290,16 +418,16 @@{"name": "partial-two-frames","category": "partial",- "bytes": "{\"version\":1,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"body\":\"\"}\n{\"version\":1,\"type\":\"response\",\"id\":\"req-1\",\"status\":200,\"headers\":{\"content-type\":\"application/json\"},\"body\":\"{\\\"ok\\\":true}\",\"outcome\":\"completed\"}\n",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"bodyByteCount\":0}\n{\"version\":2,\"type\":\"response\",\"id\":\"req-1\",\"status\":200,\"headers\":{\"content-type\":\"application/json\"},\"bodyByteCount\":11,\"outcome\":\"completed\"}\n","splitByteOffsets": [7,- 199,- 343+ 174,+ 344],"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "request","id": "req-1","method": "GET",@@ -309,19 +437,19 @@"accept": "application/json","content-type": "application/json"},- "body": ""+ "bodyByteCount": 0}},{"frame": {- "version": 1,+ "version": 2,"type": "response","id": "req-1","status": 200,"headers": {"content-type": "application/json"},- "body": "{\"ok\":true}",+ "bodyByteCount": 11,"outcome": "completed"}}@@ -330,14 +458,14 @@{"name": "partial-no-trailing-newline","category": "partial",- "bytes": "{\"version\":1,\"type\":\"heartbeat\"}",+ "bytes": "{\"version\":2,\"type\":\"heartbeat\"}","expected": []},{"name": "oversized-complete-line","category": "oversized","maxFrameBytes": 64,- "bytes": "{\"version\":1,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"body\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"}\n",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"q=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"bodyByteCount\":0}\n","expected": [{"error": "frame_too_large"@@ -351,23 +479,33 @@"splitByteOffsets": [40],- "bytes": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy\n{\"version\":1,\"type\":\"heartbeat\"}\n",+ "bytes": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy\n{\"version\":2,\"type\":\"heartbeat\"}\n","expected": [{"error": "frame_too_large"},{"frame": {- "version": 1,+ "version": 2,"type": "heartbeat"}}]},+ {+ "name": "version-mismatch-lower",+ "category": "versionMismatch",+ "bytes": "{\"version\":1,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"bodyByteCount\":0}\n",+ "expected": [+ {+ "error": "version_mismatch"+ }+ ]+ },{"name": "version-mismatch-higher","category": "versionMismatch",- "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"body\":\"\"}\n",+ "bytes": "{\"version\":3,\"type\":\"request\",\"id\":\"req-1\",\"method\":\"GET\",\"path\":\"/api/issues/PAP-1\",\"query\":\"expand=comments\",\"headers\":{\"accept\":\"application/json\",\"content-type\":\"application/json\"},\"bodyByteCount\":0}\n","expected": [{"error": "version_mismatch"@@ -387,19 +525,19 @@{"name": "request-id-at-max-bytes","category": "idBoundValid",- "bytes": "{\"version\":1,\"type\":\"request\",\"id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"body\":\"\"}\n",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"bodyByteCount\":0}\n","roundTrip": true,"expected": [{"frame": {- "version": 1,+ "version": 2,"type": "request","id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","method": "GET","path": "/","query": "","headers": {},- "body": ""+ "bodyByteCount": 0}}]@@ -407,7 +545,17 @@{"name": "request-id-over-max-bytes","category": "idBoundInvalid",- "bytes": "{\"version\":1,\"type\":\"request\",\"id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"body\":\"\"}\n",+ "bytes": "{\"version\":2,\"type\":\"request\",\"id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"method\":\"GET\",\"path\":\"/\",\"query\":\"\",\"headers\":{},\"bodyByteCount\":0}\n",+ "expected": [+ {+ "error": "id_too_large"+ }+ ]+ },+ {+ "name": "body-chunk-id-over-max-bytes",+ "category": "idBoundInvalid",+ "bytes": "{\"version\":2,\"type\":\"body_chunk\",\"id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"seq\":0,\"data\":\"eA==\"}\n","expected": [{"error": "id_too_large"@@ -421,14 +569,28 @@"name": "encode-within-bound","maxFrameBytes": 200,"frame": {- "version": 1,+ "version": 2,"type": "request","id": "req-enc-1","method": "GET","path": "/","query": "","headers": {},- "body": "small"+ "bodyByteCount": 5+ },+ "expected": {+ "ok": true+ }+ },+ {+ "name": "encode-body-chunk-within-bound",+ "maxFrameBytes": 200,+ "frame": {+ "version": 2,+ "type": "body_chunk",+ "id": "req-enc-3",+ "seq": 0,+ "data": "Y2h1bmsgcGF5bG9hZA=="},"expected": {"ok": true@@ -438,7 +600,7 @@"name": "encode-control-frame-never-rejected","maxFrameBytes": 200,"frame": {- "version": 1,+ "version": 2,"type": "heartbeat"},"expected": {@@ -449,14 +611,15 @@"name": "encode-over-bound","maxFrameBytes": 200,"frame": {- "version": 1,+ "version": 2,"type": "response","id": "req-enc-2","status": 200,"headers": {- "content-type": "application/json"+ "content-type": "application/json",+ "x-pad": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},- "body": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",+ "bodyByteCount": 0,"outcome": "completed"},"expected": {diff --git a/packages/adapter-utils/src/execution-target-sandbox.test.ts b/packages/adapter-utils/src/execution-target-sandbox.test.tsindex 0ecf167102..b5c5c6b148 100644--- a/packages/adapter-utils/src/execution-target-sandbox.test.ts+++ b/packages/adapter-utils/src/execution-target-sandbox.test.ts@@ -61,6 +61,7 @@ import {type DuplexRequestFrame,type DuplexResponseFrame,} from "./duplex-frame-codec.js";+import { splitBodyIntoChunkFrames } from "./duplex-body-spool.js";import {assertNestedDuplexBrokerBudgets,createDuplexBridgeBroker,@@ -92,6 +93,51 @@ import {const execFileAsync = promisify(execFile);+/**+ * Emit one duplex request the way the sandbox gateway sends it under the chunked+ * body protocol: the envelope frame that carries `bodyByteCount`, then the+ * `body_chunk` frames that carry the body. A non-empty body rides one or more+ * `body_chunk` frames that share the envelope id; an empty body sends no chunk.+ */+function emitDuplexRequest(+ control: { emitData: (chunk: string) => void },+ frame: Omit<DuplexRequestFrame, "bodyByteCount">,+ bodyText: string,+): void {+ const body = Buffer.from(bodyText, "utf8");+ control.emitData(encodeDuplexFrame({ ...frame, bodyByteCount: body.length }));+ for (const chunk of splitBodyIntoChunkFrames(frame.id, body, DUPLEX_FRAME_VERSION)) {+ control.emitData(encodeDuplexFrame(chunk));+ }+}++/**+ * Send one duplex response the way the host broker sends it under the chunked+ * body protocol: the envelope frame that carries `bodyByteCount`, then the+ * `body_chunk` frames that carry the body. The gateway reassembles the body from+ * the chunk frames before it writes the HTTP response.+ */+function sendDuplexResponse(+ send: (frame: Record<string, unknown>) => void,+ response: { id: string | undefined; status: number; headers: Record<string, string>; outcome?: string },+ bodyText: string,+): void {+ const id = response.id ?? "";+ const body = Buffer.from(bodyText, "utf8");+ send({+ version: DUPLEX_FRAME_VERSION,+ type: "response",+ id,+ status: response.status,+ headers: response.headers,+ bodyByteCount: body.length,+ ...(response.outcome !== undefined ? { outcome: response.outcome } : {}),+ });+ for (const chunk of splitBodyIntoChunkFrames(id, body, DUPLEX_FRAME_VERSION)) {+ send(chunk as unknown as Record<string, unknown>);+ }+}+type RecordedSpan = { name: string; parentName: string | null; ended: boolean };/**@@ -3140,7 +3186,7 @@ describe("sandbox adapter execution targets", () => {if (onOpen) {onOpen({ nonce, port, emitRaw, emitFrame, emitExit });} else {- emitFrame({ version: 1, type: "ready", nonce });+ emitFrame({ version: 2, type: "ready", nonce });}});},@@ -3250,8 +3296,9 @@ describe("sandbox adapter execution targets", () => {// The gateway forwards one agent request as a request frame. The broker// forwards it on the host path with the real token and the run id, then// writes one response frame back.- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-1",@@ -3259,8 +3306,8 @@ describe("sandbox adapter execution targets", () => {path: "/api/agents/me",query: "",headers: { authorization: "Bearer bridge-token" },- body: "",- }),+ },+ "",);await waitForCondition(() => control.written.length >= 1,@@ -3304,7 +3351,7 @@ describe("sandbox adapter execution targets", () => {// The flood is larger than the ceiling; the READY frame is far smaller.const ledger = new DuplexAggregateByteLedger({ ceilingBytes: 4096 });const { runner, control } = makeDuplexSelectionRunner((ctx) => {- ctx.emitFrame({ version: 1, type: "ready", nonce: ctx.nonce });+ ctx.emitFrame({ version: 2, type: "ready", nonce: ctx.nonce });ctx.emitRaw("x".repeat(64 * 1024));});const { recorder, counters } = createRecordingDuplexRecorder();@@ -3557,15 +3604,15 @@ describe("sandbox adapter execution targets", () => {{name: "a mismatched nonce",onOpen: (ctx: DuplexOpenContext) =>- ctx.emitFrame({ version: 1, type: "ready", nonce: "00000000000000000000000000000000" }),+ ctx.emitFrame({ version: 2, type: "ready", nonce: "00000000000000000000000000000000" }),},{name: "an incomplete READY frame",- onOpen: (ctx: DuplexOpenContext) => ctx.emitRaw('{"version":1,"type":"ready"}\n'),+ onOpen: (ctx: DuplexOpenContext) => ctx.emitRaw('{"version":2,"type":"ready"}\n'),},{name: "protocol contamination before READY",- onOpen: (ctx: DuplexOpenContext) => ctx.emitFrame({ version: 1, type: "heartbeat" }),+ onOpen: (ctx: DuplexOpenContext) => ctx.emitFrame({ version: 2, type: "heartbeat" }),},{name: "a gateway bind failure with no READY frame",@@ -3619,12 +3666,12 @@ describe("sandbox adapter execution targets", () => {{name: "an attacker-owned numeric local port",buildReady: (nonce: string, attackerPort: number) =>- `{"version":1,"type":"ready","nonce":"${nonce}","port":${attackerPort}}\n`,+ `{"version":2,"type":"ready","nonce":"${nonce}","port":${attackerPort}}\n`,},{name: "a channel-supplied host URL",buildReady: (nonce: string, attackerPort: number) =>- `{"version":1,"type":"ready","nonce":"${nonce}","address":"http://127.0.0.1:${attackerPort}"}\n`,+ `{"version":2,"type":"ready","nonce":"${nonce}","address":"http://127.0.0.1:${attackerPort}"}\n`,},])("rejects a READY frame that carries $name and never sends the bridge token there",@@ -3724,8 +3771,9 @@ describe("sandbox adapter execution targets", () => {});try {expect(bridge?.env.PAPERCLIP_API_BRIDGE_MODE).toBe("duplex_v1");- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-forbidden",@@ -3733,8 +3781,8 @@ describe("sandbox adapter execution targets", () => {path: "/api/secret-admin-route",query: "",headers: { authorization: "Bearer bridge-token", "content-type": "application/json" },- body: JSON.stringify({ escalate: true }),- }),+ },+ JSON.stringify({ escalate: true }),);await waitForCondition(() => control.written.length >= 1,@@ -3850,8 +3898,9 @@ describe("sandbox adapter execution targets", () => {});try {expect(bridge?.env.PAPERCLIP_API_BRIDGE_MODE).toBe("duplex_v1");- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-obs",@@ -3859,8 +3908,8 @@ describe("sandbox adapter execution targets", () => {path: "/api/agents/me",query: "",headers: { authorization: "Bearer bridge-token" },- body: "",- }),+ },+ "",);await waitForCondition(() => control.written.length >= 1,@@ -4060,8 +4109,9 @@ describe("sandbox adapter execution targets", () => {try {expect(bridge?.env.PAPERCLIP_API_BRIDGE_MODE).toBe("duplex_v1");if (dispatchFirst) {- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-loss",@@ -4069,8 +4119,8 @@ describe("sandbox adapter execution targets", () => {path: "/api/agents/me",query: "",headers: { authorization: "Bearer bridge-token" },- body: "",- }),+ },+ "",);await waitForCondition(() => control.written.length >= 1,@@ -4126,8 +4176,9 @@ describe("sandbox adapter execution targets", () => {try {// The throwing recorder never blocked the duplex selection.expect(bridge?.env.PAPERCLIP_API_BRIDGE_MODE).toBe("duplex_v1");- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-guard",@@ -4135,8 +4186,8 @@ describe("sandbox adapter execution targets", () => {path: "/api/agents/me",query: "",headers: { authorization: "Bearer bridge-token" },- body: "",- }),+ },+ "",);await waitForCondition(() => control.written.length >= 1,@@ -4192,7 +4243,7 @@ describe("sandbox adapter execution targets", () => {onData(listener: (chunk: string) => void): void {dataListener = listener;control.emitData = (chunk) => dataListener?.(chunk);- setImmediate(() => dataListener?.(`${JSON.stringify({ version: 1, type: "ready", nonce })}\n`));+ setImmediate(() => dataListener?.(`${JSON.stringify({ version: 2, type: "ready", nonce })}\n`));},onExit(_listener: (exit: { exitCode: number | null }) => void): void {},stop(): void {},@@ -4237,8 +4288,9 @@ describe("sandbox adapter execution targets", () => {// A request that carries the sentinel route, query, body, and bridge token.// The response write then fails with the sentinel provider error.- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-redact",@@ -4246,8 +4298,8 @@ describe("sandbox adapter execution targets", () => {path: `/api/${ROUTE_SENTINEL}`,query: `secret=${QUERY_SENTINEL}`,headers: { authorization: `Bearer ${BRIDGE_TOKEN_SENTINEL}` },- body: BODY_SENTINEL,- }),+ },+ BODY_SENTINEL,);// Give the forward and the failing response write time to run and record a loss.await waitForCondition(@@ -4303,8 +4355,9 @@ describe("sandbox adapter execution targets", () => {});try {expect(bridge?.env.PAPERCLIP_API_BRIDGE_MODE).toBe("duplex_v1");- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-prov",@@ -4312,8 +4365,8 @@ describe("sandbox adapter execution targets", () => {path: "/api/agents/me",query: "",headers: { authorization: "Bearer bridge-token" },- body: "",- }),+ },+ "",);await waitForCondition(() => spans.some((s) => s.name === DUPLEX_SPAN_REQUEST),@@ -4527,7 +4580,7 @@ describe("sandbox adapter execution targets", () => {const reserveSpy = vi.spyOn(ledger, "reserve");const { runner, control } = makeDuplexSelectionRunner((ctx) => {ctx.emitRaw("pty-echo-noise");- ctx.emitFrame({ version: 1, type: "ready", nonce: ctx.nonce });+ ctx.emitFrame({ version: 2, type: "ready", nonce: ctx.nonce });});const target: AdapterSandboxExecutionTarget = {kind: "remote",@@ -4644,9 +4697,9 @@ describe("sandbox adapter execution targets", () => {const noisePrefix = "\n".repeat(blankLineCount) + "a non-frame echo line\n";const { runner, control } = makeDuplexSelectionRunner((ctx) => {ctx.emitRaw(noisePrefix);- ctx.emitFrame({ version: 1, type: "ready", nonce: ctx.nonce });+ ctx.emitFrame({ version: 2, type: "ready", nonce: ctx.nonce });});- const readyLine = '{"version":1,"type":"ready","nonce":"<nonce>"}\n';+ const readyLine = '{"version":2,"type":"ready","nonce":"<nonce>"}\n';const totalBytes = noisePrefix.length + readyLine.length;const { recorder, counters } = createRecordingDuplexRecorder();const target: AdapterSandboxExecutionTarget = {@@ -4701,8 +4754,8 @@ describe("sandbox adapter execution targets", () => {// must skip the echo line and a partial-JSON line, then accept the READY frame.const { runner, control } = makeDuplexSelectionRunner((ctx) => {ctx.emitRaw("sh -c exec env PAPERCLIP_BRIDGE_NONCE=... node gateway.mjs\n");- ctx.emitRaw('{"version":1,"type":"ready"}\n');- ctx.emitFrame({ version: 1, type: "ready", nonce: ctx.nonce });+ ctx.emitRaw('{"version":2,"type":"ready"}\n');+ ctx.emitFrame({ version: 2, type: "ready", nonce: ctx.nonce });});const { recorder, counters } = createRecordingDuplexRecorder();const target: AdapterSandboxExecutionTarget = {@@ -4752,7 +4805,7 @@ describe("sandbox adapter execution targets", () => {// the `ready_nonce_mismatch` reason.const { runner, control } = makeDuplexSelectionRunner((ctx) => {ctx.emitRaw("a non-frame echo line\n");- ctx.emitFrame({ version: 1, type: "ready", nonce: "00000000000000000000000000000000" });+ ctx.emitFrame({ version: 2, type: "ready", nonce: "00000000000000000000000000000000" });});const { recorder, counters } = createRecordingDuplexRecorder();const target: AdapterSandboxExecutionTarget = {@@ -4808,7 +4861,7 @@ describe("sandbox adapter execution targets", () => {// per-skip cap check stops the bypass.const readinessBufferCapBytes = DEFAULT_MAX_DUPLEX_FRAME_BYTES + 4_096;const { runner, control } = makeDuplexSelectionRunner((ctx) => {- const readyLine = `${JSON.stringify({ version: 1, type: "ready", nonce: ctx.nonce })}\n`;+ const readyLine = `${JSON.stringify({ version: 2, type: "ready", nonce: ctx.nonce })}\n`;ctx.emitRaw("\n".repeat(readinessBufferCapBytes + 1) + readyLine);});const { recorder, counters } = createRecordingDuplexRecorder();@@ -4860,7 +4913,7 @@ describe("sandbox adapter execution targets", () => {// carries the closed `fallback_reason` dimension, so a reader can group the// failed opens by reason.const { runner } = makeDuplexSelectionRunner((ctx) =>- ctx.emitFrame({ version: 1, type: "ready", nonce: "00000000000000000000000000000000" }),+ ctx.emitFrame({ version: 2, type: "ready", nonce: "00000000000000000000000000000000" }),);const { recorder, spans } = createRecordingDuplexRecorder();const target: AdapterSandboxExecutionTarget = {@@ -4930,8 +4983,9 @@ describe("sandbox adapter execution targets", () => {});try {expect(bridge?.env.PAPERCLIP_API_BRIDGE_MODE).toBe("duplex_v1");- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-hdr",@@ -4946,8 +5000,8 @@ describe("sandbox adapter execution targets", () => {// A sandbox-supplied auth header the host must replace with the real token.authorization: "Bearer bridge-token",},- body: "",- }),+ },+ "",);await waitForCondition(() => api.requests.length >= 1,@@ -5000,8 +5054,9 @@ describe("sandbox adapter execution targets", () => {try {// The broker started with derived nested budgets, so the duplex transport serves.expect(bridge?.env.PAPERCLIP_API_BRIDGE_MODE).toBe("duplex_v1");- control.emitData(- encodeDuplexFrame({+ emitDuplexRequest(+ control,+ {version: DUPLEX_FRAME_VERSION,type: "request",id: "req-budget",@@ -5009,8 +5064,8 @@ describe("sandbox adapter execution targets", () => {path: "/api/agents/me",query: "",headers: { authorization: "Bearer bridge-token" },- body: "",- }),+ },+ "",);await waitForCondition(() => control.written.length >= 1,@@ -5120,7 +5175,7 @@ describe("sandbox adapter execution targets", () => {"daytona@212487a7f3c9:~$ exec 2>'/tmp/paperclip-duplex-x.log'; stty raw -echo; " +"exec 'bash' '-c' 'exec env PAPERCLIP_BRIDGE_NONCE=" + ctx.nonce + " node gateway.mjs'\r\n",);- ctx.emitRaw('{"version":1,"type":"ready","nonce":"' + ctx.nonce + '"}\n');+ ctx.emitRaw('{"version":2,"type":"ready","nonce":"' + ctx.nonce + '"}\n');});expect(mode).toBe("duplex_v1");}, 20000);@@ -5137,7 +5192,7 @@ describe("sandbox adapter execution targets", () => {"stty raw -echo; exec 'bash' '-c' 'exec env node gateway.mjs'\r\n",);// No newline between the escape sequence and the frame: same line.- ctx.emitRaw('\x1b[?2004l\r{"version":1,"type":"ready","nonce":"' + ctx.nonce + '"}\n');+ ctx.emitRaw('\x1b[?2004l\r{"version":2,"type":"ready","nonce":"' + ctx.nonce + '"}\n');});expect(mode).toBe("duplex_v1");}, 20000);@@ -5146,7 +5201,7 @@ describe("sandbox adapter execution targets", () => {it("PTY replay: accepts READY split across chunk boundaries", async () => {const { mode } = await runReadinessReplay((ctx) => {ctx.emitRaw("prompt$ wrapper-line\r\n");- const frame = '{"version":1,"type":"ready","nonce":"' + ctx.nonce + '"}\n';+ const frame = '{"version":2,"type":"ready","nonce":"' + ctx.nonce + '"}\n';ctx.emitRaw(frame.slice(0, 12));ctx.emitRaw(frame.slice(12));});@@ -5159,7 +5214,7 @@ describe("sandbox adapter execution targets", () => {const noise = Buffer.from("prompt ✓ done\r\n", "utf8");ctx.emitRaw(noise.slice(0, 8).toString("utf8"));ctx.emitRaw(noise.slice(8).toString("utf8"));- ctx.emitRaw('{"version":1,"type":"ready","nonce":"' + ctx.nonce + '"}\n');+ ctx.emitRaw('{"version":2,"type":"ready","nonce":"' + ctx.nonce + '"}\n');});expect(mode).toBe("duplex_v1");}, 20000);@@ -5170,7 +5225,7 @@ describe("sandbox adapter execution targets", () => {const { mode } = await runReadinessReplay((ctx) => {const line = "x".repeat(64) + "\n";for (let i = 0; i < 80_000; i += 1) ctx.emitRaw(line);- ctx.emitRaw('{"version":1,"type":"ready","nonce":"' + ctx.nonce + '"}\n');+ ctx.emitRaw('{"version":2,"type":"ready","nonce":"' + ctx.nonce + '"}\n');});expect(mode).toBe("queue_v1");}, 30000);@@ -5280,7 +5335,7 @@ describe("sandbox duplex gateway", () => {// process the launch replaced the shell with.await writeFile(stub,- '#!/bin/sh\nprintf \'{"version":1,"type":"ready","nonce":"%s"}\\n\' "$PAPERCLIP_BRIDGE_NONCE"\n',+ '#!/bin/sh\nprintf \'{"version":2,"type":"ready","nonce":"%s"}\\n\' "$PAPERCLIP_BRIDGE_NONCE"\n',"utf8",);const argv = buildDuplexGatewayLaunchArgv({@@ -5641,15 +5696,16 @@ describe("sandbox duplex gateway", () => {"if-none-match": '"cache-key"',});- gateway.sendFrame({- version: 1,- type: "response",- id: requestFrame.id,- status: 200,- headers: { "content-type": "application/json", etag: '"rev-1"', "content-length": "999" },- body: JSON.stringify({ ok: true }),- outcome: "completed",- });+ sendDuplexResponse(+ gateway.sendFrame,+ {+ id: requestFrame.id,+ status: 200,+ headers: { "content-type": "application/json", etag: '"rev-1"', "content-length": "999" },+ outcome: "completed",+ },+ JSON.stringify({ ok: true }),+ );const response = await responsePromise;expect(response.status).toBe(200);expect(response.headers.get("content-type")).toContain("application/json");@@ -5666,42 +5722,45 @@ describe("sandbox duplex gateway", () => {const patchFrame = await gateway.waitForFrame((frame) => frame.type === "request" && frame.id !== requestFrame.id,);- gateway.sendFrame({- version: 1,- type: "response",- id: patchFrame.id,- status: 200,- headers: { "content-type": "application/json" },- body: JSON.stringify({ error: "outcome_indeterminate" }),- outcome: "indeterminate",- });+ sendDuplexResponse(+ gateway.sendFrame,+ {+ id: patchFrame.id,+ status: 200,+ headers: { "content-type": "application/json" },+ outcome: "indeterminate",+ },+ JSON.stringify({ error: "outcome_indeterminate" }),+ );const indeterminate = await indeterminatePromise;expect(indeterminate.status).toBe(409);await gateway.stop();}, 20000);- it("fails a request that exceeds the frame size bound with a local 413 and keeps the channel open", async () => {+ it("fails a request over the body size limit locally and keeps the channel open", async () => {const token = "duplex-token-oversize-request";- // Raise the body limit above the frame bound, so `readBody` accepts the body- // and the encode guard is the only limit the request meets. The default frame- // bound is 1,000,000 bytes.+ // The chunked body protocol splits a large body into fixed-size body_chunk+ // frames that each stay under the frame bound, so a body never exceeds the+ // frame bound on its own. The operative local guard for a request too large to+ // deliver is now the body size limit. Set it to 1,000,000 bytes here.const gateway = await startDuplexGateway({PAPERCLIP_BRIDGE_TOKEN: token,- PAPERCLIP_BRIDGE_MAX_BODY_BYTES: "3000000",+ PAPERCLIP_BRIDGE_MAX_BODY_BYTES: "1000000",});- // A body over the frame bound makes the request frame exceed the bound. The- // gateway must fail this one local request with a clean 413 and forward no- // frame.+ // A body over the body size limit is rejected locally. The gateway must fail+ // this one local request cleanly and forward no frame.const oversizeBody = JSON.stringify({ body: "x".repeat(1_100_000) });const tooLarge = await fetch(`${gateway.baseUrl}/api/issues/issue-1/comments`, {method: "POST",headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },body: oversizeBody,});- expect(tooLarge.status).toBe(413);- await expect(tooLarge.json()).resolves.toEqual({ error: "request_too_large" });+ expect(tooLarge.status).toBe(502);+ await expect(tooLarge.json()).resolves.toEqual({+ error: "Bridge request body exceeded the configured size limit.",+ });// The oversized request forwarded no frame. It never left the gateway.expect(gateway.frames.filter((frame) => frame.type === "request")).toHaveLength(0);@@ -5714,15 +5773,16 @@ describe("sandbox duplex gateway", () => {headers: { authorization: `Bearer ${token}` },});const requestFrame = await gateway.waitForFrame((frame) => frame.type === "request");- gateway.sendFrame({- version: 1,- type: "response",- id: requestFrame.id,- status: 200,- headers: { "content-type": "application/json" },- body: JSON.stringify({ ok: true }),- outcome: "completed",- });+ sendDuplexResponse(+ gateway.sendFrame,+ {+ id: requestFrame.id,+ status: 200,+ headers: { "content-type": "application/json" },+ outcome: "completed",+ },+ JSON.stringify({ ok: true }),+ );const okResponse = await okPromise;expect(okResponse.status).toBe(200);await expect(okResponse.json()).resolves.toEqual({ ok: true });@@ -5859,24 +5919,21 @@ describe("sandbox duplex gateway", () => {// Feed a malformed inbound line and an unknown response id. Both force a// diagnostic path; none of it may reach stdout.gateway.sendRaw("this is not a frame\n");- gateway.sendFrame({- version: 1,- type: "response",- id: "unknown-id",- status: 200,- headers: {},- body: "",- outcome: "completed",- });- gateway.sendFrame({- version: 1,- type: "response",- id: requestFrame.id,- status: 200,- headers: { "content-type": "application/json" },- body: "{}",- outcome: "completed",- });+ sendDuplexResponse(+ gateway.sendFrame,+ { id: "unknown-id", status: 200, headers: {}, outcome: "completed" },+ "",+ );+ sendDuplexResponse(+ gateway.sendFrame,+ {+ id: requestFrame.id,+ status: 200,+ headers: { "content-type": "application/json" },+ outcome: "completed",+ },+ "{}",+ );const response = await responsePromise;expect(response.status).toBe(200);@@ -5932,7 +5989,7 @@ function createFakeDuplexChannel(): {channel: CommandManagedDuplexChannel;emitData: (chunk: string) => void;emitExit: (exit: { exitCode: number | null }) => void;- written: DuplexResponseFrame[];+ written: Array<DuplexResponseFrame & { body: string }>;writtenTypes: string[];stopped: () => number;setWriteError: (error: Error | null) => void;@@ -5943,16 +6000,43 @@ function createFakeDuplexChannel(): {let writeError: Error | null = null;let closeBehavior: "resolve" | "hang" | "reject" = "resolve";let stopCount = 0;- const written: DuplexResponseFrame[] = [];+ // The broker writes a response as one envelope frame that carries+ // `bodyByteCount`, then the `body_chunk` frames that carry the body. Reassemble+ // the body so a test reads the response the same way it did with the one-frame+ // model.+ const written: Array<DuplexResponseFrame & { body: string }> = [];const writtenTypes: string[] = [];+ const responseAssembly = new Map<+ string,+ { frame: DuplexResponseFrame; received: number; chunks: Buffer[] }+ >();const channel: CommandManagedDuplexChannel = {write(data: string): void {if (writeError) throw writeError;const decoded = decodeDuplexLine(data.replace(/\n$/, ""));- if (decoded.ok) {- writtenTypes.push(decoded.frame.type);- if (decoded.frame.type === "response") written.push(decoded.frame);+ if (!decoded.ok) return;+ const frame = decoded.frame;+ writtenTypes.push(frame.type);+ if (frame.type === "response") {+ if (frame.bodyByteCount === 0) {+ written.push({ ...frame, body: "" });+ } else {+ responseAssembly.set(frame.id, { frame, received: 0, chunks: [] });+ }+ } else if (frame.type === "body_chunk") {+ const assembly = responseAssembly.get(frame.id);+ if (!assembly) return;+ const decodedChunk = Buffer.from(frame.data, "base64");+ assembly.received += decodedChunk.length;+ assembly.chunks.push(decodedChunk);+ if (assembly.received >= assembly.frame.bodyByteCount) {+ responseAssembly.delete(frame.id);+ written.push({+ ...assembly.frame,+ body: Buffer.concat(assembly.chunks).toString("utf8"),+ });+ }}},onData(listener: (chunk: string) => void): void {@@ -5987,8 +6071,16 @@ function createFakeDuplexChannel(): {};}-/** Build one request frame line the fake channel can emit. */-function requestFrameLine(overrides: Partial<DuplexRequestFrame> & { id: string }): string {+/**+ * Build one request as its envelope line (carrying `bodyByteCount`) plus its+ * `body_chunk` lines, so the fake channel emits a whole request in one write. The+ * broker reassembles the body from the chunk frames before it forwards.+ */+function requestFrameLine(+ overrides: Partial<Omit<DuplexRequestFrame, "bodyByteCount">> & { id: string },+ bodyText: string = JSON.stringify({ body: "hello" }),+): string {+ const body = Buffer.from(bodyText, "utf8");const frame: DuplexRequestFrame = {version: DUPLEX_FRAME_VERSION,type: "request",@@ -5997,9 +6089,13 @@ function requestFrameLine(overrides: Partial<DuplexRequestFrame> & { id: stringpath: overrides.path ?? "/api/issues/PAP-1/comments",query: overrides.query ?? "",headers: overrides.headers ?? { authorization: "Bearer bridge-token" },- body: overrides.body ?? JSON.stringify({ body: "hello" }),+ bodyByteCount: body.length,};- return encodeDuplexFrame(frame);+ let line = encodeDuplexFrame(frame);+ for (const chunk of splitBodyIntoChunkFrames(frame.id, body, DUPLEX_FRAME_VERSION)) {+ line += encodeDuplexFrame(chunk);+ }+ return line;}/** Wait for the pending microtasks and macrotasks to settle. */@@ -6015,7 +6111,7 @@ describe("createDuplexBridgeBroker", () => {// broker passes the decoded request straight through, so the sandbox request// still carries only the bridge token here, and the handler applies the real// token and the signed run identifier on the existing forward path.- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async (request): Promise<DuplexBrokerForwardResult> => {received.push(request);@@ -6050,7 +6146,7 @@ describe("createDuplexBridgeBroker", () => {it("moves through opening, open, closing, closed in order", async () => {const fake = createFakeDuplexChannel();const states: DuplexBrokerState[] = [];- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),onStateChange: (state) => states.push(state),@@ -6089,7 +6185,7 @@ describe("createDuplexBridgeBroker", () => {])("enters lost on $name", async ({ reason, trigger }) => {const fake = createFakeDuplexChannel();const losses: DuplexBrokerLossRecord[] = [];- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),onLoss: (record) => losses.push(record),@@ -6107,7 +6203,7 @@ describe("createDuplexBridgeBroker", () => {it("enters lost on a close timeout", async () => {const fake = createFakeDuplexChannel();fake.setCloseBehavior("hang");- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),closeTimeoutMs: 20,@@ -6123,7 +6219,7 @@ describe("createDuplexBridgeBroker", () => {it("stops the heartbeat, marks the run bridge ended, and dispatches nothing after loss", async () => {const fake = createFakeDuplexChannel();const forwarded: string[] = [];- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async (request) => {forwarded.push(request.id);@@ -6147,7 +6243,7 @@ describe("createDuplexBridgeBroker", () => {it("forwards one request id one time, so a repeated frame never reaches the API twice", async () => {const fake = createFakeDuplexChannel();const forwarded: string[] = [];- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async (request) => {forwarded.push(request.id);@@ -6171,7 +6267,7 @@ describe("createDuplexBridgeBroker", () => {const fake = createFakeDuplexChannel();const records: DuplexBrokerRequestRecord[] = [];let clock = 1000;- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),now: () => clock,@@ -6194,7 +6290,7 @@ describe("createDuplexBridgeBroker", () => {it("latches a failure when a loss orders before an orderly completion and names the typed reason", async () => {const fake = createFakeDuplexChannel();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),});@@ -6227,7 +6323,7 @@ describe("createDuplexBridgeBroker", () => {},};const fake = createFakeDuplexChannel();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),telemetry: createDuplexTelemetry({ recorder, providerKey: "daytona" }),@@ -6263,7 +6359,7 @@ describe("createDuplexBridgeBroker", () => {const logLines: string[] = [];const fake = createFakeDuplexChannel();const sentinel = "SENTINEL-PROVIDER-TEXT-1a2b3c";- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),telemetry: createDuplexTelemetry({ recorder, providerKey: "daytona" }),@@ -6287,7 +6383,7 @@ describe("createDuplexBridgeBroker", () => {expect(logLines.join("\n")).not.toContain(sentinel);});- it("rejects a configuration where an inner budget is not smaller than its outer budget", () => {+ it("rejects a configuration where an inner budget is not smaller than its outer budget", async () => {expect(() =>assertNestedDuplexBrokerBudgets({forwardTimeoutMs: 32_000,@@ -6302,13 +6398,15 @@ describe("createDuplexBridgeBroker", () => {gatewayWaitMs: 35_000,}),).toThrow(/response budget/);- expect(() =>+ // The async broker construction validates budgets before its first await, so+ // an invalid budget set surfaces as a rejected promise.+ await expect(createDuplexBridgeBroker({channel: createFakeDuplexChannel().channel,forwardRequest: async () => ({ status: 200 }),budgets: { forwardTimeoutMs: 40_000 },}),- ).toThrow(/forward budget/);+ ).rejects.toThrow(/forward budget/);// The default budget set holds the nested order.expect(() =>assertNestedDuplexBrokerBudgets({@@ -6384,7 +6482,7 @@ describe("sandbox target spec parse: enableSandboxDuplexBridge", () => {describe("settleRunDisposition atomic read and mark", () => {it("marks the orderly completion and reports a success for a healthy channel", async () => {const fake = createFakeDuplexChannel();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),});@@ -6400,7 +6498,7 @@ describe("settleRunDisposition atomic read and mark", () => {it("reports the failure and does not mark for a latched loss", async () => {const fake = createFakeDuplexChannel();- const broker = createDuplexBridgeBroker({+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),});@@ -6443,8 +6541,8 @@ describe("CLI-lane run-disposition seam", () => {} as AdapterSandboxExecutionTarget;}- function startBroker(fake: ReturnType<typeof createFakeDuplexChannel>) {- const broker = createDuplexBridgeBroker({+ async function startBroker(fake: ReturnType<typeof createFakeDuplexChannel>) {+ const broker = await createDuplexBridgeBroker({channel: fake.channel,forwardRequest: async () => ({ status: 200 }),});@@ -6454,7 +6552,7 @@ describe("CLI-lane run-disposition seam", () => {it("fails a clean CLI completion closed when the duplex channel was lost mid-turn", async () => {const fake = createFakeDuplexChannel();- const broker = startBroker(fake);+ const broker = await startBroker(fake);// The control channel dies mid-turn, before the CLI process exits.fake.emitExit({ exitCode: 1 });await flushMacrotasks();@@ -6478,7 +6576,7 @@ describe("CLI-lane run-disposition seam", () => {it("keeps a clean CLI completion a success when the channel stays healthy, and a teardown loss stays benign", async () => {const fake = createFakeDuplexChannel();- const broker = startBroker(fake);+ const broker = await startBroker(fake);const runner = mockRunner({ ...CLEAN_RESULT });const result = await runAdapterExecutionTargetProcess("run-cli-ok", sandboxTarget(runner), "agent-cli", [], {@@ -6502,7 +6600,7 @@ describe("CLI-lane run-disposition seam", () => {it("keeps a clean CLI completion a success when the gateway exits during the run-log tail finish", async () => {const fake = createFakeDuplexChannel();- const broker = startBroker(fake);+ const broker = await startBroker(fake);// A run-log tail whose finish emits a gateway exit. This reproduces the// race where the duplex gateway dies after the clean process completion but@@ -6542,7 +6640,7 @@ describe("CLI-lane run-disposition seam", () => {it("cannot clear the loss latch with a later completion", async () => {const fake = createFakeDuplexChannel();- const broker = startBroker(fake);+ const broker = await startBroker(fake);// The loss latches before the CLI process exits.fake.emitExit({ exitCode: 1 });await flushMacrotasks();@@ -6565,7 +6663,7 @@ describe("CLI-lane run-disposition seam", () => {it("leaves an already-failed CLI result unchanged and never settles the disposition", async () => {const fake = createFakeDuplexChannel();- const broker = startBroker(fake);+ const broker = await startBroker(fake);// The control channel is lost, but the process itself also exited non-zero.fake.emitExit({ exitCode: 1 });await flushMacrotasks();@@ -6662,7 +6760,7 @@ describe("duplex readiness gate replay-buffer reservation", () => {}function readyLine(): string {- return `${JSON.stringify({ version: 1, type: "ready", nonce: READY_NONCE })}\n`;+ return `${JSON.stringify({ version: 2, type: "ready", nonce: READY_NONCE })}\n`;}it("charges the post-READY suffix and releases it after the broker handoff", async () => {diff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.tsindex 065a7f8c5b..c21b7d3a87 100644--- a/packages/adapter-utils/src/execution-target.ts+++ b/packages/adapter-utils/src/execution-target.ts@@ -2,6 +2,7 @@ import fs from "node:fs/promises";import net from "node:net";import os from "node:os";import path from "node:path";+import { Readable } from "node:stream";import { randomBytes, randomUUID } from "node:crypto";import type { SshRemoteExecutionSpec } from "./ssh.js";import {@@ -59,6 +60,7 @@ import {DEFAULT_MAX_DUPLEX_FRAME_BYTES,type DuplexRequestFrame,} from "./duplex-frame-codec.js";+import type { ReassembledBody } from "./duplex-body-spool.js";import {createDuplexTelemetry,type DuplexFallbackReason,@@ -3132,9 +3134,24 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {// file bridge and the duplex broker. The sandbox request carries only the// bridge token; the real agent token never leaves the host.const forwardBridgeRequest = async (- request: { method: string; path: string; query: string; headers: Record<string, string>; body: string },+ request: {+ method: string;+ path: string;+ query: string;+ headers: Record<string, string>;+ /** The file bridge passes the whole request body here as one string. */+ body?: string;+ },signal?: AbortSignal,- options?: { suppressDebugLog?: boolean },+ options?: {+ suppressDebugLog?: boolean;+ /**+ * The duplex broker passes the reassembled request body here. The forward+ * streams it to the host, so a spilled body never loads into memory on the+ * receive side. The forward never disposes it; the broker owns its lifecycle.+ */+ reassembledBody?: ReassembledBody;+ },): Promise<{ status: number; headers: Record<string, string>; body: string }> => {const method = request.method.trim().toUpperCase() || "GET";// The per-request debug log prints the method, the path, and the query. The@@ -3159,12 +3176,26 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {// the forward budget here, whichever comes first.const timeoutSignal = AbortSignal.timeout(forwardTimeoutMs);const forwardSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;- const response = await fetch(buildBridgeForwardUrl(hostApiUrl, request), {+ // Build the request-body init. A GET or a HEAD carries no body. The duplex+ // broker passes the reassembled body: stream it, so a body that spilled to+ // disk never loads into memory here. A streamed body needs `duplex: "half"`.+ // The file bridge passes the whole body as one string.+ const forwardInit: RequestInit & { duplex?: "half" } = {method,headers,- ...(method === "GET" || method === "HEAD" ? {} : { body: request.body }),signal: forwardSignal,- });+ };+ if (method !== "GET" && method !== "HEAD") {+ if (options?.reassembledBody) {+ forwardInit.body = Readable.toWeb(+ options.reassembledBody.createReadStream(),+ ) as unknown as ReadableStream<Uint8Array>;+ forwardInit.duplex = "half";+ } else if (typeof request.body === "string") {+ forwardInit.body = request.body;+ }+ }+ const response = await fetch(buildBridgeForwardUrl(hostApiUrl, request), forwardInit);if (emitDebugLog) {await onLog("stdout",@@ -3375,14 +3406,14 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {// token only now, after readiness passed.let broker: DuplexBridgeBroker | null = null;try {- broker = createDuplexBridgeBroker({+ broker = await createDuplexBridgeBroker({channel: gate.brokerChannel,// Derive the nested budgets from the forward budget, so any forward// budget keeps the nested order the broker asserts at construction.budgets: deriveNestedDuplexBrokerBudgets(forwardTimeoutMs),forwardRequest: async (request: DuplexRequestFrame,- options: { signal: AbortSignal },+ options: { signal: AbortSignal; body: ReassembledBody },): Promise<DuplexBrokerForwardResult> => {const denialReason = authorizeSandboxCallbackBridgeRequestWithRoutes(request);if (denialReason) {@@ -3402,9 +3433,11 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {headers: sanitizeSandboxCallbackBridgeHeaders(request.headers),};// Suppress the per-request debug log on the duplex path, so no route- // or query rides a log line here.+ // or query rides a log line here. Stream the reassembled request+ // body, so a spilled body never loads into memory on the host.return forwardBridgeRequest(sanitizedRequest, options.signal, {suppressDebugLog: true,+ reassembledBody: options.body,});},// The duplex path emits only the fixed transport telemetry. It passes nodiff --git a/packages/adapter-utils/src/sandbox-callback-bridge.ts b/packages/adapter-utils/src/sandbox-callback-bridge.tsindex 9c3d073919..5d8907ce04 100644--- a/packages/adapter-utils/src/sandbox-callback-bridge.ts+++ b/packages/adapter-utils/src/sandbox-callback-bridge.ts@@ -1763,7 +1763,8 @@ export async function startSandboxCallbackBridgeServer(input: {* compatible with the host codec. {@link getSandboxDuplexGatewayCodecSource}* returns this exact source so a test can run every fixture vector against it.*/-const DUPLEX_GATEWAY_CODEC_SOURCE = `const DUPLEX_FRAME_VERSION = 1;+const DUPLEX_GATEWAY_CODEC_SOURCE = `const DUPLEX_FRAME_VERSION = 2;+const DUPLEX_BODY_CHUNK_RAW_BYTES = 256 * 1024;const DEFAULT_MAX_DUPLEX_FRAME_BYTES = 1000000;const DEFAULT_MAX_DUPLEX_REQUEST_ID_BYTES = 256;const DEFAULT_MAX_DUPLEX_DECODER_BYTES = ${DEFAULT_BRIDGE_MAX_DUPLEX_DECODER_BYTES};@@ -1792,6 +1793,10 @@ function duplexIsStringRecord(value) {return true;}+function duplexIsSafeNonNegativeInteger(value) {+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;+}+function encodeDuplexFrame(frame) {return JSON.stringify(frame) + "\\n";}@@ -1828,6 +1833,8 @@ function duplexValidateFrame(frame) {return duplexValidateRequest(frame);case "response":return duplexValidateResponse(frame);+ case "body_chunk":+ return duplexValidateBodyChunk(frame);case "ready":return duplexValidateReady(frame);case "heartbeat":@@ -1847,7 +1854,7 @@ function duplexValidateRequest(frame) {typeof frame.method !== "string" ||typeof frame.path !== "string" ||typeof frame.query !== "string" ||- typeof frame.body !== "string" ||+ !duplexIsSafeNonNegativeInteger(frame.bodyByteCount) ||!duplexIsStringRecord(frame.headers)) {return duplexFail("malformed_frame", "request frame has a missing or wrong-typed field");@@ -1862,7 +1869,7 @@ function duplexValidateResponse(frame) {if (typeof frame.id !== "string" ||typeof frame.status !== "number" ||- typeof frame.body !== "string" ||+ !duplexIsSafeNonNegativeInteger(frame.bodyByteCount) ||!duplexIsStringRecord(frame.headers) ||typeof frame.outcome !== "string" ||!DUPLEX_RESPONSE_OUTCOMES.has(frame.outcome)@@ -1875,6 +1882,19 @@ function duplexValidateResponse(frame) {return duplexOk(frame);}+function duplexValidateBodyChunk(frame) {+ if (typeof frame.id !== "string" || typeof frame.data !== "string") {+ return duplexFail("malformed_frame", "body_chunk frame has a missing or wrong-typed field");+ }+ if (!duplexIsSafeNonNegativeInteger(frame.seq)) {+ return duplexFail("malformed_frame", "body_chunk frame has a missing or wrong-typed seq");+ }+ if (Buffer.byteLength(frame.id, "utf8") > DEFAULT_MAX_DUPLEX_REQUEST_ID_BYTES) {+ return duplexFail("id_too_large", "body_chunk frame id exceeds the maximum size");+ }+ return duplexOk(frame);+}+function duplexValidateReady(frame) {if (typeof frame.nonce !== "string") {return duplexFail("malformed_frame", "ready frame has a missing or wrong-typed nonce");@@ -2198,10 +2218,37 @@ async function runFileGateway() {});}+// Split one whole body buffer into body_chunk frames. The gateway buffers the+// whole source body once, then splits it here. Each frame carries one fixed raw+// slice as base64 text, except the final frame, which carries the remaining+// bytes. A zero-length body yields no frame. Send-side true streaming is a+// separate goal; this whole-body split is acceptable for this gateway.+function splitDuplexBodyIntoChunks(id, body) {+ const frames = [];+ let seq = 0;+ for (let offset = 0; offset < body.length; offset += DUPLEX_BODY_CHUNK_RAW_BYTES) {+ const slice = body.subarray(offset, offset + DUPLEX_BODY_CHUNK_RAW_BYTES);+ frames.push({+ version: DUPLEX_FRAME_VERSION,+ type: "body_chunk",+ id: id,+ seq: seq,+ data: slice.toString("base64"),+ });+ seq += 1;+ }+ return frames;+}+function runDuplexGateway() {// One outstanding local request per id. Each entry holds the HTTP resolver and// the wait-budget timer.const pending = new Map();+ // One in-flight response reassembly per id. The host returns a response as an+ // envelope frame that carries bodyByteCount, then the body_chunk frames that+ // carry the body. The gateway reassembles the response body in memory here; it+ // does not spill, because a production response body stays small.+ const responseAssembly = new Map();let unavailable = false;let lossTriggered = false;let lastInboundAt = Date.now();@@ -2243,27 +2290,102 @@ function runDuplexGateway() {});}pending.clear();+ responseAssembly.clear();const exitTimer = setTimeout(() => process.exit(0), lossExitGraceMs);if (typeof exitTimer.unref === "function") exitTimer.unref();}+ // Fail one outstanding request with a bounded local 502. The gateway calls it+ // when a response reassembly breaks: a reordered seq, a base64 that is not+ // canonical, or a total that overruns the declared body size. The host is the+ // response peer, so this is a defensive local error, not a channel loss.+ function failRequest(id, message) {+ responseAssembly.delete(id);+ const entry = pending.get(id);+ if (!entry) return;+ pending.delete(id);+ clearTimeout(entry.timer);+ entry.resolve({+ status: 502,+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ error: message }),+ });+ }+function handleInboundFrame(frame) {if (frame.type === "response") {const entry = pending.get(frame.id);if (!entry) return;- pending.delete(frame.id);- clearTimeout(entry.timer);// Map an indeterminate outcome to a non-retryable 409, the same contract// the file gateway applies through the outcome header.const statusCode =frame.outcome === "indeterminate" ? 409 : typeof frame.status === "number" ? frame.status : 200;- entry.resolve({+ const headers = frame.headers || {};+ if (frame.bodyByteCount === 0) {+ // A zero-length body accepts no body_chunk, so the response completes now.+ pending.delete(frame.id);+ responseAssembly.delete(frame.id);+ clearTimeout(entry.timer);+ entry.resolve({ status: statusCode, headers: headers, body: "" });+ return;+ }+ // The body rides body_chunk frames that share this id. Record the envelope+ // and wait for the chunks.+ responseAssembly.set(frame.id, {status: statusCode,- headers: frame.headers || {},- body: typeof frame.body === "string" ? frame.body : "",+ headers: headers,+ bodyByteCount: frame.bodyByteCount,+ received: 0,+ nextSeq: 0,+ chunks: [],});return;}+ if (frame.type === "body_chunk") {+ const asm = responseAssembly.get(frame.id);+ if (!asm) return;+ if (frame.seq !== asm.nextSeq) {+ failRequest(frame.id, "duplex response body_chunk seq is out of order");+ return;+ }+ const decoded = Buffer.from(frame.data, "base64");+ if (decoded.toString("base64") !== frame.data) {+ failRequest(frame.id, "duplex response body_chunk is not canonical base64");+ return;+ }+ if (decoded.length === 0) {+ failRequest(frame.id, "duplex response body_chunk is empty");+ return;+ }+ if (asm.received + decoded.length > asm.bodyByteCount) {+ failRequest(frame.id, "duplex response body overruns the declared size");+ return;+ }+ const isFinal = asm.received + decoded.length === asm.bodyByteCount;+ if (+ decoded.length > DUPLEX_BODY_CHUNK_RAW_BYTES ||+ (!isFinal && decoded.length !== DUPLEX_BODY_CHUNK_RAW_BYTES)+ ) {+ failRequest(frame.id, "duplex response body_chunk has the wrong size");+ return;+ }+ asm.nextSeq += 1;+ asm.received += decoded.length;+ asm.chunks.push(decoded);+ if (asm.received === asm.bodyByteCount) {+ const entry = pending.get(frame.id);+ responseAssembly.delete(frame.id);+ if (!entry) return;+ pending.delete(frame.id);+ clearTimeout(entry.timer);+ entry.resolve({+ status: asm.status,+ headers: asm.headers,+ body: Buffer.concat(asm.chunks).toString("utf8"),+ });+ }+ return;+ }if (frame.type === "close") {triggerLoss("host sent a close frame");return;@@ -2320,11 +2442,14 @@ function runDuplexGateway() {return;}const requestId = randomUUID();- const requestBody = await readBody(req);+ const requestBodyBuffer = Buffer.from(await readBody(req), "utf8");if (unavailable) {writeJsonResponse(res, 503, { error: "bridge_unavailable" });return;}+ // The request body rides body_chunk frames. The envelope carries only the+ // raw byte count, so the envelope stays small and the body splits into+ // fixed-size slices that each stay under the frame bound.const requestFrame = {version: DUPLEX_FRAME_VERSION,type: "request",@@ -2333,20 +2458,36 @@ function runDuplexGateway() {path: url.pathname,query: url.search,headers: normalizeHeaders(req.headers),- body: requestBody,+ bodyByteCount: requestBodyBuffer.length,};- // Enforce the frame size bound on encode. When the request body makes the- // frame exceed the bound, fail this one local request with a clean 413. Do- // not write the frame and do not trigger loss. The frame never leaves the- // gateway, so no other in-flight request is affected and the channel stays- // open.const encodedRequest = encodeDuplexFrameChecked(requestFrame);if (!encodedRequest.ok) {writeJsonResponse(res, 413, { error: "request_too_large" });return;}+ // Pre-encode every body_chunk frame and enforce the frame size bound on+ // each. A fixed raw slice never exceeds the bound, so this guard is+ // defensive. On a rejection, fail this one local request with a clean 413.+ // The frames never leave the gateway, so no other in-flight request is+ // affected and the channel stays open.+ const chunkFrames = splitDuplexBodyIntoChunks(requestId, requestBodyBuffer);+ const encodedChunks = [];+ let chunkTooLarge = false;+ for (const chunk of chunkFrames) {+ const encodedChunk = encodeDuplexFrameChecked(chunk);+ if (!encodedChunk.ok) {+ chunkTooLarge = true;+ break;+ }+ encodedChunks.push(encodedChunk.line);+ }+ if (chunkTooLarge) {+ writeJsonResponse(res, 413, { error: "request_too_large" });+ return;+ }const response = await new Promise((resolve) => {const timer = setTimeout(() => {+ responseAssembly.delete(requestId);if (pending.delete(requestId)) {resolve({status: 502,@@ -2357,6 +2498,7 @@ function runDuplexGateway() {}, responseTimeoutMs);pending.set(requestId, { resolve: resolve, timer: timer });process.stdout.write(encodedRequest.line);+ for (const line of encodedChunks) process.stdout.write(line);});res.statusCode = typeof response.status === "number" ? response.status : 200;for (const [key, value] of Object.entries(response.headers || {})) {