@paperclipai/plugin-daytona 2026.824.0 → 2026.825.0-beta.1

package/dist/duplex-command-stream.d.ts

@@ -0,0 +1,97 @@
+import type { DaytonaPtyProcess } from "./login-pty.js";
+export type { DaytonaPtyCreateOptions, DaytonaPtyHandle, DaytonaPtyProcess, } from "./login-pty.js";
+/**
+ * A live duplex channel session for one command. The session allocates a real
+ * pseudo-terminal in raw mode, streams the raw output, accepts host input, and
+ * stops the child. The shape matches the worker duplex channel session, so the
+ * worker forwards the data and the exit with no adapter.
+ */
+export interface DuplexChannelSession {
+    /** Registers the one data listener. The session streams each raw byte chunk in order. */
+    onData(listener: (chunk: Uint8Array) => void): void;
+    /** Writes raw input bytes to the pseudo-terminal. */
+    write(data: Uint8Array): void;
+    /**
+     * Resolves when the command ends or the transport closes. A numeric `exitCode`
+     * is a real process exit. `transportClosed` is true when the pseudo-terminal
+     * socket closed with no exit data, so the caller can tell a real process exit
+     * from a reason-less transport close.
+     */
+    wait(): Promise<{
+        exitCode: number | null;
+        transportClosed: boolean;
+    }>;
+    /** Stops the child process. Safe to call more than one time. */
+    kill(): void;
+    /** Releases the session resources. Safe to call more than one time. */
+    close(): Promise<void>;
+}
+/**
+ * Opens a {@link DuplexChannelSession} for `command`. The transport calls it one
+ * time. `command` is an argument vector: element 0 is the program and the rest
+ * are its arguments. The session quotes each element, so a shell metacharacter in
+ * an element cannot inject a shell command.
+ */
+export type DuplexChannelSessionOpener = (command: readonly string[]) => Promise<DuplexChannelSession>;
+/**
+ * The typed, closed reason for a duplex channel write failure. The seam reports
+ * only this constant, never the raw provider error text. It maps to the host
+ * telemetry `write_error` loss reason.
+ */
+export declare const DAYTONA_DUPLEX_WRITE_ERROR_REASON: "write_error";
+/** The typed reason a rejected host-to-sandbox write reports. */
+export type DaytonaDuplexWriteErrorReason = typeof DAYTONA_DUPLEX_WRITE_ERROR_REASON;
+/** The options for the Daytona duplex channel session. */
+export interface DaytonaDuplexChannelOptions {
+    /** The working directory for the duplex channel PTY. Defaults to the sandbox default. */
+    cwd?: string;
+    /**
+     * The absolute sandbox path for the gateway diagnostics. The wrapper redirects
+     * the terminal's stderr to this path, so a diagnostic line never reaches the
+     * stdout frame stream. Defaults to a per-channel path under `/tmp`.
+     */
+    diagnosticsPath?: string;
+    /**
+     * The write-error seam. The session calls it one time when a host-to-sandbox
+     * `sendInput` rejects. The session then ends the channel at once. The seam
+     * carries only the typed {@link DaytonaDuplexWriteErrorReason}; the raw provider
+     * error never reaches it.
+     */
+    onWriteError?: (reason: DaytonaDuplexWriteErrorReason) => void;
+}
+/**
+ * Builds the launch wrapper input line for the duplex channel. `command` is an
+ * argument vector: element 0 is the program and the rest are its arguments.
+ *
+ * The wrapper does three steps in order:
+ *   1. `exec 2>'<diagnosticsPath>'` redirects the shell's stderr to the file. The
+ *      later `exec` inherits it, so the gateway diagnostics land in the file and
+ *      never on the stdout frame stream.
+ *   2. `stty raw -echo` sets the terminal to raw mode with echo off, so the
+ *      terminal neither echoes host input as data nor translates newlines.
+ *   3. `exec '<program>' '<arg>'...` replaces the shell with the gateway, so the
+ *      PTY runs the gateway directly and the gateway exit code becomes the PTY
+ *      exit code.
+ *
+ * The wrapper quotes the diagnostics path and every command argument as a
+ * single-quoted shell word. So a shell metacharacter in a path or an argument
+ * stays literal text and cannot inject a shell command.
+ */
+export declare function buildDuplexChannelLaunchWrapper(command: readonly string[], diagnosticsPath: string): string;
+/**
+ * Opens a Daytona duplex channel PTY session for `command` and returns it as a
+ * {@link DuplexChannelSession}. The session allocates a real pseudo-terminal in
+ * raw mode, streams the raw output, accepts host input, and stops the child.
+ *
+ * The function forwards the terminal bytes unchanged. It buffers the output
+ * until the transport registers the listener, so no early chunk is lost.
+ */
+export declare function openDaytonaDuplexChannelSession(process: DaytonaPtyProcess, command: readonly string[], options?: DaytonaDuplexChannelOptions): Promise<DuplexChannelSession>;
+/**
+ * Creates a {@link DuplexChannelSessionOpener} bound to a Daytona `process`. Pass
+ * `sandbox.process` from the Daytona SDK. The opener runs the gateway command on a
+ * raw pseudo-terminal, streams the output, accepts host input, and stops the child
+ * for a terminal state.
+ */
+export declare function createDaytonaDuplexChannelSessionOpener(process: DaytonaPtyProcess, options?: DaytonaDuplexChannelOptions): DuplexChannelSessionOpener;
+//# sourceMappingURL=duplex-command-stream.d.ts.map

