cloudflare-openhands-sdk 0.1.0

package/dist/openhands/index.js

@@ -0,0 +1,178 @@
+// src/utils/agent-server.ts
+var DEFAULT_AGENT_SERVER_PATH = "/container-server/software-agent-sdk/.venv/bin/agent-server";
+var DEFAULT_AGENT_SERVER_DIR = "/container-server/software-agent-sdk";
+function getDefaultAgentServerPath() {
+  return DEFAULT_AGENT_SERVER_PATH;
+}
+function getDefaultAgentServerDir() {
+  return DEFAULT_AGENT_SERVER_DIR;
+}
+async function checkAgentServerExists(sandbox, path = DEFAULT_AGENT_SERVER_PATH) {
+  try {
+    const result = await sandbox.exec(`test -f ${path} && echo "EXISTS" || echo "NOT_FOUND"`);
+    return result.stdout.trim() === "EXISTS";
+  } catch {
+    return false;
+  }
+}
+async function findAgentServerPath(sandbox) {
+  const locations = [
+    DEFAULT_AGENT_SERVER_PATH,
+    "/software-agent-sdk/.venv/bin/agent-server",
+    "/root/software-agent-sdk/.venv/bin/agent-server"
+  ];
+  for (const location of locations) {
+    if (await checkAgentServerExists(sandbox, location)) {
+      return location;
+    }
+  }
+  try {
+    const result = await sandbox.exec("which agent-server");
+    const path = result.stdout.trim();
+    if (path && !path.includes("not found")) {
+      return path;
+    }
+  } catch {}
+  return null;
+}
+function buildAgentServerCommand(port, directory) {
+  const command = `${DEFAULT_AGENT_SERVER_PATH} --host 0.0.0.0 --port ${port}`;
+  return directory && directory !== DEFAULT_AGENT_SERVER_DIR ? `cd ${directory} && ${command}` : command;
+}
+
+// src/openhands/types.ts
+class OpenhandsStartupError extends Error {
+  code = "OPENHANDS_STARTUP_FAILED";
+  context;
+  constructor(message, context, options) {
+    super(message, options);
+    this.name = "OpenhandsStartupError";
+    this.context = context;
+  }
+}
+// src/openhands/openhands.ts
+var DEFAULT_PORT = 8001;
+async function findExistingAgentServer(sandbox, port) {
+  const processes = await sandbox.listProcesses();
+  const commandPattern = DEFAULT_AGENT_SERVER_PATH;
+  for (const proc of processes) {
+    if (proc.command.includes(commandPattern)) {
+      if (proc.command.includes(`--port ${port}`) || proc.command.includes(`--port=${port}`)) {
+        if (proc.status === "starting" || proc.status === "running") {
+          return proc;
+        }
+      }
+    }
+  }
+  return null;
+}
+async function startAgentServer(sandbox, port, options) {
+  const directory = options.directory || DEFAULT_AGENT_SERVER_DIR;
+  const command = buildAgentServerCommand(port, directory);
+  const process = await sandbox.startProcess(command, {
+    cwd: directory,
+    env: options.env
+  });
+  try {
+    await process.waitForPort(port, {
+      mode: "http",
+      path: "/",
+      timeout: 60000
+    });
+  } catch (e) {
+    const logs = await process.getLogs();
+    throw new OpenhandsStartupError(`agent-server failed to start on port ${port}. Stderr: ${logs.stderr || "(empty)"}`, {
+      port,
+      stderr: logs.stderr,
+      command: process.command,
+      processId: process.id
+    }, { cause: e });
+  }
+  return process;
+}
+async function ensureAgentServer(sandbox, port, options) {
+  const existingProcess = await findExistingAgentServer(sandbox, port);
+  if (existingProcess) {
+    if (existingProcess.status === "starting") {
+      try {
+        await existingProcess.waitForPort(port, {
+          mode: "http",
+          path: "/",
+          timeout: 60000
+        });
+      } catch (e) {
+        const logs = await existingProcess.getLogs();
+        throw new OpenhandsStartupError(`agent-server failed to start. Stderr: ${logs.stderr || "(empty)"}`, {
+          port,
+          stderr: logs.stderr,
+          command: existingProcess.command,
+          processId: existingProcess.id
+        }, { cause: e });
+      }
+    }
+    return existingProcess;
+  }
+  try {
+    return await startAgentServer(sandbox, port, options);
+  } catch (startupError) {
+    const retryProcess = await findExistingAgentServer(sandbox, port);
+    if (retryProcess) {
+      if (retryProcess.status === "starting") {
+        try {
+          await retryProcess.waitForPort(port, {
+            mode: "http",
+            path: "/",
+            timeout: 60000
+          });
+        } catch (e) {
+          const logs = await retryProcess.getLogs();
+          throw new OpenhandsStartupError(`agent-server failed to start. Stderr: ${logs.stderr || "(empty)"}`, {
+            port,
+            stderr: logs.stderr,
+            command: retryProcess.command,
+            processId: retryProcess.id
+          }, { cause: e });
+        }
+      }
+      return retryProcess;
+    }
+    throw startupError;
+  }
+}
+async function createOpenhandsServer(sandbox, options = {}) {
+  const port = options.port ?? DEFAULT_PORT;
+  const process = await ensureAgentServer(sandbox, port, options);
+  let previewUrl;
+  if (options.exposePort) {
+    if (!options.hostname) {
+      throw new Error("hostname is required when exposePort is true. Provide hostname in options or extract from request URL.");
+    }
+    try {
+      const exposed = await sandbox.exposePort(port, {
+        hostname: options.hostname
+      });
+      previewUrl = typeof exposed === "string" ? exposed : exposed.url;
+    } catch (error) {
+      console.warn("Failed to expose port:", error);
+    }
+  }
+  return {
+    port,
+    url: `http://localhost:${port}`,
+    previewUrl,
+    processId: process.id,
+    async close() {
+      await process.kill("SIGTERM");
+    }
+  };
+}
+function proxyToOpenhands(request, sandbox, server) {
+  return sandbox.containerFetch(request, server.port);
+}
+export {
+  proxyToOpenhands,
+  createOpenhandsServer,
+  OpenhandsStartupError
+};
+
+//# debugId=4C4FB2DEC1D2C02F64756E2164756E21

