zevairouter 1.0.35 → 1.0.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zevairouter",
-  "version": "1.0.35",
+  "version": "1.0.36",
   "description": "ZevaiRouter - AI Router with provider automation, multi-account workflows, and quota tracking",
   "bin": {
     "zevai": "./cli/cli.js"
@@ -70,8 +70,8 @@
     "camoufox-js": "^0.11.0",
     "playwright": "^1.54.2"
   },
-  "comment_better_sqlite3": "kept in optionalDependencies so npm install doesn't fail on systems without build tools — sql.js is used as fallback at runtime",
-  "comment_camoufox_js": "optional stealth-Firefox engine for bulk-import; runtime auto-installs to user data dir if user picks Camoufox in the modal but the package is missing — Chromium remains the default and works without this dep",
+  "comment_better_sqlite3": "kept in optionalDependencies so npm install doesn't fail on systems without build tools \u2014 sql.js is used as fallback at runtime",
+  "comment_camoufox_js": "optional stealth-Firefox engine for bulk-import; runtime auto-installs to user data dir if user picks Camoufox in the modal but the package is missing \u2014 Chromium remains the default and works without this dep",
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",
     "esbuild": "^0.28.1",

package/src/app/(dashboard)/dashboard/automation/page.js

@@ -1,7 +1,7 @@
 "use client";
 
 import { useCallback, useEffect, useMemo, useState } from "react";
-import { Badge, Button, BulkAccountAutomationModal, Card, CardSkeleton, KiroOAuthWrapper, OAuthModal } from "@/shared/components";
+import { Badge, Button, BulkAccountAutomationModal, Card, CardSkeleton, CodeBuddyCnPhoneRegisterModal, KiroOAuthWrapper, OAuthModal } from "@/shared/components";
 import { FREE_PROVIDERS } from "@/shared/constants/providers";
 
 // Render the provider's real logo from /providers/<id>.png, falling back to
@@ -308,6 +308,150 @@ function CodeBuddyAutomationPanel({ providerInfo, onRefresh }) {
   );
 }
 
