@agent-relay/cloud 12.0.0-rc.0 → 12.1.0

package/dist/fleet-sandbox.d.ts

@@ -1,8 +1,16 @@
+/**
+ * Cloud may hand back the gateway route owned by a provisioned sandbox. This
+ * is deliberately an exact-origin allowlist: a route is control-plane input,
+ * not a caller-controlled SDK override.
+ */
+export declare const CANONICAL_RELAYCAST_ORIGIN = "https://cast.agentrelay.com";
+export declare const AGENT37_RELAYCAST_ORIGIN = "https://agent37-cast.agentrelay.com";
 export type CloudFleetSandboxRequestOptions = {
     apiUrl?: string;
     signal?: AbortSignal;
     timeoutMs?: number;
 };
+export type CloudFleetSandboxProviderId = 'daytona' | 'e2b' | 'vercel' | 'freestyle' | 'agent37' | 'microsandbox';
 /**
  * Carries every safe identifier Cloud returned when provisioning failed after
  * the request may have created a billable sandbox.
@@ -11,11 +19,16 @@ export declare class CloudFleetSandboxProvisionError extends Error {
     readonly cloudWorkspaceId?: string;
     readonly sandboxId?: string;
     readonly nodeName?: string;
+    readonly providerId?: CloudFleetSandboxProviderId;
+    /** A 2xx response proved this exact caller-owned sandbox was provisioned. */
+    readonly confirmedProvisioned: boolean;
     readonly outcomeUnknown: boolean;
     constructor(message: string, identity?: {
         cloudWorkspaceId?: string;
         sandboxId?: string;
         nodeName?: string;
+        providerId?: CloudFleetSandboxProviderId;
+        confirmedProvisioned?: boolean;
         outcomeUnknown?: boolean;
         cause?: unknown;
     });
