@tangle-network/agent-app 0.36.0 → 0.38.0

package/dist/{chunk-GZGF3JWQ.js → chunk-MJ3RUHD4.js}

@@ -1,15 +1,60 @@
 import {
   assertHarnessModelCompatible
 } from "./chunk-5VXPDXZJ.js";
+import {
+  base64UrlDecodeText,
+  base64UrlEncodeText,
+  constantTimeEqual,
+  hmacSha256Base64Url
+} from "./chunk-VT5DI6GL.js";
 import {
   buildAppToolMcpServer
 } from "./chunk-A76ZHWNF.js";
+import {
+  resolveTangleExecutionEnvironment,
+  trimOrNull
+} from "./chunk-7W5XSTUF.js";
 
 // src/sandbox/index.ts
 import {
   Sandbox
 } from "@tangle-network/sandbox";
 
+// src/sandbox/outcome.ts
+var ok = (value) => ({ succeeded: true, value });
+var fail = (error) => ({
+  succeeded: false,
+  error: error instanceof Error ? error : new Error(String(error))
+});
+
+// src/sandbox/terminal-proxy-token.ts
+var TERMINAL_PROXY_TOKEN_TTL_MS = 15 * 60 * 1e3;
+async function mintTerminalProxyToken(secret, identity, ttlMs = TERMINAL_PROXY_TOKEN_TTL_MS, now = Date.now) {
+  if (!secret) return fail(new Error("mintTerminalProxyToken: secret is required"));
+  if (!identity.userId || !identity.workspaceId || !identity.sandboxId) {
+    return fail(new Error("mintTerminalProxyToken: userId/workspaceId/sandboxId are required"));
+  }
+  const expiresAt = new Date(now() + ttlMs);
+  const payload = { ...identity, exp: Math.floor(expiresAt.getTime() / 1e3) };
+  const encoded = base64UrlEncodeText(JSON.stringify(payload));
+  const sig = await hmacSha256Base64Url(encoded, secret);
+  return ok({ token: `${encoded}.${sig}`, expiresAt });
+}
+async function verifyTerminalProxyToken(secret, token, expected, now = Date.now) {
+  if (!secret) return false;
+  const [encoded, sig, extra] = token.split(".");
+  if (!encoded || !sig || extra !== void 0) return false;
+  const expectedSig = await hmacSha256Base64Url(encoded, secret);
+  if (!constantTimeEqual(sig, expectedSig)) return false;
+  let payload;
+  try {
+    payload = JSON.parse(base64UrlDecodeText(encoded));
+  } catch {
+    return false;
+  }
+  return payload.userId === expected.userId && payload.workspaceId === expected.workspaceId && payload.sandboxId === expected.sandboxId && Number.isFinite(payload.exp) && payload.exp > Math.floor(now() / 1e3);
+}
+
 // src/sandbox/workspace-terminal.ts
 function createWorkspaceSandboxManager(opts) {
   return {
@@ -43,9 +88,9 @@ function createWorkspaceSandboxManager(opts) {
     }
   };
 }
-var DEFAULT_TERMINAL_TOKEN_PREFIX = "sbxt_";
 var DEFAULT_TERMINAL_TOKEN_TTL_MS = 15 * 60 * 1e3;
 var BEARER_SUBPROTOCOL_PREFIX = "bearer.";
