@tangle-network/sandbox 0.38.2 → 0.39.1-develop.20260912191433.b31d83f

package/README.md

@@ -277,6 +277,14 @@ try {
 
 Use the same `idempotencyKey` only when retrying the same logical create request.
 
+Inspect `SandboxError.createFailureDisposition` only on the top-level error returned by `create()`.
+The value `"not-admitted"` proves that this call's attempts admitted no sandbox.
+An absent value means unknown, even when the last HTTP status is 429.
+Do not infer this call's disposition from `cause` or earlier calls with the same key.
+This evidence does not exclude a sandbox from an earlier call with that key.
+Cleanup may skip same-key recovery after `"not-admitted"` only when the key was fresh for this call.
+Transport failures and unclassified responses remain uncertain; keep their recovery path.
+
 ## Commands and files
 
 `exec()` returns the exit code, standard output, standard error, and timing data.
@@ -310,10 +318,10 @@ console.log(config);
 | Public API request | 1 MiB | `SANDBOX_PROXY_REQUEST_MAX_BYTES` | Requests routed through the Sandbox API |
 | Direct runtime file request | 32 MiB | `SANDBOX_DIRECT_FILE_REQUEST_MAX_BYTES` | Direct runtime requests |
 | Multipart upload | 5 MiB | `FILE_MULTIPART_UPLOAD_MAX_BYTES` | One multipart upload |
-| Chunked upload part | 768 KiB | `FILE_UPLOAD_PART_MAX_BYTES` | One `fs.uploadData()` part |
-| Chunked upload session | 64 MiB | `FILE_UPLOAD_SESSION_MAX_BYTES` | One complete `fs.uploadData()` call |
+| Chunked upload part | 768 KiB | `FILE_UPLOAD_PART_MAX_BYTES` | One `fs.upload()` or `fs.uploadData()` part |
+| Chunked upload session | 64 MiB | `FILE_UPLOAD_SESSION_MAX_BYTES` | One complete `fs.upload()` or `fs.uploadData()` call |
 
-Use `fs.uploadData()` when content is larger than the single-request limit.
+Use `fs.upload()` for local files or `fs.uploadData()` for in-memory content larger than the single-request limit.
 
 The instance also exposes `git`, `tools`, `process`, `terminals`, `network`, `egress`, `previewLinks`, `images`, and `backend` capability clients.
 Unsupported capabilities fail with a typed SDK error.

package/dist/agent/index.d.ts

@@ -1,6 +1,6 @@
-import { g as SandboxSession, h as SandboxTaskSession, r as SandboxInstance } from "../sandbox-DQmu7a6M.js";
-import { D as CodeExecutionResult, E as CodeExecutionOptions, O as CodeLanguage, Si as SessionListOptions, bi as SessionInfo, d as BackendConfig, k as CodeResultPart } from "../types-DTDI3kek.js";
-import { i as Sandbox } from "../client-XqUR9qgS.js";
+import { g as SandboxSession, h as SandboxTaskSession, r as SandboxInstance } from "../sandbox-C8xeDrlS.js";
+import { D as CodeExecutionResult, E as CodeExecutionOptions, O as CodeLanguage, Si as SessionListOptions, bi as SessionInfo, d as BackendConfig, k as CodeResultPart } from "../types-BZuZPQ0N.js";
+import { i as Sandbox } from "../client-fy_RYdGN.js";
 import * as _$_modelcontextprotocol_sdk_server_index_js0 from "@modelcontextprotocol/sdk/server/index.js";
 
 //#region src/agent/instances.d.ts

package/dist/agent/index.js

@@ -1,7 +1,7 @@
-import { f as assertCurrentBackendType } from "../runtime-api-CrjcDtUw.js";
-import { f as StateError, m as ValidationError, s as NotFoundError } from "../errors-MMMPY4T6.js";
-import { n as Sandbox } from "../client-DRumogtw.js";
-import { t as SandboxInstance } from "../sandbox-CzBWptVE.js";
+import { f as assertCurrentBackendType } from "../runtime-api-DokfzHVX.js";
+import { f as StateError, m as ValidationError, s as NotFoundError } from "../errors-V6uPkjfJ.js";
+import { n as Sandbox } from "../client-j6FmPkNB.js";
+import { t as SandboxInstance } from "../sandbox-BFZa_Gx-.js";
 import { createRequire } from "node:module";
 //#region src/agent/instances.ts
 const managers = /* @__PURE__ */ new WeakMap();

package/dist/{agent-run-outcome-Bq1aHHPy.d.ts → agent-run-outcome-BSysiQWr.d.ts}

@@ -1,4 +1,4 @@
-import { a as AgentQuestionRequest, et as DurablePlanSnapshot, fr as SandboxEvent, i as AgentApprovalRequirement, o as AgentRunStatus, s as AgentToolInvocation } from "./types-DTDI3kek.js";
+import { a as AgentQuestionRequest, et as DurablePlanSnapshot, fr as SandboxEvent, i as AgentApprovalRequirement, o as AgentRunStatus, s as AgentToolInvocation } from "./types-BZuZPQ0N.js";
 import { InteractionRequest } from "@tangle-network/agent-interface";
 
 //#region src/agent-run-outcome.d.ts

package/dist/auth/index.d.ts

@@ -1,2 +1,2 @@
-import { _ as ReadTokenPayload, a as issueCollaborationToken, c as issueSessionScopedToken, d as AnyTokenPayload, f as BatchScopedTokenPayload, g as ProjectScopedTokenPayload, h as IssueCollaborationTokenOptions, i as issueBatchScopedToken, l as unsafeDecodeToken, m as CollaborationTokenPayload, n as getTokenTTL, o as issueProjectScopedToken, p as CollaborationAccess, r as isTokenExpiringSoon, s as issueReadToken, t as ProductTokenIssuer, u as verifyToken, v as SessionScopedTokenPayload, y as TokenScope } from "../index-Bq_z_u6A.js";
-export { AnyTokenPayload, BatchScopedTokenPayload, CollaborationAccess, CollaborationTokenPayload, IssueCollaborationTokenOptions, ProductTokenIssuer, ProjectScopedTokenPayload, ReadTokenPayload, SessionScopedTokenPayload, TokenScope, getTokenTTL, isTokenExpiringSoon, issueBatchScopedToken, issueCollaborationToken, issueProjectScopedToken, issueReadToken, issueSessionScopedToken, unsafeDecodeToken, verifyToken };
+import { _ as ReadTokenPayload, a as issueCollaborationToken, b as materializeCliAuthBundle, c as issueSessionScopedToken, d as AnyTokenPayload, f as BatchScopedTokenPayload, g as ProjectScopedTokenPayload, h as IssueCollaborationTokenOptions, i as issueBatchScopedToken, l as unsafeDecodeToken, m as CollaborationTokenPayload, n as getTokenTTL, o as issueProjectScopedToken, p as CollaborationAccess, r as isTokenExpiringSoon, s as issueReadToken, t as ProductTokenIssuer, u as verifyToken, v as SessionScopedTokenPayload, y as TokenScope } from "../index-CS-t6tPU.js";
+export { AnyTokenPayload, BatchScopedTokenPayload, CollaborationAccess, CollaborationTokenPayload, IssueCollaborationTokenOptions, ProductTokenIssuer, ProjectScopedTokenPayload, ReadTokenPayload, SessionScopedTokenPayload, TokenScope, getTokenTTL, isTokenExpiringSoon, issueBatchScopedToken, issueCollaborationToken, issueProjectScopedToken, issueReadToken, issueSessionScopedToken, materializeCliAuthBundle, unsafeDecodeToken, verifyToken };

package/dist/auth/index.js

@@ -1,3 +1,4 @@
+import { n as materializeCliAuthBundle } from "../cli-auth-bundle-DUsK57rK.js";
 //#region src/auth/tokens.ts
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -311,4 +312,4 @@ var ProductTokenIssuer = class {
 	}
 };
 //#endregion
