managed-deepagents 0.5.4-dev.2 → 0.5.4-dev.21

package/dist/runtime/sandbox-manager.d.ts

@@ -1,39 +1,40 @@
-import type { SandboxBackendProtocolV2 } from "deepagents";
+import { type SandboxBackendProtocolV2 } from "deepagents";
 import type { IdentityDefinition } from "../identity/index.js";
 import type { SandboxDefinition } from "../sandbox.js";
 import { type Connector } from "./connector.js";
 import type { ManagedRunConfig } from "./types.js";
-type LangSmithSandboxClientLoader = () => Promise<{
-    SandboxClient: new (options?: {
-        apiKey?: string;
-    }) => {
-        createSandbox(options?: Record<string, unknown>): Promise<unknown>;
-        getSandbox?(name: string): Promise<unknown>;
-        startSandbox?(name: string): Promise<unknown>;
-        deleteSandbox?(name: string): Promise<void>;
-    };
-}>;
+/** Deployment secret naming the recipe snapshot baked at `mda deploy`. */
+export declare const RECIPE_SNAPSHOT_ENV = "MDA_SANDBOX_RECIPE_SNAPSHOT";
+/**
+ * Env var naming the workspace the CLI baked the recipe snapshot into.
+ *
+ * `mda deploy` sets it on the deployment and `mda dev` stages it into the local
+ * `.env`. Sandboxes and snapshots are workspace-scoped, so the runtime must
+ * send it too — an API key whose default workspace differs from this one
+ * resolves `snapshotName` in the wrong workspace and 404s on the recipe.
+ */
+export declare const WORKSPACE_ID_ENV = "LANGSMITH_WORKSPACE_ID";
 /** Optional runtime inputs that drive connector sandbox provisioning. */
 export interface ResolveManagedSandboxOptions {
     connectors?: Connector[];
     identity?: IdentityDefinition;
 }
 /**
- * Resolve (and cache) the scoped LangSmith sandbox backend for this run,
- * provisioning it with `setup.sh` the first time it is created.
+ * Resolve (and cache) the per-thread LangSmith sandbox backend for this run.
+ * When deploy baked a recipe, new sandboxes clone it; otherwise Host supplies
+ * its default image.
  *
  * Connectors that implement {@link Connector.sandbox} run on create, when a
  * new thread starts against a reused sandbox (mode `"reuse"`), and on later
  * messages in an already-synced thread (mode `"credentials"`).
  */