+function CodeBuddyCnBulkTokenModal({ isOpen, onClose, onSuccess }) {
+  const [tokens, setTokens] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState(null);
+
+  const handleImport = async () => {
+    if (!tokens.trim()) return;
+    setLoading(true);
+    setResult(null);
+    try {
+      const res = await fetch("/api/oauth/codebuddy-cn/bulk-token", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tokens }),
+      });
+      const data = await res.json();
+      setResult(data);
+      if (data.success) onSuccess?.();
+    } catch (error) {
+      setResult({ error: error.message });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (!isOpen) return null;
+
+  let successMsg = null;
+  if (result?.success) {
+    const parts = [`Imported ${result.imported}/${result.total} tokens.`];
+    if (result.failed) parts.push(`${result.failed} failed.`);
+    successMsg = parts.join(" ");
+  }
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50" onClick={onClose}>
+      <div className="w-full max-w-lg rounded-xl border border-border bg-surface p-6 shadow-xl" onClick={(e) => e.stopPropagation()}>
+        <h3 className="mb-4 text-lg font-semibold text-text-main">CodeBuddy CN OAuth Token Import</h3>
+        <p className="mb-2 text-xs text-text-muted">Paste CodeBuddy CN OAuth tokens, one per line. Supports:</p>
+        <div className="mb-3 space-y-1 rounded-lg bg-background/50 p-3 text-xs text-text-muted">
+          <div><code className="text-[10px] bg-border/50 px-1.5 py-0.5 rounded">accessToken</code> — access token only</div>
+          <div><code className="text-[10px] bg-border/50 px-1.5 py-0.5 rounded">accessToken:refreshToken</code> — enables auto-refresh</div>
+        </div>
+        <textarea
+          className="mb-3 w-full rounded-lg border border-border bg-background p-3 font-mono text-xs text-text-main placeholder:text-text-muted focus:border-primary focus:outline-none"
+          rows={8}
+          placeholder={"eyJhbGciOiJSUzI1NiIs...\neyJhbGciOiJSUzI1NiIs...:eyJhbGciOiJSUzI1NiIs..."}
+          value={tokens}
+          onChange={(e) => setTokens(e.target.value)}
+          disabled={loading}
+        />
+        {result && (
+          <div className={"mb-3 rounded-lg p-3 text-xs " + (result.success ? "bg-green-500/10 text-green-400" : "bg-red-500/10 text-red-400")}>
+            {successMsg || result.error || "Import failed"}
+          </div>
+        )}
+        <div className="flex justify-end gap-2">
+          <button type="button" onClick={onClose} className="rounded-lg px-4 py-2 text-sm text-text-muted hover:bg-border/50">Close</button>
+          <button
+            type="button"
+            onClick={handleImport}
+            disabled={loading || !tokens.trim()}
+            className="rounded-lg bg-primary px-4 py-2 text-sm font-medium text-white hover:bg-primary/90 disabled:opacity-50"
+          >
+            {loading ? "Importing..." : "Import Tokens"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function CodeBuddyCnAutomationPanel({ providerInfo, onRefresh }) {
+  const [isPhoneOpen, setIsPhoneOpen] = useState(false);
+  const [isBulkTokenOpen, setIsBulkTokenOpen] = useState(false);
+  const [isOAuthOpen, setIsOAuthOpen] = useState(false);
+
+  return (
+    <>
+      <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
+        <button
+          type="button"
+          onClick={() => setIsPhoneOpen(true)}
+          className="flex min-h-[112px] min-w-0 flex-col gap-2 rounded-lg border border-border bg-surface px-4 py-3 text-left transition-colors hover:border-primary/40 hover:bg-primary/5"
+        >
+          <span className="flex items-center gap-2 text-sm font-semibold text-text-main">
+            <span className="material-symbols-outlined text-[20px] text-primary">smartphone</span>
+            Auto Register (Phone)
+          </span>
+          <span className="text-xs leading-relaxed text-text-muted">
+            Bulk auto-register CodeBuddy CN accounts using 5sim virtual phone numbers (HK/China). Includes device-code token capture.
+          </span>
+        </button>
+        <button
+          type="button"
+          onClick={() => setIsBulkTokenOpen(true)}
+          className="flex min-h-[112px] min-w-0 flex-col gap-2 rounded-lg border border-border bg-surface px-4 py-3 text-left transition-colors hover:border-primary/40 hover:bg-primary/5"
+        >
+          <span className="flex items-center gap-2 text-sm font-semibold text-text-main">
+            <span className="material-symbols-outlined text-[20px] text-primary">playlist_add</span>
+            OAuth Token Import
+          </span>
+          <span className="text-xs leading-relaxed text-text-muted">
+            Paste pre-obtained CodeBuddy CN OAuth tokens with optional refresh tokens.
+          </span>
+        </button>
+        <button
+          type="button"
+          onClick={() => setIsOAuthOpen(true)}
+          className="flex min-h-[112px] min-w-0 flex-col gap-2 rounded-lg border border-border bg-surface px-4 py-3 text-left transition-colors hover:border-primary/40 hover:bg-primary/5"
+        >
+          <span className="flex items-center gap-2 text-sm font-semibold text-text-main">
+            <span className="material-symbols-outlined text-[20px] text-primary">login</span>
+            Device OAuth Login
+          </span>
+          <span className="text-xs leading-relaxed text-text-muted">
+            Open CodeBuddy CN browser login and poll until the OAuth token is saved.
+          </span>
+        </button>
+      </div>
+      <CodeBuddyCnPhoneRegisterModal
+        isOpen={isPhoneOpen}
+        onClose={() => setIsPhoneOpen(false)}
+        onSuccess={onRefresh}
+      />
+      <CodeBuddyCnBulkTokenModal
+        isOpen={isBulkTokenOpen}
+        onClose={() => setIsBulkTokenOpen(false)}
+        onSuccess={onRefresh}
+      />
+      <OAuthModal
+        isOpen={isOAuthOpen}
+        provider="codebuddy-cn"
+        providerInfo={providerInfo}
+        onSuccess={() => {
+          onRefresh?.();
+          setIsOAuthOpen(false);
+        }}
+        onClose={() => setIsOAuthOpen(false)}
+      />
+    </>
+  );
+}
+
 function QoderAutomationPanel({ providerInfo, onRefresh }) {
   const [isBulkOpen, setIsBulkOpen] = useState(false);
   const [isOAuthOpen, setIsOAuthOpen] = useState(false);
@@ -469,6 +613,14 @@ const AUTOMATION_PROVIDERS = [
     supportedModes: ["bulk-account", "device-oauth"],
     component: CodeBuddyAutomationPanel,
   },
+  {
+    id: "codebuddy-cn",
+    label: "CodeBuddy CN",
+    icon: "smart_toy",
+    description: "Phone-number auto-registration via 5sim SMS, token import, and device OAuth.",
+    supportedModes: ["bulk-account", "device-oauth"],
+    component: CodeBuddyCnAutomationPanel,
+  },
   {
     id: "qoder",
     label: "Qoder",

package/src/app/api/oauth/codebuddy-cn/bulk-import/[jobId]/cancel/route.js

@@ -0,0 +1,19 @@
+import { NextResponse } from "next/server";
+import { getCodeBuddyCnBulkImportManager } from "@/lib/oauth/services/codebuddyCnBulkImportManager";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(_request, { params }) {
+  const { jobId } = await params;
+  const manager = getCodeBuddyCnBulkImportManager();
+  const job = manager.cancelJob(jobId);
+
+  if (!job) {
+    return NextResponse.json({ error: "Bulk import job not found" }, { status: 404 });
+  }
+
+  return NextResponse.json({
+    success: true,
+    job,
+  });
+}

package/src/app/api/oauth/codebuddy-cn/bulk-import/[jobId]/manual/[workerId]/route.js

@@ -0,0 +1,30 @@
+import { NextResponse } from "next/server";
+import { getCodeBuddyCnBulkImportManager } from "@/lib/oauth/services/codebuddyCnBulkImportManager";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(_request, { params }) {
+  const { jobId, workerId } = await params;
+  const manager = getCodeBuddyCnBulkImportManager();
+  const result = await manager.openManualSession(jobId, workerId);
+
+  if (!result) {
+    return NextResponse.json({ error: "Bulk import job not found" }, { status: 404 });
+  }
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        error: result.error || "Manual session not found for this worker",
+        job: result.job,
+      },
+      { status: 404 }
+    );
+  }
+
+  return NextResponse.json({
+    success: true,
+    job: result.job,
+    account: result.account,
+  });
+}

package/src/app/api/oauth/codebuddy-cn/bulk-import/[jobId]/route.js

@@ -0,0 +1,26 @@
+import { NextResponse } from "next/server";
+import {
+  getCodeBuddyCnBulkImportManager,
+  buildLookupResponse,
+} from "@/lib/oauth/services/codebuddyCnBulkImportManager";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(_request, { params }) {
+  const { jobId } = await params;
+  const manager = getCodeBuddyCnBulkImportManager();
+
+  const job = await manager.getJobWithPreview(jobId);
+
+  if (!job) {
+    return NextResponse.json({
+      success: true,
+      ...buildLookupResponse(null, { stale: true }),
+    });
+  }
+
+  return NextResponse.json({
+    success: true,
+    ...buildLookupResponse(job),
+  });
+}

package/src/app/api/oauth/codebuddy-cn/bulk-import/latest/route.js

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+import {
+  getCodeBuddyCnBulkImportManager,
+  buildLookupResponse,
+} from "@/lib/oauth/services/codebuddyCnBulkImportManager";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request) {
+  const manager = getCodeBuddyCnBulkImportManager();
+  const searchParams = new URL(request.url).searchParams;
+  const scope = searchParams.get("scope");
+  const includeRecentTerminal = scope === "recent" || scope === "recoverable" || scope === "all";
+  const job = await manager.getLatestJobWithPreview({ includeRecentTerminal });
+
+  if (!job) {
+    return NextResponse.json({
+      success: true,
+      ...buildLookupResponse(null),
+    });
+  }
+
+  return NextResponse.json({
+    success: true,
+    ...buildLookupResponse(job),
+  });
+}