-export { ProductTokenIssuer, getTokenTTL, isTokenExpiringSoon, issueBatchScopedToken, issueCollaborationToken, issueProjectScopedToken, issueReadToken, issueSessionScopedToken, unsafeDecodeToken, verifyToken };
+export { ProductTokenIssuer, getTokenTTL, isTokenExpiringSoon, issueBatchScopedToken, issueCollaborationToken, issueProjectScopedToken, issueReadToken, issueSessionScopedToken, materializeCliAuthBundle, unsafeDecodeToken, verifyToken };

package/dist/{browser-interactive-control-controller-lRfzpg9t.d.ts → browser-interactive-control-controller-BELrFH4f.d.ts}

@@ -1,4 +1,4 @@
-import { r as TerminalStreamHandlers } from "./terminal-stream-5GNLCsms.js";
+import { r as TerminalStreamHandlers } from "./terminal-stream-CcaBTVg3.js";
 import { AgentInteractiveSessionAttach, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionStatus } from "@tangle-network/agent-interface";
 import { AgentInteractiveSessionControlClaim as AgentInteractiveSessionControlClaim$1, AgentInteractiveSessionControlClaimRequest as AgentInteractiveSessionControlClaimRequest$1, AgentInteractiveSessionRef as AgentInteractiveSessionRef$1 } from "@tangle-network/agent-interface/environment-interactive-control";
 

package/dist/cli-auth-bundle-DUsK57rK.js