+var LEGACY_TERMINAL_TOKEN_PREFIX = "sbxt_";
 async function createSandboxTerminalToken(subject, opts) {
   validateTerminalSubject(subject);
   const secret = opts.secret?.trim();
@@ -53,38 +98,16 @@ async function createSandboxTerminalToken(subject, opts) {
   const now = opts.now ?? Date.now;
   const expiresInMs = opts.expiresInMs ?? DEFAULT_TERMINAL_TOKEN_TTL_MS;
   if (!Number.isFinite(expiresInMs) || expiresInMs <= 0) throw new Error("expiresInMs must be a positive number");
-  const expiresAt = new Date(now() + expiresInMs);
-  const payload = {
-    ...subject,
-    exp: Math.floor(expiresAt.getTime() / 1e3),
-    n: crypto.randomUUID()
-  };
-  const encodedPayload = base64urlText(JSON.stringify(payload));
-  const signature = await signText(encodedPayload, secret);
-  return {
-    token: `${opts.prefix ?? DEFAULT_TERMINAL_TOKEN_PREFIX}${encodedPayload}.${signature}`,
-    expiresAt
-  };
+  const minted = await mintTerminalProxyToken(secret, subject, expiresInMs, now);
+  if (!minted.succeeded) throw minted.error;
+  return minted.value;
 }
 async function verifySandboxTerminalToken(token, expected, opts) {
   validateTerminalSubject(expected);
   const secret = opts.secret?.trim();
-  const prefix = opts.prefix ?? DEFAULT_TERMINAL_TOKEN_PREFIX;
-  if (!secret || !token.startsWith(prefix)) return false;
-  const body = token.slice(prefix.length);
-  const dot = body.lastIndexOf(".");
-  if (dot <= 0 || dot === body.length - 1) return false;
-  const encodedPayload = body.slice(0, dot);
-  const signature = body.slice(dot + 1);
-  if (!timingSafeEqual(signature, await signText(encodedPayload, secret))) return false;
-  let payload;
-  try {
-    payload = JSON.parse(textFromBase64url(encodedPayload));
-  } catch {
-    return false;
-  }
   const now = opts.now ?? Date.now;
-  return payload.userId === expected.userId && payload.workspaceId === expected.workspaceId && payload.sandboxId === expected.sandboxId && Number.isFinite(payload.exp) && payload.exp > Math.floor(now() / 1e3);
+  const normalized = token.startsWith(LEGACY_TERMINAL_TOKEN_PREFIX) ? token.slice(LEGACY_TERMINAL_TOKEN_PREFIX.length) : token;
+  return verifyTerminalProxyToken(secret ?? "", normalized, expected, now);
 }
 function createWorkspaceSandboxConnectionHandler(opts) {
   return async function handleWorkspaceSandboxConnection({ request, params }) {
@@ -101,7 +124,7 @@ function createWorkspaceSandboxConnectionHandler(opts) {
         { status: 500 }
       );
     }
-    const directSidecarUrl = box.connection?.sidecarUrl ?? (box.connection?.authToken ? box.connection?.runtimeUrl : void 0);
+    const directSidecarUrl = box.connection?.sidecarUrl ?? box.connection?.runtimeUrl;
     const directSidecarToken = box.connection?.authToken ?? box.connection?.sidecarToken;
     const directSidecarExpiresAt = box.connection?.authTokenExpiresAt;
     if (opts.exposeDirectSidecar && directSidecarUrl && directSidecarToken && directSidecarExpiresAt) {
@@ -114,7 +137,7 @@ function createWorkspaceSandboxConnectionHandler(opts) {
         sandboxId: box.id
       });
     }
-    if (!box.connection?.runtimeUrl) {
+    if (!directSidecarUrl) {
       return Response.json(
         {
           error: "Workspace sandbox runtime not ready. The sandbox is still initializing -- retry in a few seconds.",
@@ -128,7 +151,7 @@ function createWorkspaceSandboxConnectionHandler(opts) {
     try {
       scoped = await createSandboxTerminalToken(
         { userId: user.id, workspaceId, sandboxId: box.id },
-        { secret, expiresInMs: opts.tokenExpiresInMs, prefix: opts.tokenPrefix }
+        { secret, expiresInMs: opts.tokenExpiresInMs }
       );
     } catch (err) {
       return Response.json(
@@ -161,20 +184,21 @@ function createWorkspaceSandboxRuntimeProxyHandler(opts) {
     await opts.requireWorkspaceAccess({ request, userId: user.id, workspaceId, sandboxId });
     const token = terminalTokenFromRequest(request.headers);
     const secret = typeof opts.tokenSecret === "function" ? opts.tokenSecret() : opts.tokenSecret;
-    if (!token || !await verifySandboxTerminalToken(token, { userId: user.id, workspaceId, sandboxId }, { secret, prefix: opts.tokenPrefix })) {
+    if (!token || !await verifySandboxTerminalToken(token, { userId: user.id, workspaceId, sandboxId }, { secret })) {
       return Response.json({ error: "Invalid terminal token" }, { status: 403 });
     }
     const requestUrl = new URL(request.url);
     const runtimeConnection = await opts.getSandboxRuntimeConnection?.({ request, userId: user.id, workspaceId, sandboxId });
-    const credentials = runtimeConnection ? null : await opts.getSandboxApiCredentials({ request, userId: user.id, workspaceId, sandboxId });
-    const upstreamUrl = runtimeConnection ? new URL(encodedRuntimePath, `${runtimeConnection.runtimeUrl.replace(/\/+$/, "")}/`) : new URL(
+    const directRuntimeConnection = runtimeConnection?.runtimeUrl && runtimeConnection.authToken ? runtimeConnection : null;
+    const credentials = directRuntimeConnection ? null : await opts.getSandboxApiCredentials({ request, userId: user.id, workspaceId, sandboxId });
+    const upstreamUrl = directRuntimeConnection ? new URL(encodedRuntimePath, `${directRuntimeConnection.runtimeUrl.replace(/\/+$/, "")}/`) : new URL(
       `/v1/sandboxes/${encodeURIComponent(sandboxId)}/runtime/${encodedRuntimePath}`,
       credentials.baseUrl
     );
     upstreamUrl.search = requestUrl.search;
     const headers = buildSandboxRuntimeProxyHeaders(
       request.headers,
-      runtimeConnection?.authToken ?? credentials.apiKey,
+      directRuntimeConnection?.authToken ?? credentials.apiKey,
       opts.forwardHeaders
     );
     const init = {
@@ -203,7 +227,10 @@ function matchSandboxTerminalWsPath(pathname) {
   if (!m) return null;
   const [, workspaceId, sandboxId, subPath] = m;
   if (!workspaceId || !sandboxId || !subPath) return null;
-  return { workspaceId: decodeURIComponent(workspaceId), sandboxId: decodeURIComponent(sandboxId), subPath };
+  const decodedWorkspaceId = safeDecodeURIComponent(workspaceId);
+  const decodedSandboxId = safeDecodeURIComponent(sandboxId);
+  if (!decodedWorkspaceId || !decodedSandboxId) return null;
+  return { workspaceId: decodedWorkspaceId, sandboxId: decodedSandboxId, subPath };
 }
 function isSandboxTerminalWsUpgrade(request) {
   if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") return false;
@@ -238,16 +265,19 @@ function createWorkspaceSandboxTerminalUpgradeHandler(opts) {
     }
     const token = terminalTokenFromRequest(request.headers);
     const secret = typeof opts.tokenSecret === "function" ? opts.tokenSecret() : opts.tokenSecret;
-    if (!token || !await verifySandboxTerminalToken(token, { userId: user.id, workspaceId, sandboxId }, { secret, prefix: opts.tokenPrefix })) {
+    if (!token || !await verifySandboxTerminalToken(token, { userId: user.id, workspaceId, sandboxId }, { secret })) {
       return new Response("Invalid terminal token", { status: 403 });
     }
     const runtimeConnection = await opts.getSandboxRuntimeConnection?.({ request, userId: user.id, workspaceId, sandboxId });
-    const credentials = runtimeConnection ? null : await opts.getSandboxApiCredentials({ request, userId: user.id, workspaceId, sandboxId });
-    const upstreamUrl = runtimeConnection ? new URL(subPath, `${runtimeConnection.runtimeUrl.replace(/\/+$/, "")}/`) : new URL(`/v1/sandboxes/${encodeURIComponent(sandboxId)}/runtime/${subPath}`, credentials.baseUrl);
+    const directRuntimeConnection = runtimeConnection?.runtimeUrl && runtimeConnection.authToken ? runtimeConnection : null;
+    const credentials = directRuntimeConnection ? null : await opts.getSandboxApiCredentials({ request, userId: user.id, workspaceId, sandboxId });
+    const upstreamUrl = directRuntimeConnection ? new URL(subPath, `${directRuntimeConnection.runtimeUrl.replace(/\/+$/, "")}/`) : new URL(`/v1/sandboxes/${encodeURIComponent(sandboxId)}/runtime/${subPath}`, credentials.baseUrl);
     upstreamUrl.search = url.search;
     const upstreamHeaders = new Headers(request.headers);
-    upstreamHeaders.set("Authorization", `Bearer ${runtimeConnection?.authToken ?? credentials.apiKey}`);
+    const upstreamBearer = directRuntimeConnection?.authToken ?? credentials.apiKey;
+    upstreamHeaders.set("Authorization", `Bearer ${upstreamBearer}`);
     upstreamHeaders.delete("host");
+    stripBearerSubprotocol(upstreamHeaders);
     const fetchImpl = opts.fetch ?? fetch;
     return fetchImpl(upstreamUrl.toString(), { method: request.method, headers: upstreamHeaders });
   };
@@ -286,7 +316,7 @@ function bearerSubprotocolToken(value) {
     const encoded = protocol.slice(BEARER_SUBPROTOCOL_PREFIX.length);
     if (!encoded) return null;
     try {
-      const token = textFromBase64url(encoded).trim();
+      const token = base64UrlDecodeText(encoded).trim();
       return token || null;
     } catch {
       return null;
@@ -297,45 +327,94 @@ function bearerSubprotocolToken(value) {
 function terminalTokenFromRequest(headers) {
   return bearerToken(headers.get("Authorization")) ?? bearerSubprotocolToken(headers.get("Sec-WebSocket-Protocol"));
 }
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}
+function stripBearerSubprotocol(headers) {
+  const value = headers.get("Sec-WebSocket-Protocol");
+  if (!value) return;
+  const protocols = value.split(",").map((part) => part.trim()).filter((part) => part && !part.toLowerCase().startsWith(BEARER_SUBPROTOCOL_PREFIX));
+  if (protocols.length) {
+    headers.set("Sec-WebSocket-Protocol", protocols.join(", "));
+  } else {
+    headers.delete("Sec-WebSocket-Protocol");
+  }
+}
 function validateTerminalSubject(subject) {
   if (!subject.userId) throw new Error("userId is required");
   if (!subject.workspaceId) throw new Error("workspaceId is required");
   if (!subject.sandboxId) throw new Error("sandboxId is required");
 }
-async function signText(message, secret) {
-  const enc = new TextEncoder();
-  const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(message));
-  return base64url(new Uint8Array(sig));
-}
-function base64urlText(text) {
-  return base64url(new TextEncoder().encode(text));
-}
-function textFromBase64url(value) {
-  const b64 = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
-  const bin = atob(b64);
-  const bytes = new Uint8Array(bin.length);
-  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
-  return new TextDecoder().decode(bytes);
-}
-function base64url(bytes) {
-  let s = "";
-  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
-  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function timingSafeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return diff === 0;
-}
 
 // src/sandbox/index.ts
-var ok = (value) => ({ succeeded: true, value });
-var fail = (error) => ({
-  succeeded: false,
-  error: error instanceof Error ? error : new Error(String(error))
-});
+var DEFAULT_SANDBOX_DIRECT_KEY_NAMES = [
+  "TCLOUD_SANDBOX_API_KEY",
+  "SANDBOX_API_KEY",
+  "TANGLE_API_KEY"
+];
+var DEFAULT_SANDBOX_BASE_URL_NAMES = ["SANDBOX_GATEWAY_URL", "SANDBOX_API_URL"];
+function normalizeBaseUrl(value) {
+  return value.trim().replace(/\/v1\/?$/, "").replace(/\/+$/, "");
+}
+function processEnv() {
+  return typeof process === "undefined" ? {} : process.env;
+}
+function directEnvCredentialsAllowed(environment, allow) {
+  if (typeof allow === "function") return allow(environment);
+  if (typeof allow === "boolean") return allow;
+  return environment === "development" || environment === "test";
+}
+function resolveSandboxBaseUrl(env, names, defaultBaseUrl) {
+  for (const name of names) {
+    const value2 = trimOrNull(env[name]);
+    if (value2) return normalizeBaseUrl(value2);
+  }
+  const value = trimOrNull(defaultBaseUrl);
+  if (value) return normalizeBaseUrl(value);
+  throw new Error(
+    `Sandbox base URL is required (set one of ${names.join(", ")} or pass defaultBaseUrl).`
+  );
+}
+function resolveDirectSandboxCredentials(env, keyNames, baseUrlNames, defaultBaseUrl) {
+  for (const name of keyNames) {
+    const apiKey = trimOrNull(env[name]);
+    if (!apiKey) continue;
+    return {
+      apiKey,
+      baseUrl: resolveSandboxBaseUrl(env, baseUrlNames, defaultBaseUrl)
+    };
+  }
+  return null;
+}
+async function resolveSandboxClientCredentials(options = {}) {
+  const env = options.env ?? processEnv();
+  const environment = options.environment ?? resolveTangleExecutionEnvironment(env);
+  const keyNames = options.directKeyNames ?? DEFAULT_SANDBOX_DIRECT_KEY_NAMES;
+  const baseUrlNames = options.baseUrlNames ?? DEFAULT_SANDBOX_BASE_URL_NAMES;
+  const directAllowed = directEnvCredentialsAllowed(environment, options.allowDirectEnvCredentials);
+  const direct = () => directAllowed ? resolveDirectSandboxCredentials(env, keyNames, baseUrlNames, options.defaultBaseUrl) : null;
+  if (environment === "development" || environment === "test") {
+    const credentials2 = direct();
+    if (credentials2) return credentials2;
+  }
+  const provisioned = await options.provision?.({ environment, env });
+  if (provisioned) {
+    return {
+      apiKey: provisioned.apiKey,
+      baseUrl: normalizeBaseUrl(provisioned.baseUrl)
+    };
+  }
+  const credentials = direct();
+  if (credentials) return credentials;
+  const directHint = directAllowed ? ` or set one of ${keyNames.join(", ")}` : "";
+  throw new Error(
+    `Sandbox credentials are required for ${environment} (provide a provision callback${directHint}).`
+  );
+}
 var DEFAULT_SANDBOX_RESOURCES = {
   image: "universal",
   cpuCores: 2,
@@ -380,6 +459,87 @@ function buildAppToolMcpServers(options) {
 function shellSingleQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+var DEFAULT_SANDBOX_TOOL_BASE_DIR = "/home/agent/tools";
+var SAFE_TOOL_SEGMENT = /^[A-Za-z0-9._-]+$/;
+function normalizeSandboxToolSegment(value, label) {
+  const segment = value.trim();
+  if (!segment || segment === "." || segment === ".." || !SAFE_TOOL_SEGMENT.test(segment)) {
+    throw new Error(`${label} must contain only letters, numbers, dots, underscores, or hyphens.`);
+  }
+  return segment;
+}
+function normalizeSandboxToolDir(value, label) {
+  const dir = value.trim().replace(/\/+$/, "");
+  if (!dir || !dir.startsWith("/") || dir.includes("\0") || dir.includes("\n")) {
+    throw new Error(`${label} must be an absolute sandbox path.`);
+  }
+  return dir === "" ? "/" : dir;
+}
+function sandboxToolRootDir(options) {
+  const appName = normalizeSandboxToolSegment(options.appName, "sandbox tool appName");
+  const baseDir = normalizeSandboxToolDir(
+    options.baseDir ?? DEFAULT_SANDBOX_TOOL_BASE_DIR,
+    "sandbox tool baseDir"
+  );
+  return `${baseDir}/${appName}`;
+}
+function sandboxToolBinDir(options) {
+  normalizeSandboxToolSegment(options.appName, "sandbox tool appName");
+  if (options.binDir) return normalizeSandboxToolDir(options.binDir, "sandbox tool binDir");
+  return `${sandboxToolRootDir(options)}/bin`;
+}
+function sandboxToolPath(options) {
+  const toolName = normalizeSandboxToolSegment(options.toolName, "sandbox tool name");
+  return `${sandboxToolBinDir(options)}/${toolName}`;
+}
+function buildSandboxToolFileMounts(options) {
+  return options.tools.map((tool) => {
+    const name = normalizeSandboxToolSegment(tool.name, "sandbox tool name");
+    return {
+      path: sandboxToolPath({ ...options, toolName: name }),
+      resource: { kind: "inline", name, content: tool.content },
+      executable: tool.executable ?? true
+    };
+  });
+}
+function buildSandboxToolPathSetupScript(options) {
+  const binDir = sandboxToolBinDir(options);
+  const exportLine = `export PATH=${binDir}:$PATH`;
+  return [
+    "set -eu",
+    `mkdir -p ${shellSingleQuote(binDir)}`,
+    `PATH=${shellSingleQuote(binDir)}:$PATH`,
+    "export PATH",
+    'for profile in "${HOME:-/home/agent}/.profile" "${HOME:-/home/agent}/.bashrc" "${HOME:-/home/agent}/.zshrc"; do',
+    '  mkdir -p "$(dirname "$profile")"',
+    '  touch "$profile"',
+    `  grep -Fqx ${shellSingleQuote(exportLine)} "$profile" || printf '\\n%s\\n' ${shellSingleQuote(exportLine)} >> "$profile"`,
+    "done"
+  ].join("\n");
+}
+async function runSandboxToolPathSetup(box, options) {
+  try {
+    const res = await box.exec(buildSandboxToolPathSetupScript(options));
+    if (res.exitCode !== 0) {
+      return fail(
+        new Error(
+          `runSandboxToolPathSetup: failed to configure PATH for ${sandboxToolBinDir(options)} (exit ${res.exitCode}): ${res.stderr.slice(0, 500)}`
+        )
+      );
+    }
+    return ok(void 0);
+  } catch (err) {
+    return fail(new Error("runSandboxToolPathSetup: exec failed", { cause: err }));
+  }
+}
+function shellPath(path) {
+  if (path === "~") return '"$HOME"';
+  if (path.startsWith("~/")) {
+    const rest = path.slice(2);
+    return rest ? `"$HOME"/${shellSingleQuote(rest)}` : '"$HOME"';
+  }
+  return shellSingleQuote(path);
+}
 function splitDeferredProfileFiles(profile) {
   const files = profile.resources?.files ?? [];
   const deferredFiles = [];
@@ -395,6 +555,25 @@ function splitDeferredProfileFiles(profile) {
   };
   return { leanProfile, deferredFiles };
 }
+var PROFILE_WRITE_B64_CHUNK_CHARS = 3e3;
+var PROFILE_WRITE_MAX_429_RETRIES = 4;
+var PROFILE_WRITE_RETRY_BASE_MS = 250;
+var PROFILE_WRITE_RETRY_MAX_MS = 2e3;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function rateLimit(err) {
+  if (err && typeof err === "object") {
+    const e = err;
+    const retryAfterMs = typeof e.retryAfterMs === "number" ? e.retryAfterMs : void 0;
+    if (e.status === 429) return { is429: true, retryAfterMs };
+    if (typeof e.code === "string" && /rate.?limit|too.?many.?requests|429/i.test(e.code)) {
+      return { is429: true, retryAfterMs };
+    }
+    if (typeof e.message === "string" && /\b429\b|rate.?limit|too many requests/i.test(e.message)) {
+      return { is429: true, retryAfterMs };
+    }
+  }
+  return { is429: false };
+}
 async function writeProfileFilesToBox(box, files) {
   for (const mount of files) {
     if (mount.resource.kind !== "inline") continue;
@@ -404,22 +583,45 @@ async function writeProfileFilesToBox(box, files) {
     const dir = path.replace(/\/[^/]*$/, "");
     const isBin = /(^|\/)(s?bin)\//.test(path);
     const executable = mount.executable ?? isBin;
-    const q = shellSingleQuote(path);
-    const mkdir = dir && dir !== path ? `mkdir -p ${shellSingleQuote(dir)} && ` : "";
-    const chmod = executable ? ` && chmod +x ${q}` : "";
-    const cmd = `${mkdir}printf '%s' ${shellSingleQuote(b64)} | base64 -d > ${q}${chmod}`;
-    try {
-      const res = await box.exec(cmd);
-      if (res.exitCode !== 0) {
-        return fail(
-          new Error(
-            `writeProfileFilesToBox: failed to write ${path} (exit ${res.exitCode}): ${res.stderr.slice(0, 500)}`
-          )
-        );
+    const q = shellPath(path);
+    const qb64 = shellPath(`${path}.b64`);
+    const step = async (cmd) => {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          const res2 = await box.exec(cmd);
+          if (res2.exitCode !== 0) {
+            return fail(
+              new Error(
+                `writeProfileFilesToBox: failed to write ${path} (exit ${res2.exitCode}): ${res2.stderr.slice(0, 500)}`
+              )
+            );
+          }
+          return ok(void 0);
+        } catch (err) {
+          const { is429, retryAfterMs } = rateLimit(err);
+          if (is429 && attempt < PROFILE_WRITE_MAX_429_RETRIES) {
+            const backoff = Math.min(
+              PROFILE_WRITE_RETRY_BASE_MS * 2 ** attempt,
+              PROFILE_WRITE_RETRY_MAX_MS
+            );
+            await sleep(retryAfterMs ?? backoff);
+            continue;
+          }
+          return fail(new Error(`writeProfileFilesToBox: exec failed for ${path}`, { cause: err }));
+        }
       }
-    } catch (err) {
-      return fail(new Error(`writeProfileFilesToBox: exec failed for ${path}`, { cause: err }));
+    };
+    const mkdir = dir && dir !== path ? `mkdir -p ${shellPath(dir)} && ` : "";
+    let res = await step(`${mkdir}: > ${qb64}`);
+    if (!res.succeeded) return res;
+    for (let i = 0; i < b64.length; i += PROFILE_WRITE_B64_CHUNK_CHARS) {
+      const slice = b64.slice(i, i + PROFILE_WRITE_B64_CHUNK_CHARS);
+      res = await step(`printf '%s' '${slice}' >> ${qb64}`);
+      if (!res.succeeded) return res;
     }
+    const chmod = executable ? ` && chmod +x ${q}` : "";
+    res = await step(`base64 -d ${qb64} > ${q} && rm -f ${qb64}${chmod}`);
+    if (!res.succeeded) return res;
   }
   return ok(void 0);
 }
@@ -479,6 +681,38 @@ async function isBoxAlive(box, harness, probe) {
     return false;
   }
 }
+var RUNTIME_CONNECTION_WAIT_MS = 3e4;
+var RUNTIME_CONNECTION_POLL_MS = 1e3;
+function sandboxRuntimeUrl(box) {
+  const connection = box.connection;
+  return connection?.sidecarUrl ?? connection?.runtimeUrl;
+}
+function sandboxEdgeFailed(box) {
+  const connection = box.connection;
+  return connection?.edgeStatus === "failed" || Boolean(connection?.edgeError);
+}
+async function refreshRuntimeConnection(client, box) {
+  let current = box;
+  if (sandboxRuntimeUrl(current)) return current;
+  const deadline = Date.now() + RUNTIME_CONNECTION_WAIT_MS;
+  while (Date.now() < deadline) {
+    try {
+      await current.refresh();
+      if (sandboxRuntimeUrl(current)) return current;
+      const latest = await client.get(current.id);
+      if (latest) current = latest;
+      if (sandboxRuntimeUrl(current)) return current;
+    } catch {
+    }
+    await new Promise((resolve) => setTimeout(resolve, RUNTIME_CONNECTION_POLL_MS));
+  }
+  return current;
+}
+async function isReusableBox(box, harness, probe) {
+  if (sandboxEdgeFailed(box)) return false;
+  if (!sandboxRuntimeUrl(box)) return false;
+  return isBoxAlive(box, harness, probe);
+}
 async function resumeStoppedBox(client, name, timeoutMs) {
   try {
     const stopped = await client.list({ status: "stopped" });
@@ -508,18 +742,28 @@ async function ensureWorkspaceSandbox(shell, options) {
       if (!dropped.succeeded) {
         throw new Error(`forceNew: sandbox ${name} could not be deleted`, { cause: dropped.error });
       }
-    } else if (found.metadata?.harness === harness && await isBoxAlive(found, harness, shell.livenessProbe)) {
-      const written = await materializeDeferredFilesForExistingBox(shell, found, workspaceId, userId);
-      if (!written.succeeded) {
-        throw new Error(`deferred file write failed on reused box ${name}`, { cause: written.error });
-      }
-      if (shell.bootstrap) {
-        const boot = await shell.bootstrap(found, scope);
-        if (!boot.succeeded) {
-          throw new Error(`bootstrap failed on reused box ${name}`, { cause: boot.error });
+    } else if (found.metadata?.harness === harness) {
+      const ready = await refreshRuntimeConnection(client, found);
+      if (await isReusableBox(ready, harness, shell.livenessProbe)) {
+        const written = await materializeDeferredFilesForExistingBox(shell, ready, workspaceId, userId);
+        if (!written.succeeded) {
+          throw new Error(`deferred file write failed on reused box ${name}`, { cause: written.error });
+        }
+        if (shell.bootstrap) {
+          const boot = await shell.bootstrap(ready, scope);
+          if (!boot.succeeded) {
+            throw new Error(`bootstrap failed on reused box ${name}`, { cause: boot.error });
+          }
         }
+        return ready;
+      }
+      const dropped = await deleteBox(ready);
+      if (!dropped.succeeded) {
+        throw new Error(
+          `sandbox ${name} (was ${String(found.metadata?.harness ?? "unknown")}, want ${harness}, or unresponsive) could not be deleted`,
+          { cause: dropped.error }
+        );
       }
-      return found;
     } else {
       const dropped = await deleteBox(found);
       if (!dropped.succeeded) {
@@ -532,19 +776,28 @@ async function ensureWorkspaceSandbox(shell, options) {
   }
   if (!forceNew && shell.resumeStopped !== false) {
     const resumed = await resumeStoppedBox(client, name, resumeTimeout);
-    if (resumed.succeeded && resumed.value && await isBoxAlive(resumed.value, harness, shell.livenessProbe)) {
-      const box2 = resumed.value;
-      const written = await materializeDeferredFilesForExistingBox(shell, box2, workspaceId, userId);
-      if (!written.succeeded) {
-        throw new Error(`deferred file write failed on resumed box ${name}`, { cause: written.error });
-      }
-      if (shell.bootstrap) {
-        const boot = await shell.bootstrap(box2, scope);
-        if (!boot.succeeded) {
-          throw new Error(`bootstrap failed on resumed box ${name}`, { cause: boot.error });
+    if (resumed.succeeded && resumed.value) {
+      const box2 = await refreshRuntimeConnection(client, resumed.value);
+      if (await isReusableBox(box2, harness, shell.livenessProbe)) {
+        const written = await materializeDeferredFilesForExistingBox(shell, box2, workspaceId, userId);
+        if (!written.succeeded) {
+          throw new Error(`deferred file write failed on resumed box ${name}`, { cause: written.error });
         }
+        if (shell.bootstrap) {
+          const boot = await shell.bootstrap(box2, scope);
+          if (!boot.succeeded) {
+            throw new Error(`bootstrap failed on resumed box ${name}`, { cause: boot.error });
+          }
+        }
+        return box2;
+      }
+      const dropped = await deleteBox(box2);
+      if (!dropped.succeeded) {
+        throw new Error(
+          `resumed sandbox ${name} (was ${String(box2.metadata?.harness ?? "unknown")}, want ${harness}, or unresponsive) could not be deleted`,
+          { cause: dropped.error }
+        );
       }
-      return box2;
     }
   }
   const connectedIntegrationIds = await shell.connectedIntegrationIds(workspaceId);
@@ -585,6 +838,7 @@ async function ensureWorkspaceSandbox(shell, options) {
     backend: { type: harness, profile, ...model ? { model } : {} },
     ...storage ? { storage } : {},
     ...restore ? restore : {},
+    ...shell.webTerminalEnabled ? { webTerminalEnabled: true } : {},
     maxLifetimeSeconds: resources.maxLifetimeSeconds,
     idleTimeoutSeconds: resources.idleTimeoutSeconds,
     resources: {
@@ -593,9 +847,9 @@ async function ensureWorkspaceSandbox(shell, options) {
       diskGB: resources.diskGB
     }
   };
-  const box = await client.create(payload);
+  let box = await client.create(payload);
   await box.waitFor("running", { timeoutMs: 12e4 });
-  if (!box.connection?.runtimeUrl) await box.refresh();
+  box = await refreshRuntimeConnection(client, box);
   if (deferredFiles.length > 0) {
     const written = await writeProfileFilesToBox(box, deferredFiles);
     if (!written.succeeded) {
@@ -828,64 +1082,6 @@ async function driveSandboxTurn(shell, box, message, options) {
     return fail(err);
   }
 }
-var TERMINAL_PROXY_TOKEN_TTL_MS = 15 * 60 * 1e3;
-async function signTerminalProxyToken(secret, encodedPayload) {
-  const key = await crypto.subtle.importKey(
-    "raw",
-    new TextEncoder().encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(encodedPayload));
-  return base64UrlEncodeBytes(new Uint8Array(sig));
-}
-async function mintTerminalProxyToken(secret, identity, ttlMs = TERMINAL_PROXY_TOKEN_TTL_MS) {
-  if (!secret) return fail(new Error("mintTerminalProxyToken: secret is required"));
-  if (!identity.userId || !identity.workspaceId || !identity.sandboxId) {
-    return fail(new Error("mintTerminalProxyToken: userId/workspaceId/sandboxId are required"));
-  }
-  const expiresAt = new Date(Date.now() + ttlMs);
-  const payload = { ...identity, exp: Math.floor(expiresAt.getTime() / 1e3) };
-  const encoded = base64UrlEncodeUtf8(JSON.stringify(payload));
-  const sig = await signTerminalProxyToken(secret, encoded);
-  return ok({ token: `${encoded}.${sig}`, expiresAt });
-}
-async function verifyTerminalProxyToken(secret, token, expected) {
-  if (!secret) return false;
-  const [encoded, sig, extra] = token.split(".");
-  if (!encoded || !sig || extra !== void 0) return false;
-  const expectedSig = await signTerminalProxyToken(secret, encoded);
-  if (!constantTimeEqual(sig, expectedSig)) return false;
-  let payload;
-  try {
-    payload = JSON.parse(base64UrlDecodeUtf8(encoded));
-  } catch {
-    return false;
-  }
-  return payload.userId === expected.userId && payload.workspaceId === expected.workspaceId && payload.sandboxId === expected.sandboxId && Number.isFinite(payload.exp) && payload.exp > Math.floor(Date.now() / 1e3);
-}
-function base64UrlEncodeBytes(bytes) {
-  let bin = "";
-  for (const b of bytes) bin += String.fromCharCode(b);
-  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function base64UrlEncodeUtf8(v) {
-  return base64UrlEncodeBytes(new TextEncoder().encode(v));
-}
-function base64UrlDecodeUtf8(v) {
-  const padded = v.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(v.length / 4) * 4, "=");
-  const bin = atob(padded);
-  const bytes = new Uint8Array(bin.length);
-  for (let i = 0; i < bin.length; i += 1) bytes[i] = bin.charCodeAt(i);
-  return new TextDecoder().decode(bytes);
-}
-function constantTimeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let r = 0;
-  for (let i = 0; i < a.length; i += 1) r |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return r === 0;
-}
 var SEVERED_FINISH_REASONS = /* @__PURE__ */ new Set(["error", "other", "unknown"]);
 function asPlainRecord(v) {
   return v && typeof v === "object" && !Array.isArray(v) ? v : null;
@@ -928,6 +1124,8 @@ function firstQuestionText(value) {
 }
 
 export {
+  mintTerminalProxyToken,
+  verifyTerminalProxyToken,
   createWorkspaceSandboxManager,
   createSandboxTerminalToken,
   verifySandboxTerminalToken,
@@ -941,10 +1139,17 @@ export {
   bearerToken,
   bearerSubprotocolToken,
   terminalTokenFromRequest,
+  resolveSandboxClientCredentials,
   DEFAULT_SANDBOX_RESOURCES,
   getClient,
   resetClientCache,
   buildAppToolMcpServers,
+  sandboxToolRootDir,
+  sandboxToolBinDir,
+  sandboxToolPath,
+  buildSandboxToolFileMounts,
+  buildSandboxToolPathSetupScript,
+  runSandboxToolPathSetup,
   splitDeferredProfileFiles,
   writeProfileFilesToBox,
   ensureWorkspaceSandbox,
@@ -963,10 +1168,8 @@ export {
   deleteSecret,
   mintSandboxScopedToken,
   driveSandboxTurn,
-  mintTerminalProxyToken,
-  verifyTerminalProxyToken,
   classifySeveredStream,
   isTerminalPromptEvent,
   detectInteractiveQuestion
 };
-//# sourceMappingURL=chunk-GZGF3JWQ.js.map
+//# sourceMappingURL=chunk-MJ3RUHD4.js.map