The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(sandbox): declare and collect the advisory read-write intent (#10521)
Nicky Leach5cffd5c72eec
diff --git a/packages/adapter-utils/src/sandbox-managed-runtime.test.ts b/packages/adapter-utils/src/sandbox-managed-runtime.test.tsindex 63cabb0932..db796761f2 100644--- a/packages/adapter-utils/src/sandbox-managed-runtime.test.ts+++ b/packages/adapter-utils/src/sandbox-managed-runtime.test.ts@@ -93,6 +93,41 @@ function attachNativeRecordingSyncIn(};}+// A capturing `syncIn` that records every operation for assertion and+// materializes file AND directory mappings. A directory mapping (a referenced+// project) uses `mirrorDirectory`, so a test can assert the advisory `access`+// intent on directory mappings as well as file mappings.+function attachCapturingSyncIn(+ client: SandboxManagedRuntimeClient,+ captured: SandboxSyncOperation[],+): void {+ client.syncIn = async (operations: SandboxSyncOperation[]): Promise<SandboxSyncResult> => {+ const resultOperations: SandboxSyncResult["operations"] = [];+ for (const operation of operations) {+ captured.push(operation);+ let filesTransferred = 0;+ let bytesTransferred = 0;+ for (const mapping of operation.files) {+ await mkdir(path.posix.dirname(mapping.targetPath), { recursive: true });+ if (mapping.kind === "directory") {+ await mirrorDirectory(mapping.sourcePath, mapping.targetPath);+ } else {+ const bytes = await readFile(mapping.sourcePath);+ await writeFile(mapping.targetPath, bytes);+ if (mapping.mode != null) await fsPromises.chmod(mapping.targetPath, mapping.mode);+ bytesTransferred += bytes.byteLength;+ }+ filesTransferred += 1;+ }+ for (const command of operation.postUploadCommands ?? []) {+ await execFile("sh", ["-c", command.command], { maxBuffer: 32 * 1024 * 1024 });+ }+ resultOperations.push({ operationId: operation.operationId, filesTransferred, bytesTransferred });+ }+ return { operations: resultOperations };+ };+}+vi.mock("node:fs", async (importOriginal) => {const actual = await importOriginal<typeof import("node:fs")>();return {@@ -1282,6 +1317,18 @@ describe("sandbox managed runtime", () => {`rm -rf ${q(path.posix.join(prepared.runtimeRootDir, "widget"))} && mkdir -p ${q(path.posix.join(prepared.runtimeRootDir, "widget"))}`,);+ // The asset tar carries the asset directory as its read-write destination,+ // because the extract command fills that directory, not the staging archive.+ const assetTarMapping = assetOp!.files.find((mapping) => mapping.targetPath.endsWith("widget-upload.tar"));+ expect(assetTarMapping?.access).toBe("rw");+ expect(assetTarMapping?.writablePath).toBe(prepared.assetDirs.widget);++ // The staged helper file is a read-only input that the command consumes, so+ // it is `access: "ro"` and never joins the writable set.+ const stageMapping = assetOp!.files.find((mapping) => mapping.targetPath.endsWith("widget-helper.sh"));+ expect(stageMapping?.access).toBe("ro");+ expect(stageMapping?.writablePath).toBeUndefined();+// The asset actually materialized through the native seam.await expect(readFile(path.join(prepared.assetDirs.widget, "seed.txt"), "utf8")).resolves.toBe("seed\n");});@@ -1643,6 +1690,137 @@ describe("sandbox managed runtime", () => {.resolves.toBe("{\"OPENAI_API_KEY\":\"sk-test\"}\n");});+ it("authors the advisory access intent rw on workspace, git, and asset inbound mappings", async () => {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-access-rw-"));+ cleanupDirs.push(rootDir);+ const sourceRepoDir = path.join(rootDir, "source-repo");+ const localWorkspaceDir = path.join(rootDir, "local-workspace");+ const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");+ const assetDir = path.join(rootDir, "asset-home");++ // A git-backed workspace produces both a git-history tar and an overlay tar.+ await mkdir(sourceRepoDir, { recursive: true });+ await git(sourceRepoDir, ["init"]);+ await git(sourceRepoDir, ["checkout", "-b", "main"]);+ await git(sourceRepoDir, ["config", "user.name", "Paperclip Test"]);+ await git(sourceRepoDir, ["config", "user.email", "[email protected]"]);+ await writeFile(path.join(sourceRepoDir, "tracked.txt"), "tracked\n", "utf8");+ await git(sourceRepoDir, ["add", "tracked.txt"]);+ await git(sourceRepoDir, ["commit", "-m", "base"]);+ await git(sourceRepoDir, ["worktree", "add", "-b", "work", localWorkspaceDir, "HEAD"]);++ await mkdir(assetDir, { recursive: true });+ await writeFile(path.join(assetDir, "config.toml"), "model = \"gpt\"\n", "utf8");++ const client: SandboxManagedRuntimeClient = {+ makeDir: async (remotePath) => { await mkdir(remotePath, { recursive: true }); },+ writeFile: async (remotePath, bytes) => {+ await mkdir(path.dirname(remotePath), { recursive: true });+ await writeFile(remotePath, Buffer.from(bytes));+ },+ readFile: async (remotePath) => await readFile(remotePath),+ listFiles: async () => [],+ remove: async (remotePath) => { await rm(remotePath, { recursive: true, force: true }); },+ run: async (command) => { await execFile("sh", ["-c", command], { maxBuffer: 32 * 1024 * 1024 }); },+ };+ const captured: SandboxSyncOperation[] = [];+ attachCapturingSyncIn(client, captured);++ await prepareSandboxManagedRuntime({+ spec: {+ transport: "sandbox",+ provider: "test",+ sandboxId: "sandbox-1",+ remoteCwd: remoteWorkspaceDir,+ timeoutMs: 30_000,+ apiKey: null,+ },+ adapterKey: "test-adapter",+ client,+ workspaceLocalDir: localWorkspaceDir,+ assets: [{ key: "home", localDir: assetDir }],+ });++ const findMapping = (base: string) =>+ captured+ .flatMap((op) => op.files)+ .find((mapping) => path.posix.basename(mapping.targetPath) === base);++ // The workspace, git-history, and asset destinations receive read-write bytes,+ // so the author marks each mapping `access: "rw"`.+ expect(findMapping("workspace-upload.tar")?.access).toBe("rw");+ expect(findMapping("git-workspace-upload.tar")?.access).toBe("rw");+ expect(findMapping("home-upload.tar")?.access).toBe("rw");++ // Each tar mapping uploads a staging archive under the runtime root, so its+ // `targetPath` is not the read-write destination. `writablePath` names the+ // directory that the post-upload extract command fills: the workspace+ // directory for the workspace and git tars, and the asset directory for the+ // asset tar.+ const remoteAssetDir = path.posix.join(remoteWorkspaceDir, ".paperclip-runtime", "test-adapter", "home");+ expect(findMapping("workspace-upload.tar")?.writablePath).toBe(remoteWorkspaceDir);+ expect(findMapping("git-workspace-upload.tar")?.writablePath).toBe(remoteWorkspaceDir);+ expect(findMapping("home-upload.tar")?.writablePath).toBe(remoteAssetDir);+ });++ it("authors the advisory access intent ro on referenced-project inbound mappings", async () => {+ const flagKey = "PAPERCLIP_MULTI_PROJECT_WORKSPACE_SYNC";+ const priorFlag = process.env[flagKey];+ process.env[flagKey] = "1";+ try {+ const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-access-ro-"));+ cleanupDirs.push(rootDir);+ const localWorkspaceDir = path.join(rootDir, "local-workspace");+ const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");+ const referencedDir = path.join(rootDir, "referenced-project");+ await mkdir(localWorkspaceDir, { recursive: true });+ await mkdir(referencedDir, { recursive: true });+ await writeFile(path.join(localWorkspaceDir, "README.md"), "anchor\n", "utf8");+ await writeFile(path.join(referencedDir, "notes.md"), "reference\n", "utf8");++ const client: SandboxManagedRuntimeClient = {+ makeDir: async (remotePath) => { await mkdir(remotePath, { recursive: true }); },+ writeFile: async (remotePath, bytes) => {+ await mkdir(path.dirname(remotePath), { recursive: true });+ await writeFile(remotePath, Buffer.from(bytes));+ },+ readFile: async (remotePath) => await readFile(remotePath),+ listFiles: async () => [],+ remove: async (remotePath) => { await rm(remotePath, { recursive: true, force: true }); },+ run: async (command) => { await execFile("sh", ["-c", command], { maxBuffer: 32 * 1024 * 1024 }); },+ };+ const captured: SandboxSyncOperation[] = [];+ attachCapturingSyncIn(client, captured);++ await prepareSandboxManagedRuntime({+ spec: {+ transport: "sandbox",+ provider: "test",+ sandboxId: "sandbox-1",+ remoteCwd: remoteWorkspaceDir,+ timeoutMs: 30_000,+ apiKey: null,+ },+ adapterKey: "test-adapter",+ client,+ workspaceLocalDir: localWorkspaceDir,+ additionalSources: [{ localPath: referencedDir, projectId: "proj-first" }],+ });++ const referencedMapping = captured+ .flatMap((op) => op.files)+ .find((mapping) => path.posix.basename(mapping.targetPath) === "project-proj-first");++ // A referenced project is a read-only tree, so the author marks it `access: "ro"`.+ expect(referencedMapping).toBeDefined();+ expect(referencedMapping?.kind).toBe("directory");+ expect(referencedMapping?.access).toBe("ro");+ } finally {+ if (priorFlag === undefined) delete process.env[flagKey];+ else process.env[flagKey] = priorFlag;+ }+ });+it("keeps the sandbox runtime core free of Codex-specific string literals", async () => {const coreSource = await readFile(new URL("./sandbox-managed-runtime.ts", import.meta.url), "utf8");// The seam must be generic: no adapter (Codex) knowledge may live in the core.diff --git a/packages/adapter-utils/src/sandbox-managed-runtime.ts b/packages/adapter-utils/src/sandbox-managed-runtime.tsindex ae6d433c75..0cff256464 100644--- a/packages/adapter-utils/src/sandbox-managed-runtime.ts+++ b/packages/adapter-utils/src/sandbox-managed-runtime.ts@@ -161,6 +161,24 @@ export interface SandboxSyncFileMapping {mode?: number;exclude?: string[];followSymlinks?: boolean;+ /**+ * Advisory read-write intent for the sandbox target. `"rw"` marks a target the+ * agent may change and keep; `"ro"` marks a read-only tree. An absent value+ * defaults to `"ro"` (read-only is the safe default for an advisory signal).+ * The field is advisory metadata for an optional sandbox feedback wrapper. It+ * does not change the transfer and adds no security.+ */+ access?: "rw" | "ro";+ /**+ * The sandbox directory that becomes read-write when `access` is `"rw"` and a+ * post-upload command extracts `targetPath` into a different directory. A tar+ * mapping uploads an archive under the runtime root, so its `targetPath` is the+ * staging archive, not the directory the extract command fills. This field+ * names that final destination directory. When absent, the read-write+ * destination is the parent directory of `targetPath`. Advisory; ignored when+ * `access` is not `"rw"`.+ */+ writablePath?: string;}/**@@ -816,7 +834,7 @@ export async function prepareSandboxManagedRuntime(input: {exclude: [".paperclip-runtime"],});});- workspaceFiles.push({ sourcePath: gitTarPath, targetPath: remoteGitTar, kind: "file" });+ workspaceFiles.push({ sourcePath: gitTarPath, targetPath: remoteGitTar, kind: "file", access: "rw", writablePath: workspaceRemoteDir });workspacePostUploadCommands.push({command: buildWorkspaceTarExtractCommand({workspaceRemoteDir,@@ -847,7 +865,7 @@ export async function prepareSandboxManagedRuntime(input: {exclude: gitSnapshot ? undefined : workspaceArchiveExclude,});const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-upload.tar");- workspaceFiles.push({ sourcePath: workspaceTarPath, targetPath: remoteWorkspaceTar, kind: "file" });+ workspaceFiles.push({ sourcePath: workspaceTarPath, targetPath: remoteWorkspaceTar, kind: "file", access: "rw", writablePath: workspaceRemoteDir });workspacePostUploadCommands.push({command: buildWorkspaceTarExtractCommand({workspaceRemoteDir,@@ -898,7 +916,7 @@ export async function prepareSandboxManagedRuntime(input: {exclude: asset.exclude,});const files: SandboxSyncFileMapping[] = [- { sourcePath: assetTarPath, targetPath: remoteAssetTar, kind: "file" },+ { sourcePath: assetTarPath, targetPath: remoteAssetTar, kind: "file", access: "rw", writablePath: remoteAssetDir },];// Stage provision helper files (e.g. the merge scripts) into the temp dir// and map them alongside the asset tar so they ride the same native upload.@@ -912,10 +930,14 @@ export async function prepareSandboxManagedRuntime(input: {: stageFile.contents;const stageHostPath = path.join(tempDir, `${asset.key}.stage.${safeName}`);await fs.writeFile(stageHostPath, stageBytes);+ // A stage helper file (for example a merge script) is a read-only input+ // that the provision command reads; the agent does not change it and does+ // not keep it. So it is `access: "ro"` and never joins the writable set.files.push({sourcePath: stageHostPath,targetPath: path.posix.join(runtimeRootDir, safeName),kind: "file",+ access: "ro",});}const postUploadCommand = asset.provision?.postUploadCommand?.({@@ -967,6 +989,7 @@ export async function prepareSandboxManagedRuntime(input: {targetPath: remoteProjectDir,kind: "directory",exclude: additionalSourceExclude,+ access: "ro",}],sourceRoots: [localPath],targetRoots: [remoteProjectDir],diff --git a/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts b/packages/plugins/sandbox-providers/daytona/src/plugin.test.tsindex df19124bfc..868261d5d3 100644--- a/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts+++ b/packages/plugins/sandbox-providers/daytona/src/plugin.test.ts@@ -32,6 +32,7 @@ import plugin, {setDaytonaTimingClockForTest,setDaytonaHandleFreshnessClockForTest,__resetDaytonaSandboxHandleCacheForTest,+ __getDaytonaWritableDirsForTest,} from "./plugin.js";import manifest from "./manifest.js";@@ -2200,6 +2201,124 @@ describe("daytona native file-sync hooks", () => {expect(plugin.definition.onEnvironmentSyncOut).toBeTypeOf("function");});+ it("records the writablePath destination of a staging-tar rw mapping, not the staging parent", async () => {+ const hostDir = await makeHostDir();+ const source = path.join(hostDir, "workspace.tar");+ await fs.writeFile(source, "bytes");++ const sandbox = createMockSandbox();+ mockGet.mockResolvedValue(sandbox);++ const params = {+ driverKey: "daytona",+ companyId: "company-1",+ environmentId: "env-1",+ config: { timeoutMs: 300000, reuseLease: false },+ lease: syncLease(),+ operations: [+ {+ operationId: "sync-op-rw",+ files: [+ {+ // The mapping uploads a staging tar under the runtime root, and a+ // post-upload command extracts it into the workspace directory. So+ // `writablePath` names the real read-write destination.+ sourcePath: source,+ targetPath: `${REMOTE_DIR}/.paperclip-runtime/workspace-upload.tar`,+ kind: "file" as const,+ access: "rw" as const,+ writablePath: REMOTE_DIR,+ },+ ],+ },+ ],+ };+ await plugin.definition.onEnvironmentSyncIn?.(params);++ // The set holds the extract destination, not the staging archive parent.+ const recorded = __getDaytonaWritableDirsForTest(params);+ expect(recorded).toContain(REMOTE_DIR);+ expect(recorded).not.toContain(`${REMOTE_DIR}/.paperclip-runtime`);+ });++ it("falls back to the parent directory of an rw mapping with no writablePath", async () => {+ const hostDir = await makeHostDir();+ const source = path.join(hostDir, "in-place.txt");+ await fs.writeFile(source, "bytes");++ const sandbox = createMockSandbox();+ mockGet.mockResolvedValue(sandbox);++ const params = {+ driverKey: "daytona",+ companyId: "company-1",+ environmentId: "env-1",+ config: { timeoutMs: 300000, reuseLease: false },+ lease: syncLease(),+ operations: [+ {+ operationId: "sync-op-rw-inplace",+ files: [+ {+ // No post-upload extract, so the mapping writes `targetPath` in+ // place and the parent directory is the read-write destination.+ sourcePath: source,+ targetPath: `${REMOTE_DIR}/data/in-place.txt`,+ kind: "file" as const,+ access: "rw" as const,+ },+ ],+ },+ ],+ };+ await plugin.definition.onEnvironmentSyncIn?.(params);++ expect(__getDaytonaWritableDirsForTest(params)).toContain(`${REMOTE_DIR}/data`);+ });++ it("skips ro and access-absent sync targets in the advisory writable set", async () => {+ const hostDir = await makeHostDir();+ const roSource = path.join(hostDir, "referenced");+ const defaultSource = path.join(hostDir, "default.tar");+ await fs.mkdir(roSource, { recursive: true });+ await fs.writeFile(path.join(roSource, "notes.md"), "reference");+ await fs.writeFile(defaultSource, "bytes");++ const sandbox = createMockSandbox();+ mockGet.mockResolvedValue(sandbox);++ const params = {+ driverKey: "daytona",+ companyId: "company-1",+ environmentId: "env-1",+ config: { timeoutMs: 300000, reuseLease: false },+ lease: syncLease(),+ operations: [+ {+ operationId: "sync-op-ro",+ files: [+ {+ sourcePath: roSource,+ targetPath: `${REMOTE_DIR}/.paperclip-runtime/project-proj-first`,+ kind: "directory" as const,+ access: "ro" as const,+ },+ {+ // An absent `access` defaults to read-only, so it is not recorded.+ sourcePath: defaultSource,+ targetPath: `${REMOTE_DIR}/.paperclip-runtime/default-upload.tar`,+ kind: "file" as const,+ },+ ],+ },+ ],+ };+ await plugin.definition.onEnvironmentSyncIn?.(params);++ // Neither the ro directory nor the access-absent file directory is recorded.+ expect(__getDaytonaWritableDirsForTest(params)).toEqual([]);+ });+it("syncIn coalesces file mappings into one uploadFiles batch to reserved temp destinations, then one batched mv, applying secret mode via setFilePermissions before the rename", async () => {const hostDir = await makeHostDir();const secretSource = path.join(hostDir, "auth.json");diff --git a/packages/plugins/sandbox-providers/daytona/src/plugin.ts b/packages/plugins/sandbox-providers/daytona/src/plugin.tsindex e92366d28a..4efc06bf09 100644--- a/packages/plugins/sandbox-providers/daytona/src/plugin.ts+++ b/packages/plugins/sandbox-providers/daytona/src/plugin.ts@@ -36,6 +36,7 @@ import type {PluginEnvironmentSyncResult,PluginEnvironmentValidateConfigParams,PluginEnvironmentValidationResult,+ PluginSyncOperation,} from "@paperclipai/plugin-sdk";import { performSyncIn, performSyncOut } from "./file-sync.js";@@ -1096,6 +1097,55 @@ const sandboxHandleCache = (() => {return { get, seed, clear, reset, markFresh };})();+// Advisory writable-set store. It holds, per lease scope, the sandbox+// directories that a sync operation declared read-write (`access: "rw"`). An+// optional sandbox feedback wrapper reads this set later to bind those+// directories read-write, so an agent gets real-time feedback when a write to a+// non-persistent path fails. The store is advisory and best-effort in-memory+// state: it adds no security (the ephemeral sandbox stays the only boundary),+// and a cold store (for example after a worker restart) degrades to the+// workspace baseline, never to a crash. The store is keyed the same way as+// `sandboxHandleCache`, by `sandboxHandleCacheKey(scope)`.+const sandboxHandleWritableDirs = (() => {+ const dirsByKey = new Map<string, Set<string>>();++ // Record the read-write destination directory of every `access: "rw"`+ // mapping. Skip read-only mappings (`access` absent or `"ro"`). Read-only is+ // the safe default for an advisory signal.+ //+ // A workspace, git-history, or asset mapping uploads a tar archive, so its+ // `targetPath` is the staging archive under the runtime root, not the directory+ // that the post-upload extract command fills. For those mappings the author+ // sets `writablePath` to the final destination directory, so this records the+ // real read-write destination, not the staging parent. When `writablePath` is+ // absent the mapping writes `targetPath` in place, so the parent directory of+ // `targetPath` is the destination.+ function recordWritableTargets(scope: SandboxScope, operations: PluginSyncOperation[]): void {+ const key = sandboxHandleCacheKey(scope);+ for (const operation of operations) {+ for (const mapping of operation.files) {+ if (mapping.access !== "rw") continue;+ let dirs = dirsByKey.get(key);+ if (!dirs) {+ dirs = new Set<string>();+ dirsByKey.set(key, dirs);+ }+ dirs.add(mapping.writablePath ?? path.posix.dirname(mapping.targetPath));+ }+ }+ }++ function get(scope: SandboxScope): ReadonlySet<string> {+ return dirsByKey.get(sandboxHandleCacheKey(scope)) ?? new Set<string>();+ }++ function reset(): void {+ dirsByKey.clear();+ }++ return { recordWritableTargets, get, reset };+})();+/*** Test seam: clear the process-scoped handle cache between tests so a handle* memoized under a reused composite key in one test never leaks into the next.@@ -1106,6 +1156,29 @@ export function __resetDaytonaSandboxHandleCacheForTest(): void {sandboxHandleTeardownGates.reset();sandboxHandleActivityGates.reset();sandboxHandleLeaseAdmissionStates.reset();+ sandboxHandleWritableDirs.reset();+}++/**+ * Test seam: read the advisory writable directories recorded for a sync scope.+ * The caller passes the same `onEnvironmentSyncIn` inputs, so this rebuilds the+ * exact scope key the hook used. Not used in production.+ */+export function __getDaytonaWritableDirsForTest(input: {+ driverKey: string;+ companyId: string;+ environmentId: string;+ lease: { providerLeaseId?: string | null };+ config: Record<string, unknown>;+}): string[] {+ const scope: SandboxScope = {+ driverKey: input.driverKey,+ companyId: input.companyId,+ environmentId: input.environmentId,+ providerLeaseId: input.lease.providerLeaseId ?? "",+ config: parseDriverConfig(input.config),+ };+ return [...sandboxHandleWritableDirs.get(scope)];}async function getSandbox(scope: SandboxScope, options: SandboxLookupOptions = {}): Promise<Sandbox> {@@ -1874,6 +1947,9 @@ const plugin = definePlugin({providerLeaseId: params.lease.providerLeaseId,config,};+ // Collect the advisory read-write destinations for this scope. This records+ // intent only; it does not change the transfer below.+ sandboxHandleWritableDirs.recordWritableTargets(scope, params.operations);return await withSandboxActivityGate(scope, async () => {const sandbox = await getSandbox(scope, { bypassTeardownGate: true });await ensureSandboxStarted(sandbox, timeoutSeconds);diff --git a/packages/plugins/sdk/src/protocol.ts b/packages/plugins/sdk/src/protocol.tsindex d9b78d416b..f85446a83c 100644--- a/packages/plugins/sdk/src/protocol.ts+++ b/packages/plugins/sdk/src/protocol.ts@@ -691,6 +691,30 @@ export interface PluginSyncFileMapping {* as links; `true` dereferences them to their target bytes. Mirrors tar's `-h`.*/followSymlinks?: boolean;+ /**+ * Advisory read-write intent for the sandbox target. `"rw"` means the author+ * expects the agent to change the bytes at the target and keep the change.+ * `"ro"` means the target is a read-only tree. An absent value defaults to+ * `"ro"` (read-only is the safe default for an advisory signal).+ *+ * This field is advisory metadata for an optional sandbox feedback wrapper. It+ * does not change the transfer and adds no security. A provider may read it to+ * bind the read-write targets read-write under the wrapper, but the ephemeral+ * sandbox stays the only security boundary.+ */+ access?: "rw" | "ro";+ /**+ * The sandbox directory that becomes read-write when `access` is `"rw"` and a+ * post-upload command extracts `targetPath` into a different directory. A+ * workspace, git-history, or asset mapping uploads a tar archive, so its+ * `targetPath` is the staging archive under the runtime root, not the directory+ * that the extract command fills. This field names that final destination+ * directory, so a consumer records the real read-write destination, not the+ * staging parent. When absent, the read-write destination is the parent+ * directory of `targetPath`. This field is advisory and ignored when `access`+ * is not `"rw"`.+ */+ writablePath?: string;}/**