feat: allow passing an existing session_id to skip browser creation

When session_id is provided in the payload, the CUA task uses that
existing browser session directly instead of creating a new one. The
caller is responsible for the session lifecycle. This lets users
pre-configure browsers with any settings and reuse sessions across tasks.

Made-with: Cursor

Author: masnwilliams

pkg/templates/python/cua/main.py

@@ -48,6 +48,7 @@ class CuaInput(TypedDict, total=False):
     provider: Literal["anthropic", "openai", "gemini"]
     model: str
     record_replay: bool
+    session_id: str
     browser: BrowserConfig
 
 
@@ -83,6 +84,21 @@ async def cua_task(ctx: kernel.KernelContext, payload: CuaInput | None = None) -
         if requested:
             providers = [requested] + [p for p in providers if p is not requested]
 
+    # Use an existing browser session or create a new one
+    if payload.get("session_id"):
+        task_result = await run_with_fallback(
+            providers,
+            TaskOptions(
+                query=payload["query"],
+                kernel=kernel_client,
+                session_id=payload["session_id"],
+                model=payload.get("model"),
+                viewport_width=1280,
+                viewport_height=800,
+            ),
+        )
+        return {"result": task_result.result, "provider": task_result.provider}
+
     browser_cfg = payload.get("browser") or {}
     session = KernelBrowserSession(
         kernel_client,

pkg/templates/typescript/cua/index.ts

@@ -29,6 +29,7 @@ interface CuaInput {
   provider?: ProviderName;
   model?: string;
   record_replay?: boolean;
+  session_id?: string;
   browser?: BrowserConfig;
 }
 
@@ -66,6 +67,19 @@ app.action<CuaInput, CuaOutput>(
       }
     }
 
+    // Use an existing browser session or create a new one
+    if (payload.session_id) {
+      const { result, provider } = await runWithFallback(providers, {
+        query: payload.query,
+        model: payload.model,
+        kernel,
+        sessionId: payload.session_id,
+        viewportWidth: 1280,
+        viewportHeight: 800,
+      });
+      return { result, provider };
+    }
+
     const session = new KernelBrowserSession(kernel, {
       invocationId: ctx.invocation_id,
       stealth: true,