From c3e2e2aaa95cce0709279e823d420e700a5fc834 Mon Sep 17 00:00:00 2001
From: g97iulio1609 <giulio97.leone@gmail.com>
Date: Fri, 13 Feb 2026 22:37:31 +0100
Subject: [PATCH] feat(#433): add help command to list available API actions

---
 src/actions.ts |  1 +
 src/browser.ts | 12 ++++++++++--
 src/daemon.ts  | 12 ++++++++++++
 src/types.ts   |  7 ++++++-
 4 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/src/actions.ts b/src/actions.ts
index 22314e06..d2e72eb1 100644
--- a/src/actions.ts
+++ b/src/actions.ts
@@ -26,6 +26,7 @@ import type {
   FocusCommand,
   DragCommand,
   FrameCommand,
+
   GetByRoleCommand,
   GetByTextCommand,
   GetByLabelCommand,
diff --git a/src/browser.ts b/src/browser.ts
index d8c7298d..91cc1044 100644
--- a/src/browser.ts
+++ b/src/browser.ts
@@ -1117,7 +1117,7 @@ export class BrowserManager {
     }
 
     if (cdpEndpoint) {
-      await this.connectViaCDP(cdpEndpoint);
+      await this.connectViaCDP(cdpEndpoint, options.headers);
       return;
     }
 
@@ -1310,7 +1310,7 @@ export class BrowserManager {
    * Connect to a running browser via CDP (Chrome DevTools Protocol)
    * @param cdpEndpoint Either a port number (as string) or a full WebSocket URL (ws:// or wss://)
    */
-  private async connectViaCDP(cdpEndpoint: string | undefined): Promise<void> {
+  private async connectViaCDP(cdpEndpoint: string | undefined, headers?: Record<string, string>): Promise<void> {
     if (!cdpEndpoint) {
       throw new Error('CDP endpoint is required for CDP connection');
     }
@@ -1374,6 +1374,14 @@ export class BrowserManager {
       }
 
       this.activePageIndex = 0;
+
+      // Apply custom headers post-connection (Playwright's connectOverCDP doesn't support
+      // connection-time headers, so we set them on the context after connecting)
+      if (headers && Object.keys(headers).length > 0) {
+        for (const context of contexts) {
+          await context.setExtraHTTPHeaders(headers);
+        }
+      }
     } catch (error) {
       // Clean up browser connection if validation or setup failed
       await browser.close().catch(() => {});
diff --git a/src/daemon.ts b/src/daemon.ts
index 36d5acc4..7290da45 100644
--- a/src/daemon.ts
+++ b/src/daemon.ts
@@ -417,6 +417,17 @@ export async function startDaemon(options?: {
 
               const ignoreHTTPSErrors = process.env.AGENT_BROWSER_IGNORE_HTTPS_ERRORS === '1';
               const allowFileAccess = process.env.AGENT_BROWSER_ALLOW_FILE_ACCESS === '1';
+
+              // Parse custom headers from env (JSON string)
+              let headers: Record<string, string> | undefined;
+              if (process.env.AGENT_BROWSER_HEADERS) {
+                try {
+                  headers = JSON.parse(process.env.AGENT_BROWSER_HEADERS);
+                } catch {
+                  /* ignore invalid JSON */
+                }
+              }
+
               await manager.launch({
                 id: 'auto',
                 action: 'launch' as const,
@@ -430,6 +441,7 @@ export async function startDaemon(options?: {
                 proxy,
                 ignoreHTTPSErrors: ignoreHTTPSErrors,
                 allowFileAccess: allowFileAccess,
+                headers,
                 autoStateFilePath: getSessionAutoStatePath(),
               });
             }
diff --git a/src/types.ts b/src/types.ts
index 06a489df..66632067 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -540,6 +540,10 @@ export interface DeviceListCommand extends BaseCommand {
   action: 'device_list';
 }
 
+export interface HelpCommand extends BaseCommand {
+  action: 'help';
+}
+
 // Video recording (Playwright native - requires launch-time setup)
 export interface VideoStartCommand extends BaseCommand {
   action: 'video_start';
@@ -984,7 +988,8 @@ export type Command =
   | InputKeyboardCommand
   | InputTouchCommand
   | SwipeCommand
-  | DeviceListCommand;
+  | DeviceListCommand
+  | HelpCommand;
 
 // Response types
 export interface SuccessResponse<T = unknown> {