@@ -23,23 +36,56 @@ export declare class CloudFleetSandboxProvisionError extends Error {
 export type EnsureCloudFleetSandboxInput = {
     /** Cloud UUID or unified rw_* workspace id. */
     workspaceId: string;
+    /** Caller-declared one-time Cloud identity used to resume a cut-off provision. */
+    sandboxId?: string;
     name?: string;
     requiredCapability: string;
     maxAgents?: number;
     mountRelayfile?: boolean;
+    /**
+     * Relayfile directory subtrees to materialize in the sandbox. Each path
+     * must use the explicit `/path/**` subtree form accepted by Cloud.
+     */
+    relayfilePaths?: readonly string[];
     forceProvision?: boolean;
+    /** Constrain provisioning to a provider that Cloud has enabled for routing. */
+    providerId?: CloudFleetSandboxProviderId;
+    /** Provider-neutral semantics; Cloud owns the provider decision. */
+    workloadProfile?: CloudFleetSandboxWorkloadProfile;
     waitTimeoutMs?: number;
+    /**
+     * Repositories to clone into `/srv/agent-workforce/<name>` inside the
+     * provisioned sandbox. Each entry is a bare `owner/name`; cloud validates
+     * the shape on the wire before the sandbox script ever sees it.
+     *
+     * Required for the factory-cloud dispatch path so its worker_cwd
+     * (`/srv/agent-workforce/<repo>`) is resolvable on the JIT node. Cloud
+     * PR #3212 implements the ensure-side; this helper just plumbs it through.
+     */
+    repos?: readonly string[];
 };
-export type CloudFleetSandboxReady = {
+export type CloudFleetSandboxWorkloadProfile = 'standard' | 'long-running-agent' | 'standard-long-running-agent';
+type CloudFleetSandboxReadyBase = {
     outcome: 'provisioned';
     cloudWorkspaceId: string;
     nodeId: string;
     nodeName: string;
     sandboxId: string;
+    providerSandboxId?: string;
     relayWorkspaceId: string;
+    /** Closed server-owned Relaycast contract when Cloud returned one. Required for Agent37. */
+    relaycastTarget?: CloudFleetRelaycastTarget;
     relayfileMounted: boolean;
     relayfileMountPath?: string;
+    providerId?: CloudFleetSandboxProviderId;
 };
+/** Daytona responses always carry the independently attested provider UUID. */
+export type CloudFleetSandboxReady = (CloudFleetSandboxReadyBase & {
+    providerId: 'daytona';
+    providerSandboxId: string;
+}) | (CloudFleetSandboxReadyBase & {
+    providerId?: Exclude<CloudFleetSandboxProviderId, 'daytona'>;
+});
 export type CloudFleetSandboxReused = {
     outcome: 'reused';
     cloudWorkspaceId: string;
@@ -48,22 +94,46 @@ export type CloudFleetSandboxReused = {
     status: string;
     activeAgents: number | null;
     maxAgents: number | null;
+    providerId?: CloudFleetSandboxProviderId;
+    /** Closed server-owned Relaycast contract when Cloud returned one. Required for Agent37. */
+    relaycastTarget?: CloudFleetRelaycastTarget;
 };
-export type CloudFleetSandboxProvisioningTimeout = {
+type CloudFleetSandboxProvisioningTimeoutBase = {
     outcome: 'provisioning_timeout';
     cloudWorkspaceId: string;
     sandboxId: string;
+    providerSandboxId?: string;
     relayWorkspaceId: string;
+    relaycastTarget?: CloudFleetRelaycastTarget;
     nodeName: string;
     waitedMs: number;
+    providerId?: CloudFleetSandboxProviderId;
 };
+/** Daytona timeout responses also prove the provider UUID before they are surfaced. */
+export type CloudFleetSandboxProvisioningTimeout = (CloudFleetSandboxProvisioningTimeoutBase & {
+    providerId: 'daytona';
+    providerSandboxId: string;
+}) | (CloudFleetSandboxProvisioningTimeoutBase & {
+    providerId?: Exclude<CloudFleetSandboxProviderId, 'daytona'>;
+});
 export type EnsureCloudFleetSandboxResult = CloudFleetSandboxReady | CloudFleetSandboxReused | CloudFleetSandboxProvisioningTimeout;
 export type DeleteCloudFleetSandboxInput = {
     cloudWorkspaceId: string;
     sandboxId: string;
+    providerId?: CloudFleetSandboxProviderId;
+};
+export type CloudFleetRelaycastRoute = 'canonical' | 'agent37-isolated';
+export type CloudFleetRelaycastTarget = {
+    route: CloudFleetRelaycastRoute;
+    baseUrl: string;
+    workspaceId: string;
+    relaycastApiKey: string;
 };
+/** Validate Cloud's closed Relaycast route, identity, and scoped credential contract. */
+export declare function normalizeRelaycastTarget(value: unknown): CloudFleetRelaycastTarget;
 /** Resolve a Relay workspace in Cloud, provision/reuse a node, and wait for readiness. */
 export declare function ensureCloudFleetSandbox(input: EnsureCloudFleetSandboxInput, options?: CloudFleetSandboxRequestOptions): Promise<EnsureCloudFleetSandboxResult>;
-/** Best-effort-safe deletion for a Cloud-owned Daytona fleet sandbox. */
+/** Best-effort-safe deletion for a Cloud-owned fleet sandbox. */
 export declare function deleteCloudFleetSandbox(input: DeleteCloudFleetSandboxInput, options?: CloudFleetSandboxRequestOptions): Promise<void>;
+export {};
 //# sourceMappingURL=fleet-sandbox.d.ts.map

package/dist/fleet-sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fleet-sandbox.d.ts","sourceRoot":"","sources":["../src/fleet-sandbox.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;gBAG/B,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE;QACR,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,KAAK,CAAC,EAAE,OAAO,CAAC;KACZ;CAST;AAED,MAAM,MAAM,4BAA4B,GAAG;IACzC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,aAAa,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,QAAQ,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG;IACjD,OAAO,EAAE,sBAAsB,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GACrC,sBAAsB,GACtB,uBAAuB,GACvB,oCAAoC,CAAC;AAEzC,MAAM,MAAM,4BAA4B,GAAG;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAgJF,0FAA0F;AAC1F,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,4BAA4B,EACnC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,6BAA6B,CAAC,CA+ExC;AAED,yEAAyE;AACzE,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,4BAA4B,EACnC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAsBf"}
+{"version":3,"file":"fleet-sandbox.d.ts","sourceRoot":"","sources":["../src/fleet-sandbox.ts"],"names":[],"mappings":"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"}

package/dist/fleet-sandbox.js

@@ -2,7 +2,23 @@ import { authorizedApiFetch, ensureCloudSession } from './auth.js';
 import { redactCredentialValues } from './redact.js';
 import { defaultApiUrl } from './types.js';
 const CLOUD_WORKSPACE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const DEFAULT_ENSURE_TIMEOUT_MS = 120_000;
+const CLOUD_SANDBOX_ID_PATTERN = /^sbx_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const DAYTONA_PROVIDER_SANDBOX_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * Cloud may hand back the gateway route owned by a provisioned sandbox. This
+ * is deliberately an exact-origin allowlist: a route is control-plane input,
+ * not a caller-controlled SDK override.
+ */
+export const CANONICAL_RELAYCAST_ORIGIN = 'https://cast.agentrelay.com';
+export const AGENT37_RELAYCAST_ORIGIN = 'https://agent37-cast.agentrelay.com';
+const TRUSTED_RELAYCAST_ORIGINS = new Set([CANONICAL_RELAYCAST_ORIGIN, AGENT37_RELAYCAST_ORIGIN]);
+const DEFAULT_RESOLUTION_TIMEOUT_MS = 120_000;
+// Mounted provisioning can spend up to 240s completing the initial Relayfile
+// sync, then up to 90s waiting for the enrolled node to report ready. Leave a
+// bounded margin for Daytona creation and credential setup so the client does
+// not abandon a successful server-side request without receiving its sandbox
+// identity (which prevents the CLI from cleaning it up safely).
+const DEFAULT_ENSURE_TIMEOUT_MS = 480_000;
 const DEFAULT_DELETE_TIMEOUT_MS = 30_000;
 /**
  * Carries every safe identifier Cloud returned when provisioning failed after
@@ -12,6 +28,9 @@ export class CloudFleetSandboxProvisionError extends Error {
     cloudWorkspaceId;
     sandboxId;
     nodeName;
+    providerId;
+    /** A 2xx response proved this exact caller-owned sandbox was provisioned. */
+    confirmedProvisioned;
     outcomeUnknown;
     constructor(message, identity = {}) {
         super(message, identity.cause === undefined ? undefined : { cause: identity.cause });
@@ -19,9 +38,21 @@ export class CloudFleetSandboxProvisionError extends Error {
         this.cloudWorkspaceId = identity.cloudWorkspaceId;
         this.sandboxId = identity.sandboxId;
         this.nodeName = identity.nodeName;
-        this.outcomeUnknown = identity.outcomeUnknown === true;
+        this.providerId = identity.providerId;
+        this.confirmedProvisioned = identity.confirmedProvisioned === true;
+        this.outcomeUnknown = !this.confirmedProvisioned && identity.outcomeUnknown === true;
     }
 }
+class CloudFleetSandboxIdentityMismatchError extends Error {
+}
+const CLOUD_FLEET_SANDBOX_PROVIDER_IDS = [
+    'daytona',
+    'e2b',
+    'vercel',
+    'freestyle',
+    'agent37',
+    'microsandbox',
+];
 function isObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -29,6 +60,53 @@ function readString(payload, key) {
     const value = payload[key];
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
+function normalizeRelaycastOrigin(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`Cloud fleet sandbox response has an invalid ${field}.`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(value.trim());
+    }
+    catch {
+        throw new Error(`Cloud fleet sandbox response has an invalid ${field}.`);
+    }
+    if (parsed.protocol !== 'https:' ||
+        parsed.username ||
+        parsed.password ||
+        parsed.port ||
+        parsed.search ||
+        parsed.hash ||
+        (parsed.pathname !== '' && parsed.pathname !== '/') ||
+        !TRUSTED_RELAYCAST_ORIGINS.has(parsed.origin)) {
+        throw new Error(`Cloud fleet sandbox response has an untrusted ${field}.`);
+    }
+    return parsed.origin;
+}
+/** Validate Cloud's closed Relaycast route, identity, and scoped credential contract. */
+export function normalizeRelaycastTarget(value) {
+    if (!isObject(value)) {
+        throw new Error('Cloud fleet sandbox response is missing relaycastTarget.');
+    }
+    const route = readString(value, 'route');
+    if (route !== 'canonical' && route !== 'agent37-isolated') {
+        throw new Error('Cloud fleet sandbox response has an unknown Relaycast route.');
+    }
+    const baseUrl = normalizeRelaycastOrigin(value.baseUrl, 'relaycastTarget.baseUrl');
+    const expectedOrigin = route === 'canonical' ? CANONICAL_RELAYCAST_ORIGIN : AGENT37_RELAYCAST_ORIGIN;
+    if (baseUrl !== expectedOrigin) {
+        throw new Error('Cloud fleet sandbox response mapped Relaycast route to the wrong origin.');
+    }
+    const workspaceId = readString(value, 'workspaceId');
+    if (!workspaceId) {
+        throw new Error('Cloud fleet sandbox response is missing relaycastTarget.workspaceId.');
+    }
+    const relaycastApiKey = readString(value, 'relaycastApiKey');
+    if (!relaycastApiKey || !/^rk_live_[A-Za-z0-9_-]+$/.test(relaycastApiKey)) {
+        throw new Error('Cloud fleet sandbox response has an invalid Relaycast API key.');
+    }
+    return { route, baseUrl, workspaceId, relaycastApiKey };
+}
 function readNumber(payload, key) {
     const value = payload[key];
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
@@ -39,6 +117,22 @@ function requiredNumber(payload, key, context) {
         throw new Error(`${context} response is missing ${key}.`);
     return value;
 }
+function assertProviderRelaycastTarget(providerId, target) {
+    if (providerId === 'agent37') {
+        if (!target) {
+            throw new Error('Cloud fleet sandbox response is missing the Agent37 Relaycast target.');
+        }
+        if (target.route !== 'agent37-isolated' || target.baseUrl !== AGENT37_RELAYCAST_ORIGIN) {
+            throw new Error('Cloud fleet sandbox response mapped Agent37 to a non-isolated Relaycast target.');
+        }
+        return;
+    }
+    if (providerId !== undefined && target) {
+        if (target.route !== 'canonical' || target.baseUrl !== CANONICAL_RELAYCAST_ORIGIN) {
+            throw new Error(`Cloud fleet sandbox response mapped ${providerId} to a non-canonical Relaycast target.`);
+        }
+    }
+}
 function boundedSignal(options, defaultTimeoutMs) {
     const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
@@ -77,6 +171,39 @@ function requiredString(payload, key, context) {
         throw new Error(`${context} response is missing ${key}.`);
     return value;
 }
+function validateSandboxIdentity(input) {
+    if (input.sandboxId !== undefined && typeof input.sandboxId !== 'string') {
+        throw new Error('Cloud fleet sandbox sandboxId must be a string.');
+    }
+    if (input.name !== undefined && typeof input.name !== 'string') {
+        throw new Error('Cloud fleet sandbox name must be a string.');
+    }
+    const sandboxId = input.sandboxId?.trim();
+    const name = input.name?.trim();
+    if (input.sandboxId !== undefined && (!sandboxId || !CLOUD_SANDBOX_ID_PATTERN.test(sandboxId))) {
+        throw new Error('Cloud fleet sandbox sandboxId must match lowercase sbx_<UUID> using an RFC 4122 UUID.');
+    }
+    if (sandboxId !== undefined && input.forceProvision !== true) {
+        throw new Error('Cloud fleet sandbox sandboxId requires forceProvision: true.');
+    }
+    if (sandboxId !== undefined && !name) {
+        throw new Error('Cloud fleet sandbox sandboxId requires a node name.');
+    }
+    const longRunning = input.workloadProfile === 'long-running-agent' || input.workloadProfile === 'standard-long-running-agent';
+    if (longRunning && sandboxId !== undefined) {
+        if (input.forceProvision !== true) {
+            throw new Error('Long-running Cloud fleet sandbox requests require forceProvision: true.');
+        }
+        const expectedName = `fleet-sandbox-${sandboxId.slice('sbx_'.length)}`;
+        if (name !== expectedName) {
+            throw new Error(`Long-running Cloud fleet sandbox requests require name '${expectedName}' to preserve the one-to-one sandbox identity.`);
+        }
+    }
+    return {
+        ...(sandboxId === undefined ? {} : { sandboxId }),
+        ...(name === undefined ? {} : { name }),
+    };
+}
 async function resolveCloudWorkspaceId(workspaceId, auth, signal) {
     const { response, auth: activeAuth } = await authorizedApiFetch(auth, `/api/v1/workspaces/${encodeURIComponent(workspaceId)}/resolve`, { method: 'GET', signal }, { interactive: false });
     const payload = await readJson(response);
@@ -93,29 +220,105 @@ async function resolveCloudWorkspaceId(workspaceId, auth, signal) {
         auth: activeAuth,
     };
 }
-function normalizeEnsureResult(payload, cloudWorkspaceId) {
+function readProviderId(payload, exactProviderRequested) {
+    const value = readString(payload, 'providerId');
+    if (value === undefined)
+        return undefined;
+    if (CLOUD_FLEET_SANDBOX_PROVIDER_IDS.includes(value)) {
+        return value;
+    }
+    if (exactProviderRequested) {
+        throw new Error('Cloud fleet sandbox response has an unknown providerId.');
+    }
+    return undefined;
+}
+function assertExpectedSandboxIdentity(payload, expectedSandboxId) {
+    const sandboxId = requiredString(payload, 'sandboxId', 'Cloud fleet sandbox');
+    if (sandboxId !== expectedSandboxId) {
+        throw new CloudFleetSandboxIdentityMismatchError(`Cloud returned sandboxId ${sandboxId} instead of requested sandboxId ${expectedSandboxId}.`);
+    }
+}
+/** Daytona's control-plane identity and its provider UUID are distinct. */
+function normalizeProviderSandboxId(payload, providerId) {
+    const providerSandboxId = readString(payload, 'providerSandboxId');
+    if (providerId !== 'daytona')
+        return providerSandboxId;
+    if (!providerSandboxId || !DAYTONA_PROVIDER_SANDBOX_ID_PATTERN.test(providerSandboxId)) {
+        throw new Error('Cloud fleet sandbox response is missing a valid Daytona providerSandboxId.');
+    }
+    return providerSandboxId;
+}
+/**
+ * A malformed success response can still leave a billable sandbox behind. It
+ * is safe to delete only when the response itself confirms the exact
+ * caller-checkpointed identity; never promote a returned or ambient identity
+ * to cleanup authority.
+ */
+function confirmsProvisionedSandboxIdentity(payload, expectedSandboxId, expectedNodeName, requestedProviderId) {
+    if (!isObject(payload) || expectedSandboxId === undefined || requestedProviderId !== 'daytona')
+        return false;
+    // A timeout is also a response from an accepted provision request. When it
+    // echoes the exact caller-checkpointed public identity, Cloud can safely
+    // delete that one sandbox even if the provider UUID is malformed or absent.
+    if (!['provisioned', 'provisioning_timeout'].includes(readString(payload, 'outcome') ?? ''))
+        return false;
+    if (readString(payload, 'sandboxId') !== expectedSandboxId)
+        return false;
+    if (expectedNodeName !== undefined && readString(payload, 'nodeName') !== expectedNodeName)
+        return false;
+    return readString(payload, 'providerId') === requestedProviderId;
+}
+function normalizeEnsureResult(payload, cloudWorkspaceId, expectedSandboxId, expectedNodeName, requestedProviderId) {
     if (!isObject(payload))
         throw new Error('Cloud fleet sandbox response was not valid JSON.');
+    // A caller-declared identity is the cleanup authority. Validate it before
+    // reading any other response field so malformed and future outcomes cannot
+    // make an untrusted public ID eligible for automatic deletion.
+    if (expectedSandboxId !== undefined) {
+        assertExpectedSandboxIdentity(payload, expectedSandboxId);
+    }
     const outcome = readString(payload, 'outcome');
     const nodeName = requiredString(payload, 'nodeName', 'Cloud fleet sandbox');
+    if (expectedSandboxId !== undefined && expectedNodeName !== undefined && nodeName !== expectedNodeName) {
+        throw new CloudFleetSandboxIdentityMismatchError(`Cloud returned nodeName ${nodeName} instead of requested nodeName ${expectedNodeName}.`);
+    }
+    const providerId = readProviderId(payload, requestedProviderId !== undefined);
+    if (requestedProviderId !== undefined && providerId !== requestedProviderId) {
+        throw new Error(providerId === undefined
+            ? `Cloud did not prove requested provider ${requestedProviderId}.`
+            : `Cloud returned provider ${providerId} instead of requested provider ${requestedProviderId}.`);
+    }
     if (outcome === 'provisioned') {
         if (typeof payload.relayfileMounted !== 'boolean') {
             throw new Error('Cloud fleet sandbox response is missing relayfileMounted.');
         }
+        const sandboxId = requiredString(payload, 'sandboxId', 'Cloud fleet sandbox');
+        const providerSandboxId = normalizeProviderSandboxId(payload, providerId);
+        const relayWorkspaceId = requiredString(payload, 'relayWorkspaceId', 'Cloud fleet sandbox');
+        const relaycastTarget = payload.relaycastTarget === undefined ? undefined : normalizeRelaycastTarget(payload.relaycastTarget);
+        if (relaycastTarget !== undefined && relaycastTarget.workspaceId !== relayWorkspaceId) {
+            throw new Error('Cloud fleet sandbox response has mismatched Relaycast workspace identities.');
+        }
+        assertProviderRelaycastTarget(providerId, relaycastTarget);
         return {
             outcome,
             cloudWorkspaceId,
             nodeId: requiredString(payload, 'nodeId', 'Cloud fleet sandbox'),
             nodeName,
-            sandboxId: requiredString(payload, 'sandboxId', 'Cloud fleet sandbox'),
-            relayWorkspaceId: requiredString(payload, 'relayWorkspaceId', 'Cloud fleet sandbox'),
+            sandboxId,
+            ...(providerSandboxId === undefined ? {} : { providerSandboxId }),
+            relayWorkspaceId,
+            ...(relaycastTarget === undefined ? {} : { relaycastTarget }),
             relayfileMounted: payload.relayfileMounted,
+            ...(providerId === undefined ? {} : { providerId }),
             ...(readString(payload, 'relayfileMountPath')
                 ? { relayfileMountPath: readString(payload, 'relayfileMountPath') }
                 : {}),
         };
     }
     if (outcome === 'reused') {
+        const relaycastTarget = payload.relaycastTarget === undefined ? undefined : normalizeRelaycastTarget(payload.relaycastTarget);
+        assertProviderRelaycastTarget(providerId, relaycastTarget);
         return {
             outcome,
             cloudWorkspaceId,
@@ -124,16 +327,28 @@ function normalizeEnsureResult(payload, cloudWorkspaceId) {
             status: requiredString(payload, 'status', 'Cloud fleet sandbox'),
             activeAgents: readNumber(payload, 'activeAgents') ?? null,
             maxAgents: readNumber(payload, 'maxAgents') ?? null,
+            ...(providerId === undefined ? {} : { providerId }),
+            ...(relaycastTarget === undefined ? {} : { relaycastTarget }),
         };
     }
     if (outcome === 'provisioning_timeout') {
+        const sandboxId = requiredString(payload, 'sandboxId', 'Cloud fleet sandbox');
+        const providerSandboxId = normalizeProviderSandboxId(payload, providerId);
+        const relayWorkspaceId = requiredString(payload, 'relayWorkspaceId', 'Cloud fleet sandbox');
+        const relaycastTarget = payload.relaycastTarget === undefined ? undefined : normalizeRelaycastTarget(payload.relaycastTarget);
+        if (relaycastTarget !== undefined && relaycastTarget.workspaceId !== relayWorkspaceId) {
+            throw new Error('Cloud fleet sandbox response has mismatched Relaycast workspace identities.');
+        }
         return {
             outcome,
             cloudWorkspaceId,
-            sandboxId: requiredString(payload, 'sandboxId', 'Cloud fleet sandbox'),
-            relayWorkspaceId: requiredString(payload, 'relayWorkspaceId', 'Cloud fleet sandbox'),
+            sandboxId,
+            ...(providerSandboxId === undefined ? {} : { providerSandboxId }),
+            relayWorkspaceId,
+            ...(relaycastTarget === undefined ? {} : { relaycastTarget }),
             nodeName,
             waitedMs: requiredNumber(payload, 'waitedMs', 'Cloud fleet sandbox'),
+            ...(providerId === undefined ? {} : { providerId }),
         };
     }
     throw new Error('Cloud fleet sandbox response has an unknown outcome.');
@@ -146,11 +361,15 @@ export async function ensureCloudFleetSandbox(input, options = {}) {
         throw new Error('A workspace ID is required to provision a fleet sandbox.');
     if (!requiredCapability)
         throw new Error('A spawn capability is required to provision a fleet sandbox.');
+    const sandboxIdentity = validateSandboxIdentity(input);
+    if (input.relayfilePaths !== undefined && input.relayfilePaths.length === 0) {
+        throw new Error('At least one Relayfile subtree path is required when relayfilePaths is provided.');
+    }
     const session = await ensureCloudSession({
         apiUrl: options.apiUrl || defaultApiUrl(),
         interactive: false,
     });
-    const resolutionSignal = boundedSignal(options, DEFAULT_ENSURE_TIMEOUT_MS);
+    const resolutionSignal = boundedSignal(options, DEFAULT_RESOLUTION_TIMEOUT_MS);
     const resolved = await resolveCloudWorkspaceId(workspaceId, session.auth, resolutionSignal);
     const signal = boundedSignal(options, DEFAULT_ENSURE_TIMEOUT_MS);
     let response;
@@ -161,53 +380,87 @@ export async function ensureCloudFleetSandbox(input, options = {}) {
             body: JSON.stringify({
                 workspaceId: resolved.cloudWorkspaceId,
                 requiredCapability,
-                ...(input.name ? { name: input.name } : {}),
+                ...(sandboxIdentity.sandboxId === undefined ? {} : { sandboxId: sandboxIdentity.sandboxId }),
+                ...(sandboxIdentity.name === undefined ? {} : { name: sandboxIdentity.name }),
                 ...(input.maxAgents !== undefined ? { maxAgents: input.maxAgents } : {}),
                 ...(input.mountRelayfile !== undefined ? { mountRelayfile: input.mountRelayfile } : {}),
+                ...(input.relayfilePaths === undefined ? {} : { relayfilePaths: [...input.relayfilePaths] }),
                 ...(input.forceProvision !== undefined ? { forceProvision: input.forceProvision } : {}),
+                ...(input.providerId !== undefined ? { providerId: input.providerId } : {}),
+                ...(input.workloadProfile !== undefined ? { workloadProfile: input.workloadProfile } : {}),
                 ...(input.waitTimeoutMs !== undefined ? { waitTimeoutMs: input.waitTimeoutMs } : {}),
+                ...(input.repos !== undefined && input.repos.length > 0 ? { repos: [...input.repos] } : {}),
             }),
         }, { interactive: false }));
     }
     catch (error) {
         throw new CloudFleetSandboxProvisionError(redactCredentialValues(`Cloud fleet sandbox request ended without a complete response: ${error instanceof Error ? error.message : String(error)}`), {
             cloudWorkspaceId: resolved.cloudWorkspaceId,
+            ...(sandboxIdentity.sandboxId === undefined ? {} : { sandboxId: sandboxIdentity.sandboxId }),
             ...(input.name ? { nodeName: input.name } : {}),
+            ...(input.providerId ? { providerId: input.providerId } : {}),
             outcomeUnknown: true,
             cause: error,
         });
     }
     const payload = await readJson(response);
     if (!response.ok) {
+        const returnedSandboxId = isObject(payload) ? readString(payload, 'sandboxId') : undefined;
+        if (sandboxIdentity.sandboxId !== undefined &&
+            returnedSandboxId !== undefined &&
+            returnedSandboxId !== sandboxIdentity.sandboxId) {
+            const mismatch = new CloudFleetSandboxIdentityMismatchError(`Cloud returned sandboxId ${returnedSandboxId} instead of requested sandboxId ${sandboxIdentity.sandboxId}.`);
+            throw new CloudFleetSandboxProvisionError(mismatch.message, {
+                cloudWorkspaceId: resolved.cloudWorkspaceId,
+                ...(sandboxIdentity.name === undefined ? {} : { nodeName: sandboxIdentity.name }),
+                ...(input.providerId === undefined ? {} : { providerId: input.providerId }),
+                outcomeUnknown: true,
+                cause: mismatch,
+            });
+        }
         const error = endpointError('provision the fleet sandbox', response, payload);
+        // Gateway/server failures can arrive after Cloud accepted the ensure
+        // request but before it could return an identity. Keep every 5xx failure
+        // replayable as an unknown outcome, even for legacy custom-name callers;
+        // never copy an unverified response ID into cleanup authority.
+        if (response.status >= 500) {
+            throw new CloudFleetSandboxProvisionError(error.message, {
+                cloudWorkspaceId: resolved.cloudWorkspaceId,
+                ...(sandboxIdentity.sandboxId === undefined ? {} : { sandboxId: sandboxIdentity.sandboxId }),
+                ...(sandboxIdentity.name === undefined ? {} : { nodeName: sandboxIdentity.name }),
+                ...(input.providerId === undefined ? {} : { providerId: input.providerId }),
+                outcomeUnknown: true,
+                cause: error,
+            });
+        }
         if (isObject(payload) && readString(payload, 'sandboxId')) {
             throw new CloudFleetSandboxProvisionError(error.message, {
                 cloudWorkspaceId: resolved.cloudWorkspaceId,
-                sandboxId: readString(payload, 'sandboxId'),
-                nodeName: readString(payload, 'nodeName') ?? input.name,
+                ...(sandboxIdentity.sandboxId === undefined ? {} : { sandboxId: sandboxIdentity.sandboxId }),
+                ...(sandboxIdentity.name === undefined ? {} : { nodeName: sandboxIdentity.name }),
+                ...(input.providerId === undefined ? {} : { providerId: input.providerId }),
+                outcomeUnknown: true,
                 cause: error,
             });
         }
         throw error;
     }
     try {
-        return normalizeEnsureResult(payload, resolved.cloudWorkspaceId);
+        return normalizeEnsureResult(payload, resolved.cloudWorkspaceId, sandboxIdentity.sandboxId, sandboxIdentity.name, input.providerId);
     }
     catch (error) {
+        const confirmedProvisioned = confirmsProvisionedSandboxIdentity(payload, sandboxIdentity.sandboxId, sandboxIdentity.name, input.providerId);
         throw new CloudFleetSandboxProvisionError(error instanceof Error ? error.message : 'Cloud fleet sandbox response was invalid.', {
             cloudWorkspaceId: resolved.cloudWorkspaceId,
-            ...(isObject(payload) && readString(payload, 'sandboxId')
-                ? { sandboxId: readString(payload, 'sandboxId') }
-                : {}),
-            ...(isObject(payload) && (readString(payload, 'nodeName') ?? input.name)
-                ? { nodeName: readString(payload, 'nodeName') ?? input.name }
-                : {}),
-            outcomeUnknown: true,
+            ...(sandboxIdentity.sandboxId === undefined ? {} : { sandboxId: sandboxIdentity.sandboxId }),
+            ...(sandboxIdentity.name === undefined ? {} : { nodeName: sandboxIdentity.name }),
+            ...(input.providerId === undefined ? {} : { providerId: input.providerId }),
+            ...(confirmedProvisioned ? { confirmedProvisioned: true } : { outcomeUnknown: true }),
             cause: error,
         });
     }
 }
-/** Best-effort-safe deletion for a Cloud-owned Daytona fleet sandbox. */
+/** Best-effort-safe deletion for a Cloud-owned fleet sandbox. */
 export async function deleteCloudFleetSandbox(input, options = {}) {
     const cloudWorkspaceId = input.cloudWorkspaceId.trim();
     const sandboxId = input.sandboxId.trim();
@@ -221,7 +474,10 @@ export async function deleteCloudFleetSandbox(input, options = {}) {
     const { response } = await authorizedApiFetch(session.auth, `/api/v1/fleet/nodes/sandbox/${encodeURIComponent(sandboxId)}`, {
         method: 'DELETE',
         signal,
-        body: JSON.stringify({ workspaceId: cloudWorkspaceId }),
+        body: JSON.stringify({
+            workspaceId: cloudWorkspaceId,
+            ...(input.providerId === undefined ? {} : { providerId: input.providerId }),
+        }),
     }, { interactive: false });
     const payload = await readJson(response);
     if (!response.ok)