Beacon Lens Create

Beacon lens create

A lens is one self-contained HTML file that renders one agent trace: the prompts, agent messages, tool calls, commands, file edits, approvals, token usage and threat-rule findings Beacon recorded for a session. The local dashboard (beacon endpoint dashboard) shows lenses as tabs on a session's page, next to Full session, and runs each one in a locked-down frame.

You write the file, check it against the user's real sessions, and install it. Nothing is published anywhere: lenses live on this machine.

Step 1: check that Beacon is available

beacon version

If beacon is not found, tell the user that lenses need the Beacon CLI, point them to https://docs.beacon.sh/get-started/overview, and stop. Do not install it yourself.

Step 2: decide what the lens shows

Start from the user's description. If it is missing, or leaves a choice open that changes what the numbers mean (what counts as a "turn", a "failure", a "risky" command, which cost total), ask one focused question before building. Define each unit from this request, not from another lens, and label anything derived or estimated as such.

Step 3: read the spec and the real data

beacon lenses spec              # the format, the data, the sandbox, the style tokens
beacon lenses spec --example    # a complete working lens to start from
beacon lenses list              # lens ids already in use
beacon lenses data              # exactly what getTrace() returns for the latest session
beacon lenses data --session <session-id>

Read the whole spec before writing anything. Then look at real data rather than guessing its shape from the spec: note which event types the user's sessions carry, whether file.diff, command.output or usage is present, and whether findings exists. Design for those, and for sessions that lack them. The output contains whatever content the log retained (prompts, command output, diffs), so read it locally and do not paste large amounts back to the user.

Step 4: write the file

One HTML file. No build step, bundler or package.json. Write it in the user's project or a scratch directory, never directly in the lens store.

Hard limits

The dashboard enforces these; a lens that breaks them fails to install or fails to run.

• One file, at most 16 MiB, with every script, style, image and font inline (data: URIs for images and fonts). Inlining a library is allowed but counts against the size and costs parse time on every open; prefer a few lines of your own.
• A manifest, in exactly one element whose opening tag is spelled exactly <script type="application/beacon-lens+json">, holding id, title, version and "api": "beacon.lens.v1" (optionally description, icon, author; unknown keys are an error). The id is lowercase letters, digits and hyphens, and cannot be a built-in lens's id.
• No network and nothing loaded by URL. The frame's Content Security Policy blocks fetch, XHR, WebSockets, EventSource, sendBeacon, remote scripts, stylesheets, fonts and images, @import, workers, nested frames, eval and new Function.
• No dashboard access. The frame is sandbox="allow-scripts" with an opaque origin: no cookies, localStorage, sessionStorage or IndexedDB, no access to the parent page, no popups or forms. Keep state in memory.
• Never navigate the frame. The dashboard closes a lens that loads a second document.

The data

The host defines window.beacon before your scripts run. Its one call is the whole data API:

const data = await window.beacon.getTrace();

It resolves once with everything you get and never refreshes. Calling it again returns the same promise. It rejects with an Error if the trace does not arrive within 10 seconds; show that message instead of a blank tab.

The result is LensDataV1; beacon lenses spec has the full shape. The parts you will use most:

• trace.summary: title, started_at/ended_at, event_count, harness.name, session, repository, model, token_usage.
• trace.events[], in order, each with id, number, timestamp, type, action and optional title, summary, fidelity, content, tool, command, file, mcp, approval, policy, error, model, usage, tool_call_id. error.type is set when the runtime reported the action as failed, even on an event whose type is not error. type is one of user_message, agent_message, agent_reasoning, tool_call, tool_result, command, file, mcp, approval, token_usage, session, error, other, and the list can grow.
• findings: threat-rule matches, each pointing at its evidence by event_ids.
• token_usage and token_coverage: the trace's counted usage, and whether this runtime reports usage at all.
• truncated: the trace was cut to fit the size cap.

Things that are easy to get wrong:

• Retained text is an object, not a string. Prompts, messages, command.output and file.diff arrive as {text?, included, retention, redacted?, truncated?, hash?, bytes?}. When included is false the text was not kept or was redacted; show the hash and bytes instead of an empty box, and say why.
• Missing is not empty. An absent findings means the trace was not scanned; an empty findings.items means it was scanned and nothing matched. Say which. The same goes for token_usage.
• Do not sum usage across events for a total. Some runtimes report the same tokens on two channels or as cumulative counters. token_usage.totals is the deduplicated count; if you also show per-event figures, say they can add up to more. cost_usd is only ever what the runtime reported. Lens data carries no estimate (Beacon's list-price estimates live in beacon token-usage and the Tokens page), and a lens must not compute one.
• fidelity: "inferred" marks an action Beacon derived rather than observed (for example an approval built from a pre-tool notification). Show the difference when it matters.
• Pair calls with results on tool_call_id, not on adjacency, and order by number or timestamp, not array position.
• Be honest about truncation. When truncated is true, or trace.events.length is less than trace.summary.event_count, say "over the first N of M events" instead of presenting a partial total as the whole trace. A finding's evidence may point at an event that is not in the bundle.

Rules for the code

• Only these fields are guaranteed: api_version, trace.schema_version, trace.id, trace.summary.id, trace.events (possibly empty), each event's id, number, timestamp, type and action, and truncated. Everything else can be missing. Show a placeholder, never undefined or NaN, and never throw on a missing field.
• Skip what you do not recognise: new event types, enum values and fields appear without a version bump.
• Treat every string as untrusted. Trace content is whatever the agent and its tools produced, often HTML, code and markup. Build nodes with textContent or document.createTextNode; never innerHTML, outerHTML, insertAdjacentHTML or document.write, and never use trace content as a URL.
• Render immediately: a loading line first, then the content when getTrace() resolves, an error line if it rejects, and an empty state for a trace with nothing to show. Keep the states mutually exclusive; if you use the hidden attribute, add [hidden] { display: none !important; } so your own display rules cannot reveal two states at once.
• Expect thousands of events. Build the DOM once; summarise, collapse or paginate long lists instead of rendering every row.
• No settings and no persistence; there is nowhere to save anything.