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(sandbox): add a duplex transport for Daytona behind a default-off kill switch (#11750)
Nicky Leachfaab2620ad24
diff --git a/packages/adapter-utils/src/command-managed-runtime.ts b/packages/adapter-utils/src/command-managed-runtime.tsindex 22a458b135..4c879dbf4d 100644--- a/packages/adapter-utils/src/command-managed-runtime.ts+++ b/packages/adapter-utils/src/command-managed-runtime.ts@@ -19,13 +19,14 @@ import type { RuntimeProgressSink, RuntimeStatusSink } from "./runtime-progress.import type { RuntimeSpanRunner } from "./acpx-engine/startup-timing.js";/**- * Input for a duplex channel open. The caller supplies only the command line- * the sandbox runs as the channel child process. The runner adds the lease- * scope from its own closure. This type is separate from the worker manager's+ * Input for a duplex channel open. The caller supplies only the command argument+ * vector the sandbox runs as the channel child process. Element 0 is the program+ * and the rest are its arguments. The runner adds the lease scope from its own+ * closure. This type is separate from the worker manager's* `DuplexChannelOpenInput`, which also carries the lease scope fields.*/export interface DuplexChannelOpenInput {- command: string;+ command: readonly string[];}/**diff --git a/packages/adapter-utils/src/execution-target-sandbox.test.ts b/packages/adapter-utils/src/execution-target-sandbox.test.tsindex 3e41253f53..75756182a5 100644--- a/packages/adapter-utils/src/execution-target-sandbox.test.ts+++ b/packages/adapter-utils/src/execution-target-sandbox.test.ts@@ -4,9 +4,15 @@ import { execFile, spawn } from "node:child_process";import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";import os from "node:os";import path from "node:path";+import { fileURLToPath } from "node:url";import { promisify } from "node:util";import { afterEach, describe, expect, it, vi } from "vitest";+import {+ getSandboxCallbackBridgeServerSource,+ getSandboxDuplexGatewayCodecSource,+} from "./sandbox-callback-bridge.js";+import {DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,adapterExecutionTargetSessionIdentity,@@ -2748,3 +2754,524 @@ describe("sandbox adapter execution targets", () => {}});});++// One decoded stdout frame from the generated duplex gateway. The gateway writes+// newline-delimited JSON frames to stdout, so the test parses each line.+interface DecodedGatewayFrame {+ version?: number;+ type?: string;+ id?: string;+ method?: string;+ path?: string;+ query?: string;+ headers?: Record<string, string>;+ body?: string;+ address?: string;+ __unparsed?: string;+}++// One decode result from the embedded codec. The shape mirrors the host codec:+// a valid frame or a protocol error with a code.+interface EmbeddedDecodeResult {+ ok: boolean;+ frame?: unknown;+ error?: { code: string; message: string };+}++// The names the embedded codec source declares. A test wraps the source and+// reads these names back.+interface EmbeddedCodec {+ encodeDuplexFrame: (frame: unknown) => string;+ decodeDuplexLine: (line: string | Buffer) => EmbeddedDecodeResult;+ DuplexFrameDecoder: new (options?: { maxFrameBytes?: number }) => {+ push: (chunk: Buffer) => EmbeddedDecodeResult[];+ };+ DUPLEX_FRAME_VERSION: number;+ DEFAULT_MAX_DUPLEX_FRAME_BYTES: number;+}++type ExpectedVectorResult = { frame: unknown } | { error: string };++interface DuplexFrameVector {+ name: string;+ category: string;+ bytes: string;+ splitByteOffsets?: number[];+ maxFrameBytes?: number;+ roundTrip?: boolean;+ expected: ExpectedVectorResult[];+}++interface DuplexFrameFixture {+ frameVersion: number;+ defaultMaxFrameBytes: number;+ vectors: DuplexFrameVector[];+}++describe("sandbox duplex gateway", () => {+ const duplexCleanupDirs: string[] = [];+ const duplexChildren: Array<ReturnType<typeof spawn>> = [];++ afterEach(async () => {+ while (duplexChildren.length > 0) {+ const child = duplexChildren.pop();+ if (!child) continue;+ child.kill("SIGKILL");+ }+ while (duplexCleanupDirs.length > 0) {+ const dir = duplexCleanupDirs.pop();+ if (!dir) continue;+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);+ }+ });++ interface DuplexGatewayHandle {+ baseUrl: string;+ frames: DecodedGatewayFrame[];+ stderr: () => string;+ waitForFrame: (+ predicate: (frame: DecodedGatewayFrame) => boolean,+ timeoutMs?: number,+ ) => Promise<DecodedGatewayFrame>;+ sendFrame: (frame: Record<string, unknown>) => void;+ sendRaw: (text: string) => void;+ endStdin: () => void;+ exited: Promise<number | null>;+ stop: () => Promise<void>;+ }++ // Start the generated gateway `.mjs` in duplex mode as a real child process.+ // The test writes response frames to the child stdin and reads request frames+ // from the child stdout, so it stands in for the host side of the channel.+ async function startDuplexGateway(env: Record<string, string>): Promise<DuplexGatewayHandle> {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-duplex-gateway-"));+ duplexCleanupDirs.push(rootDir);+ const entrypoint = path.join(rootDir, "gateway.mjs");+ await writeFile(entrypoint, getSandboxCallbackBridgeServerSource(), "utf8");++ const child = spawn(process.execPath, [entrypoint], {+ stdio: ["pipe", "pipe", "pipe"],+ env: {+ ...process.env,+ PAPERCLIP_API_BRIDGE_MODE: "duplex_v1",+ PAPERCLIP_BRIDGE_HOST: "127.0.0.1",+ PAPERCLIP_BRIDGE_PORT: "0",+ ...env,+ },+ });+ duplexChildren.push(child);++ const frames: DecodedGatewayFrame[] = [];+ const waiters: Array<{+ predicate: (frame: DecodedGatewayFrame) => boolean;+ resolve: (frame: DecodedGatewayFrame) => void;+ }> = [];+ let stdoutBuffer = "";+ let stderrText = "";++ child.stdout?.setEncoding("utf8");+ child.stdout?.on("data", (chunk: string) => {+ stdoutBuffer += chunk;+ let newlineIndex = stdoutBuffer.indexOf("\n");+ while (newlineIndex !== -1) {+ const line = stdoutBuffer.slice(0, newlineIndex);+ stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);+ if (line.length > 0) {+ let frame: DecodedGatewayFrame;+ try {+ frame = JSON.parse(line) as DecodedGatewayFrame;+ } catch {+ frame = { __unparsed: line };+ }+ frames.push(frame);+ for (const waiter of [...waiters]) {+ if (waiter.predicate(frame)) {+ waiters.splice(waiters.indexOf(waiter), 1);+ waiter.resolve(frame);+ }+ }+ }+ newlineIndex = stdoutBuffer.indexOf("\n");+ }+ });+ child.stderr?.setEncoding("utf8");+ child.stderr?.on("data", (chunk: string) => {+ stderrText += chunk;+ });++ const exited = new Promise<number | null>((resolve) => {+ child.on("exit", (code) => resolve(code));+ });++ const waitForFrame = (+ predicate: (frame: DecodedGatewayFrame) => boolean,+ timeoutMs = 5000,+ ): Promise<DecodedGatewayFrame> => {+ const existing = frames.find(predicate);+ if (existing) return Promise.resolve(existing);+ return new Promise<DecodedGatewayFrame>((resolve, reject) => {+ const waiter = {+ predicate,+ resolve: (frame: DecodedGatewayFrame) => {+ clearTimeout(timer);+ resolve(frame);+ },+ };+ const timer = setTimeout(() => {+ const index = waiters.indexOf(waiter);+ if (index !== -1) waiters.splice(index, 1);+ reject(new Error(`Timed out waiting for a gateway frame. stderr: ${stderrText}`));+ }, timeoutMs);+ waiters.push(waiter);+ });+ };++ const handle: DuplexGatewayHandle = {+ baseUrl: "",+ frames,+ stderr: () => stderrText,+ waitForFrame,+ sendFrame: (frame) => {+ child.stdin?.write(`${JSON.stringify(frame)}\n`);+ },+ sendRaw: (text) => {+ child.stdin?.write(text);+ },+ endStdin: () => {+ child.stdin?.end();+ },+ exited,+ stop: async () => {+ child.kill("SIGKILL");+ await exited.catch(() => null);+ },+ };++ const ready = await waitForFrame((frame) => frame.type === "ready");+ handle.baseUrl = String(ready.address);+ return handle;+ }++ it("embedded gateway codec passes every vector in the shared fixture", async () => {+ const codecFactory = new Function(+ `${getSandboxDuplexGatewayCodecSource()}\nreturn { encodeDuplexFrame, decodeDuplexLine, DuplexFrameDecoder, DUPLEX_FRAME_VERSION, DEFAULT_MAX_DUPLEX_FRAME_BYTES };`,+ ) as unknown as () => EmbeddedCodec;+ const codec = codecFactory();++ const fixturePath = fileURLToPath(new URL("./duplex-frame-vectors.json", import.meta.url));+ const fixture = JSON.parse(await readFile(fixturePath, "utf8")) as DuplexFrameFixture;++ expect(fixture.frameVersion).toBe(codec.DUPLEX_FRAME_VERSION);+ expect(fixture.defaultMaxFrameBytes).toBe(codec.DEFAULT_MAX_DUPLEX_FRAME_BYTES);+ expect(fixture.vectors.length).toBeGreaterThanOrEqual(22);++ const failures: string[] = [];+ for (const vector of fixture.vectors) {+ const decoder = new codec.DuplexFrameDecoder(+ vector.maxFrameBytes ? { maxFrameBytes: vector.maxFrameBytes } : undefined,+ );+ const buffer = Buffer.from(vector.bytes, "utf8");+ const offsets = vector.splitByteOffsets;+ const bounds =+ offsets && offsets.length > 0 ? [0, ...offsets, buffer.length] : [0, buffer.length];+ const results: EmbeddedDecodeResult[] = [];+ for (let index = 0; index < bounds.length - 1; index += 1) {+ results.push(...decoder.push(buffer.subarray(bounds[index], bounds[index + 1])));+ }++ if (results.length !== vector.expected.length) {+ failures.push(`${vector.name}: got ${results.length} results, want ${vector.expected.length}`);+ continue;+ }+ vector.expected.forEach((want, index) => {+ const got = results[index];+ if ("frame" in want) {+ if (!got.ok) {+ failures.push(`${vector.name}[${index}]: expected a frame, got an error`);+ return;+ }+ try {+ expect(got.frame).toEqual(want.frame);+ } catch {+ failures.push(`${vector.name}[${index}]: frame does not match`);+ }+ } else {+ if (got.ok) {+ failures.push(`${vector.name}[${index}]: expected an error, got a frame`);+ return;+ }+ if (got.error?.code !== want.error) {+ failures.push(`${vector.name}[${index}]: error ${got.error?.code} != ${want.error}`);+ }+ }+ });+ }+ expect(failures).toEqual([]);++ // The encode side stays wire compatible too: one line, one newline, and the+ // same frame after a decode round trip.+ for (const vector of fixture.vectors.filter((entry) => entry.roundTrip)) {+ const want = vector.expected[0];+ if (!("frame" in want)) continue;+ const encoded = codec.encodeDuplexFrame(want.frame);+ expect(encoded.endsWith("\n")).toBe(true);+ expect(encoded.slice(0, -1)).not.toContain("\n");+ const decoded = codec.decodeDuplexLine(encoded.slice(0, -1));+ expect(decoded.ok).toBe(true);+ expect(decoded.frame).toEqual(want.frame);+ }+ });++ it("returns the same HTTP response as the file gateway for a forwarded request", async () => {+ const token = "duplex-token-forward";+ const gateway = await startDuplexGateway({ PAPERCLIP_BRIDGE_TOKEN: token });++ const responsePromise = fetch(`${gateway.baseUrl}/api/agents/me?view=compact`, {+ headers: {+ authorization: `Bearer ${token}`,+ accept: "application/json",+ "if-none-match": '"cache-key"',+ "x-bridge-debug": "drop-me",+ },+ });+ const requestFrame = await gateway.waitForFrame((frame) => frame.type === "request");+ expect(requestFrame.method).toBe("GET");+ expect(requestFrame.path).toBe("/api/agents/me");+ expect(requestFrame.query).toBe("?view=compact");+ // Only allowlisted headers forward; the bearer and the debug header drop.+ expect(requestFrame.headers).toEqual({+ accept: "application/json",+ "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",+ });+ const response = await responsePromise;+ expect(response.status).toBe(200);+ expect(response.headers.get("content-type")).toContain("application/json");+ expect(response.headers.get("etag")).toBe('"rev-1"');+ await expect(response.json()).resolves.toEqual({ ok: true });++ // An indeterminate outcome maps to a non-retryable 409, the same contract the+ // file gateway applies through the outcome header.+ const indeterminatePromise = fetch(`${gateway.baseUrl}/api/issues/issue-1`, {+ method: "PATCH",+ headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },+ body: JSON.stringify({ status: "in_progress" }),+ });+ 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",+ });+ const indeterminate = await indeterminatePromise;+ expect(indeterminate.status).toBe(409);++ await gateway.stop();+ }, 20000);++ it("enforces the bearer check, JSON-only rule, body limit, and depth limit", async () => {+ const token = "duplex-token-contract";+ const gateway = await startDuplexGateway({+ PAPERCLIP_BRIDGE_TOKEN: token,+ PAPERCLIP_BRIDGE_MAX_QUEUE_DEPTH: "1",+ PAPERCLIP_BRIDGE_MAX_BODY_BYTES: "16",+ });++ const badAuth = await fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: "Bearer wrong-token" },+ });+ expect(badAuth.status).toBe(401);+ await expect(badAuth.json()).resolves.toEqual({ error: "Invalid bridge token." });++ const nonJson = await fetch(`${gateway.baseUrl}/api/issues/issue-1/comments`, {+ method: "POST",+ headers: { authorization: `Bearer ${token}`, "content-type": "text/plain" },+ body: "not json",+ });+ expect(nonJson.status).toBe(415);+ await expect(nonJson.json()).resolves.toEqual({+ error: "Bridge only accepts JSON request bodies.",+ });++ const oversizeBody = await fetch(`${gateway.baseUrl}/api/issues/issue-1/comments`, {+ method: "POST",+ headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },+ body: JSON.stringify({ body: "x".repeat(64) }),+ });+ expect(oversizeBody.status).toBe(502);+ await expect(oversizeBody.json()).resolves.toEqual({+ error: "Bridge request body exceeded the configured size limit.",+ });++ // No request frame forwarded so far: the guards rejected before forwarding.+ const framesBeforeDepth = gateway.frames.filter((frame) => frame.type === "request").length;+ expect(framesBeforeDepth).toBe(0);++ // One outstanding request fills the single depth slot; the host never+ // responds, so the slot stays used.+ const outstanding = fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${token}` },+ });+ void outstanding.catch(() => undefined);+ await gateway.waitForFrame((frame) => frame.type === "request");++ const queueFull = await fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${token}` },+ });+ expect(queueFull.status).toBe(503);+ await expect(queueFull.json()).resolves.toEqual({ error: "Bridge request queue is full." });++ // Only the outstanding request forwarded a frame; the queue-full request did+ // not.+ const framesAfterDepth = gateway.frames.filter((frame) => frame.type === "request").length;+ expect(framesAfterDepth).toBe(1);++ await gateway.stop();+ }, 20000);++ it("answers outstanding requests 409 and new requests 503 on stdin EOF, then exits", async () => {+ const token = "duplex-token-eof";+ const gateway = await startDuplexGateway({+ PAPERCLIP_BRIDGE_TOKEN: token,+ PAPERCLIP_BRIDGE_LOSS_EXIT_GRACE_MS: "3000",+ });++ const outstanding = fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${token}` },+ });+ await gateway.waitForFrame((frame) => frame.type === "request");+ gateway.endStdin();++ const lossResponse = await outstanding;+ expect(lossResponse.status).toBe(409);+ expect(lossResponse.headers.get("x-paperclip-bridge-outcome")).toBe("indeterminate");+ await expect(lossResponse.json()).resolves.toEqual({ error: "outcome_indeterminate" });++ const afterLoss = await fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${token}` },+ });+ expect(afterLoss.status).toBe(503);+ await expect(afterLoss.json()).resolves.toEqual({ error: "bridge_unavailable" });++ const exitCode = await gateway.exited;+ expect(exitCode).toBe(0);+ }, 20000);++ it("applies the same loss behavior on a heartbeat timeout", async () => {+ const token = "duplex-token-heartbeat";+ const gateway = await startDuplexGateway({+ PAPERCLIP_BRIDGE_TOKEN: token,+ PAPERCLIP_BRIDGE_HEARTBEAT_TIMEOUT_MS: "400",+ PAPERCLIP_BRIDGE_LOSS_EXIT_GRACE_MS: "3000",+ PAPERCLIP_BRIDGE_RESPONSE_TIMEOUT_MS: "30000",+ });++ // Never send an inbound frame: inbound silence trips the heartbeat timeout.+ const outstanding = fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${token}` },+ });+ await gateway.waitForFrame((frame) => frame.type === "request");++ const lossResponse = await outstanding;+ expect(lossResponse.status).toBe(409);+ await expect(lossResponse.json()).resolves.toEqual({ error: "outcome_indeterminate" });++ const afterLoss = await fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${token}` },+ });+ expect(afterLoss.status).toBe(503);+ await expect(afterLoss.json()).resolves.toEqual({ error: "bridge_unavailable" });++ const exitCode = await gateway.exited;+ expect(exitCode).toBe(0);+ }, 20000);++ it("keeps diagnostics off stdout; stdout carries only frames", async () => {+ const token = "duplex-token-stdout";+ const gateway = await startDuplexGateway({ PAPERCLIP_BRIDGE_TOKEN: token });++ const responsePromise = fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${token}` },+ });+ const requestFrame = await gateway.waitForFrame((frame) => frame.type === "request");++ // 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",+ });++ const response = await responsePromise;+ expect(response.status).toBe(200);++ // Every stdout line parsed as a frame; none was diagnostic text.+ expect(gateway.frames.some((frame) => frame.__unparsed !== undefined)).toBe(false);+ expect(+ gateway.frames.every(+ (frame) => typeof frame.version === "number" && typeof frame.type === "string",+ ),+ ).toBe(true);+ const allowedTypes = new Set(["ready", "heartbeat", "request"]);+ expect(gateway.frames.every((frame) => allowedTypes.has(String(frame.type)))).toBe(true);++ // The malformed inbound line produced a stderr diagnostic, not a stdout one.+ expect(gateway.stderr()).toContain("dropped an inbound frame");++ await gateway.stop();+ }, 20000);++ it("defaults the wait budget to 35 s and honors the environment key override", async () => {+ // The generated source carries the 35 s default.+ expect(getSandboxCallbackBridgeServerSource()).toContain("35000");++ const token = "duplex-token-budget";+ const gateway = await startDuplexGateway({+ PAPERCLIP_BRIDGE_TOKEN: token,+ PAPERCLIP_BRIDGE_RESPONSE_TIMEOUT_MS: "150",+ PAPERCLIP_BRIDGE_HEARTBEAT_TIMEOUT_MS: "30000",+ });++ const started = Date.now();+ const response = await fetch(`${gateway.baseUrl}/api/agents/me`, {+ headers: { authorization: `Bearer ${token}` },+ });+ expect(response.status).toBe(502);+ await expect(response.json()).resolves.toEqual({+ error: "Timed out waiting for host bridge response.",+ });+ expect(Date.now() - started).toBeLessThan(4000);++ await gateway.stop();+ }, 20000);+});diff --git a/packages/adapter-utils/src/sandbox-callback-bridge.ts b/packages/adapter-utils/src/sandbox-callback-bridge.tsindex 25db401931..2c28dfe635 100644--- a/packages/adapter-utils/src/sandbox-callback-bridge.ts+++ b/packages/adapter-utils/src/sandbox-callback-bridge.ts@@ -55,6 +55,28 @@ const SANDBOX_CALLBACK_BRIDGE_ENTRYPOINT = "paperclip-bridge-server.mjs";const SANDBOX_EXEC_CHANNEL_ENV = "PAPERCLIP_SANDBOX_EXEC_CHANNEL";const SANDBOX_EXEC_CHANNEL_BRIDGE = "bridge";+// The two bridge modes the generated gateway supports. The file mode polls a+// request/response queue on disk. The duplex mode forwards one request frame to+// stdout and resolves one response frame from stdin. The generated `.mjs`+// selects the mode from `PAPERCLIP_API_BRIDGE_MODE`.+const SANDBOX_CALLBACK_BRIDGE_FILE_MODE = "queue_v1";+const SANDBOX_CALLBACK_BRIDGE_DUPLEX_MODE = "duplex_v1";++// The duplex gateway HTTP wait budget default. The gateway waits this long for a+// response frame before it answers the local caller with a 502 timeout. The+// value stays configurable through `PAPERCLIP_BRIDGE_RESPONSE_TIMEOUT_MS`, the+// same environment key the file mode reads.+const DEFAULT_DUPLEX_GATEWAY_WAIT_BUDGET_MS = 35_000;+// How often the duplex gateway writes a heartbeat frame to stdout.+const DEFAULT_DUPLEX_GATEWAY_HEARTBEAT_INTERVAL_MS = 5_000;+// The duplex gateway treats the channel as lost when no inbound frame arrives on+// stdin within this window.+const DEFAULT_DUPLEX_GATEWAY_HEARTBEAT_TIMEOUT_MS = 20_000;+// After a loss, the duplex gateway answers each new local request with a 503,+// then exits when this grace ends. The grace gives the local caller time to read+// the 409 for an outstanding request and a 503 for a new request.+const DEFAULT_DUPLEX_GATEWAY_LOSS_EXIT_GRACE_MS = 1_000;+/** Span name that wraps one Paperclip-API callback request — read the request,* write the response, and remove the request file. */const CALLBACK_BRIDGE_RELAY_REQUEST_SPAN = "sandbox.callbackBridge.relayRequest";@@ -413,7 +435,7 @@ export function buildSandboxCallbackBridgeEnv(input: {maxBodyBytes?: number | null;}): Record<string, string> {return {- PAPERCLIP_API_BRIDGE_MODE: "queue_v1",+ PAPERCLIP_API_BRIDGE_MODE: SANDBOX_CALLBACK_BRIDGE_FILE_MODE,PAPERCLIP_BRIDGE_QUEUE_DIR: input.queueDir,PAPERCLIP_BRIDGE_TOKEN: input.bridgeToken,PAPERCLIP_BRIDGE_HOST: input.host?.trim() || "127.0.0.1",@@ -1710,30 +1732,230 @@ export async function startSandboxCallbackBridgeServer(input: {};}+/**+ * The zero-dependency codec the generated duplex gateway embeds. It is a plain+ * JavaScript copy of the host codec in `duplex-frame-codec.ts`. It uses only the+ * `Buffer`, `JSON`, `Object`, `Set`, and `Array` globals, so the generated+ * `.mjs` needs no workspace import. It carries no template literal and no `${`+ * sequence, so it embeds inside the gateway template literal with no escape.+ *+ * A shared fixture file (`duplex-frame-vectors.json`) proves this copy stays wire+ * 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 DEFAULT_MAX_DUPLEX_FRAME_BYTES = 1000000;+const DUPLEX_NEWLINE_BYTE = 0x0a;+const DUPLEX_EMPTY = Buffer.alloc(0);+const DUPLEX_RESPONSE_OUTCOMES = new Set(["completed", "indeterminate", "unavailable"]);++function duplexOk(frame) {+ return { ok: true, frame: frame };+}++function duplexFail(code, message) {+ return { ok: false, error: { code: code, message: message } };+}++function duplexIsPlainObject(value) {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}++function duplexIsStringRecord(value) {+ if (!duplexIsPlainObject(value)) return false;+ for (const entry of Object.values(value)) {+ if (typeof entry !== "string") return false;+ }+ return true;+}++function encodeDuplexFrame(frame) {+ return JSON.stringify(frame) + "\\n";+}++function decodeDuplexLine(line) {+ const text = typeof line === "string" ? line : line.toString("utf8");+ let parsed;+ try {+ parsed = JSON.parse(text);+ } catch (error) {+ return duplexFail("malformed_frame", "frame is not valid JSON");+ }+ if (!duplexIsPlainObject(parsed)) {+ return duplexFail("malformed_frame", "frame is not a JSON object");+ }+ if (parsed.version !== DUPLEX_FRAME_VERSION) {+ return duplexFail("version_mismatch", "frame version " + String(parsed.version) + " is not " + DUPLEX_FRAME_VERSION);+ }+ return duplexValidateFrame(parsed);+}++function duplexValidateFrame(frame) {+ switch (frame.type) {+ case "request":+ return duplexValidateRequest(frame);+ case "response":+ return duplexValidateResponse(frame);+ case "ready":+ return duplexValidateReady(frame);+ case "heartbeat":+ return duplexOk(frame);+ case "close":+ return duplexOk(frame);+ case "error":+ return duplexValidateError(frame);+ default:+ return duplexFail("unknown_type", "unknown frame type " + JSON.stringify(frame.type));+ }+}++function duplexValidateRequest(frame) {+ if (+ typeof frame.id !== "string" ||+ typeof frame.method !== "string" ||+ typeof frame.path !== "string" ||+ typeof frame.query !== "string" ||+ typeof frame.body !== "string" ||+ !duplexIsStringRecord(frame.headers)+ ) {+ return duplexFail("malformed_frame", "request frame has a missing or wrong-typed field");+ }+ return duplexOk(frame);+}++function duplexValidateResponse(frame) {+ if (+ typeof frame.id !== "string" ||+ typeof frame.status !== "number" ||+ typeof frame.body !== "string" ||+ !duplexIsStringRecord(frame.headers) ||+ typeof frame.outcome !== "string" ||+ !DUPLEX_RESPONSE_OUTCOMES.has(frame.outcome)+ ) {+ return duplexFail("malformed_frame", "response frame has a missing or wrong-typed field");+ }+ return duplexOk(frame);+}++function duplexValidateReady(frame) {+ if (typeof frame.address !== "string") {+ return duplexFail("malformed_frame", "ready frame has a missing or wrong-typed address");+ }+ return duplexOk(frame);+}++function duplexValidateError(frame) {+ if (typeof frame.code !== "string") {+ return duplexFail("malformed_frame", "error frame has a missing or wrong-typed code");+ }+ if (frame.message !== undefined && typeof frame.message !== "string") {+ return duplexFail("malformed_frame", "error frame has a wrong-typed message");+ }+ return duplexOk(frame);+}++class DuplexFrameDecoder {+ constructor(options) {+ this.buffer = DUPLEX_EMPTY;+ this.discarding = false;+ this.maxFrameBytes =+ options && options.maxFrameBytes != null ? options.maxFrameBytes : DEFAULT_MAX_DUPLEX_FRAME_BYTES;+ }++ push(chunk) {+ const incoming = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : Buffer.from(chunk);+ this.buffer = this.buffer.length === 0 ? incoming : Buffer.concat([this.buffer, incoming]);+ const results = [];+ for (;;) {+ if (this.discarding) {+ const newlineIndex = this.buffer.indexOf(DUPLEX_NEWLINE_BYTE);+ if (newlineIndex === -1) {+ this.buffer = DUPLEX_EMPTY;+ break;+ }+ this.buffer = this.buffer.subarray(newlineIndex + 1);+ this.discarding = false;+ continue;+ }+ const newlineIndex = this.buffer.indexOf(DUPLEX_NEWLINE_BYTE);+ if (newlineIndex === -1) {+ if (this.buffer.length > this.maxFrameBytes) {+ results.push(duplexFail("frame_too_large", "frame exceeds the maximum size"));+ this.discarding = true;+ this.buffer = DUPLEX_EMPTY;+ }+ break;+ }+ const line = this.buffer.subarray(0, newlineIndex);+ this.buffer = this.buffer.subarray(newlineIndex + 1);+ if (line.length === 0) continue;+ if (line.length > this.maxFrameBytes) {+ results.push(duplexFail("frame_too_large", "frame exceeds the maximum size"));+ continue;+ }+ results.push(decodeDuplexLine(line));+ }+ return results;+ }+}`;++/**+ * Return the exact zero-dependency codec source the generated duplex gateway+ * embeds. A test runs every fixture vector against this source, so it proves the+ * embedded copy decodes the same bytes as the host codec. The source declares+ * `encodeDuplexFrame`, `decodeDuplexLine`, `DuplexFrameDecoder`,+ * `DUPLEX_FRAME_VERSION`, and `DEFAULT_MAX_DUPLEX_FRAME_BYTES`, but exports none+ * of them; a caller wraps it to read those names.+ */+export function getSandboxDuplexGatewayCodecSource(): string {+ return DUPLEX_GATEWAY_CODEC_SOURCE;+}+export function getSandboxCallbackBridgeServerSource(): string {return `import { randomUUID, timingSafeEqual } from "node:crypto";import { createServer } from "node:http";import { promises as fs } from "node:fs";import path from "node:path";+const bridgeMode = process.env.PAPERCLIP_API_BRIDGE_MODE || "${SANDBOX_CALLBACK_BRIDGE_FILE_MODE}";const queueDir = process.env.PAPERCLIP_BRIDGE_QUEUE_DIR;const bridgeToken = process.env.PAPERCLIP_BRIDGE_TOKEN;const host = process.env.PAPERCLIP_BRIDGE_HOST || "127.0.0.1";const port = Number(process.env.PAPERCLIP_BRIDGE_PORT || "0");const pollIntervalMs = Number(process.env.PAPERCLIP_BRIDGE_POLL_INTERVAL_MS || "100");-const responseTimeoutMs = Number(process.env.PAPERCLIP_BRIDGE_RESPONSE_TIMEOUT_MS || "30000");+const responseTimeoutMs = Number(+ process.env.PAPERCLIP_BRIDGE_RESPONSE_TIMEOUT_MS ||+ (bridgeMode === "${SANDBOX_CALLBACK_BRIDGE_DUPLEX_MODE}"+ ? "${DEFAULT_DUPLEX_GATEWAY_WAIT_BUDGET_MS}"+ : "${DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS}"),+);const maxQueueDepth = Number(process.env.PAPERCLIP_BRIDGE_MAX_QUEUE_DEPTH || "${DEFAULT_BRIDGE_MAX_QUEUE_DEPTH}");const maxBodyBytes = Number(process.env.PAPERCLIP_BRIDGE_MAX_BODY_BYTES || "${DEFAULT_BRIDGE_MAX_BODY_BYTES}");+const heartbeatIntervalMs = Number(+ process.env.PAPERCLIP_BRIDGE_HEARTBEAT_INTERVAL_MS || "${DEFAULT_DUPLEX_GATEWAY_HEARTBEAT_INTERVAL_MS}",+);+const heartbeatTimeoutMs = Number(+ process.env.PAPERCLIP_BRIDGE_HEARTBEAT_TIMEOUT_MS || "${DEFAULT_DUPLEX_GATEWAY_HEARTBEAT_TIMEOUT_MS}",+);+const lossExitGraceMs = Number(+ process.env.PAPERCLIP_BRIDGE_LOSS_EXIT_GRACE_MS || "${DEFAULT_DUPLEX_GATEWAY_LOSS_EXIT_GRACE_MS}",+);+// The header allowlist. Both the file gateway and the duplex gateway strip an+// inbound request to these headers before they forward it. One copy serves both+// modes. The route allowlist stays on the host: both modes forward a request to+// the host, and the host enforces the same route allowlist for each.const allowedHeaders = new Set(${JSON.stringify([...DEFAULT_SANDBOX_CALLBACK_BRIDGE_HEADER_ALLOWLIST])});-if (!queueDir || !bridgeToken) {+if (!bridgeToken) {+ throw new Error("PAPERCLIP_BRIDGE_TOKEN is required.");+}+if (bridgeMode !== "${SANDBOX_CALLBACK_BRIDGE_DUPLEX_MODE}" && !queueDir) {throw new Error("PAPERCLIP_BRIDGE_QUEUE_DIR and PAPERCLIP_BRIDGE_TOKEN are required.");}-const requestsDir = path.posix.join(queueDir, "requests");-const responsesDir = path.posix.join(queueDir, "responses");-const logsDir = path.posix.join(queueDir, "logs");-const readyFile = path.posix.join(queueDir, "ready.json");+// The embedded zero-dependency frame codec. The duplex gateway uses it; the file+// gateway ignores it.+${DUPLEX_GATEWAY_CODEC_SOURCE}function sleep(ms) {return new Promise((resolve) => setTimeout(resolve, ms));@@ -1766,11 +1988,6 @@ async function readBody(req) {return Buffer.concat(chunks).toString("utf8");}-async function queueDepth() {- const entries = await fs.readdir(requestsDir, { withFileTypes: true }).catch(() => []);- return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).length;-}-function tokensMatch(received) {const expected = Buffer.from(bridgeToken, "utf8");const actual = Buffer.from(typeof received === "string" ? received : "", "utf8");@@ -1778,116 +1995,327 @@ function tokensMatch(received) {return timingSafeEqual(expected, actual);}-async function waitForResponse(requestId) {- const responsePath = path.posix.join(responsesDir, \`\${requestId}.json\`);- const deadline = Date.now() + responseTimeoutMs;- while (Date.now() < deadline) {- const body = await fs.readFile(responsePath, "utf8").catch(() => null);- if (body != null) {- await fs.rm(responsePath, { force: true }).catch(() => undefined);- return JSON.parse(body);+function writeJsonResponse(res, status, body) {+ res.statusCode = status;+ res.setHeader("content-type", "application/json");+ res.end(JSON.stringify(body));+}++async function runFileGateway() {+ const requestsDir = path.posix.join(queueDir, "requests");+ const responsesDir = path.posix.join(queueDir, "responses");+ const logsDir = path.posix.join(queueDir, "logs");+ const readyFile = path.posix.join(queueDir, "ready.json");++ async function queueDepth() {+ const entries = await fs.readdir(requestsDir, { withFileTypes: true }).catch(() => []);+ return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).length;+ }++ async function waitForResponse(requestId) {+ const responsePath = path.posix.join(responsesDir, \`\${requestId}.json\`);+ const deadline = Date.now() + responseTimeoutMs;+ while (Date.now() < deadline) {+ const body = await fs.readFile(responsePath, "utf8").catch(() => null);+ if (body != null) {+ await fs.rm(responsePath, { force: true }).catch(() => undefined);+ return JSON.parse(body);+ }+ await sleep(pollIntervalMs);}- await sleep(pollIntervalMs);+ throw new Error("Timed out waiting for host bridge response.");}- throw new Error("Timed out waiting for host bridge response.");++ const server = createServer(async (req, res) => {+ try {+ const auth = req.headers.authorization || "";+ const receivedToken = auth.startsWith("Bearer ") ? auth.slice("Bearer ".length) : "";+ if (!tokensMatch(receivedToken)) {+ writeJsonResponse(res, 401, { error: "Invalid bridge token." });+ return;+ }++ if (await queueDepth() >= maxQueueDepth) {+ writeJsonResponse(res, 503, { error: "Bridge request queue is full." });+ return;+ }++ const url = new URL(req.url || "/", "http://127.0.0.1");+ const contentType = typeof req.headers["content-type"] === "string" ? req.headers["content-type"] : "";+ if (req.method && req.method !== "GET" && req.method !== "HEAD" && !/json/i.test(contentType)) {+ writeJsonResponse(res, 415, { error: "Bridge only accepts JSON request bodies." });+ return;+ }+ const requestId = randomUUID();+ const requestBody = await readBody(req);+ const payload = {+ id: requestId,+ method: req.method || "GET",+ path: url.pathname,+ query: url.search,+ headers: normalizeHeaders(req.headers),+ body: requestBody,+ createdAt: new Date().toISOString(),+ };+ const requestPath = path.posix.join(requestsDir, \`\${requestId}.json\`);+ const tempPath = \`\${requestPath}.tmp\`;+ await fs.writeFile(tempPath, \`\${JSON.stringify(payload)}\\n\`, "utf8");+ await fs.rename(tempPath, requestPath);++ const response = await waitForResponse(requestId);+ const responseHeaders = response.headers || {};+ // The host marks a possibly-committed mutation with an indeterminate outcome.+ // The host cannot cancel a host operation that is in flight, so the mutation+ // may have committed before the worker aborted the handler. A 5xx status is+ // retryable by convention, so a caller that retries 5xx would apply the+ // mutation twice. Map the indeterminate outcome to a non-retryable 409, so a+ // standard retry policy does not repeat the request. The outcome header and+ // body stay, so a caller that reads them still sees the indeterminate result.+ const bridgeOutcome = responseHeaders["x-paperclip-bridge-outcome"];+ if (bridgeOutcome === "indeterminate") {+ res.statusCode = 409;+ } else {+ res.statusCode = typeof response.status === "number" ? response.status : 200;+ }+ for (const [key, value] of Object.entries(responseHeaders)) {+ if (typeof value !== "string" || key.toLowerCase() === "content-length") continue;+ res.setHeader(key, value);+ }+ res.end(typeof response.body === "string" ? response.body : "");+ } catch (error) {+ writeJsonResponse(res, 502, { error: error instanceof Error ? error.message : String(error) });+ }+ });++ async function shutdown() {+ server.close(() => {+ process.exit(0);+ });+ }++ process.on("SIGINT", () => void shutdown());+ process.on("SIGTERM", () => void shutdown());++ await fs.mkdir(requestsDir, { recursive: true });+ await fs.mkdir(responsesDir, { recursive: true });+ await fs.mkdir(logsDir, { recursive: true });++ server.listen(port, host, async () => {+ const address = server.address();+ if (!address || typeof address === "string") {+ throw new Error("Bridge server did not expose a TCP address.");+ }+ const ready = {+ pid: process.pid,+ host,+ port: address.port,+ baseUrl: \`http://\${host}:\${address.port}\`,+ startedAt: new Date().toISOString(),+ };+ const tempReadyFile = \`\${readyFile}.tmp\`;+ await fs.writeFile(tempReadyFile, JSON.stringify(ready), "utf8");+ await fs.rename(tempReadyFile, readyFile);+ });}-const server = createServer(async (req, res) => {- try {- const auth = req.headers.authorization || "";- const receivedToken = auth.startsWith("Bearer ") ? auth.slice("Bearer ".length) : "";- if (!tokensMatch(receivedToken)) {- res.statusCode = 401;- res.setHeader("content-type", "application/json");- res.end(JSON.stringify({ error: "Invalid bridge token." }));- return;+function runDuplexGateway() {+ // One outstanding local request per id. Each entry holds the HTTP resolver and+ // the wait-budget timer.+ const pending = new Map();+ let unavailable = false;+ let lossTriggered = false;+ let lastInboundAt = Date.now();++ function diag(message) {+ // Diagnostics go to stderr only. Stdout carries frames.+ process.stderr.write("[paperclip-bridge] " + message + "\\n");+ }++ function writeFrame(frame) {+ process.stdout.write(encodeDuplexFrame(frame));+ }++ function stopTimers() {+ clearInterval(heartbeatSendTimer);+ clearInterval(heartbeatWatchTimer);+ }++ // Loss behavior. On stdin end, a close frame, or a heartbeat timeout, answer+ // every outstanding request with a non-retryable 409 (the request may have+ // reached the host), answer every new request with a retryable 503 (the+ // request never left the gateway), then exit. The gateway never replays a+ // request.+ function triggerLoss(reason) {+ if (lossTriggered) return;+ lossTriggered = true;+ unavailable = true;+ diag("duplex channel lost: " + reason);+ stopTimers();+ for (const entry of pending.values()) {+ clearTimeout(entry.timer);+ entry.resolve({+ status: 409,+ headers: {+ "content-type": "application/json",+ "x-paperclip-bridge-outcome": "indeterminate",+ },+ body: JSON.stringify({ error: "outcome_indeterminate" }),+ });}+ pending.clear();+ const exitTimer = setTimeout(() => process.exit(0), lossExitGraceMs);+ if (typeof exitTimer.unref === "function") exitTimer.unref();+ }- if (await queueDepth() >= maxQueueDepth) {- res.statusCode = 503;- res.setHeader("content-type", "application/json");- res.end(JSON.stringify({ error: "Bridge request queue is full." }));+ 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({+ status: statusCode,+ headers: frame.headers || {},+ body: typeof frame.body === "string" ? frame.body : "",+ });return;}-- const url = new URL(req.url || "/", "http://127.0.0.1");- const contentType = typeof req.headers["content-type"] === "string" ? req.headers["content-type"] : "";- if (req.method && req.method !== "GET" && req.method !== "HEAD" && !/json/i.test(contentType)) {- res.statusCode = 415;- res.setHeader("content-type", "application/json");- res.end(JSON.stringify({ error: "Bridge only accepts JSON request bodies." }));+ if (frame.type === "close") {+ triggerLoss("host sent a close frame");return;}- const requestId = randomUUID();- const requestBody = await readBody(req);- const payload = {- id: requestId,- method: req.method || "GET",- path: url.pathname,- query: url.search,- headers: normalizeHeaders(req.headers),- body: requestBody,- createdAt: new Date().toISOString(),- };- const requestPath = path.posix.join(requestsDir, \`\${requestId}.json\`);- const tempPath = \`\${requestPath}.tmp\`;- await fs.writeFile(tempPath, \`\${JSON.stringify(payload)}\\n\`, "utf8");- await fs.rename(tempPath, requestPath);-- const response = await waitForResponse(requestId);- const responseHeaders = response.headers || {};- // The host marks a possibly-committed mutation with an indeterminate outcome.- // The host cannot cancel a host operation that is in flight, so the mutation- // may have committed before the worker aborted the handler. A 5xx status is- // retryable by convention, so a caller that retries 5xx would apply the- // mutation twice. Map the indeterminate outcome to a non-retryable 409, so a- // standard retry policy does not repeat the request. The outcome header and- // body stay, so a caller that reads them still sees the indeterminate result.- const bridgeOutcome = responseHeaders["x-paperclip-bridge-outcome"];- if (bridgeOutcome === "indeterminate") {- res.statusCode = 409;- } else {- res.statusCode = typeof response.status === "number" ? response.status : 200;+ // A heartbeat, ready, error, or request frame proves liveness but needs no+ // local action here.+ }++ const decoder = new DuplexFrameDecoder();+ process.stdin.on("data", (chunk) => {+ lastInboundAt = Date.now();+ for (const result of decoder.push(chunk)) {+ if (!result.ok) {+ diag("dropped an inbound frame: " + result.error.code);+ continue;+ }+ handleInboundFrame(result.frame);}- for (const [key, value] of Object.entries(responseHeaders)) {- if (typeof value !== "string" || key.toLowerCase() === "content-length") continue;- res.setHeader(key, value);+ });+ process.stdin.on("end", () => triggerLoss("stdin reached end of file"));+ process.stdin.on("error", (error) =>+ triggerLoss("stdin error: " + (error && error.message ? error.message : String(error))),+ );++ const heartbeatSendTimer = setInterval(() => {+ writeFrame({ version: DUPLEX_FRAME_VERSION, type: "heartbeat" });+ }, heartbeatIntervalMs);+ const heartbeatWatchTimer = setInterval(() => {+ if (Date.now() - lastInboundAt > heartbeatTimeoutMs) {+ triggerLoss("no inbound frame within the heartbeat timeout");}- res.end(typeof response.body === "string" ? response.body : "");- } catch (error) {- res.statusCode = 502;- res.setHeader("content-type", "application/json");- res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));- }-});+ }, Math.max(200, Math.floor(heartbeatTimeoutMs / 4)));-async function shutdown() {- server.close(() => {- process.exit(0);+ const server = createServer(async (req, res) => {+ try {+ const auth = req.headers.authorization || "";+ const receivedToken = auth.startsWith("Bearer ") ? auth.slice("Bearer ".length) : "";+ if (!tokensMatch(receivedToken)) {+ writeJsonResponse(res, 401, { error: "Invalid bridge token." });+ return;+ }+ if (unavailable) {+ writeJsonResponse(res, 503, { error: "bridge_unavailable" });+ return;+ }+ if (pending.size >= maxQueueDepth) {+ writeJsonResponse(res, 503, { error: "Bridge request queue is full." });+ return;+ }+ const url = new URL(req.url || "/", "http://127.0.0.1");+ const contentType = typeof req.headers["content-type"] === "string" ? req.headers["content-type"] : "";+ if (req.method && req.method !== "GET" && req.method !== "HEAD" && !/json/i.test(contentType)) {+ writeJsonResponse(res, 415, { error: "Bridge only accepts JSON request bodies." });+ return;+ }+ const requestId = randomUUID();+ const requestBody = await readBody(req);+ if (unavailable) {+ writeJsonResponse(res, 503, { error: "bridge_unavailable" });+ return;+ }+ const requestFrame = {+ version: DUPLEX_FRAME_VERSION,+ type: "request",+ id: requestId,+ method: req.method || "GET",+ path: url.pathname,+ query: url.search,+ headers: normalizeHeaders(req.headers),+ body: requestBody,+ };+ const response = await new Promise((resolve) => {+ const timer = setTimeout(() => {+ if (pending.delete(requestId)) {+ resolve({+ status: 502,+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ error: "Timed out waiting for host bridge response." }),+ });+ }+ }, responseTimeoutMs);+ pending.set(requestId, { resolve: resolve, timer: timer });+ writeFrame(requestFrame);+ });+ res.statusCode = typeof response.status === "number" ? response.status : 200;+ for (const [key, value] of Object.entries(response.headers || {})) {+ if (typeof value !== "string" || key.toLowerCase() === "content-length") continue;+ res.setHeader(key, value);+ }+ res.end(typeof response.body === "string" ? response.body : "");+ } catch (error) {+ writeJsonResponse(res, 502, { error: error instanceof Error ? error.message : String(error) });+ }});-}-process.on("SIGINT", () => void shutdown());-process.on("SIGTERM", () => void shutdown());+ process.on("SIGINT", () => {+ try {+ server.close();+ } catch (error) {+ diag("server close error: " + (error && error.message ? error.message : String(error)));+ }+ process.exit(0);+ });+ process.on("SIGTERM", () => {+ try {+ server.close();+ } catch (error) {+ diag("server close error: " + (error && error.message ? error.message : String(error)));+ }+ process.exit(0);+ });-await fs.mkdir(requestsDir, { recursive: true });-await fs.mkdir(responsesDir, { recursive: true });-await fs.mkdir(logsDir, { recursive: true });+ server.listen(port, host, () => {+ const address = server.address();+ if (!address || typeof address === "string") {+ diag("duplex gateway did not expose a TCP address");+ process.exit(1);+ return;+ }+ // The one READY frame carries the validated listener address. Stdout carries+ // only frames.+ writeFrame({+ version: DUPLEX_FRAME_VERSION,+ type: "ready",+ address: "http://" + host + ":" + address.port,+ });+ });+}-server.listen(port, host, async () => {- const address = server.address();- if (!address || typeof address === "string") {- throw new Error("Bridge server did not expose a TCP address.");- }- const ready = {- pid: process.pid,- host,- port: address.port,- baseUrl: \`http://\${host}:\${address.port}\`,- startedAt: new Date().toISOString(),- };- const tempReadyFile = \`\${readyFile}.tmp\`;- await fs.writeFile(tempReadyFile, JSON.stringify(ready), "utf8");- await fs.rename(tempReadyFile, readyFile);-});`;+if (bridgeMode === "${SANDBOX_CALLBACK_BRIDGE_DUPLEX_MODE}") {+ runDuplexGateway();+} else {+ await runFileGateway();+}`;}diff --git a/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.live.test.ts b/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.live.test.tsnew file mode 100644index 0000000000..88b80d2ec3--- /dev/null+++ b/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.live.test.ts@@ -0,0 +1,194 @@+// 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 {+ openDaytonaDuplexChannelSession,+ type DaytonaPtyProcess,+ type DuplexChannelSession,+} 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;++// The minimal shape of the live Daytona sandbox that the test uses. The dynamic+// import returns the real SDK types; this local shape keeps the file type-safe+// without a static SDK import.+interface LiveDaytonaSandbox {+ process: DaytonaPtyProcess & {+ executeCommand(command: string): Promise<{ exitCode?: number; result?: string }>;+ listSessions?: () => Promise<Array<{ sessionId?: string }>>;+ };+ delete(): Promise<void>;+}++/**+ * 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: () => string,+ predicate: (text: string) => boolean,+ timeoutMs: number,+ label: string,+): Promise<void> {+ 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: LiveDaytonaSandbox,+): Promise<{ session: DuplexChannelSession; readOutput: () => string }> {+ 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: LiveDaytonaSandbox | null = null;++ beforeAll(async () => {+ const { Daytona } = await import("@daytonaio/sdk");+ const client = new Daytona({ apiKey: DAYTONA_API_KEY });+ sandbox = (await client.create()) as unknown as LiveDaytonaSandbox;+ }, 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(`${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(`${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,+ );+});diff --git a/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.test.ts b/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.test.tsnew file mode 100644index 0000000000..476591afd6--- /dev/null+++ b/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.test.ts@@ -0,0 +1,416 @@+import { describe, expect, it } from "vitest";+import {+ buildDuplexChannelLaunchWrapper,+ createDaytonaDuplexChannelSessionOpener,+ openDaytonaDuplexChannelSession,+ type DaytonaPtyCreateOptions,+ type DaytonaPtyHandle,+ type DaytonaPtyProcess,+} from "./duplex-command-stream.js";++// The carriage return that submits the launch wrapper line to the terminal.+const ENTER = "\r";++// The gateway command the tests run on the channel. The command is an argument+// vector: element 0 is the program and the rest are its arguments. The real+// command is the generated duplex gateway; the tests use a placeholder, because+// the fake PTY runs no process.+const GATEWAY = ["node", "/paperclip/gateway.mjs"];++// The gateway argument vector after the wrapper quotes each element. The wrapper+// quotes every argument as a single-quoted shell word.+const GATEWAY_QUOTED = "'node' '/paperclip/gateway.mjs'";++/**+ * A fake Daytona PTY handle. It records each input write, drives the output+ * stream on demand, and records the kill and the disconnect. The tests use it in+ * place of the real SDK `PtyHandle`, so the session runs with no sandbox. The fake+ * never echoes input back as output, so a test proves the channel adds no echo.+ */+function createFakePtyHandle(onData: (data: Uint8Array) => void | Promise<void>): DaytonaPtyHandle & {+ inputs: string[];+ emitText: (text: string) => void;+ emitBytes: (bytes: Uint8Array) => void;+ finish: (exitCode: number | undefined) => void;+ killed: number;+ disconnected: number;+} {+ const encoder = new TextEncoder();+ const inputs: string[] = [];+ let resolveWait: ((value: { exitCode?: number; error?: string }) => void) | null = null;+ const waitPromise = new Promise<{ exitCode?: number; error?: string }>((resolve) => {+ resolveWait = resolve;+ });+ let killed = 0;+ let disconnected = 0;+ return {+ async waitForConnection(): Promise<void> {},+ async sendInput(data: string | Uint8Array): Promise<void> {+ inputs.push(typeof data === "string" ? data : new TextDecoder().decode(data));+ },+ wait(): Promise<{ exitCode?: number; error?: string }> {+ return waitPromise;+ },+ async kill(): Promise<void> {+ killed += 1;+ },+ async disconnect(): Promise<void> {+ disconnected += 1;+ },+ // Test control below. The session never reads these fields.+ emitText(text: string): void {+ onData(encoder.encode(text));+ },+ emitBytes(bytes: Uint8Array): void {+ onData(bytes);+ },+ finish(exitCode: number | undefined): void {+ resolveWait?.({ exitCode });+ },+ get inputs(): string[] {+ return inputs;+ },+ get killed(): number {+ return killed;+ },+ get disconnected(): number {+ return disconnected;+ },+ };+}++/**+ * A fake Daytona process. It opens one fake PTY handle and records the create+ * options, so a test asserts the terminal size and the launch wrapper.+ */+function createFakeProcess(): DaytonaPtyProcess & {+ handle: ReturnType<typeof createFakePtyHandle> | null;+ createOptions: DaytonaPtyCreateOptions | null;+} {+ const state: {+ handle: ReturnType<typeof createFakePtyHandle> | null;+ createOptions: DaytonaPtyCreateOptions | null;+ } = { handle: null, createOptions: null };+ return {+ get handle() {+ return state.handle;+ },+ get createOptions() {+ return state.createOptions;+ },+ async createPty(options: DaytonaPtyCreateOptions): Promise<DaytonaPtyHandle> {+ state.createOptions = options;+ const handle = createFakePtyHandle(options.onData);+ state.handle = handle;+ return handle;+ },+ };+}++// ---------------------------------------------------------------------------+// Characterization: which Daytona primitive carries a clean framed stream.+// ---------------------------------------------------------------------------+// The Daytona SDK proves two primitives. The ordinary session primitive+// dispatches a command and tails its output, split into stdout and stderr. It+// exposes no call that writes bytes to a running command's stdin, so it cannot+// carry host input on the same channel as the output. The PTY primitive exposes+// `sendInput` for host input and one `onData` callback for the output, on one live+// socket. Only the PTY carries a bidirectional stream on one connection, so the+// duplex channel uses the PTY. These tests record that decision against the two+// SDK surface shapes.++/** The subset of the Daytona session command surface, for the characterization. */+interface DaytonaSessionCommandSurface {+ createSession(sessionId: string): Promise<void>;+ executeSessionCommand(sessionId: string, command: unknown): Promise<{ cmdId?: string }>;+ getSessionCommandLogs(+ sessionId: string,+ commandId: string,+ onStdout: (chunk: string) => void,+ onStderr: (chunk: string) => void,+ ): Promise<void>;+ deleteSession(sessionId: string): Promise<void>;+}++describe("duplex primitive characterization", () => {+ it("the PTY surface carries host input and process output on one connection", () => {+ const process = createFakeProcess();+ // The PTY surface exposes both directions: `sendInput` for host bytes and the+ // `onData` create option for process bytes. This is the bidirectional shape a+ // duplex channel needs.+ expect(typeof process.createPty).toBe("function");+ const handleKeys: Array<keyof DaytonaPtyHandle> = [+ "waitForConnection",+ "sendInput",+ "wait",+ "kill",+ "disconnect",+ ];+ // `sendInput` is the host-to-process direction; the create option `onData` is+ // the process-to-host direction. Both exist on the PTY primitive.+ expect(handleKeys).toContain("sendInput");+ });++ it("the session command surface exposes no write to a running command's stdin", () => {+ // The session surface dispatches a command and tails split stdout/stderr. No+ // member writes bytes to a running command's stdin, so it cannot carry the+ // host input on the output channel. The duplex channel therefore uses the PTY,+ // not a session.+ const sessionMembers: Array<keyof DaytonaSessionCommandSurface> = [+ "createSession",+ "executeSessionCommand",+ "getSessionCommandLogs",+ "deleteSession",+ ];+ expect(sessionMembers).not.toContain("sendInput" as never);+ expect(sessionMembers).not.toContain("write" as never);+ // The log tail splits the output into two streams; a single framed duplex+ // stream must stay on one path, which the PTY `onData` provides.+ expect(sessionMembers).toContain("getSessionCommandLogs");+ });+});++// ---------------------------------------------------------------------------+// Launch wrapper: raw mode, echo off, diagnostics to a file, direct exec.+// ---------------------------------------------------------------------------++describe("buildDuplexChannelLaunchWrapper", () => {+ it("sets raw mode with echo off, redirects diagnostics to a file, and execs the gateway", () => {+ const wrapper = buildDuplexChannelLaunchWrapper(GATEWAY, "/tmp/diag.log");++ // Raw mode with echo off stops the terminal echoing host input as data and+ // stops newline translation, so the newline-delimited frames stay intact.+ expect(wrapper).toContain("stty raw -echo");+ // The diagnostics go to the file, never to the stdout frame stream. The+ // wrapper quotes the path as a single-quoted shell word.+ expect(wrapper).toContain("2>'/tmp/diag.log'");+ // The gateway starts with `exec`, so the PTY runs it directly and its exit+ // code becomes the PTY exit code.+ expect(wrapper).toContain(`exec ${GATEWAY_QUOTED}`);+ // The line ends with the Enter byte, so the shell runs it.+ expect(wrapper.endsWith(ENTER)).toBe(true);+ // Raw mode is set before the gateway starts.+ expect(wrapper.indexOf("stty raw -echo")).toBeLessThan(+ wrapper.indexOf(`exec ${GATEWAY_QUOTED}`),+ );+ });++ it("quotes a diagnostics path that holds shell metacharacters, so it cannot inject a command", () => {+ const wrapper = buildDuplexChannelLaunchWrapper(GATEWAY, "/tmp/x; rm -rf ~");++ // The path is one single-quoted word, so the shell reads the metacharacters as+ // literal text. The dangerous `rm` never becomes its own command.+ expect(wrapper).toContain("2>'/tmp/x; rm -rf ~'");+ expect(wrapper).not.toContain("2>/tmp/x; rm -rf ~");+ });++ it("quotes a single quote in the diagnostics path", () => {+ const wrapper = buildDuplexChannelLaunchWrapper(GATEWAY, "/tmp/o'clock.log");++ // A single quote closes the word, adds an escaped quote, and reopens the word.+ expect(wrapper).toContain(`2>'/tmp/o'"'"'clock.log'`);+ });++ it("quotes each command argument that holds shell metacharacters", () => {+ const wrapper = buildDuplexChannelLaunchWrapper(+ ["node", "/paperclip/gateway.mjs", "; rm -rf ~"],+ "/tmp/diag.log",+ );++ // Each argument is one single-quoted word, so the metacharacters stay literal+ // text. The dangerous `rm` argument never becomes its own command.+ expect(wrapper).toContain(`exec 'node' '/paperclip/gateway.mjs' '; rm -rf ~'`);+ expect(wrapper).not.toContain("; rm -rf ~;");+ expect(wrapper).not.toContain("exec node /paperclip/gateway.mjs ; rm -rf ~");+ });++ it("rejects an empty command argument vector", () => {+ // An empty vector has no program to exec, so the wrapper fails loudly.+ expect(() => buildDuplexChannelLaunchWrapper([], "/tmp/diag.log")).toThrow(+ /at least one argument/,+ );+ });+});++describe("openDaytonaDuplexChannelSession", () => {+ it("starts the gateway through the raw-mode wrapper on a fixed-size terminal", async () => {+ const process = createFakeProcess();++ await openDaytonaDuplexChannelSession(process, GATEWAY);++ expect(process.createOptions?.cols).toBe(120);+ expect(process.createOptions?.rows).toBe(30);+ const launch = process.handle?.inputs[0] ?? "";+ expect(launch).toContain("stty raw -echo");+ expect(launch).toContain(`exec ${GATEWAY_QUOTED}`);+ expect(launch.endsWith(ENTER)).toBe(true);+ });++ it("redirects diagnostics to the given file path", async () => {+ const process = createFakeProcess();++ await openDaytonaDuplexChannelSession(process, GATEWAY, {+ diagnosticsPath: "/tmp/paperclip-duplex-fixed.log",+ });++ expect(process.handle?.inputs[0]).toContain("2>'/tmp/paperclip-duplex-fixed.log'");+ });++ it("defaults the diagnostics path under /tmp when the caller gives none", async () => {+ const process = createFakeProcess();++ await openDaytonaDuplexChannelSession(process, GATEWAY);++ expect(process.handle?.inputs[0]).toMatch(/2>'\/tmp\/paperclip-duplex-[0-9a-f-]+\.log'/);+ });++ it("delivers a host write to the process and does not echo it back as data", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ session.onData((chunk) => received.push(chunk));++ // The launch wrapper is the first input; the host frame write is the second.+ session.write('{"version":1,"type":"heartbeat"}\n');+ expect(process.handle?.inputs[1]).toBe('{"version":1,"type":"heartbeat"}\n');+ // The fake terminal echoes nothing, so the write produces no data callback.+ // A real terminal in raw mode with echo off behaves the same way.+ expect(received).toEqual([]);+ });++ it("keeps the data order and the frame newlines intact", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ session.onData((chunk) => received.push(chunk));++ process.handle?.emitText('{"version":1,"type":"ready","address":"127.0.0.1:8080"}\n');+ process.handle?.emitText('{"version":1,"type":"heartbeat"}\n');++ // The order is preserved and no newline is translated (no stray "\r").+ expect(received).toEqual([+ '{"version":1,"type":"ready","address":"127.0.0.1:8080"}\n',+ '{"version":1,"type":"heartbeat"}\n',+ ]);+ expect(received.join("")).not.toContain("\r");+ });++ it("reassembles a frame split across two output chunks", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ session.onData((chunk) => received.push(chunk));++ const frame = '{"version":1,"type":"response","id":"r1","status":200,"headers":{},"body":"","outcome":"completed"}\n';+ process.handle?.emitText(frame.slice(0, 20));+ process.handle?.emitText(frame.slice(20));++ expect(received.join("")).toBe(frame);+ });++ it("carries a large frame without loss", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ session.onData((chunk) => received.push(chunk));++ const body = "x".repeat(500_000);+ const frame = `{"version":1,"type":"response","id":"big","status":200,"headers":{},"body":"${body}","outcome":"completed"}\n`;+ process.handle?.emitText(frame);++ expect(received.join("")).toBe(frame);+ expect(received.join("").length).toBe(frame.length);+ });++ it("keeps a multibyte character whole across two output chunks", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ session.onData((chunk) => received.push(chunk));++ // The euro sign is three UTF-8 bytes. Split it across two chunks, so the+ // stream decoder must join the bytes.+ const euro = new TextEncoder().encode("€");+ process.handle?.emitBytes(euro.subarray(0, 2));+ process.handle?.emitBytes(euro.subarray(2));++ expect(received.join("")).toBe("€");+ });++ it("buffers early output until the listener registers", async () => {+ const process = createFakeProcess();+ const received: string[] = [];++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ // Output arrives before the transport registers the listener.+ process.handle?.emitText('{"version":1,');+ process.handle?.emitText('"type":"heartbeat"}\n');+ expect(received).toEqual([]);++ session.onData((chunk) => received.push(chunk));+ // The session flushes the buffered output in order on registration.+ expect(received).toEqual(['{"version":1,"type":"heartbeat"}\n']);+ });++ it("resolves wait with the gateway exit code", async () => {+ const process = createFakeProcess();++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ process.handle?.finish(3);++ await expect(session.wait()).resolves.toEqual({ exitCode: 3 });+ });++ it("maps an absent exit code to null", async () => {+ const process = createFakeProcess();++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ process.handle?.finish(undefined);++ await expect(session.wait()).resolves.toEqual({ exitCode: null });+ });++ it("kills the child on stop and releases the socket on close", async () => {+ const process = createFakeProcess();++ const session = await openDaytonaDuplexChannelSession(process, GATEWAY);+ session.kill();+ expect(process.handle?.killed).toBe(1);++ await session.close();+ // Close stops the child and releases the socket, so a closed channel holds no+ // live terminal.+ expect(process.handle?.killed).toBeGreaterThanOrEqual(1);+ expect(process.handle?.disconnected).toBe(1);+ });++ it("passes the working directory to the pseudo-terminal", async () => {+ const process = createFakeProcess();++ await openDaytonaDuplexChannelSession(process, GATEWAY, { cwd: "/paperclip-workspace" });++ expect(process.createOptions?.cwd).toBe("/paperclip-workspace");+ });+});++describe("createDaytonaDuplexChannelSessionOpener", () => {+ it("opens a session for the command on each call", async () => {+ const process = createFakeProcess();+ const opener = createDaytonaDuplexChannelSessionOpener(process, { cwd: "/paperclip-workspace" });++ const session = await opener(GATEWAY);++ expect(process.createOptions?.cwd).toBe("/paperclip-workspace");+ expect(process.handle?.inputs[0]).toContain(`exec ${GATEWAY_QUOTED}`);+ expect(typeof session.onData).toBe("function");+ expect(typeof session.write).toBe("function");+ expect(typeof session.wait).toBe("function");+ expect(typeof session.kill).toBe("function");+ expect(typeof session.close).toBe("function");+ });+});diff --git a/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.ts b/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.tsnew file mode 100644index 0000000000..9651f65714--- /dev/null+++ b/packages/plugins/sandbox-providers/daytona/src/duplex-command-stream.ts@@ -0,0 +1,229 @@+// 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+// `setup-token-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 type {+ DaytonaPtyCreateOptions,+ DaytonaPtyHandle,+ DaytonaPtyProcess,+} from "./setup-token-pty.js";++export type {+ DaytonaPtyCreateOptions,+ DaytonaPtyHandle,+ DaytonaPtyProcess,+} from "./setup-token-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 chunk in order. */+ onData(listener: (chunk: string) => void): void;+ /** Writes raw input bytes to the pseudo-terminal. */+ write(data: string): void;+ /** Resolves with the child exit code when the command ends. */+ wait(): Promise<{ exitCode: number | null }>;+ /** 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 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 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: string): string {+ 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: readonly string[],+ diagnosticsPath: string,+): string {+ 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 decodes the terminal bytes as a UTF-8 stream, so a multibyte+ * character that splits across two output chunks stays whole. It buffers the+ * output until the transport registers the listener, so no early chunk is lost.+ */+export async function openDaytonaDuplexChannelSession(+ process: DaytonaPtyProcess,+ command: readonly string[],+ options?: DaytonaDuplexChannelOptions,+): Promise<DuplexChannelSession> {+ const decoder = new TextDecoder("utf-8");+ let listener: ((chunk: string) => void) | null = null;+ let buffered = "";++ 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: Uint8Array): void => {+ // Decode the terminal bytes as a stream, so a split multibyte character+ // stays whole across two chunks. Forward the raw text; the frame codec owns+ // the newline-delimited JSON parsing.+ const text = decoder.decode(data, { stream: true });+ if (text.length === 0) return;+ if (listener) listener(text);+ else buffered += text;+ },+ });++ 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));++ return {+ onData(next: (chunk: string) => void): void {+ listener = next;+ if (buffered.length > 0) {+ const pending = buffered;+ buffered = "";+ next(pending);+ }+ },+ write(data: string): void {+ // Fire the input write. A write error must not throw into the transport, so+ // the transport's stream stays the single result path.+ void handle.sendInput(data).catch(() => undefined);+ },+ async wait(): Promise<{ exitCode: number | null }> {+ const result = await handle.wait();+ return { exitCode: typeof result.exitCode === "number" ? result.exitCode : null };+ },+ kill(): void {+ void handle.kill().catch(() => undefined);+ },+ async close(): Promise<void> {+ // 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: DaytonaPtyProcess,+ options?: DaytonaDuplexChannelOptions,+): DuplexChannelSessionOpener {+ return (command: readonly string[]) =>+ openDaytonaDuplexChannelSession(process, command, options);+}diff --git a/packages/plugins/sandbox-providers/daytona/src/manifest.ts b/packages/plugins/sandbox-providers/daytona/src/manifest.tsindex 149d284a30..1dff4695e5 100644--- a/packages/plugins/sandbox-providers/daytona/src/manifest.ts+++ b/packages/plugins/sandbox-providers/daytona/src/manifest.ts@@ -10,7 +10,8 @@ const PLUGIN_ID = "paperclip.daytona-sandbox-provider";// 0.1.3 renamed the login transport flag from `supportsSetupTokenLogin` to the// neutral `supportsLoginPty`.// 0.1.4 adds the `concurrentSyncOperations` sandbox capability to the driver.-const PLUGIN_VERSION = "0.1.4";+// 0.1.5 adds the `duplexCommandStream` sandbox capability to the driver.+const PLUGIN_VERSION = "0.1.5";const manifest: PaperclipPluginManifestV1 = {id: PLUGIN_ID,@@ -44,9 +45,15 @@ const manifest: PaperclipPluginManifestV1 = {// waits for all active calls. Declare the opt-in capability so the host may// schedule sync operations concurrently. The host resolves it `true` only// when the worker also verifies both sync verbs.+ //+ // Daytona carries the sandbox callback bridge on one live duplex channel+ // over a raw pseudo-terminal. Declare the opt-in capability so the host may+ // select the duplex transport. The host resolves it `true` only when the+ // worker also verifies the `duplexChannelOpen` handler.sandboxCapabilities: {incrementalSessionOutput: true,concurrentSyncOperations: true,+ duplexCommandStream: true,},supportsInteractiveSetup: true,interactiveSetupConnectionTypes: ["ssh"],diff --git a/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts b/packages/plugins/sandbox-providers/daytona/src/plugin.test.tsindex 35021fac1f..1fb64271b8 100644--- a/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts+++ b/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts@@ -148,6 +148,139 @@ describe("Daytona sandbox provider plugin", () => {});});+ it("declares the duplex-command-stream capability and the four channel handlers", () => {+ // Daytona carries the callback bridge on one duplex channel, so it declares+ // the opt-in capability. The host resolves it `true` only when the worker also+ // verifies the `duplexChannelOpen` handler, which the four handlers provide.+ expect(manifest.environmentDrivers?.[0]?.sandboxCapabilities).toMatchObject({+ duplexCommandStream: true,+ });+ expect(plugin.definition.onDuplexChannelOpen).toBeTypeOf("function");+ expect(plugin.definition.onDuplexChannelWrite).toBeTypeOf("function");+ expect(plugin.definition.onDuplexChannelStop).toBeTypeOf("function");+ expect(plugin.definition.onDuplexChannelClose).toBeTypeOf("function");+ });++ it("bumps the plugin version so the server reconciles the stored manifest", () => {+ // The bundled-plugin boot reconcile refreshes the stored manifest for an+ // existing install only when the version changes. The duplex capability needs+ // the bump to reach an existing install.+ expect(manifest.version).toBe("0.1.5");+ });++ it("opens a duplex channel, forwards a host write, and closes it on lease release", async () => {+ process.env.DAYTONA_API_KEY = "host-key";+ // A fake PTY handle records each host write, drives the data stream on demand,+ // and records the kill and the disconnect.+ const inputs: string[] = [];+ let killed = 0;+ let disconnected = 0;+ let ptyOnData: ((data: Uint8Array) => void) | null = null;+ const handle = {+ async waitForConnection() {},+ async sendInput(data: string | Uint8Array) {+ inputs.push(typeof data === "string" ? data : new TextDecoder().decode(data));+ },+ wait() {+ return new Promise<{ exitCode?: number }>(() => {});+ },+ async kill() {+ killed += 1;+ },+ async disconnect() {+ disconnected += 1;+ },+ };+ const sandbox = createMockSandbox();+ (sandbox.process as Record<string, unknown>).createPty = vi.fn(+ async (options: { onData: (data: Uint8Array) => void }) => {+ ptyOnData = options.onData;+ return handle;+ },+ );+ mockCreate.mockResolvedValue(sandbox);++ // Capture the data and the exit the worker forwards through `ctx.duplexChannel`.+ const dataChunks: Array<{ workerSessionId: string; chunk: string }> = [];+ const restore = __setDaytonaPluginContextForTest({+ duplexChannel: {+ data: (workerSessionId: string, chunk: string) =>+ dataChunks.push({ workerSessionId, chunk }),+ exit: () => {},+ },+ } as unknown as PluginContext);++ try {+ await plugin.definition.onEnvironmentAcquireLease?.({+ driverKey: "daytona",+ companyId: "company-1",+ environmentId: "env-1",+ runId: "run-1",+ agentId: "agent-1",+ executionWorkspaceId: "workspace-1",+ adapterType: "codex_local",+ config: { image: "node:20", timeoutMs: 300000, reuseLease: true },+ });++ const open = await plugin.definition.onDuplexChannelOpen?.({+ hostRouteId: "route-1",+ driverKey: "daytona",+ companyId: "company-1",+ environmentId: "env-1",+ providerLeaseId: "sandbox-123",+ command: ["node", "/paperclip/gateway.mjs"],+ });+ expect(open?.workerSessionId).toMatch(/^duplex-/);+ const workerSessionId = open?.workerSessionId ?? "";++ // The launch wrapper sets raw mode with echo off and redirects diagnostics.+ // It quotes each command argument and the diagnostics path as a shell word.+ expect(inputs[0]).toContain("stty raw -echo");+ expect(inputs[0]).toContain("exec 'node' '/paperclip/gateway.mjs'");+ expect(inputs[0]).toMatch(/2>'\/tmp\/paperclip-duplex-.+\.log'/);++ // A host write reaches the process on the same channel.+ await plugin.definition.onDuplexChannelWrite?.({+ workerSessionId,+ data: '{"version":1,"type":"heartbeat"}\n',+ });+ expect(inputs[1]).toBe('{"version":1,"type":"heartbeat"}\n');++ // Process output reaches the host as a data notification bound to the+ // worker session id.+ ptyOnData?.(new TextEncoder().encode('{"version":1,"type":"ready","address":"127.0.0.1:1"}\n'));+ expect(dataChunks).toEqual([+ {+ workerSessionId,+ chunk: '{"version":1,"type":"ready","address":"127.0.0.1:1"}\n',+ },+ ]);++ // Lease release closes the channel: it kills the child and releases the+ // pseudo-terminal socket.+ await plugin.definition.onEnvironmentReleaseLease?.({+ driverKey: "daytona",+ companyId: "company-1",+ environmentId: "env-1",+ providerLeaseId: "sandbox-123",+ config: { image: "node:20", timeoutMs: 300000, reuseLease: true },+ });+ expect(killed).toBeGreaterThanOrEqual(1);+ expect(disconnected).toBe(1);++ // The channel entry is gone, so a later write is a no-op and reaches no+ // process.+ const inputsBefore = inputs.length;+ await plugin.definition.onDuplexChannelWrite?.({+ workerSessionId,+ data: "late\n",+ });+ expect(inputs.length).toBe(inputsBefore);+ } finally {+ restore();+ }+ });+it("normalizes config and validates the API key fallback", async () => {process.env.DAYTONA_API_KEY = "host-key";diff --git a/packages/plugins/sandbox-providers/daytona/src/plugin.ts b/packages/plugins/sandbox-providers/daytona/src/plugin.tsindex 2416b17fcd..684ec2b816 100644--- a/packages/plugins/sandbox-providers/daytona/src/plugin.ts+++ b/packages/plugins/sandbox-providers/daytona/src/plugin.ts@@ -66,6 +66,24 @@ import type {DaytonaPtyProcess,} from "./setup-token-pty.js";+// The Daytona duplex command stream for the sandbox callback bridge. The channel+// runs the gateway command on a raw pseudo-terminal, streams the frames, and+// accepts host input. The worker resolves the sandbox by the provider lease id,+// registers the channel under the host route id, and streams the data and the+// exit through `ctx.duplexChannel`.+export {+ createDaytonaDuplexChannelSessionOpener,+ openDaytonaDuplexChannelSession,+ buildDuplexChannelLaunchWrapper,+} from "./duplex-command-stream.js";+export type {+ DuplexChannelSession,+ DuplexChannelSessionOpener,+ DaytonaDuplexChannelOptions,+} from "./duplex-command-stream.js";+import { openDaytonaDuplexChannelSession as openDuplexChannelSession } from "./duplex-command-stream.js";+import type { DuplexChannelSession } from "./duplex-command-stream.js";+// Injectable monotonic clock for provider-boundary timing (Open Q1). Defaults// to the real wall clock; `plugin.test.ts` overrides it via// `setDaytonaTimingClockForTest` so the measured `durationMs`/`getDurationMs`@@ -1899,6 +1917,41 @@ function forgetDaytonaSetupTokenPty(entry: DaytonaSetupTokenPtyEntry): void {daytonaSetupTokenPtyBySession.delete(entry.workerSessionId);}+// The worker-side registry of live duplex channels. The worker registers each+// channel under the host-owned route identifier at open time, so the host closes+// the exact channel by that identifier even when the open reply was lost. It also+// indexes by the worker session identifier for write and stop. Each entry records+// the provider lease id, so a lease teardown closes only its own channels. The+// `onShutdown` hook closes every open channel here.+interface DaytonaDuplexChannelEntry {+ hostRouteId: string;+ workerSessionId: string;+ providerLeaseId: string;+ session: DuplexChannelSession;+}+const daytonaDuplexChannelByRoute = new Map<string, DaytonaDuplexChannelEntry>();+const daytonaDuplexChannelBySession = new Map<string, DaytonaDuplexChannelEntry>();++function forgetDaytonaDuplexChannel(entry: DaytonaDuplexChannelEntry): void {+ daytonaDuplexChannelByRoute.delete(entry.hostRouteId);+ daytonaDuplexChannelBySession.delete(entry.workerSessionId);+}++// Close every open duplex channel that belongs to one provider lease and drop its+// entry. The lease teardown hooks (release, destroy, resume) call this, so a+// channel never outlives the sandbox that carries it. The close kills the child+// and releases the pseudo-terminal socket, so no live channel survives the+// teardown. The stored identifiers are always cleared, so no orphan id survives.+async function closeDaytonaDuplexChannelsForLease(providerLeaseId: string): Promise<void> {+ const matches = [...daytonaDuplexChannelByRoute.values()].filter(+ (entry) => entry.providerLeaseId === providerLeaseId,+ );+ for (const entry of matches) {+ forgetDaytonaDuplexChannel(entry);+ await entry.session.close().catch(() => undefined);+ }+}+const plugin = definePlugin({async setup(ctx) {// Hoist the context to a module variable so the lifecycle hooks and the@@ -2106,6 +2159,10 @@ const plugin = definePlugin({// session and leak its shell until sandbox reaping.if (sandbox.state !== "started") {sandboxHandleSessionStore.clear(scope);+ // A stopped sandbox loses its pseudo-terminals, so a stored duplex channel+ // is dead after a real restart. Close and drop every channel on this lease+ // before the restart, so no stale channel id survives the resume.+ await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);}await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));try {@@ -2170,6 +2227,9 @@ const plugin = definePlugin({evictSandboxHandle(scope);await sandboxHandleActivityGates.waitForIdle(scope);await teardownSession(sandbox, scope);+ // Close every duplex channel on this lease before the stop or the delete,+ // so no channel outlives the sandbox and no stored channel id survives.+ await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);if (config.reuseLease) {if (sandbox.state !== "stopped") {@@ -2234,6 +2294,9 @@ const plugin = definePlugin({evictSandboxHandle(scope);await sandboxHandleActivityGates.waitForIdle(scope);await teardownSession(sandbox, scope);+ // Close every duplex channel on this lease before the delete, so no channel+ // outlives the sandbox and no stored channel id survives.+ await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);await sandbox.delete(toTimeoutSeconds(config.timeoutMs));} finally {sandboxHandleTeardownGates.end(scope, teardownGate);@@ -2734,8 +2797,76 @@ const plugin = definePlugin({return { hostRouteId: params.hostRouteId };},- // Close every open login pseudo-terminal on an orderly shutdown, then drain the- // sandbox handle cache, so a graceful shutdown holds no live login terminal.+ // Open one persistent duplex channel. Resolve the cached sandbox by the provider+ // lease id, run the gateway command on a raw pseudo-terminal, and register the+ // channel under the host route id. Stream the raw data and the exit through+ // `ctx.duplexChannel`, bound to the returned worker session id. Fail closed when+ // no cached sandbox matches the lease.+ async onDuplexChannelOpen(params) {+ const sandbox = await sandboxHandleCache.findByProviderLeaseId(params.providerLeaseId);+ if (!sandbox) {+ throw new Error(+ "Daytona duplex channel: no cached sandbox resolves the provider lease.",+ );+ }+ const session = await openDuplexChannelSession(+ sandbox.process as unknown as DaytonaPtyProcess,+ params.command,+ );+ const workerSessionId = `duplex-${randomUUID()}`;+ const entry: DaytonaDuplexChannelEntry = {+ hostRouteId: params.hostRouteId,+ workerSessionId,+ providerLeaseId: params.providerLeaseId,+ session,+ };+ daytonaDuplexChannelByRoute.set(params.hostRouteId, entry);+ daytonaDuplexChannelBySession.set(workerSessionId, entry);+ // Register the data listener before the first write, so no early data chunk is+ // lost. The client stamps the worker session id, so the host binds the data to+ // the open route.+ session.onData((chunk) => {+ pluginContext?.duplexChannel.data(workerSessionId, chunk);+ });+ // Forward the child exit one time. The host resolves the open route on it.+ void session.wait().then(+ (result) => pluginContext?.duplexChannel.exit(workerSessionId, result.exitCode),+ () => pluginContext?.duplexChannel.exit(workerSessionId, null),+ );+ return { workerSessionId };+ },++ // Write host input to an open duplex channel, keyed by the worker session id.+ // Drop the input for an unknown session.+ async onDuplexChannelWrite(params) {+ const entry = daytonaDuplexChannelBySession.get(params.workerSessionId);+ if (!entry) return;+ entry.session.write(params.data);+ },++ // Stop an open duplex channel child, keyed by the worker session id.+ async onDuplexChannelStop(params) {+ const entry = daytonaDuplexChannelBySession.get(params.workerSessionId);+ if (!entry) return;+ entry.session.kill();+ },++ // Close an open duplex channel by the host route id and acknowledge the close+ // with the same identifier. The close is idempotent: it returns the+ // acknowledgement even when the entry is already gone, so the host confirms the+ // channel is closed. The worker never keys the close on the worker session id.+ async onDuplexChannelClose(params) {+ const entry = daytonaDuplexChannelByRoute.get(params.hostRouteId);+ if (entry) {+ forgetDaytonaDuplexChannel(entry);+ await entry.session.close().catch(() => undefined);+ }+ return { hostRouteId: params.hostRouteId };+ },++ // Close every open login pseudo-terminal and every open duplex channel on an+ // orderly shutdown, then drain the sandbox handle cache, so a graceful shutdown+ // holds no live terminal and no live channel.async onShutdown() {const openSessions = [...daytonaSetupTokenPtyByRoute.values()];daytonaSetupTokenPtyByRoute.clear();@@ -2743,6 +2874,12 @@ const plugin = definePlugin({for (const entry of openSessions) {await entry.session.close().catch(() => undefined);}+ const openChannels = [...daytonaDuplexChannelByRoute.values()];+ daytonaDuplexChannelByRoute.clear();+ daytonaDuplexChannelBySession.clear();+ for (const entry of openChannels) {+ await entry.session.close().catch(() => undefined);+ }sandboxHandleCache.reset();},});diff --git a/packages/plugins/sdk/src/protocol.duplex-channel.test.ts b/packages/plugins/sdk/src/protocol.duplex-channel.test.tsindex 306d7646c5..b9fb2529d4 100644--- a/packages/plugins/sdk/src/protocol.duplex-channel.test.ts+++ b/packages/plugins/sdk/src/protocol.duplex-channel.test.ts@@ -33,7 +33,7 @@ describe("duplex channel request schemas", () => {companyId: "company-1",environmentId: "env-1",providerLeaseId: "lease-1",- command: "paperclip-bridge",+ command: ["paperclip-bridge"],};const reply: PluginDuplexChannelOpenResult = { workerSessionId: "ws-1" };expect(open.hostRouteId).toBe("route-1");@@ -47,20 +47,20 @@ describe("duplex channel request schemas", () => {companyId: "company-1",environmentId: "env-1",providerLeaseId: "lease-1",- command: "paperclip-bridge",+ command: ["paperclip-bridge"],};expect(open).toBeDefined();});- it("rejects an open request with a non-string command", () => {+ it("rejects an open request whose command is not a string array", () => {const open: PluginDuplexChannelOpenParams = {hostRouteId: "route-1",driverKey: "daytona",companyId: "company-1",environmentId: "env-1",providerLeaseId: "lease-1",- // @ts-expect-error — command must be a string.- command: 42,+ // @ts-expect-error — command must be a string array.+ command: "paperclip-bridge",};expect(open).toBeDefined();});diff --git a/packages/plugins/sdk/src/protocol.ts b/packages/plugins/sdk/src/protocol.tsindex 72585f7324..f81c2bd0dc 100644--- a/packages/plugins/sdk/src/protocol.ts+++ b/packages/plugins/sdk/src/protocol.ts@@ -1111,8 +1111,12 @@ export interface PluginDuplexChannelOpenParams {environmentId: string;/** The provider lease the sandbox is cached under. The worker resolves the sandbox by it. */providerLeaseId: string;- /** The command the worker runs on the channel. */- command: string;+ /**+ * The command argument vector the worker runs on the channel. Element 0 is the+ * program and the rest are its arguments. The worker quotes each element for the+ * shell, so a shell metacharacter in an element cannot inject a shell command.+ */+ command: readonly string[];}/** The open reply. It returns the worker session identifier for data binding only. */diff --git a/packages/plugins/sdk/src/testing.ts b/packages/plugins/sdk/src/testing.tsindex cf0c05b919..43ce72f658 100644--- a/packages/plugins/sdk/src/testing.ts+++ b/packages/plugins/sdk/src/testing.ts@@ -2486,6 +2486,14 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {// No-op in test harness — the host login route is not wired here.},},+ duplexChannel: {+ data(_workerSessionId: string, _chunk: string) {+ // No-op in test harness — the host duplex route is not wired here.+ },+ exit(_workerSessionId: string, _exitCode: number | null) {+ // No-op in test harness — the host duplex route is not wired here.+ },+ },tools: {register(name, _decl, fn) {requireCapability(manifest, capabilitySet, "agent.tools.register");diff --git a/packages/plugins/sdk/src/types.ts b/packages/plugins/sdk/src/types.tsindex 455e70592f..6eda319ba5 100644--- a/packages/plugins/sdk/src/types.ts+++ b/packages/plugins/sdk/src/types.ts@@ -2037,6 +2037,36 @@ export interface PluginSetupTokenPtyClient {exit(workerSessionId: string, exitCode: number | null): void;}+/**+ * `ctx.duplexChannel` — stream one persistent duplex channel's data and exit from+ * a sandbox provider worker to the host.+ *+ * The worker registers the data listener on the channel and forwards each raw+ * chunk through `data(workerSessionId, chunk)`. It forwards the child exit through+ * `exit(workerSessionId, exitCode)`. Each call carries the worker session+ * identifier the open reply returned, so the host binds the data to the open route+ * by that identifier while the route is open. The host drops a chunk or an exit+ * that carries an unknown or a mismatched identifier, and it never logs the raw+ * bytes. The default is a no-op that never throws. This client models the+ * `setupTokenPty` client, but it carries no login command allowlist.+ */+export interface PluginDuplexChannelClient {+ /**+ * Deliver one raw data chunk of a persistent duplex channel.+ *+ * @param workerSessionId - The worker session identifier the open reply returned.+ * @param chunk - The raw channel output text.+ */+ data(workerSessionId: string, chunk: string): void;+ /**+ * Deliver the child exit of a persistent duplex channel.+ *+ * @param workerSessionId - The worker session identifier the open reply returned.+ * @param exitCode - The child exit code, or null when the child ended with no code.+ */+ exit(workerSessionId: string, exitCode: number | null): void;+}+// ---------------------------------------------------------------------------// Full plugin context// ---------------------------------------------------------------------------@@ -2157,6 +2187,10 @@ export interface PluginContext {* pseudo-terminal. */setupTokenPty: PluginSetupTokenPtyClient;+ /** Stream one persistent duplex channel's data and exit to the host. The+ * default is a no-op for a provider that opens no duplex channel. */+ duplexChannel: PluginDuplexChannelClient;+/** Register agent tool handlers. Requires `agent.tools.register`. */tools: PluginToolsClient;diff --git a/packages/plugins/sdk/src/worker-rpc-host.ts b/packages/plugins/sdk/src/worker-rpc-host.tsindex c7cadbc5e9..4c00884e11 100644--- a/packages/plugins/sdk/src/worker-rpc-host.ts+++ b/packages/plugins/sdk/src/worker-rpc-host.ts@@ -115,6 +115,8 @@ import type {import {SETUP_TOKEN_PTY_OUTPUT_NOTIFICATION,SETUP_TOKEN_PTY_EXIT_NOTIFICATION,+ DUPLEX_CHANNEL_DATA_NOTIFICATION,+ DUPLEX_CHANNEL_EXIT_NOTIFICATION,JSONRPC_VERSION,JSONRPC_ERROR_CODES,PLUGIN_RPC_ERROR_CODES,@@ -1400,6 +1402,30 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost},},+ duplexChannel: {+ data(workerSessionId: string, chunk: string): void {+ // Forward one raw data chunk of a persistent duplex channel. The+ // notification carries the worker session identifier, so the host binds+ // the chunk to the open route by that identifier while the route is+ // open. The host drops an unknown or a mismatched identifier and never+ // logs the raw bytes. This notification carries no invocation id,+ // because it fires after the open reply returns.+ if (typeof workerSessionId !== "string" || workerSessionId.length === 0) return;+ if (typeof chunk !== "string" || chunk.length === 0) return;+ notifyHost(DUPLEX_CHANNEL_DATA_NOTIFICATION, { workerSessionId, chunk });+ },+ exit(workerSessionId: string, exitCode: number | null): void {+ // Forward the child exit of a persistent duplex channel. The host+ // resolves the open route's wait promise by the worker session+ // identifier while the route is open.+ if (typeof workerSessionId !== "string" || workerSessionId.length === 0) return;+ notifyHost(DUPLEX_CHANNEL_EXIT_NOTIFICATION, {+ workerSessionId,+ exitCode: typeof exitCode === "number" ? exitCode : null,+ });+ },+ },+tools: {register(name: string,diff --git a/packages/plugins/sdk/tests/worker-rpc-host.test.ts b/packages/plugins/sdk/tests/worker-rpc-host.test.tsindex 0b1f336c19..38c6e9b6b7 100644--- a/packages/plugins/sdk/tests/worker-rpc-host.test.ts+++ b/packages/plugins/sdk/tests/worker-rpc-host.test.ts@@ -925,7 +925,7 @@ describe("worker duplex channel dispatch", () => {async setup() {},async onDuplexChannelOpen(params) {expect(params.hostRouteId).toBe("route-1");- expect(params.command).toBe("paperclip-bridge");+ expect(params.command).toEqual(["paperclip-bridge"]);expect(params.providerLeaseId).toBe("lease-1");return { workerSessionId: "ws-1" };},@@ -1004,7 +1004,7 @@ describe("worker duplex channel dispatch", () => {companyId: "company-1",environmentId: "env-1",providerLeaseId: "lease-1",- command: "paperclip-bridge",+ command: ["paperclip-bridge"],}),).resolves.toEqual({ workerSessionId: "ws-1" });diff --git a/packages/shared/src/feature-catalog.ts b/packages/shared/src/feature-catalog.tsindex ef21ee914d..ef06ca8d37 100644--- a/packages/shared/src/feature-catalog.ts+++ b/packages/shared/src/feature-catalog.ts@@ -253,6 +253,14 @@ export const INSTANCE_FEATURE_CATALOG: Record<InstanceFeatureKey, FeatureCatalogcloudDefault: true,selfHostedDefault: false,},+ enableSandboxDuplexBridge: {+ title: "Sandbox Duplex Bridge",+ description:+ "Let a run open the sandbox duplex command-stream bridge when the provider grants the capability. The host reads this per run before it selects the transport. Off keeps the file bridge for every run.",+ tier: "managed",+ cloudDefault: false,+ selfHostedDefault: false,+ },enableWorktreeRunExecution: {title: "Worktree Run Execution",description:diff --git a/packages/shared/src/types/instance.ts b/packages/shared/src/types/instance.tsindex 0d69369d60..cfb296dd73 100644--- a/packages/shared/src/types/instance.ts+++ b/packages/shared/src/types/instance.ts@@ -89,6 +89,13 @@ export interface InstanceExperimentalSettings {* instances, which have no trusted cloud tenant path.*/enableOwnerInstanceAdmin: boolean;+ /**+ * Kill switch for the sandbox duplex command-stream bridge. Default off. The+ * host reads this per run before it selects the callback bridge transport.+ * Off forces the file bridge for every run with no manifest change and no+ * redeploy.+ */+ enableSandboxDuplexBridge: boolean;/*** Worktree preview instances (`PAPERCLIP_IN_WORKTREE=true`) suppress the* heartbeat run engine by default so previews never self-execute tasks. Whendiff --git a/packages/shared/src/validators/instance.test.ts b/packages/shared/src/validators/instance.test.tsindex ae7ab4cbe3..e2a518e99f 100644--- a/packages/shared/src/validators/instance.test.ts+++ b/packages/shared/src/validators/instance.test.ts@@ -24,6 +24,29 @@ describe("instance experimental settings validators", () => {expect(settings.enableGoalsSidebarLink).toBe(false);});+ it("defaults the sandbox duplex bridge kill switch off", () => {+ const settings = instanceExperimentalSettingsSchema.parse({});++ expect(settings.enableSandboxDuplexBridge).toBe(false);+ });++ it("accepts an explicit sandbox duplex bridge kill switch value", () => {+ expect(+ instanceExperimentalSettingsSchema.parse({ enableSandboxDuplexBridge: true })+ .enableSandboxDuplexBridge,+ ).toBe(true);+ expect(+ instanceExperimentalSettingsSchema.parse({ enableSandboxDuplexBridge: false })+ .enableSandboxDuplexBridge,+ ).toBe(false);+ });++ it("accepts the sandbox duplex bridge kill switch in a patch", () => {+ expect(+ patchInstanceExperimentalSettingsSchema.parse({ enableSandboxDuplexBridge: true }),+ ).toEqual({ enableSandboxDuplexBridge: true });+ });+it("defaults worktree run execution off", () => {const settings = instanceExperimentalSettingsSchema.parse({});diff --git a/packages/shared/src/validators/instance.ts b/packages/shared/src/validators/instance.tsindex 4af496897b..0ae769f8f8 100644--- a/packages/shared/src/validators/instance.ts+++ b/packages/shared/src/validators/instance.ts@@ -66,6 +66,10 @@ export const instanceExperimentalSettingsSchema = z.object({enableWorkspaceBranchReconcileForward: z.boolean().default(true),enableWorkspaceDirtyQuarantineRepair: z.boolean().default(true),enableOwnerInstanceAdmin: z.boolean().default(false),+ // Kill switch for the sandbox duplex command-stream bridge. Default off. When+ // off the host keeps the file bridge for every run with no manifest change and+ // no redeploy. The host reads this per run before it selects the transport.+ enableSandboxDuplexBridge: z.boolean().default(false),enableWorktreeRunExecution: z.boolean().default(false),worktreeRunExecutionActivatedAt: z.string().datetime().nullable().default(null),worktreeRunExecutionActivationInstanceId: z.string().min(1).nullable().default(null),diff --git a/server/src/__tests__/environment-runtime-duplex-bridge-input.test.ts b/server/src/__tests__/environment-runtime-duplex-bridge-input.test.tsnew file mode 100644index 0000000000..640a59a458--- /dev/null+++ b/server/src/__tests__/environment-runtime-duplex-bridge-input.test.ts@@ -0,0 +1,69 @@+import { beforeAll, describe, expect, it } from "vitest";+import { createDb } from "@paperclipai/db";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.js";+import {+ environmentRuntimeService,+ resolveSandboxDuplexBridgeInput,+} from "../services/environment-runtime.ts";+import { instanceSettingsService } from "../services/instance-settings.ts";++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres duplex bridge input tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}++describe("resolveSandboxDuplexBridgeInput", () => {+ it("carries an enabled kill switch into the bridge input", () => {+ expect(resolveSandboxDuplexBridgeInput({ enableSandboxDuplexBridge: true })).toEqual({+ enableDuplexBridge: true,+ });+ });++ it("keeps the file bridge when the kill switch is off", () => {+ expect(resolveSandboxDuplexBridgeInput({ enableSandboxDuplexBridge: false })).toEqual({+ enableDuplexBridge: false,+ });+ });+});++describeEmbeddedPostgres("environmentRuntimeService.readSandboxDuplexBridgeInput", () => {+ let stopDb: (() => Promise<void>) | null = null;+ let db!: ReturnType<typeof createDb>;+ let runtime!: ReturnType<typeof environmentRuntimeService>;+ let settings!: ReturnType<typeof instanceSettingsService>;++ beforeAll(async () => {+ const started = await startEmbeddedPostgresTestDatabase("environment-runtime-duplex-bridge");+ stopDb = started.stop;+ db = createDb(started.connectionString);+ runtime = environmentRuntimeService(db);+ settings = instanceSettingsService(db);+ return async () => {+ await stopDb?.();+ };+ });++ it("defaults the per-run bridge input to the file bridge", async () => {+ expect(await runtime.readSandboxDuplexBridgeInput()).toEqual({ enableDuplexBridge: false });+ });++ it("reads the enabled kill switch from instance settings for a run", async () => {+ await settings.updateExperimental({ enableSandboxDuplexBridge: true });++ expect(await runtime.readSandboxDuplexBridgeInput()).toEqual({ enableDuplexBridge: true });+ });++ it("returns to the file bridge when the kill switch is turned back off", async () => {+ await settings.updateExperimental({ enableSandboxDuplexBridge: true });+ await settings.updateExperimental({ enableSandboxDuplexBridge: false });++ expect(await runtime.readSandboxDuplexBridgeInput()).toEqual({ enableDuplexBridge: false });+ });+});diff --git a/server/src/__tests__/instance-settings-service.test.ts b/server/src/__tests__/instance-settings-service.test.tsindex 4c5627f417..d55a2064d3 100644--- a/server/src/__tests__/instance-settings-service.test.ts+++ b/server/src/__tests__/instance-settings-service.test.ts@@ -52,6 +52,7 @@ describe("instance settings service", () => {enableWorkspaceBranchReconcileForward: true,enableWorkspaceDirtyQuarantineRepair: false,enableOwnerInstanceAdmin: false,+ enableSandboxDuplexBridge: false,enableWorktreeRunExecution: false,worktreeRunExecutionActivatedAt: null,worktreeRunExecutionActivationInstanceId: null,diff --git a/server/src/services/environment-runtime.ts b/server/src/services/environment-runtime.tsindex 9588740e03..6cf5cf33f2 100644--- a/server/src/services/environment-runtime.ts+++ b/server/src/services/environment-runtime.ts@@ -7,6 +7,7 @@ import type {EnvironmentLease,EnvironmentLeaseStatus,ExecutionWorkspace,+ InstanceExperimentalSettings,IssueExecutionWorkspaceSettings,PluginEnvironmentConfig,SandboxEnvironmentConfig,@@ -32,6 +33,7 @@ import {type StartupSpanContext,} from "@paperclipai/adapter-utils/acpx-engine/startup-timing";import { environmentService } from "./environments.js";+import { instanceSettingsService } from "./instance-settings.js";import {collectEnvironmentSecretRefs,parseEnvironmentDriverConfig,@@ -321,6 +323,29 @@ export function buildEnvironmentLeaseContext(input: {};}+/**+ * The per-run duplex bridge input. The host resolves it for each new run before+ * it selects the sandbox callback bridge transport. When `enableDuplexBridge` is+ * false the host keeps the file bridge with no manifest change and no redeploy.+ * The transport selection reads this input in a later phase; this phase only+ * delivers the setting and the per-run read.+ */+export interface ResolvedSandboxDuplexBridgeInput {+ /** True only when the instance opts in to the sandbox duplex command stream. */+ enableDuplexBridge: boolean;+}++/**+ * Map the experimental instance setting `enableSandboxDuplexBridge` into the+ * per-run duplex bridge input. The setting is the kill switch. It defaults off,+ * so an absent or false setting keeps the file bridge.+ */+export function resolveSandboxDuplexBridgeInput(+ experimental: Pick<InstanceExperimentalSettings, "enableSandboxDuplexBridge">,+): ResolvedSandboxDuplexBridgeInput {+ return { enableDuplexBridge: experimental.enableSandboxDuplexBridge === true };+}+function stripSecretRefValuesFromPluginLeaseMetadata(input: {metadata: Record<string, unknown> | null | undefined;schema: Record<string, unknown> | null | undefined;@@ -498,8 +523,12 @@ export interface EnvironmentDriverSyncInput extends EnvironmentDriverLeaseInput}export interface EnvironmentDriverOpenDuplexChannelInput extends EnvironmentDriverLeaseInput {- /** The command line the sandbox runs as the duplex channel child process. */- command: string;+ /**+ * The command argument vector the sandbox runs as the duplex channel child+ * process. Element 0 is the program. The worker runs the vector with no+ * shell, so a shell metacharacter in an element cannot inject a command.+ */+ command: readonly string[];}export interface EnvironmentRuntimeDriver {@@ -3138,6 +3167,17 @@ export function environmentRuntimeService(return {getDriver,+ /**+ * Read the sandbox duplex bridge kill switch for a new run. The host calls it+ * per run before it selects the callback bridge transport. It reads the+ * experimental instance setting `enableSandboxDuplexBridge` and maps it into+ * the resolved bridge input. The default-off setting keeps the file bridge.+ */+ async readSandboxDuplexBridgeInput(): Promise<ResolvedSandboxDuplexBridgeInput> {+ const experimental = await instanceSettingsService(db).getExperimental();+ return resolveSandboxDuplexBridgeInput(experimental);+ },+async acquireRunLease(input: {companyId: string;environment: Environment;diff --git a/server/src/services/instance-settings.ts b/server/src/services/instance-settings.tsindex 32e2c125ed..473b12313b 100644--- a/server/src/services/instance-settings.ts+++ b/server/src/services/instance-settings.ts@@ -245,6 +245,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimentaenableWorkspaceBranchReconcileForward: parsed.data.enableWorkspaceBranchReconcileForward ?? true,enableWorkspaceDirtyQuarantineRepair: parsed.data.enableWorkspaceDirtyQuarantineRepair ?? true,enableOwnerInstanceAdmin: parsed.data.enableOwnerInstanceAdmin ?? false,+ enableSandboxDuplexBridge: parsed.data.enableSandboxDuplexBridge ?? false,enableWorktreeRunExecution: parsed.data.enableWorktreeRunExecution ?? false,worktreeRunExecutionActivatedAt: parsed.data.worktreeRunExecutionActivatedAt ?? null,worktreeRunExecutionActivationInstanceId:@@ -282,6 +283,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimentaenableWorkspaceBranchReconcileForward: true,enableWorkspaceDirtyQuarantineRepair: true,enableOwnerInstanceAdmin: false,+ enableSandboxDuplexBridge: false,enableWorktreeRunExecution: false,worktreeRunExecutionActivatedAt: null,worktreeRunExecutionActivationInstanceId: null,diff --git a/server/src/services/plugin-worker-manager.ts b/server/src/services/plugin-worker-manager.tsindex 8c54cdbeb2..3412290cb2 100644--- a/server/src/services/plugin-worker-manager.ts+++ b/server/src/services/plugin-worker-manager.ts@@ -490,7 +490,12 @@ export interface DuplexChannelOpenInput {companyId: string;environmentId: string;providerLeaseId: string;- command: string;+ /**+ * The command argument vector the worker runs on the channel. Element 0 is the+ * program. The worker runs the vector with no shell, so a shell metacharacter+ * in an element cannot inject a command.+ */+ command: readonly string[];}/**diff --git a/ui/src/pages/InstanceExperimentalSettings.test.tsx b/ui/src/pages/InstanceExperimentalSettings.test.tsxindex 25a717df60..87cdfef1c8 100644--- a/ui/src/pages/InstanceExperimentalSettings.test.tsx+++ b/ui/src/pages/InstanceExperimentalSettings.test.tsx@@ -99,6 +99,7 @@ function defaultExperimentalSettings(): InstanceExperimentalSettingsPayload {enableWorkspaceBranchReconcileForward: true,enableWorkspaceDirtyQuarantineRepair: true,enableOwnerInstanceAdmin: false,+ enableSandboxDuplexBridge: false,enableWorktreeRunExecution: false,worktreeRunExecutionActivatedAt: null,worktreeRunExecutionActivationInstanceId: null,