An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
feat(settings): describe the guardrail policy, and write one override at a time
Shahriar7f7584a9eae7
diff --git a/lib/actions/protocol.ts b/lib/actions/protocol.tsindex c660b88..057a599 100644--- a/lib/actions/protocol.ts+++ b/lib/actions/protocol.ts@@ -3,13 +3,14 @@ import type { AgentKind, AgentState } from '@/lib/agents/catalog';import type { MonitorSample } from '@/lib/monitor/events';import type { RecordedEvent } from '@/lib/recordings/events';import type { RecordingWorkflow } from '@/lib/recordings/workflow';+import type { GuardrailSettings, GuardrailValue } from '@/lib/settings/guardrails';import type { SkillDraft } from '@/lib/skills/format';import type { SiteMapDraft } from '@/lib/skills/site-map';export const ACTION_CHANNEL = 'browsentic/action';export const BRIDGE_CHANNEL = 'browsentic/bridge';-export const SOCKET_PROTOCOL_VERSION = 11;+export const SOCKET_PROTOCOL_VERSION = 12;export const EXTERNAL_RUN_ID = 'external';@@ -37,7 +38,9 @@ export type BridgeRequest =| { channel: typeof BRIDGE_CHANNEL; op: 'monitorState' }| { channel: typeof BRIDGE_CHANNEL; op: 'agentState'; refresh?: boolean }| { channel: typeof BRIDGE_CHANNEL; op: 'setAgent'; agent: AgentKind }- | { channel: typeof BRIDGE_CHANNEL; op: 'grantAgent'; agent: AgentKind };+ | { channel: typeof BRIDGE_CHANNEL; op: 'grantAgent'; agent: AgentKind }+ | { channel: typeof BRIDGE_CHANNEL; op: 'guardrails' }+ | { channel: typeof BRIDGE_CHANNEL; op: 'setGuardrail'; setting: string; value: GuardrailValue };export type ActionResult<T = unknown> =| { ok: true; data: T }@@ -146,7 +149,10 @@ export type SocketFrame =| { t: 'agentState'; id: string; refresh?: boolean }| { t: 'setAgent'; id: string; agent: AgentKind }| { t: 'grantAgent'; id: string; agent: AgentKind }- | { t: 'agentInfo'; id: string; result: ActionResult<AgentState> };+ | { t: 'agentInfo'; id: string; result: ActionResult<AgentState> }+ | { t: 'guardrails'; id: string }+ | { t: 'setGuardrail'; id: string; setting: string; value: GuardrailValue }+ | { t: 'guardrailInfo'; id: string; result: ActionResult<GuardrailSettings> };export interface RecordingAnalysis {workflow: RecordingWorkflow;@@ -175,6 +181,8 @@ export const EXTENSION_REQUEST_FRAMES = ['agentState','setAgent','grantAgent',+ 'guardrails',+ 'setGuardrail',] as const;export type ExtensionRequest = Extract<SocketFrame, { t: (typeof EXTENSION_REQUEST_FRAMES)[number] }>;diff --git a/lib/settings/guardrails.ts b/lib/settings/guardrails.tsnew file mode 100644index 0000000..cde5cf4--- /dev/null+++ b/lib/settings/guardrails.ts@@ -0,0 +1,69 @@+/**+ * The shape of the guardrail settings screen, shared by the side panel that renders it+ * and the daemon that fills it in.+ *+ * The screen is a list of overrides, not a list of switches that turn protection on. A+ * row with no `override` is a row using whatever Browsentic ships, which is what a fresh+ * install has everywhere — so the settings tab starts entirely untouched and nothing+ * about the default posture depends on someone having visited it.+ *+ * `locked` rows are shown and explained but cannot be changed from the panel. They are+ * not preferences: allowing `javascript:` navigations or a credential in a query string+ * has no use that is worth a switch someone can hit by accident. Editing+ * `~/.browsentic/config.json` by hand still works, for whoever genuinely means it.+ */++export type RuleEffect = 'allow' | 'confirm' | 'deny';++export interface GuardrailToggle {+ /** Rule id, as it appears in `guardrails.rules` in config.json. */+ readonly id: string;+ readonly title: string;+ /** What the agent is told when this fires. Doubles as the row's explanation. */+ readonly reason: string;+ /** The effect with nothing overridden — what the row falls back to when switched off. */+ readonly fallback: RuleEffect;+ /** Present only when the user has overridden it. Absent is the default state. */+ readonly override?: RuleEffect;+ /** Shown, explained, not changeable from the panel. */+ readonly locked?: boolean;+}++export interface GuardrailSwitch {+ readonly enabled: boolean;+ readonly overridden: boolean;+}++export interface GuardrailSettings {+ readonly rules: readonly GuardrailToggle[];+ /** Marking page text as untrusted data on its way to the model. */+ readonly fence: GuardrailSwitch;+ /** What a `confirm` becomes for a caller with nobody to ask. */+ readonly unattended: { readonly effect: 'allow' | 'deny'; readonly overridden: boolean };+ /** Standing host allowlist added to every run's scope. Edited in config.json. */+ readonly hosts: readonly string[];+ /** Where an override is written, so the panel can say so. */+ readonly configPath: string;+}++/**+ * What a row writes. A rule takes an effect, the two switches take a boolean or a+ * side, and `null` clears the override and puts the row back on the shipped default.+ */+export type GuardrailValue = RuleEffect | boolean | null;++export const FENCE_SETTING = 'fence';+export const UNATTENDED_SETTING = 'unattended';++/** Settings that are not a rule id. Written to their own config keys. */+export const SWITCH_SETTINGS: readonly string[] = [FENCE_SETTING, UNATTENDED_SETTING];++export function isRuleEffect(value: unknown): value is RuleEffect {+ return value === 'allow' || value === 'confirm' || value === 'deny';+}++export const EFFECT_LABEL: Record<RuleEffect, string> = {+ allow: 'Allow',+ confirm: 'Ask',+ deny: 'Block',+};diff --git a/mcp/src/agent/config.ts b/mcp/src/agent/config.tsindex ab08074..9dce5f2 100644--- a/mcp/src/agent/config.ts+++ b/mcp/src/agent/config.ts@@ -1,6 +1,7 @@import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';import { join } from 'node:path';import { AGENTS, AGENT_KINDS, DEFAULT_AGENT, isAgentKind, type AgentKind } from '@/lib/agents/catalog';+import { FENCE_SETTING, UNATTENDED_SETTING, type GuardrailValue, type RuleEffect } from '@/lib/settings/guardrails';import type { GuardrailConfig } from '../guardrails';import { stateDir } from '../lockfile';@@ -79,6 +80,7 @@ interface StoredConfig extends Record<string, unknown> {agent?: unknown;agents?: Record<string, { bin?: unknown; model?: unknown; effort?: unknown } | undefined>;requireApproval?: unknown;+ guardrails?: unknown;/** Pre-0.2 layout: one Claude Code runner, configured at the top level. */claudeBin?: unknown;model?: unknown;@@ -136,6 +138,36 @@ export function writeActiveAgent(kind: AgentKind): void {write({ ...stored, agent: kind });}+/**+ * Write one guardrail override, leaving every other key in config.json alone. `null`+ * removes the override rather than writing a value equal to the default — so a config+ * file only ever names the decisions someone actually made, and a change to a shipped+ * default reaches an install that never overrode it.+ */+export function writeGuardrailSetting(setting: string, value: GuardrailValue): void {+ const stored = readStored();+ const guardrails: GuardrailConfig = { ...((stored.guardrails as GuardrailConfig | undefined) ?? {}) };++ if (setting === FENCE_SETTING) {+ if (value === null) delete guardrails.fence;+ else guardrails.fence = value === true;+ } else if (setting === UNATTENDED_SETTING) {+ if (value === null) delete guardrails.unattended;+ else guardrails.unattended = value === 'allow' ? 'allow' : 'deny';+ } else {+ const rules = { ...(guardrails.rules ?? {}) };+ if (value === null) delete rules[setting];+ else rules[setting] = value as RuleEffect;+ if (Object.keys(rules).length) guardrails.rules = rules;+ else delete guardrails.rules;+ }++ const next = { ...stored };+ if (Object.keys(guardrails).length) next.guardrails = guardrails;+ else delete next.guardrails;+ write(next);+}+function write(config: StoredConfig): void {mkdirSync(stateDir, { recursive: true, mode: 0o700 });writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });diff --git a/mcp/src/daemon.ts b/mcp/src/daemon.tsindex 4b868d5..30bf275 100644--- a/mcp/src/daemon.ts+++ b/mcp/src/daemon.ts@@ -13,6 +13,7 @@ import {type RunEvent,type SocketFrame,} from '@/lib/actions/protocol';+import type { GuardrailSettings } from '@/lib/settings/guardrails';import { hashManifest } from '@/lib/actions/manifest';import { describeActions } from '@/lib/actions/registry';import { RESERVED_PREFIX } from '@/lib/actions/reserved';@@ -43,7 +44,7 @@ import { AgentSession } from './agent/service';import { summarizeFile } from './agent/analyze';import { analyzeRecording } from './agent/recording';import { nameSession } from './agent/title';-import { readAgentConfig, writeActiveAgent } from './agent/config';+import { configPath, readAgentConfig, writeActiveAgent, writeGuardrailSetting } from './agent/config';import { agentState, grantRunner } from './agent/runners';import { deleteSiteMap, deleteSkill, saveSkill } from './agent/skill-store';import { commitStaging, discardStaging } from './agent/site-map-store';@@ -54,14 +55,17 @@ import {blocked,decide,describe as describeDecision,+ guardrailSettings,policyFrom,sealSecrets,+ settingWritable,summary as summarizeDecision,} from './guardrails';import { log } from './log';import { readLockfile, writeLockfile, clearLockfile, type Lockfile } from './lockfile';type AgentFrame = Extract<SocketFrame, { t: 'agentState' | 'setAgent' | 'grantAgent' }>;+type GuardrailFrame = Extract<SocketFrame, { t: 'guardrails' | 'setGuardrail' }>;const IDLE_EXIT_MS = 30 * 60 * 1000;const HANDSHAKE_TIMEOUT_MS = 10_000;@@ -323,6 +327,9 @@ export async function startDaemon({ version, idleExit = true }: DaemonOptions):);return;}+ if (request.t === 'guardrails' || request.t === 'setGuardrail') {+ return source.send({ t: 'guardrailInfo', id: request.id, result: settleGuardrail(request) });+ }if (request.t === 'saveSkill') {return source.send({ t: 'skillResult', id: request.id, result: saveSkill(request.skill) });}@@ -371,6 +378,21 @@ export async function startDaemon({ version, idleExit = true }: DaemonOptions):return success(await agentState(readAgentConfig(), { refresh }));}+ function settleGuardrail(request: GuardrailFrame): ActionResult<GuardrailSettings> {+ if (request.t === 'setGuardrail') {+ if (!settingWritable(request.setting, request.value)) {+ return failure(+ 'INVALID_INPUT',+ `"${request.setting}" is not a guardrail the panel may set. Locked rules are edited in ${configPath}.`,+ );+ }+ writeGuardrailSetting(request.setting, request.value);+ log(`guardrail ${request.setting} → ${request.value === null ? 'default' : String(request.value)}`);+ }+ const config = readAgentConfig();+ return success(guardrailSettings(config.guardrails ?? {}, config.requireApproval, configPath));+ }+async function pushAgentState(target: ExtensionLink): Promise<void> {const state = await agentState(readAgentConfig());if (target.isOpen) target.send({ t: 'agentInfo', id: '', result: success(state) });diff --git a/mcp/src/guardrails/index.ts b/mcp/src/guardrails/index.tsindex c8934e5..a768510 100644--- a/mcp/src/guardrails/index.ts+++ b/mcp/src/guardrails/index.ts@@ -7,6 +7,7 @@* policy.ts what may happen in a page — rules as data over a closed set of conditions* fence.ts what the model is told about where text came from* secrets.ts what a credential looks like on its way out, and why it cannot come back+ * settings.ts the same policy, described for the panel that lets you override it* spawn.ts what the agent CLI itself is allowed to reach on the machine** and pure helpers that read them: `decide()`, `fence()`, `sealSecrets()`, `vetPlan()`,@@ -38,5 +39,7 @@ export { FENCE_NOTE, IMAGE_NOTE, fence, fenceTag, shouldFence } from './fence';export { sealSecrets, sealSecretsIn, sealingStream } from './secrets';+export { guardrailSettings, settingWritable } from './settings';+export { CONTAINMENT, describeContainment, sealEnv, sealedAway, vetPlan } from './spawn';export type { LocalTools, SpawnMode, SpawnPlan } from './spawn';diff --git a/mcp/src/guardrails/policy.ts b/mcp/src/guardrails/policy.tsindex 3860907..46d8665 100644--- a/mcp/src/guardrails/policy.ts+++ b/mcp/src/guardrails/policy.ts@@ -25,6 +25,7 @@import { RESERVED_PREFIX } from '@/lib/actions/reserved';import { handlesIn, sealedHandles } from '@/lib/secrets';+import type { RuleEffect } from '@/lib/settings/guardrails';import { hostAllowed, targetUrl, targetsAnotherTab, urlPayloadBytes, type Scope } from './scope';export const SUBMIT_ACTION = 'page.submitForm';@@ -32,7 +33,8 @@ export const UPLOAD_ACTION = 'page.attachFile';export const EXTRACT_ACTION = 'page.extractText';export const CAPTCHA_ACTION = 'page.solveCaptcha';-export type Effect = 'allow' | 'confirm' | 'deny';+/** One definition, shared with the settings screen that renders it. */+export type Effect = RuleEffect;/*** Who is asking. `agent` is a Browsentic run driven from the side panel — it has adiff --git a/mcp/src/guardrails/settings.ts b/mcp/src/guardrails/settings.tsnew file mode 100644index 0000000..00b7eab--- /dev/null+++ b/mcp/src/guardrails/settings.ts@@ -0,0 +1,76 @@+/**+ * Describing the policy to the panel that renders it.+ *+ * Everything here is derived from `DEFAULT_RULES` and the live config, so a rule added+ * to the policy appears in the settings screen with no second edit — and a rule whose+ * title or reason changes says the new thing in both places.+ *+ * `fallback` is the effect this install would use with nothing overridden, which is not+ * always the shipped constant: `form-submission` takes its default from the legacy+ * `requireApproval` key. Computing it by re-running `policyFrom` without the rule+ * overrides is the only way to get that right without restating the derivation.+ */++import {+ FENCE_SETTING,+ UNATTENDED_SETTING,+ isRuleEffect,+ type GuardrailSettings,+ type GuardrailToggle,+ type GuardrailValue,+ type RuleEffect,+} from '@/lib/settings/guardrails';+import { DEFAULT_RULES, policyFrom, type GuardrailConfig } from './policy';++/**+ * Not preferences. Allowing `javascript:` navigation, letting a page call an internal+ * verb, or letting a released credential travel in a query string have no use worth a+ * switch someone can hit by accident. Hand-editing config.json still works.+ */+const LOCKED = new Set(['reserved-action', 'non-http-navigation', 'secret-in-url']);++const RULE_IDS = new Set(DEFAULT_RULES.map((rule) => rule.id));++export function guardrailSettings(+ config: GuardrailConfig,+ requireApproval: readonly string[],+ configPath: string,+): GuardrailSettings {+ const overrides = config.rules ?? {};+ const baseline = policyFrom({ ...config, rules: {} }, requireApproval);++ const rules: GuardrailToggle[] = baseline.rules.map((rule) => {+ const override = overrides[rule.id];+ return {+ id: rule.id,+ title: rule.title,+ reason: rule.reason,+ fallback: rule.effect,+ ...(isRuleEffect(override) ? { override } : {}),+ ...(LOCKED.has(rule.id) ? { locked: true } : {}),+ };+ });++ return {+ rules,+ fence: { enabled: config.fence !== false, overridden: config.fence !== undefined },+ unattended: {+ effect: config.unattended === 'allow' ? 'allow' : 'deny',+ overridden: config.unattended !== undefined,+ },+ hosts: config.hosts ?? [],+ configPath,+ };+}++/** Whether the panel may write this setting at all, and whether the value fits it. */+export function settingWritable(setting: string, value: GuardrailValue): boolean {+ if (setting === FENCE_SETTING) return value === null || typeof value === 'boolean';+ if (setting === UNATTENDED_SETTING) return value === null || value === 'allow' || value === 'deny';+ if (!RULE_IDS.has(setting) || LOCKED.has(setting)) return false;+ return value === null || isRuleEffect(value);+}++export function ruleEffect(value: GuardrailValue): RuleEffect | null {+ return isRuleEffect(value) ? value : null;+}