integrate-sdk 0.9.9-dev.0 → 0.9.13-dev.0

package/dist/index.js

@@ -1,4 +1,19 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
@@ -9,6 +24,13 @@ var __export = (target, all) => {
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 
 // src/protocol/jsonrpc.ts
 function parseMessage(message) {
@@ -9015,6 +9037,7 @@ export { callTool };
 var exports_executor = {};
 __export(exports_executor, {
   isSandboxAvailable: () => isSandboxAvailable,
+  getSandboxImportError: () => getSandboxImportError,
   executeSandboxCode: () => executeSandboxCode,
   __setSandboxUnavailableForTests: () => __setSandboxUnavailableForTests,
   __setSandboxFactoryForTests: () => __setSandboxFactoryForTests
@@ -9023,10 +9046,15 @@ function __setSandboxFactoryForTests(factory) {
   sandboxFactoryOverride = factory;
   _sandboxForcedUnavailableForTests = false;
   _sandboxAvailableCache = null;
+  _sandboxImportError = null;
 }
 function __setSandboxUnavailableForTests(force) {
   _sandboxForcedUnavailableForTests = force;
   _sandboxAvailableCache = null;
+  _sandboxImportError = force ? new Error("Sandbox forced unavailable by test seam.") : null;
+}
+function getSandboxImportError() {
+  return _sandboxImportError;
 }
 async function isSandboxAvailable() {
   if (_sandboxAvailableCache !== null)
@@ -9037,15 +9065,17 @@ async function isSandboxAvailable() {
   }
   if (sandboxFactoryOverride) {
     _sandboxAvailableCache = true;
+    _sandboxImportError = null;
     return true;
   }
   try {
-    const dynamicImport = new Function("specifier", "return import(specifier)");
-    await dynamicImport("@" + "vercel/sandbox");
+    await import("@vercel/sandbox");
     _sandboxAvailableCache = true;
+    _sandboxImportError = null;
     return true;
-  } catch {
+  } catch (err) {
     _sandboxAvailableCache = false;
+    _sandboxImportError = err;
     return false;
   }
 }
@@ -9053,12 +9083,12 @@ async function loadSandboxFactory() {
   if (sandboxFactoryOverride)
     return sandboxFactoryOverride;
   try {
-    const dynamicImport = new Function("specifier", "return import(specifier)");
-    const pkg = "@" + "vercel/sandbox";
-    const mod = await dynamicImport(pkg);
+    const mod = await import("@vercel/sandbox");
     return mod.Sandbox ?? mod.default?.Sandbox ?? mod;
   } catch (err) {
-    throw new Error("Code Mode requires the optional peer dependency `@vercel/sandbox`. " + "Install it with `npm install @vercel/sandbox` (or `bun add @vercel/sandbox`).");
+    _sandboxImportError = err;
+    const detail = err instanceof Error ? `: ${err.message}` : "";
+    throw new Error("Code Mode failed to load `@vercel/sandbox`" + detail + ". Ensure the package is installed and reachable at runtime. On Next.js/Vercel, confirm it is listed in `dependencies` (not only `devDependencies`) and that the route using Code Mode runs in the Node.js runtime (not Edge).");
   }
 }
 function wrapUserCode(code) {
@@ -9178,30 +9208,58 @@ async function executeSandboxCode(options) {
     }
   }
 }
-var sandboxFactoryOverride = null, _sandboxAvailableCache = null, _sandboxForcedUnavailableForTests = false, RESULT_SENTINEL = "__INTEGRATE_RESULT__";
+var sandboxFactoryOverride = null, _sandboxAvailableCache = null, _sandboxImportError = null, _sandboxForcedUnavailableForTests = false, RESULT_SENTINEL = "__INTEGRATE_RESULT__";
 var init_executor = () => {};
 
 // src/code-mode/tool-builder.ts
+var exports_tool_builder = {};
+__export(exports_tool_builder, {
+  warnCodeModeFallback: () => warnCodeModeFallback,
+  resolveCodeModePublicUrl: () => resolveCodeModePublicUrl,
+  resolveCodeModeClientConfig: () => resolveCodeModeClientConfig,
+  diagnoseCodeMode: () => diagnoseCodeMode,
+  canUseCodeMode: () => canUseCodeMode,
+  buildCodeModeTool: () => buildCodeModeTool,
+  __resetCodeModeFallbackWarnings: () => __resetCodeModeFallbackWarnings,
+  CODE_MODE_TOOL_NAME: () => CODE_MODE_TOOL_NAME
+});
 function resolveCodeModeClientConfig(client) {
   const oauthConfig = client.__oauthConfig;
   return oauthConfig?.codeMode ?? {};
 }
+function resolveCodeModePublicUrl(serverConfig = {}) {
+  return serverConfig.publicUrl ?? getEnv("INTEGRATE_URL");
+}
 async function diagnoseCodeMode(client) {
   if (!await isSandboxAvailable()) {
     return { available: false, reason: "sandbox-missing" };
   }
   const serverConfig = resolveCodeModeClientConfig(client);
-  const publicUrl = serverConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+  const publicUrl = resolveCodeModePublicUrl(serverConfig);
   if (!publicUrl) {
     return { available: false, reason: "no-public-url" };
   }
   return { available: true };
 }
+async function canUseCodeMode(client) {
+  return (await diagnoseCodeMode(client)).available;
+}
+function buildFallbackMessage(reason) {
+  if (reason === "no-public-url") {
+    return "[integrate-sdk] Code Mode unavailable (reason: no-public-url) — falling back to tool mode. " + "Set `codeMode.publicUrl` on your server config or the `INTEGRATE_URL` env var.";
+  }
+  const importError = getSandboxImportError();
+  const detail = importError instanceof Error ? ` Underlying import error: ${importError.message}` : importError ? ` Underlying import error: ${String(importError)}` : "";
+  return "[integrate-sdk] Code Mode unavailable (reason: sandbox-missing) — falling back to tool mode. " + "Ensure `@vercel/sandbox` is in `dependencies` and the route runs in the Node.js runtime (not Edge)." + detail;
+}
+function __resetCodeModeFallbackWarnings() {
+  warnedCodeModeReasons.clear();
+}
 function warnCodeModeFallback(reason) {
   if (warnedCodeModeReasons.has(reason))
     return;
   warnedCodeModeReasons.add(reason);
-  console.warn(CODE_MODE_UNAVAILABLE_MESSAGES[reason]);
+  console.warn(buildFallbackMessage(reason));
 }
 function buildCodeModeTool(client, options) {
   const { tools, providerTokens, context, integrationIds } = options;
@@ -9214,7 +9272,9 @@ function buildCodeModeTool(client, options) {
 ${generated.source}
 \`\`\``;
   const execute = async ({ code }) => {
-    const publicUrl = sandboxOverrides.publicUrl ?? serverCodeModeConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+    const publicUrl = resolveCodeModePublicUrl({
+      publicUrl: sandboxOverrides.publicUrl ?? serverCodeModeConfig.publicUrl
+    });
     const apiKey = client.__oauthConfig?.apiKey;
     if (!publicUrl) {
       return {
@@ -9223,7 +9283,7 @@ ${generated.source}
         stdout: "",
         stderr: "",
         durationMs: 0,
-        error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_PUBLIC_URL env var). " + "The sandbox uses it to call back into /api/integrate/mcp."
+        error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_URL env var). " + "The sandbox uses it to call back into /api/integrate/mcp."
       };
     }
     const mcpUrl = publicUrl.replace(/\/$/, "") + "/api/integrate/mcp";
@@ -9257,7 +9317,7 @@ ${generated.source}
     execute
   };
 }
-var CODE_MODE_TOOL_NAME = "execute_code", DEFAULT_INSTRUCTIONS, CODE_MODE_UNAVAILABLE_MESSAGES, warnedCodeModeReasons;
+var CODE_MODE_TOOL_NAME = "execute_code", DEFAULT_INSTRUCTIONS, warnedCodeModeReasons;
 var init_tool_builder = __esm(() => {
   init_type_generator();
   init_executor();
@@ -9282,10 +9342,6 @@ var init_tool_builder = __esm(() => {
     "API surface:"
   ].join(`
 `);
-  CODE_MODE_UNAVAILABLE_MESSAGES = {
-    "sandbox-missing": "[integrate-sdk] Code Mode unavailable (reason: sandbox-missing) — falling back to tool mode. " + "Install `@vercel/sandbox` (e.g. `bun add @vercel/sandbox`) to enable Code Mode.",
-    "no-public-url": "[integrate-sdk] Code Mode unavailable (reason: no-public-url) — falling back to tool mode. " + "Set `codeMode.publicUrl` on your server config or the `INTEGRATE_PUBLIC_URL` env var."
-  };
   warnedCodeModeReasons = new Set;
 });
 
@@ -11779,11 +11835,12 @@ function createMCPServer(config) {
           return Response.json({ error: "`code` is required and must be a non-empty string." }, { status: 400 });
         }
         const { executeSandboxCode: executeSandboxCode2 } = await Promise.resolve().then(() => (init_executor(), exports_executor));
+        const { resolveCodeModePublicUrl: resolveCodeModePublicUrl2 } = await Promise.resolve().then(() => (init_tool_builder(), exports_tool_builder));
         const codeModeConfig = config.codeMode ?? {};
-        const publicUrl = codeModeConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+        const publicUrl = resolveCodeModePublicUrl2(codeModeConfig);
         if (!publicUrl) {
           return Response.json({
-            error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_PUBLIC_URL env var). Set it to the public origin where /api/integrate/mcp is reachable."
+            error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_URL env var). Set it to the public origin where /api/integrate/mcp is reachable."
           }, { status: 500 });
         }
         let contextOverride = body.context;

package/dist/oauth.js

@@ -1,4 +1,20 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
@@ -9,6 +25,7 @@ var __export = (target, all) => {
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/utils/logger.ts
 function shouldLog(level, context) {
@@ -8849,6 +8866,7 @@ export { callTool };
 var exports_executor = {};
 __export(exports_executor, {
   isSandboxAvailable: () => isSandboxAvailable,
+  getSandboxImportError: () => getSandboxImportError,
   executeSandboxCode: () => executeSandboxCode,
   __setSandboxUnavailableForTests: () => __setSandboxUnavailableForTests,
   __setSandboxFactoryForTests: () => __setSandboxFactoryForTests
@@ -8857,10 +8875,15 @@ function __setSandboxFactoryForTests(factory) {
   sandboxFactoryOverride = factory;
   _sandboxForcedUnavailableForTests = false;
   _sandboxAvailableCache = null;
+  _sandboxImportError = null;
 }
 function __setSandboxUnavailableForTests(force) {
   _sandboxForcedUnavailableForTests = force;
   _sandboxAvailableCache = null;
+  _sandboxImportError = force ? new Error("Sandbox forced unavailable by test seam.") : null;
+}
+function getSandboxImportError() {
+  return _sandboxImportError;
 }
 async function isSandboxAvailable() {
   if (_sandboxAvailableCache !== null)
@@ -8871,15 +8894,17 @@ async function isSandboxAvailable() {
   }
   if (sandboxFactoryOverride) {
     _sandboxAvailableCache = true;
+    _sandboxImportError = null;
     return true;
   }
   try {
-    const dynamicImport = new Function("specifier", "return import(specifier)");
-    await dynamicImport("@" + "vercel/sandbox");
+    await import("@vercel/sandbox");
     _sandboxAvailableCache = true;
+    _sandboxImportError = null;
     return true;
-  } catch {
+  } catch (err) {
     _sandboxAvailableCache = false;
+    _sandboxImportError = err;
     return false;
   }
 }
@@ -8887,12 +8912,12 @@ async function loadSandboxFactory() {
   if (sandboxFactoryOverride)
     return sandboxFactoryOverride;
   try {
-    const dynamicImport = new Function("specifier", "return import(specifier)");
-    const pkg = "@" + "vercel/sandbox";
-    const mod = await dynamicImport(pkg);
+    const mod = await import("@vercel/sandbox");
     return mod.Sandbox ?? mod.default?.Sandbox ?? mod;
   } catch (err) {
-    throw new Error("Code Mode requires the optional peer dependency `@vercel/sandbox`. " + "Install it with `npm install @vercel/sandbox` (or `bun add @vercel/sandbox`).");
+    _sandboxImportError = err;
+    const detail = err instanceof Error ? `: ${err.message}` : "";
+    throw new Error("Code Mode failed to load `@vercel/sandbox`" + detail + ". Ensure the package is installed and reachable at runtime. On Next.js/Vercel, confirm it is listed in `dependencies` (not only `devDependencies`) and that the route using Code Mode runs in the Node.js runtime (not Edge).");
   }
 }
 function wrapUserCode(code) {
@@ -9012,30 +9037,58 @@ async function executeSandboxCode(options) {
     }
   }
 }
-var sandboxFactoryOverride = null, _sandboxAvailableCache = null, _sandboxForcedUnavailableForTests = false, RESULT_SENTINEL = "__INTEGRATE_RESULT__";
+var sandboxFactoryOverride = null, _sandboxAvailableCache = null, _sandboxImportError = null, _sandboxForcedUnavailableForTests = false, RESULT_SENTINEL = "__INTEGRATE_RESULT__";
 var init_executor = () => {};
 
 // src/code-mode/tool-builder.ts
+var exports_tool_builder = {};
+__export(exports_tool_builder, {
+  warnCodeModeFallback: () => warnCodeModeFallback,
+  resolveCodeModePublicUrl: () => resolveCodeModePublicUrl,
+  resolveCodeModeClientConfig: () => resolveCodeModeClientConfig,
+  diagnoseCodeMode: () => diagnoseCodeMode,
+  canUseCodeMode: () => canUseCodeMode,
+  buildCodeModeTool: () => buildCodeModeTool,
+  __resetCodeModeFallbackWarnings: () => __resetCodeModeFallbackWarnings,
+  CODE_MODE_TOOL_NAME: () => CODE_MODE_TOOL_NAME
+});
 function resolveCodeModeClientConfig(client) {
   const oauthConfig = client.__oauthConfig;
   return oauthConfig?.codeMode ?? {};
 }
+function resolveCodeModePublicUrl(serverConfig = {}) {
+  return serverConfig.publicUrl ?? getEnv("INTEGRATE_URL");
+}
 async function diagnoseCodeMode(client) {
   if (!await isSandboxAvailable()) {
     return { available: false, reason: "sandbox-missing" };
   }
   const serverConfig = resolveCodeModeClientConfig(client);
-  const publicUrl = serverConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+  const publicUrl = resolveCodeModePublicUrl(serverConfig);
   if (!publicUrl) {
     return { available: false, reason: "no-public-url" };
   }
   return { available: true };
 }
+async function canUseCodeMode(client) {
+  return (await diagnoseCodeMode(client)).available;
+}
+function buildFallbackMessage(reason) {
+  if (reason === "no-public-url") {
+    return "[integrate-sdk] Code Mode unavailable (reason: no-public-url) — falling back to tool mode. " + "Set `codeMode.publicUrl` on your server config or the `INTEGRATE_URL` env var.";
+  }
+  const importError = getSandboxImportError();
+  const detail = importError instanceof Error ? ` Underlying import error: ${importError.message}` : importError ? ` Underlying import error: ${String(importError)}` : "";
+  return "[integrate-sdk] Code Mode unavailable (reason: sandbox-missing) — falling back to tool mode. " + "Ensure `@vercel/sandbox` is in `dependencies` and the route runs in the Node.js runtime (not Edge)." + detail;
+}
+function __resetCodeModeFallbackWarnings() {
+  warnedCodeModeReasons.clear();
+}
 function warnCodeModeFallback(reason) {
   if (warnedCodeModeReasons.has(reason))
     return;
   warnedCodeModeReasons.add(reason);
-  console.warn(CODE_MODE_UNAVAILABLE_MESSAGES[reason]);
+  console.warn(buildFallbackMessage(reason));
 }
 function buildCodeModeTool(client, options) {
   const { tools, providerTokens, context, integrationIds } = options;
@@ -9048,7 +9101,9 @@ function buildCodeModeTool(client, options) {
 ${generated.source}
 \`\`\``;
   const execute = async ({ code }) => {
-    const publicUrl = sandboxOverrides.publicUrl ?? serverCodeModeConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+    const publicUrl = resolveCodeModePublicUrl({
+      publicUrl: sandboxOverrides.publicUrl ?? serverCodeModeConfig.publicUrl
+    });
     const apiKey = client.__oauthConfig?.apiKey;
     if (!publicUrl) {
       return {
@@ -9057,7 +9112,7 @@ ${generated.source}
         stdout: "",
         stderr: "",
         durationMs: 0,
-        error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_PUBLIC_URL env var). " + "The sandbox uses it to call back into /api/integrate/mcp."
+        error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_URL env var). " + "The sandbox uses it to call back into /api/integrate/mcp."
       };
     }
     const mcpUrl = publicUrl.replace(/\/$/, "") + "/api/integrate/mcp";
@@ -9091,7 +9146,7 @@ ${generated.source}
     execute
   };
 }
-var CODE_MODE_TOOL_NAME = "execute_code", DEFAULT_INSTRUCTIONS, CODE_MODE_UNAVAILABLE_MESSAGES, warnedCodeModeReasons;
+var CODE_MODE_TOOL_NAME = "execute_code", DEFAULT_INSTRUCTIONS, warnedCodeModeReasons;
 var init_tool_builder = __esm(() => {
   init_type_generator();
   init_executor();
@@ -9116,10 +9171,6 @@ var init_tool_builder = __esm(() => {
     "API surface:"
   ].join(`
 `);
-  CODE_MODE_UNAVAILABLE_MESSAGES = {
-    "sandbox-missing": "[integrate-sdk] Code Mode unavailable (reason: sandbox-missing) — falling back to tool mode. " + "Install `@vercel/sandbox` (e.g. `bun add @vercel/sandbox`) to enable Code Mode.",
-    "no-public-url": "[integrate-sdk] Code Mode unavailable (reason: no-public-url) — falling back to tool mode. " + "Set `codeMode.publicUrl` on your server config or the `INTEGRATE_PUBLIC_URL` env var."
-  };
   warnedCodeModeReasons = new Set;
 });
 
@@ -11613,11 +11664,12 @@ function createMCPServer(config) {
           return Response.json({ error: "`code` is required and must be a non-empty string." }, { status: 400 });
         }
         const { executeSandboxCode: executeSandboxCode2 } = await Promise.resolve().then(() => (init_executor(), exports_executor));
+        const { resolveCodeModePublicUrl: resolveCodeModePublicUrl2 } = await Promise.resolve().then(() => (init_tool_builder(), exports_tool_builder));
         const codeModeConfig = config.codeMode ?? {};
-        const publicUrl = codeModeConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+        const publicUrl = resolveCodeModePublicUrl2(codeModeConfig);
         if (!publicUrl) {
           return Response.json({
-            error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_PUBLIC_URL env var). Set it to the public origin where /api/integrate/mcp is reachable."
+            error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_URL env var). Set it to the public origin where /api/integrate/mcp is reachable."
           }, { status: 500 });
         }
         let contextOverride = body.context;

package/dist/react.js

@@ -1,4 +1,19 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
@@ -9,6 +24,13 @@ var __export = (target, all) => {
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 
 // src/utils/logger.ts
 function shouldLog(level, context) {

package/dist/server.js

@@ -1,4 +1,20 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
@@ -9,6 +25,7 @@ var __export = (target, all) => {
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/protocol/jsonrpc.ts
 function parseMessage(message) {
@@ -9529,6 +9546,7 @@ export { callTool };
 var exports_executor = {};
 __export(exports_executor, {
   isSandboxAvailable: () => isSandboxAvailable,
+  getSandboxImportError: () => getSandboxImportError,
   executeSandboxCode: () => executeSandboxCode,
   __setSandboxUnavailableForTests: () => __setSandboxUnavailableForTests,
   __setSandboxFactoryForTests: () => __setSandboxFactoryForTests
@@ -9537,10 +9555,15 @@ function __setSandboxFactoryForTests(factory) {
   sandboxFactoryOverride = factory;
   _sandboxForcedUnavailableForTests = false;
   _sandboxAvailableCache = null;
+  _sandboxImportError = null;
 }
 function __setSandboxUnavailableForTests(force) {
   _sandboxForcedUnavailableForTests = force;
   _sandboxAvailableCache = null;
+  _sandboxImportError = force ? new Error("Sandbox forced unavailable by test seam.") : null;
+}
+function getSandboxImportError() {
+  return _sandboxImportError;
 }
 async function isSandboxAvailable() {
   if (_sandboxAvailableCache !== null)
@@ -9551,15 +9574,17 @@ async function isSandboxAvailable() {
   }
   if (sandboxFactoryOverride) {
     _sandboxAvailableCache = true;
+    _sandboxImportError = null;
     return true;
   }
   try {
-    const dynamicImport = new Function("specifier", "return import(specifier)");
-    await dynamicImport("@" + "vercel/sandbox");
+    await import("@vercel/sandbox");
     _sandboxAvailableCache = true;
+    _sandboxImportError = null;
     return true;
-  } catch {
+  } catch (err) {
     _sandboxAvailableCache = false;
+    _sandboxImportError = err;
     return false;
   }
 }
@@ -9567,12 +9592,12 @@ async function loadSandboxFactory() {
   if (sandboxFactoryOverride)
     return sandboxFactoryOverride;
   try {
-    const dynamicImport = new Function("specifier", "return import(specifier)");
-    const pkg = "@" + "vercel/sandbox";
-    const mod = await dynamicImport(pkg);
+    const mod = await import("@vercel/sandbox");
     return mod.Sandbox ?? mod.default?.Sandbox ?? mod;
   } catch (err) {
-    throw new Error("Code Mode requires the optional peer dependency `@vercel/sandbox`. " + "Install it with `npm install @vercel/sandbox` (or `bun add @vercel/sandbox`).");
+    _sandboxImportError = err;
+    const detail = err instanceof Error ? `: ${err.message}` : "";
+    throw new Error("Code Mode failed to load `@vercel/sandbox`" + detail + ". Ensure the package is installed and reachable at runtime. On Next.js/Vercel, confirm it is listed in `dependencies` (not only `devDependencies`) and that the route using Code Mode runs in the Node.js runtime (not Edge).");
   }
 }
 function wrapUserCode(code) {
@@ -9692,30 +9717,58 @@ async function executeSandboxCode(options) {
     }
   }
 }
-var sandboxFactoryOverride = null, _sandboxAvailableCache = null, _sandboxForcedUnavailableForTests = false, RESULT_SENTINEL = "__INTEGRATE_RESULT__";
+var sandboxFactoryOverride = null, _sandboxAvailableCache = null, _sandboxImportError = null, _sandboxForcedUnavailableForTests = false, RESULT_SENTINEL = "__INTEGRATE_RESULT__";
 var init_executor = () => {};
 
 // src/code-mode/tool-builder.ts
+var exports_tool_builder = {};
+__export(exports_tool_builder, {
+  warnCodeModeFallback: () => warnCodeModeFallback,
+  resolveCodeModePublicUrl: () => resolveCodeModePublicUrl,
+  resolveCodeModeClientConfig: () => resolveCodeModeClientConfig,
+  diagnoseCodeMode: () => diagnoseCodeMode,
+  canUseCodeMode: () => canUseCodeMode,
+  buildCodeModeTool: () => buildCodeModeTool,
+  __resetCodeModeFallbackWarnings: () => __resetCodeModeFallbackWarnings,
+  CODE_MODE_TOOL_NAME: () => CODE_MODE_TOOL_NAME
+});
 function resolveCodeModeClientConfig(client) {
   const oauthConfig = client.__oauthConfig;
   return oauthConfig?.codeMode ?? {};
 }
+function resolveCodeModePublicUrl(serverConfig = {}) {
+  return serverConfig.publicUrl ?? getEnv("INTEGRATE_URL");
+}
 async function diagnoseCodeMode(client) {
   if (!await isSandboxAvailable()) {
     return { available: false, reason: "sandbox-missing" };
   }
   const serverConfig = resolveCodeModeClientConfig(client);
-  const publicUrl = serverConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+  const publicUrl = resolveCodeModePublicUrl(serverConfig);
   if (!publicUrl) {
     return { available: false, reason: "no-public-url" };
   }
   return { available: true };
 }
+async function canUseCodeMode(client) {
+  return (await diagnoseCodeMode(client)).available;
+}
+function buildFallbackMessage(reason) {
+  if (reason === "no-public-url") {
+    return "[integrate-sdk] Code Mode unavailable (reason: no-public-url) — falling back to tool mode. " + "Set `codeMode.publicUrl` on your server config or the `INTEGRATE_URL` env var.";
+  }
+  const importError = getSandboxImportError();
+  const detail = importError instanceof Error ? ` Underlying import error: ${importError.message}` : importError ? ` Underlying import error: ${String(importError)}` : "";
+  return "[integrate-sdk] Code Mode unavailable (reason: sandbox-missing) — falling back to tool mode. " + "Ensure `@vercel/sandbox` is in `dependencies` and the route runs in the Node.js runtime (not Edge)." + detail;
+}
+function __resetCodeModeFallbackWarnings() {
+  warnedCodeModeReasons.clear();
+}
 function warnCodeModeFallback(reason) {
   if (warnedCodeModeReasons.has(reason))
     return;
   warnedCodeModeReasons.add(reason);
-  console.warn(CODE_MODE_UNAVAILABLE_MESSAGES[reason]);
+  console.warn(buildFallbackMessage(reason));
 }
 function buildCodeModeTool(client, options) {
   const { tools, providerTokens, context, integrationIds } = options;
@@ -9728,7 +9781,9 @@ function buildCodeModeTool(client, options) {
 ${generated.source}
 \`\`\``;
   const execute = async ({ code }) => {
-    const publicUrl = sandboxOverrides.publicUrl ?? serverCodeModeConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+    const publicUrl = resolveCodeModePublicUrl({
+      publicUrl: sandboxOverrides.publicUrl ?? serverCodeModeConfig.publicUrl
+    });
     const apiKey = client.__oauthConfig?.apiKey;
     if (!publicUrl) {
       return {
@@ -9737,7 +9792,7 @@ ${generated.source}
         stdout: "",
         stderr: "",
         durationMs: 0,
-        error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_PUBLIC_URL env var). " + "The sandbox uses it to call back into /api/integrate/mcp."
+        error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_URL env var). " + "The sandbox uses it to call back into /api/integrate/mcp."
       };
     }
     const mcpUrl = publicUrl.replace(/\/$/, "") + "/api/integrate/mcp";
@@ -9771,7 +9826,7 @@ ${generated.source}
     execute
   };
 }
-var CODE_MODE_TOOL_NAME = "execute_code", DEFAULT_INSTRUCTIONS, CODE_MODE_UNAVAILABLE_MESSAGES, warnedCodeModeReasons;
+var CODE_MODE_TOOL_NAME = "execute_code", DEFAULT_INSTRUCTIONS, warnedCodeModeReasons;
 var init_tool_builder = __esm(() => {
   init_type_generator();
   init_executor();
@@ -9796,10 +9851,6 @@ var init_tool_builder = __esm(() => {
     "API surface:"
   ].join(`
 `);
-  CODE_MODE_UNAVAILABLE_MESSAGES = {
-    "sandbox-missing": "[integrate-sdk] Code Mode unavailable (reason: sandbox-missing) — falling back to tool mode. " + "Install `@vercel/sandbox` (e.g. `bun add @vercel/sandbox`) to enable Code Mode.",
-    "no-public-url": "[integrate-sdk] Code Mode unavailable (reason: no-public-url) — falling back to tool mode. " + "Set `codeMode.publicUrl` on your server config or the `INTEGRATE_PUBLIC_URL` env var."
-  };
   warnedCodeModeReasons = new Set;
 });
 
@@ -12293,11 +12344,12 @@ function createMCPServer(config) {
           return Response.json({ error: "`code` is required and must be a non-empty string." }, { status: 400 });
         }
         const { executeSandboxCode: executeSandboxCode2 } = await Promise.resolve().then(() => (init_executor(), exports_executor));
+        const { resolveCodeModePublicUrl: resolveCodeModePublicUrl2 } = await Promise.resolve().then(() => (init_tool_builder(), exports_tool_builder));
         const codeModeConfig = config.codeMode ?? {};
-        const publicUrl = codeModeConfig.publicUrl ?? getEnv("INTEGRATE_PUBLIC_URL");
+        const publicUrl = resolveCodeModePublicUrl2(codeModeConfig);
         if (!publicUrl) {
           return Response.json({
-            error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_PUBLIC_URL env var). Set it to the public origin where /api/integrate/mcp is reachable."
+            error: "Code Mode requires `codeMode.publicUrl` in createMCPServer config (or the INTEGRATE_URL env var). Set it to the public origin where /api/integrate/mcp is reachable."
           }, { status: 500 });
         }
         let contextOverride = body.context;

package/dist/src/code-mode/executor.d.ts

@@ -45,6 +45,14 @@ interface SandboxFactory {
 export declare function __setSandboxFactoryForTests(factory: SandboxFactory | null): void;
 /** @internal — used by unit tests to simulate missing @vercel/sandbox. */
 export declare function __setSandboxUnavailableForTests(force: boolean): void;
+/**
+ * Returns the most recent error observed while attempting to import
+ * `@vercel/sandbox`. Useful for surfacing the root cause when the availability
+ * check returns `false` — the warning in `tool-builder.ts` pipes this through
+ * to the user so they don't have to guess whether it's a missing package, a
+ * bundler issue, or a runtime restriction.
+ */
+export declare function getSandboxImportError(): unknown;
 export declare function isSandboxAvailable(): Promise<boolean>;
 export interface ExecuteSandboxCodeOptions {
     /** Source code the LLM produced. Treated as an async function body. */