Skip to content

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

Add inventory heartbeat telemetry

shukieshah245683ef28b7
diff --git a/README.md b/README.md
index e041fdbd..818a8ffa 100644
--- a/README.md
+++ b/README.md
@@ -147,7 +147,7 @@ management (SIEM), log aggregation, and object storage destinations.
| Destination | Support path |
| --- | --- |
-| [AWS S3](https://docs.asymptotelabs.ai/cli/siem-forwarding-s3) | Vector content pack over local JSONL using customer-managed AWS credentials |
+| [AWS S3](https://docs.asymptotelabs.ai/cli/siem-forwarding-s3) | Vector content pack over local runtime and inventory JSONL using customer-managed AWS credentials |
| [Google Cloud Storage](https://docs.asymptotelabs.ai/cli/siem-forwarding-gcs) | Vector content pack over local JSONL using customer-managed Google credentials |
#### Local
@@ -172,8 +172,9 @@ Beacon includes a local, read-only dashboard for validating endpoint activity
without a hosted backend. See the [dashboard docs](https://docs.asymptotelabs.ai/cli/dashboard)
for overview, log search, and runtime JSONL inspection.
-Beacon writes endpoint activity to `runtime.jsonl`; local log storage and
-retention behavior are summarized in the
+Beacon writes endpoint activity to `runtime.jsonl` and periodic Cursor/Claude
+Code configuration inventory metadata to the sibling `inventory_state.jsonl`.
+Local log storage and retention behavior are summarized in the
[local testing and logs docs](https://docs.asymptotelabs.ai/cli/local-testing-logs).
For offline threat detection, `beacon scan` runs open threat rules over local
diff --git a/cli/beacon-hooks/cmd/endpoint_events.go b/cli/beacon-hooks/cmd/endpoint_events.go
index 7d6e953a..8bcccd2f 100644
--- a/cli/beacon-hooks/cmd/endpoint_events.go
+++ b/cli/beacon-hooks/cmd/endpoint_events.go
@@ -6,6 +6,7 @@ import (
"encoding/hex"
"fmt"
"os"
+ "os/exec"
"path/filepath"
"strings"
"time"
@@ -14,6 +15,8 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
)
+var runInventoryHeartbeatCommand = exec.CommandContext
+
func emitHookEvent(logger *logging.Logger, action, category, severity, message string, input map[string]interface{}, fields map[string]interface{}) {
if fields == nil {
fields = map[string]interface{}{}
@@ -78,6 +81,55 @@ func maybeUploadCursorCloudTelemetry(logger *logging.Logger) {
uploadCloudTelemetry(logger, true)
}
+func maybeEmitInventoryHeartbeat(logger *logging.Logger, input map[string]interface{}) {
+ if platformFlag != "cursor" && platformFlag != "claude" {
+ return
+ }
+ cliPath := strings.TrimSpace(os.Getenv("BEACON_ENDPOINT_CLI"))
+ if cliPath == "" {
+ return
+ }
+ args := []string{"endpoint", "inventory", "heartbeat", "--trigger", "hook", "--trigger-harness", platformFlag}
+ if configPath := strings.TrimSpace(os.Getenv("BEACON_ENDPOINT_CONFIG")); configPath != "" {
+ args = append(args, "--config", configPath)
+ }
+ if logPath := inventoryEndpointLogPath(); logPath != "" {
+ args = append(args, "--log-path", logPath)
+ }
+ if cwd := resolveCwd(input, platformFlag); cwd != "" {
+ args = append(args, "--working-dir", cwd)
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+ defer cancel()
+ cmd := runInventoryHeartbeatCommand(ctx, cliPath, args...)
+ if out, err := cmd.CombinedOutput(); err != nil {
+ logger.Warn("Inventory heartbeat failed", "error", err.Error(), "output", strings.TrimSpace(string(out)))
+ }
+}
+
+func inventoryEndpointLogPath() string {
+ if path := firstHookEnv("BEACON_ENDPOINT_LOG", "BEACON_CLOUD_LOG_PATH", "BEACON_LOG_PATH", "BEACON_RUNTIME_LOG"); path != "" {
+ return path
+ }
+ if os.Getenv("BEACON_ENDPOINT_MODE") == "" {
+ return ""
+ }
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return ""
+ }
+ return filepath.Join(home, ".beacon", "endpoint", "logs", "runtime.jsonl")
+}
+
+func firstHookEnv(keys ...string) string {
+ for _, key := range keys {
+ if value := strings.TrimSpace(os.Getenv(key)); value != "" {
+ return value
+ }
+ }
+ return ""
+}
+
func sessionFields(sessionID string, input map[string]interface{}) map[string]interface{} {
fields := map[string]interface{}{}
session := map[string]interface{}{}
diff --git a/cli/beacon-hooks/cmd/endpoint_events_test.go b/cli/beacon-hooks/cmd/endpoint_events_test.go
new file mode 100644
index 00000000..082308ff
--- /dev/null
+++ b/cli/beacon-hooks/cmd/endpoint_events_test.go
@@ -0,0 +1,84 @@
+package cmd
+
+import (
+ "context"
+ "os"
+ "os/exec"
+ "reflect"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon-hooks/internal/logging"
+)
+
+func TestMaybeEmitInventoryHeartbeatInvokesBeaconCLI(t *testing.T) {
+ oldPlatform := platformFlag
+ oldRunner := runInventoryHeartbeatCommand
+ defer func() {
+ platformFlag = oldPlatform
+ runInventoryHeartbeatCommand = oldRunner
+ }()
+ platformFlag = "cursor"
+ t.Setenv("BEACON_ENDPOINT_CLI", "/usr/local/bin/beacon")
+ t.Setenv("BEACON_ENDPOINT_CONFIG", "/tmp/beacon/config.json")
+ t.Setenv("BEACON_ENDPOINT_LOG", "/tmp/beacon/runtime.jsonl")
+
+ var gotName string
+ var gotArgs []string
+ runInventoryHeartbeatCommand = func(ctx context.Context, name string, args ...string) *exec.Cmd {
+ gotName = name
+ gotArgs = append([]string(nil), args...)
+ cmd := exec.CommandContext(ctx, os.Args[0], "-test.run=TestInventoryHeartbeatCommandHelperProcess")
+ cmd.Env = append(os.Environ(), "GO_WANT_INVENTORY_HELPER_PROCESS=1")
+ return cmd
+ }
+
+ logger := logging.NewLoggerForPlatform("test", "cursor")
+ maybeEmitInventoryHeartbeat(logger, map[string]interface{}{"cwd": "/repo"})
+
+ if gotName != "/usr/local/bin/beacon" {
+ t.Fatalf("command name = %q, want beacon path", gotName)
+ }
+ wantArgs := []string{
+ "endpoint", "inventory", "heartbeat",
+ "--trigger", "hook",
+ "--trigger-harness", "cursor",
+ "--config", "/tmp/beacon/config.json",
+ "--log-path", "/tmp/beacon/runtime.jsonl",
+ "--working-dir", "/repo",
+ }
+ if !reflect.DeepEqual(gotArgs, wantArgs) {
+ t.Fatalf("args = %#v, want %#v", gotArgs, wantArgs)
+ }
+}
+
+func TestMaybeEmitInventoryHeartbeatSkipsUnsupportedPlatform(t *testing.T) {
+ oldPlatform := platformFlag
+ oldRunner := runInventoryHeartbeatCommand
+ defer func() {
+ platformFlag = oldPlatform
+ runInventoryHeartbeatCommand = oldRunner
+ }()
+ platformFlag = "codex"
+ t.Setenv("BEACON_ENDPOINT_CLI", "/usr/local/bin/beacon")
+ called := false
+ runInventoryHeartbeatCommand = func(ctx context.Context, name string, args ...string) *exec.Cmd {
+ called = true
+ cmd := exec.CommandContext(ctx, os.Args[0], "-test.run=TestInventoryHeartbeatCommandHelperProcess")
+ cmd.Env = append(os.Environ(), "GO_WANT_INVENTORY_HELPER_PROCESS=1")
+ return cmd
+ }
+
+ logger := logging.NewLoggerForPlatform("test", "codex")
+ maybeEmitInventoryHeartbeat(logger, map[string]interface{}{"cwd": "/repo"})
+
+ if called {
+ t.Fatal("inventory heartbeat command should not run for unsupported platform")
+ }
+}
+
+func TestInventoryHeartbeatCommandHelperProcess(t *testing.T) {
+ if os.Getenv("GO_WANT_INVENTORY_HELPER_PROCESS") != "1" {
+ return
+ }
+ os.Exit(0)
+}
diff --git a/cli/beacon-hooks/cmd/prompt_submit.go b/cli/beacon-hooks/cmd/prompt_submit.go
index 95542594..0cb5456d 100644
--- a/cli/beacon-hooks/cmd/prompt_submit.go
+++ b/cli/beacon-hooks/cmd/prompt_submit.go
@@ -40,6 +40,7 @@ func runPromptSubmit(cmd *cobra.Command, args []string) {
}
logger.Debug("Prompt submit observed")
+ maybeEmitInventoryHeartbeat(logger, input)
fields := sessionFields(sessionID, input)
if isCascadePlatform(platformFlag) {
fields = cascadeMetadataFields(sessionID, input)
diff --git a/cli/beacon-hooks/cmd/session_start.go b/cli/beacon-hooks/cmd/session_start.go
index ab8b4047..d5fbc34f 100644
--- a/cli/beacon-hooks/cmd/session_start.go
+++ b/cli/beacon-hooks/cmd/session_start.go
@@ -35,6 +35,7 @@ func runSessionStart(cmd *cobra.Command, args []string) {
if err := cloudshuttle.ResetFromEnv(); err != nil {
platformLogger.Warn("Failed to reset cloud telemetry log", "error", err.Error())
}
+ maybeEmitInventoryHeartbeat(platformLogger, input)
if sessionID == "" {
if isDevinLikePlatform(platformFlag) {
logger := logging.NewLoggerForPlatform("session-start", platformFlag)
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index 15fdc24b..f420af04 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -415,10 +415,11 @@ Beacon endpoint configuration.
```
The S3 pack keeps Beacon as a local JSONL producer and documents forwarding
-`runtime.jsonl` into an AWS S3 bucket with a customer-managed Vector host agent.
-Store AWS credentials, profiles, IAM roles, bucket policies, lifecycle rules,
-and encryption settings in AWS, Vector, or deployment tooling, not in Beacon
-endpoint configuration.
+`runtime.jsonl` and the sibling `inventory_state.jsonl` into separate
+`runtime/` and `inventory/` S3 prefixes with a customer-managed Vector host
+agent. Store AWS credentials, profiles, IAM roles, bucket policies, lifecycle
+rules, and encryption settings in AWS, Vector, or deployment tooling, not in
+Beacon endpoint configuration.
## AWS CloudWatch Logs
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index 9fb53f39..2e1bbdce 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -70,6 +70,11 @@ var endpointOpts struct {
includeEventSummaries bool
includeRawEvents bool
writeInventoryEvent bool
+ inventoryHeartbeatForce bool
+ inventoryHeartbeatConfig string
+ inventoryWorkingDir string
+ inventoryTrigger string
+ inventoryTriggerHarness string
}
var endpointCmd = &cobra.Command{
@@ -93,6 +98,14 @@ var endpointInventoryCmd = &cobra.Command{
RunE: runEndpointInventory,
}
+var endpointInventoryHeartbeatCmd = &cobra.Command{
+ Use: "heartbeat",
+ Short: "Write endpoint inventory heartbeat events",
+ Hidden: true,
+ SilenceUsage: true,
+ RunE: runEndpointInventoryHeartbeat,
+}
+
var endpointTestEventCmd = &cobra.Command{
Use: "test-event",
Aliases: []string{"validate-pipeline"},
@@ -349,6 +362,7 @@ func init() {
endpointCmd.AddCommand(endpointIntegrationsCmd)
endpointCmd.AddCommand(endpointHooksCmd)
endpointCmd.AddCommand(endpointConfigCmd)
+ endpointInventoryCmd.AddCommand(endpointInventoryHeartbeatCmd)
endpointConfigCmd.AddCommand(endpointConfigShowCmd)
endpointConfigCmd.AddCommand(endpointConfigValidateCmd)
endpointIntegrationsCmd.AddCommand(endpointIntegrationsValidateCmd)
@@ -370,7 +384,7 @@ func init() {
endpointVSCodeCmd.AddCommand(endpointVSCodeStatusCmd)
endpointVSCodeCmd.AddCommand(endpointVSCodeValidateCmd)
- for _, c := range []*cobra.Command{endpointInstallCmd, endpointStatusCmd, endpointDoctorCmd, endpointInventoryCmd, endpointDiscoverCmd, endpointTestEventCmd, endpointBundleDiagnosticsCmd, endpointUninstallCmd, endpointRepairCmd, endpointConfigShowCmd, endpointConfigValidateCmd, endpointIntegrationsValidateCmd, topLevelDoctorCmd, topLevelStatusCmd, topLevelInventoryCmd} {
+ for _, c := range []*cobra.Command{endpointInstallCmd, endpointStatusCmd, endpointDoctorCmd, endpointInventoryCmd, endpointInventoryHeartbeatCmd, endpointDiscoverCmd, endpointTestEventCmd, endpointBundleDiagnosticsCmd, endpointUninstallCmd, endpointRepairCmd, endpointConfigShowCmd, endpointConfigValidateCmd, endpointIntegrationsValidateCmd, topLevelDoctorCmd, topLevelStatusCmd, topLevelInventoryCmd} {
c.Flags().BoolVar(&endpointOpts.userMode, "user", true, "Use per-user endpoint paths")
c.Flags().BoolVar(&endpointOpts.systemMode, "system", false, "Use system endpoint paths and launch daemon")
c.Flags().StringVar(&endpointOpts.logPath, "log-path", "", "Runtime JSONL log path")
@@ -416,6 +430,12 @@ func init() {
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print inventory as JSON")
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.allTargets, "all", false, "Include all supported targets")
endpointInventoryCmd.Flags().BoolVar(&endpointOpts.writeInventoryEvent, "write-event", false, "Append inventory events to the endpoint runtime log")
+ endpointInventoryHeartbeatCmd.Flags().BoolVar(&endpointOpts.inventoryHeartbeatForce, "force", false, "Write inventory heartbeat even when TTL has not expired")
+ endpointInventoryHeartbeatCmd.Flags().StringVar(&endpointOpts.inventoryHeartbeatConfig, "config", "", "Endpoint config path")
+ endpointInventoryHeartbeatCmd.Flags().StringVar(&endpointOpts.inventoryWorkingDir, "working-dir", "", "Working directory for project inventory")
+ endpointInventoryHeartbeatCmd.Flags().StringVar(&endpointOpts.inventoryTrigger, "trigger", "manual", "Inventory trigger source")
+ endpointInventoryHeartbeatCmd.Flags().StringVar(&endpointOpts.inventoryTriggerHarness, "trigger-harness", "", "Harness that triggered inventory")
+ endpointInventoryHeartbeatCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print heartbeat result as JSON")
topLevelDoctorCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print doctor results as JSON")
topLevelDoctorCmd.Flags().BoolVar(&endpointOpts.fix, "fix", false, "Apply safe endpoint doctor remediations")
topLevelStatusCmd.Flags().BoolVar(&endpointOpts.jsonOutput, "json", false, "Print status as JSON")
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.go
index e1882ecd..d9cd17c9 100644
--- a/cli/beacon/cmd/endpoint_diagnostics.go
+++ b/cli/beacon/cmd/endpoint_diagnostics.go
@@ -324,64 +324,174 @@ func runEndpointInventory(cmd *cobra.Command, args []string) error {
}
func writeInventoryEvents(cfg endpointconfig.Config, result endpointinventory.Result) error {
- for _, config := range result.Configs {
- if !config.Exists {
- continue
- }
- servers := mcpServersForConfig(result.MCPServers, config)
- event := schema.NewEvent(schema.NewEventOptions{
- Action: "config.inventory",
- Category: "inventory",
- Severity: schema.SeverityInfo,
- AgentVersion: version.GetVersion(),
- Harness: schema.HarnessInfo{
- Name: config.Runtime,
- ConfigPath: config.Path,
- },
- Message: fmt.Sprintf("%s config inventory observed", config.Runtime),
- })
- event.Raw = map[string]interface{}{
- "inventory": map[string]interface{}{
- "config": config,
- "mcp_servers": servers,
- },
- }
- if _, err := writer.AppendEvent(event, writer.Options{Path: cfg.LogPath, UserMode: cfg.UserMode}); err != nil {
- return err
- }
+ settings := endpointconfig.InventoryConfig(cfg)
+ _, err := writeInventorySnapshotEvents(cfg, settings, result, "manual", "", true, endpointinventory.State{})
+ return err
+}
+
+type inventoryHeartbeatWriteResult struct {
+ Written bool `json:"written"`
+ SnapshotWritten bool `json:"snapshot_written"`
+ SkippedReason string `json:"skipped_reason,omitempty"`
+ SnapshotDigest string `json:"snapshot_digest,omitempty"`
+ PreviousDigest string `json:"previous_snapshot_digest,omitempty"`
+}
+
+func runEndpointInventoryHeartbeat(cmd *cobra.Command, args []string) error {
+ cfg, err := loadInventoryHeartbeatConfig(endpointUserMode(), endpointOpts.logPath, endpointOpts.inventoryHeartbeatConfig)
+ if err != nil {
+ return err
}
- for _, skill := range result.Skills {
- if !skill.Exists {
- continue
- }
- event := schema.NewEvent(schema.NewEventOptions{
- Action: "skill.inventory",
- Category: "inventory",
- Severity: schema.SeverityInfo,
- AgentVersion: version.GetVersion(),
- Harness: schema.HarnessInfo{
- Name: skill.Runtime,
- ConfigPath: skill.ManifestPath,
- },
- Message: fmt.Sprintf("%s skill inventory observed", skill.Runtime),
- })
- event.Raw = map[string]interface{}{
- "inventory": map[string]interface{}{
- "skill": skill,
- },
- }
- if _, err := writer.AppendEvent(event, writer.Options{Path: cfg.LogPath, UserMode: cfg.UserMode}); err != nil {
- return err
+ settings := endpointconfig.InventoryConfig(cfg)
+ result, err := writeInventoryHeartbeat(cfg, settings, endpointOpts.inventoryHeartbeatForce, endpointOpts.inventoryWorkingDir, endpointOpts.inventoryTrigger, endpointOpts.inventoryTriggerHarness)
+ if endpointOpts.jsonOutput {
+ _ = json.NewEncoder(os.Stdout).Encode(result)
+ }
+ return err
+}
+
+func loadInventoryHeartbeatConfig(userMode bool, logPath, configPath string) (endpointconfig.Config, error) {
+ if configPath == "" {
+ return loadConfigForMode(userMode, logPath), nil
+ }
+ data, err := os.ReadFile(configPath)
+ if err != nil {
+ return endpointconfig.Config{}, err
+ }
+ var cfg endpointconfig.Config
+ if err := json.Unmarshal(data, &cfg); err != nil {
+ return endpointconfig.Config{}, err
+ }
+ endpointconfig.NormalizeDestinations(&cfg)
+ if err := endpointconfig.ValidateDestinations(cfg.Destinations); err != nil {
+ return endpointconfig.Config{}, err
+ }
+ if logPath != "" {
+ cfg.LogPath = logPath
+ }
+ if cfg.LogPath == "" {
+ cfg.LogPath = writer.DefaultPath(cfg.UserMode)
+ }
+ return cfg, nil
+}
+
+func writeInventoryHeartbeat(cfg endpointconfig.Config, settings endpointconfig.InventorySettings, force bool, workingDir, trigger, triggerHarness string) (inventoryHeartbeatWriteResult, error) {
+ if !settings.Enabled && !force {
+ return inventoryHeartbeatWriteResult{SkippedReason: "disabled"}, nil
+ }
+ now := time.Now().UTC()
+ statePath := endpointinventory.StatePathForLog(cfg.LogPath, cfg.UserMode)
+ locked, state, err := endpointinventory.LockState(statePath)
+ if err != nil {
+ return inventoryHeartbeatWriteResult{}, err
+ }
+ defer locked.Close()
+ if !force && !endpointinventory.TTLExpired(state, now, settings.TTLSeconds) {
+ return inventoryHeartbeatWriteResult{SkippedReason: "ttl_active", PreviousDigest: state.LastSnapshotDigest}, nil
+ }
+ scanOpts := endpointinventory.Options{
+ WorkingDir: workingDir,
+ Runtimes: settings.Runtimes,
+ Now: func() time.Time { return now },
+ }
+ inventoryResult := endpointinventory.Scan(scanOpts)
+ writeResult, err := writeInventorySnapshotEvents(cfg, settings, inventoryResult, trigger, triggerHarness, state.LastSnapshotDigest != endpointinventory.SnapshotDigest(inventoryResult), state)
+ if err != nil {
+ return writeResult, err
+ }
+ if err := locked.Save(endpointinventory.State{
+ LastEmittedAt: now.Format(time.RFC3339),
+ LastSnapshotDigest: writeResult.SnapshotDigest,
+ }); err != nil {
+ return writeResult, err
+ }
+ return writeResult, nil
+}
+
+func writeInventorySnapshotEvents(cfg endpointconfig.Config, settings endpointconfig.InventorySettings, result endpointinventory.Result, trigger, triggerHarness string, writeSnapshot bool, state endpointinventory.State) (inventoryHeartbeatWriteResult, error) {
+ digest := endpointinventory.SnapshotDigest(result)
+ previousDigest := state.LastSnapshotDigest
+ counts := endpointinventory.CountsFor(result)
+ inventoryMeta := map[string]interface{}{
+ "generated_at": result.GeneratedAt,
+ "runtimes": settings.Runtimes,
+ "trigger": trigger,
+ "trigger_harness": triggerHarness,
+ "ttl_seconds": settings.TTLSeconds,
+ "snapshot_digest": digest,
+ "previous_snapshot_digest": previousDigest,
+ "counts": counts,
+ }
+ if previousDigest == "" {
+ inventoryMeta["change_reason"] = "initial"
+ } else if previousDigest != digest {
+ inventoryMeta["change_reason"] = "changed"
+ } else {
+ inventoryMeta["change_reason"] = "unchanged"
+ }
+ heartbeat := schema.NewEvent(schema.NewEventOptions{
+ Action: "inventory.heartbeat",
+ Category: "inventory",
+ Severity: schema.SeverityInfo,
+ AgentVersion: version.GetVersion(),
+ Harness: schema.HarnessInfo{Name: "endpoint"},
+ Message: "Agent configuration inventory heartbeat observed",
+ })
+ heartbeat.Raw = map[string]interface{}{"inventory": inventoryMeta}
+ inventoryLogPath := endpointinventory.LogPath(cfg.LogPath, cfg.UserMode)
+ if _, err := writer.AppendEvent(heartbeat, writer.Options{Path: inventoryLogPath, UserMode: cfg.UserMode}); err != nil {
+ return inventoryHeartbeatWriteResult{SnapshotDigest: digest, PreviousDigest: previousDigest}, err
+ }
+ out := inventoryHeartbeatWriteResult{Written: true, SnapshotDigest: digest, PreviousDigest: previousDigest}
+ if !writeSnapshot && previousDigest != "" {
+ return out, nil
+ }
+ snapshot := schema.NewEvent(schema.NewEventOptions{
+ Action: "inventory.snapshot",
+ Category: "inventory",
+ Severity: schema.SeverityInfo,
+ AgentVersion: version.GetVersion(),
+ Harness: schema.HarnessInfo{Name: "endpoint"},
+ Message: "Agent configuration inventory snapshot observed",
+ })
+ snapshot.Raw = map[string]interface{}{
+ "inventory": map[string]interface{}{
+ "generated_at": result.GeneratedAt,
+ "runtimes": settings.Runtimes,
+ "trigger": trigger,
+ "trigger_harness": triggerHarness,
+ "ttl_seconds": settings.TTLSeconds,
+ "snapshot_digest": digest,
+ "previous_snapshot_digest": previousDigest,
+ "counts": counts,
+ "user_scope": result.UserScope,
+ "configs": existingInventoryConfigs(result.Configs),
+ "mcp_servers": result.MCPServers,
+ "skills": existingInventorySkills(result.Skills),
+ },
+ }
+ if _, err := writer.AppendEvent(snapshot, writer.Options{Path: inventoryLogPath, UserMode: cfg.UserMode}); err != nil {
+ return out, err
+ }
+ out.SnapshotWritten = true
+ return out, nil
+}
+
+func existingInventoryConfigs(configs []endpointinventory.Config) []endpointinventory.Config {
+ out := make([]endpointinventory.Config, 0, len(configs))
+ for _, config := range configs {
+ if config.Exists {
+ out = append(out, config)
}
}
- return nil
+ return out
}
-func mcpServersForConfig(servers []endpointinventory.MCPServer, config endpointinventory.Config) []endpointinventory.MCPServer {
- out := []endpointinventory.MCPServer{}
- for _, server := range servers {
- if server.Runtime == config.Runtime && server.SourcePathHash == config.PathHash {
- out = append(out, server)
+func existingInventorySkills(skills []endpointinventory.Skill) []endpointinventory.Skill {
+ out := make([]endpointinventory.Skill, 0, len(skills))
+ for _, skill := range skills {
+ if skill.Exists {
+ out = append(out, skill)
}
}
return out
diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.go
index a2502bf4..9e23b6dd 100644
--- a/cli/beacon/cmd/endpoint_test.go
+++ b/cli/beacon/cmd/endpoint_test.go
@@ -713,7 +713,7 @@ func TestRobustEndpointCommandsRegistered(t *testing.T) {
}
}
-func TestWriteInventoryEventsAppendsConfigInventory(t *testing.T) {
+func TestWriteInventoryEventsAppendsInventorySnapshot(t *testing.T) {
logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
cfg := endpointconfig.Default(true, logPath)
result := endpointinventory.Result{
@@ -778,16 +778,20 @@ func TestWriteInventoryEventsAppendsConfigInventory(t *testing.T) {
if err := writeInventoryEvents(cfg, result); err != nil {
t.Fatalf("writeInventoryEvents returned error: %v", err)
}
- data, err := os.ReadFile(logPath)
+ if data, err := os.ReadFile(logPath); err == nil && strings.Contains(string(data), "inventory.") {
+ t.Fatalf("runtime log should not contain inventory events: %s", string(data))
+ }
+ inventoryLogPath := endpointinventory.LogPath(logPath, cfg.UserMode)
+ data, err := os.ReadFile(inventoryLogPath)
if err != nil {
t.Fatal(err)
}
text := string(data)
- if strings.Count(text, "config.inventory") != 1 {
- t.Fatalf("inventory events = %d, want 1; log=%s", strings.Count(text, "config.inventory"), text)
+ if strings.Count(text, "inventory.heartbeat") != 1 {
+ t.Fatalf("heartbeat events = %d, want 1; log=%s", strings.Count(text, "inventory.heartbeat"), text)
}
- if strings.Count(text, "skill.inventory") != 1 {
- t.Fatalf("skill inventory events = %d, want 1; log=%s", strings.Count(text, "skill.inventory"), text)
+ if strings.Count(text, "inventory.snapshot") != 1 {
+ t.Fatalf("snapshot events = %d, want 1; log=%s", strings.Count(text, "inventory.snapshot"), text)
}
if !strings.Contains(text, "filesystem") {
t.Fatalf("inventory log missing MCP server summary: %s", text)
@@ -800,6 +804,74 @@ func TestWriteInventoryEventsAppendsConfigInventory(t *testing.T) {
}
}
+func TestInventoryHeartbeatTTLAndSnapshotDigest(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ work := t.TempDir()
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ writeTestFile(t, filepath.Join(home, ".cursor", "mcp.json"), `{"mcpServers":{"one":{"command":"npx"}}}`)
+ cfg := endpointconfig.Default(true, logPath)
+ enabled := true
+ cfg.Inventory = &endpointconfig.Inventory{Enabled: &enabled, TTLSeconds: 86400, Runtimes: []string{"cursor", "claude_code"}}
+ settings := endpointconfig.InventoryConfig(cfg)
+
+ first, err := writeInventoryHeartbeat(cfg, settings, false, work, "hook", "cursor")
+ if err != nil {
+ t.Fatalf("first heartbeat returned error: %v", err)
+ }
+ if !first.Written || !first.SnapshotWritten || first.SnapshotDigest == "" {
+ t.Fatalf("first heartbeat = %#v, want heartbeat and snapshot", first)
+ }
+ second, err := writeInventoryHeartbeat(cfg, settings, false, work, "hook", "cursor")
+ if err != nil {
+ t.Fatalf("second heartbeat returned error: %v", err)
+ }
+ if second.Written || second.SkippedReason != "ttl_active" {
+ t.Fatalf("second heartbeat = %#v, want TTL skip", second)
+ }
+ forced, err := writeInventoryHeartbeat(cfg, settings, true, work, "hook", "cursor")
+ if err != nil {
+ t.Fatalf("forced heartbeat returned error: %v", err)
+ }
+ if !forced.Written || forced.SnapshotWritten {
+ t.Fatalf("forced unchanged heartbeat = %#v, want heartbeat only", forced)
+ }
+
+ writeTestFile(t, filepath.Join(home, ".cursor", "mcp.json"), `{"mcpServers":{"one":{"command":"npx"},"two":{"command":"uvx"}}}`)
+ changed, err := writeInventoryHeartbeat(cfg, settings, true, work, "hook", "cursor")
+ if err != nil {
+ t.Fatalf("changed heartbeat returned error: %v", err)
+ }
+ if !changed.Written || !changed.SnapshotWritten || changed.SnapshotDigest == forced.SnapshotDigest {
+ t.Fatalf("changed heartbeat = %#v, want new snapshot digest", changed)
+ }
+
+ if data, err := os.ReadFile(logPath); err == nil && strings.Contains(string(data), "inventory.") {
+ t.Fatalf("runtime log should not contain inventory events: %s", string(data))
+ }
+ inventoryLogPath := endpointinventory.LogPath(logPath, cfg.UserMode)
+ data, err := os.ReadFile(inventoryLogPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ text := string(data)
+ if strings.Count(text, "inventory.heartbeat") != 3 {
+ t.Fatalf("heartbeat count = %d, want 3; log=%s", strings.Count(text, "inventory.heartbeat"), text)
+ }
+ if strings.Count(text, "inventory.snapshot") != 2 {
+ t.Fatalf("snapshot count = %d, want 2; log=%s", strings.Count(text, "inventory.snapshot"), text)
+ }
+ if !strings.Contains(text, `"server_name":"two"`) {
+ t.Fatalf("changed snapshot missing new MCP server: %s", text)
+ }
+ if _, err := os.Stat(filepath.Join(filepath.Dir(logPath), "inventory-state.json")); err != nil {
+ t.Fatalf("inventory state should live beside inventory log: %v", err)
+ }
+ if _, err := os.Stat(filepath.Join(home, ".beacon", "endpoint", "inventory-state.json")); !os.IsNotExist(err) {
+ t.Fatalf("inventory state should not use endpoint config base, err=%v", err)
+ }
+}
+
func TestTopLevelAliasesRegistered(t *testing.T) {
for _, name := range []string{"doctor", "status", "inventory"} {
cmd, _, err := rootCmd.Find([]string{name})
@@ -815,6 +887,16 @@ func TestTopLevelAliasesRegistered(t *testing.T) {
}
}
+func writeTestFile(t *testing.T, path, content string) {
+ t.Helper()
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(path, []byte(content), 0600); err != nil {
+ t.Fatal(err)
+ }
+}
+
func TestRobustCLIFlagsRegistered(t *testing.T) {
for _, cmd := range []*cobra.Command{endpointInstallCmd, endpointRepairCmd, endpointUninstallCmd, endpointHooksInstallCmd, endpointHooksUninstallCmd} {
if cmd.Flags().Lookup("dry-run") == nil {
diff --git a/cli/beacon/internal/endpoint/config/config.go b/cli/beacon/internal/endpoint/config/config.go
index 340a5d3e..ee17708a 100644
--- a/cli/beacon/internal/endpoint/config/config.go
+++ b/cli/beacon/internal/endpoint/config/config.go
@@ -27,6 +27,7 @@ type Config struct {
Collector Collector `json:"collector"`
Harnesses []string `json:"harnesses"`
EventCategories []string `json:"event_categories,omitempty"`
+ Inventory *Inventory `json:"inventory_heartbeat,omitempty"`
Destinations *Destinations `json:"destinations,omitempty"`
ManagedUpload *ManagedUpload `json:"managed_upload,omitempty"`
}
@@ -41,6 +42,18 @@ type Collector struct {
IncludeCodexSpans bool `json:"include_codex_spans,omitempty"`
}
+type Inventory struct {
+ Enabled *bool `json:"enabled,omitempty"`
+ TTLSeconds int `json:"ttl_seconds,omitempty"`
+ Runtimes []string `json:"runtimes,omitempty"`
+}
+
+type InventorySettings struct {
+ Enabled bool
+ TTLSeconds int
+ Runtimes []string
+}
+
type Destinations struct {
SplunkHEC *SplunkHEC `json:"splunk_hec,omitempty"`
FalconHEC *FalconHEC `json:"falcon_hec,omitempty"`
@@ -91,6 +104,31 @@ func Default(userMode bool, logPath string) Config {
}
}
+func InventoryDefaults() InventorySettings {
+ return InventorySettings{
+ Enabled: true,
+ TTLSeconds: 24 * 60 * 60,
+ Runtimes: []string{"cursor", "claude_code"},
+ }
+}
+
+func InventoryConfig(cfg Config) InventorySettings {
+ settings := InventoryDefaults()
+ if cfg.Inventory == nil {
+ return settings
+ }
+ if cfg.Inventory.Enabled != nil {
+ settings.Enabled = *cfg.Inventory.Enabled
+ }
+ if cfg.Inventory.TTLSeconds > 0 {
+ settings.TTLSeconds = cfg.Inventory.TTLSeconds
+ }
+ if len(cfg.Inventory.Runtimes) > 0 {
+ settings.Runtimes = append([]string(nil), cfg.Inventory.Runtimes...)
+ }
+ return settings
+}
+
func BaseDir(userMode bool) string {
if userMode {
home, err := os.UserHomeDir()
diff --git a/cli/beacon/internal/endpoint/config/config_test.go b/cli/beacon/internal/endpoint/config/config_test.go
index c23a80b3..e0f52474 100644
--- a/cli/beacon/internal/endpoint/config/config_test.go
+++ b/cli/beacon/internal/endpoint/config/config_test.go
@@ -28,6 +28,10 @@ func TestDefaultUserConfigUsesHomeScopedPaths(t *testing.T) {
if len(cfg.Harnesses) != 2 || cfg.Harnesses[0] != "claude" || cfg.Harnesses[1] != "codex" {
t.Fatalf("unexpected default harnesses: %#v", cfg.Harnesses)
}
+ inventory := InventoryConfig(cfg)
+ if !inventory.Enabled || inventory.TTLSeconds != 86400 || len(inventory.Runtimes) != 2 || inventory.Runtimes[0] != "cursor" || inventory.Runtimes[1] != "claude_code" {
+ t.Fatalf("unexpected inventory defaults: %#v", inventory)
+ }
}
func TestSaveLoadRoundTrip(t *testing.T) {
@@ -40,6 +44,8 @@ func TestSaveLoadRoundTrip(t *testing.T) {
cfg.Collector.IncludeRuntimeMetrics = true
cfg.Collector.IncludeCodexSpans = true
cfg.EventCategories = []string{"tool", "session"}
+ enabled := true
+ cfg.Inventory = &Inventory{Enabled: &enabled, TTLSeconds: 30, Runtimes: []string{"cursor"}}
path, err := Save(cfg)
if err != nil {
@@ -68,6 +74,10 @@ func TestSaveLoadRoundTrip(t *testing.T) {
if len(loaded.EventCategories) != 2 || loaded.EventCategories[1] != "session" {
t.Fatalf("EventCategories did not round-trip: %#v", loaded.EventCategories)
}
+ inventory := InventoryConfig(loaded)
+ if !inventory.Enabled || inventory.TTLSeconds != 30 || len(inventory.Runtimes) != 1 || inventory.Runtimes[0] != "cursor" {
+ t.Fatalf("Inventory did not round-trip: %#v", inventory)
+ }
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read saved config: %v", err)
diff --git a/cli/beacon/internal/endpoint/hooks/runtime.go b/cli/beacon/internal/endpoint/hooks/runtime.go
index 9c9b1e3e..557c92f4 100644
--- a/cli/beacon/internal/endpoint/hooks/runtime.go
+++ b/cli/beacon/internal/endpoint/hooks/runtime.go
@@ -111,7 +111,11 @@ func isRuntimeInstalled(runtime hookRuntime, opts RuntimeOptions) bool {
}
func endpointCommandPrefix(platform, binaryPath, logPath, configPath string) string {
- return fmt.Sprintf("BEACON_ENDPOINT_MODE=1 BEACON_ENDPOINT_LOG=%s BEACON_ENDPOINT_CONFIG=%s %s --platform %s", shellQuote(logPath), shellQuote(configPath), shellQuote(binaryPath), platform)
+ cliEnv := ""
+ if cliPath, err := os.Executable(); err == nil && cliPath != "" {
+ cliEnv = " BEACON_ENDPOINT_CLI=" + shellQuote(cliPath)
+ }
+ return fmt.Sprintf("BEACON_ENDPOINT_MODE=1 BEACON_ENDPOINT_LOG=%s BEACON_ENDPOINT_CONFIG=%s%s %s --platform %s", shellQuote(logPath), shellQuote(configPath), cliEnv, shellQuote(binaryPath), platform)
}
func isEndpointHookCommand(command, platform string) bool {
diff --git a/cli/beacon/internal/endpoint/inventory/heartbeat.go b/cli/beacon/internal/endpoint/inventory/heartbeat.go
new file mode 100644
index 00000000..a888e4db
--- /dev/null
+++ b/cli/beacon/internal/endpoint/inventory/heartbeat.go
@@ -0,0 +1,195 @@
+package inventory
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "syscall"
+ "time"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+)
+
+const stateFileName = "inventory-state.json"
+const LogFileName = "inventory_state.jsonl"
+
+type Counts struct {
+ Configs int `json:"configs"`
+ MCPServers int `json:"mcp_servers"`
+ Skills int `json:"skills"`
+}
+
+type State struct {
+ LastEmittedAt string `json:"last_emitted_at,omitempty"`
+ LastSnapshotDigest string `json:"last_snapshot_digest,omitempty"`
+}
+
+type LockedState struct {
+ path string
+ file *os.File
+}
+
+func StatePath(userMode bool) string {
+ return filepath.Join(endpointconfig.BaseDir(userMode), stateFileName)
+}
+
+func StatePathForLog(runtimeLogPath string, userMode bool) string {
+ return filepath.Join(filepath.Dir(LogPath(runtimeLogPath, userMode)), stateFileName)
+}
+
+func LogPath(runtimeLogPath string, userMode bool) string {
+ if runtimeLogPath != "" {
+ return filepath.Join(filepath.Dir(runtimeLogPath), LogFileName)
+ }
+ if userMode {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return filepath.Join(".", ".beacon", "endpoint", "logs", LogFileName)
+ }
+ return filepath.Join(home, ".beacon", "endpoint", "logs", LogFileName)
+ }
+ return filepath.Join("/var/log", "beacon-agent", LogFileName)
+}
+
+func LockState(path string) (*LockedState, State, error) {
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ return nil, State{}, err
+ }
+ file, err := os.OpenFile(path+".lock", os.O_CREATE|os.O_RDWR, 0644)
+ if err != nil {
+ return nil, State{}, err
+ }
+ if err := syscall.Flock(int(file.Fd()), syscall.LOCK_EX); err != nil {
+ _ = file.Close()
+ return nil, State{}, err
+ }
+ state, err := ReadState(path)
+ if err != nil {
+ _ = syscall.Flock(int(file.Fd()), syscall.LOCK_UN)
+ _ = file.Close()
+ return nil, State{}, err
+ }
+ return &LockedState{path: path, file: file}, state, nil
+}
+
+func (s *LockedState) Save(state State) error {
+ if s == nil {
+ return nil
+ }
+ data, err := json.MarshalIndent(state, "", " ")
+ if err != nil {
+ return err
+ }
+ if err := os.MkdirAll(filepath.Dir(s.path), 0755); err != nil {
+ return err
+ }
+ return os.WriteFile(s.path, data, 0644)
+}
+
+func (s *LockedState) Close() error {
+ if s == nil || s.file == nil {
+ return nil
+ }
+ unlockErr := syscall.Flock(int(s.file.Fd()), syscall.LOCK_UN)
+ closeErr := s.file.Close()
+ if unlockErr != nil {
+ return unlockErr
+ }
+ return closeErr
+}
+
+func ReadState(path string) (State, error) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return State{}, nil
+ }
+ return State{}, err
+ }
+ var state State
+ if err := json.Unmarshal(data, &state); err != nil {
+ return State{}, err
+ }
+ return state, nil
+}
+
+func CountsFor(result Result) Counts {
+ return Counts{
+ Configs: countExistingConfigs(result.Configs),
+ MCPServers: len(result.MCPServers),
+ Skills: countExistingSkills(result.Skills),
+ }
+}
+
+func SnapshotDigest(result Result) string {
+ payload := struct {
+ Configs []Config `json:"configs"`
+ MCPServers []MCPServer `json:"mcp_servers"`
+ Skills []Skill `json:"skills"`
+ UserScope UserScope `json:"user_scope"`
+ }{
+ Configs: existingConfigs(result.Configs),
+ MCPServers: result.MCPServers,
+ Skills: existingSkills(result.Skills),
+ UserScope: result.UserScope,
+ }
+ data, err := json.Marshal(payload)
+ if err != nil {
+ return hashString(result.GeneratedAt)
+ }
+ sum := sha256.Sum256(data)
+ return "sha256:" + hex.EncodeToString(sum[:])
+}
+
+func TTLExpired(state State, now time.Time, ttlSeconds int) bool {
+ if ttlSeconds <= 0 || state.LastEmittedAt == "" {
+ return true
+ }
+ last, err := time.Parse(time.RFC3339, state.LastEmittedAt)
+ if err != nil {
+ return true
+ }
+ return !now.Before(last.Add(time.Duration(ttlSeconds) * time.Second))
+}
+
+func existingConfigs(configs []Config) []Config {
+ out := make([]Config, 0, len(configs))
+ for _, config := range configs {
+ if config.Exists {
+ out = append(out, config)
+ }
+ }
+ return out
+}
+
+func existingSkills(skills []Skill) []Skill {
+ out := make([]Skill, 0, len(skills))
+ for _, skill := range skills {
+ if skill.Exists {
+ out = append(out, skill)
+ }
+ }
+ return out
+}
+
+func countExistingConfigs(configs []Config) int {
+ count := 0
+ for _, config := range configs {
+ if config.Exists {
+ count++
+ }
+ }
+ return count
+}
+
+func countExistingSkills(skills []Skill) int {
+ count := 0
+ for _, skill := range skills {
+ if skill.Exists {
+ count++
+ }
+ }
+ return count
+}
diff --git a/cli/beacon/internal/endpoint/inventory/inventory.go b/cli/beacon/internal/endpoint/inventory/inventory.go
index f9a694a5..68d10f9d 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory.go
@@ -54,6 +54,7 @@ const (
type Options struct {
HomeDir string
WorkingDir string
+ Runtimes []string
Now func() time.Time
}
@@ -143,15 +144,43 @@ func Scan(opts Options) Result {
WorkDirHash: hashString(wd),
},
}
- for _, item := range candidates(home, wd) {
+ for _, item := range filterCandidates(candidates(home, wd), opts.Runtimes) {
config, servers := inspectCandidate(item, redaction)
result.Configs = append(result.Configs, config)
result.MCPServers = append(result.MCPServers, servers...)
}
- result.Skills = scanSkills(home, wd, redaction)
+ result.Skills = scanSkills(home, wd, redaction, opts.Runtimes)
return result
}
+func filterCandidates(items []candidate, runtimes []string) []candidate {
+ allowed := runtimeSet(runtimes)
+ if len(allowed) == 0 {
+ return items
+ }
+ out := make([]candidate, 0, len(items))
+ for _, item := range items {
+ if allowed[item.runtime] {
+ out = append(out, item)
+ }
+ }
+ return out
+}
+
+func runtimeSet(runtimes []string) map[string]bool {
+ if len(runtimes) == 0 {
+ return nil
+ }
+ out := map[string]bool{}
+ for _, runtime := range runtimes {
+ runtime = strings.TrimSpace(runtime)
+ if runtime != "" {
+ out[runtime] = true
+ }
+ }
+ return out
+}
+
func candidates(home, wd string) []candidate {
items := []candidate{}
items = append(items, claudeCandidates(home, wd)...)
diff --git a/cli/beacon/internal/endpoint/inventory/inventory_test.go b/cli/beacon/internal/endpoint/inventory/inventory_test.go
index c07a5baa..0c8afde1 100644
--- a/cli/beacon/internal/endpoint/inventory/inventory_test.go
+++ b/cli/beacon/internal/endpoint/inventory/inventory_test.go
@@ -106,6 +106,47 @@ func TestScanIncludesNamesAndPaths(t *testing.T) {
}
}
+func TestScanFiltersRuntimes(t *testing.T) {
+ home := t.TempDir()
+ work := t.TempDir()
+ writeFile(t, filepath.Join(home, ".claude", "settings.json"), `{"mcpServers":{"filesystem":{"command":"npx"}}}`)
+ writeFile(t, filepath.Join(home, ".codex", "config.toml"), `[mcp_servers.github]
+command = "gh"
+`)
+ writeFile(t, filepath.Join(home, ".cursor", "mcp.json"), `{"mcpServers":{"remote":{"url":"https://example.test/sse"}}}`)
+ writeFile(t, filepath.Join(home, ".cursor", "skills", "direct", "SKILL.md"), "# Direct")
+ writeFile(t, filepath.Join(home, ".agents", "skills", "agent", "SKILL.md"), "# Agent")
+
+ result := Scan(Options{
+ HomeDir: home,
+ WorkingDir: work,
+ Runtimes: []string{"cursor", "claude_code"},
+ Now: fixedNow,
+ })
+
+ for _, config := range result.Configs {
+ if config.Runtime != "cursor" && config.Runtime != "claude_code" {
+ t.Fatalf("unexpected config runtime after filter: %#v", config)
+ }
+ }
+ for _, server := range result.MCPServers {
+ if server.Runtime != "cursor" && server.Runtime != "claude_code" {
+ t.Fatalf("unexpected MCP runtime after filter: %#v", server)
+ }
+ }
+ for _, skill := range result.Skills {
+ if skill.Runtime != "cursor" && skill.Runtime != "claude_code" {
+ t.Fatalf("unexpected skill runtime after filter: %#v", skill)
+ }
+ }
+ if assertServerPresent(result.MCPServers, "codex_cli", "github") {
+ t.Fatalf("codex server should be filtered out: %#v", result.MCPServers)
+ }
+ if findSkill(result.Skills, "agent_skills", "agent", filepath.Join(home, ".agents", "skills", "agent", "SKILL.md")) != nil {
+ t.Fatalf("agent_skills root should be filtered out: %#v", result.Skills)
+ }
+}
+
func TestScanKeepsPartialResultsWhenAConfigIsMalformed(t *testing.T) {
home := t.TempDir()
work := t.TempDir()
@@ -424,6 +465,16 @@ func TestSkillScanIsBoundedToDirectSkillManifests(t *testing.T) {
}
}
+func TestInventoryLogAndStatePathsFollowRuntimeLog(t *testing.T) {
+ runtimeLog := filepath.Join("/tmp", "beacon", "runtime.jsonl")
+ if got, want := LogPath(runtimeLog, true), filepath.Join("/tmp", "beacon", "inventory_state.jsonl"); got != want {
+ t.Fatalf("LogPath = %q, want %q", got, want)
+ }
+ if got, want := StatePathForLog(runtimeLog, true), filepath.Join("/tmp", "beacon", "inventory-state.json"); got != want {
+ t.Fatalf("StatePathForLog = %q, want %q", got, want)
+ }
+}
+
func fixedNow() time.Time {
return time.Date(2026, 6, 5, 7, 0, 0, 0, time.UTC)
}
@@ -466,6 +517,15 @@ func assertServer(t *testing.T, servers []MCPServer, runtime, name, transport st
t.Fatalf("server %s/%s not found in %#v", runtime, name, servers)
}
+func assertServerPresent(servers []MCPServer, runtime, name string) bool {
+ for _, server := range servers {
+ if server.Runtime == runtime && server.ServerName == name {
+ return true
+ }
+ }
+ return false
+}
+
func findConfig(configs []Config, runtime, path string) *Config {
pathHash := hashString(path)
for i := range configs {
diff --git a/cli/beacon/internal/endpoint/inventory/skills.go b/cli/beacon/internal/endpoint/inventory/skills.go
index 6727f4c7..73b63468 100644
--- a/cli/beacon/internal/endpoint/inventory/skills.go
+++ b/cli/beacon/internal/endpoint/inventory/skills.go
@@ -33,14 +33,28 @@ type skillRoot struct {
scope string
}
-func scanSkills(home, wd, redaction string) []Skill {
+func scanSkills(home, wd, redaction string, runtimes []string) []Skill {
var skills []Skill
- for _, root := range skillRoots(home, wd) {
+ for _, root := range filterSkillRoots(skillRoots(home, wd), runtimes) {
skills = append(skills, inspectSkillRoot(root, redaction)...)
}
return dedupeSkills(skills)
}
+func filterSkillRoots(items []skillRoot, runtimes []string) []skillRoot {
+ allowed := runtimeSet(runtimes)
+ if len(allowed) == 0 {
+ return items
+ }
+ out := make([]skillRoot, 0, len(items))
+ for _, item := range items {
+ if allowed[item.runtime] {
+ out = append(out, item)
+ }
+ }
+ return out
+}
+
func skillRoots(home, wd string) []skillRoot {
items := []skillRoot{
{runtime: "claude_code", path: filepath.Join(home, ".claude", "skills"), scope: ScopeUser},
diff --git a/cli/beacon/internal/endpoint/s3/pack/README.md b/cli/beacon/internal/endpoint/s3/pack/README.md
index b506ec04..49a46051 100644
--- a/cli/beacon/internal/endpoint/s3/pack/README.md
+++ b/cli/beacon/internal/endpoint/s3/pack/README.md
@@ -1,7 +1,8 @@
# Beacon Endpoint Agent AWS S3 Pack
This pack forwards Beacon endpoint JSONL events into an AWS S3 bucket. Beacon
-still writes one local source of truth: `runtime.jsonl`. AWS credentials,
+writes runtime activity to `runtime.jsonl` and configuration inventory telemetry
+to `inventory_state.jsonl`. AWS credentials,
profiles, IAM roles, bucket policies, object lifecycle rules, and server-side
encryption stay in AWS, Vector, or customer-managed deployment tooling, not in
Beacon endpoint configuration.
@@ -9,7 +10,7 @@ Beacon endpoint configuration.
## Prerequisites
- Beacon endpoint installed and writing local JSONL.
-- An AWS S3 bucket for Beacon runtime logs.
+- An AWS S3 bucket for Beacon runtime and inventory logs.
- An IAM role or credentials available through the standard AWS credential
provider chain for the process running Vector or the AWS CLI smoke test.
@@ -17,6 +18,7 @@ Recommended S3 layout:
```text
s3://example-security-logs/beacon/runtime/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
+s3://example-security-logs/beacon/inventory/date=YYYY-MM-DD/<timestamp>-<uuid>.jsonl.gz
```
Example least-privilege IAM policy for a dedicated Beacon prefix:
@@ -28,7 +30,7 @@ Example least-privilege IAM policy for a dedicated Beacon prefix:
{
"Effect": "Allow",
"Action": ["s3:PutObject"],
- "Resource": "arn:aws:s3:::example-security-logs/beacon/runtime/*"
+ "Resource": "arn:aws:s3:::example-security-logs/beacon/*"
}
]
}
@@ -53,11 +55,18 @@ CLI:
- System mode: `/var/log/beacon-agent/runtime.jsonl`
- Custom mode: the value passed with `--log-path`
+The generated Vector config also tails the sibling inventory log:
+
+- User mode: `~/.beacon/endpoint/logs/inventory_state.jsonl`
+- System mode: `/var/log/beacon-agent/inventory_state.jsonl`
+- Custom mode: `inventory_state.jsonl` in the same directory as `--log-path`
+
For MDM or managed endpoint deployment, prefer Beacon system mode so your
customer-managed log shipper can tail `/var/log/beacon-agent/runtime.jsonl`
without per-user home directory ACLs.
-The generated `vector.toml` uses the same selected Beacon log path.
+The generated `vector.toml` uses the selected Beacon runtime log path and the
+derived sibling inventory log path.
## One-Shot Smoke Test
@@ -67,7 +76,7 @@ whole file every time.
```bash
export BEACON_S3_BUCKET="example-security-logs"
-export BEACON_S3_PREFIX="beacon/runtime"
+export BEACON_S3_PREFIX="beacon"
export AWS_REGION="us-east-1"
./beacon-s3-pack/s3-upload-smoke-test.sh
```
@@ -83,26 +92,28 @@ runtime state.
Confirm the uploaded object:
```bash
-aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/smoke-tests/" --region "$AWS_REGION"
-aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/smoke-tests/<object>.jsonl" - --region "$AWS_REGION" | grep "Beacon endpoint S3 validation event"
+aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/smoke-tests/" --region "$AWS_REGION"
+aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/smoke-tests/<object>.jsonl" - --region "$AWS_REGION" | grep "Beacon endpoint S3 validation event"
```
## Production Forwarding
For production, use the generated Vector config as a customer-managed host-agent
forwarding template. Beacon remains the local JSONL producer; Vector tails
-`runtime.jsonl`, checkpoints file offsets in its `data_dir`, batches Beacon
-events, and writes gzip-compressed newline-delimited JSON objects into AWS S3.
+`runtime.jsonl` and `inventory_state.jsonl`, checkpoints file offsets in its
+`data_dir`, batches Beacon events, and writes gzip-compressed newline-delimited
+JSON objects into AWS S3.
Install Vector using your normal endpoint management tooling, then copy the
generated config into Vector's config directory. On a macOS system-mode Beacon
-deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl`:
+deployment, the generated config tails `/var/log/beacon-agent/runtime.jsonl` and
+`/var/log/beacon-agent/inventory_state.jsonl`:
```bash
sudo mkdir -p /etc/vector
sudo cp ./beacon-s3-pack/vector.toml /etc/vector/beacon-s3.toml
export BEACON_S3_BUCKET="example-security-logs"
-export BEACON_S3_PREFIX="beacon/runtime"
+export BEACON_S3_PREFIX="beacon"
export AWS_REGION="us-east-1"
vector validate /etc/vector/beacon-s3.toml
vector --config /etc/vector/beacon-s3.toml
@@ -123,7 +134,9 @@ destination secrets in Beacon endpoint configuration or `s3-vector.toml`.
The Vector template is intentionally simple and expects a Vector version with
the `file` source, `remap` transform, and `aws_s3` sink. It parses each Beacon
JSONL line and re-encodes the original Beacon event as NDJSON so S3 receives one
-Beacon event per line, without a Vector wrapper.
+Beacon event per line, without a Vector wrapper. Runtime activity is written
+under `${BEACON_S3_PREFIX}/runtime/date=.../`; inventory telemetry is written
+under `${BEACON_S3_PREFIX}/inventory/date=.../`.
The template uses date-partitioned `key_prefix`, `filename_time_format = "%s"`,
and `filename_append_uuid = true` so production forwarding does not overwrite
@@ -152,8 +165,8 @@ new line. Beacon can write the local validation event, but remote delivery must
be confirmed with AWS tooling:
```bash
-aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/" --recursive --region "$AWS_REGION"
-aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/date=<date>/<object>.jsonl.gz" - --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
+aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/" --recursive --region "$AWS_REGION"
+aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" - --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
```
Expected validation fields:
diff --git a/cli/beacon/internal/endpoint/s3/pack/s3-upload-smoke-test.sh.tmpl b/cli/beacon/internal/endpoint/s3/pack/s3-upload-smoke-test.sh.tmpl
index c5b7de09..0359648a 100644
--- a/cli/beacon/internal/endpoint/s3/pack/s3-upload-smoke-test.sh.tmpl
+++ b/cli/beacon/internal/endpoint/s3/pack/s3-upload-smoke-test.sh.tmpl
@@ -2,7 +2,8 @@
set -eu
BEACON_LOG="${BEACON_LOG:-{{LOG_PATH}}}"
-BEACON_S3_PREFIX="${BEACON_S3_PREFIX:-beacon/runtime}"
+BEACON_INVENTORY_LOG="${BEACON_INVENTORY_LOG:-{{INVENTORY_LOG_PATH}}}"
+BEACON_S3_PREFIX="${BEACON_S3_PREFIX:-beacon}"
AWS_REGION="${AWS_REGION:-us-east-1}"
if [ -z "${BEACON_S3_BUCKET:-}" ]; then
@@ -22,12 +23,23 @@ fi
prefix="${BEACON_S3_PREFIX%/}"
timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
-key="${prefix}/smoke-tests/beacon-runtime-${timestamp}.jsonl"
+runtime_key="${prefix}/runtime/smoke-tests/beacon-runtime-${timestamp}.jsonl"
-aws s3 cp "$BEACON_LOG" "s3://${BEACON_S3_BUCKET}/${key}" \
+aws s3 cp "$BEACON_LOG" "s3://${BEACON_S3_BUCKET}/${runtime_key}" \
--region "$AWS_REGION" \
--content-type "application/x-ndjson"
-echo "Uploaded one-shot Beacon log copy to s3://${BEACON_S3_BUCKET}/${key}"
+echo "Uploaded one-shot Beacon runtime log copy to s3://${BEACON_S3_BUCKET}/${runtime_key}"
+
+if [ -r "$BEACON_INVENTORY_LOG" ]; then
+ inventory_key="${prefix}/inventory/smoke-tests/beacon-inventory-${timestamp}.jsonl"
+ aws s3 cp "$BEACON_INVENTORY_LOG" "s3://${BEACON_S3_BUCKET}/${inventory_key}" \
+ --region "$AWS_REGION" \
+ --content-type "application/x-ndjson"
+ echo "Uploaded one-shot Beacon inventory log copy to s3://${BEACON_S3_BUCKET}/${inventory_key}"
+else
+ echo "Beacon inventory log is not readable yet, skipping optional upload: $BEACON_INVENTORY_LOG"
+fi
+
echo "AWS credentials were resolved by the standard AWS credential provider chain."
echo "This script is for validation only; use vector.toml for production forwarding."
diff --git a/cli/beacon/internal/endpoint/s3/pack/vector.toml.tmpl b/cli/beacon/internal/endpoint/s3/pack/vector.toml.tmpl
index dbbf445c..6454fb47 100644
--- a/cli/beacon/internal/endpoint/s3/pack/vector.toml.tmpl
+++ b/cli/beacon/internal/endpoint/s3/pack/vector.toml.tmpl
@@ -11,19 +11,60 @@ type = "file"
include = ["{{LOG_PATH}}"]
read_from = "end"
-[transforms.beacon_json]
+[sources.beacon_inventory]
+type = "file"
+include = ["{{INVENTORY_LOG_PATH}}"]
+read_from = "end"
+
+[transforms.beacon_runtime_json]
type = "remap"
inputs = ["beacon_runtime"]
source = '''
. = parse_json!(.message)
'''
-[sinks.beacon_s3]
+[transforms.beacon_inventory_json]
+type = "remap"
+inputs = ["beacon_inventory"]
+source = '''
+. = parse_json!(.message)
+'''
+
+[sinks.beacon_runtime_s3]
+type = "aws_s3"
+inputs = ["beacon_runtime_json"]
+bucket = "${BEACON_S3_BUCKET}"
+region = "${AWS_REGION:-us-east-1}"
+key_prefix = "${BEACON_S3_PREFIX:-beacon}/runtime/date=%F/"
+filename_time_format = "%s"
+filename_append_uuid = true
+filename_extension = "jsonl.gz"
+compression = "gzip"
+content_encoding = "gzip"
+content_type = "application/x-ndjson"
+storage_class = "${BEACON_S3_STORAGE_CLASS:-STANDARD}"
+
+[sinks.beacon_runtime_s3.encoding]
+codec = "json"
+
+[sinks.beacon_runtime_s3.framing]
+method = "newline_delimited"
+
+[sinks.beacon_runtime_s3.batch]
+max_bytes = 10000000
+timeout_secs = 300
+
+[sinks.beacon_runtime_s3.request]
+retry_attempts = 10
+retry_initial_backoff_secs = 1
+retry_max_duration_secs = 300
+
+[sinks.beacon_inventory_s3]
type = "aws_s3"
-inputs = ["beacon_json"]
+inputs = ["beacon_inventory_json"]
bucket = "${BEACON_S3_BUCKET}"
region = "${AWS_REGION:-us-east-1}"
-key_prefix = "${BEACON_S3_PREFIX:-beacon/runtime}/date=%F/"
+key_prefix = "${BEACON_S3_PREFIX:-beacon}/inventory/date=%F/"
filename_time_format = "%s"
filename_append_uuid = true
filename_extension = "jsonl.gz"
@@ -32,17 +73,17 @@ content_encoding = "gzip"
content_type = "application/x-ndjson"
storage_class = "${BEACON_S3_STORAGE_CLASS:-STANDARD}"
-[sinks.beacon_s3.encoding]
+[sinks.beacon_inventory_s3.encoding]
codec = "json"
-[sinks.beacon_s3.framing]
+[sinks.beacon_inventory_s3.framing]
method = "newline_delimited"
-[sinks.beacon_s3.batch]
+[sinks.beacon_inventory_s3.batch]
max_bytes = 10000000
timeout_secs = 300
-[sinks.beacon_s3.request]
+[sinks.beacon_inventory_s3.request]
retry_attempts = 10
retry_initial_backoff_secs = 1
retry_max_duration_secs = 300
diff --git a/cli/beacon/internal/endpoint/s3/s3_test.go b/cli/beacon/internal/endpoint/s3/s3_test.go
index 62717b73..e683811b 100644
--- a/cli/beacon/internal/endpoint/s3/s3_test.go
+++ b/cli/beacon/internal/endpoint/s3/s3_test.go
@@ -18,6 +18,9 @@ func TestUploadSmokeTestUsesConfiguredPath(t *testing.T) {
if !strings.Contains(got, "/tmp/beacon/runtime.jsonl") {
t.Fatalf("script did not include configured path: %s", got)
}
+ if !strings.Contains(got, "/tmp/beacon/inventory_state.jsonl") {
+ t.Fatalf("script did not include derived inventory path: %s", got)
+ }
if strings.Contains(got, "{{LOG_PATH}}") {
t.Fatalf("script still contains template token: %s", got)
}
@@ -69,6 +72,9 @@ func TestInstallPackWritesExpectedFiles(t *testing.T) {
if !strings.Contains(string(vectorConfig), "/tmp/beacon/runtime.jsonl") {
t.Fatalf("generated vector config missing configured log path: %s", vectorConfig)
}
+ if !strings.Contains(string(vectorConfig), "/tmp/beacon/inventory_state.jsonl") {
+ t.Fatalf("generated vector config missing derived inventory log path: %s", vectorConfig)
+ }
info, err = os.Stat(vectorPath)
if err != nil {
t.Fatal(err)
@@ -82,12 +88,14 @@ func TestVectorConfigUsesAWSS3SinkAndPreservesJSONShape(t *testing.T) {
got := mustRead("pack/vector.toml.tmpl")
for _, want := range []string{
`include = ["{{LOG_PATH}}"]`,
+ `include = ["{{INVENTORY_LOG_PATH}}"]`,
`read_from = "end"`,
`. = parse_json!(.message)`,
`type = "aws_s3"`,
`bucket = "${BEACON_S3_BUCKET}"`,
`region = "${AWS_REGION:-us-east-1}"`,
- `key_prefix = "${BEACON_S3_PREFIX:-beacon/runtime}/date=%F/"`,
+ `key_prefix = "${BEACON_S3_PREFIX:-beacon}/runtime/date=%F/"`,
+ `key_prefix = "${BEACON_S3_PREFIX:-beacon}/inventory/date=%F/"`,
`filename_time_format = "%s"`,
`filename_append_uuid = true`,
`filename_extension = "jsonl.gz"`,
@@ -142,6 +150,7 @@ func TestPackREADMEMentionsS3SetupAndProductionForwarding(t *testing.T) {
"BEACON_S3_PREFIX",
"aws s3 ls",
"aws s3 cp",
+ "inventory_state.jsonl",
"Beacon endpoint S3 validation event",
"vendor=beacon product=endpoint-agent destination.type=s3 destination.mode=aws_s3_jsonl",
"vector.toml",
@@ -149,6 +158,7 @@ func TestPackREADMEMentionsS3SetupAndProductionForwarding(t *testing.T) {
"without a Vector wrapper",
"Content Handling",
"/var/log/beacon-agent/runtime.jsonl",
+ "/var/log/beacon-agent/inventory_state.jsonl",
"Beacon does not store AWS credentials",
"server-side encryption",
} {
diff --git a/cli/beacon/internal/endpoint/siempack/siempack.go b/cli/beacon/internal/endpoint/siempack/siempack.go
index bcb1119a..be9948c9 100644
--- a/cli/beacon/internal/endpoint/siempack/siempack.go
+++ b/cli/beacon/internal/endpoint/siempack/siempack.go
@@ -10,6 +10,7 @@ import (
)
const logPathToken = "{{LOG_PATH}}"
+const inventoryLogPathToken = "{{INVENTORY_LOG_PATH}}"
type File struct {
Name string
@@ -27,7 +28,15 @@ func ReadFile(fsys fs.FS, path string) (string, error) {
}
func RenderLogPath(content, logPath string) string {
- return strings.ReplaceAll(content, logPathToken, logPath)
+ content = strings.ReplaceAll(content, logPathToken, logPath)
+ return strings.ReplaceAll(content, inventoryLogPathToken, InventoryLogPath(logPath))
+}
+
+func InventoryLogPath(logPath string) string {
+ if logPath == "" {
+ return "inventory_state.jsonl"
+ }
+ return filepath.Join(filepath.Dir(logPath), "inventory_state.jsonl")
}
// JSONEscapeForString escapes s for safe embedding inside a JSON string literal
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index 32c15617..a1078758 100644
--- a/docs/changelog/cli.mdx
+++ b/docs/changelog/cli.mdx
@@ -25,7 +25,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.
- **Agent skills inventory** · `beacon endpoint inventory` now discovers local agent skill manifests for Claude Code, Cursor, and `.agents/skills`, reporting names, paths, and content hashes for change detection. See the [Skills inventory guide](/inventory/skills).
- **Skills in the local dashboard** · The Agent Inventory view in the local dashboard shows an Agent Skills table and summary card alongside agent harnesses and MCP servers, so operators can see installed skills at a glance.
- **Metadata-only by design** · Skill discovery records hashes and file paths only — `SKILL.md` instruction bodies are never read or stored, consistent with Beacon's [data inventory](/security/data-inventory) posture.
-- **Optional `skill.inventory` events** · Running inventory with `--write-event` appends a `skill.inventory` event to the runtime log so installed-skill state can be forwarded to any configured SIEM destination.
+- **Optional inventory snapshot events** · Running inventory with `--write-event` appends metadata-only inventory heartbeat and snapshot events to `inventory_state.jsonl` so installed-skill state can be kept separate from runtime activity telemetry.
### v0.0.67 · June 15, 2026
diff --git a/docs/cli/endpoint-inventory.mdx b/docs/cli/endpoint-inventory.mdx
index f9b2da77..06b666a4 100644
--- a/docs/cli/endpoint-inventory.mdx
+++ b/docs/cli/endpoint-inventory.mdx
@@ -29,6 +29,29 @@ Inventory can include:
Human-readable and JSON inventory use the same default filtering: configuration records, MCP server context, and skill manifests are shown when they are relevant to the local endpoint state. Use `--all` with `--json` when you need the complete supported inventory surface for fleet comparison or troubleshooting.
+## Inventory Heartbeats
+
+Cursor and Claude Code endpoint hooks can periodically append inventory telemetry to a separate `inventory_state.jsonl` file beside `runtime.jsonl`:
+
+- `inventory.heartbeat` records that Beacon checked local agent configuration inventory, including counts and a snapshot digest.
+- `inventory.snapshot` records the current metadata-only inventory when the snapshot changed or when inventory is first initialized.
+
+Inventory snapshots include config file metadata, MCP server metadata, skill metadata, and hook config metadata. They do not include skill instruction bodies, MCP secret values, full environment values, full command arguments, or unrelated config content.
+
+The heartbeat TTL is configured in the existing endpoint config file:
+
+```json title="~/.beacon/endpoint/config.json"
+{
+ "inventory_heartbeat": {
+ "enabled": true,
+ "ttl_seconds": 86400,
+ "runtimes": ["cursor", "claude_code"]
+ }
+}
+```
+
+For a manual smoke test, temporarily lower `ttl_seconds`, start a Cursor or Claude Code session with Beacon hooks installed, add a harmless test MCP server to `~/.cursor/mcp.json`, `.cursor/mcp.json`, `~/.claude/settings.json`, or `.claude/settings.json`, then trigger another hook action. `inventory_state.jsonl` should contain an `inventory.heartbeat` event and, when the digest changes, an `inventory.snapshot` event with the new MCP server metadata under `raw.inventory.mcp_servers`. `runtime.jsonl` should remain limited to agent runtime activity.
+
## Flags
| Flag | Description |
diff --git a/docs/security/data-inventory.mdx b/docs/security/data-inventory.mdx
index bd4dcbb4..084dfed0 100644
--- a/docs/security/data-inventory.mdx
+++ b/docs/security/data-inventory.mdx
@@ -33,7 +33,14 @@ Beacon writes normalized endpoint events only when supported runtimes provide te
| MCP servers | Runtime, source path hash, server name/hash, transport, command name/hash, argument count, safe env-key names/counts, and definition hash |
| Agent skills | Runtime/source family, scope, skill name/hash, root and manifest path/hash, file hash, modified time, and parser status |
-Skill inventory is metadata-only. Beacon hashes `SKILL.md` manifests for change detection but does not retain skill instruction bodies in inventory JSON, dashboard responses, or `skill.inventory` events.
+Skill inventory is metadata-only. Beacon hashes `SKILL.md` manifests for change detection but does not retain skill instruction bodies in inventory JSON, dashboard responses, or inventory snapshot events.
+
+Inventory heartbeat telemetry uses a separate local JSONL file, `inventory_state.jsonl`, so `runtime.jsonl` stays scoped to agent runtime activity. For Cursor and Claude Code, normal hook execution can periodically write:
+
+- `inventory.heartbeat`, a small event showing that Beacon checked local agent configuration inventory and recording counts plus a snapshot digest.
+- `inventory.snapshot`, a metadata-only snapshot written when the digest changes or inventory is first initialized.
+
+Snapshots include config-file metadata, MCP server metadata, skill metadata, and hook config metadata. They do not include skill instruction bodies, MCP secret values, full environment values, full command arguments, or unrelated config content.
## Required Fields
diff --git a/packaging/macos/README.md b/packaging/macos/README.md
index a3ec95a2..6b365d2d 100644
--- a/packaging/macos/README.md
+++ b/packaging/macos/README.md
@@ -134,9 +134,12 @@ identity, MDM, or secret tooling. Keep AWS credentials, IAM roles, log group
retention, and encryption outside Beacon endpoint configuration.
For AWS S3, keep Beacon as the local JSONL producer and deploy Vector to tail
-`/var/log/beacon-agent/runtime.jsonl` into a customer-managed bucket. Generate
-Beacon's S3 content pack for setup guidance, a Vector config, sample events, and
-validation commands:
+`/var/log/beacon-agent/runtime.jsonl` and
+`/var/log/beacon-agent/inventory_state.jsonl` into a customer-managed bucket.
+The generated S3 config writes runtime activity under `runtime/date=.../` and
+inventory telemetry under `inventory/date=.../` below the same
+`BEACON_S3_PREFIX`. Generate Beacon's S3 content pack for setup guidance, a
+Vector config, sample events, and validation commands:
```bash
/opt/beacon/bin/beacon endpoint s3 install-pack --system --output ./beacon-s3-pack
@@ -348,8 +351,10 @@ integrations; the helper writes hook events to
Use `/opt/beacon/jamf/claude/common/repair-hooks.sh` when a Jamf policy
needs only to repair the system endpoint, prepare
-`/var/log/beacon-agent/runtime.jsonl` for user-run hooks, reinstall Claude Code
-hooks for the interactive console user, and run a manual Claude hook smoke test.
+`/var/log/beacon-agent/runtime.jsonl`,
+`/var/log/beacon-agent/inventory_state.jsonl`, and the inventory heartbeat state
+file for user-run hooks, reinstall Claude Code hooks for the interactive console
+user, and run a manual Claude hook smoke test.
`repair-hooks.sh` Jamf script parameters:
@@ -376,9 +381,24 @@ Parameter 10: Vector read_from, default end
```
Use `/opt/beacon/jamf/claude/falcon/repair-hooks-and-forwarder.sh` when one
-policy should repair Beacon, prepare `/var/log/beacon-agent/runtime.jsonl`,
-install Claude hooks for the console user, and install the Falcon Vector
-forwarder without relying on collector-based Falcon forwarding.
+policy should repair Beacon, prepare `/var/log/beacon-agent/runtime.jsonl` and
+the sibling inventory log/state files, install Claude hooks for the console
+user, and install the Falcon Vector forwarder without relying on collector-based
+Falcon forwarding.
+
+`s3/install-forwarder.sh` Jamf script parameters:
+
+```text
+Parameter 4: S3 bucket
+Parameter 5: AWS region
+Parameter 6: S3 prefix root, default beacon
+Parameter 7: S3 storage class, default STANDARD
+Parameter 8: Vector read_from, default end
+```
+
+Set `BEACON_RUNTIME_LOG_PATHS` to override the tailed runtime logs. The S3
+forwarder derives an `inventory_state.jsonl` path beside each runtime path and
+ships those inventory files under the `inventory/` S3 folder.
The Jamf Claude helper source paths map into the package as:
diff --git a/packaging/macos/jamf/claude/common/repair-hooks.sh b/packaging/macos/jamf/claude/common/repair-hooks.sh
index 8a9c87de..4eccee16 100755
--- a/packaging/macos/jamf/claude/common/repair-hooks.sh
+++ b/packaging/macos/jamf/claude/common/repair-hooks.sh
@@ -7,6 +7,10 @@ BEACON_COLLECTOR="${BEACON_COLLECTOR:-/opt/beacon/bin/beacon-otelcol}"
RUNTIME_LOG="${BEACON_RUNTIME_LOG:-/var/log/beacon-agent/runtime.jsonl}"
RUNTIME_DIR="$(dirname "$RUNTIME_LOG")"
RUNTIME_LOCK="${RUNTIME_LOG}.lock"
+INVENTORY_LOG="${BEACON_INVENTORY_LOG:-$RUNTIME_DIR/inventory_state.jsonl}"
+INVENTORY_LOCK="${INVENTORY_LOG}.lock"
+INVENTORY_STATE="${BEACON_INVENTORY_STATE:-$RUNTIME_DIR/inventory-state.json}"
+INVENTORY_STATE_LOCK="${INVENTORY_STATE}.lock"
OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${4:-4317}}"
OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-${5:-4318}}"
@@ -36,10 +40,10 @@ echo "Repairing Beacon system endpoint..."
echo "Preparing runtime log path for user-run hooks..."
mkdir -p "$RUNTIME_DIR"
-touch "$RUNTIME_LOG" "$RUNTIME_LOCK"
-chown root:wheel "$RUNTIME_DIR" "$RUNTIME_LOG" "$RUNTIME_LOCK"
+touch "$RUNTIME_LOG" "$RUNTIME_LOCK" "$INVENTORY_LOG" "$INVENTORY_LOCK" "$INVENTORY_STATE" "$INVENTORY_STATE_LOCK"
+chown root:wheel "$RUNTIME_DIR" "$RUNTIME_LOG" "$RUNTIME_LOCK" "$INVENTORY_LOG" "$INVENTORY_LOCK" "$INVENTORY_STATE" "$INVENTORY_STATE_LOCK"
chmod 755 "$RUNTIME_DIR"
-chmod 644 "$RUNTIME_LOG" "$RUNTIME_LOCK"
+chmod 644 "$RUNTIME_LOG" "$RUNTIME_LOCK" "$INVENTORY_LOG" "$INVENTORY_LOCK" "$INVENTORY_STATE" "$INVENTORY_STATE_LOCK"
CONSOLE_USER="$(stat -f %Su /dev/console 2>/dev/null || true)"
@@ -70,10 +74,14 @@ chown -R "$CONSOLE_USER:$USER_GROUP" "$HOME_DIR/.beacon"
chmod 755 "$HOME_DIR/.beacon" "$HOME_DIR/.beacon/endpoint" "$HOOK_DIR"
rm -f "$HOOK_BIN"
-echo "Granting $CONSOLE_USER append access to Beacon runtime log and lock..."
+echo "Granting $CONSOLE_USER append access to Beacon runtime and inventory logs..."
chmod +a "$CONSOLE_USER allow list,search,add_file,delete_child,readattr,writeattr" "$RUNTIME_DIR" || true
chmod +a "$CONSOLE_USER allow read,write,append,readattr,writeattr,readextattr,writeextattr" "$RUNTIME_LOG" || true
chmod +a "$CONSOLE_USER allow read,write,append,readattr,writeattr,readextattr,writeextattr" "$RUNTIME_LOCK" || true
+chmod +a "$CONSOLE_USER allow read,write,append,readattr,writeattr,readextattr,writeextattr" "$INVENTORY_LOG" || true
+chmod +a "$CONSOLE_USER allow read,write,append,readattr,writeattr,readextattr,writeextattr" "$INVENTORY_LOCK" || true
+chmod +a "$CONSOLE_USER allow read,write,append,readattr,writeattr,readextattr,writeextattr" "$INVENTORY_STATE" || true
+chmod +a "$CONSOLE_USER allow read,write,append,readattr,writeattr,readextattr,writeextattr" "$INVENTORY_STATE_LOCK" || true
echo "Installing Claude Code hooks as $CONSOLE_USER..."
sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" "$BEACON_BIN" endpoint hooks install \
@@ -91,6 +99,10 @@ fi
echo "Validating hook write permissions..."
sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" test -w "$RUNTIME_LOG"
sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" sh -c ": >> '$RUNTIME_LOCK'"
+sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" test -w "$INVENTORY_LOG"
+sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" sh -c ": >> '$INVENTORY_LOCK'"
+sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" test -w "$INVENTORY_STATE"
+sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" sh -c ": >> '$INVENTORY_STATE_LOCK'"
echo "Running manual Claude hook smoke test..."
sudo -u "$CONSOLE_USER" HOME="$HOME_DIR" BEACON_SMOKE_RUNTIME_LOG="$RUNTIME_LOG" sh -lc '
@@ -113,4 +125,7 @@ launchctl print system/com.beacon.endpoint.collector || true
echo "Last Beacon runtime events..."
tail -n 10 "$RUNTIME_LOG" || true
+echo "Last Beacon inventory events..."
+tail -n 10 "$INVENTORY_LOG" || true
+
echo "Done. Fully restart Claude Code and start a new session to test real hook events."
diff --git a/packaging/macos/jamf/claude/s3/install-forwarder.sh b/packaging/macos/jamf/claude/s3/install-forwarder.sh
index d2a03928..51736084 100755
--- a/packaging/macos/jamf/claude/s3/install-forwarder.sh
+++ b/packaging/macos/jamf/claude/s3/install-forwarder.sh
@@ -13,7 +13,7 @@ PLIST_PATH="$LAUNCHDAEMONS_DIR/$LABEL.plist"
S3_BUCKET="${BEACON_S3_BUCKET:-${4:-}}"
AWS_REGION_VALUE="${AWS_REGION:-${5:-}}"
-S3_PREFIX="${BEACON_S3_PREFIX:-${6:-beacon/runtime}}"
+S3_PREFIX="${BEACON_S3_PREFIX:-${6:-beacon}}"
S3_STORAGE_CLASS="${BEACON_S3_STORAGE_CLASS:-${7:-STANDARD}}"
VECTOR_READ_FROM="${BEACON_VECTOR_READ_FROM:-${8:-end}}"
RUNTIME_LOG_PATHS="${BEACON_RUNTIME_LOG_PATHS:-/var/log/beacon-agent/runtime.jsonl}"
@@ -62,11 +62,12 @@ xml_escape() {
}
include_array() {
+ paths="$1"
old_ifs="$IFS"
IFS=,
first=1
printf '['
- for raw in $RUNTIME_LOG_PATHS; do
+ for raw in $paths; do
path="$(printf '%s' "$raw" | sed 's/^ *//; s/ *$//')"
[ -n "$path" ] || continue
if [ "$first" -eq 0 ]; then
@@ -87,10 +88,29 @@ include_array() {
IFS="$old_ifs"
}
+inventory_paths() {
+ old_ifs="$IFS"
+ IFS=,
+ first=1
+ for raw in $RUNTIME_LOG_PATHS; do
+ path="$(printf '%s' "$raw" | sed 's/^ *//; s/ *$//')"
+ [ -n "$path" ] || continue
+ dir="$(dirname "$path")"
+ if [ "$first" -eq 0 ]; then
+ printf ','
+ fi
+ printf '%s/inventory_state.jsonl' "$dir"
+ first=0
+ done
+ IFS="$old_ifs"
+}
+
mkdir -p "$BASE_DIR" "$DATA_DIR" "$LAUNCHDAEMONS_DIR"
chmod 0755 "$BASE_DIR" "$DATA_DIR" "$LAUNCHDAEMONS_DIR" 2>/dev/null || true
-INCLUDES="$(include_array)"
+RUNTIME_INCLUDES="$(include_array "$RUNTIME_LOG_PATHS")"
+INVENTORY_LOG_PATHS="$(inventory_paths)"
+INVENTORY_INCLUDES="$(include_array "$INVENTORY_LOG_PATHS")"
cat >"$CONFIG_PATH" <<EOF
# Managed by Beacon. Do not edit by hand.
@@ -99,22 +119,63 @@ data_dir = "$(printf '%s' "$DATA_DIR" | sed 's/\\/\\\\/g; s/"/\\"/g')"
[sources.beacon_runtime]
type = "file"
-include = $INCLUDES
+include = $RUNTIME_INCLUDES
+read_from = "\${BEACON_VECTOR_READ_FROM:-end}"
+
+[sources.beacon_inventory]
+type = "file"
+include = $INVENTORY_INCLUDES
read_from = "\${BEACON_VECTOR_READ_FROM:-end}"
-[transforms.beacon_json]
+[transforms.beacon_runtime_json]
type = "remap"
inputs = ["beacon_runtime"]
source = '''
. = parse_json!(.message)
'''
-[sinks.beacon_s3]
+[transforms.beacon_inventory_json]
+type = "remap"
+inputs = ["beacon_inventory"]
+source = '''
+. = parse_json!(.message)
+'''
+
+[sinks.beacon_runtime_s3]
+type = "aws_s3"
+inputs = ["beacon_runtime_json"]
+bucket = "\${BEACON_S3_BUCKET}"
+region = "\${AWS_REGION}"
+key_prefix = "\${BEACON_S3_PREFIX:-beacon}/runtime/date=%F/"
+filename_time_format = "%s"
+filename_append_uuid = true
+filename_extension = "jsonl.gz"
+compression = "gzip"
+content_encoding = "gzip"
+content_type = "application/x-ndjson"
+storage_class = "\${BEACON_S3_STORAGE_CLASS:-STANDARD}"
+
+[sinks.beacon_runtime_s3.encoding]
+codec = "json"
+
+[sinks.beacon_runtime_s3.framing]
+method = "newline_delimited"
+
+[sinks.beacon_runtime_s3.batch]
+max_bytes = 10000000
+timeout_secs = 300
+
+[sinks.beacon_runtime_s3.request]
+retry_attempts = 10
+retry_initial_backoff_secs = 1
+retry_max_duration_secs = 300
+
+[sinks.beacon_inventory_s3]
type = "aws_s3"
-inputs = ["beacon_json"]
+inputs = ["beacon_inventory_json"]
bucket = "\${BEACON_S3_BUCKET}"
region = "\${AWS_REGION}"
-key_prefix = "\${BEACON_S3_PREFIX:-beacon/runtime}/date=%F/"
+key_prefix = "\${BEACON_S3_PREFIX:-beacon}/inventory/date=%F/"
filename_time_format = "%s"
filename_append_uuid = true
filename_extension = "jsonl.gz"
@@ -123,17 +184,17 @@ content_encoding = "gzip"
content_type = "application/x-ndjson"
storage_class = "\${BEACON_S3_STORAGE_CLASS:-STANDARD}"
-[sinks.beacon_s3.encoding]
+[sinks.beacon_inventory_s3.encoding]
codec = "json"
-[sinks.beacon_s3.framing]
+[sinks.beacon_inventory_s3.framing]
method = "newline_delimited"
-[sinks.beacon_s3.batch]
+[sinks.beacon_inventory_s3.batch]
max_bytes = 10000000
timeout_secs = 300
-[sinks.beacon_s3.request]
+[sinks.beacon_inventory_s3.request]
retry_attempts = 10
retry_initial_backoff_secs = 1
retry_max_duration_secs = 300
diff --git a/packaging/macos/jamf/claude/s3/repair-hooks-and-forwarder.sh b/packaging/macos/jamf/claude/s3/repair-hooks-and-forwarder.sh
index b07caa9c..16f6faa9 100755
--- a/packaging/macos/jamf/claude/s3/repair-hooks-and-forwarder.sh
+++ b/packaging/macos/jamf/claude/s3/repair-hooks-and-forwarder.sh
@@ -6,7 +6,7 @@ FORWARDER_SCRIPT="${BEACON_S3_VECTOR_SCRIPT:-/opt/beacon/jamf/claude/s3/install-
S3_BUCKET="${BEACON_S3_BUCKET:-${4:-}}"
AWS_REGION_VALUE="${AWS_REGION:-${5:-}}"
-S3_PREFIX="${BEACON_S3_PREFIX:-${6:-beacon/runtime}}"
+S3_PREFIX="${BEACON_S3_PREFIX:-${6:-beacon}}"
S3_STORAGE_CLASS="${BEACON_S3_STORAGE_CLASS:-${7:-STANDARD}}"
VECTOR_READ_FROM="${BEACON_VECTOR_READ_FROM:-${8:-end}}"
OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${9:-4317}}"
diff --git a/packaging/macos/test-endpoint-scripts.sh b/packaging/macos/test-endpoint-scripts.sh
index 5bb2e92f..f47ea76f 100644
--- a/packaging/macos/test-endpoint-scripts.sh
+++ b/packaging/macos/test-endpoint-scripts.sh
@@ -23,6 +23,10 @@ for script in "$ROOT_DIR"/packaging/macos/scripts/* "$ROOT_DIR"/packaging/macos/
;;
esac
done
+if ! grep -q 'INVENTORY_STATE' "$ROOT_DIR/packaging/macos/jamf/claude/common/repair-hooks.sh"; then
+ echo "repair-hooks should prepare inventory heartbeat state files" >&2
+ exit 1
+fi
PKG_TEST_BIN="$TMP_DIR/pkg-bin"
PKG_TEST_ROOT="$TMP_DIR/pkg-root"
@@ -472,10 +476,30 @@ if [ ! -f "$S3_LAUNCHDAEMONS_DIR/com.beacon.endpoint.s3-forwarder.plist" ]; then
echo "S3 Vector plist was not written" >&2
exit 1
fi
-if ! grep -q 'sinks.beacon_s3' "$S3_FORWARDER_BASE/s3-vector.toml"; then
+if ! grep -q 'sinks.beacon_runtime_s3' "$S3_FORWARDER_BASE/s3-vector.toml"; then
echo "S3 Vector config missing sink" >&2
exit 1
fi
+if ! grep -q 'sinks.beacon_inventory_s3' "$S3_FORWARDER_BASE/s3-vector.toml"; then
+ echo "S3 Vector config missing inventory sink" >&2
+ exit 1
+fi
+if ! grep -q "$TMP_DIR/s3-runtime.jsonl" "$S3_FORWARDER_BASE/s3-vector.toml"; then
+ echo "S3 Vector config missing runtime log path" >&2
+ exit 1
+fi
+if ! grep -q "$TMP_DIR/inventory_state.jsonl" "$S3_FORWARDER_BASE/s3-vector.toml"; then
+ echo "S3 Vector config missing derived inventory log path" >&2
+ exit 1
+fi
+if ! grep -q 'key_prefix = "${BEACON_S3_PREFIX:-beacon}/runtime/date=%F/"' "$S3_FORWARDER_BASE/s3-vector.toml"; then
+ echo "S3 Vector config missing runtime prefix" >&2
+ exit 1
+fi
+if ! grep -q 'key_prefix = "${BEACON_S3_PREFIX:-beacon}/inventory/date=%F/"' "$S3_FORWARDER_BASE/s3-vector.toml"; then
+ echo "S3 Vector config missing inventory prefix" >&2
+ exit 1
+fi
if ! grep -q 'compression = "gzip"' "$S3_FORWARDER_BASE/s3-vector.toml"; then
echo "S3 Vector config missing gzip compression" >&2
exit 1