@penclipai/adapter-utils 2026.704.0 → 2026.714.0

package/dist/execution-target-sandbox.test.js

@@ -1,13 +1,20 @@
 import { createServer } from "node:http";
+import net from "node:net";
+import { execFile, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { promisify } from "node:util";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC, adapterExecutionTargetSessionIdentity, adapterExecutionTargetToRemoteSpec, adapterExecutionTargetUsesPaperclipBridge, ensureAdapterExecutionTargetCommandResolvable, resolveAdapterExecutionTargetTimeoutSec, runAdapterExecutionTargetProcess, runAdapterExecutionTargetShellCommand, startAdapterExecutionTargetPaperclipBridge, } from "./execution-target.js";
+import { DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC, adapterExecutionTargetSessionIdentity, adapterExecutionTargetToRemoteSpec, adapterExecutionTargetUsesPaperclipBridge, ensureAdapterExecutionTargetCommandResolvable, formatAdapterExecutionTimeoutErrorMessage, formatAdapterExecutionTimeoutStartLogLine, resolveAdapterExecutionTargetTimeout, resolveAdapterExecutionTargetTimeoutSec, runAdapterExecutionTargetProcess, runAdapterExecutionTargetShellCommand, startAdapterExecutionTargetProcessSessionBridge, startAdapterExecutionTargetPaperclipBridge, } from "./execution-target.js";
 import { createSandboxRunLogTailFactory } from "./sandbox-run-log-stream.js";
 import { runChildProcess } from "./server-utils.js";
 import { shellQuote } from "./ssh.js";
+const execFileAsync = promisify(execFile);
+const PROCESS_SESSION_TEST_TIMEOUT_MS = process.platform === "win32" ? 45_000 : 5_000;
+const PROCESS_SESSION_PROXY_TIMEOUT_MS = process.platform === "win32" ? 30_000 : 5_000;
+const PROCESS_SESSION_LIVE_OUTPUT_TIMEOUT_MS = process.platform === "win32" ? 20_000 : 3_000;
 function resolveTestPosixShellCommand(command) {
     if (process.platform !== "win32")
         return command === "bash" ? "/bin/bash" : "sh";
@@ -107,8 +114,8 @@ describe("sandbox adapter execution targets", () => {
             "",
         ].join("\n");
     }
-    async function waitForCondition(predicate, message) {
-        const deadline = Date.now() + 1000;
+    async function waitForCondition(predicate, message, timeoutMs = 1000) {
+        const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             if (predicate())
                 return;
@@ -116,6 +123,60 @@ describe("sandbox adapter execution targets", () => {
         }
         throw new Error(message);
     }
+    function parseProcessSessionProxyCommand(command) {
+        if (process.platform !== "win32")
+            return { command, args: [], sourcePath: command };
+        const match = command.match(/^"([^"]+)"\s+"([^"]+)"$/);
+        if (!match)
+            throw new Error(`Unexpected Windows process session proxy command: ${command}`);
+        return { command: match[1], args: [match[2]], sourcePath: match[2] };
+    }
+    function spawnProcessSessionProxy(agentCommand) {
+        const parsed = parseProcessSessionProxyCommand(agentCommand);
+        return spawn(parsed.command, parsed.args, {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    }
+    function processSessionProxySourcePath(command) {
+        return parseProcessSessionProxyCommand(command).sourcePath;
+    }
+    async function waitForChildSpawn(child) {
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", reject);
+        });
+    }
+    async function runProxyWithInput(bridge, input) {
+        const child = spawnProcessSessionProxy(bridge.agentCommand);
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        await waitForChildSpawn(child);
+        await bridge.ready;
+        child.stdin.end(input);
+        const code = await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error(`Timed out waiting for process session proxy (stdout=${JSON.stringify(stdout)}, stderr=${JSON.stringify(stderr)}).`));
+            }, PROCESS_SESSION_PROXY_TIMEOUT_MS);
+            child.on("error", (error) => {
+                clearTimeout(timeout);
+                reject(error);
+            });
+            child.on("close", (exitCode) => {
+                clearTimeout(timeout);
+                resolve(exitCode);
+            });
+        });
+        return { stdout, stderr, code };
+    }
     function combinedStream(events, stream) {
         return events.filter((event) => event.stream === stream).map((event) => event.chunk).join("");
     }