package/dist/openhands/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/utils/agent-server.ts", "../src/openhands/types.ts", "../src/openhands/openhands.ts"],
+  "sourcesContent": [
+    "import type { Sandbox } from '@cloudflare/sandbox';\n\n/**\n * Default path to agent-server executable\n */\nexport const DEFAULT_AGENT_SERVER_PATH =\n  '/container-server/software-agent-sdk/.venv/bin/agent-server';\n\n/**\n * Default working directory for agent-server\n */\nexport const DEFAULT_AGENT_SERVER_DIR =\n  '/container-server/software-agent-sdk';\n\n/**\n * Get the default agent-server executable path\n */\nexport function getDefaultAgentServerPath(): string {\n  return DEFAULT_AGENT_SERVER_PATH;\n}\n\n/**\n * Get the default agent-server working directory\n */\nexport function getDefaultAgentServerDir(): string {\n  return DEFAULT_AGENT_SERVER_DIR;\n}\n\n/**\n * Check if agent-server exists at the given path\n */\nexport async function checkAgentServerExists(\n  sandbox: Sandbox<unknown>,\n  path: string = DEFAULT_AGENT_SERVER_PATH\n): Promise<boolean> {\n  try {\n    const result = await sandbox.exec(\n      `test -f ${path} && echo \"EXISTS\" || echo \"NOT_FOUND\"`\n    );\n    return result.stdout.trim() === 'EXISTS';\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Find agent-server executable by checking common locations\n */\nexport async function findAgentServerPath(\n  sandbox: Sandbox<unknown>\n): Promise<string | null> {\n  const locations = [\n    DEFAULT_AGENT_SERVER_PATH,\n    '/software-agent-sdk/.venv/bin/agent-server',\n    '/root/software-agent-sdk/.venv/bin/agent-server',\n  ];\n\n  for (const location of locations) {\n    if (await checkAgentServerExists(sandbox, location)) {\n      return location;\n    }\n  }\n\n  // Try which as fallback\n  try {\n    const result = await sandbox.exec('which agent-server');\n    const path = result.stdout.trim();\n    if (path && !path.includes('not found')) {\n      return path;\n    }\n  } catch {\n    // Ignore errors\n  }\n\n  return null;\n}\n\n/**\n * Build the agent-server command\n */\nexport function buildAgentServerCommand(\n  port: number,\n  directory?: string\n): string {\n  const command = `${DEFAULT_AGENT_SERVER_PATH} --host 0.0.0.0 --port ${port}`;\n  return directory && directory !== DEFAULT_AGENT_SERVER_DIR\n    ? `cd ${directory} && ${command}`\n    : command;\n}\n\n",
+    "import type { Process } from '@cloudflare/sandbox';\n\n/**\n * Configuration options for starting OpenHands agent-server\n */\nexport interface OpenhandsOptions {\n  /** Port for agent-server (default: 8001) */\n  port?: number;\n  /** Working directory for agent-server (default: /container-server/software-agent-sdk) */\n  directory?: string;\n  /** Hostname for preview URL exposure (required if exposePort is true) */\n  hostname?: string;\n  /** Enable preview URL exposure (default: false) */\n  exposePort?: boolean;\n  /** Environment variables for agent-server */\n  env?: Record<string, string>;\n  /** Sandbox name/session ID (default: 'my-sandbox') */\n  sandboxName?: string;\n}\n\n/**\n * Server lifecycle management\n */\nexport interface OpenhandsServer {\n  /** Port the server is running on */\n  port: number;\n  /** Base URL for server (http://localhost:{port}) */\n  url: string;\n  /** Preview URL if port was exposed (optional) */\n  previewUrl?: string;\n  /** Process ID */\n  processId: string;\n  /** Close the server gracefully */\n  close(): Promise<void>;\n}\n\n/**\n * Context information for startup errors\n */\nexport interface OpenhandsStartupContext {\n  port: number;\n  stderr?: string;\n  command?: string;\n  processId?: string;\n}\n\n/**\n * Error thrown when agent-server fails to start\n */\nexport class OpenhandsStartupError extends Error {\n  readonly code = 'OPENHANDS_STARTUP_FAILED' as const;\n  readonly context: OpenhandsStartupContext;\n\n  constructor(\n    message: string,\n    context: OpenhandsStartupContext,\n    options?: ErrorOptions\n  ) {\n    super(message, options);\n    this.name = 'OpenhandsStartupError';\n    this.context = context;\n  }\n}\n\n",
+    "import type { Sandbox, Process } from '@cloudflare/sandbox';\nimport type {\n  OpenhandsOptions,\n  OpenhandsServer,\n  OpenhandsStartupContext,\n} from './types';\nimport { OpenhandsStartupError } from './types';\nimport {\n  buildAgentServerCommand,\n  DEFAULT_AGENT_SERVER_DIR,\n  DEFAULT_AGENT_SERVER_PATH,\n} from '../utils/agent-server';\n\nconst DEFAULT_PORT = 8001;\n\n/**\n * Find an existing agent-server process running on the specified port.\n * Returns the process if found and still active, null otherwise.\n */\nasync function findExistingAgentServer(\n  sandbox: Sandbox<unknown>,\n  port: number\n): Promise<Process | null> {\n  const processes = await sandbox.listProcesses();\n  const commandPattern = DEFAULT_AGENT_SERVER_PATH;\n\n  for (const proc of processes) {\n    // Match commands that contain the agent-server path\n    if (proc.command.includes(commandPattern)) {\n      // Check if the command includes the port\n      if (\n        proc.command.includes(`--port ${port}`) ||\n        proc.command.includes(`--port=${port}`)\n      ) {\n        if (proc.status === 'starting' || proc.status === 'running') {\n          return proc;\n        }\n      }\n    }\n  }\n\n  return null;\n}\n\n/**\n * Start a new agent-server process\n */\nasync function startAgentServer(\n  sandbox: Sandbox<unknown>,\n  port: number,\n  options: OpenhandsOptions\n): Promise<Process> {\n  const directory = options.directory || DEFAULT_AGENT_SERVER_DIR;\n  const command = buildAgentServerCommand(port, directory);\n\n  const process = await sandbox.startProcess(command, {\n    cwd: directory,\n    env: options.env,\n  });\n\n  // Wait for the server to be ready\n  try {\n    await process.waitForPort(port, {\n      mode: 'http',\n      path: '/',\n      timeout: 60_000, // 60 seconds\n    });\n  } catch (e) {\n    const logs = await process.getLogs();\n    throw new OpenhandsStartupError(\n      `agent-server failed to start on port ${port}. Stderr: ${logs.stderr || '(empty)'}`,\n      {\n        port,\n        stderr: logs.stderr,\n        command: process.command,\n        processId: process.id,\n      },\n      { cause: e }\n    );\n  }\n\n  return process;\n}\n\n/**\n * Ensures agent-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 */\nasync function ensureAgentServer(\n  sandbox: Sandbox<unknown>,\n  port: number,\n  options: OpenhandsOptions\n): Promise<Process> {\n  // Check if agent-server is already running on this port\n  const existingProcess = await findExistingAgentServer(sandbox, port);\n  if (existingProcess) {\n    // Reuse existing process - wait for it to be ready if still starting\n    if (existingProcess.status === 'starting') {\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 OpenhandsStartupError(\n          `agent-server failed to start. Stderr: ${logs.stderr || '(empty)'}`,\n          {\n            port,\n            stderr: logs.stderr,\n            command: existingProcess.command,\n            processId: existingProcess.id,\n          },\n          { cause: e }\n        );\n      }\n    }\n    return existingProcess;\n  }\n\n  // Try to start a new agent-server\n  try {\n    return await startAgentServer(sandbox, port, options);\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 findExistingAgentServer(sandbox, port);\n    if (retryProcess) {\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 OpenhandsStartupError(\n            `agent-server failed to start. Stderr: ${logs.stderr || '(empty)'}`,\n            {\n              port,\n              stderr: logs.stderr,\n              command: retryProcess.command,\n              processId: retryProcess.id,\n            },\n            { cause: e }\n          );\n        }\n      }\n      return retryProcess;\n    }\n\n    // No concurrent process found, rethrow the original error\n    throw startupError;\n  }\n}\n\n/**\n * Starts an agent-server inside a Sandbox container.\n *\n * This function manages the server lifecycle only. If an agent-server is already\n * running on the specified port, this function will reuse it instead of starting\n * a new one.\n *\n * @param sandbox - The Sandbox instance to run agent-server in\n * @param options - Configuration options\n * @returns Promise resolving to server handle { port, url, previewUrl?, close() }\n *\n * @example\n * ```typescript\n * import { getSandbox } from '@cloudflare/sandbox'\n * import { createOpenhandsServer } from 'openhands-sdk/openhands'\n *\n * const sandbox = getSandbox(env.Sandbox, 'my-sandbox')\n * const server = await createOpenhandsServer(sandbox, {\n *   port: 8001,\n *   exposePort: true,\n *   hostname: 'yourdomain.com'\n * })\n *\n * // Proxy requests to the server\n * return sandbox.containerFetch(request, server.port)\n *\n * // When done\n * await server.close()\n * ```\n */\nexport async function createOpenhandsServer(\n  sandbox: Sandbox<unknown>,\n  options: OpenhandsOptions = {}\n): Promise<OpenhandsServer> {\n  const port = options.port ?? DEFAULT_PORT;\n  const process = await ensureAgentServer(sandbox, port, options);\n\n  let previewUrl: string | undefined;\n\n  // Optionally expose port for preview URL\n  if (options.exposePort) {\n    if (!options.hostname) {\n      throw new Error(\n        'hostname is required when exposePort is true. Provide hostname in options or extract from request URL.'\n      );\n    }\n\n    try {\n      const exposed = await sandbox.exposePort(port, {\n        hostname: options.hostname,\n      });\n      previewUrl = typeof exposed === 'string' ? exposed : exposed.url;\n    } catch (error) {\n      // Log but don't fail - server is still running\n      console.warn('Failed to expose port:', error);\n    }\n  }\n\n  return {\n    port,\n    url: `http://localhost:${port}`,\n    previewUrl,\n    processId: process.id,\n    async close() {\n      await process.kill('SIGTERM');\n    },\n  };\n}\n\n/**\n * Proxy a request to the agent-server.\n *\n * This function handles proxying only - you must start the server separately\n * using `createOpenhandsServer()`.\n *\n * @param request - The incoming HTTP request\n * @param sandbox - The Sandbox instance running agent-server\n * @param server - The agent-server handle from createOpenhandsServer()\n * @returns Response from agent-server\n *\n * @example\n * ```typescript\n * import { getSandbox } from '@cloudflare/sandbox'\n * import { createOpenhandsServer, proxyToOpenhands } from 'openhands-sdk/openhands'\n *\n * export default {\n *   async fetch(request: Request, env: Env) {\n *     const sandbox = getSandbox(env.Sandbox, 'my-sandbox')\n *     const server = await createOpenhandsServer(sandbox, {\n *       port: 8001,\n *       exposePort: true,\n *       hostname: 'yourdomain.com'\n *     })\n *     return proxyToOpenhands(request, sandbox, server)\n *   }\n * }\n * ```\n */\nexport function proxyToOpenhands(\n  request: Request,\n  sandbox: Sandbox<unknown>,\n  server: OpenhandsServer\n): Response | Promise<Response> {\n  return sandbox.containerFetch(request, server.port);\n}\n\n"
+  ],
+  "mappings": "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",
+  "debugId": "4C4FB2DEC1D2C02F64756E2164756E21",
+  "names": []
+}

