From 8d7a067c8d82a592bfb3dcacf05305c39550cbc6 Mon Sep 17 00:00:00 2001 From: astarring Date: Wed, 9 Sep 2026 02:35:42 +0800 Subject: 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 --- src/cdp/commands.ts | 4 +++ src/domains/headers.ts | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++ src/prompt.ts | 1 + src/registry.ts | 3 ++ 4 files changed, 97 insertions(+) create mode 100644 src/domains/headers.ts (limited to 'src') 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> { + 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> { + 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 = [ dragAndDropTool, httpGetTool, networkRequestsTool, + setHeadersTool, + clearHeadersTool, consoleTool, snapshotTool, executeJsTool, -- cgit v1.2.3