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
/**
* Installing and calling an approved toolkit.
*
* The store is the extension's record of what the user actually approved: the code, the
* tab, and the origin it was approved on. `page.injectCode` is gated by the daemon's
* policy and `page.runCode` is not, so this file is what keeps the ungated half honest —
* a call can only ever reach code that came from an approved install, on the same tab
* and the same site. A page reload wipes the main world but not the record, so the first
* call afterwards re-installs the same approved source rather than asking again.
*/
import { browser } from 'wxt/browser';
import { z } from 'zod';
import { invokeInTab } from '@/lib/actions/client';
import { injectCode } from '@/lib/actions/page/inject-code';
import { runCode } from '@/lib/actions/page/run-code';
import { installerSource, TOOLKIT_MISSING, type ToolkitEntry } from '@/lib/actions/page/toolkit';
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
import { scopeOf, slugFromPurpose } from '@/lib/skills/saved-tool';
import { send, withDebugger } from './cdp';
import { mainWorldOf, type FrameContext } from './frame-context';
import { getSavedTool, scopeMatches } from './saved-tools';
import { refusalForTab } from './site-guard';
const TOOLKITS_KEY = 'browsentic/codeToolkits';
const FIREFOX_HINT =
'Installing page code needs Chrome’s debugger, which Firefox does not expose — use the ordinary page tools instead.';
const MAX_ERROR_LENGTH = 600;
const FRAME_CONTEXT_HINT =
'Chrome’s debugger found no script context for the frame in focus — call page.switchFrame with no arguments and inject from the top document, or enter the frame again once it has loaded.';
interface StoredToolkit {
id: string;
origin: string;
purpose: string;
code: string;
entries: ToolkitEntry[];
installedAt: number;
}
/**
* What the panel is asked about a second after an install lands. Metadata only: the code
* stays here, and the panel already has it from the approval it just answered.
*/
export interface ToolOffer {
toolkitId: string;
/** The zero-argument entry point a saved tool would call. */
fn: string;
purpose: string;
suggestedSlug: string;
host: string;
segment: string;
origin: string;
}
/** How long after an install the offer appears. Long enough to see the effect land first. */
const OFFER_DELAY_MS = 1_000;
const offerListeners = new Set<(offer: ToolOffer) => void>();
export function onToolOffer(listener: (offer: ToolOffer) => void): void {
offerListeners.add(listener);
}
type ToolkitMap = Record<string, StoredToolkit>;
export interface EvaluateReply {
result?: { value?: unknown };
exceptionDetails?: { text?: string; exception?: { description?: string } };
}
/**
* Where a toolkit lives: a desktop tab, or the tab in front on the phone. `key` names its record,
* `evaluate` runs the installer in the page's main world through a debugger, and `call` runs
* `page.runCode`'s page side, which reaches the toolkit by DOM events from its own world.
*/
export interface ToolkitPlace {
key: string;
evaluate(source: string): Promise<ActionResult<EvaluateReply>>;
call(input: unknown): Promise<ActionResult>;
/** The blocked-sites refusal for the page there now, if any. */
refusal(): Promise<ActionResult | null>;
}
export const tabPlace = (tabId: number): ToolkitPlace => ({
key: String(tabId),
evaluate: (source) =>
withDebugger(tabId, FIREFOX_HINT, async (session) => {
const context = await mainWorldOf(session);
return context ? success(await evaluate(context, source)) : failure('FRAME_UNREACHABLE', FRAME_CONTEXT_HINT);
}) as Promise<ActionResult<EvaluateReply>>,
call: (input) => invokeInTab(tabId, runCode.name, input),
refusal: () => refusalForTab(tabId),
});
async function readToolkits(): Promise<ToolkitMap> {
const stored = await browser.storage.session.get(TOOLKITS_KEY);
return (stored[TOOLKITS_KEY] as ToolkitMap | undefined) ?? {};
}
async function writeToolkit(key: string, toolkit: StoredToolkit | null): Promise<void> {
const map = await readToolkits();
if (toolkit) map[key] = toolkit;
else delete map[key];
await browser.storage.session.set({ [TOOLKITS_KEY]: map });
}
async function forgetToolkit(key: string): Promise<void> {
await writeToolkit(key, null);
}
export function serveCodeToolkits(): void {
browser.tabs.onRemoved.addListener((tabId) => void forgetToolkit(String(tabId)));
}
export function originOf(url: string | undefined): string | undefined {
if (!url) return undefined;
try {
const origin = new URL(url).origin;
return origin === 'null' ? undefined : origin;
} catch {
return undefined;
}
}
export async function installToolkit(place: ToolkitPlace, url: string | undefined, input: unknown): Promise<ActionResult> {
const parsed = injectCode.input.safeParse(input ?? {});
if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
const origin = originOf(url);
if (!origin) {
return failure('UNSUPPORTED', 'Page code can only be installed on an http(s) page.');
}
const { purpose, code, call } = parsed.data;
const toolkit: StoredToolkit = {
id: crypto.randomUUID(),
origin,
purpose,
code,
entries: [],
installedAt: Date.now(),
};
const installed = await evaluateInstaller(place, toolkit);
if (!installed.ok) return installed;
toolkit.entries = installed.data as ToolkitEntry[];
await writeToolkit(place.key, toolkit);
const summary = {
toolkitId: toolkit.id,
origin,
purpose,
functions: toolkit.entries.map((entry) => entry.name),
};
const called = call ? await runToolkit(place, url, { function: call.function, args: call.args }) : null;
offerToKeep(toolkit, url, call?.function);
if (!called) return success(summary);
return called.ok
? success({ ...summary, called: called.data })
: success({ ...summary, callFailed: called.error });
}
/**
* Ask, once, whether this is worth keeping. Only a zero-argument entry point can be
* offered, because `/` invocation passes nothing: prefer the one just called, since that
* is the effect the user watched happen, and otherwise take a lone zero-argument function.
* Anything else stays a one-off, which is the honest answer for a toolkit that needs input.
*/
function offerToKeep(toolkit: StoredToolkit, url: string | undefined, called: string | undefined): void {
const zeroArg = toolkit.entries.filter((entry) => entry.arity === 0);
const entry = zeroArg.find((candidate) => candidate.name === called) ?? (zeroArg.length === 1 ? zeroArg[0] : null);
const scope = url ? scopeOf(url) : null;
if (!entry || !scope) return;
setTimeout(() => {
const offer: ToolOffer = {
toolkitId: toolkit.id,
fn: entry.name,
purpose: toolkit.purpose,
suggestedSlug: slugFromPurpose(toolkit.purpose, entry.name),
host: scope.host,
segment: scope.segment,
origin: toolkit.origin,
};
for (const listener of offerListeners) listener(offer);
}, OFFER_DELAY_MS);
}
/**
* The `/` path. No guardrail runs here and none should: this code was read and approved
* when it was saved, the user asked for it by name just now, and the daemon is not in the
* loop at all — which is also what keeps it out of reach of an MCP client. Blocked sites
* are the exception: they bind the user's own tools too.
*/
export async function runSavedTool(place: ToolkitPlace, url: string | undefined, toolId: string): Promise<ActionResult> {
const refused = await place.refusal();
if (refused) return refused;
const tool = await getSavedTool(toolId);
if (!tool) return failure('UNKNOWN_TOOL', 'That tool is no longer saved.');
if (!scopeMatches(tool, url)) {
return failure(
'TOOLKIT_SCOPE',
`“${tool.name}” was saved for ${tool.origin}/${tool.scope.segment}, and this tab is somewhere else.`,
);
}
const staged: StoredToolkit = {
id: tool.id,
origin: tool.origin,
purpose: tool.description,
code: tool.code,
entries: [],
installedAt: Date.now(),
};
const installed = await evaluateInstaller(place, staged);
if (!installed.ok) return installed;
staged.entries = installed.data as ToolkitEntry[];
await writeToolkit(place.key, staged);
return place.call({ function: tool.fn, args: [], timeoutMs: 10_000 });
}
/**
* The approved source for a toolkit still installed in this tab, by the id the offer
* carried. Saving reads it from here rather than from the panel, so the code makes one
* fewer hop and the panel never has to hold it to hand it back.
*/
export async function toolkitCode(place: Pick<ToolkitPlace, 'key'>, toolkitId: string): Promise<string | null> {
const toolkit = (await readToolkits())[place.key];
return toolkit && toolkit.id === toolkitId ? toolkit.code : null;
}
export async function runToolkit(place: ToolkitPlace, url: string | undefined, input: unknown): Promise<ActionResult> {
const parsed = runCode.input.safeParse(input ?? {});
if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
const toolkit = (await readToolkits())[place.key];
if (!toolkit) {
return failure(
TOOLKIT_MISSING,
'No toolkit is installed in this tab. Call page.injectCode first, and the user will be asked to approve the code.',
);
}
const origin = originOf(url);
if (origin !== toolkit.origin) {
await forgetToolkit(place.key);
return failure(
'TOOLKIT_SCOPE',
`That toolkit was approved for ${toolkit.origin}, but this tab is on ${origin ?? 'another page'}. Install it again here if the job continues.`,
);
}
if (!toolkit.entries.some((entry) => entry.name === parsed.data.function)) {
return failure(
'UNKNOWN_FUNCTION',
`This toolkit has no function named “${parsed.data.function}”. It defines: ${toolkit.entries.map((entry) => entry.name).join(', ')}.`,
);
}
const called = await place.call(parsed.data);
if (called.ok || called.error.code !== TOOLKIT_MISSING) return called;
const reinstalled = await evaluateInstaller(place, toolkit);
if (!reinstalled.ok) return reinstalled;
return place.call(parsed.data);
}
async function evaluateInstaller(place: ToolkitPlace, toolkit: StoredToolkit): Promise<ActionResult> {
const evaluated = await place.evaluate(installerSource(toolkit.id, toolkit.code));
if (!evaluated.ok) return evaluated;
const thrown = evaluated.data.exceptionDetails;
if (thrown) {
return failure('CODE_ERROR', `The code failed while installing: ${describeThrow(thrown)}`);
}
const entries = evaluated.data.result?.value;
if (!Array.isArray(entries)) {
return failure('CODE_ERROR', 'The code installed but reported no functions.');
}
return success(entries as ToolkitEntry[]);
}
function evaluate({ session, contextId }: FrameContext, expression: string): Promise<EvaluateReply> {
return send<EvaluateReply>(session, 'Runtime.evaluate', {
expression,
returnByValue: true,
awaitPromise: true,
...(contextId == null ? {} : { contextId }),
});
}
function describeThrow(thrown: NonNullable<EvaluateReply['exceptionDetails']>): string {
const detail = thrown.exception?.description ?? thrown.text ?? 'unknown error';
return detail.length > MAX_ERROR_LENGTH ? `${detail.slice(0, MAX_ERROR_LENGTH)}…` : detail;
}