@@ -167,6 +228,268 @@ describe("sandbox adapter execution targets", () => {
             remoteCwd: "/workspace",
         });
     });
+    it("bridges bidirectional sandbox process sessions through a local ACPX-spawnable proxy", async () => {
+        const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-"));
+        cleanupDirs.push(rootDir);
+        const childPath = path.join(rootDir, "fake-acp-child.mjs");
+        await writeFile(childPath, [
+            "process.stdin.on('data', (chunk) => {",
+            "  process.stdout.write('out:' + chunk.toString());",
+            "  process.stderr.write('err:' + chunk.toString());",
+            "});",
+        ].join("\n"), "utf8");
+        const target = {
+            kind: "remote",
+            transport: "sandbox",
+            providerKey: "local-test",
+            remoteCwd: rootDir,
+            timeoutMs: 30_000,
+            runner: createLocalSandboxRunner(),
+        };
+        const bridge = await startAdapterExecutionTargetProcessSessionBridge({
+            runId: "run-process-session",
+            target,
+            runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),
+            adapterKey: "acpx",
+            command: process.execPath,
+            args: [childPath],
+            cwd: rootDir,
+            env: {},
+            timeoutSec: 5,
+            onLog: async () => { },
+        });
+        expect(bridge).not.toBeNull();
+        try {
+            const result = await runProxyWithInput(bridge, "hello\n");
+            expect(result.code).toBe(0);
+            expect(result.stdout).toBe("out:hello\n");
+            expect(result.stderr).toBe("err:hello\n");
+        }
+        finally {
+            await bridge?.stop();
+        }
+    }, PROCESS_SESSION_TEST_TIMEOUT_MS);
+    it("buffers sandbox process session output until the local proxy connects", async () => {
+        const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-buffer-"));
+        cleanupDirs.push(rootDir);
+        const childPath = path.join(rootDir, "fast-acp-child.mjs");
+        await writeFile(childPath, [
+            "process.stdout.write('early-out\\n');",
+            "process.stderr.write('early-err\\n');",
+            "setTimeout(() => process.exit(0), 20);",
+        ].join("\n"), "utf8");
+        const target = {
+            kind: "remote",
+            transport: "sandbox",
+            providerKey: "local-test",
+            remoteCwd: rootDir,
+            timeoutMs: 30_000,
+            runner: createLocalSandboxRunner(),
+        };
+        const bridge = await startAdapterExecutionTargetProcessSessionBridge({
+            runId: "run-process-session-buffer",
+            target,
+            runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),
+            adapterKey: "acpx",
+            command: process.execPath,
+            args: [childPath],
+            cwd: rootDir,
+            env: {},
+            timeoutSec: 5,
+            onLog: async () => { },
+        });
+        expect(bridge).not.toBeNull();
+        try {
+            await new Promise((resolve) => setTimeout(resolve, 300));
+            const result = await runProxyWithInput(bridge, "");
+            expect(result.code).toBe(0);
+            expect(result.stdout).toBe("early-out\n");
+            expect(result.stderr).toBe("early-err\n");
+        }
+        finally {
+            await bridge?.stop();
+        }
+    }, PROCESS_SESSION_TEST_TIMEOUT_MS);
+    it("delivers full output when the sandbox child exits immediately after writing", async () => {
+        const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-fast-exit-"));
+        cleanupDirs.push(rootDir);
+        const childPath = path.join(rootDir, "instant-exit-acp-child.mjs");
+        await writeFile(childPath, [
+            "process.stdout.write('final-out\\n');",
+            "process.stderr.write('final-err\\n');",
+        ].join("\n"), "utf8");
+        const target = {
+            kind: "remote",
+            transport: "sandbox",
+            providerKey: "local-test",
+            remoteCwd: rootDir,
+            timeoutMs: 30_000,
+            runner: createLocalSandboxRunner(),
+        };
+        const bridge = await startAdapterExecutionTargetProcessSessionBridge({
+            runId: "run-process-session-fast-exit",
+            target,
+            runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),
+            adapterKey: "acpx",
+            command: process.execPath,
+            args: [childPath],
+            cwd: rootDir,
+            env: {},
+            timeoutSec: 5,
+            onLog: async () => { },
+        });
+        expect(bridge).not.toBeNull();
+        try {
+            const result = await runProxyWithInput(bridge, "");
+            expect(result.code).toBe(0);
+            expect(result.stdout).toBe("final-out\n");
+            expect(result.stderr).toBe("final-err\n");
+        }
+        finally {
+            await bridge?.stop();
+        }
+    }, PROCESS_SESSION_TEST_TIMEOUT_MS);
+    it("ignores unauthenticated connections to the process session bridge", async () => {
+        const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-auth-"));
+        cleanupDirs.push(rootDir);
+        const childPath = path.join(rootDir, "guarded-acp-child.mjs");
+        await writeFile(childPath, "process.stdout.write('guarded-out\\n');", "utf8");
+        const target = {
+            kind: "remote",
+            transport: "sandbox",
+            providerKey: "local-test",
+            remoteCwd: rootDir,
+            timeoutMs: 30_000,
+            runner: createLocalSandboxRunner(),
+        };
+        const bridge = await startAdapterExecutionTargetProcessSessionBridge({
+            runId: "run-process-session-auth",
+            target,
+            runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),
+            adapterKey: "acpx",
+            command: process.execPath,
+            args: [childPath],
+            cwd: rootDir,
+            env: {},
+            timeoutSec: 5,
+            onLog: async () => { },
+        });
+        expect(bridge).not.toBeNull();
+        let squatter = null;
+        try {
+            const proxySource = await readFile(processSessionProxySourcePath(bridge.agentCommand), "utf8");
+            const port = Number(/port: (\d+)/.exec(proxySource)?.[1] ?? Number.NaN);
+            expect(Number.isFinite(port)).toBe(true);
+            // An idle local connection must not claim the session or see buffered output.
+            const squatterSocket = net.createConnection({ host: "127.0.0.1", port });
+            squatter = squatterSocket;
+            let squatterReceived = "";
+            squatterSocket.setEncoding("utf8");
+            squatterSocket.on("data", (chunk) => {
+                squatterReceived += chunk;
+            });
+            squatterSocket.on("error", () => undefined);
+            await new Promise((resolve, reject) => {
+                squatterSocket.once("connect", () => resolve());
+                squatterSocket.once("error", reject);
+            });
+            // A peer presenting the wrong token is disconnected outright.
+            const badPeer = net.createConnection({ host: "127.0.0.1", port });
+            badPeer.on("error", () => undefined);
+            const badPeerClosed = new Promise((resolve) => badPeer.once("close", () => resolve()));
+            badPeer.once("connect", () => badPeer.write(`${JSON.stringify({ token: "wrong-token", type: "stdinEnd" })}\n`));
+            await badPeerClosed;
+            // The authenticated proxy still attaches and receives the buffered output.
+            const result = await runProxyWithInput(bridge, "");
+            expect(result.code).toBe(0);
+            expect(result.stdout).toBe("guarded-out\n");
+            expect(squatterReceived).toBe("");
+        }
+        finally {
+            squatter?.destroy();
+            await bridge?.stop();
+        }
+    }, PROCESS_SESSION_TEST_TIMEOUT_MS);
+    it("streams sandbox process session output before the remote child exits", async () => {
+        const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-stream-"));
+        cleanupDirs.push(rootDir);
+        const childPath = path.join(rootDir, "streaming-acp-child.mjs");
+        await writeFile(childPath, [
+            "process.stdin.setEncoding('utf8');",
+            "process.stdin.on('data', (chunk) => {",
+            "  if (chunk.includes('ping')) {",
+            "    process.stdout.write('delta:ping\\n');",
+            "    process.stderr.write('trace:ping\\n');",
+            "  }",
+            "  if (chunk.includes('finish')) process.exit(0);",
+            "});",
+            "process.stdin.resume();",
+        ].join("\n"), "utf8");
+        const target = {
+            kind: "remote",
+            transport: "sandbox",
+            providerKey: "local-test",
+            remoteCwd: rootDir,
+            timeoutMs: 30_000,
+            runner: createLocalSandboxRunner(),
+        };
+        const bridge = await startAdapterExecutionTargetProcessSessionBridge({
+            runId: "run-process-session-stream",
+            target,
+            runtimeRootDir: path.posix.join(rootDir, ".paperclip-runtime", "acpx"),
+            adapterKey: "acpx",
+            command: process.execPath,
+            args: [childPath],
+            cwd: rootDir,
+            env: {},
+            timeoutSec: 5,
+            onLog: async () => { },
+        });
+        expect(bridge).not.toBeNull();
+        const child = spawnProcessSessionProxy(bridge.agentCommand);
+        let stdout = "";
+        let stderr = "";
+        let exited = false;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        const exitPromise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error("Timed out waiting for streaming process session proxy."));
+            }, PROCESS_SESSION_PROXY_TIMEOUT_MS);
+            child.on("error", (error) => {
+                clearTimeout(timeout);
+                reject(error);
+            });
+            child.on("exit", (exitCode) => {
+                exited = true;
+                clearTimeout(timeout);
+                resolve(exitCode);
+            });
+        });
+        try {
+            await waitForChildSpawn(child);
+            await bridge.ready;
+            child.stdin.write("ping\n");
+            await waitForCondition(() => stdout.includes("delta:ping\n") && stderr.includes("trace:ping\n"), "Timed out waiting for live process session output.", PROCESS_SESSION_LIVE_OUTPUT_TIMEOUT_MS);
+            expect(exited).toBe(false);
+            child.stdin.end("finish\n");
+            await expect(exitPromise).resolves.toBe(0);
+        }
+        finally {
+            if (!exited) {
+                child.kill("SIGKILL");
+                await exitPromise.catch(() => undefined);
+            }
+            await bridge?.stop();
+        }
+    }, PROCESS_SESSION_TEST_TIMEOUT_MS);
     it("applies the remote sandbox fallback when adapter timeoutSec is unset", () => {
         const sandboxTarget = {
             kind: "remote",
@@ -174,6 +497,10 @@ describe("sandbox adapter execution targets", () => {
             remoteCwd: "/workspace",
             runner: createLocalSandboxRunner(),
         };
+        // The sandbox default is a 4h wall-clock backstop matching the recovery
+        // watchdog critical threshold (ACTIVE_RUN_OUTPUT_CRITICAL_THRESHOLD_MS);
+        // the output-inactivity monitor remains the primary hang detector.
+        expect(DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC).toBe(4 * 60 * 60);
         expect(resolveAdapterExecutionTargetTimeoutSec(sandboxTarget, 0)).toBe(DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC);
         expect(resolveAdapterExecutionTargetTimeoutSec(sandboxTarget, 90)).toBe(90);
         expect(resolveAdapterExecutionTargetTimeoutSec({
@@ -191,6 +518,90 @@ describe("sandbox adapter execution targets", () => {
                 strictHostKeyChecking: true,
             },
         }, 0)).toBe(0);
+        expect(resolveAdapterExecutionTargetTimeoutSec({ kind: "local" }, 0)).toBe(0);
+    });
+    it("reports which knob produced the resolved timeout", () => {
+        const sandboxTarget = {
+            kind: "remote",
+            transport: "sandbox",
+            remoteCwd: "/workspace",
+            runner: createLocalSandboxRunner(),
+        };
+        expect(resolveAdapterExecutionTargetTimeout(sandboxTarget, 0)).toEqual({
+            timeoutSec: DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,
+            source: "sandbox_default",
+        });
+        expect(resolveAdapterExecutionTargetTimeout(sandboxTarget, 90)).toEqual({
+            timeoutSec: 90,
+            source: "configured",
+        });
+        expect(resolveAdapterExecutionTargetTimeout({ kind: "local" }, 0)).toEqual({
+            timeoutSec: 0,
+            source: "unlimited",
+        });
+        // Fractional (sub-second) configured timeouts are preserved rather than
+        // floored to 0, which would silently mean "no timeout".
+        expect(resolveAdapterExecutionTargetTimeout({ kind: "local" }, 0.01)).toEqual({
+            timeoutSec: 0.01,
+            source: "configured",
+        });
+        expect(resolveAdapterExecutionTargetTimeout(sandboxTarget, 0.5)).toEqual({
+            timeoutSec: 0.5,
+            source: "configured",
+        });
+    });
+    it("treats a negative timeoutSec as the explicit no-timeout opt-out, even on sandbox targets", () => {
+        const sandboxTarget = {
+            kind: "remote",
+            transport: "sandbox",
+            remoteCwd: "/workspace",
+            runner: createLocalSandboxRunner(),
+        };
+        expect(resolveAdapterExecutionTargetTimeout(sandboxTarget, -1)).toEqual({
+            timeoutSec: 0,
+            source: "configured",
+        });
+        expect(resolveAdapterExecutionTargetTimeout({ kind: "local" }, -1)).toEqual({
+            timeoutSec: 0,
+            source: "configured",
+        });
+        expect(resolveAdapterExecutionTargetTimeoutSec(sandboxTarget, -1)).toBe(0);
+        // Explicit zero intentionally does NOT opt out: the adapter config UI
+        // persists the schema default of 0 for untouched fields, so a stored
+        // timeoutSec=0 cannot be read as operator intent. It keeps the sandbox
+        // backstop; the documented opt-out is a negative value.
+        expect(resolveAdapterExecutionTargetTimeout(sandboxTarget, 0)).toEqual({
+            timeoutSec: DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,
+            source: "sandbox_default",
+        });
+        // Unset behaves like zero.
+        expect(resolveAdapterExecutionTargetTimeout(sandboxTarget, undefined)).toEqual({
+            timeoutSec: DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,
+            source: "sandbox_default",
+        });
+        expect(resolveAdapterExecutionTargetTimeout({ kind: "local" }, undefined)).toEqual({
+            timeoutSec: 0,
+            source: "unlimited",
+        });
+    });
+    it("formats self-describing timeout errors naming the timer and knob", () => {
+        expect(formatAdapterExecutionTimeoutErrorMessage({
+            timeoutSec: DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,
+            source: "sandbox_default",
+        })).toBe("Run exceeded the adapter execution timeout (timeoutSec=14400, sandbox default). " +
+            "Set adapterConfig.timeoutSec to raise it.");
+        expect(formatAdapterExecutionTimeoutErrorMessage({ timeoutSec: 1800, source: "configured" })).toBe("Run exceeded the adapter execution timeout (timeoutSec=1800, configured via adapterConfig.timeoutSec). " +
+            "Set adapterConfig.timeoutSec to raise it.");
+    });
+    it("formats the start-of-run timeout log line with the resolved value and source", () => {
+        expect(formatAdapterExecutionTimeoutStartLogLine({
+            timeoutSec: DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,
+            source: "sandbox_default",
+        })).toBe("Adapter execution timeout: timeoutSec=14400 (sandbox default; set adapterConfig.timeoutSec to override).");
+        expect(formatAdapterExecutionTimeoutStartLogLine({ timeoutSec: 900, source: "configured" })).toBe("Adapter execution timeout: timeoutSec=900 (configured via adapterConfig.timeoutSec; set adapterConfig.timeoutSec to override).");
+        expect(formatAdapterExecutionTimeoutStartLogLine({ timeoutSec: 0, source: "unlimited" })).toBe("Adapter execution timeout: none (no adapter wall-clock timeout for this target; set adapterConfig.timeoutSec to add one).");
+        // Negative opt-out resolves to { timeoutSec: 0, source: "configured" }.
+        expect(formatAdapterExecutionTimeoutStartLogLine({ timeoutSec: 0, source: "configured" })).toBe("Adapter execution timeout: none (explicitly disabled via adapterConfig.timeoutSec; set it to a positive value to add one).");
     });
     it("uses the caller timeout override when installing a missing sandbox command", async () => {
         const runner = {
@@ -820,7 +1231,7 @@ describe("sandbox adapter execution targets", () => {
         try {
             expect(bridge).not.toBeNull();
             expect(runner.execute).toHaveBeenCalled();
-            expect(runner.execute.mock.calls.some(([input]) => input.timeoutMs === 1_800_000)).toBe(true);
+            expect(runner.execute.mock.calls.some(([input]) => input.timeoutMs === DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC * 1000)).toBe(true);
         }
         finally {
             await bridge?.stop();