The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
docs(lenses): concept page, CLI reference, and dashboard and README mentions
Claude581f305751c2
diff --git a/CLAUDE.md b/CLAUDE.mdindex 8fed9cca..20cbcfeb 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -15,7 +15,7 @@ Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes.- `plugins`: TypeScript sources for the managed runtime plugins/extensions (`opencode-beacon`, `cline-beacon`, `pi-beacon`, `omp-beacon`, `openclaw-beacon`, `prime-beacon`, `omo-beacon`), each mirrored into an embedded copy under `cli/beacon/internal/endpoint/hooks/assets/`.- `agent-skills`: publishable Agent Skills plugin for the traces-to-memory workflow (`beacon-memory-recall`, `beacon-memory-distill`, `beacon-memory-promote`) and for authoring dashboard lenses (`beacon-lens-create`) with manifests for Claude Code, Agent Plugins (Codex, Copilot, VS Code, Kiro, Devin), Cursor, Kimi Code, and Gemini CLI. At the repo root, `.claude-plugin/marketplace.json` is read by most harnesses, `.cursor-plugin/marketplace.json` by Cursor, and `package.json` (`pi.skills` only) makes the repo a Pi/Prime Agent package; keep that root `package.json` free of dependencies and scripts. `cli/beacon/cmd/agent_skills_test.go` checks every `beacon` command and flag the skills name against the real command tree, so rename a command and update the skills together.- `rules` and `spec/threat-rules`: the open rule corpus and the Threat Rules format it conforms to. Every rule's `taxonomy.beacon_category` is its directory name, and the six embedded baseline rules in `pkg/asymptoteobserve/rulestore/baseline` are byte-identical copies of their corpus rules; conformance tests enforce both.-- `spec/lenses`: the Lenses format — single-file HTML views of one trace that the local dashboard runs in a sandboxed, network-less frame and feeds once through `window.beacon.getTrace()`. The contract types (`LensManifestV1`, `LensDataV1`) live in `pkg/asymptoteobserve/lens.go`, and `lens_test.go` pins the spec's examples and manifest schema to them. The dashboard builds the data in `BuildLensData` (`/api/lens-data`), lists lenses at `/api/lenses`, and serves each lens at `/lenses/frame/<id>` under the spec's CSP with `lenses/prelude.js` (which defines `window.beacon`) injected ahead of it; that route is the only one that may be framed. Built-in lenses are `cli/beacon/internal/endpoint/dashboard/lenses/*.lens.html`, and `activity` is byte-identical to the spec example (a test enforces it). The session page (`static/session.html`, `initLensTabs` in `app.js`) shows lenses as tabs fed by `/api/lens-data?session=`, which projects exactly the events that page lists; it is the host half of the protocol and closes a lens that errors, stalls, or navigates its own frame. Installed lenses live in the lens store (`cli/beacon/internal/endpoint/lensstore`, `<BaseDir>/lenses/<id>.lens.html`, 0600 under 0700), written only by `beacon lenses add|remove` (`cli/beacon/cmd/lenses.go`); the dashboard rescans it per request and never writes it, and a store lens can never shadow a built-in. `asymptoteobserve.CheckLensFile` is the one file check every installer, server and linter uses. The authoring loop is `beacon lenses spec` (the spec carried in the binary as `dashboard/lenses/SPEC.md`, kept byte-identical to `spec/lenses/SPEC.md` by a test), `beacon lenses data` (the exact `LensDataV1` for a session), `beacon lenses lint` (`lensstore.Lint`; built-ins must lint clean) and `beacon lenses preview` (the dashboard with `Options.LensFiles`, re-read per reload).+- `spec/lenses`: the Lenses format — single-file HTML views of one trace that the local dashboard runs in a sandboxed, network-less frame and feeds once through `window.beacon.getTrace()`. The contract types (`LensManifestV1`, `LensDataV1`) live in `pkg/asymptoteobserve/lens.go`, and `lens_test.go` pins the spec's examples and manifest schema to them. The dashboard builds the data in `BuildLensData` (`/api/lens-data`), lists lenses at `/api/lenses`, and serves each lens at `/lenses/frame/<id>` under the spec's CSP with `lenses/prelude.js` (which defines `window.beacon`) injected ahead of it; that route is the only one that may be framed. Built-in lenses are `cli/beacon/internal/endpoint/dashboard/lenses/*.lens.html`, and `activity` is byte-identical to the spec example (a test enforces it). The session page (`static/session.html`, `initLensTabs` in `app.js`) shows lenses as tabs fed by `/api/lens-data?session=`, which projects exactly the events that page lists; it is the host half of the protocol and closes a lens that errors, stalls, or navigates its own frame. Installed lenses live in the lens store (`cli/beacon/internal/endpoint/lensstore`, `<BaseDir>/lenses/<id>.lens.html`, 0600 under 0700), written only by `beacon lenses add|remove` (`cli/beacon/cmd/lenses.go`); the dashboard rescans it per request and never writes it, and a store lens can never shadow a built-in. `asymptoteobserve.CheckLensFile` is the one file check every installer, server and linter uses. User docs are `docs/concepts/lenses.mdx` and `docs/cli/lenses.mdx`; keep them in sync with the commands and built-in lenses. The authoring loop is `beacon lenses spec` (the spec carried in the binary as `dashboard/lenses/SPEC.md`, kept byte-identical to `spec/lenses/SPEC.md` by a test), `beacon lenses data` (the exact `LensDataV1` for a session), `beacon lenses lint` (`lensstore.Lint`; built-ins must lint clean) and `beacon lenses preview` (the dashboard with `Options.LensFiles`, re-read per reload).- `beacon-sandbox`: harness that runs a real Claude Code session in a disposable sandbox and checks what Beacon captured. See `beacon-sandbox/AGENTS.md`.- `packaging`: macOS, Linux, and Windows packaging and deployment assets.- `docs`: the published documentation site (docs.asymptotelabs.ai).diff --git a/README.md b/README.mdindex 44599b63..516cbc4f 100644--- a/README.md+++ b/README.md@@ -256,6 +256,12 @@ beacon endpoint dashboardUse it to explore session history across harnesses and understand what your agents actually did.+Each session page can also show **lenses**: purpose-built views of one trace, such as files+changed with their diffs, an itemized token bill, a security review grouped by risk, or the+approval timeline. A lens is a single HTML file running in a sandboxed, network-less frame,+so you can have your coding agent write your own (`beacon lenses spec`, `lint`, `preview`,+`add`). See [Lenses](https://docs.beacon.sh/concepts/lenses).+The underlying JSONL remains directly accessible, so you're never dependent on the UI.---diff --git a/docs/cli/dashboard.mdx b/docs/cli/dashboard.mdxindex ecaf8888..62c7307d 100644--- a/docs/cli/dashboard.mdx+++ b/docs/cli/dashboard.mdx@@ -30,6 +30,10 @@ poll, and OTLP collection paths.summaries.- **Session detail:** open a session timeline with metadata, activity and severitysummaries, event filters, raw JSON, and value inspectors.+- **Lenses:** add tabs to a session's page that show it from one angle: files+ changed with diffs, an itemized token bill, a security review, approvals, or a+ [lens you wrote](/concepts/lenses). Each lens runs in a sandboxed frame with no+ network access.- **Agent Activity:** review aggregate local activity, risk signals, harnesses,models, repositories, MCP servers, and runtime inventory.- **Memory:** inspect read-only counts and tables for local evaluations, reviewdiff --git a/docs/cli/lenses.mdx b/docs/cli/lenses.mdxnew file mode 100644index 00000000..97b6442a--- /dev/null+++ b/docs/cli/lenses.mdx@@ -0,0 +1,143 @@+---+title: "beacon lenses"+description: "Manage and author lenses: single-file views of one trace in the local dashboard"+---++## Command overview++`beacon lenses` manages the lens store and the tools for writing a lens. A+[lens](/concepts/lenses) is one HTML file that renders one trace as a tab on a session's+page in the local dashboard ([`beacon endpoint dashboard`](/cli/dashboard)).++```bash title="Command syntax"+beacon lenses list [--json]+beacon lenses add <file> [--force]+beacon lenses remove <id>+beacon lenses show <id>+beacon lenses spec [--example]+beacon lenses data [--session <id> | --trace <id>]+beacon lenses lint <file>... [--strict] [--json]+beacon lenses preview <file> [--session <id>] [--addr <host:port>] [--open]+```++Every command is local. None of them touches the network, and the dashboard only reads the+store; it never writes it.++## The lens store++Installed lenses live in `~/.beacon/endpoint/lenses` (with `--system`, under the system+endpoint directory), one `<id>.lens.html` file per lens. The directory is `0700` and each+file `0600`. The file name comes from the lens's manifest `id`, not from the file you+installed. The dashboard reads the store on every page load, so an added or removed lens+shows up without restarting it.++A lens in the store can never take the place of a built-in lens: built-in IDs are refused+on install, and a store file that claims one is ignored.++## beacon lenses list++Lists the built-in and installed lenses with their version and source (`builtin` or+`store`). A file in the store that is not a valid lens is named in a warning and left out;+the other lenses still list.++| Flag | Description |+|------|-------------|+| `--json` | Print JSON, including each store lens's path |+| `--user` / `--system` | Use the per-user (default) or system endpoint paths |++## beacon lenses add++Checks a lens file against the [spec](https://github.com/asymptote-labs/agent-beacon/blob/main/spec/lenses/SPEC.md)+(at most 16 MiB, one valid manifest) and copies it into the store under its manifest `id`.++Replacing an installed lens needs a higher `version` in the new file's manifest, so adding+an old copy by mistake does not downgrade it. `--force` replaces it anyway.++```bash+beacon lenses add ./command-log.lens.html+# installed command-log v1 (~/.beacon/endpoint/lenses/command-log.lens.html)+```++| Flag | Description |+|------|-------------|+| `--force` | Replace an installed lens even when the new version is not higher |+| `--user` / `--system` | Use the per-user (default) or system endpoint paths |++## beacon lenses remove++Deletes an installed lens by `id`. Built-in lenses cannot be removed.++## beacon lenses show++Prints a lens's manifest, its source, and, for an installed lens, its path.++## beacon lenses spec++Prints the lens specification: the file format, the manifest, the data+`window.beacon.getTrace()` returns, the sandbox rules and the style tokens. It is carried in+the binary, so it works offline and always matches the installed Beacon.++| Flag | Description |+|------|-------------|+| `--example` | Print a complete, working lens to start from (the built-in Activity lens) |++## beacon lenses data++Prints exactly what a lens receives from `window.beacon.getTrace()` for one session (as on+the dashboard's session page) or one trace. With neither flag it uses the most recent+session in the runtime log.++The output includes whatever content the log retained, such as prompts, command output and+diffs.++| Flag | Description |+|------|-------------|+| `--session <id>` | Session ID |+| `--trace <id>` | Trace ID, instead of a session |+| `--log-path <path>` | Runtime JSONL log path |+| `--user` / `--system` | Use the per-user (default) or system endpoint paths |++## beacon lenses lint++Checks lens files against the spec. **Errors** (an oversized file, a missing or invalid+manifest) stop a lens from running. **Warnings** name the line where a lens does something+the sandbox will block or the spec forbids:++- parsing trace content as HTML (`innerHTML`, `insertAdjacentHTML`, `document.write`)+- network requests (`fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `sendBeacon`)+- scripts, images, fonts or stylesheets loaded by URL+- browser storage and cookies+- messaging or navigating another window, or its own frame+- `eval`, `new Function` and workers+- a root sized to the viewport (`100vh`), which never settles because the frame grows to fit+- never calling `window.beacon.getTrace()`++The command exits non-zero when there are errors, or warnings with `--strict`.++| Flag | Description |+|------|-------------|+| `--strict` | Fail on warnings too |+| `--json` | Print JSON |++## beacon lenses preview++Lints a lens file, then runs the dashboard with the file added and prints the session page+that shows it. The file is read again on every page load: edit it and reload. Nothing is+installed. The command runs until you stop it.++```bash+beacon lenses preview ./command-log.lens.html --session 5f0c2a9e+# Previewing Command Log (command-log) from /home/me/command-log.lens.html+# Open: http://127.0.0.1:8766/session.html?id=5f0c2a9e&lens=command-log+```++The preview listens on `127.0.0.1:8766` by default, so it can run next to a dashboard on+the default `8765`. A lens with a built-in's `id` cannot be previewed; give it its own.++| Flag | Description |+|------|-------------|+| `--session <id>` | Session to open (default: the most recent session) |+| `--addr <host:port>` | Loopback address to serve the preview on (default `127.0.0.1:8766`) |+| `--open` | Open the preview in a browser |+| `--log-path <path>` | Runtime JSONL log path |+| `--user` / `--system` | Use the per-user (default) or system endpoint paths |diff --git a/docs/concepts/beacon-skills.mdx b/docs/concepts/beacon-skills.mdxindex 3da6b3cd..d3f04b8e 100644--- a/docs/concepts/beacon-skills.mdx+++ b/docs/concepts/beacon-skills.mdx@@ -21,6 +21,7 @@ control of every write to memory.| `beacon-memory-recall` | Before a task, retrieves approved project memory relevant to it | None || `beacon-memory-distill` | Turns selected traces into reviewed memory: dry run, a consented evaluation, a lesson drafted from the source trace, approval by the user | Evaluator call only, after the user agrees || `beacon-memory-promote` | Installs an approved memory as a project Agent Skill | None |+| `beacon-lens-create` | Builds a [lens](/concepts/lenses) for the local dashboard: reads the spec, inspects real trace data, writes, lints and previews the file with the user, then installs it | None |## Requirementsdiff --git a/docs/concepts/lenses.mdx b/docs/concepts/lenses.mdxnew file mode 100644index 00000000..34d0e996--- /dev/null+++ b/docs/concepts/lenses.mdx@@ -0,0 +1,132 @@+---+title: "Lenses"+description: "Purpose-built views of one agent trace, as tabs in the local dashboard, and how to make your own"+---++## Overview++A trace holds everything an agent did in a session: what it was asked, the commands it+ran, the files it changed, what it spent, and what the threat rules flagged. The full event+list shows all of it at once. A **lens** shows one trace from one angle: every file the+agent changed with its diffs, or the run as an itemized bill.++Lenses are tabs on a session's page in the local dashboard+([`beacon endpoint dashboard`](/cli/dashboard)), next to **Full session**. Click **+** to+add one; the dashboard remembers which lenses you opened and keeps the selected one in the+page URL, so a link opens straight to it.++Beacon ships five lenses, and you can add your own. A lens is one HTML file, so any coding+agent can write one.++## Built-in lenses++| Lens | What it shows |+|------|---------------|+| **Activity** | What the agent did, counted by kind, the commands it ran with their exit codes, and each rule finding linked to its evidence. It is also the spec's example lens. |+| **Files Changed** | Every file the agent created, edited or deleted, as a tree with line counts. Selecting a file shows each of its edits in order, with the diff, or the diff's hash and size when it was not retained. Files only read are counted, not listed. |+| **Token Usage** | An itemized bill: counted usage and runtime-reported cost, split by model and by turn, then every event that reported usage. When the events' own numbers add up to more than Beacon counts (usage reported on two channels, or as a cumulative counter), the lens says so. It also says when a runtime that should report usage did not, and when a runtime never exposes usage at all. |+| **Security Review** | [Threat-rule](/detections) findings grouped as **untrusted input** (prompt injection), **sensitive access** (credentials, metadata endpoints) and **consequential action** (exfiltration, destructive commands, sensitive edits). It calls out a trace that has all three, which is how an injected instruction turns into stolen data, and shows each finding's evidence events. |+| **Approvals & Policy** | Every approval decision in order: allowed or denied, whether the operator or a policy provider (the optional `BEACON_POLICY_PROVIDER` seam) decided, what it was about, and whether the runtime reported it or Beacon inferred it. |++## How a lens runs++A lens is untrusted code looking at sensitive data, so the dashboard runs it on a short+leash:++- **No network.** The lens runs in a sandboxed frame under a Content Security Policy with+ `connect-src 'none'`. It cannot fetch, open a socket, load a remote image or font, or+ navigate its frame anywhere else. A lens that tries to navigate is closed.+- **No dashboard access.** The frame has an opaque origin. It cannot read the dashboard's+ pages, storage or API.+- **One delivery of data.** The trace arrives once, through `window.beacon.getTrace()`,+ over a private message channel. It is computed from the local log when the page loads and+ is never refreshed.+- **Failure is contained.** If a lens throws before it renders, never asks for its trace,+ or has not rendered after ten seconds, the dashboard closes it and shows the full session+ with a notice.++The data is the trace bundle every Beacon trace consumer reads, plus the trace's rule+findings and its token usage as [`beacon token-usage`](/cli/token-usage) counts it. A lens+sees whatever content the local log retained, after Beacon's redaction: prompts, command+output and diffs when retention is `full`. It can show that on screen and nowhere else.+[Forwarding privacy modes](/concepts/vector-forwarding) control what leaves the machine;+they do not reduce what a local lens receives.++## Make your own lens++The fastest way is to ask your coding agent. The `beacon-lens-create` skill in Beacon's+[Agent Skills plugin](/concepts/beacon-skills) walks it through the whole loop. Without the+skill, give it this:++```text+Build a Beacon lens that <describe the view>. Read `beacon lenses spec` first, look at+real data with `beacon lenses data`, lint with `beacon lenses lint`, and preview it with+`beacon lenses preview` before installing it with `beacon lenses add`.+```++By hand, the loop is the same:++```bash+beacon lenses spec # the format, the data, the sandbox, the style tokens+beacon lenses spec --example > my.lens.html+beacon lenses data --session <id> # exactly what getTrace() returns for a real session+beacon lenses lint my.lens.html # spec errors, and code the sandbox would block+beacon lenses preview my.lens.html # the dashboard with your lens added; edit and reload+beacon lenses add my.lens.html # install it into the lens store+```++1. **Read the spec.** It defines the manifest every lens carries, the data, the sandbox+ and the style tokens that match the dashboard.+2. **Look at real data.** Design for the fields your sessions actually carry, and for+ sessions that lack them.+3. **Lint.** Errors stop a lens from running. Warnings name the line where the lens does+ something the sandbox will block, such as `fetch`, `innerHTML` or a script loaded from a+ CDN.+4. **Preview.** `beacon lenses preview` serves the dashboard with the file added and prints+ the session page to open. The file is read again on every reload.+5. **Install.** `beacon lenses add` copies the file into the lens store+ (`~/.beacon/endpoint/lenses`), where every session page offers it. To update a lens, bump+ the `version` in its manifest and add it again.++See [`beacon lenses`](/cli/lenses) for every command and flag, and the+[lens specification](https://github.com/asymptote-labs/agent-beacon/blob/main/spec/lenses/SPEC.md)+for the format.++## What a lens file looks like++```html+<!doctype html>+<html lang="en">+<head>+<meta charset="utf-8">+<script type="application/beacon-lens+json">+{ "id": "command-log", "title": "Command Log", "version": 1, "api": "beacon.lens.v1" }+</script>+</head>+<body>+<p id="status">Loading trace…</p>+<ol id="commands"></ol>+<script>+window.beacon.getTrace().then(function (data) {+ var list = document.getElementById("commands");+ data.trace.events.forEach(function (event) {+ if (!event.command) return;+ var item = document.createElement("li");+ item.textContent = event.command.command; // never innerHTML: trace content is untrusted+ list.appendChild(item);+ });+ document.getElementById("status").hidden = true;+});+</script>+</body>+</html>+```++## Limits++- A lens is one file of at most 16 MiB, with everything inline.+- A lens sees one trace. A view across several sessions is not supported yet.+- Lenses are local. The store is per user on this machine, and there is no hosted gallery+ or sharing; to share a lens, share the file.+- Very large traces are cut to fit: the lens receives the longest prefix of events that+ fits, and the data says it was truncated.diff --git a/docs/docs.json b/docs/docs.jsonindex ff22ae74..ee335d06 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -76,6 +76,7 @@"concepts/cross-harness-memory","concepts/beacon-skills","concepts/session-handoff",+ "concepts/lenses",{"group": "Unified Telemetry Schema","root": "telemetry-schema/event-schema",@@ -358,6 +359,7 @@]},"cli/handoff",+ "cli/lenses","cli/git","cli/token-usage","cli/version"