@crewhaus/tool-navigate 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@crewhaus/tool-navigate",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Navigate tool — drives driver.goto(url) for the BROW agent (Section 25 BROW)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/computer-use-driver": "0.0.0",
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/tool-builder": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "zod": "^3.23.8"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-navigate"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-navigate#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import type { Driver } from "@crewhaus/computer-use-driver";
+import { NavigateError, createNavigateTool } from "./index.js";
+
+type GotoRecord = { calls: string[] };
+
+function stubDriver(record: GotoRecord, opts: { gotoErr?: Error } = {}): Driver {
+  return {
+    backend: "chromium",
+    async connect() {},
+    async goto(url: string) {
+      record.calls.push(url);
+      if (opts.gotoErr) throw opts.gotoErr;
+    },
+    async screenshot() {
+      return new Uint8Array(0);
+    },
+    async click() {},
+    async type() {},
+    async key() {},
+    async scroll() {},
+    async getViewport() {
+      return { width: 800, height: 600, devicePixelRatio: 1 };
+    },
+    async disconnect() {},
+  };
+}
+
+describe("createNavigateTool", () => {
+  test("happy path: forwards url to driver.goto and returns a text confirmation", async () => {
+    const record: GotoRecord = { calls: [] };
+    const tool = createNavigateTool({ driver: stubDriver(record) });
+
+    const result = await tool.execute({ url: "https://example.com/" }, {});
+    expect(record.calls).toEqual(["https://example.com/"]);
+    expect(Array.isArray(result)).toBe(true);
+    if (!Array.isArray(result)) throw new Error("expected ToolResultContent array");
+    expect(result).toHaveLength(1);
+    const block = result[0];
+    if (block?.type !== "text") throw new Error("expected text block");
+    expect(block.text).toBe("navigated to https://example.com/");
+  });
+
+  test("schema rejects non-URL strings (and missing url)", () => {
+    const record: GotoRecord = { calls: [] };
+    const tool = createNavigateTool({ driver: stubDriver(record) });
+    expect(() => tool.inputSchema.parse({ url: "not-a-url" })).toThrow();
+    expect(() => tool.inputSchema.parse({})).toThrow();
+  });
+
+  test("driver.goto failure surfaces as NavigateError with the URL in the message", async () => {
+    const record: GotoRecord = { calls: [] };
+    const tool = createNavigateTool({
+      driver: stubDriver(record, { gotoErr: new Error("net::ERR_NAME_NOT_RESOLVED") }),
+    });
+    try {
+      await tool.execute({ url: "https://does-not-exist.invalid/" }, {});
+      throw new Error("expected NavigateError to be thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(NavigateError);
+      expect((err as Error).message).toContain("https://does-not-exist.invalid/");
+      expect((err as Error).message).toContain("net::ERR_NAME_NOT_RESOLVED");
+    }
+  });
+
+  test("flag profile: default-allowed, external scope, classifier off", () => {
+    const record: GotoRecord = { calls: [] };
+    const tool = createNavigateTool({ driver: stubDriver(record) });
+    // destructive: false → permission-engine allows in default mode.
+    // Navigation is the agent's bootstrap; gating it behind alwaysAllow
+    // would silently break every browser spec without explicit rules.
+    expect(tool.destructive).toBe(false);
+    expect(tool.readOnly).toBe(false);
+    expect(tool.classifyOutput).toBe(false);
+    expect(tool.scope).toBe("external");
+    expect(tool.name).toBe("Navigate");
+  });
+});

package/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Catalog R4 `tool-navigate` — Section 25 BROW.
+ *
+ * `Navigate(url)` tool. Drives `driver.goto(url)` so the browser agent
+ * can bootstrap to a starting page. Returns a short text confirmation
+ * the model can read back; surfaces playwright errors verbatim (e.g.
+ * unreachable host, navigation timeout) so the model can recover or
+ * report the failure.
+ *
+ * Flag profile: `destructive: false` (default-allowed). Navigation is
+ * the agent's only bootstrap path — gating it behind an `alwaysAllow`
+ * rule would silently break every spec that doesn't define one. The
+ * §3 permission-engine still applies the user's explicit `alwaysDeny`
+ * rules; Click/Type/Key/Scroll stay destructive-by-default in
+ * `tool-mouse-keyboard`.
+ *
+ * Scope is `"external"` because the URL request crosses a network
+ * boundary; the §3 egress-classifier can hook in here later. Output
+ * classification is off — the response is a deterministic short string,
+ * not model-generated content.
+ */
+import type { Driver } from "@crewhaus/computer-use-driver";
+import { CrewhausError } from "@crewhaus/errors";
+import { buildTool } from "@crewhaus/tool-builder";
+import type { RegisteredTool, ToolResultContent } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+
+export class NavigateError extends CrewhausError {
+  override readonly name = "NavigateError";
+  constructor(message: string, cause?: unknown) {
+    super("tool", message, cause);
+  }
+}
+
+const navigateSchema = z
+  .object({
+    /** Absolute URL to navigate to (http/https). */
+    url: z.string().url(),
+  })
+  .strict();
+
+export type CreateNavigateToolOptions = {
+  readonly driver: Driver;
+};
+
+export function createNavigateTool(opts: CreateNavigateToolOptions): RegisteredTool {
+  return buildTool({
+    name: "Navigate",
+    description:
+      "Navigate the browser to a URL. Call this first to load a starting page (e.g. a search engine, documentation site, or known landing page) before using Screenshot/FindElement/Click/Type. Returns a short confirmation; pair with Screenshot to see what loaded.",
+    inputSchema: navigateSchema,
+    readOnly: false,
+    destructive: false,
+    concurrencySafe: false,
+    classifyOutput: false,
+    scope: "external",
+    execute: async (input): Promise<ToolResultContent> => {
+      try {
+        await opts.driver.goto(input.url);
+      } catch (err) {
+        throw new NavigateError(
+          `navigation to ${input.url} failed: ${(err as Error).message}`,
+          err,
+        );
+      }
+      return [{ type: "text", text: `navigated to ${input.url}` }];
+    },
+  });
+}