diff --git a/changelog.d/added-18493-topic-pr-claims.md b/changelog.d/added-18493-topic-pr-claims.md new file mode 100644 index 0000000000..541b8a5046 --- /dev/null +++ b/changelog.d/added-18493-topic-pr-claims.md @@ -0,0 +1 @@ +- Long-lived agents can claim a topic for one pull request with `bd topic claim --repo --pr `: the claim is stored in the agent's bead store, a second open claim for the same topic is refused, the kick lists the agent's claims (also as `${TOPIC_CLAIMS}`) so it finds its PR by number after a branch rename, the FIX-BEFORE-NEW and held-PR blocks show the topic next to the PR, and hive releases the claim when the PR merges or closes. diff --git a/src/cmd/bd/main.go b/src/cmd/bd/main.go index 1e1edb4327..2fea464be9 100644 --- a/src/cmd/bd/main.go +++ b/src/cmd/bd/main.go @@ -77,6 +77,8 @@ func main() { cmdRemember(os.Args[2:]) case "kb": cmdKB(os.Args[2:]) + case "topic": + cmdTopic(os.Args[2:]) case "dolt": cmdDolt(os.Args[2:]) case "init": @@ -110,6 +112,10 @@ Commands: kb import-file [--name ] Import document from file kb list-docs List imported documents remember "" Quick-add an advisory bead + topic claim --repo o/r --pr N [--branch B] + Claim a topic for one PR (refused if held by another PR) + topic get [--json] | list [--json] | release + Read, list or release topic claims close Close a bead decompose [--plan ] [--actor ] Decompose an epic into a DAG of child task beads diff --git a/src/cmd/bd/topic.go b/src/cmd/bd/topic.go new file mode 100644 index 0000000000..45c35e49b7 --- /dev/null +++ b/src/cmd/bd/topic.go @@ -0,0 +1,167 @@ +package main + +import ( + "encoding/json" + "errors" + "flag" + "fmt" + "io" + "os" + + "github.com/hivecommons/hive/pkg/beads" +) + +// bd topic: durable one-PR-per-topic claims (hivecommons/hive#18493). +// +// bd topic claim --repo owner/name --pr N [--branch B] [--actor A] +// bd topic get [--json] +// bd topic list [--json] +// bd topic release +// +// Exit codes: 0 success, 1 usage or store error, 2 refused (the topic is +// held by a different PR) or not found on get. +const ( + topicExitOK = 0 + topicExitError = 1 + topicExitRefused = 2 +) + +const topicUsage = `Usage: + bd topic claim --repo owner/name --pr N [--branch B] [--actor A] + bd topic get [--json] + bd topic list [--json] + bd topic release ` + +func cmdTopic(args []string) { + if code := runTopic(args, openStore, os.Stdout, os.Stderr); code != topicExitOK { + os.Exit(code) + } +} + +// runTopic is cmdTopic without the process exit, so every path is testable +// in-process. +func runTopic(args []string, open func() *beads.Store, stdout, stderr io.Writer) int { + if len(args) < 1 { + fmt.Fprintln(stderr, topicUsage) + return topicExitError + } + sub, rest := args[0], args[1:] + switch sub { + case "list": + return topicList(rest, open, stdout, stderr) + case "claim", "get", "release": + default: + fmt.Fprintf(stderr, "bd topic: unknown subcommand %q\n%s\n", sub, topicUsage) + return topicExitError + } + if len(rest) < 1 || rest[0] == "" || rest[0][0] == '-' { + fmt.Fprintf(stderr, "bd topic %s: requires a topic key\n", sub) + return topicExitError + } + key, flags := rest[0], rest[1:] + switch sub { + case "claim": + return topicClaim(key, flags, open, stdout, stderr) + case "get": + return topicGet(key, flags, open, stdout, stderr) + default: + return topicRelease(key, open, stdout, stderr) + } +} + +func topicClaim(key string, args []string, open func() *beads.Store, stdout, stderr io.Writer) int { + fs := flag.NewFlagSet("topic claim", flag.ContinueOnError) + fs.SetOutput(stderr) + repo := fs.String("repo", "", "Repository as owner/name (required)") + pr := fs.Int("pr", 0, "Pull request number (required)") + branch := fs.String("branch", "", "Current head branch") + actor := fs.String("actor", os.Getenv("HIVE_AGENT"), "Claiming agent (default $HIVE_AGENT)") + if err := fs.Parse(args); err != nil { + return topicExitError + } + claim, err := open().ClaimTopic(*actor, beads.TopicClaim{Key: key, Repo: *repo, PR: *pr, Branch: *branch}) + if errors.Is(err, beads.ErrTopicClaimed) { + fmt.Fprintf(stderr, "bd topic claim: refused: %v (work on that PR, or release the topic first)\n", err) + return topicExitRefused + } + if err != nil { + fmt.Fprintf(stderr, "bd topic claim: %v\n", err) + return topicExitError + } + return writeTopicJSON(stdout, stderr, claim) +} + +func topicGet(key string, args []string, open func() *beads.Store, stdout, stderr io.Writer) int { + fs := flag.NewFlagSet("topic get", flag.ContinueOnError) + fs.SetOutput(stderr) + jsonOut := fs.Bool("json", false, "Output as JSON") + if err := fs.Parse(args); err != nil { + return topicExitError + } + claim, ok := open().Topic(key) + if !ok { + fmt.Fprintf(stderr, "bd topic get: no open claim for %q\n", key) + return topicExitRefused + } + if *jsonOut { + return writeTopicJSON(stdout, stderr, claim) + } + fmt.Fprintln(stdout, formatTopicLine(claim)) + return topicExitOK +} + +func topicList(args []string, open func() *beads.Store, stdout, stderr io.Writer) int { + fs := flag.NewFlagSet("topic list", flag.ContinueOnError) + fs.SetOutput(stderr) + jsonOut := fs.Bool("json", false, "Output as JSON") + if err := fs.Parse(args); err != nil { + return topicExitError + } + claims := open().OpenTopics() + if *jsonOut { + if claims == nil { + claims = []beads.TopicClaim{} + } + return writeTopicJSON(stdout, stderr, claims) + } + if len(claims) == 0 { + fmt.Fprintln(stdout, "No open topic claims.") + return topicExitOK + } + for _, c := range claims { + fmt.Fprintln(stdout, formatTopicLine(c)) + } + return topicExitOK +} + +func topicRelease(key string, open func() *beads.Store, stdout, stderr io.Writer) int { + released, err := open().ReleaseTopic(key, beads.TopicStateReleased) + if err != nil { + fmt.Fprintf(stderr, "bd topic release: %v\n", err) + return topicExitError + } + if !released { + fmt.Fprintf(stdout, "No open claim for %q\n", key) + return topicExitOK + } + fmt.Fprintf(stdout, "Released topic %q\n", key) + return topicExitOK +} + +func formatTopicLine(c beads.TopicClaim) string { + line := fmt.Sprintf("%s → %s#%d", c.Key, c.Repo, c.PR) + if c.Branch != "" { + line += " (branch " + c.Branch + ")" + } + return line +} + +func writeTopicJSON(stdout, stderr io.Writer, v interface{}) int { + enc := json.NewEncoder(stdout) + enc.SetIndent("", " ") + if err := enc.Encode(v); err != nil { + fmt.Fprintf(stderr, "bd topic: json encode error: %v\n", err) + return topicExitError + } + return topicExitOK +} diff --git a/src/cmd/bd/topic_test.go b/src/cmd/bd/topic_test.go new file mode 100644 index 0000000000..222c0a7882 --- /dev/null +++ b/src/cmd/bd/topic_test.go @@ -0,0 +1,103 @@ +package main + +import ( + "bytes" + "encoding/json" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/beads" +) + +func topicStoreOpener(t *testing.T) func() *beads.Store { + t.Helper() + dir := t.TempDir() + return func() *beads.Store { + s, err := beads.NewStore(dir) + if err != nil { + t.Fatal(err) + } + return s + } +} + +func runTopicT(open func() *beads.Store, args ...string) (int, string, string) { + var out, errOut bytes.Buffer + code := runTopic(args, open, &out, &errOut) + return code, out.String(), errOut.String() +} + +func TestTopicClaimGetListRelease(t *testing.T) { + open := topicStoreOpener(t) + t.Setenv("HIVE_AGENT", "deps") + + code, out, errOut := runTopicT(open, "claim", "deps-bump", "--repo", "acme/widget", "--pr", "12", "--branch", "deps/a") + if code != topicExitOK { + t.Fatalf("claim exit %d: %s", code, errOut) + } + var claim beads.TopicClaim + if err := json.Unmarshal([]byte(out), &claim); err != nil || claim.PR != 12 || claim.Actor != "deps" { + t.Fatalf("claim output %q (%v)", out, err) + } + + code, _, errOut = runTopicT(open, "claim", "deps-bump", "--repo", "acme/widget", "--pr", "13") + if code != topicExitRefused || !strings.Contains(errOut, "refused") || !strings.Contains(errOut, "acme/widget#12") { + t.Fatalf("second claim exit %d: %s", code, errOut) + } + + if code, out, _ = runTopicT(open, "get", "deps-bump"); code != topicExitOK || !strings.Contains(out, "deps-bump → acme/widget#12 (branch deps/a)") { + t.Fatalf("get exit %d: %q", code, out) + } + if code, out, _ = runTopicT(open, "get", "deps-bump", "--json"); code != topicExitOK || !strings.Contains(out, `"pr": 12`) { + t.Fatalf("get --json exit %d: %q", code, out) + } + if code, out, _ = runTopicT(open, "list"); code != topicExitOK || !strings.Contains(out, "deps-bump → acme/widget#12") { + t.Fatalf("list exit %d: %q", code, out) + } + if code, out, _ = runTopicT(open, "list", "--json"); code != topicExitOK || !strings.Contains(out, `"key": "deps-bump"`) { + t.Fatalf("list --json exit %d: %q", code, out) + } + + if code, out, _ = runTopicT(open, "release", "deps-bump"); code != topicExitOK || !strings.Contains(out, "Released") { + t.Fatalf("release exit %d: %q", code, out) + } + if code, out, _ = runTopicT(open, "release", "deps-bump"); code != topicExitOK || !strings.Contains(out, "No open claim") { + t.Fatalf("second release exit %d: %q", code, out) + } + if code, _, _ = runTopicT(open, "get", "deps-bump"); code != topicExitRefused { + t.Fatalf("get after release exit %d", code) + } + if code, out, _ = runTopicT(open, "list"); code != topicExitOK || !strings.Contains(out, "No open topic claims.") { + t.Fatalf("empty list exit %d: %q", code, out) + } + if code, out, _ = runTopicT(open, "list", "--json"); code != topicExitOK || strings.TrimSpace(out) != "[]" { + t.Fatalf("empty list --json exit %d: %q", code, out) + } +} + +func TestTopicUsageErrors(t *testing.T) { + open := topicStoreOpener(t) + for name, args := range map[string][]string{ + "no subcommand": {}, + "unknown": {"frob"}, + "missing key": {"claim"}, + "flag as key": {"get", "--json"}, + "bad claim flag": {"claim", "k", "--nope"}, + "claim no pr": {"claim", "k", "--repo", "a/b"}, + "bad get flag": {"get", "k", "--nope"}, + "bad list flag": {"list", "--nope"}, + "bad release key": {"release", "a b"}, + } { + if code, _, _ := runTopicT(open, args...); code != topicExitError { + t.Errorf("%s: exit %d, want %d", name, code, topicExitError) + } + } +} + +func TestMainDispatchTopic(t *testing.T) { + t.Setenv("BD_DIR", t.TempDir()) + out := runMain(t, "topic", "list") + if !strings.Contains(out, "No open topic claims.") { + t.Fatalf("main(topic list) = %q", out) + } +} diff --git a/src/cmd/hive/github_client_config.go b/src/cmd/hive/github_client_config.go index b9908ca338..289d6e88dd 100644 --- a/src/cmd/hive/github_client_config.go +++ b/src/cmd/hive/github_client_config.go @@ -382,9 +382,17 @@ func (b *boot) applyGitHubClientDashboardHooks(client *github.Client) { // governor's cached snapshot now, instead of waiting for GitHub's // `closed` delivery to come back round through the hub. evictHiveClosedPR(b.dashSrv, rec, time.Now()) + // #18493: a PR the hive merged or closed releases its topic claim. + if state := topicStateForAudit(rec.Action); state != "" { + releaseTopicClaimsForPR(b.beadStores, rec.Repo, rec.Target, state, b.logger) + } }) client.SetPRTerminalObservedHook(func(obs github.PRTerminalObservation) { ts := obs.ObservedAt.UTC().Format(time.RFC3339) + // #18493: an observed merge or close releases the PR's topic claim. + if state := topicStateForTerminal(obs.State); state != "" { + releaseTopicClaimsForPR(b.beadStores, obs.Repo, obs.Number, state, b.logger) + } switch obs.State { case github.PRStateMerged: path := obs.Attribution diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index af8950203b..5095272d26 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -3518,6 +3518,10 @@ func (b *boot) bootSupervision() { // Dashboard maintainer notes on a listed item ride its kick as private // context (pkg/scheduler/kick_maintainer_notes.go). b.sched.SetMaintainerNotesLookup(maintainernotes.Default().List) + // #18493: agents' durable topic claims (bd topic) ride their kicks and tag + // the PR rows of the FIX-BEFORE-NEW and held-PR blocks. Read b.beadStores + // at call time, not at wire time. + b.sched.SetTopicClaimLookup(func() []scheduler.TopicClaim { return topicClaimLookup(b.beadStores)() }) // #9584: close answered question issues unless the author objects (default off). b.questionAutoclose.Store(wireQuestionAutoclose(b.ctx, b.cfg, b.sched, func() *github.Client { return b.ghClient }, b.logger)) // The pr-request watcher's PR-opened hook (Linear session narration, the diff --git a/src/cmd/hive/main_eval_cycle.go b/src/cmd/hive/main_eval_cycle.go index 26e660c119..fc849c158a 100644 --- a/src/cmd/hive/main_eval_cycle.go +++ b/src/cmd/hive/main_eval_cycle.go @@ -1344,6 +1344,9 @@ func runEvalCycle( // stores can become stale between eval cycles. Reload failures are deduped // (WARN once per distinct error, then DEBUG) — see beads_reload.go (#5505). reloadBeadStores(beadStores, logger) + // #18493: release topic claims whose PR merged or closed, and follow a + // claimed PR's renamed head branch. + syncTopicClaims(beadStores, actionable, logger) // Phase 4 Part B: `plan`/`epic` label trigger. An actionable issue carrying a // plan label auto-mints an epic and requests decomposition — the same flow as diff --git a/src/cmd/hive/topic_claims.go b/src/cmd/hive/topic_claims.go new file mode 100644 index 0000000000..8bd8f77552 --- /dev/null +++ b/src/cmd/hive/topic_claims.go @@ -0,0 +1,150 @@ +package main + +import ( + "log/slog" + "sort" + "strings" + + "github.com/hivecommons/hive/pkg/beads" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/scheduler" +) + +// Topic-claim wiring (hivecommons/hive#18493). Agents write claims into their +// own bead store with `bd topic claim`; the governor reads them for the kick +// (scheduler.SetTopicClaimLookup), follows a claimed PR's head branch across +// renames, and releases a claim once its PR merges or closes. + +// topicClaimLookup projects every agent's open topic claims for the +// scheduler. Stores are read in agent-name order so the kick is stable. +func topicClaimLookup(stores map[string]*beads.Store) scheduler.TopicClaimLookup { + return func() []scheduler.TopicClaim { + names := make([]string, 0, len(stores)) + for name := range stores { + names = append(names, name) + } + sort.Strings(names) + var out []scheduler.TopicClaim + for _, name := range names { + store := stores[name] + if store == nil { + continue + } + for _, c := range store.OpenTopics() { + out = append(out, scheduler.TopicClaim{Agent: name, Key: c.Key, Repo: c.Repo, PR: c.PR, Branch: c.Branch}) + } + } + return out + } +} + +// releaseTopicClaimsForPR ends every agent's open claim held through +// repo#number once the PR reached a terminal state (beads.TopicStateMerged +// or beads.TopicStateClosed). It returns how many claims were released. +func releaseTopicClaimsForPR(stores map[string]*beads.Store, repo string, number int, state string, logger *slog.Logger) int { + if repo == "" || number <= 0 { + return 0 + } + total := 0 + for name, store := range stores { + if store == nil { + continue + } + n, err := store.ReleaseTopicsForPR(repo, number, state) + if err != nil && logger != nil { + logger.Warn("topic claim release failed", "agent", name, "repo", repo, "pr", number, "error", err) + } + if n > 0 && logger != nil { + logger.Info("topic claim released", "agent", name, "repo", repo, "pr", number, "state", state, "count", n) + } + total += n + } + return total +} + +// topicStateForPR maps a PR's observed state to the claim state that ends a +// claim, or "" while the PR is still open. +func topicStateForPR(pr github.PullRequest) string { + if !pr.MergedAt.IsZero() || strings.EqualFold(pr.State, github.PRStateMerged) { + return beads.TopicStateMerged + } + if strings.EqualFold(pr.State, github.PRStateClosed) { + return beads.TopicStateClosed + } + return "" +} + +// topicStateForTerminal maps a merged/closed observation or audit state to a +// claim state, or "" for anything else. +func topicStateForTerminal(state string) string { + switch state { + case github.PRStateMerged: + return beads.TopicStateMerged + case github.PRStateClosed: + return beads.TopicStateClosed + } + return "" +} + +// topicStateForAudit maps the hive's own merge/close audit action to a claim +// state, or "" for any other action. +func topicStateForAudit(action string) string { + switch action { + case github.AuditActionPRMerged: + return beads.TopicStateMerged + case github.AuditActionPRClosed: + return beads.TopicStateClosed + } + return "" +} + +// syncTopicClaims is the poll path, run each eval cycle after the bead stores +// reload: a claimed PR the snapshot shows merged or closed releases its +// claim, and an open one whose head branch changed updates the claim's +// branch so the record follows a rename. +func syncTopicClaims(stores map[string]*beads.Store, actionable *github.ActionableResult, logger *slog.Logger) { + if actionable == nil || len(stores) == 0 { + return + } + prs := make([]github.PullRequest, 0, len(actionable.PRs.Items)+len(actionable.PRs.Held)+len(actionable.PRs.Attributed)) + prs = append(prs, actionable.PRs.Items...) + prs = append(prs, actionable.PRs.Held...) + prs = append(prs, actionable.PRs.Attributed...) + for name, store := range stores { + if store == nil { + continue + } + for _, claim := range store.OpenTopics() { + pr, ok := findTopicPR(prs, claim) + if !ok { + continue + } + if state := topicStateForPR(pr); state != "" { + releaseTopicClaimsForPR(map[string]*beads.Store{name: store}, claim.Repo, claim.PR, state, logger) + continue + } + if pr.HeadRef == "" || pr.HeadRef == claim.Branch { + continue + } + if _, err := store.SetTopicBranch(claim.Repo, claim.PR, pr.HeadRef); err != nil && logger != nil { + logger.Warn("topic claim branch refresh failed", "agent", name, "topic", claim.Key, "error", err) + } + } + } +} + +// findTopicPR returns the snapshot's copy of the claim's PR. A terminal copy +// wins over an open one, since Attributed can carry a PR that left Items. +func findTopicPR(prs []github.PullRequest, claim beads.TopicClaim) (github.PullRequest, bool) { + var found github.PullRequest + ok := false + for _, pr := range prs { + if pr.Number != claim.PR || !beads.SameTopicRepo(pr.Repo, claim.Repo) { + continue + } + if !ok || topicStateForPR(pr) != "" { + found, ok = pr, true + } + } + return found, ok +} diff --git a/src/cmd/hive/topic_claims_test.go b/src/cmd/hive/topic_claims_test.go new file mode 100644 index 0000000000..afdb8e1538 --- /dev/null +++ b/src/cmd/hive/topic_claims_test.go @@ -0,0 +1,122 @@ +package main + +import ( + "io" + "log/slog" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/beads" + "github.com/hivecommons/hive/pkg/github" +) + +func topicTestStores(t *testing.T, names ...string) map[string]*beads.Store { + t.Helper() + out := make(map[string]*beads.Store, len(names)) + for _, name := range names { + s, err := beads.NewStore(t.TempDir()) + if err != nil { + t.Fatal(err) + } + out[name] = s + } + return out +} + +func quietTopicLogger() *slog.Logger { return slog.New(slog.NewTextHandler(io.Discard, nil)) } + +func TestTopicClaimLookupProjectsEveryStore(t *testing.T) { + stores := topicTestStores(t, "deps", "release") + stores["empty"] = nil + _, _ = stores["deps"].ClaimTopic("deps", beads.TopicClaim{Key: "deps-bump", Repo: "acme/widget", PR: 3, Branch: "b"}) + _, _ = stores["release"].ClaimTopic("release", beads.TopicClaim{Key: "rel", Repo: "acme/widget", PR: 4}) + got := topicClaimLookup(stores)() + if len(got) != 2 || got[0].Agent != "deps" || got[0].Key != "deps-bump" || got[0].Branch != "b" || got[1].Agent != "release" || got[1].PR != 4 { + t.Fatalf("lookup = %+v", got) + } +} + +func TestReleaseTopicClaimsForPR(t *testing.T) { + stores := topicTestStores(t, "deps") + stores["nil"] = nil + _, _ = stores["deps"].ClaimTopic("deps", beads.TopicClaim{Key: "k", Repo: "acme/widget", PR: 3}) + if n := releaseTopicClaimsForPR(stores, "", 3, beads.TopicStateMerged, quietTopicLogger()); n != 0 { + t.Fatalf("empty repo released %d", n) + } + if n := releaseTopicClaimsForPR(stores, "widget", 3, beads.TopicStateMerged, quietTopicLogger()); n != 1 { + t.Fatalf("released %d, want 1", n) + } + if _, ok := stores["deps"].Topic("k"); ok { + t.Fatal("claim still open after merge") + } +} + +func TestTopicStateMappings(t *testing.T) { + if topicStateForPR(github.PullRequest{MergedAt: time.Now()}) != beads.TopicStateMerged || + topicStateForPR(github.PullRequest{State: "merged"}) != beads.TopicStateMerged || + topicStateForPR(github.PullRequest{State: "closed"}) != beads.TopicStateClosed || + topicStateForPR(github.PullRequest{State: "open"}) != "" { + t.Fatal("topicStateForPR mismatch") + } + if topicStateForTerminal(github.PRStateMerged) != beads.TopicStateMerged || + topicStateForTerminal(github.PRStateClosed) != beads.TopicStateClosed || + topicStateForTerminal("open") != "" { + t.Fatal("topicStateForTerminal mismatch") + } + if topicStateForAudit(github.AuditActionPRMerged) != beads.TopicStateMerged || + topicStateForAudit(github.AuditActionPRClosed) != beads.TopicStateClosed || + topicStateForAudit("other") != "" { + t.Fatal("topicStateForAudit mismatch") + } +} + +func TestSyncTopicClaimsFollowsRenameAndReleases(t *testing.T) { + stores := topicTestStores(t, "deps") + stores["nil"] = nil + s := stores["deps"] + _, _ = s.ClaimTopic("deps", beads.TopicClaim{Key: "renamed", Repo: "acme/widget", PR: 1, Branch: "old"}) + _, _ = s.ClaimTopic("deps", beads.TopicClaim{Key: "merged", Repo: "acme/widget", PR: 2}) + _, _ = s.ClaimTopic("deps", beads.TopicClaim{Key: "closed", Repo: "acme/widget", PR: 3}) + _, _ = s.ClaimTopic("deps", beads.TopicClaim{Key: "unseen", Repo: "acme/widget", PR: 4, Branch: "keep"}) + _, _ = s.ClaimTopic("deps", beads.TopicClaim{Key: "nohead", Repo: "acme/widget", PR: 5, Branch: "keep"}) + + actionable := &github.ActionableResult{PRs: github.PRResult{ + Items: []github.PullRequest{ + {Repo: "widget", Number: 1, HeadRef: "new", State: "open"}, + {Repo: "widget", Number: 2, HeadRef: "x", State: "open"}, + {Repo: "widget", Number: 5, State: "open"}, + }, + Held: []github.PullRequest{{Repo: "acme/widget", Number: 3, State: "closed"}}, + Attributed: []github.PullRequest{{Repo: "acme/widget", Number: 2, MergedAt: time.Now(), State: "closed"}}, + }} + syncTopicClaims(stores, actionable, quietTopicLogger()) + + open := map[string]beads.TopicClaim{} + for _, c := range s.OpenTopics() { + open[c.Key] = c + } + if len(open) != 3 { + t.Fatalf("open claims = %+v", open) + } + if open["renamed"].Branch != "new" { + t.Errorf("branch did not follow rename: %+v", open["renamed"]) + } + if open["unseen"].Branch != "keep" || open["nohead"].Branch != "keep" { + t.Errorf("unrelated claims changed: %+v", open) + } + for _, b := range s.List(beads.ListFilter{}) { + switch b.Meta(beads.MetaTopicKey) { + case "merged": + if b.Meta(beads.MetaTopicState) != beads.TopicStateMerged { + t.Errorf("merged claim state = %q", b.Meta(beads.MetaTopicState)) + } + case "closed": + if b.Meta(beads.MetaTopicState) != beads.TopicStateClosed { + t.Errorf("closed claim state = %q", b.Meta(beads.MetaTopicState)) + } + } + } + + syncTopicClaims(stores, nil, quietTopicLogger()) + syncTopicClaims(nil, actionable, quietTopicLogger()) +} diff --git a/src/docs/beads-cli.md b/src/docs/beads-cli.md index c9165ba067..34dea591c3 100644 --- a/src/docs/beads-cli.md +++ b/src/docs/beads-cli.md @@ -17,8 +17,42 @@ | `bd remember "fact"` | Quick-add an advisory bead authored by `system`. | | `bd init` | No-op compatibility command; opening the store creates it. | | `bd dolt push` | No-op compatibility command; bead data is already persisted on disk. | +| `bd topic claim --repo --pr [--branch ] [--actor ]` | Claim a topic for one pull request. See [Topic claims](#topic-claims). | +| `bd topic get [--json]` / `bd topic list [--json]` / `bd topic release ` | Read, list or release topic claims. | | `bd decompose [--plan ] [--actor ] [--auto-approve] [--print-prompt]` | Decompose an epic bead into a DAG of child task beads. See below. | +## Topic claims + +A long-lived agent that owns one ongoing topic (a dependency-bump PR, a release +PR) records which pull request carries it, so it finds that PR by number on +every later kick instead of by branch name (hivecommons/hive#18493). + +```bash +bd topic claim deps-bump --repo acme/widget --pr 412 --branch deps/bump-go +bd topic get deps-bump # deps-bump → acme/widget#412 (branch deps/bump-go) +bd topic list --json +bd topic release deps-bump +``` + +- The claim is one `in_progress` chore bead in the agent's own store, with + `external_ref` `topic:` and metadata `topic_key`, `topic_repo`, + `topic_pr`, `topic_branch` and `topic_state`. Keys are lowercased and may + not contain whitespace. +- At most one claim per key is open. Claiming an open key again for the same + PR is idempotent and updates the branch; claiming it for a different PR is + refused with exit code `2` and names the PR that holds it. `bd topic get` + also exits `2` when no claim is open. +- `--actor` defaults to `$HIVE_AGENT`. +- Hive releases a claim when its PR merges or closes (`topic_state` becomes + `merged` or `closed`): on the hive's own merge or close, on an observed + terminal PR, and on each eval cycle's snapshot. The same eval-cycle pass + updates `topic_branch` when the PR's head branch was renamed. + `bd topic release` records `released`. `bd reset` closes open claims too. +- The kick shows an agent its open claims in a `📌 Topic claims` block, also + available to kick templates as `${TOPIC_CLAIMS}` (which renders the usage + lines even when the agent holds no claim). The FIX-BEFORE-NEW and hold-gated + PR blocks tag a claimed PR with `[topic: ]`. + ## Decomposing an epic `bd decompose` turns one epic bead into a graph of child task beads, wiring diff --git a/src/pkg/beads/topic.go b/src/pkg/beads/topic.go new file mode 100644 index 0000000000..8298be90ad --- /dev/null +++ b/src/pkg/beads/topic.go @@ -0,0 +1,322 @@ +package beads + +import ( + "errors" + "fmt" + "sort" + "strconv" + "strings" + "time" + + "github.com/google/uuid" +) + +// Topic claims (hivecommons/hive#18493). +// +// A long-lived agent that owns one ongoing topic (a dependency-bump PR, a +// release PR) used to find its own PR by branch name. A renamed or deleted +// branch, or a second branch, lost its place and it opened a duplicate PR. +// A topic claim is a durable record in the agent's own bead store: +// +// topic key -> {repo, PR number, branch, state} +// +// stored as one in_progress chore bead whose ExternalRef is "topic:". +// The PR number is the identity; the branch is informational and is +// refreshed by the governor when the PR's head ref changes. At most one OPEN +// claim exists per key per store, and a claim for a different PR under an +// open key is refused. The governor releases the claim (closes the bead with +// topic_state merged/closed) when the PR merges or closes. + +const ( + // TopicRefPrefix prefixes the ExternalRef of a topic-claim bead. + TopicRefPrefix = "topic:" + + // Metadata keys a topic-claim bead carries. + MetaTopicKey = "topic_key" + MetaTopicRepo = "topic_repo" + MetaTopicPR = "topic_pr" + MetaTopicBranch = "topic_branch" + MetaTopicState = "topic_state" + + // TopicStateOpen is a live claim; the others record why it ended. + TopicStateOpen = "open" + TopicStateMerged = "merged" + TopicStateClosed = "closed" + TopicStateReleased = "released" + + // maxTopicKeyLen bounds a topic key so a pasted paragraph is rejected + // instead of becoming a key. + maxTopicKeyLen = 128 +) + +// ErrTopicClaimed is returned when a topic already has an open claim for a +// different pull request. +var ErrTopicClaimed = errors.New("topic already claimed") + +// TopicClaim is one topic-claim record, projected from its bead. +type TopicClaim struct { + Key string `json:"key"` + Repo string `json:"repo"` + PR int `json:"pr"` + Branch string `json:"branch,omitempty"` + State string `json:"state"` + Actor string `json:"actor,omitempty"` + BeadID string `json:"bead_id"` + UpdatedAt time.Time `json:"updated_at"` +} + +// NormalizeTopicKey trims and lowercases a topic key and rejects an empty, +// over-long or whitespace-carrying one. +func NormalizeTopicKey(key string) (string, error) { + k := strings.ToLower(strings.TrimSpace(key)) + if k == "" { + return "", errors.New("topic key is empty") + } + if len(k) > maxTopicKeyLen { + return "", fmt.Errorf("topic key longer than %d bytes", maxTopicKeyLen) + } + if strings.ContainsAny(k, " \t\r\n") { + return "", errors.New("topic key must not contain whitespace") + } + return k, nil +} + +// SameTopicRepo reports whether two repository spellings name the same repo. +// "owner/name" is compared whole when both sides carry an owner; otherwise +// only the name part is compared, because some hive surfaces carry the bare +// repo name. +func SameTopicRepo(a, b string) bool { + a, b = strings.ToLower(strings.TrimSpace(a)), strings.ToLower(strings.TrimSpace(b)) + if a == "" || b == "" { + return false + } + if strings.Contains(a, "/") && strings.Contains(b, "/") { + return a == b + } + return repoName(a) == repoName(b) +} + +func repoName(r string) string { + if i := strings.LastIndex(r, "/"); i >= 0 { + return r[i+1:] + } + return r +} + +func isTopicBead(b *Bead) bool { + return b != nil && strings.HasPrefix(b.ExternalRef, TopicRefPrefix) +} + +func isOpenTopicBead(b *Bead) bool { + return isTopicBead(b) && b.Status != StatusClosed && b.Status != StatusDone +} + +func topicFromBead(b *Bead) TopicClaim { + pr, _ := strconv.Atoi(b.Meta(MetaTopicPR)) + state := b.Meta(MetaTopicState) + if state == "" { + state = TopicStateOpen + } + return TopicClaim{ + Key: strings.TrimPrefix(b.ExternalRef, TopicRefPrefix), + Repo: b.Meta(MetaTopicRepo), + PR: pr, + Branch: b.Meta(MetaTopicBranch), + State: state, + Actor: b.Actor, + BeadID: b.ID, + UpdatedAt: b.UpdatedAt.Time, + } +} + +// openTopicBead returns the open bead for key. Caller holds s.mu. +func (s *Store) openTopicBead(key string) *Bead { + ref := TopicRefPrefix + key + for _, b := range s.beads { + if b.ExternalRef == ref && isOpenTopicBead(b) { + return b + } + } + return nil +} + +// ClaimTopic records that actor owns topic c.Key through pull request +// c.Repo#c.PR. Claiming an open topic again for the same PR is idempotent and +// refreshes its branch (a branch rename); claiming it for a different PR +// returns ErrTopicClaimed together with the existing claim. +func (s *Store) ClaimTopic(actor string, c TopicClaim) (TopicClaim, error) { + key, err := NormalizeTopicKey(c.Key) + if err != nil { + return TopicClaim{}, err + } + repo := strings.TrimSpace(c.Repo) + if repo == "" { + return TopicClaim{}, errors.New("topic claim needs a repo") + } + if c.PR <= 0 { + return TopicClaim{}, errors.New("topic claim needs a pull request number") + } + branch := strings.TrimSpace(c.Branch) + + s.mu.Lock() + defer s.mu.Unlock() + defer s.lockAndRefresh()() + + now := flexTime{time.Now().UTC()} + if b := s.openTopicBead(key); b != nil { + existing := topicFromBead(b) + if existing.PR != c.PR || !SameTopicRepo(existing.Repo, repo) { + return existing, fmt.Errorf("%w: %s is held by %s#%d", ErrTopicClaimed, key, existing.Repo, existing.PR) + } + if branch != "" && branch != existing.Branch { + if b.Metadata == nil { + b.Metadata = make(map[string]interface{}) + } + b.Metadata[MetaTopicBranch] = branch + b.UpdatedAt = now + if err := s.persist(b); err != nil { + return existing, err + } + } + return topicFromBead(b), nil + } + + metadata := map[string]interface{}{ + MetaTopicKey: key, + MetaTopicRepo: repo, + MetaTopicPR: strconv.Itoa(c.PR), + MetaTopicBranch: branch, + MetaTopicState: TopicStateOpen, + } + if s.hiveID != "" { + metadata[hiveIDMetadataKey] = s.hiveID + } + b := &Bead{ + ID: uuid.New().String()[:12], + Title: "topic: " + key, + Type: TypeChore, + Status: StatusInProgress, + Priority: PriorityMedium, + Actor: actor, + ExternalRef: TopicRefPrefix + key, + Metadata: metadata, + CreatedAt: now, + UpdatedAt: now, + } + s.beads[b.ID] = b + s.evictOldClosed() + if err := s.persist(b); err != nil { + return TopicClaim{}, err + } + return topicFromBead(b), nil +} + +// Topic returns the open claim for key. +func (s *Store) Topic(key string) (TopicClaim, bool) { + k, err := NormalizeTopicKey(key) + if err != nil { + return TopicClaim{}, false + } + s.mu.RLock() + defer s.mu.RUnlock() + if b := s.openTopicBead(k); b != nil { + return topicFromBead(b), true + } + return TopicClaim{}, false +} + +// OpenTopics returns every open topic claim, sorted by key. +func (s *Store) OpenTopics() []TopicClaim { + s.mu.RLock() + defer s.mu.RUnlock() + var out []TopicClaim + for _, b := range s.beads { + if isOpenTopicBead(b) { + out = append(out, topicFromBead(b)) + } + } + sort.Slice(out, func(i, j int) bool { return out[i].Key < out[j].Key }) + return out +} + +// ReleaseTopic ends the open claim for key, recording state (merged, closed +// or released). It reports whether a claim was open. +func (s *Store) ReleaseTopic(key, state string) (bool, error) { + k, err := NormalizeTopicKey(key) + if err != nil { + return false, err + } + return s.mutateOpenTopics(func(b *Bead) bool { return strings.TrimPrefix(b.ExternalRef, TopicRefPrefix) == k }, + func(b *Bead, now flexTime) { closeTopicBead(b, state, now) }) +} + +// ReleaseTopicsForPR ends every open claim held through repo#pr, recording +// state. It returns how many were released. +func (s *Store) ReleaseTopicsForPR(repo string, pr int, state string) (int, error) { + if pr <= 0 { + return 0, nil + } + n := 0 + _, err := s.mutateOpenTopics(func(b *Bead) bool { return topicMatchesPR(b, repo, pr) }, + func(b *Bead, now flexTime) { closeTopicBead(b, state, now); n++ }) + return n, err +} + +// SetTopicBranch records the current head branch of repo#pr on every open +// claim held through it, so the record follows a renamed branch. It returns +// how many claims changed. +func (s *Store) SetTopicBranch(repo string, pr int, branch string) (int, error) { + branch = strings.TrimSpace(branch) + if pr <= 0 || branch == "" { + return 0, nil + } + n := 0 + _, err := s.mutateOpenTopics(func(b *Bead) bool { + return topicMatchesPR(b, repo, pr) && b.Meta(MetaTopicBranch) != branch + }, func(b *Bead, now flexTime) { + b.Metadata[MetaTopicBranch] = branch + b.UpdatedAt = now + n++ + }) + return n, err +} + +func topicMatchesPR(b *Bead, repo string, pr int) bool { + got, _ := strconv.Atoi(b.Meta(MetaTopicPR)) + return got == pr && SameTopicRepo(b.Meta(MetaTopicRepo), repo) +} + +func closeTopicBead(b *Bead, state string, now flexTime) { + if state == "" { + state = TopicStateReleased + } + b.Metadata[MetaTopicState] = state + b.Status = StatusClosed + b.ClosedAt = &now + b.UpdatedAt = now +} + +// mutateOpenTopics applies fn to every open topic bead match accepts, under +// the store and cross-process locks, and persists once if any changed. +func (s *Store) mutateOpenTopics(match func(*Bead) bool, fn func(*Bead, flexTime)) (bool, error) { + s.mu.Lock() + defer s.mu.Unlock() + defer s.lockAndRefresh()() + + now := flexTime{time.Now().UTC()} + changed := false + for _, b := range s.beads { + if !isOpenTopicBead(b) || !match(b) { + continue + } + if b.Metadata == nil { + b.Metadata = make(map[string]interface{}) + } + fn(b, now) + changed = true + } + if !changed { + return false, nil + } + return true, s.persist(nil) +} diff --git a/src/pkg/beads/topic_test.go b/src/pkg/beads/topic_test.go new file mode 100644 index 0000000000..565a21fd81 --- /dev/null +++ b/src/pkg/beads/topic_test.go @@ -0,0 +1,158 @@ +package beads + +import ( + "errors" + "strings" + "testing" +) + +func newTopicStore(t *testing.T) *Store { + t.Helper() + s, err := NewStore(t.TempDir()) + if err != nil { + t.Fatal(err) + } + s.SetHiveID("hive-test") + return s +} + +func TestClaimTopicRefusesSecondOpenClaimAndFollowsRename(t *testing.T) { + s := newTopicStore(t) + got, err := s.ClaimTopic("deps", TopicClaim{Key: " Deps-Bump ", Repo: "acme/widget", PR: 12, Branch: "deps/a"}) + if err != nil { + t.Fatal(err) + } + if got.Key != "deps-bump" || got.PR != 12 || got.Branch != "deps/a" || got.State != TopicStateOpen || got.Actor != "deps" || got.BeadID == "" { + t.Fatalf("claim = %+v", got) + } + + // Same PR again (a later kick, the branch renamed): idempotent, branch follows. + again, err := s.ClaimTopic("deps", TopicClaim{Key: "deps-bump", Repo: "ACME/widget", PR: 12, Branch: "deps/b"}) + if err != nil || again.BeadID != got.BeadID || again.Branch != "deps/b" { + t.Fatalf("re-claim = %+v, %v", again, err) + } + // Same PR with no branch keeps the recorded one. + if keep, err := s.ClaimTopic("deps", TopicClaim{Key: "deps-bump", Repo: "acme/widget", PR: 12}); err != nil || keep.Branch != "deps/b" { + t.Fatalf("re-claim without branch = %+v, %v", keep, err) + } + + // A different PR for the open topic is refused and names the holder. + held, err := s.ClaimTopic("deps", TopicClaim{Key: "deps-bump", Repo: "acme/widget", PR: 13}) + if !errors.Is(err, ErrTopicClaimed) || held.PR != 12 || !strings.Contains(err.Error(), "acme/widget#12") { + t.Fatalf("second claim = %+v, %v", held, err) + } + if _, err := s.ClaimTopic("deps", TopicClaim{Key: "deps-bump", Repo: "other/widget", PR: 12}); !errors.Is(err, ErrTopicClaimed) { + t.Fatalf("same number in another repo must be refused, got %v", err) + } + + // Durable: a fresh store on the same dir sees the claim. + reopened, err := NewStore(s.dir) + if err != nil { + t.Fatal(err) + } + c, ok := reopened.Topic("DEPS-BUMP") + if !ok || c.PR != 12 || c.Branch != "deps/b" { + t.Fatalf("reopened Topic = %+v, %v", c, ok) + } + if b, _ := reopened.Get(c.BeadID); b.Meta(hiveIDMetadataKey) != "hive-test" || b.Status != StatusInProgress || b.Type != TypeChore { + t.Fatalf("bead = %+v", b) + } +} + +func TestClaimTopicValidation(t *testing.T) { + s := newTopicStore(t) + for name, c := range map[string]TopicClaim{ + "empty key": {Key: " ", Repo: "a/b", PR: 1}, + "space key": {Key: "a b", Repo: "a/b", PR: 1}, + "long key": {Key: strings.Repeat("k", maxTopicKeyLen+1), Repo: "a/b", PR: 1}, + "no repo": {Key: "k", PR: 1}, + "no pr": {Key: "k", Repo: "a/b"}, + "negative": {Key: "k", Repo: "a/b", PR: -1}, + } { + if _, err := s.ClaimTopic("x", c); err == nil { + t.Errorf("%s: claim accepted", name) + } + } + if _, ok := s.Topic("bad key"); ok { + t.Error("Topic accepted an invalid key") + } + if _, err := s.ReleaseTopic("", TopicStateReleased); err == nil { + t.Error("ReleaseTopic accepted an empty key") + } +} + +func TestReleaseTopicAndReclaim(t *testing.T) { + s := newTopicStore(t) + first, _ := s.ClaimTopic("deps", TopicClaim{Key: "k", Repo: "acme/widget", PR: 1}) + released, err := s.ReleaseTopic("k", "") + if err != nil || !released { + t.Fatalf("release = %v, %v", released, err) + } + if _, ok := s.Topic("k"); ok { + t.Fatal("released topic still open") + } + b, _ := s.Get(first.BeadID) + if b.Status != StatusClosed || b.Meta(MetaTopicState) != TopicStateReleased || b.ClosedAt == nil { + t.Fatalf("released bead = %+v", b) + } + if again, err := s.ReleaseTopic("k", TopicStateReleased); err != nil || again { + t.Fatalf("second release = %v, %v", again, err) + } + // Released: a new PR may claim the topic. + if c, err := s.ClaimTopic("deps", TopicClaim{Key: "k", Repo: "acme/widget", PR: 2}); err != nil || c.BeadID == first.BeadID { + t.Fatalf("reclaim = %+v, %v", c, err) + } +} + +func TestReleaseTopicsForPRAndSetBranch(t *testing.T) { + s := newTopicStore(t) + _, _ = s.ClaimTopic("deps", TopicClaim{Key: "a", Repo: "acme/widget", PR: 5, Branch: "old"}) + _, _ = s.ClaimTopic("deps", TopicClaim{Key: "b", Repo: "acme/widget", PR: 6}) + + if n, err := s.SetTopicBranch("widget", 5, "new"); err != nil || n != 1 { + t.Fatalf("SetTopicBranch = %d, %v", n, err) + } + if n, _ := s.SetTopicBranch("widget", 5, "new"); n != 0 { + t.Fatalf("unchanged branch counted %d", n) + } + if n, _ := s.SetTopicBranch("widget", 5, " "); n != 0 { + t.Fatalf("empty branch counted %d", n) + } + if c, _ := s.Topic("a"); c.Branch != "new" { + t.Fatalf("branch = %q", c.Branch) + } + + if n, err := s.ReleaseTopicsForPR("acme/widget", 5, TopicStateMerged); err != nil || n != 1 { + t.Fatalf("ReleaseTopicsForPR = %d, %v", n, err) + } + if n, _ := s.ReleaseTopicsForPR("acme/widget", 0, TopicStateMerged); n != 0 { + t.Fatalf("pr 0 released %d", n) + } + open := s.OpenTopics() + if len(open) != 1 || open[0].Key != "b" { + t.Fatalf("open = %+v", open) + } + closed := 0 + for _, b := range s.List(ListFilter{}) { + if b.Meta(MetaTopicState) == TopicStateMerged && b.Status == StatusClosed { + closed++ + } + } + if closed != 1 { + t.Fatalf("merged beads = %d", closed) + } +} + +func TestSameTopicRepoAndProjection(t *testing.T) { + if !SameTopicRepo("Acme/Widget", "acme/widget") || SameTopicRepo("a/widget", "b/widget") || + !SameTopicRepo("widget", "a/widget") || SameTopicRepo("", "widget") { + t.Fatal("SameTopicRepo mismatch") + } + b := &Bead{ID: "x", ExternalRef: TopicRefPrefix + "k", Metadata: map[string]interface{}{MetaTopicPR: float64(9)}} + if c := topicFromBead(b); c.PR != 9 || c.State != TopicStateOpen || c.Key != "k" { + t.Fatalf("projection = %+v", c) + } + if isOpenTopicBead(&Bead{ExternalRef: "https://x"}) || isOpenTopicBead(nil) { + t.Fatal("non-topic bead counted as a topic") + } +} diff --git a/src/pkg/scheduler/kick_layout.go b/src/pkg/scheduler/kick_layout.go index 13757c3a6e..5ea2371802 100644 --- a/src/pkg/scheduler/kick_layout.go +++ b/src/pkg/scheduler/kick_layout.go @@ -32,6 +32,7 @@ import ( // 12. red-PR fix-before-new dynamic (ci-failing.json) // 13. review-thread fix-before-new dynamic (review-threads.json) // 14. PR follow-up handoff dynamic (pr-followup/) +// 14a. topic claims dynamic (bd topic claims, #18493) // 15. guide flow line dynamic (guide only) // 16. in-flight note dynamic (session claims) // 16a. maintainer notes dynamic (dashboard notes on listed items) @@ -115,6 +116,7 @@ func (s *Scheduler) assembleKick(a kickAssembly, message string) string { message = s.addReviewThreadFixFirst(a.agent, message) message = s.addPRFollowUpHandoff(a.agent, message) message = s.addRemoteItemHandoff(a.agent, message) + message = s.addTopicClaims(a.agent, message) message = s.addGuideFlow(a.agent, a.actionable, message) message = s.addInflightNote(message, a.issues) message = s.addMaintainerNotes(message, a.issues) diff --git a/src/pkg/scheduler/policy_overlays.go b/src/pkg/scheduler/policy_overlays.go index d27ebf3066..e813f93a81 100644 --- a/src/pkg/scheduler/policy_overlays.go +++ b/src/pkg/scheduler/policy_overlays.go @@ -206,7 +206,7 @@ func (s *Scheduler) redPRFixSection(agentName string) string { if err != nil { data = nil } - return formatRedPRFixDataGuarded(data, base, github.CIFailureSignals().ForAgent(base), s.busyBranchChecker(base)) + return formatRedPRFixDataWithTopics(data, base, github.CIFailureSignals().ForAgent(base), s.busyBranchChecker(base), s.topicClaimsFor(agentName)) } // CIFailureKickMessage is the targeted kick a webhook CI-failure signal @@ -292,6 +292,13 @@ func formatRedPRFixDataWithSignals(data []byte, agent string, signals []github.C // reports busy is not one of the agent's push targets; it is listed below the // gate as "suggest, do not push" and does not hold back new work. func formatRedPRFixDataGuarded(data []byte, agent string, signals []github.CIFailureSignal, busy busyBranchCheck) string { + return formatRedPRFixDataWithTopics(data, agent, signals, busy, nil) +} + +// formatRedPRFixDataWithTopics is formatRedPRFixDataGuarded with each listed +// PR tagged by the topic its owner claimed for it, if any +// (hivecommons/hive#18493). +func formatRedPRFixDataWithTopics(data []byte, agent string, signals []github.CIFailureSignal, busy busyBranchCheck, topics []TopicClaim) string { type ciFailingRow struct { Number int `json:"number"` Repo string `json:"repo"` @@ -463,7 +470,7 @@ func formatRedPRFixDataGuarded(data []byte, agent string, signals []github.CIFai b.WriteString(fmt.Sprintf(" … and %d more (full list: %s)\n", len(mine)-i, ciFailingPath)) break } - b.WriteString(fmt.Sprintf(" #%d %s — %s\n", pr.Number, pr.Repo, pr.Title)) + b.WriteString(fmt.Sprintf(" #%d %s%s — %s\n", pr.Number, pr.Repo, topicTag(topics, pr.Repo, pr.Number), pr.Title)) if pr.Adopted { b.WriteString(fmt.Sprintf(" ADOPTED contributor PR (stage 074, head repo %s): the author is offline; `gh pr checkout` then push to the PR's own branch — maintainer_can_modify grants access.\n", pr.HeadRepo)) b.WriteString(adoptedPRStatusRule) @@ -706,6 +713,7 @@ func (s *Scheduler) formatHeldPRClaimsWithPolicy(actionable *github.ActionableRe repoOrder := make([]string, 0, 8) byRepo := make(map[string][]github.HoldItem) heldPRs := make(map[string]github.PullRequest, len(actionable.PRs.Held)) + topics := s.allTopicClaims() for _, pr := range actionable.PRs.Held { heldPRs[fmt.Sprintf("%s#%d", pr.Repo, pr.Number)] = pr } @@ -736,7 +744,7 @@ func (s *Scheduler) formatHeldPRClaimsWithPolicy(actionable *github.ActionableRe if reviewState != "" { reviewState = " — " + reviewState } - b.WriteString(fmt.Sprintf(" %s#%d %s%s\n", item.Repo, item.Number, title, reviewState)) + b.WriteString(fmt.Sprintf(" %s#%d%s %s%s\n", item.Repo, item.Number, topicTag(topics, item.Repo, item.Number), title, reviewState)) shown++ } if omitted := len(items) - limit; omitted > 0 { diff --git a/src/pkg/scheduler/scheduler.go b/src/pkg/scheduler/scheduler.go index 8fe924b725..e0f652e1a9 100644 --- a/src/pkg/scheduler/scheduler.go +++ b/src/pkg/scheduler/scheduler.go @@ -49,6 +49,7 @@ type Scheduler struct { inflight InflightLookup prLease PRLeaseLookup maintainerNotes MaintainerNotesLookup + topicClaims TopicClaimLookup runAdmitter RunAdmitter triageCommenter TriageCommenter clarity clarityGateState diff --git a/src/pkg/scheduler/templates.go b/src/pkg/scheduler/templates.go index ea1b6efd78..0d5b3cd21d 100644 --- a/src/pkg/scheduler/templates.go +++ b/src/pkg/scheduler/templates.go @@ -401,6 +401,7 @@ func (s *Scheduler) substituteTemplateWithVars(template string, actionable *gith "GH_AUTH": lit(s.ghAuthInstructions()), "WORK_TRACKER": lit(s.workTrackerSection()), "IN_FLIGHT": lit(inflightNote(heldInflight)), + "TOPIC_CLAIMS": lit(topicClaimsSection(s.topicClaimsFor(agentName))), "PROJECT_ORG": lit(s.cfg.Project.Org), "PROJECT_NAME": lit(s.cfg.Project.Name), "PROJECT_PRIMARY_REPO": lit(fullPrimaryRepo), diff --git a/src/pkg/scheduler/topic_claims.go b/src/pkg/scheduler/topic_claims.go new file mode 100644 index 0000000000..d40c110103 --- /dev/null +++ b/src/pkg/scheduler/topic_claims.go @@ -0,0 +1,132 @@ +package scheduler + +import ( + "fmt" + "strings" +) + +// Topic claims in the kick (hivecommons/hive#18493). +// +// A long-lived agent records "topic key -> one PR" with `bd topic claim` +// (pkg/beads/topic.go). The kick shows the agent its open claims so it finds +// its PR by number on every later kick, even after a branch rename, and the +// FIX-BEFORE-NEW and held-PR blocks name the topic next to the PR. + +// TopicClaim is one open topic claim, as the kick needs it. Agent is the bead +// store (lane) that holds it. +type TopicClaim struct { + Agent string + Key string + Repo string + PR int + Branch string +} + +// TopicClaimLookup returns every open topic claim across the hive's agents. +type TopicClaimLookup func() []TopicClaim + +// SetTopicClaimLookup installs (or with nil, removes) the topic-claim lookup. +func (s *Scheduler) SetTopicClaimLookup(fn TopicClaimLookup) { + s.mu.Lock() + defer s.mu.Unlock() + s.topicClaims = fn +} + +// allTopicClaims returns the installed lookup's claims, or nil. +func (s *Scheduler) allTopicClaims() []TopicClaim { + s.mu.RLock() + fn := s.topicClaims + s.mu.RUnlock() + if fn == nil { + return nil + } + return fn() +} + +// topicClaimsFor returns the open claims held by agentName's lane. +func (s *Scheduler) topicClaimsFor(agentName string) []TopicClaim { + base := s.cfg.BaseAgentName(agentName) + var out []TopicClaim + for _, c := range s.allTopicClaims() { + if c.Agent == base || c.Agent == agentName { + out = append(out, c) + } + } + return out +} + +// topicKeyFor returns the topic key held through repo#number, or "". +func topicKeyFor(claims []TopicClaim, repo string, number int) string { + for _, c := range claims { + if c.PR == number && sameRepoSpelling(c.Repo, repo) { + return c.Key + } + } + return "" +} + +// topicTag is the " [topic: key]" suffix a PR row carries, or "". +func topicTag(claims []TopicClaim, repo string, number int) string { + if key := topicKeyFor(claims, repo, number); key != "" { + return " [topic: " + key + "]" + } + return "" +} + +// sameRepoSpelling matches "owner/name" whole when both sides carry an owner, +// otherwise by name only (kick surfaces carry either spelling). +func sameRepoSpelling(a, b string) bool { + a, b = strings.ToLower(strings.TrimSpace(a)), strings.ToLower(strings.TrimSpace(b)) + if a == "" || b == "" { + return false + } + if strings.Contains(a, "/") && strings.Contains(b, "/") { + return a == b + } + return a[strings.LastIndex(a, "/")+1:] == b[strings.LastIndex(b, "/")+1:] +} + +// topicClaimsHeader opens the kick block; the seam skips a kick that already +// carries it (the template placed ${TOPIC_CLAIMS}). +const topicClaimsHeader = "## 📌 Topic claims (one PR per topic)" + +// topicClaimsUsage is how an agent claims, reads and releases a topic. +const topicClaimsUsage = "Claim a new topic right after opening its PR: `bd topic claim --repo --pr --branch `.\n" + + "Read one back with `bd topic get `; give one up with `bd topic release `. A second claim on an\n" + + "open topic for a different PR is refused. Hive releases a claim when its PR merges or closes.\n" + +// topicClaimsSection renders the ${TOPIC_CLAIMS} block. It always carries the +// usage lines, so a template that places the variable teaches the command +// even before the agent holds a claim. +func topicClaimsSection(claims []TopicClaim) string { + var b strings.Builder + b.WriteString(topicClaimsHeader + "\n\n") + if len(claims) == 0 { + b.WriteString("You hold no topic claims.\n") + } else { + b.WriteString("You own these topics. Find each PR by NUMBER, never by branch name, and keep working\n") + b.WriteString("on that PR (`gh pr checkout --repo `). Do NOT open a second PR for a claimed topic:\n") + for _, c := range claims { + line := fmt.Sprintf(" %s → %s#%d", c.Key, c.Repo, c.PR) + if c.Branch != "" { + line += " (branch " + c.Branch + ")" + } + b.WriteString(line + "\n") + } + } + b.WriteString(topicClaimsUsage) + return b.String() +} + +// addTopicClaims appends the agent's topic claims to a resolved kick when it +// holds any and the template did not place ${TOPIC_CLAIMS} itself. +func (s *Scheduler) addTopicClaims(agentName, message string) string { + if message == "" || strings.Contains(message, topicClaimsHeader) { + return message + } + claims := s.topicClaimsFor(agentName) + if len(claims) == 0 { + return message + } + return appendKickSection(message, topicClaimsSection(claims)) +} diff --git a/src/pkg/scheduler/topic_claims_test.go b/src/pkg/scheduler/topic_claims_test.go new file mode 100644 index 0000000000..d691a49f8f --- /dev/null +++ b/src/pkg/scheduler/topic_claims_test.go @@ -0,0 +1,135 @@ +package scheduler + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" +) + +func topicLookup(claims ...TopicClaim) TopicClaimLookup { + return func() []TopicClaim { return claims } +} + +func TestHeldPRBlockAndKickShowTopicClaims(t *testing.T) { + s := heldPRCoordinationScheduler(t, 3, "ISSUES_AND_PRS") + s.SetTopicClaimLookup(topicLookup( + TopicClaim{Agent: "quality", Key: "deps-bump", Repo: "acme/widget", PR: 26, Branch: "deps/renamed"}, + TopicClaim{Agent: "scanner", Key: "release", Repo: "acme/widget", PR: 40}, + )) + actionable := &github.ActionableResult{ + Hold: github.HoldResult{Total: 1, PRs: 1, Items: []github.HoldItem{ + {Repo: "acme/widget", Number: 26, Type: "pr", Title: "Bump deps"}, + }}, + } + msg := s.BuildAgentMessage("quality", nil, actionable) + for _, want := range []string{ + "acme/widget#26 [topic: deps-bump] Bump deps", + topicClaimsHeader, + "deps-bump → acme/widget#26 (branch deps/renamed)", + "bd topic claim ", + } { + if !strings.Contains(msg, want) { + t.Errorf("kick missing %q:\n%s", want, msg) + } + } + if strings.Contains(msg, "release → acme/widget#40") { + t.Errorf("another lane's topic claim leaked into the kick:\n%s", msg) + } + + s.SetTopicClaimLookup(nil) + msg = s.BuildAgentMessage("quality", nil, actionable) + if strings.Contains(msg, topicClaimsHeader) || strings.Contains(msg, "[topic:") { + t.Errorf("kick carries topic claims with no lookup installed:\n%s", msg) + } +} + +func TestTopicClaimsTemplateVariable(t *testing.T) { + redirectPolicySeams(t) + dir := t.TempDir() + agentsDir := filepath.Join(dir, "examples", "kubestellar", "agents") + if err := os.MkdirAll(agentsDir, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(agentsDir, "deps.md"), []byte("DEPS BODY\n${TOPIC_CLAIMS}\nEND BODY"), 0o644); err != nil { + t.Fatal(err) + } + cfg := &config.Config{ + Project: config.ProjectConfig{Org: "acme", Name: "Acme", PrimaryRepo: "widget", Repos: []string{"acme/widget"}}, + AgentRuntimeConfig: config.AgentRuntimeConfig{Agents: map[string]config.AgentConfig{ + "deps": {Role: "deps", Mode: "ISSUES_AND_PRS", KickTemplate: "deps.md"}, + }}, + Policies: config.PoliciesConfig{LocalDir: dir}, + } + s := New(cfg, testLogger()) + + msg := s.BuildAgentMessage("deps", nil, &github.ActionableResult{}) + if !strings.Contains(msg, "You hold no topic claims.") || !strings.Contains(msg, "bd topic claim") { + t.Fatalf("${TOPIC_CLAIMS} did not render the empty block:\n%s", msg) + } + + s.SetTopicClaimLookup(topicLookup(TopicClaim{Agent: "deps", Key: "deps-bump", Repo: "acme/widget", PR: 7})) + msg = s.BuildAgentMessage("deps", nil, &github.ActionableResult{}) + if got := strings.Count(msg, topicClaimsHeader); got != 1 { + t.Fatalf("topic block rendered %d times, want 1 (the seam must not repeat a placed variable):\n%s", got, msg) + } + if !strings.Contains(msg, "deps-bump → acme/widget#7\n") { + t.Fatalf("claim missing from ${TOPIC_CLAIMS}:\n%s", msg) + } + if strings.Index(msg, topicClaimsHeader) > strings.Index(msg, "END BODY") { + t.Fatalf("block not placed where the template put it:\n%s", msg) + } +} + +func TestRedPRFixBlockTagsTopic(t *testing.T) { + data := []byte(`{"ci_failing":[{"number":5,"repo":"acme/widget","title":"Bump deps","agent":"scanner","failing_checks":["build"]}, +{"number":6,"repo":"acme/widget","title":"Other","agent":"scanner","failing_checks":["build"]}]}`) + out := formatRedPRFixDataWithTopics(data, "scanner", nil, nil, []TopicClaim{{Agent: "scanner", Key: "deps-bump", Repo: "widget", PR: 5}}) + if !strings.Contains(out, "#5 acme/widget [topic: deps-bump] — Bump deps") { + t.Fatalf("FIX-BEFORE-NEW row not tagged with its topic:\n%s", out) + } + if !strings.Contains(out, "#6 acme/widget — Other") { + t.Fatalf("unclaimed row changed:\n%s", out) + } + if plain := formatRedPRFixDataWithSignals(data, "scanner", nil); strings.Contains(plain, "[topic:") { + t.Fatalf("untagged renderer carries a topic:\n%s", plain) + } +} + +func TestTopicClaimHelpers(t *testing.T) { + cases := []struct { + a, b string + want bool + }{ + {"acme/widget", "ACME/Widget", true}, + {"acme/widget", "other/widget", false}, + {"widget", "acme/widget", true}, + {"widget", "gadget", false}, + {"", "widget", false}, + } + for _, tc := range cases { + if got := sameRepoSpelling(tc.a, tc.b); got != tc.want { + t.Errorf("sameRepoSpelling(%q, %q) = %v, want %v", tc.a, tc.b, got, tc.want) + } + } + claims := []TopicClaim{{Key: "k", Repo: "acme/widget", PR: 3}} + if got := topicTag(claims, "acme/widget", 3); got != " [topic: k]" { + t.Errorf("topicTag = %q", got) + } + if got := topicTag(claims, "acme/widget", 4); got != "" { + t.Errorf("topicTag on unclaimed PR = %q", got) + } + + s := &Scheduler{} + if got := s.addTopicClaims("deps", ""); got != "" { + t.Errorf("empty message grew: %q", got) + } + msg := "BODY\n" + topicClaimsHeader + "\n" + s.SetTopicClaimLookup(topicLookup(TopicClaim{Agent: "deps", Key: "k", Repo: "acme/widget", PR: 3})) + if got := s.addTopicClaims("deps", msg); got != msg { + t.Errorf("seam repeated a placed block: %q", got) + } +}