Add unified CUA template with multi-provider fallback

Adds a new 'cua' template (TypeScript + Python) that supports Anthropic,
OpenAI, and Gemini CUA providers behind a clean abstraction layer. Includes
automatic fallback on provider-level errors (rate limits, API errors) while
preserving task-level error behavior. Config-driven via CUA_PROVIDER and
CUA_FALLBACK_PROVIDERS env vars, with per-request provider override support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: masnwilliams

pkg/create/templates.go

@@ -19,6 +19,7 @@ const (
 	TemplateOpenAGIComputerUse   = "openagi-computer-use"
 	TemplateClaudeAgentSDK       = "claude-agent-sdk"
 	TemplateYutoriComputerUse    = "yutori"
+	TemplateCUA                  = "cua"
 )
 
 type TemplateInfo struct {
@@ -90,6 +91,11 @@ var Templates = map[string]TemplateInfo{
 		Description: "Implements a Yutori n1 computer use agent",
 		Languages:   []string{LanguageTypeScript, LanguagePython},
 	},
+	TemplateCUA: {
+		Name:        "Unified CUA",
+		Description: "Multi-provider CUA with automatic fallback (Anthropic, OpenAI, Gemini)",
+		Languages:   []string{LanguageTypeScript, LanguagePython},
+	},
 }
 
 // GetSupportedTemplatesForLanguage returns a list of all supported template names for a given language
@@ -213,6 +219,11 @@ var Commands = map[string]map[string]DeployConfig{
 			NeedsEnvFile:  true,
 			InvokeCommand: `kernel invoke ts-yutori-cua cua-task --payload '{"query": "Navigate to https://example.com and describe the page"}'`,
 		},
+		TemplateCUA: {
+			EntryPoint:    "index.ts",
+			NeedsEnvFile:  true,
+			InvokeCommand: `kernel invoke ts-cua cua-task --payload '{"query": "Navigate to https://example.com and describe the page"}'`,
+		},
 	},
 	LanguagePython: {
 		TemplateSampleApp: {
@@ -260,6 +271,11 @@ var Commands = map[string]map[string]DeployConfig{
 			NeedsEnvFile:  true,
 			InvokeCommand: `kernel invoke python-yutori-cua cua-task --payload '{"query": "Navigate to https://example.com and describe the page"}'`,
 		},
+		TemplateCUA: {
+			EntryPoint:    "main.py",
+			NeedsEnvFile:  true,
+			InvokeCommand: `kernel invoke python-cua cua-task --payload '{"query": "Navigate to https://example.com and describe the page"}'`,
+		},
 	},
 }
 

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

@@ -0,0 +1,10 @@
+# Primary provider: anthropic, openai, or gemini
+CUA_PROVIDER=anthropic
+
+# Fallback providers (comma-separated, tried in order on provider errors)
+# CUA_FALLBACK_PROVIDERS=openai,gemini
+
+# Provider API keys (set the ones you need)
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+# OPENAI_API_KEY=your_openai_api_key_here
+# GOOGLE_API_KEY=your_google_api_key_here

pkg/templates/python/cua/README.md

