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
feat(lenses): lens store and `beacon lenses list|add|remove|show`
Claude49f99129e8da
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 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.txtfor forbidden in init update claude cursor dep-scan config; doif grep -E "^[[:space:]]+$forbidden([[:space:]]|$)" /tmp/beacon-help.txt; thenecho "forbidden command exposed: $forbidden"diff --git a/CLAUDE.md b/CLAUDE.mdindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 7a3c0657..40ed5bf0 100644--- a/cli/beacon/internal/endpoint/dashboard/lenses.go+++ b/cli/beacon/internal/endpoint/dashboard/lenses.go@@ -3,6 +3,7 @@ package dashboardimport ("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]lensorder []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))returndiff --git a/cli/beacon/internal/endpoint/dashboard/lenses_test.go b/cli/beacon/internal/endpoint/dashboard/lenses_test.goindex 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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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.goindex 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)+ }+ }+}