From dd0c89d8aace35620a5ca28feb70088e3286c787 Mon Sep 17 00:00:00 2001
From: Harivansh Rathi <rathiharivansh@gmail.com>
Date: Wed, 11 Mar 2026 02:08:27 -0400
Subject: [PATCH] ubuntu

---
 .../coding-agent/src/core/tools/browser.ts    | 28 +++++++++++++++++++
 .../coding-agent/test/browser-tool.test.ts    | 27 ++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/packages/coding-agent/src/core/tools/browser.ts b/packages/coding-agent/src/core/tools/browser.ts
index 5eb53bf..838c2f2 100644
--- a/packages/coding-agent/src/core/tools/browser.ts
+++ b/packages/coding-agent/src/core/tools/browser.ts
@@ -187,6 +187,7 @@ export interface BrowserToolOptions {
   profileDir?: string;
   stateDir?: string;
   agentDir?: string;
+  headed?: boolean;
 }
 
 interface BrowserCommandContext {
@@ -262,6 +263,30 @@ function ensureBrowserDirs(profilePath: string, stateDir: string): void {
   mkdirSync(stateDir, { recursive: true });
 }
 
+function isTruthyEnv(value: string | undefined): boolean {
+  if (!value) {
+    return false;
+  }
+
+  switch (value.trim().toLowerCase()) {
+    case "":
+    case "0":
+    case "false":
+    case "no":
+    case "off":
+      return false;
+    default:
+      return true;
+  }
+}
+
+function shouldLaunchHeaded(options?: BrowserToolOptions): boolean {
+  if (options?.headed !== undefined) {
+    return options.headed;
+  }
+  return isTruthyEnv(process.env.COMPANION_AGENT_BROWSER_HEADED);
+}
+
 function createBrowserCommandContext(
   profilePath: string,
   stateDir: string,
@@ -328,6 +353,9 @@ function buildBrowserCommand(
   const profilePath = getBrowserProfilePath(cwd, options);
   const stateDir = getBrowserStateDir(cwd, options);
   const baseArgs = ["--profile", profilePath];
+  if (shouldLaunchHeaded(options)) {
+    baseArgs.push("--headed");
+  }
 
   switch (input.action) {
     case "open": {
diff --git a/packages/coding-agent/test/browser-tool.test.ts b/packages/coding-agent/test/browser-tool.test.ts
index 19ded39..c8b9005 100644
--- a/packages/coding-agent/test/browser-tool.test.ts
+++ b/packages/coding-agent/test/browser-tool.test.ts
@@ -117,6 +117,33 @@ describe("browser tool", () => {
     expect(details?.profilePath).toBe(profileDir);
   });
 
+  it("can force agent-browser into headed mode for desktop sandboxes", async () => {
+    const cwd = createTempDir("coding-agent-browser-headed-");
+    const profileDir = join(cwd, "profile");
+    const stateDir = join(cwd, "states");
+    const { calls, operations } = createMockBrowserOperations();
+
+    const browserTool = createBrowserTool(cwd, {
+      operations,
+      profileDir,
+      stateDir,
+      headed: true,
+    });
+
+    await browserTool.execute("browser-open-headed", {
+      action: "open",
+      url: "https://example.com",
+    });
+
+    expect(calls[0]?.args).toEqual([
+      "--profile",
+      profileDir,
+      "--headed",
+      "open",
+      "https://example.com",
+    ]);
+  });
+
   it("uses interactive snapshots by default and returns snapshot text", async () => {
     const cwd = createTempDir("coding-agent-browser-snapshot-");
     const profileDir = join(cwd, "profile");