@tangle-network/sandbox 0.10.2 → 0.10.4

package/dist/{sandbox-CeimsfC8.js → sandbox-Be9WAqSg.js}

@@ -1,159 +1,6 @@
+import { n as normalizeSessionInfo, r as normalizeRuntimeBackendConfig, t as SandboxRuntimeApi } from "./runtime-api-CYA2DUQw.js";
 import { c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, p as parseErrorResponse, s as QuotaError, t as AuthError, u as StateError } from "./errors-DSz87Rkk.js";
 import { addTokenUsage, readTokenCostUsd, readTokenUsage } from "@tangle-network/agent-core";
-//#region src/backend-config.ts
-const LEGACY_QUESTION_ALIAS_KEY = ["question", "Channel"].join("");
-function parseModelString(model) {
-	const parts = model.split("/");
-	if (parts.length >= 2) return {
-		provider: parts[0],
-		model: parts.slice(1).join("/")
-	};
-	return { model };
-}
-/**
-* Normalize runtime backend config for the wire format.
-*
-* Callers set `backend.profile` (named string or portable AgentProfile).
-* This function generates the native `inlineProfile` shim automatically.
-*/
-function normalizeRuntimeBackendConfig(backend, options = {}) {
-	if (!backend && !options.model) return void 0;
-	if (backend && LEGACY_QUESTION_ALIAS_KEY in backend) throw new Error(`[sandbox-sdk] backend.${LEGACY_QUESTION_ALIAS_KEY} was removed. Use backend.interactions.question instead.`);
-	const portableProfile = backend?.profile && typeof backend.profile !== "string" ? backend.profile : void 0;
-	const inlineProfile = portableProfile ? toBackendProfile(portableProfile) : void 0;
-	const callerInlineProfile = backend?.inlineProfile;
-	if (callerInlineProfile && !inlineProfile) console.warn("[sandbox-sdk] backend.inlineProfile is deprecated. Use backend.profile (AgentPortableProfile) instead.");
-	if (inlineProfile && portableProfile) {
-		const reasoningEffort = portableProfile.model?.reasoningEffort ?? portableProfile.extensions?.[backend?.type ?? ""]?.reasoningEffort;
-		if (typeof reasoningEffort === "string" && reasoningEffort !== "auto" && reasoningEffort !== "none") inlineProfile.reasoningEffort = reasoningEffort;
-	}
-	return {
-		...backend?.type ? { type: backend.type } : {},
-		...typeof backend?.profile === "string" ? { profile: backend.profile } : {},
-		...inlineProfile ? { inlineProfile } : callerInlineProfile ? { inlineProfile: callerInlineProfile } : {},
-		...backend?.model ? { model: backend.model } : options.model ? { model: parseModelString(options.model) } : {},
-		...backend?.server ? { server: backend.server } : {},
-		...backend?.interactions !== void 0 ? { interactions: backend.interactions } : {},
-		...backend?.metadata !== void 0 ? { metadata: backend.metadata } : {}
-	};
-}
-/**
-* Permission keys the sidecar's strict `permission` schema accepts
-* (apps/sidecar/src/schemas/agent-profile-schema.ts → permissionConfigSchema).
-* Any other portable-permission key is a per-tool gate, not a permission, and
-* is routed into `tools` instead of passed through — the sidecar's `.strict()`
-* schema rejects unknown permission keys with `unrecognized_keys`.
-*
-* Name must not carry an UPPERCASE `SIDECAR_`/`ORCHESTRATOR_`-style prefix:
-* obfuscate.sh runs `--rename-globals false`, so a module-global identifier
-* ships verbatim in dist/, and verify-dist.sh bans those prefixes as
-* closed-source leaks.
-*/
-const CANONICAL_PERMISSION_KEYS = new Set([
-	"edit",
-	"bash",
-	"webfetch",
-	"mcp",
-	"doom_loop",
-	"external_directory"
-]);
-function hasAnyProfileResource(resources) {
-	return !!(resources.files?.length || resources.tools?.length || resources.skills?.length || resources.agents?.length || resources.commands?.length || resources.instructions);
-}
-function validateProfileResources(profile) {
-	if (profile.resources !== void 0 && (profile.resources === null || typeof profile.resources !== "object" || Array.isArray(profile.resources))) throw new Error("backend.profile.resources must be an object when provided");
-	if (profile.resources?.plugins?.length) throw new Error("backend.profile.resources.plugins is not supported by the sandbox SDK profile contract; use backend-specific provider profiles for OpenCode plugin resources");
-}
-function toBackendProfile(profile) {
-	validateProfileResources(profile);
-	const permission = {};
-	const derivedTools = {};
-	for (const [rawKey, value] of Object.entries(profile.permissions ?? {})) {
-		const key = rawKey === "network" ? "webfetch" : rawKey;
-		if (CANONICAL_PERMISSION_KEYS.has(key)) permission[key] = value;
-		else if (typeof value === "string") derivedTools[key] = value !== "deny";
-		else console.warn(`[sandbox-sdk] dropping unsupported permission key "${rawKey}": not a canonical sidecar permission and not a string tool gate`);
-	}
-	const tools = {
-		...derivedTools,
-		...profile.tools ?? {}
-	};
-	const mcp = profile.mcp ? Object.fromEntries(Object.entries(profile.mcp).map(([name, config]) => {
-		const c = config;
-		const transport = c.transport;
-		const command = c.command;
-		const hasCommand = Array.isArray(command) ? command.length > 0 : typeof command === "string" && command.trim().length > 0;
-		const isRemote = transport === "http" || transport === "sse" || typeof c.url === "string" && !hasCommand;
-		const enabled = c.enabled;
-		const timeout = c.timeout;
-		if (isRemote) return [name, {
-			type: "remote",
-			url: c.url,
-			...c.headers ? { headers: c.headers } : {},
-			...enabled !== void 0 ? { enabled } : {},
-			...timeout !== void 0 ? { timeout } : {}
-		}];
-		return [name, {
-			type: "local",
-			command: [...Array.isArray(command) ? command : typeof command === "string" ? command.trim().split(/\s+/).filter(Boolean) : [], ...c.args ?? []],
-			...c.env ? { environment: c.env } : {},
-			...enabled !== void 0 ? { enabled } : {},
-			...timeout !== void 0 ? { timeout } : {}
-		}];
-	})) : void 0;
-	const openCodeExtension = profile.extensions?.opencode;
-	const plugins = openCodeExtension?.plugins;
-	if (plugins !== void 0 && (!Array.isArray(plugins) || plugins.some((plugin) => typeof plugin !== "string" || !plugin.trim()))) throw new Error("backend.profile.extensions.opencode.plugins must be an array of non-empty package names");
-	const commands = openCodeExtension?.commands;
-	if (commands !== void 0 && (commands === null || typeof commands !== "object" || Array.isArray(commands))) throw new Error("backend.profile.extensions.opencode.commands must be an object");
-	const profileExtends = openCodeExtension?.extends;
-	if (profileExtends !== void 0 && typeof profileExtends !== "string" && (!Array.isArray(profileExtends) || profileExtends.some((entry) => typeof entry !== "string" || !entry.trim()))) throw new Error("backend.profile.extensions.opencode.extends must be a profile name or array of profile names");
-	const agents = profile.subagents ? Object.fromEntries(Object.entries(profile.subagents).map(([name, subagent]) => [name, {
-		description: subagent.description,
-		prompt: subagent.prompt,
-		model: subagent.model,
-		tools: subagent.tools,
-		permission: subagent.permissions,
-		maxSteps: subagent.maxSteps,
-		...subagent.metadata ?? {}
-	}])) : void 0;
-	return {
-		name: profile.name,
-		description: profile.description,
-		version: profile.version,
-		tags: profile.tags,
-		...profileExtends ? { extends: profileExtends } : {},
-		model: profile.model?.default,
-		small_model: profile.model?.small,
-		...profile.prompt?.systemPrompt ? { systemPrompt: profile.prompt.systemPrompt } : {},
-		...Object.keys(tools).length > 0 ? { tools } : {},
-		...profile.prompt?.instructions?.length ? { instructions: profile.prompt.instructions } : {},
-		...Object.keys(permission).length > 0 ? { permission } : {},
-		...mcp ? { mcp } : {},
-		...profile.connections?.length ? { connections: profile.connections } : {},
-		...agents ? { agent: agents } : {},
-		...profile.resources && hasAnyProfileResource(profile.resources) ? { resources: profile.resources } : {},
-		...profile.hooks ? { hooks: profile.hooks } : {},
-		...profile.modes ? { modes: profile.modes } : {},
-		...commands ? { command: commands } : {},
-		...plugins?.length ? { plugin: plugins } : {},
-		...profile.extensions ? { extensions: profile.extensions } : {}
-	};
-}
-/**
-* Serialize a portable AgentProfile into the sidecar's canonical inline-profile
-* wire shape (validated by inlineProfileSchema in
-* apps/sidecar/src/schemas/agent-profile-schema.ts).
-*
-* Single choke point every product shares: streamPrompt →
-* normalizeRuntimeBackendConfig → toBackendProfile. Exported so callers and the
-* drift-guard test target one contract — the test parses this output with the
-* sidecar's own schema, so any future schema tightening fails here first.
-*/
-function serializeForSidecar(profile) {
-	return toBackendProfile(profile);
-}
-//#endregion
 //#region src/lib/sse-parser.ts
 /**
 * Parse a streaming SSE response body into an async iterable of
@@ -599,244 +446,6 @@ function collectAgentResponseText(events) {
 	return responseText && responseText.trim().length > 0 ? responseText : void 0;
 }
 //#endregion
-//#region src/runtime-api.ts
-/** Internal typed client for routes served by a sandbox runtime. */
-var SandboxRuntimeApi = class {
-	terminals;
-	constructor(transport) {
-		this.transport = transport;
-		this.terminals = {
-			create: (options, request) => this.createTerminal(options, request),
-			input: (terminalId, data, request) => this.writeTerminal(terminalId, data, request),
-			list: () => this.listTerminals(),
-			get: (terminalId) => this.getTerminal(terminalId)
-		};
-	}
-	async health() {
-		await this.transport.ensureRunning();
-		return this.json("/health", { method: "GET" });
-	}
-	async ports() {
-		await this.transport.ensureRunning();
-		return (await this.json("/ports", { method: "GET" })).data?.ports ?? [];
-	}
-	async profiles() {
-		await this.transport.ensureRunning();
-		return this.json("/profiles", { method: "GET" });
-	}
-	async readFiles(paths, options = {}) {
-		if (paths.length === 0) return {
-			files: [],
-			errors: [],
-			stats: {
-				requested: 0,
-				succeeded: 0,
-				failed: 0
-			}
-		};
-		await this.transport.ensureRunning();
-		const files = [];
-		const errors = [];
-		let requested = 0;
-		let succeeded = 0;
-		let failed = 0;
-		for (let offset = 0; offset < paths.length; offset += 100) {
-			const chunk = paths.slice(offset, offset + 100);
-			const params = new URLSearchParams();
-			if (options.sessionId) params.set("sessionId", options.sessionId);
-			const query = params.toString();
-			const payload = await this.json(`/files/read-batch${query ? `?${query}` : ""}`, {
-				method: "POST",
-				body: JSON.stringify({
-					paths: chunk,
-					...options.encoding ? { encoding: options.encoding } : {}
-				})
-			});
-			for (const [path, result] of Object.entries(payload.data.files)) if (result.success) files.push({
-				path,
-				content: result.content,
-				encoding: result.encoding,
-				hash: result.hash,
-				size: result.size,
-				mtime: result.mtime
-			});
-			else errors.push({
-				path,
-				error: result.error,
-				code: result.code
-			});
-			const results = Object.values(payload.data.files);
-			requested += payload.data.stats?.requested ?? chunk.length;
-			succeeded += payload.data.stats?.succeeded ?? results.filter((entry) => entry.success).length;
-			failed += payload.data.stats?.failed ?? results.filter((entry) => !entry.success).length;
-		}
-		return {
-			files,
-			errors,
-			stats: {
-				requested,
-				succeeded,
-				failed
-			}
-		};
-	}
-	async fileTree(path, options = {}) {
-		if (options.maxDepth !== void 0 && (!Number.isInteger(options.maxDepth) || options.maxDepth < 1 || options.maxDepth > 20)) throw new ValidationError("maxDepth must be an integer between 1 and 20");
-		await this.transport.ensureRunning();
-		const params = new URLSearchParams({ path });
-		if (options.maxDepth !== void 0) params.set("maxDepth", String(options.maxDepth));
-		if (options.sessionId) params.set("sessionId", options.sessionId);
-		return (await this.json(`/files/tree?${params}`, { method: "GET" })).data;
-	}
-	async createSession(options) {
-		await this.transport.ensureRunning();
-		const info = normalizeSessionInfo(await this.json("/agents/sessions", {
-			method: "POST",
-			body: JSON.stringify({
-				...options.title !== void 0 ? { title: options.title } : {},
-				...options.parentId !== void 0 ? { parentID: options.parentId } : {},
-				backend: normalizeRuntimeBackendConfig(options.backend)
-			})
-		}));
-		if (!info) throw new ServerError("Session creation response missing session id", 502, {
-			endpoint: "/agents/sessions",
-			origin: "runtime"
-		});
-		return info;
-	}
-	async createTaskSession(options) {
-		await this.transport.ensureRunning();
-		const info = await this.json("/tasks", {
-			method: "POST",
-			body: JSON.stringify({
-				sessionId: options.sessionId,
-				backend: normalizeRuntimeBackendConfig(options.backend),
-				title: options.title,
-				...options.parentSessionId !== void 0 ? { parentSessionId: options.parentSessionId } : {},
-				...options.profile !== void 0 ? { profile: options.profile } : {},
-				...options.isolateFileWrites !== void 0 ? { isolateFileWrites: options.isolateFileWrites } : {}
-			})
-		});
-		if (!info.id) throw new ServerError("Task session creation response missing session id", 502, {
-			endpoint: "/tasks",
-			origin: "runtime"
-		});
-		return info;
-	}
-	async sendSessionMessage(id, request, options = {}) {
-		if (options.timeoutMs !== void 0 && options.timeoutMs <= 0) throw new ValidationError("timeoutMs must be greater than zero");
-		await this.transport.ensureRunning();
-		const headers = new Headers({ "x-no-retry": "true" });
-		if (options.credentials?.apiKey) headers.set("X-Backend-Api-Key", options.credentials.apiKey);
-		if (options.credentials?.baseUrl) headers.set("X-Backend-Base-Url", options.credentials.baseUrl);
-		const timeoutSignal = options.timeoutMs !== void 0 ? AbortSignal.timeout(options.timeoutMs) : void 0;
-		const signal = options.signal && timeoutSignal ? AbortSignal.any([options.signal, timeoutSignal]) : options.signal ?? timeoutSignal;
-		return this.json(`/agents/sessions/${encodeURIComponent(id)}/messages`, {
-			method: "POST",
-			headers,
-			signal,
-			body: JSON.stringify({
-				...request.messageId !== void 0 ? { messageID: request.messageId } : {},
-				parts: request.parts,
-				...request.system !== void 0 ? { system: request.system } : {},
-				...request.agent !== void 0 ? { agent: request.agent } : {},
-				...request.model !== void 0 ? { model: {
-					providerID: request.model.providerId,
-					modelID: request.model.modelId
-				} } : {},
-				...request.reasoningEffort !== void 0 ? { reasoningEffort: request.reasoningEffort } : {},
-				...request.turnId !== void 0 ? { turnId: request.turnId } : {},
-				...request.interactions !== void 0 ? { interactions: request.interactions } : {}
-			})
-		});
-	}
-	async deleteSession(id) {
-		await this.transport.ensureRunning();
-		await this.request(`/agents/sessions/${encodeURIComponent(id)}`, { method: "DELETE" });
-	}
-	async taskSessionChanges(id) {
-		await this.transport.ensureRunning();
-		return this.json(`/tasks/${encodeURIComponent(id)}/changes`, { method: "GET" });
-	}
-	async commitTaskSession(id, options = {}) {
-		await this.transport.ensureRunning();
-		return this.json(`/tasks/${encodeURIComponent(id)}/changes`, {
-			method: "POST",
-			body: JSON.stringify({
-				...options.message !== void 0 ? { message: options.message } : {},
-				...options.files !== void 0 ? { files: options.files } : {}
-			})
-		});
-	}
-	async createTerminal(options = {}, request = {}) {
-		await this.transport.ensureRunning();
-		const params = new URLSearchParams();
-		if (request.sessionId) params.set("sessionId", request.sessionId);
-		const query = params.toString();
-		return (await this.json(`/terminals${query ? `?${query}` : ""}`, {
-			method: "POST",
-			body: JSON.stringify(options)
-		})).data;
-	}
-	async writeTerminal(terminalId, data, request = {}) {
-		await this.transport.ensureRunning();
-		const params = new URLSearchParams();
-		if (request.sessionId) params.set("sessionId", request.sessionId);
-		const query = params.toString();
-		await this.request(`/terminals/${encodeURIComponent(terminalId)}/input${query ? `?${query}` : ""}`, {
-			method: "POST",
-			body: JSON.stringify({ data })
-		});
-	}
-	async listTerminals() {
-		await this.transport.ensureRunning();
-		return (await this.json("/terminals", { method: "GET" })).data ?? [];
-	}
-	async getTerminal(terminalId) {
-		await this.transport.ensureRunning();
-		const response = await this.transport.fetch(`/terminals/${encodeURIComponent(terminalId)}`, { method: "GET" });
-		if (response.status === 404) return null;
-		await this.assertOk(response);
-		return (await response.json()).data;
-	}
-	async json(path, init) {
-		return await (await this.request(path, init)).json();
-	}
-	async request(path, init) {
-		const response = await this.transport.fetch(path, init);
-		await this.assertOk(response);
-		return response;
-	}
-	async assertOk(response) {
-		if (response.ok) return;
-		const body = await response.text();
-		throw parseErrorResponse(response.status, body, void 0, response.headers);
-	}
-};
-function normalizeSessionInfo(raw) {
-	const id = raw.id;
-	if (typeof id !== "string") return null;
-	const status = raw.status || "running";
-	return {
-		id,
-		parentId: typeof raw.parentID === "string" ? raw.parentID : typeof raw.parentId === "string" ? raw.parentId : void 0,
-		status: [
-			"queued",
-			"running",
-			"completed",
-			"failed",
-			"cancelled"
-		].includes(status) ? status : "running",
-		backend: typeof raw.backendType === "string" ? raw.backendType : typeof raw.backend === "string" ? raw.backend : void 0,
-		model: typeof raw.model === "string" ? raw.model : void 0,
-		promptCount: typeof raw.promptCount === "number" ? raw.promptCount : void 0,
-		createdAt: raw.createdAt ? new Date(raw.createdAt) : void 0,
-		startedAt: raw.startedAt ? new Date(raw.startedAt) : void 0,
-		endedAt: raw.endedAt ? new Date(raw.endedAt) : void 0,
-		raw
-	};
-}
-//#endregion
 //#region src/interactive.ts
 /**
 * Handle for one session's interactive harness. Obtained via
@@ -1143,6 +752,13 @@ function isTransientSnapshotVisibilityError(error) {
 	return message.includes("SNAPSHOT_NOT_FOUND") || message.includes("Failed to list snapshot") || message.includes("Storage agent error (404)");
 }
 /**
+* The extra separator is intentional: absolute paths produce `//`, allowing
+* the runtime route wildcard to retain the path's leading slash.
+*/
+function runtimeFilesystemPath(endpoint, path) {
+	return `${endpoint}/${path}`;
+}
+/**
 * Single source of truth for a run's outcome, shared by
 * `prompt`/`task`/`_sessionResult`/turn settling. A run succeeds only when it
 * reached a terminal event, raised no run-level error, hit no approval gate,
@@ -2757,7 +2373,7 @@ var SandboxInstance = class SandboxInstance {
 		const fs = await import("node:fs/promises");
 		const path = await import("node:path");
 		await fs.mkdir(path.dirname(localPath), { recursive: true });
-		const response = await this.runtimeFetch(`/fs/download${remotePath}`, { method: "GET" });
+		const response = await this.runtimeFetch(runtimeFilesystemPath("/fs/download", remotePath), { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -2807,7 +2423,7 @@ var SandboxInstance = class SandboxInstance {
 		const fs = await import("node:fs/promises");
 		const path = await import("node:path");
 		const { execSync } = await import("node:child_process");
-		const response = await this.runtimeFetch(`/fs/download-dir${remoteDir}`, { method: "GET" });
+		const response = await this.runtimeFetch(runtimeFilesystemPath("/fs/download-dir", remoteDir), { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -2830,7 +2446,8 @@ var SandboxInstance = class SandboxInstance {
 		if (options?.long) params.set("long", "true");
 		if (options?.sessionId) params.set("sessionId", options.sessionId);
 		const query = params.toString();
-		const url = query ? `/fs/list${path}?${query}` : `/fs/list${path}`;
+		const basePath = runtimeFilesystemPath("/fs/list", path);
+		const url = query ? `${basePath}?${query}` : basePath;
 		const response = await this.runtimeFetch(url, { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
@@ -2852,7 +2469,7 @@ var SandboxInstance = class SandboxInstance {
 	}
 	async fsStat(path) {
 		await this.ensureRunning();
-		const response = await this.runtimeFetch(`/fs/stat${path}`, { method: "GET" });
+		const response = await this.runtimeFetch(runtimeFilesystemPath("/fs/stat", path), { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -2890,7 +2507,8 @@ var SandboxInstance = class SandboxInstance {
 		if (options?.recursive) params.set("recursive", "true");
 		if (options?.sessionId) params.set("sessionId", options.sessionId);
 		const query = params.toString();
-		const url = query ? `/fs${path}?${query}` : `/fs${path}`;
+		const basePath = runtimeFilesystemPath("/fs", path);
+		const url = query ? `${basePath}?${query}` : basePath;
 		const response = await this.runtimeFetch(url, { method: "DELETE" });
 		if (!response.ok) {
 			const body = await response.text();
@@ -2902,7 +2520,8 @@ var SandboxInstance = class SandboxInstance {
 		const params = new URLSearchParams();
 		if (options?.recursive) params.set("recursive", "true");
 		const query = params.toString();
-		const url = query ? `/fs/mkdir${path}?${query}` : `/fs/mkdir${path}`;
+		const basePath = runtimeFilesystemPath("/fs/mkdir", path);
+		const url = query ? `${basePath}?${query}` : basePath;
 		const response = await this.runtimeFetch(url, { method: "POST" });
 		if (!response.ok) {
 			const body = await response.text();
@@ -2911,7 +2530,7 @@ var SandboxInstance = class SandboxInstance {
 	}
 	async fsExists(path) {
 		await this.ensureRunning();
-		const response = await this.runtimeFetch(`/fs/exists${path}`, { method: "GET" });
+		const response = await this.runtimeFetch(runtimeFilesystemPath("/fs/exists", path), { method: "GET" });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -4112,7 +3731,89 @@ var SandboxInstance = class SandboxInstance {
 		return ((await response.json()).children ?? []).map((child) => new SandboxInstance(this.client, this.parseInfo(child), this.defaultRuntimeBackend));
 	}
 	/**
+	* Speculative rollouts: branch this RUNNING sandbox into `n` copy-on-write
+	* children, run the SAME agent turn in every child in parallel, and
+	* optionally score each child by running `scorer.command` inside it (exit 0
+	* passes; stdout is parsed as the numeric score — highest wins).
+	*
+	* Async-op shape: resolves as soon as the children exist (their turns are
+	* still running); poll {@link getRollout} or use {@link waitForRollout} for
+	* results. Children are first-class sandboxes the caller may promote or
+	* delete — each occupies a concurrent-session quota slot like a create.
+	*
+	* @example
+	* ```typescript
+	* const started = await box.rollout({
+	*   n: 4,
+	*   parts: [{ type: "text", text: "make the failing test pass" }],
+	*   scorer: { type: "command", command: "npm test --silent && echo 1" },
+	* });
+	* const settled = await box.waitForRollout(started.rolloutId);
+	* console.log(settled.winner, settled.results);
+	* ```
+	*/
+	async rollout(options) {
+		if (!Number.isInteger(options.n) || options.n < 1 || options.n > 8) throw new ValidationError(`rollout n must be an integer in [1, 8] (got ${options.n})`);
+		if (!Array.isArray(options.parts) || options.parts.length === 0) throw new ValidationError("rollout parts must be a non-empty array");
+		if (options.scorer?.type === "command" && !options.scorer.command) throw new ValidationError("scorer.command is required when scorer.type is \"command\"");
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/rollouts`, {
+			method: "POST",
+			body: JSON.stringify({
+				n: options.n,
+				parts: options.parts,
+				...options.scorer ? { scorer: options.scorer } : {}
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		if (typeof data.rolloutId !== "string" || data.rolloutId.length === 0) throw new ServerError(`Rollout create returned ${response.status} but body had no rolloutId: ${JSON.stringify(data).slice(0, 200)}`, response.status);
+		return data;
+	}
+	/**
+	* Poll a rollout's status and per-child results.
+	*
+	* Failed or timed-out children appear as result entries with `error` set —
+	* partial results are never dropped. Rollout poll-state lives in
+	* orchestrator RAM: after an orchestrator restart this returns 404 while
+	* the children themselves survive as first-class sandboxes.
+	*/
+	async getRollout(rolloutId) {
+		if (!rolloutId) throw new ValidationError("rolloutId is required");
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/rollouts/${encodeURIComponent(rolloutId)}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	/**
+	* Poll {@link getRollout} until the rollout leaves `running`, then return
+	* the terminal record — including `partial`/`failed` outcomes, whose
+	* per-child `error` entries are results the caller inspects, not
+	* exceptions. Throws {@link TimeoutError} on deadline or abort.
+	*/
+	async waitForRollout(rolloutId, options) {
+		const timeoutMs = options?.timeoutMs ?? 36e4;
+		const pollIntervalMs = options?.pollIntervalMs ?? 2e3;
+		const startTime = Date.now();
+		while (true) {
+			if (options?.signal?.aborted) throw new TimeoutError(0, "Aborted");
+			const record = await this.getRollout(rolloutId);
+			if (record.status !== "running") return record;
+			if (Date.now() - startTime > timeoutMs) throw new TimeoutError(timeoutMs, `Timed out waiting for rollout ${rolloutId} to settle`);
+			await this.sleep(pollIntervalMs);
+		}
+	}
+	/**
 	* Stop the sandbox (keeps state for resume).
+	*
+	* The stop response carries the orchestrator's per-phase stop breakdown
+	* (`stop_metering` / `container_kill` / `stop_complete` /
+	* `stop_unaccounted`); after this resolves, {@link startupDiagnostics}
+	* returns it (replacing the create breakdown).
 	*/
 	async stop() {
 		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/stop`, { method: "POST" });