package/dist/openhands/openhands.d.ts

@@ -0,0 +1,64 @@
+import type { Sandbox } from '@cloudflare/sandbox';
+import type { OpenhandsOptions, OpenhandsServer } from './types';
+/**
+ * Starts an agent-server inside a Sandbox container.
+ *
+ * This function manages the server lifecycle only. If an agent-server is already
+ * running on the specified port, this function will reuse it instead of starting
+ * a new one.
+ *
+ * @param sandbox - The Sandbox instance to run agent-server in
+ * @param options - Configuration options
+ * @returns Promise resolving to server handle { port, url, previewUrl?, close() }
+ *
+ * @example
+ * ```typescript
+ * import { getSandbox } from '@cloudflare/sandbox'
+ * import { createOpenhandsServer } from 'openhands-sdk/openhands'
+ *
+ * const sandbox = getSandbox(env.Sandbox, 'my-sandbox')
+ * const server = await createOpenhandsServer(sandbox, {
+ *   port: 8001,
+ *   exposePort: true,
+ *   hostname: 'yourdomain.com'
+ * })
+ *
+ * // Proxy requests to the server
+ * return sandbox.containerFetch(request, server.port)
+ *
+ * // When done
+ * await server.close()
+ * ```
+ */
+export declare function createOpenhandsServer(sandbox: Sandbox<unknown>, options?: OpenhandsOptions): Promise<OpenhandsServer>;
+/**
+ * Proxy a request to the agent-server.
+ *
+ * This function handles proxying only - you must start the server separately
+ * using `createOpenhandsServer()`.
+ *
+ * @param request - The incoming HTTP request
+ * @param sandbox - The Sandbox instance running agent-server
+ * @param server - The agent-server handle from createOpenhandsServer()
+ * @returns Response from agent-server
+ *
+ * @example
+ * ```typescript
+ * import { getSandbox } from '@cloudflare/sandbox'
+ * import { createOpenhandsServer, proxyToOpenhands } from 'openhands-sdk/openhands'
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const sandbox = getSandbox(env.Sandbox, 'my-sandbox')
+ *     const server = await createOpenhandsServer(sandbox, {
+ *       port: 8001,
+ *       exposePort: true,
+ *       hostname: 'yourdomain.com'
+ *     })
+ *     return proxyToOpenhands(request, sandbox, server)
+ *   }
+ * }
+ * ```
+ */
+export declare function proxyToOpenhands(request: Request, sandbox: Sandbox<unknown>, server: OpenhandsServer): Response | Promise<Response>;
+//# sourceMappingURL=openhands.d.ts.map

