feat: add per-request browser config (proxy, profile, extensions, timeout)

Add optional `browser` field to CUA payload for per-request browser
session configuration. Supports proxy_id, profile (id/name/save_changes),
extensions, and timeout_seconds. Viewport and stealth remain deploy-time
defaults since CUA providers depend on consistent viewport dimensions.

Made-with: Cursor

Author: masnwilliams

pkg/templates/python/cua/.env.example

@@ -12,3 +12,15 @@ CUA_PROVIDER=anthropic
 ANTHROPIC_API_KEY=your_anthropic_api_key_here
 OPENAI_API_KEY=your_openai_api_key_here
 GOOGLE_API_KEY=your_google_api_key_here
+
+# Browser config (proxy, profile, extensions, timeout) is set per-request
+# via the payload "browser" field, not here. Example:
+#   kernel invoke python-cua cua-task --payload '{
+#     "query": "...",
+#     "browser": {
+#       "proxy_id": "proxy_abc123",
+#       "profile": { "name": "my-profile", "save_changes": true },
+#       "extensions": [{ "name": "my-extension" }],
+#       "timeout_seconds": 600
+#     }
+#   }'

pkg/templates/python/cua/main.py

@@ -25,11 +25,30 @@
 app = kernel.App("python-cua")
 
 
+class BrowserProfile(TypedDict, total=False):
+    id: str
+    name: str
+    save_changes: bool
+
+
+class BrowserExtension(TypedDict, total=False):
+    id: str
+    name: str
+
+
+class BrowserConfig(TypedDict, total=False):
+    proxy_id: str
+    profile: BrowserProfile
+    extensions: list[BrowserExtension]
+    timeout_seconds: int
+
+
 class CuaInput(TypedDict, total=False):
     query: str
     provider: Literal["anthropic", "openai", "gemini"]
     model: str
     record_replay: bool
+    browser: BrowserConfig
 
 
 class CuaOutput(TypedDict, total=False):
@@ -64,12 +83,17 @@ 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]
 
+    browser_cfg = payload.get("browser") or {}
     session = KernelBrowserSession(
         kernel_client,
         SessionOptions(
             invocation_id=ctx.invocation_id,
             stealth=True,
             record_replay=payload.get("record_replay", False),
+            proxy_id=browser_cfg.get("proxy_id"),
+            profile=browser_cfg.get("profile"),
+            extensions=browser_cfg.get("extensions"),
+            timeout_seconds=browser_cfg.get("timeout_seconds", 300),
         ),
     )
 

pkg/templates/python/cua/session.py

@@ -19,6 +19,9 @@ class SessionOptions:
     replay_grace_period: float = 5.0
     viewport_width: int = 1280
     viewport_height: int = 800
+    proxy_id: str | None = None
+    profile: dict | None = None
+    extensions: list[dict] | None = None
 
 
 @dataclass
@@ -68,15 +71,25 @@ def info(self) -> SessionInfo:
         )
 
     async def start(self) -> SessionInfo:
-        browser = await asyncio.to_thread(
-            self.kernel.browsers.create,
-            invocation_id=self.opts.invocation_id,
-            stealth=self.opts.stealth,
-            timeout_seconds=self.opts.timeout_seconds,
-            viewport={
+        create_kwargs: dict = {
+            "invocation_id": self.opts.invocation_id,
+            "stealth": self.opts.stealth,
+            "timeout_seconds": self.opts.timeout_seconds,
+            "viewport": {
                 "width": self.opts.viewport_width,
                 "height": self.opts.viewport_height,
             },
+        }
+        if self.opts.proxy_id:
+            create_kwargs["proxy_id"] = self.opts.proxy_id
+        if self.opts.profile:
+            create_kwargs["profile"] = self.opts.profile
+        if self.opts.extensions:
+            create_kwargs["extensions"] = self.opts.extensions
+
+        browser = await asyncio.to_thread(
+            self.kernel.browsers.create,
+            **create_kwargs,
         )
 
         self._session_id = browser.session_id

pkg/templates/typescript/cua/.env.example

@@ -12,3 +12,15 @@ CUA_PROVIDER=anthropic
 ANTHROPIC_API_KEY=your_anthropic_api_key_here
 OPENAI_API_KEY=your_openai_api_key_here
 GOOGLE_API_KEY=your_google_api_key_here
+
+# Browser config (proxy, profile, extensions, timeout) is set per-request
+# via the payload "browser" field, not here. Example:
+#   kernel invoke ts-cua cua-task --payload '{
+#     "query": "...",
+#     "browser": {
+#       "proxy_id": "proxy_abc123",
+#       "profile": { "name": "my-profile", "save_changes": true },
+#       "extensions": [{ "name": "my-extension" }],
+#       "timeout_seconds": 600
+#     }
+#   }'

pkg/templates/typescript/cua/index.ts

@@ -17,11 +17,19 @@ import { resolveProviders, runWithFallback, type ProviderName } from './provider
 const kernel = new Kernel();
 const app = kernel.app('ts-cua');
 
+interface BrowserConfig {
+  proxy_id?: string;
+  profile?: { id?: string; name?: string; save_changes?: boolean };
+  extensions?: Array<{ id?: string; name?: string }>;
+  timeout_seconds?: number;
+}
+
 interface CuaInput {
   query: string;
   provider?: ProviderName;
   model?: string;
   record_replay?: boolean;
+  browser?: BrowserConfig;
 }
 
 interface CuaOutput {
@@ -62,6 +70,10 @@ app.action<CuaInput, CuaOutput>(
       invocationId: ctx.invocation_id,
       stealth: true,
       recordReplay: payload.record_replay ?? false,
+      ...(payload.browser?.proxy_id ? { proxyId: payload.browser.proxy_id } : {}),
+      ...(payload.browser?.profile ? { profile: payload.browser.profile } : {}),
+      ...(payload.browser?.extensions ? { extensions: payload.browser.extensions } : {}),
+      ...(payload.browser?.timeout_seconds ? { timeoutSeconds: payload.browser.timeout_seconds } : {}),
     });
 
     await session.start();

pkg/templates/typescript/cua/session.ts

@@ -14,6 +14,9 @@ export interface SessionOptions {
   replayGracePeriod?: number;
   viewportWidth?: number;
   viewportHeight?: number;
+  proxyId?: string;
+  profile?: { id?: string; name?: string; save_changes?: boolean };
+  extensions?: Array<{ id?: string; name?: string }>;
 }
 
 export interface SessionInfo {
@@ -75,6 +78,9 @@ export class KernelBrowserSession {
       stealth: this.opts.stealth,
       timeout_seconds: this.opts.timeoutSeconds,
       viewport: { width: this.opts.viewportWidth, height: this.opts.viewportHeight },
+      ...(this.opts.proxyId ? { proxy_id: this.opts.proxyId } : {}),
+      ...(this.opts.profile ? { profile: this.opts.profile } : {}),
+      ...(this.opts.extensions?.length ? { extensions: this.opts.extensions } : {}),
     });
 
     this._sessionId = browser.session_id;