@@ -4120,7 +3821,9 @@ var SandboxInstance = class SandboxInstance {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
+		const diagnostics = await this.readLifecycleDiagnostics(response);
 		await this.refresh();
+		if (diagnostics) this.info.startupDiagnostics = diagnostics;
 	}
 	/**
 	* Resume a stopped sandbox.
@@ -4137,10 +3840,18 @@ var SandboxInstance = class SandboxInstance {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
+		const diagnostics = await this.readLifecycleDiagnostics(response);
 		await this.refresh();
+		if (diagnostics) this.info.startupDiagnostics = diagnostics;
 	}
 	/**
 	* Delete the sandbox permanently.
+	*
+	* The delete response carries the orchestrator's per-phase delete breakdown
+	* (`container_remove` / `storage_binding_wait` / `cleanup_parallel` /
+	* `delete_complete` / `delete_unaccounted`); after this resolves,
+	* {@link startupDiagnostics} returns it for post-mortem reads on the
+	* now-gone sandbox.
 	*/
 	async delete() {
 		const response = await this.client.fetch(`/v1/sandboxes/${this.id}`, { method: "DELETE" });
@@ -4148,6 +3859,17 @@ var SandboxInstance = class SandboxInstance {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
+		const diagnostics = await this.readLifecycleDiagnostics(response);
+		if (diagnostics) this.info.startupDiagnostics = diagnostics;
+	}
+	/**
+	* Read the per-phase lifecycle breakdown off a stop/resume/delete response
+	* body. Never throws: diagnostics are measurement data — a body that fails
+	* to parse (older API, empty body) must not fail the lifecycle call.
+	*/
+	async readLifecycleDiagnostics(response) {
+		const data = await response.json().catch(() => null);
+		return data ? normalizeStartupDiagnostics(data.startupDiagnostics) : null;
 	}
 	/**
 	* keepAlive is intentionally unavailable until the API exposes timeout updates.
@@ -4732,6 +4454,7 @@ var SandboxInstance = class SandboxInstance {
 	* gates ProductTokenIssuer-issued JWTs — no new sidecar surface.
 	*/
 	async mintScopedToken(opts) {
+		if ((opts.scope === "session" || opts.scope === "session-runtime") && !opts.sessionId) throw new ValidationError(`${opts.scope} scope requires a sessionId`);
 		const response = await this.client.fetch(`/v1/sandboxes/${encodeURIComponent(this.id)}/scoped-token`, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
@@ -4772,7 +4495,7 @@ var SandboxInstance = class SandboxInstance {
 		const search = new URLSearchParams();
 		search.set("sessionId", id);
 		if (opts?.since) search.set("since", opts.since);
-		const response = await this.runtimeFetch(`/agents/events/?${search.toString()}`, { signal: opts?.signal });
+		const response = await this.runtimeFetch(`/agents/events?${search.toString()}`, { signal: opts?.signal });
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
@@ -5047,4 +4770,4 @@ function quoteForShell(value) {
 	return `'${value.replace(/'/g, "'\\''")}'`;
 }
 //#endregion
-export { normalizeRuntimeBackendConfig as _, InteractiveSessionHandle as a, getSandboxEventText as c, exportTraceBundle as d, otelTraceIdForTangleTrace as f, parseSSEStream as g, encodeTextForWire as h, SandboxSession as i, normalizeConnection as l, encodePromptForWire as m, normalizeStartupDiagnostics as n, applySandboxEventText as o, toOtelJson as p, SandboxTaskSession as r, collectAgentResponseText as s, SandboxInstance as t, buildTraceExportPayload as u, serializeForSidecar as v };
+export { InteractiveSessionHandle as a, getSandboxEventText as c, exportTraceBundle as d, otelTraceIdForTangleTrace as f, parseSSEStream as g, encodeTextForWire as h, SandboxSession as i, normalizeConnection as l, encodePromptForWire as m, normalizeStartupDiagnostics as n, applySandboxEventText as o, toOtelJson as p, SandboxTaskSession as r, collectAgentResponseText as s, SandboxInstance as t, buildTraceExportPayload as u };