@@ -0,0 +1,86 @@
+# Kernel Unified CUA Template (Python)
+
+A unified Computer Use Agent (CUA) template that supports multiple providers with automatic fallback.
+
+## Supported Providers
+
+| Provider | Model | Env Var |
+|----------|-------|---------|
+| Anthropic | `claude-sonnet-4-6` | `ANTHROPIC_API_KEY` |
+| OpenAI | `gpt-5.4` | `OPENAI_API_KEY` |
+| Gemini | `gemini-2.5-computer-use-preview-10-2025` | `GOOGLE_API_KEY` |
+
+## Setup
+
+1. Get your API keys:
+   - **Kernel**: [dashboard.onkernel.com](https://dashboard.onkernel.com)
+   - **Anthropic**: [console.anthropic.com](https://console.anthropic.com)
+   - **OpenAI**: [platform.openai.com](https://platform.openai.com)
+   - **Google**: [aistudio.google.com](https://aistudio.google.com)
+
+2. Configure and deploy:
+```bash
+kernel login
+cp .env.example .env  # Add your API keys and configure providers
+kernel deploy main.py --env-file .env
+```
+
+## Configuration
+
+Set these environment variables in your `.env` file:
+
+```bash
+# Primary provider (default: anthropic)
+CUA_PROVIDER=anthropic
+
+# Fallback providers, tried in order on provider errors (optional)
+CUA_FALLBACK_PROVIDERS=openai,gemini
+
+# API keys for each provider you want to use
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+GOOGLE_API_KEY=AI...
+```
+
+## Usage
+
+```bash
+# Use default provider
+kernel invoke python-cua cua-task --payload '{"query": "Navigate to https://example.com and describe the page"}'
+
+# Override provider per-request
+kernel invoke python-cua cua-task --payload '{"query": "Search for kernel.sh", "provider": "openai"}'
+
+# With replay recording
+kernel invoke python-cua cua-task --payload '{"query": "Navigate to https://example.com", "record_replay": true}'
+```
+
+## How Fallback Works
+
+The fallback mechanism triggers on **provider-level errors** only:
+- Rate limits (429)
+- Server errors (500, 502, 503)
+- Authentication failures
+- Network errors
+
+It does **not** fall back on task-level failures.
+
+## Architecture
+
+```
+main.py               Entry point, Kernel app registration
+session.py            Browser lifecycle management (shared)
+tools.py              Common action types + Kernel API executor (shared)
+providers/
+  __init__.py         Provider factory + fallback logic
+  anthropic.py        Anthropic Claude computer use adapter
+  openai_provider.py  OpenAI CUA adapter
+  gemini.py           Google Gemini computer use adapter
+```
+
+## Resources
+
+- [Kernel Documentation](https://www.kernel.sh/docs/quickstart)
+- [Anthropic Computer Use](https://docs.anthropic.com/en/docs/build-with-claude/computer-use)
+- [OpenAI Computer Use](https://platform.openai.com/docs/guides/computer-use)
+- [Gemini Computer Use](https://ai.google.dev/gemini-api/docs/computer-use)

pkg/templates/python/cua/main.py

@@ -0,0 +1,99 @@
+"""
+Unified CUA (Computer Use Agent) template.
+
+Supports Anthropic, OpenAI, and Gemini providers with automatic fallback.
+Configure via environment variables:
+  CUA_PROVIDER            - Primary provider: anthropic, openai, or gemini (default: anthropic)
+  CUA_FALLBACK_PROVIDERS  - Comma-separated fallback order (e.g. "openai,gemini")
+  ANTHROPIC_API_KEY       - Required if using Anthropic
+  OPENAI_API_KEY          - Required if using OpenAI
+  GOOGLE_API_KEY          - Required if using Gemini
+"""
+
+import os
+from typing import NotRequired, Optional, TypedDict
+
+import kernel
+from session import KernelBrowserSession
+from tools import KernelExecutor
+from providers import run_with_fallback, ProviderConfig
+
+# Parse provider configuration
+PRIMARY_PROVIDER = os.getenv("CUA_PROVIDER", "anthropic")
+FALLBACK_PROVIDERS = [
+    p.strip() for p in os.getenv("CUA_FALLBACK_PROVIDERS", "").split(",") if p.strip()
+]
+PROVIDER_CHAIN = [PRIMARY_PROVIDER] + FALLBACK_PROVIDERS
+
+API_KEY_MAP = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "gemini": "GOOGLE_API_KEY",
+}
+
+configured = [p for p in PROVIDER_CHAIN if os.getenv(API_KEY_MAP.get(p, ""))]
+if not configured:
+    keys = [API_KEY_MAP.get(p, p) for p in PROVIDER_CHAIN]
+    raise ValueError(
+        f"No API keys found for configured providers {PROVIDER_CHAIN}. "
+        f"Set at least one of: {', '.join(keys)}"
+    )
+
+
+class CuaInput(TypedDict):
+    query: str
+    provider: NotRequired[str]
+    model: NotRequired[str]
+    record_replay: NotRequired[bool]
+
+
+class CuaOutput(TypedDict):
+    result: str
+    provider: str
+    replay_url: Optional[str]
+
+
+app = kernel.App("python-cua")
+
+
+@app.action("cua-task")
+async def cua_task(
+    ctx: kernel.KernelContext,
+    payload: CuaInput,
+) -> CuaOutput:
+    if not payload or not payload.get("query"):
+        raise ValueError("Query is required")
+
+    # Allow per-request provider override
+    if payload.get("provider"):
+        provider_chain = [payload["provider"]] + [p for p in PROVIDER_CHAIN if p != payload["provider"]]
+    else:
+        provider_chain = PROVIDER_CHAIN
+
+    record_replay = payload.get("record_replay", False)
+
+    async with KernelBrowserSession(
+        invocation_id=ctx.invocation_id,
+        stealth=True,
+        record_replay=record_replay,
+    ) as session:
+        print("Kernel browser live view url:", session.live_view_url)
+
+        executor = KernelExecutor(session.kernel, session.session_id)
+
+        result = await run_with_fallback(
+            provider_chain,
+            ProviderConfig(
+                query=payload["query"],
+                model=payload.get("model"),
+                viewport_width=session.viewport_width,
+                viewport_height=session.viewport_height,
+            ),
+            executor,
+        )
+
+    return {
+        "result": result.result,
+        "provider": result.provider,
+        "replay_url": session.replay_view_url,
+    }

pkg/templates/python/cua/providers/__init__.py

@@ -0,0 +1,97 @@
+"""
+Provider factory and fallback logic.
+
+Creates provider instances and handles automatic fallback on provider errors
+(rate limits, API errors). Does NOT fall back on task-level failures.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Protocol
+
+from tools import KernelExecutor
+
+
+@dataclass
+class ProviderConfig:
+    query: str
+    model: Optional[str] = None
+    api_key: Optional[str] = None
+    viewport_width: int = 1280
+    viewport_height: int = 800
+
+
+@dataclass
+class ProviderResult:
+    result: str
+    provider: str
+
+
+class CUAProvider(Protocol):
+    name: str
+
+    async def run(self, config: ProviderConfig, executor: KernelExecutor) -> ProviderResult: ...
+
+
+def create_provider(name: str) -> CUAProvider:
+    if name == "anthropic":
+        from providers.anthropic import AnthropicProvider
+        return AnthropicProvider()
+    elif name == "openai":
+        from providers.openai_provider import OpenAIProvider
+        return OpenAIProvider()
+    elif name == "gemini":
+        from providers.gemini import GeminiProvider
+        return GeminiProvider()
+    else:
+        raise ValueError(f"Unknown provider: {name}. Supported: anthropic, openai, gemini")
+
+
+# Errors that indicate a provider-level failure (should trigger fallback)
+_PROVIDER_ERROR_KEYWORDS = [
+    "rate limit", "429", "503", "502", "500", "overloaded", "capacity",
+    "api key", "authentication", "unauthorized", "forbidden", "quota",
+    "timeout", "connection", "refused", "reset",
+]
+
+
+def _is_provider_error(error: Exception) -> bool:
+    msg = str(error).lower()
+    return any(kw in msg for kw in _PROVIDER_ERROR_KEYWORDS)
+
+
+async def run_with_fallback(
+    providers: list[str],
+    config: ProviderConfig,
+    executor: KernelExecutor,
+) -> ProviderResult:
+    """
+    Run a CUA task with automatic fallback across providers.
+
+    Tries the primary provider first. On provider-level errors (rate limits, API errors),
+    falls back to the next provider. Does NOT fall back on task-level failures.
+    """
+    errors: list[tuple[str, Exception]] = []
+
+    for provider_name in providers:
+        provider = create_provider(provider_name)
+        try:
+            print(f"[cua] Trying provider: {provider_name}")
+            result = await provider.run(config, executor)
+            print(f"[cua] Provider {provider_name} succeeded")
+            return result
+        except Exception as e:
+            errors.append((provider_name, e))
+            print(f"[cua] Provider {provider_name} failed: {e}")
+
+            if not _is_provider_error(e):
+                raise
+
+            if provider_name == providers[-1]:
+                error_details = "\n".join(f"  {name}: {err}" for name, err in errors)
+                raise RuntimeError(f"All providers failed:\n{error_details}") from e
+
+            print("[cua] Falling back to next provider...")
+
+    raise RuntimeError("No providers configured")