@agent-relay/sandbox 0.1.1 → 0.1.3

package/dist/freestyle/runtime.js

@@ -0,0 +1,798 @@
+import { Buffer } from "node:buffer";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { freestyleObservedCapabilities, freestyleSandboxCapabilities, freestyleWorkflowCapabilities, } from "./capabilities.js";
+import { createOfficialFreestyleClient, } from "./internal/sdk.js";
+const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+const DEFAULT_CREATE_TIMEOUT_MS = 120_000;
+const DEFAULT_LOOKUP_TIMEOUT_MS = 10_000;
+const DEFAULT_LIFECYCLE_SETTLE_TIMEOUT_MS = 120_000;
+const DEFAULT_POLL_INTERVAL_MS = 500;
+const COMMAND_REQUEST_GRACE_MS = 5_000;
+export class FreestyleCreateTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Freestyle create did not complete within ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = "FreestyleCreateTimeoutError";
+    }
+}
+export class FreestyleLookupTimeoutError extends Error {
+    timeoutMs;
+    operation;
+    constructor(timeoutMs, operation) {
+        super(`Freestyle ${operation} did not complete within ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.operation = operation;
+        this.name = "FreestyleLookupTimeoutError";
+    }
+}
+export class FreestyleLifecycleTimeoutError extends Error {
+    sandboxId;
+    expected;
+    lastState;
+    timeoutMs;
+    constructor(sandboxId, expected, lastState, timeoutMs) {
+        super(`Freestyle VM "${sandboxId}" did not reach ${expected} within ${timeoutMs}ms `
+            + `(last state: "${lastState}")`);
+        this.sandboxId = sandboxId;
+        this.expected = expected;
+        this.lastState = lastState;
+        this.timeoutMs = timeoutMs;
+        this.name = "FreestyleLifecycleTimeoutError";
+    }
+}
+export class FreestyleDestroyVerificationError extends Error {
+    sandboxId;
+    timeoutMs;
+    constructor(sandboxId, timeoutMs) {
+        super(`Freestyle VM "${sandboxId}" delete was accepted but absence was not verified `
+            + `within ${timeoutMs}ms`);
+        this.sandboxId = sandboxId;
+        this.timeoutMs = timeoutMs;
+        this.name = "FreestyleDestroyVerificationError";
+    }
+}
+export class FreestyleUnknownExitCodeError extends Error {
+    constructor() {
+        super("Freestyle exec response omitted statusCode; refusing to treat it as success");
+        this.name = "FreestyleUnknownExitCodeError";
+    }
+}
+export class FreestyleLaunchEnvironmentUnsupportedError extends Error {
+    constructor() {
+        super("Freestyle vms.create has no environment field; launch env must be provisioned "
+            + "provider-neutrally after create");
+        this.name = "FreestyleLaunchEnvironmentUnsupportedError";
+    }
+}
+export class FreestyleCapabilityMismatchError extends Error {
+    constructor(message) {
+        super(`Freestyle capability declaration mismatch: ${message}`);
+        this.name = "FreestyleCapabilityMismatchError";
+    }
+}
+export class FreestyleRuntime {
+    id = "freestyle";
+    capabilities = freestyleWorkflowCapabilities;
+    declaredCapabilities = freestyleSandboxCapabilities;
+    observedCapabilities = freestyleObservedCapabilities;
+    apiKey;
+    baseUrl;
+    defaultHomeDir;
+    namePrefix;
+    snapshotId;
+    persistence;
+    idleTimeoutSeconds;
+    requestTimeoutMs;
+    createTimeoutMs;
+    lookupTimeoutMs;
+    lifecycleSettleTimeoutMs;
+    pollIntervalMs;
+    injectedClientFactory;
+    registrations = new Map();
+    reconciliations = new Set();
+    constructor(options, dependencies = {}) {
+        this.apiKey = required(options.apiKey, "Freestyle API key");
+        this.defaultHomeDir = required(options.defaultHomeDir, "Freestyle default home directory");
+        this.namePrefix = validateNamePrefix(options.namePrefix);
+        this.baseUrl = optionalTrimmed(options.baseUrl);
+        this.snapshotId = optionalTrimmed(options.snapshotId);
+        this.persistence = validatePersistence(options.persistence);
+        this.idleTimeoutSeconds = validateIdleTimeout(options.idleTimeoutSeconds);
+        this.requestTimeoutMs = positiveDuration(options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+        this.createTimeoutMs = positiveDuration(options.createTimeoutMs, DEFAULT_CREATE_TIMEOUT_MS);
+        this.lookupTimeoutMs = positiveDuration(options.lookupTimeoutMs, DEFAULT_LOOKUP_TIMEOUT_MS);
+        this.lifecycleSettleTimeoutMs = positiveDuration(options.lifecycleSettleTimeoutMs, DEFAULT_LIFECYCLE_SETTLE_TIMEOUT_MS);
+        this.pollIntervalMs = positiveDuration(options.pollIntervalMs, DEFAULT_POLL_INTERVAL_MS);
+        this.injectedClientFactory = dependencies.clientFactory;
+        assertFreestyleCapabilityImplementation(this);
+    }
+    async launch(options = {}) {
+        if (hasEntries(options.env)) {
+            throw new FreestyleLaunchEnvironmentUnsupportedError();
+        }
+        const timeoutMs = options.createTimeoutSeconds && options.createTimeoutSeconds > 0
+            ? Math.ceil(options.createTimeoutSeconds * 1_000)
+            : this.createTimeoutMs;
+        const callerName = options.name?.trim() || options.label?.trim();
+        const name = this.ownedName(callerName);
+        // Only a name we generated with a fresh UUID is safe to reconcile by name.
+        // Deterministic slug names (derived from caller-supplied input) can collide
+        // across concurrent launches — matching on such a name could destroy a
+        // sibling's live VM. Leave those documented as unreconciled.
+        const reconcilableName = callerName ? null : name;
+        const client = await this.client(timeoutMs);
+        // Hold the raw create promise so it outlives the client-side deadline
+        // race. `withDeadline` only abandons the wait — the SDK call can still
+        // complete after we reject, and Freestyle may then hand back a billed VM
+        // that this adapter never registered. Reconcile that outcome in the
+        // background so the caller sees a clean rejection without leaking a VM.
+        const pending = client.vms.create({
+            name,
+            persistence: this.persistence,
+            ...(this.snapshotId ? { snapshotId: this.snapshotId } : {}),
+            ...(this.idleTimeoutSeconds !== undefined
+                ? { idleTimeoutSeconds: this.idleTimeoutSeconds }
+                : {}),
+        });
+        let created;
+        try {
+            created = await withDeadline(pending, timeoutMs, () => new FreestyleCreateTimeoutError(timeoutMs));
+        }
+        catch (error) {
+            if (error instanceof FreestyleCreateTimeoutError && reconcilableName) {
+                this.trackReconciliation(this.reconcileOrphanedCreate(pending, reconcilableName));
+            }
+            else {
+                // Nothing to reconcile — either not our timeout, or a caller-supplied
+                // name we cannot uniquely correlate. Swallow any late rejection so
+                // the runtime does not emit an unhandledRejection warning.
+                this.trackReconciliation(swallow(pending));
+            }
+            throw error;
+        }
+        if (!created || typeof created.vmId !== "string" || !created.vmId.trim()) {
+            throw new Error("Freestyle create response is missing vmId");
+        }
+        const id = created.vmId.trim();
+        this.register(id, {
+            owned: true,
+            labels: options.labels ?? {},
+            state: "STARTED",
+        });
+        return {
+            id,
+            state: "STARTED",
+            homeDir: this.defaultHomeDir,
+            ...(options.workdir ? { workdir: options.workdir } : {}),
+        };
+    }
+    async findByLabels(_labels, _options = {}) {
+        // Freestyle vms.create has no label field. Returning a name-based guess here
+        // would turn ownership naming into a false warm-lease capability.
+        return null;
+    }
+    async findAllByLabels(_labels, _options = {}) {
+        return [];
+    }
+    async countByLabels(_labels, _options = {}) {
+        return 0;
+    }
+    async listOwned(options = {}) {
+        const items = await this.listRemote(options.timeoutMs ?? this.lookupTimeoutMs, "owned VM list");
+        const states = options.states === undefined ? null : options.states;
+        return items
+            .filter((item) => typeof item.name === "string" && this.isOwnedName(item.name))
+            .filter((item) => options.includeDeleted || !item.deleted)
+            .filter((item) => matchesListedState(item, states, options.includeDeleted === true))
+            .map((item) => ({
+            id: item.id,
+            name: item.name,
+            state: normalizeState(item.state),
+            deleted: Boolean(item.deleted),
+            ...(item.createdAt ? { createdAt: item.createdAt } : {}),
+            ...(item.sizing
+                ? {
+                    sizing: {
+                        ...(typeof item.sizing.vcpuCount === "number"
+                            ? { vcpus: item.sizing.vcpuCount }
+                            : {}),
+                        ...(typeof item.sizing.memSizeMib === "number"
+                            ? { memoryMiB: item.sizing.memSizeMib }
+                            : {}),
+                        ...(typeof item.sizing.rootfsSizeMb === "number"
+                            ? { storageMiB: item.sizing.rootfsSizeMb }
+                            : {}),
+                    },
+                }
+                : {}),
+        }));
+    }
+    async getById(id, options = {}) {
+        const item = await this.remoteById(id, this.lookupTimeoutMs);
+        if (!item || item.deleted) {
+            return null;
+        }
+        const states = options.states === undefined ? null : options.states;
+        if (!matchesState(item, states)) {
+            return null;
+        }
+        this.register(id, {
+            owned: options.owned ?? false,
+            labels: {},
+            state: normalizeState(item.state),
+        });
+        return {
+            id,
+            state: normalizeState(item.state),
+            homeDir: options.homeDir ?? this.defaultHomeDir,
+            ...(options.workdir ? { workdir: options.workdir } : {}),
+            ...(item.createdAt ? { createdAt: item.createdAt } : {}),
+            ...(item.lastNetworkActivity ? { lastActivityAt: item.lastNetworkActivity } : {}),
+        };
+    }
+    async runScript(handle, options) {
+        this.requireRegistered(handle);
+        const command = buildFreestyleCommand(options.command, options);
+        const commandTimeoutMs = options.timeoutMs && options.timeoutMs > 0
+            ? Math.ceil(options.timeoutMs)
+            : undefined;
+        const requestTimeoutMs = commandTimeoutMs
+            ? Math.max(this.requestTimeoutMs, commandTimeoutMs + COMMAND_REQUEST_GRACE_MS)
+            : this.requestTimeoutMs;
+        const vm = await this.vm(handle.id, requestTimeoutMs);
+        const result = await withDeadline(vm.exec({
+            command,
+            ...(commandTimeoutMs ? { timeoutMs: commandTimeoutMs } : {}),
+        }), requestTimeoutMs, () => new FreestyleLookupTimeoutError(requestTimeoutMs, "exec request"));
+        const stdout = result.stdout ?? "";
+        const stderr = result.stderr ?? "";
+        return {
+            output: combineOutput(stdout, stderr),
+            ...(stdout ? { stdout } : {}),
+            ...(stderr ? { stderr } : {}),
+            exitCode: typeof result.statusCode === "number" ? result.statusCode : null,
+        };
+    }
+    async exec(handle, command, options = {}) {
+        const result = await this.runScript(handle, { command, ...options });
+        if (result.exitCode === null) {
+            throw new FreestyleUnknownExitCodeError();
+        }
+        return { output: result.output, exitCode: result.exitCode };
+    }
+    async uploadFile(handle, source, destination) {
+        this.requireRegistered(handle);
+        const bytes = typeof source === "string" ? await readFile(source) : source;
+        const parent = parentDirectory(destination);
+        if (parent) {
+            const mkdir = await this.runScript(handle, {
+                command: `mkdir -p ${shellSingleQuote(parent)}`,
+                timeoutMs: 30_000,
+            });
+            if (mkdir.exitCode !== 0) {
+                throw new Error(`Failed to create Freestyle upload directory "${parent}"`);
+            }
+        }
+        const vm = await this.vm(handle.id, this.requestTimeoutMs);
+        await withDeadline(vm.fs.writeFile(destination, bytes), this.requestTimeoutMs, () => new FreestyleLookupTimeoutError(this.requestTimeoutMs, "file upload"));
+    }
+    async uploadBundle(handle, options) {
+        const destinations = [];
+        for (const file of options.files) {
+            await this.uploadFile(handle, file.source, file.destination);
+            destinations.push(file.destination);
+        }
+        if (options.manifest !== undefined) {
+            const path = options.manifestPath ?? "/workspace/manifest.json";
+            await this.uploadFile(handle, Buffer.from(JSON.stringify(options.manifest, null, 2), "utf8"), path);
+            destinations.push(path);
+        }
+        if (destinations.length > 0) {
+            const verified = await this.runScript(handle, {
+                command: destinations
+                    .map((path) => `test -f ${shellSingleQuote(path)}`)
+                    .join(" && "),
+                timeoutMs: 30_000,
+            });
+            if (verified.exitCode !== 0) {
+                throw new Error("Failed to verify uploaded Freestyle bundle files");
+            }
+        }
+    }
+    async downloadFile(handle, source, destination) {
+        this.requireRegistered(handle);
+        const vm = await this.vm(handle.id, this.requestTimeoutMs);
+        const bytes = Buffer.from(await withDeadline(vm.fs.readFile(source), this.requestTimeoutMs, () => new FreestyleLookupTimeoutError(this.requestTimeoutMs, "file download")));
+        if (destination) {
+            await writeFile(destination, bytes);
+            return;
+        }
+        return bytes;
+    }
+    async getHomeDir(handle) {
+        this.requireRegistered(handle);
+        handle.homeDir = handle.homeDir ?? this.defaultHomeDir;
+        return handle.homeDir;
+    }
+    async stop(handle) {
+        const entry = this.registrations.get(handle.id);
+        if (!entry || !entry.owned) {
+            return;
+        }
+        const current = await this.requireRemote(handle.id);
+        if (current.state === "stopped" || current.state === "suspended") {
+            entry.state = "STOPPED";
+            handle.state = "STOPPED";
+            return;
+        }
+        if (current.state === "stopping") {
+            await this.waitForState(handle.id, new Set(["stopped"]), "stopped");
+        }
+        else if (current.state === "suspending") {
+            await this.waitForState(handle.id, new Set(["suspended"]), "suspended");
+        }
+        else {
+            const vm = await this.vm(handle.id, this.requestTimeoutMs);
+            await withDeadline(vm.stop(), this.requestTimeoutMs, () => new FreestyleLookupTimeoutError(this.requestTimeoutMs, "stop request"));
+            await this.waitForState(handle.id, new Set(["stopped"]), "stopped");
+        }
+        entry.state = "STOPPED";
+        handle.state = "STOPPED";
+    }
+    async start(handle) {
+        const entry = this.registrations.get(handle.id);
+        if (!entry || !entry.owned) {
+            return handle;
+        }
+        let current = await this.requireRemote(handle.id);
+        if (current.state === "running") {
+            handle.state = "STARTED";
+            entry.state = "STARTED";
+            return handle;
+        }
+        if (current.state === "starting" || current.state === "building") {
+            await this.waitForState(handle.id, new Set(["running"]), "running");
+            handle.state = "STARTED";
+            entry.state = "STARTED";
+            return handle;
+        }
+        if (current.state === "suspending") {
+            await this.waitForState(handle.id, new Set(["suspended"]), "suspended");
+            current = await this.requireRemote(handle.id);
+        }
+        else if (current.state === "stopping") {
+            await this.waitForState(handle.id, new Set(["stopped"]), "stopped");
+            current = await this.requireRemote(handle.id);
+        }
+        if (current.state === "lost") {
+            throw new Error(`Freestyle VM "${handle.id}" is lost and cannot be started`);
+        }
+        const vm = await this.vm(handle.id, this.requestTimeoutMs);
+        await withDeadline(vm.start(this.idleTimeoutSeconds !== undefined
+            ? { idleTimeoutSeconds: this.idleTimeoutSeconds }
+            : {}), this.requestTimeoutMs, () => new FreestyleLookupTimeoutError(this.requestTimeoutMs, "start request"));
+        await this.waitForState(handle.id, new Set(["running"]), "running");
+        entry.state = "STARTED";
+        handle.state = "STARTED";
+        return handle;
+    }
+    async destroy(handle) {
+        const entry = this.registrations.get(handle.id);
+        if (!entry) {
+            return;
+        }
+        if (!entry.owned) {
+            this.registrations.delete(handle.id);
+            return;
+        }
+        const client = await this.client(this.requestTimeoutMs);
+        // The delete call and the verification share one teardown, so a lost
+        // response or a request that crosses `requestTimeoutMs` must not report
+        // failure without first checking the authoritative list. If the provider
+        // actually performed the delete, `waitUntilDeleted` will confirm it and
+        // teardown resolves cleanly; only an unverified failure retains ownership.
+        let deleteError;
+        try {
+            await withDeadline(client.vms.delete({ vmId: handle.id }), this.requestTimeoutMs, () => new FreestyleLookupTimeoutError(this.requestTimeoutMs, "delete request"));
+        }
+        catch (error) {
+            deleteError = error;
+        }
+        const verified = await this.waitUntilDeleted(handle.id);
+        if (!verified) {
+            if (deleteError !== undefined) {
+                // Delete request failed and the VM is still visible: surface the
+                // original transport failure so the caller can decide whether to
+                // retry, and retain the registration so cleanup remains reachable.
+                throw deleteError;
+            }
+            // Retain the registration so a caller can retry cleanup.
+            throw new FreestyleDestroyVerificationError(handle.id, this.lifecycleSettleTimeoutMs);
+        }
+        this.registrations.delete(handle.id);
+    }
+    /**
+     * Drain in-flight orphaned-create reconciliations.
+     *
+     * A `launch()` whose client-side deadline fires may schedule a background
+     * delete for a VM the provider still allocates. Short-lived processes and
+     * tests must wait for those before exiting, or the reconciliation is what
+     * gets leaked. Long-lived hosts can ignore it; either way, this method is
+     * safe to call more than once and does not surface reconciliation errors.
+     */
+    async close() {
+        if (this.reconciliations.size === 0) {
+            return;
+        }
+        await Promise.allSettled([...this.reconciliations]);
+    }
+    /**
+     * Terminate a create that outlived its client-side deadline.
+     *
+     * Called only for names this runtime generated with a fresh UUID, so a
+     * match in the provider listing is unambiguously our own late allocation.
+     * All failure modes are silent by design: `launch()` has already rejected,
+     * so there is no caller to raise to. `close()` awaits pending
+     * reconciliations before the process exits.
+     */
+    async reconcileOrphanedCreate(pending, name) {
+        let vmId;
+        try {
+            const settled = await pending;
+            if (settled
+                && typeof settled === "object"
+                && typeof settled.vmId === "string"
+                && settled.vmId.trim()) {
+                vmId = settled.vmId.trim();
+            }
+        }
+        catch {
+            // Create ultimately rejected — nothing was allocated, nothing to clean.
+            return;
+        }
+        if (!vmId) {
+            // No id came back. Fall back to the authoritative listing to find any
+            // row the provider allocated under the name we asked for.
+            try {
+                const owned = await this.listOwned({ states: null });
+                const match = owned.find((vm) => vm.name === name);
+                if (!match) {
+                    return;
+                }
+                vmId = match.id;
+            }
+            catch {
+                return;
+            }
+        }
+        // Register just long enough to satisfy destroy()'s ownership gate and
+        // then reuse the same verified-absence teardown the normal path uses.
+        this.register(vmId, { owned: true, labels: {}, state: "STARTED" });
+        try {
+            await this.destroy({ id: vmId, state: "STARTED", homeDir: this.defaultHomeDir });
+        }
+        catch {
+            // Best effort. The next `listOwned` sweep or a follow-up cleanup pass
+            // is the safety net; there is no useful action from here.
+        }
+    }
+    trackReconciliation(work) {
+        this.reconciliations.add(work);
+        void work.finally(() => this.reconciliations.delete(work));
+    }
+    async client(requestTimeoutMs) {
+        if (this.injectedClientFactory) {
+            return this.injectedClientFactory(requestTimeoutMs);
+        }
+        return createOfficialFreestyleClient({ apiKey: this.apiKey, ...(this.baseUrl ? { baseUrl: this.baseUrl } : {}) }, requestTimeoutMs);
+    }
+    async vm(id, requestTimeoutMs) {
+        const client = await this.client(requestTimeoutMs);
+        return client.vms.ref({ vmId: id });
+    }
+    register(id, next) {
+        const existing = this.registrations.get(id);
+        this.registrations.set(id, {
+            owned: existing?.owned === true || next.owned,
+            labels: hasEntries(next.labels) ? { ...next.labels } : existing?.labels ?? {},
+            state: next.state ?? existing?.state,
+        });
+    }
+    requireRegistered(handle) {
+        const entry = this.registrations.get(handle.id);
+        if (!entry) {
+            throw new Error(`Freestyle runtime handle "${handle.id}" is not attached`);
+        }
+        return entry;
+    }
+    async listRemote(timeoutMs, operation) {
+        const client = await this.client(timeoutMs);
+        const response = await withDeadline(client.vms.list(), timeoutMs, () => new FreestyleLookupTimeoutError(timeoutMs, operation));
+        if (!response || !Array.isArray(response.vms)) {
+            throw new Error("Freestyle VM list response is malformed");
+        }
+        const malformedIndex = response.vms.findIndex((item) => !isFreestyleVmListItem(item));
+        if (malformedIndex !== -1) {
+            throw new Error(`Freestyle VM list item ${malformedIndex} is malformed`);
+        }
+        return response.vms;
+    }
+    async remoteById(id, timeoutMs) {
+        const items = await this.listRemote(timeoutMs, `lookup for VM "${id}"`);
+        return items.find((item) => item.id === id) ?? null;
+    }
+    async requireRemote(id) {
+        const item = await this.remoteById(id, this.lookupTimeoutMs);
+        if (!item || item.deleted) {
+            throw new Error(`Freestyle VM "${id}" is no longer available`);
+        }
+        return item;
+    }
+    async waitForState(id, expected, description) {
+        const deadline = Date.now() + this.lifecycleSettleTimeoutMs;
+        let lastState = "unknown";
+        for (;;) {
+            const remainingMs = Math.max(1, deadline - Date.now());
+            const item = await this.remoteById(id, Math.min(this.lookupTimeoutMs, remainingMs));
+            if (!item || item.deleted) {
+                throw new Error(`Freestyle VM "${id}" disappeared while waiting for ${description}`);
+            }
+            lastState = item.state;
+            if (expected.has(item.state)) {
+                return item;
+            }
+            if (item.state === "lost") {
+                throw new Error(`Freestyle VM "${id}" became lost while waiting for ${description}`);
+            }
+            if (Date.now() >= deadline) {
+                throw new FreestyleLifecycleTimeoutError(id, description, lastState, this.lifecycleSettleTimeoutMs);
+            }
+            await delay(this.pollIntervalMs);
+        }
+    }
+    async waitUntilDeleted(id) {
+        const deadline = Date.now() + this.lifecycleSettleTimeoutMs;
+        for (;;) {
+            const remainingMs = Math.max(1, deadline - Date.now());
+            const item = await this.remoteById(id, Math.min(this.lookupTimeoutMs, remainingMs));
+            // Freestyle may keep a soft-deleted row in vms.list; deleted:true is as
+            // authoritative as absence and must not be mistaken for a leaked VM.
+            if (!item || item.deleted === true) {
+                return true;
+            }
+            if (Date.now() >= deadline) {
+                return false;
+            }
+            await delay(this.pollIntervalMs);
+        }
+    }
+    ownedName(requested) {
+        if (!requested) {
+            return `${this.namePrefix}-${randomUUID().replaceAll("-", "").slice(0, 16)}`;
+        }
+        if (this.isOwnedName(requested)) {
+            return requested;
+        }
+        const slug = requested
+            .normalize("NFKC")
+            .replace(/[^A-Za-z0-9._-]+/gu, "-")
+            .replace(/^-+|-+$/gu, "") || "sandbox";
+        const digest = createHash("sha256").update(requested).digest("hex").slice(0, 8);
+        return `${this.namePrefix}-${slug}-${digest}`;
+    }
+    isOwnedName(name) {
+        return name === this.namePrefix || name.startsWith(`${this.namePrefix}-`);
+    }
+}
+/**
+ * Construction-time reconciliation between SDK-free declarations and the
+ * implemented surface. The registry is exhaustive over every capability key.
+ * Behavioral false claims (warmLease/lifecycle) may retain probe methods; a
+ * true claim is never allowed without the necessary implementation.
+ */
+function assertFreestyleCapabilityImplementation(runtime) {
+    const workflowRegistry = {
+        pty: false,
+        snapshots: false,
+        isolation: "strong",
+        persistentHandle: typeof runtime.getById === "function",
+        streamingLogs: false,
+    };
+    for (const key of Object.keys(workflowRegistry)) {
+        if (workflowRegistry[key] !== freestyleWorkflowCapabilities[key]) {
+            throw new FreestyleCapabilityMismatchError(String(key));
+        }
+    }
+    const outerRegistry = {
+        warmLease: false,
+        lifecycle: typeof runtime.start === "function" && typeof runtime.stop === "function",
+    };
+    if (freestyleSandboxCapabilities.warmLease && !outerRegistry.warmLease) {
+        throw new FreestyleCapabilityMismatchError("warmLease");
+    }
+    if (freestyleSandboxCapabilities.lifecycle && !outerRegistry.lifecycle) {
+        throw new FreestyleCapabilityMismatchError("lifecycle");
+    }
+    const observedRegistry = {
+        cleanupVerified: typeof runtime.destroy === "function" && typeof runtime.listOwned === "function",
+        fork: false,
+        lifecycle: outerRegistry.lifecycle,
+        neverIdle: false,
+        ptySurvival: false,
+        snapshotCapture: false,
+        streamingExec: false,
+        warmLease: outerRegistry.warmLease,
+    };
+    for (const key of Object.keys(observedRegistry)) {
+        if (freestyleObservedCapabilities[key] && !observedRegistry[key]) {
+            throw new FreestyleCapabilityMismatchError(String(key));
+        }
+    }
+}
+export function buildFreestyleCommand(command, options = {}) {
+    const statements = [];
+    for (const [name, value] of Object.entries(options.env ?? {})) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)) {
+            throw new Error(`Invalid Freestyle environment variable name "${name}"`);
+        }
+        statements.push(`export ${name}=${shellSingleQuote(value)}`);
+    }
+    if (options.cwd) {
+        statements.push(`cd ${shellSingleQuote(options.cwd)} || exit $?`);
+    }
+    statements.push(command);
+    return statements.join("\n");
+}
+function validatePersistence(value) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Freestyle persistence policy is required");
+    }
+    if (value.type === "persistent" || value.type === "ephemeral") {
+        return { type: value.type };
+    }
+    if (value.type === "sticky"
+        && Number.isFinite(value.priority)
+        && Number.isInteger(value.priority)) {
+        return { type: "sticky", priority: value.priority };
+    }
+    throw new Error("Freestyle persistence policy is invalid");
+}
+function validateIdleTimeout(value) {
+    if (value === undefined || value === null) {
+        return value;
+    }
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error("Freestyle idleTimeoutSeconds must be null or a non-negative number");
+    }
+    return Math.ceil(value);
+}
+function validateNamePrefix(value) {
+    const prefix = required(value, "Freestyle name prefix");
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(prefix)) {
+        throw new Error("Freestyle name prefix must contain only letters, numbers, dot, underscore, or hyphen");
+    }
+    return prefix;
+}
+function required(value, description) {
+    const normalized = value?.trim();
+    if (!normalized) {
+        throw new Error(`${description} is required`);
+    }
+    return normalized;
+}
+function optionalTrimmed(value) {
+    const normalized = value?.trim();
+    return normalized || undefined;
+}
+function positiveDuration(value, fallback) {
+    return value !== undefined && Number.isFinite(value) && value > 0
+        ? Math.ceil(value)
+        : fallback;
+}
+function hasEntries(value) {
+    return !!value && Object.keys(value).length > 0;
+}
+function isFreestyleVmListItem(value) {
+    return Boolean(value
+        && typeof value === "object"
+        && typeof value.id === "string"
+        && value.id.trim()
+        && typeof value.state === "string"
+        && value.state.trim());
+}
+function normalizeState(state) {
+    switch (state.toLowerCase()) {
+        case "running":
+            return "STARTED";
+        case "stopped":
+        case "suspended":
+            return "STOPPED";
+        case "building":
+        case "starting":
+            return "STARTING";
+        case "stopping":
+        case "suspending":
+            return "STOPPING";
+        case "lost":
+            return "FAILED";
+        default:
+            return state.toUpperCase();
+    }
+}
+function normalizeRequestedState(state) {
+    const normalized = state.toUpperCase();
+    if (normalized === "RUNNING")
+        return "STARTED";
+    if (normalized === "PAUSED" || normalized === "SUSPENDED")
+        return "STOPPED";
+    return normalized;
+}
+function matchesState(item, states) {
+    if (item.deleted)
+        return false;
+    if (states === null)
+        return true;
+    const actual = normalizeState(item.state);
+    return states.some((state) => normalizeRequestedState(state) === actual);
+}
+function matchesListedState(item, states, includeDeleted) {
+    if (item.deleted && !includeDeleted)
+        return false;
+    if (states === null)
+        return true;
+    const actual = normalizeState(item.state);
+    return states.some((state) => normalizeRequestedState(state) === actual);
+}
+function combineOutput(stdout, stderr) {
+    if (stdout && stderr) {
+        return stdout.endsWith("\n") || stderr.startsWith("\n")
+            ? `${stdout}${stderr}`
+            : `${stdout}\n${stderr}`;
+    }
+    return stdout || stderr || "";
+}
+function parentDirectory(destination) {
+    const normalized = destination.trim().replace(/\/+$/gu, "");
+    const index = normalized.lastIndexOf("/");
+    return index > 0 ? normalized.slice(0, index) : null;
+}
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+async function withDeadline(operation, timeoutMs, timeoutError) {
+    let timer;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(timeoutError()), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function delay(timeoutMs) {
+    return new Promise((resolve) => setTimeout(resolve, timeoutMs));
+}
+/**
+ * Consume a promise's eventual settlement without acting on it.
+ *
+ * Used when `launch()` has already rejected and there is no productive
+ * reconciliation to run (e.g. a caller-supplied name we cannot uniquely
+ * correlate). Without this, a late create rejection would surface as an
+ * unhandledRejection warning even though nothing wants the result.
+ */
+async function swallow(operation) {
+    try {
+        await operation;
+    }
+    catch {
+        // Ignored on purpose.
+    }
+}
+//# sourceMappingURL=runtime.js.map