Skip to content

The open-source app everyone uses to manage agents at work

feat: run ACP sessions in sandbox execution targets (#9390)

Devin Foley9cde4e128c4f
diff --git a/packages/adapter-utils/src/acpx-engine/execute.test.ts b/packages/adapter-utils/src/acpx-engine/execute.test.ts
index a953021dca..bdadebda32 100644
--- a/packages/adapter-utils/src/acpx-engine/execute.test.ts
+++ b/packages/adapter-utils/src/acpx-engine/execute.test.ts
@@ -13,6 +13,7 @@ import {
parseGeminiVersionParts,
rewriteGeminiAcpFlagForVersion,
} from "./execute.js";
+import { runChildProcess } from "../server-utils.js";
const execFileAsync = promisify(execFile);
@@ -50,6 +51,44 @@ async function createSkill(root: string, name: string, body = `---\nrequired: fa
};
}
+function createLocalSandboxRunner(
+ onExecute?: (input: {
+ command: string;
+ args?: string[];
+ cwd?: string;
+ env?: Record<string, string>;
+ }) => void,
+) {
+ let counter = 0;
+ return {
+ execute: async (input: {
+ command: string;
+ args?: string[];
+ cwd?: string;
+ env?: Record<string, string>;
+ stdin?: string;
+ timeoutMs?: number;
+ onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+ onSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;
+ }) => {
+ counter += 1;
+ onExecute?.(input);
+ const command = input.command === "bash" ? "/bin/bash" : input.command;
+ return await runChildProcess(`acpx-sandbox-run-${counter}`, command, input.args ?? [], {
+ cwd: input.cwd ?? process.cwd(),
+ env: input.env ?? {},
+ stdin: input.stdin,
+ timeoutSec: Math.max(1, Math.ceil((input.timeoutMs ?? 30_000) / 1000)),
+ graceSec: 5,
+ onLog: input.onLog ?? (async () => {}),
+ onSpawn: input.onSpawn
+ ? async (meta) => input.onSpawn?.({ pid: meta.pid, startedAt: meta.startedAt })
+ : undefined,
+ });
+ },
+ };
+}
+
function buildRuntime() {
return {
ensureSession: async () => ({
@@ -158,6 +197,61 @@ describe("shared ACPX engine runtime behavior", () => {
expect(prompt).not.toContain("$PAPERCLIP_API_BASE/api/issues/$PAPERCLIP_TASK_ID");
});
+ it("emits ACP text deltas as stdout transcript records", async () => {
+ const root = await makeTempRoot();
+ const stateDir = path.join(root, "state");
+ const logs: Array<{ stream: string; text: string }> = [];
+ const execute = createAcpxEngineExecutor({
+ createRuntime: () => ({
+ ensureSession: async () => ({
+ backendSessionId: "backend-session",
+ agentSessionId: "agent-session",
+ runtimeSessionName: "runtime-session",
+ }),
+ startTurn: () => ({
+ events: (async function* () {
+ yield {
+ type: "text_delta",
+ text: "streamed hello",
+ stream: "output",
+ tag: "agent_message_chunk",
+ };
+ yield { type: "done", stopReason: "end_turn" };
+ })(),
+ result: Promise.resolve({ status: "completed", stopReason: "end_turn" }),
+ cancel: async () => {},
+ }),
+ close: async () => {},
+ }) as never,
+ });
+
+ const result = await execute({
+ runId: "run-streaming-text-delta",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ },
+ runtime: {},
+ config: { agent: "custom", agentCommand: "node ./fake-acp.js", stateDir },
+ context: {},
+ onLog: async (stream: "stdout" | "stderr", text: string) => {
+ logs.push({ stream, text });
+ },
+ onMeta: async () => {},
+ } as never);
+
+ expect(result.exitCode).toBe(0);
+ expect(logs).toContainEqual({
+ stream: "stdout",
+ text: `${JSON.stringify({
+ type: "acpx.text_delta",
+ text: "streamed hello",
+ channel: "output",
+ tag: "agent_message_chunk",
+ })}\n`,
+ });
+ });
+
it.skipIf(process.platform === "win32")("materializes ACPX Claude skills without symlinked descendants", async () => {
const root = await makeTempRoot();
const skillRoot = path.join(root, "skills");
@@ -558,6 +652,57 @@ describe("shared ACPX engine runtime behavior", () => {
expect(wrapper).toContain("exec node ./fake-acp.js");
});
+ it("starts sandbox ACP process sessions in the remote execution cwd", async () => {
+ const root = await makeTempRoot();
+ const stateDir = path.join(root, "state");
+ const localCwd = path.join(root, "worktree");
+ const remoteCwd = path.join(root, "remote-workspace");
+ await fs.mkdir(localCwd, { recursive: true });
+ await fs.mkdir(remoteCwd, { recursive: true });
+
+ let sessionPayload: Record<string, unknown> | null = null;
+ const runner = createLocalSandboxRunner(
+ (input: { args?: string[]; env?: Record<string, string> }) => {
+ if (input.env?.PAPERCLIP_SANDBOX_EXEC_CHANNEL === "bridge") {
+ const script = input.args?.[1] ?? "";
+ const match = script.match(/PAPERCLIP_PROCESS_SESSION_COMMAND_B64='([^']+)'/);
+ if (match) {
+ sessionPayload = JSON.parse(Buffer.from(match[1]!, "base64").toString("utf8")) as Record<string, unknown>;
+ }
+ }
+ },
+ );
+
+ await runExecutor(
+ { agent: "custom", agentCommand: "node ./fake-acp.js", stateDir, cwd: localCwd },
+ {
+ authToken: "real-run-jwt",
+ executionTarget: {
+ kind: "remote",
+ transport: "sandbox",
+ providerKey: "fake-plugin",
+ remoteCwd,
+ runner,
+ },
+ },
+ );
+
+ expect(sessionPayload).toMatchObject({
+ command: "sh",
+ args: ["-lc", "exec node ./fake-acp.js"],
+ cwd: remoteCwd,
+ });
+ const payloadEnv = ((sessionPayload as Record<string, unknown> | null)?.env ?? {}) as Record<string, unknown>;
+ expect(payloadEnv).toMatchObject({
+ PAPERCLIP_API_BRIDGE_MODE: "queue_v1",
+ });
+ expect(String(payloadEnv.PAPERCLIP_API_URL ?? "")).toMatch(
+ /^http:\/\/127\.0\.0\.1:\d+$/,
+ );
+ expect(payloadEnv.PAPERCLIP_API_KEY).toBeTruthy();
+ expect(payloadEnv.PAPERCLIP_API_KEY).not.toBe("real-run-jwt");
+ });
+
it.skipIf(process.platform === "win32")("drops benign ACP nes/close cleanup stderr but keeps it in the run log", async () => {
const root = await makeTempRoot();
const stateDir = path.join(root, "state");
diff --git a/packages/adapter-utils/src/acpx-engine/execute.ts b/packages/adapter-utils/src/acpx-engine/execute.ts
index 6d4a849d9f..32dbac0877 100644
--- a/packages/adapter-utils/src/acpx-engine/execute.ts
+++ b/packages/adapter-utils/src/acpx-engine/execute.ts
@@ -12,6 +12,10 @@ import {
formatAdapterExecutionTimeoutStartLogLine,
readAdapterExecutionTarget,
resolveAdapterExecutionTargetTimeout,
+ startAdapterExecutionTargetPaperclipBridge,
+ startAdapterExecutionTargetProcessSessionBridge,
+ type AdapterExecutionTargetPaperclipBridgeHandle,
+ type AdapterExecutionTargetProcessSessionBridgeHandle,
type AdapterExecutionTargetTimeoutResolution,
} from "@paperclipai/adapter-utils/execution-target";
import {
@@ -112,6 +116,8 @@ interface AcpxPreparedRuntime {
fingerprint: string;
agentCommand: string | null;
agentRegistry: AcpAgentRegistry;
+ processSessionBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null;
+ paperclipBridge: AdapterExecutionTargetPaperclipBridgeHandle | null;
remoteExecutionIdentity: Record<string, unknown> | null;
skillPromptInstructions: string;
skillsIdentity: Record<string, unknown>;
@@ -180,12 +186,20 @@ interface BuiltInAgentCommand {
shellCommand: string;
}
-async function resolveBuiltInAgentCommand(agent: string, packageRootDir: string): Promise<BuiltInAgentCommand | null> {
+async function resolveBuiltInAgentCommand(input: {
+ agent: string;
+ packageRootDir: string;
+ executionTargetIsRemote: boolean;
+}): Promise<BuiltInAgentCommand | null> {
+ const { agent, packageRootDir, executionTargetIsRemote } = input;
if (agent === "gemini") {
return { command: "gemini --acp", shellCommand: "gemini --acp" };
}
const binName = agent === "claude" ? "claude-agent-acp" : agent === "codex" ? "codex-acp" : null;
if (!binName) return null;
+ if (executionTargetIsRemote) {
+ return { command: binName, shellCommand: binName };
+ }
const resolved = (await findAncestorBin(packageRootDir, binName)) ?? binName;
return { command: resolved, shellCommand: shellQuote(resolved) };
}
@@ -1062,7 +1076,11 @@ async function buildRuntime(input: {
}
const configuredCommand = asString(config.agentCommand, "").trim();
- const builtInCommand = await resolveBuiltInAgentCommand(acpxAgent, input.engine.packageRootDir);
+ const builtInCommand = await resolveBuiltInAgentCommand({
+ agent: acpxAgent,
+ packageRootDir: input.engine.packageRootDir,
+ executionTargetIsRemote,
+ });
let agentCommand = configuredCommand || builtInCommand?.command || null;
let agentCommandShell = configuredCommand || builtInCommand?.shellCommand || "";
if (acpxAgent === "gemini" && agentCommandShell) {
@@ -1087,7 +1105,58 @@ async function buildRuntime(input: {
})
: null;
const wrapperPath = wrapper?.wrapperPath ?? null;
- const overrides = wrapperPath ? { [acpxAgent]: wrapperPath } : undefined;
+ let paperclipBridge: AdapterExecutionTargetPaperclipBridgeHandle | null = null;
+ if (
+ executionTarget?.kind === "remote" &&
+ executionTarget.transport === "sandbox" &&
+ Boolean(executionTarget.runner) &&
+ agentCommandShell
+ ) {
+ paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
+ runId,
+ target: { ...executionTarget, streamRunLogs: false },
+ runtimeRootDir: null,
+ adapterKey: input.engine.adapterType,
+ timeoutSec,
+ hostApiToken: env.PAPERCLIP_API_KEY,
+ onLog: input.ctx.onLog,
+ });
+ if (paperclipBridge) {
+ Object.assign(env, paperclipBridge.env);
+ await input.ctx.onLog("stdout", "[paperclip] Sandbox ACP API callback bridge enabled for this run.\n");
+ }
+ }
+ const runtimeEnv = Object.fromEntries(
+ Object.entries(ensurePathInEnv({ ...process.env, ...env })).filter(
+ (entry): entry is [string, string] => typeof entry[1] === "string",
+ ),
+ );
+ let processSessionBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null = null;
+ try {
+ processSessionBridge =
+ executionTarget?.kind === "remote" &&
+ executionTarget.transport === "sandbox" &&
+ Boolean(executionTarget.runner) &&
+ agentCommandShell
+ ? await startAdapterExecutionTargetProcessSessionBridge({
+ runId,
+ target: executionTarget,
+ runtimeRootDir: null,
+ adapterKey: input.engine.adapterType,
+ command: "sh",
+ args: ["-lc", `exec ${agentCommandShell}`],
+ cwd: effectiveExecutionCwd,
+ env: runtimeEnv,
+ timeoutSec,
+ onLog: input.ctx.onLog,
+ })
+ : null;
+ } catch (err) {
+ await paperclipBridge?.stop().catch(() => {});
+ throw err;
+ }
+ const overrideCommand = processSessionBridge?.agentCommand ?? wrapperPath;
+ const overrides = overrideCommand ? { [acpxAgent]: overrideCommand } : undefined;
const agentRegistry = createAgentRegistry({ overrides });
const fingerprint = shortHash({
acpxAgent,
@@ -1113,7 +1182,6 @@ async function buildRuntime(input: {
});
const taskKey = asString(input.ctx.runtime.taskKey, "") || wakeTaskId || workspaceId || "default";
const sessionKey = `paperclip:${agent.companyId}:${agent.id}:${taskKey}:${fingerprint}`;
- const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
const loggedEnv = buildInvocationEnvForLogs(env, {
runtimeEnv,
includeRuntimeKeys: ["HOME"],
@@ -1141,6 +1209,8 @@ async function buildRuntime(input: {
fingerprint,
agentCommand,
agentRegistry,
+ processSessionBridge,
+ paperclipBridge,
remoteExecutionIdentity,
skillPromptInstructions,
skillsIdentity: {
@@ -1202,6 +1272,13 @@ async function applySessionConfigOptions(input: {
}
}
+async function cleanupRemoteBridges(prepared: AcpxPreparedRuntime): Promise<void> {
+ await Promise.allSettled([
+ prepared.processSessionBridge?.stop(),
+ prepared.paperclipBridge?.stop(),
+ ]);
+}
+
function renderPaperclipEnvNote(env: Record<string, string>): string {
const paperclipKeys = Object.keys(env)
.filter((key) => key.startsWith("PAPERCLIP_"))
@@ -1692,6 +1769,7 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {
err,
phase: "ensure_session",
});
+ await cleanupRemoteBridges(prepared);
return {
exitCode: 1,
signal: null,
@@ -1707,6 +1785,7 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {
}
if (!handle) {
+ await cleanupRemoteBridges(prepared);
return {
exitCode: 1,
signal: null,
@@ -1744,6 +1823,7 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {
clearWarmHandleTimer(existing);
warmHandles.delete(prepared.sessionKey);
}
+ await cleanupRemoteBridges(prepared);
return {
exitCode: 1,
signal: null,
@@ -1856,7 +1936,7 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {
discardPersistentState: terminal.status === "cancelled" || timedOut,
}).catch(() => {});
}
- } else if (prepared.mode === "persistent" && warmIdleMs > 0) {
+ } else if (prepared.mode === "persistent" && warmIdleMs > 0 && !prepared.processSessionBridge) {
const existing = warmHandles.get(prepared.sessionKey);
if (existing && !warmHandleMatches(existing, runtime, sessionHandle)) {
await runtime.close({
@@ -1908,6 +1988,7 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {
stopReason: terminalStopReason,
message: errorMessage,
});
+ await cleanupRemoteBridges(prepared);
return {
exitCode: terminal.status === "completed" ? 0 : 1,
signal: timedOut ? "SIGTERM" : null,
@@ -1959,6 +2040,7 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {
phase: "turn",
messageOverride,
});
+ await cleanupRemoteBridges(prepared);
return {
exitCode: 1,
signal: timedOut ? "SIGTERM" : null,
diff --git a/packages/adapter-utils/src/execution-target-sandbox.test.ts b/packages/adapter-utils/src/execution-target-sandbox.test.ts
index a28ca2d150..657a506557 100644
--- a/packages/adapter-utils/src/execution-target-sandbox.test.ts
+++ b/packages/adapter-utils/src/execution-target-sandbox.test.ts
@@ -1,7 +1,10 @@
import { createServer } from "node:http";
-import { mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import net from "node:net";
+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 { promisify } from "node:util";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
@@ -16,6 +19,7 @@ import {
resolveAdapterExecutionTargetTimeoutSec,
runAdapterExecutionTargetProcess,
runAdapterExecutionTargetShellCommand,
+ startAdapterExecutionTargetProcessSessionBridge,
startAdapterExecutionTargetPaperclipBridge,
type AdapterSandboxExecutionTarget,
} from "./execution-target.js";
@@ -23,6 +27,8 @@ import { createSandboxRunLogTailFactory } from "./sandbox-run-log-stream.js";
import { runChildProcess } from "./server-utils.js";
import { shellQuote } from "./ssh.js";
+const execFileAsync = promisify(execFile);
+
describe("sandbox adapter execution targets", () => {
const cleanupDirs: string[] = [];
@@ -90,8 +96,8 @@ describe("sandbox adapter execution targets", () => {
].join("\n");
}
- async function waitForCondition(predicate: () => boolean, message: string): Promise<void> {
- const deadline = Date.now() + 1000;
+ async function waitForCondition(predicate: () => boolean, message: string, timeoutMs = 1000): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
if (predicate()) return;
await new Promise((resolve) => setTimeout(resolve, 5));
@@ -99,6 +105,36 @@ describe("sandbox adapter execution targets", () => {
throw new Error(message);
}
+ async function runProxyWithInput(command: string, input: string): Promise<{ stdout: string; stderr: string; code: number | null }> {
+ const child = spawn(command, [], { stdio: ["pipe", "pipe", "pipe"] });
+ 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;
+ });
+ child.stdin.end(input);
+ const code = await new Promise<number | null>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ child.kill("SIGKILL");
+ reject(new Error("Timed out waiting for process session proxy."));
+ }, 5000);
+ child.on("error", (error) => {
+ clearTimeout(timeout);
+ reject(error);
+ });
+ child.on("exit", (exitCode) => {
+ clearTimeout(timeout);
+ resolve(exitCode);
+ });
+ });
+ return { stdout, stderr, code };
+ }
+
function combinedStream(
events: Array<{ stream: "stdout" | "stderr"; chunk: string }>,
stream: "stdout" | "stderr",
@@ -158,6 +194,301 @@ describe("sandbox adapter execution targets", () => {
});
});
+ 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: AdapterSandboxExecutionTarget = {
+ 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!.agentCommand, "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();
+ }
+ });
+
+ 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: AdapterSandboxExecutionTarget = {
+ 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!.agentCommand, "");
+ expect(result.code).toBe(0);
+ expect(result.stdout).toBe("early-out\n");
+ expect(result.stderr).toBe("early-err\n");
+ } finally {
+ await bridge?.stop();
+ }
+ });
+
+ 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: AdapterSandboxExecutionTarget = {
+ 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!.agentCommand, "");
+ expect(result.code).toBe(0);
+ expect(result.stdout).toBe("final-out\n");
+ expect(result.stderr).toBe("final-err\n");
+ } finally {
+ await bridge?.stop();
+ }
+ });
+
+ 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: AdapterSandboxExecutionTarget = {
+ 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: net.Socket | null = null;
+ try {
+ const proxySource = await readFile(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: string) => {
+ squatterReceived += chunk;
+ });
+ squatterSocket.on("error", () => undefined);
+ await new Promise<void>((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<void>((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!.agentCommand, "");
+ expect(result.code).toBe(0);
+ expect(result.stdout).toBe("guarded-out\n");
+ expect(squatterReceived).toBe("");
+ } finally {
+ squatter?.destroy();
+ await bridge?.stop();
+ }
+ });
+
+ 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: AdapterSandboxExecutionTarget = {
+ 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 = spawn(bridge!.agentCommand, [], { stdio: ["pipe", "pipe", "pipe"] });
+ 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<number | null>((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ child.kill("SIGKILL");
+ reject(new Error("Timed out waiting for streaming process session proxy."));
+ }, 5000);
+ child.on("error", (error) => {
+ clearTimeout(timeout);
+ reject(error);
+ });
+ child.on("exit", (exitCode) => {
+ exited = true;
+ clearTimeout(timeout);
+ resolve(exitCode);
+ });
+ });
+
+ try {
+ 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.",
+ 3000,
+ );
+ 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();
+ }
+ });
+
it("applies the remote sandbox fallback when adapter timeoutSec is unset", () => {
const sandboxTarget: AdapterSandboxExecutionTarget = {
kind: "remote",
diff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.ts
index 948b44501f..e264ab7698 100644
--- a/packages/adapter-utils/src/execution-target.ts
+++ b/packages/adapter-utils/src/execution-target.ts
@@ -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 type { SshRemoteExecutionSpec } from "./ssh.js";
import {
prepareCommandManagedRuntime,
@@ -125,6 +129,11 @@ export interface AdapterExecutionTargetPaperclipBridgeHandle {
stop(): Promise<void>;
}
+export interface AdapterExecutionTargetProcessSessionBridgeHandle {
+ agentCommand: string;
+ stop(): Promise<void>;
+}
+
export { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
// 4-hour wall-clock backstop for sandbox-backed adapter runs. This is a
@@ -1200,6 +1209,412 @@ async function readBridgeForwardResponseBody(response: Response, maxBodyBytes: n
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: unknown): string {
+ return `${JSON.stringify(value)}\n`;
+}
+
+function splitJsonLines(buffer: string): { lines: string[]; rest: string } {
+ const parts = buffer.split(/\n/);
+ return { lines: parts.slice(0, -1), rest: parts.at(-1) ?? "" };
+}
+
+async function writeProcessSessionProxyScript(dir: string, port: number, token: string): Promise<string> {
+ await fs.mkdir(dir, { recursive: true });
+ const proxyPath = path.join(dir, PROCESS_SESSION_PROXY_SCRIPT);
+ await fs.writeFile(proxyPath, getProcessSessionProxySource({ port, token }), { mode: 0o700 });
+ return proxyPath;
+}
+
+async function syncProcessSessionRemoteScript(input: {
+ client: ReturnType<typeof createCommandManagedSandboxCallbackBridgeQueueClient>;
+ remoteScriptPath: string;
+}): Promise<void> {
+ await input.client.writeTextFile(input.remoteScriptPath, getProcessSessionRemoteSource());
+}
+
+async function readRemoteJsonFiles(input: {
+ client: ReturnType<typeof createCommandManagedSandboxCallbackBridgeQueueClient>;
+ dir: string;
+}): Promise<Array<{ name: string; body: string }>> {
+ const names = await input.client.listJsonFiles(input.dir);
+ const out: Array<{ name: string; body: string }> = [];
+ 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: net.Server): Promise<number> {
+ await new Promise<void>((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: {
+ runId: string;
+ target: AdapterExecutionTarget | null | undefined;
+ runtimeRootDir: string | null | undefined;
+ adapterKey: string;
+ command: string;
+ args: string[];
+ cwd: string;
+ env: Record<string, string>;
+ timeoutSec?: number | null;
+ onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+}): Promise<AdapterExecutionTargetProcessSessionBridgeHandle | null> {
+ 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 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 = Buffer.from(JSON.stringify({
+ command: input.command,
+ args: input.args,
+ cwd: input.cwd || target.remoteCwd,
+ env: sanitizeRemoteExecutionEnv(input.env),
+ }), "utf8").toString("base64");
+
+ 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)}`,
+ `PAPERCLIP_PROCESS_SESSION_DIR=${shellQuote(sessionDir)} ` +
+ `PAPERCLIP_PROCESS_SESSION_COMMAND_B64=${shellQuote(commandPayload)} ` +
+ `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: net.Socket | null = null;
+ let stopping = false;
+ let stdinSeq = 0;
+ let pollTimer: NodeJS.Timeout | null = null;
+ const pendingRemoteEvents: Array<{
+ type?: string;
+ stream?: "stdout" | "stderr";
+ data?: string;
+ code?: number | null;
+ signal?: string | null;
+ message?: string;
+ }> = [];
+ const token = createSandboxCallbackBridgeToken(18);
+ const proxyDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-process-session-proxy-"));
+
+ const writeRemoteEventToSocket = (event: (typeof pendingRemoteEvents)[number]) => {
+ 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: (typeof pendingRemoteEvents)[number]) => {
+ 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<net.Socket>();
+ 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: { token?: string; type?: string; data?: string };
+ try {
+ message = JSON.parse(line) as { token?: string; type?: string; data?: string };
+ } catch {
+ nextSocket.destroy();
+ return;
+ }
+ if (message.token !== token) {
+ nextSocket.destroy();
+ return;
+ }
+ if (!authenticated) {
+ if (socket) {
+ nextSocket.destroy();
+ return;
+ }
+ authenticated = true;
+ clearTimeout(authTimer);
+ socket = nextSocket;
+ flushPendingRemoteEvents();
+ }
+ void (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) => {
+ 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) as {
+ type?: string;
+ stream?: "stdout" | "stderr";
+ data?: string;
+ code?: number | null;
+ signal?: string | null;
+ message?: string;
+ };
+ 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,
+ stop: async () => {
+ stopping = true;
+ if (pollTimer) clearTimeout(pollTimer);
+ for (const liveSocket of liveSockets) liveSocket.destroy();
+ await new Promise<void>((resolve) => server.close(() => resolve())).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: { port: number; token: string }): string {
+ 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;
+
+function send(message) {
+ socket.write(JSON.stringify({ token, ...message }) + "\\n");
+}
+
+socket.on("connect", () => send({ type: "hello" }));
+process.stdin.on("data", (chunk) => send({ type: "stdin", data: Buffer.from(chunk).toString("base64") }));
+process.stdin.on("end", () => send({ type: "stdinEnd" }));
+process.stdin.resume();
+
+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");
+ (message.stream === "stderr" ? process.stderr : process.stdout).write(out);
+ } else if (message.type === "error") {
+ process.stderr.write(String(message.message || "Process session bridge failed.") + "\\n");
+ exiting = true;
+ process.exitCode = 1;
+ socket.end();
+ } else if (message.type === "exit") {
+ exiting = true;
+ process.exitCode = typeof message.code === "number" ? message.code : 1;
+ socket.end();
+ }
+ }
+});
+socket.on("close", () => {
+ if (!exiting) process.exit(1);
+});
+`;
+}
+
+function getProcessSessionRemoteSource(): string {
+ 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;
+const commandPayload = process.env.PAPERCLIP_PROCESS_SESSION_COMMAND_B64;
+if (!sessionDir || !commandPayload) throw new Error("Missing process session bridge env.");
+
+const stdinDir = path.posix.join(sessionDir, "stdin");
+const eventsDir = path.posix.join(sessionDir, "events");
+let seq = 0;
+let stdinClosed = false;
+
+const config = JSON.parse(Buffer.from(commandPayload, "base64").toString("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 entries = (await fs.readdir(stdinDir).catch(() => [])).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: {
runId: string;
target: AdapterExecutionTarget | null | undefined;
diff --git a/packages/adapter-utils/src/sandbox-callback-bridge.test.ts b/packages/adapter-utils/src/sandbox-callback-bridge.test.ts
index c0ada020ab..d47e1dc038 100644
--- a/packages/adapter-utils/src/sandbox-callback-bridge.test.ts
+++ b/packages/adapter-utils/src/sandbox-callback-bridge.test.ts
@@ -896,6 +896,9 @@ describe("sandbox callback bridge", () => {
{ method: "POST", path: "/api/issues/issue-1/release" },
{ method: "PATCH", path: "/api/issues/issue-1" },
{ method: "GET", path: "/api/issues/issue-1/approvals" },
+ { method: "GET", path: "/api/issues/issue-1/work-products" },
+ { method: "POST", path: "/api/issues/issue-1/work-products" },
+ { method: "PATCH", path: "/api/work-products/wp-1" },
{ method: "GET", path: "/api/issues/issue-1/interactions" },
{ method: "GET", path: "/api/issues/issue-1/interactions/inter-1" },
{ method: "POST", path: "/api/issues/issue-1/interactions" },
@@ -940,6 +943,7 @@ describe("sandbox callback bridge", () => {
{ method: "POST", path: "/api/companies/co-1/archive" },
{ method: "DELETE", path: "/api/issues/issue-1/documents/plan" },
{ method: "DELETE", path: "/api/issues/issue-1/approvals/ap-1" },
+ { method: "DELETE", path: "/api/work-products/wp-1" },
{ method: "POST", path: "/api/approvals/ap-1/approve" },
{ method: "POST", path: "/api/approvals/ap-1/reject" },
{ method: "POST", path: "/api/companies/co-1/logo" },
diff --git a/packages/adapter-utils/src/sandbox-callback-bridge.ts b/packages/adapter-utils/src/sandbox-callback-bridge.ts
index 6531aacfe9..4bc19f08ae 100644
--- a/packages/adapter-utils/src/sandbox-callback-bridge.ts
+++ b/packages/adapter-utils/src/sandbox-callback-bridge.ts
@@ -67,6 +67,11 @@ export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCa
{ method: "PATCH", path: /^\/api\/issues\/[^/]+$/ },
{ method: "GET", path: /^\/api\/issues\/[^/]+\/approvals$/ },
+ // Work products: publish branch/commit/artifact metadata for completed work.
+ { method: "GET", path: /^\/api\/issues\/[^/]+\/work-products$/ },
+ { method: "POST", path: /^\/api\/issues\/[^/]+\/work-products$/ },
+ { method: "PATCH", path: /^\/api\/work-products\/[^/]+$/ },
+
// Issue-thread interactions (suggest tasks, ask questions, request confirmation)
{ method: "GET", path: /^\/api\/issues\/[^/]+\/interactions(?:\/[^/]+)?$/ },
{ method: "POST", path: /^\/api\/issues\/[^/]+\/interactions$/ },
diff --git a/packages/adapters/claude-local/src/server/acp.test.ts b/packages/adapters/claude-local/src/server/acp.test.ts
index 791f0b719c..ba8cb5bc34 100644
--- a/packages/adapters/claude-local/src/server/acp.test.ts
+++ b/packages/adapters/claude-local/src/server/acp.test.ts
@@ -258,6 +258,79 @@ describe("claude_local ACP lane", () => {
).resolves.toEqual({ engine: "acp", explicit: true });
});
+ it("uses ACP for bridged sandbox auto runs when the ACP command is configured as a shell command", async () => {
+ setNodeVersion("v22.12.0");
+ await expect(
+ resolveClaudeExecutionEngineForRun({
+ config: { agentCommand: "claude-agent-acp" },
+ executionTarget: {
+ kind: "remote",
+ transport: "sandbox",
+ providerKey: "fake-plugin",
+ remoteCwd: "/work",
+ runner: {
+ execute: async () => ({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: "",
+ stderr: "",
+ pid: null,
+ startedAt: new Date().toISOString(),
+ }),
+ },
+ },
+ }),
+ ).resolves.toEqual({ engine: "acp", explicit: false });
+ });
+
+ it("falls back to the CLI lane for one-shot sandbox auto runs", async () => {
+ setNodeVersion("v22.12.0");
+ await expect(
+ resolveClaudeExecutionEngineForRun({
+ config: {},
+ executionTarget: {
+ kind: "remote",
+ transport: "sandbox",
+ providerKey: "fake-plugin",
+ remoteCwd: "/work",
+ },
+ }),
+ ).resolves.toMatchObject({
+ engine: "cli",
+ explicit: false,
+ fallbackReason: expect.stringContaining("bidirectional remote process"),
+ });
+ });
+
+ it("falls back to the CLI lane for non-sandbox remote auto runs", async () => {
+ setNodeVersion("v22.12.0");
+ await expect(
+ resolveClaudeExecutionEngineForRun({
+ config: {},
+ executionTarget: {
+ kind: "remote",
+ transport: "ssh",
+ remoteCwd: "/work",
+ spec: {
+ host: "127.0.0.1",
+ port: 22,
+ username: "fixture",
+ remoteCwd: "/work",
+ remoteWorkspacePath: "/work",
+ privateKey: null,
+ knownHosts: null,
+ strictHostKeyChecking: true,
+ },
+ },
+ }),
+ ).resolves.toMatchObject({
+ engine: "cli",
+ explicit: false,
+ fallbackReason: expect.stringContaining("sandbox remote targets only"),
+ });
+ });
+
it("reports ACP prerequisites for the ACP lane", async () => {
const root = await makeTempRoot("paperclip-claude-acp-env-");
const commandPath = path.join(root, "bin", "claude-agent-acp");
diff --git a/packages/adapters/claude-local/src/server/acp.ts b/packages/adapters/claude-local/src/server/acp.ts
index 63dcd13254..8b74ddfdef 100644
--- a/packages/adapters/claude-local/src/server/acp.ts
+++ b/packages/adapters/claude-local/src/server/acp.ts
@@ -8,7 +8,11 @@ import type {
AdapterExecutionContext,
AdapterExecutionResult,
} from "@paperclipai/adapter-utils";
-import { readAdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
+import {
+ ensureAdapterExecutionTargetCommandResolvable,
+ readAdapterExecutionTarget,
+ resolveAdapterExecutionTargetCwd,
+} from "@paperclipai/adapter-utils/execution-target";
import {
DEFAULT_ACP_ENGINE_MODE,
DEFAULT_ACP_ENGINE_NON_INTERACTIVE_PERMISSIONS,
@@ -179,10 +183,30 @@ async function findAncestorBin(startDir: string, binName: string): Promise<strin
}
}
-async function commandIsResolvable(command: string): Promise<boolean> {
+async function commandIsResolvable(
+ command: string,
+ input?: ClaudeEngineResolutionInput,
+): Promise<boolean> {
const trimmed = command.trim();
if (!trimmed) return false;
if (looksLikeShellCommand(trimmed)) return true;
+ const target = readAdapterExecutionTarget({
+ executionTarget: input?.executionTarget,
+ legacyRemoteExecution: input?.executionTransport?.remoteExecution,
+ });
+ if (target?.kind === "remote") {
+ try {
+ await ensureAdapterExecutionTargetCommandResolvable(
+ trimmed,
+ target,
+ resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()),
+ process.env,
+ );
+ return true;
+ } catch {
+ return false;
+ }
+ }
if (path.isAbsolute(trimmed) || hasPathSeparator(trimmed)) return pathExists(trimmed);
return (await findCommandOnPath(trimmed)) !== null;
}
@@ -197,6 +221,22 @@ async function resolveClaudeAcpCommand(config: Record<string, unknown>): Promise
);
}
+function sandboxTargetHasProcessSessionBridge(
+ target: ReturnType<typeof readAdapterExecutionTarget>,
+): boolean {
+ return target?.kind === "remote" && target.transport === "sandbox" && Boolean(target.runner);
+}
+
+async function resolveClaudeAcpCommandForTarget(
+ config: Record<string, unknown>,
+ target: ReturnType<typeof readAdapterExecutionTarget>,
+): Promise<string> {
+ const configured = firstNonEmptyString(config.agentCommand, config.acpAgentCommand);
+ if (configured) return configured;
+ if (target?.kind === "remote") return "claude-agent-acp";
+ return resolveClaudeAcpCommand(config);
+}
+
async function defaultClaudeAcpFallbackReason(
input: ClaudeEngineResolutionInput,
): Promise<string | null> {
@@ -204,14 +244,17 @@ async function defaultClaudeAcpFallbackReason(
executionTarget: input.executionTarget,
legacyRemoteExecution: input.executionTransport?.remoteExecution,
});
- if (target?.kind === "remote") {
- return "Claude ACP currently supports only the local Paperclip host, but this run targets a remote environment.";
+ if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target)) {
+ if (target.transport === "sandbox") {
+ return "Claude ACP requires a bidirectional remote process target; this sandbox exposes only one-shot command execution.";
+ }
+ return "Claude ACP supports sandbox remote targets only; this run targets a non-sandbox remote environment.";
}
if (!nodeVersionMeetsClaudeAcpMinimum()) {
return `Node ${process.version} does not satisfy Claude ACP's Node >=${MIN_ACP_NODE_VERSION} prerequisite.`;
}
- const command = await resolveClaudeAcpCommand(input.config);
- if (!(await commandIsResolvable(command))) {
+ const command = await resolveClaudeAcpCommandForTarget(input.config, target);
+ if (!(await commandIsResolvable(command, input))) {
return `Claude ACP server command is not available: ${command}.`;
}
return null;
@@ -244,10 +287,10 @@ export async function testClaudeAcpEnvironment(
if (targetIsRemote) {
checks.push({
- code: "claude_acp_remote_target_unsupported",
- level: "error",
- message: "Claude ACP currently runs on the local Paperclip host and cannot target a remote execution environment.",
- hint: "Use engine=cli for remote or sandbox Claude runs.",
+ code: "claude_acp_remote_target",
+ level: "info",
+ message: "Claude ACP will run against the remote execution environment.",
+ hint: "Remote ACP requires a bidirectional process target such as SSH or Paperclip's sandbox process-session bridge.",
});
}
@@ -279,8 +322,11 @@ export async function testClaudeAcpEnvironment(
: `Run Claude ACP with Node >=${MIN_ACP_NODE_VERSION} or switch engine=cli.`,
});
- const command = await resolveClaudeAcpCommand(config);
- const commandResolvable = await commandIsResolvable(command);
+ const command = await resolveClaudeAcpCommandForTarget(config, target);
+ const commandResolvable = await commandIsResolvable(command, {
+ config,
+ executionTarget: ctx.executionTarget,
+ });
checks.push({
code: commandResolvable ? "claude_acp_command_resolvable" : "claude_acp_command_missing",
level: commandResolvable ? "info" : "error",
diff --git a/packages/adapters/claude-local/src/server/test.probe.test.ts b/packages/adapters/claude-local/src/server/test.probe.test.ts
index 130fb22e43..9ff7b5f0e8 100644
--- a/packages/adapters/claude-local/src/server/test.probe.test.ts
+++ b/packages/adapters/claude-local/src/server/test.probe.test.ts
@@ -88,7 +88,7 @@ describe("claude sandbox hello probe diagnostics", () => {
const result = await testEnvironment({
companyId: "company-1",
adapterType: "claude_local",
- config: { command: "claude", model: "claude-opus-4-8" },
+ config: { engine: "cli", command: "claude", model: "claude-opus-4-8" },
executionTarget: sandboxTarget,
environmentName: "Daytona",
});
@@ -114,7 +114,7 @@ describe("claude sandbox hello probe diagnostics", () => {
const result = await testEnvironment({
companyId: "company-1",
adapterType: "claude_local",
- config: { command: "claude" },
+ config: { engine: "cli", command: "claude" },
executionTarget: sandboxTarget,
environmentName: "Daytona",
});
@@ -133,7 +133,7 @@ describe("claude sandbox hello probe diagnostics", () => {
const result = await testEnvironment({
companyId: "company-1",
adapterType: "claude_local",
- config: { command: "claude" },
+ config: { engine: "cli", command: "claude" },
executionTarget: sandboxTarget,
environmentName: "Daytona",
});
@@ -152,7 +152,7 @@ describe("claude sandbox hello probe diagnostics", () => {
const result = await testEnvironment({
companyId: "company-1",
adapterType: "claude_local",
- config: { command: "claude" },
+ config: { engine: "cli", command: "claude" },
executionTarget: sandboxTarget,
environmentName: "Daytona",
});
diff --git a/packages/adapters/codex-local/src/server/acp.test.ts b/packages/adapters/codex-local/src/server/acp.test.ts
index cfb7df5550..100e147400 100644
--- a/packages/adapters/codex-local/src/server/acp.test.ts
+++ b/packages/adapters/codex-local/src/server/acp.test.ts
@@ -245,6 +245,79 @@ describe("codex_local ACP lane", () => {
).resolves.toEqual({ engine: "acp", explicit: true });
});
+ it("uses ACP for bridged sandbox auto runs when the ACP command is configured as a shell command", async () => {
+ setNodeVersion("v22.13.0");
+ await expect(
+ resolveCodexExecutionEngineForRun({
+ config: { agentCommand: "codex-acp" },
+ executionTarget: {
+ kind: "remote",
+ transport: "sandbox",
+ providerKey: "fake-plugin",
+ remoteCwd: "/work",
+ runner: {
+ execute: async () => ({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: "",
+ stderr: "",
+ pid: null,
+ startedAt: new Date().toISOString(),
+ }),
+ },
+ },
+ }),
+ ).resolves.toEqual({ engine: "acp", explicit: false });
+ });
+
+ it("falls back to the CLI lane for one-shot sandbox auto runs", async () => {
+ setNodeVersion("v22.13.0");
+ await expect(
+ resolveCodexExecutionEngineForRun({
+ config: {},
+ executionTarget: {
+ kind: "remote",
+ transport: "sandbox",
+ providerKey: "fake-plugin",
+ remoteCwd: "/work",
+ },
+ }),
+ ).resolves.toMatchObject({
+ engine: "cli",
+ explicit: false,
+ fallbackReason: expect.stringContaining("bidirectional remote process"),
+ });
+ });
+
+ it("falls back to the CLI lane for non-sandbox remote auto runs", async () => {
+ setNodeVersion("v22.13.0");
+ await expect(
+ resolveCodexExecutionEngineForRun({
+ config: {},
+ executionTarget: {
+ kind: "remote",
+ transport: "ssh",
+ remoteCwd: "/work",
+ spec: {
+ host: "127.0.0.1",
+ port: 22,
+ username: "fixture",
+ remoteCwd: "/work",
+ remoteWorkspacePath: "/work",
+ privateKey: null,
+ knownHosts: null,
+ strictHostKeyChecking: true,
+ },
+ },
+ }),
+ ).resolves.toMatchObject({
+ engine: "cli",
+ explicit: false,
+ fallbackReason: expect.stringContaining("sandbox remote targets only"),
+ });
+ });
+
it("maps Codex config to the ACPX Codex target", () => {
expect(buildCodexAcpConfig({
engine: "acp",
diff --git a/packages/adapters/codex-local/src/server/acp.ts b/packages/adapters/codex-local/src/server/acp.ts
index 8336babae6..6b8ae974ca 100644
--- a/packages/adapters/codex-local/src/server/acp.ts
+++ b/packages/adapters/codex-local/src/server/acp.ts
@@ -8,7 +8,11 @@ import type {
AdapterExecutionContext,
AdapterExecutionResult,
} from "@paperclipai/adapter-utils";
-import { readAdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
+import {
+ ensureAdapterExecutionTargetCommandResolvable,
+ readAdapterExecutionTarget,
+ resolveAdapterExecutionTargetCwd,
+} from "@paperclipai/adapter-utils/execution-target";
import {
DEFAULT_ACP_ENGINE_MODE,
DEFAULT_ACP_ENGINE_NON_INTERACTIVE_PERMISSIONS,
@@ -179,10 +183,30 @@ async function findAncestorBin(startDir: string, binName: string): Promise<strin
}
}
-async function commandIsResolvable(command: string): Promise<boolean> {
+async function commandIsResolvable(
+ command: string,
+ input?: CodexEngineResolutionInput,
+): Promise<boolean> {
const trimmed = command.trim();
if (!trimmed) return false;
if (looksLikeShellCommand(trimmed)) return true;
+ const target = readAdapterExecutionTarget({
+ executionTarget: input?.executionTarget,
+ legacyRemoteExecution: input?.executionTransport?.remoteExecution,
+ });
+ if (target?.kind === "remote") {
+ try {
+ await ensureAdapterExecutionTargetCommandResolvable(
+ trimmed,
+ target,
+ resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()),
+ process.env,
+ );
+ return true;
+ } catch {
+ return false;
+ }
+ }
if (path.isAbsolute(trimmed) || hasPathSeparator(trimmed)) return pathExists(trimmed);
return (await findCommandOnPath(trimmed)) !== null;
}
@@ -197,6 +221,22 @@ async function resolveCodexAcpCommand(config: Record<string, unknown>): Promise<
);
}
+function sandboxTargetHasProcessSessionBridge(
+ target: ReturnType<typeof readAdapterExecutionTarget>,
+): boolean {
+ return target?.kind === "remote" && target.transport === "sandbox" && Boolean(target.runner);
+}
+
+async function resolveCodexAcpCommandForTarget(
+ config: Record<string, unknown>,
+ target: ReturnType<typeof readAdapterExecutionTarget>,
+): Promise<string> {
+ const configured = firstNonEmptyString(config.agentCommand, config.acpAgentCommand);
+ if (configured) return configured;
+ if (target?.kind === "remote") return "codex-acp";
+ return resolveCodexAcpCommand(config);
+}
+
async function defaultCodexAcpFallbackReason(
input: CodexEngineResolutionInput,
): Promise<string | null> {
@@ -204,14 +244,17 @@ async function defaultCodexAcpFallbackReason(
executionTarget: input.executionTarget,
legacyRemoteExecution: input.executionTransport?.remoteExecution,
});
- if (target?.kind === "remote") {
- return "Codex ACP currently supports only the local Paperclip host, but this run targets a remote environment.";
+ if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target)) {
+ if (target.transport === "sandbox") {
+ return "Codex ACP requires a bidirectional remote process target; this sandbox exposes only one-shot command execution.";
+ }
+ return "Codex ACP supports sandbox remote targets only; this run targets a non-sandbox remote environment.";
}
if (!nodeVersionMeetsCodexAcpMinimum()) {
return `Node ${process.version} does not satisfy Codex ACP's Node >=${MIN_ACP_NODE_VERSION} prerequisite.`;
}
- const command = await resolveCodexAcpCommand(input.config);
- if (!(await commandIsResolvable(command))) {
+ const command = await resolveCodexAcpCommandForTarget(input.config, target);
+ if (!(await commandIsResolvable(command, input))) {
return `Codex ACP server command is not available: ${command}.`;
}
return null;
@@ -257,10 +300,10 @@ export async function testCodexAcpEnvironment(
if (targetIsRemote) {
checks.push({
- code: "codex_acp_remote_target_unsupported",
- level: "error",
- message: "Codex ACP currently runs on the local Paperclip host and cannot target a remote execution environment.",
- hint: "Use engine=cli for remote or sandbox Codex runs.",
+ code: "codex_acp_remote_target",
+ level: "info",
+ message: "Codex ACP will run against the remote execution environment.",
+ hint: "Remote ACP requires a bidirectional process target such as SSH or Paperclip's sandbox process-session bridge.",
});
}
@@ -292,8 +335,11 @@ export async function testCodexAcpEnvironment(
: `Run Codex ACP with Node >=${MIN_ACP_NODE_VERSION} or switch engine=cli.`,
});
- const command = await resolveCodexAcpCommand(config);
- const commandResolvable = await commandIsResolvable(command);
+ const command = await resolveCodexAcpCommandForTarget(config, target);
+ const commandResolvable = await commandIsResolvable(command, {
+ config,
+ executionTarget: ctx.executionTarget,
+ });
checks.push({
code: commandResolvable ? "codex_acp_command_resolvable" : "codex_acp_command_missing",
level: commandResolvable ? "info" : "error",
diff --git a/packages/adapters/gemini-local/src/server/acp.test.ts b/packages/adapters/gemini-local/src/server/acp.test.ts
index 9f0a7cfdc0..6ec366c6b7 100644
--- a/packages/adapters/gemini-local/src/server/acp.test.ts
+++ b/packages/adapters/gemini-local/src/server/acp.test.ts
@@ -264,10 +264,11 @@ describe("gemini_local ACP lane", () => {
).resolves.toEqual({ engine: "acp", explicit: true });
});
- it("falls back to the CLI lane for remote auto runs", async () => {
+ it("falls back to the CLI lane for non-sandbox remote auto runs", async () => {
+ setNodeVersion("v20.0.0");
await expect(
resolveGeminiExecutionEngineForRun({
- config: {},
+ config: { agentCommand: "gemini --acp" },
executionTarget: {
kind: "remote",
transport: "ssh",
@@ -287,7 +288,55 @@ describe("gemini_local ACP lane", () => {
).resolves.toMatchObject({
engine: "cli",
explicit: false,
- fallbackReason: expect.stringContaining("remote environment"),
+ fallbackReason: expect.stringContaining("sandbox remote targets only"),
+ });
+ });
+
+ it("falls back to the CLI lane for one-shot sandbox auto runs", async () => {
+ setNodeVersion("v20.0.0");
+ await expect(
+ resolveGeminiExecutionEngineForRun({
+ config: {},
+ executionTarget: {
+ kind: "remote",
+ transport: "sandbox",
+ providerKey: "fake-plugin",
+ remoteCwd: "/work",
+ },
+ }),
+ ).resolves.toMatchObject({
+ engine: "cli",
+ explicit: false,
+ fallbackReason: expect.stringContaining("bidirectional remote process"),
+ });
+ });
+
+ it("uses ACP for bridged sandbox auto runs when the ACP command is configured as a shell command", async () => {
+ setNodeVersion("v20.0.0");
+ await expect(
+ resolveGeminiExecutionEngineForRun({
+ config: { agentCommand: "gemini --acp" },
+ executionTarget: {
+ kind: "remote",
+ transport: "sandbox",
+ providerKey: "fake-plugin",
+ remoteCwd: "/work",
+ runner: {
+ execute: async () => ({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: "",
+ stderr: "",
+ pid: null,
+ startedAt: new Date().toISOString(),
+ }),
+ },
+ },
+ }),
+ ).resolves.toEqual({
+ engine: "acp",
+ explicit: false,
});
});
diff --git a/packages/adapters/gemini-local/src/server/acp.ts b/packages/adapters/gemini-local/src/server/acp.ts
index f357933d67..bdedd2df43 100644
--- a/packages/adapters/gemini-local/src/server/acp.ts
+++ b/packages/adapters/gemini-local/src/server/acp.ts
@@ -8,7 +8,11 @@ import type {
AdapterExecutionContext,
AdapterExecutionResult,
} from "@paperclipai/adapter-utils";
-import { readAdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
+import {
+ ensureAdapterExecutionTargetCommandResolvable,
+ readAdapterExecutionTarget,
+ resolveAdapterExecutionTargetCwd,
+} from "@paperclipai/adapter-utils/execution-target";
import {
DEFAULT_ACP_ENGINE_MODE,
DEFAULT_ACP_ENGINE_NON_INTERACTIVE_PERMISSIONS,
@@ -183,9 +187,30 @@ function resolveConfigPath(config: Record<string, unknown>): string {
: process.env.PATH ?? "";
}
-async function commandIsResolvable(command: string, pathValue = process.env.PATH ?? ""): Promise<boolean> {
+async function commandIsResolvable(
+ command: string,
+ pathValue = process.env.PATH ?? "",
+ input?: GeminiEngineResolutionInput,
+): Promise<boolean> {
const token = firstShellToken(command);
if (!token) return true;
+ const target = readAdapterExecutionTarget({
+ executionTarget: input?.executionTarget,
+ legacyRemoteExecution: input?.executionTransport?.remoteExecution,
+ });
+ if (target?.kind === "remote") {
+ try {
+ await ensureAdapterExecutionTargetCommandResolvable(
+ token,
+ target,
+ resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()),
+ process.env,
+ );
+ return true;
+ } catch {
+ return false;
+ }
+ }
if (path.isAbsolute(token) || hasPathSeparator(token)) return pathExists(token);
return (await findCommandOnPath(token, pathValue)) !== null;
}
@@ -197,6 +222,12 @@ function resolveGeminiAcpCommand(config: Record<string, unknown>): string {
return `${geminiCommand} --acp`;
}
+function sandboxTargetHasProcessSessionBridge(
+ target: ReturnType<typeof readAdapterExecutionTarget>,
+): boolean {
+ return target?.kind === "remote" && target.transport === "sandbox" && Boolean(target.runner);
+}
+
async function defaultGeminiAcpFallbackReason(
input: GeminiEngineResolutionInput,
): Promise<string | null> {
@@ -204,14 +235,17 @@ async function defaultGeminiAcpFallbackReason(
executionTarget: input.executionTarget,
legacyRemoteExecution: input.executionTransport?.remoteExecution,
});
- if (target?.kind === "remote") {
- return "Gemini ACP currently supports only the local Paperclip host, but this run targets a remote environment.";
+ if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target)) {
+ if (target.transport === "sandbox") {
+ return "Gemini ACP requires a bidirectional remote process target; this sandbox exposes only one-shot command execution.";
+ }
+ return "Gemini ACP supports sandbox remote targets only; this run targets a non-sandbox remote environment.";
}
if (!nodeVersionMeetsGeminiAcpMinimum()) {
return `Node ${process.version} does not satisfy Gemini ACP's Node >=${MIN_ACP_NODE_VERSION} prerequisite.`;
}
const command = resolveGeminiAcpCommand(input.config);
- if (!(await commandIsResolvable(command, resolveConfigPath(input.config)))) {
+ if (!(await commandIsResolvable(command, resolveConfigPath(input.config), input))) {
return `Gemini ACP command is not available: ${command}.`;
}
return null;
@@ -244,10 +278,10 @@ export async function testGeminiAcpEnvironment(
if (targetIsRemote) {
checks.push({
- code: "gemini_acp_remote_target_unsupported",
- level: "error",
- message: "Gemini ACP currently runs on the local Paperclip host and cannot target a remote execution environment.",
- hint: "Use engine=cli for remote or sandbox Gemini runs.",
+ code: "gemini_acp_remote_target",
+ level: "info",
+ message: "Gemini ACP will run against the remote execution environment.",
+ hint: "Remote ACP requires a bidirectional process target such as SSH or Paperclip's sandbox process-session bridge.",
});
}
@@ -280,7 +314,10 @@ export async function testGeminiAcpEnvironment(
});
const command = resolveGeminiAcpCommand(config);
- const commandResolvable = await commandIsResolvable(command, resolveConfigPath(config));
+ const commandResolvable = await commandIsResolvable(command, resolveConfigPath(config), {
+ config,
+ executionTarget: ctx.executionTarget,
+ });
checks.push({
code: commandResolvable ? "gemini_acp_command_resolvable" : "gemini_acp_command_missing",
level: commandResolvable ? "info" : "error",
diff --git a/packages/adapters/gemini-local/src/server/execute.remote.test.ts b/packages/adapters/gemini-local/src/server/execute.remote.test.ts
index 0fcbcfffd7..2b307ae544 100644
--- a/packages/adapters/gemini-local/src/server/execute.remote.test.ts
+++ b/packages/adapters/gemini-local/src/server/execute.remote.test.ts
@@ -272,6 +272,9 @@ describe("gemini remote execution", () => {
taskKey: null,
},
config: {
+ // Pin the CLI lane: sandbox targets with a runner now default to ACP,
+ // and this test covers the CLI lane's managed-HOME auth flow.
+ engine: "cli",
command: "gemini",
env: { GEMINI_API_KEY: "test-key" },
},
diff --git a/packages/plugins/sandbox-providers/daytona/src/plugin.ts b/packages/plugins/sandbox-providers/daytona/src/plugin.ts
index 07e22516ac..aab0b293d3 100644
--- a/packages/plugins/sandbox-providers/daytona/src/plugin.ts
+++ b/packages/plugins/sandbox-providers/daytona/src/plugin.ts
@@ -901,7 +901,14 @@ const plugin = definePlugin({
});
return {
providerLeaseId: sandbox.id,
- metadata: leaseMetadata({ config, sandbox, shellCommand, remoteCwd, resumedLease: false, workspaceSentinel }),
+ metadata: leaseMetadata({
+ config,
+ sandbox,
+ shellCommand,
+ remoteCwd,
+ resumedLease: false,
+ workspaceSentinel,
+ }),
};
} catch (error) {
await sandbox.delete(toTimeoutSeconds(config.timeoutMs)).catch(() => undefined);
@@ -933,7 +940,14 @@ const plugin = definePlugin({
const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(config.timeoutMs));
return {
providerLeaseId: sandbox.id,
- metadata: leaseMetadata({ config, sandbox, shellCommand, remoteCwd, resumedLease: true, workspaceSentinel }),
+ metadata: leaseMetadata({
+ config,
+ sandbox,
+ shellCommand,
+ remoteCwd,
+ resumedLease: true,
+ workspaceSentinel,
+ }),
};
} catch (error) {
await sandbox.delete(toTimeoutSeconds(config.timeoutMs)).catch(() => undefined);
diff --git a/server/src/__tests__/environment-execution-target.test.ts b/server/src/__tests__/environment-execution-target.test.ts
index 6577abed16..a627f105ca 100644
--- a/server/src/__tests__/environment-execution-target.test.ts
+++ b/server/src/__tests__/environment-execution-target.test.ts
@@ -133,6 +133,49 @@ describe("resolveEnvironmentExecutionTarget", () => {
});
});
+ it("keeps sandbox targets on callback bridge execution even when lease metadata advertises SSH access", async () => {
+ mockResolveEnvironmentDriverConfigForRuntime.mockResolvedValue({
+ driver: "sandbox",
+ config: {
+ provider: "fake-plugin",
+ reuseLease: false,
+ timeoutMs: 30_000,
+ },
+ });
+
+ const target = await resolveEnvironmentExecutionTarget({
+ db: {} as never,
+ companyId: "company-1",
+ adapterType: "claude_local",
+ environment: {
+ id: "env-1",
+ driver: "sandbox",
+ config: {
+ provider: "fake-plugin",
+ },
+ },
+ leaseId: "lease-1",
+ leaseMetadata: {
+ remoteCwd: "/home/sandbox/paperclip-workspace",
+ sshAccess: {
+ type: "ssh",
+ host: "ssh.example.test",
+ port: 22,
+ username: "paperclip",
+ },
+ },
+ lease: null,
+ environmentRuntime: null,
+ });
+
+ expect(target).toMatchObject({
+ kind: "remote",
+ transport: "sandbox",
+ providerKey: "fake-plugin",
+ remoteCwd: "/home/sandbox/paperclip-workspace",
+ });
+ });
+
it("resolves SSH execution targets in bridge mode", async () => {
mockResolveEnvironmentDriverConfigForRuntime.mockResolvedValue({
driver: "ssh",