package/src/app/api/oauth/codebuddy-cn/bulk-import/route.js

@@ -0,0 +1,61 @@
+import { NextResponse } from "next/server";
+import {
+  getCodeBuddyCnBulkImportManager,
+  CODEBUDDY_CN_MAX_COUNT,
+  SUPPORTED_REGIONS,
+  DEFAULT_REGION,
+} from "@/lib/oauth/services/codebuddyCnBulkImportManager";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const count = body?.count;
+    const region = body?.region || DEFAULT_REGION;
+
+    // Validate count
+    const countNum = Number.parseInt(count, 10);
+    if (!Number.isFinite(countNum) || countNum < 1) {
+      return NextResponse.json(
+        { error: "count must be a positive integer (>= 1)" },
+        { status: 400 }
+      );
+    }
+    if (countNum > CODEBUDDY_CN_MAX_COUNT) {
+      return NextResponse.json(
+        { error: `count exceeds maximum of ${CODEBUDDY_CN_MAX_COUNT}` },
+        { status: 400 }
+      );
+    }
+
+    // Validate region
+    if (!SUPPORTED_REGIONS.has(region)) {
+      return NextResponse.json(
+        { error: `region must be one of: ${[...SUPPORTED_REGIONS].join(", ")}` },
+        { status: 400 }
+      );
+    }
+
+    const manager = getCodeBuddyCnBulkImportManager();
+    const job = await manager.startJob({
+      count: countNum,
+      concurrency: body?.concurrency,
+      engine: body?.engine,
+      proxyPoolMode: body?.proxyPoolMode,
+      proxyPoolId: body?.proxyPoolId,
+      region,
+    });
+
+    return NextResponse.json({
+      success: true,
+      job,
+    });
+  } catch (error) {
+    const status = error?.error ? 400 : 500;
+    return NextResponse.json(
+      { error: error?.error || error?.message || "Failed to start CodeBuddy CN bulk import" },
+      { status }
+    );
+  }
+}