package/dist/duplex-command-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplex-command-stream.d.ts","sourceRoot":"","sources":["../src/duplex-command-stream.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAGV,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAIxB;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,yFAAyF;IACzF,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IACpD,qDAAqD;IACrD,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B;;;;;OAKG;IACH,IAAI,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,eAAe,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACvE,gEAAgE;IAChE,IAAI,IAAI,IAAI,CAAC;IACb,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,SAAS,MAAM,EAAE,KACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,EAAG,aAAsB,CAAC;AAExE,iEAAiE;AACjE,MAAM,MAAM,6BAA6B,GAAG,OAAO,iCAAiC,CAAC;AAErF,0DAA0D;AAC1D,MAAM,WAAW,2BAA2B;IAC1C,yFAAyF;IACzF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,6BAA6B,KAAK,IAAI,CAAC;CAChE;AAwBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,eAAe,EAAE,MAAM,GACtB,MAAM,CASR;AAED;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,oBAAoB,CAAC,CA2G/B;AAED;;;;;GAKG;AACH,wBAAgB,uCAAuC,CACrD,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,2BAA2B,GACpC,0BAA0B,CAG5B"}

package/dist/duplex-command-stream.js

@@ -0,0 +1,205 @@
+// The Daytona duplex command stream for the sandbox callback bridge. The bridge
+// needs one live bidirectional byte stream: the host writes request frames to the
+// process, and the process writes response frames back, on one connection while
+// the command runs. This module binds a Daytona pseudo-terminal (PTY) to a small
+// session that the duplex transport consumes, so the gateway runs on a real
+// terminal, streams its output, and receives host input.
+//
+// Primitive choice (the first acceptance criterion of the phase): the Daytona SDK
+// proves two primitives. The ordinary session primitive (`createSession` plus
+// `executeSessionCommand` plus `getSessionCommandLogs`) dispatches a command and
+// tails its output, split into separate stdout and stderr streams. It exposes no
+// call that writes bytes to a running command's stdin. The PTY primitive
+// (`createPty`) exposes `sendInput` for host-to-process bytes and one `onData`
+// callback for process-to-host bytes, on one live socket. Only the PTY carries a
+// bidirectional stream on one connection, so this module uses the PTY. The
+// characterization test in `duplex-command-stream.test.ts` records the evidence.
+//
+// Clean stream: a PTY echoes its input and translates newlines by default
+// (`ICRNL` on input, `ONLCR` on output). The frames are newline-delimited JSON, so
+// echo and newline translation corrupt the stream. The launch wrapper runs
+// `stty raw -echo` before it starts the gateway, so the terminal becomes an 8-bit
+// transparent path with no echo and no newline translation. The wrapper also
+// redirects the gateway diagnostics to a file, so a diagnostic line never reaches
+// the stdout frame stream. The wrapper starts the gateway with `exec`, so the PTY
+// runs the gateway directly and the gateway exit code becomes the PTY exit code.
+//
+// Dependency boundary: this provider plugin ships standalone (the workspace
+// excludes `packages/plugins/sandbox-providers/**`). So the module imports no
+// workspace package. It reuses the narrow Daytona PTY surface that
+// `login-pty.ts` declares (`DaytonaPtyProcess`, `DaytonaPtyHandle`,
+// `DaytonaPtyCreateOptions`), so a caller passes `sandbox.process` with no
+// adapter. The narrow surface keeps the module unit-testable with a fake PTY.
+import { randomUUID } from "node:crypto";
+import { sendPtyInputInChunks } from "./pty-chunked-input.js";
+/**
+ * The typed, closed reason for a duplex channel write failure. The seam reports
+ * only this constant, never the raw provider error text. It maps to the host
+ * telemetry `write_error` loss reason.
+ */
+export const DAYTONA_DUPLEX_WRITE_ERROR_REASON = "write_error";
+// The terminal size for the duplex channel PTY. The channel carries bytes, not a
+// visible UI, so a fixed standard size is enough. A fixed size keeps the launch
+// deterministic.
+const DUPLEX_CHANNEL_PTY_COLS = 120;
+const DUPLEX_CHANNEL_PTY_ROWS = 30;
+/**
+ * The input terminator that submits the launch wrapper line. The terminal reads
+ * the carriage return as the Enter key, so the shell runs the wrapper line.
+ */
+const PTY_COMMAND_TERMINATOR = "\r";
+/**
+ * Quotes one value for a POSIX shell. The result is one single-quoted word, so
+ * the shell reads it as literal text and never expands or splits it. The function
+ * closes the quote, adds an escaped single quote, and reopens the quote for each
+ * single quote in the value.
+ */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+/**
+ * Builds the launch wrapper input line for the duplex channel. `command` is an
+ * argument vector: element 0 is the program and the rest are its arguments.
+ *
+ * The wrapper does three steps in order:
+ *   1. `exec 2>'<diagnosticsPath>'` redirects the shell's stderr to the file. The
+ *      later `exec` inherits it, so the gateway diagnostics land in the file and
+ *      never on the stdout frame stream.
+ *   2. `stty raw -echo` sets the terminal to raw mode with echo off, so the
+ *      terminal neither echoes host input as data nor translates newlines.
+ *   3. `exec '<program>' '<arg>'...` replaces the shell with the gateway, so the
+ *      PTY runs the gateway directly and the gateway exit code becomes the PTY
+ *      exit code.
+ *
+ * The wrapper quotes the diagnostics path and every command argument as a
+ * single-quoted shell word. So a shell metacharacter in a path or an argument
+ * stays literal text and cannot inject a shell command.
+ */
+export function buildDuplexChannelLaunchWrapper(command, diagnosticsPath) {
+    if (command.length === 0) {
+        throw new Error("The duplex channel launch command needs at least one argument.");
+    }
+    const quotedCommand = command.map(shellQuote).join(" ");
+    return (`exec 2>${shellQuote(diagnosticsPath)}; stty raw -echo; ` +
+        `exec ${quotedCommand}${PTY_COMMAND_TERMINATOR}`);
+}
+/**
+ * Opens a Daytona duplex channel PTY session for `command` and returns it as a
+ * {@link DuplexChannelSession}. The session allocates a real pseudo-terminal in
+ * raw mode, streams the raw output, accepts host input, and stops the child.
+ *
+ * The function forwards the terminal bytes unchanged. It buffers the output
+ * until the transport registers the listener, so no early chunk is lost.
+ */
+export async function openDaytonaDuplexChannelSession(process, command, options) {
+    let listener = null;
+    let buffered = Buffer.alloc(0);
+    const diagnosticsPath = options?.diagnosticsPath ?? `/tmp/paperclip-duplex-${randomUUID()}.log`;
+    const handle = await process.createPty({
+        id: `paperclip-duplex-${randomUUID()}`,
+        ...(options?.cwd ? { cwd: options.cwd } : {}),
+        cols: DUPLEX_CHANNEL_PTY_COLS,
+        rows: DUPLEX_CHANNEL_PTY_ROWS,
+        onData: (data) => {
+            // Forward the raw bytes unchanged; the frame codec owns the
+            // newline-delimited JSON parsing and any multi-byte character
+            // reassembly on the read side.
+            if (data.byteLength === 0)
+                return;
+            if (listener)
+                listener(data);
+            else
+                buffered = buffered.length === 0 ? Buffer.from(data) : Buffer.concat([buffered, data]);
+        },
+    });
+    await handle.waitForConnection();
+    // Start the gateway through the raw-mode wrapper. Raw mode with echo off stops
+    // the terminal from echoing host input back as data and from translating the
+    // frame newlines. The diagnostics redirect keeps the stdout frame stream clean.
+    await handle.sendInput(buildDuplexChannelLaunchWrapper(command, diagnosticsPath));
+    // Report a host-to-sandbox write failure one time and end the channel at once.
+    // The seam carries only the typed reason; the raw provider error never leaves
+    // this scope. The channel end propagates the loss up through the exit.
+    //
+    // `channelTerminated` turns true on the first rejected chunk, before the early
+    // return, so a later queued write reads it and sends no chunk. Without the flag
+    // a queued write runs after the terminal kill and calls `sendInput` on the
+    // closed transport.
+    let channelTerminated = false;
+    let writeErrorReported = false;
+    const endOnWriteError = () => {
+        channelTerminated = true;
+        if (writeErrorReported)
+            return;
+        writeErrorReported = true;
+        options?.onWriteError?.(DAYTONA_DUPLEX_WRITE_ERROR_REASON);
+        void handle.kill().catch(() => undefined);
+    };
+    // The tail of the write chain. The chunker awaits each chunk, so one write can
+    // suspend between its chunks. The chain runs each write after the previous
+    // write ends, so the chunks of two writes never interleave on the wire. The
+    // chain never rejects, because the chunker maps a rejected send to
+    // `endOnWriteError` and returns.
+    let writeChain = Promise.resolve();
+    return {
+        onData(next) {
+            listener = next;
+            if (buffered.length > 0) {
+                const pending = buffered;
+                buffered = Buffer.alloc(0);
+                next(pending);
+            }
+        },
+        write(data) {
+            // Send the input as byte-bounded chunks under the provider message cap. A
+            // whole payload in one message can cross the cap and take the channel down,
+            // so the chunker slices the payload and sends each chunk in order. The chain
+            // runs this write after the previous write ends, so two writes keep their
+            // order and never interleave their chunks. A write error must not throw into
+            // the transport, so the transport's stream stays the single result path. On
+            // a rejected chunk, the chunker ends the channel one time through
+            // `endOnWriteError` and sends no later chunk. The raw provider error never
+            // reaches a sink.
+            //
+            // A rejected chunk terminalizes the channel and kills the transport. So this
+            // write skips the send when `channelTerminated` is true, and a queued write
+            // never calls `sendInput` on the closed transport.
+            writeChain = writeChain.then(() => {
+                if (channelTerminated)
+                    return;
+                return sendPtyInputInChunks((chunk) => handle.sendInput(chunk), data, endOnWriteError);
+            });
+        },
+        async wait() {
+            const result = await handle.wait();
+            if (typeof result.exitCode === "number") {
+                // A numeric exit code is a real process exit. The SDK parses it from the
+                // pseudo-terminal WebSocket close reason (for example `{"exitCode":0}`).
+                return { exitCode: result.exitCode, transportClosed: false };
+            }
+            // A non-numeric exit code marks a reason-less transport close: the socket
+            // closed with no exit data. It is a transport close, not a process exit.
+            return { exitCode: null, transportClosed: true };
+        },
+        kill() {
+            void handle.kill().catch(() => undefined);
+        },
+        async close() {
+            // Stop the child and release the socket. `kill` ends the gateway and `wait`
+            // resolves with the exit; `disconnect` releases the PTY socket. Both are
+            // safe to call more than one time, so close stays idempotent.
+            await handle.kill().catch(() => undefined);
+            await handle.disconnect().catch(() => undefined);
+        },
+    };
+}
+/**
+ * Creates a {@link DuplexChannelSessionOpener} bound to a Daytona `process`. Pass
+ * `sandbox.process` from the Daytona SDK. The opener runs the gateway command on a
+ * raw pseudo-terminal, streams the output, accepts host input, and stops the child
+ * for a terminal state.
+ */
+export function createDaytonaDuplexChannelSessionOpener(process, options) {
+    return (command) => openDaytonaDuplexChannelSession(process, command, options);
+}
+//# sourceMappingURL=duplex-command-stream.js.map

