@cloudflare/sandbox 0.7.4 → 0.7.6

package/dist/openai/index.d.ts

@@ -1,4 +1,4 @@
-import { t as Sandbox } from "../sandbox-CgjQQZGw.js";
+import { t as Sandbox } from "../sandbox-DGAjk7r3.js";
 import { ApplyPatchOperation, ApplyPatchResult, Editor as Editor$1, Shell as Shell$1, ShellAction, ShellResult } from "@openai/agents";
 
 //#region src/openai/index.d.ts

package/dist/opencode/index.d.ts

@@ -1,5 +1,5 @@
-import { t as Sandbox } from "../sandbox-CgjQQZGw.js";
-import { t as OpencodeStartupContext } from "../contexts-uY_burk0.js";
+import { t as Sandbox } from "../sandbox-DGAjk7r3.js";
+import { o as OpencodeStartupContext } from "../contexts-BHx40XTT.js";
 import { OpencodeClient } from "@opencode-ai/sdk/v2/client";
 import { Config } from "@opencode-ai/sdk/v2";
 
@@ -141,6 +141,14 @@ declare function createOpencodeServer(sandbox: Sandbox<unknown>, options?: Openc
  * ```
  */
 declare function createOpencode<TClient = OpencodeClient>(sandbox: Sandbox<unknown>, options?: OpencodeOptions): Promise<OpencodeResult<TClient>>;
+/**
+ * Proxy a request directly to the OpenCode server.
+ *
+ * Unlike `proxyToOpencode()`, this helper does not apply any web UI redirects
+ * or query parameter rewrites. Use it for API/CLI traffic where raw request
+ * forwarding is preferred.
+ */
+declare function proxyToOpencodeServer(request: Request, sandbox: Sandbox<unknown>, server: OpencodeServer): Promise<Response>;
 /**
  * Proxy a request to the OpenCode web UI.
  *
@@ -190,5 +198,5 @@ declare function createOpencode<TClient = OpencodeClient>(sandbox: Sandbox<unkno
  */
 declare function proxyToOpencode(request: Request, sandbox: Sandbox<unknown>, server: OpencodeServer): Response | Promise<Response>;
 //#endregion
-export { type OpencodeOptions, type OpencodeResult, type OpencodeServer, OpencodeStartupError, createOpencode, createOpencodeServer, proxyToOpencode };
+export { type OpencodeOptions, type OpencodeResult, type OpencodeServer, OpencodeStartupError, createOpencode, createOpencodeServer, proxyToOpencode, proxyToOpencodeServer };
 //# sourceMappingURL=index.d.ts.map

package/dist/opencode/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/opencode/types.ts","../../src/opencode/opencode.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOiB,UAAA,eAAA,CAMN;EAMM;EAaA,IAAA,CAAA,EAAA,MAAA;EAAyB;EAEhC,SAAA,CAAA,EAAA,MAAA;EAEA;EAAc,MAAA,CAAA,EAvBb,MAuBa;AAMxB;;;;AAA0C,UAvBzB,cAAA,CAuByB;EAAK;;;;ECgQzB;EACX,KAAA,EAAA,EDlRA,OCkRA,CAAA,IAAA,CAAA;;;;;AAiEX;AAA+C,UD5U9B,cC4U8B,CAAA,UD5UL,cC4UK,CAAA,CAAA;EACpC;EACC,MAAA,ED5UF,OC4UE;EACc;EAAf,MAAA,ED3UD,cC2UC;;;AAkEX;;AAEW,cDzYE,oBAAA,SAA6B,KAAA,CCyY/B;EACD,SAAA,IAAA,EAAA,yBAAA;EACP,SAAA,OAAA,EDzYwB,sBCyYxB;EAAmB,WAAA,CAAA,OAAA,EAAA,MAAA,EAAA,OAAA,EDrYT,sBCqYS,EAAA,OAAA,CAAA,EDpYR,YCoYQ;;;;;;;AD9atB;AAYA;AAaA;;;;;AAUA;;;;;;;;;ACgQA;;;;;;AAkEA;;;;;;;;AAqEA;;;;;;;;;;;;;iBAvIsB,oBAAA,UACX,4BACC,kBACT,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+DW,yBAAyB,yBACpC,4BACC,kBACT,QAAQ,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkEV,eAAA,UACL,kBACA,0BACD,iBACP,WAAW,QAAQ"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/opencode/types.ts","../../src/opencode/opencode.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOiB,UAAA,eAAA,CAMN;EAMM;EAaA,IAAA,CAAA,EAAA,MAAA;EAAyB;EAEhC,SAAA,CAAA,EAAA,MAAA;EAEA;EAAc,MAAA,CAAA,EAvBb,MAuBa;AAMxB;;;;AAA0C,UAvBzB,cAAA,CAuByB;EAAK;;;;ECoQzB;EACX,KAAA,EAAA,EDtRA,OCsRA,CAAA,IAAA,CAAA;;;;;AAiEX;AAA+C,UDhV9B,cCgV8B,CAAA,UDhVL,cCgVK,CAAA,CAAA;EACpC;EACC,MAAA,EDhVF,OCgVE;EACc;EAAf,MAAA,ED/UD,cC+UC;;;AA0BX;;AAEW,cDrWE,oBAAA,SAA6B,KAAA,CCqW/B;EACD,SAAA,IAAA,EAAA,yBAAA;EACC,SAAA,OAAA,EDrWgB,sBCqWhB;EAAR,WAAA,CAAA,OAAA,EAAA,MAAA,EAAA,OAAA,EDjWU,sBCiWV,EAAA,OAAA,CAAA,EDhWW,YCgWX;;;;;;;AD1YH;AAYA;AAaA;;;;;AAUA;;;;;;;;;ACoQA;;;;;;AAkEA;;;;;;;;AA6BA;;;;;;;AAuDA;;;;;;AAIc,iBA1JQ,oBAAA,CA0JR,OAAA,EAzJH,OAyJG,CAAA,OAAA,CAAA,EAAA,OAAA,CAAA,EAxJF,eAwJE,CAAA,EAvJX,OAuJW,CAvJH,cAuJG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAxFQ,yBAAyB,yBACpC,4BACC,kBACT,QAAQ,eAAe;;;;;;;;iBA0BV,qBAAA,UACL,kBACA,0BACD,iBACP,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmDK,eAAA,UACL,kBACA,0BACD,iBACP,WAAW,QAAQ"}

package/dist/opencode/index.js

@@ -1,5 +1,5 @@
 import { l as createLogger } from "../dist-D9B_6gn_.js";
-import { t as ErrorCode } from "../errors-Bzl0ZNia.js";
+import { t as ErrorCode } from "../errors-CYUY62c6.js";
 
 //#region src/opencode/types.ts
 /**
@@ -24,6 +24,7 @@ function getLogger() {
 	});
 }
 const DEFAULT_PORT = 4096;
+const OPENCODE_STARTUP_TIMEOUT_MS = 18e4;
 const OPENCODE_SERVE = (port) => `opencode serve --port ${port} --hostname 0.0.0.0`;
 /**
 * Build the full command, optionally with a directory prefix.
@@ -72,8 +73,9 @@ async function ensureOpencodeServer(sandbox, port, directory, config) {
 			try {
 				await existingProcess.waitForPort(port, {
 					mode: "http",
-					path: "/",
-					timeout: 6e4
+					path: "/global/health",
+					status: 200,
+					timeout: OPENCODE_STARTUP_TIMEOUT_MS
 				});
 			} catch (e) {
 				const logs = await existingProcess.getLogs();
@@ -102,8 +104,9 @@ async function ensureOpencodeServer(sandbox, port, directory, config) {
 			if (retryProcess.status === "starting") try {
 				await retryProcess.waitForPort(port, {
 					mode: "http",
-					path: "/",
-					timeout: 6e4
+					path: "/global/health",
+					status: 200,
+					timeout: OPENCODE_STARTUP_TIMEOUT_MS
 				});
 			} catch (e) {
 				const logs = await retryProcess.getLogs();
@@ -153,8 +156,9 @@ async function startOpencodeServer(sandbox, port, directory, config) {
 	try {
 		await process.waitForPort(port, {
 			mode: "http",
-			path: "/",
-			timeout: 6e4
+			path: "/global/health",
+			status: 200,
+			timeout: OPENCODE_STARTUP_TIMEOUT_MS
 		});
 		getLogger().info("OpenCode server started successfully", {
 			port,
@@ -291,6 +295,16 @@ async function createOpencode(sandbox, options) {
 	};
 }
 /**
+* Proxy a request directly to the OpenCode server.
+*
+* Unlike `proxyToOpencode()`, this helper does not apply any web UI redirects
+* or query parameter rewrites. Use it for API/CLI traffic where raw request
+* forwarding is preferred.
+*/
+function proxyToOpencodeServer(request, sandbox, server) {
+	return sandbox.containerFetch(request, server.port);
+}
+/**
 * Proxy a request to the OpenCode web UI.
 *
 * This function handles the redirect and proxying only - you must start the
@@ -345,9 +359,9 @@ function proxyToOpencode(request, sandbox, server) {
 			return Response.redirect(url.toString(), 302);
 		}
 	}
-	return sandbox.containerFetch(request, server.port);
+	return proxyToOpencodeServer(request, sandbox, server);
 }
 
 //#endregion
-export { OpencodeStartupError, createOpencode, createOpencodeServer, proxyToOpencode };
+export { OpencodeStartupError, createOpencode, createOpencodeServer, proxyToOpencode, proxyToOpencodeServer };
 //# sourceMappingURL=index.js.map

package/dist/opencode/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["createOpencodeClient: OpencodeClientFactory | undefined","env: Record<string, string>"],"sources":["../../src/opencode/types.ts","../../src/opencode/opencode.ts"],"sourcesContent":["import type { Config } from '@opencode-ai/sdk/v2';\nimport type { OpencodeClient } from '@opencode-ai/sdk/v2/client';\nimport { ErrorCode, type OpencodeStartupContext } from '@repo/shared/errors';\n\n/**\n * Configuration options for starting OpenCode server\n */\nexport interface OpencodeOptions {\n  /** Port for OpenCode server (default: 4096) */\n  port?: number;\n  /** Working directory for OpenCode (default: container's cwd) */\n  directory?: string;\n  /** OpenCode configuration */\n  config?: Config;\n}\n\n/**\n * Server lifecycle management\n */\nexport interface OpencodeServer {\n  /** Port the server is running on */\n  port: number;\n  /** Base URL for SDK client (http://localhost:{port}) */\n  url: string;\n  /** Close the server gracefully */\n  close(): Promise<void>;\n}\n\n/**\n * Result from createOpencode()\n * Client type comes from @opencode-ai/sdk (user's version)\n */\nexport interface OpencodeResult<TClient = OpencodeClient> {\n  /** OpenCode SDK client with Sandbox transport */\n  client: TClient;\n  /** Server lifecycle management */\n  server: OpencodeServer;\n}\n\n/**\n * Error thrown when OpenCode server fails to start\n */\nexport class OpencodeStartupError extends Error {\n  public readonly code = ErrorCode.OPENCODE_STARTUP_FAILED;\n  public readonly context: OpencodeStartupContext;\n\n  constructor(\n    message: string,\n    context: OpencodeStartupContext,\n    options?: ErrorOptions\n  ) {\n    super(message, options);\n    this.name = 'OpencodeStartupError';\n    this.context = context;\n  }\n}\n","import type { Config } from '@opencode-ai/sdk/v2';\nimport type { OpencodeClient } from '@opencode-ai/sdk/v2/client';\nimport { createLogger, type Logger, type Process } from '@repo/shared';\nimport type { Sandbox } from '../sandbox';\nimport type { OpencodeOptions, OpencodeResult, OpencodeServer } from './types';\nimport { OpencodeStartupError } from './types';\n\n// Lazy logger creation to avoid global scope restrictions in Workers\nfunction getLogger(): Logger {\n  return createLogger({ component: 'sandbox-do', operation: 'opencode' });\n}\n\nconst DEFAULT_PORT = 4096;\nconst OPENCODE_SERVE = (port: number) =>\n  `opencode serve --port ${port} --hostname 0.0.0.0`;\n\n/**\n * Build the full command, optionally with a directory prefix.\n * If directory is provided, we cd to it first so OpenCode uses it as cwd.\n */\nfunction buildOpencodeCommand(port: number, directory?: string): string {\n  const serve = OPENCODE_SERVE(port);\n  return directory ? `cd ${directory} && ${serve}` : serve;\n}\n\ntype OpencodeClientFactory = (options: {\n  baseUrl: string;\n  fetch: typeof fetch;\n  directory?: string;\n}) => OpencodeClient;\n\n// Dynamic import to handle peer dependency\nlet createOpencodeClient: OpencodeClientFactory | undefined;\n\nasync function ensureSdkLoaded(): Promise<void> {\n  if (createOpencodeClient) return;\n\n  try {\n    const sdk = await import('@opencode-ai/sdk/v2/client');\n    createOpencodeClient = sdk.createOpencodeClient as OpencodeClientFactory;\n  } catch {\n    throw new Error(\n      '@opencode-ai/sdk is required for OpenCode integration. ' +\n        'Install it with: npm install @opencode-ai/sdk'\n    );\n  }\n}\n\n/**\n * Find an existing OpenCode server process running on the specified port.\n * Returns the process if found and still active, null otherwise.\n * Matches by the serve command pattern since directory prefix may vary.\n */\nasync function findExistingOpencodeProcess(\n  sandbox: Sandbox<unknown>,\n  port: number\n): Promise<Process | null> {\n  const processes = await sandbox.listProcesses();\n  const serveCommand = OPENCODE_SERVE(port);\n\n  for (const proc of processes) {\n    // Match commands that contain the serve command (with or without cd prefix)\n    if (proc.command.includes(serveCommand)) {\n      if (proc.status === 'starting' || proc.status === 'running') {\n        return proc;\n      }\n    }\n  }\n\n  return null;\n}\n\n/**\n * Ensures OpenCode server is running in the container.\n * Reuses existing process if one is already running on the specified port.\n * Handles concurrent startup attempts gracefully by retrying on failure.\n * Returns the process handle.\n */\nasync function ensureOpencodeServer(\n  sandbox: Sandbox<unknown>,\n  port: number,\n  directory?: string,\n  config?: Config\n): Promise<Process> {\n  // Check if OpenCode is already running on this port\n  const existingProcess = await findExistingOpencodeProcess(sandbox, port);\n  if (existingProcess) {\n    // Reuse existing process - wait for it to be ready if still starting\n    if (existingProcess.status === 'starting') {\n      getLogger().debug('Found starting OpenCode process, waiting for ready', {\n        port,\n        processId: existingProcess.id\n      });\n      try {\n        await existingProcess.waitForPort(port, {\n          mode: 'http',\n          path: '/',\n          timeout: 60_000\n        });\n      } catch (e) {\n        const logs = await existingProcess.getLogs();\n        throw new OpencodeStartupError(\n          `OpenCode server failed to start. Stderr: ${logs.stderr || '(empty)'}`,\n          { port, stderr: logs.stderr, command: existingProcess.command },\n          { cause: e }\n        );\n      }\n    }\n    getLogger().debug('Reusing existing OpenCode process', {\n      port,\n      processId: existingProcess.id\n    });\n    return existingProcess;\n  }\n\n  // Try to start a new OpenCode server\n  try {\n    return await startOpencodeServer(sandbox, port, directory, config);\n  } catch (startupError) {\n    // Startup failed - check if another concurrent request started the server\n    // This handles the race condition where multiple requests try to start simultaneously\n    const retryProcess = await findExistingOpencodeProcess(sandbox, port);\n    if (retryProcess) {\n      getLogger().debug(\n        'Startup failed but found concurrent process, reusing',\n        {\n          port,\n          processId: retryProcess.id\n        }\n      );\n      // Wait for the concurrent server to be ready\n      if (retryProcess.status === 'starting') {\n        try {\n          await retryProcess.waitForPort(port, {\n            mode: 'http',\n            path: '/',\n            timeout: 60_000\n          });\n        } catch (e) {\n          const logs = await retryProcess.getLogs();\n          throw new OpencodeStartupError(\n            `OpenCode server failed to start. Stderr: ${logs.stderr || '(empty)'}`,\n            { port, stderr: logs.stderr, command: retryProcess.command },\n            { cause: e }\n          );\n        }\n      }\n      return retryProcess;\n    }\n\n    // No concurrent server found - the failure was genuine\n    throw startupError;\n  }\n}\n\n/**\n * Internal function to start a new OpenCode server process.\n */\nasync function startOpencodeServer(\n  sandbox: Sandbox<unknown>,\n  port: number,\n  directory?: string,\n  config?: Config\n): Promise<Process> {\n  getLogger().info('Starting OpenCode server', { port, directory });\n\n  // Pass config via OPENCODE_CONFIG_CONTENT and also extract API keys to env vars\n  // because OpenCode's provider auth looks for env vars like ANTHROPIC_API_KEY\n  const env: Record<string, string> = {};\n\n  if (config) {\n    env.OPENCODE_CONFIG_CONTENT = JSON.stringify(config);\n\n    // Extract API keys from provider config\n    // Support both options.apiKey (official type) and legacy top-level apiKey\n    if (\n      config.provider &&\n      typeof config.provider === 'object' &&\n      !Array.isArray(config.provider)\n    ) {\n      for (const [providerId, providerConfig] of Object.entries(\n        config.provider\n      )) {\n        if (providerId === 'cloudflare-ai-gateway') {\n          continue;\n        }\n\n        // Try options.apiKey first (official Config type)\n        let apiKey = providerConfig?.options?.apiKey;\n        // Fall back to top-level apiKey for convenience\n        if (!apiKey) {\n          apiKey = (providerConfig as Record<string, unknown> | undefined)\n            ?.apiKey as string | undefined;\n        }\n        if (typeof apiKey === 'string') {\n          const envVar = `${providerId.toUpperCase()}_API_KEY`;\n          env[envVar] = apiKey;\n        }\n      }\n\n      const aiGatewayConfig = config.provider['cloudflare-ai-gateway'];\n      if (aiGatewayConfig?.options) {\n        const options = aiGatewayConfig.options as Record<string, unknown>;\n\n        if (typeof options.accountId === 'string') {\n          env.CLOUDFLARE_ACCOUNT_ID = options.accountId;\n        }\n\n        if (typeof options.gatewayId === 'string') {\n          env.CLOUDFLARE_GATEWAY_ID = options.gatewayId;\n        }\n\n        if (typeof options.apiToken === 'string') {\n          env.CLOUDFLARE_API_TOKEN = options.apiToken;\n        }\n      }\n    }\n  }\n\n  const command = buildOpencodeCommand(port, directory);\n  const process = await sandbox.startProcess(command, {\n    env: Object.keys(env).length > 0 ? env : undefined\n  });\n\n  // Wait for server to be ready\n  try {\n    await process.waitForPort(port, {\n      mode: 'http',\n      path: '/',\n      timeout: 60_000\n    });\n    getLogger().info('OpenCode server started successfully', {\n      port,\n      processId: process.id\n    });\n  } catch (e) {\n    const logs = await process.getLogs();\n    const error = e instanceof Error ? e : undefined;\n    getLogger().error('OpenCode server failed to start', error, {\n      port,\n      stderr: logs.stderr\n    });\n    throw new OpencodeStartupError(\n      `OpenCode server failed to start. Stderr: ${logs.stderr || '(empty)'}`,\n      { port, stderr: logs.stderr, command },\n      { cause: e }\n    );\n  }\n\n  return process;\n}\n\n/**\n * Starts an OpenCode server inside a Sandbox container.\n *\n * This function manages the server lifecycle only - use `createOpencode()` if you\n * also need a typed SDK client for programmatic access.\n *\n * If an OpenCode server is already running on the specified port, this function\n * will reuse it instead of starting a new one.\n *\n * @param sandbox - The Sandbox instance to run OpenCode in\n * @param options - Configuration options\n * @returns Promise resolving to server handle { port, url, close() }\n *\n * @example\n * ```typescript\n * import { getSandbox } from '@cloudflare/sandbox'\n * import { createOpencodeServer } from '@cloudflare/sandbox/opencode'\n *\n * const sandbox = getSandbox(env.Sandbox, 'my-agent')\n * const server = await createOpencodeServer(sandbox, {\n *   directory: '/home/user/my-project',\n *   config: {\n *     provider: {\n *       anthropic: {\n *         options: { apiKey: env.ANTHROPIC_KEY }\n *       },\n *       // Or use Cloudflare AI Gateway (with unified billing, no provider keys needed).\n *       // 'cloudflare-ai-gateway': {\n *       //   options: {\n *       //     accountId: env.CF_ACCOUNT_ID,\n *       //     gatewayId: env.CF_GATEWAY_ID,\n *       //     apiToken: env.CF_API_TOKEN\n *       //   },\n *       //   models: { 'anthropic/claude-sonnet-4-5-20250929': {} }\n *       // }\n *     }\n *   }\n * })\n *\n * // Proxy requests to the web UI\n * return sandbox.containerFetch(request, server.port)\n *\n * // When done\n * await server.close()\n * ```\n */\nexport async function createOpencodeServer(\n  sandbox: Sandbox<unknown>,\n  options?: OpencodeOptions\n): Promise<OpencodeServer> {\n  const port = options?.port ?? DEFAULT_PORT;\n  const process = await ensureOpencodeServer(\n    sandbox,\n    port,\n    options?.directory,\n    options?.config\n  );\n\n  return {\n    port,\n    url: `http://localhost:${port}`,\n    close: () => process.kill('SIGTERM')\n  };\n}\n\n/**\n * Creates an OpenCode server inside a Sandbox container and returns a typed SDK client.\n *\n * This function is API-compatible with OpenCode's own createOpencode(), but uses\n * Sandbox process management instead of Node.js spawn. The returned client uses\n * a custom fetch adapter to route requests through the Sandbox container.\n *\n * If an OpenCode server is already running on the specified port, this function\n * will reuse it instead of starting a new one.\n *\n * @param sandbox - The Sandbox instance to run OpenCode in\n * @param options - Configuration options\n * @returns Promise resolving to { client, server }\n *\n * @example\n * ```typescript\n * import { getSandbox } from '@cloudflare/sandbox'\n * import { createOpencode } from '@cloudflare/sandbox/opencode'\n *\n * const sandbox = getSandbox(env.Sandbox, 'my-agent')\n * const { client, server } = await createOpencode(sandbox, {\n *   directory: '/home/user/my-project',\n *   config: {\n *     provider: {\n *       anthropic: {\n *         options: { apiKey: env.ANTHROPIC_KEY }\n *       },\n *       // Or use Cloudflare AI Gateway (with unified billing, no provider keys needed).\n *       // 'cloudflare-ai-gateway': {\n *       //   options: {\n *       //     accountId: env.CF_ACCOUNT_ID,\n *       //     gatewayId: env.CF_GATEWAY_ID,\n *       //     apiToken: env.CF_API_TOKEN\n *       //   },\n *       //   models: { 'anthropic/claude-sonnet-4-5-20250929': {} }\n *       // }\n *     }\n *   }\n * })\n *\n * // Use the SDK client for programmatic access\n * const session = await client.session.create()\n *\n * // When done\n * await server.close()\n * ```\n */\nexport async function createOpencode<TClient = OpencodeClient>(\n  sandbox: Sandbox<unknown>,\n  options?: OpencodeOptions\n): Promise<OpencodeResult<TClient>> {\n  await ensureSdkLoaded();\n\n  const server = await createOpencodeServer(sandbox, options);\n\n  const clientFactory = createOpencodeClient;\n  if (!clientFactory) {\n    throw new Error('OpenCode SDK client unavailable.');\n  }\n\n  const client = clientFactory({\n    baseUrl: server.url,\n    fetch: (input, init?) =>\n      sandbox.containerFetch(new Request(input, init), server.port)\n  });\n\n  return { client: client as TClient, server };\n}\n\n/**\n * Proxy a request to the OpenCode web UI.\n *\n * This function handles the redirect and proxying only - you must start the\n * server separately using `createOpencodeServer()`.\n *\n * Specifically handles:\n * 1. Ensuring the `?url=` parameter is set (required for OpenCode's frontend to\n *    make API calls through the proxy instead of directly to localhost:4096)\n * 2. Proxying the request to the container\n *\n * @param request - The incoming HTTP request\n * @param sandbox - The Sandbox instance running OpenCode\n * @param server - The OpenCode server handle from createOpencodeServer()\n * @returns Response from OpenCode or a redirect response\n *\n * @example\n * ```typescript\n * import { getSandbox } from '@cloudflare/sandbox'\n * import { createOpencodeServer, proxyToOpencode } from '@cloudflare/sandbox/opencode'\n *\n * export default {\n *   async fetch(request: Request, env: Env) {\n *     const sandbox = getSandbox(env.Sandbox, 'opencode')\n *     const server = await createOpencodeServer(sandbox, {\n *       directory: '/home/user/project',\n *       config: {\n *         provider: {\n *           anthropic: {\n *             options: { apiKey: env.ANTHROPIC_KEY }\n *           },\n *           // Optional: Route all providers through Cloudflare AI Gateway\n *           'cloudflare-ai-gateway': {\n *             options: {\n *               accountId: env.CF_ACCOUNT_ID,\n *               gatewayId: env.CF_GATEWAY_ID,\n *               apiToken: env.CF_API_TOKEN\n *             }\n *           }\n *         }\n *       }\n *     })\n *     return proxyToOpencode(request, sandbox, server)\n *   }\n * }\n * ```\n */\nexport function proxyToOpencode(\n  request: Request,\n  sandbox: Sandbox<unknown>,\n  server: OpencodeServer\n): Response | Promise<Response> {\n  const url = new URL(request.url);\n\n  // OpenCode's frontend defaults to http://127.0.0.1:4096 when hostname includes\n  // \"localhost\" or \"opencode.ai\". The ?url= parameter overrides this behavior.\n  // We only redirect GET requests for HTML pages (initial page load).\n  // API calls (POST, PATCH, etc.) and asset requests are proxied directly\n  // since redirecting POST loses the request body.\n  if (!url.searchParams.has('url') && request.method === 'GET') {\n    const accept = request.headers.get('accept') || '';\n    const isHtmlRequest = accept.includes('text/html') || url.pathname === '/';\n    if (isHtmlRequest) {\n      url.searchParams.set('url', url.origin);\n      return Response.redirect(url.toString(), 302);\n    }\n  }\n\n  return sandbox.containerFetch(request, server.port);\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["createOpencodeClient: OpencodeClientFactory | undefined","env: Record<string, string>"],"sources":["../../src/opencode/types.ts","../../src/opencode/opencode.ts"],"sourcesContent":["import type { Config } from '@opencode-ai/sdk/v2';\nimport type { OpencodeClient } from '@opencode-ai/sdk/v2/client';\nimport { ErrorCode, type OpencodeStartupContext } from '@repo/shared/errors';\n\n/**\n * Configuration options for starting OpenCode server\n */\nexport interface OpencodeOptions {\n  /** Port for OpenCode server (default: 4096) */\n  port?: number;\n  /** Working directory for OpenCode (default: container's cwd) */\n  directory?: string;\n  /** OpenCode configuration */\n  config?: Config;\n}\n\n/**\n * Server lifecycle management\n */\nexport interface OpencodeServer {\n  /** Port the server is running on */\n  port: number;\n  /** Base URL for SDK client (http://localhost:{port}) */\n  url: string;\n  /** Close the server gracefully */\n  close(): Promise<void>;\n}\n\n/**\n * Result from createOpencode()\n * Client type comes from @opencode-ai/sdk (user's version)\n */\nexport interface OpencodeResult<TClient = OpencodeClient> {\n  /** OpenCode SDK client with Sandbox transport */\n  client: TClient;\n  /** Server lifecycle management */\n  server: OpencodeServer;\n}\n\n/**\n * Error thrown when OpenCode server fails to start\n */\nexport class OpencodeStartupError extends Error {\n  public readonly code = ErrorCode.OPENCODE_STARTUP_FAILED;\n  public readonly context: OpencodeStartupContext;\n\n  constructor(\n    message: string,\n    context: OpencodeStartupContext,\n    options?: ErrorOptions\n  ) {\n    super(message, options);\n    this.name = 'OpencodeStartupError';\n    this.context = context;\n  }\n}\n","import type { Config } from '@opencode-ai/sdk/v2';\nimport type { OpencodeClient } from '@opencode-ai/sdk/v2/client';\nimport { createLogger, type Logger, type Process } from '@repo/shared';\nimport type { Sandbox } from '../sandbox';\nimport type { OpencodeOptions, OpencodeResult, OpencodeServer } from './types';\nimport { OpencodeStartupError } from './types';\n\n// Lazy logger creation to avoid global scope restrictions in Workers\nfunction getLogger(): Logger {\n  return createLogger({ component: 'sandbox-do', operation: 'opencode' });\n}\n\nconst DEFAULT_PORT = 4096;\nconst OPENCODE_STARTUP_TIMEOUT_MS = 180_000;\nconst OPENCODE_SERVE = (port: number) =>\n  `opencode serve --port ${port} --hostname 0.0.0.0`;\n\n/**\n * Build the full command, optionally with a directory prefix.\n * If directory is provided, we cd to it first so OpenCode uses it as cwd.\n */\nfunction buildOpencodeCommand(port: number, directory?: string): string {\n  const serve = OPENCODE_SERVE(port);\n  return directory ? `cd ${directory} && ${serve}` : serve;\n}\n\ntype OpencodeClientFactory = (options: {\n  baseUrl: string;\n  fetch: typeof fetch;\n  directory?: string;\n}) => OpencodeClient;\n\n// Dynamic import to handle peer dependency\nlet createOpencodeClient: OpencodeClientFactory | undefined;\n\nasync function ensureSdkLoaded(): Promise<void> {\n  if (createOpencodeClient) return;\n\n  try {\n    const sdk = await import('@opencode-ai/sdk/v2/client');\n    createOpencodeClient = sdk.createOpencodeClient as OpencodeClientFactory;\n  } catch {\n    throw new Error(\n      '@opencode-ai/sdk is required for OpenCode integration. ' +\n        'Install it with: npm install @opencode-ai/sdk'\n    );\n  }\n}\n\n/**\n * Find an existing OpenCode server process running on the specified port.\n * Returns the process if found and still active, null otherwise.\n * Matches by the serve command pattern since directory prefix may vary.\n */\nasync function findExistingOpencodeProcess(\n  sandbox: Sandbox<unknown>,\n  port: number\n): Promise<Process | null> {\n  const processes = await sandbox.listProcesses();\n  const serveCommand = OPENCODE_SERVE(port);\n\n  for (const proc of processes) {\n    // Match commands that contain the serve command (with or without cd prefix)\n    if (proc.command.includes(serveCommand)) {\n      if (proc.status === 'starting' || proc.status === 'running') {\n        return proc;\n      }\n    }\n  }\n\n  return null;\n}\n\n/**\n * Ensures OpenCode server is running in the container.\n * Reuses existing process if one is already running on the specified port.\n * Handles concurrent startup attempts gracefully by retrying on failure.\n * Returns the process handle.\n */\nasync function ensureOpencodeServer(\n  sandbox: Sandbox<unknown>,\n  port: number,\n  directory?: string,\n  config?: Config\n): Promise<Process> {\n  // Check if OpenCode is already running on this port\n  const existingProcess = await findExistingOpencodeProcess(sandbox, port);\n  if (existingProcess) {\n    // Reuse existing process - wait for it to be ready if still starting\n    if (existingProcess.status === 'starting') {\n      getLogger().debug('Found starting OpenCode process, waiting for ready', {\n        port,\n        processId: existingProcess.id\n      });\n      try {\n        await existingProcess.waitForPort(port, {\n          mode: 'http',\n          path: '/global/health',\n          status: 200,\n          timeout: OPENCODE_STARTUP_TIMEOUT_MS\n        });\n      } catch (e) {\n        const logs = await existingProcess.getLogs();\n        throw new OpencodeStartupError(\n          `OpenCode server failed to start. Stderr: ${logs.stderr || '(empty)'}`,\n          { port, stderr: logs.stderr, command: existingProcess.command },\n          { cause: e }\n        );\n      }\n    }\n    getLogger().debug('Reusing existing OpenCode process', {\n      port,\n      processId: existingProcess.id\n    });\n    return existingProcess;\n  }\n\n  // Try to start a new OpenCode server\n  try {\n    return await startOpencodeServer(sandbox, port, directory, config);\n  } catch (startupError) {\n    // Startup failed - check if another concurrent request started the server\n    // This handles the race condition where multiple requests try to start simultaneously\n    const retryProcess = await findExistingOpencodeProcess(sandbox, port);\n    if (retryProcess) {\n      getLogger().debug(\n        'Startup failed but found concurrent process, reusing',\n        {\n          port,\n          processId: retryProcess.id\n        }\n      );\n      // Wait for the concurrent server to be ready\n      if (retryProcess.status === 'starting') {\n        try {\n          await retryProcess.waitForPort(port, {\n            mode: 'http',\n            path: '/global/health',\n            status: 200,\n            timeout: OPENCODE_STARTUP_TIMEOUT_MS\n          });\n        } catch (e) {\n          const logs = await retryProcess.getLogs();\n          throw new OpencodeStartupError(\n            `OpenCode server failed to start. Stderr: ${logs.stderr || '(empty)'}`,\n            { port, stderr: logs.stderr, command: retryProcess.command },\n            { cause: e }\n          );\n        }\n      }\n      return retryProcess;\n    }\n\n    // No concurrent server found - the failure was genuine\n    throw startupError;\n  }\n}\n\n/**\n * Internal function to start a new OpenCode server process.\n */\nasync function startOpencodeServer(\n  sandbox: Sandbox<unknown>,\n  port: number,\n  directory?: string,\n  config?: Config\n): Promise<Process> {\n  getLogger().info('Starting OpenCode server', { port, directory });\n\n  // Pass config via OPENCODE_CONFIG_CONTENT and also extract API keys to env vars\n  // because OpenCode's provider auth looks for env vars like ANTHROPIC_API_KEY\n  const env: Record<string, string> = {};\n\n  if (config) {\n    env.OPENCODE_CONFIG_CONTENT = JSON.stringify(config);\n\n    // Extract API keys from provider config\n    // Support both options.apiKey (official type) and legacy top-level apiKey\n    if (\n      config.provider &&\n      typeof config.provider === 'object' &&\n      !Array.isArray(config.provider)\n    ) {\n      for (const [providerId, providerConfig] of Object.entries(\n        config.provider\n      )) {\n        if (providerId === 'cloudflare-ai-gateway') {\n          continue;\n        }\n\n        // Try options.apiKey first (official Config type)\n        let apiKey = providerConfig?.options?.apiKey;\n        // Fall back to top-level apiKey for convenience\n        if (!apiKey) {\n          apiKey = (providerConfig as Record<string, unknown> | undefined)\n            ?.apiKey as string | undefined;\n        }\n        if (typeof apiKey === 'string') {\n          const envVar = `${providerId.toUpperCase()}_API_KEY`;\n          env[envVar] = apiKey;\n        }\n      }\n\n      const aiGatewayConfig = config.provider['cloudflare-ai-gateway'];\n      if (aiGatewayConfig?.options) {\n        const options = aiGatewayConfig.options as Record<string, unknown>;\n\n        if (typeof options.accountId === 'string') {\n          env.CLOUDFLARE_ACCOUNT_ID = options.accountId;\n        }\n\n        if (typeof options.gatewayId === 'string') {\n          env.CLOUDFLARE_GATEWAY_ID = options.gatewayId;\n        }\n\n        if (typeof options.apiToken === 'string') {\n          env.CLOUDFLARE_API_TOKEN = options.apiToken;\n        }\n      }\n    }\n  }\n\n  const command = buildOpencodeCommand(port, directory);\n  const process = await sandbox.startProcess(command, {\n    env: Object.keys(env).length > 0 ? env : undefined\n  });\n\n  // Wait for server to be ready - check the actual health endpoint\n  try {\n    await process.waitForPort(port, {\n      mode: 'http',\n      path: '/global/health',\n      status: 200,\n      timeout: OPENCODE_STARTUP_TIMEOUT_MS\n    });\n    getLogger().info('OpenCode server started successfully', {\n      port,\n      processId: process.id\n    });\n  } catch (e) {\n    const logs = await process.getLogs();\n    const error = e instanceof Error ? e : undefined;\n    getLogger().error('OpenCode server failed to start', error, {\n      port,\n      stderr: logs.stderr\n    });\n    throw new OpencodeStartupError(\n      `OpenCode server failed to start. Stderr: ${logs.stderr || '(empty)'}`,\n      { port, stderr: logs.stderr, command },\n      { cause: e }\n    );\n  }\n\n  return process;\n}\n\n/**\n * Starts an OpenCode server inside a Sandbox container.\n *\n * This function manages the server lifecycle only - use `createOpencode()` if you\n * also need a typed SDK client for programmatic access.\n *\n * If an OpenCode server is already running on the specified port, this function\n * will reuse it instead of starting a new one.\n *\n * @param sandbox - The Sandbox instance to run OpenCode in\n * @param options - Configuration options\n * @returns Promise resolving to server handle { port, url, close() }\n *\n * @example\n * ```typescript\n * import { getSandbox } from '@cloudflare/sandbox'\n * import { createOpencodeServer } from '@cloudflare/sandbox/opencode'\n *\n * const sandbox = getSandbox(env.Sandbox, 'my-agent')\n * const server = await createOpencodeServer(sandbox, {\n *   directory: '/home/user/my-project',\n *   config: {\n *     provider: {\n *       anthropic: {\n *         options: { apiKey: env.ANTHROPIC_KEY }\n *       },\n *       // Or use Cloudflare AI Gateway (with unified billing, no provider keys needed).\n *       // 'cloudflare-ai-gateway': {\n *       //   options: {\n *       //     accountId: env.CF_ACCOUNT_ID,\n *       //     gatewayId: env.CF_GATEWAY_ID,\n *       //     apiToken: env.CF_API_TOKEN\n *       //   },\n *       //   models: { 'anthropic/claude-sonnet-4-5-20250929': {} }\n *       // }\n *     }\n *   }\n * })\n *\n * // Proxy requests to the web UI\n * return sandbox.containerFetch(request, server.port)\n *\n * // When done\n * await server.close()\n * ```\n */\nexport async function createOpencodeServer(\n  sandbox: Sandbox<unknown>,\n  options?: OpencodeOptions\n): Promise<OpencodeServer> {\n  const port = options?.port ?? DEFAULT_PORT;\n  const process = await ensureOpencodeServer(\n    sandbox,\n    port,\n    options?.directory,\n    options?.config\n  );\n\n  return {\n    port,\n    url: `http://localhost:${port}`,\n    close: () => process.kill('SIGTERM')\n  };\n}\n\n/**\n * Creates an OpenCode server inside a Sandbox container and returns a typed SDK client.\n *\n * This function is API-compatible with OpenCode's own createOpencode(), but uses\n * Sandbox process management instead of Node.js spawn. The returned client uses\n * a custom fetch adapter to route requests through the Sandbox container.\n *\n * If an OpenCode server is already running on the specified port, this function\n * will reuse it instead of starting a new one.\n *\n * @param sandbox - The Sandbox instance to run OpenCode in\n * @param options - Configuration options\n * @returns Promise resolving to { client, server }\n *\n * @example\n * ```typescript\n * import { getSandbox } from '@cloudflare/sandbox'\n * import { createOpencode } from '@cloudflare/sandbox/opencode'\n *\n * const sandbox = getSandbox(env.Sandbox, 'my-agent')\n * const { client, server } = await createOpencode(sandbox, {\n *   directory: '/home/user/my-project',\n *   config: {\n *     provider: {\n *       anthropic: {\n *         options: { apiKey: env.ANTHROPIC_KEY }\n *       },\n *       // Or use Cloudflare AI Gateway (with unified billing, no provider keys needed).\n *       // 'cloudflare-ai-gateway': {\n *       //   options: {\n *       //     accountId: env.CF_ACCOUNT_ID,\n *       //     gatewayId: env.CF_GATEWAY_ID,\n *       //     apiToken: env.CF_API_TOKEN\n *       //   },\n *       //   models: { 'anthropic/claude-sonnet-4-5-20250929': {} }\n *       // }\n *     }\n *   }\n * })\n *\n * // Use the SDK client for programmatic access\n * const session = await client.session.create()\n *\n * // When done\n * await server.close()\n * ```\n */\nexport async function createOpencode<TClient = OpencodeClient>(\n  sandbox: Sandbox<unknown>,\n  options?: OpencodeOptions\n): Promise<OpencodeResult<TClient>> {\n  await ensureSdkLoaded();\n\n  const server = await createOpencodeServer(sandbox, options);\n\n  const clientFactory = createOpencodeClient;\n  if (!clientFactory) {\n    throw new Error('OpenCode SDK client unavailable.');\n  }\n\n  const client = clientFactory({\n    baseUrl: server.url,\n    fetch: (input, init?) =>\n      sandbox.containerFetch(new Request(input, init), server.port)\n  });\n\n  return { client: client as TClient, server };\n}\n\n/**\n * Proxy a request directly to the OpenCode server.\n *\n * Unlike `proxyToOpencode()`, this helper does not apply any web UI redirects\n * or query parameter rewrites. Use it for API/CLI traffic where raw request\n * forwarding is preferred.\n */\nexport function proxyToOpencodeServer(\n  request: Request,\n  sandbox: Sandbox<unknown>,\n  server: OpencodeServer\n): Promise<Response> {\n  return sandbox.containerFetch(request, server.port);\n}\n\n/**\n * Proxy a request to the OpenCode web UI.\n *\n * This function handles the redirect and proxying only - you must start the\n * server separately using `createOpencodeServer()`.\n *\n * Specifically handles:\n * 1. Ensuring the `?url=` parameter is set (required for OpenCode's frontend to\n *    make API calls through the proxy instead of directly to localhost:4096)\n * 2. Proxying the request to the container\n *\n * @param request - The incoming HTTP request\n * @param sandbox - The Sandbox instance running OpenCode\n * @param server - The OpenCode server handle from createOpencodeServer()\n * @returns Response from OpenCode or a redirect response\n *\n * @example\n * ```typescript\n * import { getSandbox } from '@cloudflare/sandbox'\n * import { createOpencodeServer, proxyToOpencode } from '@cloudflare/sandbox/opencode'\n *\n * export default {\n *   async fetch(request: Request, env: Env) {\n *     const sandbox = getSandbox(env.Sandbox, 'opencode')\n *     const server = await createOpencodeServer(sandbox, {\n *       directory: '/home/user/project',\n *       config: {\n *         provider: {\n *           anthropic: {\n *             options: { apiKey: env.ANTHROPIC_KEY }\n *           },\n *           // Optional: Route all providers through Cloudflare AI Gateway\n *           'cloudflare-ai-gateway': {\n *             options: {\n *               accountId: env.CF_ACCOUNT_ID,\n *               gatewayId: env.CF_GATEWAY_ID,\n *               apiToken: env.CF_API_TOKEN\n *             }\n *           }\n *         }\n *       }\n *     })\n *     return proxyToOpencode(request, sandbox, server)\n *   }\n * }\n * ```\n */\nexport function proxyToOpencode(\n  request: Request,\n  sandbox: Sandbox<unknown>,\n  server: OpencodeServer\n): Response | Promise<Response> {\n  const url = new URL(request.url);\n\n  // OpenCode's frontend defaults to http://127.0.0.1:4096 when hostname includes\n  // \"localhost\" or \"opencode.ai\". The ?url= parameter overrides this behavior.\n  // We only redirect GET requests for HTML pages (initial page load).\n  // API calls (POST, PATCH, etc.) and asset requests are proxied directly\n  // since redirecting POST loses the request body.\n  if (!url.searchParams.has('url') && request.method === 'GET') {\n    const accept = request.headers.get('accept') || '';\n    const isHtmlRequest = accept.includes('text/html') || url.pathname === '/';\n    if (isHtmlRequest) {\n      url.searchParams.set('url', url.origin);\n      return Response.redirect(url.toString(), 302);\n    }\n  }\n\n  return proxyToOpencodeServer(request, sandbox, server);\n}\n"],"mappings":"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"}

package/dist/{sandbox-CgjQQZGw.d.ts → sandbox-DGAjk7r3.d.ts}

@@ -348,6 +348,62 @@ interface PtyOptions {
   rows?: number;
 }
 //#endregion
+//#region ../shared/dist/request-types.d.ts
+/**
+ * Request types for API calls to the container
+ * Single source of truth for the contract between SDK clients and container handlers
+ */
+/**
+ * Request to execute a command
+ */
+interface ExecuteRequest {
+  command: string;
+  sessionId?: string;
+  background?: boolean;
+  timeoutMs?: number;
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+}
+/**
+ * Request to start a background process
+ * Uses flat structure consistent with other endpoints
+ */
+interface StartProcessRequest {
+  command: string;
+  sessionId?: string;
+  processId?: string;
+  timeoutMs?: number;
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  encoding?: string;
+  autoCleanup?: boolean;
+}
+/**
+ * Request to expose a port
+ */
+interface ExposePortRequest {
+  port: number;
+  name?: string;
+}
+/**
+ * Response from the container after creating a backup archive
+ */
+interface CreateBackupResponse {
+  success: boolean;
+  /** Size of the archive in bytes */
+  sizeBytes: number;
+  /** Path to the archive file in the container */
+  archivePath: string;
+}
+/**
+ * Response from the container after restoring a backup
+ */
+interface RestoreBackupResponse {
+  success: boolean;
+  /** Directory that was restored */
+  dir: string;
+}
+//#endregion
 //#region ../shared/dist/types.d.ts
 interface BaseExecOptions {
   /**
@@ -1009,8 +1065,41 @@ interface ExecutionSession {
   deleteCodeContext(contextId: string): Promise<void>;
   mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
   unmountBucket(mountPath: string): Promise<void>;
+  createBackup(options: BackupOptions): Promise<DirectoryBackup>;
+  restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>;
   terminal(request: Request, options?: PtyOptions): Promise<Response>;
 }
+/**
+ * Options for creating a directory backup
+ */
+interface BackupOptions {
+  /** Directory to back up (absolute path). Required. */
+  dir: string;
+  /** Human-readable name for this backup. Optional. */
+  name?: string;
+  /** Seconds until automatic garbage collection. Default: 259200 (3 days). No upper limit. */
+  ttl?: number;
+}
+/**
+ * Handle representing a stored directory backup.
+ * Serializable (two strings). The user stores this and passes it to restoreBackup().
+ */
+interface DirectoryBackup {
+  /** Unique backup identifier */
+  readonly id: string;
+  /** Directory that was backed up */
+  readonly dir: string;
+}
+/**
+ * Result returned from a successful restoreBackup() call
+ */
+interface RestoreBackupResult {
+  success: boolean;
+  /** The directory that was restored */
+  dir: string;
+  /** Backup ID that was restored */
+  id: string;
+}
 /**
  * Supported S3-compatible storage providers
  */
@@ -1128,6 +1217,8 @@ interface ISandbox {
   runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
   listCodeContexts(): Promise<CodeContext[]>;
   deleteCodeContext(contextId: string): Promise<void>;
+  createBackup(options: BackupOptions): Promise<DirectoryBackup>;
+  restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>;
   wsConnect(request: Request, port: number): Promise<Response>;
 }
 declare function isExecResult(value: any): value is ExecResult;
@@ -1320,6 +1411,31 @@ declare abstract class BaseHttpClient {
   protected logError(operation: string, error: unknown): void;
 }
 //#endregion
+//#region src/clients/backup-client.d.ts
+/**
+ * Client for backup operations.
+ *
+ * Handles communication with the container's backup endpoints.
+ * The container creates/extracts squashfs archives locally.
+ * R2 upload/download is handled by the Sandbox DO, not by this client.
+ */
+declare class BackupClient extends BaseHttpClient {
+  /**
+   * Tell the container to create a squashfs archive from a directory.
+   * @param dir - Directory to back up
+   * @param archivePath - Where the container should write the archive
+   * @param sessionId - Session context
+   */
+  createArchive(dir: string, archivePath: string, sessionId: string): Promise<CreateBackupResponse>;
+  /**
+   * Tell the container to restore a squashfs archive into a directory.
+   * @param dir - Target directory
+   * @param archivePath - Path to the archive file in the container
+   * @param sessionId - Session context
+   */
+  restoreArchive(dir: string, archivePath: string, sessionId: string): Promise<RestoreBackupResponse>;
+}
+//#endregion
 //#region src/clients/command-client.d.ts
 /**
  * Response interface for command execution
@@ -1692,6 +1808,7 @@ declare class UtilityClient extends BaseHttpClient {
  * WebSocket mode reduces sub-request count when running inside Workers/Durable Objects.
  */
 declare class SandboxClient {
+  readonly backup: BackupClient;
   readonly commands: CommandClient;
   readonly files: FileClient;
   readonly processes: ProcessClient;
@@ -1738,6 +1855,24 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   private keepAliveEnabled;
   private activeMounts;
   private transport;
+  private backupBucket;
+  /**
+   * Serializes backup operations to prevent concurrent create/restore on the same sandbox.
+   *
+   * This is in-memory state — it resets if the Durable Object is evicted and
+   * re-instantiated (e.g. after sleep). This is acceptable because the container
+   * filesystem is also lost on eviction, so there is no archive to race on.
+   */
+  private backupInProgress;
+  /**
+   * R2 presigned URL credentials for direct container-to-R2 transfers.
+   * All four fields plus the R2 binding must be configured for backup to work.
+   */
+  private r2AccessKeyId;
+  private r2SecretAccessKey;
+  private r2AccountId;
+  private backupBucketName;
+  private r2Client;
   /**
    * Default container startup timeouts (conservative for production)
    * Based on Cloudflare docs: "Containers take several minutes to provision"
@@ -1972,7 +2107,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * @param options - Configuration options
    * @param options.hostname - Your Worker's domain name (required for preview URL construction)
    * @param options.name - Optional friendly name for the port
-   * @param options.token - Optional custom token for the preview URL (1-16 characters: lowercase letters, numbers, hyphens, underscores)
+   * @param options.token - Optional custom token for the preview URL (1-16 characters: lowercase letters, numbers, underscores)
    *                       If not provided, a random 16-character token will be generated automatically
    * @returns Preview URL information including the full URL, port number, and optional name
    *
@@ -1985,9 +2120,9 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * // With custom token for stable URLs across deployments
    * const { url } = await sandbox.exposePort(8080, {
    *   hostname: 'example.com',
-   *   token: 'my-token-v1'
+   *   token: 'my_token_v1'
    * });
-   * // url: https://8080-sandbox-id-my-token-v1.example.com
+   * // url: https://8080-sandbox-id-my_token_v1.example.com
    */
   exposePort(port: number, options: {
     name?: string;
@@ -2042,7 +2177,111 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
   listCodeContexts(): Promise<CodeContext[]>;
   deleteCodeContext(contextId: string): Promise<void>;
+  /** UUID v4 format validator for backup IDs */
+  private static readonly UUID_REGEX;
+  /**
+   * Validate that a directory path is safe for backup operations.
+   * Rejects empty, relative, traversal, and null-byte paths.
+   */
+  private static validateBackupDir;
+  /**
+   * Returns the R2 bucket or throws if backup is not configured.
+   */
+  private requireBackupBucket;
+  private static readonly PRESIGNED_URL_EXPIRY_SECONDS;
+  /**
+   * Ensure a dedicated session for backup operations exists.
+   * Isolates backup shell commands (curl, stat, rm, mkdir) from user exec()
+   * calls to prevent session state interference and interleaving.
+   */
+  private ensureBackupSession;
+  /**
+   * Returns validated presigned URL configuration or throws if not configured.
+   * All credential fields plus the R2 binding are required for backup to work.
+   */
+  private requirePresignedUrlSupport;
+  /**
+   * Generate a presigned GET URL for downloading an object from R2.
+   * The container can curl this URL directly without credentials.
+   */
+  private generatePresignedGetUrl;
+  /**
+   * Generate a presigned PUT URL for uploading an object to R2.
+   * The container can curl PUT to this URL directly without credentials.
+   */
+  private generatePresignedPutUrl;
+  /**
+   * Upload a backup archive via presigned PUT URL.
+   * The container curls the archive directly to R2, bypassing the DO.
+   * ~24 MB/s throughput vs ~0.6 MB/s for base64 readFile.
+   */
+  private uploadBackupPresigned;
+  /**
+   * Download a backup archive via presigned GET URL.
+   * The container curls the archive directly from R2, bypassing the DO.
+   * ~93 MB/s throughput vs ~0.6 MB/s for base64 writeFile.
+   */
+  private downloadBackupPresigned;
+  /**
+   * Serialize backup operations on this sandbox instance.
+   * Concurrent backup/restore calls are queued so the multi-step
+   * create-archive → read → upload (or download → write → extract) flow
+   * is not interleaved with another backup operation on the same directory.
+   */
+  private enqueueBackupOp;
+  /**
+   * Create a backup of a directory and upload it to R2.
+   *
+   * Flow:
+   *   1. Container creates squashfs archive from the directory
+   *   2. Container uploads the archive directly to R2 via presigned URL
+   *   3. DO writes metadata to R2
+   *   4. Container cleans up the local archive
+   *
+   * The returned DirectoryBackup handle is serializable. Store it anywhere
+   * (KV, D1, DO storage) and pass it to restoreBackup() later.
+   *
+   * Concurrent backup/restore calls on the same sandbox are serialized.
+   *
+   * Partially-written files in the target directory may not be captured
+   * consistently. Completed writes are captured.
+   *
+   * NOTE: Expired backups are not automatically deleted from R2. Configure
+   * R2 lifecycle rules on the BACKUP_BUCKET to garbage-collect objects
+   * under the `backups/` prefix after the desired retention period.
+   */
+  createBackup(options: BackupOptions): Promise<DirectoryBackup>;
+  private doCreateBackup;
+  /**
+   * Restore a backup from R2 into a directory.
+   *
+   * Flow:
+   *   1. DO reads metadata from R2 and checks TTL
+   *   2. Container downloads the archive directly from R2 via presigned URL
+   *   3. Container mounts the squashfs archive with FUSE overlayfs
+   *
+   * The target directory becomes an overlay mount with the backup as a
+   * read-only lower layer and a writable upper layer for copy-on-write.
+   * Any processes writing to the directory should be stopped first.
+   *
+   * **Mount Lifecycle**: The FUSE overlay mount persists only while the
+   * container is running. When the sandbox sleeps or the container restarts,
+   * the mount is lost and the directory becomes empty. Re-restore from the
+   * backup handle to recover. This is an ephemeral restore, not a persistent
+   * extraction.
+   *
+   * The backup is restored into `backup.dir`. This may differ from the
+   * directory that was originally backed up, allowing cross-directory restore.
+   *
+   * Overlapping backups are independent: restoring a parent directory
+   * overwrites everything inside it, including subdirectories that were
+   * backed up separately. When restoring both, restore the parent first.
+   *
+   * Concurrent backup/restore calls on the same sandbox are serialized.
+   */
+  restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>;
+  private doRestoreBackup;
 }
 //#endregion
-export { ProcessKillResult as $, ResponseHandler as A, FileMetadata as B, CommandClient as C, ErrorResponse as D, ContainerStub as E, ExecEvent as F, LogEvent as G, GitCheckoutResult as H, ExecOptions as I, PortExposeResult as J, MountBucketOptions as K, ExecResult as L, BaseExecOptions as M, BucketCredentials as N, HttpClientOptions as O, BucketProvider as P, ProcessInfoResult as Q, ExecutionSession as R, WriteFileRequest as S, BaseApiResponse as T, ISandbox as U, FileStreamEvent as V, ListFilesOptions as W, Process as X, PortListResult as Y, ProcessCleanupResult as Z, GitClient as _, ExecutionResult as _t, CreateSessionRequest as a, SandboxOptions as at, MkdirRequest as b, DeleteSessionResponse as c, WaitForLogResult as ct, ProcessClient as d, isProcess as dt, ProcessListResult as et, PortClient as f, isProcessStatus as ft, GitCheckoutRequest as g, Execution as gt, InterpreterClient as h, CreateContextOptions as ht, CommandsResponse as i, ProcessStatus as it, SessionRequest as j, RequestConfig as k, PingResponse as l, WaitForPortOptions as lt, ExecutionCallbacks as m, CodeContext as mt, getSandbox as n, ProcessOptions as nt, CreateSessionResponse as o, SessionOptions as ot, UnexposePortRequest as p, PtyOptions as pt, PortCloseResult as q, SandboxClient as r, ProcessStartResult as rt, DeleteSessionRequest as s, StreamOptions as st, Sandbox as t, ProcessLogsResult as tt, UtilityClient as u, isExecResult as ut, FileClient as v, RunCodeOptions as vt, ExecuteResponse as w, ReadFileRequest as x, FileOperationRequest as y, FileChunk as z };
-//# sourceMappingURL=sandbox-CgjQQZGw.d.ts.map
+export { Process as $, RequestConfig as A, ExecResult as B, CommandClient as C, Execution as Ct, ContainerStub as D, BaseApiResponse as E, BucketCredentials as F, GitCheckoutResult as G, FileChunk as H, BucketProvider as I, LogEvent as J, ISandbox as K, DirectoryBackup as L, SessionRequest as M, BackupOptions as N, ErrorResponse as O, BaseExecOptions as P, PortListResult as Q, ExecEvent as R, WriteFileRequest as S, CreateContextOptions as St, BackupClient as T, RunCodeOptions as Tt, FileMetadata as U, ExecutionSession as V, FileStreamEvent as W, PortCloseResult as X, MountBucketOptions as Y, PortExposeResult as Z, GitClient as _, ExecuteRequest as _t, CreateSessionRequest as a, ProcessOptions as at, MkdirRequest as b, PtyOptions as bt, DeleteSessionResponse as c, RestoreBackupResult as ct, ProcessClient as d, StreamOptions as dt, ProcessCleanupResult as et, PortClient as f, WaitForLogResult as ft, GitCheckoutRequest as g, isProcessStatus as gt, InterpreterClient as h, isProcess as ht, CommandsResponse as i, ProcessLogsResult as it, ResponseHandler as j, HttpClientOptions as k, PingResponse as l, SandboxOptions as lt, ExecutionCallbacks as m, isExecResult as mt, getSandbox as n, ProcessKillResult as nt, CreateSessionResponse as o, ProcessStartResult as ot, UnexposePortRequest as p, WaitForPortOptions as pt, ListFilesOptions as q, SandboxClient as r, ProcessListResult as rt, DeleteSessionRequest as s, ProcessStatus as st, Sandbox as t, ProcessInfoResult as tt, UtilityClient as u, SessionOptions as ut, FileClient as v, ExposePortRequest as vt, ExecuteResponse as w, ExecutionResult as wt, ReadFileRequest as x, CodeContext as xt, FileOperationRequest as y, StartProcessRequest as yt, ExecOptions as z };
+//# sourceMappingURL=sandbox-DGAjk7r3.d.ts.map