Skip to content

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.

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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 a
diff --git a/mcp/src/guardrails/settings.ts b/mcp/src/guardrails/settings.ts
new file mode 100644
index 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;
+}