package/dist/duplex-command-stream.js.map

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

package/dist/duplex-command-stream.live.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=duplex-command-stream.live.test.d.ts.map

package/dist/duplex-command-stream.live.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplex-command-stream.live.test.d.ts","sourceRoot":"","sources":["../src/duplex-command-stream.live.test.ts"],"names":[],"mappings":""}

package/dist/duplex-command-stream.live.test.js

@@ -0,0 +1,324 @@
+// Live characterization of the Daytona duplex channel against the real provider.
+//
+// The test is credential-gated by design. It runs only when the run shell holds a
+// Daytona API key, and it skips cleanly when the key is absent. The key comes from
+// `DAYTONA_API_KEY`, which the plugin also reads as the credential fallback
+// (`plugin.ts`). A skip is acceptable: the merged live coverage re-runs at a later
+// phase and at rollout.
+//
+// What it proves on one live sandbox:
+//   1. The duplex channel and an ordinary command run at the same time.
+//   2. Host input sent after the child starts arrives, with no terminal echo and
+//      no frame corruption.
+//   3. Channel teardown leaves no leaked provider session.
+//
+// The channel runs `cat` as the child. `cat` copies its input to its output, so a
+// host write returns one time as program output. The launch wrapper sets the
+// pseudo-terminal to raw mode with echo off, so the terminal adds no second copy
+// and no newline translation. A returned line that equals the sent line, one time,
+// proves both the delivery and the clean stream.
+//
+// The Daytona SDK is a runtime dependency of this live test only. The module loads
+// it with a dynamic import inside the gated block, so the file imports with no SDK
+// present and the other Daytona tests still run without it.
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { randomUUID } from "node:crypto";
+import http2 from "node:http2";
+import { Duplex } from "node:stream";
+import { openDaytonaDuplexChannelSession, } from "./duplex-command-stream.js";
+const DAYTONA_API_KEY = process.env.DAYTONA_API_KEY?.trim() ?? "";
+const HAS_DAYTONA_CREDENTIAL = DAYTONA_API_KEY.length > 0;
+const describeLive = HAS_DAYTONA_CREDENTIAL ? describe : describe.skip;
+if (!HAS_DAYTONA_CREDENTIAL) {
+    // eslint-disable-next-line no-console
+    console.warn("Skipping the Daytona duplex channel live test: DAYTONA_API_KEY is not set in the run shell.");
+}
+// A live sandbox create and destroy needs a generous timeout. The provider round
+// trip dominates the wall-clock time.
+const LIVE_TIMEOUT_MS = 180_000;
+/**
+ * Wait until `predicate(text)` is true for the running output, or reject after
+ * `timeoutMs`. The poll interval is short, so the wait ends soon after the output
+ * arrives.
+ */
+async function waitFor(readOutput, predicate, timeoutMs, label) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (predicate(readOutput()))
+            return;
+        if (Date.now() > deadline) {
+            throw new Error(`Timed out waiting for ${label}. Output so far: ${JSON.stringify(readOutput())}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+/** Open a `cat` duplex channel and collect its output into a growing string. */
+async function openCatChannel(sandbox) {
+    let output = "";
+    const session = await openDaytonaDuplexChannelSession(sandbox.process, ["cat"]);
+    session.onData((chunk) => {
+        output += chunk;
+    });
+    return { session, readOutput: () => output };
+}
+describeLive("Daytona duplex channel (live)", () => {
+    let sandbox = null;
+    beforeAll(async () => {
+        const { Daytona } = await import("@daytonaio/sdk");
+        const client = new Daytona({ apiKey: DAYTONA_API_KEY });
+        sandbox = (await client.create());
+    }, LIVE_TIMEOUT_MS);
+    afterAll(async () => {
+        await sandbox?.delete().catch(() => undefined);
+    }, LIVE_TIMEOUT_MS);
+    it("runs the duplex channel and an ordinary command on one live sandbox", async () => {
+        const live = sandbox;
+        const { session, readOutput } = await openCatChannel(live);
+        try {
+            // Run an ordinary command while the channel child stays alive. Both use the
+            // same live sandbox, so a success on both proves they coexist.
+            const token = `ordinary-${randomUUID()}`;
+            const ordinary = await live.process.executeCommand(`printf %s ${token}`);
+            expect(ordinary.exitCode ?? 0).toBe(0);
+            expect(ordinary.result ?? "").toContain(token);
+            // The channel child still answers. A write returns as program output.
+            const ping = `chan-${randomUUID()}`;
+            session.write(Buffer.from(`${ping}\n`));
+            await waitFor(readOutput, (text) => text.includes(ping), 30_000, "channel echo");
+        }
+        finally {
+            await session.close();
+        }
+    }, LIVE_TIMEOUT_MS);
+    it("delivers host input sent after startup with no echo and no frame corruption", async () => {
+        const live = sandbox;
+        const { session, readOutput } = await openCatChannel(live);
+        try {
+            // Let the launch wrapper run `stty raw -echo` before the host input. The
+            // wrapper output echoes in cooked mode, so wait for the raw-mode switch
+            // before the measured write.
+            await new Promise((resolve) => setTimeout(resolve, 4_000));
+            const baseline = readOutput().length;
+            const line = `PING-${randomUUID()}`;
+            session.write(Buffer.from(`${line}\n`));
+            await waitFor(readOutput, (text) => text.slice(baseline).includes(line), 30_000, "delayed host input");
+            // Only `cat` writes the line, one time. Raw mode with echo off adds no
+            // second copy, so the sent token appears exactly one time after the write.
+            const afterWrite = readOutput().slice(baseline);
+            const occurrences = afterWrite.split(line).length - 1;
+            expect(occurrences).toBe(1);
+            // The stream carries the frame bytes with no newline translation. The
+            // returned line keeps its single line-feed and gains no carriage return.
+            expect(afterWrite).toContain(`${line}\n`);
+            expect(afterWrite).not.toContain(`${line}\r`);
+        }
+        finally {
+            await session.close();
+        }
+    }, LIVE_TIMEOUT_MS);
+    it("leaves no leaked provider session after channel close", async () => {
+        const live = sandbox;
+        const listSessions = live.process.listSessions?.bind(live.process);
+        const baseline = listSessions ? (await listSessions()).length : 0;
+        const { session } = await openCatChannel(live);
+        await session.close();
+        if (listSessions) {
+            // The channel uses a pseudo-terminal, not an ordinary session. So the
+            // session list stays at the baseline. A leaked session would raise the
+            // count.
+            const after = (await listSessions()).length;
+            expect(after).toBe(baseline);
+        }
+        // The child exits after close, so a fresh ordinary command still succeeds on
+        // the same sandbox. A leaked channel would block or corrupt the sandbox.
+        const token = `after-close-${randomUUID()}`;
+        const probe = await live.process.executeCommand(`printf %s ${token}`);
+        expect(probe.exitCode ?? 0).toBe(0);
+        expect(probe.result ?? "").toContain(token);
+    }, LIVE_TIMEOUT_MS);
+    it("serves repeated channel round trips with no idle polling and no per-request session growth", async () => {
+        const live = sandbox;
+        const listSessions = live.process.listSessions?.bind(live.process);
+        const { session, readOutput } = await openCatChannel(live);
+        try {
+            // Wait for the raw-mode switch, then take the open baseline. The channel
+            // uses a pseudo-terminal, not an ordinary session, so the session list
+            // stays flat through the whole exchange.
+            await new Promise((resolve) => setTimeout(resolve, 4_000));
+            const openSessions = listSessions ? (await listSessions()).length : 0;
+            // Send a batch of request-shaped lines over the one open channel and
+            // measure the round-trip latency of each. The transport writes no queue
+            // file and runs no exec per line, so the round trip is the stream latency.
+            const latenciesMs = [];
+            const rounds = 10;
+            for (let index = 0; index < rounds; index += 1) {
+                const line = `RTT-${index}-${randomUUID()}`;
+                const baseline = readOutput().length;
+                const start = Date.now();
+                session.write(Buffer.from(`${line}\n`));
+                await waitFor(readOutput, (text) => text.slice(baseline).includes(line), 30_000, "channel round trip");
+                latenciesMs.push(Date.now() - start);
+            }
+            // Hold the channel idle. A polling transport would run a provider exec on
+            // each tick and raise the session count. The duplex channel polls nothing.
+            await new Promise((resolve) => setTimeout(resolve, 5_000));
+            if (listSessions) {
+                const afterSessions = (await listSessions()).length;
+                // Zero idle polls and zero per-request session growth: the session count
+                // never rose above the open baseline.
+                expect(afterSessions).toBe(openSessions);
+            }
+            const min = Math.min(...latenciesMs);
+            const max = Math.max(...latenciesMs);
+            const avg = Math.round(latenciesMs.reduce((sum, value) => sum + value, 0) / latenciesMs.length);
+            // eslint-disable-next-line no-console
+            console.log(`[duplex-live] channel round-trip latency over ${rounds} requests: min=${min}ms avg=${avg}ms max=${max}ms; idle-poll session growth=0; per-request session growth=0`);
+            expect(latenciesMs.length).toBe(rounds);
+        }
+        finally {
+            await session.close();
+        }
+    }, LIVE_TIMEOUT_MS);
+    it("leaves no leaked session and keeps the sandbox usable after a forced mid-flight disconnect", async () => {
+        const live = sandbox;
+        const listSessions = live.process.listSessions?.bind(live.process);
+        const baseline = listSessions ? (await listSessions()).length : 0;
+        const { session, readOutput } = await openCatChannel(live);
+        // Wait for the raw-mode switch, then start a write and force a disconnect
+        // before its echo returns. The abrupt close models a lost provider channel.
+        await new Promise((resolve) => setTimeout(resolve, 4_000));
+        const inFlight = `INFLIGHT-${randomUUID()}`;
+        session.write(Buffer.from(`${inFlight}\n`));
+        // Close at once, without waiting for the echo. The pending round trip never
+        // settles through the stream; the channel tears down instead.
+        await session.close();
+        if (listSessions) {
+            // The forced disconnect left no leaked provider session. The count is back
+            // at the baseline that preceded the channel.
+            const after = (await listSessions()).length;
+            expect(after).toBe(baseline);
+        }
+        // Do not read the in-flight echo; the disconnect settled the run. Reference
+        // the output length only to keep the reader wired.
+        expect(readOutput().length).toBeGreaterThanOrEqual(0);
+        // The sandbox stays usable: a fresh ordinary command still succeeds. A
+        // leaked channel would block or corrupt the sandbox.
+        const token = `post-disconnect-${randomUUID()}`;
+        const probe = await live.process.executeCommand(`printf %s ${token}`);
+        expect(probe.exitCode ?? 0).toBe(0);
+        expect(probe.result ?? "").toContain(token);
+        // eslint-disable-next-line no-console
+        console.log("[duplex-live] forced mid-flight disconnect: leaked sessions=0; sandbox usable after=yes");
+    }, LIVE_TIMEOUT_MS);
+    it("test_live_daytona_run_uses_http2_v1_end_to_end", async () => {
+        // Phase 4 selects http2_v1 by running one Node HTTP/2 session directly
+        // on this same pseudo-terminal channel, right after the READY line.
+        // This package ships standalone (see the file header), so it cannot
+        // import the host readiness gate or the preface scan from
+        // `@paperclipai/adapter-utils`; this test reimplements the minimal,
+        // self-contained version of both, using only `node:http2`, so the
+        // proof runs against a real Daytona PTY end to end.
+        const live = sandbox;
+        const nonce = randomUUID();
+        // The 24-octet HTTP/2 client connection preface (RFC 9113, Section 3.4).
+        const CLIENT_PREFACE = Buffer.from("505249202a20485454502f322e300d0a0d0a534d0d0a0d0a", "hex");
+        // The sandbox-side child: send the READY line, then hand stdin/stdout to
+        // a real HTTP/2 client session and dispatch one request — the same
+        // shape `runHttp2Gateway()` in `sandbox-callback-bridge.ts` runs.
+        const nodeScript = [
+            `process.stdout.write(JSON.stringify({version:2,type:"ready",nonce:${JSON.stringify(nonce)}})+"\\n");`,
+            `const http2=require("node:http2");`,
+            `const {Duplex}=require("node:stream");`,
+            `const stdio=new Duplex({read(){},write(chunk,enc,cb){const ok=process.stdout.write(chunk);if(ok)cb();else process.stdout.once("drain",cb);}});`,
+            `process.stdin.on("data",c=>stdio.push(c));`,
+            `process.stdin.on("end",()=>stdio.push(null));`,
+            `const session=http2.connect("http://bridge.internal",{createConnection:()=>stdio});`,
+            `session.on("error",()=>process.exit(1));`,
+            `const stream=session.request({":method":"GET",":path":"/ping"});`,
+            `let body="";`,
+            `stream.on("data",c=>{body+=c;});`,
+            `stream.on("error",()=>process.exit(3));`,
+            `stream.on("end",()=>{session.close(()=>process.exit(body==="pong"?0:2));});`,
+            `stream.end();`,
+        ].join("");
+        const session = await openDaytonaDuplexChannelSession(live.process, ["node", "-e", nodeScript]);
+        try {
+            // Reads bytes from the channel until it finds one complete newline-
+            // terminated READY line, then hands every later byte — including any
+            // already-buffered suffix of the same chunk — to `onAfterReady`.
+            const readyAndAfter = await new Promise((resolve, reject) => {
+                let buffer = Buffer.alloc(0);
+                const timer = setTimeout(() => reject(new Error(`Timed out waiting for the READY line. Bytes so far: ${buffer.length}`)), 30_000);
+                session.onData((chunk) => {
+                    buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+                    const newlineIndex = buffer.indexOf(0x0a);
+                    if (newlineIndex === -1)
+                        return;
+                    clearTimeout(timer);
+                    const line = buffer.subarray(0, newlineIndex).toString("utf8");
+                    const decoded = JSON.parse(line);
+                    resolve({ nonce: decoded.nonce ?? "", afterReady: Buffer.from(buffer.subarray(newlineIndex + 1)) });
+                });
+            });
+            expect(readyAndAfter.nonce).toBe(nonce);
+            // Scan the retained suffix for the client preface, the same rule
+            // `createHttp2PrefaceScanningChannel` in `execution-target.ts` applies:
+            // the scan window opens only on bytes after the accepted READY line.
+            let sawPreface = false;
+            let downstream = null;
+            let pendingAfterPreface = Buffer.alloc(0);
+            let scanBuffer = readyAndAfter.afterReady;
+            function deliver(chunk) {
+                if (downstream)
+                    downstream(chunk);
+                else
+                    pendingAfterPreface = Buffer.concat([pendingAfterPreface, chunk]);
+            }
+            function handleChunk(chunk) {
+                if (sawPreface) {
+                    deliver(chunk);
+                    return;
+                }
+                scanBuffer = Buffer.concat([scanBuffer, chunk]);
+                const offset = scanBuffer.indexOf(CLIENT_PREFACE);
+                if (offset === -1)
+                    return;
+                sawPreface = true;
+                const fromPreface = Buffer.from(scanBuffer.subarray(offset));
+                scanBuffer = Buffer.alloc(0);
+                deliver(fromPreface);
+            }
+            // The already-retained suffix might already hold the preface.
+            handleChunk(Buffer.alloc(0));
+            session.onData((chunk) => handleChunk(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+            // Wrap the channel as a Node `Duplex` starting at the preface offset,
+            // and bind one plaintext HTTP/2 server session on it.
+            const boundDuplex = new Duplex({
+                read() { },
+                write(chunk, _encoding, callback) {
+                    session.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                    callback();
+                },
+            });
+            downstream = (chunk) => boundDuplex.push(chunk);
+            if (pendingAfterPreface.length > 0) {
+                boundDuplex.push(pendingAfterPreface);
+                pendingAfterPreface = Buffer.alloc(0);
+            }
+            const server = http2.createServer();
+            server.on("stream", (stream) => {
+                stream.respond({ ":status": 200 });
+                stream.end("pong");
+            });
+            server.emit("connection", boundDuplex);
+            const exit = await session.wait();
+            expect(exit.exitCode).toBe(0);
+            // eslint-disable-next-line no-console
+            console.log("[duplex-live] http2_v1: READY, then the real client preface, then one full HTTP/2 round trip, all over one live Daytona PTY.");
+        }
+        finally {
+            await session.close();
+        }
+    }, LIVE_TIMEOUT_MS);
+});
+//# sourceMappingURL=duplex-command-stream.live.test.js.map