Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

feat(lenses): lens store and `beacon lenses list|add|remove|show`

Claude49f99129e8da
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ed0be190..7632ca9d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -257,6 +257,7 @@ jobs:
./beacon scan --help > /tmp/beacon-scan-help.txt
./beacon rules --help > /tmp/beacon-rules-help.txt
./beacon rules lint --help > /tmp/beacon-rules-lint-help.txt
+ ./beacon lenses --help > /tmp/beacon-lenses-help.txt
for forbidden in init update claude cursor dep-scan config; do
if grep -E "^[[:space:]]+$forbidden([[:space:]]|$)" /tmp/beacon-help.txt; then
echo "forbidden command exposed: $forbidden"
diff --git a/CLAUDE.md b/CLAUDE.md
index 93c445aa..82ca57c7 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`) 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. The `beacon lenses` CLI is not built yet.
+- `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.
- `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/cli/beacon/cmd/lenses.go b/cli/beacon/cmd/lenses.go
new file mode 100644
index 00000000..a4bb5904
--- /dev/null
+++ b/cli/beacon/cmd/lenses.go
@@ -0,0 +1,167 @@
+package cmd
+
+import (
+ "fmt"
+
+ "github.com/spf13/cobra"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lensstore"
+)
+
+var lensesOpts struct {
+ userMode bool
+ systemMode bool
+ force bool
+ json bool
+}
+
+func lensesUserMode() bool {
+ if lensesOpts.systemMode {
+ return false
+ }
+ return lensesOpts.userMode
+}
+
+var lensesCmd = &cobra.Command{
+ Use: "lenses",
+ Short: "Manage lenses: single-file views of a trace in the local dashboard",
+ Long: `Manage the local lens store (~/.beacon/endpoint/lenses).
+
+A lens is one HTML file that renders one trace. The dashboard ('beacon endpoint dashboard')
+shows lenses as tabs on a session's page, runs each in a sandboxed frame with no network,
+and hands it the trace through window.beacon.getTrace(). Beacon ships built-in lenses; the
+store holds the ones you add. The format is spec/lenses/SPEC.md.`,
+}
+
+// lensListEntry is one row of 'beacon lenses list --json'.
+type lensListEntry struct {
+ ID string `json:"id"`
+ Title string `json:"title"`
+ Description string `json:"description,omitempty"`
+ Version int `json:"version"`
+ Source string `json:"source"`
+ Path string `json:"path,omitempty"`
+}
+
+var lensesListCmd = &cobra.Command{
+ Use: "list",
+ Short: "List built-in and installed lenses",
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ builtins, err := dashboard.BuiltinLenses()
+ if err != nil {
+ return err
+ }
+ dir := lensesStoreDir()
+ stored, problems, err := lensstore.List(dir)
+ if err != nil {
+ return err
+ }
+ entries := make([]lensListEntry, 0, len(builtins)+len(stored))
+ for _, l := range builtins {
+ entries = append(entries, lensListEntry{ID: l.ID, Title: l.Title, Description: l.Description, Version: l.Version, Source: l.Source})
+ }
+ for _, l := range stored {
+ entries = append(entries, lensListEntry{ID: l.Manifest.ID, Title: l.Manifest.Title, Description: l.Manifest.Description, Version: l.Manifest.Version, Source: dashboard.LensSourceStore, Path: l.Path})
+ }
+ for _, p := range problems {
+ fmt.Fprintf(cmd.ErrOrStderr(), "warning: %s is not a valid lens and is ignored: %v\n", p.Path, p.Err)
+ }
+ out := cmd.OutOrStdout()
+ if lensesOpts.json {
+ return writeIndentedJSON(out, map[string]interface{}{"lenses": entries, "store": dir})
+ }
+ for _, e := range entries {
+ fmt.Fprintf(out, "%-24s v%-4d %-8s %s\n", e.ID, e.Version, e.Source, e.Title)
+ }
+ fmt.Fprintf(out, "\n%d lens(es). Store: %s\n", len(entries), dir)
+ return nil
+ },
+}
+
+var lensesAddCmd = &cobra.Command{
+ Use: "add <file>",
+ Short: "Install a lens file into the store",
+ Long: `Check a lens file against the spec and copy it into the store under its manifest id.
+
+Replacing an installed lens needs a higher manifest version, or --force. A built-in lens's
+id cannot be used. The dashboard picks the lens up on its next page load.`,
+ Args: cobra.ExactArgs(1),
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ reserved, err := dashboard.BuiltinLensIDs()
+ if err != nil {
+ return err
+ }
+ lens, replaced, err := lensstore.Install(lensesStoreDir(), args[0], lensstore.InstallOptions{Reserved: reserved, Force: lensesOpts.force})
+ if err != nil {
+ return err
+ }
+ out := cmd.OutOrStdout()
+ switch {
+ case replaced > 0:
+ fmt.Fprintf(out, "updated %s v%d -> v%d (%s)\n", lens.Manifest.ID, replaced, lens.Manifest.Version, lens.Path)
+ case replaced < 0:
+ fmt.Fprintf(out, "replaced an invalid file with %s v%d (%s)\n", lens.Manifest.ID, lens.Manifest.Version, lens.Path)
+ default:
+ fmt.Fprintf(out, "installed %s v%d (%s)\n", lens.Manifest.ID, lens.Manifest.Version, lens.Path)
+ }
+ return nil
+ },
+}
+
+var lensesRemoveCmd = &cobra.Command{
+ Use: "remove <id>",
+ Short: "Remove an installed lens by id",
+ Args: cobra.ExactArgs(1),
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ path, err := lensstore.Remove(lensesStoreDir(), args[0])
+ if err != nil {
+ return err
+ }
+ fmt.Fprintf(cmd.OutOrStdout(), "removed %s (%s)\n", args[0], path)
+ return nil
+ },
+}
+
+var lensesShowCmd = &cobra.Command{
+ Use: "show <id>",
+ Short: "Print a lens's manifest and where it comes from",
+ Args: cobra.ExactArgs(1),
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ id := args[0]
+ builtins, err := dashboard.BuiltinLenses()
+ if err != nil {
+ return err
+ }
+ for _, l := range builtins {
+ if l.ID == id {
+ return writeIndentedJSON(cmd.OutOrStdout(), map[string]interface{}{"manifest": l, "source": l.Source})
+ }
+ }
+ _, manifest, err := lensstore.Read(lensesStoreDir(), id)
+ if err != nil {
+ return fmt.Errorf("no lens %q: %w", id, err)
+ }
+ path, _ := lensstore.PathFor(lensesStoreDir(), id)
+ return writeIndentedJSON(cmd.OutOrStdout(), map[string]interface{}{"manifest": manifest, "source": dashboard.LensSourceStore, "path": path})
+ },
+}
+
+func lensesStoreDir() string {
+ return lensstore.Dir(lensesUserMode())
+}
+
+func init() {
+ for _, c := range []*cobra.Command{lensesListCmd, lensesAddCmd, lensesRemoveCmd, lensesShowCmd} {
+ c.Flags().BoolVar(&lensesOpts.userMode, "user", true, "Use per-user endpoint paths")
+ c.Flags().BoolVar(&lensesOpts.systemMode, "system", false, "Use system endpoint paths")
+ }
+ lensesListCmd.Flags().BoolVar(&lensesOpts.json, "json", false, "Print JSON")
+ lensesAddCmd.Flags().BoolVar(&lensesOpts.force, "force", false, "Replace an installed lens even when the new version is not higher")
+ lensesCmd.AddCommand(lensesListCmd, lensesAddCmd, lensesRemoveCmd, lensesShowCmd)
+ rootCmd.AddCommand(lensesCmd)
+}
diff --git a/cli/beacon/cmd/lenses_test.go b/cli/beacon/cmd/lenses_test.go
new file mode 100644
index 00000000..8ed54928
--- /dev/null
+++ b/cli/beacon/cmd/lenses_test.go
@@ -0,0 +1,126 @@
+package cmd
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lensstore"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+func writeTestLens(t *testing.T, dir, id string, version string) string {
+ t.Helper()
+ path := filepath.Join(dir, id+"-src.html")
+ html := `<!doctype html><script type="application/beacon-lens+json">{"id":"` + id + `","title":"Test ` + id +
+ `","version":` + version + `,"api":"beacon.lens.v1"}</script><script>window.beacon.getTrace()</script>`
+ if err := os.WriteFile(path, []byte(html), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
+
+func useLensTestHome(t *testing.T) {
+ t.Helper()
+ testenv.SetHome(t, t.TempDir())
+ prev := lensesOpts
+ lensesOpts.userMode, lensesOpts.systemMode, lensesOpts.force, lensesOpts.json = true, false, false, false
+ t.Cleanup(func() { lensesOpts = prev })
+}
+
+func TestLensesAddListShowRemove(t *testing.T) {
+ useLensTestHome(t)
+ src := t.TempDir()
+
+ cmd, buf := newCmd()
+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "mine", "1")}); err != nil {
+ t.Fatalf("add: %v", err)
+ }
+ if !strings.HasPrefix(buf.String(), "installed mine v1 (") {
+ t.Fatalf("add output = %q", buf.String())
+ }
+
+ cmd, buf = newCmd()
+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "mine", "2")}); err != nil || !strings.HasPrefix(buf.String(), "updated mine v1 -> v2") {
+ t.Fatalf("update = %v, %q", err, buf.String())
+ }
+ cmd, _ = newCmd()
+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "mine", "2")}); err == nil {
+ t.Fatal("reinstalling the same version without --force succeeded")
+ }
+
+ lensesOpts.json = true
+ cmd, buf = newCmd()
+ if err := lensesListCmd.RunE(cmd, nil); err != nil {
+ t.Fatal(err)
+ }
+ var listed struct {
+ Lenses []lensListEntry `json:"lenses"`
+ Store string `json:"store"`
+ }
+ if err := json.Unmarshal(buf.Bytes(), &listed); err != nil {
+ t.Fatalf("list --json: %v\n%s", err, buf.String())
+ }
+ sources := map[string]string{}
+ for _, l := range listed.Lenses {
+ sources[l.ID] = l.Source
+ }
+ if sources["mine"] != "store" || sources["activity"] != "builtin" || listed.Store != lensstore.Dir(true) {
+ t.Fatalf("list = %+v", listed)
+ }
+ lensesOpts.json = false
+
+ cmd, buf = newCmd()
+ if err := lensesShowCmd.RunE(cmd, []string{"mine"}); err != nil || !strings.Contains(buf.String(), `"version": 2`) || !strings.Contains(buf.String(), `"source": "store"`) {
+ t.Fatalf("show = %v, %s", err, buf.String())
+ }
+ cmd, buf = newCmd()
+ if err := lensesShowCmd.RunE(cmd, []string{"activity"}); err != nil || !strings.Contains(buf.String(), `"source": "builtin"`) {
+ t.Fatalf("show builtin = %v, %s", err, buf.String())
+ }
+
+ cmd, buf = newCmd()
+ if err := lensesRemoveCmd.RunE(cmd, []string{"mine"}); err != nil || !strings.HasPrefix(buf.String(), "removed mine") {
+ t.Fatalf("remove = %v, %q", err, buf.String())
+ }
+ cmd, _ = newCmd()
+ if err := lensesShowCmd.RunE(cmd, []string{"mine"}); err == nil {
+ t.Fatal("show found a removed lens")
+ }
+}
+
+func TestLensesAddRefusesBuiltinIDsAndInvalidFiles(t *testing.T) {
+ useLensTestHome(t)
+ src := t.TempDir()
+ cmd, _ := newCmd()
+ if err := lensesAddCmd.RunE(cmd, []string{writeTestLens(t, src, "files-changed", "1")}); err == nil || !strings.Contains(err.Error(), "built-in") {
+ t.Fatalf("built-in id = %v", err)
+ }
+ bad := filepath.Join(src, "bad.html")
+ if err := os.WriteFile(bad, []byte("<p>no manifest</p>"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if err := lensesAddCmd.RunE(cmd, []string{bad}); err == nil {
+ t.Fatal("an invalid lens installed")
+ }
+}
+
+func TestLensesListWarnsAboutBrokenStoreFiles(t *testing.T) {
+ useLensTestHome(t)
+ store := lensstore.Dir(true)
+ if err := os.MkdirAll(store, 0o700); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(filepath.Join(store, "junk.lens.html"), []byte("junk"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ cmd, buf := newCmd()
+ if err := lensesListCmd.RunE(cmd, nil); err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(buf.String(), "junk.lens.html is not a valid lens") || !strings.Contains(buf.String(), "activity") {
+ t.Fatalf("list output = %q", buf.String())
+ }
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/lenses.go b/cli/beacon/internal/endpoint/dashboard/lenses.go
index 7a3c0657..40ed5bf0 100644
--- a/cli/beacon/internal/endpoint/dashboard/lenses.go
+++ b/cli/beacon/internal/endpoint/dashboard/lenses.go
@@ -3,6 +3,7 @@ package dashboard
import (
"bytes"
"embed"
+ "errors"
"fmt"
"io/fs"
"net/http"
@@ -11,6 +12,7 @@ import (
"sort"
"strings"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lensstore"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
@@ -42,6 +44,8 @@ const (
LensSourceBuiltin = "builtin"
// LensSourceFile marks a lens read from a file named in Options.LensFiles.
LensSourceFile = "file"
+ // LensSourceStore marks a lens installed with `beacon lenses add`.
+ LensSourceStore = "store"
)
// LensInfo is one lens as the dashboard lists it.
@@ -68,6 +72,31 @@ type lens struct {
type lensRegistry struct {
byID map[string]lens
order []string
+ // storeDir is the lens store, read on every request so `beacon lenses add` and `remove` take
+ // effect without restarting the dashboard. A store lens never shadows a built-in or file lens.
+ storeDir string
+}
+
+// BuiltinLenses returns the lenses that ship in the binary, sorted by ID.
+func BuiltinLenses() ([]LensInfo, error) {
+ registry, err := loadBuiltinLenses(builtinLensFiles)
+ if err != nil {
+ return nil, err
+ }
+ return registry.list().Lenses, nil
+}
+
+// BuiltinLensIDs returns the IDs the built-in lenses hold, which the lens store may not use.
+func BuiltinLensIDs() (map[string]bool, error) {
+ builtins, err := BuiltinLenses()
+ if err != nil {
+ return nil, err
+ }
+ ids := make(map[string]bool, len(builtins))
+ for _, l := range builtins {
+ ids[l.ID] = true
+ }
+ return ids, nil
}
// loadBuiltinLenses reads every built-in lens. A built-in that breaks the spec is a build defect,
@@ -83,7 +112,7 @@ func loadBuiltinLenses(files fs.FS) (*lensRegistry, error) {
if err != nil {
return nil, err
}
- manifest, err := checkLensFile(html)
+ manifest, err := asymptoteobserve.CheckLensFile(html)
if err != nil {
return nil, fmt.Errorf("built-in lens %s: %w", name, err)
}
@@ -106,7 +135,7 @@ func (r *lensRegistry) addLensFiles(paths []string) error {
if err != nil {
return err
}
- manifest, err := checkLensFile(html)
+ manifest, err := asymptoteobserve.CheckLensFile(html)
if err != nil {
return fmt.Errorf("lens %s: %w", file, err)
}
@@ -127,18 +156,6 @@ func (r *lensRegistry) add(l lens) error {
return nil
}
-// checkLensFile applies the spec's file rules: the size cap and a valid manifest.
-func checkLensFile(html []byte) (asymptoteobserve.LensManifestV1, error) {
- if len(html) > asymptoteobserve.LensMaxBytes {
- return asymptoteobserve.LensManifestV1{}, fmt.Errorf("%d bytes is over the %d-byte limit", len(html), asymptoteobserve.LensMaxBytes)
- }
- manifest, err := asymptoteobserve.ParseLensManifest(html)
- if err != nil {
- return manifest, err
- }
- return manifest, manifest.Validate()
-}
-
func lensInfo(manifest asymptoteobserve.LensManifestV1, source string) LensInfo {
return LensInfo{
ID: manifest.ID,
@@ -160,7 +177,7 @@ func (l lens) document() ([]byte, error) {
if err != nil {
return nil, err
}
- manifest, err := checkLensFile(html)
+ manifest, err := asymptoteobserve.CheckLensFile(html)
if err != nil {
return nil, err
}
@@ -175,6 +192,15 @@ func (r *lensRegistry) list() LensListResponse {
for _, id := range r.order {
out.Lenses = append(out.Lenses, r.byID[id].info)
}
+ if r.storeDir != "" {
+ // A broken store file is left out here; `beacon lenses list` names it.
+ stored, _, _ := lensstore.List(r.storeDir)
+ for _, l := range stored {
+ if _, taken := r.byID[l.Manifest.ID]; !taken {
+ out.Lenses = append(out.Lenses, lensInfo(l.Manifest, LensSourceStore))
+ }
+ }
+ }
return out
}
@@ -214,12 +240,22 @@ func (r *lensRegistry) serveLensFrame(w http.ResponseWriter, req *http.Request)
return
}
id := strings.TrimPrefix(req.URL.Path, lensFramePrefix)
- found, ok := r.byID[id]
- if !ok {
+ var (
+ document []byte
+ err error
+ )
+ if found, ok := r.byID[id]; ok {
+ document, err = found.document()
+ } else if r.storeDir != "" && asymptoteobserve.ValidLensID(id) {
+ document, _, err = lensstore.Read(r.storeDir, id)
+ if errors.Is(err, os.ErrNotExist) {
+ http.NotFound(w, req)
+ return
+ }
+ } else {
http.NotFound(w, req)
return
}
- document, err := found.document()
if err != nil {
writeError(w, http.StatusInternalServerError, fmt.Errorf("lens %s: %w", id, err))
return
diff --git a/cli/beacon/internal/endpoint/dashboard/lenses_test.go b/cli/beacon/internal/endpoint/dashboard/lenses_test.go
index 415ee249..75dd2a9b 100644
--- a/cli/beacon/internal/endpoint/dashboard/lenses_test.go
+++ b/cli/beacon/internal/endpoint/dashboard/lenses_test.go
@@ -13,6 +13,9 @@ import (
"strings"
"testing"
"testing/fstest"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lensstore"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
)
// lensSpecDir locates spec/lenses from this file, so tests compare against what the spec publishes.
@@ -350,3 +353,53 @@ func TestLensFilesAreCheckedAtStartup(t *testing.T) {
})
}
}
+
+// Store lenses appear and disappear without a dashboard restart, and never shadow a built-in.
+func TestStoreLensesAreServedFromTheStore(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ store := lensstore.Dir(true)
+ handler := lensTestHandler(t)
+ listIDs := func() map[string]string {
+ var list LensListResponse
+ if err := json.Unmarshal(serve(handler, http.MethodGet, "/api/lenses").Body.Bytes(), &list); err != nil {
+ t.Fatal(err)
+ }
+ out := map[string]string{}
+ for _, l := range list.Lenses {
+ out[l.ID] = l.Source
+ }
+ return out
+ }
+
+ // Installed after the dashboard started.
+ src := writeLensFile(t, t.TempDir(), "mine", "<p>mine</p>")
+ if _, _, err := lensstore.Install(store, src, lensstore.InstallOptions{}); err != nil {
+ t.Fatal(err)
+ }
+ if got := listIDs(); got["mine"] != LensSourceStore || got["activity"] != LensSourceBuiltin {
+ t.Fatalf("lenses = %v", got)
+ }
+ rec := serve(handler, http.MethodGet, "/lenses/frame/mine")
+ if rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), "<p>mine</p>") || rec.Header().Get("Content-Security-Policy") != lensFrameCSP {
+ t.Fatalf("store lens = %d", rec.Code)
+ }
+
+ // A hand-placed store file with a built-in's id does not shadow it.
+ writeLensFile(t, store, "activity", "<p>impostor</p>")
+ if got := listIDs(); got["activity"] != LensSourceBuiltin {
+ t.Fatalf("activity source = %q", got["activity"])
+ }
+ if body := serve(handler, http.MethodGet, "/lenses/frame/activity").Body.String(); strings.Contains(body, "impostor") {
+ t.Fatal("a store file shadowed the built-in activity lens")
+ }
+
+ if _, err := lensstore.Remove(store, "mine"); err != nil {
+ t.Fatal(err)
+ }
+ if _, ok := listIDs()["mine"]; ok {
+ t.Fatal("a removed lens is still listed")
+ }
+ if rec := serve(handler, http.MethodGet, "/lenses/frame/mine"); rec.Code != http.StatusNotFound {
+ t.Fatalf("removed lens = %d, want 404", rec.Code)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/server.go b/cli/beacon/internal/endpoint/dashboard/server.go
index 1406c1ec..6a290f9c 100644
--- a/cli/beacon/internal/endpoint/dashboard/server.go
+++ b/cli/beacon/internal/endpoint/dashboard/server.go
@@ -16,6 +16,7 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/detect"
endpointhooks "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/inventory"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lensstore"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/tokens"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
@@ -100,6 +101,7 @@ func Handler(opts Options) (http.Handler, error) {
if err := lenses.addLensFiles(opts.LensFiles); err != nil {
return nil, err
}
+ lenses.storeDir = lensstore.Dir(rulesUserMode)
mux := http.NewServeMux()
mux.HandleFunc("/api/status", func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
diff --git a/cli/beacon/internal/endpoint/lensstore/lensstore.go b/cli/beacon/internal/endpoint/lensstore/lensstore.go
new file mode 100644
index 00000000..18d029a2
--- /dev/null
+++ b/cli/beacon/internal/endpoint/lensstore/lensstore.go
@@ -0,0 +1,181 @@
+// Package lensstore manages the local lens store: the lens files a user installed with
+// `beacon lenses add`, which the dashboard offers next to its built-in lenses.
+//
+// The store is a flat directory of <id>.lens.html files under the endpoint base directory. The
+// dashboard only reads it; every write goes through this package from the CLI, so the dashboard
+// stays read-only. A file is checked against spec/lenses/SPEC.md when it is installed and again
+// whenever it is read, because a person can edit the store by hand.
+package lensstore
+
+import (
+ "errors"
+ "fmt"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// FileSuffix is the extension every stored lens carries.
+const FileSuffix = ".lens.html"
+
+// Lens is one installed lens.
+type Lens struct {
+ Manifest asymptoteobserve.LensManifestV1
+ Path string
+}
+
+// Problem is a file in the store that is not a valid lens. Listing reports it instead of failing,
+// so one broken file does not hide every other lens.
+type Problem struct {
+ Path string
+ Err error
+}
+
+// Dir returns the store directory for the user or system endpoint.
+func Dir(userMode bool) string {
+ return filepath.Join(endpointconfig.BaseDir(userMode), "lenses")
+}
+
+// PathFor returns where the lens with id is stored. It refuses an ID that is not well formed, so a
+// caller can never be steered outside the store.
+func PathFor(dir, id string) (string, error) {
+ if !asymptoteobserve.ValidLensID(id) {
+ return "", fmt.Errorf("%q is not a lens id", id)
+ }
+ return filepath.Join(dir, id+FileSuffix), nil
+}
+
+// List returns the valid lenses in dir, sorted by ID, and the files that are not valid lenses. A
+// missing directory is an empty store.
+func List(dir string) ([]Lens, []Problem, error) {
+ entries, err := os.ReadDir(dir)
+ if errors.Is(err, os.ErrNotExist) {
+ return nil, nil, nil
+ }
+ if err != nil {
+ return nil, nil, err
+ }
+ var lenses []Lens
+ var problems []Problem
+ for _, entry := range entries {
+ if entry.IsDir() || !strings.HasSuffix(entry.Name(), FileSuffix) {
+ continue
+ }
+ path := filepath.Join(dir, entry.Name())
+ _, manifest, err := readFile(path, strings.TrimSuffix(entry.Name(), FileSuffix))
+ if err != nil {
+ problems = append(problems, Problem{Path: path, Err: err})
+ continue
+ }
+ lenses = append(lenses, Lens{Manifest: manifest, Path: path})
+ }
+ sort.Slice(lenses, func(i, j int) bool { return lenses[i].Manifest.ID < lenses[j].Manifest.ID })
+ return lenses, problems, nil
+}
+
+// Read returns the stored lens with id, checked again as it is read.
+func Read(dir, id string) ([]byte, asymptoteobserve.LensManifestV1, error) {
+ path, err := PathFor(dir, id)
+ if err != nil {
+ return nil, asymptoteobserve.LensManifestV1{}, err
+ }
+ return readFile(path, id)
+}
+
+// readFile checks a stored file and that it declares the ID its name promises.
+func readFile(path, id string) ([]byte, asymptoteobserve.LensManifestV1, error) {
+ html, err := os.ReadFile(path)
+ if err != nil {
+ return nil, asymptoteobserve.LensManifestV1{}, err
+ }
+ manifest, err := asymptoteobserve.CheckLensFile(html)
+ if err != nil {
+ return nil, manifest, err
+ }
+ if manifest.ID != id {
+ return nil, manifest, fmt.Errorf("file is named for %q but declares id %q", id, manifest.ID)
+ }
+ return html, manifest, nil
+}
+
+// InstallOptions controls Install.
+type InstallOptions struct {
+ // Reserved are IDs the store may not use: the dashboard's built-in lenses.
+ Reserved map[string]bool
+ // Force replaces an installed lens even when the new file's version is not newer.
+ Force bool
+}
+
+// Install checks the lens file at src and copies it into dir under its manifest ID. It returns
+// the installed lens and the version it replaced: 0 for a new lens, -1 when it replaced a file that
+// was not a valid lens. Replacing an installed lens
+// needs a newer version or Force, so reinstalling an old copy by mistake does not downgrade it.
+func Install(dir, src string, opts InstallOptions) (Lens, int, error) {
+ html, err := os.ReadFile(src)
+ if err != nil {
+ return Lens{}, 0, err
+ }
+ manifest, err := asymptoteobserve.CheckLensFile(html)
+ if err != nil {
+ return Lens{}, 0, fmt.Errorf("%s is not a valid lens: %w", src, err)
+ }
+ if opts.Reserved[manifest.ID] {
+ return Lens{}, 0, fmt.Errorf("%q is a built-in lens id; give this lens another id", manifest.ID)
+ }
+ dest, err := PathFor(dir, manifest.ID)
+ if err != nil {
+ return Lens{}, 0, err
+ }
+ replaced := 0
+ if _, current, err := readFile(dest, manifest.ID); err == nil {
+ replaced = current.Version
+ if !opts.Force && manifest.Version <= current.Version {
+ return Lens{}, 0, fmt.Errorf("lens %q version %d is already installed; bump the version or pass --force", manifest.ID, current.Version)
+ }
+ } else if _, statErr := os.Stat(dest); statErr == nil {
+ // An unreadable or invalid file is in the way. Replacing it is what the user asked for.
+ replaced = -1
+ }
+ if err := os.MkdirAll(dir, 0o700); err != nil {
+ return Lens{}, 0, err
+ }
+ tmp, err := os.CreateTemp(dir, ".install-*"+FileSuffix+".tmp")
+ if err != nil {
+ return Lens{}, 0, err
+ }
+ tmpPath := tmp.Name()
+ defer os.Remove(tmpPath)
+ if _, err := tmp.Write(html); err != nil {
+ tmp.Close()
+ return Lens{}, 0, err
+ }
+ if err := tmp.Close(); err != nil {
+ return Lens{}, 0, err
+ }
+ if err := os.Chmod(tmpPath, 0o600); err != nil {
+ return Lens{}, 0, err
+ }
+ if err := os.Rename(tmpPath, dest); err != nil {
+ return Lens{}, 0, err
+ }
+ return Lens{Manifest: manifest, Path: dest}, replaced, nil
+}
+
+// Remove deletes the stored lens with id and returns its path.
+func Remove(dir, id string) (string, error) {
+ path, err := PathFor(dir, id)
+ if err != nil {
+ return "", err
+ }
+ if err := os.Remove(path); err != nil {
+ if errors.Is(err, os.ErrNotExist) {
+ return "", fmt.Errorf("no installed lens %q in %s", id, dir)
+ }
+ return "", err
+ }
+ return path, nil
+}
diff --git a/cli/beacon/internal/endpoint/lensstore/lensstore_test.go b/cli/beacon/internal/endpoint/lensstore/lensstore_test.go
new file mode 100644
index 00000000..ee5176be
--- /dev/null
+++ b/cli/beacon/internal/endpoint/lensstore/lensstore_test.go
@@ -0,0 +1,155 @@
+package lensstore
+
+import (
+ "os"
+ "path/filepath"
+ "strconv"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+func lensFile(t *testing.T, dir, name, id string, version int) string {
+ t.Helper()
+ path := filepath.Join(dir, name)
+ html := `<!doctype html><script type="application/beacon-lens+json">{"id":"` + id + `","title":"T","version":` +
+ strconv.Itoa(version) + `,"api":"beacon.lens.v1"}</script><p>v` + strconv.Itoa(version) + `</p>`
+ if err := os.WriteFile(path, []byte(html), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
+
+func TestInstallListReadRemove(t *testing.T) {
+ src := t.TempDir()
+ store := filepath.Join(t.TempDir(), "lenses")
+
+ // The stored name comes from the manifest id, not the source file name.
+ lens, replaced, err := Install(store, lensFile(t, src, "whatever.html", "my-lens", 1), InstallOptions{})
+ if err != nil || replaced != 0 {
+ t.Fatalf("Install = %v, replaced %d", err, replaced)
+ }
+ if lens.Path != filepath.Join(store, "my-lens.lens.html") || lens.Manifest.ID != "my-lens" {
+ t.Fatalf("installed %+v", lens)
+ }
+ if testenv.HasPOSIXFileModes() {
+ if info, _ := os.Stat(store); info.Mode().Perm() != 0o700 {
+ t.Errorf("store mode = %v, want 0700", info.Mode().Perm())
+ }
+ if info, _ := os.Stat(lens.Path); info.Mode().Perm() != 0o600 {
+ t.Errorf("lens mode = %v, want 0600", info.Mode().Perm())
+ }
+ }
+
+ lenses, problems, err := List(store)
+ if err != nil || len(problems) != 0 || len(lenses) != 1 || lenses[0].Manifest.ID != "my-lens" {
+ t.Fatalf("List = %+v, %+v, %v", lenses, problems, err)
+ }
+ html, manifest, err := Read(store, "my-lens")
+ if err != nil || manifest.Version != 1 || !strings.Contains(string(html), "<p>v1</p>") {
+ t.Fatalf("Read = %v, %+v", err, manifest)
+ }
+
+ path, err := Remove(store, "my-lens")
+ if err != nil || path != lens.Path {
+ t.Fatalf("Remove = %q, %v", path, err)
+ }
+ if _, err := os.Stat(path); !os.IsNotExist(err) {
+ t.Fatal("removed lens still exists")
+ }
+ if _, err := Remove(store, "my-lens"); err == nil || !strings.Contains(err.Error(), "no installed lens") {
+ t.Fatalf("second Remove = %v", err)
+ }
+ // No temp files are left behind.
+ entries, _ := os.ReadDir(store)
+ if len(entries) != 0 {
+ t.Fatalf("store holds %d leftover entries", len(entries))
+ }
+}
+
+func TestInstallReplacesOnlyNewerVersionsUnlessForced(t *testing.T) {
+ src := t.TempDir()
+ store := t.TempDir()
+ if _, _, err := Install(store, lensFile(t, src, "a.html", "my-lens", 2), InstallOptions{}); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := Install(store, lensFile(t, src, "b.html", "my-lens", 2), InstallOptions{}); err == nil || !strings.Contains(err.Error(), "bump the version") {
+ t.Fatalf("same version = %v, want refusal", err)
+ }
+ if _, _, err := Install(store, lensFile(t, src, "c.html", "my-lens", 1), InstallOptions{}); err == nil {
+ t.Fatal("an older version replaced a newer one")
+ }
+ if _, replaced, err := Install(store, lensFile(t, src, "d.html", "my-lens", 3), InstallOptions{}); err != nil || replaced != 2 {
+ t.Fatalf("newer version = %v, replaced %d", err, replaced)
+ }
+ if _, replaced, err := Install(store, lensFile(t, src, "e.html", "my-lens", 1), InstallOptions{Force: true}); err != nil || replaced != 3 {
+ t.Fatalf("forced downgrade = %v, replaced %d", err, replaced)
+ }
+ if _, manifest, _ := Read(store, "my-lens"); manifest.Version != 1 {
+ t.Fatalf("stored version = %d, want the forced 1", manifest.Version)
+ }
+}
+
+func TestInstallRefusals(t *testing.T) {
+ src := t.TempDir()
+ store := t.TempDir()
+ if _, _, err := Install(store, lensFile(t, src, "a.html", "activity", 1), InstallOptions{Reserved: map[string]bool{"activity": true}}); err == nil || !strings.Contains(err.Error(), "built-in") {
+ t.Fatalf("reserved id = %v", err)
+ }
+ bad := filepath.Join(src, "bad.html")
+ if err := os.WriteFile(bad, []byte("<p>no manifest</p>"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := Install(store, bad, InstallOptions{}); err == nil || !strings.Contains(err.Error(), "not a valid lens") {
+ t.Fatalf("invalid lens = %v", err)
+ }
+ if _, _, err := Install(store, filepath.Join(src, "absent.html"), InstallOptions{}); err == nil {
+ t.Fatal("a missing file installed")
+ }
+}
+
+func TestListReportsBrokenFilesWithoutHidingTheRest(t *testing.T) {
+ store := t.TempDir()
+ lensFile(t, store, "good.lens.html", "good", 1)
+ lensFile(t, store, "renamed.lens.html", "other-id", 1) // name and id disagree
+ if err := os.WriteFile(filepath.Join(store, "junk.lens.html"), []byte("not a lens"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(filepath.Join(store, "notes.txt"), []byte("ignored"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ lenses, problems, err := List(store)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(lenses) != 1 || lenses[0].Manifest.ID != "good" {
+ t.Fatalf("lenses = %+v", lenses)
+ }
+ if len(problems) != 2 {
+ t.Fatalf("problems = %+v, want the renamed and junk files", problems)
+ }
+ if _, _, err := Read(store, "renamed"); err == nil || !strings.Contains(err.Error(), "declares id") {
+ t.Fatalf("Read of a misnamed file = %v", err)
+ }
+
+ missing, problems, err := List(filepath.Join(store, "absent"))
+ if err != nil || missing != nil || problems != nil {
+ t.Fatalf("missing store = %v, %v, %v", missing, problems, err)
+ }
+}
+
+func TestIDsCannotLeaveTheStore(t *testing.T) {
+ store := t.TempDir()
+ for _, id := range []string{"../escape", "a/b", `a\b`, "", ".hidden", "UPPER"} {
+ if _, err := PathFor(store, id); err == nil {
+ t.Errorf("PathFor(%q) accepted", id)
+ }
+ if _, _, err := Read(store, id); err == nil {
+ t.Errorf("Read(%q) accepted", id)
+ }
+ if _, err := Remove(store, id); err == nil {
+ t.Errorf("Remove(%q) accepted", id)
+ }
+ }
+}
diff --git a/pkg/asymptoteobserve/lens.go b/pkg/asymptoteobserve/lens.go
index b5e66cc9..ee61f998 100644
--- a/pkg/asymptoteobserve/lens.go
+++ b/pkg/asymptoteobserve/lens.go
@@ -174,6 +174,24 @@ func lensText(field, value string, maxRunes int, required bool) []error {
return problems
}
+// ValidLensID reports whether id is a well-formed lens ID. Callers that turn an ID into a file name
+// check it first, so an ID can never name a path outside the lens store.
+func ValidLensID(id string) bool { return lensIDPattern.MatchString(id) }
+
+// CheckLensFile applies the spec's file-level rules -- the size cap, exactly one manifest, and a
+// valid manifest -- and returns the manifest. Everything that installs, serves or lints a lens
+// uses it, so they cannot disagree about what a lens is.
+func CheckLensFile(html []byte) (LensManifestV1, error) {
+ if len(html) > LensMaxBytes {
+ return LensManifestV1{}, fmt.Errorf("lens is %d bytes, over the %d-byte limit", len(html), LensMaxBytes)
+ }
+ manifest, err := ParseLensManifest(html)
+ if err != nil {
+ return manifest, err
+ }
+ return manifest, manifest.Validate()
+}
+
// ParseLensManifest reads the manifest out of a lens file. It requires exactly one manifest
// element and decodes it strictly: an unknown field is an error, so a misspelled key is caught when
// the lens is linted rather than silently ignored. The result is not validated; call Validate.
diff --git a/pkg/asymptoteobserve/lens_test.go b/pkg/asymptoteobserve/lens_test.go
index 2bc5e771..c0a85ce0 100644
--- a/pkg/asymptoteobserve/lens_test.go
+++ b/pkg/asymptoteobserve/lens_test.go
@@ -286,3 +286,21 @@ func TestLensManifestSchemaInSync(t *testing.T) {
t.Errorf("api const: schema %q, Go %q", props["api"].Const, LensAPIVersion)
}
}
+
+func TestCheckLensFile(t *testing.T) {
+ good := []byte(`<script type="application/beacon-lens+json">{"id":"x","title":"X","version":1,"api":"beacon.lens.v1"}</script>`)
+ if m, err := CheckLensFile(good); err != nil || m.ID != "x" {
+ t.Fatalf("CheckLensFile(good) = %+v, %v", m, err)
+ }
+ if _, err := CheckLensFile([]byte(`<script type="application/beacon-lens+json">{"id":"X","title":"X","version":1,"api":"beacon.lens.v1"}</script>`)); err == nil {
+ t.Fatal("an invalid manifest passed")
+ }
+ if _, err := CheckLensFile(append(good, make([]byte, LensMaxBytes)...)); err == nil || !strings.Contains(err.Error(), "limit") {
+ t.Fatalf("an oversized lens passed: %v", err)
+ }
+ for id, want := range map[string]bool{"files-changed": true, "../etc": false, "a/b": false, "": false, "UP": false} {
+ if ValidLensID(id) != want {
+ t.Errorf("ValidLensID(%q) = %v", id, !want)
+ }
+ }
+}