@@ -0,0 +1,25 @@
+//#region ../../../packages/cli-agent-registry/dist/cli-auth-bundle.mjs
+const DEFAULT_MODE = 384;
+const AUTH_BUNDLE_PATHS = Object.freeze({
+	codex: ".codex/auth.json",
+	"claude-code": ".claude/.credentials.json"
+});
+/** Convert a native credential JSON bundle without reading host credentials. */
+function materializeCliAuthBundle(backendType, rawBundle) {
+	if (backendType !== "codex" && backendType !== "claude-code") throw new Error("CLI auth bundle is not supported for the selected backend");
+	if (typeof rawBundle !== "string") throw new Error("CLI auth bundle must be a JSON object");
+	let value;
+	try {
+		value = JSON.parse(rawBundle);
+	} catch {
+		throw new Error("CLI auth bundle must be a JSON object");
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("CLI auth bundle must be a JSON object");
+	return [{
+		path: AUTH_BUNDLE_PATHS[backendType],
+		content: rawBundle,
+		mode: DEFAULT_MODE
+	}];
+}
+//#endregion
+export { materializeCliAuthBundle as n, AUTH_BUNDLE_PATHS as t };

package/dist/{client-XqUR9qgS.d.ts → client-fy_RYdGN.d.ts}

@@ -1,6 +1,6 @@
-import { l as TraceExportResult, n as HttpClient, r as SandboxInstance, u as TraceExportSink } from "./sandbox-DQmu7a6M.js";
-import { l as ScopedToken, s as MintInteractiveSessionTokenOptions } from "./terminal-stream-5GNLCsms.js";
-import { Ar as SandboxFleetToken, At as FleetDriveTurnRequest, Bn as PublicTemplateVersionInfo, Br as SandboxIdentity, Dt as FleetDispatchResultBufferOptions, Er as SandboxFleetManifest, Et as FleetDispatchResultBuffer, F as CreateSandboxFleetOptions, Fr as SandboxFleetUsage, Ft as FleetPromptDispatchResult, Gn as ReconcileSandboxFleetsOptions, Hn as PublishPublicTemplateVersionOptions, I as CreateSandboxFleetTokenOptions, Ji as TokenRefreshHandler, Kn as ReconcileSandboxFleetsResult, L as CreateSandboxFleetWithCoordinatorOptions, Li as SubscriptionInfo, Lr as SandboxFleetWorkspaceReconcileResult, Mn as PromptInputPart, Mt as FleetExecDispatchResult, N as CreateIntelligenceReportOptions, Ni as SshKeysManager, Nn as PromptOptions, Nt as FleetMachineId, Or as SandboxFleetOperationsSummary, Ot as FleetDispatchStreamOptions, P as CreateRequestOptions, Pn as PromptResult, Pr as SandboxFleetTraceOptions, Pt as FleetPromptDispatchOptions, R as CreateSandboxOptions, Rr as SandboxFleetWorkspaceRestoreResult, Tt as FleetDispatchCancelResult, Un as ReapExpiredSandboxFleetsOptions, Vn as PublishPublicTemplateOptions, Vr as SandboxInfo, Wn as ReapExpiredSandboxFleetsResult, _r as SandboxFleetDispatchResponse, an as IntelligenceReportCompareTo, ar as SandboxConfig, b as BatchRunRequest, br as SandboxFleetInfo, ca as BatchEvent, dn as ListSandboxFleetOptions, dr as SandboxEnvironment, dt as ExecResult, ea as UsageInfo, fn as ListSandboxOptions, hr as SandboxFleetCostEstimate, in as IntelligenceReportBudget, jr as SandboxFleetTraceBundle, jt as FleetExecDispatchOptions, kt as FleetDriveTurnOutcome, l as AttachSandboxFleetMachineOptions, mr as SandboxFleetArtifactSpec, pr as SandboxFleetArtifact, rn as IntelligenceReport, sn as IntelligenceReportWindow, ui as SecretsManager, ut as ExecOptions, v as BatchResult, vr as SandboxFleetDriverCapability, wr as SandboxFleetMachineRecord, y as BatchRunOptions, zn as PublicTemplateInfo, zr as SandboxFleetWorkspaceSnapshotResult } from "./types-DTDI3kek.js";
+import { l as TraceExportResult, n as HttpClient, r as SandboxInstance, u as TraceExportSink } from "./sandbox-C8xeDrlS.js";
+import { l as ScopedToken, s as MintInteractiveSessionTokenOptions } from "./terminal-stream-CcaBTVg3.js";
+import { Ar as SandboxFleetToken, At as FleetDriveTurnRequest, Bn as PublicTemplateVersionInfo, Br as SandboxIdentity, Dt as FleetDispatchResultBufferOptions, Er as SandboxFleetManifest, Et as FleetDispatchResultBuffer, F as CreateSandboxFleetOptions, Fr as SandboxFleetUsage, Ft as FleetPromptDispatchResult, Gn as ReconcileSandboxFleetsOptions, Hn as PublishPublicTemplateVersionOptions, I as CreateSandboxFleetTokenOptions, Ji as TokenRefreshHandler, Kn as ReconcileSandboxFleetsResult, L as CreateSandboxFleetWithCoordinatorOptions, Li as SubscriptionInfo, Lr as SandboxFleetWorkspaceReconcileResult, Mn as PromptInputPart, Mt as FleetExecDispatchResult, N as CreateIntelligenceReportOptions, Ni as SshKeysManager, Nn as PromptOptions, Nt as FleetMachineId, Or as SandboxFleetOperationsSummary, Ot as FleetDispatchStreamOptions, P as CreateRequestOptions, Pn as PromptResult, Pr as SandboxFleetTraceOptions, Pt as FleetPromptDispatchOptions, R as CreateSandboxOptions, Rr as SandboxFleetWorkspaceRestoreResult, Tt as FleetDispatchCancelResult, Un as ReapExpiredSandboxFleetsOptions, Vn as PublishPublicTemplateOptions, Vr as SandboxInfo, Wn as ReapExpiredSandboxFleetsResult, _r as SandboxFleetDispatchResponse, an as IntelligenceReportCompareTo, ar as SandboxConfig, b as BatchRunRequest, br as SandboxFleetInfo, ca as BatchEvent, dn as ListSandboxFleetOptions, dr as SandboxEnvironment, dt as ExecResult, ea as UsageInfo, fn as ListSandboxOptions, hr as SandboxFleetCostEstimate, in as IntelligenceReportBudget, jr as SandboxFleetTraceBundle, jt as FleetExecDispatchOptions, kt as FleetDriveTurnOutcome, l as AttachSandboxFleetMachineOptions, mr as SandboxFleetArtifactSpec, pr as SandboxFleetArtifact, rn as IntelligenceReport, sn as IntelligenceReportWindow, ui as SecretsManager, ut as ExecOptions, v as BatchResult, vr as SandboxFleetDriverCapability, wr as SandboxFleetMachineRecord, y as BatchRunOptions, zn as PublicTemplateInfo, zr as SandboxFleetWorkspaceSnapshotResult } from "./types-BZuZPQ0N.js";
 import { AgentInteractiveSessionRef } from "@tangle-network/agent-interface";
 import { z } from "zod";
 
@@ -23,6 +23,9 @@ declare const backendRegistryCapabilitiesSchema: z.ZodObject<{
   imageInput: z.ZodBoolean;
   contextWindow: z.ZodNumber;
   mcp: z.ZodBoolean;
+  runtimeAttachments: z.ZodOptional<z.ZodObject<{
+    mcp: z.ZodLiteral<true>;
+  }, z.core.$strip>>;
   sessions: z.ZodBoolean;
   configurable: z.ZodBoolean;
   interactions: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<("permission" | "question" | "plan")[], string[]>>;
@@ -40,6 +43,9 @@ declare const backendRegistryEntrySchema: z.ZodObject<{
     imageInput: z.ZodBoolean;
     contextWindow: z.ZodNumber;
     mcp: z.ZodBoolean;
+    runtimeAttachments: z.ZodOptional<z.ZodObject<{
+      mcp: z.ZodLiteral<true>;
+    }, z.core.$strip>>;
     sessions: z.ZodBoolean;
     configurable: z.ZodBoolean;
     interactions: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<("permission" | "question" | "plan")[], string[]>>;
@@ -59,6 +65,9 @@ declare const backendRegistryResponseSchema: z.ZodObject<{
       imageInput: z.ZodBoolean;
       contextWindow: z.ZodNumber;
       mcp: z.ZodBoolean;
+      runtimeAttachments: z.ZodOptional<z.ZodObject<{
+        mcp: z.ZodLiteral<true>;
+      }, z.core.$strip>>;
       sessions: z.ZodBoolean;
       configurable: z.ZodBoolean;
       interactions: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<("permission" | "question" | "plan")[], string[]>>;
@@ -422,7 +431,7 @@ declare class Sandbox implements HttpClient, ScopedTokenHttpClient {
    * });
    * ```
    */
-  create(options?: CreateSandboxOptions, requestOptions?: CreateRequestOptions): Promise<SandboxInstance>;
+  create(inputOptions?: CreateSandboxOptions, requestOptions?: CreateRequestOptions): Promise<SandboxInstance>;
   /**
    * Poll a sandbox to `running` by id. Surfaces a real provision failure
    * as a {@link StateError} (carrying the sandbox's error message) rather

package/dist/{client-DRumogtw.js → client-j6FmPkNB.js}

@@ -1,7 +1,7 @@
-import { _ as backendTypeSchema, c as encodePromptForWire, d as applyRequestedModel, f as assertCurrentBackendType, l as encodeTextForWire, o as SANDBOX_PROXY_REQUEST_MAX_BYTES, p as normalizeRuntimeBackendConfig, u as parseSSEStream } from "./runtime-api-CrjcDtUw.js";
-import { c as PartialFailureError, d as ServerError, h as parseErrorResponse, m as ValidationError, o as NetworkError, p as TimeoutError, s as NotFoundError, t as AuthError, u as SandboxError } from "./errors-MMMPY4T6.js";
+import { c as encodePromptForWire, d as applyRequestedModel, f as assertCurrentBackendType, l as encodeTextForWire, m as normalizeRuntimeBackendConfig, o as SANDBOX_PROXY_REQUEST_MAX_BYTES, u as parseSSEStream, v as backendTypeSchema } from "./runtime-api-DokfzHVX.js";
+import { c as PartialFailureError, d as ServerError, h as parseErrorResponse, m as ValidationError, o as NetworkError, p as TimeoutError, s as NotFoundError, t as AuthError, u as SandboxError } from "./errors-V6uPkjfJ.js";
 import { n as combineAbortSignals } from "./abort-signal-si1WMfJb.js";
-import { E as normalizeConnection, O as exportTraceBundle, b as requestInteractiveSessionToken, i as normalizeStartupDiagnostics, n as createSandboxInstanceFromResponse, r as normalizeSandboxCreateReceipt } from "./sandbox-CzBWptVE.js";
+import { E as normalizeConnection, O as exportTraceBundle, b as requestInteractiveSessionToken, i as normalizeStartupDiagnostics, n as createSandboxInstanceFromResponse, r as normalizeSandboxCreateReceipt } from "./sandbox-BFZa_Gx-.js";
 import { agentProfileSchema } from "@tangle-network/agent-interface";
 import { z } from "zod";
 //#region src/backend-registry.ts
@@ -24,6 +24,7 @@ const backendRegistryCapabilitiesSchema = z.object({
 	imageInput: z.boolean(),
 	contextWindow: z.number(),
 	mcp: z.boolean(),
+	runtimeAttachments: z.object({ mcp: z.literal(true) }).optional(),
 	sessions: z.boolean(),
 	configurable: z.boolean(),
 	interactions: z.array(z.string().min(1)).transform((values) => values.filter(isBackendRegistryInteractionKind))
@@ -2429,6 +2430,56 @@ const RETRYABLE_CREATE_STATUS_CODES = new Set([
 	503,
 	504
 ]);
+/**
+* 503 classes that mean "the cell cannot place a create right now, ask
+* again", not "this create failed". They are what a caller sees while the
+* production host-agent rolls: placement is drained on the only host, so an
+* unkeyed create fails `CAPACITY_EXHAUSTED` (`HOST_PRESSURE` and
+* `PROVISIONING_PAUSED` are the sibling admission refusals the orchestrator
+* maps to 503), and a keyed create cannot verify its ref while the agent is
+* down (`IDEMPOTENT_CREATE_PROBE_FAILED`). Re-POSTing is safe: the admission
+* refusals started no provision, the probe answer is the Worker declining to
+* act until it can prove what exists, and the idempotency key joins
+* whichever provision did start.
+*
+* `SANDBOX_CREATE_RECONCILING` is deliberately not in the family. The Worker
+* answers it (Retry-After 2) when a same-key create meets a journaled D1
+* reservation left by an earlier attempt
+* (products/sandbox/api/src/routes/sandbox-create-idempotency-flow.ts). The
+* Worker releases that journal on the three admission refusals above
+* (sandbox-create-failure.ts, `PRE_PROVISION_REFUSAL_CODES`), so the hold
+* can only follow a retained real failure: a provision that started and
+* failed, or a create whose commit never ran because the Worker or the
+* controller stopped mid-create. The reconciler leaves such a journal alone
+* for RESERVATION_TTL_MS = 5 min and then releases it only after three
+* authoritative misses, one cron tick apart
+* (products/sandbox/api/src/cf/create-reservation-reconciler.ts), which is
+* longer than the 150 s ceiling below and the 120 s default create budget.
+* Retrying it on the time budget could never outlast the hold; it only
+* turned a ~10 s failure into a 120 s TimeoutError. It keeps the
+* five-attempt budget, paced on its Retry-After, like every other 503. The
+* same code also answers a failed read of that recovery state, a transient
+* the short budget already covers.
+*/
+const DEPLOY_WINDOW_RETRY_CODES = new Set([
+	"IDEMPOTENT_CREATE_PROBE_FAILED",
+	"CAPACITY_EXHAUSTED",
+	"HOST_PRESSURE",
+	"PROVISIONING_PAUSED"
+]);
+/**
+* Longest a create keeps re-POSTing through the deploy-window family,
+* counted from the start of the create. Sized to the production host-agent
+* roll in `.github/actions/update-host-agents/action.yml` (drain placement
+* on the host, swap the agent, restore placement): the last measured roll
+* kept placement drained for 124 s. The caller's create deadline binds
+* first when it is shorter, and the 120 s default is, so a default create
+* waits out its own deadline rather than this ceiling.
+*/
+const DEPLOY_WINDOW_RETRY_MS = 15e4;
+function isDeployWindowCreateError(cause) {
+	return cause instanceof SandboxError && cause.status === 503 && DEPLOY_WINDOW_RETRY_CODES.has(cause.code);
+}
 function isRetryableCreateError(cause) {
 	if (cause instanceof NetworkError) return true;
 	return cause instanceof SandboxError && cause.status !== void 0 && RETRYABLE_CREATE_STATUS_CODES.has(cause.status);
@@ -2480,11 +2531,11 @@ function withRequestContextHeaders(response, path, method) {
 	});
 }
 async function resolveLocalCliAuthFiles(backendType) {
-	const { discoverLocalCliAuthFiles } = await import("./local-cli-auth-CJmSpTjk.js");
+	const { discoverLocalCliAuthFiles } = await import("./local-cli-auth-BAJuMBZU.js");
 	return discoverLocalCliAuthFiles(backendType);
 }
 async function describeLocalCliAuthExpectation(backendType) {
-	const { describeLocalCliAuthExpectation: describe } = await import("./local-cli-auth-CJmSpTjk.js");
+	const { describeLocalCliAuthExpectation: describe } = await import("./local-cli-auth-BAJuMBZU.js");
 	return describe(backendType);
 }
 async function hydrateLocalCliBackendAuth(backend, baseUrl, trustLocalCliAuth) {
@@ -2661,11 +2712,24 @@ var Sandbox = class {
 	* });
 	* ```
 	*/
-	async create(options, requestOptions) {
+	async create(inputOptions, requestOptions) {
+		let options = inputOptions;
+		if (options?.backend?.runtimeAttachments !== void 0) {
+			normalizeRuntimeBackendConfig(options.backend);
+			options = {
+				...options,
+				backend: {
+					...options.backend,
+					runtimeAttachments: structuredClone(options.backend.runtimeAttachments)
+				}
+			};
+		}
 		if (options?.backend?.type !== void 0) assertCurrentBackendType(options.backend.type);
 		const timeoutMs = requestOptions?.timeoutMs ?? (options?.gpuLease ? DEFAULT_GPU_CREATE_TIMEOUT_MS : DEFAULT_CREATE_TIMEOUT_MS);
 		const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
-		const deadline = Date.now() + timeoutMs;
+		const startedAt = Date.now();
+		const deadline = startedAt + timeoutMs;
+		const deployWindowDeadline = Math.min(deadline, startedAt + DEPLOY_WINDOW_RETRY_MS);
 		const git = options?.git ? {
 			url: options.git.url,
 			ref: options.git.ref,
@@ -2754,17 +2818,37 @@ var Sandbox = class {
 			idempotencyKey,
 			billingOwnerId: options?.billingOwnerId
 		});
-		const createTimeoutError = () => new TimeoutError(timeoutMs, `Sandbox create did not complete within ${timeoutMs}ms. The provision may still be running server-side; retry create() with idempotencyKey="${idempotencyKey}" to join it.`);
-		const waitBeforeRetry = async (cause, failedAttempt) => {
+		let lastServerError;
+		let allPreviousCreateAttemptsRefused = true;
+		const createTimeoutError = () => new TimeoutError(timeoutMs, `Sandbox create did not complete within ${timeoutMs}ms. ` + (lastServerError ? `The last attempt failed with ${lastServerError.code}${lastServerError.status === void 0 ? "" : ` (HTTP ${lastServerError.status})`}: ${lastServerError.message}. ` : "") + `The provision may still be running server-side; retry create() with idempotencyKey="${idempotencyKey}" to join it.`, allPreviousCreateAttemptsRefused && lastServerError?.createFailureDisposition === "not-admitted" ? { createFailureDisposition: "not-admitted" } : void 0, lastServerError);
+		const sleepBeforeRetry = async (delayMs) => {
 			try {
-				await waitForCreateRetry(createRetryDelayMs(cause, failedAttempt), postSignal);
+				await waitForCreateRetry(delayMs, postSignal);
 			} catch (waitError) {
 				if (requestOptions?.signal?.aborted) throw waitError;
 				throw createTimeoutError();
 			}
 		};
+		const waitBeforeRetry = async (cause, failedAttempt) => {
+			if (isDeployWindowCreateError(cause)) {
+				const delayMs = Math.max(createRetryDelayMs(cause, failedAttempt), CREATE_RETRY_BASE_DELAY_MS);
+				if (delayMs >= deployWindowDeadline - Date.now()) throw deployWindowDeadline === deadline ? createTimeoutError() : cause;
+				await sleepBeforeRetry(delayMs);
+				return;
+			}
+			const delayMs = createRetryDelayMs(cause, failedAttempt);
+			if (cause instanceof SandboxError && delayMs >= deadline - Date.now()) throw cause;
+			await sleepBeforeRetry(delayMs);
+		};
 		let response;
-		for (let attempt = 1; attempt <= CREATE_POST_MAX_ATTEMPTS; attempt++) {
+		let shortBudgetFailures = 0;
+		const exhaustsRetryBudget = (error) => {
+			if (!isRetryableCreateError(error)) return true;
+			if (isDeployWindowCreateError(error)) return false;
+			shortBudgetFailures += 1;
+			return shortBudgetFailures >= CREATE_POST_MAX_ATTEMPTS;
+		};
+		for (let attempt = 1;; attempt++) {
 			try {
 				response = await this.fetch("/v1/sandboxes", {
 					method: "POST",
@@ -2773,16 +2857,20 @@ var Sandbox = class {
 					body: createRequestBody
 				}, { timeoutMs });
 			} catch (error) {
+				allPreviousCreateAttemptsRefused = false;
 				if (requestOptions?.signal?.aborted) throw error;
+				if (error instanceof SandboxError && !(error instanceof TimeoutError)) lastServerError = error;
 				if (postDeadline.aborted || Date.now() >= deadline || error instanceof TimeoutError || error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) throw createTimeoutError();
-				if (attempt >= CREATE_POST_MAX_ATTEMPTS || !isRetryableCreateError(error)) throw error;
+				if (exhaustsRetryBudget(error instanceof Error ? error : new Error(String(error)))) throw error;
 				await waitBeforeRetry(error, attempt);
 				continue;
 			}
 			if (response.ok) break;
 			const body = await response.text();
-			const error = parseErrorResponse(response.status, body, void 0, response.headers);
-			if (attempt >= CREATE_POST_MAX_ATTEMPTS || !isRetryableCreateError(error)) throw error;
+			const error = parseErrorResponse(response.status, body, { allPreviousCreateAttemptsRefused }, response.headers);
+			allPreviousCreateAttemptsRefused = error.createFailureDisposition === "not-admitted";
+			lastServerError = error;
+			if (exhaustsRetryBudget(error)) throw error;
 			await waitBeforeRetry(error, attempt);
 			response = void 0;
 		}

package/dist/collaboration/index.d.ts

@@ -1,2 +1,2 @@
-import { _ as CollaborationTransportConfig, a as CollaborationClient, c as CollaborationClientConfig, d as CollaborationDocumentRef, f as CollaborationFileBridgeOptions, g as CollaborationTokenRefreshResponse, h as CollaborationTokenRefreshRequest, i as parseCollaborationDocumentId, l as CollaborationDocumentAdapter, m as CollaborationPermissions, n as buildCollaborationDocumentId, o as CollaborationBootstrapRequest, p as CollaborationFileEvent, r as normalizeCollaborationPath, s as CollaborationBootstrapResponse, t as CollaborationFileBridge, u as CollaborationDocumentChange, v as SaveCollaborationSnapshotRequest, y as SaveCollaborationSnapshotResponse } from "../index-CMLW3u5K.js";
+import { _ as CollaborationTransportConfig, a as CollaborationClient, c as CollaborationClientConfig, d as CollaborationDocumentRef, f as CollaborationFileBridgeOptions, g as CollaborationTokenRefreshResponse, h as CollaborationTokenRefreshRequest, i as parseCollaborationDocumentId, l as CollaborationDocumentAdapter, m as CollaborationPermissions, n as buildCollaborationDocumentId, o as CollaborationBootstrapRequest, p as CollaborationFileEvent, r as normalizeCollaborationPath, s as CollaborationBootstrapResponse, t as CollaborationFileBridge, u as CollaborationDocumentChange, v as SaveCollaborationSnapshotRequest, y as SaveCollaborationSnapshotResponse } from "../index-BzAxTiqF.js";
 export { CollaborationBootstrapRequest, CollaborationBootstrapResponse, CollaborationClient, CollaborationClientConfig, CollaborationDocumentAdapter, CollaborationDocumentChange, CollaborationDocumentRef, CollaborationFileBridge, CollaborationFileBridgeOptions, CollaborationFileEvent, CollaborationPermissions, CollaborationTokenRefreshRequest, CollaborationTokenRefreshResponse, CollaborationTransportConfig, SaveCollaborationSnapshotRequest, SaveCollaborationSnapshotResponse, buildCollaborationDocumentId, normalizeCollaborationPath, parseCollaborationDocumentId };

package/dist/collaboration/index.js

@@ -1,2 +1,2 @@
-import { a as CollaborationClient, i as parseCollaborationDocumentId, n as buildCollaborationDocumentId, r as normalizeCollaborationPath, t as CollaborationFileBridge } from "../collaboration-DoSvMDEu.js";
+import { a as CollaborationClient, i as parseCollaborationDocumentId, n as buildCollaborationDocumentId, r as normalizeCollaborationPath, t as CollaborationFileBridge } from "../collaboration-CDvc5Hxk.js";
 export { CollaborationClient, CollaborationFileBridge, buildCollaborationDocumentId, normalizeCollaborationPath, parseCollaborationDocumentId };

package/dist/{collaboration-DoSvMDEu.js → collaboration-CDvc5Hxk.js}

@@ -1,4 +1,4 @@
-import { h as parseErrorResponse, o as NetworkError, p as TimeoutError } from "./errors-MMMPY4T6.js";
+import { h as parseErrorResponse, o as NetworkError, p as TimeoutError } from "./errors-V6uPkjfJ.js";
 //#region src/collaboration/client.ts
 const DEFAULT_TIMEOUT_MS = 3e4;
 function normalizeBaseUrl(url) {

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { a as WorkspaceImagePublishRequestOptions, i as WorkspaceImagePublishInput, o as WorkspaceImagePublishResult, r as SandboxInstance, s as WorkspaceImages } from "./sandbox-DQmu7a6M.js";
-import { Cn as PreviewLinkWaitOptions, Mn as PromptInputPart, R as CreateSandboxOptions, Sn as PreviewLinkManager, Vr as SandboxInfo, Yr as SandboxStatus, ar as SandboxConfig, dt as ExecResult, gn as NetworkConfig, ut as ExecOptions, xn as PreviewLinkInfo } from "./types-DTDI3kek.js";
-import { C as isBackendRegistryInteractionKind, S as backendRegistryResponseSchema, T as parseBackendRegistryResponseBody, _ as BackendRegistryInteractionKind, b as backendRegistryEntrySchema, g as BackendRegistryEntry, h as BackendRegistryCapabilities, i as Sandbox, v as BackendRegistryResponse, w as parseBackendRegistryResponse, x as backendRegistryInteractionKindSchema, y as backendRegistryCapabilitiesSchema } from "./client-XqUR9qgS.js";
-import { a as FileWriteConflictError, c as PartialFailureError, d as SandboxErrorJson, f as SandboxFailureDetail, g as ValidationError, h as TimeoutError, l as QuotaError, m as StateError, n as CapabilityError, o as NetworkError, p as ServerError, s as NotFoundError, t as AuthError, u as SandboxError } from "./errors-BMinPhXs.js";
+import { a as WorkspaceImagePublishRequestOptions, i as WorkspaceImagePublishInput, o as WorkspaceImagePublishResult, r as SandboxInstance, s as WorkspaceImages } from "./sandbox-C8xeDrlS.js";
+import { Cn as PreviewLinkWaitOptions, Mn as PromptInputPart, R as CreateSandboxOptions, Sn as PreviewLinkManager, Vr as SandboxInfo, Yr as SandboxStatus, ar as SandboxConfig, dt as ExecResult, gn as NetworkConfig, ut as ExecOptions, xn as PreviewLinkInfo } from "./types-BZuZPQ0N.js";
+import { C as isBackendRegistryInteractionKind, S as backendRegistryResponseSchema, T as parseBackendRegistryResponseBody, _ as BackendRegistryInteractionKind, b as backendRegistryEntrySchema, g as BackendRegistryEntry, h as BackendRegistryCapabilities, i as Sandbox, v as BackendRegistryResponse, w as parseBackendRegistryResponse, x as backendRegistryInteractionKindSchema, y as backendRegistryCapabilitiesSchema } from "./client-fy_RYdGN.js";
+import { a as FileWriteConflictError, c as PartialFailureError, d as SandboxErrorJson, f as SandboxFailureDetail, g as ValidationError, h as TimeoutError, l as QuotaError, m as StateError, n as CapabilityError, o as NetworkError, p as ServerError, s as NotFoundError, t as AuthError, u as SandboxError } from "./errors-Cv3Td7LB.js";
 export { AuthError, type BackendRegistryCapabilities, type BackendRegistryEntry, type BackendRegistryInteractionKind, type BackendRegistryResponse, CapabilityError, type CreateSandboxOptions, type ExecOptions, type ExecResult, FileWriteConflictError, type NetworkConfig, NetworkError, NotFoundError, PartialFailureError, type PreviewLinkInfo, type PreviewLinkManager, type PreviewLinkWaitOptions, type PromptInputPart, QuotaError, Sandbox, type SandboxConfig, SandboxError, type SandboxErrorJson, type SandboxFailureDetail, type SandboxInfo, SandboxInstance, type SandboxStatus, ServerError, StateError, TimeoutError, ValidationError, type WorkspaceImagePublishInput, type WorkspaceImagePublishRequestOptions, type WorkspaceImagePublishResult, WorkspaceImages, backendRegistryCapabilitiesSchema, backendRegistryEntrySchema, backendRegistryInteractionKindSchema, backendRegistryResponseSchema, isBackendRegistryInteractionKind, parseBackendRegistryResponse, parseBackendRegistryResponseBody };

package/dist/core.js

@@ -1,4 +1,4 @@
-import { a as FileWriteConflictError, c as PartialFailureError, d as ServerError, f as StateError, l as QuotaError, m as ValidationError, n as CapabilityError, o as NetworkError, p as TimeoutError, s as NotFoundError, t as AuthError, u as SandboxError } from "./errors-MMMPY4T6.js";
-import { _ as parseBackendRegistryResponse, f as backendRegistryCapabilitiesSchema, g as isBackendRegistryInteractionKind, h as backendRegistryResponseSchema, m as backendRegistryInteractionKindSchema, n as Sandbox, p as backendRegistryEntrySchema, v as parseBackendRegistryResponseBody } from "./client-DRumogtw.js";
-import { a as WorkspaceImages, t as SandboxInstance } from "./sandbox-CzBWptVE.js";
+import { a as FileWriteConflictError, c as PartialFailureError, d as ServerError, f as StateError, l as QuotaError, m as ValidationError, n as CapabilityError, o as NetworkError, p as TimeoutError, s as NotFoundError, t as AuthError, u as SandboxError } from "./errors-V6uPkjfJ.js";
+import { _ as parseBackendRegistryResponse, f as backendRegistryCapabilitiesSchema, g as isBackendRegistryInteractionKind, h as backendRegistryResponseSchema, m as backendRegistryInteractionKindSchema, n as Sandbox, p as backendRegistryEntrySchema, v as parseBackendRegistryResponseBody } from "./client-j6FmPkNB.js";
+import { a as WorkspaceImages, t as SandboxInstance } from "./sandbox-BFZa_Gx-.js";
 export { AuthError, CapabilityError, FileWriteConflictError, NetworkError, NotFoundError, PartialFailureError, QuotaError, Sandbox, SandboxError, SandboxInstance, ServerError, StateError, TimeoutError, ValidationError, WorkspaceImages, backendRegistryCapabilitiesSchema, backendRegistryEntrySchema, backendRegistryInteractionKindSchema, backendRegistryResponseSchema, isBackendRegistryInteractionKind, parseBackendRegistryResponse, parseBackendRegistryResponseBody };

package/dist/{errors-BMinPhXs.d.ts → errors-Cv3Td7LB.d.ts}

@@ -22,6 +22,13 @@ declare class SandboxError extends Error {
   readonly sidecarVersion?: string;
   /** Sidecar image/tag/sha when the runtime emitted it */
   readonly containerImage?: string;
+  /**
+   * On create's top-level error, proves this call's attempts admitted no
+   * sandbox. Absence is unknown. Earlier errors in `cause` describe only
+   * their attempt prefix, not subsequent attempts or earlier calls using
+   * the same idempotency key.
+   */
+  readonly createFailureDisposition?: "not-admitted";
   constructor(message: string, code: string, status?: number, metadata?: SandboxErrorMetadata);
 }
 type SandboxErrorOrigin = "sidecar" | "sandbox-api" | "control-plane" | "runtime" | "unknown";
@@ -31,6 +38,7 @@ interface SandboxErrorMetadata {
   retryAfterMs?: number;
   sidecarVersion?: string;
   containerImage?: string;
+  createFailureDisposition?: "not-admitted";
 }
 type SandboxErrorJson = string | number | boolean | null | {
   [key: string]: SandboxErrorJson;
@@ -128,7 +136,19 @@ declare class EgressProxyRecoveryError extends SandboxError {
 declare class TimeoutError extends SandboxError {
   /** Timeout duration in milliseconds */
   readonly timeoutMs: number;
-  constructor(timeoutMs: number, message?: string, metadata?: SandboxErrorMetadata);
+  /**
+   * The last typed failure the operation had already received when the
+   * deadline fired, when there was one.
+   *
+   * An operation that spends its budget across several attempts (create's
+   * bounded POST retry) usually learns the server's failure class on an
+   * earlier attempt — `CONTAINER_START_FAILED`, `PROVISIONING_ERROR`,
+   * `RATE_LIMIT_EXCEEDED`. Without this field that class dies at the
+   * deadline and the caller is left with a timeout that names no cause,
+   * which is the last discard in a chain built specifically to deliver it.
+   */
+  readonly cause?: SandboxError;
+  constructor(timeoutMs: number, message?: string, metadata?: SandboxErrorMetadata, cause?: SandboxError);
 }
 /**
  * A network or connection error occurred.

package/dist/{errors-MMMPY4T6.js → errors-V6uPkjfJ.js}

@@ -22,6 +22,13 @@ var SandboxError = class extends Error {
 	sidecarVersion;
 	/** Sidecar image/tag/sha when the runtime emitted it */
 	containerImage;
+	/**
+	* On create's top-level error, proves this call's attempts admitted no
+	* sandbox. Absence is unknown. Earlier errors in `cause` describe only
+	* their attempt prefix, not subsequent attempts or earlier calls using
+	* the same idempotency key.
+	*/
+	createFailureDisposition;
 	constructor(message, code, status, metadata) {
 		super(message);
 		this.name = "SandboxError";
@@ -32,6 +39,7 @@ var SandboxError = class extends Error {
 		this.retryAfterMs = metadata?.retryAfterMs;
 		this.sidecarVersion = metadata?.sidecarVersion;
 		this.containerImage = metadata?.containerImage;
+		this.createFailureDisposition = metadata?.createFailureDisposition;
 	}
 };
 /**
@@ -168,10 +176,23 @@ var EgressProxyRecoveryError = class extends SandboxError {
 var TimeoutError = class extends SandboxError {
 	/** Timeout duration in milliseconds */
 	timeoutMs;
-	constructor(timeoutMs, message, metadata) {
+	/**
+	* The last typed failure the operation had already received when the
+	* deadline fired, when there was one.
+	*
+	* An operation that spends its budget across several attempts (create's
+	* bounded POST retry) usually learns the server's failure class on an
+	* earlier attempt — `CONTAINER_START_FAILED`, `PROVISIONING_ERROR`,
+	* `RATE_LIMIT_EXCEEDED`. Without this field that class dies at the
+	* deadline and the caller is left with a timeout that names no cause,
+	* which is the last discard in a chain built specifically to deliver it.
+	*/
+	cause;
+	constructor(timeoutMs, message, metadata, cause) {
 		super(message ?? `Request timed out after ${timeoutMs}ms`, "TIMEOUT", 408, metadata);
 		this.name = "TimeoutError";
 		this.timeoutMs = timeoutMs;
+		this.cause = cause;
 	}
 };
 /**
@@ -288,7 +309,7 @@ function parseErrorResponse(status, body, context, headers) {
 	const code = (typeof data.code === "string" ? asErrorCode(data.code) : void 0) ?? nestedCode;
 	const rawLog = typeof errorObj === "object" && errorObj !== null ? errorObj.log : void 0;
 	const logTail = typeof rawLog === "string" && rawLog.trim().length > 0 ? rawLog.trim() : void 0;
-	const prefix = context ? `${context.method ?? "REQUEST"} ${context.path ?? ""}: ` : "";
+	const prefix = context?.method || context?.path ? `${context.method ?? "REQUEST"} ${context.path ?? ""}: ` : "";
 	const composedMessage = shouldAppendDetails ? `${baseMessage}: ${details}` : baseMessage;
 	const messageWithReason = `${prefix}${reason && !composedMessage.includes(reason) ? `${composedMessage}: ${reason}` : composedMessage}`;
 	const message = logTail && !messageWithReason.includes(logTail) ? `${messageWithReason}\n${logTail}` : messageWithReason;
@@ -297,7 +318,8 @@ function parseErrorResponse(status, body, context, headers) {
 		endpoint: context?.path ?? headers?.get("x-tangle-request-path") ?? void 0,
 		retryAfterMs: parseRetryAfterMs(headers?.get("retry-after") ?? void 0, data),
 		sidecarVersion: headers?.get("x-sidecar-version") ?? void 0,
-		containerImage: headers?.get("x-sidecar-image") ?? headers?.get("x-sidecar-image-tag") ?? void 0
+		containerImage: headers?.get("x-sidecar-image") ?? headers?.get("x-sidecar-image-tag") ?? void 0,
+		createFailureDisposition: context?.allPreviousCreateAttemptsRefused === true && (context.method ?? headers?.get("x-tangle-request-method")) === "POST" && (context.path ?? headers?.get("x-tangle-request-path")) === "/v1/sandboxes" && status === 429 && (code === "RATE_LIMIT_EXCEEDED" || code === "QUOTA_EXCEEDED" || code === "PLATFORM_RATE_LIMITED") ? "not-admitted" : void 0
 	};
 	if (isQuotaCode(code)) return new QuotaError(data.quotaType || "rate_limit", message, data.current, data.limit, metadata, status);
 	if (isCapabilityCode(code)) return new CapabilityError(message, code, status, metadata, readCapability(data, errorObj));

package/dist/{index-Bq_z_u6A.d.ts → index-CS-t6tPU.d.ts}

@@ -1,3 +1,13 @@
+//#region ../../../packages/cli-agent-registry/dist/cli-auth-bundle.d.mts
+//#region src/cli-auth-bundle.d.ts
+type LocalCliAuthFile = {
+  path: string;
+  content: string;
+  mode?: number;
+};
+/** Convert a native credential JSON bundle without reading host credentials. */
+declare function materializeCliAuthBundle(backendType: string, rawBundle: string): LocalCliAuthFile[]; //#endregion
+//#endregion
 //#region src/auth/types.d.ts
 /**
  * Auth Types
@@ -217,4 +227,4 @@ declare class ProductTokenIssuer {
   getTtlMinutes(tier?: "free" | "pro" | "enterprise"): number;
 }
 //#endregion
-export { ReadTokenPayload as _, issueCollaborationToken as a, issueSessionScopedToken as c, AnyTokenPayload as d, BatchScopedTokenPayload as f, ProjectScopedTokenPayload as g, IssueCollaborationTokenOptions as h, issueBatchScopedToken as i, unsafeDecodeToken as l, CollaborationTokenPayload as m, getTokenTTL as n, issueProjectScopedToken as o, CollaborationAccess as p, isTokenExpiringSoon as r, issueReadToken as s, ProductTokenIssuer as t, verifyToken as u, SessionScopedTokenPayload as v, TokenScope as y };
+export { ReadTokenPayload as _, issueCollaborationToken as a, materializeCliAuthBundle as b, issueSessionScopedToken as c, AnyTokenPayload as d, BatchScopedTokenPayload as f, ProjectScopedTokenPayload as g, IssueCollaborationTokenOptions as h, issueBatchScopedToken as i, unsafeDecodeToken as l, CollaborationTokenPayload as m, getTokenTTL as n, issueProjectScopedToken as o, CollaborationAccess as p, isTokenExpiringSoon as r, issueReadToken as s, ProductTokenIssuer as t, verifyToken as u, SessionScopedTokenPayload as v, TokenScope as y };

package/dist/{index-D3h0zRzl.d.ts → index-hYNUMvGr.d.ts}

@@ -1,5 +1,5 @@
-import { n as HttpClient, r as SandboxInstance } from "./sandbox-DQmu7a6M.js";
-import { R as CreateSandboxOptions } from "./types-DTDI3kek.js";
+import { n as HttpClient, r as SandboxInstance } from "./sandbox-C8xeDrlS.js";
+import { R as CreateSandboxOptions } from "./types-BZuZPQ0N.js";
 
 //#region src/tangle/abi.d.ts
 /**