Client-side tools & the browser adapter
An MCP server gives the assistant tools that run on a server. A client-side tool runs in the visitor’s browser instead. The server interrupts the turn, the kit runs your handler against the live DOM or app state, and the result flows back into the model’s context. This is how the assistant reads the page the user is looking at, and how it changes that page without a round-trip through your backend.
There are two ways to register one. Pick by what the tool does.
Raw browser tool
Section titled “Raw browser tool”Use diosc('tool', name, handler) when the tool is a single self-contained action — read something, move
somewhere, poke one piece of app state.
diosc('tool', 'highlight_row', async (params) => { const row = document.querySelector(`[data-id="${params.id}"]`); if (!row) return { error: `Row ${params.id} not found` }; row.scrollIntoView(); row.classList.add('is-highlighted'); return { highlighted: params.id };});The backend fires a browser:<name> interrupt for the matching tool. The kit runs your handler with the
tool’s parameters and submits whatever it returns as the tool result. handler(params) may be sync or
async. Return any JSON-serializable value; return { error: '…' } (or throw) to report failure — the
message becomes the tool’s error result.
The kit ships two built-in browser tools, registered for you:
| Tool | What it does |
|---|---|
navigate | Routes through the kit’s navigation handler. A host that called setNavigationHandler (React Router, SvelteKit goto, and so on) gets SPA navigation with no reload; otherwise it falls back to window.location.assign. Returns { navigatedTo }. |
read_page | With a selector, returns that element’s content (trimmed text) and html. Without one, returns { url, path, title, content }, where content is the page’s visible text with script/style/img/svg/iframe stripped, capped at 5,000 characters. |
navigate is what the Northwind storefront wires up to let the assistant move the shopper between pages —
the hub only ever emits paths it validated against the assistant’s Sitemap.
You can override either built-in by registering your own handler under the same name.
Browser adapter
Section titled “Browser adapter”Use diosc('browserAdapter', adapter) when the assistant needs to understand and mutate a live view — a
form, an editor, a canvas. The adapter does two things a raw tool can’t: it feeds the model a fresh
snapshot of the page every turn, and it turns a set of typed intents into first-class tools with a
built-in approval gate.
diosc('browserAdapter', { // Pulled fresh on every turn and attached to the outgoing message, // so the model always reasons about the current page. async read() { return { url: location.href, title: document.title, description: 'Flowchart editor — the open document', content: editor.toMarkdown(), data: { nodeCount: editor.nodes.length }, }; }, intents: [ { name: 'apply_changes', description: 'Apply a diff of node/edge operations to the open diagram.', schema: { type: 'object', properties: { ops: { type: 'array', items: { type: 'object' } } }, required: ['ops'], }, async handler(args) { const applied = editorBridge.apply(args.ops); return { success: true, data: { applied } }; }, }, ],});adapter.read() returns a PageSnapshot — { url, title, description?, content?, data? }. The kit calls
it on every invoke and attaches the result to the user message, so the model sees the page as it is
right now, not as it was when the widget loaded. description is your one-line summary of the view,
content is its semantic text or markdown, and data is any JSON-serializable structured state.
Each entry in adapter.intents is an IntentDefinition — { name, description, schema, handler, approval? } —
and becomes a tool the model can call, registered under the name browser_<name> (so the intent above is
the tool browser_apply_changes). schema is JSON Schema describing the intent’s arguments; the model
fills it, and the kit hands the result to handler(args).
Only metadata crosses the wire when the kit announces your intents: each intent’s name, description,
schema, and — if present — its approval.severity. The handler, and the approval.summary/diff
functions, stay in the browser and never reach the backend or the model. Pass diosc('browserAdapter', null) to clear the
adapter; the kit stops attaching snapshots and unregisters the intent dispatcher.
The intent result contract
Section titled “The intent result contract”An intent handler returns an IntentResult:
interface IntentResult { success: boolean; data?: unknown; // what the model reads back error?: string; // failure detail file?: IntentFileEmission; // deliver a downloadable file (below)}Put whatever the model should reason about next in data — the count of rows changed, the new document
title, the id it created. Set success: false with an error when the action couldn’t complete.
Return a file from a client-side tool
Section titled “Return a file from a client-side tool”A client-side tool can hand the user a file the browser generated — a PNG export of the canvas, a CSV built
from the current table, a rendered PDF. Set file on the result to an IntentFileEmission:
async handler(args) { const blob = await canvas.toBlob('image/png'); return { success: true, file: { content: blob, filename: 'diagram.png', mimeType: 'image/png' }, };}content may be a Blob/File (best for binary), a data: URL string, or a plain string treated as text.
filename includes the extension; mimeType is required for a typeless Blob or a text string.
The kit uploads the bytes through the authenticated transport — the same path the file picker uses, so the
same session and the user’s file permission apply — renders a download chip on the assistant message, and
strips the bytes before the result returns. What the model sees is a byte-free descriptor:
{ fileId, filename, format, downloadUrl, sizeBytes } — the same shape the server-side generate_file tool
produces. The bytes never enter the model’s context, which is what keeps the Credential
Blind boundary intact. The chip is baked into the saved message, so it
survives a reload.
Do not attach a chip yourself. Returning file is the whole contract — the kit does the upload,
the chip, and the byte stripping. If delivery fails, the result degrades to { success: false } rather
than throwing. The file goes through the same upload limit and storage
quota as any upload: a refused file keeps its reason in the result —
code: 'FILE_TOO_LARGE' with limitBytes, or code: 'QUOTA_EXCEEDED' with usageBytes, quotaBytes,
usageFiles and quotaFiles — so the model can tell the user why.
Gate an intent behind approval
Section titled “Gate an intent behind approval”An intent that mutates state — writes to a record, applies a diff, deletes something — should ask the user
first. Add an approval block:
{ name: 'apply_changes', description: 'Apply a diff to the open diagram.', schema: { /* … */ }, approval: { severity: 'medium', summary: (args) => `Apply ${args.ops.length} change(s) to the diagram`, diff: (args) => args.ops.map((op) => ({ field: op.target, current: op.before ?? '—', next: op.after ?? '—', })), }, async handler(args) { /* … */ },}When approval is present, the kit asks the user in the tab that runs the intent, before the handler
runs. This is Responsibility-First: the assistant may not trigger a declared
intent without an explicit human decision. The hub does not hold the call for approval — the decision is
made in the page, every time.
The dialog shows:
- Summary.
summary(args)titles the request. - Diff.
diff(args)returns{ field, current, next }rows, rendered as a before/after table. - Risk level.
severitysets the badge. - Editable arguments. When the intent has a
schema, the dialog shows a form for the arguments, typed from that schema. An edit that breaks the schema can’t be submitted.
Editing is unavailable when the schema uses oneOf, anyOf, allOf, not, $ref, format,
patternProperties or if/then/else. The dialog then says editing isn’t available for this action, and
the user can only approve or reject.
Nothing runs until they decide. The outcome shapes the call:
- Approve — the handler runs with the model’s arguments.
- Edit — the user’s edited values arrive as the handler’s arguments instead.
- Reject — the handler never runs; the intent returns
{ success: false, error: 'Action declined by user' }, with the user’s reason appended when they gave one.
If the user presses Stop while the dialog is open, the dialog closes and the handler does not run.
What the hub records
Section titled “What the hub records”Each approval-gated call is written to the approval log as one row, the same log MCP approvals use. The row is opened as pending when the call is sent and closed by the user’s decision. It holds:
- the
severity; - the decision;
- whether the user edited the arguments;
- the arguments that ran, redacted the same way as MCP rows.
The summary, the diff and the handler stay in the browser. The model never sees the prompt or the diff —
it only learns the decision. If the call ends without a decision, or the hub had to fail it (see
When the tab goes away), the row is closed as a timeout and carries the failure
code. This gate follows the same model as server-side Consensus, applied to a tool
that runs in the page. Browser actions don’t appear in the away-approvals list, because the user is already
in the tab.
A vanished intent fails fast
Section titled “A vanished intent fails fast”Intents are re-read off the current adapter each time one is dispatched. If the page changed between the
model deciding to call browser_apply_changes and the interrupt arriving — the user navigated away, you
swapped adapters, the editor closed — the intent is no longer in adapter.intents. The kit returns
{ error: 'intent "apply_changes" no longer available — page changed' } rather than running a stale handler
against a view that no longer exists. The model reads that and re-plans.
When the tab goes away
Section titled “When the tab goes away”A browser call runs in one tab. While it is in flight, the hub keeps the chat on that tab: another tab can’t take the chat over until the call is answered. If the tab goes away anyway — the user reloads, closes it, or the browser crashes — the hub fails the call at once. It never waits for a tab to come back, and it never runs the call again.
| Call | What the model gets |
|---|---|
read_page | TAB_GONE. Nothing changed, so the model may read again. |
| An intent | OUTCOME_UNKNOWN. The handler may have run, so the model is told to check the page before repeating it. |
navigate | If a tab reattaches to the chat within 30 seconds, the result is taken from that tab’s page: success if it landed where requested, otherwise the page it landed on. If none does, TAB_GONE. This is how a full-reload navigate completes. |
A browser call needs a tab that shows the chat. When none does — a turn running in the background while the
user is elsewhere — the call fails at once with NO_TAB, and the model is told to ask the user to open the
chat in a tab. Server-side (MCP) tools in the same turn are not affected, and closing the tab fails nothing
when the turn calls only those.
Every failure above is a result the model reads, like any tool error. It carries on or reports the problem.
Warn before the user leaves
Section titled “Warn before the user leaves”While the assistant runs a browser call other than navigate, the kit registers a beforeunload handler, so
the browser asks the user to confirm before they reload or close the page. It is removed when the call
finishes, and it is not armed for the assistant’s own navigate. The prompt text is the browser’s own.
This is on by default. To turn it off, clear Confirm before leaving the page while the assistant is using
it in the assistant’s Navigation settings in the admin portal (the browserUnloadGuard setting).
Worked examples
Section titled “Worked examples”- Tutorial: Plynth — a browser adapter whose
browser_apply_changesintent edits a live diagram through an editor bridge, with destructive operations approval-gated. - Tutorial: Northwind — the built-in
navigatetool moving a shopper between validated storefront routes.
Next: Frontend integration for loading the widget, or the
Client command API reference for every diosc() command.