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
import { execFileSync } from "node:child_process";
import { promises as fs } from "node:fs";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const mockCreate = vi.hoisted(() => vi.fn());
const mockGet = vi.hoisted(() => vi.fn());
const mockSnapshotGet = vi.hoisted(() => vi.fn());
const mockSnapshotDelete = vi.hoisted(() => vi.fn());
const { MockDaytonaNotFoundError, MockDaytonaTimeoutError } = vi.hoisted(() => {
class MockDaytonaNotFoundError extends Error {}
class MockDaytonaTimeoutError extends Error {}
return { MockDaytonaNotFoundError, MockDaytonaTimeoutError };
});
vi.mock("@daytonaio/sdk", () => ({
Daytona: class MockDaytona {
create = mockCreate;
get = mockGet;
snapshot = {
get: mockSnapshotGet,
delete: mockSnapshotDelete,
};
constructor(_config?: unknown) {}
},
DaytonaNotFoundError: MockDaytonaNotFoundError,
DaytonaTimeoutError: MockDaytonaTimeoutError,
}));
import plugin, {
setDaytonaTimingClockForTest,
setDaytonaHandleFreshnessClockForTest,
__resetDaytonaSandboxHandleCacheForTest,
__getDaytonaWritableDirsForTest,
__setDaytonaPluginContextForTest,
} from "./plugin.js";
import type { PluginContext } from "@paperclipai/plugin-sdk";
import { environmentSyncErrorData, readEnvironmentSyncErrorDiagnostic, withEnvironmentSyncErrorCapture, environmentCreationCleanupErrorData, readEnvironmentCreationCleanupError, readEnvironmentAcquisitionDiagnostic } from "@paperclipai/plugin-sdk";
import manifest from "./manifest.js";
import { parseTarVerboseListingLine, splitLinkEntryOnce } from "./file-sync.js";
describe("Daytona read-only resource inspection", () => {
const params = { driverKey: "daytona", companyId: "fixture-company", environmentId: "fixture-environment",
providerLeaseId: "sandbox-123", config: { apiKey: "fixture-not-a-key" } };
afterEach(() => { vi.clearAllMocks(); vi.unstubAllEnvs(); __resetDaytonaSandboxHandleCacheForTest(); });
it.each(["started", "stopped"])("observes a %s sandbox without lifecycle calls", async state => {
const sandbox = createMockSandbox({ state }); mockGet.mockResolvedValue(sandbox);
expect(await plugin.definition.onEnvironmentInspectLease!(params)).toEqual({ providerLeaseId: "sandbox-123", state: state === "stopped" ? "stopped" : "active" });
expect(mockGet).toHaveBeenLastCalledWith("sandbox-123");
for (const method of [sandbox.start, sandbox.stop, sandbox.delete, sandbox.archive, sandbox.refreshData]) expect(method).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it("accepts only typed provider not-found as deletion proof", async () => {
__resetDaytonaSandboxHandleCacheForTest();
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("not found"));
expect(await plugin.definition.onEnvironmentInspectLease!(params)).toEqual({ providerLeaseId: "sandbox-123", state: "destroyed" });
expect(await plugin.definition.onIdleDrain!(new AbortController().signal)).toBe("none");
});
it("does not use an ambient account credential to certify historical deletion", async () => {
expect(await plugin.definition.onEnvironmentInspectLease!({ ...params, config: {} })).toEqual({ providerLeaseId: "sandbox-123", state: "unknown" });
expect(mockGet).not.toHaveBeenCalled();
});
it.each(["DAYTONA_API_URL", "DAYTONA_SERVER_URL"])("does not substitute ambient %s for the recorded API endpoint", async variable => {
vi.stubEnv(variable, "https://replacement.example.test/api");
expect((await plugin.definition.onEnvironmentInspectLease!(params)).state).toBe("unknown");
expect(mockGet).not.toHaveBeenCalled();
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("gone"));
expect((await plugin.definition.onEnvironmentInspectLease!({ ...params, config: { ...params.config, apiUrl: "https://recorded.example.test/api" } })).state).toBe("destroyed");
});
it.each(["401 unauthorized", "404 proxy not found", "network unavailable"])("does not turn %s into proof", async message => {
mockGet.mockRejectedValue(new Error(message));
await expect(plugin.definition.onEnvironmentInspectLease!(params)).rejects.toThrow(message);
});
it("rejects another resource and re-reads provider state on every observation", async () => {
mockGet.mockResolvedValueOnce(createMockSandbox({ id: "another-sandbox" })).mockRejectedValueOnce(new MockDaytonaNotFoundError("gone"));
expect((await plugin.definition.onEnvironmentInspectLease!(params)).state).toBe("unknown");
expect((await plugin.definition.onEnvironmentInspectLease!(params)).state).toBe("destroyed");
expect(mockGet).toHaveBeenCalledTimes(2);
});
});
describe("Daytona idle eligibility", () => {
const params = { driverKey: "daytona", companyId: "fixture-company", environmentId: "fixture-environment",
config: { apiKey: "fixture-not-a-key", reuseLease: true } };
const signal = new AbortController().signal;
beforeEach(() => { mockCreate.mockReset(); mockGet.mockReset(); __resetDaytonaSandboxHandleCacheForTest(); });
afterEach(() => { vi.restoreAllMocks(); __resetDaytonaSandboxHandleCacheForTest(); });
it("permits a fresh unused provider but remains conservative after provider access", async () => {
__resetDaytonaSandboxHandleCacheForTest();
const signal = new AbortController().signal;
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
mockGet.mockRejectedValueOnce(new Error("provider unreachable"));
await plugin.definition.onEnvironmentProbe!({
driverKey: "daytona", companyId: "fixture-company", environmentId: "fixture-environment",
config: { apiKey: "fixture-not-a-key" },
}).catch(() => undefined);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
__resetDaytonaSandboxHandleCacheForTest();
});
it("permits idle after a probe's exact sandbox deletion succeeds", async () => {
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
expect((await plugin.definition.onEnvironmentProbe!(params)).ok).toBe(true);
expect(sandbox.delete).toHaveBeenCalledTimes(1);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
});
it.each(["probe", "failed acquisition", "failed interactive setup", "cancelled setup"] as const)(
"waits for remote deletion before allowing idle after %s",
async kind => {
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox); mockGet.mockResolvedValue(sandbox);
if (kind === "failed acquisition" || kind === "failed interactive setup") {
sandbox.fs.createFolder.mockRejectedValueOnce(new Error("workspace setup failed"));
}
let finishDeletion!: () => void;
let remotelyDestroyed = false;
const deletion = new Promise<void>(resolve => {
finishDeletion = () => { remotelyDestroyed = true; resolve(); };
});
// The SDK's default resolves after acceptance. Only wait=true observes
// completed deletion, which can happen after the request is acknowledged.
sandbox.delete.mockImplementation(async (_timeout?: number, wait = false) => {
if (wait) await deletion;
});
const input = { ...params, config: { ...params.config, reuseLease: false } };
const pending = kind === "probe" ? plugin.definition.onEnvironmentProbe!(input)
: kind === "failed acquisition" ? plugin.definition.onEnvironmentAcquireLease!({ ...input, runId: "fixture-run" })
: kind === "failed interactive setup" ? plugin.definition.onEnvironmentStartInteractiveSetup!({ ...input, sessionId: "fixture-setup" })
: plugin.definition.onEnvironmentCancelInteractiveSetup!({ ...input, providerLeaseId: sandbox.id, reason: "user_cancelled" });
let settled = false;
const outcome = pending.then(() => { settled = true; }, () => { settled = true; });
try {
await vi.waitFor(() => expect(sandbox.delete).toHaveBeenCalledTimes(1));
await new Promise<void>(resolve => setImmediate(resolve));
expect(remotelyDestroyed).toBe(false);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
expect(settled).toBe(false);
finishDeletion(); await outcome;
expect(remotelyDestroyed).toBe(true);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
} finally {
finishDeletion(); await outcome;
}
},
);
it("retains a failed probe deletion until exact provider cleanup succeeds", async () => {
const sandbox = createMockSandbox();
sandbox.delete.mockRejectedValueOnce(new Error("delete unavailable"));
mockCreate.mockResolvedValue(sandbox); mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentProbe!(params);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
await plugin.definition.onEnvironmentDestroyLease!({ ...params, providerLeaseId: sandbox.id });
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
});
it.each(["stop", "release", "retain", "destroy"])("clears verified %s without clearing another account", async kind => {
const first = createMockSandbox({ id: "sandbox-a" });
const second = createMockSandbox({ id: "sandbox-b" });
mockCreate.mockResolvedValueOnce(first).mockResolvedValueOnce(second);
first.delete.mockRejectedValueOnce(new Error("deferred"));
second.delete.mockRejectedValueOnce(new Error("deferred"));
await plugin.definition.onEnvironmentProbe!(params);
const other = { ...params, config: { ...params.config, apiKey: "fixture-other-account" } };
await plugin.definition.onEnvironmentProbe!(other);
mockGet.mockResolvedValue(first);
const cleanup = { ...params, providerLeaseId: first.id };
if (kind === "stop") await plugin.definition.onEnvironmentStopLease!(cleanup);
else if (kind === "release") await plugin.definition.onEnvironmentReleaseLease!(cleanup);
else if (kind === "retain") await plugin.definition.onEnvironmentReleaseLease!({ ...cleanup, resourceDisposition: "stop_and_retain" });
else await plugin.definition.onEnvironmentDestroyLease!(cleanup);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
mockGet.mockResolvedValue(second);
await plugin.definition.onEnvironmentDestroyLease!({ ...other, providerLeaseId: second.id });
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
});
it("keeps a pending create after exact cleanup until it settles and absence is re-proven", async () => {
let finishCreate!: (sandbox: ReturnType<typeof createMockSandbox>) => void;
const sandbox = createMockSandbox();
mockCreate.mockImplementation(() => new Promise(resolve => { finishCreate = resolve; }));
const probe = plugin.definition.onEnvironmentProbe!(params);
await vi.waitFor(() => expect(finishCreate).toBeTypeOf("function"));
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("gone"));
await plugin.definition.onEnvironmentDestroyLease!({ ...params, providerLeaseId: sandbox.id });
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
// The late create must finish its own deletion. Its tracked raw request
// cannot be confused with a completed RPC or another resource's receipt.
finishCreate(sandbox); await probe;
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
});
it("can clear verified absence after a failed deletion without starting the sandbox", async () => {
const sandbox = createMockSandbox(); sandbox.delete.mockRejectedValue(new Error("unavailable"));
mockCreate.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentProbe!(params);
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("gone"));
await plugin.definition.onEnvironmentInspectLease!({ ...params, providerLeaseId: sandbox.id });
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
expect(sandbox.start).not.toHaveBeenCalled();
});
it("clears both sandboxes when their successful stops overlap", async () => {
const first = createMockSandbox({ id: "sandbox-a" });
const second = createMockSandbox({ id: "sandbox-b" });
for (const sandbox of [first, second]) sandbox.delete.mockRejectedValueOnce(new Error("deferred"));
mockCreate.mockResolvedValueOnce(first).mockResolvedValueOnce(second);
await plugin.definition.onEnvironmentProbe!(params);
await plugin.definition.onEnvironmentProbe!(params);
mockGet.mockImplementation(async id => id === first.id ? first : second);
let finishFirst!: () => void, finishSecond!: () => void;
first.stop.mockImplementation(() => new Promise<void>(resolve => { finishFirst = resolve; }));
second.stop.mockImplementation(() => new Promise<void>(resolve => { finishSecond = resolve; }));
const stopFirst = plugin.definition.onEnvironmentStopLease!({ ...params, providerLeaseId: first.id });
const stopSecond = plugin.definition.onEnvironmentStopLease!({ ...params, providerLeaseId: second.id });
await vi.waitFor(() => {
expect(finishFirst).toBeTypeOf("function"); expect(finishSecond).toBeTypeOf("function");
});
finishFirst(); await stopFirst;
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
finishSecond(); await stopSecond;
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
});
it("keeps a stale stopped reply from clearing a start that finished during the read", async () => {
const sandbox = createMockSandbox({ state: "stopped" });
mockGet.mockResolvedValue(sandbox);
let finishStart!: () => void, finishRead!: () => void;
let remoteRunning = false;
sandbox.start.mockImplementation(async () => {
await new Promise<void>(resolve => { finishStart = resolve; });
remoteRunning = true; sandbox.state = "started";
});
sandbox.stop.mockImplementation(async () => { remoteRunning = false; sandbox.state = "stopped"; });
const execute = plugin.definition.onEnvironmentExecute!({ ...params, bypassSession: true,
lease: { providerLeaseId: sandbox.id, metadata: {} }, command: "printf", args: ["hi"], timeoutMs: 1000 });
await vi.waitFor(() => expect(finishStart).toBeTypeOf("function"));
sandbox.refreshData.mockImplementationOnce(async () => {
await new Promise<void>(resolve => { finishRead = resolve; });
sandbox.state = "stopped"; // The reply contains the state captured before Start.
});
const stopped = plugin.definition.onEnvironmentStopLease!({ ...params, providerLeaseId: sandbox.id });
await vi.waitFor(() => expect(finishRead).toBeTypeOf("function"));
finishStart(); await execute;
finishRead(); await stopped;
expect(remoteRunning).toBe(true);
expect(sandbox.stop).not.toHaveBeenCalled();
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
sandbox.state = "started"; // A subsequent fresh read observes the real state.
await plugin.definition.onEnvironmentStopLease!({ ...params, providerLeaseId: sandbox.id });
expect(remoteRunning).toBe(false);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
});
it("retains a raw command dispatch after its deadline and an intervening stop", async () => {
const sandbox = createMockSandbox(); mockGet.mockResolvedValue(sandbox);
let finishDispatch!: (value: { cmdId: string }) => void;
sandbox.process.executeSessionCommand.mockImplementation(() => new Promise(resolve => { finishDispatch = resolve; }));
vi.useFakeTimers();
try {
const execution = plugin.definition.onEnvironmentExecute!({ ...params,
lease: { providerLeaseId: sandbox.id, metadata: {} }, command: "printf", args: ["hi"],
timeoutMs: 1000, commandTimeoutMs: 1000 });
await vi.advanceTimersByTimeAsync(0);
expect(finishDispatch).toBeTypeOf("function");
await vi.advanceTimersByTimeAsync(1000);
expect(await execution).toMatchObject({ timedOut: true });
await plugin.definition.onEnvironmentStopLease!({ ...params, providerLeaseId: sandbox.id });
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
finishDispatch({ cmdId: "late-command" });
await vi.advanceTimersByTimeAsync(0);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("present");
await plugin.definition.onEnvironmentStopLease!({ ...params, providerLeaseId: sandbox.id });
expect(sandbox.stop).toHaveBeenCalledTimes(2);
expect(await plugin.definition.onIdleDrain!(signal)).toBe("none");
} finally { vi.useRealTimers(); }
});
});
function createMockSandbox(overrides: {
id?: string;
name?: string;
state?: string;
recoverable?: boolean;
workDir?: string;
autoDestroyAt?: string | null;
updatedAt?: string;
} = {}) {
return {
id: overrides.id ?? "sandbox-123",
name: overrides.name ?? "paperclip-sandbox",
state: overrides.state ?? "started",
recoverable: overrides.recoverable ?? false,
target: "us",
errorReason: null,
// A configured provider TTL populates `autoDestroyAt` after `setTtl` +
// `refreshData`. The default mock leaves it unset (no TTL configured).
autoDestroyAt: overrides.autoDestroyAt ?? undefined,
updatedAt: overrides.updatedAt,
autoDeleteInterval: -1,
getWorkDir: vi.fn().mockResolvedValue(overrides.workDir ?? "/home/daytona"),
getUserHomeDir: vi.fn().mockResolvedValue("/home/daytona"),
start: vi.fn().mockResolvedValue(undefined),
stop: vi.fn().mockResolvedValue(undefined),
recover: vi.fn().mockResolvedValue(undefined),
// Real `refreshData` re-reads live provider state and mutates `state` in
// place; the default mock leaves state untouched, and tests that exercise a
// provider-initiated auto-stop override it to flip `state` to "stopped".
refreshData: vi.fn().mockResolvedValue(undefined),
resize: vi.fn().mockResolvedValue(undefined),
delete: vi.fn().mockResolvedValue(undefined),
archive: vi.fn().mockResolvedValue(undefined),
setTtl: vi.fn().mockResolvedValue(undefined),
setAutoDeleteInterval: vi.fn().mockResolvedValue(undefined),
createSshAccess: vi.fn().mockResolvedValue({
token: "ssh-token-secret",
command: "ssh [email protected]",
}),
getPreviewLink: vi.fn().mockResolvedValue({
url: "https://43127-sandbox-123.proxy.daytona.test",
token: "preview-token-secret",
}),
_experimental_createSnapshot: vi.fn().mockResolvedValue(undefined),
fs: {
createFolder: vi.fn().mockResolvedValue(undefined),
uploadFile: vi.fn().mockResolvedValue(undefined),
deleteFile: vi.fn().mockResolvedValue(undefined),
// Native batch file-transfer primitives (Daytona SDK 0.171.0). Extended
// here so the sync hooks can be exercised without a real SDK install.
uploadFiles: vi.fn().mockResolvedValue(undefined),
downloadFiles: vi.fn().mockResolvedValue([]),
setFilePermissions: vi.fn().mockResolvedValue(undefined),
},
process: {
executeCommand: vi.fn().mockResolvedValue({
exitCode: 0,
result: "bash",
artifacts: { stdout: "bash" },
}),
// Session API (Daytona SDK 0.203.0). The exec hook opens one session per
// lease and dispatches every command into it. `executeSessionCommand`
// returns a `cmdId`; `getSessionCommand` reports the exit code; and
// `getSessionCommandLogs` returns separated `stdout` and `stderr`.
createSession: vi.fn().mockResolvedValue(undefined),
executeSessionCommand: vi.fn().mockResolvedValue({ cmdId: "cmd-1" }),
getSessionCommand: vi.fn().mockResolvedValue({ id: "cmd-1", command: "", exitCode: 0 }),
getSessionCommandLogs: vi.fn().mockResolvedValue({ stdout: "", stderr: "" }),
deleteSession: vi.fn().mockResolvedValue(undefined),
},
};
}
describe("Daytona sandbox provider plugin", () => {
beforeEach(() => {
mockCreate.mockReset();
mockGet.mockReset();
mockSnapshotGet.mockReset();
mockSnapshotDelete.mockReset();
vi.restoreAllMocks();
delete process.env.DAYTONA_API_KEY;
// The started-sandbox handle cache is process-scoped; clear it between tests
// so a handle memoized under a reused composite key never leaks forward.
__resetDaytonaSandboxHandleCacheForTest();
});
const snapshotRecord = { id: "a6b9e7d0-f886-471a-b461-640dd03e8d0f", name: "managed-snapshot", organizationId: "provider-account", createdAt: "2026-10-07T23:19:57.133Z" };
const snapshotProbe = { driverKey: "daytona", companyId: "company-1", environmentId: "env-1", runId: "probe-1",
resolveSnapshotIdentity: true, config: { apiKey: "fixture-key", snapshot: "managed-snapshot", reuseLease: false } };
it("qualifies a named snapshot by creating from its immutable provider ID", async () => {
mockSnapshotGet.mockResolvedValue(snapshotRecord);
mockCreate.mockResolvedValue(createMockSandbox());
const lease = await plugin.definition.onEnvironmentAcquireLease!(snapshotProbe);
expect(mockSnapshotGet).toHaveBeenCalledWith("managed-snapshot");
expect(mockCreate.mock.calls[0][0].snapshot).toBe(snapshotRecord.id);
expect(lease.metadata).toMatchObject({ snapshot: "managed-snapshot", snapshotIdentity: {
...snapshotRecord, provider: "daytona", requestedRef: "managed-snapshot",
} });
});
it("does not resolve snapshot names during ordinary acquisition", async () => {
mockCreate.mockResolvedValue(createMockSandbox());
await plugin.definition.onEnvironmentAcquireLease!({ ...snapshotProbe, resolveSnapshotIdentity: undefined });
expect(mockSnapshotGet).not.toHaveBeenCalled();
expect(mockCreate.mock.calls[0][0].snapshot).toBe("managed-snapshot");
});
it.each([{ id: "mutable-name" }, { organizationId: "" }, { name: "different-name" }, { createdAt: "invalid" }])(
"rejects unverified snapshot identity %j before allocation", async invalid => {
mockSnapshotGet.mockResolvedValue({ ...snapshotRecord, ...invalid });
await expect(plugin.definition.onEnvironmentAcquireLease!(snapshotProbe)).rejects.toThrow("immutable snapshot identity");
expect(mockCreate).not.toHaveBeenCalled();
},
);
it("never allocates after a snapshot identity lookup times out", async () => {
vi.useFakeTimers();
try {
let resolveLookup!: (value: typeof snapshotRecord) => void;
mockSnapshotGet.mockReturnValue(new Promise(resolve => { resolveLookup = resolve; }));
const result = plugin.definition.onEnvironmentAcquireLease!(snapshotProbe).catch(error => error);
await vi.advanceTimersByTimeAsync(10_001);
expect(await result).toBeInstanceOf(Error);
resolveLookup(snapshotRecord);
await vi.advanceTimersByTimeAsync(1);
expect(mockCreate).not.toHaveBeenCalled();
} finally { vi.useRealTimers(); }
});
it("declares environment lifecycle handlers", async () => {
expect(await plugin.definition.onHealth?.()).toEqual({
status: "ok",
message: "Daytona sandbox provider plugin healthy",
});
expect(plugin.definition.onEnvironmentAcquireLease).toBeTypeOf("function");
expect(plugin.definition.onEnvironmentExecute).toBeTypeOf("function");
expect(plugin.definition.onEnvironmentStartInteractiveSetup).toBeTypeOf("function");
expect(plugin.definition.onEnvironmentCaptureTemplate).toBeTypeOf("function");
expect(manifest.environmentDrivers?.[0]).toMatchObject({
defaultAcquireTimeoutMs: 300_000,
supportsInteractiveSetup: true,
interactiveSetupConnectionTypes: ["ssh"],
supportsTemplateCapture: true,
templateRefKind: "snapshot",
supportsTemplateDelete: true,
// Daytona streams incremental session output, so it declares the opt-in
// capability that selects the session-output streaming path.
sandboxCapabilities: { incrementalSessionOutput: true },
});
});
it("declares the concurrent-sync-operations capability so the host may parallelize sync operations", () => {
// Daytona runs file transfers into and out of the sandbox in parallel, so it
// declares the opt-in capability. The host resolves it `true` only when the
// worker also verifies both sync verbs, which the sync hooks provide.
expect(manifest.environmentDrivers?.[0]?.sandboxCapabilities).toMatchObject({
concurrentSyncOperations: true,
});
});
it("declares the duplex-command-stream capability and the four channel handlers", () => {
// Daytona carries the callback bridge on one duplex channel, so it declares
// the opt-in capability. The host resolves it `true` only when the worker also
// verifies the `duplexChannelOpen` handler, which the four handlers provide.
expect(manifest.environmentDrivers?.[0]?.sandboxCapabilities).toMatchObject({
duplexCommandStream: true,
});
expect(plugin.definition.onDuplexChannelOpen).toBeTypeOf("function");
expect(plugin.definition.onDuplexChannelWrite).toBeTypeOf("function");
expect(plugin.definition.onDuplexChannelStop).toBeTypeOf("function");
expect(plugin.definition.onDuplexChannelClose).toBeTypeOf("function");
});
it("declares and returns private authenticated runner WebSocket ingress", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
const base = {
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { image: "node:20", timeoutMs: 300_000, reuseLease: false },
};
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
...base,
runId: "00000000-0000-4000-8000-000000000001",
});
const endpoint = await plugin.definition.onEnvironmentRunnerIngressEndpoint?.({
...base,
lease: lease!,
port: 43_127,
path: "/api/runner/v1/connect/00000000-0000-4000-8000-000000000001",
});
expect(manifest.environmentDrivers?.[0]?.sandboxCapabilities).toMatchObject({
runnerWebSocketIngress: true,
});
expect(endpoint).toMatchObject({
kind: "authenticated_websocket",
websocketUrl:
"wss://43127-sandbox-123.proxy.daytona.test/api/runner/v1/connect/00000000-0000-4000-8000-000000000001",
secretHeaders: [
{ name: "X-Daytona-Preview-Token", value: "preview-token-secret" },
],
});
expect(endpoint?.websocketUrl).not.toContain("preview-token-secret");
expect(endpoint?.websocketUrl).not.toContain("host-key");
});
it("keeps ingress generation independent of token rotation and changes it after a sandbox lifecycle revision", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ updatedAt: "2026-08-25T10:00:00.000Z" });
sandbox.getPreviewLink
.mockResolvedValueOnce({
url: "https://43127-sandbox-123.proxy.daytona.test",
token: "preview-token-1",
})
.mockResolvedValueOnce({
url: "https://43127-sandbox-123.proxy.daytona.test",
token: "preview-token-2",
})
.mockResolvedValueOnce({
url: "https://43127-sandbox-123.proxy.daytona.test",
token: "preview-token-3",
});
mockCreate.mockResolvedValue(sandbox);
const base = {
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { image: "node:20", timeoutMs: 300_000, reuseLease: false },
};
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
...base,
runId: "00000000-0000-4000-8000-000000000001",
});
const request = {
...base,
lease: lease!,
port: 43_127,
path: "/api/runner/v1/connect/00000000-0000-4000-8000-000000000001",
};
const first = await plugin.definition.onEnvironmentRunnerIngressEndpoint?.(request);
const second = await plugin.definition.onEnvironmentRunnerIngressEndpoint?.(request);
expect(second?.generation).toBe(first?.generation);
expect(second?.secretHeaders).not.toEqual(first?.secretHeaders);
sandbox.updatedAt = "2026-08-25T10:05:00.000Z";
const restarted = await plugin.definition.onEnvironmentRunnerIngressEndpoint?.(request);
expect(restarted?.generation).not.toBe(first?.generation);
});
it("bumps the plugin version so the server reconciles the stored manifest", () => {
// The bundled-plugin boot reconcile refreshes the stored manifest for an
// existing install only when the version changes. The acquisition budget needs
// the bump to reach an existing install.
expect(manifest.version).toBe("0.1.8");
});
it.each([false, true])("closes duplex routes on lease release even when bridge drain hangs: %s", async (hangDrain) => {
process.env.DAYTONA_API_KEY = "host-key";
// A fake PTY handle records each host write, drives the data stream on demand,
// and records the kill and the disconnect.
const inputs: string[] = [];
let killed = 0;
let disconnected = 0;
let ptyOnData: ((data: Uint8Array) => void) | null = null;
const handle = {
async waitForConnection() {},
async sendInput(data: string | Uint8Array) {
inputs.push(typeof data === "string" ? data : new TextDecoder().decode(data));
},
wait() {
return new Promise<{ exitCode?: number }>(() => {});
},
async kill() {
killed += 1;
},
async disconnect() {
disconnected += 1;
},
};
const sandbox = createMockSandbox();
(sandbox.process as Record<string, unknown>).createPty = vi.fn(
async (options: { onData: (data: Uint8Array) => void }) => {
ptyOnData = options.onData;
return handle;
},
);
mockCreate.mockResolvedValue(sandbox);
// Capture the data and the exit the worker forwards through `ctx.duplexChannel`.
// `ctx.duplexChannel.data` carries raw bytes; decode each chunk to text so the
// assertion below reads the plain-text payload.
const dataChunks: Array<{ hostRouteId: string; workerSessionId: string; chunk: string }> = [];
const restore = __setDaytonaPluginContextForTest({
duplexChannel: {
data: (hostRouteId: string, workerSessionId: string, chunk: Uint8Array) =>
dataChunks.push({ hostRouteId, workerSessionId, chunk: Buffer.from(chunk).toString("utf8") }),
exit: () => {},
},
} as unknown as PluginContext);
let finishBlocked: (() => void) | undefined;
let blocked: Promise<unknown> | undefined;
try {
await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
agentId: "agent-1",
executionWorkspaceId: "workspace-1",
adapterType: "codex_local",
config: { image: "node:20", timeoutMs: 300000, livenessTimeoutMs: 5, reuseLease: true },
});
const open = await plugin.definition.onDuplexChannelOpen?.({
hostRouteId: "route-1",
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
command: ["node", "/paperclip/gateway.mjs"],
});
expect(open?.workerSessionId).toMatch(/^duplex-/);
// The open reply echoes the host route id, so the host binds the exact pair.
expect(open?.hostRouteId).toBe("route-1");
const workerSessionId = open?.workerSessionId ?? "";
// The launch wrapper sets raw mode with echo off and redirects diagnostics.
// It quotes each command argument and the diagnostics path as a shell word.
expect(inputs[0]).toContain("stty raw -echo");
expect(inputs[0]).toContain("exec 'node' '/paperclip/gateway.mjs'");
expect(inputs[0]).toMatch(/2>'\/tmp\/paperclip-duplex-.+\.log'/);
// A host write on the exact pair reaches the process on the same channel.
// `data` arrives in the wire-safe base64 form (see `ChannelBytesWireValue`
// in the plugin SDK's protocol.ts).
await plugin.definition.onDuplexChannelWrite?.({
hostRouteId: "route-1",
workerSessionId,
data: Buffer.from('{"version":1,"type":"heartbeat"}\n', "utf8").toString("base64"),
});
expect(inputs[1]).toBe('{"version":1,"type":"heartbeat"}\n');
// A write whose pair does not match the bound entry applies no bytes. The
// worker acts only on the exact live pair.
const inputsBeforeForeign = inputs.length;
await plugin.definition.onDuplexChannelWrite?.({
hostRouteId: "route-foreign",
workerSessionId,
data: Buffer.from("foreign\n", "utf8").toString("base64"),
});
expect(inputs.length).toBe(inputsBeforeForeign);
// A stop whose pair does not match the bound entry stops nothing.
const killedBeforeForeign = killed;
await plugin.definition.onDuplexChannelStop?.({
hostRouteId: "route-foreign",
workerSessionId,
});
expect(killed).toBe(killedBeforeForeign);
// Process output reaches the host as a data notification bound to the exact
// pair, so it echoes the host route id and the worker session id.
(ptyOnData as ((data: Uint8Array) => void) | null)?.(
new TextEncoder().encode('{"version":1,"type":"ready","address":"127.0.0.1:1"}\n'),
);
expect(dataChunks).toEqual([
{
hostRouteId: "route-1",
workerSessionId,
chunk: '{"version":1,"type":"ready","address":"127.0.0.1:1"}\n',
},
]);
if (hangDrain) {
sandbox.process.executeCommand.mockImplementationOnce(async () => {
await new Promise<void>(resolve => { finishBlocked = resolve; });
return { exitCode: 0, result: "done", artifacts: { stdout: "done" } };
});
blocked = plugin.definition.onEnvironmentExecute?.({ driverKey: "daytona", companyId: "company-1",
environmentId: "env-1", config: { timeoutMs: 300000 }, bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} }, command: "printf", args: ["done"] });
await vi.waitFor(() => expect(finishBlocked).toBeTypeOf("function"));
}
sandbox.stop.mockImplementation(async () => { expect(disconnected).toBe(1); });
// Route invalidation must happen before provider stop, including after drain timeout.
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { image: "node:20", timeoutMs: 300000, livenessTimeoutMs: 5, reuseLease: true },
});
expect(killed).toBeGreaterThanOrEqual(1);
expect(disconnected).toBe(1);
// The channel entry is gone, so a later write is a no-op and reaches no
// process.
const inputsBefore = inputs.length;
await plugin.definition.onDuplexChannelWrite?.({
hostRouteId: "route-1",
workerSessionId,
data: Buffer.from("late\n", "utf8").toString("base64"),
});
expect(inputs.length).toBe(inputsBefore);
} finally {
finishBlocked?.();
await blocked;
restore();
}
});
it("normalizes config and validates the API key fallback", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const result = await plugin.definition.onEnvironmentValidateConfig?.({
driverKey: "daytona",
config: {
apiKey: " explicit-key ",
apiUrl: " https://app.daytona.io/api ",
target: " us ",
snapshot: " base-snapshot ",
language: " typescript ",
timeoutMs: "450000.9",
autoStopInterval: "15",
autoArchiveInterval: "60",
autoDeleteInterval: "-1",
reuseLease: true,
},
});
expect(result).toEqual({
ok: true,
normalizedConfig: {
apiKey: "explicit-key",
apiUrl: "https://app.daytona.io/api",
target: "us",
snapshot: "base-snapshot",
image: null,
language: "typescript",
timeoutMs: 450000,
livenessTimeoutMs: 30000,
cpu: null,
memory: null,
disk: null,
gpu: null,
autoStopInterval: 15,
autoArchiveInterval: 60,
autoDeleteInterval: -1,
reuseLease: true,
archiveOnRelease: false,
},
});
});
it("applies quota-safety auto-stop/archive/delete defaults when unset", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const result = await plugin.definition.onEnvironmentValidateConfig?.({
driverKey: "daytona",
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: true,
},
});
expect(result).toMatchObject({
ok: true,
normalizedConfig: {
autoStopInterval: 15,
autoArchiveInterval: 60,
autoDeleteInterval: 10080,
},
});
});
it("preserves an explicit 0/-1 to disable auto intervals", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const result = await plugin.definition.onEnvironmentValidateConfig?.({
driverKey: "daytona",
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
autoStopInterval: 0,
autoArchiveInterval: 0,
autoDeleteInterval: -1,
reuseLease: true,
},
});
expect(result).toMatchObject({
ok: true,
normalizedConfig: {
autoStopInterval: 0,
autoArchiveInterval: 0,
autoDeleteInterval: -1,
},
});
});
it("forwards auto-archive/auto-delete defaults to the Daytona create call", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
config: {
image: "node:20",
timeoutMs: 300000,
reuseLease: false,
},
});
const [createParams] = mockCreate.mock.calls[0] as [Record<string, unknown>];
expect(createParams).toMatchObject({
autoStopInterval: 15,
autoArchiveInterval: 60,
autoDeleteInterval: 10080,
});
});
describe("fresh acquisition deadline", () => {
const params = {
driverKey: "daytona", companyId: "company-1", environmentId: "env-1", runId: "run-1",
config: { image: "node:20", reuseLease: false },
};
beforeEach(() => {
process.env.DAYTONA_API_KEY = "host-key";
vi.useFakeTimers();
});
afterEach(() => { vi.useRealTimers(); });
it.each(["create", "workspace", "shell", "expiry", "sentinel"] as const)("records the %s acquisition deadline without advancing late setup", async phase => {
const sandbox = createMockSandbox();
const never = () => new Promise<never>(() => {});
mockCreate.mockResolvedValue(sandbox);
if (phase === "create") mockCreate.mockImplementation(never);
if (phase === "workspace") sandbox.getWorkDir.mockImplementation(never);
if (phase === "shell") sandbox.process.executeCommand.mockImplementation(never);
if (phase === "expiry") sandbox.setTtl.mockImplementation(never);
if (phase === "sentinel") sandbox.fs.uploadFile.mockImplementation(never);
const pending = plugin.definition.onEnvironmentAcquireLease!({ ...params,
config: { ...params.config, timeoutMs: 2_000 },
...(phase === "sentinel" ? { agentId: "agent-fixture", issueId: "issue-fixture" } : {}),
...(phase === "expiry" ? { requestedExpiresAt: new Date(Date.now() + 60_000).toISOString() } : {}),
}).catch(error => error);
await vi.advanceTimersByTimeAsync(2_000);
const error = await pending;
// The default lookup mock returns no sandbox, so a pending create reports `unavailable`.
expect(readEnvironmentAcquisitionDiagnostic(error)).toEqual({ phase, elapsedMs: 2_000, budgetMs: 2_000,
...(phase === "create" ? { providerState: "unavailable" } : {}) });
expect(error.message).toBe("Daytona lease acquisition timed out; allocation cleanup is pending");
expect(sandbox.delete).not.toHaveBeenCalled();
if (phase !== "create") expect(mockGet).not.toHaveBeenCalled();
});
function ownedCreation(state: string) {
const requested = mockCreate.mock.calls.at(-1)![0];
return { ...createMockSandbox({ state }), name: requested.name, labels: { ...requested.labels } };
}
it.each([
["pulling_snapshot", "pulling_snapshot"], ["starting", "starting"], ["pending_build", "pending_build"],
["error", "error"], ["stopped", "other"], ["11184809", "other"],
])("records provider state %s as %s when creation is still pending at the deadline", async (state, expected) => {
mockCreate.mockImplementation(() => new Promise(() => {}));
let found: ReturnType<typeof ownedCreation> | undefined;
mockGet.mockImplementation(async () => (found = ownedCreation(state)));
const pending = plugin.definition.onEnvironmentAcquireLease!({ ...params, config: { ...params.config, timeoutMs: 2_000 } }).catch(error => error);
await vi.advanceTimersByTimeAsync(2_000);
const error = await pending;
expect(readEnvironmentAcquisitionDiagnostic(error)).toEqual({ phase: "create", elapsedMs: 2_000, budgetMs: 2_000, providerState: expected });
expect(mockGet).toHaveBeenCalledOnce();
expect(mockGet).toHaveBeenCalledWith(mockCreate.mock.calls[0][0].name);
// Read-only: no deletion, and the host-owned cleanup envelope is unchanged.
expect(found!.delete).not.toHaveBeenCalled();
expect(readEnvironmentCreationCleanupError(error)?.observedProviderLeaseId).toBeUndefined();
expect(JSON.stringify(environmentCreationCleanupErrorData(error, true))).not.toContain(found!.id);
});
it.each([
["absent", () => mockGet.mockRejectedValue(new MockDaytonaNotFoundError("private-not-found"))],
["unavailable", () => mockGet.mockRejectedValue(new Error("private-provider-failure"))],
["unavailable", () => mockGet.mockImplementation(async () => {
const foreign = ownedCreation("started"); foreign.labels["paperclip-run-id"] = "foreign-run"; return foreign;
})],
])("records %s when the deadline lookup cannot attribute an allocation", async (expected, arrange) => {
mockCreate.mockImplementation(() => new Promise(() => {}));
arrange();
const pending = plugin.definition.onEnvironmentAcquireLease!({ ...params, config: { ...params.config, timeoutMs: 2_000 } }).catch(error => error);
await vi.advanceTimersByTimeAsync(2_000);
const error = await pending;
expect(readEnvironmentAcquisitionDiagnostic(error)?.providerState).toBe(expected);
expect(JSON.stringify(environmentCreationCleanupErrorData(error, true))).not.toContain("private-");
});
it("bounds a hung deadline lookup well inside the host's RPC margin", async () => {
mockCreate.mockImplementation(() => new Promise(() => {}));
mockGet.mockImplementation(() => new Promise(() => {}));
let settled = false;
const pending = plugin.definition.onEnvironmentAcquireLease!(params).catch(error => { settled = true; return error; });
await vi.advanceTimersByTimeAsync(304_999);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(1);
const error = await pending;
expect(readEnvironmentAcquisitionDiagnostic(error)).toEqual({ phase: "create", elapsedMs: 300_000, budgetMs: 300_000, providerState: "unavailable" });
expect(error.message).toBe("Daytona lease acquisition timed out; allocation cleanup is pending");
});
it("keeps the timeout result when a late create settles during the deadline lookup", async () => {
const sandbox = createMockSandbox();
mockCreate.mockImplementation(() => new Promise(resolve => setTimeout(() => resolve(sandbox), 2_500)));
mockGet.mockImplementation(() => new Promise(resolve => setTimeout(() => resolve(ownedCreation("starting")), 4_000)));
let settled = false;
const pending = plugin.definition.onEnvironmentAcquireLease!({ ...params, config: { ...params.config, timeoutMs: 2_000 } })
.catch(error => { settled = true; return error; });
// The host serializes the error on settlement; it must wait for the lookup.
await vi.advanceTimersByTimeAsync(3_000);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(3_000);
const error = await pending;
expect(readEnvironmentAcquisitionDiagnostic(error)).toEqual({ phase: "create", elapsedMs: 2_000, budgetMs: 2_000, providerState: "starting" });
expect(readEnvironmentCreationCleanupError(error)?.providerLeaseId).toBe(mockCreate.mock.calls[0][0].name);
expect(sandbox.getWorkDir).not.toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it.each(["create", "workspace"] as const)("keeps the original %s observation when cleanup consumes the remaining deadline", async phase => {
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
const fail = () => new Promise<never>((_resolve, reject) => setTimeout(() => reject(new Error("private-provider-failure")), 100));
if (phase === "create") { mockCreate.mockImplementation(fail); mockGet.mockImplementation(() => new Promise(() => {})); }
else { sandbox.getWorkDir.mockImplementation(fail); sandbox.delete.mockImplementation(() => new Promise(() => {})); }
const pending = plugin.definition.onEnvironmentAcquireLease!({ ...params, config: { ...params.config, timeoutMs: 2_000 } }).catch(error => error);
await vi.advanceTimersByTimeAsync(2_000);
const error = await pending;
expect(readEnvironmentAcquisitionDiagnostic(error)).toEqual({ phase, elapsedMs: 100, budgetMs: 2_000 });
expect(error.message).toBe("Daytona lease acquisition timed out; allocation cleanup is pending");
expect(JSON.stringify(environmentCreationCleanupErrorData(error, true))).not.toContain("private-");
await vi.advanceTimersByTimeAsync(20_000);
expect(readEnvironmentAcquisitionDiagnostic(error)?.elapsedMs).toBe(100);
});
it("isolates overlapping acquisition observations and does not annotate successful leases", async () => {
const sandbox = createMockSandbox();
mockCreate.mockImplementationOnce(() => new Promise(() => {})).mockResolvedValueOnce(sandbox);
sandbox.getWorkDir.mockImplementation(() => new Promise(() => {}));
const first = plugin.definition.onEnvironmentAcquireLease!({ ...params, config: { ...params.config, timeoutMs: 2_000 } }).catch(error => error);
await vi.advanceTimersByTimeAsync(100);
const second = plugin.definition.onEnvironmentAcquireLease!({ ...params, config: { ...params.config, timeoutMs: 3_000 } }).catch(error => error);
await vi.advanceTimersByTimeAsync(3_000);
expect(readEnvironmentAcquisitionDiagnostic(await first)).toEqual({ phase: "create", elapsedMs: 2_000, budgetMs: 2_000, providerState: "unavailable" });
expect(readEnvironmentAcquisitionDiagnostic(await second)).toEqual({ phase: "workspace", elapsedMs: 3_000, budgetMs: 3_000 });
mockCreate.mockResolvedValue(createMockSandbox());
expect(await plugin.definition.onEnvironmentAcquireLease!(params)).not.toHaveProperty("acquisitionDiagnostic");
});
it("allows a slow create and setup that finish inside the total budget", async () => {
const sandbox = createMockSandbox();
mockCreate.mockImplementation(() => new Promise(resolve => setTimeout(() => resolve(sandbox), 280_000)));
sandbox.process.executeCommand.mockImplementation(() => new Promise(resolve => setTimeout(() => resolve({ result: "bash" }), 15_000)));
const pending = plugin.definition.onEnvironmentAcquireLease!(params);
await vi.advanceTimersByTimeAsync(295_000);
expect(await pending).toMatchObject({ providerLeaseId: sandbox.id });
expect(vi.getTimerCount()).toBe(0);
});
it("journals ownership before the host deadline when setup outlasts creation", async () => {
const sandbox = createMockSandbox();
mockCreate.mockImplementation(() => new Promise(resolve => setTimeout(() => resolve(sandbox), 280_000)));
sandbox.process.executeCommand.mockImplementation(() => new Promise(resolve => setTimeout(() => resolve({ result: "bash" }), 55_000)));
const pending = plugin.definition.onEnvironmentAcquireLease!(params).catch(error => error);
await vi.advanceTimersByTimeAsync(300_000);
const cleanup = readEnvironmentCreationCleanupError(await pending);
expect(cleanup).toMatchObject({ companyId: params.companyId, environmentId: params.environmentId,
runId: params.runId, observedProviderLeaseId: sandbox.id, providerLeaseId: mockCreate.mock.calls[0][0].name });
await vi.advanceTimersByTimeAsync(35_000);
expect(sandbox.setTtl).not.toHaveBeenCalled();
expect(sandbox.fs.uploadFile).not.toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it("records an uncertain create and rejects its late result without starting setup", async () => {
const sandbox = createMockSandbox();
mockCreate.mockImplementation(() => new Promise(resolve => setTimeout(() => resolve(sandbox), 310_000)));
const pending = plugin.definition.onEnvironmentAcquireLease!(params).catch(error => error);
await vi.advanceTimersByTimeAsync(300_000);
const cleanup = readEnvironmentCreationCleanupError(await pending);
expect(cleanup?.providerLeaseId).toBe(mockCreate.mock.calls[0][0].name);
expect(cleanup?.observedProviderLeaseId).toBeUndefined();
await vi.advanceTimersByTimeAsync(10_000);
expect(sandbox.getWorkDir).not.toHaveBeenCalled();
expect(sandbox.process.executeCommand).not.toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it("keeps a failed setup's ownership when inline deletion does not finish", async () => {
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
sandbox.getWorkDir.mockRejectedValue(new Error("workspace unavailable"));
sandbox.delete.mockImplementation(() => new Promise(() => {}));
const pending = plugin.definition.onEnvironmentAcquireLease!({ ...params,
config: { ...params.config, timeoutMs: 2_000 },
}).catch(error => error);
await vi.advanceTimersByTimeAsync(2_000);
expect(readEnvironmentCreationCleanupError(await pending)).toMatchObject({
observedProviderLeaseId: sandbox.id, companyId: params.companyId, runId: params.runId,
});
expect(sandbox.delete).toHaveBeenCalledOnce();
});
it("keeps ownership when setup and its inline deletion both reject", async () => {
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
sandbox.getWorkDir.mockRejectedValue(new Error("workspace unavailable"));
sandbox.delete.mockRejectedValue(new Error("delete unavailable"));
const error = await plugin.definition.onEnvironmentAcquireLease!(params).catch(error => error);
expect(readEnvironmentCreationCleanupError(error)).toMatchObject({
observedProviderLeaseId: sandbox.id, companyId: params.companyId, runId: params.runId,
});
expect(vi.getTimerCount()).toBe(0);
expect(readEnvironmentAcquisitionDiagnostic(error)).toEqual({ phase: "workspace", elapsedMs: 0, budgetMs: 300_000 });
});
});
describe("failed sandbox creation cleanup", () => {
const params = {
driverKey: "daytona", companyId: "company-1", environmentId: "env-1", runId: "run-1",
config: { image: "node:20", timeoutMs: 300_000, reuseLease: false, livenessTimeoutMs: 100 },
};
const createError = new MockDaytonaTimeoutError("Failed to create and start sandbox within 300 seconds");
beforeEach(() => {
process.env.DAYTONA_API_KEY = "host-key";
mockCreate.mockRejectedValue(createError);
});
function ownedSandbox() {
const requested = mockCreate.mock.calls.at(-1)![0];
return { ...createMockSandbox(), name: requested.name, labels: { ...requested.labels } };
}
async function unresolvedCreation() {
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("not visible yet"));
const error = await plugin.definition.onEnvironmentAcquireLease!(params).catch(error => error);
const cleanup = readEnvironmentCreationCleanupError(error);
expect(cleanup).not.toBeNull();
return { error, cleanup: cleanup! };
}
async function journalObservation(cleanup: NonNullable<ReturnType<typeof readEnvironmentCreationCleanupError>>) {
const error = await plugin.definition.onEnvironmentDestroyLease!({ ...params,
providerLeaseId: cleanup.providerLeaseId, leaseMetadata: { failedCreateCleanup: cleanup },
}).catch(error => error);
const observed = readEnvironmentCreationCleanupError(error);
expect(observed?.observedProviderLeaseId).toBeTruthy();
return observed!;
}
it("hands non-secret cleanup ownership to the host when creation is uncertain", async () => {
const { error, cleanup } = await unresolvedCreation();
expect(cleanup).toMatchObject({ companyId: params.companyId, environmentId: params.environmentId, runId: params.runId,
providerLeaseId: mockCreate.mock.calls[0][0].name, labels: mockCreate.mock.calls[0][0].labels });
expect(cleanup.accountFingerprint).toMatch(/^[a-f0-9]{64}$/);
expect(JSON.stringify(environmentCreationCleanupErrorData(error))).not.toContain("host-key");
expect(JSON.stringify(environmentCreationCleanupErrorData(error))).not.toContain(createError.message);
});
it("preserves ownership when the SDK adds labels to its mutable create input", async () => {
mockCreate.mockImplementation(async (input) => {
// Daytona 0.203.0 writes its default language into params.labels.
input.labels["code-toolbox-language"] = "python";
throw createError;
});
const { error, cleanup } = await unresolvedCreation();
expect(environmentCreationCleanupErrorData(error)).toBeDefined();
expect(cleanup.labels).not.toHaveProperty("code-toolbox-language");
const orphan = ownedSandbox();
mockGet.mockResolvedValue(orphan);
const observed = await journalObservation(cleanup);
expect(orphan.delete).not.toHaveBeenCalled();
await expect(plugin.definition.onEnvironmentDestroyLease!({ ...params,
providerLeaseId: cleanup.providerLeaseId, leaseMetadata: { failedCreateCleanup: observed },
})).resolves.toEqual({ providerLeaseId: cleanup.providerLeaseId, state: "destroyed" });
expect(orphan.delete).toHaveBeenCalledWith(10, true);
});
it("retries a late-visible failed creation using its persisted ownership envelope", async () => {
const { cleanup } = await unresolvedCreation();
const orphan = ownedSandbox(); mockGet.mockResolvedValue(orphan);
const observed = await journalObservation(cleanup);
expect(orphan.delete).not.toHaveBeenCalled();
await expect(plugin.definition.onEnvironmentDestroyLease!({ ...params, providerLeaseId: cleanup.providerLeaseId,
leaseMetadata: { failedCreateCleanup: observed } })).resolves.toEqual({ providerLeaseId: cleanup.providerLeaseId, state: "destroyed" });
expect(mockGet).toHaveBeenLastCalledWith(orphan.id);
expect(orphan.delete).toHaveBeenCalledWith(10, true);
expect(orphan.process.executeCommand).not.toHaveBeenCalled();
});
it("keeps a failed-creation retry unresolved while the allocation is still not visible", async () => {
const { cleanup } = await unresolvedCreation();
await expect(plugin.definition.onEnvironmentDestroyLease!({ ...params, providerLeaseId: cleanup.providerLeaseId,
leaseMetadata: { failedCreateCleanup: cleanup } })).rejects.toThrow();
});
it("accepts absence only after a matching provider ID was observed", async () => {
const { cleanup } = await unresolvedCreation();
const orphan = ownedSandbox(); mockGet.mockResolvedValue(orphan);
const observed = await journalObservation(cleanup);
expect(orphan.delete).not.toHaveBeenCalled();
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("already deleted"));
await expect(plugin.definition.onEnvironmentDestroyLease!({ ...params,
providerLeaseId: cleanup.providerLeaseId, leaseMetadata: { failedCreateCleanup: observed },
})).resolves.toEqual({ providerLeaseId: cleanup.providerLeaseId, state: "destroyed" });
expect(mockGet).toHaveBeenLastCalledWith(orphan.id);
});
it("retains the observed ID when immediate deletion loses its acknowledgement", async () => {
let orphan: ReturnType<typeof ownedSandbox>;
mockGet.mockImplementation(async () => {
orphan = ownedSandbox();
orphan.delete.mockRejectedValue(new Error("delete response lost"));
return orphan;
});
const error = await plugin.definition.onEnvironmentAcquireLease!(params).catch(error => error);
const cleanup = readEnvironmentCreationCleanupError(error)!;
expect(cleanup.observedProviderLeaseId).toBe(orphan!.id);
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("already deleted"));
await expect(plugin.definition.onEnvironmentDestroyLease!({ ...params,
providerLeaseId: cleanup.providerLeaseId, leaseMetadata: { failedCreateCleanup: cleanup },
})).resolves.toEqual({ providerLeaseId: cleanup.providerLeaseId, state: "destroyed" });
});
it.each(["company", "account", "labels"])("fences failed-creation retries by %s", async (mismatch) => {
const { cleanup } = await unresolvedCreation();
const orphan = ownedSandbox(); mockGet.mockResolvedValue(orphan);
if (mismatch === "labels") orphan.labels["paperclip-run-id"] = "foreign-run";
const retry = { ...params, providerLeaseId: cleanup.providerLeaseId, leaseMetadata: { failedCreateCleanup: cleanup } };
if (mismatch === "company") retry.companyId = "foreign-company";
if (mismatch === "account") process.env.DAYTONA_API_KEY = "another-account-key";
await expect(plugin.definition.onEnvironmentDestroyLease!(retry)).rejects.toThrow();
expect(orphan.delete).not.toHaveBeenCalled();
});
it("deletes the exact sandbox left behind when create times out, then preserves the create error", async () => {
let orphan: ReturnType<typeof ownedSandbox>;
mockGet.mockImplementation(async () => (orphan = ownedSandbox()));
await expect(plugin.definition.onEnvironmentAcquireLease?.(params)).rejects.toBe(createError);
expect(mockCreate.mock.calls[0][0].name).toMatch(/^paperclip-create-[0-9a-f-]{36}$/);
expect(mockGet).toHaveBeenCalledWith(mockCreate.mock.calls[0][0].name);
expect(orphan!.delete).toHaveBeenCalledWith(10, true);
expect(orphan!.process.executeCommand).not.toHaveBeenCalled();
});
it.each(["paperclip-company-id", "paperclip-environment-id", "paperclip-run-id", "paperclip-create-attempt", "paperclip-provider"])("never deletes a sandbox with a mismatched %s", async (label) => {
let orphan: ReturnType<typeof ownedSandbox>;
mockGet.mockImplementation(async () => {
orphan = ownedSandbox(); orphan.labels[label] = "different-owner"; return orphan;
});
await expect(plugin.definition.onEnvironmentAcquireLease?.(params)).rejects.toThrow("cleanup could not be confirmed");
expect(orphan!.delete).not.toHaveBeenCalled();
});
it("never deletes a sandbox returned for a different name", async () => {
const wrong = { ...createMockSandbox(), labels: {} };
mockGet.mockResolvedValue(wrong);
await expect(plugin.definition.onEnvironmentAcquireLease?.(params)).rejects.toThrow("cleanup could not be confirmed");
expect(wrong.delete).not.toHaveBeenCalled();
});
it("does not treat a not-found lookup after uncertain creation as confirmed cleanup", async () => {
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("missing"));
await expect(plugin.definition.onEnvironmentAcquireLease?.(params)).rejects.toThrow("cleanup could not be confirmed");
expect(mockGet).toHaveBeenCalledTimes(1);
});
it("reports unconfirmed cleanup when the provider lookup fails", async () => {
mockGet.mockRejectedValue(new Error("provider unavailable"));
await expect(plugin.definition.onEnvironmentAcquireLease?.(params)).rejects.toThrow("cleanup could not be confirmed");
});
it("reports unconfirmed cleanup when provider deletion fails", async () => {
mockGet.mockImplementation(async () => {
const orphan = ownedSandbox(); orphan.delete.mockRejectedValue(new Error("delete failed")); return orphan;
});
await expect(plugin.definition.onEnvironmentAcquireLease?.(params)).rejects.toThrow("cleanup could not be confirmed");
});
it("bounds a hung provider lookup and preserves both failure causes", async () => {
vi.useFakeTimers();
try {
mockGet.mockImplementation(() => new Promise(() => {}));
const result = plugin.definition.onEnvironmentAcquireLease!(params).catch((error: unknown) => error);
await vi.advanceTimersByTimeAsync(10_001);
const error = await result;
expect(error).toBeInstanceOf(AggregateError);
expect((error as AggregateError).errors[0]).toBe(createError);
expect((error as Error).message).toContain(mockCreate.mock.calls[0][0].name);
} finally { vi.useRealTimers(); }
});
it("bounds a hung provider deletion without returning a lease", async () => {
vi.useFakeTimers();
try {
mockGet.mockImplementation(async () => {
const orphan = ownedSandbox(); orphan.delete.mockImplementation(() => new Promise(() => {})); return orphan;
});
const result = plugin.definition.onEnvironmentAcquireLease!(params).catch((error: unknown) => error);
await vi.advanceTimersByTimeAsync(15_001);
expect(await result).toBeInstanceOf(AggregateError);
} finally { vi.useRealTimers(); }
});
it("uses distinct creation identities for concurrent attempts on the same run", async () => {
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("missing"));
await Promise.allSettled([
plugin.definition.onEnvironmentAcquireLease?.(params),
plugin.definition.onEnvironmentAcquireLease?.(params),
]);
const requests = mockCreate.mock.calls.map(([request]) => request);
expect(requests).toHaveLength(2);
expect(new Set(requests.map((r) => r.name)).size).toBe(2);
expect(new Set(requests.map((r) => r.labels["paperclip-create-attempt"])).size).toBe(2);
});
});
it("rejects ambiguous or invalid config", async () => {
await expect(plugin.definition.onEnvironmentValidateConfig?.({
driverKey: "daytona",
config: {
apiUrl: "not-a-url",
image: "node:20",
snapshot: "snapshot-a",
timeoutMs: 0,
},
})).resolves.toEqual({
ok: false,
errors: [
"Daytona sandbox environments must set either image or snapshot, not both.",
"apiUrl must be a valid URL.",
"timeoutMs must be between 1 and 86400000.",
"Daytona sandbox environments require an API key in config or DAYTONA_API_KEY.",
],
});
});
it("probes by creating and then deleting a sandbox", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentProbe?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: false,
},
});
expect(mockCreate).toHaveBeenCalled();
expect(sandbox.fs.createFolder).toHaveBeenCalledWith("/home/daytona/paperclip-workspace", "755");
expect(sandbox.delete).toHaveBeenCalledWith(300, true);
expect(result).toMatchObject({
ok: true,
metadata: {
provider: "daytona",
shellCommand: "bash",
sandboxId: "sandbox-123",
remoteCwd: "/home/daytona/paperclip-workspace",
},
});
});
it("acquires a lease from a created sandbox", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
agentId: "agent-1",
executionWorkspaceId: "workspace-1",
adapterType: "codex_local",
config: {
image: "node:20",
timeoutMs: 300000,
reuseLease: true,
},
});
expect(lease).toMatchObject({
providerLeaseId: "sandbox-123",
metadata: {
provider: "daytona",
shellCommand: "bash",
sandboxId: "sandbox-123",
remoteCwd: "/home/daytona/paperclip-workspace",
reuseLease: true,
workspaceSentinel: {
path: "/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json",
result: "written",
},
},
});
expect(sandbox.fs.createFolder).toHaveBeenCalledWith(
"/home/daytona/paperclip-workspace/.paperclip-runtime",
"755",
);
expect(sandbox.fs.uploadFile).toHaveBeenCalledWith(
expect.any(Buffer),
"/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json",
300,
);
});
it("does not configure a provider ttl when the acquire carries no requested expiry", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
config: { image: "node:20", timeoutMs: 300000, reuseLease: false },
});
// A generic caller keeps the current behavior: no provider ttl, no expiry.
expect(sandbox.setTtl).not.toHaveBeenCalled();
expect(lease?.expiresAt ?? null).toBeNull();
});
it("configures a provider ttl at or before the requested expiry and returns the provider expiry", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const autoDestroyAt = new Date(Date.now() + 30 * 60_000).toISOString();
const sandbox = createMockSandbox({ autoDestroyAt });
mockCreate.mockResolvedValue(sandbox);
const requestedExpiresAt = new Date(Date.now() + 30 * 60_000 + 30_000).toISOString();
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
config: { image: "node:20", timeoutMs: 300000, reuseLease: false },
requestedExpiresAt,
});
// The provider ttl is rounded DOWN to whole minutes, so the destroy time
// never lands after the requested deadline.
expect(sandbox.setTtl).toHaveBeenCalledTimes(1);
expect(sandbox.setTtl).toHaveBeenCalledWith(30);
expect(sandbox.refreshData).toHaveBeenCalled();
// The lease carries the real provider destroy time as evidence of the bound.
expect(lease?.expiresAt).toBe(autoDestroyAt);
});
it("returns no expiry when the requested deadline is less than one minute away", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ autoDestroyAt: "must-not-be-read" });
mockCreate.mockResolvedValue(sandbox);
const requestedExpiresAt = new Date(Date.now() + 30_000).toISOString();
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
config: { image: "node:20", timeoutMs: 300000, reuseLease: false },
requestedExpiresAt,
});
// Daytona ttl granularity is one minute, so a nearer deadline maps to no
// valid provider ttl. The provider grants no expiry and the server fails
// closed on the null expiry.
expect(sandbox.setTtl).not.toHaveBeenCalled();
expect(lease?.expiresAt ?? null).toBeNull();
});
it("starts an interactive setup sandbox with redacted metadata and one-time SSH payload", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
const session = await plugin.definition.onEnvironmentStartInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
sessionId: "setup-1",
sourceTemplateRef: "existing-secret-snapshot",
sourceTemplateKind: "snapshot",
connectionExpiresInMinutes: 30,
config: {
image: "node:20",
timeoutMs: 300000,
reuseLease: false,
},
});
const [createParams] = mockCreate.mock.calls[0] as [Record<string, unknown>];
expect(createParams).toMatchObject({
snapshot: "existing-secret-snapshot",
labels: {
"paperclip-provider": "daytona",
"paperclip-setup-session-id": "setup-1",
"paperclip-purpose": "interactive_setup",
},
});
expect(createParams).not.toHaveProperty("image");
expect(sandbox.createSshAccess).toHaveBeenCalledWith(30);
expect(session).toMatchObject({
providerLeaseId: "sandbox-123",
status: "waiting_for_user",
connectionSummary: {
type: "ssh",
username: "token",
hostRedacted: true,
portRedacted: true,
commandRedacted: true,
},
connectionPayload: {
type: "ssh",
command: "ssh [email protected]",
token: "ssh-token-secret",
},
metadata: {
provider: "daytona",
connectionRedacted: true,
sourceTemplateRefRedacted: true,
},
});
expect(JSON.stringify(session?.metadata)).not.toContain("ssh-token-secret");
expect(JSON.stringify(session?.metadata)).not.toContain("existing-secret-snapshot");
expect(JSON.stringify(session?.connectionSummary)).not.toContain("ssh-token-secret");
});
it("starts interactive setup from an image source when the environment is image-backed", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentStartInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
sessionId: "setup-image-1",
sourceTemplateRef: "node:20",
sourceTemplateKind: "image",
connectionExpiresInMinutes: 30,
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: false,
},
});
const [createParams] = mockCreate.mock.calls[0] as [Record<string, unknown>];
expect(createParams).toMatchObject({
image: "node:20",
labels: {
"paperclip-provider": "daytona",
"paperclip-setup-session-id": "setup-image-1",
"paperclip-purpose": "interactive_setup",
},
});
expect(createParams).not.toHaveProperty("snapshot");
});
it("cleans up the setup sandbox if SSH access is unsupported", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
delete (sandbox as { createSshAccess?: unknown }).createSshAccess;
mockCreate.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentStartInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
sessionId: "setup-1",
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: false,
},
})).rejects.toThrow("Sandbox.createSshAccess");
expect(sandbox.delete).toHaveBeenCalledWith(300, true);
});
it("returns setup status without minting SSH access unless requested", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-setup" });
mockGet.mockResolvedValue(sandbox);
const session = await plugin.definition.onEnvironmentGetInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-setup",
includeConnectionPayload: false,
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: false,
},
});
expect(sandbox.createSshAccess).not.toHaveBeenCalled();
expect(session).toMatchObject({
providerLeaseId: "sandbox-setup",
status: "waiting_for_user",
connectionSummary: {
type: "ssh",
hostRedacted: true,
portRedacted: true,
},
connectionPayload: null,
});
});
it("returns missing setup status when the Daytona sandbox is gone", async () => {
process.env.DAYTONA_API_KEY = "host-key";
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("missing"));
await expect(plugin.definition.onEnvironmentGetInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-missing",
includeConnectionPayload: true,
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: false,
},
})).resolves.toEqual({
providerLeaseId: null,
status: "missing",
connectionSummary: null,
connectionPayload: null,
metadata: {
provider: "daytona",
missing: true,
},
});
});
it("captures a Daytona snapshot from a live setup sandbox with redacted metadata", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-setup" });
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentCaptureTemplate?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-setup",
templateLabel: " Paperclip Env 1 ",
sourceTemplateRef: "source-secret-snapshot",
previousTemplateRef: "previous-secret-snapshot",
timeoutMs: 120000,
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: false,
},
});
expect(sandbox._experimental_createSnapshot).toHaveBeenCalledWith("paperclip-env-1", 120);
expect(result).toMatchObject({
templateKind: "snapshot",
templateRef: "paperclip-env-1",
metadata: {
provider: "daytona",
sandboxId: "sandbox-setup",
sourceTemplateRefRedacted: true,
previousTemplateRefRedacted: true,
},
});
expect(JSON.stringify(result?.metadata)).not.toContain("source-secret-snapshot");
expect(JSON.stringify(result?.metadata)).not.toContain("previous-secret-snapshot");
});
it("cancels an interactive setup sandbox by deleting it", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-setup" });
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentCancelInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-setup",
reason: "user_cancelled",
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: false,
},
});
expect(sandbox.delete).toHaveBeenCalledWith(300, true);
expect(result).toMatchObject({
status: "cancelled",
metadata: {
provider: "daytona",
sandboxId: "sandbox-setup",
reason: "user_cancelled",
},
});
});
it("deletes Daytona snapshot templates through the snapshot service", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const snapshot = { name: "captured-template" };
mockSnapshotGet.mockResolvedValue(snapshot);
const result = await plugin.definition.onEnvironmentDeleteTemplate?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
templateRef: "captured-template",
templateKind: "snapshot",
reason: "cleanup",
config: {
snapshot: "base-snapshot",
timeoutMs: 300000,
reuseLease: false,
},
});
expect(mockSnapshotGet).toHaveBeenCalledWith("captured-template");
expect(mockSnapshotDelete).toHaveBeenCalledWith(snapshot);
expect(result).toEqual({
deleted: true,
metadata: {
provider: "daytona",
templateKind: "snapshot",
templateRefRedacted: true,
reason: "cleanup",
},
});
});
it("passes configured resources to Daytona for image-based creation", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
agentId: "agent-1",
executionWorkspaceId: "workspace-1",
adapterType: "codex_local",
config: {
image: "node:20",
cpu: 4,
memory: 8,
disk: 20,
timeoutMs: 300000,
reuseLease: true,
},
});
expect(mockCreate).toHaveBeenCalledTimes(1);
const [createParams] = mockCreate.mock.calls[0] as [Record<string, unknown>];
expect(createParams).toMatchObject({
image: "node:20",
resources: { cpu: 4, memory: 8, disk: 20, gpu: undefined },
});
expect(createParams).not.toHaveProperty("snapshot");
expect(sandbox.resize).not.toHaveBeenCalled();
});
it("drops resource settings for snapshot-backed runtime creation instead of failing", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
agentId: "agent-1",
executionWorkspaceId: "workspace-1",
adapterType: "codex_local",
config: {
snapshot: "captured-snapshot",
cpu: 4,
memory: 8,
disk: 20,
timeoutMs: 300000,
reuseLease: true,
},
});
expect(mockCreate).toHaveBeenCalledTimes(1);
const [createParams] = mockCreate.mock.calls[0] as [Record<string, unknown>];
expect(createParams).toMatchObject({ snapshot: "captured-snapshot" });
expect(createParams).not.toHaveProperty("resources");
expect(createParams).not.toHaveProperty("image");
});
it("rejects resource settings for snapshot-backed creation", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const result = await plugin.definition.onEnvironmentValidateConfig?.({
driverKey: "daytona",
config: {
snapshot: "base-snapshot",
cpu: 4,
memory: 8,
disk: 20,
timeoutMs: 300000,
reuseLease: true,
},
});
expect(result).toEqual({
ok: false,
errors: [
"Daytona resource settings require image-backed sandbox creation; snapshot/default sandbox creation cannot override CPU, memory, disk, or GPU.",
],
});
});
it("rejects resource settings for default sandbox creation before creating a sandbox", async () => {
process.env.DAYTONA_API_KEY = "host-key";
await expect(plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
agentId: "agent-1",
executionWorkspaceId: "workspace-1",
adapterType: "codex_local",
config: {
cpu: 4,
memory: 4,
timeoutMs: 300000,
reuseLease: false,
},
})).rejects.toThrow(
"Daytona resource settings require image-backed sandbox creation; default sandbox creation cannot override CPU, memory, disk, or GPU.",
);
expect(mockCreate).not.toHaveBeenCalled();
});
it("records requested resources in lease metadata", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockCreate.mockResolvedValue(sandbox);
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
agentId: "agent-1",
executionWorkspaceId: "workspace-1",
adapterType: "codex_local",
config: {
image: "daytonaio/sandbox:0.8.0",
cpu: 4,
memory: 8,
timeoutMs: 300000,
reuseLease: true,
},
});
expect(lease?.metadata).toMatchObject({ cpu: 4, memory: 8 });
expect(lease?.metadata).not.toHaveProperty("disk");
expect(lease?.metadata).not.toHaveProperty("gpu");
});
it.each(["matched", "mismatch", "missing", "foreign_run", "foreign_allocation", "legacy"])("verifies an ephemeral run-bound workspace before export recovery: %s", async outcome => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "ephemeral-owned" });
mockCreate.mockResolvedValue(sandbox);
const base = { driverKey: "daytona", companyId: "company-1", environmentId: "env-1", agentId: "agent-1",
issueId: "issue-1", adapterType: "paperclip_runner", config: { reuseLease: false } };
const lease = await plugin.definition.onEnvironmentAcquireLease!({ ...base, runId: "run-1" });
const sentinel = lease.metadata!.workspaceSentinel as { token: string; result: string };
expect(sentinel).toMatchObject({ token: expect.stringMatching(/^[a-f0-9]{64}$/), result: "written" });
const second = await plugin.definition.onEnvironmentAcquireLease!({ ...base, runId: "run-2" });
expect((second.metadata!.workspaceSentinel as { token: string }).token).not.toBe(sentinel.token);
sandbox.process.executeCommand.mockResolvedValueOnce({ exitCode: outcome === "missing" ? 1 : 0,
result: JSON.stringify({ token: outcome === "matched" ? sentinel.token : "foreign" }), artifacts: { stdout: "" } });
const metadata = { ...lease.metadata,
...(outcome === "foreign_run" ? { nativeWorkspaceExportResume: { runId: "foreign-run" } } : {}),
...(outcome === "legacy" ? { workspaceSentinel: { result: "skipped", token: null } } : {}) };
sandbox.fs.createFolder.mockClear(); sandbox.fs.uploadFile.mockClear(); sandbox.stop.mockClear();
const resumed = await plugin.definition.onEnvironmentResumeLease!({ ...base, providerLeaseId: outcome === "foreign_allocation" ? "replacement" : lease.providerLeaseId!, leaseMetadata: metadata });
expect(resumed).toMatchObject(outcome === "matched" ? { providerLeaseId: sandbox.id, metadata: { workspaceSentinel: { result: "matched" } } }
: { providerLeaseId: null, metadata: { expired: true, workspaceSentinel: { result: ["foreign_run", "foreign_allocation", "legacy"].includes(outcome) ? "mismatch" : outcome } } });
expect(sandbox.fs.createFolder).not.toHaveBeenCalled();
expect(sandbox.fs.uploadFile).not.toHaveBeenCalled();
expect(sandbox.stop).not.toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it("changes reusable-lease sentinel identity when resources change", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const acquireWithCpu = async (cpu: number): Promise<string> => {
const sandbox = createMockSandbox();
mockCreate.mockResolvedValueOnce(sandbox);
await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
agentId: "agent-1",
executionWorkspaceId: "workspace-1",
adapterType: "codex_local",
config: {
image: "daytonaio/sandbox:0.8.0",
cpu,
timeoutMs: 300000,
reuseLease: true,
},
});
const uploadCall = sandbox.fs.uploadFile.mock.calls.find(
(call) => typeof call[1] === "string" && call[1].endsWith("reusable-sandbox-lease.json"),
) as [Buffer, string, number] | undefined;
expect(uploadCall).toBeTruthy();
const parsed = JSON.parse((uploadCall as [Buffer, string, number])[0].toString("utf8")) as { token: string };
return parsed.token;
};
const tokenCpu1 = await acquireWithCpu(1);
const tokenCpu4 = await acquireWithCpu(4);
expect(tokenCpu1).toBeTruthy();
expect(tokenCpu4).toBeTruthy();
expect(tokenCpu1).not.toEqual(tokenCpu4);
});
it("deletes the sandbox if lease setup throws after sandbox creation", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.getWorkDir.mockRejectedValue(new Error("workdir lookup failed"));
mockCreate.mockResolvedValue(sandbox);
await expect(
plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
config: {
image: "node:20",
timeoutMs: 300000,
reuseLease: true,
},
}),
).rejects.toThrow("workdir lookup failed");
expect(sandbox.delete).toHaveBeenCalledTimes(1);
});
it("falls back to sh metadata when bash is not present in the sandbox image", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.executeCommand.mockResolvedValue({
exitCode: 0,
result: "sh",
artifacts: { stdout: "sh" },
});
mockCreate.mockResolvedValue(sandbox);
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
runId: "run-1",
config: {
image: "busybox:latest",
timeoutMs: 300000,
reuseLease: true,
},
});
expect(lease).toMatchObject({
metadata: {
shellCommand: "sh",
},
});
});
it("preserves the sandbox if resume setup throws after the sandbox starts", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-resume", state: "stopped" });
sandbox.getWorkDir.mockRejectedValue(new Error("workdir lookup failed"));
mockGet.mockResolvedValue(sandbox);
await expect(
plugin.definition.onEnvironmentResumeLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-resume",
config: {
timeoutMs: 300000,
reuseLease: true,
},
}),
).rejects.toThrow("workdir lookup failed");
expect(sandbox.start).toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it("marks missing reusable leases as expired on resume", async () => {
process.env.DAYTONA_API_KEY = "host-key";
mockGet.mockRejectedValue(new MockDaytonaNotFoundError("missing"));
await expect(plugin.definition.onEnvironmentResumeLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: {
timeoutMs: 300000,
reuseLease: true,
},
})).resolves.toEqual({
providerLeaseId: null,
metadata: { expired: true },
});
});
it("resumes a reusable lease when the workspace sentinel matches", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-reuse", state: "stopped" });
sandbox.process.executeCommand
.mockResolvedValueOnce({
exitCode: 0,
result: JSON.stringify({ token: "sentinel-token" }),
artifacts: { stdout: JSON.stringify({ token: "sentinel-token" }) },
})
.mockResolvedValueOnce({
exitCode: 0,
result: "bash",
artifacts: { stdout: "bash" },
});
mockGet.mockResolvedValue(sandbox);
const lease = await plugin.definition.onEnvironmentResumeLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-reuse",
config: {
timeoutMs: 300000,
reuseLease: true,
},
leaseMetadata: {
workspaceSentinel: {
path: "/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json",
token: "sentinel-token",
result: "written",
},
},
});
expect(sandbox.start).toHaveBeenCalledWith(300);
expect(lease).toMatchObject({
providerLeaseId: "sandbox-reuse",
metadata: {
resumedLease: true,
resumedFromState: "stopped",
sandboxState: "started",
workspaceSentinel: {
result: "matched",
token: "sentinel-token",
},
},
});
});
describe("missing-container resume", () => {
const sandboxId = "00000000-0000-4000-8000-000000000001";
const missing = `not found: failed to inspect sandbox container ${sandboxId}: Error response from daemon: No such container: ${sandboxId}`;
const params = {
driverKey: "daytona", companyId: "company-1", environmentId: "env-1", providerLeaseId: sandboxId,
config: { apiKey: "host-key", timeoutMs: 300000, livenessTimeoutMs: 100, reuseLease: true },
leaseMetadata: { workspaceSentinel: { path: "/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json", token: "sentinel-token" } },
};
const resume = () => plugin.definition.onEnvironmentResumeLease!(params);
function missingSandbox() {
return { ...createMockSandbox({ id: sandboxId, state: "error", recoverable: false }), errorReason: missing };
}
function allowSentinel(sandbox: ReturnType<typeof missingSandbox>) {
sandbox.process.executeCommand.mockResolvedValueOnce({ exitCode: 0,
result: JSON.stringify({ token: "sentinel-token" }), artifacts: { stdout: JSON.stringify({ token: "sentinel-token" }) },
});
}
it("expires a provider record with a freshly confirmed missing container without replacing it", async () => {
const sandbox = missingSandbox();
mockGet.mockResolvedValue(sandbox);
for (let attempt = 0; attempt < 2; attempt++) {
await expect(resume()).resolves.toEqual({ providerLeaseId: null, metadata: { expired: true } });
}
expect(mockGet).toHaveBeenCalledTimes(2);
expect(sandbox.refreshData).toHaveBeenCalledTimes(2);
expect(sandbox.start).not.toHaveBeenCalled();
expect(sandbox.recover).not.toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it.each(["sandbox-opaque", "sandbox.with+[literal](characters)"])("matches the opaque sandbox ID literally: %s", async (id) => {
const sandbox = { ...missingSandbox(), id, errorReason: missing.replaceAll(sandboxId, id) };
mockGet.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentResumeLease!({ ...params, providerLeaseId: id }))
.resolves.toEqual({ providerLeaseId: null, metadata: { expired: true } });
expect(sandbox.refreshData).toHaveBeenCalledOnce();
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it.each([
"not found: provider temporarily unavailable",
missing.replace("No such container:", "No such volume:"),
missing.replace(/000000000001$/, "000000000002"),
missing.replaceAll(sandboxId, "00000000-0000-4000-8000-000000000002"),
])("preserves an unexplained unrecoverable error: %s", async (errorReason) => {
const sandbox = { ...missingSandbox(), errorReason };
mockGet.mockResolvedValue(sandbox);
await expect(resume()).rejects.toThrow("unrecoverable error state");
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it("uses provider recovery when the sandbox is recoverable", async () => {
const sandbox = { ...missingSandbox(), recoverable: true };
allowSentinel(sandbox);
mockGet.mockResolvedValue(sandbox);
await expect(resume()).resolves.toMatchObject({ providerLeaseId: sandboxId });
expect(sandbox.recover).toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it("reuses a sandbox whose fresh state disproves the cached loss", async () => {
const sandbox = missingSandbox();
sandbox.refreshData.mockImplementation(async () => { sandbox.state = "started"; });
allowSentinel(sandbox);
mockGet.mockResolvedValue(sandbox);
await expect(resume()).resolves.toMatchObject({ providerLeaseId: sandboxId });
expect(sandbox.start).not.toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it.each([new MockDaytonaTimeoutError("timed out"), new Error("provider 503")])("preserves the lease if confirmation fails: %s", async (error) => {
const sandbox = missingSandbox();
sandbox.refreshData.mockRejectedValue(error);
mockGet.mockResolvedValue(sandbox);
await expect(resume()).rejects.toThrow(error.message);
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it("preserves an unknown error returned by the fresh provider read", async () => {
const sandbox = missingSandbox();
sandbox.refreshData.mockImplementation(async () => { sandbox.errorReason = "provider unavailable"; });
mockGet.mockResolvedValue(sandbox);
await expect(resume()).rejects.toThrow("unrecoverable error state");
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it("rejects a refreshed handle belonging to a different sandbox", async () => {
const sandbox = missingSandbox();
sandbox.refreshData.mockImplementation(async () => { sandbox.id = "another-sandbox"; });
mockGet.mockResolvedValue(sandbox);
await expect(resume()).rejects.toThrow("handle mismatch");
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it("accepts a typed not-found result while confirming the missing container", async () => {
const sandbox = missingSandbox();
sandbox.refreshData.mockRejectedValue(new MockDaytonaNotFoundError("missing"));
mockGet.mockResolvedValue(sandbox);
await expect(resume()).resolves.toEqual({ providerLeaseId: null, metadata: { expired: true } });
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
});
it("bounds a stalled confirmation and preserves the lease", async () => {
vi.useFakeTimers();
try {
const sandbox = missingSandbox();
sandbox.refreshData.mockImplementation(() => new Promise(() => {}));
mockGet.mockResolvedValue(sandbox);
const result = resume().then(() => null, error => error as Error);
await vi.advanceTimersByTimeAsync(101);
expect((await result)?.message).toContain("sandbox.refreshData");
expect(sandbox.delete).not.toHaveBeenCalled();
expect(mockCreate).not.toHaveBeenCalled();
} finally { vi.useRealTimers(); }
});
});
it("expires a reusable lease when the workspace sentinel does not match", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-reuse", state: "stopped" });
sandbox.process.executeCommand.mockResolvedValueOnce({
exitCode: 0,
result: JSON.stringify({ token: "other-token" }),
artifacts: { stdout: JSON.stringify({ token: "other-token" }) },
});
mockGet.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentResumeLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-reuse",
config: {
timeoutMs: 300000,
reuseLease: true,
},
leaseMetadata: {
workspaceSentinel: {
path: "/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json",
token: "sentinel-token",
result: "written",
},
},
})).resolves.toEqual({
providerLeaseId: null,
metadata: {
expired: true,
workspaceSentinel: {
path: "/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json",
token: "sentinel-token",
result: "mismatch",
},
},
});
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(1);
});
it("refreshes a cached stopped handle before granting a termination receipt", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-resumed", state: "stopped" });
sandbox.refreshData.mockImplementation(async () => { sandbox.state = "started"; });
mockGet.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: sandbox.id, config: { reuseLease: true },
})).resolves.toEqual({ providerLeaseId: sandbox.id, state: "stopped" });
expect(sandbox.refreshData).toHaveBeenCalled();
expect(sandbox.stop).toHaveBeenCalled();
});
it("does not acknowledge termination when both provider stop and delete fail", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-failed-stop", state: "started" });
sandbox.stop.mockRejectedValueOnce(new Error("stop failed"));
sandbox.delete.mockRejectedValueOnce(new Error("delete failed"));
mockGet.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: sandbox.id, config: { reuseLease: true },
})).rejects.toThrow("delete failed");
});
it.each([false, true])("explicit stop retains an ephemeral sandbox even when stop fails: %s", async fail => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-stop-only", state: "started" });
if (fail) sandbox.stop.mockRejectedValueOnce(new Error("stop failed"));
mockGet.mockResolvedValue(sandbox);
const stop = plugin.definition.onEnvironmentStopLease!({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: sandbox.id, config: { reuseLease: false },
});
if (fail) await expect(stop).rejects.toThrow("stop failed");
else await expect(stop).resolves.toEqual({ providerLeaseId: sandbox.id, state: "stopped" });
expect(sandbox.stop).toHaveBeenCalledTimes(1);
expect(sandbox.delete).not.toHaveBeenCalled();
});
it.each([true, false])("preserves an archived source only after fresh retention confirmation: %s", async confirmed => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-already-archived", state: "archived" });
sandbox.stop.mockRejectedValue(new Error("The provider rejects Stop for an archived sandbox"));
sandbox.refreshData.mockImplementation(async () => { sandbox.autoDeleteInterval = confirmed ? -1 : 0; });
mockGet.mockResolvedValue(sandbox);
const stop = plugin.definition.onEnvironmentStopLease!({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: sandbox.id, config: { reuseLease: false },
});
if (confirmed) await expect(stop).resolves.toEqual({ providerLeaseId: sandbox.id, state: "stopped" });
else await expect(stop).rejects.toThrow("retention policy was not confirmed");
expect(sandbox.setAutoDeleteInterval).toHaveBeenCalledWith(-1);
expect(sandbox.refreshData).toHaveBeenCalled();
expect(sandbox.stop).not.toHaveBeenCalled();
expect(sandbox.start).not.toHaveBeenCalled();
expect(sandbox.archive).not.toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it("stops an archived handle that a fresh provider read shows has resumed", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-archive-resumed", state: "archived" });
sandbox.refreshData.mockImplementation(async () => { sandbox.state = "started"; });
mockGet.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentStopLease!({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: sandbox.id, config: { reuseLease: false },
})).resolves.toEqual({ providerLeaseId: sandbox.id, state: "stopped" });
expect(sandbox.stop).toHaveBeenCalledOnce();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it("stops reusable leases and deletes ephemeral leases on release", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const reusable = createMockSandbox({ id: "sandbox-reusable" });
const ephemeral = createMockSandbox({ id: "sandbox-ephemeral" });
mockGet.mockResolvedValueOnce(reusable).mockResolvedValueOnce(ephemeral);
const reusableReceipt = await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-reusable",
config: {
timeoutMs: 300000,
reuseLease: true,
},
});
const ephemeralReceipt = await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-ephemeral",
config: {
timeoutMs: 300000,
reuseLease: false,
},
});
expect(reusableReceipt).toEqual({ providerLeaseId: "sandbox-reusable", state: "stopped" });
expect(ephemeralReceipt).toEqual({ providerLeaseId: "sandbox-ephemeral", state: "destroyed" });
expect(reusable.stop).toHaveBeenCalledWith(300);
expect(reusable.delete).not.toHaveBeenCalled();
expect(ephemeral.delete).toHaveBeenCalledWith(300, true);
});
it.each([false, true])("preserves an ephemeral completed workspace on explicit stop-and-retain (stop fails: %s)", async (stopFails) => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-saved-work", state: "started" });
if (stopFails) sandbox.stop.mockRejectedValueOnce(new Error("injected stop transport failure"));
mockGet.mockResolvedValue(sandbox);
const stop = plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: sandbox.id, config: { timeoutMs: 300000, reuseLease: false },
resourceDisposition: "stop_and_retain",
} as Parameters<NonNullable<typeof plugin.definition.onEnvironmentReleaseLease>>[0]);
if (stopFails) await expect(stop).rejects.toThrow("injected stop transport failure");
else await expect(stop).resolves.toEqual({ providerLeaseId: sandbox.id, state: "stopped" });
expect(sandbox.stop).toHaveBeenCalledOnce();
expect(sandbox.delete).not.toHaveBeenCalled();
expect(sandbox.archive).not.toHaveBeenCalled();
});
it.each(["confirmed", "setter_failed", "refresh_failed", "not_confirmed"])("disables provider auto-delete before preserving stopped work: %s", async kind => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = Object.assign(createMockSandbox({ id: "sandbox-auto-delete", state: "started" }), { autoDeleteInterval: 0 });
let providerAutoDelete = 0, implicitlyDeleted = false;
sandbox.setAutoDeleteInterval.mockImplementation(async () => {
if (kind === "setter_failed") throw new Error("setter unavailable");
sandbox.autoDeleteInterval = -1; // SDK setter updates its local field even without a fresh provider read.
if (kind !== "not_confirmed") providerAutoDelete = -1;
});
sandbox.refreshData.mockImplementation(async () => {
if (kind === "refresh_failed") throw new Error("refresh unavailable");
sandbox.autoDeleteInterval = providerAutoDelete;
});
sandbox.stop.mockImplementation(async () => { implicitlyDeleted = providerAutoDelete === 0; });
mockGet.mockResolvedValue(sandbox);
const stop = plugin.definition.onEnvironmentStopLease!({ driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: sandbox.id, config: { reuseLease: false, autoDeleteInterval: 0 } });
if (kind === "confirmed") {
await expect(stop).resolves.toEqual({ providerLeaseId: sandbox.id, state: "stopped" });
expect(sandbox.setAutoDeleteInterval).toHaveBeenCalledWith(-1);
expect(sandbox.setAutoDeleteInterval.mock.invocationCallOrder[0]).toBeLessThan(sandbox.refreshData.mock.invocationCallOrder.at(-1)!);
expect(sandbox.refreshData.mock.invocationCallOrder.at(-1)!).toBeLessThan(sandbox.stop.mock.invocationCallOrder[0]);
} else {
await expect(stop).rejects.toThrow();
expect(sandbox.stop).not.toHaveBeenCalled();
}
expect(implicitlyDeleted).toBe(false);
expect(sandbox.delete).not.toHaveBeenCalled();
expect(sandbox.archive).not.toHaveBeenCalled();
});
it("archives instead of deleting when the lease was acquired with archiveOnRelease", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-test-probe", state: "started" });
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-test-probe",
config: {
timeoutMs: 300000,
reuseLease: false,
archiveOnRelease: true,
},
});
expect(sandbox.stop).toHaveBeenCalledWith(300);
expect(sandbox.setAutoDeleteInterval).toHaveBeenCalledWith(60);
expect(sandbox.archive).toHaveBeenCalled();
expect(sandbox.delete).not.toHaveBeenCalled();
});
it("falls back to delete when archiving an archiveOnRelease lease fails", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-test-probe", state: "stopped" });
sandbox.archive.mockRejectedValueOnce(new Error("archive unsupported"));
mockGet.mockResolvedValue(sandbox);
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-test-probe",
config: {
timeoutMs: 300000,
reuseLease: false,
archiveOnRelease: true,
},
});
expect(sandbox.stop).not.toHaveBeenCalled();
expect(sandbox.archive).toHaveBeenCalled();
expect(sandbox.delete).toHaveBeenCalledWith(300, true);
expect(warnSpy).toHaveBeenCalled();
});
it("falls back to delete when stopping a reusable lease from an error state fails", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const errored = createMockSandbox({ id: "sandbox-error", state: "error" });
errored.stop.mockRejectedValueOnce(new Error("stop failed"));
mockGet.mockResolvedValue(errored);
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-error",
config: {
timeoutMs: 300000,
reuseLease: true,
},
});
expect(errored.stop).toHaveBeenCalledWith(300);
expect(errored.delete).toHaveBeenCalledWith(300, true);
});
it("falls back to delete when stopping a healthy reusable lease fails mid-call", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-running", state: "started" });
sandbox.stop.mockRejectedValueOnce(new Error("api timeout"));
mockGet.mockResolvedValue(sandbox);
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-running",
config: {
timeoutMs: 300000,
reuseLease: true,
},
});
expect(sandbox.stop).toHaveBeenCalledWith(300);
expect(sandbox.delete).toHaveBeenCalledWith(300, true);
expect(warnSpy).toHaveBeenCalled();
});
describe("session model lifecycle (per-lease session store)", () => {
// A recording plugin tracer that captures every provider span the session
// hooks open. It satisfies the structural plugin tracer contract.
const makeRecordingTracer = () => {
const spans: Array<{
name: string;
attributes: Record<string, unknown>;
status: { code: number; message?: string } | null;
ended: boolean;
}> = [];
const tracer = {
startSpan(name: string, options?: { attributes?: Record<string, string | number | boolean> }) {
const span = {
name,
attributes: { ...(options?.attributes ?? {}) } as Record<string, unknown>,
status: null as { code: number; message?: string } | null,
ended: false,
setAttribute(key: string, value: unknown) {
span.attributes[key] = value;
},
setStatus(status: { code: number; message?: string }) {
span.status = status;
},
end() {
span.ended = true;
},
};
spans.push(span);
return span;
},
};
return { tracer, spans };
};
const sessionExecParams = (overrides: Record<string, unknown> = {}) => ({
driverKey: "daytona" as const,
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "printf",
args: ["hello"],
cwd: "/workspace",
timeoutMs: 1000,
...overrides,
});
it("opens one session when two first commands overlap", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
// Hold the first session create open, so the second first command reaches
// the session store before the first create resolves. Without a single
// flight guard, both commands would open a session for one lease and the
// first session id would leak.
let releaseCreate: () => void = () => {};
const createGate = new Promise<void>((resolve) => {
releaseCreate = resolve;
});
sandbox.process.createSession.mockImplementationOnce(async () => {
await createGate;
});
const first = plugin.definition.onEnvironmentExecute?.(sessionExecParams());
const second = plugin.definition.onEnvironmentExecute?.(sessionExecParams());
// Flush the pending microtasks, so both commands park on the held create.
await new Promise((resolve) => setTimeout(resolve, 0));
releaseCreate();
await Promise.all([first, second]);
expect(sandbox.process.createSession).toHaveBeenCalledTimes(1);
const sessionId = sandbox.process.createSession.mock.calls[0]![0] as string;
// Teardown deletes the same single session id, so no session leaks.
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
});
expect(sandbox.process.deleteSession).toHaveBeenCalledTimes(1);
expect(sandbox.process.deleteSession).toHaveBeenCalledWith(sessionId);
});
it("runs a bypassSession command one-shot and leaves the session closed", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
// The provision command runs before the run opens its trace root, so the
// host marks it `bypassSession`. The provider must not open the session for
// it, or the `session.open` span loses its run parent.
await plugin.definition.onEnvironmentExecute?.(
sessionExecParams({ bypassSession: true }),
);
expect(sandbox.process.createSession).not.toHaveBeenCalled();
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(1);
});
it("opens the session on the first in-run command after a bypassSession command", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
// A bypassSession command runs first (no session), then an in-run command
// opens the one session. The session-setup span then parents to the run
// trace, and every later in-run command reuses the same session.
await plugin.definition.onEnvironmentExecute?.(
sessionExecParams({ bypassSession: true }),
);
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
expect(sandbox.process.createSession).toHaveBeenCalledTimes(1);
const sessionId = sandbox.process.createSession.mock.calls[0]![0] as string;
expect(sessionId).toMatch(/^paperclip-/);
});
it("deletes the session and clears the store on release", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
const sessionId = sandbox.process.createSession.mock.calls[0]![0] as string;
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
});
expect(sandbox.process.deleteSession).toHaveBeenCalledWith(sessionId);
});
it("deletes the session at destroy even when the sandbox delete throws", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.delete.mockRejectedValueOnce(new Error("delete failed"));
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
const sessionId = sandbox.process.createSession.mock.calls[0]![0] as string;
await expect(
plugin.definition.onEnvironmentDestroyLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
}),
).rejects.toThrow(/delete failed/);
expect(sandbox.process.deleteSession).toHaveBeenCalledWith(sessionId);
});
it("deletes the session on interactive-setup cancel", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
const sessionId = sandbox.process.createSession.mock.calls[0]![0] as string;
await plugin.definition.onEnvironmentCancelInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
});
expect(sandbox.process.deleteSession).toHaveBeenCalledWith(sessionId);
});
it("logs loudly and does not throw when the session delete fails", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.deleteSession.mockRejectedValueOnce(new Error("session gone"));
mockGet.mockResolvedValue(sandbox);
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
const sessionId = sandbox.process.createSession.mock.calls[0]![0] as string;
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
});
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining(sessionId));
// The rest of teardown still ran: the ephemeral sandbox was deleted.
expect(sandbox.delete).toHaveBeenCalledWith(300, true);
});
it("returns a destroy receipt only after the provider confirms deletion", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
let complete!: () => void;
sandbox.delete.mockImplementationOnce(() => new Promise<void>(resolve => { complete = resolve; }));
const release = plugin.definition.onEnvironmentDestroyLease!({ driverKey: "daytona",
companyId: "company-1", environmentId: "env-1", providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false } });
let settled = false;
void Promise.resolve(release).then(() => { settled = true; });
await vi.waitFor(() => expect(sandbox.delete).toHaveBeenCalledWith(300, true));
expect(settled).toBe(false);
complete();
await expect(release).resolves.toEqual({ providerLeaseId: "sandbox-123", state: "destroyed" });
});
it("clears the session store after delete so no orphan id survives a second teardown", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const releaseParams = {
driverKey: "daytona" as const,
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: true },
};
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
await plugin.definition.onEnvironmentReleaseLease?.(releaseParams);
// The store is now clear. A second teardown finds no id and does not delete
// a session again, which proves no orphan id survived the first delete.
await plugin.definition.onEnvironmentReleaseLease?.(releaseParams);
expect(sandbox.process.deleteSession).toHaveBeenCalledTimes(1);
});
it("clears the session store when resume restarts a stopped sandbox", async () => {
process.env.DAYTONA_API_KEY = "host-key";
// A stopped sandbox lost its session shell, so resume must clear the stale
// id and the next execute must open a fresh session.
const sandbox = createMockSandbox({ state: "stopped" });
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
expect(sandbox.process.createSession).toHaveBeenCalledTimes(1);
await plugin.definition.onEnvironmentResumeLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
leaseMetadata: {
remoteCwd: "/home/daytona/paperclip-workspace",
workspaceSentinel: {
path: "/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json",
token: "token-1",
},
},
});
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
expect(sandbox.process.createSession).toHaveBeenCalledTimes(2);
});
it("keeps the session when resume runs on a still-running sandbox", async () => {
process.env.DAYTONA_API_KEY = "host-key";
// A running sandbox keeps its live session shell. Resume must not clear the
// stored id, or a later command opens a second session and teardown deletes
// only one, so the first session leaks until sandbox reaping.
const sandbox = createMockSandbox({ state: "started" });
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
expect(sandbox.process.createSession).toHaveBeenCalledTimes(1);
const sessionId = sandbox.process.createSession.mock.calls[0]![0] as string;
await plugin.definition.onEnvironmentResumeLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
leaseMetadata: {
remoteCwd: "/home/daytona/paperclip-workspace",
workspaceSentinel: {
path: "/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json",
token: "token-1",
},
},
});
// The next command reuses the one live session, so no second session opens.
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
expect(sandbox.process.createSession).toHaveBeenCalledTimes(1);
// Teardown deletes the one session id, so no shell leaks.
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
});
expect(sandbox.process.deleteSession).toHaveBeenCalledTimes(1);
expect(sandbox.process.deleteSession).toHaveBeenCalledWith(sessionId);
});
it("emits a session.open span on create and a session.close span on delete", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = makeRecordingTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
const setup = spans.find((span) => span.name === "session.open");
expect(setup).toBeDefined();
expect(setup!.ended).toBe(true);
expect(setup!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
});
const teardown = spans.find((span) => span.name === "session.close");
expect(teardown).toBeDefined();
expect(teardown!.ended).toBe(true);
expect(teardown!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");
} finally {
restore();
}
});
it("marks the session.open span failed when the session create throws", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.createSession.mockRejectedValueOnce(new Error("create boom"));
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = makeRecordingTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await expect(
plugin.definition.onEnvironmentExecute?.(sessionExecParams()),
).rejects.toThrow(/create boom/);
const setup = spans.find((span) => span.name === "session.open");
expect(setup).toBeDefined();
expect(setup!.ended).toBe(true);
expect(setup!.status?.code).toBe(2);
} finally {
restore();
}
});
it("dispatches commands into the session and returns separate stdout and stderr", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.getSessionCommand.mockResolvedValue({ id: "cmd-1", command: "", exitCode: 7 });
sandbox.process.getSessionCommand.mockResolvedValueOnce({ exitCode: undefined });
// A session command tries the log stream first: it delivers stdout and
// stderr from the callback log form.
sandbox.process.getSessionCommandLogs.mockImplementation(
async (
_sid: string,
_cmdId: string,
onStdout?: (chunk: string) => void,
onStderr?: (chunk: string) => void,
) => {
onStdout?.("out-here");
onStderr?.("err-here");
},
);
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
// The command runs through the session, not the one-shot path.
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).not.toHaveBeenCalled();
const [sid, req, timeoutArg] = sandbox.process.executeSessionCommand.mock.calls[0] as [
string,
{ command: string; runAsync?: boolean },
number,
];
expect(sid).toMatch(/^paperclip-/);
expect(req.runAsync).toBe(true);
expect(timeoutArg).toBe(1);
// The built command carries the login-shell script and the user command.
expect(req.command).toMatch(/&& env .*'printf' 'hello'/);
// The session command runs plain: no bwrap wrapper and no su privilege drop.
expect(req.command).not.toContain("sudo -n bwrap");
expect(req.command).not.toContain("su -s /bin/sh");
// True separated streams come from the callback log stream.
expect(result).toMatchObject({ exitCode: 7, timedOut: false, stdout: "out-here", stderr: "err-here" });
expect(typeof (result!.metadata as Record<string, unknown>)?.durationMs).toBe("number");
});
it("wraps each user command in a subshell so a top-level exit cannot kill the session shell", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(
sessionExecParams({ command: "exit", args: ["3"] }),
);
const [, req] = sandbox.process.executeSessionCommand.mock.calls[0] as [
string,
{ command: string },
];
// The whole login-shell script (with the user `exit`) runs inside a
// subshell, so a top-level exit ends the subshell, not the session shell.
expect(req.command.trimStart()).toMatch(/^\(/);
expect(req.command.trimEnd()).toMatch(/\)$/);
expect(req.command).toMatch(/'exit' '3'/);
});
it("reuses the same session (one persistent shell) across commands", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
await plugin.definition.onEnvironmentExecute?.(sessionExecParams());
expect(sandbox.process.createSession).toHaveBeenCalledTimes(1);
const sessionId = sandbox.process.createSession.mock.calls[0]![0] as string;
expect(sessionId).toMatch(/^paperclip-/);
const firstSid = sandbox.process.executeSessionCommand.mock.calls[0]![0] as string;
const secondSid = sandbox.process.executeSessionCommand.mock.calls[1]![0] as string;
expect(firstSid).toBe(secondSid);
});
it("returns a session timeout on the poll fallback when the command never reports an exit code", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
// The log stream fails, so the dispatch falls back to the poll path. The
// command stays running there: the exit code never arrives, so the poll
// deadline fires.
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void) => {
if (onStdout) {
throw new Error("socket error");
}
return { stdout: "", stderr: "" };
},
);
sandbox.process.getSessionCommand.mockResolvedValue({ id: "cmd-1", command: "", exitCode: undefined });
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(
sessionExecParams({ timeoutMs: 1 }),
);
expect(result).toMatchObject({ exitCode: null, timedOut: true });
expect(result!.stderr).toMatch(/timed out/);
});
describe("log stream (default)", () => {
const createStreamingSandbox = () => {
const sandbox = createMockSandbox();
sandbox.process.getSessionCommand.mockResolvedValueOnce({ exitCode: undefined });
return sandbox;
};
// A session command tries the log stream first. It streams stdout and
// stderr from the callback log form instead of the 50-ms poll, and falls
// back to the poll only when the stream fails.
const streamExecParams = (overrides: Record<string, unknown> = {}) =>
sessionExecParams(overrides);
// Long-lived healthy streams keep producing output. Quiet streams now
// switch to snapshots, which have separate lifetime coverage below.
async function streamFor(ms: number, onStderr?: (chunk: string) => void) {
const timer = setInterval(() => onStderr?.("."), 10_000);
try { await new Promise((resolve) => setTimeout(resolve, ms)); }
finally { clearInterval(timer); }
}
it("completes a session command beyond a synchronous gateway deadline without redispatch", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
sandbox.process.executeCommand.mockRejectedValue(new MockDaytonaTimeoutError("opaque gateway timeout"));
sandbox.process.getSessionCommand.mockResolvedValue({ exitCode: 0 });
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void) => {
if (!onStdout) return { stdout: "first;last;", stderr: "" };
onStdout("first;");
await streamFor(3_600_001, onStderr);
onStdout("last;");
},
);
mockGet.mockResolvedValue(sandbox);
vi.useFakeTimers();
try {
const params = streamExecParams({ timeoutMs: 14_400_000, commandTimeoutMs: 14_400_000 });
// Characterize the one-shot transport failure with the same command
// and budget, then exercise the existing asynchronous session path.
expect(await plugin.definition.onEnvironmentExecute?.({ ...params, bypassSession: true }))
.toMatchObject({ timedOut: true, exitCode: null });
sandbox.process.executeCommand.mockClear();
const pending = plugin.definition.onEnvironmentExecute?.(params);
await vi.advanceTimersByTimeAsync(3_600_002);
expect(await pending).toMatchObject({ timedOut: false, exitCode: 0, stdout: "first;last;" });
expect(sandbox.process.executeCommand).not.toHaveBeenCalled();
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeSessionCommand.mock.calls[0]![1]).toMatchObject({ runAsync: true });
expect(sandbox.process.executeSessionCommand.mock.calls[0]![2]).toBe(14400);
await plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: "sandbox-123", config: params.config,
});
expect(sandbox.process.deleteSession).toHaveBeenCalledTimes(1);
} finally { vi.useRealTimers(); }
});
it.each([undefined, 0])("preserves the existing healthy session lifetime with command timeout %s", async (commandTimeoutMs) => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
sandbox.process.getSessionCommand.mockResolvedValue({ exitCode: 0 });
sandbox.process.getSessionCommandLogs.mockImplementation(async (_s: string, _c: string, stdout?: (chunk: string) => void, stderr?: (chunk: string) => void) => {
if (!stdout) return { stdout: "done;", stderr: "" };
await streamFor(60_000, stderr);
stdout("done;");
});
mockGet.mockResolvedValue(sandbox);
vi.useFakeTimers();
try {
const pending = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 1000, commandTimeoutMs }));
await vi.advanceTimersByTimeAsync(60_000);
expect(await pending).toMatchObject({ timedOut: false, exitCode: 0, stdout: "done;" });
expect(vi.getTimerCount()).toBe(0);
} finally { vi.useRealTimers(); }
});
it("removes deadline listeners from completed reads during a quiet polling run", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
sandbox.process.getSessionCommand.mockResolvedValue({ exitCode: undefined });
sandbox.process.getSessionCommandLogs.mockImplementation(async (_s: string, _c: string, stdout?: (chunk: string) => void) => {
if (stdout) { stdout("partial;"); return; }
return { stdout: "partial;", stderr: "" };
});
mockGet.mockResolvedValue(sandbox);
const added = vi.spyOn(AbortSignal.prototype, "addEventListener");
const removed = vi.spyOn(AbortSignal.prototype, "removeEventListener");
vi.useFakeTimers();
try {
const pending = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 60_000, commandTimeoutMs: 60_000 }));
await vi.advanceTimersByTimeAsync(30_000);
const signal = added.mock.contexts.find((value, index) => added.mock.calls[index]?.[0] === "abort");
expect(signal).toBeDefined();
const count = (spy: typeof added | typeof removed) => spy.mock.calls.filter((call, index) => call[0] === "abort" && spy.mock.contexts[index] === signal).length;
expect(count(added)).toBeGreaterThan(50);
expect(count(added) - count(removed)).toBeLessThanOrEqual(1);
await vi.advanceTimersByTimeAsync(30_000);
expect(await pending).toMatchObject({ timedOut: true, exitCode: null, stdout: "partial;" });
expect(count(removed)).toBe(count(added));
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally { added.mockRestore(); removed.mockRestore(); vi.useRealTimers(); }
});
it.each(["stream", "status", "snapshot", "dispatch", "final snapshot"])("preserves a command deadline during a healthy or stalled %s observation", async (phase) => {
process.env.DAYTONA_API_KEY = "host-key";
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest({ execution: { log: executionLog } } as unknown as PluginContext);
const sandbox = createStreamingSandbox();
let lateOutput: ((chunk: string) => void) | undefined;
let rejectStream: ((error: Error) => void) | undefined;
let keepAlive: ReturnType<typeof setInterval> | undefined;
sandbox.process.getSessionCommand.mockResolvedValue({ exitCode: phase === "final snapshot" ? 0 : undefined });
sandbox.process.getSessionCommandLogs.mockImplementation(async (_s: string, _c: string, stdout?: (chunk: string) => void) => {
if (!stdout) {
if (phase === "snapshot" || phase === "final snapshot") return new Promise(() => {});
return { stdout: "first;", stderr: "" };
}
stdout("first;");
if (phase === "stream") {
lateOutput = stdout;
keepAlive = setInterval(() => stdout("."), 10000);
return new Promise((_resolve, reject) => { rejectStream = reject; });
}
});
if (phase === "status") sandbox.process.getSessionCommand.mockImplementation(async () => new Promise(() => {}));
if (phase === "dispatch") sandbox.process.executeSessionCommand.mockImplementation(async () => new Promise(() => {}));
mockGet.mockResolvedValue(sandbox);
vi.useFakeTimers();
try {
const pending = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 14_400_000, commandTimeoutMs: 60000 }));
let settled = false;
void pending?.then(() => { settled = true; });
await vi.advanceTimersByTimeAsync(59999);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(1);
const result = await pending;
expect(result).toMatchObject({ timedOut: true, exitCode: null });
if (phase === "final snapshot") {
expect(result?.metadata).toMatchObject({ timeoutScope: "session_log_observation", commandExitConfirmed: true, observedExitCode: 0 });
expect(result?.stderr).toContain("Session log observation timed out after 60 s; final output may be incomplete.");
} else expect(result?.stderr).toContain("Command timed out after 60 s.");
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).not.toHaveBeenCalled();
const logged = executionLog.mock.calls.length;
lateOutput?.("late private output");
rejectStream?.(new Error("late transport rejection"));
await vi.advanceTimersByTimeAsync(1);
expect(executionLog.mock.calls.length).toBe(logged);
expect(JSON.stringify(result)).not.toContain("late private");
clearInterval(keepAlive);
await plugin.definition.onEnvironmentReleaseLease?.({ driverKey: "daytona", companyId: "company-1", environmentId: "env-1", providerLeaseId: "sandbox-123", config: streamExecParams().config });
expect(sandbox.process.deleteSession).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally { clearInterval(keepAlive); restore(); vi.useRealTimers(); }
});
it.each(["", "prefix;🙂;"])("recovers unseen output and cancellation from a stuck socket after prefix %j", async (prefix) => {
process.env.DAYTONA_API_KEY = "host-key";
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest(
{ execution: { log: executionLog } } as unknown as PluginContext,
);
const sandbox = createStreamingSandbox();
let lateOutput!: (chunk: string) => void;
let rejectStream!: (error: Error) => void;
let snapshots = 0;
let cancelled = false;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void) => {
if (onStdout) {
lateOutput = onStdout;
onStdout(prefix);
return new Promise((_resolve, reject) => { rejectStream = reject; });
}
snapshots += 1;
return { stdout: prefix + "permission;" + (cancelled ? "cancelled;" : ""), stderr: "" };
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => ({ exitCode: cancelled ? 0 : undefined }));
mockGet.mockResolvedValue(sandbox);
vi.useFakeTimers();
try {
const promise = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 400 }));
let settled = false;
void promise?.then(() => { settled = true; });
await vi.advanceTimersByTimeAsync(14_999);
expect(snapshots).toBe(0);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(1);
expect(snapshots).toBe(1);
expect(executionLog).toHaveBeenCalledWith("stdout", "permission;");
// The abandoned socket cannot corrupt snapshot cursors or publish
// output after the timeout, including a delayed rejection.
lateOutput("stale bytes");
rejectStream(new Error("late socket failure"));
await vi.advanceTimersByTimeAsync(2_000);
expect(settled).toBe(false);
expect(snapshots).toBe(3);
cancelled = true;
await vi.advanceTimersByTimeAsync(1_000);
expect(await promise).toMatchObject({ exitCode: 0, timedOut: false, stdout: prefix + "permission;cancelled;" });
lateOutput("after settlement");
expect(executionLog.mock.calls).toEqual([
...(prefix ? [["stdout", prefix]] : []), ["stdout", "permission;"], ["stdout", "cancelled;"],
]);
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(sandbox.process.getSessionCommandLogs.mock.calls.filter((call) => call[2])).toHaveLength(1);
expect(vi.getTimerCount()).toBe(0);
} finally {
vi.useRealTimers();
restore();
}
});
it.each(["status", "snapshot"])("bounds a stuck %s read after an idle socket without claiming exit", async (stalledRead) => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
let releaseRead!: () => void;
const stalled = new Promise<void>((resolve) => { releaseRead = resolve; });
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest(
{ execution: { log: executionLog } } as unknown as PluginContext,
);
sandbox.process.getSessionCommand.mockImplementation(async () => {
if (stalledRead === "status") await stalled;
return { exitCode: undefined };
});
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void) => {
if (onStdout) {
onStdout("prefix;");
return new Promise(() => {});
}
await stalled;
return { stdout: "prefix;late;", stderr: "" };
},
);
mockGet.mockResolvedValue(sandbox);
vi.useFakeTimers();
try {
const promise = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 400 }));
await vi.advanceTimersByTimeAsync(15_400);
expect(await promise).toMatchObject({
exitCode: null, timedOut: true, stdout: "prefix;",
metadata: { timeoutScope: "session_log_observation", commandExitConfirmed: false },
});
releaseRead();
await vi.advanceTimersByTimeAsync(1_000);
expect(executionLog.mock.calls).toEqual([["stdout", "prefix;"]]);
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally {
releaseRead();
vi.useRealTimers();
restore();
}
});
it("streams ordered stdout and stderr from the callback log form (test_log_stream_delivers_ordered_chunks)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
sandbox.process.getSessionCommand.mockResolvedValue({ id: "cmd-1", command: "", exitCode: 0 });
// The callback form emits stdout and stderr chunks in order. The plugin
// keeps each stream in its own arrival order.
sandbox.process.getSessionCommandLogs.mockImplementation(
async (
_sid: string,
_cmdId: string,
onStdout?: (chunk: string) => void,
onStderr?: (chunk: string) => void,
) => {
onStdout?.("out-1;");
onStderr?.("err-1;");
onStdout?.("out-2;");
onStderr?.("err-2;");
},
);
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams());
// One callback stream plus a final snapshot to reconcile unseen bytes.
expect(sandbox.process.getSessionCommandLogs).toHaveBeenCalledTimes(2);
const streamCall = sandbox.process.getSessionCommandLogs.mock.calls[0]!;
expect(typeof streamCall[2]).toBe("function");
expect(typeof streamCall[3]).toBe("function");
expect(result).toMatchObject({
exitCode: 0,
timedOut: false,
stdout: "out-1;out-2;",
stderr: "err-1;err-2;",
});
expect(typeof (result!.metadata as Record<string, unknown>)?.durationMs).toBe("number");
});
it("reads the exit code once after the stream ends (test_log_stream_reads_exit_code_once_after_stream_end)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
sandbox.process.getSessionCommand.mockResolvedValue({ id: "cmd-1", command: "", exitCode: 5 });
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void) => {
onStdout?.("done");
},
);
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams());
// The exit code read runs one time after the stream promise resolves.
expect(sandbox.process.getSessionCommand).toHaveBeenCalledTimes(2);
expect(result).toMatchObject({ exitCode: 5, timedOut: false, stdout: "done" });
});
it("keeps a running command alive after a clean log-stream close", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest(
{ execution: { log: executionLog } } as unknown as PluginContext,
);
try {
const sandbox = createStreamingSandbox();
let streams = 0;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void) => {
if (!onStdout) return { stdout: "first;last;", stderr: "" };
streams += 1;
onStdout?.("first;");
if (streams === 2) onStdout?.("last;");
// The SDK resolves on WebSocket close, including an idle close.
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => ({
id: "cmd-1", command: "", exitCode: streams === 1 ? undefined : 7,
}));
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 2000 }));
expect(result).toMatchObject({ exitCode: 7, timedOut: false, stdout: "first;last;" });
expect(executionLog.mock.calls).toEqual([["stdout", "first;"], ["stdout", "last;"]]);
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(streams).toBe(2);
} finally {
restore();
}
});
it.each(["first;live;done;", "first;"])("polls live output after repeated clean stream closes with terminal snapshot %j", async (finalSnapshot) => {
process.env.DAYTONA_API_KEY = "host-key";
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest(
{ execution: { log: executionLog } } as unknown as PluginContext,
);
try {
const sandbox = createStreamingSandbox();
let snapshots = 0;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void) => {
if (onStdout) {
onStdout("first;");
return;
}
snapshots += 1;
return { stdout: snapshots === 1 ? "first;live;" : finalSnapshot, stderr: "" };
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => {
if (snapshots > 0) {
// New output must reach the bridge while the command still runs.
expect(executionLog).toHaveBeenCalledWith("stdout", "live;");
}
return { id: "cmd-1", command: "", exitCode: snapshots > 0 ? 9 : undefined };
});
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 2000 }));
expect(result).toMatchObject({
exitCode: 9, timedOut: false, stdout: finalSnapshot.length > 11 ? finalSnapshot : "first;live;",
});
expect(executionLog.mock.calls).toEqual([
["stdout", "first;"], ["stdout", "live;"],
...(finalSnapshot.endsWith("done;") ? [["stdout", "done;"]] : []),
]);
expect(sandbox.process.getSessionCommandLogs.mock.calls.filter((call) => call[2]).length).toBe(2);
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
} finally {
restore();
}
});
it.each(["close", "reject"])("preserves healthy stream lifetimes after an aged %s", async (ending) => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
let streams = 0;
let exited = false;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void) => {
if (!onStdout) return { stdout: "first;last;", stderr: "" };
streams += 1;
onStdout("first;");
await streamFor(3_600_000, onStderr);
if (streams === 1 && ending === "reject") throw new Error("socket error");
if (streams === 2) { onStdout("last;"); exited = true; }
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => ({ exitCode: exited ? 7 : undefined }));
mockGet.mockResolvedValue(sandbox);
vi.useFakeTimers();
try {
const promise = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 300_000 }));
let settled = false;
void promise?.then(() => { settled = true; });
await vi.advanceTimersByTimeAsync(3_600_000);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(350);
expect(streams).toBe(2);
await vi.advanceTimersByTimeAsync(300_001);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(3_300_000);
expect(await promise).toMatchObject({ exitCode: 7, timedOut: false, stdout: "first;last;" });
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally {
vi.useRealTimers();
}
});
it("polls an aged running command after repeated EOF without inventing an exit or lifetime cap", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
let streams = 0;
let snapshots = 0;
let exited = false;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void) => {
if (!onStdout) { snapshots += 1; return { stdout: "partial;", stderr: "" }; }
onStdout("partial;");
if (++streams === 1) await streamFor(3_600_000, onStderr);
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => ({ exitCode: exited ? 0 : undefined }));
mockGet.mockResolvedValue(sandbox);
vi.useFakeTimers();
try {
const promise = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 400 }));
let settled = false;
void promise?.then(() => { settled = true; });
await vi.advanceTimersByTimeAsync(3_602_700);
expect(settled).toBe(false);
expect(snapshots).toBe(3);
exited = true;
await vi.advanceTimersByTimeAsync(1000);
expect(await promise).toMatchObject({ exitCode: 0, timedOut: false, stdout: "partial;" });
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally {
vi.useRealTimers();
}
});
it.each([0, 3_600_000])("retains the fallback budget and partial output after a failed stream lasting %i ms", async (streamLifetime) => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
let streams = 0;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void) => {
if (onStdout) {
onStdout("partial;");
if (++streams === 1 && streamLifetime > 0) await streamFor(streamLifetime, onStderr);
throw new Error("socket error");
}
return { stdout: "partial;", stderr: "" };
},
);
sandbox.process.getSessionCommand.mockResolvedValue({ exitCode: undefined });
mockGet.mockResolvedValue(sandbox);
vi.useFakeTimers();
try {
const promise = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 400 }));
let settled = false;
void promise?.then(() => { settled = true; });
await vi.advanceTimersByTimeAsync(streamLifetime + 399);
expect(settled).toBe(false);
expect(streams).toBe(2);
await vi.advanceTimersByTimeAsync(1);
expect(await promise).toMatchObject({ exitCode: null, timedOut: true, stdout: "partial;" });
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally {
vi.useRealTimers();
}
});
it("preserves provider status errors after a clean stream close", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
sandbox.process.getSessionCommandLogs.mockResolvedValue(undefined);
sandbox.process.getSessionCommand.mockRejectedValue(new Error("session no longer exists"));
mockGet.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentExecute?.(streamExecParams()))
.rejects.toThrow("session no longer exists");
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
});
it("reads bytes written after socket close before the exit code becomes visible", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void) => {
if (onStdout) onStdout("prefix;");
else return { stdout: "prefix;tail;", stderr: "final error output" };
},
);
sandbox.process.getSessionCommand
.mockResolvedValueOnce({ exitCode: undefined })
.mockResolvedValue({ exitCode: 3 });
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams());
expect(result).toMatchObject({ exitCode: 3, stdout: "prefix;tail;", stderr: "final error output" });
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
});
it.each(["status", "snapshot", "final snapshot"])("bounds a stalled %s observation after clean close and ignores late callbacks", async (stall) => {
process.env.DAYTONA_API_KEY = "host-key";
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest(
{ execution: { log: executionLog } } as unknown as PluginContext,
);
vi.useFakeTimers();
try {
const sandbox = createStreamingSandbox();
let streams = 0;
let lateOutput: ((chunk: string) => void) | undefined;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void) => {
if (onStdout) {
streams += 1;
lateOutput = onStdout;
onStdout("partial;");
onStderr?.("partial error;");
return;
}
return new Promise(() => {});
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => {
if (stall === "status") return new Promise(() => {});
return { exitCode: stall === "final snapshot" ? 0 : undefined };
});
mockGet.mockResolvedValue(sandbox);
const promise = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 800 }));
let settled = false;
void promise?.then(() => { settled = true; });
await vi.advanceTimersByTimeAsync(799);
expect(settled).toBe(false);
await vi.advanceTimersByTimeAsync(701);
const result = await promise;
expect(result).toMatchObject({
exitCode: null,
timedOut: true,
stdout: "partial;",
metadata: {
timeoutScope: "session_log_observation",
commandExitConfirmed: stall === "final snapshot",
...(stall === "final snapshot" ? { observedExitCode: 0 } : {}),
},
});
expect(result!.stderr).toMatch(/^partial error;Session log observation timed out/);
const received = [...executionLog.mock.calls];
lateOutput?.("late output must be ignored");
expect(executionLog.mock.calls).toEqual(received);
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally {
vi.useRealTimers();
restore();
}
});
it.each(["status", "final snapshot", "fallback snapshot"])("preserves observation state when the SDK %s times out", async (stage) => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void) => {
if (!onStdout) throw new MockDaytonaTimeoutError("provider timeout");
onStdout("partial;");
onStderr?.("partial error;");
if (stage === "fallback snapshot") throw new Error("socket error");
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => {
if (stage === "status") throw new MockDaytonaTimeoutError("provider timeout");
return { exitCode: stage === "final snapshot" ? 0 : undefined };
});
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams());
expect(result).toMatchObject({
exitCode: null, timedOut: true, stdout: "partial;",
metadata: {
timeoutScope: "session_log_observation",
commandExitConfirmed: stage === "final snapshot",
...(stage === "final snapshot" ? { observedExitCode: 0 } : {}),
},
});
expect(result!.stderr).toMatch(/^partial error;Session log observation timed out/);
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
});
it.each(["observation", "legacy fallback", "SDK"])("retains pending replacement characters in a %s timeout result only", async (stage) => {
process.env.DAYTONA_API_KEY = "host-key";
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest(
{ execution: { log: executionLog } } as unknown as PluginContext,
);
vi.useFakeTimers();
try {
const sandbox = createStreamingSandbox();
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void) => {
onStdout?.("A\uFFFD");
onStderr?.("E\uFFFD\uFFFD");
if (stage === "legacy fallback") throw new Error("socket error");
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => {
if (stage === "SDK") throw new MockDaytonaTimeoutError("provider timeout");
return new Promise(() => {});
});
mockGet.mockResolvedValue(sandbox);
const promise = plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 400 }));
await vi.advanceTimersByTimeAsync(400);
const result = await promise;
expect(result).toMatchObject({ exitCode: null, timedOut: true, stdout: "A\uFFFD" });
expect(result!.stderr).toMatch(/^E\uFFFD\uFFFD/);
expect(executionLog.mock.calls).toEqual([["stdout", "A"], ["stderr", "E"]]);
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
expect(vi.getTimerCount()).toBe(0);
} finally {
vi.useRealTimers();
restore();
}
});
it.each([
{ text: "A🙂Z", snapshot: "A🙂Z" },
{ text: "A\uFFFD", snapshot: "" },
{ text: "A\uFFFD\uFFFD", snapshot: "A\uFFFD" },
{ text: "A\uFFFD\uFFFD", snapshot: "" },
])("preserves UTF-8 when the SDK decoder flushes on clean close: $text", async ({ text, snapshot }) => {
process.env.DAYTONA_API_KEY = "host-key";
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest(
{ execution: { log: executionLog } } as unknown as PluginContext,
);
try {
const sandbox = createStreamingSandbox();
let streams = 0;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (_sid: string, _cmdId: string, onStdout?: (chunk: string) => void, onStderr?: (chunk: string) => void) => {
if (!onStdout) return { stdout: snapshot, stderr: "E🙂Z" };
streams += 1;
// The pinned SDK streams bytes through TextDecoder and flushes
// it on clean socket close. Model that native decoder boundary
// without importing the optional provider package in root CI.
const emitClosedStream = (bytes: Buffer, emit: (chunk: string) => void) => {
const decoder = new TextDecoder();
const text = decoder.decode(bytes, { stream: true });
if (text) emit(text);
const tail = decoder.decode();
if (tail) emit(tail);
};
const stdout = Buffer.from(text);
const stderr = Buffer.from("E🙂Z");
emitClosedStream(streams === 1 && text.includes("🙂") ? stdout.subarray(0, 2) : stdout, onStdout);
emitClosedStream(streams === 1 ? stderr.subarray(0, 2) : stderr, onStderr!);
},
);
sandbox.process.getSessionCommand.mockImplementation(async () => ({ exitCode: streams === 1 ? undefined : 0 }));
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams({ timeoutMs: 2000 }));
expect(result).toMatchObject({ exitCode: 0, stdout: text, stderr: "E🙂Z" });
for (const [stream, expected] of [["stdout", text], ["stderr", "E🙂Z"]]) {
expect(executionLog.mock.calls.filter(([name]) => name === stream).map(([, chunk]) => chunk).join("")).toBe(expected);
}
expect(sandbox.process.executeSessionCommand).toHaveBeenCalledTimes(1);
} finally {
restore();
}
});
it("falls back to the poll path when the stream promise rejects (test_log_stream_disconnect_rejects_and_falls_back_to_poll)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
// The callback form disconnects and rejects. The snapshot form (no
// callbacks) serves the poll fallback read.
sandbox.process.getSessionCommandLogs.mockImplementation(
async (
_sid: string,
_cmdId: string,
onStdout?: (chunk: string) => void,
) => {
if (onStdout) {
onStdout("partial");
throw new Error("socket error");
}
return { stdout: "partialpoll-out", stderr: "poll-err" };
},
);
// The command still runs to its exit on the server, so the poll reads it.
sandbox.process.getSessionCommand.mockResolvedValue({ id: "cmd-1", command: "", exitCode: 9 });
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams());
// The poll fallback served the final result, and the command still
// yielded its exit code.
expect(result).toMatchObject({ exitCode: 9, timedOut: false, stdout: "partialpoll-out", stderr: "poll-err" });
// The snapshot form (two args) ran for the fallback read.
const snapshotCalls = sandbox.process.getSessionCommandLogs.mock.calls.filter(
(call) => call[2] === undefined,
);
expect(snapshotCalls.length).toBeGreaterThanOrEqual(1);
});
it("drops the replayed prefix by byte offset on a reconnect (test_log_stream_reconnect_drops_replayed_prefix_by_byte_offset)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createStreamingSandbox();
let attempt = 0;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (
_sid: string,
_cmdId: string,
onStdout?: (chunk: string) => void,
onStderr?: (chunk: string) => void,
) => {
attempt += 1;
if (attempt === 1) {
// First connection: deliver a prefix, then the socket drops.
onStdout?.("AAA");
onStderr?.("EEE");
throw new Error("socket error");
}
// Reconnect: Daytona replays the whole log from byte 0, then the new
// tail. The plugin must drop the replayed prefix.
onStdout?.("AAA");
onStdout?.("BBB");
onStderr?.("EEE");
onStderr?.("FFF");
},
);
sandbox.process.getSessionCommand.mockResolvedValue({ id: "cmd-1", command: "", exitCode: 0 });
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.(streamExecParams());
// The pre-disconnect bytes appear one time, not two.
expect(result).toMatchObject({ exitCode: 0, timedOut: false, stdout: "AAABBB", stderr: "EEEFFF" });
expect(sandbox.process.getSessionCommandLogs.mock.calls.filter((call) => call[2])).toHaveLength(2);
});
it("emits each new chunk to the host and drops a replayed prefix (test_log_stream_emits_execute_log_per_chunk)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const executionLog = vi.fn();
const restore = __setDaytonaPluginContextForTest(
{ execution: { log: executionLog } } as unknown as PluginContext,
);
try {
const sandbox = createStreamingSandbox();
let attempt = 0;
sandbox.process.getSessionCommandLogs.mockImplementation(
async (
_sid: string,
_cmdId: string,
onStdout?: (chunk: string) => void,
onStderr?: (chunk: string) => void,
) => {
attempt += 1;
if (attempt === 1) {
onStdout?.("AAA");
onStderr?.("EEE");
throw new Error("socket error");
}
// Reconnect replays the whole log from byte 0, then the new tail.
onStdout?.("AAA");
onStdout?.("BBB");
onStderr?.("EEE");
onStderr?.("FFF");
},
);
sandbox.process.getSessionCommand.mockResolvedValue({ id: "cmd-1", command: "", exitCode: 0 });
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(streamExecParams());
// Each genuinely new chunk reaches the host exactly once. The replayed
// prefix ("AAA"/"EEE") on the reconnect is not re-emitted.
expect(executionLog.mock.calls).toEqual([
["stdout", "AAA"],
["stderr", "EEE"],
["stdout", "BBB"],
["stderr", "FFF"],
]);
} finally {
restore();
}
});
});
});
it("executes commands one-shot and returns combined output via stdout", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.executeCommand.mockResolvedValue({
exitCode: 7,
result: "stdout\nstderr\n",
artifacts: { stdout: "stdout\nstderr\n" },
});
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: {
timeoutMs: 300000,
reuseLease: false,
},
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "printf",
args: ["hello"],
cwd: "/workspace",
env: { FOO: "bar" },
timeoutMs: 1000,
});
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(1);
const [command, cwdArg, envArg, timeoutArg] = sandbox.process.executeCommand.mock.calls[0] as [string, unknown, unknown, number];
expect(command).toMatch(/\/etc\/profile/);
expect(command).toMatch(/"\$HOME\/\.profile"/);
expect(command).not.toMatch(/nvm\.sh/);
expect(command).toMatch(/&& cd '\/workspace'/);
expect(command).toMatch(/&& env GIT_TERMINAL_PROMPT='0' GCM_INTERACTIVE='Never' GIT_ASKPASS='echo' SSH_ASKPASS='echo' SSH_ASKPASS_REQUIRE='force' FOO='bar' 'printf' 'hello'$/);
expect(command).not.toMatch(/(?:^|&& )exec /);
// cwd/env are baked into the command itself; we pass undefined to the SDK
// so its own cwd argument does not run before the caller env is applied.
expect(cwdArg).toBeUndefined();
expect(envArg).toBeUndefined();
expect(timeoutArg).toBe(1);
expect(result).toMatchObject({
exitCode: 7,
timedOut: false,
stdout: "stdout\nstderr\n",
stderr: "",
});
// Provider-boundary timings ride the free-form result metadata (Open Q1).
expect(typeof (result!.metadata as Record<string, unknown>)?.durationMs).toBe("number");
expect(typeof (result!.metadata as Record<string, unknown>)?.getDurationMs).toBe("number");
});
it("reports provider executeCommand and client.get durations via result metadata (injected clock)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.executeCommand.mockResolvedValue({
exitCode: 0,
result: "ok",
artifacts: { stdout: "ok" },
});
mockGet.mockResolvedValue(sandbox);
// Deterministic clock: getSandbox spans 40ms, executeCommand spans 600ms.
// Call order across the execute path is: getStart, getEnd, execStart, execEnd.
const ticks = [1000, 1040, 1040, 1640];
let i = 0;
const restoreClock = setDaytonaTimingClockForTest(() => ticks[Math.min(i++, ticks.length - 1)]!);
try {
const result = await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "printf",
args: ["hello"],
cwd: "/workspace",
timeoutMs: 1000,
});
expect(result!.metadata).toMatchObject({ durationMs: 600, getDurationMs: 40 });
} finally {
restoreClock();
}
});
it("sets metadata.cacheHit false on a client.get miss and true on a warm-handle hit", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.executeCommand.mockResolvedValue({
exitCode: 0,
result: "ok",
artifacts: { stdout: "ok" },
});
mockGet.mockResolvedValue(sandbox);
const execParams = {
driverKey: "daytona" as const,
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "printf",
args: ["hello"],
cwd: "/workspace",
timeoutMs: 1000,
};
// First execute: the handle cache is empty, so the lookup calls `client.get`
// and reports a miss.
const first = await plugin.definition.onEnvironmentExecute?.(execParams);
expect(first!.metadata).toMatchObject({ cacheHit: false });
expect(mockGet).toHaveBeenCalledTimes(1);
// Second execute: the warm handle cache serves the handle, so the lookup
// makes no `client.get` round trip and reports a hit.
const second = await plugin.definition.onEnvironmentExecute?.(execParams);
expect(second!.metadata).toMatchObject({ cacheHit: true });
expect(mockGet).toHaveBeenCalledTimes(1);
});
it("stages stdin in the sandbox filesystem when execution needs redirected input", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: {
timeoutMs: 300000,
reuseLease: false,
},
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "cat",
args: [],
cwd: "/workspace",
stdin: "input payload",
timeoutMs: 1000,
});
expect(sandbox.fs.uploadFile).toHaveBeenCalledWith(
Buffer.from("input payload", "utf8"),
expect.stringMatching(/^\/tmp\/paperclip-stdin-/),
1,
);
const [command] = sandbox.process.executeCommand.mock.calls[0] as [string];
expect(command).toMatch(/\/etc\/profile/);
expect(command).not.toMatch(/nvm\.sh/);
expect(command).toMatch(/&& cd '\/workspace'/);
expect(command).toMatch(/env .* 'cat' < '\/tmp\/paperclip-stdin-/);
expect(command).not.toMatch(/(?:^|&& )exec /);
expect(sandbox.fs.deleteFile).toHaveBeenCalledWith(expect.stringMatching(/^\/tmp\/paperclip-stdin-/));
expect(result).toMatchObject({
exitCode: 0,
timedOut: false,
});
});
it("runs the one-shot command plain with no bwrap or su wrapper", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: { remoteCwd: "/home/daytona/paperclip-workspace" } },
command: "printf",
args: ["hello"],
cwd: "/workspace",
timeoutMs: 1000,
});
const [command] = sandbox.process.executeCommand.mock.calls[0] as [string];
expect(command).not.toContain("sudo -n bwrap");
expect(command).not.toContain("su -s /bin/sh");
expect(command).toMatch(/'printf' 'hello'$/);
});
it("rejects invalid shell env keys before execution", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: {
timeoutMs: 300000,
reuseLease: false,
},
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "printf",
args: ["hello"],
env: { "BAD-KEY": "bar" },
})).rejects.toThrow("Invalid sandbox environment variable key: BAD-KEY");
expect(sandbox.process.executeCommand).not.toHaveBeenCalled();
});
it("returns a timed out execute result when the Daytona SDK times out", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.executeCommand.mockRejectedValue(new MockDaytonaTimeoutError("command timed out"));
mockGet.mockResolvedValue(sandbox);
// Injected clock: getStart=0, getEnd=10 (getDurationMs=10), execStart=20,
// execEnd/timeout=1520 (durationMs=1500). Deterministic so the timeout path's
// provider-exec attribution is asserted exactly.
const ticks = [0, 10, 20, 1520];
let i = 0;
const restoreClock = setDaytonaTimingClockForTest(() => ticks[Math.min(i++, ticks.length - 1)]!);
let result;
try {
result = await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: {
timeoutMs: 300000,
reuseLease: false,
},
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "sleep",
args: ["60"],
cwd: "/workspace",
timeoutMs: 1000,
});
} finally {
restoreClock();
}
expect(result).toMatchObject({
exitCode: null,
timedOut: true,
stdout: "",
stderr: "command timed out\n",
});
// The exec reached executeCommand before timing out, so its wall-time is
// preserved as durationMs (provider-exec attribution is not dropped on the
// timeout path); the getSandbox re-fetch duration is also reported.
expect(result!.metadata).toMatchObject({ durationMs: 1500, getDurationMs: 10 });
});
it("injects noninteractive git credential defaults for every one-shot command", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "git",
args: ["status"],
timeoutMs: 5000,
});
const [command] = sandbox.process.executeCommand.mock.calls[0] as [string];
expect(command).toContain("GIT_TERMINAL_PROMPT='0'");
expect(command).toContain("GCM_INTERACTIVE='Never'");
expect(command).toContain("GIT_ASKPASS='echo'");
expect(command).toContain("SSH_ASKPASS='echo'");
expect(command).toContain("SSH_ASKPASS_REQUIRE='force'");
});
it("caps git network commands at 120 s and returns an actionable message on timeout", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.executeCommand.mockRejectedValue(new MockDaytonaTimeoutError("timed out"));
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "git",
args: ["push", "origin", "HEAD"],
cwd: "/workspace",
timeoutMs: 300000,
});
const [, , , timeoutArg] = sandbox.process.executeCommand.mock.calls[0] as [string, unknown, unknown, number];
expect(timeoutArg).toBe(120);
expect(result).toMatchObject({ exitCode: null, timedOut: true });
expect(result?.stderr).toMatch(/unreachable|credentials/i);
});
// ─── Exec command shape ────────────────────────────────────────────────────
// The wrapper sources the login profiles so `node` resolves on the reference
// image, then runs the command. It no longer sources `nvm.sh`, while every
// other exec surface (env prefix, cwd, quoting, stdin, durationMs) stays
// intact.
it("test_exec_command_preserves_env_cwd_and_duration", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
sandbox.process.executeCommand.mockResolvedValue({
exitCode: 0,
result: "ok",
artifacts: { stdout: "ok" },
});
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "base64",
args: ["-d"],
cwd: "/workspace",
env: { FOO: "bar" },
timeoutMs: 1000,
});
const [command] = sandbox.process.executeCommand.mock.calls[0] as [string];
// The command sources the login profiles first, then runs the `cd` and the
// env prefix with the noninteractive git defaults.
expect(command).toMatch(/^if \[ -f \/etc\/profile \]/);
expect(command).toMatch(/&& cd '\/workspace' && env /);
expect(command).toMatch(/GIT_TERMINAL_PROMPT='0'/);
expect(command).toMatch(/FOO='bar' 'base64' '-d'$/);
expect(command).toMatch(/\/etc\/profile/);
expect(command).not.toMatch(/nvm\.sh/);
// durationMs attribution stays intact.
expect(typeof (result!.metadata as Record<string, unknown>)?.durationMs).toBe("number");
});
it("test_exec_command_sources_profile_without_nvm", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
// A node-launching exec resolves `node` through the login profiles, which
// Daytona's non-login `executeCommand` shell does not source on its own. The
// wrapper sources the profiles but no longer sources `nvm.sh`.
await plugin.definition.onEnvironmentExecute?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
bypassSession: true,
lease: { providerLeaseId: "sandbox-123", metadata: {} },
command: "node",
args: ["--version"],
cwd: "/workspace",
timeoutMs: 1000,
});
const [command] = sandbox.process.executeCommand.mock.calls[0] as [string];
expect(command).toMatch(/\/etc\/profile/);
expect(command).toMatch(/"\$HOME\/\.profile"/);
expect(command).not.toMatch(/nvm\.sh/);
expect(command).not.toMatch(/NVM_DIR/);
});
// ─── Per-lease started-sandbox handle cache ────────────────────────────────
// These prove the security conditions: single-fetch-per-lease, strict
// composite-key isolation (no cross-lease / cross-company / cross-env reuse),
// eviction at every teardown, no caching of failed populates, single-flight
// concurrency, and sentinel re-verification on a cached resume — plus that a
// handle left idle past the provider auto-stop window is refreshed before
// reuse so a provider-initiated stop is not hidden behind a stale snapshot.
describe("started-sandbox handle cache", () => {
function execParams(
providerLeaseId: string,
overrides: { companyId?: string; environmentId?: string; driverKey?: string } = {},
) {
return {
driverKey: overrides.driverKey ?? "daytona",
companyId: overrides.companyId ?? "company-1",
environmentId: overrides.environmentId ?? "env-1",
config: { timeoutMs: 300000, reuseLease: false },
bypassSession: true,
lease: { providerLeaseId, metadata: {} },
command: "printf",
args: ["hi"],
timeoutMs: 1000,
};
}
it("reuses the cached handle across execs on one lease (single client.get)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
// Second exec is served from the cache: no second REST re-fetch.
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(2);
});
it("keeps getDurationMs present (≈0) on a cache hit", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
const hit = await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
// The observability contract holds even when the fetch is elided.
expect(typeof (hit!.metadata as Record<string, unknown>)?.getDurationMs).toBe("number");
});
it("never serves lease A's handle to lease B (distinct fetch per lease)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandboxA = createMockSandbox({ id: "lease-a" });
const sandboxB = createMockSandbox({ id: "lease-b" });
mockGet.mockImplementation(async (id: string) => (id === "lease-a" ? sandboxA : sandboxB));
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await plugin.definition.onEnvironmentExecute?.(execParams("lease-b"));
expect(mockGet).toHaveBeenCalledTimes(2);
expect(sandboxA.process.executeCommand).toHaveBeenCalledTimes(1);
expect(sandboxB.process.executeCommand).toHaveBeenCalledTimes(1);
});
it("does not share a handle across companies or environments for the same providerLeaseId", async () => {
process.env.DAYTONA_API_KEY = "host-key";
mockGet.mockImplementation(async () => createMockSandbox({ id: "sandbox-x" }));
await plugin.definition.onEnvironmentExecute?.(execParams("sandbox-x", { companyId: "company-1", environmentId: "env-1" }));
await plugin.definition.onEnvironmentExecute?.(execParams("sandbox-x", { companyId: "company-2", environmentId: "env-1" }));
await plugin.definition.onEnvironmentExecute?.(execParams("sandbox-x", { companyId: "company-1", environmentId: "env-2" }));
// Three distinct composite keys → three independent fetches; the bare
// providerLeaseId is never a shared cache slot.
expect(mockGet).toHaveBeenCalledTimes(3);
});
it("keeps account credentials and API endpoints isolated for the same sandbox ID", async () => {
mockGet.mockImplementation(async () => createMockSandbox({ id: "sandbox-account" }));
const params = execParams("sandbox-account");
for (const config of [
{ apiKey: "account-a", apiUrl: "https://one.daytona.test/api" },
{ apiKey: "account-b", apiUrl: "https://one.daytona.test/api" },
{ apiKey: "account-a", apiUrl: "https://two.daytona.test/api" },
]) {
await plugin.definition.onEnvironmentExecute!({
...params, config: { ...params.config, ...config },
});
}
expect(mockGet).toHaveBeenCalledTimes(3);
});
it("rejects a queued execute after release teardown closes the lease", async () => {
process.env.DAYTONA_API_KEY = "host-key";
mockGet.mockImplementation(async () => createMockSandbox({ id: "lease-a" }));
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a")); // miss → get #1 (cached)
const releasePromise = plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: false },
});
await new Promise((resolve) => setTimeout(resolve, 0));
const queuedExecute = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await expect(queuedExecute).rejects.toThrow(/no longer active/);
await releasePromise;
// The tombstone closes the lease, so the queued execute never reacquires
// the sandbox after teardown.
expect(mockGet).toHaveBeenCalledTimes(1);
});
it("rejects an overlapping execute after release teardown closes the lease", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let stopStarted = false;
let resolveRelease!: () => void;
const releaseGate = new Promise<void>((resolve) => {
resolveRelease = resolve;
});
sandbox.stop.mockImplementation(() => {
stopStarted = true;
return releaseGate;
});
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
const releasePromise = plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: true },
});
await new Promise((resolve) => setTimeout(resolve, 0));
expect(stopStarted).toBe(true);
const overlappingExec = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await expect(overlappingExec).rejects.toThrow(/no longer active/);
resolveRelease();
await releasePromise;
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.stop).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(1);
});
it("cancels active work before waiting for a stalled execute to drain", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let release!: () => void;
sandbox.process.executeCommand.mockImplementation(async () => {
await new Promise<void>(resolve => { release = resolve; });
return { exitCode: 0, result: "", artifacts: { stdout: "" } };
});
mockGet.mockResolvedValue(sandbox);
const execute = plugin.definition.onEnvironmentExecute!(execParams("lease-a"));
await vi.waitFor(() => expect(release).toBeTypeOf("function"));
const cancellation = plugin.definition.onEnvironmentReleaseLease!({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: "lease-a", config: { timeoutMs: 300000, reuseLease: true },
cancelActiveWork: true,
});
try {
await vi.waitFor(() => expect(sandbox.stop).toHaveBeenCalledTimes(1), { timeout: 500 });
await expect(cancellation).resolves.toEqual({ providerLeaseId: "lease-a", state: "stopped" });
expect(await plugin.definition.onIdleDrain!(new AbortController().signal)).toBe("present");
await expect(plugin.definition.onEnvironmentExecute!(execParams("lease-a"))).rejects.toThrow(/no longer active/);
await expect(plugin.definition.onEnvironmentResumeLease!({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: "lease-a", config: { timeoutMs: 300000, reuseLease: true },
})).rejects.toThrow(/still settling cancelled work/);
expect(sandbox.start).not.toHaveBeenCalled();
} finally {
release();
await execute;
await cancellation;
}
// Completion of the old command is not a second stop receipt. Re-read
// the exact resource after it settles before clearing worker evidence.
expect(await plugin.definition.onIdleDrain!(new AbortController().signal)).toBe("present");
sandbox.state = "stopped";
await plugin.definition.onEnvironmentInspectLease!({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: "lease-a", config: { apiKey: "host-key" },
});
expect(await plugin.definition.onIdleDrain!(new AbortController().signal)).toBe("none");
});
it("does not report termination when the provider rejects Stop", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
sandbox.stop.mockRejectedValue(new Error("provider unavailable"));
mockGet.mockResolvedValue(sandbox);
await expect(plugin.definition.onEnvironmentReleaseLease!({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: "lease-a", config: { timeoutMs: 300000, reuseLease: true },
cancelActiveWork: true,
})).rejects.toThrow("provider unavailable");
expect(sandbox.delete).not.toHaveBeenCalled();
await expect(plugin.definition.onEnvironmentExecute!(execParams("lease-a"))).rejects.toThrow(/no longer active/);
});
it.each(["release", "destroy"])("%s terminates through the provider when bridge activity never settles", async (kind) => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let finish!: () => void;
sandbox.process.executeCommand.mockImplementation(async () => {
await new Promise<void>(resolve => { finish = resolve; });
return { exitCode: 0, result: "bash", artifacts: { stdout: "bash" } };
});
mockGet.mockResolvedValue(sandbox);
const execute = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await vi.waitFor(() => expect(finish).toBeTypeOf("function"));
const params = { driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
providerLeaseId: "lease-a", config: { timeoutMs: 300000, livenessTimeoutMs: 5, reuseLease: true } };
try {
const receipt = kind === "release"
? await plugin.definition.onEnvironmentReleaseLease?.(params)
: await plugin.definition.onEnvironmentDestroyLease?.(params);
expect(receipt).toEqual({ providerLeaseId: "lease-a", state: kind === "release" ? "stopped" : "destroyed" });
expect(kind === "release" ? sandbox.stop : sandbox.delete).toHaveBeenCalledTimes(1);
await expect(plugin.definition.onEnvironmentExecute?.(execParams("lease-a"))).rejects.toThrow(/no longer active/);
} finally { finish(); await execute; }
});
it("waits for an in-flight execute before teardown cleanup starts", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let resolveExecute!: () => void;
sandbox.process.executeCommand.mockImplementation(async () => {
await new Promise<void>((resolve) => {
resolveExecute = resolve;
});
return {
exitCode: 0,
result: "bash",
artifacts: { stdout: "bash" },
};
});
mockGet.mockResolvedValue(sandbox);
const executePromise = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await new Promise((resolve) => setTimeout(resolve, 0));
const releasePromise = plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: true },
});
await new Promise((resolve) => setTimeout(resolve, 0));
expect(sandbox.stop).not.toHaveBeenCalled();
resolveExecute();
await Promise.all([executePromise, releasePromise]);
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(1);
expect(sandbox.stop).toHaveBeenCalledTimes(1);
});
it("keeps the teardown gate closed until overlapping teardowns both finish", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let stopStarted = false;
let deleteStarted = false;
let resolveStop!: () => void;
let resolveDelete!: () => void;
const stopGate = new Promise<void>((resolve) => {
resolveStop = resolve;
});
const deleteGate = new Promise<void>((resolve) => {
resolveDelete = resolve;
});
sandbox.stop.mockImplementation(() => {
stopStarted = true;
return stopGate;
});
sandbox.delete.mockImplementation(() => {
deleteStarted = true;
return deleteGate;
});
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
const releasePromise = plugin.definition.onEnvironmentReleaseLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: true },
});
await new Promise((resolve) => setTimeout(resolve, 0));
expect(stopStarted).toBe(true);
const destroyPromise = plugin.definition.onEnvironmentDestroyLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: true },
});
await new Promise((resolve) => setTimeout(resolve, 0));
expect(deleteStarted).toBe(true);
resolveDelete();
await destroyPromise;
const overlappingExec = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await expect(overlappingExec).rejects.toThrow(/no longer active/);
resolveStop();
await releasePromise;
expect(mockGet).toHaveBeenCalledTimes(2);
expect(sandbox.stop).toHaveBeenCalledTimes(1);
expect(sandbox.delete).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(1);
});
it("rejects a queued execute after destroy teardown closes the lease", async () => {
process.env.DAYTONA_API_KEY = "host-key";
mockGet.mockImplementation(async () => createMockSandbox({ id: "lease-a" }));
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
const destroyPromise = plugin.definition.onEnvironmentDestroyLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: false },
});
await new Promise((resolve) => setTimeout(resolve, 0));
const queuedExecute = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await expect(queuedExecute).rejects.toThrow(/no longer active/);
await destroyPromise;
expect(mockGet).toHaveBeenCalledTimes(1);
});
it("rejects a queued execute after interactive cancel closes the lease", async () => {
process.env.DAYTONA_API_KEY = "host-key";
mockGet.mockImplementation(async () => createMockSandbox({ id: "lease-a" }));
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
const cancelPromise = plugin.definition.onEnvironmentCancelInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: false },
reason: "cancelled",
});
await new Promise((resolve) => setTimeout(resolve, 0));
const queuedExecute = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await expect(queuedExecute).rejects.toThrow(/no longer active/);
await cancelPromise;
expect(mockGet).toHaveBeenCalledTimes(1);
});
it("waits for an in-flight execute before interactive cancel cleanup starts", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let resolveExecute!: () => void;
sandbox.process.executeCommand.mockImplementation(async () => {
await new Promise<void>((resolve) => {
resolveExecute = resolve;
});
return {
exitCode: 0,
result: "bash",
artifacts: { stdout: "bash" },
};
});
mockGet.mockResolvedValue(sandbox);
const executePromise = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await new Promise((resolve) => setTimeout(resolve, 0));
const cancelPromise = plugin.definition.onEnvironmentCancelInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: false },
reason: "cancelled",
});
await new Promise((resolve) => setTimeout(resolve, 0));
expect(sandbox.delete).not.toHaveBeenCalled();
resolveExecute();
await Promise.all([executePromise, cancelPromise]);
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(1);
expect(sandbox.delete).toHaveBeenCalledTimes(1);
});
it("waits for an in-flight syncIn before interactive cancel cleanup starts", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const hostDir = await fs.mkdtemp(path.join(os.tmpdir(), "daytona-cancel-sync-"));
const source = path.join(hostDir, "payload.txt");
await fs.writeFile(source, "payload");
const remoteDir = "/home/daytona/paperclip-workspace";
const sandbox = createMockSandbox({ id: "lease-a" });
let resolveUpload!: () => void;
sandbox.fs.uploadFiles.mockImplementation(async () => {
await new Promise<void>((resolve) => {
resolveUpload = resolve;
});
});
mockGet.mockResolvedValue(sandbox);
const syncPromise = plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: { providerLeaseId: "lease-a", metadata: { remoteCwd: remoteDir } },
operations: [
{
operationId: "sync-op-1",
files: [{ sourcePath: source, targetPath: `${remoteDir}/payload.txt`, kind: "file" }],
},
],
});
// Let syncIn register on the activity gate and reach the hung upload.
// The real `fs.stat` and `mkdir` round trip run before the upload call,
// so a fixed tick count can race ahead of them on a slower or busier
// host. Poll for the actual upload call instead of guessing a tick
// count, so this assertion never fires before syncIn reaches the hang.
await vi.waitFor(() => {
expect(sandbox.fs.uploadFiles).toHaveBeenCalled();
});
const cancelPromise = plugin.definition.onEnvironmentCancelInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: false },
reason: "cancelled",
});
await new Promise((resolve) => setTimeout(resolve, 0));
// Cancel must drain the active sync before deleting the sandbox out from
// under it — the same activity-gate contract the execute path relies on.
expect(sandbox.delete).not.toHaveBeenCalled();
resolveUpload();
await Promise.all([syncPromise, cancelPromise]);
expect(sandbox.fs.uploadFiles).toHaveBeenCalledTimes(1);
expect(sandbox.delete).toHaveBeenCalledTimes(1);
await fs.rm(hostDir, { recursive: true, force: true });
});
it("rejects a queued execute once interactive cancel tombstones the lease", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let resolveFirstExecute!: () => void;
let cancelResolved = false;
let queuedExecuteRejected = false;
sandbox.process.executeCommand.mockImplementation(async () => {
await new Promise<void>((resolve) => {
resolveFirstExecute = resolve;
});
return {
exitCode: 0,
result: "bash",
artifacts: { stdout: "bash" },
};
});
mockGet.mockResolvedValue(sandbox);
const firstExecutePromise = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
await new Promise((resolve) => setTimeout(resolve, 0));
const cancelPromise = plugin.definition.onEnvironmentCancelInteractiveSetup?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: false },
reason: "cancelled",
});
await new Promise((resolve) => setTimeout(resolve, 0));
const queuedExecutePromise = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
queuedExecutePromise?.catch(() => {
queuedExecuteRejected = true;
});
await new Promise((resolve) => setTimeout(resolve, 0));
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.delete).not.toHaveBeenCalled();
resolveFirstExecute();
await cancelPromise!.then(() => {
cancelResolved = true;
});
await expect(queuedExecutePromise).rejects.toThrow(/no longer active/);
await firstExecutePromise;
expect(cancelResolved).toBe(true);
expect(queuedExecuteRejected).toBe(true);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(1);
expect(sandbox.delete).toHaveBeenCalledTimes(1);
});
it("waits for an in-flight snapshot capture before destroy cleanup starts", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let resolveSnapshot!: () => void;
sandbox._experimental_createSnapshot.mockImplementation(async () => {
await new Promise<void>((resolve) => {
resolveSnapshot = resolve;
});
});
mockGet.mockResolvedValue(sandbox);
const capturePromise = plugin.definition.onEnvironmentCaptureTemplate?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: false },
templateLabel: "snapshot-check",
});
await new Promise((resolve) => setTimeout(resolve, 0));
const destroyPromise = plugin.definition.onEnvironmentDestroyLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: false },
});
await new Promise((resolve) => setTimeout(resolve, 0));
expect(sandbox.delete).not.toHaveBeenCalled();
resolveSnapshot();
await Promise.all([capturePromise, destroyPromise]);
expect(sandbox._experimental_createSnapshot).toHaveBeenCalledTimes(1);
expect(sandbox.delete).toHaveBeenCalledTimes(1);
});
it("does not cache a failed populate (NotFound) — the next lookup re-fetches", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
mockGet
.mockRejectedValueOnce(new MockDaytonaNotFoundError("missing"))
.mockResolvedValue(sandbox);
const first = await plugin.definition.onEnvironmentResumeLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: true },
});
expect(first).toEqual({ providerLeaseId: null, metadata: { expired: true } });
// The rejected populate must not linger; the exec re-fetches successfully.
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
expect(mockGet).toHaveBeenCalledTimes(2);
});
it("single-flights concurrent misses on one lease into a single client.get", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
let resolveGet: ((value: unknown) => void) | undefined;
mockGet.mockImplementation(
() => new Promise((resolve) => { resolveGet = resolve; }),
);
const p1 = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
const p2 = plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
// Let both execs reach the shared in-flight populate before it resolves.
await Promise.resolve();
resolveGet?.(sandbox);
await Promise.all([p1, p2]);
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(2);
});
it("keeps concurrent different-lease populates isolated (no promise crossing)", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandboxA = createMockSandbox({ id: "lease-a" });
const sandboxB = createMockSandbox({ id: "lease-b" });
mockGet.mockImplementation(async (id: string) => (id === "lease-a" ? sandboxA : sandboxB));
await Promise.all([
plugin.definition.onEnvironmentExecute?.(execParams("lease-a")),
plugin.definition.onEnvironmentExecute?.(execParams("lease-b")),
]);
expect(mockGet).toHaveBeenCalledTimes(2);
expect(mockGet).toHaveBeenCalledWith("lease-a");
expect(mockGet).toHaveBeenCalledWith("lease-b");
// Each lease executed in its OWN sandbox, never the other's handle.
expect(sandboxA.process.executeCommand).toHaveBeenCalledTimes(1);
expect(sandboxB.process.executeCommand).toHaveBeenCalledTimes(1);
});
it("re-verifies the workspace sentinel on a cached resume and evicts on mismatch", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a", state: "started" });
// Every executeCommand (exec body + sentinel `cat`) returns a NON-matching token.
sandbox.process.executeCommand.mockResolvedValue({
exitCode: 0,
result: JSON.stringify({ token: "other-token" }),
artifacts: { stdout: JSON.stringify({ token: "other-token" }) },
});
mockGet.mockImplementation(async () => sandbox);
// Prime the cache with a successful exec on this lease.
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
expect(mockGet).toHaveBeenCalledTimes(1);
const sentinelCallsBefore = sandbox.process.executeCommand.mock.calls.length;
// Resume hits the cache but MUST still verify the sentinel; mismatch expires.
const resumed = await plugin.definition.onEnvironmentResumeLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "lease-a",
config: { timeoutMs: 300000, reuseLease: true },
leaseMetadata: {
workspaceSentinel: {
path: "/home/daytona/paperclip-workspace/.paperclip-runtime/reusable-sandbox-lease.json",
token: "expected-token",
result: "written",
},
},
});
expect(resumed).toMatchObject({
providerLeaseId: null,
metadata: { expired: true, workspaceSentinel: { result: "mismatch" } },
});
// The sentinel `cat` ran on the cached handle — verification was not skipped.
expect(sandbox.process.executeCommand.mock.calls.length).toBeGreaterThan(sentinelCallsBefore);
// The mismatched entry was evicted, so the next exec re-fetches.
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
expect(mockGet).toHaveBeenCalledTimes(2);
});
it("refreshes a handle left idle past the auto-stop window and restarts a provider-stopped sandbox", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a", state: "started" });
// Daytona auto-stopped the sandbox while our cached handle sat idle: a live
// refresh reveals the true "stopped" state that the cached snapshot hid.
sandbox.refreshData.mockImplementation(async () => {
sandbox.state = "stopped";
});
mockGet.mockResolvedValue(sandbox);
let nowMs = 1_000_000;
const restoreFreshness = setDaytonaHandleFreshnessClockForTest(() => nowMs);
try {
// Prime the cache (single fetch, snapshot "started").
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
expect(sandbox.refreshData).not.toHaveBeenCalled();
expect(sandbox.start).not.toHaveBeenCalled();
// Idle past half of the default 15-min auto-stop interval (> 7.5 min).
nowMs += 8 * 60_000;
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
} finally {
restoreFreshness();
}
// The stale handle was refreshed in place (no second REST fetch — the same
// authenticated handle), the refresh exposed the stopped state, and the
// sandbox was restarted before the exec instead of running against a
// stopped sandbox.
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.refreshData).toHaveBeenCalledTimes(1);
expect(sandbox.start).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(2);
});
it("does not refresh a handle reused within the auto-stop window", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
mockGet.mockResolvedValue(sandbox);
let nowMs = 5_000_000;
const restoreFreshness = setDaytonaHandleFreshnessClockForTest(() => nowMs);
try {
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
// Two more execs, each 6 min after the previous — always inside the
// 7.5-min window measured from the last reuse.
nowMs += 6 * 60_000;
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
nowMs += 6 * 60_000;
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
} finally {
restoreFreshness();
}
// Each reuse resets the freshness marker (an operation follows, resetting
// the provider idle clock), so an actively-used lease never pays a refresh.
expect(sandbox.refreshData).not.toHaveBeenCalled();
expect(mockGet).toHaveBeenCalledTimes(1);
});
it("does not advance freshness when an execute fails before succeeding", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
sandbox.process.executeCommand
.mockRejectedValueOnce(new Error("command failed"))
.mockResolvedValue({
exitCode: 0,
result: "bash",
artifacts: { stdout: "bash" },
});
mockGet.mockResolvedValue(sandbox);
let nowMs = 7_000_000;
const restoreFreshness = setDaytonaHandleFreshnessClockForTest(() => nowMs);
try {
await expect(plugin.definition.onEnvironmentExecute?.(execParams("lease-a"))).rejects.toThrow(
"command failed",
);
nowMs += 8 * 60_000;
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
} finally {
restoreFreshness();
}
expect(sandbox.refreshData).toHaveBeenCalledTimes(1);
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(2);
});
it("does not advance freshness when an execute times out before succeeding", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
sandbox.process.executeCommand
.mockRejectedValueOnce(new MockDaytonaTimeoutError("timed out"))
.mockResolvedValue({
exitCode: 0,
result: "bash",
artifacts: { stdout: "bash" },
});
mockGet.mockResolvedValue(sandbox);
let nowMs = 8_000_000;
const restoreFreshness = setDaytonaHandleFreshnessClockForTest(() => nowMs);
try {
const first = await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
expect(first).toMatchObject({ timedOut: true, exitCode: null });
nowMs += 8 * 60_000;
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
} finally {
restoreFreshness();
}
expect(sandbox.refreshData).toHaveBeenCalledTimes(1);
expect(mockGet).toHaveBeenCalledTimes(1);
expect(sandbox.process.executeCommand).toHaveBeenCalledTimes(2);
});
it("never refreshes when auto-stop is disabled, even after a long idle gap", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a" });
mockGet.mockResolvedValue(sandbox);
const disabledAutoStop = { timeoutMs: 300000, reuseLease: false, autoStopInterval: 0 };
let nowMs = 2_000_000;
const restoreFreshness = setDaytonaHandleFreshnessClockForTest(() => nowMs);
try {
await plugin.definition.onEnvironmentExecute?.({ ...execParams("lease-a"), config: disabledAutoStop });
nowMs += 60 * 60_000; // an hour idle
await plugin.definition.onEnvironmentExecute?.({ ...execParams("lease-a"), config: disabledAutoStop });
} finally {
restoreFreshness();
}
// Auto-stop off → the provider never stops the sandbox out from under the
// handle, so the cached started snapshot is trusted without a refresh.
expect(sandbox.refreshData).not.toHaveBeenCalled();
expect(mockGet).toHaveBeenCalledTimes(1);
});
it("evicts the handle when a freshness refresh fails so the next lookup re-fetches", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const first = createMockSandbox({ id: "lease-a" });
first.refreshData.mockRejectedValue(new MockDaytonaNotFoundError("sandbox vanished"));
const second = createMockSandbox({ id: "lease-a" });
mockGet.mockResolvedValueOnce(first).mockResolvedValue(second);
let nowMs = 3_000_000;
const restoreFreshness = setDaytonaHandleFreshnessClockForTest(() => nowMs);
try {
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a")); // fetch #1 → first
nowMs += 8 * 60_000; // idle past the refresh window
// The refresh rejects; execute surfaces it (fail closed) and the bad
// entry is evicted.
await expect(
plugin.definition.onEnvironmentExecute?.(execParams("lease-a")),
).rejects.toThrow("sandbox vanished");
// Evicted → the following exec re-fetches a fresh handle.
await plugin.definition.onEnvironmentExecute?.(execParams("lease-a"));
} finally {
restoreFreshness();
}
expect(mockGet).toHaveBeenCalledTimes(2);
expect(second.process.executeCommand).toHaveBeenCalledTimes(1);
});
it("surfaces a bounded timeout when the freshness refresh never responds", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "lease-a", state: "started" });
// The sandbox connection went silent: `refreshData` never resolves and
// never rejects. Without a per-call bound the exec would stall until the
// outer RPC ceiling fires.
sandbox.refreshData.mockImplementation(() => new Promise<void>(() => {}));
mockGet.mockResolvedValue(sandbox);
// A short liveness bound keeps the test fast and proves the config path.
const config = { timeoutMs: 300000, reuseLease: false, livenessTimeoutMs: 50 };
let nowMs = 4_000_000;
const restoreFreshness = setDaytonaHandleFreshnessClockForTest(() => nowMs);
try {
// Prime the cache (single fetch, snapshot "started").
await plugin.definition.onEnvironmentExecute?.({ ...execParams("lease-a"), config });
// Idle past half of the default 15-min auto-stop interval so the next
// lookup refreshes the stale handle.
nowMs += 8 * 60_000;
await expect(
plugin.definition.onEnvironmentExecute?.({ ...execParams("lease-a"), config }),
).rejects.toThrow(/did not respond within 50 ms/);
} finally {
restoreFreshness();
}
expect(sandbox.refreshData).toHaveBeenCalledTimes(1);
// The failed refresh evicted the handle, so the next lookup re-fetches.
await plugin.definition.onEnvironmentExecute?.({ ...execParams("lease-a"), config });
expect(mockGet).toHaveBeenCalledTimes(2);
});
it.each(["workspace", "projectless task"])("realizes a resumed %s lease after the provider fills in an unspecified target", async (scope) => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-default-target" });
mockCreate.mockResolvedValue(sandbox);
mockGet.mockResolvedValue(sandbox);
const base = { driverKey: "daytona", companyId: "company-1", environmentId: "env-1" };
const config = { image: "node:20", timeoutMs: 300000, reuseLease: true };
const lease = await plugin.definition.onEnvironmentAcquireLease!({
...base, runId: "run-1", agentId: "agent-1", config,
...(scope === "workspace" ? { executionWorkspaceId: "workspace-1" } : { issueId: "task-1" }),
});
// The host materializes provider metadata into later operation config,
// but resumes with the environment's original, target-less config.
const realizedConfig = { ...config, ...lease.metadata };
expect(realizedConfig).toMatchObject({ target: "us" });
await plugin.definition.onEnvironmentRealizeWorkspace!({
...base, config: realizedConfig, lease,
workspace: { remotePath: "/home/daytona/paperclip-workspace" },
});
expect(mockGet).not.toHaveBeenCalled();
await plugin.definition.onEnvironmentReleaseLease!({
...base, config: realizedConfig, providerLeaseId: lease.providerLeaseId!,
});
await expect(plugin.definition.onEnvironmentRealizeWorkspace!({
...base, config, lease,
workspace: { remotePath: "/home/daytona/paperclip-workspace" },
})).rejects.toThrow(/no longer active/);
await expect(plugin.definition.onEnvironmentRealizeWorkspace!({
...base, config: realizedConfig, lease,
workspace: { remotePath: "/home/daytona/paperclip-workspace" },
})).rejects.toThrow(/no longer active/);
sandbox.state = "stopped";
const sentinel = lease.metadata!.workspaceSentinel as { token: string };
expect(sentinel.token).toMatch(/^[a-f0-9]{64}$/);
sandbox.process.executeCommand.mockResolvedValueOnce({
exitCode: 0, result: JSON.stringify({ token: sentinel.token }),
artifacts: { stdout: JSON.stringify({ token: sentinel.token }) },
});
const resumed = await plugin.definition.onEnvironmentResumeLease!({
...base, config, providerLeaseId: lease.providerLeaseId!, leaseMetadata: lease.metadata,
});
expect(resumed.metadata).toMatchObject({
resumedLease: true, workspaceSentinel: { result: "matched" },
});
await expect(plugin.definition.onEnvironmentRealizeWorkspace!({
...base, config: { ...config, ...resumed.metadata }, lease: resumed,
workspace: { remotePath: "/home/daytona/paperclip-workspace" },
})).resolves.toMatchObject({ cwd: "/home/daytona/paperclip-workspace" });
});
it("realizes the workspace from the acquire-seeded handle without a client.get", async () => {
process.env.DAYTONA_API_KEY = "host-key";
const sandbox = createMockSandbox({ id: "sandbox-seed" });
mockCreate.mockResolvedValue(sandbox);
const base = { driverKey: "daytona", companyId: "company-1", environmentId: "env-1" };
const config = { image: "node:20", timeoutMs: 300000, reuseLease: false };
const lease = await plugin.definition.onEnvironmentAcquireLease?.({
...base,
runId: "run-1",
config,
});
expect(lease?.providerLeaseId).toBe("sandbox-seed");
const realize = await plugin.definition.onEnvironmentRealizeWorkspace?.({
...base,
lease: { providerLeaseId: lease!.providerLeaseId, metadata: lease!.metadata },
workspace: { remotePath: "/home/daytona/paperclip-workspace" },
config,
});
// Acquire seeded the handle under the exact scope realize reads, so realize
// reuses it and never pays a real REST re-fetch.
expect(mockGet).not.toHaveBeenCalled();
expect(sandbox.fs.createFolder).toHaveBeenCalledWith("/home/daytona/paperclip-workspace", "755");
expect(realize?.cwd).toBe("/home/daytona/paperclip-workspace");
});
});
});
describe("daytona native file-sync hooks", () => {
const REMOTE_DIR = "/home/daytona/paperclip-workspace";
const tempDirs: string[] = [];
async function makeHostDir(): Promise<string> {
const dir = await fs.mkdtemp(path.join(os.tmpdir(), "daytona-sync-test-"));
tempDirs.push(dir);
return dir;
}
function syncLease(overrides: Record<string, unknown> = {}) {
return {
providerLeaseId: "sandbox-123",
metadata: { provider: "daytona", remoteCwd: REMOTE_DIR, ...overrides },
};
}
// A concurrency gate for a fake transfer call (uploadFiles / downloadFiles).
// The gate lets two concurrent hook calls both enter the fake, then holds them
// there until the test releases them. It records the peak number of calls that
// are in the fake at the same time, so a test proves the two calls overlap.
//
// `expected` is how many calls the test starts. `bothArrived` resolves once
// that many calls sit inside the fake at the same moment. `release()` frees
// them. `body` is the fake implementation: it marks arrival, waits for the
// release, and then runs `onRelease` to produce the fake result.
function createTransferGate<T>(expected: number, onRelease: (args: unknown[]) => Promise<T>) {
let inFlight = 0;
let peakInFlight = 0;
let signalArrived!: () => void;
const bothArrived = new Promise<void>((resolve) => {
signalArrived = resolve;
});
let signalReleased!: () => void;
const released = new Promise<void>((resolve) => {
signalReleased = resolve;
});
const body = async (...args: unknown[]): Promise<T> => {
inFlight += 1;
peakInFlight = Math.max(peakInFlight, inFlight);
if (inFlight === expected) signalArrived();
await released;
inFlight -= 1;
return onRelease(args);
};
return {
body,
bothArrived,
release: () => signalReleased(),
peak: () => peakInFlight,
};
}
// Write each download request's snapshot bytes to its host destination and
// report success, matching the real batch-download contract the outbound sync
// path expects.
async function fulfilDownload(args: unknown[]): Promise<Array<{ source: string; result: string }>> {
const requests = args[0] as Array<{ source: string; destination: string }>;
return Promise.all(
requests.map(async (request) => {
await fs.writeFile(request.destination, "bytes");
return { source: request.source, result: request.destination };
}),
);
}
function syncInParams(overrides: {
operationId: string;
sourcePath: string;
targetPath: string;
}) {
return {
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: overrides.operationId,
files: [{ sourcePath: overrides.sourcePath, targetPath: overrides.targetPath, kind: "file" as const }],
},
],
};
}
function syncOutParams(overrides: {
operationId: string;
sourcePath: string;
targetPath: string;
}) {
return {
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: overrides.operationId,
files: [{ sourcePath: overrides.sourcePath, targetPath: overrides.targetPath, kind: "file" as const }],
},
],
};
}
beforeEach(() => {
mockGet.mockReset();
process.env.DAYTONA_API_KEY = "host-key";
__resetDaytonaSandboxHandleCacheForTest();
});
afterEach(async () => {
await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
});
it("declares both sync hooks so the worker advertises the native transport", () => {
expect(plugin.definition.onEnvironmentSyncIn).toBeTypeOf("function");
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");
const plainSource = path.join(hostDir, "config.txt");
await fs.writeFile(secretSource, "credential-material");
await fs.writeFile(plainSource, "plain");
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const result = await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-1",
files: [
{ sourcePath: secretSource, targetPath: `${REMOTE_DIR}/.secret/auth.json`, kind: "file", mode: 0o600 },
{ sourcePath: plainSource, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" },
],
},
],
});
// Exactly one bulk upload for both file mappings.
expect(sandbox.fs.uploadFiles).toHaveBeenCalledTimes(1);
const [uploads] = sandbox.fs.uploadFiles.mock.calls[0] as [Array<{ source: string; destination: string }>];
expect(uploads).toHaveLength(2);
// String sources stream from the local path; destinations are reserved temps.
expect(uploads[0].source).toBe(secretSource);
for (const upload of uploads) {
expect(path.posix.basename(upload.destination)).toMatch(/^\.paperclip-upload-/);
expect(upload.destination).not.toBe(`${REMOTE_DIR}/.secret/auth.json`);
// TOCTOU-hardened: the privileged upload destination is a DIRECT child of the
// workspace root, never a sibling under the target's (sandbox-swappable)
// parent dir, so a parent symlink swap cannot redirect the write out of root.
expect(path.posix.dirname(upload.destination)).toBe(REMOTE_DIR);
}
// Secret mode applied on the TEMP path (before the rename) so the target
// never appears at a widened window; applied via setFilePermissions as "600".
expect(sandbox.fs.setFilePermissions).toHaveBeenCalledTimes(1);
const [permPath, perms] = sandbox.fs.setFilePermissions.mock.calls[0] as [string, { mode: string }];
expect(path.posix.basename(permPath)).toMatch(/^\.paperclip-upload-/);
expect(perms).toEqual({ mode: "600" });
// The setFilePermissions on the temp precedes the mv that promotes it.
const secretTemp = permPath;
const mvCall = sandbox.process.executeCommand.mock.calls.find(([cmd]) => String(cmd).includes("mv -f"));
expect(mvCall).toBeDefined();
const mvCommand = String(mvCall?.[0]);
// Each promotion is one plain `mv -f <scratch> <target>` command, batched
// together in a single sandbox invocation.
expect(mvCommand).toContain(secretTemp);
expect(mvCommand).toContain(`${REMOTE_DIR}/.secret/auth.json`);
// Both temps are promoted (one mv line per rename).
expect(mvCommand.match(/mv -f /g)).toHaveLength(2);
expect(result).toEqual({
operations: [{ operationId: "sync-op-1", filesTransferred: 2, bytesTransferred: "credential-material".length + "plain".length }],
});
});
// A recording tracer that captures every provider span the file sync opens.
// It satisfies the structural plugin tracer contract.
function createRecordingPluginTracer() {
const spans: Array<{
name: string;
attributes: Record<string, unknown>;
status: { code: number; message?: string } | null;
ended: boolean;
}> = [];
const tracer = {
startSpan(name: string, options?: { attributes?: Record<string, string | number | boolean> }) {
const span = {
name,
attributes: { ...(options?.attributes ?? {}) } as Record<string, unknown>,
status: null as { code: number; message?: string } | null,
ended: false,
setAttribute(key: string, value: unknown) {
span.attributes[key] = value;
},
setStatus(status: { code: number; message?: string }) {
span.status = status;
},
end() {
span.ended = true;
},
};
spans.push(span);
return span;
},
};
return { tracer, spans };
}
it("opens a transfer span with the guard round-trip count around the bulk file upload", async () => {
const hostDir = await makeHostDir();
const source = path.join(hostDir, "config.txt");
await fs.writeFile(source, "plain");
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-1",
files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" }],
},
],
});
} finally {
restore();
}
const transfer = spans.find((span) => span.name === "transfer");
expect(transfer).toBeDefined();
expect(transfer!.ended).toBe(true);
// One serial guard round trip before the transfer: mkdir (with the zstd probe).
expect(transfer!.attributes["paperclip.sandbox.startup.transfer.guard.count"]).toBe(1);
expect(transfer!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");
expect(typeof transfer!.attributes["paperclip.sandbox.startup.transfer.wall_ms"]).toBe("number");
// A bulk file upload builds no host tarball, so it opens no pack span.
expect(spans.find((span) => span.name === "pack")).toBeUndefined();
});
it("marks the inbound transfer span with the inbound direction attribute", async () => {
const hostDir = await makeHostDir();
const source = path.join(hostDir, "config.txt");
await fs.writeFile(source, "plain");
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncIn?.(
syncInParams({
operationId: "sync-op-in-dir",
sourcePath: source,
targetPath: `${REMOTE_DIR}/config.txt`,
}),
);
} finally {
restore();
}
// An upload to the sandbox is an inbound transfer.
const transfer = spans.find((span) => span.name === "transfer");
expect(transfer).toBeDefined();
expect(transfer!.attributes["paperclip.sandbox.startup.transfer.direction"]).toBe("inbound");
});
it("marks the outbound transfer span with the outbound direction attribute", async () => {
const hostDir = await makeHostDir();
const sandbox = createMockSandbox();
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination?: string }>) => {
return Promise.all(
requests.map(async (req) => {
await fs.writeFile(req.destination!, "bytes");
return { source: req.source, result: req.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncOut?.(
syncOutParams({
operationId: "sync-op-out-dir",
sourcePath: `${REMOTE_DIR}/out/result.txt`,
targetPath: path.join(hostDir, "result.txt"),
}),
);
} finally {
restore();
}
// A download from the sandbox is an outbound transfer.
const transfer = spans.find((span) => span.name === "transfer");
expect(transfer).toBeDefined();
expect(transfer!.attributes["paperclip.sandbox.startup.transfer.direction"]).toBe("outbound");
});
it("opens a pack span and a transfer span around a directory mapping sync", async () => {
const hostDir = await makeHostDir();
const sourceDir = path.join(hostDir, "assets");
await fs.mkdir(sourceDir, { recursive: true });
await fs.writeFile(path.join(sourceDir, "a.txt"), "alpha");
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-dir",
files: [
{ sourcePath: sourceDir, targetPath: `${REMOTE_DIR}/.paperclip-runtime/assets`, kind: "directory" },
],
},
],
});
} finally {
restore();
}
const pack = spans.find((span) => span.name === "pack");
expect(pack).toBeDefined();
expect(pack!.ended).toBe(true);
expect(pack!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");
expect(typeof pack!.attributes["paperclip.sandbox.startup.pack.wall_ms"]).toBe("number");
const transfer = spans.find((span) => span.name === "transfer");
expect(transfer).toBeDefined();
// One serial guard round trip before the transfer: mkdir.
expect(transfer!.attributes["paperclip.sandbox.startup.transfer.guard.count"]).toBe(1);
});
it("opens ensureDirectory, transfer, promote spans in call order for a file-mapping sync", async () => {
const hostDir = await makeHostDir();
const source = path.join(hostDir, "config.txt");
await fs.writeFile(source, "plain");
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-order",
files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" }],
},
],
});
} finally {
restore();
}
expect(spans.map((span) => span.name)).toEqual([
"ensureDirectory",
"transfer",
"promote",
]);
for (const span of spans) {
expect(span.ended).toBe(true);
expect(span.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");
// A per-round-trip span carries no `*.wall_ms` attribute; the native span
// width carries its time. Only `pack` and `transfer` keep a wall_ms value.
if (span.name !== "transfer") {
expect(span.attributes["paperclip.sandbox.startup.ensureDirectory.wall_ms"]).toBeUndefined();
expect(span.attributes["paperclip.sandbox.startup.promote.wall_ms"]).toBeUndefined();
}
}
});
it("opens pack, ensureDirectory, transfer, extractTarball spans in call order for a directory-mapping sync", async () => {
const hostDir = await makeHostDir();
const sourceDir = path.join(hostDir, "assets");
await fs.mkdir(sourceDir, { recursive: true });
await fs.writeFile(path.join(sourceDir, "a.txt"), "alpha");
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-dir-order",
files: [
{ sourcePath: sourceDir, targetPath: `${REMOTE_DIR}/.paperclip-runtime/assets`, kind: "directory" },
],
},
],
});
} finally {
restore();
}
expect(spans.map((span) => span.name)).toEqual([
"pack",
"ensureDirectory",
"transfer",
"extractTarball",
]);
for (const span of spans) {
expect(span.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");
}
});
it("opens a postUploadCommand span for a post-upload command with a working directory", async () => {
const hostDir = await makeHostDir();
const source = path.join(hostDir, "config.txt");
await fs.writeFile(source, "plain");
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-post",
files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" }],
postUploadCommands: [{ command: "run-me", cwd: `${REMOTE_DIR}/sub` }],
},
],
});
} finally {
restore();
}
// The full order: the file mapping opens ensureDirectory, transfer, promote;
// the post-upload command then opens the postUploadCommand span.
expect(spans.map((span) => span.name)).toEqual([
"ensureDirectory",
"transfer",
"promote",
"postUploadCommand",
]);
const provision = spans.find((span) => span.name === "postUploadCommand");
expect(provision!.ended).toBe(true);
expect(provision!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");
});
it("gzip-tars a directory mapping host-side honoring excludes and the followSymlinks flag, then extracts it in-sandbox via a single quoted tar command", async () => {
const hostDir = await makeHostDir();
const sourceDir = path.join(hostDir, "assets");
await fs.mkdir(path.join(sourceDir, "keep"), { recursive: true });
await fs.writeFile(path.join(sourceDir, "keep", "a.txt"), "alpha");
await fs.writeFile(path.join(sourceDir, "skip.log"), "noise");
await fs.symlink("keep/a.txt", path.join(sourceDir, "link.txt"));
const sandbox = createMockSandbox();
// Capture the tar listing inside the upload mock, before withHostTempDir
// cleans the host scratch dir.
let capturedTarListing = "";
sandbox.fs.uploadFiles.mockImplementation(async (uploads: Array<{ source: string }>) => {
capturedTarListing = execFileSync("tar", ["-tvf", uploads[0].source]).toString();
});
mockGet.mockResolvedValue(sandbox);
// Preserve-symlink case (followSymlinks falsy → no -h).
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-dir",
files: [
{
sourcePath: sourceDir,
targetPath: `${REMOTE_DIR}/.paperclip-runtime/assets`,
kind: "directory",
exclude: ["*.log"],
},
],
},
],
});
expect(sandbox.fs.uploadFiles).toHaveBeenCalledTimes(1);
const [uploads] = sandbox.fs.uploadFiles.mock.calls[0] as [Array<{ source: string; destination: string }>];
expect(uploads).toHaveLength(1);
expect(uploads[0].source).toMatch(/\.tar\.gz$/);
expect(path.posix.basename(uploads[0].destination)).toMatch(/^\.paperclip-upload-.*\.tar\.gz$/);
expect(uploads[0].destination.startsWith(`${REMOTE_DIR}/`)).toBe(true);
// Inspect the real host tar: excluded file gone; symlink preserved AS a link.
expect(capturedTarListing).toContain("keep/a.txt");
expect(capturedTarListing).not.toContain("skip.log");
expect(capturedTarListing).toMatch(/link\.txt ->|link\.txt link to/);
// The target dir is created by its own mkdir command, before the upload.
const mkdirCall = sandbox.process.executeCommand.mock.calls.find(
([cmd]) =>
String(cmd).includes("mkdir -p") &&
String(cmd).includes(`'${REMOTE_DIR}/.paperclip-runtime/assets'`) &&
!String(cmd).includes("tar -xf"),
);
expect(mkdirCall).toBeDefined();
const extractCall = sandbox.process.executeCommand.mock.calls.find(([cmd]) => String(cmd).includes("tar -xf"));
expect(extractCall).toBeDefined();
const extractCommand = String(extractCall?.[0]);
// The extract is one plain `tar -xf <scratch-tar> -C <target>` command,
// followed by removing the scratch tar.
expect(extractCommand).toContain(".paperclip-runtime/assets");
expect(extractCommand).toContain("tar -xf");
expect(extractCommand).toMatch(/rm -f .*\.paperclip-upload-.*\.tar\.gz/);
});
it("syncIn dereferences symlinks to bytes when followSymlinks is true (tar -h)", async () => {
const hostDir = await makeHostDir();
const sourceDir = path.join(hostDir, "deref");
await fs.mkdir(sourceDir, { recursive: true });
await fs.writeFile(path.join(sourceDir, "real.txt"), "payload");
await fs.symlink("real.txt", path.join(sourceDir, "alias.txt"));
const sandbox = createMockSandbox();
let capturedTarListing = "";
sandbox.fs.uploadFiles.mockImplementation(async (uploads: Array<{ source: string }>) => {
capturedTarListing = execFileSync("tar", ["-tvf", uploads[0].source]).toString();
});
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-deref",
files: [{ sourcePath: sourceDir, targetPath: `${REMOTE_DIR}/deref`, kind: "directory", followSymlinks: true }],
},
],
});
// Dereferenced: alias becomes a regular file, not a link.
expect(capturedTarListing).not.toMatch(/alias\.txt ->/);
expect(capturedTarListing).toContain("alias.txt");
});
it("syncOut reads all file mappings via one downloadFiles batch, writes each to its host target, and returns per-operation counts", async () => {
const hostDir = await makeHostDir();
const sandbox = createMockSandbox();
// The download reads sandbox-side snapshots (reserved temp names), which are
// index-aligned with the file mappings; write payloads in request order.
const payloadsInOrder = ["result-bytes", "secret-bytes"];
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination?: string }>) => {
return Promise.all(
requests.map(async (req, index) => {
await fs.writeFile(req.destination!, payloadsInOrder[index]);
return { source: req.source, result: req.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
const resultTarget = path.join(hostDir, "result.txt");
const secretTarget = path.join(hostDir, "secret.key");
const result = await plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-out",
files: [
{ sourcePath: `${REMOTE_DIR}/out/result.txt`, targetPath: resultTarget, kind: "file" },
{ sourcePath: `${REMOTE_DIR}/out/secret.key`, targetPath: secretTarget, kind: "file", mode: 0o600 },
],
},
],
});
expect(sandbox.fs.downloadFiles).toHaveBeenCalledTimes(1);
const [requests] = sandbox.fs.downloadFiles.mock.calls[0] as [Array<{ source: string; destination: string }>];
expect(requests).toHaveLength(2);
for (const req of requests) {
expect(path.basename(req.destination)).toMatch(/^\.paperclip-upload-/);
// TOCTOU-closed: the download reads a reserved snapshot inside the remote
// dir, never the mutable original source path.
expect(req.source.startsWith(`${REMOTE_DIR}/`)).toBe(true);
expect(path.posix.basename(req.source)).toMatch(/^\.paperclip-upload-/);
}
expect(requests.map((req) => req.source)).not.toContain(`${REMOTE_DIR}/out/result.txt`);
expect(requests.map((req) => req.source)).not.toContain(`${REMOTE_DIR}/out/secret.key`);
expect(await fs.readFile(resultTarget, "utf8")).toBe("result-bytes");
expect(await fs.readFile(secretTarget, "utf8")).toBe("secret-bytes");
// Secret lands 0600 on the host target.
expect((await fs.stat(secretTarget)).mode & 0o777).toBe(0o600);
expect(result).toEqual({
operations: [
{ operationId: "sync-op-out", filesTransferred: 2, bytesTransferred: "result-bytes".length + "secret-bytes".length },
],
});
});
it.each(["sandbox_access", "file_download"] as const)("keeps the deleted-sandbox policy and bounded %s evidence", async (step) => {
const hostDir = await makeHostDir();
const source = Object.freeze(Object.assign(new MockDaytonaNotFoundError("private-provider-detail"), {
status: 404, cause: { code: "EIO", token: "private-provider-token" },
}));
if (step === "sandbox_access") mockGet.mockRejectedValue(source);
else {
const sandbox = createMockSandbox();
sandbox.fs.downloadFiles.mockRejectedValue(source);
mockGet.mockResolvedValue(sandbox);
}
await withEnvironmentSyncErrorCapture(async () => {
const error = await plugin.definition.onEnvironmentSyncOut!({
driverKey: "daytona", companyId: "company-1", environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: true }, lease: syncLease(),
operations: [{ operationId: "sync-op-missing-sandbox", files: [{
sourcePath: `${REMOTE_DIR}/out/result.txt`, targetPath: path.join(hostDir, "result.txt"), kind: "file",
}] }],
}).catch(error => error);
expect(error).toBeInstanceOf(Error);
expect(error.message).toBe("daytona_sandbox_not_found");
expect(error).not.toHaveProperty("cause");
const diagnostic = readEnvironmentSyncErrorDiagnostic({ data: environmentSyncErrorData(error) });
expect(diagnostic).toEqual({ errorCode: "EIO", httpStatus: 404, transferStep: step });
expect(JSON.stringify(diagnostic)).not.toContain("private-provider-");
});
});
it("syncOut snapshot guard re-checks the resolved source is a non-symlink regular file immediately before copying (validation→copy TOCTOU)", async () => {
const hostDir = await makeHostDir();
const sandbox = createMockSandbox();
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination?: string }>) => {
return Promise.all(
requests.map(async (req) => {
await fs.writeFile(req.destination!, "bytes");
return { source: req.source, result: req.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-out-nofollow",
files: [{ sourcePath: `${REMOTE_DIR}/out/data.txt`, targetPath: path.join(hostDir, "data.txt"), kind: "file" }],
},
],
});
// The snapshot guard runs realpath → confine → no-follow re-check → cp, all in
// one `sh -c`. The `[ -L ]`/`[ -f ]` re-check must precede the `cp` so a source
// the sandbox repointed to a symlink after realpath is refused, not followed.
const guardCall = sandbox.process.executeCommand.mock.calls.find(
([cmd]) => String(cmd).includes("_pc_resolve") && String(cmd).includes("cp --"),
);
expect(guardCall).toBeDefined();
const guardCommand = String(guardCall?.[0]);
expect(guardCommand).toContain('[ -L "$_pc_real" ]');
expect(guardCommand).toContain('[ -f "$_pc_real" ]');
const noFollowIdx = guardCommand.indexOf('[ -L "$_pc_real" ]');
const copyIdx = guardCommand.indexOf('cp -- "$_pc_real"');
expect(noFollowIdx).toBeGreaterThan(-1);
expect(copyIdx).toBeGreaterThan(noFollowIdx);
});
it("syncOut fails loud when any per-file download reports an error, and leaves no target file", async () => {
const hostDir = await makeHostDir();
const sandbox = createMockSandbox();
// Requests read snapshots (index-aligned with mappings); the second mapping
// (`missing.txt`) reports a per-file error.
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination?: string }>) => {
return requests.map((req, index) =>
index === 1
? { source: req.source, error: "not found", errorDetails: { message: "not found", statusCode: 404 } }
: { source: req.source, result: req.destination },
);
});
mockGet.mockResolvedValue(sandbox);
const okTarget = path.join(hostDir, "ok.txt");
const badTarget = path.join(hostDir, "missing.txt");
await expect(
plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-err",
files: [
{ sourcePath: `${REMOTE_DIR}/ok.txt`, targetPath: okTarget, kind: "file" },
{ sourcePath: `${REMOTE_DIR}/missing.txt`, targetPath: badTarget, kind: "file" },
],
},
],
}),
).rejects.toThrow(/download failed for .*missing\.txt: not found/);
// Fail-loud: no target file is promoted when the batch has any error.
await expect(fs.stat(okTarget)).rejects.toThrow();
await expect(fs.stat(badTarget)).rejects.toThrow();
});
it("syncOut rejects an outbound source whose in-sandbox realpath escapes the workspace remote dir, before any download", async () => {
const hostDir = await makeHostDir();
const sandbox = createMockSandbox();
// The in-sandbox realpath guard runs as a single `sh -c` probe; report the
// escape exit code (42) for that probe while leaving any other command green,
// so the guard is the only thing that can trip this test.
sandbox.process.executeCommand.mockImplementation(async (command: string) => {
if (command.includes("_pc_resolve")) {
return { exitCode: 42, result: `ESCAPE:${REMOTE_DIR}/out/link.txt`, artifacts: { stdout: "" } };
}
return { exitCode: 0, result: "bash", artifacts: { stdout: "bash" } };
});
mockGet.mockResolvedValue(sandbox);
const target = path.join(hostDir, "link.txt");
await expect(
plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-escape-out",
files: [{ sourcePath: `${REMOTE_DIR}/out/link.txt`, targetPath: target, kind: "file" }],
},
],
}),
).rejects.toThrow(/outbound symlink-escape guard command failed \(exit 42\)/);
// Fail-closed: the guard trips before any bytes are read, and no target lands.
expect(sandbox.fs.downloadFiles).not.toHaveBeenCalled();
await expect(fs.stat(target)).rejects.toThrow();
});
it("syncOut fails closed when the sandbox has no path canonicalizer to resolve the symlink guard", async () => {
const hostDir = await makeHostDir();
const sandbox = createMockSandbox();
// Neither `realpath` nor `readlink` present → the probe exits 40 rather than
// silently skipping the guard the host-side string check cannot enforce.
sandbox.process.executeCommand.mockImplementation(async (command: string) => {
if (command.includes("_pc_resolve")) {
return { exitCode: 40, result: "no path canonicalizer available", artifacts: { stdout: "" } };
}
return { exitCode: 0, result: "bash", artifacts: { stdout: "bash" } };
});
mockGet.mockResolvedValue(sandbox);
const target = path.join(hostDir, "data.txt");
await expect(
plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-no-canon",
files: [{ sourcePath: `${REMOTE_DIR}/out/data.txt`, targetPath: target, kind: "file" }],
},
],
}),
).rejects.toThrow(/outbound symlink-escape guard command failed \(exit 40\)/);
expect(sandbox.fs.downloadFiles).not.toHaveBeenCalled();
await expect(fs.stat(target)).rejects.toThrow();
});
it("syncIn sweeps staged temps when the batched rename fails mid-promotion", async () => {
const hostDir = await makeHostDir();
const source = path.join(hostDir, "config.txt");
await fs.writeFile(source, "plain");
const sandbox = createMockSandbox();
// mkdir + realpath guard succeed; the promoting `mv -f` fails, leaving staged
// `.paperclip-upload-*` temps that the error path must sweep with `rm -f`.
sandbox.process.executeCommand.mockImplementation(async (command: string) => {
if (command.includes("mv -f")) {
return { exitCode: 1, result: "mv: permission denied", artifacts: { stdout: "mv: permission denied" } };
}
return { exitCode: 0, result: "bash", artifacts: { stdout: "bash" } };
});
mockGet.mockResolvedValue(sandbox);
await expect(
plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-in-rename-fail",
files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" }],
},
],
}),
).rejects.toThrow(/syncIn rename command failed \(exit 1\)/);
// The upload happened, so a temp was staged; the error path cleans it up.
expect(sandbox.fs.uploadFiles).toHaveBeenCalledTimes(1);
const cleanupCall = sandbox.process.executeCommand.mock.calls.find(
([cmd]) => String(cmd).includes("rm -f") && String(cmd).includes(".paperclip-upload-"),
);
expect(cleanupCall).toBeDefined();
});
it("syncOut refuses a sandbox-authored tarball whose members escape the extraction dir (path traversal)", async () => {
const hostRoot = await makeHostDir();
const restored = path.join(hostRoot, "restored");
const sandbox = createMockSandbox();
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination?: string }>) => {
return Promise.all(
requests.map(async (req) => {
// Craft a tar containing a traversal member `../escape.txt`.
const staging = await fs.mkdtemp(path.join(os.tmpdir(), "daytona-evil-"));
tempDirs.push(staging);
await fs.mkdir(path.join(staging, "sub"), { recursive: true });
await fs.writeFile(path.join(staging, "sub", "escape.txt"), "escape");
// GNU spells member-name rewriting --transform; bsdtar (macOS) spells it -s.
const gnuTar = execFileSync("tar", ["--version"]).toString().includes("GNU tar");
execFileSync("tar", [
"-cf",
req.destination!,
"-C",
path.join(staging, "sub"),
...(gnuTar ? ["--transform", "s,^,../,"] : ["-s", ",^,../,"]),
"escape.txt",
]);
return { source: req.source, result: req.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
await expect(
plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-out-traversal",
files: [{ sourcePath: `${REMOTE_DIR}/proj`, targetPath: restored, kind: "directory" }],
},
],
}),
).rejects.toThrow(/escapes the extraction dir/);
// The traversal member (`../escape.txt` relative to `restored`) was never
// written above the extraction dir.
await expect(fs.stat(path.join(hostRoot, "escape.txt"))).rejects.toThrow();
});
it.each(["../../outside.txt", "/tmp/paperclip-git-workspace-example/skills/demo"])("syncOut refuses a sandbox-authored tarball with escaping symlink target %s", async (linkTarget) => {
const hostRoot = await makeHostDir();
const restored = path.join(hostRoot, "restored");
const sandbox = createMockSandbox();
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination?: string }>) => {
return Promise.all(
requests.map(async (req) => {
// Craft a tar whose sole member is a symlink pointing outside the tree.
const staging = await fs.mkdtemp(path.join(os.tmpdir(), "daytona-evil-"));
tempDirs.push(staging);
await fs.mkdir(path.join(staging, "sub"), { recursive: true });
await fs.symlink(linkTarget, path.join(staging, "sub", "evil"));
execFileSync("tar", ["-cf", req.destination!, "-C", path.join(staging, "sub"), "evil"]);
return { source: req.source, result: req.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
await expect(
plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-out-symlink-escape",
files: [{ sourcePath: `${REMOTE_DIR}/proj`, targetPath: restored, kind: "directory" }],
},
],
}),
).rejects.toThrow(/link whose target escapes the extraction dir/);
// Fail-closed: the confinement check runs before extraction touches disk.
await expect(fs.stat(restored)).rejects.toThrow();
});
it("syncOut refuses a symlink whose name embeds the listing delimiter (ambiguous split hides the real target)", async () => {
const hostRoot = await makeHostDir();
const restored = path.join(hostRoot, "restored");
const sandbox = createMockSandbox();
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination?: string }>) => {
return Promise.all(
requests.map(async (req) => {
// A symlink literally named "evil -> decoy" with an escaping target
// lists as "evil -> decoy -> ../../outside.txt"; splitting at the
// first delimiter would validate "decoy -> ../../outside.txt" (which
// normalizes in-tree) while tar extracts the real escaping link.
const staging = await fs.mkdtemp(path.join(os.tmpdir(), "daytona-evil-"));
tempDirs.push(staging);
await fs.mkdir(path.join(staging, "sub"), { recursive: true });
await fs.symlink("../../outside.txt", path.join(staging, "sub", "evil -> decoy"));
execFileSync("tar", ["-cf", req.destination!, "-C", path.join(staging, "sub"), "evil -> decoy"]);
return { source: req.source, result: req.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
await expect(
plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-out-ambiguous-symlink",
files: [{ sourcePath: `${REMOTE_DIR}/proj`, targetPath: restored, kind: "directory" }],
},
],
}),
).rejects.toThrow(/ambiguous symlink entry/);
// Fail-closed: the confinement check runs before extraction touches disk.
await expect(fs.stat(restored)).rejects.toThrow();
});
it("round-trips a directory (syncIn then syncOut) preserving contents, a 0600 file, and a preserved symlink", async () => {
const hostRoot = await makeHostDir();
const source = path.join(hostRoot, "src");
await fs.mkdir(path.join(source, "nested"), { recursive: true });
await fs.writeFile(path.join(source, "nested", "data.txt"), "hello world");
await fs.writeFile(path.join(source, "secret"), "top-secret");
await fs.chmod(path.join(source, "secret"), 0o600);
await fs.symlink("nested/data.txt", path.join(source, "shortcut"));
await fs.mkdir(path.join(source, ".claude", "skills"), { recursive: true });
await fs.symlink("../../nested", path.join(source, ".claude", "skills", "demo"));
// Simulate the sandbox filesystem with a host-side directory the mock tar
// commands operate on, so the round-trip exercises real tar create/extract.
const sandboxFsRoot = await makeHostDir();
const remoteTargetDir = path.join(sandboxFsRoot, "materialized");
const sandbox = createMockSandbox();
// syncIn: capture the uploaded host tar and extract it into the simulated
// sandbox dir, mirroring the in-sandbox `tar -xf`.
sandbox.fs.uploadFiles.mockImplementation(async (uploads: Array<{ source: string; destination: string }>) => {
for (const upload of uploads) {
await fs.mkdir(remoteTargetDir, { recursive: true });
execFileSync("tar", ["-xpf", upload.source, "-C", remoteTargetDir]);
}
});
// syncOut: build a tar of the simulated sandbox dir and stream it to the
// requested host destination, mirroring in-sandbox `tar -c` + downloadFiles.
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination?: string }>) => {
return Promise.all(
requests.map(async (req) => {
const entries = (await fs.readdir(remoteTargetDir)).sort();
execFileSync("tar", ["-cpf", req.destination!, "-C", remoteTargetDir, "--", ...entries]);
return { source: req.source, result: req.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{ operationId: "rt-in", files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/proj`, kind: "directory" }] },
],
});
const restored = path.join(hostRoot, "restored");
await plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{ operationId: "rt-out", files: [{ sourcePath: `${REMOTE_DIR}/proj`, targetPath: restored, kind: "directory" }] },
],
});
expect(await fs.readFile(path.join(restored, "nested", "data.txt"), "utf8")).toBe("hello world");
expect(await fs.readFile(path.join(restored, "secret"), "utf8")).toBe("top-secret");
expect((await fs.stat(path.join(restored, "secret"))).mode & 0o777).toBe(0o600);
const linkStat = await fs.lstat(path.join(restored, "shortcut"));
expect(linkStat.isSymbolicLink()).toBe(true);
expect(await fs.readlink(path.join(restored, "shortcut"))).toBe("nested/data.txt");
expect(await fs.readlink(path.join(restored, ".claude", "skills", "demo"))).toBe("../../nested");
expect(await fs.readFile(path.join(restored, ".claude", "skills", "demo", "data.txt"), "utf8")).toBe("hello world");
});
// -------------------------------------------------------------------------
// Post-upload commands (Phase 3 / Security Conditions C1–C4). Daytona runs an
// operation's ordered `postUploadCommands` in-sandbox AFTER `uploadFiles`,
// fail-fast, with the command `cwd` re-confined under the workspace remote dir.
// -------------------------------------------------------------------------
it("runs post-upload commands in array order AFTER uploadFiles, each verbatim via the exec seam", async () => {
const hostDir = await makeHostDir();
const source = path.join(hostDir, "config.txt");
await fs.writeFile(source, "plain");
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "op-cmd",
files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" }],
postUploadCommands: [
{ command: "codex-auth-merge --first" },
{ command: "chmod 600 config.txt" },
],
},
],
});
// Both commands ran, VERBATIM (first arg is the exact authored string — the
// provider never rewrote/concatenated a shell fragment onto it: C1/C3).
const findCall = (cmd: string) =>
sandbox.process.executeCommand.mock.calls.find(([c]) => c === cmd);
expect(findCall("codex-auth-merge --first")).toBeDefined();
expect(findCall("chmod 600 config.txt")).toBeDefined();
// Ordered: the first command's exec precedes the second's (C4 array order).
const orderOf = (cmd: string) => {
const idx = sandbox.process.executeCommand.mock.calls.findIndex(([c]) => c === cmd);
return sandbox.process.executeCommand.mock.invocationCallOrder[idx];
};
expect(orderOf("codex-auth-merge --first")).toBeLessThan(orderOf("chmod 600 config.txt"));
// Upload happened BEFORE the first command.
expect(sandbox.fs.uploadFiles.mock.invocationCallOrder[0]).toBeLessThan(
orderOf("codex-auth-merge --first"),
);
// Absent `cwd` defaults to the provider-resolved remote dir — never a process
// default cwd (C2). The command's structured cwd argument is REMOTE_DIR.
expect(findCall("codex-auth-merge --first")?.[1]).toBe(REMOTE_DIR);
});
it("aborts the operation fail-loud on a non-zero post-upload command exit, skipping the remainder (C4)", async () => {
const hostDir = await makeHostDir();
const source = path.join(hostDir, "config.txt");
await fs.writeFile(source, "plain");
const sandbox = createMockSandbox();
// The first command exits non-zero; every transfer/guard script stays green.
sandbox.process.executeCommand.mockImplementation(async (command: string) => {
if (command === "failing-command") {
return { exitCode: 7, result: "boom", artifacts: { stdout: "boom" } };
}
return { exitCode: 0, result: "", artifacts: { stdout: "" } };
});
mockGet.mockResolvedValue(sandbox);
await expect(
plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "op-fail",
files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" }],
postUploadCommands: [{ command: "failing-command" }, { command: "should-not-run" }],
},
],
}),
).rejects.toThrow(/post-upload command failed \(exit 7\)/);
// Fail-fast: the command after the failing one never executed.
expect(
sandbox.process.executeCommand.mock.calls.some(([c]) => c === "should-not-run"),
).toBe(false);
});
// -------------------------------------------------------------------------
// Merged git-workspace operation. A git-backed workspace stage-sync rides ONE
// operation whose `files` carry the git-history tar and the workspace-overlay
// tar, with the two extract commands as ordered `postUploadCommands`. The
// operation shares one mkdir, one confine guard, one `uploadFiles`, and one
// rename exec.
// -------------------------------------------------------------------------
it("stages a merged git-workspace operation as one uploadFiles batch and one rename exec, both extracts in order", async () => {
const hostDir = await makeHostDir();
const gitTar = path.join(hostDir, "git-workspace.tar");
const overlayTar = path.join(hostDir, "workspace.tar");
await fs.writeFile(gitTar, "git-bytes");
await fs.writeFile(overlayTar, "overlay-bytes");
const runtimeDir = `${REMOTE_DIR}/.paperclip-runtime/adapter`;
const sandbox = createMockSandbox();
mockGet.mockResolvedValue(sandbox);
const gitExtract = "git-history-extract";
const overlayExtract = "workspace-overlay-extract";
const result = await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "merged-workspace",
files: [
{ sourcePath: gitTar, targetPath: `${runtimeDir}/git-workspace-upload.tar`, kind: "file" },
{ sourcePath: overlayTar, targetPath: `${runtimeDir}/workspace-upload.tar`, kind: "file" },
],
postUploadCommands: [{ command: gitExtract }, { command: overlayExtract }],
},
],
});
// One bulk upload carries BOTH tars; one rename exec promotes both temps.
expect(sandbox.fs.uploadFiles).toHaveBeenCalledTimes(1);
const [uploads] = sandbox.fs.uploadFiles.mock.calls[0] as [Array<{ source: string; destination: string }>];
expect(uploads).toHaveLength(2);
const mvCalls = sandbox.process.executeCommand.mock.calls.filter(([cmd]) =>
String(cmd).includes("mv -f"),
);
expect(mvCalls).toHaveLength(1);
expect(String(mvCalls[0][0]).match(/mv -f /g)).toHaveLength(2);
// Both extract commands ran, in array order, AFTER the upload (git first).
const orderOf = (cmd: string) => {
const idx = sandbox.process.executeCommand.mock.calls.findIndex(([c]) => c === cmd);
return sandbox.process.executeCommand.mock.invocationCallOrder[idx];
};
expect(orderOf(gitExtract)).toBeLessThan(orderOf(overlayExtract));
expect(sandbox.fs.uploadFiles.mock.invocationCallOrder[0]).toBeLessThan(orderOf(gitExtract));
expect(result).toEqual({
operations: [{
operationId: "merged-workspace",
filesTransferred: 2,
bytesTransferred: "git-bytes".length + "overlay-bytes".length,
}],
});
});
it("stops the overlay and remove-deleted commands when the git extract fails (merged operation fail-fast)", async () => {
const hostDir = await makeHostDir();
const gitTar = path.join(hostDir, "git-workspace.tar");
const overlayTar = path.join(hostDir, "workspace.tar");
await fs.writeFile(gitTar, "git-bytes");
await fs.writeFile(overlayTar, "overlay-bytes");
const runtimeDir = `${REMOTE_DIR}/.paperclip-runtime/adapter`;
const sandbox = createMockSandbox();
// The first (git-history) extract exits non-zero; every transfer/guard script
// stays green so the fail-fast loop is the only thing that can trip this test.
sandbox.process.executeCommand.mockImplementation(async (command: string) => {
if (command === "git-history-extract") {
return { exitCode: 5, result: "boom", artifacts: { stdout: "boom" } };
}
return { exitCode: 0, result: "", artifacts: { stdout: "" } };
});
mockGet.mockResolvedValue(sandbox);
await expect(
plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "merged-failfast",
files: [
{ sourcePath: gitTar, targetPath: `${runtimeDir}/git-workspace-upload.tar`, kind: "file" },
{ sourcePath: overlayTar, targetPath: `${runtimeDir}/workspace-upload.tar`, kind: "file" },
],
postUploadCommands: [
{ command: "git-history-extract" },
{ command: "workspace-overlay-extract" },
{ command: "remove-deleted-paths" },
],
},
],
}),
).rejects.toThrow(/post-upload command failed \(exit 5\)/);
// Fail-fast: the overlay extract and the remove-deleted command never ran.
const ran = (cmd: string) =>
sandbox.process.executeCommand.mock.calls.some(([c]) => c === cmd);
expect(ran("git-history-extract")).toBe(true);
expect(ran("workspace-overlay-extract")).toBe(false);
expect(ran("remove-deleted-paths")).toBe(false);
});
it("issues no extra exec when an operation has no post-upload commands (backward-compat)", async () => {
const hostDir = await makeHostDir();
const source = path.join(hostDir, "config.txt");
await fs.writeFile(source, "plain");
const baseline = createMockSandbox();
mockGet.mockResolvedValue(baseline);
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{ operationId: "op-plain", files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" }] },
],
});
const baselineExecCount = baseline.process.executeCommand.mock.calls.length;
// Same operation, now with an (empty) postUploadCommands array — must be
// byte-identical: an absent/empty command list adds zero execs.
// Reset the process-scoped handle cache so the second operation fetches its
// own `withEmpty` handle. Both operations reuse the same providerLeaseId, so
// without this reset the cache serves the first `baseline` handle again and
// `withEmpty` records zero execs.
__resetDaytonaSandboxHandleCacheForTest();
const withEmpty = createMockSandbox();
mockGet.mockResolvedValue(withEmpty);
await plugin.definition.onEnvironmentSyncIn?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "op-plain",
files: [{ sourcePath: source, targetPath: `${REMOTE_DIR}/config.txt`, kind: "file" }],
postUploadCommands: [],
},
],
});
expect(withEmpty.process.executeCommand.mock.calls.length).toBe(baselineExecCount);
});
it("runs two concurrent inbound syncIn calls with separate reserved scratch names", async () => {
const hostDir = await makeHostDir();
const sourceA = path.join(hostDir, "a.txt");
const sourceB = path.join(hostDir, "b.txt");
await fs.writeFile(sourceA, "alpha");
await fs.writeFile(sourceB, "beta");
const sandbox = createMockSandbox();
// Gate the upload so both concurrent calls sit inside uploadFiles together.
const gate = createTransferGate(2, async () => undefined);
sandbox.fs.uploadFiles.mockImplementation(gate.body);
mockGet.mockResolvedValue(sandbox);
const callA = plugin.definition.onEnvironmentSyncIn?.(
syncInParams({ operationId: "in-a", sourcePath: sourceA, targetPath: `${REMOTE_DIR}/a.txt` }),
);
const callB = plugin.definition.onEnvironmentSyncIn?.(
syncInParams({ operationId: "in-b", sourcePath: sourceB, targetPath: `${REMOTE_DIR}/b.txt` }),
);
// Both calls reached the upload before either finished, so they overlap.
await gate.bothArrived;
expect(gate.peak()).toBe(2);
expect(sandbox.fs.uploadFiles).toHaveBeenCalledTimes(2);
gate.release();
await Promise.all([callA, callB]);
// Each concurrent call staged its upload under its own reserved scratch name;
// the two calls never share a temporary destination.
const destinations = sandbox.fs.uploadFiles.mock.calls.flatMap(
([uploads]) => (uploads as Array<{ destination: string }>).map((upload) => upload.destination),
);
expect(destinations).toHaveLength(2);
for (const destination of destinations) {
expect(path.posix.basename(destination)).toMatch(/^\.paperclip-upload-/);
expect(path.posix.dirname(destination)).toBe(REMOTE_DIR);
}
expect(new Set(destinations).size).toBe(destinations.length);
});
it("runs two concurrent outbound syncOut calls that both reach downloadFiles before either opens", async () => {
const hostDir = await makeHostDir();
const targetA = path.join(hostDir, "a.txt");
const targetB = path.join(hostDir, "b.txt");
const sandbox = createMockSandbox();
// Gate the download so both concurrent calls sit inside downloadFiles
// together before either resolves.
const gate = createTransferGate(2, fulfilDownload);
sandbox.fs.downloadFiles.mockImplementation(gate.body);
mockGet.mockResolvedValue(sandbox);
const callA = plugin.definition.onEnvironmentSyncOut?.(
syncOutParams({ operationId: "out-a", sourcePath: `${REMOTE_DIR}/a.txt`, targetPath: targetA }),
);
const callB = plugin.definition.onEnvironmentSyncOut?.(
syncOutParams({ operationId: "out-b", sourcePath: `${REMOTE_DIR}/b.txt`, targetPath: targetB }),
);
// Both calls reached the download before either gate opened, so they overlap.
await gate.bothArrived;
expect(gate.peak()).toBe(2);
expect(sandbox.fs.downloadFiles).toHaveBeenCalledTimes(2);
gate.release();
await Promise.all([callA, callB]);
// Each concurrent call read its own reserved snapshot; the two calls never
// share a download source.
const sources = sandbox.fs.downloadFiles.mock.calls.flatMap(
([requests]) => (requests as Array<{ source: string }>).map((request) => request.source),
);
expect(sources).toHaveLength(2);
for (const source of sources) {
expect(source.startsWith(`${REMOTE_DIR}/`)).toBe(true);
expect(path.posix.basename(source)).toMatch(/^\.paperclip-upload-/);
}
expect(new Set(sources).size).toBe(sources.length);
expect(await fs.readFile(targetA, "utf8")).toBe("bytes");
expect(await fs.readFile(targetB, "utf8")).toBe("bytes");
});
it("waits for one active inbound and one active outbound call before teardown releases the sandbox", async () => {
const hostDir = await makeHostDir();
const inboundSource = path.join(hostDir, "in.txt");
const outboundTarget = path.join(hostDir, "out.txt");
await fs.writeFile(inboundSource, "inbound");
const sandbox = createMockSandbox({ id: "sandbox-123" });
// Hold the inbound upload and the outbound download open at the same time, so
// the shared lease has two active sync calls when teardown starts.
let uploadArrived!: () => void;
const uploadStarted = new Promise<void>((resolve) => { uploadArrived = resolve; });
let releaseUpload!: () => void;
sandbox.fs.uploadFiles.mockImplementation(async () => {
await new Promise<void>((resolve) => {
releaseUpload = resolve;
uploadArrived();
});
});
let downloadArrived!: () => void;
const downloadStarted = new Promise<void>((resolve) => { downloadArrived = resolve; });
let releaseDownload!: () => void;
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination: string }>) => {
await new Promise<void>((resolve) => {
releaseDownload = resolve;
downloadArrived();
});
return Promise.all(
requests.map(async (request) => {
await fs.writeFile(request.destination, "bytes");
return { source: request.source, result: request.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
const inboundCall = plugin.definition.onEnvironmentSyncIn?.(
syncInParams({ operationId: "in-active", sourcePath: inboundSource, targetPath: `${REMOTE_DIR}/in.txt` }),
);
const outboundCall = plugin.definition.onEnvironmentSyncOut?.(
syncOutParams({ operationId: "out-active", sourcePath: `${REMOTE_DIR}/out.txt`, targetPath: outboundTarget }),
);
// Wait for the actual transfers. One event-loop tick does not guarantee
// that the inbound filesystem reads have finished on a busy runner.
await Promise.all([uploadStarted, downloadStarted]);
const destroyCall = plugin.definition.onEnvironmentDestroyLease?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
providerLeaseId: "sandbox-123",
config: { timeoutMs: 300000, reuseLease: false },
});
await new Promise((resolve) => setTimeout(resolve, 0));
// Two active sync calls block teardown, so it must not delete the sandbox yet.
expect(sandbox.delete).not.toHaveBeenCalled();
// Release only the inbound call. One outbound call is still active, so
// teardown must keep waiting.
releaseUpload();
await inboundCall;
await new Promise((resolve) => setTimeout(resolve, 0));
expect(sandbox.delete).not.toHaveBeenCalled();
// Release the outbound call. No sync call is active now, so teardown deletes.
releaseDownload();
await Promise.all([outboundCall, destroyCall]);
expect(sandbox.fs.uploadFiles).toHaveBeenCalledTimes(1);
expect(sandbox.fs.downloadFiles).toHaveBeenCalledTimes(1);
expect(sandbox.delete).toHaveBeenCalledTimes(1);
});
it("opens a transfer span with the guard round-trip count around the bulk file download", async () => {
const hostDir = await makeHostDir();
const target = path.join(hostDir, "result.txt");
const sandbox = createMockSandbox();
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination: string }>) => {
return Promise.all(
requests.map(async (request) => {
await fs.writeFile(request.destination, "bytes");
return { source: request.source, result: request.destination };
}),
);
});
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-out",
files: [{ sourcePath: `${REMOTE_DIR}/out/result.txt`, targetPath: target, kind: "file" }],
},
],
});
} finally {
restore();
}
const transfer = spans.find((span) => span.name === "transfer");
expect(transfer).toBeDefined();
expect(transfer!.ended).toBe(true);
// One serial guard round trip before the transfer: the validate-and-snapshot.
expect(transfer!.attributes["paperclip.sandbox.startup.transfer.guard.count"]).toBe(1);
expect(transfer!.attributes["paperclip.sandbox.startup.provider"]).toBe("daytona");
expect(typeof transfer!.attributes["paperclip.sandbox.startup.transfer.wall_ms"]).toBe("number");
});
it("opens a transfer span around a directory-mapping download with the guard round-trip count", async () => {
const hostDir = await makeHostDir();
const targetDir = path.join(hostDir, "assets");
const sandbox = createMockSandbox();
sandbox.fs.downloadFiles.mockImplementation(async (requests: Array<{ source: string; destination: string }>) => {
// Write a valid empty tar (1024-byte zero EOF marker) so host-side extract
// is a clean no-op.
await Promise.all(requests.map((request) => fs.writeFile(request.destination, Buffer.alloc(1024))));
return requests.map((request) => ({ source: request.source, result: request.destination }));
});
mockGet.mockResolvedValue(sandbox);
const { tracer, spans } = createRecordingPluginTracer();
const restore = __setDaytonaPluginContextForTest({ tracer } as unknown as PluginContext);
try {
await plugin.definition.onEnvironmentSyncOut?.({
driverKey: "daytona",
companyId: "company-1",
environmentId: "env-1",
config: { timeoutMs: 300000, reuseLease: false },
lease: syncLease(),
operations: [
{
operationId: "sync-op-out-dir",
files: [{ sourcePath: `${REMOTE_DIR}/out/assets`, targetPath: targetDir, kind: "directory" }],
},
],
});
} finally {
restore();
}
const transfer = spans.find((span) => span.name === "transfer");
expect(transfer).toBeDefined();
expect(transfer!.ended).toBe(true);
// Two serial guard round trips before the transfer: confinement + in-sandbox
// tar.
expect(transfer!.attributes["paperclip.sandbox.startup.transfer.guard.count"]).toBe(2);
expect(typeof transfer!.attributes["paperclip.sandbox.startup.transfer.wall_ms"]).toBe("number");
});
});
describe("daytona manifest memory config", () => {
const memorySchema = (
manifest.environmentDrivers?.[0]?.configSchema as {
properties?: Record<string, { type?: string; enum?: unknown[] }>;
required?: string[];
}
);
it("offers memory as a fixed dropdown of supported sandbox sizes", () => {
expect(memorySchema.properties?.memory?.enum).toEqual([1, 2, 4, 8]);
});
it("excludes 0 — an invalid Daytona memory configuration", () => {
expect(memorySchema.properties?.memory?.enum).not.toContain(0);
});
it("keeps memory optional so the blank/default selection stays valid", () => {
expect(memorySchema.required ?? []).not.toContain("memory");
});
});
describe("daytona manifest form defaults", () => {
const configSchema = (
manifest.environmentDrivers?.[0]?.configSchema as {
properties?: Record<
string,
{ format?: string; enum?: unknown[]; minimum?: number; default?: unknown }
>;
}
);
const properties = configSchema.properties ?? {};
it("pre-fills sizing and image fields for the environment form", () => {
expect(properties.cpu?.default).toBe(4);
expect(properties.memory?.default).toBe(4);
expect(properties.disk?.default).toBe(10);
expect(properties.image?.default).toBe("daytonaio/sandbox:0.8.0");
});
it("keeps each default within its own schema constraints", () => {
expect(properties.memory?.enum).toContain(properties.memory?.default);
expect(properties.cpu?.default as number).toBeGreaterThanOrEqual(
properties.cpu?.minimum ?? 1,
);
expect(properties.disk?.default as number).toBeGreaterThanOrEqual(
properties.disk?.minimum ?? 1,
);
});
it("declares no default on secret-ref fields, which would be persisted as a company secret", () => {
for (const prop of Object.values(properties)) {
if (prop.format === "secret-ref") {
expect(prop.default).toBeUndefined();
}
}
});
});
describe("parseTarVerboseListingLine", () => {
it("parses GNU tar listing lines (file, dir, symlink, hardlink, numeric owner)", () => {
expect(parseTarVerboseListingLine("-rw-r--r-- daytona/daytona 7560 2026-08-11 21:43 AGENTS.md")).toEqual({
typeFlag: "-",
rest: "AGENTS.md",
});
expect(parseTarVerboseListingLine("drwxr-xr-x daytona/daytona 0 2026-08-11 21:43 nested/")).toEqual({
typeFlag: "d",
rest: "nested/",
});
expect(
parseTarVerboseListingLine("lrwxrwxrwx daytona/daytona 0 2026-08-11 21:43 shortcut -> nested/data.txt"),
).toEqual({ typeFlag: "l", rest: "shortcut -> nested/data.txt" });
expect(
parseTarVerboseListingLine("hrw-r--r-- daytona/daytona 0 2026-08-11 21:43 copy.txt link to data.txt"),
).toEqual({ typeFlag: "h", rest: "copy.txt link to data.txt" });
expect(parseTarVerboseListingLine("-rw-r--r-- 0/0 12 2026-08-11 21:43 root-owned.txt")).toEqual({
typeFlag: "-",
rest: "root-owned.txt",
});
});
it("parses bsdtar (macOS) listing lines, including year-form dates", () => {
expect(parseTarVerboseListingLine("-rw-r--r-- 0 daytona daytona 7560 Aug 11 21:43 AGENTS.md")).toEqual({
typeFlag: "-",
rest: "AGENTS.md",
});
expect(parseTarVerboseListingLine("drwxr-xr-x 0 daytona daytona 0 Aug 11 21:43 nested/")).toEqual({
typeFlag: "d",
rest: "nested/",
});
expect(
parseTarVerboseListingLine("lrwxr-xr-x 0 daytona daytona 0 Aug 11 21:43 shortcut -> nested/data.txt"),
).toEqual({ typeFlag: "l", rest: "shortcut -> nested/data.txt" });
expect(
parseTarVerboseListingLine("hrw-r--r-- 0 daytona daytona 0 Aug 11 21:43 copy.txt link to data.txt"),
).toEqual({ typeFlag: "h", rest: "copy.txt link to data.txt" });
expect(parseTarVerboseListingLine("-rw-r--r-- 0 daytona daytona 7560 Aug 11 2025 old.txt")).toEqual({
typeFlag: "-",
rest: "old.txt",
});
});
it("keeps the true member name for bsdtar lines with numeric uid/gid, so traversal stays visible", () => {
// With unresolvable ids bsdtar prints bare numbers; a looser GNU-first parse
// would read this shape shifted by one field and report the member name as
// "21:43 ../escape.txt", hiding the leading "../" from the traversal check.
expect(parseTarVerboseListingLine("-rw-r--r-- 0 1001 1001 7560 Aug 11 21:43 ../escape.txt")).toEqual({
typeFlag: "-",
rest: "../escape.txt",
});
});
it("returns null (fail closed) for lines matching neither dialect", () => {
expect(parseTarVerboseListingLine("not a tar listing line")).toBeNull();
expect(parseTarVerboseListingLine("tar: Error is not recoverable: exiting now")).toBeNull();
// Device nodes carry "major,minor" instead of a byte count in both dialects.
expect(parseTarVerboseListingLine("crw-rw-rw- root/root 1,3 2026-08-11 21:43 dev/null")).toBeNull();
expect(parseTarVerboseListingLine("crw-rw-rw- 0 root wheel 1,3 Aug 11 21:43 dev/null")).toBeNull();
});
});
describe("splitLinkEntryOnce", () => {
it("splits a clean single-delimiter link field", () => {
expect(splitLinkEntryOnce("shortcut -> nested/data.txt", " -> ")).toEqual({
name: "shortcut",
target: "nested/data.txt",
});
expect(splitLinkEntryOnce("copy.txt link to data.txt", " link to ")).toEqual({
name: "copy.txt",
target: "data.txt",
});
});
it("returns null (fail closed) when the delimiter is absent or appears more than once", () => {
expect(splitLinkEntryOnce("no delimiter here", " -> ")).toBeNull();
// A link name or target embedding the delimiter makes the split point
// unresolvable; either split choice can hide an escaping target.
expect(splitLinkEntryOnce("evil -> decoy -> ../../outside.txt", " -> ")).toBeNull();
expect(splitLinkEntryOnce("a link to b link to ../../outside.txt", " link to ")).toBeNull();
});
});