-export declare function resolveManagedSandbox(sandbox: SandboxDefinition, setupScript: string | undefined, config: ManagedRunConfig | undefined, options?: ResolveManagedSandboxOptions): Promise<SandboxBackendProtocolV2>;
-/** Derive the process-level reuse key from the configured sandbox scope. */
-export declare function sandboxScopeKey(sandbox: SandboxDefinition, config: ManagedRunConfig | undefined): string;
+export declare function resolveManagedSandbox(sandbox: SandboxDefinition, config: ManagedRunConfig | undefined, options?: ResolveManagedSandboxOptions): Promise<SandboxBackendProtocolV2>;
+/** Derive the process-level reuse key (always one sandbox per thread). */
+export declare function sandboxScopeKey(config: ManagedRunConfig | undefined): string;
 /** Clear the process-level sandbox cache. Test-only. */
 export declare function clearManagedSandboxCacheForTests(): void;
 /** Options that pin invalidation to the sandbox that actually failed. */
 export interface InvalidateManagedSandboxOptions {
-    setupScript?: string;
     /** Backend id captured before the failing operation. */
     expectedBackendId?: string;
     /** Host box name captured before the failing operation. */
@@ -43,7 +44,7 @@ export interface InvalidateManagedSandboxOptions {
  * Drop a cached sandbox and delete its Host box so recreate cannot adopt it.
  *
  * Process-cache clear alone is not enough under deploy: names are deterministic
- * per scope, so the next resolve would re-adopt the same broken box. Mark the
+ * per thread, so the next resolve would re-adopt the same broken box. Mark the
  * name blocked (delete can lag) and best-effort `deleteSandbox`.
  *
  * When `expectedBackendId` / `expectedHostName` are set, only pop the cache
@@ -51,18 +52,11 @@ export interface InvalidateManagedSandboxOptions {
  * already have replaced it — deleting the replacement would strand the healthy
  * recreate.
  */
-export declare function invalidateManagedSandbox(sandbox: SandboxDefinition, config: ManagedRunConfig | undefined, setupScriptOrOptions?: string | InvalidateManagedSandboxOptions): Promise<void>;
+export declare function invalidateManagedSandbox(sandbox: SandboxDefinition, config: ManagedRunConfig | undefined, options?: InvalidateManagedSandboxOptions): Promise<void>;
 /** Host box name recorded for a resolved backend instance. */
 export declare function managedSandboxHostName(backend: object): string | undefined;
 /** True when a sandbox API error is worth invalidating + recreating once. */
 export declare function isTransientSandboxError(error: unknown): boolean;
-/** Override the LangSmith SDK loader. Test-only. */
-export declare function setLangSmithSandboxClientLoaderForTests(loader?: LangSmithSandboxClientLoader): void;
-/** Override the DeepAgents LangSmith backend wrapper. Test-only. */
-export declare function setLangSmithSandboxBackendForTests(backend?: new (options: {
-    sandbox: unknown;
-    defaultTimeout?: number;
-}) => object): void;
 /**
  * Deployment this runtime belongs to, used to name the sandboxes it creates so
  * `mda delete` can find them again.
@@ -72,27 +66,29 @@ export declare function setLangSmithSandboxBackendForTests(backend?: new (option
  * local `mda dev`, where sandboxes stay unnamed and LangSmith generates a name.
  */
 export declare function managedDeploymentName(): string | undefined;
-/** How a sandbox was provisioned, beyond the scope it serves. */
-export interface SandboxProvisioning {
-    /** Options handed to `createSandbox` (snapshot, sizing, TTLs). */
-    createOptions?: Record<string, unknown>;
-    /** Contents of the project's `setup.sh`, if it has one. */
-    setupScript?: string;
-}
 /**
- * Deterministic sandbox name for a deployment, sandbox scope, and provisioning
- * recipe.
+ * Deterministic sandbox name for a deployment and thread.
  *
- * The inputs are digested rather than embedded because the scope key carries
- * thread and assistant UUIDs; a short digest keeps the name clear of any length
- * limit while staying stable across container restarts, which is what lets a
- * restarted deployment re-adopt its sandbox instead of leaking it.
+ * The thread key is digested rather than embedded so names stay short and
+ * stable across container restarts. Recipe (`setup.sh` / bake base) changes do
+ * **not** rename live boxes — new threads clone the new recipe; live threads
+ * keep `/workspace` until idle reclaim.
+ */
+export declare function managedSandboxName(deployment: string, scopeKey: string): string;
+/**
+ * Options for `createSandbox`. Thread boxes clone the deploy-baked recipe when
+ * present; author `snapshotName` / `snapshotId` / `dockerImage` are bake bases
+ * only and are not passed here.
+ */
+export declare function sandboxCreateOptions(sandbox: SandboxDefinition): Record<string, unknown>;
+/**
+ * Constructor options for the LangSmith sandbox client.
  *
- * Provisioning is part of the identity so that editing `setup.sh` or switching
- * snapshots produces a different name. An adopted sandbox skips provisioning, so
- * without this a redeploy would silently leave existing threads on the old
- * environment.
+ * Both the API key and the workspace scope come from the environment `mda`
+ * wrote, so every sandbox call lands in the workspace holding the baked recipe.
  */
-export declare function managedSandboxName(deployment: string, scopeKey: string, provisioning?: SandboxProvisioning): string;
-export {};
+export declare function sandboxClientOptions(sandbox: SandboxDefinition): {
+    apiKey?: string;
+    headers?: Record<string, string>;
+} | undefined;
 //# sourceMappingURL=sandbox-manager.d.ts.map

package/dist/runtime/sandbox-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../../src/runtime/sandbox-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../../src/runtime/sandbox-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,gCAAgC,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,2BAA2B,CAAC;AAuEzD,yEAAyE;AACzE,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,wBAAwB,CAAC,CAwEnC;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GAAG,MAAM,CAE5E;AAED,wDAAwD;AACxD,wBAAgB,gCAAgC,IAAI,IAAI,CAGvD;AAED,yEAAyE;AACzE,MAAM,WAAW,+BAA+B;IAC9C,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAiEf;AAED,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E;AA+BD,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAe/D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,SAAS,CAK1D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAMR;AAkED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBzB;AAYD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,GACzB;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,SAAS,CAYnE"}

package/dist/runtime/sandbox-manager.js

@@ -1,17 +1,37 @@
 import { createHash, randomBytes } from "node:crypto";
+import { LangSmithSandbox } from "deepagents";
+import { Sandbox, SandboxClient } from "langsmith/sandbox";
 import { hasSandboxConnectors, runConnectorSandboxHooks, } from "./connector.js";
-import { runSetupScript } from "./setup-script.js";
-import { isSandboxStreamError } from "./sandbox-stream-retry.js";
+import { HOST_SANDBOX_NAME_LIMIT } from "./sandbox-names.js";
+/** Deployment secret naming the recipe snapshot baked at `mda deploy`. */
+export const RECIPE_SNAPSHOT_ENV = "MDA_SANDBOX_RECIPE_SNAPSHOT";
 /**
- * Created sandboxes, keyed by scope, reused for the lifetime of this runtime
- * process. Storing the in-flight promise dedupes concurrent runs and guarantees
- * `setup.sh` is executed only once per newly created sandbox.
+ * Env var naming the workspace the CLI baked the recipe snapshot into.
+ *
+ * `mda deploy` sets it on the deployment and `mda dev` stages it into the local
+ * `.env`. Sandboxes and snapshots are workspace-scoped, so the runtime must
+ * send it too — an API key whose default workspace differs from this one
+ * resolves `snapshotName` in the wrong workspace and 404s on the recipe.
+ */
+export const WORKSPACE_ID_ENV = "LANGSMITH_WORKSPACE_ID";
+/** Header the LangSmith APIs use to scope a request to one workspace. */
+const TENANT_HEADER = "X-Tenant-Id";
+/**
+ * Created sandboxes, keyed by thread, reused for the lifetime of this runtime
+ * process. Storing the in-flight promise dedupes concurrent runs. Provisioning
+ * (`setup.sh`) happens at deploy bake, not on thread create.
  */
 const managedSandboxes = new Map();
 /** Host box names that must not be re-adopted after invalidate until recreate. */
 const invalidatedSandboxNames = new Set();
 /** Host box name for a resolved backend instance (survives cache replacement). */
 const backendHostNames = new WeakMap();
+/** Cold-box race: command stream died before the sandbox accepted the command. */
+const STREAM_NEVER_STARTED_RE = /Command stream ended before ['"]started['"] message/i;
+const STREAM_NEVER_STARTED_NAMES = new Set([
+    "_StreamEndedBeforeStarted",
+    "StreamEndedBeforeStarted",
+]);
 /**
  * Separator between the deployment name and the identity digest in a managed
  * sandbox name.
@@ -24,32 +44,28 @@ const backendHostNames = new WeakMap();
 const SANDBOX_NAME_SEPARATOR = "--";
 /** Hex characters of the identity digest kept in a sandbox name. */
 const SANDBOX_DIGEST_LENGTH = 12;
+const SANDBOX_FALLBACK_SUFFIX_LENGTH = 9;
+const MAX_PRIMARY_DEPLOYMENT_COMPONENT_LENGTH = HOST_SANDBOX_NAME_LIMIT -
+    SANDBOX_NAME_SEPARATOR.length -
+    SANDBOX_DIGEST_LENGTH;
+const MAX_FALLBACK_DEPLOYMENT_COMPONENT_LENGTH = MAX_PRIMARY_DEPLOYMENT_COMPONENT_LENGTH - SANDBOX_FALLBACK_SUFFIX_LENGTH;
+const SANDBOX_DEPLOYMENT_DIGEST_LENGTH = 8;
 /** Sandbox statuses that can be adopted as-is. */
 const ADOPTABLE_STATUS = new Set(["ready", "running"]);
 /** Sandbox status for one that is stopped but restartable. */
 const STOPPED_STATUS = "stopped";
-const defaultLangSmithSandboxClientLoader = async () => {
-    const dynamicImport = new Function("specifier", "return import(specifier)");
-    return (await dynamicImport("langsmith/sandbox"));
-};
-let langSmithSandboxClientLoader = defaultLangSmithSandboxClientLoader;
-const defaultLangSmithSandboxBackendLoader = async () => {
-    const { LangSmithSandbox } = await import("deepagents");
-    return LangSmithSandbox;
-};
-let langSmithSandboxBackendLoader = defaultLangSmithSandboxBackendLoader;
 /**
- * Resolve (and cache) the scoped LangSmith sandbox backend for this run,
- * provisioning it with `setup.sh` the first time it is created.
+ * Resolve (and cache) the per-thread LangSmith sandbox backend for this run.
+ * When deploy baked a recipe, new sandboxes clone it; otherwise Host supplies
+ * its default image.
  *
  * Connectors that implement {@link Connector.sandbox} run on create, when a
  * new thread starts against a reused sandbox (mode `"reuse"`), and on later
  * messages in an already-synced thread (mode `"credentials"`).
  */
-export function resolveManagedSandbox(sandbox, setupScript, config, options) {
-    const key = sandboxScopeKey(sandbox, config);
+export function resolveManagedSandbox(sandbox, config, options) {
+    const key = sandboxScopeKey(config);
     const hasSandbox = hasSandboxConnectors(options?.connectors);
-    const threadKey = threadSyncKey(sandbox, config);
     let entry = managedSandboxes.get(key);
     if (!entry) {
         const created = {
@@ -57,7 +73,7 @@ export function resolveManagedSandbox(sandbox, setupScript, config, options) {
             syncChain: Promise.resolve(),
             freshlyCreated: true,
             ready: Promise.resolve().then(async () => {
-                const { backend, hostName } = await createLangSmithSandbox(sandbox, setupScript, config, options, "create", key);
+                const { backend, hostName } = await createLangSmithSandbox(sandbox, config, options, "create", key);
                 created.hostName = hostName;
                 const id = backend.id;
                 created.backendId =
@@ -65,7 +81,7 @@ export function resolveManagedSandbox(sandbox, setupScript, config, options) {
                 if (hostName) {
                     backendHostNames.set(backend, hostName);
                 }
-                created.syncedThreads.add(threadKey);
+                created.syncedThreads.add(key);
                 return backend;
             }),
         };
@@ -89,7 +105,7 @@ export function resolveManagedSandbox(sandbox, setupScript, config, options) {
                 cached.freshlyCreated = false;
                 return;
             }
-            if (cached.syncedThreads.has(threadKey)) {
+            if (cached.syncedThreads.has(key)) {
                 // Same thread: refresh credentials / CLI wiring without re-cloning.
                 // Otherwise redeploys that fix auth (e.g. gh wrapper) never apply mid-thread.
                 await runConnectorSandboxHooks(options?.connectors, {
@@ -107,18 +123,14 @@ export function resolveManagedSandbox(sandbox, setupScript, config, options) {
                 config,
                 identity: options?.identity,
             });
-            cached.syncedThreads.add(threadKey);
+            cached.syncedThreads.add(key);
         });
         await cached.syncChain;
         return backend;
     });
 }
-/** Derive the process-level reuse key from the configured sandbox scope. */
-export function sandboxScopeKey(sandbox, config) {
-    const scope = sandbox.options?.scope ?? "thread";
-    if (scope === "agent") {
-        return `agent:${assistantIdFromConfig(config)}`;
-    }
+/** Derive the process-level reuse key (always one sandbox per thread). */
+export function sandboxScopeKey(config) {
     return `thread:${threadIdFromConfig(config)}`;
 }
 /** Clear the process-level sandbox cache. Test-only. */
@@ -130,7 +142,7 @@ export function clearManagedSandboxCacheForTests() {
  * Drop a cached sandbox and delete its Host box so recreate cannot adopt it.
  *
  * Process-cache clear alone is not enough under deploy: names are deterministic
- * per scope, so the next resolve would re-adopt the same broken box. Mark the
+ * per thread, so the next resolve would re-adopt the same broken box. Mark the
  * name blocked (delete can lag) and best-effort `deleteSandbox`.
  *
  * When `expectedBackendId` / `expectedHostName` are set, only pop the cache
@@ -138,13 +150,9 @@ export function clearManagedSandboxCacheForTests() {
  * already have replaced it — deleting the replacement would strand the healthy
  * recreate.
  */
-export async function invalidateManagedSandbox(sandbox, config, setupScriptOrOptions) {
-    const options = typeof setupScriptOrOptions === "string" ||
-        setupScriptOrOptions === undefined
-        ? { setupScript: setupScriptOrOptions }
-        : setupScriptOrOptions;
-    const { setupScript, expectedBackendId, expectedHostName } = options;
-    const key = sandboxScopeKey(sandbox, config);
+export async function invalidateManagedSandbox(sandbox, config, options = {}) {
+    const { expectedBackendId, expectedHostName } = options;
+    const key = sandboxScopeKey(config);
     const names = new Set();
     let popCache = true;
     let entry = managedSandboxes.get(key);
@@ -180,7 +188,7 @@ export async function invalidateManagedSandbox(sandbox, config, setupScriptOrOpt
         expectedBackendId === undefined &&
         expectedHostName === undefined) {
         try {
-            const computed = hostSandboxNameFor(sandbox, config, setupScript);
+            const computed = hostSandboxNameFor(config);
             if (computed) {
                 names.add(computed);
             }
@@ -201,11 +209,33 @@ export async function invalidateManagedSandbox(sandbox, config, setupScriptOrOpt
 export function managedSandboxHostName(backend) {
     return backendHostNames.get(backend);
 }
+/**
+ * True when execute failed before the sandbox accepted the command.
+ *
+ * Matches only the cold-box readiness race (named error or message). Ambiguous
+ * stream/transport errors may have already started a command — those belong on
+ * other recreate matchers, not this classifier.
+ */
+function isSandboxStreamError(error) {
+    if (error instanceof Error && STREAM_NEVER_STARTED_NAMES.has(error.name)) {
+        return true;
+    }
+    if (error !== null &&
+        typeof error === "object" &&
+        STREAM_NEVER_STARTED_NAMES.has(error.constructor?.name ?? "")) {
+        return true;
+    }
+    const message = error instanceof Error
+        ? `${error.name}: ${error.message}`
+        : typeof error === "string"
+            ? error
+            : String(error);
+    return STREAM_NEVER_STARTED_RE.test(message);
+}
 /** True when a sandbox API error is worth invalidating + recreating once. */
 export function isTransientSandboxError(error) {
-    // Never-started stream race is also recreate-safe (and retried in place first
-    // by executeWithStreamRetry during provision). Truncated HTTP bodies and
-    // peer-closed errors are recreate-only — do not replay in place.
+    // Never-started stream race is recreate-safe. Truncated HTTP bodies and
+    // peer-closed errors are recreate-only as well.
     if (isSandboxStreamError(error)) {
         return true;
     }
@@ -216,16 +246,6 @@ export function isTransientSandboxError(error) {
             : String(error);
     return /LangSmithSandboxError|HTTP 502|Bad Gateway|HTTP 503|HTTP 504|ECONNRESET|ETIMEDOUT|peer closed connection without sending complete message body|incomplete chunked read|sandbox.*(not found|gone|unavailable|terminated)/i.test(message);
 }
-/** Override the LangSmith SDK loader. Test-only. */
-export function setLangSmithSandboxClientLoaderForTests(loader) {
-    langSmithSandboxClientLoader = loader ?? defaultLangSmithSandboxClientLoader;
-}
-/** Override the DeepAgents LangSmith backend wrapper. Test-only. */
-export function setLangSmithSandboxBackendForTests(backend) {
-    langSmithSandboxBackendLoader = backend
-        ? async () => backend
-        : defaultLangSmithSandboxBackendLoader;
-}
 /**
  * Deployment this runtime belongs to, used to name the sandboxes it creates so
  * `mda delete` can find them again.
@@ -239,35 +259,40 @@ export function managedDeploymentName() {
         stringOption(process.env.MDA_DEPLOYMENT_NAME));
 }
 /**
- * Deterministic sandbox name for a deployment, sandbox scope, and provisioning
- * recipe.
+ * Deterministic sandbox name for a deployment and thread.
  *
- * The inputs are digested rather than embedded because the scope key carries
- * thread and assistant UUIDs; a short digest keeps the name clear of any length
- * limit while staying stable across container restarts, which is what lets a
- * restarted deployment re-adopt its sandbox instead of leaking it.
- *
- * Provisioning is part of the identity so that editing `setup.sh` or switching
- * snapshots produces a different name. An adopted sandbox skips provisioning, so
- * without this a redeploy would silently leave existing threads on the old
- * environment.
+ * The thread key is digested rather than embedded so names stay short and
+ * stable across container restarts. Recipe (`setup.sh` / bake base) changes do
+ * **not** rename live boxes — new threads clone the new recipe; live threads
+ * keep `/workspace` until idle reclaim.
  */
-export function managedSandboxName(deployment, scopeKey, provisioning = {}) {
+export function managedSandboxName(deployment, scopeKey) {
+    return managedSandboxNameWithDeploymentLimit(deployment, scopeKey, MAX_PRIMARY_DEPLOYMENT_COMPONENT_LENGTH);
+}
+function managedSandboxFallbackName(deployment, scopeKey) {
+    return `${managedSandboxNameWithDeploymentLimit(deployment, scopeKey, MAX_FALLBACK_DEPLOYMENT_COMPONENT_LENGTH)}-${sandboxNameSuffix()}`;
+}
+function managedSandboxNameWithDeploymentLimit(deployment, scopeKey, deploymentLimit) {
     const digest = createHash("sha256")
         .update(scopeKey)
-        .update("\0")
-        .update(provisioningFingerprint(provisioning))
         .digest("hex")
         .slice(0, SANDBOX_DIGEST_LENGTH);
-    return `${deployment}${SANDBOX_NAME_SEPARATOR}${digest}`;
+    return `${sandboxDeploymentComponent(deployment, deploymentLimit)}${SANDBOX_NAME_SEPARATOR}${digest}`;
 }
-/** Stable string for a provisioning recipe, insensitive to option ordering. */
-function provisioningFingerprint(provisioning) {
-    const createOptions = Object.entries(provisioning.createOptions ?? {}).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
-    return JSON.stringify([createOptions, provisioning.setupScript ?? ""]);
+function sandboxDeploymentComponent(deployment, maxLength) {
+    const characters = Array.from(deployment);
+    if (characters.length <= maxLength) {
+        return deployment;
+    }
+    const digest = createHash("sha256")
+        .update(deployment)
+        .digest("hex")
+        .slice(0, SANDBOX_DEPLOYMENT_DIGEST_LENGTH);
+    const prefixLength = maxLength - SANDBOX_DEPLOYMENT_DIGEST_LENGTH - 1;
+    return `${characters.slice(0, prefixLength).join("")}-${digest}`;
 }
-async function createLangSmithSandbox(sandbox, setupScript, config, options, mode, scopeKey) {
-    const { backend, adopted, hostName } = await createLangSmithSandboxBackend(sandbox, scopeKey, setupScript);
+async function createLangSmithSandbox(sandbox, config, options, mode, scopeKey) {
+    const { backend, adopted, hostName } = await createLangSmithSandboxBackend(sandbox, scopeKey);
     await runConnectorSandboxHooks(options?.connectors, {
         backend,
         // An adopted sandbox already ran create-time provisioning in an earlier
@@ -276,46 +301,52 @@ async function createLangSmithSandbox(sandbox, setupScript, config, options, mod
         config,
         identity: options?.identity,
     });
-    // Only a new sandbox needs `setup.sh`: an adopted one ran this exact script
-    // already, since a changed script yields a different sandbox name.
-    if (!adopted && setupScript && setupScript.trim().length > 0) {
-        await runSetupScript(backend, setupScript);
-    }
     return { backend, hostName };
 }
-function sandboxCreateOptions(sandbox) {
-    const { scope: _scope, apiKey: _apiKey, defaultTimeout: _defaultTimeout, templateName, snapshotId, ...resolvedCreateOptions } = sandbox.options ?? {};
-    const createSandboxOptions = resolvedCreateOptions;
-    if (snapshotId && templateName) {
-        throw new Error("snapshotId and templateName are mutually exclusive. Pass only one creation source.");
-    }
-    if (templateName) {
-        createSandboxOptions.snapshotName = templateName;
-    }
-    if (snapshotId) {
-        createSandboxOptions.snapshotId = snapshotId;
+/**
+ * Options for `createSandbox`. Thread boxes clone the deploy-baked recipe when
+ * present; author `snapshotName` / `snapshotId` / `dockerImage` are bake bases
+ * only and are not passed here.
+ */
+export function sandboxCreateOptions(sandbox) {
+    const { apiKey: _apiKey, defaultTimeout: _defaultTimeout, snapshotName: _snapshotName, snapshotId: _snapshotId, dockerImage: _dockerImage, registry: _registry, ...resolvedCreateOptions } = sandbox.options ?? {};
+    const createSandboxOptions = {
+        ...resolvedCreateOptions,
+    };
+    const recipe = stringOption(process.env[RECIPE_SNAPSHOT_ENV]);
+    if (recipe) {
+        createSandboxOptions.snapshotName = recipe;
     }
     return createSandboxOptions;
 }
-function hostSandboxNameFor(sandbox, config, setupScript) {
+function hostSandboxNameFor(config) {
     const deployment = managedDeploymentName();
     if (!deployment) {
         return undefined;
     }
-    return managedSandboxName(deployment, sandboxScopeKey(sandbox, config), {
-        createOptions: sandboxCreateOptions(sandbox),
-        setupScript,
-    });
+    return managedSandboxName(deployment, sandboxScopeKey(config));
 }
-async function sandboxClientFor(sandbox) {
-    const { SandboxClient } = await langSmithSandboxClientLoader();
+/**
+ * Constructor options for the LangSmith sandbox client.
+ *
+ * Both the API key and the workspace scope come from the environment `mda`
+ * wrote, so every sandbox call lands in the workspace holding the baked recipe.
+ */
+export function sandboxClientOptions(sandbox) {
     const apiKey = stringOption(sandbox.options?.apiKey) ??
         stringOption(process.env.LANGSMITH_API_KEY);
-    return new SandboxClient(apiKey ? { apiKey } : undefined);
+    const workspaceId = stringOption(process.env[WORKSPACE_ID_ENV]);
+    if (!apiKey && !workspaceId) {
+        return undefined;
+    }
+    return {
+        ...(apiKey ? { apiKey } : {}),
+        ...(workspaceId ? { headers: { [TENANT_HEADER]: workspaceId } } : {}),
+    };
 }
 async function deleteHostSandbox(sandbox, name) {
     try {
-        const client = await sandboxClientFor(sandbox);
+        const client = new SandboxClient(sandboxClientOptions(sandbox));
         if (typeof client.deleteSandbox !== "function") {
             return;
         }
@@ -329,29 +360,25 @@ async function deleteHostSandbox(sandbox, name) {
         console.warn(`[mda] sandbox invalidate: delete failed name=${JSON.stringify(name)} err=${label}`);
     }
 }
-async function createLangSmithSandboxBackend(sandbox, scopeKey, setupScript) {
-    const { apiKey = process.env.LANGSMITH_API_KEY, defaultTimeout } = sandbox.options ?? {};
+async function createLangSmithSandboxBackend(sandbox, scopeKey) {
+    const { defaultTimeout } = sandbox.options ?? {};
     const createSandboxOptions = sandboxCreateOptions(sandbox);
-    const { SandboxClient } = await langSmithSandboxClientLoader();
-    const sdkOptions = stringOption(apiKey);
-    const client = new SandboxClient(sdkOptions ? { apiKey: sdkOptions } : undefined);
+    const client = new SandboxClient(sandboxClientOptions(sandbox));
     const deployment = managedDeploymentName();
     const sandboxName = deployment
-        ? managedSandboxName(deployment, scopeKey, {
-            createOptions: createSandboxOptions,
-            setupScript,
-        })
+        ? managedSandboxName(deployment, scopeKey)
+        : undefined;
+    const fallbackName = deployment
+        ? () => managedSandboxFallbackName(deployment, scopeKey)
         : undefined;
-    const { sandbox: langSmithSandbox, adopted } = await resolveSandboxInstance(client, createSandboxOptions, sandboxName);
-    const resolved = langSmithSandbox;
-    const hostName = stringOption(resolved.name) ?? sandboxName;
+    const { sandbox: langSmithSandbox, adopted } = await resolveSandboxInstance(client, createSandboxOptions, sandboxName, fallbackName);
+    const hostName = stringOption(langSmithSandbox.name) ?? sandboxName;
     console.info(`[mda] sandbox resolve: ${adopted ? "adopted" : "created"} ` +
         `name=${JSON.stringify(hostName ?? null)} ` +
-        `id=${JSON.stringify(resolved.id ?? null)} ` +
+        `id=${JSON.stringify(langSmithSandbox.id ?? null)} ` +
         `scope=${JSON.stringify(scopeKey)}`);
-    const Backend = await langSmithSandboxBackendLoader();
     return {
-        backend: new Backend({
+        backend: new LangSmithSandbox({
             sandbox: langSmithSandbox,
             defaultTimeout,
         }),
@@ -366,7 +393,7 @@ async function createLangSmithSandboxBackend(sandbox, scopeKey, setupScript) {
  * finds the sandbox its predecessor created instead of stranding it until the
  * idle TTL fires. When `name` is undefined (local dev) this is a plain create.
  */
-async function resolveSandboxInstance(client, createSandboxOptions, name) {
+async function resolveSandboxInstance(client, createSandboxOptions, name, fallbackName) {
     if (!name) {
         return {
             sandbox: await client.createSandbox(createSandboxOptions),
@@ -403,7 +430,7 @@ async function resolveSandboxInstance(client, createSandboxOptions, name) {
         // Keep the deployment prefix so teardown still finds this sandbox.
         const created = await client.createSandbox({
             ...createSandboxOptions,
-            name: `${name}-${sandboxNameSuffix()}`,
+            name: fallbackName?.() ?? `${name}-${sandboxNameSuffix()}`,
         });
         invalidatedSandboxNames.delete(name);
         return { sandbox: created, adopted: false };
@@ -426,9 +453,6 @@ async function adoptSandbox(client, name) {
     catch {
         return undefined;
     }
-    if (existing === undefined || existing === null) {
-        return undefined;
-    }
     const status = stringOption(existing.status)?.toLowerCase();
     // No status reported: assume the SDK handed back a usable sandbox.
     if (status === undefined || ADOPTABLE_STATUS.has(status)) {
@@ -452,29 +476,13 @@ function isSandboxNameConflict(error) {
 function sandboxNameSuffix() {
     return randomBytes(4).toString("hex");
 }
-function threadSyncKey(sandbox, config) {
-    const scope = sandbox.options?.scope ?? "thread";
-    if (scope === "agent") {
-        // Agent-scoped sandboxes are shared; sync once per thread that uses them.
-        try {
-            return `thread:${threadIdFromConfig(config)}`;
-        }
-        catch {
-            return "thread:__missing__";
-        }
-    }
-    return sandboxScopeKey(sandbox, config);
-}
 function threadIdFromConfig(config) {
     const threadId = configValue(config, "thread_id");
     if (threadId === undefined) {
-        throw new Error('sandbox scope "thread" requires configurable.thread_id');
+        throw new Error("managed sandboxes require configurable.thread_id (one sandbox per thread)");
     }
     return threadId;
 }
-function assistantIdFromConfig(config) {
-    return configValue(config, "assistant_id") ?? "agent";
-}
 function stringOption(value) {
     if (typeof value !== "string")
         return undefined;