package/dist/openhands/openhands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openhands.d.ts","sourceRoot":"","sources":["../../src/openhands/openhands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAW,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EAEhB,MAAM,SAAS,CAAC;AA2JjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EACzB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAkC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EACzB,MAAM,EAAE,eAAe,GACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAE9B"}

package/dist/openhands/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Configuration options for starting OpenHands agent-server
+ */
+export interface OpenhandsOptions {
+    /** Port for agent-server (default: 8001) */
+    port?: number;
+    /** Working directory for agent-server (default: /container-server/software-agent-sdk) */
+    directory?: string;
+    /** Hostname for preview URL exposure (required if exposePort is true) */
+    hostname?: string;
+    /** Enable preview URL exposure (default: false) */
+    exposePort?: boolean;
+    /** Environment variables for agent-server */
+    env?: Record<string, string>;
+    /** Sandbox name/session ID (default: 'my-sandbox') */
+    sandboxName?: string;
+}
+/**
+ * Server lifecycle management
+ */
+export interface OpenhandsServer {
+    /** Port the server is running on */
+    port: number;
+    /** Base URL for server (http://localhost:{port}) */
+    url: string;
+    /** Preview URL if port was exposed (optional) */
+    previewUrl?: string;
+    /** Process ID */
+    processId: string;
+    /** Close the server gracefully */
+    close(): Promise<void>;
+}
+/**
+ * Context information for startup errors
+ */
+export interface OpenhandsStartupContext {
+    port: number;
+    stderr?: string;
+    command?: string;
+    processId?: string;
+}
+/**
+ * Error thrown when agent-server fails to start
+ */
+export declare class OpenhandsStartupError extends Error {
+    readonly code: "OPENHANDS_STARTUP_FAILED";
+    readonly context: OpenhandsStartupContext;
+    constructor(message: string, context: OpenhandsStartupContext, options?: ErrorOptions);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/openhands/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/openhands/types.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;IACpD,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;gBAGxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,uBAAuB,EAChC,OAAO,CAAC,EAAE,YAAY;CAMzB"}

package/dist/routes/handler.d.ts

@@ -0,0 +1,51 @@
+import { type OpenhandsOptions } from '../openhands';
+export type OpenhandsEnv = {
+    Sandbox: {
+        get(id: {
+            toString(): string;
+        }): {
+            fetch(input: string | Request, init?: RequestInit): Promise<Response>;
+        };
+    };
+};
+/**
+ * Options for OpenHands route handler
+ */
+export interface OpenhandsHandlerOptions extends OpenhandsOptions {
+    /** Base path for OpenHands routes (default: '') */
+    basePath?: string;
+    /** Custom sandbox name resolver */
+    getSandboxName?: (request: Request) => string | null;
+}
+/**
+ * Creates a middleware function that handles OpenHands routes.
+ * Returns null if the request doesn't match OpenHands routes (allows chaining).
+ *
+ * @param options - Configuration options
+ * @returns Middleware function
+ */
+export declare function createOpenhandsHandler<Env extends OpenhandsEnv = OpenhandsEnv>(options?: OpenhandsHandlerOptions): (request: Request, env: Env) => Promise<Response | null>;
+/**
+ * Attaches OpenHands routes to an existing fetch handler.
+ * This wraps your handler with OpenHands route handling and preview URL proxying.
+ *
+ * @param fetchHandler - Your existing fetch handler
+ * @param options - Configuration options
+ * @returns Wrapped fetch handler
+ *
+ * @example
+ * ```typescript
+ * import { attachOpenhandsRoutes } from 'openhands-sdk/routes';
+ *
+ * export default attachOpenhandsRoutes(async (request, env) => {
+ *   // Your custom routes here
+ *   return new Response('Not found', { status: 404 });
+ * }, {
+ *   port: 8001,
+ *   exposePort: true,
+ *   hostname: 'yourdomain.com'
+ * });
+ * ```
+ */
+export declare function attachOpenhandsRoutes<Env extends OpenhandsEnv = OpenhandsEnv>(fetchHandler: (request: Request, env: Env) => Response | Promise<Response>, options?: OpenhandsHandlerOptions): (request: Request, env: Env) => Promise<Response>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/routes/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/routes/handler.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAC;AAOtB,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE;QACP,GAAG,CAAC,EAAE,EAAE;YAAE,QAAQ,IAAI,MAAM,CAAA;SAAE,GAAG;YAC/B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;SACvE,CAAC;KACH,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAC;CACtD;AA+CD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,SAAS,YAAY,GAAG,YAAY,EAC5E,OAAO,GAAE,uBAA4B,IASnC,SAAS,OAAO,EAChB,KAAK,GAAG,KACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAiH5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,SAAS,YAAY,GAAG,YAAY,EAC3E,YAAY,EAAE,CACZ,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,GAAG,KACL,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,EACjC,OAAO,GAAE,uBAA4B,GACpC,CACD,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,GAAG,KACL,OAAO,CAAC,QAAQ,CAAC,CAgBrB"}