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 path from "node:path";
import { createHash, randomUUID } from "node:crypto";
import { Daytona, DaytonaNotFoundError, DaytonaTimeoutError } from "@daytonaio/sdk";
import type {
CreateSandboxBaseParams,
CreateSandboxFromImageParams,
CreateSandboxFromSnapshotParams,
DaytonaConfig,
Resources,
Sandbox,
} from "@daytonaio/sdk";
import { decodeChannelBytes, definePlugin, NOOP_PLUGIN_TRACER, PluginEnvironmentCreationCleanupError, readEnvironmentCreationCleanupError, withEnvironmentSyncTransferStep, preserveEnvironmentSyncErrorDiagnostic } from "@paperclipai/plugin-sdk";
import type {
PluginContext,
PluginEnvironmentCreationCleanup,
PluginEnvironmentAcquisitionDiagnostic,
PluginEnvironmentAcquisitionProviderState,
PluginTracer,
PluginEnvironmentAcquireLeaseParams,
PluginEnvironmentCancelInteractiveSetupParams,
PluginEnvironmentCancelInteractiveSetupResult,
PluginEnvironmentCaptureTemplateParams,
PluginEnvironmentCaptureTemplateResult,
PluginEnvironmentDeleteTemplateParams,
PluginEnvironmentDeleteTemplateResult,
PluginEnvironmentDestroyLeaseParams,
PluginEnvironmentInspectLeaseParams,
PluginEnvironmentLeaseObservation,
PluginEnvironmentExecuteParams,
PluginEnvironmentExecuteResult,
PluginEnvironmentRunnerIngressEndpointParams,
PluginEnvironmentRunnerIngressEndpoint,
PluginEnvironmentGetInteractiveSetupParams,
PluginEnvironmentInteractiveSetupSession,
PluginEnvironmentLease,
PluginEnvironmentProbeParams,
PluginEnvironmentProbeResult,
PluginEnvironmentRealizeWorkspaceParams,
PluginEnvironmentRealizeWorkspaceResult,
PluginEnvironmentReleaseLeaseParams,
PluginEnvironmentTerminationReceipt,
PluginEnvironmentResumeLeaseParams,
PluginEnvironmentStartInteractiveSetupParams,
PluginEnvironmentSyncInParams,
PluginEnvironmentSyncOutParams,
PluginEnvironmentSyncResult,
PluginEnvironmentValidateConfigParams,
PluginEnvironmentValidationResult,
PluginSyncOperation,
} from "@paperclipai/plugin-sdk";
import { performSyncIn, performSyncOut, withProviderSpan } from "./file-sync.js";
import { DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS } from "./manifest.js";
import { observeSessionStreamExit } from "./session-stream-exit.js";
import { DaytonaIdleActivity, trackDaytonaHooks, type DaytonaIdleProof } from "./idle-activity.js";
// The Claude `setup-token` login pseudo-terminal (PTY) session for this provider.
// The session runs the login command on a real pseudo-terminal, streams the
// terminal output, and delivers the delayed browser code plus the Enter byte. A
// later phase binds the opener to `sandbox.process` and wraps it with the
// `createLoginPtyTransport` factory from `@paperclipai/adapter-utils` to
// build the transport the login runner drives.
export {
createDaytonaLoginPtySessionOpener,
openDaytonaLoginPtySession,
createDaytonaLoginHomeFs,
} from "./login-pty.js";
export type {
LoginPtySession,
LoginPtySessionOpener,
LoginPtyLaunchDescriptor,
DaytonaPtyHandle,
DaytonaPtyProcess,
DaytonaPtyCreateOptions,
DaytonaLoginPtyOptions,
DaytonaLoginHomeFs,
} from "./login-pty.js";
import {
openDaytonaLoginPtySession as openLoginPtySession,
createDaytonaLoginHomeFs,
} from "./login-pty.js";
import type {
LoginPtySession as LoginPtyWorkerSession,
DaytonaPtyProcess,
DaytonaSandboxExec,
} from "./login-pty.js";
// The Daytona duplex command stream for the sandbox callback bridge. The channel
// runs the gateway command on a raw pseudo-terminal, streams the frames, and
// accepts host input. The worker resolves the sandbox by the provider lease id,
// registers the channel under the host route id, and streams the data and the
// exit through `ctx.duplexChannel`.
export {
createDaytonaDuplexChannelSessionOpener,
openDaytonaDuplexChannelSession,
buildDuplexChannelLaunchWrapper,
} from "./duplex-command-stream.js";
export type {
DuplexChannelSession,
DuplexChannelSessionOpener,
DaytonaDuplexChannelOptions,
} from "./duplex-command-stream.js";
import { openDaytonaDuplexChannelSession as openDuplexChannelSession } from "./duplex-command-stream.js";
import type { DuplexChannelSession } from "./duplex-command-stream.js";
// Injectable monotonic clock for provider-boundary timing (Open Q1). Defaults
// to the real wall clock; `plugin.test.ts` overrides it via
// `setDaytonaTimingClockForTest` so the measured `durationMs`/`getDurationMs`
// are deterministic. The timing path never calls `Date.now()` directly.
let timingNow: () => number = () => Date.now();
// The plugin context, hoisted to a module variable in `setup(ctx)`. The
// lifecycle hooks and the file-sync helpers have no closure over `ctx`, so they
// read the tracer through `getPluginTracer()`. Before `setup` runs (or in a
// test) the tracer is a no-op, so a span never throws.
let pluginContext: PluginContext | null = null;
// A deadline does not settle the underlying request. Keep both that request
// and its allocation until completion and scoped provider cleanup are proven.
const idleActivity = new DaytonaIdleActivity();
/**
* Return the plugin tracer. It is the injected `ctx.tracer` after `setup`, or a
* no-op before it. A provider span opened through it records only when tracing
* is on and an active host trace context is present.
*/
export function getPluginTracer(): PluginTracer {
return pluginContext?.tracer ?? NOOP_PLUGIN_TRACER;
}
/**
* Test seam: set the module-level plugin context, and return a restore function.
* `plugin.test.ts` uses it to inject a recording tracer without running `setup`.
*/
export function __setDaytonaPluginContextForTest(ctx: PluginContext | null): () => void {
const previous = pluginContext;
pluginContext = ctx;
return () => {
pluginContext = previous;
};
}
/**
* Test seam: override the provider-timing clock and return a restore function.
* Not used in production, where the default wall clock always applies.
*/
export function setDaytonaTimingClockForTest(now: () => number): () => void {
const previous = timingNow;
timingNow = now;
return () => {
timingNow = previous;
};
}
// Injectable clock for the handle cache's freshness bookkeeping, deliberately
// kept separate from the provider-timing clock so tests can advance virtual time
// past a lease's auto-stop interval without perturbing the `getDurationMs` /
// `durationMs` measurements that ride on `timingNow`.
let handleFreshnessNow: () => number = () => Date.now();
/**
* Test seam: override the handle-cache freshness clock and return a restore
* function. Not used in production, where the default wall clock always applies.
*/
export function setDaytonaHandleFreshnessClockForTest(now: () => number): () => void {
const previous = handleFreshnessNow;
handleFreshnessNow = now;
return () => {
handleFreshnessNow = previous;
};
}
interface DaytonaDriverConfig {
apiKey: string | null;
apiUrl: string | null;
target: string | null;
snapshot: string | null;
image: string | null;
language: string | null;
timeoutMs: number;
livenessTimeoutMs: number;
cpu: number | null;
memory: number | null;
disk: number | null;
gpu: number | null;
autoStopInterval: number | null;
autoArchiveInterval: number | null;
autoDeleteInterval: number | null;
reuseLease: boolean;
archiveOnRelease: boolean;
}
type WorkspaceSentinelResult = {
path: string;
token: string | null;
runId?: string;
providerLeaseId?: string;
result: "written" | "matched" | "missing" | "mismatch" | "skipped";
};
type DaytonaSshAccess = {
token?: string | null;
command?: string | null;
sshCommand?: string | null;
expiresAt?: string | null;
};
type DaytonaInteractiveSandbox = Sandbox & {
createSshAccess?: (expiresInMinutes?: number) => Promise<DaytonaSshAccess>;
_experimental_createSnapshot?: (name: string, timeout?: number) => Promise<void>;
};
type DaytonaSnapshotService = {
get?: (name: string) => Promise<unknown>;
delete?: (snapshot: unknown) => Promise<void>;
};
type SnapshotIdentity = { provider: "daytona"; requestedRef: string; id: string; name: string; organizationId: string; createdAt: string };
const WORKSPACE_SENTINEL_RELATIVE_PATH = ".paperclip-runtime/reusable-sandbox-lease.json";
// Quota-safety defaults (minutes). Daytona counts *stopped* sandboxes against
// the storage quota; only *archived* sandboxes move to cold object storage and
// stop counting. Without these, stopped/leaked sandboxes accumulate until the
// org quota fills. We apply sane defaults so every sandbox eventually leaves the
// quota on its own even when our own cleanup fails or never runs (crashed runs,
// failed lease destroys, orphaned probes). All three stay overridable per
// environment; an explicit 0/-1 in config is preserved.
//
// - autoStop: stop idle *running* sandboxes (frees CPU/RAM, starts the archive clock).
// - autoArchive: archive *stopped* sandboxes so they leave the disk quota.
// - autoDelete: backstop reaper for sandboxes nobody resumes.
const DEFAULT_AUTO_STOP_INTERVAL_MINUTES = 15;
const DEFAULT_AUTO_ARCHIVE_INTERVAL_MINUTES = 60;
const DEFAULT_AUTO_DELETE_INTERVAL_MINUTES = 7 * 24 * 60; // 7 days
// Sandboxes released with `archiveOnRelease` (test/probe runs) are archived so
// operators can inspect them from the Daytona dashboard, then expired by
// Daytona itself after this interval (counted from the stop that precedes the
// archive) so debugging copies don't accumulate.
const ARCHIVE_ON_RELEASE_AUTO_DELETE_MINUTES = 60;
// Fail-fast cap for git network operations (push, fetch, pull, ls-remote, etc.)
// so a stalled remote or missing credential never consumes the full 900 s adapter
// RPC ceiling; callers always see an actionable error within this window.
const GIT_NETWORK_TIMEOUT_MS = 120_000;
// Per-call bound on the provider liveness read (`sandbox.refreshData()`). The
// Daytona SDK gives this metadata read no timeout, so a silently unresponsive
// sandbox connection leaves it pending with no error. The plugin then stalls
// until the outer host-to-worker RPC backstop fires, which is a general ceiling,
// not a fast, specific detector. This bound turns that silent hang into a fast,
// clear error. It is configurable through `livenessTimeoutMs`; a value of 0 or
// less disables the extra bound.
const DEFAULT_LIVENESS_TIMEOUT_MS = 30_000;
// Extra margin added to the SDK start/recover timeout when the plugin wraps
// those lifecycle calls in its own per-call bound. The SDK call already carries
// a `timeoutSeconds` deadline; the wrapper is a backstop for a connection-level
// hang that the SDK deadline can miss. The margin lets the SDK deadline fire
// first on a normal slow start, so the wrapper only fires on a true hang.
const LIVENESS_START_TIMEOUT_MARGIN_MS = 5_000;
// Noninteractive git credential defaults injected into every Daytona one-shot
// command so that git operations never stall waiting for a terminal prompt.
// Callers can override any of these via the env parameter.
const NONINTERACTIVE_GIT_ENV: Record<string, string> = {
GIT_TERMINAL_PROMPT: "0",
GCM_INTERACTIVE: "Never",
GIT_ASKPASS: "echo",
SSH_ASKPASS: "echo",
SSH_ASKPASS_REQUIRE: "force",
};
const DEFAULT_SSH_ACCESS_MINUTES = 60;
const DAYTONA_SSH_GATEWAY_HOST = "ssh.app.daytona.io";
function parseOptionalString(value: unknown): string | null {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}
function parseOptionalInteger(value: unknown): number | null {
if (value == null || value === "") return null;
const parsed = Number(value);
return Number.isFinite(parsed) ? Math.trunc(parsed) : null;
}
function parseOptionalNumber(value: unknown): number | null {
if (value == null || value === "") return null;
const parsed = Number(value);
return Number.isFinite(parsed) ? parsed : null;
}
function parseDriverConfig(raw: Record<string, unknown>): DaytonaDriverConfig {
const timeoutMs = Number(raw.timeoutMs ?? DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS);
const livenessTimeoutMs = Number(raw.livenessTimeoutMs ?? DEFAULT_LIVENESS_TIMEOUT_MS);
return {
apiKey: parseOptionalString(raw.apiKey),
apiUrl: parseOptionalString(raw.apiUrl),
target: parseOptionalString(raw.target),
snapshot: parseOptionalString(raw.snapshot),
image: parseOptionalString(raw.image),
language: parseOptionalString(raw.language),
timeoutMs: Number.isFinite(timeoutMs) ? Math.trunc(timeoutMs) : DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS,
livenessTimeoutMs: Number.isFinite(livenessTimeoutMs) ? Math.trunc(livenessTimeoutMs) : DEFAULT_LIVENESS_TIMEOUT_MS,
cpu: parseOptionalNumber(raw.cpu),
memory: parseOptionalNumber(raw.memory),
disk: parseOptionalNumber(raw.disk),
gpu: parseOptionalNumber(raw.gpu),
autoStopInterval: parseOptionalInteger(raw.autoStopInterval) ?? DEFAULT_AUTO_STOP_INTERVAL_MINUTES,
autoArchiveInterval: parseOptionalInteger(raw.autoArchiveInterval) ?? DEFAULT_AUTO_ARCHIVE_INTERVAL_MINUTES,
autoDeleteInterval: parseOptionalInteger(raw.autoDeleteInterval) ?? DEFAULT_AUTO_DELETE_INTERVAL_MINUTES,
reuseLease: raw.reuseLease === true,
archiveOnRelease: raw.archiveOnRelease === true,
};
}
function resolveApiKey(config: DaytonaDriverConfig): string {
if (config.apiKey) {
return config.apiKey;
}
const envApiKey = process.env.DAYTONA_API_KEY?.trim() ?? "";
if (!envApiKey) {
throw new Error("Daytona sandbox environments require an API key in config or DAYTONA_API_KEY.");
}
return envApiKey;
}
function createDaytonaClient(config: DaytonaDriverConfig): Daytona {
const clientConfig: DaytonaConfig = {
apiKey: resolveApiKey(config),
};
if (config.apiUrl) clientConfig.apiUrl = config.apiUrl;
if (config.target) clientConfig.target = config.target;
return new Daytona(clientConfig);
}
function buildResources(config: DaytonaDriverConfig): Resources | undefined {
if (config.cpu == null && config.memory == null && config.disk == null && config.gpu == null) {
return undefined;
}
return {
cpu: config.cpu ?? undefined,
memory: config.memory ?? undefined,
disk: config.disk ?? undefined,
gpu: config.gpu ?? undefined,
};
}
function buildCreateParams(
config: DaytonaDriverConfig,
labels: Record<string, string>,
): CreateSandboxFromImageParams | CreateSandboxFromSnapshotParams {
const base: CreateSandboxBaseParams = {
labels,
language: config.language ?? undefined,
autoStopInterval: config.autoStopInterval ?? undefined,
autoArchiveInterval: config.autoArchiveInterval ?? undefined,
autoDeleteInterval: config.autoDeleteInterval ?? undefined,
};
if (config.image) {
return {
...base,
image: config.image,
resources: buildResources(config),
};
}
return {
...base,
snapshot: config.snapshot ?? undefined,
};
}
function hasResourceRequest(config: DaytonaDriverConfig): boolean {
return config.cpu != null || config.memory != null || config.disk != null || config.gpu != null;
}
function validateResourceRequest(config: DaytonaDriverConfig): string | null {
if (!hasResourceRequest(config) || config.image) return null;
return "Daytona resource settings require image-backed sandbox creation; snapshot/default sandbox creation cannot override CPU, memory, disk, or GPU.";
}
function validateRuntimeResourceRequest(config: DaytonaDriverConfig): string | null {
// A snapshot bakes in its own resource allocation, so resources are dropped at
// create time (see buildCreateParams) rather than failing the run when a custom
// image snapshot is layered over a base config that carries CPU/memory/disk/GPU.
if (!hasResourceRequest(config) || config.image || config.snapshot) return null;
return "Daytona resource settings require image-backed sandbox creation; default sandbox creation cannot override CPU, memory, disk, or GPU.";
}
function buildSandboxLabels(input: {
companyId: string;
environmentId: string;
runId?: string;
setupSessionId?: string;
purpose?: string;
reuseLease: boolean;
}): Record<string, string> {
return {
"paperclip-provider": "daytona",
"paperclip-company-id": input.companyId,
"paperclip-environment-id": input.environmentId,
"paperclip-reuse-lease": input.reuseLease ? "true" : "false",
...(input.runId ? { "paperclip-run-id": input.runId } : {}),
...(input.setupSessionId ? { "paperclip-setup-session-id": input.setupSessionId } : {}),
...(input.purpose ? { "paperclip-purpose": input.purpose } : {}),
};
}
function toTimeoutSeconds(timeoutMs: number): number {
return Math.max(1, Math.ceil(timeoutMs / 1000));
}
function resolveTimeoutMs(paramsTimeoutMs: number | undefined, config: DaytonaDriverConfig): number {
return paramsTimeoutMs != null && Number.isFinite(paramsTimeoutMs) && paramsTimeoutMs > 0
? Math.trunc(paramsTimeoutMs)
: config.timeoutMs;
}
function formatErrorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}
function stableStringify(value: unknown): string {
if (Array.isArray(value)) {
return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
}
if (isRecord(value)) {
return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
}
return JSON.stringify(value) ?? "null";
}
function isValidUrl(value: string): boolean {
try {
new URL(value);
return true;
} catch {
return false;
}
}
// A per-call liveness bound elapsed before the wrapped provider call returned.
// The message names the operation and the bound so an operator sees at once
// that the sandbox connection is unresponsive, not that the operation is slow.
class SandboxLivenessTimeoutError extends Error {
constructor(operation: string, timeoutMs: number) {
super(
`Daytona sandbox liveness call "${operation}" did not respond within ${timeoutMs} ms; `
+ "the sandbox connection is unresponsive.",
);
this.name = "SandboxLivenessTimeoutError";
}
}
// Race a provider call against a per-call deadline. A value of 0 or less turns
// the bound off and runs the call unwrapped. The timer is always cleared, so a
// call that resolves before the deadline leaks no pending timer. A call that
// never resolves stays pending after the deadline rejects, but it holds no
// timer and produces no unhandled rejection.
async function withLivenessTimeout<T>(
operation: string,
timeoutMs: number,
run: () => Promise<T>,
): Promise<T> {
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
return idleActivity.track(run);
}
let timer: ReturnType<typeof setTimeout> | undefined;
const deadline = new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new SandboxLivenessTimeoutError(operation, timeoutMs)), timeoutMs);
});
try {
return await Promise.race([idleActivity.track(run), deadline]);
} finally {
if (timer !== undefined) clearTimeout(timer);
}
}
/** A dead bridge must not prevent provider-level termination. Stop/delete is
* the receipt boundary; timing out this drain is never termination evidence. */
async function drainSandboxBeforeTermination(sandbox: Sandbox, scope: SandboxScope) {
const timeoutMs = Math.max(1, Math.min(scope.config.livenessTimeoutMs || 10_000, 10_000));
const steps: [string, () => Promise<unknown>][] = [
["sandbox.activityDrain", () => sandboxHandleActivityGates.waitForIdle(scope)],
["sandbox.sessionTeardown", () => teardownSession(sandbox, scope)],
["sandbox.channelTeardown", () => closeDaytonaDuplexChannelsForLease(scope.providerLeaseId)],
];
for (const [operation, action] of steps) {
try { await withLivenessTimeout(operation, timeoutMs, action); }
catch {
// Each cleanup is independent; one hung bridge must not retain other routes.
console.warn("Sandbox bridge cleanup failed; continuing provider termination.");
}
}
}
async function terminateAtProvider<T>(scope: SandboxScope, operation: string, action: () => Promise<T>) {
const timeoutMs = scope.config.timeoutMs > 0 ? scope.config.timeoutMs : DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS;
return withLivenessTimeout(operation, timeoutMs + LIVENESS_START_TIMEOUT_MARGIN_MS, action);
}
async function ensureSandboxStarted(sandbox: Sandbox, timeoutSeconds: number): Promise<void> {
if (sandbox.state === "started") return;
// Bound the lifecycle call just past its own SDK deadline. A normal slow start
// finishes within `timeoutSeconds`; only a connection-level hang the SDK
// deadline misses reaches this wrapper bound.
const startBoundMs = timeoutSeconds * 1_000 + LIVENESS_START_TIMEOUT_MARGIN_MS;
if (sandbox.state === "error") {
if (sandbox.recoverable) {
await withLivenessTimeout("sandbox.recover", startBoundMs, () => sandbox.recover(timeoutSeconds));
return;
}
throw new Error(`Daytona sandbox ${sandbox.id} is in an unrecoverable error state: ${sandbox.errorReason ?? "unknown error"}`);
}
await withLivenessTimeout("sandbox.start", startBoundMs, () => sandbox.start(timeoutSeconds));
}
function hasMissingSandboxContainer(sandbox: Sandbox): boolean {
if (sandbox.state !== "error" || sandbox.recoverable !== false || typeof sandbox.errorReason !== "string") return false;
if (typeof sandbox.id !== "string" || !sandbox.id) return false;
return sandbox.errorReason ===
`not found: failed to inspect sandbox container ${sandbox.id}: Error response from daemon: No such container: ${sandbox.id}`;
}
async function resolveSandboxWorkingDirectory(sandbox: Sandbox, create = true): Promise<string> {
const root = (await sandbox.getWorkDir())?.trim()
|| (await sandbox.getUserHomeDir())?.trim()
|| "/home/daytona";
const remoteCwd = path.posix.join(root, "paperclip-workspace");
if (create) await sandbox.fs.createFolder(remoteCwd, "755");
return remoteCwd;
}
async function detectSandboxShellCommand(sandbox: Sandbox, timeoutSeconds: number): Promise<"bash" | "sh"> {
try {
const result = await sandbox.process.executeCommand(
"if command -v bash >/dev/null 2>&1; then printf bash; else printf sh; fi",
undefined,
undefined,
timeoutSeconds,
);
return result.result?.trim() === "bash" ? "bash" : "sh";
} catch {
return "sh";
}
}
function parseProbeInteger(value: string | undefined | null): number | null {
const trimmed = value?.trim() ?? "";
if (!/^\d+$/.test(trimmed)) {
return null;
}
const parsed = Number.parseInt(trimmed, 10);
return Number.isInteger(parsed) ? parsed : null;
}
function workspaceSentinelToken(input: {
params: Pick<PluginEnvironmentAcquireLeaseParams, "companyId" | "environmentId" | "agentId" | "executionWorkspaceId" | "issueId" | "adapterType" | "runId">;
providerLeaseId: string;
config: DaytonaDriverConfig;
}): string | null {
if ((!input.config.reuseLease && !input.params.runId) || !input.params.agentId || (!input.params.executionWorkspaceId && !input.params.issueId)) {
return null;
}
return createHash("sha256")
.update(stableStringify({
provider: "daytona",
...(!input.config.reuseLease ? { ephemeralRunId: input.params.runId, ephemeralProviderLeaseId: input.providerLeaseId } : {}),
companyId: input.params.companyId,
environmentId: input.params.environmentId,
agentId: input.params.agentId,
executionWorkspaceId: input.params.executionWorkspaceId,
...(input.params.executionWorkspaceId ? {} : { projectlessIssueId: input.params.issueId }),
adapterType: input.params.adapterType ?? null,
image: input.config.image,
snapshot: input.config.snapshot,
target: input.config.target,
// Include resource-shaping inputs so changing the requested allocation
// expires old reusable leases and forces a fresh sandbox instead of
// reusing a previously provisioned (e.g. one-CPU) sandbox.
cpu: input.config.cpu,
memory: input.config.memory,
disk: input.config.disk,
gpu: input.config.gpu,
}))
.digest("hex");
}
function workspaceSentinelPath(remoteCwd: string): string {
return path.posix.join(remoteCwd, WORKSPACE_SENTINEL_RELATIVE_PATH);
}
async function writeWorkspaceSentinel(input: {
sandbox: Sandbox;
remoteCwd: string;
params: PluginEnvironmentAcquireLeaseParams;
config: DaytonaDriverConfig;
timeoutSeconds: number;
}): Promise<WorkspaceSentinelResult> {
const sentinelPath = workspaceSentinelPath(input.remoteCwd);
const token = workspaceSentinelToken({ params: input.params, config: input.config, providerLeaseId: input.sandbox.id });
if (!token) {
return { path: sentinelPath, token: null, result: "skipped" };
}
await input.sandbox.fs.createFolder(path.posix.dirname(sentinelPath), "755");
await input.sandbox.fs.uploadFile(
Buffer.from(JSON.stringify({
version: 1,
token,
companyId: input.params.companyId,
environmentId: input.params.environmentId,
agentId: input.params.agentId,
executionWorkspaceId: input.params.executionWorkspaceId,
...(input.params.executionWorkspaceId ? {} : { projectlessIssueId: input.params.issueId }),
adapterType: input.params.adapterType ?? null,
provider: "daytona",
writtenAt: new Date().toISOString(),
}, null, 2), "utf8"),
sentinelPath,
input.timeoutSeconds,
);
return { path: sentinelPath, token, result: "written",
...(!input.config.reuseLease ? { runId: input.params.runId!, providerLeaseId: input.sandbox.id } : {}) };
}
async function verifyWorkspaceSentinel(input: {
sandbox: Sandbox;
remoteCwd: string;
leaseMetadata?: Record<string, unknown>;
timeoutSeconds: number;
}): Promise<WorkspaceSentinelResult> {
const metadataSentinel = isRecord(input.leaseMetadata?.workspaceSentinel)
? input.leaseMetadata.workspaceSentinel
: null;
const sentinelPath = typeof metadataSentinel?.path === "string"
? metadataSentinel.path
: workspaceSentinelPath(input.remoteCwd);
const binding = typeof metadataSentinel?.runId === "string" && typeof metadataSentinel?.providerLeaseId === "string"
? { runId: metadataSentinel.runId, providerLeaseId: metadataSentinel.providerLeaseId } : {};
const expectedToken = typeof metadataSentinel?.token === "string" ? metadataSentinel.token : null;
if (!expectedToken) {
return { path: sentinelPath, token: null, result: "missing" };
}
const result = await input.sandbox.process.executeCommand(
`cat ${shellQuote(sentinelPath)}`,
undefined,
undefined,
input.timeoutSeconds,
);
if (result.exitCode !== 0) {
return { path: sentinelPath, token: expectedToken, result: "missing" };
}
try {
const parsed = JSON.parse(result.result ?? result.artifacts?.stdout ?? "") as unknown;
const actualToken = isRecord(parsed) && typeof parsed.token === "string" ? parsed.token : null;
return {
path: sentinelPath,
token: expectedToken,
...binding,
result: actualToken === expectedToken ? "matched" : "mismatch",
};
} catch {
return { path: sentinelPath, token: expectedToken, result: "mismatch" };
}
}
function leaseMetadata(input: {
config: DaytonaDriverConfig;
sandbox: Sandbox;
shellCommand: "bash" | "sh";
remoteCwd: string;
resumedLease: boolean;
resumedFromState?: string | null;
sandboxState?: string | null;
workspaceSentinel?: WorkspaceSentinelResult;
snapshotIdentity?: SnapshotIdentity;
}) {
return {
provider: "daytona",
shellCommand: input.shellCommand,
sandboxId: input.sandbox.id,
sandboxName: input.sandbox.name,
sandboxState: input.sandboxState ?? input.sandbox.state ?? null,
image: input.config.image,
snapshot: input.config.snapshot,
...(input.snapshotIdentity ? { snapshotIdentity: input.snapshotIdentity } : {}),
target: input.sandbox.target,
timeoutMs: input.config.timeoutMs,
reuseLease: input.config.reuseLease,
// Persisted so the release path (which rebuilds config from lease
// metadata) still knows to archive instead of delete.
...(input.config.archiveOnRelease ? { archiveOnRelease: true } : {}),
remoteCwd: input.remoteCwd,
resumedLease: input.resumedLease,
...(input.resumedLease
? { resumedFromState: input.resumedFromState ?? null }
: {}),
// Record the resources Paperclip attempted to request so future diagnosis
// can compare requested allocation against what Daytona provisioned.
...(input.config.cpu != null ? { cpu: input.config.cpu } : {}),
...(input.config.memory != null ? { memory: input.config.memory } : {}),
...(input.config.disk != null ? { disk: input.config.disk } : {}),
...(input.config.gpu != null ? { gpu: input.config.gpu } : {}),
...(input.workspaceSentinel ? { workspaceSentinel: input.workspaceSentinel } : {}),
};
}
function shellQuote(value: string): string {
return `'${value.replace(/'/g, `'"'"'`)}'`;
}
function resolveConnectionExpiresInMinutes(value: number | null | undefined): number {
if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_SSH_ACCESS_MINUTES;
return Math.min(24 * 60, Math.max(1, Math.trunc(value)));
}
function expiresAtForMinutes(minutes: number): string {
return new Date(Date.now() + minutes * 60_000).toISOString();
}
// Configure a provider-side time-to-live so Daytona destroys the sandbox at or
// before the caller-requested deadline, even after a Paperclip crash or outage.
// `setTtl` counts wall-clock time regardless of the sandbox state, so the destroy
// happens even when the sandbox is stopped, paused, or archived. The function
// returns the real provider destroy time (`autoDestroyAt`) as evidence of the
// provider-side bound. It returns null when the caller sets no deadline, when the
// deadline is invalid, or when the deadline is less than one minute away (Daytona
// TTL granularity is one minute, so a nearer deadline maps to no valid TTL). The
// server then fails closed on a null expiry and releases the lease.
async function configureSandboxExpiry(input: {
sandbox: Sandbox;
requestedExpiresAt: string | null | undefined;
nowMs: number;
}): Promise<string | null> {
const requestedMs = input.requestedExpiresAt ? Date.parse(input.requestedExpiresAt) : Number.NaN;
if (!Number.isFinite(requestedMs)) return null;
// Round DOWN so the provider destroy time never lands after the deadline.
const ttlMinutes = Math.floor((requestedMs - input.nowMs) / 60_000);
if (ttlMinutes < 1) return null;
await input.sandbox.setTtl(ttlMinutes);
await input.sandbox.refreshData();
const autoDestroyAt = input.sandbox.autoDestroyAt;
return typeof autoDestroyAt === "string" && autoDestroyAt.trim().length > 0
? autoDestroyAt.trim()
: null;
}
function sanitizeSnapshotName(value: string | null | undefined, fallback: string): string {
const cleaned = (value ?? fallback)
.trim()
.toLowerCase()
.replace(/[^a-z0-9._-]+/g, "-")
.replace(/^-+|-+$/g, "")
.slice(0, 96);
return cleaned || fallback;
}
function withSetupSourceTemplate(
config: DaytonaDriverConfig,
params: Pick<PluginEnvironmentStartInteractiveSetupParams, "sourceTemplateRef" | "sourceTemplateKind">,
): DaytonaDriverConfig {
if (!params.sourceTemplateRef) return config;
const sourceKind = params.sourceTemplateKind ?? "snapshot";
if (sourceKind === "image") {
return {
...config,
image: params.sourceTemplateRef,
snapshot: null,
};
}
if (sourceKind !== "snapshot") {
throw new Error(`Daytona interactive setup can start from image or snapshot templates only, not ${sourceKind}.`);
}
return {
...config,
snapshot: params.sourceTemplateRef,
image: null,
};
}
async function createSshConnection(
sandbox: Sandbox,
expiresInMinutes: number,
): Promise<Pick<PluginEnvironmentInteractiveSetupSession, "connectionSummary" | "connectionPayload">> {
const createSshAccess = (sandbox as DaytonaInteractiveSandbox).createSshAccess;
if (typeof createSshAccess !== "function") {
throw new Error(
"Daytona interactive setup requires @daytonaio/sdk Sandbox.createSshAccess support.",
);
}
const fallbackExpiresAt = expiresAtForMinutes(expiresInMinutes);
const access = await createSshAccess.call(sandbox, expiresInMinutes);
const token = typeof access.token === "string" && access.token.trim().length > 0
? access.token.trim()
: null;
const commandFromAccess =
typeof access.command === "string" && access.command.trim().length > 0
? access.command.trim()
: typeof access.sshCommand === "string" && access.sshCommand.trim().length > 0
? access.sshCommand.trim()
: null;
const command = commandFromAccess ?? (token ? `ssh ${token}@${DAYTONA_SSH_GATEWAY_HOST}` : null);
if (!command) {
throw new Error("Daytona SSH access did not return a token or SSH command.");
}
const expiresAt = typeof access.expiresAt === "string" && access.expiresAt.trim().length > 0
? access.expiresAt.trim()
: fallbackExpiresAt;
return {
connectionSummary: {
type: "ssh",
username: "token",
hostRedacted: true,
portRedacted: true,
commandRedacted: true,
expiresAt,
metadata: {
provider: "daytona",
expiresInMinutes,
},
},
connectionPayload: {
type: "ssh",
command,
token,
expiresAt,
metadata: {
provider: "daytona",
sensitive: true,
},
},
};
}
function interactiveSetupMetadata(input: {
config: DaytonaDriverConfig;
sandbox: Sandbox;
shellCommand: "bash" | "sh";
remoteCwd: string;
sourceTemplateRef?: string | null;
}) {
return {
provider: "daytona",
sandboxId: input.sandbox.id,
sandboxState: input.sandbox.state ?? null,
shellCommand: input.shellCommand,
imageConfigured: Boolean(input.config.image),
snapshotConfigured: Boolean(input.config.snapshot),
sourceTemplateRefRedacted: Boolean(input.sourceTemplateRef),
target: input.sandbox.target,
timeoutMs: input.config.timeoutMs,
remoteCwd: input.remoteCwd,
connectionRedacted: true,
};
}
function isValidShellEnvKey(value: string): boolean {
return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
}
const GIT_NETWORK_SUBCOMMANDS = new Set(["push", "fetch", "pull", "ls-remote", "clone"]);
function isGitNetworkCommand(command: string, args: string[]): boolean {
if (path.basename(command) !== "git") return false;
// Find the first positional arg (the git subcommand), skipping flags and their values.
let i = 0;
while (i < args.length) {
const arg = args[i];
if (arg === "-C" || arg === "-c" || arg === "--git-dir" || arg === "--work-tree") {
i += 2;
continue;
}
if (arg.startsWith("-")) {
i++;
continue;
}
if (GIT_NETWORK_SUBCOMMANDS.has(arg)) return true;
if (arg === "remote") {
const next = args.slice(i + 1).find(a => !a.startsWith("-"));
return next === "update";
}
if (arg === "submodule") {
const next = args.slice(i + 1).find(a => !a.startsWith("-"));
return next === "update";
}
return false;
}
return false;
}
// Build the one-shot exec command. Daytona's `executeCommand` runs the script
// in a non-login shell, so it does not source `/etc/profile` on its own. The
// Daytona reference image puts `node`, `claude`, and the other CLIs on the PATH
// through `/etc/profile.d/00-restore-env.sh`, which only `/etc/profile` sources.
// So the wrapper sources the login profiles itself; a non-login shell is then
// enough to resolve the CLIs. The wrapper no longer sources `nvm.sh`; the
// sandbox image supplies `node` on the PATH. See the sandbox runtime
// requirements document.
function buildLoginShellScript(input: {
command: string;
args: string[];
cwd?: string;
env?: Record<string, string>;
stdinPath?: string;
}): string {
const callerEnv = input.env ?? {};
for (const key of Object.keys(callerEnv)) {
if (!isValidShellEnvKey(key)) {
throw new Error(`Invalid sandbox environment variable key: ${key}`);
}
}
// Caller env takes priority over noninteractive git credential defaults
const env = { ...NONINTERACTIVE_GIT_ENV, ...callerEnv };
const envArgs = Object.entries(env)
.filter((entry): entry is [string, string] => typeof entry[1] === "string")
.map(([key, value]) => `${key}=${shellQuote(value)}`);
const commandParts = [shellQuote(input.command), ...input.args.map(shellQuote)].join(" ");
const redirectedCommand = input.stdinPath
? `${commandParts} < ${shellQuote(input.stdinPath)}`
: commandParts;
// Each `executeCommand` call runs in its own shell, so we don't `exec`-
// replace it; running the command as the last `&&`-chained line is enough to
// surface the right exit code.
const finalLine = envArgs.length > 0
? `env ${envArgs.join(" ")} ${redirectedCommand}`
: redirectedCommand;
const lines = [
'if [ -f /etc/profile ]; then . /etc/profile >/dev/null 2>&1 || true; fi',
'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi',
// .bash_profile typically sources .bashrc itself; only source .bashrc
// directly when no .bash_profile exists to avoid double-running setup.
'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; elif [ -f "$HOME/.bashrc" ]; then . "$HOME/.bashrc" >/dev/null 2>&1 || true; fi',
'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi',
];
if (input.cwd) {
lines.push(`cd ${shellQuote(input.cwd)}`);
}
lines.push(finalLine);
return lines.join(" && ");
}
// The workspace remote dir is the confinement root for native file sync. It is
// recorded on the lease metadata at acquire/resume time; require it so a sync can
// never run without a concrete root to confine every sandbox path against.
function resolveSyncRemoteDir(lease: { metadata?: Record<string, unknown> | null }): string {
const remoteCwd = lease.metadata?.remoteCwd;
if (typeof remoteCwd === "string" && remoteCwd.trim().length > 0) {
return remoteCwd.trim();
}
throw new Error("Daytona file sync requires a workspace remote dir on the lease metadata.");
}
async function createSandbox(
params: PluginEnvironmentAcquireLeaseParams | PluginEnvironmentProbeParams | PluginEnvironmentStartInteractiveSetupParams,
config: DaytonaDriverConfig,
options: {
purpose?: string;
onCreateAttempt?: (cleanup: PluginEnvironmentCreationCleanup) => void;
onCreateFailure?: () => PluginEnvironmentAcquisitionDiagnostic;
onSnapshotIdentity?: (identity: SnapshotIdentity) => void;
} = {},
): Promise<Sandbox> {
const resourceRequestError = validateRuntimeResourceRequest(config);
if (resourceRequestError) {
throw new Error(resourceRequestError);
}
const client = createDaytonaClient(config);
let createConfig = config;
if ("resolveSnapshotIdentity" in params && params.resolveSnapshotIdentity && config.snapshot && !config.image) {
// This read happens only during explicit qualification. The SDK does not
// bound snapshot.get; a timed-out read must never continue into allocation.
const snapshot = await withLivenessTimeout("snapshot.identity", Math.min(config.timeoutMs || 10_000, 10_000),
() => client.snapshot.get(config.snapshot!));
if (!/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(snapshot.id ?? "")
|| !snapshot.name || !snapshot.organizationId || !snapshot.createdAt
|| (config.snapshot !== snapshot.id && config.snapshot !== snapshot.name)
|| !Number.isFinite(Date.parse(String(snapshot.createdAt)))) {
throw new Error("Daytona did not return an immutable snapshot identity. Retry the connection probe or select Legacy runner.");
}
const identity: SnapshotIdentity = { provider: "daytona", requestedRef: config.snapshot,
id: snapshot.id, name: snapshot.name, organizationId: snapshot.organizationId, createdAt: new Date(snapshot.createdAt).toISOString() };
createConfig = { ...config, snapshot: identity.id };
options.onSnapshotIdentity?.(identity);
}
// The SDK can create a sandbox and then throw while waiting for it to start.
// Keep an attempt-specific provider name so that failure cannot lose ownership.
const attemptId = randomUUID();
const name = `paperclip-create-${attemptId}`;
const labels = { ...buildSandboxLabels({
companyId: params.companyId,
environmentId: params.environmentId,
runId: "runId" in params ? params.runId : undefined,
setupSessionId: "sessionId" in params ? params.sessionId : undefined,
purpose: options.purpose,
reuseLease: config.reuseLease,
}), "paperclip-create-attempt": attemptId };
// The SDK mutates params.labels (for example, code-toolbox-language).
// Preserve our immutable ownership snapshot for validation and retry.
const createParams = { ...buildCreateParams(createConfig, { ...labels }), name };
const cleanup: PluginEnvironmentCreationCleanup = {
providerLeaseId: name, companyId: params.companyId, environmentId: params.environmentId,
...("runId" in params ? { runId: params.runId } : {}),
attemptId, labels, accountFingerprint: sandboxAccountDiscriminator(config),
};
options.onCreateAttempt?.(cleanup);
const allocation = idleActivity.resource(providerActivityKey(params, config, name), true);
try {
const sandbox = await idleActivity.track(() => client.create(createParams, {
timeout: toTimeoutSeconds(config.timeoutMs),
}));
idleActivity.observe(allocation, providerActivityKey(params, config, sandbox.id));
return sandbox;
} catch (createError) {
// Observe the create failure before compensating deletion can stall or fail.
const diagnostic = options.onCreateFailure?.();
try {
// A not-found lookup after an uncertain create is not a deletion receipt:
// the provider may still materialize the request. Keep the name in the
// error so cleanup can be reconciled rather than declaring success.
await destroyFailedCreation(config, cleanup, params.driverKey);
} catch (cleanupError) {
throw new PluginEnvironmentCreationCleanupError([createError, cleanupError],
`Daytona sandbox creation failed; cleanup could not be confirmed for ${name}`, cleanup, diagnostic);
}
throw createError;
}
}
// Resolve by the immutable creation name, not through the admitted-lease cache:
// the SDK's returned sandbox ID differs from this provisional name. Persist a
// verified provider ID before host-driven deletion. Its later absence is then
// conclusive, even if the deletion receipt or database update was lost.
async function destroyFailedCreation(
config: DaytonaDriverConfig, cleanup: PluginEnvironmentCreationCleanup,
driverKey: string,
requireDurableObservation = false,
): Promise<void> {
if (cleanup.providerLeaseId !== `paperclip-create-${cleanup.attemptId}` ||
cleanup.accountFingerprint !== sandboxAccountDiscriminator(config) ||
cleanup.labels["paperclip-provider"] !== "daytona" ||
cleanup.labels["paperclip-create-attempt"] !== cleanup.attemptId ||
cleanup.labels["paperclip-company-id"] !== cleanup.companyId ||
cleanup.labels["paperclip-environment-id"] !== cleanup.environmentId ||
(cleanup.runId !== undefined && cleanup.labels["paperclip-run-id"] !== cleanup.runId)) {
throw new Error("Failed-create sandbox ownership does not match");
}
const identity = { driverKey, companyId: cleanup.companyId, environmentId: cleanup.environmentId };
const allocation = idleActivity.resource(providerActivityKey(identity, config, cleanup.providerLeaseId), true);
if (cleanup.observedProviderLeaseId) {
idleActivity.observe(allocation, providerActivityKey(identity, config, cleanup.observedProviderLeaseId));
}
const client = createDaytonaClient(config);
let orphan: Sandbox;
const observationProof = idleActivity.proof(providerActivityKey(identity, config,
cleanup.observedProviderLeaseId ?? cleanup.providerLeaseId));
try {
orphan = await withLivenessTimeout("sandbox.failedCreateLookup", 10_000,
() => client.get(cleanup.observedProviderLeaseId ?? cleanup.providerLeaseId));
} catch (error) {
// A name that has never been observed may still materialize. An ID already
// observed with exact ownership cannot materialize as a new allocation.
if (cleanup.observedProviderLeaseId && error instanceof DaytonaNotFoundError) {
idleActivity.confirm(observationProof, true);
return;
}
throw error;
}
if ((cleanup.observedProviderLeaseId && orphan.id !== cleanup.observedProviderLeaseId) ||
orphan.name !== cleanup.providerLeaseId || Object.entries(cleanup.labels).some(([key, value]) => orphan.labels?.[key] !== value)) {
throw new Error("Failed-create sandbox ownership does not match");
}
if (!cleanup.observedProviderLeaseId) {
cleanup.observedProviderLeaseId = orphan.id;
if (requireDurableObservation) {
// No destructive call yet: the host journals the observation and retries.
throw new PluginEnvironmentCreationCleanupError([], "Persist observed sandbox identity before cleanup", cleanup);
}
}
idleActivity.observe(allocation, providerActivityKey(identity, config, orphan.id));
const deletionProof = idleActivity.proof(providerActivityKey(identity, config, orphan.id));
await withLivenessTimeout("sandbox.failedCreateDelete", 15_000, () => orphan.delete(10, true));
idleActivity.confirm(deletionProof);
}
// Daytona states reported as-is after a create deadline; any other is `other`.
const REPORTED_CREATE_STATES = new Set<string>([
"creating", "pending_build", "building_snapshot", "pulling_snapshot", "starting", "started", "error", "build_failed",
] satisfies PluginEnvironmentAcquisitionProviderState[]);
// One read-only lookup of the provisional creation name, so a create deadline
// records where the provider left the allocation. It neither deletes nor
// records an observed ID: the host-owned cleanup envelope is unchanged.
async function observeCreateState(
config: DaytonaDriverConfig, cleanup: PluginEnvironmentCreationCleanup,
): Promise<PluginEnvironmentAcquisitionProviderState> {
try {
const sandbox = await withLivenessTimeout("sandbox.createStateLookup", 5_000,
() => createDaytonaClient(config).get(cleanup.providerLeaseId));
if (!sandbox || sandbox.name !== cleanup.providerLeaseId || typeof sandbox.state !== "string" ||
Object.entries(cleanup.labels).some(([key, value]) => sandbox.labels?.[key] !== value)) return "unavailable";
return REPORTED_CREATE_STATES.has(sandbox.state) ? sandbox.state as PluginEnvironmentAcquisitionProviderState : "other";
} catch (error) {
return error instanceof DaytonaNotFoundError ? "absent" : "unavailable";
}
}
// ─── Per-lease started-sandbox handle cache ──────────────────────────────────
// Memoize the started Daytona `Sandbox` handle so repeated exec/sync/resume/
// teardown calls on one lease skip the per-call `client.get(sandboxId)` REST
// re-fetch (measured ~4,938 ms on `stage.sync`) and the client construction it
// implies. The cache is process-memory only — no handle, API key, or credential
// is ever persisted or logged (Stage-1 security review C6).
//
// Isolation is the whole game here: the cached object is an authenticated
// compute handle, so a mis-keyed or un-evicted entry could run one lease/tenant's
// commands inside another's sandbox. The guarantees below map 1:1 to the Stage-1
// required-fix conditions:
// C1 Key by a NON-SECRET composite scope, never the bare providerLeaseId:
// {driverKey, companyId, environmentId, providerLeaseId, account}. The
// account discriminator is a hash of the resolved endpoint + credentials
// so two environments pointing at different Daytona accounts (or a rotated
// key) never collide — without storing the secret in the key.
// C2 Every read (cache hit AND resolved single-flight populate) asserts the
// handle's `sandbox.id === providerLeaseId`; a mismatch evicts and throws
// (fail closed) rather than serving the wrong sandbox.
// C4 Callers evict at every teardown hook. Populate rejections (NotFound,
// network, id mismatch) are never cached — they drop from the map so the
// next call re-fetches.
// C5 In-flight populate promises live under the composite key only; there is
// no fallback lookup by bare providerLeaseId, so lease A's in-flight
// promise can never be awaited for lease B.
type SandboxScope = {
driverKey: string;
companyId: string;
environmentId: string;
providerLeaseId: string;
config: DaytonaDriverConfig;
};
function providerActivityKey(
identity: { driverKey: string; companyId: string; environmentId: string },
config: DaytonaDriverConfig,
providerLeaseId: string,
): string {
return sandboxHandleCacheKey({ ...identity, config, providerLeaseId });
}
function confirmedTermination(scope: SandboxScope, state: "stopped" | "destroyed", proof: DaytonaIdleProof): PluginEnvironmentTerminationReceipt {
idleActivity.confirm(proof);
return { providerLeaseId: scope.providerLeaseId, state };
}
// Non-secret provider/account fingerprint. Uses the *resolved* key (config or
// DAYTONA_API_KEY env fallback) so an env-provided credential is still scoped,
// but only its sha256 digest — never the key itself — enters the cache key (C1/C6).
function sandboxAccountDiscriminator(config: DaytonaDriverConfig): string {
const resolvedApiKey = config.apiKey ?? process.env.DAYTONA_API_KEY?.trim() ?? null;
return createHash("sha256")
.update(stableStringify({
apiUrl: config.apiUrl,
// Target is a creation placement hint, not account identity: the SDK
// resolves existing sandboxes by ID. Lease metadata fills an omitted
// target with the actual region, which must not split admission state.
apiKey: resolvedApiKey,
}))
.digest("hex");
}
function sandboxHandleCacheKey(scope: SandboxScope): string {
return stableStringify({
driverKey: scope.driverKey,
companyId: scope.companyId,
environmentId: scope.environmentId,
providerLeaseId: scope.providerLeaseId,
account: sandboxAccountDiscriminator(scope.config),
});
}
function assertHandleMatchesLease(sandbox: Sandbox, providerLeaseId: string): void {
// C2: a handle must never stand in for a different sandbox than the lease
// asked for. Belt-and-suspenders against a provider that returns a renamed or
// substituted sandbox, and against any future key collision.
if (sandbox.id !== providerLeaseId) {
throw new Error(
`Daytona sandbox handle mismatch: handle ${sandbox.id} does not belong to lease ${providerLeaseId}.`,
);
}
}
// A cached `Sandbox` carries the provider state captured when it was last
// fetched/refreshed. Daytona auto-stops an idle sandbox after `autoStopInterval`
// minutes, at which point that snapshot ("started") no longer matches reality
// and `ensureSandboxStarted` would wrongly skip the restart, sending every
// subsequent exec/sync at a stopped sandbox. Before reusing a handle that has
// gone untouched for this fraction of the auto-stop interval we re-read the live
// state so the restart decision is made against the truth. Reusing a handle for
// an operation resets Daytona's idle clock, so an actively-used lease stays well
// inside the window and never pays the refresh — only a lease resumed after an
// idle gap does.
const STALE_HANDLE_REFRESH_SAFETY_FRACTION = 0.5;
function staleHandleRefreshThresholdMs(autoStopIntervalMinutes: number | null): number | null {
// Auto-stop disabled (0 / null): the provider never stops the sandbox out from
// under a live handle, so the started snapshot stays valid until we evict it
// and no refresh is warranted.
if (autoStopIntervalMinutes == null || autoStopIntervalMinutes <= 0) return null;
return Math.floor(autoStopIntervalMinutes * 60_000 * STALE_HANDLE_REFRESH_SAFETY_FRACTION);
}
type SandboxHandleCacheEntry = {
sandbox: Promise<Sandbox>;
// Last time we know the live state was accurate: set when the handle is
// fetched/refreshed and on every reuse (an operation follows, resetting the
// provider idle clock).
verifiedAtMs: number;
};
type SandboxLookupOptions = {
bypassTeardownGate?: boolean;
// Report the cache decision at the handle lookup. `true` means the warm
// handle cache served the handle; `false` means the lookup called
// `client.get`. The caller uses this to set the explicit exec `cache_hit`
// flag, instead of the old `providerGetMs == 0` proxy.
onCacheDecision?: (cacheHit: boolean) => void;
};
type SandboxHandleTeardownGate = {
promise: Promise<void>;
release: () => void;
refCount: number;
};
const sandboxHandleTeardownGates = (() => {
const gates = new Map<string, SandboxHandleTeardownGate>();
function begin(scope: SandboxScope): SandboxHandleTeardownGate {
idleActivity.resource(sandboxHandleCacheKey(scope));
const key = sandboxHandleCacheKey(scope);
const existing = gates.get(key);
if (existing) {
existing.refCount += 1;
return existing;
}
let release!: () => void;
const gate: SandboxHandleTeardownGate = {
promise: new Promise<void>((resolve) => {
release = resolve;
}),
release: () => release(),
refCount: 1,
};
gates.set(key, gate);
return gate;
}
function current(scope: SandboxScope): SandboxHandleTeardownGate | null {
return gates.get(sandboxHandleCacheKey(scope)) ?? null;
}
function end(scope: SandboxScope, gate: SandboxHandleTeardownGate): void {
const key = sandboxHandleCacheKey(scope);
gate.refCount -= 1;
if (gate.refCount > 0) return;
if (gates.get(key) === gate) {
gates.delete(key);
}
gate.release();
}
function reset(): void {
gates.clear();
}
return { begin, current, end, reset };
})();
type SandboxHandleActivityGate = {
promise: Promise<void>;
release: () => void;
refCount: number;
};
const sandboxHandleActivityGates = (() => {
const gates = new Map<string, SandboxHandleActivityGate>();
async function begin(scope: SandboxScope): Promise<SandboxHandleActivityGate> {
const key = sandboxHandleCacheKey(scope);
const existing = gates.get(key);
if (existing) {
existing.refCount += 1;
return existing;
}
let release!: () => void;
const gate: SandboxHandleActivityGate = {
promise: new Promise<void>((resolve) => {
release = resolve;
}),
release: () => release(),
refCount: 1,
};
gates.set(key, gate);
return gate;
}
async function waitForIdle(scope: SandboxScope): Promise<void> {
const gate = gates.get(sandboxHandleCacheKey(scope));
if (!gate) return;
await gate.promise;
}
function end(scope: SandboxScope, gate: SandboxHandleActivityGate): void {
const key = sandboxHandleCacheKey(scope);
gate.refCount -= 1;
if (gate.refCount > 0) return;
if (gates.get(key) === gate) {
gates.delete(key);
}
gate.release();
}
function reset(): void {
gates.clear();
}
function isActive(scope: SandboxScope): boolean {
return gates.has(sandboxHandleCacheKey(scope));
}
return { begin, waitForIdle, isActive, end, reset };
})();
type SandboxLeaseAdmissionOptions = {
allowClosed?: boolean;
};
const sandboxHandleLeaseAdmissionStates = (() => {
const states = new Map<string, boolean>();
function key(scope: SandboxScope): string {
return sandboxHandleCacheKey(scope);
}
function open(scope: SandboxScope): void {
states.set(key(scope), false);
}
function close(scope: SandboxScope): void {
states.set(key(scope), true);
}
function isClosed(scope: SandboxScope): boolean {
return states.get(key(scope)) === true;
}
function reset(): void {
states.clear();
}
return { open, close, isClosed, reset };
})();
async function withSandboxActivityGate<T>(
scope: SandboxScope,
fn: () => Promise<T>,
options: SandboxLeaseAdmissionOptions = {},
): Promise<T> {
while (true) {
if (!options.allowClosed && sandboxHandleLeaseAdmissionStates.isClosed(scope)) {
throw new Error(`Daytona sandbox lease ${scope.providerLeaseId} is no longer active.`);
}
const teardownGate = sandboxHandleTeardownGates.current(scope);
if (teardownGate) {
await teardownGate.promise;
if (!options.allowClosed && sandboxHandleLeaseAdmissionStates.isClosed(scope)) {
throw new Error(`Daytona sandbox lease ${scope.providerLeaseId} is no longer active.`);
}
continue;
}
const activityGate = await sandboxHandleActivityGates.begin(scope);
try {
// A teardown can still begin between the initial check above and the
// activity-gate admission. If that happens, back out and wait for the
// teardown to finish instead of proceeding into a race with cleanup.
if (sandboxHandleTeardownGates.current(scope)) {
continue;
}
if (!options.allowClosed && sandboxHandleLeaseAdmissionStates.isClosed(scope)) {
throw new Error(`Daytona sandbox lease ${scope.providerLeaseId} is no longer active.`);
}
idleActivity.resource(sandboxHandleCacheKey(scope));
return await fn();
} finally {
sandboxHandleActivityGates.end(scope, activityGate);
}
}
}
const sandboxHandleCache = (() => {
const entries = new Map<string, SandboxHandleCacheEntry>();
function markFresh(scope: SandboxScope): void {
const entry = entries.get(sandboxHandleCacheKey(scope));
if (entry) {
entry.verifiedAtMs = handleFreshnessNow();
}
}
async function get(scope: SandboxScope, options: SandboxLookupOptions = {}): Promise<Sandbox> {
const key = sandboxHandleCacheKey(scope);
const entry = entries.get(key);
if (entry) {
// The warm handle cache holds an entry, so this lookup serves the handle
// without a `client.get` round trip. Report the cache decision now.
options.onCacheDecision?.(true);
const sandbox = await entry.sandbox;
// Re-assert on every hit; evict + fail closed on any mismatch (C2).
try {
assertHandleMatchesLease(sandbox, scope.providerLeaseId);
} catch (error) {
entries.delete(key);
throw error;
}
// Refresh the live provider state if the handle may have been auto-stopped
// since we last confirmed it, so the cached `state` snapshot can't hide a
// provider-initiated stop from `ensureSandboxStarted`. A failed refresh
// means the handle is no longer trustworthy — evict and fail closed.
const thresholdMs = staleHandleRefreshThresholdMs(scope.config.autoStopInterval);
if (thresholdMs != null && handleFreshnessNow() - entry.verifiedAtMs >= thresholdMs) {
try {
await withLivenessTimeout("sandbox.refreshData", scope.config.livenessTimeoutMs, () =>
sandbox.refreshData(),
);
} catch (error) {
entries.delete(key);
throw error;
}
}
return sandbox;
}
// The warm handle cache holds no entry, so this lookup calls `client.get`.
// Report the cache decision now, before the single-flight populate.
options.onCacheDecision?.(false);
// Single-flight: the first miss stores the in-flight promise under the
// composite key so concurrent misses on the same lease share one `client.get`
// instead of double-fetching. The promise lives only under this key (C5).
const populate = (async () => {
const client = createDaytonaClient(scope.config);
const sandbox = await client.get(scope.providerLeaseId);
assertHandleMatchesLease(sandbox, scope.providerLeaseId);
return sandbox;
})();
const populated: SandboxHandleCacheEntry = { sandbox: populate, verifiedAtMs: handleFreshnessNow() };
entries.set(key, populated);
try {
const sandbox = await populate;
return sandbox;
} catch (error) {
// A rejected populate (NotFound, network, id mismatch) must never remain
// cached (C4/C5). Guard against clobbering a newer entry under the key.
if (entries.get(key) === populated) {
entries.delete(key);
}
throw error;
}
}
// Seed the cache with a handle the caller already holds (e.g. the fresh handle
// from `createSandbox` on a cold acquire), so the next `get` under the same
// scope reuses it instead of paying a real `client.get`. The seed must land
// under the exact composite key the reader uses, or the reader misses and the
// saved round trip is lost. Assert the handle belongs to the lease so a caller
// that builds a wrong scope fails loudly here instead of caching a foreign
// handle.
function seed(scope: SandboxScope, sandbox: Sandbox): void {
assertHandleMatchesLease(sandbox, scope.providerLeaseId);
entries.set(sandboxHandleCacheKey(scope), {
sandbox: Promise.resolve(sandbox),
verifiedAtMs: handleFreshnessNow(),
});
}
function clear(scope: SandboxScope): void {
entries.delete(sandboxHandleCacheKey(scope));
}
function reset(): void {
entries.clear();
}
// Resolve a cached sandbox by its provider lease id alone. The
// login pseudo-terminal open carries only the provider lease id, not the full
// scope, so this scans the cached handles for the one whose `sandbox.id`
// matches. The lease was cached on acquire in the same worker, so the scan is
// a hit for a live login lease. It returns null when no cached handle matches,
// so the caller fails closed.
async function findByProviderLeaseId(providerLeaseId: string): Promise<Sandbox | null> {
if (!providerLeaseId) return null;
for (const entry of entries.values()) {
let sandbox: Sandbox;
try {
sandbox = await entry.sandbox;
} catch {
continue;
}
if (sandbox.id === providerLeaseId) return sandbox;
}
return null;
}
return { get, seed, clear, reset, markFresh, findByProviderLeaseId };
})();
// Preview credentials can rotate without a sandbox restart, so they must not
// define endpoint generation. Daytona's lifecycle revision does: refreshData
// updates `updatedAt` after stop/start. When Daytona does not expose a
// lifecycle revision, the in-memory generation remains stable for the worker.
const runnerIngressGenerationStore = (() => {
const entries = new Map<
string,
{ revision: string | null; generation: string }
>();
function get(sandbox: Sandbox): string {
const revision = sandbox.updatedAt ?? sandbox.createdAt ?? null;
const current = entries.get(sandbox.id);
if (current && current.revision === revision) return current.generation;
const generation = createHash("sha256")
.update(`${sandbox.id}\0${revision ?? randomUUID()}`)
.digest("hex");
entries.set(sandbox.id, { revision, generation });
return generation;
}
function reset(): void {
entries.clear();
}
return { get, reset };
})();
// Advisory writable-set store. It holds, per lease scope, the sandbox
// directories that a sync operation declared read-write (`access: "rw"`). The
// store is advisory and best-effort in-memory state: it adds no security (the
// ephemeral sandbox stays the only boundary). The store is keyed the same way
// as `sandboxHandleCache`, by `sandboxHandleCacheKey(scope)`.
//
// The command path no longer reads this set. The provider dropped the advisory
// `bwrap` wrapper that once bound these directories read-write for real-time
// feedback (see `DIRECTORY-CONSTRAINT-FINDINGS.md`). The store still records the
// read-write set, so a future isolation wrapper for the session can consume it
// without a new sync change.
const sandboxHandleWritableDirs = (() => {
const dirsByKey = new Map<string, Set<string>>();
// Record the read-write destination directory of every `access: "rw"`
// mapping. Skip read-only mappings (`access` absent or `"ro"`). Read-only is
// the safe default for an advisory signal.
//
// A workspace, git-history, or asset mapping uploads a tar archive, so its
// `targetPath` is the staging archive under the runtime root, not the directory
// that the post-upload extract command fills. For those mappings the author
// sets `writablePath` to the final destination directory, so this records the
// real read-write destination, not the staging parent. When `writablePath` is
// absent the mapping writes `targetPath` in place, so the parent directory of
// `targetPath` is the destination.
function recordWritableTargets(scope: SandboxScope, operations: PluginSyncOperation[]): void {
const key = sandboxHandleCacheKey(scope);
for (const operation of operations) {
for (const mapping of operation.files) {
if (mapping.access !== "rw") continue;
let dirs = dirsByKey.get(key);
if (!dirs) {
dirs = new Set<string>();
dirsByKey.set(key, dirs);
}
dirs.add(mapping.writablePath ?? path.posix.dirname(mapping.targetPath));
}
}
}
function get(scope: SandboxScope): ReadonlySet<string> {
return dirsByKey.get(sandboxHandleCacheKey(scope)) ?? new Set<string>();
}
function reset(): void {
dirsByKey.clear();
}
return { recordWritableTargets, get, reset };
})();
// Per-lease Daytona session-id store. It holds, per lease scope, the id of the
// one persistent session the exec hook opened for that lease. The store is
// keyed the same way as `sandboxHandleCache`, by `sandboxHandleCacheKey(scope)`.
// The exec hook creates one session on a cache miss and records its id here. The
// teardown hooks delete the session and clear the id. A resume clears the id,
// because a restarted sandbox loses its session shell, so the next exec must
// open a fresh session. The store is process-memory only; it holds an id string,
// never a handle, a credential, or a command.
const sandboxHandleSessionStore = (() => {
const idByKey = new Map<string, string>();
// In-flight session creates, keyed the same way as `idByKey`. A create records
// its promise here for the time it runs, then removes it. The map lets two
// overlapping first commands for one lease share one create. See `runSingle`.
const pendingByKey = new Map<string, Promise<string>>();
function get(scope: SandboxScope): string | undefined {
return idByKey.get(sandboxHandleCacheKey(scope));
}
function set(scope: SandboxScope, sessionId: string): void {
idByKey.set(sandboxHandleCacheKey(scope), sessionId);
}
function clear(scope: SandboxScope): void {
idByKey.delete(sandboxHandleCacheKey(scope));
}
// Single-flight guard for the first-command session create. Two overlapping
// first commands for one lease must open at most one live session. The first
// caller runs `create` and records its in-flight promise; every concurrent
// caller awaits the same promise instead of a second `create`. The store keeps
// the promise only while `create` runs, then removes it, so a later command
// (for example, after a resume clears the id) can open a fresh session. A
// failed `create` removes the promise too, so the next command retries.
function runSingle(scope: SandboxScope, create: () => Promise<string>): Promise<string> {
const key = sandboxHandleCacheKey(scope);
const inFlight = pendingByKey.get(key);
if (inFlight) return inFlight;
const promise = create();
pendingByKey.set(key, promise);
const settle = (): void => {
pendingByKey.delete(key);
};
promise.then(settle, settle);
return promise;
}
function reset(): void {
idByKey.clear();
pendingByKey.clear();
}
return { get, set, clear, runSingle, reset };
})();
/**
* Test seam: clear the process-scoped handle cache between tests so a handle
* memoized under a reused composite key in one test never leaks into the next.
* Not used in production.
*/
export function __resetDaytonaSandboxHandleCacheForTest(): void {
idleActivity.resetForTest();
sandboxHandleCache.reset();
sandboxHandleTeardownGates.reset();
sandboxHandleActivityGates.reset();
sandboxHandleLeaseAdmissionStates.reset();
sandboxHandleWritableDirs.reset();
sandboxHandleSessionStore.reset();
runnerIngressGenerationStore.reset();
}
/**
* Test seam: read the advisory writable directories recorded for a sync scope.
* The caller passes the same `onEnvironmentSyncIn` inputs, so this rebuilds the
* exact scope key the hook used. Not used in production.
*/
export function __getDaytonaWritableDirsForTest(input: {
driverKey: string;
companyId: string;
environmentId: string;
lease: { providerLeaseId?: string | null };
config: Record<string, unknown>;
}): string[] {
const scope: SandboxScope = {
driverKey: input.driverKey,
companyId: input.companyId,
environmentId: input.environmentId,
providerLeaseId: input.lease.providerLeaseId ?? "",
config: parseDriverConfig(input.config),
};
return [...sandboxHandleWritableDirs.get(scope)];
}
async function getSandbox(scope: SandboxScope, options: SandboxLookupOptions = {}): Promise<Sandbox> {
return await sandboxHandleCache.get(scope, options);
}
async function getSandboxOrNull(scope: SandboxScope, options: SandboxLookupOptions = {}): Promise<Sandbox | null> {
const proof = idleActivity.proof(sandboxHandleCacheKey(scope));
try {
return await getSandbox(scope, options);
} catch (error) {
if (error instanceof DaytonaNotFoundError) {
idleActivity.confirm(proof, true);
return null;
}
throw error;
}
}
function evictSandboxHandle(scope: SandboxScope): void {
sandboxHandleCache.clear(scope);
}
// Return the persistent session id for a lease, and open one session on a cache
// miss. The exec hook calls this once per command. The first call opens the
// session through `createSession` and records its id; every later call returns
// the stored id, so one lease runs every command in one persistent shell. The
// provider never falls back to a one-shot command to open a session.
//
// Leak bound: the Daytona SDK exposes NO per-session TTL. `createSession` takes
// only a session id, and there is no session update or expiry field. Two
// backstops bound the session against a leak. First, `teardownSession` runs a
// guaranteed `deleteSession` in every teardown hook's `try/finally`. Second, the
// sandbox-level `autoStopInterval` (15 minutes idle by default) stops the
// sandbox and, with it, every session; the `autoArchiveInterval` and
// `autoDeleteInterval` intervals then reap the sandbox. A session is a shell
// inside its sandbox and cannot outlive it.
async function getOrCreateSession(sandbox: Sandbox, scope: SandboxScope): Promise<string> {
const existing = sandboxHandleSessionStore.get(scope);
if (existing) return existing;
// Single-flight the first-command create. Two overlapping first commands for
// one lease share one create promise, so the lease opens at most one live
// session. The guard checks and starts the create in one synchronous step, so
// no second command can slip in between the store read and the create start.
return sandboxHandleSessionStore.runSingle(scope, async () => {
const sessionId = `paperclip-${randomUUID()}`;
// Wrap the session create in a short `session.open` provider span. The span
// carries no session id and no command text, only the provider family. The
// host maps the name to `sandbox.daytona.session.open`.
// `session.open` span: create the one persistent Daytona session for a lease,
// on the first in-run command — `sandbox.process.createSession`.
await withProviderSpan({
name: "session.open",
run: () => sandbox.process.createSession(sessionId),
});
sandboxHandleSessionStore.set(scope, sessionId);
return sessionId;
});
}
// Delete the persistent session for a lease and clear its stored id. Each
// teardown hook calls this inside its `try/finally`, so a failed delete never
// skips the rest of teardown. A failed delete logs the session id and the error
// loudly and does not throw past teardown; the sandbox stop or delete that
// follows removes the session shell anyway, and the sandbox-level
// `autoStopInterval` / `autoDeleteInterval` / `autoArchiveInterval` backstops
// bound any residual state (the session API exposes no per-session TTL). The
// store id is always cleared, so no orphan id survives.
async function teardownSession(sandbox: Sandbox, scope: SandboxScope): Promise<void> {
const sessionId = sandboxHandleSessionStore.get(scope);
if (!sessionId) return;
// Retire the captured identity before awaiting the provider. A late response
// must not clear a new session created after this lease is resumed.
sandboxHandleSessionStore.clear(scope);
try {
// Wrap the session delete in a short `session.close` provider span. The
// host maps the name to `sandbox.daytona.session.close`.
// `session.close` span: delete that persistent session on lease release —
// `sandbox.process.deleteSession`.
await withProviderSpan({
name: "session.close",
run: () => sandbox.process.deleteSession(sessionId),
});
} catch (error) {
console.error(
`Failed to delete Daytona session ${sessionId} during teardown: ${formatErrorMessage(error)}`,
);
}
}
// One-shot command execution via Daytona's `process.executeCommand`. This is the
// fallback path the exec hook uses when the session model is off. The command
// runs plain as the unprivileged sandbox user; the provider no longer wraps a
// user command with the advisory `bwrap` wrapper on any path.
//
// `executeCommand` returns combined stdout+stderr in `result`. We surface that
// as `stdout` and leave `stderr` empty; callers that grep for error messages
// still see them in `stdout`.
async function executeOneShot(
sandbox: Sandbox,
params: PluginEnvironmentExecuteParams,
config: DaytonaDriverConfig,
): Promise<PluginEnvironmentExecuteResult> {
const gitNet = isGitNetworkCommand(params.command, params.args ?? []);
const timeoutMs = resolveTimeoutMs(params.timeoutMs, config);
const effectiveTimeoutMs = gitNet ? Math.min(timeoutMs, GIT_NETWORK_TIMEOUT_MS) : timeoutMs;
const timeoutSeconds = toTimeoutSeconds(effectiveTimeoutMs);
const stdinPath = params.stdin != null ? `/tmp/paperclip-stdin-${randomUUID()}` : null;
// Marks the start of the `executeCommand` REST round-trip. Hoisted out of the
// try so the timeout path below can still attribute the exec wall-time it spent
// before the SDK aborted — a slow failed exec is exactly what we want to
// measure. Stays null until we are about to call `executeCommand`, so a timeout
// during the earlier `uploadFile` step honestly reports no `durationMs`.
let execStart: number | null = null;
try {
if (stdinPath) {
await sandbox.fs.uploadFile(Buffer.from(params.stdin ?? "", "utf8"), stdinPath, timeoutSeconds);
}
// Run the plain login-shell script as the unprivileged sandbox user. The
// provider no longer wraps a user command with the advisory `bwrap` wrapper.
const command = buildLoginShellScript({
command: params.command,
args: params.args ?? [],
cwd: params.cwd,
env: params.env,
stdinPath: stdinPath ?? undefined,
});
// Pass cwd undefined: `buildLoginShellScript` already injects the `cd` after
// it sources the login profiles, when params.cwd is set. The Daytona
// executor's own cwd argument runs before that profile sourcing, which is
// the wrong order (a profile could reset the caller env).
// Time only the `executeCommand` REST round-trip so the caller can
// attribute a step's exec time to the provider boundary through the
// free-form `metadata.durationMs`.
execStart = timingNow();
const result = await sandbox.process.executeCommand(command, undefined, undefined, timeoutSeconds);
const durationMs = timingNow() - execStart;
return {
exitCode: typeof result.exitCode === "number" ? result.exitCode : 1,
timedOut: false,
stdout: result.result ?? result.artifacts?.stdout ?? "",
stderr: "",
metadata: { durationMs },
};
} catch (error) {
if (error instanceof DaytonaTimeoutError) {
const timeoutMessage = gitNet
? `Git network operation timed out after ${Math.round(effectiveTimeoutMs / 1000)} s — the remote may be unreachable or noninteractive credentials are not configured.`
: error.message.trim();
// Preserve provider-boundary exec attribution on the timeout path: if the
// SDK aborted the `executeCommand` call itself, report how long it ran
// before timing out so slow failed startup exec is attributed to the
// provider, not silently dropped.
const durationMs = execStart != null ? timingNow() - execStart : undefined;
return {
exitCode: null,
timedOut: true,
stdout: "",
stderr: `${timeoutMessage}\n`,
...(durationMs != null ? { metadata: { durationMs } } : {}),
};
}
throw error;
} finally {
if (stdinPath) {
await sandbox.fs.deleteFile(stdinPath).catch(() => undefined);
}
}
}
// Fallback reads full log snapshots as well as status. Limit the heavier
// polling path while keeping output available to interactive commands.
const SESSION_LOG_POLL_INTERVAL_MS = 1000;
const SESSION_INITIAL_STATUS_TIMEOUT_MS = 500;
// A socket can stay open after it stops delivering output. Switch to saved
// logs after this much silence; silence never proves that the command exited.
const SESSION_LOG_STREAM_IDLE_MS = 15_000;
function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
// Backoff delays for the exit-code read after the log stream ends. The live
// spike measured the exit code available within one poll (91-202 ms), so the
// first read almost always holds the code. These delays cover the rare case
// where the first read has no code yet.
const SESSION_EXIT_CODE_RETRY_DELAYS_MS = [50, 100, 200];
// A bounded reconnect for the log stream. The SDK resolves on WebSocket close,
// which does not prove that the command exited. A reconnect replays the log
// from byte 0; the stream buffer drops the replayed prefix by byte offset.
// After this many reconnects the dispatch falls back to
// the poll path.
const MAX_SESSION_STREAM_RECONNECTS = 1;
// Buffers the stdout and stderr of one session command from the callback log
// stream, and drops a replayed prefix by byte offset.
//
// The Daytona callback stream replays the whole log from byte 0 after a
// reconnect (it does not resume from an offset and does not omit earlier
// bytes). So the buffer tracks the byte count it already holds per stream and
// drops any replayed bytes that fall before that count. The dedupe runs at the
// byte level, because Daytona replays the log byte-for-byte. The SDK keeps each
// multibyte UTF-8 character whole per chunk and per stream, so the delivered
// byte count always lands on a character boundary and the byte-offset split is
// safe.
//
// The buffer stores each new tail as a separate chunk and joins the chunks one
// time at read. It does not copy the earlier output on each append, so total
// buffering work stays linear in the output size, not quadratic.
function createSessionStreamBuffer(
onNewTail?: (stream: "stdout" | "stderr", text: string) => void,
) {
type Stream = {
chunks: Buffer[];
length: number;
connectionBytes: number;
pendingReplacement: string;
previousReplacement: { offset: number; text: string } | null;
};
const createStream = (): Stream => ({
chunks: [], length: 0, connectionBytes: 0, pendingReplacement: "", previousReplacement: null,
});
const streams = {
stdout: createStream(),
stderr: createStream(),
};
function append(
streamName: "stdout" | "stderr",
stream: Stream,
chunk: string,
final = false,
publish = true,
): void {
// The SDK flushes an incomplete UTF-8 character as U+FFFD on socket close.
// Do not publish that suffix or count its replacement bytes until a replay
// confirms it. A real final U+FFFD is flushed at confirmed command exit.
const text = stream.pendingReplacement + chunk;
stream.pendingReplacement = final ? "" : (text.match(/\uFFFD+$/u)?.[0] ?? "");
const buf = Buffer.from(text.slice(0, text.length - stream.pendingReplacement.length), "utf8");
const start = stream.connectionBytes;
stream.connectionBytes = start + buf.length;
if (stream.previousReplacement && stream.connectionBytes > stream.previousReplacement.offset) {
stream.previousReplacement = null;
}
// The whole chunk falls before the delivered byte count, so it is a replay.
if (start + buf.length <= stream.length) {
return;
}
// Keep only the new tail. When the whole chunk is new, `start >=
// stream.length` and the tail is the whole chunk. When the chunk straddles
// the delivered byte count, the tail starts after the replayed prefix.
const tail = start >= stream.length ? buf : buf.subarray(stream.length - start);
stream.chunks.push(tail);
stream.length += tail.length;
// Deliver only the genuinely new tail to the live sink, so a replayed
// prefix on a reconnect never reaches the host twice.
if (publish && onNewTail && tail.length > 0) {
onNewTail(streamName, tail.toString("utf8"));
}
}
return {
onStdout: (chunk: string) => append("stdout", streams.stdout, chunk),
onStderr: (chunk: string) => append("stderr", streams.stderr, chunk),
// Reset the per-connection read cursors after a reconnect, so the replayed
// prefix drops against the already-delivered byte count.
resetConnectionCursors(): void {
for (const stream of Object.values(streams)) {
if (stream.pendingReplacement &&
(!stream.previousReplacement || stream.connectionBytes > stream.previousReplacement.offset ||
(stream.connectionBytes === stream.previousReplacement.offset &&
stream.pendingReplacement.length > stream.previousReplacement.text.length))) {
stream.previousReplacement = { offset: stream.connectionBytes, text: stream.pendingReplacement };
}
stream.pendingReplacement = "";
stream.connectionBytes = 0;
}
},
finish(publish = true): void {
for (const name of ["stdout", "stderr"] as const) {
const stream = streams[name];
if (stream.previousReplacement?.offset === stream.connectionBytes &&
stream.previousReplacement.text.length > stream.pendingReplacement.length) {
stream.pendingReplacement = stream.previousReplacement.text;
}
append(name, stream, "", true, publish);
// A short terminal snapshot must not discard a genuine trailing
// replacement character already received from a longer stream.
const previous = stream.previousReplacement;
if (previous && previous.offset >= stream.length) {
stream.connectionBytes = previous.offset;
append(name, stream, previous.text, true, publish);
}
stream.previousReplacement = null;
}
},
get stdout(): string {
return Buffer.concat(streams.stdout.chunks).toString("utf8");
},
get stderr(): string {
return Buffer.concat(streams.stderr.chunks).toString("utf8");
},
};
}
type SessionLogStreamResult = {
exitCode: number | null;
pollUntilExit: boolean;
buffer: ReturnType<typeof createSessionStreamBuffer>;
};
class SessionCommandDeadlineError extends Error {}
class SessionObservationTimeoutError extends Error {}
function createCommandDeadline(timeoutMs: number | undefined) {
if (timeoutMs === undefined || timeoutMs === 0) return undefined;
if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 2_147_483_647) {
throw new Error("Invalid session command timeout");
}
let expired = false;
const dueAt = Date.now() + timeoutMs;
const controller = new AbortController();
const timer = setTimeout(() => {
expired = true;
controller.abort();
}, timeoutMs);
return {
expired: () => expired,
remainingMs: () => Math.max(0, dueAt - Date.now()),
race: async <T>(action: () => Promise<T>): Promise<T> => {
if (expired) throw new SessionCommandDeadlineError();
let rejectDeadline!: (error: SessionCommandDeadlineError) => void;
const deadline = new Promise<never>((_resolve, reject) => { rejectDeadline = reject; });
const onAbort = () => rejectDeadline(new SessionCommandDeadlineError());
controller.signal.addEventListener("abort", onAbort, { once: true });
try {
return await Promise.race([action(), deadline]);
} finally {
// Retain only active observations. A shared pending promise would keep
// every finished poll and its result until a long command ends.
controller.signal.removeEventListener("abort", onAbort);
}
},
clear: () => clearTimeout(timer),
};
}
type CommandDeadline = ReturnType<typeof createCommandDeadline>;
function withinCommandDeadline<T>(deadline: CommandDeadline, action: () => Promise<T>): Promise<T> {
return deadline ? deadline.race(() => idleActivity.track(action)) : idleActivity.track(action);
}
async function sleepWithinCommandDeadline(deadline: CommandDeadline, delayMs: number): Promise<void> {
if (!deadline) return await sleep(delayMs);
let timer: ReturnType<typeof setTimeout> | undefined;
try {
await deadline.race(() => new Promise<void>((resolve) => { timer = setTimeout(resolve, delayMs); }));
} finally {
if (timer !== undefined) clearTimeout(timer);
}
}
async function beforeSessionDeadline<T>(deadlineMs: number, action: () => Promise<T>): Promise<T> {
const remainingMs = deadlineMs - Date.now();
if (remainingMs <= 0) throw new SessionCommandDeadlineError();
let timer: ReturnType<typeof setTimeout> | undefined;
try {
return await Promise.race([
idleActivity.track(action),
new Promise<never>((_resolve, reject) => {
timer = setTimeout(() => reject(new SessionCommandDeadlineError()), remainingMs);
}),
]);
} finally {
if (timer !== undefined) clearTimeout(timer);
}
}
// A provider operation timeout bounds one observation. An explicit command
// deadline also bounds the stream; existing callers retain their run/Stop guard.
async function observeSessionCommand<T>(timeoutMs: number, action: () => Promise<T>, commandDeadline?: CommandDeadline): Promise<T> {
try {
// Use the earlier shared command timer instead of leaving a longer
// observation timer alive after the command has already settled.
if (commandDeadline && commandDeadline.remainingMs() <= timeoutMs) {
return await commandDeadline.race(() => idleActivity.track(action));
}
return await beforeSessionDeadline(Date.now() + timeoutMs, action);
} catch (error) {
if (commandDeadline?.expired()) throw new SessionCommandDeadlineError();
if (error instanceof SessionCommandDeadlineError || error instanceof DaytonaTimeoutError) {
throw new SessionObservationTimeoutError();
}
throw error;
}
}
// Stream stdout and stderr of one session command from the callback log form.
// The stream buffer drops a replayed prefix by byte offset on a reconnect.
// Rejected streams and clean closes use bounded reconnects, then polling.
// An idle socket goes directly to polling, including one that never settles.
async function runSessionLogStream(
sandbox: Sandbox,
sessionId: string,
commandId: string,
timeoutMs: number,
buffer: ReturnType<typeof createSessionStreamBuffer>,
commandDeadline?: CommandDeadline,
): Promise<SessionLogStreamResult> {
let reconnects = 0;
let pollUntilExit = false;
while (true) {
let streamClosed = false;
let acceptingOutput = true;
let exitObservation: ReturnType<typeof observeSessionStreamExit> | undefined;
let idleTimer: ReturnType<typeof setTimeout> | undefined;
let signalIdle!: () => void;
const idle = new Promise<"idle">((resolve) => { signalIdle = () => resolve("idle"); });
const armIdleTimer = () => {
clearTimeout(idleTimer);
idleTimer = setTimeout(signalIdle, SESSION_LOG_STREAM_IDLE_MS);
};
const receive = (stream: "stdout" | "stderr", chunk: string) => {
if (!acceptingOutput || commandDeadline?.expired() || !chunk) return;
armIdleTimer();
if (stream === "stdout") buffer.onStdout(chunk);
else buffer.onStderr(chunk);
};
try {
armIdleTimer();
const observed = await withinCommandDeadline(commandDeadline, () => {
exitObservation = observeSessionStreamExit(Promise.race([
idleActivity.track(() => sandbox.process.getSessionCommandLogs(
sessionId,
commandId,
(chunk) => receive("stdout", chunk),
(chunk) => receive("stderr", chunk),
)).then(() => "closed" as const),
idle,
]), async () => {
const status = await observeSessionCommand(Math.min(timeoutMs, SESSION_INITIAL_STATUS_TIMEOUT_MS),
() => sandbox.process.getSessionCommand(sessionId, commandId), commandDeadline);
return typeof status.exitCode === "number" ? status.exitCode : null;
});
return exitObservation.result;
});
if (observed.kind === "exit") return { exitCode: observed.exitCode, pollUntilExit: false, buffer };
const outcome = observed.value;
if (outcome === "idle") {
// Do not wait for the abandoned socket or open another one. The SDK
// exposes no cancellation handle. Fence its callbacks before the
// snapshot path resets the buffer's byte cursors.
return { exitCode: null, pollUntilExit: true, buffer };
}
streamClosed = true;
pollUntilExit = true;
} catch (error) {
if (error instanceof SessionCommandDeadlineError) throw error;
// The command can still be running after a log transport failure.
} finally {
// The SDK exposes no cancellation handle for this socket. Session
// teardown owns closing it; late data cannot change a settled execution.
acceptingOutput = false;
exitObservation?.stop();
clearTimeout(idleTimer);
}
if (streamClosed) {
const exitCode = await readSessionExitCode(sandbox, sessionId, commandId, timeoutMs, commandDeadline);
if (exitCode !== null) return { exitCode, pollUntilExit, buffer };
}
if (reconnects >= MAX_SESSION_STREAM_RECONNECTS) {
return { exitCode: null, pollUntilExit, buffer };
}
reconnects += 1;
buffer.resetConnectionCursors();
}
}
// Read the exit code one time after the log stream ends. The exit code is
// available within one poll, so the first read almost always holds it. Add a
// small bounded retry with backoff only for the rare case where the first read
// has no code yet. Return null when no read holds a numeric code.
async function readSessionExitCode(
sandbox: Sandbox,
sessionId: string,
commandId: string,
timeoutMs: number,
commandDeadline?: CommandDeadline,
): Promise<number | null> {
const first = await observeSessionCommand(timeoutMs, () => sandbox.process.getSessionCommand(sessionId, commandId), commandDeadline);
if (typeof first.exitCode === "number") {
return first.exitCode;
}
for (const delayMs of SESSION_EXIT_CODE_RETRY_DELAYS_MS) {
await sleepWithinCommandDeadline(commandDeadline, delayMs);
const status = await observeSessionCommand(timeoutMs, () => sandbox.process.getSessionCommand(sessionId, commandId), commandDeadline);
if (typeof status.exitCode === "number") {
return status.exitCode;
}
}
return null;
}
// Dispatch one user command into the persistent session and return its true
// stdout and stderr.
//
// The Daytona session is one persistent shell. A top-level `exit N` inside a
// session command ends that shell, so the next command then fails with "session
// process has exited". To stop a user `exit` from reaching the session shell,
// the dispatch wraps the whole login-shell script in a subshell `( ... )`. A
// user `exit` then ends only the subshell and reports its exit code, and the
// session shell stays alive. The provider passes the caller cwd and env inside
// the login-shell script on every command, so it never relies on implicit state
// that leaks between commands.
//
// The SDK exposes no built-in wait for a session command, so the dispatch runs
// the command with `runAsync: true` and polls `getSessionCommand` until the exit
// code is set. It then reads true `stdout` and `stderr` from
// `getSessionCommandLogs`, because the synchronous response fields are optional.
// The `runAsync: true` path also avoids the known `runAsync: false` login-shell
// hang.
async function executeInSession(
sandbox: Sandbox,
sessionId: string,
params: PluginEnvironmentExecuteParams,
config: DaytonaDriverConfig,
): Promise<PluginEnvironmentExecuteResult> {
const gitNet = isGitNetworkCommand(params.command, params.args ?? []);
const timeoutMs = resolveTimeoutMs(params.timeoutMs, config);
const effectiveTimeoutMs = gitNet ? Math.min(timeoutMs, GIT_NETWORK_TIMEOUT_MS) : timeoutMs;
const timeoutSeconds = toTimeoutSeconds(effectiveTimeoutMs);
const stdinPath = params.stdin != null ? `/tmp/paperclip-stdin-${randomUUID()}` : null;
// Marks the start of the session dispatch and poll. The timeout paths report
// the exec wall-time spent before the abort, so a slow command is still
// attributed to the provider boundary.
let execStart: number | null = null;
let confirmedExitCode: number | null = null;
let commandDeadline: CommandDeadline;
const streamBuffer = createSessionStreamBuffer((stream, text) => pluginContext?.execution.log(stream, text));
try {
if (stdinPath) {
await sandbox.fs.uploadFile(Buffer.from(params.stdin ?? "", "utf8"), stdinPath, timeoutSeconds);
}
const loginScript = buildLoginShellScript({
command: params.command,
args: params.args ?? [],
cwd: params.cwd,
env: params.env,
stdinPath: stdinPath ?? undefined,
});
// Subshell wrap: a top-level `exit` in the user command exits only the
// subshell, not the persistent session shell.
const command = `( ${loginScript} )`;
execStart = timingNow();
commandDeadline = createCommandDeadline(params.commandTimeoutMs);
const dispatched = await withinCommandDeadline(commandDeadline, () => sandbox.process.executeSessionCommand(
sessionId,
{ command, runAsync: true },
timeoutSeconds,
));
const commandId = dispatched.cmdId;
let initialExitCode: number | null = null;
try {
const status = await observeSessionCommand(
Math.min(effectiveTimeoutMs, SESSION_INITIAL_STATUS_TIMEOUT_MS),
() => sandbox.process.getSessionCommand(sessionId, commandId),
commandDeadline,
);
if (typeof status.exitCode === "number") initialExitCode = status.exitCode;
} catch (error) {
if (error instanceof SessionCommandDeadlineError) throw error;
}
// Log-stream path. A session command always tries the stream first: it
// streams stdout and stderr from the callback log form, then reads the exit
// code. A log socket closing without a recorded exit leaves the command
// running, so reconnect and then poll the same command without replaying it.
//
// Emit each genuinely new output chunk to the host during the active execute
// call. The host routes it to the runner log sink by the host-issued
// invocation id. This is a no-op when no plugin context is set (a direct
// test call) or when the host has no active execute route.
const streamResult = initialExitCode !== null
? { exitCode: initialExitCode, pollUntilExit: false, buffer: streamBuffer }
: await runSessionLogStream(
sandbox,
sessionId,
commandId,
effectiveTimeoutMs,
streamBuffer,
commandDeadline,
);
if (streamResult.exitCode !== null) {
confirmedExitCode = streamResult.exitCode;
// A log socket can close before the process emits its final bytes. Even
// a now-visible exit code does not prove the streamed prefix is complete.
const logs = await observeSessionCommand(effectiveTimeoutMs, () => sandbox.process.getSessionCommandLogs(sessionId, commandId), commandDeadline);
streamBuffer.resetConnectionCursors();
streamBuffer.onStdout(logs?.stdout ?? "");
streamBuffer.onStderr(logs?.stderr ?? "");
streamBuffer.finish();
const durationMs = timingNow() - execStart;
return {
exitCode: streamResult.exitCode,
timedOut: false,
stdout: streamResult.buffer.stdout,
stderr: streamResult.buffer.stderr,
metadata: { durationMs },
};
}
// Keep forwarding output while waiting for the actual command exit. ACP
// peers may need a tool response before they can finish the command. Waiting
// for exit before reading logs would strand those peers after a stream loss.
// A closed or idle log socket does not end the command's lifetime. Bound
// each recovery read independently; the caller still owns stop/teardown.
// Preserve the legacy budget starting at fallback entry when both stream
// attempts fail, including a stream that fails after running for hours.
const deadlineMs = Date.now() + effectiveTimeoutMs;
const observe = async <T>(action: () => Promise<T>): Promise<T> => {
try {
return await (streamResult.pollUntilExit
? observeSessionCommand(effectiveTimeoutMs, action, commandDeadline)
: commandDeadline ? commandDeadline.race(action) : beforeSessionDeadline(deadlineMs, action));
} catch (error) {
if (error instanceof DaytonaTimeoutError) throw new SessionObservationTimeoutError();
throw error;
}
};
while (true) {
const status = await observe(() => sandbox.process.getSessionCommand(sessionId, commandId));
if (typeof status.exitCode === "number") confirmedExitCode = status.exitCode;
const logs = await observe(() => sandbox.process.getSessionCommandLogs(sessionId, commandId));
streamResult.buffer.resetConnectionCursors();
streamResult.buffer.onStdout(logs.stdout ?? "");
streamResult.buffer.onStderr(logs.stderr ?? "");
if (confirmedExitCode !== null) {
streamResult.buffer.finish();
const durationMs = timingNow() - execStart;
return {
exitCode: confirmedExitCode,
timedOut: false,
stdout: streamResult.buffer.stdout,
stderr: streamResult.buffer.stderr,
metadata: { durationMs },
};
}
// Full log snapshots are heavier than a status read. Limit fallback
// traffic to one snapshot per second. Failed-stream fallback retains
// its original deadline, including the time spent waiting between reads.
await sleepWithinCommandDeadline(commandDeadline, streamResult.pollUntilExit ? SESSION_LOG_POLL_INTERVAL_MS
: Math.max(0, Math.min(SESSION_LOG_POLL_INTERVAL_MS, deadlineMs - Date.now())));
}
} catch (error) {
if (error instanceof SessionObservationTimeoutError ||
(error instanceof SessionCommandDeadlineError && confirmedExitCode !== null)) {
// Preserve undecided decoder suffixes in the partial result, without
// injecting a possibly incomplete character into the live protocol.
streamBuffer.finish(false);
return {
exitCode: null,
timedOut: true,
stdout: streamBuffer.stdout,
stderr: `${streamBuffer.stderr}Session log observation timed out after ${Math.round((commandDeadline?.expired() ? params.commandTimeoutMs! : effectiveTimeoutMs) / 1000)} s; ${confirmedExitCode === null ? "command exit remains unconfirmed" : "final output may be incomplete"}.\n`,
metadata: {
...(execStart != null ? { durationMs: timingNow() - execStart } : {}),
timeoutScope: "session_log_observation",
commandExitConfirmed: confirmedExitCode !== null,
...(confirmedExitCode !== null ? { observedExitCode: confirmedExitCode } : {}),
},
};
}
if (error instanceof DaytonaTimeoutError || error instanceof SessionCommandDeadlineError) {
streamBuffer.finish(false);
const timeoutMessage = gitNet
? `Git network operation timed out after ${Math.round(effectiveTimeoutMs / 1000)} s — the remote may be unreachable or noninteractive credentials are not configured.`
: error instanceof SessionCommandDeadlineError
? `Command timed out after ${Math.round((commandDeadline?.expired() ? params.commandTimeoutMs! : effectiveTimeoutMs) / 1000)} s.`
: error.message.trim();
const durationMs = execStart != null ? timingNow() - execStart : undefined;
return {
exitCode: null,
timedOut: true,
stdout: streamBuffer.stdout,
stderr: `${streamBuffer.stderr}${timeoutMessage}\n`,
...(durationMs != null ? { metadata: { durationMs } } : {}),
};
}
throw error;
} finally {
commandDeadline?.clear();
if (stdinPath) {
await sandbox.fs.deleteFile(stdinPath).catch(() => undefined);
}
}
}
// The worker-side registry of live login pseudo-terminal sessions.
// The worker registers each terminal under the host-owned route identifier at
// create time, so the host closes the exact terminal by that identifier even
// when the open reply was lost. It also indexes by the worker session identifier
// for input and stop. The `onShutdown` hook closes every open session here.
interface DaytonaLoginPtyEntry {
hostRouteId: string;
workerSessionId: string;
session: LoginPtyWorkerSession;
}
const daytonaLoginPtyByRoute = new Map<string, DaytonaLoginPtyEntry>();
const daytonaLoginPtyBySession = new Map<string, DaytonaLoginPtyEntry>();
function forgetDaytonaLoginPty(entry: DaytonaLoginPtyEntry): void {
daytonaLoginPtyByRoute.delete(entry.hostRouteId);
daytonaLoginPtyBySession.delete(entry.workerSessionId);
}
// The worker-side registry of live duplex channels. The worker registers each
// channel under the host-owned route identifier at open time, so the host closes
// the exact channel by that identifier even when the open reply was lost. It also
// indexes by the worker session identifier for write and stop. Each entry records
// the provider lease id, so a lease teardown closes only its own channels. The
// `onShutdown` hook closes every open channel here.
interface DaytonaDuplexChannelEntry {
hostRouteId: string;
workerSessionId: string;
providerLeaseId: string;
session: DuplexChannelSession;
}
const daytonaDuplexChannelByRoute = new Map<string, DaytonaDuplexChannelEntry>();
const daytonaDuplexChannelBySession = new Map<string, DaytonaDuplexChannelEntry>();
function forgetDaytonaDuplexChannel(entry: DaytonaDuplexChannelEntry): void {
daytonaDuplexChannelByRoute.delete(entry.hostRouteId);
daytonaDuplexChannelBySession.delete(entry.workerSessionId);
}
// Close every open duplex channel that belongs to one provider lease and drop its
// entry. The lease teardown hooks (release, destroy, resume) call this, so a
// channel never outlives the sandbox that carries it. The close kills the child
// and releases the pseudo-terminal socket, so no live channel survives the
// teardown. The stored identifiers are always cleared, so no orphan id survives.
async function closeDaytonaDuplexChannelsForLease(providerLeaseId: string): Promise<void> {
const matches = [...daytonaDuplexChannelByRoute.values()].filter(
(entry) => entry.providerLeaseId === providerLeaseId,
);
for (const entry of matches) forgetDaytonaDuplexChannel(entry);
await Promise.allSettled(matches.map(entry => entry.session.close()));
}
async function stopLease(params: PluginEnvironmentReleaseLeaseParams): Promise<PluginEnvironmentTerminationReceipt> {
if (!params.providerLeaseId) throw new Error("Daytona stop requires an exact sandbox identity");
const config = parseDriverConfig(params.config);
const scope: SandboxScope = { driverKey: params.driverKey, companyId: params.companyId,
environmentId: params.environmentId, providerLeaseId: params.providerLeaseId, config };
const teardownGate = sandboxHandleTeardownGates.begin(scope);
sandboxHandleLeaseAdmissionStates.close(scope);
const cleanupProof = idleActivity.proof(sandboxHandleCacheKey(scope));
try {
const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
if (!sandbox) throw new Error("Daytona retained sandbox is unavailable");
evictSandboxHandle(scope);
// Provider auto-delete can destroy a stopped sandbox without an explicit
// delete call. Confirm the provider disabled it before stopping saved work;
// the SDK setter also updates a local field, which is not sufficient proof.
const deadline = Math.min(config.livenessTimeoutMs, 30_000);
await withLivenessTimeout("sandbox.setAutoDeleteInterval", deadline, () => sandbox.setAutoDeleteInterval(-1));
await withLivenessTimeout("sandbox.refreshData", deadline, () => sandbox.refreshData());
if (sandbox.autoDeleteInterval !== -1) throw new Error("Daytona retention policy was not confirmed");
// An archive already has no live process and retains its filesystem.
// Daytona rejects Stop in this state; leave the confirmed archive cold.
if (sandbox.state !== "stopped" && sandbox.state !== "archived") {
await terminateAtProvider(scope, "sandbox.stop", () => sandbox.stop(Math.min(toTimeoutSeconds(config.timeoutMs), 30)));
}
sandboxHandleSessionStore.clear(scope);
await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);
return confirmedTermination(scope, "stopped", cleanupProof);
} finally {
sandboxHandleTeardownGates.end(scope, teardownGate);
evictSandboxHandle(scope);
}
}
const plugin = definePlugin(trackDaytonaHooks({
async setup(ctx) {
// Hoist the context to a module variable so the lifecycle hooks and the
// file-sync helpers can read `ctx.tracer` — they have no closure over `ctx`.
pluginContext = ctx;
ctx.logger.info("Daytona sandbox provider plugin ready");
},
async onHealth() {
return { status: "ok", message: "Daytona sandbox provider plugin healthy" };
},
async onIdleDrain() {
return idleActivity.present() || daytonaLoginPtyByRoute.size > 0 || daytonaDuplexChannelByRoute.size > 0
? "present" : "none";
},
async onEnvironmentValidateConfig(
params: PluginEnvironmentValidateConfigParams,
): Promise<PluginEnvironmentValidationResult> {
const config = parseDriverConfig(params.config);
const errors: string[] = [];
if (typeof params.config.image === "string" && params.config.image.trim().length === 0) {
errors.push("Daytona image cannot be empty.");
}
if (typeof params.config.snapshot === "string" && params.config.snapshot.trim().length === 0) {
errors.push("Daytona snapshot cannot be empty.");
}
if (config.image && config.snapshot) {
errors.push("Daytona sandbox environments must set either image or snapshot, not both.");
}
if (config.apiUrl && !isValidUrl(config.apiUrl)) {
errors.push("apiUrl must be a valid URL.");
}
if (config.timeoutMs < 1 || config.timeoutMs > 86_400_000) {
errors.push("timeoutMs must be between 1 and 86400000.");
}
// A value of 0 or less disables the extra bound on purpose; reject only a
// value above the outer RPC ceiling, which would make the bound useless.
if (config.livenessTimeoutMs > 86_400_000) {
errors.push("livenessTimeoutMs must be less than or equal to 86400000.");
}
if (config.autoStopInterval != null && config.autoStopInterval < 0) {
errors.push("autoStopInterval must be greater than or equal to 0.");
}
if (config.autoArchiveInterval != null && config.autoArchiveInterval < 0) {
errors.push("autoArchiveInterval must be greater than or equal to 0.");
}
if (config.autoDeleteInterval != null && config.autoDeleteInterval < -1) {
errors.push("autoDeleteInterval must be greater than or equal to -1.");
}
if (!config.apiKey && !(process.env.DAYTONA_API_KEY?.trim())) {
errors.push("Daytona sandbox environments require an API key in config or DAYTONA_API_KEY.");
}
const resourceRequestError = validateResourceRequest(config);
if (resourceRequestError) {
errors.push(resourceRequestError);
}
for (const [key, value] of Object.entries({
cpu: config.cpu,
memory: config.memory,
disk: config.disk,
gpu: config.gpu,
})) {
if (value != null && value <= 0) {
errors.push(`${key} must be greater than 0 when provided.`);
}
}
if (errors.length > 0) {
return { ok: false, errors };
}
return {
ok: true,
normalizedConfig: { ...config },
};
},
async onEnvironmentProbe(
params: PluginEnvironmentProbeParams,
): Promise<PluginEnvironmentProbeResult> {
const config = parseDriverConfig(params.config);
try {
const sandbox = await createSandbox(params, config);
try {
const remoteCwd = await resolveSandboxWorkingDirectory(sandbox);
const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(config.timeoutMs));
return {
ok: true,
summary: `Connected to Daytona sandbox ${sandbox.name}.`,
metadata: {
provider: "daytona",
shellCommand,
sandboxId: sandbox.id,
sandboxName: sandbox.name,
target: sandbox.target,
image: config.image,
snapshot: config.snapshot,
timeoutMs: config.timeoutMs,
reuseLease: config.reuseLease,
remoteCwd,
},
};
} finally {
const proof = idleActivity.proof(providerActivityKey(params, config, sandbox.id));
await sandbox.delete(toTimeoutSeconds(config.timeoutMs), true).then(
() => idleActivity.confirm(proof),
() => undefined,
);
}
} catch (error) {
return {
ok: false,
summary: "Daytona sandbox probe failed.",
metadata: {
provider: "daytona",
image: config.image,
snapshot: config.snapshot,
timeoutMs: config.timeoutMs,
reuseLease: config.reuseLease,
error: formatErrorMessage(error),
},
};
}
},
async onEnvironmentAcquireLease(
params: PluginEnvironmentAcquireLeaseParams,
): Promise<PluginEnvironmentLease> {
const config = parseDriverConfig(params.config);
let snapshotIdentity: SnapshotIdentity | undefined;
// One budget covers creation, setup, and inline cleanup. The host leaves
// 30 seconds beyond this deadline to receive/journal the cleanup record.
const budgetMs = config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_DAYTONA_OPERATION_TIMEOUT_MS;
const startedAt = Date.now();
const deadline = startedAt + budgetMs;
let expired = false;
let phase: PluginEnvironmentAcquisitionDiagnostic["phase"] = "create";
let cleanupInProgress = false;
let firstFailure: PluginEnvironmentAcquisitionDiagnostic | undefined;
const observeFailure = (): PluginEnvironmentAcquisitionDiagnostic => {
// Cleanup may consume the rest of the budget. Keep the original failed
// step and time, rather than attributing that failure to its cleanup.
return firstFailure ??= {
phase,
elapsedMs: Math.max(0, Math.min(604_800_000, Date.now() - startedAt)),
budgetMs,
};
};
let cleanup: PluginEnvironmentCreationCleanup | undefined;
const timeoutFailure = () => {
const diagnostic = observeFailure();
expired = true;
const cause = new Error(`Daytona lease acquisition exceeded ${budgetMs} ms during ${cleanupInProgress ? "cleanup" : phase}`);
return cleanup
? new PluginEnvironmentCreationCleanupError([cause],
"Daytona lease acquisition timed out; allocation cleanup is pending",
{ ...cleanup, labels: { ...cleanup.labels } }, diagnostic)
: cause;
};
const assertActive = () => {
if (expired || Date.now() >= deadline) throw timeoutFailure();
};
const deadlineFailure = async () => {
// Only a create that has neither resolved nor rejected is still pending.
const createPending = phase === "create" && firstFailure === undefined ? cleanup : undefined;
const diagnostic = observeFailure();
// Stop late setup before the lookup, so a late create cannot be admitted.
expired = true;
if (createPending) diagnostic.providerState = await observeCreateState(config, createPending);
return timeoutFailure();
};
const acquire = async (): Promise<PluginEnvironmentLease> => {
const sandbox = await createSandbox(params, config, {
onCreateAttempt: (attempt) => { assertActive(); cleanup = attempt; },
onCreateFailure: observeFailure,
onSnapshotIdentity: identity => { snapshotIdentity = identity; },
});
try {
assertActive();
if (cleanup) cleanup.observedProviderLeaseId = sandbox.id;
phase = "workspace";
const remoteCwd = await resolveSandboxWorkingDirectory(sandbox);
assertActive();
phase = "shell";
const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(Math.max(1, deadline - Date.now())));
assertActive();
// Configure a provider-side destroy time at or before a caller deadline, so
// an abandoned sandbox self-destroys even if Paperclip is down. The lease
// carries the real provider expiry (or none) as evidence of the bound.
phase = "expiry";
const expiresAt = await configureSandboxExpiry({
sandbox,
requestedExpiresAt: params.requestedExpiresAt,
nowMs: Date.now(),
});
assertActive();
phase = "sentinel";
const workspaceSentinel = await writeWorkspaceSentinel({
sandbox,
remoteCwd,
params,
config,
timeoutSeconds: toTimeoutSeconds(Math.max(1, deadline - Date.now())),
});
assertActive();
sandboxHandleLeaseAdmissionStates.open({
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: sandbox.id,
config,
});
// Seed the handle cache with the fresh handle under the exact scope that
// `onEnvironmentRealizeWorkspace` reads (providerLeaseId === sandbox.id).
// Realize then reuses this handle instead of paying a real `client.get`.
sandboxHandleCache.seed(
{
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: sandbox.id,
config,
},
sandbox,
);
return {
providerLeaseId: sandbox.id,
expiresAt,
metadata: leaseMetadata({
config,
sandbox,
shellCommand,
remoteCwd,
resumedLease: false,
workspaceSentinel,
snapshotIdentity,
}),
};
} catch (error) {
const diagnostic = observeFailure();
// After timeout the host owns the durable cleanup record. A late SDK
// completion must not admit this lease or start another setup phase.
if (!expired) {
cleanupInProgress = true;
try {
const proof = idleActivity.proof(providerActivityKey(params, config, sandbox.id));
await sandbox.delete(toTimeoutSeconds(Math.max(1, deadline - Date.now())), true);
idleActivity.confirm(proof);
} catch (cleanupError) {
if (cleanup) {
throw new PluginEnvironmentCreationCleanupError([error, cleanupError],
"Daytona lease setup failed; allocation cleanup is pending",
{ ...cleanup, labels: { ...cleanup.labels } }, diagnostic);
}
throw error;
}
}
throw error;
}
};
let timer: ReturnType<typeof setTimeout> | undefined;
let timedOut = false;
try {
return await Promise.race([
// After the deadline only the timer settles the call: a late create
// rejection cannot replace the timeout's ownership and observation.
idleActivity.track(acquire).catch((error: unknown) => timedOut ? new Promise<never>(() => undefined) : Promise.reject(error)),
new Promise<never>((_resolve, reject) => {
timer = setTimeout(() => { timedOut = true; void deadlineFailure().then(reject); }, budgetMs);
}),
]);
} finally {
clearTimeout(timer);
}
},
async onEnvironmentResumeLease(
params: PluginEnvironmentResumeLeaseParams,
): Promise<PluginEnvironmentLease> {
const config = parseDriverConfig(params.config);
if (params.leaseMetadata?.reuseLease === false) {
const sentinel = isRecord(params.leaseMetadata.workspaceSentinel) ? params.leaseMetadata.workspaceSentinel : null;
const intent = isRecord(params.leaseMetadata.nativeWorkspaceExportResume) ? params.leaseMetadata.nativeWorkspaceExportResume : null;
// Ephemeral recovery is bound at acquisition. Never mint proof during
// resume, accept a copied sentinel for a replacement, or waive legacy proof.
if (typeof sentinel?.token !== "string" || !sentinel.token || typeof sentinel.runId !== "string" || !sentinel.runId
|| sentinel.providerLeaseId !== params.providerLeaseId || params.leaseMetadata.sandboxId !== params.providerLeaseId
|| (intent && intent.runId !== sentinel.runId)) {
return { providerLeaseId: null, metadata: { expired: true, workspaceSentinel: { result: "mismatch" } } };
}
}
const scope: SandboxScope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.providerLeaseId,
config,
};
// A confirmed stop may precede completion of an old SDK request. Do not
// restart its sandbox under that request; it could still write or execute.
if (sandboxHandleLeaseAdmissionStates.isClosed(scope) && sandboxHandleActivityGates.isActive(scope)) {
throw new Error("The stopped Daytona sandbox is still settling cancelled work. Retry shortly.");
}
return await withSandboxActivityGate(scope, async () => {
const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
if (!sandbox) {
return { providerLeaseId: null, metadata: { expired: true } };
}
// Daytona can retain the API record after losing its container. Confirm
// the exact provider report again before allowing the host's existing
// backup-guarded replacement path. Unknown errors preserve the lease.
if (hasMissingSandboxContainer(sandbox)) {
try {
await withLivenessTimeout("sandbox.refreshData", config.livenessTimeoutMs, () => sandbox.refreshData());
assertHandleMatchesLease(sandbox, params.providerLeaseId);
} catch (error) {
evictSandboxHandle(scope);
if (error instanceof DaytonaNotFoundError) {
return { providerLeaseId: null, metadata: { expired: true } };
}
throw error;
}
if (hasMissingSandboxContainer(sandbox)) {
evictSandboxHandle(scope);
return { providerLeaseId: null, metadata: { expired: true } };
}
}
// A stopped sandbox loses its session shell, so the stored session id is
// stale after a real restart. Clear the id only when the sandbox is not
// already running, and clear it before the restart. A stopped sandbox has
// no live session, so the clear drops a dead id and a later command opens
// a fresh session. A running sandbox keeps its live session, so the resume
// leaves the id in place; a concurrent command still finds it and teardown
// deletes one session. An unconditional clear would drop the id of a live
// session and leak its shell until sandbox reaping.
if (sandbox.state !== "started") {
sandboxHandleSessionStore.clear(scope);
// A stopped sandbox loses its pseudo-terminals, so a stored duplex channel
// is dead after a real restart. Close and drop every channel on this lease
// before the restart, so no stale channel id survives the resume.
await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);
}
const resumedFromState = sandbox.state ?? null;
await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));
try {
const remoteCwd = await resolveSandboxWorkingDirectory(sandbox, false);
// C3: a resumed lease must clear the workspace sentinel before it is
// trusted, even when the handle came from the cache. On any non-match we
// evict the cached handle and expire the lease so a stale/foreign sandbox
// is never reused on the subsequent (sentinel-skipping) exec path.
const workspaceSentinel = await verifyWorkspaceSentinel({
sandbox,
remoteCwd,
leaseMetadata: params.leaseMetadata,
timeoutSeconds: toTimeoutSeconds(config.timeoutMs),
});
if (workspaceSentinel.result !== "matched") {
evictSandboxHandle(scope);
return {
providerLeaseId: null,
metadata: { expired: true, workspaceSentinel },
};
}
const shellCommand = await detectSandboxShellCommand(
sandbox,
toTimeoutSeconds(config.timeoutMs),
);
sandboxHandleCache.markFresh(scope);
sandboxHandleLeaseAdmissionStates.open(scope);
return {
providerLeaseId: sandbox.id,
metadata: leaseMetadata({
config,
sandbox,
shellCommand,
remoteCwd,
resumedLease: true,
resumedFromState,
sandboxState: "started",
workspaceSentinel,
}),
};
} catch (error) {
evictSandboxHandle(scope);
// A timeout, rate limit, or provider 5xx does not prove this sandbox is
// lost. Preserve the exact resource and let the host retry its recorded
// lease; replacement is permitted only after an explicit not-found or
// an immutable workspace identity mismatch.
throw error;
}
},
{ allowClosed: true },
);
},
onEnvironmentStopLease: stopLease,
async onEnvironmentReleaseLease(
params: PluginEnvironmentReleaseLeaseParams,
): Promise<PluginEnvironmentTerminationReceipt | void> {
if (!params.providerLeaseId) return;
if (params.resourceDisposition === "stop_and_retain") return stopLease(params);
const config = parseDriverConfig(params.config);
const scope: SandboxScope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.providerLeaseId,
config,
};
// C4: the lease's handle must not outlive its teardown. A teardown gate
// blocks fresh cache reads while cleanup is in flight so overlapping
// exec/sync calls cannot reacquire the same sandbox mid-stop/delete.
const teardownGate = sandboxHandleTeardownGates.begin(scope);
sandboxHandleLeaseAdmissionStates.close(scope);
let cleanupProof = idleActivity.proof(sandboxHandleCacheKey(scope));
try {
const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
if (!sandbox) return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
evictSandboxHandle(scope);
if (params.cancelActiveWork) {
// Graceful release waits for activity below. Stop must not wait on the
// command it is cancelling. Admission is already closed for this lease.
const timeoutSeconds = Math.min(toTimeoutSeconds(config.timeoutMs), 30);
await withLivenessTimeout("sandbox.refreshData", Math.min(config.livenessTimeoutMs, 30_000), () => sandbox.refreshData());
if (sandbox.state !== "stopped") await sandbox.stop(timeoutSeconds);
sandboxHandleSessionStore.clear(scope);
await closeDaytonaDuplexChannelsForLease(params.providerLeaseId);
return confirmedTermination(scope, "stopped", cleanupProof);
}
await drainSandboxBeforeTermination(sandbox, scope);
cleanupProof = idleActivity.proof(sandboxHandleCacheKey(scope));
// A cached stopped state is not a receipt: the resource could have been
// resumed since the handle was cached. Read provider state at this boundary.
await withLivenessTimeout("sandbox.refreshData", config.livenessTimeoutMs, () => sandbox.refreshData());
if (config.reuseLease) {
if (sandbox.state !== "stopped") {
try {
await terminateAtProvider(scope, "sandbox.stop", () => sandbox.stop(toTimeoutSeconds(config.timeoutMs)));
} catch (error) {
console.warn(
`Failed to stop Daytona sandbox during lease release: ${formatErrorMessage(error)}. Attempting delete instead.`,
);
await terminateAtProvider(scope, "sandbox.delete", () => sandbox.delete(toTimeoutSeconds(config.timeoutMs), true));
return confirmedTermination(scope, "destroyed", cleanupProof);
}
}
return confirmedTermination(scope, "stopped", cleanupProof);
}
if (config.archiveOnRelease) {
try {
if (sandbox.state !== "stopped") {
await terminateAtProvider(scope, "sandbox.stop", () => sandbox.stop(toTimeoutSeconds(config.timeoutMs)));
}
await sandbox.setAutoDeleteInterval(ARCHIVE_ON_RELEASE_AUTO_DELETE_MINUTES);
await sandbox.archive();
return confirmedTermination(scope, "stopped", cleanupProof);
} catch (error) {
console.warn(
`Failed to archive Daytona sandbox during lease release: ${formatErrorMessage(error)}. Falling back to delete.`,
);
}
}
await terminateAtProvider(scope, "sandbox.delete", () => sandbox.delete(toTimeoutSeconds(config.timeoutMs), true));
return confirmedTermination(scope, "destroyed", cleanupProof);
} finally {
sandboxHandleTeardownGates.end(scope, teardownGate);
evictSandboxHandle(scope);
}
},
async onEnvironmentInspectLease(
params: PluginEnvironmentInspectLeaseParams,
): Promise<PluginEnvironmentLeaseObservation> {
// An environment-variable fallback may have changed accounts since this
// historical allocation. Inspection requires explicitly scoped credentials.
if (typeof params.config.apiKey !== "string" || !params.config.apiKey.trim()) {
return { providerLeaseId: params.providerLeaseId, state: "unknown" };
}
const config = parseDriverConfig(params.config);
if (!config.apiUrl && (process.env.DAYTONA_API_URL?.trim() || process.env.DAYTONA_SERVER_URL?.trim())) {
return { providerLeaseId: params.providerLeaseId, state: "unknown" };
}
const proof = idleActivity.proof(providerActivityKey(params, config, params.providerLeaseId));
// Read directly from the provider. The setup-status path and cached lease
// reconnect path can start a stopped sandbox, so neither is an observation.
try {
const sandbox = await createDaytonaClient(config).get(params.providerLeaseId);
if (sandbox.id !== params.providerLeaseId) return { providerLeaseId: params.providerLeaseId, state: "unknown" };
if (sandbox.state === "stopped" || sandbox.state === "archived") {
idleActivity.confirm(proof, true);
}
return { providerLeaseId: sandbox.id, state: sandbox.state === "stopped" ? "stopped" : "active" };
} catch (error) {
if (error instanceof DaytonaNotFoundError) {
idleActivity.confirm(proof, true);
return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
}
throw error;
}
},
async onEnvironmentDestroyLease(
params: PluginEnvironmentDestroyLeaseParams,
): Promise<PluginEnvironmentTerminationReceipt | void> {
if (!params.providerLeaseId) return;
const config = parseDriverConfig(params.config);
if (params.leaseMetadata?.failedCreateCleanup !== undefined) {
const cleanup = readEnvironmentCreationCleanupError({ data: {
schema: "paperclip/environment-creation-cleanup/v1", cleanup: params.leaseMetadata.failedCreateCleanup,
} });
if (!cleanup || cleanup.companyId !== params.companyId || cleanup.environmentId !== params.environmentId ||
cleanup.providerLeaseId !== params.providerLeaseId) {
throw new Error("Failed-create sandbox cleanup scope does not match");
}
await destroyFailedCreation(config, cleanup, params.driverKey, true);
return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
}
const scope: SandboxScope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.providerLeaseId,
config,
};
// C4: the teardown gate blocks fresh cache reads while delete is in flight
// so overlapping exec/sync calls cannot reacquire the same sandbox mid-teardown.
const teardownGate = sandboxHandleTeardownGates.begin(scope);
sandboxHandleLeaseAdmissionStates.close(scope);
try {
const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
if (!sandbox) return { providerLeaseId: params.providerLeaseId, state: "destroyed" };
evictSandboxHandle(scope);
await drainSandboxBeforeTermination(sandbox, scope);
const cleanupProof = idleActivity.proof(sandboxHandleCacheKey(scope));
await terminateAtProvider(scope, "sandbox.delete", () => sandbox.delete(toTimeoutSeconds(config.timeoutMs), true));
return confirmedTermination(scope, "destroyed", cleanupProof);
} finally {
sandboxHandleTeardownGates.end(scope, teardownGate);
evictSandboxHandle(scope);
}
},
async onEnvironmentRealizeWorkspace(
params: PluginEnvironmentRealizeWorkspaceParams,
): Promise<PluginEnvironmentRealizeWorkspaceResult> {
const config = parseDriverConfig(params.config);
const remoteCwd =
typeof params.lease.metadata?.remoteCwd === "string" &&
params.lease.metadata.remoteCwd.trim().length > 0
? params.lease.metadata.remoteCwd.trim()
: params.workspace.remotePath ?? params.workspace.localPath ?? "/paperclip-workspace";
if (params.lease.providerLeaseId) {
const scope: SandboxScope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.lease.providerLeaseId,
config,
};
await withSandboxActivityGate(scope, async () => {
const sandbox = await getSandbox(scope, { bypassTeardownGate: true });
await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));
await sandbox.fs.createFolder(remoteCwd, "755");
});
}
return {
cwd: remoteCwd,
metadata: {
provider: "daytona",
remoteCwd,
},
};
},
async onEnvironmentStartInteractiveSetup(
params: PluginEnvironmentStartInteractiveSetupParams,
): Promise<PluginEnvironmentInteractiveSetupSession> {
const baseConfig = parseDriverConfig(params.config);
const config = withSetupSourceTemplate(baseConfig, params);
const sandbox = await createSandbox(params, config, { purpose: "interactive_setup" });
try {
const remoteCwd = await resolveSandboxWorkingDirectory(sandbox);
const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(config.timeoutMs));
const connection = await createSshConnection(
sandbox,
resolveConnectionExpiresInMinutes(params.connectionExpiresInMinutes),
);
sandboxHandleLeaseAdmissionStates.open({
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: sandbox.id,
config,
});
return {
providerLeaseId: sandbox.id,
status: "waiting_for_user",
expiresAt: params.expiresAt ?? connection.connectionPayload?.expiresAt ?? null,
...connection,
metadata: interactiveSetupMetadata({
config,
sandbox,
shellCommand,
remoteCwd,
sourceTemplateRef: params.sourceTemplateRef,
}),
};
} catch (error) {
const proof = idleActivity.proof(providerActivityKey(params, config, sandbox.id));
await sandbox.delete(toTimeoutSeconds(config.timeoutMs), true).then(
() => idleActivity.confirm(proof),
() => undefined,
);
throw error;
}
},
async onEnvironmentGetInteractiveSetup(
params: PluginEnvironmentGetInteractiveSetupParams,
): Promise<PluginEnvironmentInteractiveSetupSession> {
const config = parseDriverConfig(params.config);
if (!params.providerLeaseId) {
return {
providerLeaseId: null,
status: "missing",
connectionSummary: null,
connectionPayload: null,
metadata: {
provider: "daytona",
missing: true,
},
};
}
const scope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.providerLeaseId,
config,
};
return await withSandboxActivityGate(scope, async () => {
const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
if (!sandbox) {
return {
providerLeaseId: null,
status: "missing",
connectionSummary: null,
connectionPayload: null,
metadata: {
provider: "daytona",
missing: true,
},
};
}
await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));
const remoteCwd = await resolveSandboxWorkingDirectory(sandbox);
const shellCommand = await detectSandboxShellCommand(sandbox, toTimeoutSeconds(config.timeoutMs));
const connection = params.includeConnectionPayload === true
? await createSshConnection(sandbox, resolveConnectionExpiresInMinutes(params.connectionExpiresInMinutes))
: {
connectionSummary: {
type: "ssh" as const,
username: "token",
hostRedacted: true,
portRedacted: true,
commandRedacted: true,
metadata: {
provider: "daytona",
},
},
connectionPayload: null,
};
return {
providerLeaseId: sandbox.id,
status: "waiting_for_user",
...connection,
metadata: interactiveSetupMetadata({
config,
sandbox,
shellCommand,
remoteCwd,
}),
};
});
},
async onEnvironmentCaptureTemplate(
params: PluginEnvironmentCaptureTemplateParams,
): Promise<PluginEnvironmentCaptureTemplateResult> {
const config = parseDriverConfig(params.config);
if (!params.providerLeaseId) {
throw new Error("Cannot capture a Daytona template without a setup sandbox lease.");
}
const scope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.providerLeaseId,
config,
};
return await withSandboxActivityGate(scope, async () => {
const sandbox = await getSandbox(scope, { bypassTeardownGate: true });
const createSnapshot = (sandbox as DaytonaInteractiveSandbox)._experimental_createSnapshot;
if (typeof createSnapshot !== "function") {
throw new Error(
"Daytona template capture requires @daytonaio/sdk Sandbox._experimental_createSnapshot support.",
);
}
const templateRef = sanitizeSnapshotName(
params.templateLabel,
`paperclip-${params.environmentId}-${randomUUID().slice(0, 8)}`,
);
const timeoutMs = typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0
? Math.trunc(params.timeoutMs)
: config.timeoutMs;
await createSnapshot.call(sandbox, templateRef, toTimeoutSeconds(timeoutMs));
return {
templateKind: "snapshot",
templateRef,
metadata: {
provider: "daytona",
sandboxId: sandbox.id,
capturedAt: new Date().toISOString(),
sourceTemplateRefRedacted: Boolean(params.sourceTemplateRef),
previousTemplateRefRedacted: Boolean(params.previousTemplateRef),
timeoutMs,
},
};
});
},
async onEnvironmentCancelInteractiveSetup(
params: PluginEnvironmentCancelInteractiveSetupParams,
): Promise<PluginEnvironmentCancelInteractiveSetupResult> {
const config = parseDriverConfig(params.config);
if (!params.providerLeaseId) {
return {
status: "missing",
metadata: {
provider: "daytona",
missing: true,
reason: params.reason ?? null,
},
};
}
const scope: SandboxScope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.providerLeaseId,
config,
};
// C4: cancelling an interactive-setup lease deletes the sandbox, so the
// teardown gate blocks fresh cache reads while delete is in flight.
const teardownGate = sandboxHandleTeardownGates.begin(scope);
sandboxHandleLeaseAdmissionStates.close(scope);
try {
const sandbox = await getSandboxOrNull(scope, { bypassTeardownGate: true });
if (!sandbox) {
return {
status: "missing",
metadata: {
provider: "daytona",
missing: true,
reason: params.reason ?? null,
},
};
}
evictSandboxHandle(scope);
await sandboxHandleActivityGates.waitForIdle(scope);
await teardownSession(sandbox, scope);
const proof = idleActivity.proof(sandboxHandleCacheKey(scope));
await sandbox.delete(toTimeoutSeconds(config.timeoutMs), true);
idleActivity.confirm(proof);
return {
status: params.reason === "timed_out" ? "timed_out" : "cancelled",
metadata: {
provider: "daytona",
sandboxId: sandbox.id,
reason: params.reason ?? null,
},
};
} finally {
sandboxHandleTeardownGates.end(scope, teardownGate);
evictSandboxHandle(scope);
}
},
async onEnvironmentDeleteTemplate(
params: PluginEnvironmentDeleteTemplateParams,
): Promise<PluginEnvironmentDeleteTemplateResult> {
const templateKind = params.templateKind ?? "snapshot";
if (templateKind !== "snapshot") {
throw new Error(`Daytona can delete snapshot templates only, not ${templateKind}.`);
}
const config = parseDriverConfig(params.config);
const client = createDaytonaClient(config) as Daytona & { snapshot?: DaytonaSnapshotService };
const snapshotService = client.snapshot;
if (typeof snapshotService?.get !== "function" || typeof snapshotService.delete !== "function") {
throw new Error("Daytona template deletion requires @daytonaio/sdk snapshot.get/delete support.");
}
const snapshot = await snapshotService.get(params.templateRef);
await snapshotService.delete(snapshot);
return {
deleted: true,
metadata: {
provider: "daytona",
templateKind: "snapshot",
templateRefRedacted: true,
reason: params.reason ?? null,
},
};
},
async onEnvironmentExecute(
params: PluginEnvironmentExecuteParams,
): Promise<PluginEnvironmentExecuteResult> {
if (!params.lease.providerLeaseId) {
return {
exitCode: 1,
timedOut: false,
stdout: "",
stderr: "No provider lease ID available for execution.",
};
}
const config = parseDriverConfig(params.config);
const providerLeaseId = params.lease.providerLeaseId;
return await withSandboxActivityGate({
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId,
config,
}, async () => {
// Time the sandbox handle lookup (Open Q1) separately from the
// `executeCommand` round-trip so telemetry can split the per-call get cost
// from the exec cost. With the per-lease handle cache this collapses to ~0
// on a hit (no `client.get` REST round-trip), but the field stays present so
// `providerGetMs` remains observable — and still captures the occasional
// freshness refresh the cache issues after an idle gap. `ensureSandboxStarted`
// is a no-op for an already-started sandbox, so it is excluded from the get
// measurement.
const getStart = timingNow();
// Decide the explicit `cache_hit` flag at the true cache decision: the
// handle lookup reports whether the warm cache served the handle or the
// lookup called `client.get`. This replaces the old `providerGetMs == 0`
// proxy. The default `false` covers the theoretical case where the lookup
// reports nothing.
let cacheHit = false;
const sandbox = await getSandbox({
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId,
config,
}, {
bypassTeardownGate: true,
onCacheDecision: (hit) => {
cacheHit = hit;
},
});
const getDurationMs = timingNow() - getStart;
const scope: SandboxScope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId,
config,
};
if (sandbox.state !== "started") {
// A provider restart destroys Daytona process sessions. Drop the stale
// session id before starting the sandbox so runnerd recovery opens a
// new session instead of retrying a dead one for its whole grace.
sandboxHandleSessionStore.clear(scope);
}
await ensureSandboxStarted(sandbox, toTimeoutSeconds(resolveTimeoutMs(params.timeoutMs, config)));
// Dispatch the command. A normal command runs in the persistent session:
// the provider opens the one session on a cache miss and runs every command
// in it. The provider never falls back to a one-shot command to open a
// session; a cache miss creates one.
//
// A `bypassSession` command runs one-shot and does NOT open the session.
// The host sets this flag on a pre-run command (the workspace provision
// command) that runs before the run opens its trace root. Opening the
// session there would emit a `session.open` span with no run parent, and
// the span backend would drop it. With the bypass the session opens on the
// first in-run command, whose open span parents to the run trace.
let result: PluginEnvironmentExecuteResult;
if (!params.bypassSession) {
const sessionId = await getOrCreateSession(sandbox, scope);
result = await executeInSession(sandbox, sessionId, params, config);
} else {
result = await executeOneShot(sandbox, params, config);
}
if (!result.timedOut) {
sandboxHandleCache.markFresh(scope);
}
return {
...result,
metadata: { ...(result.metadata ?? {}), getDurationMs, cacheHit },
};
});
},
async onEnvironmentRunnerIngressEndpoint(
params: PluginEnvironmentRunnerIngressEndpointParams,
): Promise<PluginEnvironmentRunnerIngressEndpoint> {
if (params.port !== 43_127) {
throw new Error("Daytona runner ingress must use fixed port 43127.");
}
if (!/^\/api\/runner\/v1\/connect\/[^/?#]+$/.test(params.path)) {
throw new Error("Daytona runner ingress path is invalid.");
}
const providerLeaseId = params.lease.providerLeaseId;
if (!providerLeaseId) {
throw new Error("Daytona runner ingress requires a provider lease id.");
}
const config = parseDriverConfig(params.config);
return await withSandboxActivityGate(
{
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId,
config,
},
async () => {
const sandbox = await getSandbox({
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId,
config,
});
await ensureSandboxStarted(sandbox, toTimeoutSeconds(config.timeoutMs));
await withLivenessTimeout(
"sandbox.refreshData",
config.livenessTimeoutMs,
() => sandbox.refreshData(),
);
const preview = await sandbox.getPreviewLink(params.port);
if (typeof preview.url !== "string" || typeof preview.token !== "string") {
throw new Error("Daytona returned an incomplete private preview endpoint.");
}
const url = new URL(preview.url);
if (
url.protocol !== "https:" ||
url.username ||
url.password ||
url.search ||
url.hash
) {
throw new Error("Daytona returned an invalid private preview URL.");
}
url.protocol = "wss:";
url.pathname = `${url.pathname.replace(/\/$/, "")}${params.path}`;
return {
kind: "authenticated_websocket",
websocketUrl: url.toString(),
secretHeaders: [
{ name: "X-Daytona-Preview-Token", value: preview.token },
],
generation: runnerIngressGenerationStore.get(sandbox),
};
},
);
},
// Opt-in native inbound transfer. Defining this hook (with onEnvironmentSyncOut)
// makes the worker advertise `environmentSyncIn`/`environmentSyncOut`, so the
// host runner routes Daytona workspace/asset transfers through the SDK's batch
// `uploadFiles` (plus host-side tarballs for directories) instead of the
// base64-over-exec fallback. Providers that do not define these keep the
// byte-identical fallback.
async onEnvironmentSyncIn(
params: PluginEnvironmentSyncInParams,
): Promise<PluginEnvironmentSyncResult> {
if (!params.lease.providerLeaseId) {
throw new Error("Daytona syncIn requires a provider lease ID.");
}
const config = parseDriverConfig(params.config);
const remoteDir = resolveSyncRemoteDir(params.lease);
const timeoutSeconds = toTimeoutSeconds(config.timeoutMs);
const scope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.lease.providerLeaseId,
config,
};
// Collect the advisory read-write destinations for this scope. This records
// intent only; it does not change the transfer below.
sandboxHandleWritableDirs.recordWritableTargets(scope, params.operations);
return await withSandboxActivityGate(scope, async () => {
const sandbox = await getSandbox(scope, { bypassTeardownGate: true });
await ensureSandboxStarted(sandbox, timeoutSeconds);
const result = await performSyncIn({
sandbox,
operations: params.operations,
remoteDir,
timeoutSeconds,
});
sandboxHandleCache.markFresh(scope);
return result;
});
},
// Opt-in native outbound transfer. See onEnvironmentSyncIn.
async onEnvironmentSyncOut(
params: PluginEnvironmentSyncOutParams,
): Promise<PluginEnvironmentSyncResult> {
if (!params.lease.providerLeaseId) {
throw new Error("Daytona syncOut requires a provider lease ID.");
}
const config = parseDriverConfig(params.config);
const remoteDir = resolveSyncRemoteDir(params.lease);
const timeoutSeconds = toTimeoutSeconds(config.timeoutMs);
const scope = {
driverKey: params.driverKey,
companyId: params.companyId,
environmentId: params.environmentId,
providerLeaseId: params.lease.providerLeaseId,
config,
};
try {
return await withSandboxActivityGate(scope, async () => {
const sandbox = await withEnvironmentSyncTransferStep("sandbox_access", async () => {
const resolved = await getSandbox(scope, { bypassTeardownGate: true });
await ensureSandboxStarted(resolved, timeoutSeconds);
return resolved;
});
const result = await performSyncOut({
sandbox,
operations: params.operations,
remoteDir,
timeoutSeconds,
onArchiveRecovery: () => pluginContext?.logger.info("Workspace export omitted unsafe links; retrying with confined entries."),
});
sandboxHandleCache.markFresh(scope);
return result;
});
} catch (error) {
// A deleted Daytona sandbox is the one provider failure that proves its
// unexported workspace bytes no longer exist. Convert the SDK class to a
// stable cross-worker message; every other error remains retryable.
if (error instanceof DaytonaNotFoundError) {
throw preserveEnvironmentSyncErrorDiagnostic(new Error("daytona_sandbox_not_found"), error);
}
throw error;
}
},
// Open one live login pseudo-terminal. Resolve the cached sandbox by the
// provider lease id, revalidate the host launch descriptor, create the session
// home with one `mkdir -p` command, run the fixed login command on a real
// pseudo-terminal, and register the session under the host route id. Stream the
// raw output and the exit through `ctx.loginPty`, bound to the returned worker
// session id. Fail closed when no cached sandbox matches the lease.
async onLoginPtyOpen(params) {
const sandbox = await sandboxHandleCache.findByProviderLeaseId(params.providerLeaseId);
if (!sandbox) {
throw new Error(
"Daytona login pseudo-terminal: no cached sandbox resolves the provider lease.",
);
}
const homeFs = createDaytonaLoginHomeFs(sandbox.process as unknown as DaytonaSandboxExec);
const session = await openLoginPtySession(
sandbox.process as unknown as DaytonaPtyProcess,
homeFs,
{ loginCommandKey: params.loginCommandKey, sessionHome: params.sessionHome },
);
const workerSessionId = `pty-${randomUUID()}`;
const entry: DaytonaLoginPtyEntry = {
hostRouteId: params.hostRouteId,
workerSessionId,
session,
};
daytonaLoginPtyByRoute.set(params.hostRouteId, entry);
daytonaLoginPtyBySession.set(workerSessionId, entry);
// Register the output listener before the first input, so no early output
// chunk is lost. The client stamps the host route identifier and the worker
// session identifier, so the host can hold more than one concurrent login
// pseudo-terminal on this worker and binds the output to its own route.
session.onData((chunk) => {
pluginContext?.loginPty.output(params.hostRouteId, workerSessionId, chunk);
});
// Forward the child exit one time. The host resolves the login run on it.
void session.wait().then(
(result) => pluginContext?.loginPty.exit(params.hostRouteId, workerSessionId, result.exitCode),
() => pluginContext?.loginPty.exit(params.hostRouteId, workerSessionId, null),
);
return { workerSessionId };
},
// Write delayed input to an open login pseudo-terminal, keyed by the worker
// session id. Drop the input for an unknown session.
async onLoginPtyInput(params) {
const entry = daytonaLoginPtyBySession.get(params.workerSessionId);
if (!entry) return;
entry.session.write(params.data);
},
// Stop an open login pseudo-terminal child, keyed by the worker session id.
async onLoginPtyStop(params) {
const entry = daytonaLoginPtyBySession.get(params.workerSessionId);
if (!entry) return;
entry.session.kill();
},
// Close an open login pseudo-terminal by the host route id and acknowledge the
// close with the same identifier. The close is idempotent: it returns the
// acknowledgement even when the entry is already gone, so the host confirms the
// terminal is closed. The worker never keys the close on the worker session id.
async onLoginPtyClose(params) {
const entry = daytonaLoginPtyByRoute.get(params.hostRouteId);
if (entry) {
forgetDaytonaLoginPty(entry);
await entry.session.close().catch(() => undefined);
}
return { hostRouteId: params.hostRouteId };
},
// Open one persistent duplex channel. Resolve the cached sandbox by the provider
// lease id, run the gateway command on a raw pseudo-terminal, and register the
// channel under the host route id. Stream the raw data and the exit through
// `ctx.duplexChannel`, bound to the returned worker session id. Fail closed when
// no cached sandbox matches the lease.
async onDuplexChannelOpen(params) {
const sandbox = await sandboxHandleCache.findByProviderLeaseId(params.providerLeaseId);
if (!sandbox) {
throw new Error(
"Daytona duplex channel: no cached sandbox resolves the provider lease.",
);
}
const session = await openDuplexChannelSession(
sandbox.process as unknown as DaytonaPtyProcess,
params.command,
);
const workerSessionId = `duplex-${randomUUID()}`;
const entry: DaytonaDuplexChannelEntry = {
hostRouteId: params.hostRouteId,
workerSessionId,
providerLeaseId: params.providerLeaseId,
session,
};
daytonaDuplexChannelByRoute.set(params.hostRouteId, entry);
daytonaDuplexChannelBySession.set(workerSessionId, entry);
// Register the data listener before the first write, so no early data chunk is
// lost. The client echoes the host route id and the worker session id, so the
// host routes the data to the exact live pair.
session.onData((chunk) => {
pluginContext?.duplexChannel.data(entry.hostRouteId, workerSessionId, chunk);
});
// Forward the child exit one time. The host resolves the open route on it. A
// numeric exit code is a real process exit; a resolved transport close carries
// `transportClosed`, so the host keeps the two apart in the loss taxonomy. A
// rejected wait is not a resolved transport close, so it reports no code and no
// transport-close mark.
void session.wait().then(
(result) =>
pluginContext?.duplexChannel.exit(
entry.hostRouteId,
workerSessionId,
result.exitCode,
result.transportClosed,
),
() => pluginContext?.duplexChannel.exit(entry.hostRouteId, workerSessionId, null),
);
// Echo the host route id on the reply, so the host binds the exact pair.
return { hostRouteId: params.hostRouteId, workerSessionId };
},
// Write host input to an open duplex channel. Act only on the exact live pair.
// A write whose pair does not match the bound entry applies no bytes.
//
// `params.data` arrives in the wire-safe base64 form (JSON carries no binary
// type; see `ChannelBytesWireValue` in the plugin SDK's protocol.ts). Decode it
// back to raw bytes before it reaches the pseudo-terminal. A malformed value
// decodes to `null`; the worker applies no bytes rather than sending an empty
// write to the sandbox.
async onDuplexChannelWrite(params) {
const entry = daytonaDuplexChannelBySession.get(params.workerSessionId);
if (!entry || entry.hostRouteId !== params.hostRouteId) return;
const data = decodeChannelBytes(params.data);
if (data === null) return;
entry.session.write(data);
},
// Stop an open duplex channel child. Act only on the exact live pair. A stop
// whose pair does not match the bound entry stops nothing.
async onDuplexChannelStop(params) {
const entry = daytonaDuplexChannelBySession.get(params.workerSessionId);
if (!entry || entry.hostRouteId !== params.hostRouteId) return;
entry.session.kill();
},
// Close an open duplex channel by the host route id and acknowledge the close.
// The host route id is the authoritative close key, so a pre-bind close with a
// lost open reply still closes the channel. On a bound close the acknowledgement
// echoes the worker session id too, so the host verifies the exact pair. The
// close is idempotent: it returns the acknowledgement even when the entry is
// already gone, so the host confirms the channel is closed.
async onDuplexChannelClose(params) {
const entry = daytonaDuplexChannelByRoute.get(params.hostRouteId);
if (entry) {
const boundWorkerSessionId = entry.workerSessionId;
forgetDaytonaDuplexChannel(entry);
await entry.session.close().catch(() => undefined);
return { hostRouteId: params.hostRouteId, workerSessionId: boundWorkerSessionId };
}
return { hostRouteId: params.hostRouteId };
},
// Close every open login pseudo-terminal and every open duplex channel on an
// orderly shutdown, then drain the sandbox handle cache, so a graceful shutdown
// holds no live terminal and no live channel.
async onShutdown() {
const openSessions = [...daytonaLoginPtyByRoute.values()];
daytonaLoginPtyByRoute.clear();
daytonaLoginPtyBySession.clear();
for (const entry of openSessions) {
await entry.session.close().catch(() => undefined);
}
const openChannels = [...daytonaDuplexChannelByRoute.values()];
daytonaDuplexChannelByRoute.clear();
daytonaDuplexChannelBySession.clear();
for (const entry of openChannels) {
await entry.session.close().catch(() => undefined);
}
sandboxHandleCache.reset();
runnerIngressGenerationStore.reset();
},
}, idleActivity));
export default plugin;