Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
/**
* The part of the Vercel Sandbox API the session factory uses (docs/workspaces.md
* §5.7), as one small interface, so the lifecycle is written once and tested on
* the stand-in (`test/fake-api.ts`, local relays over temp dirs) as well as on
* the platform (`vercelSandboxApi`, `@vercel/sandbox` 3.7.0).
*
* Only what the probes measured is relied on (docs/sandbox-probes.md):
*
* - a stopped non-persistent sandbox can't be resumed (P0.4): `get`, then
* create, or an owner's delete and create;
* - a Drive held by another VM session answers 409 `drive_attached` for 5-8 s
* after that session goes (P0.5);
* - a VM that crashed inside stays `running` until its own timeout (P0.5), so
* whether it answers is asked with a command, not read from its status;
* - `runCommand`, `extendTimeout` and `writeFiles` resume a stopped persistent
* sandbox; on a non-persistent one they fail, so cleanup never calls them.
*
* Besides the VM, the named sandbox carries one tag of the factory's own,
* `dh-fence`: the highest fence count an owner armed the VM with (set at
* create and with the policy at every warm attach). It is the watermark a
* driver reads before it arms, rotates or replaces a VM, so a driver whose
* fence is stale (but still reads `fenced`) never deletes the newer owner's
* VM, and a VM it can't ask (lost) still says who armed it last.
*/
import { resolveProjectId } from './names.ts';
export { resolveProjectId };
/** A Drive, as the session factory needs it. */
export interface DriveInfo {
readonly name: string;
readonly driveId: string;
readonly region: string;
/** Bytes. */
readonly maxSize: number;
/** The VM session the Drive is attached to, if any. */
readonly currentSessionId?: string;
}
/** The status of a VM session, as the platform reports it. */
export type VmStatus = 'pending' | 'running' | 'stopping' | 'stopped' | 'failed' | 'aborted' | 'snapshotting';
/** What a command run through the control plane returned. */
export interface RunResult {
exitCode: number | null;
stdout: string;
stderr: string;
}
/** Where the relay and the cache dirs are in a VM, when not where the base puts them (`vm.ts`): the stand-in's temp dirs and ports. */
export interface VmLayout {
port: number;
modelPort: number;
workspace: string;
cacheRoot: string;
config: string;
}
/** A named sandbox and its current VM session. */
export interface VmHandle {
readonly name: string;
/** The current VM session. */
readonly sessionId: string;
readonly status: VmStatus;
readonly region: string;
/** When the current VM session started (epoch ms). */
readonly startedAt: number;
/** The current VM session's timeout, ms from `startedAt`. */
readonly timeout: number;
/** The `dh-fence` tag: the highest fence count an owner armed this sandbox with, if any did. */
readonly fenceMark?: number;
/** The public URL of an exposed port (`https://…`). Throws for a port the sandbox doesn't expose. */
domain(port: number): string;
/** Run a command through the control plane (authenticated with the Function's credential). */
run(command: string, args: string[], options?: { sudo?: boolean; timeoutMs?: number; signal?: AbortSignal }): Promise<RunResult>;
/** Extend the VM session's timeout by `ms`, up to the plan's cap (past it the platform refuses). */
extendTimeout(ms: number): Promise<void>;
/**
* Apply a network policy (`update({ networkPolicy })`, never the deprecated
* `updateNetworkPolicy`), and in the same call raise the `dh-fence` tag to
* `fenceMark` (never lower it).
*/
setNetwork(policy: SandboxNetworkPolicy, fenceMark?: number): Promise<void>;
stop(): Promise<void>;
delete(): Promise<void>;
/** Only the stand-in sets it. */
readonly layout?: VmLayout;
}
/** The network policy the factory applies (`@vercel/sandbox`'s `NetworkPolicy`, the subset it uses). */
export type SandboxNetworkPolicy = 'allow-all' | 'deny-all' | { allow: Record<string, { response?: { statusCode: number } }[]> };
/** What the VM boots from. */
export type BootSource = { image: string } | { snapshot: string };
export interface CreateSandbox {
name: string;
region: string;
source?: BootSource;
/** Mounted read-write at `/workspace`. */
drive: string;
/** The Drive's id as the factory checked it: a Drive fetched for the mount with another id (deleted and made again in between) is `ApiConflict('drive_changed')`. */
driveId: string;
/** The fence count of the driver that creates it: the `dh-fence` tag. */
fenceMark?: number;
ports: number[];
vcpus: number;
/** ms. */
timeout: number;
network: SandboxNetworkPolicy;
tags?: Record<string, string>;
}
/** An API call refused for a reason the lifecycle handles. */
export class ApiConflict extends Error {
constructor(
/** `name`: the sandbox name is taken; `drive_attached`: the Drive is held by another VM session; `exists`: the Drive exists; `drive_changed`: the Drive is not the one checked (another id under its name). */
readonly kind: 'name' | 'drive_attached' | 'exists' | 'drive_changed',
message: string
) {
super(message);
this.name = 'ApiConflict';
}
}
export interface SandboxApi {
/** The project the names are derived from. */
projectId(): Promise<string>;
getDrive(name: string): Promise<DriveInfo | undefined>;
/** Throws `ApiConflict('exists')` when another invocation created it first. */
/** Create a Drive; without `maxSize`, the platform's default size for the plan (1 GiB on Hobby). */
createDrive(options: { name: string; region: string; maxSize?: number }): Promise<DriveInfo>;
getSandbox(name: string): Promise<VmHandle | undefined>;
/** Throws `ApiConflict('name')` or `ApiConflict('drive_attached')`. */
createSandbox(options: CreateSandbox): Promise<VmHandle>;
}
/**
* What deleting a session's sandbox and Drive takes (`cleanup.ts`): reads,
* and the one delete the VM's handle doesn't have. Nothing here boots a VM:
* `getSandbox` never resumes one, and a `VmHandle`'s `stop` and `delete`
* act on the named sandbox without a session (P0.11: `runCommand`,
* `extendTimeout`, `update` and `writeFiles` would boot a stopped one).
*/
export interface CleanupApi {
getSandbox(name: string): Promise<VmHandle | undefined>;
/** Delete a Drive by name: `false` when there is none. `ApiConflict('drive_attached')` while a VM session still holds it (a few seconds after a VM is deleted without a stop). */
deleteDrive(name: string): Promise<boolean>;
/** Every Drive of the project whose name starts with `prefix`, every page. */
listDrives(prefix: string): AsyncIterable<DriveInfo>;
}
/** Credentials for a driver outside Vercel (`sandbox({ credentials })`); never logged, never sent to the VM. */
export interface ApiCredentials {
token: string;
teamId: string;
projectId: string;
}
/** An SDK error's status and code, never its body or headers. */
export function apiErrorOf(err: unknown): { status?: number; code?: string; message: string } {
const e = err as { message?: unknown; response?: { status?: unknown }; json?: { error?: { code?: unknown } } };
const status = typeof e?.response?.status === 'number' ? e.response.status : undefined;
const code = typeof e?.json?.error?.code === 'string' ? e.json.error.code : undefined;
return { ...(status !== undefined ? { status } : {}), ...(code !== undefined ? { code } : {}), message: String(e?.message ?? err).slice(0, 300) };
}
type Sdk = typeof import('@vercel/sandbox');
type SdkSandbox = InstanceType<Sdk['Sandbox']>;
const STATUSES = new Set<VmStatus>(['pending', 'running', 'stopping', 'stopped', 'failed', 'aborted', 'snapshotting']);
/** The tag that carries the fence watermark. */
export const FENCE_TAG = 'dh-fence';
/** The watermark a tag map carries, or undefined. */
export function fenceMarkOf(tags: Readonly<Record<string, string>> | undefined): number | undefined {
const v = tags?.[FENCE_TAG];
if (v === undefined || !/^\d{1,15}$/.test(v)) return undefined;
return Number(v);
}
/** `@vercel/sandbox` over the interface. The SDK is imported on first use, so a session that never acquires a sandbox never loads it. */
export function vercelSandboxApi(credentials?: ApiCredentials): SandboxApi & CleanupApi {
let sdk: Promise<Sdk> | undefined;
const load = () => (sdk ??= import('@vercel/sandbox'));
const creds = credentials ? { token: credentials.token, teamId: credentials.teamId, projectId: credentials.projectId } : {};
const drive = (d: InstanceType<Sdk['Drive']>): DriveInfo => ({ name: d.name, driveId: d.driveId, region: d.region, maxSize: d.maxSize, ...(d.currentSessionId ? { currentSessionId: d.currentSessionId } : {}) });
const handle = (sb: SdkSandbox): VmHandle => {
const session = sb.currentSession();
// A status this SDK doesn't name (a state added later) is waited on as booting, never deleted as failed.
const status = STATUSES.has(sb.status as VmStatus) ? (sb.status as VmStatus) : 'pending';
const fenceMark = fenceMarkOf(sb.tags);
return {
name: sb.name,
sessionId: session.sessionId,
status,
region: sb.region,
startedAt: (session.startedAt ?? session.createdAt).getTime(),
timeout: session.timeout,
...(fenceMark !== undefined ? { fenceMark } : {}),
domain: (port) => sb.domain(port),
async run(command, args, options = {}) {
const c = await sb.runCommand({ cmd: command, args, sudo: options.sudo ?? false, ...(options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}), ...(options.signal ? { signal: options.signal } : {}) });
return { exitCode: c.exitCode, stdout: await c.stdout(), stderr: await c.stderr() };
},
extendTimeout: (ms) => sb.extendTimeout(ms),
async setNetwork(policy, mark) {
const tags = sb.tags ?? {};
const raise = mark !== undefined && mark > (fenceMarkOf(tags) ?? -1);
await sb.update({ networkPolicy: policy as never, ...(raise ? { tags: { ...tags, [FENCE_TAG]: String(mark) } } : {}) });
},
async stop() {
await sb.stop();
},
delete: () => sb.delete(),
};
};
return {
projectId: async () => resolveProjectId(credentials),
async getDrive(name) {
const { Drive } = await load();
try {
return drive(await Drive.get({ name, ...creds }));
} catch (err) {
if (apiErrorOf(err).status === 404) return undefined;
throw err;
}
},
async createDrive({ name, region, maxSize }) {
const { Drive } = await load();
try {
return drive(await Drive.getOrCreate({ name, region, ...(maxSize !== undefined ? { maxSize } : {}), ...creds }));
} catch (err) {
const e = apiErrorOf(err);
if (e.status === 409) throw new ApiConflict('exists', e.message);
throw err;
}
},
async getSandbox(name) {
const { Sandbox } = await load();
try {
return handle(await Sandbox.get({ name, ...creds }));
} catch (err) {
if (apiErrorOf(err).status === 404) return undefined;
throw err;
}
},
async deleteDrive(name) {
const { Drive } = await load();
let found;
try {
found = await Drive.get({ name, ...creds });
} catch (err) {
if (apiErrorOf(err).status === 404) return false;
throw err;
}
try {
await found.delete();
return true;
} catch (err) {
const e = apiErrorOf(err);
if (e.status === 404) return false;
// Measured (A7): 409 `drive_attached` while a VM session holds it, and for some seconds after that VM is deleted without a stop.
if (e.status === 409 && e.code === 'drive_attached') throw new ApiConflict('drive_attached', e.message);
throw err;
}
},
async *listDrives(prefix) {
const { Drive } = await load();
for await (const d of await Drive.list({ namePrefix: prefix, sortBy: 'name', limit: 50, ...creds })) yield drive(d);
},
async createSandbox(o) {
const { Sandbox, Drive } = await load();
const mounted = await Drive.get({ name: o.drive, ...creds });
if (mounted.driveId !== o.driveId) throw new ApiConflict('drive_changed', 'the Drive under this name is not the one checked');
const tags = { ...(o.tags ?? {}), ...(o.fenceMark !== undefined ? { [FENCE_TAG]: String(o.fenceMark) } : {}) };
const source = o.source && 'snapshot' in o.source ? { source: { type: 'snapshot' as const, snapshotId: o.source.snapshot } } : o.source ? { image: o.source.image } : {};
try {
const sb = await Sandbox.create({
name: o.name,
region: o.region,
persistent: false,
mounts: { '/workspace': mounted },
ports: o.ports,
resources: { vcpus: o.vcpus },
timeout: o.timeout,
networkPolicy: o.network as never,
...(Object.keys(tags).length ? { tags } : {}),
...source,
...creds,
} as Parameters<Sdk['Sandbox']['create']>[0]);
return handle(sb);
} catch (err) {
const e = apiErrorOf(err);
if (e.status === 409 && e.code === 'drive_attached') throw new ApiConflict('drive_attached', e.message);
// A taken name: 409, or (P0.4) a 400 "already exists" while the old one is stopped.
if (e.status === 409 || (e.status === 400 && /already exists/i.test(e.message))) throw new ApiConflict('name', e.message);
throw err;
}
},
};
}