Merge pull request #370 from olasunkanmi-SE/feature/browser-automation-tool

feat: add Browser Automation Tool (#11)

Author: olasunkanmi-SE

package-lock.json

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { Logger, LogLevel } from "../../../infrastructure/logger/logger";
+import { BrowserTool } from "../../../tools/tools";
+import { BROWSER_ACTIONS } from "../../../tools/browser-actions";
+import { StructuredTool } from "@langchain/core/tools";
+
+const browserSchema = z.object({
+  action: z.enum(BROWSER_ACTIONS).describe("The browser action to perform."),
+  url: z.string().optional().describe("URL for navigate/tab_new actions."),
+  ref: z
+    .string()
+    .optional()
+    .describe(
+      "Element reference from a previous snapshot (for click, type, hover, select_option).",
+    ),
+  text: z.string().optional().describe("Text to type (for type action)."),
+  value: z
+    .string()
+    .optional()
+    .describe("Value to select (for select_option action)."),
+  expression: z
+    .string()
+    .optional()
+    .describe("JavaScript expression to evaluate in the page context."),
+  key: z
+    .string()
+    .optional()
+    .describe(
+      "Key to press (for press_key action, e.g. 'Enter', 'Tab', 'ArrowDown').",
+    ),
+  time: z
+    .number()
+    .optional()
+    .describe("Time to wait in ms (for wait action, default 2000)."),
+});
+
+type BrowserToolInput = z.infer<typeof browserSchema>;
+
+// StructuredTool<any> is intentional — StructuredTool<typeof browserSchema>
+// triggers TS2589 ("Type instantiation is excessively deep"). All tools
+// in this codebase use <any> for the same reason.
+export class LangChainBrowserTool extends StructuredTool<any> {
+  private readonly logger: Logger;
+  constructor(private readonly toolInstance: BrowserTool) {
+    super();
+    this.logger = Logger.initialize("LangChainBrowserTool", {
+      minLevel: LogLevel.DEBUG,
+      enableConsole: true,
+      enableFile: true,
+      enableTelemetry: true,
+    });
+  }
+
+  name = "browser";
+  description =
+    "Control a headless browser via Playwright. Navigate pages, click elements, type text, take screenshots, read page snapshots (accessibility tree), and execute JavaScript. " +
+    "Workflow: 1) navigate to a URL, 2) snapshot to see the page structure and element refs, 3) interact using refs from the snapshot.";
+
+  schema = browserSchema;
+
+  async _call(input: BrowserToolInput): Promise<string> {
+    this.logger.info(
+      `Executing tool: ${this.name} with action: ${input.action}`,
+    );
+    try {
+      const result = await this.toolInstance.execute(input);
+      return result;
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.error(`Error in tool ${this.name}: ${message}`, { input });
+      return `Error: ${message}`;
+    }
+  }
+}

src/agents/langgraph/tools/browser.ts

@@ -16,6 +16,7 @@ import {
   WebPreviewTool,
   SearchTool,
   DeepTerminalTool,
+  BrowserTool,
   TodoTool,
   MemoryTool,
   TestRunnerTool,
@@ -40,6 +41,7 @@ import { LangChainTodoTool } from "./todo";
 import { LangChainMemoryTool } from "./memory";
 import { LangChainTestRunnerTool } from "./test-runner";
 import { LangChainComposerTool } from "./composer";
+import { LangChainBrowserTool } from "./browser";
 import {
   DebugControlTool,
   DebugEvaluateTool,
@@ -146,6 +148,12 @@ class WebPreviewToolFactory implements IToolFactory {
   }
 }
 
+class BrowserToolFactory implements IToolFactory {
+  createTool(): StructuredTool<any> {
+    return new LangChainBrowserTool(new BrowserTool());
+  }
+}
+
 class TodoToolFactory implements IToolFactory {
   createTool(): StructuredTool<any> {
     return new LangChainTodoTool(new TodoTool());
@@ -266,6 +274,7 @@ const TOOL_ROLE_MAPPING: Record<string, string[]> = {
     "manage_tasks",
     "manage_core_memory",
     "compose_files",
+    "browser",
   ],
   "doc-writer": [
     "search",
@@ -285,6 +294,7 @@ const TOOL_ROLE_MAPPING: Record<string, string[]> = {
     "search_vector_db",
     "standup_intelligence",
     "team_graph",
+    "browser",
   ],
   "file-organizer": [
     "file",
@@ -328,6 +338,7 @@ const TOOL_ROLE_MAPPING: Record<string, string[]> = {
     "manage_tasks",
     "standup_intelligence",
     "team_graph",
+    "browser",
   ],
   reviewer: [
     "analyze",
@@ -366,6 +377,7 @@ const TOOL_ROLE_MAPPING: Record<string, string[]> = {
     "search_vector_db",
     "manage_terminal",
     "run_tests",
+    "browser",
   ],
   debugger: [
     "debug_get_state",
@@ -383,6 +395,7 @@ const TOOL_ROLE_MAPPING: Record<string, string[]> = {
     "edit_file",
     "ripgrep_search",
     "get_diagnostics",
+    "browser",
   ],
   "architecture-expert": [
     "get_architecture_knowledge",
@@ -424,6 +437,7 @@ export class ToolProvider {
       // new ListFilesToolFactory(), // Provided by DeepAgent backend
       // new EditFileToolFactory(), // Provided by DeepAgent backend
       new WebPreviewToolFactory(),
+      new BrowserToolFactory(),
       new SearchToolFactory(this.contextRetriever),
       new TodoToolFactory(),
       new MemoryToolFactory(),