feat: add per-tab request headers (#30)

Expose explicit set and clear tools so environment-routed pages can be opened without leaking header values or carrying headers across unrelated browsing.

Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com

Co-authored-by: zouzhigang <zouzhigang@bytedance.com>

4 files changed, 97 insertions, 0 deletions

diff --git a/src/cdp/commands.ts b/src/cdp/commands.ts
index 580f8cf..08ddf41 100644
--- a/src/cdp/commands.ts
+++ b/src/cdp/commands.ts
@@ -228,6 +228,10 @@ export const COMMANDS = {
     Type.Object({ requestId: Type.String() }),
     Type.Object({ body: Type.String(), base64Encoded: Type.Optional(Type.Boolean()) }),
   ),
+  "Network.setExtraHTTPHeaders": cmd(
+    Type.Object({ headers: Type.Record(Type.String(), Type.String()) }),
+    Empty,
+  ),
   "Emulation.setDeviceMetricsOverride": cmd(Type.Object({}, { additionalProperties: true }), Empty),
   "Accessibility.getFullAXTree": cmd(
     Type.Object({ depth: Type.Optional(Type.Number()) }, { additionalProperties: true }),
diff --git a/src/domains/headers.ts b/src/domains/headers.ts
new file mode 100644
index 0000000..035c084
--- /dev/null
+++ b/src/domains/headers.ts
@@ -0,0 +1,89 @@
+import { Type } from "typebox";
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+
+const HeaderValue = Type.String({
+  maxLength: 8192,
+  pattern: "^[^\\r\\n]*$",
+});
+
+const SetHeadersArgs = Type.Object({
+  headers: Type.Record(Type.String(), HeaderValue, {
+    minProperties: 1,
+    maxProperties: 64,
+    description: "Extra HTTP request headers for the current owned tab. Names must be valid HTTP tokens.",
+  }),
+});
+
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+const currentOwnedTarget = (
+  client: BrowserClient,
+): Result<{ readonly targetId: string }, ToolErr> => {
+  const current = client.current();
+  if (current === undefined || current === null) {
+    return err({ kind: "invalid_state", message: "No tab attached." });
+  }
+  if (!client.owns(current.targetId)) {
+    return err({
+      kind: "invalid_state",
+      message: `Current tab ${current.targetId} is not owned by this harness session.`,
+    });
+  }
+  return ok({ targetId: current.targetId });
+};
+
+export const setHeadersTool = defineBrowserTool({
+  name: "browser_set_headers",
+  label: "Browser Set Headers",
+  description:
+    "Set extra HTTP request headers on the current owned tab. Headers persist for subsequent document, subresource, fetch, and XHR requests until cleared or the tab closes.",
+  promptSnippet: "Set extra request headers on the current owned tab",
+  promptGuidelines: [
+    "If no tab is attached yet, call browser_new_tab without a URL first.",
+    "Call before navigation when a site requires routing or environment headers.",
+    "Call browser_clear_headers before switching tabs or navigating this tab to another origin.",
+    "Header values are never echoed in tool output.",
+  ],
+  parameters: SetHeadersArgs,
+  concurrency: "serialized",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const target = currentOwnedTarget(client);
+    if (!target.success) return target;
+    const invalidName = Object.keys(args.headers).find((name) => !HEADER_NAME.test(name));
+    if (invalidName !== undefined) {
+      return err({ kind: "invalid_state", message: `Invalid HTTP header name: ${JSON.stringify(invalidName)}` });
+    }
+    const result = await cdpCall(client, "Network.setExtraHTTPHeaders", { headers: args.headers });
+    if (!result.success) return result;
+    const headerNames = Object.keys(args.headers).sort();
+    return ok({
+      text: `Set ${headerNames.length} extra HTTP header(s) on tab ${target.data.targetId}: ${headerNames.join(", ")}. Values are hidden. Clear them before switching tabs or navigating to another origin.`,
+      details: { targetId: target.data.targetId, headerNames, count: headerNames.length },
+    });
+  },
+});
+
+export const clearHeadersTool = defineBrowserTool({
+  name: "browser_clear_headers",
+  label: "Browser Clear Headers",
+  description: "Clear all extra HTTP request headers previously set on the current owned tab.",
+  promptSnippet: "Clear extra request headers from the current owned tab",
+  promptGuidelines: [
+    "Call after finishing an environment-specific workflow, before switching tabs, or before navigating to another origin.",
+  ],
+  parameters: Type.Object({}),
+  concurrency: "serialized",
+  async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const target = currentOwnedTarget(client);
+    if (!target.success) return target;
+    const result = await cdpCall(client, "Network.setExtraHTTPHeaders", { headers: {} });
+    if (!result.success) return result;
+    return ok({
+      text: `Cleared extra HTTP headers from tab ${target.data.targetId}.`,
+      details: { targetId: target.data.targetId },
+    });
+  },
+});
diff --git a/src/prompt.ts b/src/prompt.ts
index c336c0c..9a28abd 100644
--- a/src/prompt.ts
+++ b/src/prompt.ts
@@ -41,6 +41,7 @@ every edit and save. Coordinates go stale; guessed selectors miss.
 | Read an article's clean text | \`browser_read_page\` (reader mode; url or owned tab) |
 | Extract specific DOM values | \`browser_execute_js\` |
 | Hit a JSON/API endpoint | \`browser_http_get\` (raw GET, outside the browser) |
+| Set or clear request headers on the current tab | \`browser_set_headers\` · \`browser_clear_headers\` |
 | Click / fill / type / select / focus / press a key | \`browser_click\` · \`browser_fill\` · \`browser_type\` · \`browser_select_option\` · \`browser_focus\` · \`browser_press_key\` |
 | Upload a file · drag · resize viewport | \`browser_upload_file\` · \`browser_drag_and_drop\` · \`browser_viewport_resize\` |
 | Go to a URL / open many / manage tabs | \`browser_navigate\` · \`browser_new_tab\` · \`browser_open_urls\` · \`browser_list_tabs\` · \`browser_switch_tab\` · \`browser_go_back\`/\`go_forward\`/\`reload\` |
diff --git a/src/registry.ts b/src/registry.ts
index 69a1845..eaa60cd 100644
--- a/src/registry.ts
+++ b/src/registry.ts
@@ -16,6 +16,7 @@ import { uploadFileTool, downloadTool, printToPdfTool } from "./domains/files";
 import { viewportResizeTool } from "./domains/viewport";
 import { dragAndDropTool } from "./domains/drag";
 import { httpGetTool, networkRequestsTool } from "./domains/network";
+import { clearHeadersTool, setHeadersTool } from "./domains/headers";
 import { consoleTool } from "./domains/console";
 import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
@@ -58,6 +59,8 @@ export const ALL_TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   dragAndDropTool,
   httpGetTool,
   networkRequestsTool,
+  setHeadersTool,
+  clearHeadersTool,
   consoleTool,
   snapshotTool,
   executeJsTool,