feat(edge-worker): optional browser-use system prompt addendum (CYHOST-991) (#1257)

* feat(edge-worker): optional browser-use system prompt addendum (CYHOST-991)

When CYRUS_BROWSER_USE_ENABLED is set to a truthy value, append a
<browser_use> section to the system prompt telling the agent it has access
to the `agent-browser` CLI and a local Chromium for screenshots and browser
automation. Off by default; cyrus-hosted sets it on cloud-runtime droplets.

* feat(edge-worker): drop chromium mention from browser-use addendum (CYHOST-991)

Per payton's feedback on PR #1257.

* docs: remove Common Commands section from CLAUDE.md

* Revert "feat(edge-worker): drop chromium mention from browser-use addendum (CYHOST-991)"

This reverts commit 4cf3b0a.

* feat(edge-worker): remove common commands section from browser-use addendum (CYHOST-991)

Per Connor's feedback on PR #1257.

* Revert "feat(edge-worker): remove common commands section from browser-use addendum (CYHOST-991)"

This reverts commit fffebb3.

* Revert "docs: remove Common Commands section from CLAUDE.md"

This reverts commit dea094f.

* feat(edge-worker): remove common commands section from browser-use addendum (CYHOST-991)

---------

Co-authored-by: cyrusagent <237105008+cyrusagent[bot]@users.noreply.github.com>
Co-authored-by: Connor Turland <1409121+Connoropolous@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+- Optional browser-use system prompt addendum that tells the agent it has access to the `agent-browser` CLI and a local Chromium for screenshots and browser automation. Enabled by setting the `CYRUS_BROWSER_USE_ENABLED` environment variable to `true` (off by default for self-host). ([CYHOST-991](https://linear.app/ceedar/issue/CYHOST-991))
+
 ## [0.2.59] - 2026-05-28
 
 ### Added

packages/edge-worker/src/RunnerConfigBuilder.ts

@@ -20,6 +20,7 @@ import type {
 } from "cyrus-core";
 import { buildIntentToAddHook } from "./hooks/IntentToAddHook.js";
 import { buildPrMarkerHook } from "./hooks/PrMarkerHook.js";
+import { appendBrowserUseAddendum } from "./prompts/browserUsePromptAddendum.js";
 import { appendFailureModeAddendum } from "./prompts/failureModePromptAddendum.js";
 
 /**
@@ -241,7 +242,9 @@ export class RunnerConfigBuilder {
 			workspaceName: input.workspaceName,
 			cyrusHome: input.cyrusHome,
 			autoMemoryDirectory,
-			appendSystemPrompt: appendFailureModeAddendum(input.systemPrompt),
+			appendSystemPrompt: appendBrowserUseAddendum(
+				appendFailureModeAddendum(input.systemPrompt),
+			),
 			...(mcpConfig ? { mcpConfig } : {}),
 			...(mcpConfigPath ? { mcpConfigPath } : {}),
 			...(input.resumeSessionId
@@ -363,7 +366,9 @@ export class RunnerConfigBuilder {
 			cyrusHome: input.cyrusHome,
 			mcpConfigPath,
 			mcpConfig,
-			appendSystemPrompt: appendFailureModeAddendum(input.systemPrompt),
+			appendSystemPrompt: appendBrowserUseAddendum(
+				appendFailureModeAddendum(input.systemPrompt),
+			),
 			// Priority order: label override > repository config > global default
 			model: finalModel,
 			fallbackModel:

packages/edge-worker/src/prompts/browserUsePromptAddendum.ts

@@ -0,0 +1,57 @@
+/**
+ * Optional system-prompt addendum that tells the agent it has access to the
+ * `agent-browser` CLI (Playwright-backed) and a local Chromium for taking
+ * screenshots and driving real browsers.
+ *
+ * Only injected when the environment variable `CYRUS_BROWSER_USE_ENABLED` is
+ * set to a truthy value. cyrus-hosted sets this on cloud-runtime droplets
+ * (where chromium + agent-browser are pre-installed) and leaves it unset for
+ * self-host runtimes (where the binaries may not be available).
+ */
+export const BROWSER_USE_PROMPT_ADDENDUM = `
+<browser_use>
+You have access to the \`agent-browser\` CLI (a Playwright-backed browser
+automation tool) and a local Chromium install. Use it to verify frontend
+changes, capture screenshots for the user, and drive real browser flows.
+
+**When to use it:**
+- After making UI or frontend changes, open the running dev server in a
+  browser and capture a screenshot to confirm the change renders as
+  expected. Attach the screenshot when summarizing your work.
+- When the user asks "what does this look like?" or requests visual proof.
+- When reproducing a bug that involves browser behavior (clicks, forms,
+  navigation, rendering).
+
+**Tips:**
+- Add \`sleep 0.5\` between rapid commands — each invocation spawns its own
+  process and the browser needs a moment to settle.
+- Use \`snapshot -i\` to find a reliable \`@ref\` before clicking; visible
+  text alone can be ambiguous.
+- For screenshots you intend to attach to a PR or Linear comment, write
+  them to the workspace (e.g. \`./screenshot.png\`) so they're picked up by
+  the upload flow.
+</browser_use>
+`.trim();
+
+/**
+ * Append the browser-use addendum to a system prompt fragment, but only when
+ * the `CYRUS_BROWSER_USE_ENABLED` env var is truthy. Returns the existing
+ * prompt unchanged otherwise.
+ */
+export function appendBrowserUseAddendum(
+	existing: string | undefined | null,
+): string {
+	const base = (existing ?? "").trimEnd();
+	if (!isBrowserUseEnabled()) {
+		return existing ?? "";
+	}
+	if (base.length === 0) return BROWSER_USE_PROMPT_ADDENDUM;
+	return `${base}\n\n${BROWSER_USE_PROMPT_ADDENDUM}`;
+}
+
+function isBrowserUseEnabled(): boolean {
+	const raw = process.env.CYRUS_BROWSER_USE_ENABLED;
+	if (!raw) return false;
+	const normalized = raw.trim().toLowerCase();
+	return normalized === "1" || normalized === "true" || normalized === "yes";
+}

packages/edge-worker/test/browserUsePromptAddendum.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+	appendBrowserUseAddendum,
+	BROWSER_USE_PROMPT_ADDENDUM,
+} from "../src/prompts/browserUsePromptAddendum.js";
+
+describe("browser-use prompt addendum", () => {
+	const original = process.env.CYRUS_BROWSER_USE_ENABLED;
+
+	beforeEach(() => {
+		delete process.env.CYRUS_BROWSER_USE_ENABLED;
+	});
+
+	afterEach(() => {
+		if (original === undefined) delete process.env.CYRUS_BROWSER_USE_ENABLED;
+		else process.env.CYRUS_BROWSER_USE_ENABLED = original;
+	});
+
+	it("includes the agent-browser CLI name and a screenshot hint", () => {
+		expect(BROWSER_USE_PROMPT_ADDENDUM).toContain("agent-browser");
+		expect(BROWSER_USE_PROMPT_ADDENDUM).toMatch(/screenshot/i);
+	});
+
+	it("returns the existing prompt unchanged when the env var is unset", () => {
+		expect(appendBrowserUseAddendum("You are Cyrus.")).toBe("You are Cyrus.");
+		expect(appendBrowserUseAddendum(undefined)).toBe("");
+		expect(appendBrowserUseAddendum(null)).toBe("");
+	});
+
+	it("returns the existing prompt unchanged when the env var is falsy", () => {
+		process.env.CYRUS_BROWSER_USE_ENABLED = "false";
+		expect(appendBrowserUseAddendum("You are Cyrus.")).toBe("You are Cyrus.");
+		process.env.CYRUS_BROWSER_USE_ENABLED = "0";
+		expect(appendBrowserUseAddendum("You are Cyrus.")).toBe("You are Cyrus.");
+	});
+
+	it("appends the addendum with a blank-line separator when enabled", () => {
+		process.env.CYRUS_BROWSER_USE_ENABLED = "true";
+		const result = appendBrowserUseAddendum("You are Cyrus.");
+		expect(result.startsWith("You are Cyrus.\n\n")).toBe(true);
+		expect(result.endsWith(BROWSER_USE_PROMPT_ADDENDUM)).toBe(true);
+	});
+
+	it("returns the addendum verbatim when enabled with no base prompt", () => {
+		process.env.CYRUS_BROWSER_USE_ENABLED = "1";
+		expect(appendBrowserUseAddendum(undefined)).toBe(
+			BROWSER_USE_PROMPT_ADDENDUM,
+		);
+		expect(appendBrowserUseAddendum("")).toBe(BROWSER_USE_PROMPT_ADDENDUM);
+	});
+
+	it("accepts common truthy spellings", () => {
+		for (const value of ["true", "1", "yes", "TRUE", " Yes "]) {
+			process.env.CYRUS_BROWSER_USE_ENABLED = value;
+			expect(appendBrowserUseAddendum("base")).toContain(
+				BROWSER_USE_PROMPT_ADDENDUM,
+			);
+		}
+	});
+});