fix(audit): make JSONL sidecar opt-in (#4688)
Routine issue history already lands in the database events tables. Stop creating or appending the interactions JSONL sidecar by default, add audit.enabled for explicit sidecar use, and expose database events via bd history --events. Fixes gastownhall/beads#4687 Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
This commit is contained in:
parent
cc5d0563a7
commit
64a136d56e
15 changed files with 181 additions and 29 deletions
|
|
@ -29,9 +29,14 @@ var (
|
|||
var auditCmd = &cobra.Command{
|
||||
Use: "audit",
|
||||
Short: "Record and label agent interactions (append-only JSONL)",
|
||||
Long: `Audit log entries are appended to .beads/interactions.jsonl.
|
||||
Long: `Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
|
||||
|
||||
Each line is one event. This file is intended to be versioned in git and used for:
|
||||
This optional JSONL sidecar is disabled by default. Enable it with:
|
||||
|
||||
bd config set audit.enabled true
|
||||
|
||||
Issue history is always recorded in the database and is visible with
|
||||
bd history <id> --events. The JSONL sidecar is for explicit interaction capture:
|
||||
- auditing ("why did the agent do that?")
|
||||
- dataset generation (SFT/RL fine-tuning)
|
||||
|
||||
|
|
@ -95,7 +100,7 @@ var auditRecordCmd = &cobra.Command{
|
|||
}
|
||||
}
|
||||
|
||||
id, err := audit.Append(&e)
|
||||
id, err := audit.AppendIfEnabled(&e)
|
||||
if err != nil {
|
||||
return HandleError("%v", err)
|
||||
}
|
||||
|
|
@ -138,7 +143,7 @@ var auditLabelCmd = &cobra.Command{
|
|||
Reason: auditLabelReason,
|
||||
}
|
||||
|
||||
id, err := audit.Append(&e)
|
||||
id, err := audit.AppendIfEnabled(&e)
|
||||
if err != nil {
|
||||
return HandleError("%v", err)
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,15 +1,18 @@
|
|||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/steveyegge/beads/internal/metrics"
|
||||
"github.com/steveyegge/beads/internal/types"
|
||||
"github.com/steveyegge/beads/internal/ui"
|
||||
)
|
||||
|
||||
var (
|
||||
historyLimit int
|
||||
historyLimit int
|
||||
historyEvents bool
|
||||
)
|
||||
|
||||
var historyCmd = &cobra.Command{
|
||||
|
|
@ -21,7 +24,8 @@ where the issue was modified.
|
|||
|
||||
Examples:
|
||||
bd history bd-123 # Show all history for issue bd-123
|
||||
bd history bd-123 --limit 5 # Show last 5 changes`,
|
||||
bd history bd-123 --limit 5 # Show last 5 changes
|
||||
bd history bd-123 --events # Show database audit events`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
SilenceUsage: true,
|
||||
SilenceErrors: true,
|
||||
|
|
@ -36,6 +40,18 @@ Examples:
|
|||
ctx := rootCtx
|
||||
issueID := args[0]
|
||||
|
||||
if historyEvents {
|
||||
events, err := collectHistoryEvents(ctx, issueID, historyLimit)
|
||||
if err != nil {
|
||||
return HandleErrorRespectJSON("failed to get history events: %v", err)
|
||||
}
|
||||
if jsonOutput {
|
||||
return outputJSON(events)
|
||||
}
|
||||
printHistoryEvents(issueID, events)
|
||||
return nil
|
||||
}
|
||||
|
||||
history, err := store.History(ctx, issueID)
|
||||
if err != nil {
|
||||
return HandleErrorRespectJSON("failed to get history: %v", err)
|
||||
|
|
@ -87,6 +103,56 @@ Examples:
|
|||
|
||||
func init() {
|
||||
historyCmd.Flags().IntVar(&historyLimit, "limit", 0, "Limit number of history entries (0 = all)")
|
||||
historyCmd.Flags().BoolVar(&historyEvents, "events", false, "Show database audit events instead of commit snapshots")
|
||||
historyCmd.ValidArgsFunction = issueIDCompletion
|
||||
rootCmd.AddCommand(historyCmd)
|
||||
}
|
||||
|
||||
func collectHistoryEvents(ctx context.Context, issueID string, limit int) ([]types.Event, error) {
|
||||
iter, err := store.IterEvents(ctx, issueID, limit)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer func() { _ = iter.Close() }()
|
||||
|
||||
var events []types.Event
|
||||
for iter.Next(ctx) {
|
||||
event := iter.Value()
|
||||
if event != nil {
|
||||
events = append(events, *event)
|
||||
}
|
||||
}
|
||||
if err := iter.Err(); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return events, nil
|
||||
}
|
||||
|
||||
func printHistoryEvents(issueID string, events []types.Event) {
|
||||
if len(events) == 0 {
|
||||
fmt.Printf("No history events found for issue %s\n", issueID)
|
||||
return
|
||||
}
|
||||
|
||||
fmt.Printf("\n%s History events for %s (%d entries)\n\n",
|
||||
ui.RenderAccent("📜"), issueID, len(events))
|
||||
for i, event := range events {
|
||||
fmt.Printf("%s %s by %s\n",
|
||||
ui.RenderMuted(event.CreatedAt.Format("2006-01-02 15:04:05")),
|
||||
event.EventType,
|
||||
event.Actor)
|
||||
if event.OldValue != nil && *event.OldValue != "" {
|
||||
fmt.Printf(" Old: %s\n", *event.OldValue)
|
||||
}
|
||||
if event.NewValue != nil && *event.NewValue != "" {
|
||||
fmt.Printf(" New: %s\n", *event.NewValue)
|
||||
}
|
||||
if event.Comment != nil && *event.Comment != "" {
|
||||
fmt.Printf(" Comment: %s\n", *event.Comment)
|
||||
}
|
||||
if i < len(events)-1 {
|
||||
fmt.Println()
|
||||
}
|
||||
}
|
||||
fmt.Println()
|
||||
}
|
||||
|
|
|
|||
|
|
@ -121,6 +121,22 @@ func TestEmbeddedHistory(t *testing.T) {
|
|||
}
|
||||
})
|
||||
|
||||
t.Run("events_json_output", func(t *testing.T) {
|
||||
events := bdHistoryJSON(t, bd, dir, issue.ID, "--events")
|
||||
if len(events) == 0 {
|
||||
t.Fatal("expected non-empty history events")
|
||||
}
|
||||
var sawStatus bool
|
||||
for _, event := range events {
|
||||
if event["event_type"] == "status_changed" {
|
||||
sawStatus = true
|
||||
}
|
||||
}
|
||||
if !sawStatus {
|
||||
t.Fatalf("expected status_changed event in history events, got %#v", events)
|
||||
}
|
||||
})
|
||||
|
||||
// ===== --json output =====
|
||||
|
||||
t.Run("json_output_structure", func(t *testing.T) {
|
||||
|
|
|
|||
|
|
@ -685,8 +685,8 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
|
|||
}
|
||||
|
||||
// Always create local .beads/ when using default location (CWD/.beads).
|
||||
// The local directory is needed for metadata.json, config.yaml, .gitignore,
|
||||
// interactions.jsonl, and hooks — regardless of where dolt data lives.
|
||||
// The local directory is needed for metadata.json, config.yaml,
|
||||
// .gitignore, and hooks — regardless of where dolt data lives.
|
||||
// Only skip when BEADS_DIR explicitly points outside the project.
|
||||
//
|
||||
// Previous logic only created .beads/ when the dolt data dir was a
|
||||
|
|
@ -775,15 +775,6 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
|
|||
}
|
||||
}
|
||||
|
||||
// Ensure interactions.jsonl exists (append-only agent audit log)
|
||||
interactionsPath := filepath.Join(beadsDir, "interactions.jsonl")
|
||||
if _, err := os.Stat(interactionsPath); os.IsNotExist(err) {
|
||||
// nolint:gosec // G306: JSONL file needs to be readable by other tools
|
||||
if err := os.WriteFile(interactionsPath, []byte{}, 0644); err != nil {
|
||||
fmt.Fprintf(os.Stderr, "Warning: failed to create interactions.jsonl: %v\n", err)
|
||||
// Non-fatal - continue anyway
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Ensure git is initialized — bd requires git for role config, sync branches,
|
||||
|
|
|
|||
|
|
@ -1463,7 +1463,9 @@ func TestEmbeddedInit(t *testing.T) {
|
|||
t.Run("files_created", func(t *testing.T) {
|
||||
dir, beadsDir, _ := bdInit(t, bd, "--prefix", "fc", "--skip-hooks")
|
||||
requireFile(t, filepath.Join(beadsDir, "config.yaml"))
|
||||
requireFile(t, filepath.Join(beadsDir, "interactions.jsonl"))
|
||||
if _, err := os.Stat(filepath.Join(beadsDir, "interactions.jsonl")); !os.IsNotExist(err) {
|
||||
t.Fatalf("interactions.jsonl should be created only when audit.enabled is true, got stat err %v", err)
|
||||
}
|
||||
requireFile(t, filepath.Join(dir, "AGENTS.md"))
|
||||
requireFile(t, filepath.Join(dir, ".agents", "skills", "beads", "SKILL.md"))
|
||||
requireFile(t, filepath.Join(dir, ".agents", "skills", "beads", "agents", "openai.yaml"))
|
||||
|
|
|
|||
|
|
@ -60,6 +60,12 @@ func renderInitConfigYAML(prefix string, noDbMode bool) []byte {
|
|||
# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)
|
||||
# actor: ""
|
||||
|
||||
# Optional JSONL sidecar for explicit agent/tool interaction audit records.
|
||||
# Issue history is always recorded in the database and is visible with
|
||||
# bd history <id> --events; this only controls .beads/interactions.jsonl.
|
||||
# audit:
|
||||
# enabled: false
|
||||
|
||||
# Export events (audit trail) to .beads/events.jsonl on each flush/sync
|
||||
# When enabled, new events are appended incrementally using a high-water mark.
|
||||
# Use 'bd export --events' to trigger manually regardless of this setting.
|
||||
|
|
|
|||
|
|
@ -1713,6 +1713,7 @@ where the issue was modified.
|
|||
Examples:
|
||||
bd history bd-123 # Show all history for issue bd-123
|
||||
bd history bd-123 --limit 5 # Show last 5 changes
|
||||
bd history bd-123 --events # Show database audit events
|
||||
|
||||
```
|
||||
bd history <id> [flags]
|
||||
|
|
@ -1721,6 +1722,7 @@ bd history <id> [flags]
|
|||
**Flags:**
|
||||
|
||||
```
|
||||
--events Show database audit events instead of commit snapshots
|
||||
--limit int Limit number of history entries (0 = all)
|
||||
```
|
||||
|
||||
|
|
@ -5470,9 +5472,14 @@ bd ado sync [flags]
|
|||
|
||||
### bd audit
|
||||
|
||||
Audit log entries are appended to .beads/interactions.jsonl.
|
||||
Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
|
||||
|
||||
Each line is one event. This file is intended to be versioned in git and used for:
|
||||
This optional JSONL sidecar is disabled by default. Enable it with:
|
||||
|
||||
bd config set audit.enabled true
|
||||
|
||||
Issue history is always recorded in the database and is visible with
|
||||
bd history <id> --events. The JSONL sidecar is for explicit interaction capture:
|
||||
- auditing ("why did the agent do that?")
|
||||
- dataset generation (SFT/RL fine-tuning)
|
||||
|
||||
|
|
|
|||
|
|
@ -9,9 +9,11 @@ import (
|
|||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/steveyegge/beads/internal/beads"
|
||||
"github.com/steveyegge/beads/internal/config"
|
||||
)
|
||||
|
||||
const (
|
||||
|
|
@ -59,6 +61,25 @@ func Path() (string, error) {
|
|||
return filepath.Join(beadsDir, FileName), nil
|
||||
}
|
||||
|
||||
// Enabled reports whether the optional JSONL interaction sidecar is enabled.
|
||||
// First-class issue history is always recorded in the database events tables;
|
||||
// this gate only controls .beads/interactions.jsonl.
|
||||
func Enabled() bool {
|
||||
if raw, ok := os.LookupEnv("BD_AUDIT_ENABLED"); ok {
|
||||
return truthy(raw)
|
||||
}
|
||||
return config.GetBool("audit.enabled")
|
||||
}
|
||||
|
||||
func truthy(raw string) bool {
|
||||
switch strings.ToLower(strings.TrimSpace(raw)) {
|
||||
case "1", "t", "true", "y", "yes", "on":
|
||||
return true
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
// EnsureFile creates .beads/interactions.jsonl if it does not exist.
|
||||
func EnsureFile() (string, error) {
|
||||
p, err := Path()
|
||||
|
|
@ -133,9 +154,18 @@ func Append(e *Entry) (string, error) {
|
|||
return e.ID, nil
|
||||
}
|
||||
|
||||
// AppendIfEnabled appends only when the optional JSONL sidecar is enabled.
|
||||
func AppendIfEnabled(e *Entry) (string, error) {
|
||||
if !Enabled() {
|
||||
return "", fmt.Errorf("audit JSONL sidecar is disabled; set audit.enabled=true or BD_AUDIT_ENABLED=1 to write %s", FileName)
|
||||
}
|
||||
return Append(e)
|
||||
}
|
||||
|
||||
// LogFieldChange logs a field change (status, assignee, priority, etc.) to the
|
||||
// audit log. This survives Dolt GC flatten, which destroys commit history.
|
||||
// Best-effort: errors are silently ignored so audit logging never blocks operations.
|
||||
// optional JSONL sidecar when it is enabled. First-class issue history is
|
||||
// recorded separately in the database events tables. Best-effort: errors are
|
||||
// silently ignored so sidecar logging never blocks operations.
|
||||
// Optional reason is included when non-empty (e.g., close reason, cleanup rule).
|
||||
func LogFieldChange(issueID, field, oldValue, newValue, actor, reason string) {
|
||||
if oldValue == newValue {
|
||||
|
|
@ -149,7 +179,7 @@ func LogFieldChange(issueID, field, oldValue, newValue, actor, reason string) {
|
|||
if reason != "" {
|
||||
extra["reason"] = reason
|
||||
}
|
||||
_, _ = Append(&Entry{
|
||||
_, _ = AppendIfEnabled(&Entry{
|
||||
Kind: "field_change",
|
||||
IssueID: issueID,
|
||||
Actor: actor,
|
||||
|
|
|
|||
|
|
@ -22,6 +22,7 @@ func TestAppend_CreatesFileAndWritesJSONL(t *testing.T) {
|
|||
t.Fatalf("write metadata.json: %v", err)
|
||||
}
|
||||
t.Setenv("BEADS_DIR", beadsDir)
|
||||
t.Setenv("BD_AUDIT_ENABLED", "1")
|
||||
|
||||
id1, err := Append(&Entry{Kind: "llm_call", Model: "test-model", Prompt: "p", Response: "r"})
|
||||
if err != nil {
|
||||
|
|
@ -55,6 +56,28 @@ func TestAppend_CreatesFileAndWritesJSONL(t *testing.T) {
|
|||
}
|
||||
}
|
||||
|
||||
func TestAppendIfEnabled_DisabledDoesNotCreateFile(t *testing.T) {
|
||||
tmp := t.TempDir()
|
||||
beadsDir := filepath.Join(tmp, ".beads")
|
||||
if err := os.MkdirAll(beadsDir, 0750); err != nil {
|
||||
t.Fatalf("mkdir: %v", err)
|
||||
}
|
||||
metadataPath := filepath.Join(beadsDir, "metadata.json")
|
||||
if err := os.WriteFile(metadataPath, []byte(`{"backend":"dolt"}`), 0644); err != nil {
|
||||
t.Fatalf("write metadata.json: %v", err)
|
||||
}
|
||||
t.Setenv("BEADS_DIR", beadsDir)
|
||||
t.Setenv("BD_AUDIT_ENABLED", "")
|
||||
|
||||
if _, err := AppendIfEnabled(&Entry{Kind: "llm_call", Model: "test-model"}); err == nil {
|
||||
t.Fatalf("expected disabled append to fail")
|
||||
}
|
||||
|
||||
if _, err := os.Stat(filepath.Join(beadsDir, FileName)); !os.IsNotExist(err) {
|
||||
t.Fatalf("disabled append created %s: %v", FileName, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEnsureFile_DoesNotTruncateWhenConcurrentCreatorWins(t *testing.T) {
|
||||
tmp := t.TempDir()
|
||||
beadsDir := filepath.Join(tmp, ".beads")
|
||||
|
|
|
|||
|
|
@ -42,6 +42,7 @@ func TestAppend_ConcurrentWritersUniqueIDs(t *testing.T) {
|
|||
t.Fatalf("write metadata.json: %v", err)
|
||||
}
|
||||
t.Setenv("BEADS_DIR", beadsDir)
|
||||
t.Setenv("BD_AUDIT_ENABLED", "1")
|
||||
|
||||
const (
|
||||
writers = 8
|
||||
|
|
|
|||
|
|
@ -171,6 +171,7 @@ func Initialize() error {
|
|||
// Set defaults for all flags
|
||||
v.SetDefault("json", false)
|
||||
v.SetDefault("events-export", false)
|
||||
v.SetDefault("audit.enabled", false)
|
||||
v.SetDefault("no-db", false)
|
||||
v.SetDefault("no-hooks", false)
|
||||
v.SetDefault("db", "")
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ func IsYamlOnlyKey(key string) bool {
|
|||
}
|
||||
|
||||
// Check prefix matches for nested keys
|
||||
prefixes := []string{"routing.", "sync.", "git.", "directory.", "repos.", "external_projects.", "validation.", "hierarchy.", "ai.", "backup.", "export.", "dolt.", "federation.", "metrics.", "list."}
|
||||
prefixes := []string{"routing.", "sync.", "git.", "directory.", "repos.", "external_projects.", "validation.", "hierarchy.", "ai.", "backup.", "export.", "dolt.", "federation.", "metrics.", "list.", "audit."}
|
||||
for _, prefix := range prefixes {
|
||||
if strings.HasPrefix(key, prefix) {
|
||||
return true
|
||||
|
|
|
|||
|
|
@ -186,9 +186,6 @@ func (u *beadsDirFSUseCaseImpl) InitializeBeadsDir(ctx context.Context, params I
|
|||
return InitializeBeadsDirResult{}, err
|
||||
}
|
||||
}
|
||||
if err := u.fsRepo.WriteInteractionsLog(ctx); err != nil {
|
||||
return InitializeBeadsDirResult{}, err
|
||||
}
|
||||
if err := u.fsRepo.WriteReadme(ctx); err != nil {
|
||||
return InitializeBeadsDirResult{}, err
|
||||
}
|
||||
|
|
|
|||
|
|
@ -10,9 +10,14 @@ Generated from `bd help --doc audit`
|
|||
|
||||
## bd audit
|
||||
|
||||
Audit log entries are appended to .beads/interactions.jsonl.
|
||||
Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
|
||||
|
||||
Each line is one event. This file is intended to be versioned in git and used for:
|
||||
This optional JSONL sidecar is disabled by default. Enable it with:
|
||||
|
||||
bd config set audit.enabled true
|
||||
|
||||
Issue history is always recorded in the database and is visible with
|
||||
bd history <id> --events. The JSONL sidecar is for explicit interaction capture:
|
||||
- auditing ("why did the agent do that?")
|
||||
- dataset generation (SFT/RL fine-tuning)
|
||||
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ where the issue was modified.
|
|||
Examples:
|
||||
bd history bd-123 # Show all history for issue bd-123
|
||||
bd history bd-123 --limit 5 # Show last 5 changes
|
||||
bd history bd-123 --events # Show database audit events
|
||||
|
||||
```
|
||||
bd history <id> [flags]
|
||||
|
|
@ -24,5 +25,6 @@ bd history <id> [flags]
|
|||
**Flags:**
|
||||
|
||||
```
|
||||
--events Show database audit events instead of commit snapshots
|
||||
--limit int Limit number of history entries (0 = all)
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue