Skip to content

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

fix(runtime): support in-place workspace realization (#10230)

Dotta4e00818574ef
diff --git a/packages/adapter-utils/src/command-managed-runtime.test.ts b/packages/adapter-utils/src/command-managed-runtime.test.ts
index 2cd4d853a2..7dc7d3a02a 100644
--- a/packages/adapter-utils/src/command-managed-runtime.test.ts
+++ b/packages/adapter-utils/src/command-managed-runtime.test.ts
@@ -239,6 +239,60 @@ describe("command managed runtime", () => {
expect(calls.filter((call) => call.stdin != null).length).toBe(1);
});
+ it("stages runtime assets without replacing or restoring an in-place workspace", async () => {
+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-command-runtime-assets-only-"));
+ cleanupDirs.push(rootDir);
+
+ const localWorkspaceDir = path.join(rootDir, "local-workspace");
+ const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");
+ const localHomeDir = path.join(rootDir, "local-home");
+ await mkdir(localWorkspaceDir, { recursive: true });
+ await mkdir(remoteWorkspaceDir, { recursive: true });
+ await mkdir(localHomeDir, { recursive: true });
+ await writeFile(path.join(localWorkspaceDir, "README.md"), "local workspace\n", "utf8");
+ await writeFile(path.join(remoteWorkspaceDir, "README.md"), "authoritative workspace\n", "utf8");
+ await writeFile(path.join(localHomeDir, "auth.json"), '{"token":"host"}\n', "utf8");
+
+ const { runner } = makeSpawnRunner();
+ let restoredAuth = "";
+ const prepared = await prepareCommandManagedRuntime({
+ runner,
+ spec: {
+ remoteCwd: remoteWorkspaceDir,
+ timeoutMs: 30_000,
+ },
+ adapterKey: "codex",
+ workspaceLocalDir: localWorkspaceDir,
+ syncWorkspace: false,
+ assets: [
+ {
+ key: "home",
+ localDir: localHomeDir,
+ restore: async ({ assetDir, readFile }) => {
+ restoredAuth = (await readFile(path.join(assetDir, "auth.json"))).toString("utf8");
+ },
+ },
+ ],
+ });
+
+ expect(prepared.workspaceRemoteDir).toBe(remoteWorkspaceDir);
+ expect(prepared.assetDirs.home).toBe(path.join(remoteWorkspaceDir, ".paperclip-runtime", "codex", "home"));
+ await expect(readFile(path.join(remoteWorkspaceDir, "README.md"), "utf8")).resolves.toBe(
+ "authoritative workspace\n",
+ );
+ await expect(readFile(path.join(prepared.assetDirs.home, "auth.json"), "utf8")).resolves.toBe(
+ '{"token":"host"}\n',
+ );
+
+ await writeFile(path.join(prepared.assetDirs.home, "auth.json"), '{"token":"remote"}\n', "utf8");
+ await prepared.restoreWorkspace();
+
+ expect(restoredAuth).toBe('{"token":"remote"}\n');
+ await expect(readFile(path.join(localWorkspaceDir, "README.md"), "utf8")).resolves.toBe(
+ "local workspace\n",
+ );
+ });
+
it("runs setup commands from a stable root cwd when staging into a nested remote workspace dir", async () => {
const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-command-runtime-nested-"));
cleanupDirs.push(rootDir);
diff --git a/packages/adapter-utils/src/command-managed-runtime.ts b/packages/adapter-utils/src/command-managed-runtime.ts
index b8b3043cca..0e93ebb175 100644
--- a/packages/adapter-utils/src/command-managed-runtime.ts
+++ b/packages/adapter-utils/src/command-managed-runtime.ts
@@ -271,6 +271,7 @@ export async function prepareCommandManagedRuntime(input: {
adapterKey: string;
workspaceLocalDir: string;
workspaceRemoteDir?: string;
+ syncWorkspace?: boolean;
workspaceExclude?: string[];
preserveAbsentOnRestore?: string[];
assets?: CommandManagedRuntimeAsset[];
@@ -325,6 +326,7 @@ export async function prepareCommandManagedRuntime(input: {
adapterKey: input.adapterKey,
workspaceLocalDir: input.workspaceLocalDir,
workspaceRemoteDir,
+ syncWorkspace: input.syncWorkspace,
workspaceExclude: mergeRuntimeExcludes(input.workspaceExclude),
preserveAbsentOnRestore: input.preserveAbsentOnRestore,
assets: input.assets,
@@ -361,6 +363,7 @@ export async function prepareCommandManagedRuntime(input: {
adapterKey: input.adapterKey,
workspaceLocalDir: input.workspaceLocalDir,
workspaceRemoteDir,
+ syncWorkspace: input.syncWorkspace,
workspaceExclude: mergeRuntimeExcludes(input.workspaceExclude),
preserveAbsentOnRestore: input.preserveAbsentOnRestore,
assets: input.assets,
diff --git a/packages/adapter-utils/src/execution-target.ts b/packages/adapter-utils/src/execution-target.ts
index f70e8e01b4..b0a93bed05 100644
--- a/packages/adapter-utils/src/execution-target.ts
+++ b/packages/adapter-utils/src/execution-target.ts
@@ -42,13 +42,31 @@ import type { LocalProcessSandboxOptions } from "./local-process-sandbox.js";
export type { RuntimeProgressSink } from "./runtime-progress.js";
-export interface AdapterLocalExecutionTarget {
+export type AdapterWorkspaceRealizationMode = "copy" | "in_place";
+
+export interface AdapterWorkspacePathAlias {
+ path: string;
+ target: string;
+}
+
+export interface AdapterWorkspaceRealization {
+ mode: AdapterWorkspaceRealizationMode;
+ authoritativeRoot: string;
+ pathAliases: AdapterWorkspacePathAlias[];
+ outboundRestorePaths: string[];
+}
+
+interface AdapterExecutionTargetWorkspaceMetadata {
+ workspaceRealization?: AdapterWorkspaceRealization | null;
+}
+
+export interface AdapterLocalExecutionTarget extends AdapterExecutionTargetWorkspaceMetadata {
kind: "local";
environmentId?: string | null;
leaseId?: string | null;
}
-export interface AdapterSshExecutionTarget {
+export interface AdapterSshExecutionTarget extends AdapterExecutionTargetWorkspaceMetadata {
kind: "remote";
transport: "ssh";
environmentId?: string | null;
@@ -57,7 +75,7 @@ export interface AdapterSshExecutionTarget {
spec: SshRemoteExecutionSpec;
}
-export interface AdapterSandboxExecutionTarget {
+export interface AdapterSandboxExecutionTarget extends AdapterExecutionTargetWorkspaceMetadata {
kind: "remote";
transport: "sandbox";
providerKey?: string | null;
@@ -1084,6 +1102,7 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
workspaceLocalDir: string;
timeoutSec?: number;
workspaceRemoteDir?: string;
+ syncWorkspace?: boolean;
workspaceExclude?: string[];
preserveAbsentOnRestore?: string[];
assets?: AdapterManagedRuntimeAsset[];
@@ -1115,6 +1134,7 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
adapterKey: input.adapterKey,
workspaceLocalDir: input.workspaceLocalDir,
workspaceRemoteDir: input.workspaceRemoteDir,
+ syncWorkspace: input.syncWorkspace,
assets: input.assets,
onProgress: input.onProgress,
});
@@ -1142,6 +1162,7 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
adapterKey: input.adapterKey,
workspaceLocalDir: input.workspaceLocalDir,
workspaceRemoteDir: input.workspaceRemoteDir,
+ syncWorkspace: input.syncWorkspace,
workspaceExclude: input.workspaceExclude,
preserveAbsentOnRestore: input.preserveAbsentOnRestore,
assets: input.assets,
diff --git a/packages/adapter-utils/src/local-process-sandbox.test.ts b/packages/adapter-utils/src/local-process-sandbox.test.ts
index 17d6055b86..36b3f8a4d3 100644
--- a/packages/adapter-utils/src/local-process-sandbox.test.ts
+++ b/packages/adapter-utils/src/local-process-sandbox.test.ts
@@ -85,6 +85,46 @@ describe("local process sandbox", () => {
expect(target.args.slice(-3)).toEqual([process.execPath, "-e", "console.log('ok')"]);
});
+ it("binds a confined absolute alias to the synchronized workspace", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-fs-alias-"));
+ cleanup.push(root);
+ const workspace = path.join(root, "workspace");
+ await fs.mkdir(workspace);
+
+ const target = await buildLocalProcessSandboxSpawnTarget({
+ executable: process.execPath,
+ args: ["-e", "process.exit(0)"],
+ cwd: workspace,
+ options: {
+ workspaceDir: workspace,
+ filesystemScope: "workspace",
+ pathAliases: [{ path: "/app", target: workspace }],
+ },
+ });
+
+ expect(target.args).toEqual(expect.arrayContaining(["--bind", workspace, "/app"]));
+ });
+
+ it("rejects writable out-of-tree paths without an outbound restore mapping", async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-fs-outbound-"));
+ cleanup.push(root);
+ const workspace = path.join(root, "workspace");
+ const outside = path.join(root, "outside");
+ await fs.mkdir(workspace);
+ await fs.mkdir(outside);
+
+ await expect(buildLocalProcessSandboxSpawnTarget({
+ executable: process.execPath,
+ args: ["-e", "process.exit(0)"],
+ cwd: workspace,
+ options: {
+ workspaceDir: workspace,
+ filesystemScope: "workspace",
+ extraPaths: [{ path: outside, access: "rw" }],
+ },
+ })).rejects.toThrow("has no outbound restore mapping");
+ });
+
it("builds a network-only namespace without changing filesystem visibility", async () => {
const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-network-sandbox-"));
cleanup.push(workspace);
diff --git a/packages/adapter-utils/src/local-process-sandbox.ts b/packages/adapter-utils/src/local-process-sandbox.ts
index 971aec31d2..7015d2a4ba 100644
--- a/packages/adapter-utils/src/local-process-sandbox.ts
+++ b/packages/adapter-utils/src/local-process-sandbox.ts
@@ -12,11 +12,18 @@ export interface LocalProcessSandboxPath {
access: LocalProcessSandboxAccess;
}
+export interface LocalProcessSandboxPathAlias {
+ path: string;
+ target: string;
+}
+
export interface LocalProcessSandboxOptions {
workspaceDir: string;
filesystemScope?: "workspace" | null;
managedPaths?: LocalProcessSandboxPath[];
extraPaths?: LocalProcessSandboxPath[];
+ pathAliases?: LocalProcessSandboxPathAlias[];
+ outboundRestorePaths?: string[];
homeDir?: string | null;
networkScope?: LocalProcessNetworkScope | null;
networkAllowlist?: string[];
@@ -319,6 +326,23 @@ export async function buildLocalProcessSandboxSpawnTarget(input: {
if (relativeCwd.startsWith("..") || path.isAbsolute(relativeCwd)) {
throw new Error(`Sandbox cwd "${cwd}" must be inside workspaceDir "${workspaceDir}".`);
}
+ const outboundRestorePaths = (input.options.outboundRestorePaths ?? []).map((candidate, index) =>
+ normalizeAbsolutePath(candidate, `Sandbox outboundRestorePaths[${index}]`));
+ for (const [index, extraPath] of (input.options.extraPaths ?? []).entries()) {
+ if (extraPath.access !== "rw") continue;
+ const normalizedExtraPath = normalizeAbsolutePath(extraPath.path, `Sandbox extraPaths[${index}].path`);
+ const relativeToWorkspace = path.relative(workspaceDir, normalizedExtraPath);
+ const synchronized = !relativeToWorkspace.startsWith("..") && !path.isAbsolute(relativeToWorkspace);
+ const restored = outboundRestorePaths.some((restorePath) => {
+ const relative = path.relative(restorePath, normalizedExtraPath);
+ return !relative.startsWith("..") && !path.isAbsolute(relative);
+ });
+ if (!synchronized && !restored) {
+ throw new Error(
+ `Writable sandbox path "${normalizedExtraPath}" is outside synchronized workspace "${workspaceDir}" and has no outbound restore mapping.`,
+ );
+ }
+ }
}
const bwrapCommand = input.options.command?.trim() || "bwrap";
@@ -354,6 +378,22 @@ export async function buildLocalProcessSandboxSpawnTarget(input: {
for (const managedPath of input.options.managedPaths ?? []) await mount(managedPath.path, managedPath.access);
for (const extraPath of input.options.extraPaths ?? []) await mount(extraPath.path, extraPath.access);
await mount(workspaceDir, "rw");
+ for (const [index, alias] of (input.options.pathAliases ?? []).entries()) {
+ const aliasPath = normalizeAbsolutePath(alias.path, `Sandbox pathAliases[${index}].path`);
+ const aliasTarget = normalizeAbsolutePath(alias.target, `Sandbox pathAliases[${index}].target`);
+ const relativeTarget = path.relative(workspaceDir, aliasTarget);
+ if (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget)) {
+ throw new Error(
+ `Sandbox path alias "${aliasPath}" must target the synchronized workspace "${workspaceDir}".`,
+ );
+ }
+ if (!(await pathExists(aliasTarget))) {
+ throw new Error(`Sandbox path alias target "${aliasTarget}" does not exist.`);
+ }
+ addParentDirectories(args, created, aliasPath);
+ args.push("--bind", aliasTarget, aliasPath);
+ created.add(aliasPath);
+ }
if (networkScope === "allowlist") {
const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-network-sandbox-"));
diff --git a/packages/adapter-utils/src/remote-managed-runtime.test.ts b/packages/adapter-utils/src/remote-managed-runtime.test.ts
new file mode 100644
index 0000000000..0d0c98fb0e
--- /dev/null
+++ b/packages/adapter-utils/src/remote-managed-runtime.test.ts
@@ -0,0 +1,95 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const {
+ prepareWorkspaceForSshExecution,
+ restoreWorkspaceFromSshExecution,
+ runSshCommand,
+ syncDirectoryToSsh,
+} = vi.hoisted(() => ({
+ prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
+ restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
+ runSshCommand: vi.fn(async () => ({
+ stdout: Buffer.from('{"token":"remote"}\n').toString("base64"),
+ stderr: "",
+ })),
+ syncDirectoryToSsh: vi.fn(async () => undefined),
+}));
+
+vi.mock("./ssh.js", () => ({
+ prepareWorkspaceForSshExecution,
+ restoreWorkspaceFromSshExecution,
+ runSshCommand,
+ syncDirectoryToSsh,
+}));
+
+import { prepareRemoteManagedRuntime } from "./remote-managed-runtime.js";
+
+describe("remote managed runtime", () => {
+ const cleanupDirs: string[] = [];
+
+ afterEach(async () => {
+ vi.clearAllMocks();
+ while (cleanupDirs.length > 0) {
+ const dir = cleanupDirs.pop();
+ if (!dir) continue;
+ await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+ }
+ });
+
+ it("restores runtime assets without restoring an in-place SSH workspace", async () => {
+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-remote-runtime-assets-only-"));
+ cleanupDirs.push(rootDir);
+ const workspaceDir = path.join(rootDir, "workspace");
+ const homeDir = path.join(rootDir, "home");
+ await mkdir(workspaceDir, { recursive: true });
+ await mkdir(homeDir, { recursive: true });
+ await writeFile(path.join(homeDir, "auth.json"), '{"token":"host"}\n', "utf8");
+
+ let restoredAuth = "";
+ const prepared = await prepareRemoteManagedRuntime({
+ spec: {
+ host: "127.0.0.1",
+ port: 2222,
+ username: "fixture",
+ remoteWorkspacePath: "/app",
+ remoteCwd: "/app",
+ privateKey: "PRIVATE KEY",
+ knownHosts: "KNOWN HOSTS",
+ strictHostKeyChecking: true,
+ },
+ runId: "run-in-place",
+ adapterKey: "codex",
+ workspaceLocalDir: workspaceDir,
+ workspaceRemoteDir: "/app",
+ syncWorkspace: false,
+ assets: [
+ {
+ key: "home",
+ localDir: homeDir,
+ restore: async ({ assetDir, readFile }) => {
+ restoredAuth = (await readFile(path.posix.join(assetDir, "auth.json"))).toString("utf8");
+ },
+ },
+ ],
+ });
+
+ expect(prepareWorkspaceForSshExecution).not.toHaveBeenCalled();
+ expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({
+ localDir: homeDir,
+ remoteDir: "/app/.paperclip-runtime/codex/home",
+ }));
+
+ await prepared.restoreWorkspace();
+
+ expect(restoreWorkspaceFromSshExecution).not.toHaveBeenCalled();
+ expect(runSshCommand).toHaveBeenCalledWith(
+ expect.anything(),
+ "base64 < '/app/.paperclip-runtime/codex/home/auth.json'",
+ { maxBuffer: 1024 * 1024 },
+ );
+ expect(restoredAuth).toBe('{"token":"remote"}\n');
+ });
+});
diff --git a/packages/adapter-utils/src/remote-managed-runtime.ts b/packages/adapter-utils/src/remote-managed-runtime.ts
index 88bb9c53fd..6d8cd3aa4b 100644
--- a/packages/adapter-utils/src/remote-managed-runtime.ts
+++ b/packages/adapter-utils/src/remote-managed-runtime.ts
@@ -3,9 +3,11 @@ import { GIT_ARCHIVE_EXCLUDES } from "./git-workspace-sync.js";
import {
type SshRemoteExecutionSpec,
prepareWorkspaceForSshExecution,
+ runSshCommand,
restoreWorkspaceFromSshExecution,
syncDirectoryToSsh,
} from "./ssh.js";
+import type { SandboxManagedRuntimeAssetRestoreContext } from "./sandbox-managed-runtime.js";
import { captureDirectorySnapshot } from "./workspace-restore-merge.js";
import type { RuntimeProgressSink } from "./runtime-progress.js";
@@ -14,6 +16,7 @@ export interface RemoteManagedRuntimeAsset {
localDir: string;
followSymlinks?: boolean;
exclude?: string[];
+ restore?: (ctx: SandboxManagedRuntimeAssetRestoreContext) => Promise<void>;
}
export interface PreparedRemoteManagedRuntime {
@@ -39,6 +42,17 @@ function asNumber(value: unknown): number {
return typeof value === "number" ? value : Number(value);
}
+function shellQuote(value: string): string {
+ return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+async function readRemoteFile(spec: SshRemoteExecutionSpec, remotePath: string): Promise<Buffer> {
+ const result = await runSshCommand(spec, `base64 < ${shellQuote(remotePath)}`, {
+ maxBuffer: 1024 * 1024,
+ });
+ return Buffer.from(result.stdout.replace(/\s+/g, ""), "base64");
+}
+
export function buildRemoteExecutionSessionIdentity(spec: SshRemoteExecutionSpec | null) {
if (!spec) return null;
return {
@@ -70,31 +84,40 @@ export async function prepareRemoteManagedRuntime(input: {
adapterKey: string;
workspaceLocalDir: string;
workspaceRemoteDir?: string;
+ syncWorkspace?: boolean;
assets?: RemoteManagedRuntimeAsset[];
// Upload progress sink. Threaded for the byte-counting transport rewrite; the
// child task wires it into the workspace/asset transfers.
onProgress?: RuntimeProgressSink;
}): Promise<PreparedRemoteManagedRuntime> {
const baseWorkspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;
- const workspaceRemoteDir = path.posix.join(
- baseWorkspaceRemoteDir,
- ".paperclip-runtime",
- "runs",
- input.runId,
- "workspace",
- );
+ const syncWorkspace = input.syncWorkspace !== false;
+ const workspaceRemoteDir = syncWorkspace
+ ? path.posix.join(
+ baseWorkspaceRemoteDir,
+ ".paperclip-runtime",
+ "runs",
+ input.runId,
+ "workspace",
+ )
+ : baseWorkspaceRemoteDir;
const runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);
- const preparedWorkspace = await prepareWorkspaceForSshExecution({
- spec: input.spec,
- localDir: input.workspaceLocalDir,
- remoteDir: workspaceRemoteDir,
- onProgress: input.onProgress,
- });
- const restoreExclude = preparedWorkspace.gitBacked ? [...GIT_ARCHIVE_EXCLUDES, ".paperclip-runtime"] : [".paperclip-runtime"];
- const baselineSnapshot = await captureDirectorySnapshot(input.workspaceLocalDir, {
- exclude: restoreExclude,
- });
+ const preparedWorkspace = syncWorkspace
+ ? await prepareWorkspaceForSshExecution({
+ spec: input.spec,
+ localDir: input.workspaceLocalDir,
+ remoteDir: workspaceRemoteDir,
+ onProgress: input.onProgress,
+ })
+ : null;
+ const baselineSnapshot = preparedWorkspace
+ ? await captureDirectorySnapshot(input.workspaceLocalDir, {
+ exclude: preparedWorkspace.gitBacked
+ ? [...GIT_ARCHIVE_EXCLUDES, ".paperclip-runtime"]
+ : [".paperclip-runtime"],
+ })
+ : null;
const assetDirs: Record<string, string> = {};
try {
@@ -112,14 +135,16 @@ export async function prepareRemoteManagedRuntime(input: {
});
}
} catch (error) {
- await restoreWorkspaceFromSshExecution({
- spec: input.spec,
- localDir: input.workspaceLocalDir,
- remoteDir: workspaceRemoteDir,
- baselineSnapshot,
- restoreGitHistory: preparedWorkspace.gitBacked,
- onProgress: input.onProgress,
- });
+ if (preparedWorkspace && baselineSnapshot) {
+ await restoreWorkspaceFromSshExecution({
+ spec: input.spec,
+ localDir: input.workspaceLocalDir,
+ remoteDir: workspaceRemoteDir,
+ baselineSnapshot,
+ restoreGitHistory: preparedWorkspace.gitBacked,
+ onProgress: input.onProgress,
+ });
+ }
throw error;
}
@@ -130,14 +155,23 @@ export async function prepareRemoteManagedRuntime(input: {
runtimeRootDir,
assetDirs,
restoreWorkspace: async (onProgress?: RuntimeProgressSink) => {
- await restoreWorkspaceFromSshExecution({
- spec: input.spec,
- localDir: input.workspaceLocalDir,
- remoteDir: workspaceRemoteDir,
- baselineSnapshot,
- restoreGitHistory: preparedWorkspace.gitBacked,
- onProgress,
- });
+ if (preparedWorkspace && baselineSnapshot) {
+ await restoreWorkspaceFromSshExecution({
+ spec: input.spec,
+ localDir: input.workspaceLocalDir,
+ remoteDir: workspaceRemoteDir,
+ baselineSnapshot,
+ restoreGitHistory: preparedWorkspace.gitBacked,
+ onProgress,
+ });
+ }
+ for (const asset of input.assets ?? []) {
+ if (!asset.restore) continue;
+ await asset.restore({
+ assetDir: path.posix.join(runtimeRootDir, asset.key),
+ readFile: (remotePath) => readRemoteFile(input.spec, remotePath),
+ });
+ }
},
};
}
diff --git a/packages/adapter-utils/src/sandbox-managed-runtime.ts b/packages/adapter-utils/src/sandbox-managed-runtime.ts
index 62bf2cf7d7..9eae6aadf3 100644
--- a/packages/adapter-utils/src/sandbox-managed-runtime.ts
+++ b/packages/adapter-utils/src/sandbox-managed-runtime.ts
@@ -561,6 +561,7 @@ export async function prepareSandboxManagedRuntime(input: {
client: SandboxManagedRuntimeClient;
workspaceLocalDir: string;
workspaceRemoteDir?: string;
+ syncWorkspace?: boolean;
workspaceExclude?: string[];
preserveAbsentOnRestore?: string[];
assets?: SandboxManagedRuntimeAsset[];
@@ -571,7 +572,8 @@ export async function prepareSandboxManagedRuntime(input: {
}): Promise<PreparedSandboxManagedRuntime> {
const workspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;
const runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);
- const gitSnapshot = await readGitWorkspaceSnapshot(input.workspaceLocalDir);
+ const syncWorkspace = input.syncWorkspace !== false;
+ const gitSnapshot = syncWorkspace ? await readGitWorkspaceSnapshot(input.workspaceLocalDir) : null;
const gitIgnoredExcludes = gitSnapshot?.ignoredPaths;
const workspaceArchiveExclude = mergeExcludes(
SANDBOX_WORKSPACE_HEAVY_DIR_EXCLUDES,
@@ -587,9 +589,9 @@ export async function prepareSandboxManagedRuntime(input: {
input.workspaceExclude,
gitIgnoredExcludes,
);
- const baselineSnapshot = await captureDirectorySnapshot(input.workspaceLocalDir, {
- exclude: restoreExclude,
- });
+ const baselineSnapshot = syncWorkspace
+ ? await captureDirectorySnapshot(input.workspaceLocalDir, { exclude: restoreExclude })
+ : null;
// Prefer the provider's native file transport when it advertised the sync
// verbs; otherwise every branch below falls back to the byte-identical tar +
@@ -606,7 +608,7 @@ export async function prepareSandboxManagedRuntime(input: {
...(gitSnapshot ? [".git"] : []),
...(input.preserveAbsentOnRestore ?? []),
]);
- if (gitSnapshot) {
+ if (syncWorkspace && gitSnapshot) {
await emitRuntimeStatus(input.onRuntimeProgress, "git_sync", "Syncing git history to sandbox");
await withShallowGitWorkspaceClone({
localDir: input.workspaceLocalDir,
@@ -648,57 +650,59 @@ export async function prepareSandboxManagedRuntime(input: {
});
}
- const workspaceTarPath = path.join(tempDir, "workspace.tar");
- const workspaceArchiveDir = gitSnapshot ? path.join(tempDir, "workspace-overlay") : input.workspaceLocalDir;
- await emitRuntimeStatus(input.onRuntimeProgress, "config_sync", "Syncing workspace to sandbox");
- if (gitSnapshot) {
- await copySelectedWorkspaceEntries({
- sourceDir: input.workspaceLocalDir,
- targetDir: workspaceArchiveDir,
- relativePaths: gitSnapshot.overlayPaths,
- exclude: workspaceArchiveExclude,
- });
- }
- await createTarballFromDirectory({
- localDir: workspaceArchiveDir,
- archivePath: workspaceTarPath,
- exclude: gitSnapshot ? undefined : workspaceArchiveExclude,
- });
- const workspaceTarBytes = await fs.readFile(workspaceTarPath);
- const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-upload.tar");
- await input.client.makeDir(runtimeRootDir);
- const workspaceUpload = makeTransferProgress(
- input.onProgress,
- "Syncing",
- "to",
- "workspace",
- { sink: input.onRuntimeProgress, phase: "config_sync" },
- );
- await input.client.writeFile(
- remoteWorkspaceTar,
- toArrayBuffer(workspaceTarBytes),
- workspaceUpload.options,
- );
- await workspaceUpload.finish(workspaceTarBytes.byteLength, workspaceTarBytes.byteLength);
- const extractWorkspaceTarCommand = gitSnapshot
- ? `mkdir -p ${shellQuote(workspaceRemoteDir)} && ` +
- `tar -xf ${shellQuote(remoteWorkspaceTar)} -C ${shellQuote(workspaceRemoteDir)} && ` +
- `rm -f ${shellQuote(remoteWorkspaceTar)}`
- : `mkdir -p ${shellQuote(workspaceRemoteDir)} && ` +
- `find ${shellQuote(workspaceRemoteDir)} -mindepth 1 -maxdepth 1 ${preserveFindArgs([...preservedNames])} -exec rm -rf -- {} + && ` +
- `tar -xf ${shellQuote(remoteWorkspaceTar)} -C ${shellQuote(workspaceRemoteDir)} && ` +
- `rm -f ${shellQuote(remoteWorkspaceTar)}`;
- await input.client.run(
- `sh -c ${shellQuote(extractWorkspaceTarCommand)}`,
- { timeoutMs: input.spec.timeoutMs },
- );
- if (gitSnapshot) {
- await removeDeletedPathsInSandbox({
- client: input.client,
- spec: input.spec,
- remoteDir: workspaceRemoteDir,
- deletedPaths: gitSnapshot.deletedPaths,
+ if (syncWorkspace) {
+ const workspaceTarPath = path.join(tempDir, "workspace.tar");
+ const workspaceArchiveDir = gitSnapshot ? path.join(tempDir, "workspace-overlay") : input.workspaceLocalDir;
+ await emitRuntimeStatus(input.onRuntimeProgress, "config_sync", "Syncing workspace to sandbox");
+ if (gitSnapshot) {
+ await copySelectedWorkspaceEntries({
+ sourceDir: input.workspaceLocalDir,
+ targetDir: workspaceArchiveDir,
+ relativePaths: gitSnapshot.overlayPaths,
+ exclude: workspaceArchiveExclude,
+ });
+ }
+ await createTarballFromDirectory({
+ localDir: workspaceArchiveDir,
+ archivePath: workspaceTarPath,
+ exclude: gitSnapshot ? undefined : workspaceArchiveExclude,
});
+ const workspaceTarBytes = await fs.readFile(workspaceTarPath);
+ const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-upload.tar");
+ await input.client.makeDir(runtimeRootDir);
+ const workspaceUpload = makeTransferProgress(
+ input.onProgress,
+ "Syncing",
+ "to",
+ "workspace",
+ { sink: input.onRuntimeProgress, phase: "config_sync" },
+ );
+ await input.client.writeFile(
+ remoteWorkspaceTar,
+ toArrayBuffer(workspaceTarBytes),
+ workspaceUpload.options,
+ );
+ await workspaceUpload.finish(workspaceTarBytes.byteLength, workspaceTarBytes.byteLength);
+ const extractWorkspaceTarCommand = gitSnapshot
+ ? `mkdir -p ${shellQuote(workspaceRemoteDir)} && ` +
+ `tar -xf ${shellQuote(remoteWorkspaceTar)} -C ${shellQuote(workspaceRemoteDir)} && ` +
+ `rm -f ${shellQuote(remoteWorkspaceTar)}`
+ : `mkdir -p ${shellQuote(workspaceRemoteDir)} && ` +
+ `find ${shellQuote(workspaceRemoteDir)} -mindepth 1 -maxdepth 1 ${preserveFindArgs([...preservedNames])} -exec rm -rf -- {} + && ` +
+ `tar -xf ${shellQuote(remoteWorkspaceTar)} -C ${shellQuote(workspaceRemoteDir)} && ` +
+ `rm -f ${shellQuote(remoteWorkspaceTar)}`;
+ await input.client.run(
+ `sh -c ${shellQuote(extractWorkspaceTarCommand)}`,
+ { timeoutMs: input.spec.timeoutMs },
+ );
+ if (gitSnapshot) {
+ await removeDeletedPathsInSandbox({
+ client: input.client,
+ spec: input.spec,
+ remoteDir: workspaceRemoteDir,
+ deletedPaths: gitSnapshot.deletedPaths,
+ });
+ }
}
for (const asset of input.assets ?? []) {
@@ -793,6 +797,16 @@ export async function prepareSandboxManagedRuntime(input: {
assetDirs,
restoreWorkspace: async (onProgress?: RuntimeProgressSink) => {
const restoreSink = onProgress ?? input.onProgress;
+ if (!syncWorkspace) {
+ for (const asset of input.assets ?? []) {
+ if (!asset.restore) continue;
+ await asset.restore({
+ assetDir: path.posix.join(runtimeRootDir, asset.key),
+ readFile: async (remotePath) => toBuffer(await input.client.readFile(remotePath)),
+ });
+ }
+ return;
+ }
await withTempDir("paperclip-sandbox-restore-", async (tempDir) => {
let importedRef: string | null = null;
let importedHead: string | null = null;
@@ -902,7 +916,7 @@ export async function prepareSandboxManagedRuntime(input: {
}
const gitHeadToIntegrate = importedHead;
await mergeDirectoryWithBaseline({
- baseline: baselineSnapshot,
+ baseline: baselineSnapshot!,
sourceDir: extractedDir,
targetDir: input.workspaceLocalDir,
beforeApply: gitHeadToIntegrate
diff --git a/packages/adapters/codex-local/src/server/acp.test.ts b/packages/adapters/codex-local/src/server/acp.test.ts
index 9af33f26c3..b789542efa 100644
--- a/packages/adapters/codex-local/src/server/acp.test.ts
+++ b/packages/adapters/codex-local/src/server/acp.test.ts
@@ -347,6 +347,30 @@ describe("codex_local ACP lane", () => {
).rejects.toThrow('filesystemScope must be "workspace"');
});
+ it("selects the CLI lane for in-place realization and rejects explicitly required ACP", async () => {
+ const executionTarget = {
+ kind: "remote" as const,
+ transport: "sandbox" as const,
+ remoteCwd: "/app",
+ workspaceRealization: {
+ mode: "in_place" as const,
+ authoritativeRoot: "/app",
+ pathAliases: [],
+ outboundRestorePaths: [],
+ },
+ };
+ await expect(
+ resolveCodexExecutionEngineForRun({ config: {}, executionTarget }),
+ ).resolves.toMatchObject({
+ engine: "cli",
+ explicit: false,
+ fallbackReason: expect.stringContaining("without ACP archive staging"),
+ });
+ await expect(
+ resolveCodexExecutionEngineForRun({ config: { engine: "acp" }, executionTarget }),
+ ).rejects.toThrow("In-place workspace realization requires the Codex CLI engine");
+ });
+
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(
diff --git a/packages/adapters/codex-local/src/server/acp.ts b/packages/adapters/codex-local/src/server/acp.ts
index cf543a2a4e..351ce5d1c1 100644
--- a/packages/adapters/codex-local/src/server/acp.ts
+++ b/packages/adapters/codex-local/src/server/acp.ts
@@ -81,6 +81,22 @@ export async function resolveCodexExecutionEngineForRun(
input: CodexEngineResolutionInput,
): Promise<CodexEngineSelection> {
const selection = normalizeEngine(input.config.engine);
+ const target = readAdapterExecutionTarget({
+ executionTarget: input.executionTarget,
+ legacyRemoteExecution: input.executionTransport?.remoteExecution,
+ });
+ if (target?.workspaceRealization?.mode === "in_place") {
+ if (selection.explicit && selection.engine === "acp") {
+ throw new Error("In-place workspace realization requires the Codex CLI engine; ACP archive staging is not supported.");
+ }
+ return {
+ engine: "cli",
+ explicit: selection.explicit,
+ ...(!selection.explicit
+ ? { fallbackReason: "In-place workspace realization must run without ACP archive staging." }
+ : {}),
+ };
+ }
const filesystemScope = parseLocalProcessFilesystemScope(input.config.filesystemScope);
const networkScope = parseLocalProcessNetworkScope(input.config.networkScope);
if (filesystemScope || networkScope) {
diff --git a/packages/adapters/codex-local/src/server/codex-auth-copyback.test.ts b/packages/adapters/codex-local/src/server/codex-auth-copyback.test.ts
index 18b706b075..4aff672ddb 100644
--- a/packages/adapters/codex-local/src/server/codex-auth-copyback.test.ts
+++ b/packages/adapters/codex-local/src/server/codex-auth-copyback.test.ts
@@ -197,6 +197,25 @@ describe("copyBackCodexAuth", () => {
}
});
+ it("creates a missing shared Codex home before staging copy-back", async () => {
+ const rootDir = await makeHostDir();
+ const hostDir = path.join(rootDir, "missing-codex-home");
+ const hostAuthPath = path.join(hostDir, "auth.json");
+ const logs: string[] = [];
+
+ const outcome = await copyBackCodexAuth({
+ readSandboxAuth: async () => Buffer.from(apiKeyAuth("sandbox-only"), "utf8"),
+ hostAuthPath,
+ log: (line) => {
+ logs.push(line);
+ },
+ });
+
+ expect(outcome).toBe("kept-host");
+ expect(await readdir(hostDir)).toEqual([]);
+ expect(logs.join("\n")).not.toContain("sandbox-only");
+ });
+
it("preserves the host file atomically when the install cannot be staged (no partial write, no leaked temp)", async () => {
// Make the host directory read-only so staging the same-filesystem temp fails
// with EACCES. The host credential must be left byte-for-byte intact and no
diff --git a/packages/adapters/codex-local/src/server/codex-auth-copyback.ts b/packages/adapters/codex-local/src/server/codex-auth-copyback.ts
index f2649ef28d..bf960701b7 100644
--- a/packages/adapters/codex-local/src/server/codex-auth-copyback.ts
+++ b/packages/adapters/codex-local/src/server/codex-auth-copyback.ts
@@ -1,5 +1,5 @@
import { execFile as execFileCallback } from "node:child_process";
-import { open, rename, rm } from "node:fs/promises";
+import { mkdir, open, rename, rm } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
@@ -115,6 +115,7 @@ export async function copyBackCodexAuth(input: CopyBackCodexAuthInput): Promise<
}
const hostDir = path.dirname(hostAuthPath);
+ await mkdir(hostDir, { recursive: true });
return withDirectoryMergeLock(hostDir, async () => {
// Stage on the same filesystem as the host target so both the predicate read
// and the final rename stay device-local (rename across devices is not
diff --git a/packages/adapters/codex-local/src/server/execute.remote.test.ts b/packages/adapters/codex-local/src/server/execute.remote.test.ts
index 44c2ed036d..4be867d325 100644
--- a/packages/adapters/codex-local/src/server/execute.remote.test.ts
+++ b/packages/adapters/codex-local/src/server/execute.remote.test.ts
@@ -9,6 +9,7 @@ const {
resolveCommandForLogs,
prepareWorkspaceForSshExecution,
restoreWorkspaceFromSshExecution,
+ runSshCommand,
syncDirectoryToSsh,
startAdapterExecutionTargetPaperclipBridge,
} = vi.hoisted(() => ({
@@ -25,6 +26,7 @@ const {
resolveCommandForLogs: vi.fn(async () => "/usr/bin/codex"),
prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
+ runSshCommand: vi.fn(async () => ({ stdout: Buffer.from("{}").toString("base64"), stderr: "" })),
syncDirectoryToSsh: vi.fn(async () => undefined),
startAdapterExecutionTargetPaperclipBridge: vi.fn(async () => ({
env: {
@@ -56,6 +58,7 @@ vi.mock("@paperclipai/adapter-utils/ssh", async () => {
...actual,
prepareWorkspaceForSshExecution,
restoreWorkspaceFromSshExecution,
+ runSshCommand,
syncDirectoryToSsh,
};
});
@@ -545,4 +548,73 @@ describe("codex remote execution", () => {
expect(call?.[3].env.CODEX_HOME).toBe(`${managedRemoteWorkspace}/.paperclip-runtime/codex/home`);
expect(call?.[3].remoteExecution?.remoteCwd).toBe(managedRemoteWorkspace);
});
+
+ it("runs in place at the authoritative root without archive prepare or restore", async () => {
+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-codex-in-place-"));
+ cleanupDirs.push(rootDir);
+ const workspaceDir = path.join(rootDir, "workspace");
+ const codexHomeDir = path.join(rootDir, "codex-home");
+ await mkdir(workspaceDir, { recursive: true });
+ await mkdir(codexHomeDir, { recursive: true });
+ await writeFile(path.join(codexHomeDir, "auth.json"), "{}", "utf8");
+
+ await execute({
+ runId: "run-in-place",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "CodexCoder",
+ adapterType: "codex_local",
+ adapterConfig: {},
+ },
+ runtime: { sessionId: null, sessionParams: null, sessionDisplayId: null, taskKey: null },
+ config: { command: "codex", env: { CODEX_HOME: codexHomeDir } },
+ context: {
+ paperclipWorkspace: {
+ cwd: workspaceDir,
+ source: "task_session",
+ },
+ },
+ executionTarget: {
+ kind: "remote",
+ transport: "ssh",
+ remoteCwd: "/copied/workspace",
+ workspaceRealization: {
+ mode: "in_place",
+ authoritativeRoot: "/app",
+ pathAliases: [],
+ outboundRestorePaths: [],
+ },
+ spec: {
+ host: "127.0.0.1",
+ port: 2222,
+ username: "fixture",
+ remoteWorkspacePath: "/app",
+ remoteCwd: "/app",
+ privateKey: "PRIVATE KEY",
+ knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",
+ strictHostKeyChecking: true,
+ },
+ },
+ onLog: async () => {},
+ });
+
+ expect(prepareWorkspaceForSshExecution).not.toHaveBeenCalled();
+ expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);
+ expect(restoreWorkspaceFromSshExecution).not.toHaveBeenCalled();
+ const homeSyncArgs = (syncDirectoryToSsh.mock.calls[0] as unknown[])?.[0] as {
+ localDir: string;
+ remoteDir: string;
+ };
+ expect(homeSyncArgs.localDir).toContain("paperclip-codex-home-sync");
+ expect(homeSyncArgs.remoteDir).toBe("/app/.paperclip-runtime/codex/home");
+ const call = runChildProcess.mock.calls[0] as unknown as
+ | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]
+ | undefined;
+ expect(call?.[3].env.PAPERCLIP_WORKSPACE_CWD).toBe("/app");
+ expect(call?.[3].env.PAPERCLIP_WORKSPACE_REALIZATION_MODE).toBe("in_place");
+ expect(call?.[3].env.PAPERCLIP_WORKSPACE_AUTHORITATIVE_ROOT).toBe("/app");
+ expect(call?.[3].env.CODEX_HOME).toBe("/app/.paperclip-runtime/codex/home");
+ expect(call?.[3].remoteExecution?.remoteCwd).toBe("/app");
+ });
});
diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.ts
index 7284c4dc92..966f681583 100644
--- a/packages/adapters/codex-local/src/server/execute.ts
+++ b/packages/adapters/codex-local/src/server/execute.ts
@@ -495,15 +495,18 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
)
: [];
const runtimePrimaryUrl = asString(context.paperclipRuntimePrimaryUrl, "");
- const configuredCwd = asString(config.cwd, "");
- const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
- const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
- const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
- const envConfig = parseObject(config.env);
const executionTarget = readAdapterExecutionTarget({
executionTarget: ctx.executionTarget,
legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
});
+ const targetWorkspaceRealization = executionTarget?.workspaceRealization ?? null;
+ const configuredCwd = asString(config.cwd, "");
+ const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
+ const effectiveWorkspaceCwd = targetWorkspaceRealization?.mode === "in_place"
+ ? targetWorkspaceRealization.authoritativeRoot
+ : useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
+ const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+ const envConfig = parseObject(config.env);
const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
const configuredCodexHome =
typeof envConfig.CODEX_HOME === "string" && envConfig.CODEX_HOME.trim().length > 0
@@ -511,7 +514,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
: null;
const codexSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredSkillNames = resolveCodexDesiredSkillNames(config, codexSkillEntries);
- await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+ if (!executionTargetIsRemote) {
+ await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+ }
const configuredOpenAiApiKey =
typeof envConfig.OPENAI_API_KEY === "string" && envConfig.OPENAI_API_KEY.trim().length > 0
? envConfig.OPENAI_API_KEY.trim()
@@ -620,12 +625,14 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
asNumber(config.timeoutSec, 0),
);
const graceSec = asNumber(config.graceSec, 20);
- let effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
+ let effectiveExecutionCwd = targetWorkspaceRealization?.mode === "in_place"
+ ? targetWorkspaceRealization.authoritativeRoot
+ : adapterExecutionTargetRemoteCwd(executionTarget, cwd);
const preparedExecutionTargetRuntime = executionTargetIsRemote
? await (async () => {
await onLog(
"stdout",
- `[paperclip] Syncing workspace and CODEX_HOME to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
+ `[paperclip] Syncing ${targetWorkspaceRealization?.mode === "in_place" ? "CODEX_HOME" : "workspace and CODEX_HOME"} to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
);
// Stage only the files Codex actually needs into a curated temp dir and
// ship THAT as the `home` asset, instead of the whole managed
@@ -642,6 +649,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
adapterKey: "codex",
timeoutSec,
workspaceLocalDir: cwd,
+ workspaceRemoteDir:
+ targetWorkspaceRealization?.mode === "in_place"
+ ? targetWorkspaceRealization.authoritativeRoot
+ : undefined,
+ syncWorkspace: targetWorkspaceRealization?.mode !== "in_place",
installCommand: SANDBOX_INSTALL_COMMAND,
detectCommand: command,
onProgress: (line) => onLog("stdout", line),
@@ -770,6 +782,10 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
executionTargetIsRemote,
executionCwd: effectiveExecutionCwd,
});
+ if (targetWorkspaceRealization) {
+ env.PAPERCLIP_WORKSPACE_REALIZATION_MODE = targetWorkspaceRealization.mode;
+ env.PAPERCLIP_WORKSPACE_AUTHORITATIVE_ROOT = targetWorkspaceRealization.authoritativeRoot;
+ }
if (runtimeServiceIntents.length > 0) {
env.PAPERCLIP_RUNTIME_SERVICE_INTENTS_JSON = JSON.stringify(runtimeServiceIntents);
}
@@ -812,6 +828,10 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
filesystemScope,
managedPaths: [{ path: effectiveCodexHome, access: "rw" }],
extraPaths: parseLocalProcessSandboxExtraPaths(config.filesystemExtraPaths),
+ pathAliases: targetWorkspaceRealization?.mode === "copy"
+ ? targetWorkspaceRealization.pathAliases
+ : [],
+ outboundRestorePaths: targetWorkspaceRealization?.outboundRestorePaths ?? [],
homeDir: filesystemScope ? effectiveCodexHome : null,
networkScope,
networkAllowlist: parseLocalProcessNetworkAllowlist(config.networkAllowlist),
diff --git a/packages/shared/src/types/workspace-runtime.ts b/packages/shared/src/types/workspace-runtime.ts
index c53be28db1..04e3c1e07f 100644
--- a/packages/shared/src/types/workspace-runtime.ts
+++ b/packages/shared/src/types/workspace-runtime.ts
@@ -297,6 +297,12 @@ export interface WorkspaceRuntimeService {
}
export type WorkspaceRealizationTransport = "local" | "ssh" | "sandbox" | "plugin";
+export type WorkspaceRealizationMode = "copy" | "in_place";
+
+export interface WorkspaceRealizationPathAlias {
+ path: string;
+ target: string;
+}
export type WorkspaceRealizationSyncStrategy =
| "none"
@@ -334,6 +340,10 @@ export interface WorkspaceRealizationRequest {
export interface WorkspaceRealizationRecord {
version: 1;
+ mode: WorkspaceRealizationMode;
+ authoritativeRoot: string;
+ pathAliases: WorkspaceRealizationPathAlias[];
+ outboundRestorePaths: string[];
transport: WorkspaceRealizationTransport;
provider: string | null;
environmentId: string;
diff --git a/server/src/__tests__/environment-run-orchestrator.test.ts b/server/src/__tests__/environment-run-orchestrator.test.ts
index c4dbb58b7e..41c2640c1d 100644
--- a/server/src/__tests__/environment-run-orchestrator.test.ts
+++ b/server/src/__tests__/environment-run-orchestrator.test.ts
@@ -186,6 +186,10 @@ function makeMockRuntime(overrides: Partial<EnvironmentRuntimeService> = {}): En
metadata: {
workspaceRealization: {
version: 1,
+ mode: "copy",
+ authoritativeRoot: "/workspace/project",
+ pathAliases: [],
+ outboundRestorePaths: [],
driver: "local",
cwd: "/workspace/project",
},
@@ -254,7 +258,15 @@ describe("environmentRunOrchestrator — realizeForRun", () => {
const result = await orchestrator.realizeForRun(makeRealizeInput());
expect(result.lease).toBeDefined();
- expect(result.executionTarget).toEqual(executionTarget);
+ expect(result.executionTarget).toEqual({
+ ...executionTarget,
+ workspaceRealization: {
+ mode: "copy",
+ authoritativeRoot: "/workspace/project",
+ pathAliases: [],
+ outboundRestorePaths: [],
+ },
+ });
expect(result.remoteExecution).toEqual(remoteExecution);
expect(result.workspaceRealization).toEqual(
expect.objectContaining({ version: 1, driver: "local" }),
@@ -264,6 +276,45 @@ describe("environmentRunOrchestrator — realizeForRun", () => {
expect(mockResolveEnvironmentExecutionTarget).toHaveBeenCalledOnce();
});
+ it("uses an in-place authoritative root on the adapter execution target", async () => {
+ mockResolveEnvironmentExecutionTarget.mockResolvedValue({
+ kind: "remote",
+ transport: "sandbox",
+ remoteCwd: "/copied/workspace",
+ });
+ const runtime = makeMockRuntime({
+ realizeWorkspace: vi.fn().mockResolvedValue({
+ cwd: "/app",
+ metadata: {
+ workspaceRealization: {
+ version: 1,
+ mode: "in_place",
+ authoritativeRoot: "/app",
+ pathAliases: [],
+ outboundRestorePaths: [],
+ },
+ },
+ }),
+ });
+ const orchestrator = environmentRunOrchestrator(mockDb, { environmentRuntime: runtime });
+
+ const result = await orchestrator.realizeForRun(
+ makeRealizeInput({ environment: makeEnvironment("sandbox") }),
+ );
+
+ expect(result.executionTarget).toEqual(expect.objectContaining({
+ kind: "remote",
+ transport: "sandbox",
+ remoteCwd: "/app",
+ workspaceRealization: {
+ mode: "in_place",
+ authoritativeRoot: "/app",
+ pathAliases: [],
+ outboundRestorePaths: [],
+ },
+ }));
+ });
+
it("realization failure: runtime.realizeWorkspace throws → EnvironmentRunError with code workspace_realization_failed", async () => {
const runtime = makeMockRuntime({
realizeWorkspace: vi.fn().mockRejectedValue(new Error("sandbox unreachable")),
diff --git a/server/src/services/environment-run-orchestrator.ts b/server/src/services/environment-run-orchestrator.ts
index c1b3656974..7ebad63739 100644
--- a/server/src/services/environment-run-orchestrator.ts
+++ b/server/src/services/environment-run-orchestrator.ts
@@ -40,6 +40,7 @@ import {
adapterExecutionTargetToRemoteSpec,
type AdapterExecutionTarget,
type AdapterRemoteExecutionSpec,
+ type AdapterWorkspaceRealization,
} from "@paperclipai/adapter-utils/execution-target";
import { buildWorkspaceRealizationRequest } from "./workspace-realization.js";
import { executionWorkspaceService } from "./execution-workspaces.js";
@@ -485,6 +486,35 @@ export function environmentRunOrchestrator(
lease,
environmentRuntime,
});
+ const realizationMode = workspaceRealization.mode === "in_place" ? "in_place" : "copy";
+ const authoritativeRoot =
+ typeof workspaceRealization.authoritativeRoot === "string" && workspaceRealization.authoritativeRoot.trim().length > 0
+ ? workspaceRealization.authoritativeRoot.trim()
+ : realizedCwd;
+ const workspaceTargetMetadata: AdapterWorkspaceRealization = {
+ mode: realizationMode,
+ authoritativeRoot,
+ pathAliases: Array.isArray(workspaceRealization.pathAliases)
+ ? workspaceRealization.pathAliases.filter(
+ (entry): entry is { path: string; target: string } =>
+ typeof entry === "object" && entry !== null &&
+ typeof (entry as { path?: unknown }).path === "string" &&
+ typeof (entry as { target?: unknown }).target === "string",
+ )
+ : [],
+ outboundRestorePaths: Array.isArray(workspaceRealization.outboundRestorePaths)
+ ? workspaceRealization.outboundRestorePaths.filter((entry): entry is string => typeof entry === "string")
+ : [],
+ };
+ if (executionTarget) {
+ executionTarget = {
+ ...executionTarget,
+ ...(executionTarget.kind === "remote" && realizationMode === "in_place"
+ ? { remoteCwd: authoritativeRoot }
+ : {}),
+ workspaceRealization: workspaceTargetMetadata,
+ } as AdapterExecutionTarget;
+ }
} catch (err) {
throw new EnvironmentRunError(
"transport_resolution_failed",
diff --git a/server/src/services/workspace-realization.ts b/server/src/services/workspace-realization.ts
index 66e8745342..ff9374a0b9 100644
--- a/server/src/services/workspace-realization.ts
+++ b/server/src/services/workspace-realization.ts
@@ -21,6 +21,22 @@ function readNumber(value: unknown): number | null {
return typeof value === "number" && Number.isFinite(value) ? value : null;
}
+function readStringArray(value: unknown): string[] {
+ return Array.isArray(value)
+ ? value.map(readString).filter((entry): entry is string => entry !== null)
+ : [];
+}
+
+function readPathAliases(value: unknown): Array<{ path: string; target: string }> {
+ if (!Array.isArray(value)) return [];
+ return value.flatMap((entry) => {
+ const parsed = parseObject(entry);
+ const aliasPath = readString(parsed.path);
+ const target = readString(parsed.target);
+ return aliasPath && target ? [{ path: aliasPath, target }] : [];
+ });
+}
+
function readWorkspaceRealizationRequest(value: unknown): WorkspaceRealizationRequest | null {
const parsed = parseObject(value);
if (parsed.version !== 1) return null;
@@ -129,9 +145,23 @@ export function buildWorkspaceRealizationRecord(input: {
const port = readNumber(leaseMetadata.port);
const username = readString(leaseMetadata.username);
const sandboxId = readString(leaseMetadata.sandboxId) ?? readString(providerMetadata.sandboxId);
+ const realizationMetadata = {
+ ...parseObject(leaseMetadata.workspaceRealization),
+ ...parseObject(providerMetadata.workspaceRealization),
+ ...providerMetadata,
+ };
+ const mode = realizationMetadata.mode === "in_place" || realizationMetadata.realizationMode === "in_place"
+ ? "in_place" as const
+ : "copy" as const;
+ const authoritativeRoot =
+ readString(realizationMetadata.authoritativeRoot) ??
+ (mode === "in_place" ? remotePath : null) ??
+ input.request.source.localPath;
+ const pathAliases = readPathAliases(realizationMetadata.pathAliases ?? realizationMetadata.workspaceAliases);
+ const outboundRestorePaths = readStringArray(realizationMetadata.outboundRestorePaths);
const sync = (() => {
- if (transport === "local") {
+ if (mode === "in_place" || transport === "local") {
return {
strategy: "none" as const,
prepare: "Use the realized local execution workspace directly.",
@@ -174,6 +204,10 @@ export function buildWorkspaceRealizationRecord(input: {
return {
version: 1,
+ mode,
+ authoritativeRoot,
+ pathAliases,
+ outboundRestorePaths,
transport,
provider,
environmentId: input.environment.id,