package/src/app/api/oauth/codebuddy-cn/bulk-token/route.js

@@ -0,0 +1,119 @@
+import { NextResponse } from "next/server";
+import { createProviderConnection } from "@/models";
+
+export const dynamic = "force-dynamic";
+
+const CODEBUDDY_CN_PROVIDER_ID = "codebuddy-cn";
+const CODEBUDDY_CN_DOMAIN = "www.codebuddy.cn";
+
+async function fetchAccountInfo(accessToken, domain) {
+  try {
+    const response = await fetch(`https://${domain}/v2/plugin/accounts`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json",
+        "X-Domain": domain,
+      },
+    });
+
+    if (!response.ok) return { uid: null, email: null, nickname: null };
+
+    const body = await response.json();
+    const accounts = body?.data?.accounts || [];
+    const account = accounts.find((a) => a.lastLogin) || accounts[0] || {};
+    return {
+      uid: account.uid || null,
+      email: account.email || account.nickname || null,
+      nickname: account.nickname || null,
+      enterpriseId: account.enterpriseId || null,
+    };
+  } catch {
+    // CN /v2/plugin/accounts shape may differ — degrade gracefully
+    return { uid: null, email: null, nickname: null };
+  }
+}
+
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const rawTokens = body?.tokens;
+
+    if (!rawTokens || (typeof rawTokens !== "string" && !Array.isArray(rawTokens))) {
+      return NextResponse.json(
+        { error: "Provide tokens as a string (one per line) or array" },
+        { status: 400 }
+      );
+    }
+
+    const tokenList = Array.isArray(rawTokens)
+      ? rawTokens.map((t) => String(t || "").trim()).filter(Boolean)
+      : String(rawTokens)
+          .split(/[\r\n]+/)
+          .map((t) => t.trim())
+          .filter(Boolean);
+
+    if (tokenList.length === 0) {
+      return NextResponse.json(
+        { error: "At least one token is required" },
+        { status: 400 }
+      );
+    }
+
+    const results = [];
+
+    for (const token of tokenList) {
+      try {
+        const info = await fetchAccountInfo(token, CODEBUDDY_CN_DOMAIN);
+        const email = info.email || `token-${token.substring(0, 8)}...`;
+
+        const providerSpecificData = {
+          domain: CODEBUDDY_CN_DOMAIN,
+          loginEmail: email,
+          automation: "bulk-token-import",
+        };
+
+        if (info.uid) providerSpecificData.uid = info.uid;
+        if (info.enterpriseId) providerSpecificData.enterpriseId = info.enterpriseId;
+
+        const connection = await createProviderConnection({
+          provider: CODEBUDDY_CN_PROVIDER_ID,
+          authType: "oauth",
+          accessToken: token,
+          email,
+          providerSpecificData,
+          testStatus: info.uid ? "active" : "unknown",
+        });
+
+        results.push({
+          email,
+          status: "success",
+          connectionId: connection.id,
+          uid: info.uid,
+        });
+      } catch (error) {
+        results.push({
+          token: token.substring(0, 12) + "...",
+          status: "failed",
+          error: error.message || "Unknown error",
+        });
+      }
+    }
+
+    const imported = results.filter((r) => r.status === "success").length;
+    const failed = results.filter((r) => r.status === "failed").length;
+
+    return NextResponse.json({
+      success: true,
+      imported,
+      failed,
+      total: tokenList.length,
+      results,
+    });
+  } catch (error) {
+    return NextResponse.json(
+      { error: error.message || "Failed to import CodeBuddy CN tokens" },
+      { status: 500 }
+    );
+  }
+}

