@penclipai/adapter-utils 2026.704.0 → 2026.714.0

package/dist/execution-target.js

@@ -1,4 +1,8 @@
+import fs from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { prepareCommandManagedRuntime, } from "./command-managed-runtime.js";
 import { buildRemoteExecutionSessionIdentity, prepareRemoteManagedRuntime, remoteExecutionSessionMatches, } from "./remote-managed-runtime.js";
 import { createCommandManagedSandboxCallbackBridgeQueueClient, createSandboxCallbackBridgeAsset, createSandboxCallbackBridgeToken, DEFAULT_SANDBOX_CALLBACK_BRIDGE_MAX_BODY_BYTES, sandboxCallbackBridgeDirectories, startSandboxCallbackBridgeServer, startSandboxCallbackBridgeWorker, } from "./sandbox-callback-bridge.js";
@@ -8,7 +12,14 @@ import { ensureCommandResolvable, resolveCommandForLogs, runChildProcess, } from
 import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
 import { preferredShellForSandbox, shellCommandArgs } from "./sandbox-shell.js";
 export { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
-export const DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC = 1_800;
+// 4-hour wall-clock backstop for sandbox-backed adapter runs. This is a
+// last-resort kill switch, not the primary hang detector: genuinely hung runs
+// are caught much earlier by the adapters' output-inactivity monitors (e.g.
+// codex-local's 7-minute monitor). The value intentionally matches the
+// recovery watchdog's ACTIVE_RUN_OUTPUT_CRITICAL_THRESHOLD_MS (4h) in
+// server/src/services/recovery/service.ts so healthy long runs are never
+// killed by the adapter before the watchdog would even consider them stuck.
+export const DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC = 14_400;
 function parseObject(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -102,21 +113,71 @@ export function describeAdapterExecutionTarget(target) {
     }
     return `sandbox environment${target.providerKey ? ` (${target.providerKey})` : ""}`;
 }
-export function resolveAdapterExecutionTargetTimeoutSec(target, configuredTimeoutSec) {
-    const normalizedConfiguredTimeoutSec = typeof configuredTimeoutSec === "number" && Number.isFinite(configuredTimeoutSec) && configuredTimeoutSec > 0
-        ? Math.floor(configuredTimeoutSec)
-        : 0;
-    if (normalizedConfiguredTimeoutSec > 0)
-        return normalizedConfiguredTimeoutSec;
+export function resolveAdapterExecutionTargetTimeout(target, configuredTimeoutSec) {
+    if (typeof configuredTimeoutSec === "number" && Number.isFinite(configuredTimeoutSec)) {
+        // Preserve fractional (sub-second) configured values instead of flooring:
+        // adapters historically honored e.g. timeoutSec=0.5, and flooring would
+        // silently turn it into "no timeout".
+        if (configuredTimeoutSec > 0) {
+            return { timeoutSec: configuredTimeoutSec, source: "configured" };
+        }
+        // A negative timeoutSec is the explicit "no adapter wall-clock timeout"
+        // opt-out, honored even on sandbox targets. Zero cannot carry that
+        // meaning: the adapter config UI persists the schema default of 0 for
+        // untouched fields, so timeoutSec=0 in stored config does not signal
+        // operator intent and falls through to target defaults below.
+        if (configuredTimeoutSec < 0) {
+            return { timeoutSec: 0, source: "configured" };
+        }
+    }
     // Local and SSH adapters preserve the historical "0 means no adapter
     // timeout" behavior. Sandbox-backed runs execute through provider RPCs
     // that usually apply their own shorter command defaults, so request an
     // explicit longer timeout for full adapter runs when the adapter leaves
     // timeoutSec unset.
     if (target?.kind === "remote" && target.transport === "sandbox") {
-        return DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC;
+        return { timeoutSec: DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC, source: "sandbox_default" };
+    }
+    return { timeoutSec: 0, source: "unlimited" };
+}
+export function resolveAdapterExecutionTargetTimeoutSec(target, configuredTimeoutSec) {
+    return resolveAdapterExecutionTargetTimeout(target, configuredTimeoutSec).timeoutSec;
+}
+function describeAdapterExecutionTimeoutSource(source) {
+    switch (source) {
+        case "configured":
+            return "configured via adapterConfig.timeoutSec";
+        case "sandbox_default":
+            return "sandbox default";
+        case "unlimited":
+            return "no adapter wall-clock timeout";
     }
-    return 0;
+}
+/**
+ * Self-describing error message for when the adapter wall-clock execution
+ * timeout kills a run. Names the timer that fired and the knob that controls
+ * it so run failures never surface as a bare "Timed out".
+ */
+export function formatAdapterExecutionTimeoutErrorMessage(resolution) {
+    return (`Run exceeded the adapter execution timeout ` +
+        `(timeoutSec=${resolution.timeoutSec}, ${describeAdapterExecutionTimeoutSource(resolution.source)}). ` +
+        `Set adapterConfig.timeoutSec to raise it.`);
+}
+/**
+ * One-line start-of-run statement of the effective wall-clock timeout and its
+ * source. Callers prefix with `[paperclip] ` and append a newline.
+ */
+export function formatAdapterExecutionTimeoutStartLogLine(resolution) {
+    if (resolution.timeoutSec <= 0) {
+        if (resolution.source === "configured") {
+            return ("Adapter execution timeout: none " +
+                "(explicitly disabled via adapterConfig.timeoutSec; set it to a positive value to add one).");
+        }
+        return ("Adapter execution timeout: none " +
+            "(no adapter wall-clock timeout for this target; set adapterConfig.timeoutSec to add one).");
+    }
+    return (`Adapter execution timeout: timeoutSec=${resolution.timeoutSec} ` +
+        `(${describeAdapterExecutionTimeoutSource(resolution.source)}; set adapterConfig.timeoutSec to override).`);
 }
 function requireSandboxRunner(target) {
     if (target.runner)
@@ -752,6 +813,424 @@ async function readBridgeForwardResponseBody(response, maxBodyBytes) {
     }
     return Buffer.concat(chunks, totalBytes).toString("utf8");
 }
+const PROCESS_SESSION_PROXY_SCRIPT = "paperclip-process-session-proxy.mjs";
+const PROCESS_SESSION_REMOTE_SCRIPT = "paperclip-process-session-remote.mjs";
+const PROCESS_SESSION_AUTH_TIMEOUT_MS = 5_000;
+function jsonLine(value) {
+    return `${JSON.stringify(value)}\n`;
+}
+function splitJsonLines(buffer) {
+    const parts = buffer.split(/\n/);
+    return { lines: parts.slice(0, -1), rest: parts.at(-1) ?? "" };
+}
+async function writeProcessSessionProxyScript(dir, port, token) {
+    await fs.mkdir(dir, { recursive: true });
+    const proxyPath = path.join(dir, PROCESS_SESSION_PROXY_SCRIPT);
+    await fs.writeFile(proxyPath, getProcessSessionProxySource({ port, token }), { mode: 0o700 });
+    if (process.platform === "win32") {
+        // ACPX splits override commands before spawning them. Use native Node
+        // directly so a .cmd shell layer cannot buffer the proxy's streaming stdin.
+        const nodePath = process.execPath.replace(/\\/g, "/");
+        const scriptPath = proxyPath.replace(/\\/g, "/");
+        return `${JSON.stringify(nodePath)} ${JSON.stringify(scriptPath)}`;
+    }
+    return proxyPath;
+}
+async function syncProcessSessionRemoteScript(input) {
+    await input.client.writeTextFile(input.remoteScriptPath, getProcessSessionRemoteSource());
+}
+async function readRemoteJsonFiles(input) {
+    const names = await input.client.listJsonFiles(input.dir);
+    const out = [];
+    for (const name of names) {
+        const filePath = path.posix.join(input.dir, name);
+        const body = await input.client.readTextFile(filePath);
+        await input.client.remove(filePath).catch(() => undefined);
+        out.push({ name, body });
+    }
+    return out;
+}
+async function waitForLocalServerListen(server) {
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        throw new Error("Process session bridge did not expose a TCP port.");
+    }
+    return address.port;
+}
+export async function startAdapterExecutionTargetProcessSessionBridge(input) {
+    if (!input.target || input.target.kind !== "remote" || input.target.transport !== "sandbox") {
+        return null;
+    }
+    const target = input.target;
+    const onLog = input.onLog ?? (async () => { });
+    const runner = requireSandboxRunner(target);
+    const shellCommand = preferredSandboxShell(target);
+    const timeoutMs = typeof input.timeoutSec === "number" && Number.isFinite(input.timeoutSec) && input.timeoutSec > 0
+        ? Math.trunc(input.timeoutSec * 1000)
+        : target.timeoutMs ?? undefined;
+    const bridgeRuntimeDir = path.posix.join(input.runtimeRootDir?.trim() || path.posix.join(target.remoteCwd, ".paperclip-runtime", input.adapterKey), "process-sessions");
+    const sessionId = randomUUID();
+    const sessionDir = path.posix.join(bridgeRuntimeDir, sessionId);
+    const stdinDir = path.posix.join(sessionDir, "stdin");
+    const eventsDir = path.posix.join(sessionDir, "events");
+    const commandFilePath = path.posix.join(sessionDir, "command.json");
+    const remoteScriptPath = path.posix.join(bridgeRuntimeDir, PROCESS_SESSION_REMOTE_SCRIPT);
+    const client = createCommandManagedSandboxCallbackBridgeQueueClient({
+        runner,
+        remoteCwd: target.remoteCwd,
+        timeoutMs,
+        shellCommand,
+    });
+    await client.makeDir(stdinDir);
+    await client.makeDir(eventsDir);
+    await syncProcessSessionRemoteScript({ client, remoteScriptPath });
+    const commandPayload = JSON.stringify({
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd || target.remoteCwd,
+        env: sanitizeRemoteExecutionEnv(input.env),
+    });
+    await client.writeTextFile(commandFilePath, commandPayload);
+    await onLog("stdout", `[paperclip] Starting ACP process session bridge in sandbox (${target.providerKey ?? "provider"}).\n`);
+    const startResult = await runner.execute({
+        command: shellCommand,
+        args: shellCommandArgs([
+            `mkdir -p ${shellQuote(stdinDir)} ${shellQuote(eventsDir)}`,
+            `chmod 600 ${shellQuote(commandFilePath)}`,
+            `PAPERCLIP_PROCESS_SESSION_DIR=${shellQuote(sessionDir)} ` +
+                `nohup node ${shellQuote(remoteScriptPath)} >/dev/null 2>&1 < /dev/null &`,
+            "printf '%s\\n' \"$!\"",
+        ].join("\n")),
+        cwd: target.remoteCwd,
+        env: {
+            PAPERCLIP_SANDBOX_EXEC_CHANNEL: "bridge",
+        },
+        timeoutMs,
+    });
+    if (startResult.timedOut || (startResult.exitCode ?? 1) !== 0) {
+        throw new Error(`Failed to start sandbox ACP process session bridge: ${startResult.stderr || startResult.stdout}`);
+    }
+    let socket = null;
+    let stopping = false;
+    let stdinSeq = 0;
+    let pollTimer = null;
+    let markReady = () => { };
+    const ready = new Promise((resolve) => {
+        markReady = resolve;
+    });
+    const pendingRemoteEvents = [];
+    const token = createSandboxCallbackBridgeToken(18);
+    const proxyDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-proxy-"));
+    const writeRemoteEventToSocket = (event) => {
+        if (!socket)
+            return false;
+        socket.write(jsonLine(event));
+        if (event.type === "exit") {
+            stopping = true;
+            socket.end();
+        }
+        else if (event.type === "error") {
+            stopping = true;
+            socket.destroy();
+        }
+        return true;
+    };
+    const deliverRemoteEvent = (event) => {
+        if (socket) {
+            writeRemoteEventToSocket(event);
+            return;
+        }
+        pendingRemoteEvents.push(event);
+        if (event.type === "exit" || event.type === "error") {
+            stopping = true;
+        }
+    };
+    const flushPendingRemoteEvents = () => {
+        if (!socket)
+            return;
+        while (pendingRemoteEvents.length > 0 && socket) {
+            const event = pendingRemoteEvents.shift();
+            if (event)
+                writeRemoteEventToSocket(event);
+        }
+    };
+    const liveSockets = new Set();
+    let stdinWriteChain = Promise.resolve();
+    const server = net.createServer((nextSocket) => {
+        liveSockets.add(nextSocket);
+        nextSocket.setEncoding("utf8");
+        nextSocket.on("error", () => undefined);
+        let connectionBuffer = "";
+        let authenticated = false;
+        // Connections own the session (and receive buffered process output) only
+        // after presenting the bridge token; idle unauthenticated peers are dropped.
+        const authTimer = setTimeout(() => {
+            if (!authenticated)
+                nextSocket.destroy();
+        }, PROCESS_SESSION_AUTH_TIMEOUT_MS);
+        authTimer.unref?.();
+        nextSocket.on("close", () => {
+            clearTimeout(authTimer);
+            liveSockets.delete(nextSocket);
+        });
+        nextSocket.on("data", (chunk) => {
+            connectionBuffer += chunk;
+            const split = splitJsonLines(connectionBuffer);
+            connectionBuffer = split.rest;
+            for (const line of split.lines) {
+                if (!line.trim())
+                    continue;
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    nextSocket.destroy();
+                    return;
+                }
+                if (message.token !== token) {
+                    nextSocket.destroy();
+                    return;
+                }
+                if (!authenticated) {
+                    if (socket) {
+                        nextSocket.destroy();
+                        return;
+                    }
+                    authenticated = true;
+                    clearTimeout(authTimer);
+                    socket = nextSocket;
+                    markReady();
+                    flushPendingRemoteEvents();
+                }
+                stdinWriteChain = stdinWriteChain.then(async () => {
+                    if (message.type === "stdin" && typeof message.data === "string") {
+                        stdinSeq += 1;
+                        const name = `${String(stdinSeq).padStart(12, "0")}.json`;
+                        await client.writeTextFile(path.posix.join(stdinDir, name), jsonLine({ type: "stdin", data: message.data }));
+                    }
+                    else if (message.type === "stdinEnd") {
+                        stdinSeq += 1;
+                        const name = `${String(stdinSeq).padStart(12, "0")}.json`;
+                        await client.writeTextFile(path.posix.join(stdinDir, name), jsonLine({ type: "stdinEnd" }));
+                    }
+                }).catch((error) => {
+                    if (!nextSocket.destroyed) {
+                        nextSocket.write(jsonLine({ type: "error", message: error instanceof Error ? error.message : String(error) }));
+                    }
+                    nextSocket.destroy();
+                });
+            }
+        });
+    });
+    const poll = async () => {
+        if (stopping)
+            return;
+        try {
+            const events = await readRemoteJsonFiles({ client, dir: eventsDir });
+            for (const event of events) {
+                const parsed = JSON.parse(event.body);
+                deliverRemoteEvent(parsed);
+                if (parsed.type === "exit" || parsed.type === "error")
+                    return;
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await onLog("stderr", `[paperclip] ACP process session bridge poll failed: ${message}\n`);
+            deliverRemoteEvent({ type: "error", message });
+            return;
+        }
+        finally {
+            if (!stopping) {
+                pollTimer = setTimeout(() => void poll(), 100);
+                pollTimer.unref?.();
+            }
+        }
+    };
+    const port = await waitForLocalServerListen(server);
+    const agentCommand = await writeProcessSessionProxyScript(proxyDir, port, token);
+    pollTimer = setTimeout(() => void poll(), 100);
+    pollTimer.unref?.();
+    return {
+        agentCommand,
+        ready,
+        stop: async () => {
+            stopping = true;
+            markReady();
+            if (pollTimer)
+                clearTimeout(pollTimer);
+            for (const liveSocket of liveSockets)
+                liveSocket.destroy();
+            await new Promise((resolve) => server.close(() => resolve())).catch(() => undefined);
+            await stdinWriteChain.catch(() => undefined);
+            await client.writeTextFile(path.posix.join(stdinDir, `${String(stdinSeq + 1).padStart(12, "0")}.json`), jsonLine({ type: "stdinEnd" })).catch(() => undefined);
+            await client.remove(sessionDir).catch(() => undefined);
+            await fs.rm(proxyDir, { recursive: true, force: true }).catch(() => undefined);
+        },
+    };
+}
+function getProcessSessionProxySource(input) {
+    return `#!/usr/bin/env node
+import net from "node:net";
+
+const socket = net.createConnection({ host: "127.0.0.1", port: ${input.port} });
+const token = ${JSON.stringify(input.token)};
+let buffer = "";
+let exiting = false;
+let outputChain = Promise.resolve();
+let connected = false;
+let stdinEnded = false;
+const pendingStdin = [];
+
+function send(message) {
+  socket.write(JSON.stringify({ token, ...message }) + "\\n");
+}
+
+function writeOutput(stream, chunk) {
+  const output = stream === "stderr" ? process.stderr : process.stdout;
+  outputChain = outputChain.then(() => new Promise((resolve) => {
+    if (output.write(chunk)) resolve();
+    else output.once("drain", resolve);
+  }));
+}
+
+function finish(code) {
+  if (exiting) return;
+  exiting = true;
+  void outputChain.then(
+    () => {
+      process.exitCode = code;
+      socket.end();
+    },
+    () => {
+      process.exitCode = 1;
+      socket.destroy();
+    },
+  );
+}
+
+socket.on("connect", () => {
+  connected = true;
+  send({ type: "hello" });
+  for (const data of pendingStdin.splice(0)) send({ type: "stdin", data });
+  if (stdinEnded) send({ type: "stdinEnd" });
+});
+process.stdin.on("data", (chunk) => {
+  const data = Buffer.from(chunk).toString("base64");
+  if (connected) send({ type: "stdin", data });
+  else pendingStdin.push(data);
+});
+process.stdin.on("end", () => {
+  stdinEnded = true;
+  if (connected) send({ type: "stdinEnd" });
+});
+
+socket.setEncoding("utf8");
+socket.on("data", (chunk) => {
+  buffer += chunk;
+  const parts = buffer.split(/\\n/);
+  buffer = parts.pop() || "";
+  for (const line of parts) {
+    if (!line.trim()) continue;
+    const message = JSON.parse(line);
+    if (message.type === "data") {
+      const out = Buffer.from(message.data || "", "base64");
+      writeOutput(message.stream, out);
+    } else if (message.type === "error") {
+      writeOutput("stderr", String(message.message || "Process session bridge failed.") + "\\n");
+      finish(1);
+    } else if (message.type === "exit") {
+      finish(typeof message.code === "number" ? message.code : 1);
+    }
+  }
+});
+socket.on("close", () => {
+  if (!exiting) process.exit(1);
+});
+`;
+}
+function getProcessSessionRemoteSource() {
+    return `import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const sessionDir = process.env.PAPERCLIP_PROCESS_SESSION_DIR;
+if (!sessionDir) throw new Error("Missing process session bridge env.");
+
+const stdinDir = path.posix.join(sessionDir, "stdin");
+const eventsDir = path.posix.join(sessionDir, "events");
+const commandFilePath = path.posix.join(sessionDir, "command.json");
+let seq = 0;
+let stdinClosed = false;
+
+const config = JSON.parse(await fs.readFile(commandFilePath, "utf8"));
+await fs.mkdir(stdinDir, { recursive: true });
+await fs.mkdir(eventsDir, { recursive: true });
+
+let writeChain = Promise.resolve();
+
+function writeEvent(event) {
+  seq += 1;
+  const file = path.posix.join(eventsDir, String(seq).padStart(12, "0") + ".json");
+  const write = writeChain.then(async () => {
+    await fs.writeFile(file + ".tmp", JSON.stringify(event) + "\\n", "utf8");
+    await fs.rename(file + ".tmp", file);
+  });
+  writeChain = write.catch(() => undefined);
+  return write;
+}
+
+const child = spawn(config.command, Array.isArray(config.args) ? config.args : [], {
+  cwd: config.cwd || process.cwd(),
+  env: { ...process.env, ...(config.env || {}) },
+  stdio: ["pipe", "pipe", "pipe"],
+});
+
+child.stdout.on("data", (chunk) => void writeEvent({ type: "data", stream: "stdout", data: Buffer.from(chunk).toString("base64") }));
+child.stderr.on("data", (chunk) => void writeEvent({ type: "data", stream: "stderr", data: Buffer.from(chunk).toString("base64") }));
+child.on("error", (error) => void writeEvent({ type: "error", message: error.message }));
+// "close" (not "exit") so stdout/stderr fully drain before the exit event;
+// the write chain then guarantees the exit file lands after every data file.
+child.on("close", (code, signal) => void writeEvent({ type: "exit", code, signal }));
+
+async function pollStdin() {
+  while (!stdinClosed) {
+    const stdinEntries = await fs.readdir(stdinDir).catch(() => null);
+    if (!stdinEntries) {
+      stdinClosed = true;
+      child.stdin.end();
+      break;
+    }
+    const entries = stdinEntries.filter((name) => name.endsWith(".json")).sort();
+    for (const name of entries) {
+      const file = path.posix.join(stdinDir, name);
+      const raw = await fs.readFile(file, "utf8").catch(() => null);
+      await fs.rm(file, { force: true }).catch(() => undefined);
+      if (!raw) continue;
+      const message = JSON.parse(raw);
+      if (message.type === "stdin" && typeof message.data === "string") {
+        child.stdin.write(Buffer.from(message.data, "base64"));
+      } else if (message.type === "stdinEnd") {
+        stdinClosed = true;
+        child.stdin.end();
+        break;
+      }
+    }
+    if (!stdinClosed) await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+void pollStdin().catch((error) => void writeEvent({ type: "error", message: error instanceof Error ? error.message : String(error) }));
+`;
+}
 export async function startAdapterExecutionTargetPaperclipBridge(input) {
     if (!adapterExecutionTargetUsesPaperclipBridge(input.target)) {
         return null;