package/src/app/api/oauth/codebuddy-cn/quota-cookie/route.js

@@ -0,0 +1,28 @@
+import { NextResponse } from "next/server";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * CodeBuddy CN quota-cookie probe — STUB.
+ *
+ * The global CodeBuddy (codebuddy.ai) quota-cookie route probes
+ * /billing/meter/get-user-resource with ProductCode "p_tcaca" and a set of
+ * TCACA_code_* package codes. The CN edition (www.codebuddy.cn / copilot.tencent.com)
+ * uses different Tencent product/package codes that are not yet documented.
+ *
+ * This stub returns a "not supported" response so the UI can gracefully hide
+ * or disable the quota-cookie feature for CN connections until the codes are
+ * identified.
+ *
+ * TODO: Populate with CN product codes after identifying the Tencent CN billing
+ * endpoint and package codes (likely different ProductCode + PackageCodes).
+ */
+export async function POST() {
+  return NextResponse.json(
+    {
+      supported: false,
+      error: "CodeBuddy CN quota tracking is not yet supported. The Tencent CN product/package codes need to be identified before quota probing can work.",
+    },
+    { status: 501 }
+  );
+}

package/src/app/api/settings/route.js

@@ -14,8 +14,9 @@ const SETTINGS_RESPONSE_HEADERS = {
 export async function GET() {
   try {
     const settings = await getSettings();
-    const { password, oidcClientSecret, ...safeSettings } = settings;
+    const { password, oidcClientSecret, fiveSimApiKey, ...safeSettings } = settings;
     safeSettings.oidcConfigured = !!(safeSettings.oidcIssuerUrl && safeSettings.oidcClientId && oidcClientSecret);
+    safeSettings.fiveSimApiKeyConfigured = !!fiveSimApiKey;
     
     const enableRequestLogs = process.env.ENABLE_REQUEST_LOGS === "true";
     const enableTranslator = process.env.ENABLE_TRANSLATOR === "true";
@@ -70,6 +71,13 @@ export async function PATCH(request) {
       }
     }
 
+    // Empty fiveSimApiKey means "keep existing" (same pattern as oidcClientSecret)
+    if (Object.prototype.hasOwnProperty.call(body, "fiveSimApiKey")) {
+      if (!body.fiveSimApiKey || !String(body.fiveSimApiKey).trim()) {
+        delete body.fiveSimApiKey;
+      }
+    }
+
     const settings = await updateSettings(body);
 
     // Apply outbound proxy settings immediately (no restart required)
@@ -90,8 +98,9 @@ export async function PATCH(request) {
       resetComboRotation();
     }
 
-    const { password, oidcClientSecret, ...safeSettings } = settings;
+    const { password, oidcClientSecret, fiveSimApiKey, ...safeSettings } = settings;
     safeSettings.oidcConfigured = !!(safeSettings.oidcIssuerUrl && safeSettings.oidcClientId && oidcClientSecret);
+    safeSettings.fiveSimApiKeyConfigured = !!fiveSimApiKey;
     return NextResponse.json(safeSettings, { headers: SETTINGS_RESPONSE_HEADERS });
   } catch (error) {
     console.log("Error updating settings:", error);

package/src/lib/db/repos/settingsRepo.js

@@ -39,6 +39,8 @@ const DEFAULT_SETTINGS = {
   ponytailEnabled: false,
   ponytailLevel: "full",
   contextInjectionEnabled: false,
+  // 5sim.net API key for CodeBuddy CN phone bulk registration (never expose raw in GET)
+  fiveSimApiKey: "",
 };
 
 async function readRaw() {

package/src/lib/oauth/services/bulkImportBrowserEngine.js

@@ -89,7 +89,7 @@ function wrapBrowserWithStealth(browser) {
   return browser;
 }
 
-async function launchChromium({ proxyUrl } = {}) {
+async function launchChromium({ proxyUrl, headless = true, windowSize = null } = {}) {
   let chromium = null;
   let importErr = null;
   try {
@@ -128,8 +128,10 @@ async function launchChromium({ proxyUrl } = {}) {
     throw friendly;
   }
 
+  const width = windowSize?.width || (headless ? 1920 : 900);
+  const height = windowSize?.height || (headless ? 1080 : 700);
   const options = {
-    headless: true,
+    headless: headless !== false,
     args: [
       "--disable-blink-features=AutomationControlled",
       "--disable-features=IsolateOrigins,site-per-process,AutomationControlled",
@@ -144,17 +146,21 @@ async function launchChromium({ proxyUrl } = {}) {
       "--disable-ipc-flooding-protection",
       "--password-store=basic",
       "--use-mock-keychain",
-      "--window-size=1920,1080",
+      `--window-size=${width},${height}`,
+      ...(headless ? [] : ["--window-position=80,80"]),
     ],
     ignoreDefaultArgs: ["--enable-automation"],
   };
-  if (proxyUrl) options.proxy = { server: proxyUrl };
+  if (proxyUrl) {
+    const { parsePlaywrightProxy } = await import("./proxyUtils.js");
+    options.proxy = parsePlaywrightProxy(proxyUrl) || { server: proxyUrl };
+  }
 
   const browser = await chromium.launch(options);
   return wrapBrowserWithStealth(browser);
 }
 
-async function launchCamoufox({ proxyUrl } = {}) {
+async function launchCamoufox({ proxyUrl, headless = true, windowSize = null } = {}) {
   const runtime = loadRuntimeHelper("camoufoxRuntime");
   if (!runtime?.ensureCamoufoxRuntime) {
     const err = new Error(
@@ -193,21 +199,42 @@ async function launchCamoufox({ proxyUrl } = {}) {
     }
   }
 
-  const camoufoxOptions = await camoufox.launchOptions({ headless: true });
-  const launchOptions = { ...camoufoxOptions };
-  if (proxyUrl) launchOptions.proxy = { server: proxyUrl };
+  // Proxy MUST be on launchOptions for Camoufox/Firefox reliability.
+  // Context-only proxy is flaky (blank pages / half-sessions / 401 on console APIs).
+  const { parsePlaywrightProxy } = await import("./proxyUtils.js");
+  const parsedProxy = proxyUrl ? (parsePlaywrightProxy(proxyUrl) || { server: proxyUrl }) : null;
+  const useHeadless = headless !== false;
+  const camoufoxOptions = await camoufox.launchOptions({
+    headless: useHeadless,
+    ...(parsedProxy ? { proxy: parsedProxy, geoip: true } : {}),
+  });
+  const launchOptions = { ...camoufoxOptions, headless: useHeadless };
+  if (parsedProxy) {
+    launchOptions.proxy = parsedProxy;
+  }
+  // Small visible window for headed CN runs (server desktop)
+  if (!useHeadless) {
+    const width = windowSize?.width || 900;
+    const height = windowSize?.height || 700;
+    launchOptions.args = [...(launchOptions.args || []), `--width=${width}`, `--height=${height}`];
+  }
 
   return firefox.launch(launchOptions);
 }
 
-export async function launchBulkImportBrowser({ engine = DEFAULT_BULK_IMPORT_ENGINE, proxyUrl } = {}) {
+export async function launchBulkImportBrowser({
+  engine = DEFAULT_BULK_IMPORT_ENGINE,
+  proxyUrl,
+  headless = true,
+  windowSize = null,
+} = {}) {
   const normalized = normalizeBulkImportEngine(engine);
   if (normalized === "camoufox") {
-    return launchCamoufox({ proxyUrl });
+    return launchCamoufox({ proxyUrl, headless, windowSize });
   }
-  return launchChromium({ proxyUrl });
+  return launchChromium({ proxyUrl, headless, windowSize });
 }
 
-export function makeBrowserLauncher({ engine, proxyUrl } = {}) {
-  return () => launchBulkImportBrowser({ engine, proxyUrl });
+export function makeBrowserLauncher({ engine, proxyUrl, headless = true, windowSize = null } = {}) {
+  return () => launchBulkImportBrowser({ engine, proxyUrl, headless, windowSize });
 }