diff --git a/changelog.d/added-18884-customers-mention-search.md b/changelog.d/added-18884-customers-mention-search.md new file mode 100644 index 0000000000..9147ea121b --- /dev/null +++ b/changelog.d/added-18884-customers-mention-search.md @@ -0,0 +1 @@ +- Customers: when an owner accepts a suggested GitHub login, the hive can now make one budgeted GitHub search for mentions and comments so the new profile starts with history (off by default; `customers.mention_search.enabled`, at most two requests per accept and a per-hour budget, shed when the API budget is low, never run by the discovery sweep, ids and counts only in the log) (#18884). diff --git a/src/cmd/hive/customers_mention.go b/src/cmd/hive/customers_mention.go new file mode 100644 index 0000000000..79c958a1cc --- /dev/null +++ b/src/cmd/hive/customers_mention.go @@ -0,0 +1,118 @@ +package main + +import ( + "context" + "errors" + "log/slog" + "time" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/customers" + "github.com/hivecommons/hive/pkg/github" +) + +// Customers step E (hivecommons/hive#18884): the budgeted GitHub mention +// search that runs when a person accepts a suggested GitHub login. It is +// reached only from customersDashboard.Accept and AcceptInto. The discovery +// sweep (customers_sweep.go) is never handed this, nor a GitHub client. + +// customersMentionTimeout bounds one accept's background search, including +// any wait for a pacing slot. +const customersMentionTimeout = 45 * time.Second + +// customersMentionSearcher adapts the shared GitHub client to +// customers.MentionSearcher. The client is read at call time so a credential +// rebuild is followed. +type customersMentionSearcher struct { + client func() *github.Client +} + +func (s customersMentionSearcher) SearchMentions(ctx context.Context, kind, login string, repos []string, limit int) ([]customers.MentionHit, error) { + c := s.client() + if c == nil { + return nil, github.ErrNoGitHubClient + } + ghKind := github.MentionSearchKindMentions + if kind == customers.MentionKindCommenter { + ghKind = github.MentionSearchKindCommenter + } + hits, err := c.SearchMentions(ctx, ghKind, login, repos, limit) + if err != nil { + if errors.Is(err, github.ErrMentionSearchRateLimited) { + return nil, customers.ErrMentionQuotaLow + } + return nil, err + } + out := make([]customers.MentionHit, 0, len(hits)) + for _, h := range hits { + out = append(out, customers.MentionHit{Repo: h.Repo, Number: h.Number, IsPR: h.IsPR, At: h.UpdatedAt}) + } + return out, nil +} + +// newCustomersMentionSearch builds the accept-time search over the people +// store's index. cfg and client are read on every call. +func newCustomersMentionSearch(svc *customers.Service, cfg func() *config.Config, client func() *github.Client) *customers.MentionSearch { + m := customers.NewMentionSearch(customersMentionSearcher{client: client}, svc.Index()) + m.Enabled = func() bool { return cfg().CustomersMentionSearchEnabled() } + m.HourlyLimit = func() int { + if c := cfg(); c != nil { + return c.Customers.MentionSearch.RequestsPerHour() + } + return config.DefaultCustomersMentionSearchMaxPerHour + } + m.Repos = func() []string { + if c := cfg(); c != nil { + return append([]string(nil), c.Project.Repos...) + } + return nil + } + m.QuotaLow = func() string { return client().OptionalSearchStandDown() } + return m +} + +// suggestedIdentity returns the identity of a suggestion before an accept +// consumes it. +func (c *customersDashboard) suggestedIdentity(suggestionID string) (customers.Identity, bool) { + for _, sg := range c.svc.Store().Suggestions() { + if sg.ID == suggestionID { + return customers.Identity{Kind: sg.Kind, Value: sg.Value}, true + } + } + return customers.Identity{}, false +} + +// searchOnAccept runs the budgeted search for the identity just accepted. It +// never delays or fails the accept: it runs in the background and logs the +// person id and counts only (never the login, a query or a token). +func (c *customersDashboard) searchOnAccept(person string, ident customers.Identity, found bool) { + if c.mentions == nil || !found || person == "" { + return + } + run := func() { + ctx, cancel := context.WithTimeout(context.Background(), customersMentionTimeout) + defer cancel() + res := c.mentions.Run(ctx, person, ident) + if c.logger == nil || res.Skipped == customers.SkipDisabled { + return + } + c.logger.Info("[customers] accept-time github search", slog.String("person", res.Person), + slog.Int("requests", res.Requests), slog.Int("found", res.Found), slog.Int("edges", res.Edges), + slog.Bool("truncated", res.Truncated), slog.String("skipped", res.Skipped)) + } + if c.spawn != nil { + c.spawn(run) + return + } + go run() +} + +// customersMentionConfig is the config the accept-time search reads on every +// call: the immutable snapshot the governor publishes after each reload, +// falling back to the boot config before the first one. +func (b *boot) customersMentionConfig() *config.Config { + if cfg := b.sweepConfig.Load(); cfg != nil { + return cfg + } + return b.cfg +} diff --git a/src/cmd/hive/customers_mention_test.go b/src/cmd/hive/customers_mention_test.go new file mode 100644 index 0000000000..e904c3c54a --- /dev/null +++ b/src/cmd/hive/customers_mention_test.go @@ -0,0 +1,202 @@ +package main + +import ( + "bytes" + "context" + "log/slog" + "os" + "strings" + "sync" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/customers" + "github.com/hivecommons/hive/pkg/dashboard" +) + +type countingMentionSearcher struct { + mu sync.Mutex + calls int + login string +} + +func (c *countingMentionSearcher) SearchMentions(_ context.Context, kind, login string, _ []string, _ int) ([]customers.MentionHit, error) { + c.mu.Lock() + defer c.mu.Unlock() + c.calls++ + c.login = login + if kind == customers.MentionKindCommenter { + return nil, nil + } + return []customers.MentionHit{{Repo: "acme/widgets", Number: 5, IsPR: true, At: time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)}}, nil +} + +func (c *countingMentionSearcher) count() int { + c.mu.Lock() + defer c.mu.Unlock() + return c.calls +} + +// wireMentionTest returns an adapter whose accept-time search is on, runs +// inline, and logs into buf. +func wireMentionTest(t *testing.T, enabled bool) (*customersDashboard, *countingMentionSearcher, *bytes.Buffer) { + t.Helper() + c := wireTestCustomers(t) + fake := &countingMentionSearcher{} + m := customers.NewMentionSearch(fake, c.svc.Index()) + m.Enabled = func() bool { return enabled } + m.HourlyLimit = func() int { return 10 } + m.Repos = func() []string { return []string{"acme/widgets"} } + c.mentions = m + c.spawn = func(f func()) { f() } + var buf bytes.Buffer + c.logger = slog.New(slog.NewTextHandler(&buf, nil)) + return c, fake, &buf +} + +// suggest makes the sweep see a login and an address nobody owns, which +// leaves one suggestion for each, and returns their ids. +func suggest(t *testing.T, c *customersDashboard) (loginID, emailID string) { + t.Helper() + at := time.Date(2026, 11, 2, 10, 0, 0, 0, time.UTC) + _, err := c.svc.Sweep(customers.SweepInput{Sightings: []customers.Sighting{ + {Source: customersSourcePoll, Observation: customers.Observation{Kind: customers.KindGitHub, Value: "zed", Predicate: customers.PredReported, Artefact: "gh:issue:acme/widgets#7", At: at}}, + {Source: customersSourceMail, Observation: customers.Observation{Kind: customers.KindEmail, Value: "yara@example.org", Predicate: customers.PredSent, Artefact: "inbox:mail:1", At: at}}, + }}) + if err != nil { + t.Fatal(err) + } + for _, sg := range c.svc.Store().Suggestions() { + switch sg.Kind { + case customers.KindGitHub: + loginID = sg.ID + case customers.KindEmail: + emailID = sg.ID + } + } + if loginID == "" || emailID == "" { + t.Fatalf("suggestions = %+v", c.svc.Store().Suggestions()) + } + return loginID, emailID +} + +// The search is reached from the accept path only: a sweep that sees a new +// login, with the search wired and on, makes no call. +func TestCustomersMentionSearchNeverRunsInTheSweep(t *testing.T) { + c, fake, _ := wireMentionTest(t, true) + suggest(t, c) + if _, err := c.svc.Sweep(customers.SweepInput{}); err != nil { + t.Fatal(err) + } + if n := fake.count(); n != 0 { + t.Fatalf("the sweep made %d GitHub searches", n) + } + // And the sweep's source cannot reach it: it is handed no client and + // names neither the search nor its adapter. + src, err := os.ReadFile("customers_sweep.go") + if err != nil { + t.Fatal(err) + } + for _, banned := range []string{"MentionSearch", "SearchMentions", "mentions"} { + if strings.Contains(string(src), "."+banned) || strings.Contains(string(src), banned+"(") { + t.Errorf("customers_sweep.go references %q; the search belongs on the accept path only", banned) + } + } + if !strings.Contains(string(src), "never handed a GitHub client") { + t.Error("the sweep's no-network comment is gone") + } +} + +func TestCustomersMentionSearchRunsOnAccept(t *testing.T) { + c, fake, buf := wireMentionTest(t, true) + loginID, _ := suggest(t, c) + owner := dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true} + res, err := c.Accept(owner, loginID) + if err != nil { + t.Fatal(err) + } + if fake.count() != customers.MentionSearchMaxRequests { + t.Fatalf("accept made %d searches, want %d", fake.count(), customers.MentionSearchMaxRequests) + } + edges, _, err := c.svc.Index().ByPerson(res.ID, customers.PredMentionedIn, "", 10) + if err != nil || len(edges) == 0 { + t.Fatalf("edges = %+v, %v", edges, err) + } + var found bool + for _, e := range edges { + if e.Artefact == "gh:pr:acme/widgets#5" && e.Source == customers.MentionSearchSource { + found = true + } + } + if !found { + t.Fatalf("the search result did not land as an edge: %+v", edges) + } + // Ids and counts only in the log. + out := buf.String() + if !strings.Contains(out, "requests=2") || !strings.Contains(out, "person="+res.ID) { + t.Fatalf("log line missing ids and counts: %q", out) + } + for _, bad := range []string{"zed", "acme", "widgets", "mentions:", "token"} { + if strings.Contains(out, bad) { + t.Errorf("log line leaks %q: %q", bad, out) + } + } +} + +func TestCustomersMentionSearchAcceptIntoAlsoSearches(t *testing.T) { + c, fake, _ := wireMentionTest(t, true) + loginID, _ := suggest(t, c) + owner := dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true} + if _, err := c.AcceptInto(owner, loginID, "me"); err != nil { + t.Fatal(err) + } + if fake.count() != customers.MentionSearchMaxRequests || fake.login != "zed" { + t.Fatalf("calls = %d, login %q", fake.count(), fake.login) + } +} + +func TestCustomersMentionSearchSkippedWhenOffOrNotALogin(t *testing.T) { + owner := dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true} + c, fake, _ := wireMentionTest(t, false) + loginID, _ := suggest(t, c) + if _, err := c.Accept(owner, loginID); err != nil || fake.count() != 0 { + t.Fatalf("off: err %v, calls %d", err, fake.count()) + } + c, fake, _ = wireMentionTest(t, true) + _, emailID := suggest(t, c) + if _, err := c.Accept(owner, emailID); err != nil || fake.count() != 0 { + t.Fatalf("an email suggestion must never be searched: err %v, calls %d", err, fake.count()) + } +} + +// A refused accept (read-only viewer, unknown suggestion) searches nothing. +func TestCustomersMentionSearchNotRunOnRefusedAccept(t *testing.T) { + c, fake, _ := wireMentionTest(t, true) + loginID, _ := suggest(t, c) + if _, err := c.Accept(dashboard.CustomersViewer{User: "reed"}, loginID); err == nil { + t.Fatal("a read-only accept must be refused") + } + if _, err := c.Accept(dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true}, "s_missing"); err == nil { + t.Fatal("an unknown suggestion must be refused") + } + if fake.count() != 0 { + t.Fatalf("%d searches after refused accepts", fake.count()) + } +} + +// The accept does not wait for GitHub: by default the search is a goroutine. +func TestCustomersMentionSearchDefaultsToBackground(t *testing.T) { + c, fake, _ := wireMentionTest(t, true) + c.spawn = nil + loginID, _ := suggest(t, c) + if _, err := c.Accept(dashboard.CustomersViewer{User: "olivia", Full: true, Owner: true}, loginID); err != nil { + t.Fatal(err) + } + deadline := time.Now().Add(5 * time.Second) + for fake.count() < customers.MentionSearchMaxRequests && time.Now().Before(deadline) { + time.Sleep(10 * time.Millisecond) + } + if fake.count() != customers.MentionSearchMaxRequests { + t.Fatalf("background search made %d calls", fake.count()) + } +} diff --git a/src/cmd/hive/customerswire.go b/src/cmd/hive/customerswire.go index 09e2488680..2cb3272658 100644 --- a/src/cmd/hive/customerswire.go +++ b/src/cmd/hive/customerswire.go @@ -31,6 +31,12 @@ type customersDashboard struct { svc *customers.Service // graph is the read-only GraphQL engine; nil if it failed to start. graph *gql.Engine + // mentions is the accept-time GitHub search (step E, #18884); nil when + // it is not wired. Only Accept and AcceptInto reach it. + mentions *customers.MentionSearch + logger *slog.Logger + // spawn runs the search; nil means a goroutine. Tests run it inline. + spawn func(func()) } // wireCustomers opens the people store and the edge index when @@ -76,7 +82,7 @@ func wireCustomersAt(dataDir, graphDir string, resolvers customers.Resolvers, lo logger.Error("[customers] graph endpoint unavailable", "error", err) } } - return &customersDashboard{svc: svc, graph: graph}, stop + return &customersDashboard{svc: svc, graph: graph, logger: logger}, stop } // customersError maps a store error onto the dashboard's sentinels, which @@ -148,7 +154,12 @@ func (c *customersDashboard) Forget(v dashboard.CustomersViewer, id string) (int } func (c *customersDashboard) Accept(v dashboard.CustomersViewer, suggestionID string) (dashboard.CustomerResult, error) { - return customerResult(c.svc.Accept(customersViewer(v), suggestionID)) + ident, found := c.suggestedIdentity(suggestionID) + res, err := customerResult(c.svc.Accept(customersViewer(v), suggestionID)) + if err == nil { + c.searchOnAccept(res.ID, ident, found) + } + return res, err } func (c *customersDashboard) Dismiss(v dashboard.CustomersViewer, suggestionID string) error { @@ -212,7 +223,12 @@ func installCustomersAgentContext(c *customersDashboard, setKickLookup func(sche } func (c *customersDashboard) AcceptInto(v dashboard.CustomersViewer, suggestionID, into string) (dashboard.CustomerResult, error) { - return customerResult(c.svc.AcceptInto(customersViewer(v), suggestionID, into)) + ident, found := c.suggestedIdentity(suggestionID) + res, err := customerResult(c.svc.AcceptInto(customersViewer(v), suggestionID, into)) + if err == nil { + c.searchOnAccept(res.ID, ident, found) + } + return res, err } func (c *customersDashboard) Merge(v dashboard.CustomersViewer, id, from string) (dashboard.CustomerResult, error) { diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 06ff7bcc08..e0391c386c 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -3633,6 +3633,9 @@ func (b *boot) bootDashboardAPIWith(deps bootDashboardAPIDeps) { if svc, stop := wireCustomers(b.cfg, b.customersResolvers(), b.logger); svc != nil { b.cleanup.push(stop) b.customers = svc + // Step E (#18884): the budgeted GitHub search on accept. Off unless + // customers.mention_search.enabled; never reached by the sweep. + svc.mentions = newCustomersMentionSearch(svc.svc, b.customersMentionConfig, b.currentGitHubClient) b.dashSrv.SetCustomersService(svc) if b.sched != nil { installCustomersAgentContext(svc, b.sched.SetCustomerContextLookup) diff --git a/src/docs/api-reference/customers.md b/src/docs/api-reference/customers.md index 5b6bbc5539..c6c043625f 100644 --- a/src/docs/api-reference/customers.md +++ b/src/docs/api-reference/customers.md @@ -17,7 +17,7 @@ The rules are enforced twice: by the handlers and again by the store's service o | `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:176` | | `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:177` | | `DELETE` | `/api/customers/{id}` | Owner only | Forget: deletes the customer, their identities and every edge to them, and keeps one salted-hash tombstone per confirmed identity so discovery does not rebuild them. 200 `{forgotten, edges_removed}`. Audited as `customer_forget` | `pkg/dashboard/api_customers.go:178` | -| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. With the optional body `{into}` (an existing customer id, or `me`) it attaches the suggestion to that customer instead: the identity becomes one of theirs, pinned as a manual decision, no new person is created, the activity moves onto them on the next sweep, and `unmerge` undoes it with the id in the target's merge history. Audited as `customer_accept`, or `customer_attach` with the target's id and never a name | `pkg/dashboard/api_customers.go:179` | +| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. With the optional body `{into}` (an existing customer id, or `me`) it attaches the suggestion to that customer instead: the identity becomes one of theirs, pinned as a manual decision, no new person is created, the activity moves onto them on the next sweep, and `unmerge` undoes it with the id in the target's merge history. Audited as `customer_accept`, or `customer_attach` with the target's id and never a name. When `customers.mention_search.enabled` is on and the suggestion is a GitHub login, a budgeted background GitHub search adds `mentioned_in` and `commented_on` edges after the accept (see the design doc, step E) | `pkg/dashboard/api_customers.go:179` | | `POST` | `/api/customers/suggestions/{sid}/dismiss` | Full view | Delete a suggestion and tombstone its key, so it is not offered again. Audited as `customer_dismiss` | `pkg/dashboard/api_customers.go:180` | | `POST` | `/api/customers/hints/{hid}/answer` | Full view | Answer a "Same person?" question: `{same}`. `true` makes the suggested identity the customer's own and deletes the suggestion; `false` closes the question for good. A question between two customers is answered by merging them, so `true` on one is 400. Audited as `customer_hint_answer` | `pkg/dashboard/api_customers.go:181` | | `POST` | `/api/customers/{id}/merge` | Full view | Fold the customer `{from}` into this one: identities, tags, goals and activity move across and the merge is recorded. 409 for two dashboard users. Audited as `customer_merge` | `pkg/dashboard/api_customers.go:182` | diff --git a/src/docs/design/customers.md b/src/docs/design/customers.md index 0f800e29de..e98d6f1279 100644 --- a/src/docs/design/customers.md +++ b/src/docs/design/customers.md @@ -268,11 +268,13 @@ One optional sweep, `customers`. Steps: enumeration the hive already made. - **D, activity:** the audit log, operator actions, share history, meeting drafts, sessions, fact authors, and beads through their issue or PR. -- **E, budgeted GitHub search on accept:** mentions and comments for a newly - accepted person, about two calls per person, one person per tick, shed when - the API budget is low. +- **E, budgeted GitHub search on accept (opt-in, off by default):** mentions and + comments for a newly accepted GitHub login, at most two calls per accept and a + per-hour budget across accepts, shed when the API budget is low. Runs from the + accept handler, never from the sweep. -A normal sweep (A to D) makes zero GitHub calls, and a test holds that. +A normal sweep (A to D) makes zero GitHub calls, and a test holds that. Step E is +not part of the sweep. What the first sweep (steps A to C, `customers` in `src/cmd/hive/sweep_workers.go`, every ten minutes) reads: @@ -316,9 +318,40 @@ manual, by whom), answering no pins the pair so it is not asked again. A hint between two customers is answered by merging them, which is the merge and split UI of a later PR. -Step E, the budgeted GitHub search for mentions and comments on accept, is not -built. The GitHub client has no comment or mention search, so it needs a new -client method and a place in the API budget. It is left for its own PR. +Step E, the budgeted GitHub search on accept, is built and opt-in. +`customers.mention_search.enabled` defaults to **off** (env +`HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED`), because it asks GitHub about a person's +login and spends shared API quota, and the section otherwise adds no outbound +path. It also needs the Customers section on. When it is on and an owner or +read-write user accepts a suggested person (or attaches one to an existing +customer), the hive runs one search for that identity, so the new profile starts +with history beyond what the hive already holds: + +- **Accept only.** The call path is the accept handler, never the discovery + sweep, which is still handed no GitHub client. A test holds both. +- **GitHub logins only.** A suggested email address is never sent to GitHub. +- **Scoped to the hive's own repositories.** The query is `mentions:` and + then `commenter:`, each limited to the configured project repositories + (as many as fit GitHub's 256-character query limit). With no repositories there + is nothing to search and no call is made. +- **Hard per-accept budget.** At most two search requests, one page of 30 results + each, so at most 60 results kept per accept. +- **Per-hour budget across accepts.** `customers.mention_search.max_requests_per_hour` + (default 10, at most 60) bounds the requests all accepts spend together in a + rolling hour. A spent budget skips the search; the profile still gets created. +- **Shared quota.** The requests go through the shared GitHub transport, so they + count in the request accounting (caller `customers_mention_search`), carry the + low pacing class, and stand down when the API budget mode is not normal, when + the core or search remaining is low, or while the secondary-limit caution + window is engaged. +- **Edges, deduplicated.** Each hit becomes a `mentioned_in` or `commented_on` + edge on the issue or pull request (source `github_search`). An edge the index + already holds is left as it is, and a hit seen by both queries is written once + per predicate. +- **Privacy.** The edge is a reference, as for every other source: no title, body + or comment text is read into the store. The log line carries the person id and + counts only, never the login, a query or a token. It runs in the background, so + the accept does not wait for GitHub, and a failure never undoes the accept. Automatic tags come from role, association and history: `maintainer` from an owner or merger role or a GitHub author association of owner, member or diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index 73daa6033f..3d5d76e2fc 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -274,6 +274,7 @@ new value at the same time. | `HIVE_CUSTOMERS_ENABLED` | No | config `customers.enabled` (default on) | Turns the Customers section and its people store on or off; `false` opens no store, runs no sweep and hides the section, overriding config. Nothing the store holds leaves the hive. | | `HIVE_CUSTOMERS_INFERENCE_ENABLED` | No | config `customers.inference.enabled` (default off) | Turns goal and satisfaction suggestions on or off, overriding config. Needs Customers on. When on, a customer's own issues, pull requests and approved mail are sent to the meetings model; every suggestion waits for a person to confirm, edit or reject it. | | `HIVE_CUSTOMERS_AVATARS_ENABLED` | No | config `customers.avatars.enabled` (default on) | Turns GitHub pictures on the Customers list on or off, overriding config. On, the viewer's browser requests `https://github.com/.png` with no referrer for each person with a confirmed GitHub login; off, the list shows initials and makes no request to github.com. | +| `HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED` | No | config `customers.mention_search.enabled` (default off) | Turns the accept-time GitHub mention search on or off, overriding config. Needs Customers on. When on, accepting a suggested GitHub login makes at most two GitHub search requests for that login, counted against the shared API budget. | | `HIVE_SESSIONS_ENABLED` | No | config `dashboard.sessions.enabled` (default on) | Turns the dashboard Inception (spek) sessions feature (interactive CLI terminals, `/api/sessions`) on or off; `false` hides it, overriding config. Limits: `HIVE_SESSIONS_MAX`, `HIVE_SESSIONS_MAX_PER_USER`, `HIVE_SESSIONS_IDLE_TTL_HOURS`. Workspace: `HIVE_SESSIONS_WORKSPACE_REPO` (the `org/repo` sessions open in, default `project.org/primary_repo`), `HIVE_SESSIONS_WORKSPACE_DIR` (root of the one shared clone per repo, `//`, and of each session's own git worktree of it, `/.sessions///` on branch `hive-session/`; sessions share commits and branches but not uncommitted edits or `.spektacular/` state; default `/data/session-sandbox/workspace`), `HIVE_SESSIONS_GID` (the sessions-only group that shares the clone, default 20000). Inbox seeds: `HIVE_SESSIONS_SEED_MAX_BYTES` (cap on one item's enveloped text in `.hive/inbox/`, default 524288); see [Sessions API](api-reference/sessions.md). | | `HIVE_SESSIONS_AUTOSTART` | No | config `dashboard.sessions.autostart` (default on) | Turns the session startup auto-answer on or off, overriding config: when a session starts the hive answers the vendor CLI's startup screens (first-run notice, trust for the session's folder, onboarding) so its first request runs unattended. It never answers a permission prompt or a login screen. `HIVE_SESSIONS_AUTOSTART_WINDOW_SEC` (default `90`) bounds how long it answers for after a start. See [Startup auto-answer](api-reference/sessions.md#startup-auto-answer). | | `HIVE_TTYD_HISTORY_LIMIT` | No | `50000` | Defense-in-depth history-limit raise applied at browser attach time; only affects panes created after attach. | diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index 5c8e409265..355461908b 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -225,6 +225,7 @@ Top-level YAML keys accepted by `config.Config`: | `customers` | Customers: one profile per person built from what the hive already holds, kept in `/data/customers/people.json` (0600) with a rebuildable edge index in `/data/graph/customers.db`. Dashboard users and people added by hand are customers; anyone else is only a suggestion until accepted. Nothing it stores leaves the hive. Design: [customers](../design/customers.md). | Default ON (`enabled: true`); `enabled: false` (or `HIVE_CUSTOMERS_ENABLED=false`) opens no store, runs no sweep and hides the section. | | `customers.inference` | Goal and satisfaction suggestions (see `customers`): the hive reads a customer's own issues, pull requests and approved mail, asks the model configured for meetings for candidate goals and a satisfaction level with the evidence behind each, and files them as suggestions for a person to confirm, edit or reject. A confirmed or manual value is never overwritten. | Default OFF (`enabled: false`) because it sends that text to the model; `enabled: true` (or `HIVE_CUSTOMERS_INFERENCE_ENABLED=true`) turns it on. Needs `customers.enabled` and a meetings model (OpenAI-compatible or Anthropic); budget about 40,000 tokens a day. | | `customers.avatars` | GitHub pictures on the Customers list. The viewer's browser requests `https://github.com/.png` (no referrer) for each person with a confirmed GitHub login on screen; nobody known only by email is looked up anywhere, and the hive neither proxies nor stores pictures. See [customers](../design/customers.md). | Default ON (`enabled: true`); `enabled: false` (or `HIVE_CUSTOMERS_AVATARS_ENABLED=false`, or Settings, Features) shows initials and makes no request to github.com. | +| `customers.mention_search` | Step E of Customers: when an owner accepts a suggested GitHub login, the hive makes one budgeted GitHub search (issues and pull requests that mention the login, and ones the login commented on, in the hive's own repositories) so the new profile starts with history beyond what the hive already holds. The results become `mentioned_in` and `commented_on` edges. Never run by the discovery sweep, and never for an email address. | Default OFF (`enabled: false`) because it sends the login to GitHub and spends shared API quota; `enabled: true` (or `HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED=true`) turns it on. Needs `customers.enabled`. `max_requests_per_hour` (default 10, at most 60) bounds all accepts together; each accept spends at most 2 requests and keeps at most 60 results. It stands down while the API budget is below normal or the secondary-limit caution window is engaged. | | `governor.first_timer_welcome` | First-time contributor welcome: when a human whose GitHub `author_association` is `FIRST_TIME_CONTRIBUTOR`/`FIRST_TIMER` opens a PR, post one comment (per author per repo, marker ``) that thanks them and invites them to run their own hive — profile, leaderboard, trust-tier progression, offline review-fix/rebase handling. Bots, `author/clanker`/`author/hive` PRs, drafts and known relay contributors are skipped. | Default ON; `enabled: false` opts out; `template_path` overrides the text. Silent without a public dashboard URL. See [Welcoming first-time contributors](../good-first-issue.md#welcoming-first-time-contributors). | | `sla` | Delivery SLA targets (`sla.targets.start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`, hours; defaults 4 / 24 / 72) the dashboard's Throughput section colours its Delivery SLA spans against. | Metrics are derived from the lifecycle timeline; no extra GitHub calls. Also editable from **Settings → Thresholds**. See [Delivery SLA](sweeps-and-operations.md#delivery-sla). | | `sentinel` | Suspicious-activity alerts: flags open PRs (any author) that touch sensitive files or look like security overrides, privilege escalation, or codebase damage. | Default ON; observe-and-alert only. See [Suspicious-activity alerts](sweeps-and-operations.md#suspicious-activity-alerts-sentinel). | diff --git a/src/hive.yaml.example b/src/hive.yaml.example index 33d2522128..d5b6198e59 100644 --- a/src/hive.yaml.example +++ b/src/hive.yaml.example @@ -1371,3 +1371,6 @@ data: # enabled: false # true (or env HIVE_CUSTOMERS_INFERENCE_ENABLED=true) suggests goals and satisfaction with the meetings model; default off # avatars: # enabled: true # false (or env HIVE_CUSTOMERS_AVATARS_ENABLED=false) shows initials and makes no browser request to github.com for pictures; default on +# mention_search: +# enabled: false # true (or env HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED=true) runs one budgeted GitHub search for mentions and comments when an owner accepts a suggested GitHub login; default off +# max_requests_per_hour: 10 # search requests all accepts may spend together per hour (default 10, at most 60); each accept spends at most 2 diff --git a/src/pkg/config/customers.go b/src/pkg/config/customers.go index 62e8e4d694..0c3066388c 100644 --- a/src/pkg/config/customers.go +++ b/src/pkg/config/customers.go @@ -18,6 +18,10 @@ type CustomersConfig struct { // never signed up, to the model the meetings feature is configured to // use. Inference CustomersInferenceConfig `yaml:"inference,omitempty" json:"inference,omitempty"` + // MentionSearch gates the one budgeted GitHub search made when an owner + // accepts a suggested person (step E of the RFC). Default OFF: it asks + // GitHub about a person's login and spends the shared API budget. + MentionSearch CustomersMentionSearchConfig `yaml:"mention_search,omitempty" json:"mention_search,omitempty"` // Avatars gates GitHub profile pictures in the Customers list. Default // ON. It is the one part of the section that makes the viewer's browser // contact another site: github.com, for people already on screen. @@ -109,3 +113,65 @@ func (c *Config) CustomersAvatarsEnabled() bool { } return c.Customers.Avatars.IsEnabled() } + +// EnvCustomersMentionSearchEnabled overrides customers.mention_search.enabled +// when it holds a recognised boolean. +const EnvCustomersMentionSearchEnabled = "HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED" + +// DefaultCustomersMentionSearchMaxPerHour is how many GitHub search requests +// the accepts of all suggested people may spend together in one hour. Each +// accept spends at most two (customers.MentionSearchMaxRequests), so the +// default allows about five accepts an hour. +const DefaultCustomersMentionSearchMaxPerHour = 10 + +// MaxCustomersMentionSearchMaxPerHour caps what a config value may ask for, so +// a typo cannot hand the feature the whole search quota. +const MaxCustomersMentionSearchMaxPerHour = 60 + +// CustomersMentionSearchConfig (`customers.mention_search:`) controls the +// budgeted GitHub search for mentions and comments that runs when an owner +// accepts a suggested GitHub login, so the new profile starts with history +// beyond what the hive already holds. The discovery sweep never runs it. +type CustomersMentionSearchConfig struct { + // Enabled turns the search on. nil = false. + Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"` + // MaxRequestsPerHour bounds the search requests all accepts may make in + // one hour. 0 = DefaultCustomersMentionSearchMaxPerHour; values above + // MaxCustomersMentionSearchMaxPerHour are lowered to it. + MaxRequestsPerHour int `yaml:"max_requests_per_hour,omitempty" json:"max_requests_per_hour,omitempty"` +} + +// IsEnabled reports whether the search is on (default off). +func (c CustomersMentionSearchConfig) IsEnabled() bool { + return c.Enabled != nil && *c.Enabled +} + +// RequestsPerHour is the hourly request budget with the default and the cap +// applied. +func (c CustomersMentionSearchConfig) RequestsPerHour() int { + switch { + case c.MaxRequestsPerHour <= 0: + return DefaultCustomersMentionSearchMaxPerHour + case c.MaxRequestsPerHour > MaxCustomersMentionSearchMaxPerHour: + return MaxCustomersMentionSearchMaxPerHour + default: + return c.MaxRequestsPerHour + } +} + +// CustomersMentionSearchEnabled reports whether the accept-time search is on: +// the HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED env wins over +// customers.mention_search.enabled when it holds a recognised boolean. It +// also needs the Customers section to be on. +func (c *Config) CustomersMentionSearchEnabled() bool { + if !c.CustomersEnabled() { + return false + } + if v, ok := parseBoolEnv(EnvCustomersMentionSearchEnabled); ok { + return v + } + if c == nil { + return false + } + return c.Customers.MentionSearch.IsEnabled() +} diff --git a/src/pkg/config/customers_test.go b/src/pkg/config/customers_test.go index d655ef43fd..c548fb29f2 100644 --- a/src/pkg/config/customers_test.go +++ b/src/pkg/config/customers_test.go @@ -110,3 +110,60 @@ func TestCustomersAvatarsEnabled(t *testing.T) { t.Fatal("a nil config has avatars on") } } + +func TestCustomersMentionSearchDefaultsOffAndNeedsCustomers(t *testing.T) { + t.Setenv(EnvCustomersEnabled, "") + t.Setenv(EnvCustomersMentionSearchEnabled, "") + var cfg Config + if cfg.CustomersMentionSearchEnabled() { + t.Fatal("the accept-time search must default off") + } + on := true + cfg.Customers.MentionSearch.Enabled = &on + if !cfg.CustomersMentionSearchEnabled() { + t.Fatal("config true must turn it on") + } + t.Setenv(EnvCustomersEnabled, "false") + if cfg.CustomersMentionSearchEnabled() { + t.Fatal("it must be off whenever Customers is off") + } + t.Setenv(EnvCustomersEnabled, "") + t.Setenv(EnvCustomersMentionSearchEnabled, "false") + if cfg.CustomersMentionSearchEnabled() { + t.Fatal("env false must win over config true") + } + t.Setenv(EnvCustomersMentionSearchEnabled, "true") + if !(&Config{}).CustomersMentionSearchEnabled() { + t.Fatal("env true must win over the default") + } + var none *Config + t.Setenv(EnvCustomersMentionSearchEnabled, "") + if none.CustomersMentionSearchEnabled() { + t.Fatal("a nil config is the default, off") + } +} + +func TestCustomersMentionSearchRequestsPerHour(t *testing.T) { + cases := []struct { + name string + yaml string + want int + }{ + {"absent", "customers: {}\n", DefaultCustomersMentionSearchMaxPerHour}, + {"zero", "customers:\n mention_search:\n max_requests_per_hour: 0\n", DefaultCustomersMentionSearchMaxPerHour}, + {"negative", "customers:\n mention_search:\n max_requests_per_hour: -3\n", DefaultCustomersMentionSearchMaxPerHour}, + {"set", "customers:\n mention_search:\n max_requests_per_hour: 4\n", 4}, + {"capped", "customers:\n mention_search:\n max_requests_per_hour: 100000\n", MaxCustomersMentionSearchMaxPerHour}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + var cfg Config + if err := yaml.Unmarshal([]byte(tc.yaml), &cfg); err != nil { + t.Fatalf("parse: %v", err) + } + if got := cfg.Customers.MentionSearch.RequestsPerHour(); got != tc.want { + t.Fatalf("RequestsPerHour = %d, want %d", got, tc.want) + } + }) + } +} diff --git a/src/pkg/config/testdata/agent_runtime_golden.json b/src/pkg/config/testdata/agent_runtime_golden.json index 100b7b01a8..08e40195c1 100644 --- a/src/pkg/config/testdata/agent_runtime_golden.json +++ b/src/pkg/config/testdata/agent_runtime_golden.json @@ -784,7 +784,8 @@ }, "customers": { "inference": {}, - "avatars": {} + "avatars": {}, + "mention_search": {} }, "duplicate_sweep": {}, "good_first_issue": {}, diff --git a/src/pkg/customers/edges.go b/src/pkg/customers/edges.go index 850834e8c7..9935e82983 100644 --- a/src/pkg/customers/edges.go +++ b/src/pkg/customers/edges.go @@ -188,6 +188,35 @@ func (x *Index) Put(edges []Edge) (int, error) { return n, nil } +// PutNew writes the edges the index does not hold yet, keyed by (person, +// predicate, artefact), and leaves an existing edge exactly as it is, so a +// weaker source cannot overwrite the time or source of a stronger one. An +// edge that cannot be stored is skipped. It returns how many were written. +func (x *Index) PutNew(edges []Edge) (int, error) { + n := 0 + err := x.db.Update(func(tx *bolt.Tx) error { + ae := tx.Bucket(bucketArtefact) + for _, e := range edges { + if !validEdge(e) { + continue + } + e.At = e.At.UTC() + if ae.Get(artefactKey(e)) != nil { + continue + } + if err := putEdge(tx, e); err != nil { + return err + } + n++ + } + return nil + }) + if err != nil { + return 0, fmt.Errorf("customers: writing edges: %w", err) + } + return n, nil +} + // ByPerson returns a page of a person's edges, newest first. predicate // filters when not empty. after is the cursor a previous page returned; // next is empty on the last page. diff --git a/src/pkg/customers/mentionsearch.go b/src/pkg/customers/mentionsearch.go new file mode 100644 index 0000000000..96715b49c2 --- /dev/null +++ b/src/pkg/customers/mentionsearch.go @@ -0,0 +1,275 @@ +package customers + +import ( + "context" + "errors" + "fmt" + "strings" + "sync" + "time" +) + +// Step E of the Customers RFC (hivecommons/hive#18742, #18884): when a +// person accepts a suggested GitHub login, one budgeted GitHub search for +// mentions and comments gives the new profile history beyond what the hive +// already holds. It is reached from the accept path only. The discovery +// sweep (Sweep) is handed no searcher and makes no network call. +// +// Privacy: only the hit's repository, number and kind are read, never a +// title, body or comment text; an edge is a reference. Nothing here logs a +// login, a query or a token: the caller logs the person id and the counts in +// MentionSearchResult. + +// Per-accept budget. Hard limits, not defaults: a configuration value can +// lower the hourly budget but never raises these. +const ( + // MentionSearchMaxRequests is the most search requests one accept makes: + // one for mentions and one for comments, about two calls per person as + // the RFC says. + MentionSearchMaxRequests = 2 + // MentionSearchPageSize is the results one request asks for (one page). + MentionSearchPageSize = 30 + // MentionSearchMaxResults is the most hits one accept keeps. + MentionSearchMaxResults = MentionSearchMaxRequests * MentionSearchPageSize + // MentionSearchSource names the edges this search writes. + MentionSearchSource = "github_search" + // MentionSearchWindow is the rolling window of the per-hour budget. + MentionSearchWindow = time.Hour +) + +// Search kinds, one request each, and the edge each one produces. +const ( + MentionKindMentions = "mentions" + MentionKindCommenter = "commenter" +) + +// Skip reasons a search reports instead of running. They are fixed words, +// safe to log. +const ( + SkipDisabled = "disabled" + SkipNoRepos = "no_repos" + SkipNotLogin = "not_a_github_login" + SkipHourlyBudget = "hourly_budget_spent" + SkipQuotaLow = "quota_low" + SkipNoSearcher = "no_searcher" +) + +// MentionHit is one issue or pull request GitHub returned for a search. It +// carries no text. +type MentionHit struct { + // Repo is "owner/name". + Repo string + Number int + IsPR bool + // At is when the item last changed, the time of the edge. + At time.Time +} + +// MentionSearcher runs one GitHub search request. kind is MentionKindMentions +// or MentionKindCommenter; repos scopes the query. It returns at most limit +// hits from one page. +type MentionSearcher interface { + SearchMentions(ctx context.Context, kind, login string, repos []string, limit int) ([]MentionHit, error) +} + +// ErrMentionQuotaLow is what a MentionGate or searcher returns when the +// shared GitHub quota says to stand down. +var ErrMentionQuotaLow = errors.New("customers: github quota low") + +// MentionSearch is the budgeted accept-time search. The zero value is not +// usable; build one with NewMentionSearch. +type MentionSearch struct { + searcher MentionSearcher + index *Index + + // Enabled, HourlyLimit, Repos and QuotaLow are read at call time so a + // settings change applies without a restart. A nil Enabled is off. + Enabled func() bool + HourlyLimit func() int + Repos func() []string + // QuotaLow reports a non-empty reason when the shared GitHub quota is + // low or the secondary-limit caution window is engaged. Nil means no + // gate. + QuotaLow func() string + + now func() time.Time + + mu sync.Mutex + spent []time.Time // request times inside the rolling hour +} + +// NewMentionSearch wires a searcher to the edge index. +func NewMentionSearch(searcher MentionSearcher, index *Index) *MentionSearch { + return &MentionSearch{searcher: searcher, index: index, now: time.Now} +} + +// MentionSearchResult counts what one accept's search did. It holds ids and +// counts only, so the whole value is safe to log. +type MentionSearchResult struct { + Person string `json:"person"` + Skipped string `json:"skipped,omitempty"` + Requests int `json:"requests"` + Found int `json:"found"` + Edges int `json:"edges"` + // Truncated is true when a page came back full, so more history exists + // than the budget reads. + Truncated bool `json:"truncated,omitempty"` +} + +// reserve takes up to want requests from the rolling hourly budget and +// returns how many it got. +func (m *MentionSearch) reserve(want, limit int) int { + m.mu.Lock() + defer m.mu.Unlock() + now := m.now() + kept := m.spent[:0] + for _, t := range m.spent { + if now.Sub(t) < MentionSearchWindow { + kept = append(kept, t) + } + } + m.spent = kept + free := limit - len(m.spent) + if free <= 0 { + return 0 + } + if want > free { + want = free + } + for i := 0; i < want; i++ { + m.spent = append(m.spent, now) + } + return want +} + +// refund hands back requests reserved but not made. +func (m *MentionSearch) refund(n int) { + m.mu.Lock() + defer m.mu.Unlock() + for ; n > 0 && len(m.spent) > 0; n-- { + m.spent = m.spent[:len(m.spent)-1] + } +} + +// Run searches GitHub for the activity of one accepted GitHub login and +// writes edges for person. It never returns the login. Only GitHub logins +// are searched: an email address is never sent to GitHub. +func (m *MentionSearch) Run(ctx context.Context, person string, ident Identity) MentionSearchResult { + res := MentionSearchResult{Person: person} + switch { + case m == nil || m.searcher == nil || m.index == nil: + res.Skipped = SkipNoSearcher + return res + case m.Enabled == nil || !m.Enabled(): + res.Skipped = SkipDisabled + return res + case ident.Kind != KindGitHub || strings.TrimSpace(ident.Value) == "" || IsBotLogin(ident.Value): + res.Skipped = SkipNotLogin + return res + } + var repos []string + if m.Repos != nil { + repos = m.Repos() + } + if len(repos) == 0 { + res.Skipped = SkipNoRepos + return res + } + if m.QuotaLow != nil && m.QuotaLow() != "" { + res.Skipped = SkipQuotaLow + return res + } + limit := 0 + if m.HourlyLimit != nil { + limit = m.HourlyLimit() + } + granted := m.reserve(MentionSearchMaxRequests, limit) + if granted == 0 { + res.Skipped = SkipHourlyBudget + return res + } + login := strings.TrimPrefix(strings.TrimSpace(ident.Value), "@") + via := IdentityKey(KindGitHub, ident.Value) + + kinds := [MentionSearchMaxRequests]string{MentionKindMentions, MentionKindCommenter} + seen := map[string]bool{} + var edges []Edge + made := 0 + for _, kind := range kinds[:granted] { + if ctx.Err() != nil { + break + } + // The quota can drop between the two requests: re-check, and hand + // back what is not spent. + if made > 0 && m.QuotaLow != nil && m.QuotaLow() != "" { + res.Skipped = SkipQuotaLow + break + } + room := MentionSearchMaxResults - len(edges) + if room <= 0 { + break + } + if room > MentionSearchPageSize { + room = MentionSearchPageSize + } + hits, err := m.searcher.SearchMentions(ctx, kind, login, repos, room) + made++ + if err != nil { + if errors.Is(err, ErrMentionQuotaLow) { + res.Skipped = SkipQuotaLow + } + break + } + if len(hits) > room { + hits = hits[:room] + } + if len(hits) >= MentionSearchPageSize { + res.Truncated = true + } + pred := PredMentionedIn + if kind == MentionKindCommenter { + pred = PredCommentedOn + } + for _, h := range hits { + if h.Repo == "" || h.Number <= 0 { + continue + } + ref := IssueRef(h.Repo, h.Number) + if h.IsPR { + ref = PRRef(h.Repo, h.Number) + } + key := pred + "\x00" + ref + if seen[key] { + continue + } + seen[key] = true + at := h.At + if at.IsZero() { + at = m.now() + } + edges = append(edges, Edge{ + Person: person, Predicate: pred, Artefact: ref, + Via: via, Source: MentionSearchSource, At: at, Confidence: 1, + }) + } + } + if made < granted { + m.refund(granted - made) + } + res.Requests = made + res.Found = len(edges) + if len(edges) > 0 { + n, err := m.index.PutNew(edges) + if err != nil { + res.Skipped = "index_error" + return res + } + res.Edges = n + } + return res +} + +// String renders the result for a log line: ids and counts only. +func (r MentionSearchResult) String() string { + return fmt.Sprintf("person=%s requests=%d found=%d edges=%d skipped=%s", r.Person, r.Requests, r.Found, r.Edges, r.Skipped) +} diff --git a/src/pkg/customers/mentionsearch_test.go b/src/pkg/customers/mentionsearch_test.go new file mode 100644 index 0000000000..ccc94b4b87 --- /dev/null +++ b/src/pkg/customers/mentionsearch_test.go @@ -0,0 +1,323 @@ +package customers + +import ( + "bytes" + "context" + "errors" + "fmt" + "log/slog" + "path/filepath" + "strings" + "sync" + "testing" + "time" +) + +type fakeMentionSearcher struct { + mu sync.Mutex + calls []string + hits map[string][]MentionHit + err error + // onCall runs before each call returns, to move the quota mid-search. + onCall func(n int) +} + +func (f *fakeMentionSearcher) SearchMentions(_ context.Context, kind, _ string, _ []string, limit int) ([]MentionHit, error) { + f.mu.Lock() + f.calls = append(f.calls, kind) + n := len(f.calls) + f.mu.Unlock() + if f.onCall != nil { + f.onCall(n) + } + if f.err != nil { + return nil, f.err + } + h := f.hits[kind] + if len(h) > limit { + h = h[:limit] + } + return h, nil +} + +func (f *fakeMentionSearcher) count() int { + f.mu.Lock() + defer f.mu.Unlock() + return len(f.calls) +} + +type mentionFixture struct { + m *MentionSearch + f *fakeMentionSearcher + index *Index + person Person + clock *time.Time + quota *string +} + +func newMentionFixture(t *testing.T) *mentionFixture { + t.Helper() + dir := t.TempDir() + store, err := Open(filepath.Join(dir, "customers"), nil) + if err != nil { + t.Fatal(err) + } + index, err := OpenIndex(filepath.Join(dir, "graph")) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = index.Close() }) + p := mustAdd(t, store, "Ada", Identity{Kind: KindGitHub, Value: "ada"}) + f := &fakeMentionSearcher{hits: map[string][]MentionHit{ + MentionKindMentions: { + {Repo: "acme/widgets", Number: 1, At: time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)}, + {Repo: "acme/widgets", Number: 2, IsPR: true, At: time.Date(2026, 11, 2, 0, 0, 0, 0, time.UTC)}, + {Repo: "acme/widgets", Number: 1}, // duplicate of the first + }, + MentionKindCommenter: { + {Repo: "acme/widgets", Number: 1, At: time.Date(2026, 11, 3, 0, 0, 0, 0, time.UTC)}, + }, + }} + now := time.Date(2026, 11, 10, 12, 0, 0, 0, time.UTC) + quota := "" + m := NewMentionSearch(f, index) + m.now = func() time.Time { return now } + m.Enabled = func() bool { return true } + m.HourlyLimit = func() int { return 10 } + m.Repos = func() []string { return []string{"acme/widgets"} } + m.QuotaLow = func() string { return quota } + return &mentionFixture{m: m, f: f, index: index, person: p, clock: &now, quota: "a} +} + +var adaLogin = Identity{Kind: KindGitHub, Value: "ada"} + +func (x *mentionFixture) edges(t *testing.T) []Edge { + t.Helper() + e, _, err := x.index.ByPerson(x.person.ID, "", "", MaxEdgePage) + if err != nil { + t.Fatal(err) + } + return e +} + +func TestMentionSearchWritesDedupedEdges(t *testing.T) { + x := newMentionFixture(t) + res := x.m.Run(context.Background(), x.person.ID, adaLogin) + if res.Skipped != "" || res.Requests != 2 { + t.Fatalf("result = %+v", res) + } + // issue 1 mentioned (the in-batch duplicate is dropped), PR 2 mentioned, + // issue 1 commented on: three edges from four hits. + if res.Found != 3 || res.Edges != 3 { + t.Fatalf("found/edges = %d/%d, want 3/3", res.Found, res.Edges) + } + got := map[string]bool{} + for _, e := range x.edges(t) { + got[e.Predicate+" "+e.Artefact] = true + if e.Source != MentionSearchSource || e.Via != "github:ada" { + t.Errorf("edge %+v has the wrong source or via", e) + } + } + for _, want := range []string{ + PredMentionedIn + " gh:issue:acme/widgets#1", + PredMentionedIn + " gh:pr:acme/widgets#2", + PredCommentedOn + " gh:issue:acme/widgets#1", + } { + if !got[want] { + t.Errorf("missing edge %q in %v", want, got) + } + } + // A second accept of the same history writes nothing new and does not + // touch the edges it already holds. + before := x.edges(t) + again := x.m.Run(context.Background(), x.person.ID, adaLogin) + if again.Found != 3 || again.Edges != 0 { + t.Fatalf("second run found/edges = %d/%d, want 3/0", again.Found, again.Edges) + } + after := x.edges(t) + if len(before) != len(after) { + t.Fatalf("edge count changed %d -> %d", len(before), len(after)) + } +} + +func TestMentionSearchKeepsExistingEdgeUntouched(t *testing.T) { + x := newMentionFixture(t) + at := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) + if _, err := x.index.Put([]Edge{{Person: x.person.ID, Predicate: PredMentionedIn, Artefact: "gh:issue:acme/widgets#1", Source: "github_poll", At: at}}); err != nil { + t.Fatal(err) + } + res := x.m.Run(context.Background(), x.person.ID, adaLogin) + if res.Edges != 2 { + t.Fatalf("edges = %d, want 2 (the one the poll made is kept)", res.Edges) + } + for _, e := range x.edges(t) { + if e.Predicate == PredMentionedIn && e.Artefact == "gh:issue:acme/widgets#1" && (e.Source != "github_poll" || !e.At.Equal(at)) { + t.Fatalf("existing edge was overwritten: %+v", e) + } + } +} + +func TestMentionSearchPerAcceptBudget(t *testing.T) { + x := newMentionFixture(t) + var big []MentionHit + for i := 1; i <= 3*MentionSearchPageSize; i++ { + big = append(big, MentionHit{Repo: "acme/widgets", Number: i}) + } + x.f.hits[MentionKindMentions] = big + x.f.hits[MentionKindCommenter] = big + res := x.m.Run(context.Background(), x.person.ID, adaLogin) + if x.f.count() > MentionSearchMaxRequests || res.Requests > MentionSearchMaxRequests { + t.Fatalf("made %d requests, budget %d", x.f.count(), MentionSearchMaxRequests) + } + if res.Found > MentionSearchMaxResults || res.Edges > MentionSearchMaxResults { + t.Fatalf("kept %d/%d results, budget %d", res.Found, res.Edges, MentionSearchMaxResults) + } + if !res.Truncated { + t.Fatal("a full page must be reported as truncated") + } +} + +func TestMentionSearchPerHourBudget(t *testing.T) { + x := newMentionFixture(t) + x.m.HourlyLimit = func() int { return 3 } + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Requests != 2 || r.Skipped != "" { + t.Fatalf("first accept = %+v", r) + } + // One request left in the hour: the second accept makes it and stops. + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Requests != 1 { + t.Fatalf("second accept requests = %d, want 1", r.Requests) + } + calls := x.f.count() + r := x.m.Run(context.Background(), x.person.ID, adaLogin) + if r.Skipped != SkipHourlyBudget || r.Requests != 0 || x.f.count() != calls { + t.Fatalf("third accept = %+v, calls %d -> %d", r, calls, x.f.count()) + } + // The window rolls: an hour later the budget is back. + *x.clock = x.clock.Add(MentionSearchWindow + time.Second) + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Skipped != "" || r.Requests != 2 { + t.Fatalf("after the window = %+v", r) + } +} + +func TestMentionSearchHourlyBudgetZeroSpendsNothing(t *testing.T) { + x := newMentionFixture(t) + x.m.HourlyLimit = func() int { return 0 } + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Skipped != SkipHourlyBudget || x.f.count() != 0 { + t.Fatalf("result = %+v, calls %d", r, x.f.count()) + } +} + +func TestMentionSearchOffSwitch(t *testing.T) { + x := newMentionFixture(t) + x.m.Enabled = func() bool { return false } + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Skipped != SkipDisabled || x.f.count() != 0 { + t.Fatalf("off: %+v, calls %d", r, x.f.count()) + } + x.m.Enabled = nil + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Skipped != SkipDisabled || x.f.count() != 0 { + t.Fatalf("nil switch must be off: %+v", r) + } + if got := len(x.edges(t)); got != 0 { + t.Fatalf("off wrote %d edges", got) + } +} + +func TestMentionSearchQuotaLowBacksOff(t *testing.T) { + x := newMentionFixture(t) + *x.quota = "api_budget_conserve" + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Skipped != SkipQuotaLow || x.f.count() != 0 { + t.Fatalf("quota low: %+v, calls %d", r, x.f.count()) + } + // A skip because of quota must not spend the hourly budget. + *x.quota = "" + x.m.HourlyLimit = func() int { return 2 } + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Requests != 2 { + t.Fatalf("after quota recovered: %+v", r) + } +} + +func TestMentionSearchQuotaDropsBetweenRequests(t *testing.T) { + x := newMentionFixture(t) + x.f.onCall = func(n int) { + if n == 1 { + *x.quota = "caution_window" + } + } + r := x.m.Run(context.Background(), x.person.ID, adaLogin) + if r.Requests != 1 || r.Skipped != SkipQuotaLow || x.f.count() != 1 { + t.Fatalf("result = %+v, calls %d", r, x.f.count()) + } + if r.Edges == 0 { + t.Fatal("what the first request found is still kept") + } + // The unspent request is handed back to the hourly budget. + x.m.HourlyLimit = func() int { return 2 } + *x.quota = "" + x.f.onCall = nil + if r2 := x.m.Run(context.Background(), x.person.ID, adaLogin); r2.Requests != 1 { + t.Fatalf("budget was not refunded: %+v", r2) + } +} + +func TestMentionSearchRateLimitedStopsAndNamesQuota(t *testing.T) { + x := newMentionFixture(t) + x.f.err = ErrMentionQuotaLow + r := x.m.Run(context.Background(), x.person.ID, adaLogin) + if r.Skipped != SkipQuotaLow || x.f.count() != 1 { + t.Fatalf("result = %+v, calls %d (a refusal must end the search)", r, x.f.count()) + } +} + +func TestMentionSearchOnlyGitHubLoginsAndRepos(t *testing.T) { + x := newMentionFixture(t) + for _, id := range []Identity{ + {Kind: KindEmail, Value: "ada@example.com"}, + {Kind: KindGitEmail, Value: "1+ada@users.noreply.github.com"}, + {Kind: KindGitHub, Value: ""}, + {Kind: KindGitHub, Value: "dependabot[bot]"}, + } { + if r := x.m.Run(context.Background(), x.person.ID, id); r.Skipped != SkipNotLogin { + t.Errorf("%+v: %+v", id, r) + } + } + x.m.Repos = func() []string { return nil } + if r := x.m.Run(context.Background(), x.person.ID, adaLogin); r.Skipped != SkipNoRepos { + t.Errorf("no repos: %+v", r) + } + if x.f.count() != 0 { + t.Fatalf("%d calls for identities that must never be searched", x.f.count()) + } + var none *MentionSearch + if r := none.Run(context.Background(), x.person.ID, adaLogin); r.Skipped != SkipNoSearcher { + t.Errorf("nil search: %+v", r) + } +} + +// The log line and the result hold ids and counts only. +func TestMentionSearchResultCarriesNoLoginOrText(t *testing.T) { + x := newMentionFixture(t) + x.f.err = errors.New("GET https://api.github.com/search/issues?q=mentions:ada token ghp_secret") + r := x.m.Run(context.Background(), x.person.ID, adaLogin) + var buf bytes.Buffer + slog.New(slog.NewTextHandler(&buf, nil)).Info("search", "result", r.String(), "person", r.Person) + // The person id is opaque and is the one thing a log line may carry. + out := strings.ReplaceAll(buf.String()+fmt.Sprintf("%+v", r), r.Person, "") + for _, bad := range []string{"ada", "Ada", "ghp_", "api.github.com", "mentions:", "token"} { + if strings.Contains(out, bad) { + t.Errorf("result %q leaks %q", out, bad) + } + } +} + +func TestMentionSearchHitsStoreNoText(t *testing.T) { + x := newMentionFixture(t) + x.m.Run(context.Background(), x.person.ID, adaLogin) + for _, e := range x.edges(t) { + if RefKind(e.Artefact) != RefGitHub { + t.Errorf("edge artefact %q is not a reference", e.Artefact) + } + if strings.ContainsAny(e.Artefact, " \n") { + t.Errorf("edge artefact %q holds free text", e.Artefact) + } + } +} diff --git a/src/pkg/dashboard/api_governor_features.go b/src/pkg/dashboard/api_governor_features.go index 58e217a67f..3cb39df9ef 100644 --- a/src/pkg/dashboard/api_governor_features.go +++ b/src/pkg/dashboard/api_governor_features.go @@ -145,6 +145,9 @@ func (s *Server) handleGovernorFeatures(w http.ResponseWriter, r *http.Request) // customers.avatars.enabled: GitHub profile pictures on the // Customers list. Default on. CustomersAvatarsEnabled *bool `json:"customersAvatarsEnabled"` + // #18884: customers.mention_search.enabled, the budgeted GitHub + // search made when a suggested person is accepted. Default off. + CustomersSearchEnabled *bool `json:"customersSearchEnabled"` AutonomyAutoPromote *bool `json:"autonomyAutoPromote"` AutonomyAutoDemote *bool `json:"autonomyAutoDemote"` @@ -378,6 +381,10 @@ func (s *Server) handleGovernorFeatures(w http.ResponseWriter, r *http.Request) on := *body.CustomersAvatarsEnabled cfg.Customers.Avatars.Enabled = &on } + if body.CustomersSearchEnabled != nil { + on := *body.CustomersSearchEnabled + cfg.Customers.MentionSearch.Enabled = &on + } if claimsTTLsChanged { applyClaimsTTLs(&cfg.Governor.Claims, body.ClaimsTTLS, body.ClaimsHumanTTLS, body.ClaimsAgentTTLS, body.ClaimsContributorTTLS, body.ClaimsMaxTTLS) // Live claims keep their expiry; claims made or renewed from now on @@ -586,6 +593,8 @@ func featuresSectionResponse(cfg *config.Config) map[string]interface{} { "customersInferenceEffective": cfg.CustomersInferenceEnabled(), "customersAvatars": cfg.Customers.Avatars.IsEnabled(), "customersAvatarsEffective": cfg.CustomersAvatarsEnabled(), + "customersSearch": cfg.Customers.MentionSearch.IsEnabled(), + "customersSearchEffective": cfg.CustomersMentionSearchEnabled(), "publicationEnabled": cfg.Publication.Enabled, "publicationPrivateChannel": cfg.Publication.PrivateChannel, "publicationOwner": cfg.Publication.Owner, diff --git a/src/pkg/dashboard/customers_mention_ui_test.go b/src/pkg/dashboard/customers_mention_ui_test.go new file mode 100644 index 0000000000..f4b8a7598c --- /dev/null +++ b/src/pkg/dashboard/customers_mention_ui_test.go @@ -0,0 +1,75 @@ +package dashboard + +import ( + "encoding/json" + "net/http" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" +) + +// TestGovernorFeatures_CustomersMentionSearchToggleRoundTrip covers +// customers.mention_search.enabled: default off, owner-only, persisted, +// reported back with the effective value, left alone by a PUT that does not +// mention it, overridden by the env var, and off whenever Customers is off. +func TestGovernorFeatures_CustomersMentionSearchToggleRoundTrip(t *testing.T) { + t.Setenv(config.EnvCustomersEnabled, "") + t.Setenv(config.EnvCustomersMentionSearchEnabled, "") + s := covApiServer(t) + type payload struct { + Features struct { + Search bool `json:"customersSearch"` + SearchEffective bool `json:"customersSearchEffective"` + } `json:"features"` + } + read := func() payload { + var p payload + if err := json.Unmarshal(doOwnerGet(s, "/api/config/governor").Body.Bytes(), &p); err != nil { + t.Fatal(err) + } + return p + } + if got := read(); got.Features.Search || got.Features.SearchEffective { + t.Fatalf("default payload = %+v, want off", got.Features) + } + if rec := putFeatures(s, map[string]any{"customersSearchEnabled": true}, func(r *http.Request) { + r.Header.Set("X-Hive-Role", "read-write") + }); rec.Code != http.StatusForbidden || s.deps.Config.Customers.MentionSearch.IsEnabled() { + t.Fatalf("non-owner PUT = %d, enabled=%v", rec.Code, s.deps.Config.Customers.MentionSearch.IsEnabled()) + } + if rec := doPut(s, "/api/config/governor/features", map[string]any{"customersSearchEnabled": true}); rec.Code != http.StatusOK { + t.Fatalf("PUT on: %d - %s", rec.Code, rec.Body.String()) + } + if got := read(); !got.Features.Search || !got.Features.SearchEffective { + t.Fatalf("after enable = %+v", got.Features) + } + if rec := doPut(s, "/api/config/governor/features", map[string]any{"retroEnabled": true}); rec.Code != http.StatusOK || !s.deps.Config.Customers.MentionSearch.IsEnabled() { + t.Fatalf("an unrelated PUT changed it: %d", rec.Code) + } + if rec := doPut(s, "/api/config/governor/features", map[string]any{"customersEnabled": false}); rec.Code != http.StatusOK { + t.Fatalf("PUT customers off: %d", rec.Code) + } + if got := read(); !got.Features.Search || got.Features.SearchEffective { + t.Fatalf("customers off = %+v, want saved on, effective off", got.Features) + } + t.Setenv(config.EnvCustomersEnabled, "true") + t.Setenv(config.EnvCustomersMentionSearchEnabled, "false") + if got := read(); !got.Features.Search || got.Features.SearchEffective { + t.Fatalf("env override = %+v", got.Features) + } +} + +func TestFeaturesTab_CustomersMentionSearchToggleMarkup(t *testing.T) { + html := featuresMarkup(t) + for _, want := range []string{ + `data-section="features" data-key="customersSearchEnabled"`, + `yamlHint('customers.mention_search.enabled')`, + `f.customersSearchEffective !== f.customersSearch`, + `HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED (or turning Customers off) overrides this setting`, + } { + if !strings.Contains(html, want) { + t.Errorf("index.html missing %q", want) + } + } +} diff --git a/src/pkg/dashboard/static-src/js/config-features.js b/src/pkg/dashboard/static-src/js/config-features.js index eaa2121a44..7586a67611 100644 --- a/src/pkg/dashboard/static-src/js/config-features.js +++ b/src/pkg/dashboard/static-src/js/config-features.js @@ -894,6 +894,11 @@ Customer avatars ${yamlHint('customers.avatars.enabled')} ${settingHelpMark('settings', 'features', 'Customer avatars', `ON by default. The Customers list shows a person's GitHub picture next to their name when they have a confirmed GitHub login. This is the one thing in Customers that leaves your browser: it asks github.com for https://github.com/.png, once per person on screen, and sends no referrer. Nothing goes to the hive's server or the hub, and nobody known only by email is looked up anywhere. Off, the list shows initials and makes no request to github.com. Applies on the next refresh. HIVE_CUSTOMERS_AVATARS_ENABLED overrides it. See src/docs/design/customers.md.`)} ${f.customersAvatarsEffective !== f.customersAvatars ? `

HIVE_CUSTOMERS_AVATARS_ENABLED overrides this setting: avatars are currently ${f.customersAvatarsEffective ? 'on' : 'off'}.

` : ''} +
+
+ Search GitHub when accepting a person ${yamlHint('customers.mention_search.enabled')} ${settingHelpMark('settings', 'features', 'Customer GitHub search on accept', `OFF by default. When on, accepting a suggested GitHub login makes one budgeted GitHub search (issues and pull requests that mention the login and ones it commented on, in this hive's own repositories) so the new profile starts with history beyond what the hive already holds. The results are stored as references only, never text. It is never run by the discovery sweep and never for an email address. It sends the login to GitHub, makes at most two search requests per accept, shares an hourly request budget across accepts (customers.mention_search.max_requests_per_hour in the config file, default 10), counts against the shared GitHub quota, and stands down while that quota is low or GitHub's secondary limit is engaged. Needs Customers on. HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED overrides it. See src/docs/design/customers.md.`)} +
+ ${f.customersSearchEffective !== f.customersSearch ? `

HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED (or turning Customers off) overrides this setting: the search is currently ${f.customersSearchEffective ? 'on' : 'off'}.

` : ''}
diff --git a/src/pkg/dashboard/static-src/js/config-state.js b/src/pkg/dashboard/static-src/js/config-state.js index a93ab77dd3..6998158f9a 100644 --- a/src/pkg/dashboard/static-src/js/config-state.js +++ b/src/pkg/dashboard/static-src/js/config-state.js @@ -114,6 +114,7 @@ { tab: 'Features', section: 'Agents & tooling', label: 'Customers', key: 'customers.enabled', text: 'customers people profile person identities tags goals satisfaction suggested forget customer graph HIVE_CUSTOMERS_ENABLED customers.enabled' }, { tab: 'Features', section: 'Agents & tooling', label: 'Customer goal and satisfaction suggestions', key: 'customers.inference.enabled', text: 'customers inference infer suggest goals satisfaction model confirm HIVE_CUSTOMERS_INFERENCE_ENABLED customers.inference.enabled' }, { tab: 'Features', section: 'Agents & tooling', label: 'Customer avatars', key: 'customers.avatars.enabled', text: 'customers avatars avatar pictures photos github profile picture privacy HIVE_CUSTOMERS_AVATARS_ENABLED customers.avatars.enabled' }, + { tab: 'Features', section: 'Agents & tooling', label: 'Customer GitHub search on accept', key: 'customers.mention_search.enabled', text: 'customers github search accept mention mentions comments history quota budget suggested person HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED customers.mention_search.enabled' }, { tab: 'Features', section: 'Agents & tooling', label: 'Re-entrant turns and PR follow-up windows', key: 'turn.reentrant.enabled', text: 'reentrant re-entrant turn envelope background fleet pr follow-up resume window retention turn.reentrant.enabled turn.reentrant.background_fleet_enabled turn.pr_follow_up.max_age turn.pr_follow_up.resume_id_max_age turn.pr_follow_up.retention' }, { tab: 'Features', section: 'Agents & tooling', label: 'Data directories and session retention', key: 'data.metrics_dir', text: 'data directories metrics logs agent configs claude copilot bob sessions retention prune janitor data.agents_dir data.bob_sessions_dir data.claude_sessions_dir data.copilot_sessions_dir data.logs_dir data.metrics_dir data.session_retention_days' }, { tab: 'Features', section: 'Integrations & observability', label: 'Standalone deployment upgrades', key: 'deployment.podman_mode', text: 'deployment podman quadlet rootless rootful docker compose upgrade helper request dir deployment.podman_mode deployment.upgrade_helper deployment.upgrade_request_dir' }, diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 41727abed1..ee57e4826b 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -63964,6 +63964,7 @@

Configure LiteLLM

{ tab: 'Features', section: 'Agents & tooling', label: 'Customers', key: 'customers.enabled', text: 'customers people profile person identities tags goals satisfaction suggested forget customer graph HIVE_CUSTOMERS_ENABLED customers.enabled' }, { tab: 'Features', section: 'Agents & tooling', label: 'Customer goal and satisfaction suggestions', key: 'customers.inference.enabled', text: 'customers inference infer suggest goals satisfaction model confirm HIVE_CUSTOMERS_INFERENCE_ENABLED customers.inference.enabled' }, { tab: 'Features', section: 'Agents & tooling', label: 'Customer avatars', key: 'customers.avatars.enabled', text: 'customers avatars avatar pictures photos github profile picture privacy HIVE_CUSTOMERS_AVATARS_ENABLED customers.avatars.enabled' }, + { tab: 'Features', section: 'Agents & tooling', label: 'Customer GitHub search on accept', key: 'customers.mention_search.enabled', text: 'customers github search accept mention mentions comments history quota budget suggested person HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED customers.mention_search.enabled' }, { tab: 'Features', section: 'Agents & tooling', label: 'Re-entrant turns and PR follow-up windows', key: 'turn.reentrant.enabled', text: 'reentrant re-entrant turn envelope background fleet pr follow-up resume window retention turn.reentrant.enabled turn.reentrant.background_fleet_enabled turn.pr_follow_up.max_age turn.pr_follow_up.resume_id_max_age turn.pr_follow_up.retention' }, { tab: 'Features', section: 'Agents & tooling', label: 'Data directories and session retention', key: 'data.metrics_dir', text: 'data directories metrics logs agent configs claude copilot bob sessions retention prune janitor data.agents_dir data.bob_sessions_dir data.claude_sessions_dir data.copilot_sessions_dir data.logs_dir data.metrics_dir data.session_retention_days' }, { tab: 'Features', section: 'Integrations & observability', label: 'Standalone deployment upgrades', key: 'deployment.podman_mode', text: 'deployment podman quadlet rootless rootful docker compose upgrade helper request dir deployment.podman_mode deployment.upgrade_helper deployment.upgrade_request_dir' }, @@ -78551,6 +78552,11 @@

${esc(s.title)}

Customer avatars ${yamlHint('customers.avatars.enabled')} ${settingHelpMark('settings', 'features', 'Customer avatars', `ON by default. The Customers list shows a person's GitHub picture next to their name when they have a confirmed GitHub login. This is the one thing in Customers that leaves your browser: it asks github.com for https://github.com/.png, once per person on screen, and sends no referrer. Nothing goes to the hive's server or the hub, and nobody known only by email is looked up anywhere. Off, the list shows initials and makes no request to github.com. Applies on the next refresh. HIVE_CUSTOMERS_AVATARS_ENABLED overrides it. See src/docs/design/customers.md.`)}
${f.customersAvatarsEffective !== f.customersAvatars ? `

HIVE_CUSTOMERS_AVATARS_ENABLED overrides this setting: avatars are currently ${f.customersAvatarsEffective ? 'on' : 'off'}.

` : ''} +
+
+ Search GitHub when accepting a person ${yamlHint('customers.mention_search.enabled')} ${settingHelpMark('settings', 'features', 'Customer GitHub search on accept', `OFF by default. When on, accepting a suggested GitHub login makes one budgeted GitHub search (issues and pull requests that mention the login and ones it commented on, in this hive's own repositories) so the new profile starts with history beyond what the hive already holds. The results are stored as references only, never text. It is never run by the discovery sweep and never for an email address. It sends the login to GitHub, makes at most two search requests per accept, shares an hourly request budget across accepts (customers.mention_search.max_requests_per_hour in the config file, default 10), counts against the shared GitHub quota, and stands down while that quota is low or GitHub's secondary limit is engaged. Needs Customers on. HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED overrides it. See src/docs/design/customers.md.`)} +
+ ${f.customersSearchEffective !== f.customersSearch ? `

HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED (or turning Customers off) overrides this setting: the search is currently ${f.customersSearchEffective ? 'on' : 'off'}.

` : ''}
diff --git a/src/pkg/github/mention_search.go b/src/pkg/github/mention_search.go new file mode 100644 index 0000000000..a5f381e2a9 --- /dev/null +++ b/src/pkg/github/mention_search.go @@ -0,0 +1,168 @@ +package github + +import ( + "context" + "errors" + "fmt" + "strings" + "time" + + gh "github.com/google/go-github/v72/github" +) + +// The Customers accept-time search (hivecommons/hive#18884). One request asks +// GitHub's issue search for the issues and pull requests that mention a login +// or that the login commented on, scoped to the hive's own repositories. It +// goes through the shared transport, so the rate-limit tracker, the REST +// accounting (caller mentionSearchCaller) and the slow-start pacer all see +// it. It reads no text: only the repository, number, kind and update time of +// each hit are returned. +const ( + // mentionSearchCaller labels the request in /api/gh-rate-limits. + mentionSearchCaller = "customers_mention_search" + // MentionSearchKindMentions and MentionSearchKindCommenter are the two + // search qualifiers the call accepts. + MentionSearchKindMentions = "mentions" + MentionSearchKindCommenter = "commenter" + // mentionSearchMaxPerPage is GitHub's page size limit. + mentionSearchMaxPerPage = 100 + // mentionSearchLowRemaining is the search-bucket remaining at or below + // which optional searches stand down. GitHub allows 30 search requests a + // minute, so a reading this low means other callers are using it. + mentionSearchLowRemaining = 5 +) + +// MentionHit is one issue or pull request found by SearchMentions. +type MentionHit struct { + // Repo is "owner/name". + Repo string + Number int + IsPR bool + UpdatedAt time.Time +} + +// OptionalSearchStandDown returns a short reason when optional work should +// not spend GitHub quota now, and "" when it may: the API budget mode is not +// normal, the secondary-limit caution window is engaged, or the core or +// search bucket is low. The reasons are fixed words, safe to log. +func (c *Client) OptionalSearchStandDown() string { + if c == nil { + return "no_client" + } + if mode, _ := c.APIBudgetMode(); mode != APIBudgetNormal { + return "api_budget_" + mode.String() + } + if RateLimitCautionEngaged() { + return "caution_window" + } + if !LowValueRESTWorkAllowed() { + return "core_low" + } + if remaining, _, ok := RateLimitBudget("search"); ok && remaining <= mentionSearchLowRemaining { + return "search_low" + } + return "" +} + +// mentionSearchQuery builds ": repo:o/r ...", adding repositories +// until GitHub's query length limit. It returns "" when no repository fits. +func mentionSearchQuery(kind, login string, repos []string) string { + q := kind + ":" + login + added := 0 + seen := map[string]bool{} + for _, r := range repos { + r = strings.TrimSpace(r) + key := strings.ToLower(r) + if r == "" || !strings.Contains(r, "/") || seen[key] { + continue + } + seen[key] = true + next := q + " repo:" + r + if len(next) > searchQueryMaxLen { + break + } + q = next + added++ + } + if added == 0 { + return "" + } + return q +} + +// SearchMentions makes ONE search request (one page of at most limit hits) +// for the issues and pull requests that mention login (kind +// MentionSearchKindMentions) or that login commented on (kind +// MentionSearchKindCommenter), in repos. repos entries are "owner/name"; a +// bare name is qualified with the client's organisation. The request is +// tagged low priority, so the pacer sheds it first under caution. +func (c *Client) SearchMentions(ctx context.Context, kind, login string, repos []string, limit int) ([]MentionHit, error) { + if c == nil || c.client == nil { + return nil, ErrNoGitHubClient + } + if kind != MentionSearchKindMentions && kind != MentionSearchKindCommenter { + return nil, fmt.Errorf("mention search: unknown kind") + } + login = strings.TrimPrefix(strings.TrimSpace(login), "@") + if login == "" || strings.ContainsAny(login, " \t\r\n:") { + return nil, fmt.Errorf("mention search: invalid login") + } + if limit <= 0 || limit > mentionSearchMaxPerPage { + limit = mentionSearchMaxPerPage + } + qualified := make([]string, 0, len(repos)) + for _, r := range repos { + if owner, name := c.splitRepo(strings.TrimSpace(r)); owner != "" && name != "" { + qualified = append(qualified, owner+"/"+name) + } + } + query := mentionSearchQuery(kind, login, qualified) + if query == "" { + return nil, nil + } + ctx = WithPacingClass(WithRESTCaller(ctx, mentionSearchCaller), PacingLow) + result, _, err := c.client.Search.Issues(ctx, query, &gh.SearchOptions{ + Sort: "updated", Order: "desc", ListOptions: gh.ListOptions{PerPage: limit}, + }) + if err != nil { + return nil, classifyMentionSearchError(ctx, err) + } + out := make([]MentionHit, 0, len(result.Issues)) + for _, is := range result.Issues { + if is == nil || is.GetNumber() <= 0 { + continue + } + o, r := blockerRepoFromURLs(is.GetRepositoryURL(), is.GetHTMLURL()) + if o == "" || r == "" { + continue + } + out = append(out, MentionHit{Repo: o + "/" + r, Number: is.GetNumber(), IsPR: is.IsPullRequest(), UpdatedAt: is.GetUpdatedAt().Time}) + if len(out) >= limit { + break + } + } + return out, nil +} + +// ErrMentionSearchRateLimited is returned when GitHub refused the search for +// a rate-limit reason (primary or secondary) or the pacer shed it. +var ErrMentionSearchRateLimited = errors.New("mention search: rate limited") + +// classifyMentionSearchError reduces a transport error to a class. go-github +// errors and URL errors echo the request URL, which holds the login being +// searched, so the original text is never returned. +func classifyMentionSearchError(ctx context.Context, err error) error { + if ctx.Err() != nil { + return ctx.Err() + } + var rl *gh.RateLimitError + var abuse *gh.AbuseRateLimitError + if errors.Is(err, ErrPacingShed) || errors.As(err, &rl) || errors.As(err, &abuse) { + return ErrMentionSearchRateLimited + } + var ghErr *gh.ErrorResponse + if errors.As(err, &ghErr) && ghErr.Response != nil { + return fmt.Errorf("mention search failed: HTTP %d", ghErr.Response.StatusCode) + } + return errors.New("mention search failed") +} diff --git a/src/pkg/github/mention_search_test.go b/src/pkg/github/mention_search_test.go new file mode 100644 index 0000000000..b19bde5631 --- /dev/null +++ b/src/pkg/github/mention_search_test.go @@ -0,0 +1,153 @@ +package github + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "net/http/httptest" + "strings" + "sync/atomic" + "testing" + "time" +) + +func TestMentionSearchQueryScopesAndBounds(t *testing.T) { + if got := mentionSearchQuery("mentions", "ada", []string{"acme/a", "ACME/A", "acme/b", "bare", ""}); got != "mentions:ada repo:acme/a repo:acme/b" { + t.Fatalf("query = %q", got) + } + if got := mentionSearchQuery("mentions", "ada", nil); got != "" { + t.Fatalf("no repos must give no query, got %q", got) + } + var many []string + for i := 0; i < 100; i++ { + many = append(many, "acme/repository-with-a-long-name-"+strings.Repeat("x", 5)) + many[i] += string(rune('a' + i%26)) + many[i] += strings.Repeat("y", i%7) + } + if q := mentionSearchQuery("commenter", "ada", many); q == "" || len(q) > searchQueryMaxLen { + t.Fatalf("query length %d, limit %d", len(q), searchQueryMaxLen) + } +} + +func TestSearchMentionsMakesOneScopedRequest(t *testing.T) { + var calls atomic.Int32 + var gotQ, gotPer string + mux := http.NewServeMux() + mux.HandleFunc("/search/issues", func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + gotQ = r.URL.Query().Get("q") + gotPer = r.URL.Query().Get("per_page") + _ = json.NewEncoder(w).Encode(map[string]any{ + "total_count": 2, + "items": []map[string]any{ + {"number": 7, "title": "secret title", "body": "secret body", "repository_url": "https://api.github.com/repos/acme/widgets", "updated_at": "2026-11-01T00:00:00Z"}, + {"number": 9, "pull_request": map[string]any{"url": "x"}, "repository_url": "https://api.github.com/repos/acme/widgets", "updated_at": "2026-11-02T00:00:00Z"}, + {"number": 0, "repository_url": "https://api.github.com/repos/acme/widgets"}, + }, + }) + }) + srv := httptest.NewServer(mux) + defer srv.Close() + c := newTestClient(t, srv, "acme", []string{"widgets"}) + hits, err := c.SearchMentions(context.Background(), MentionSearchKindMentions, "@ada", []string{"widgets", "acme/other"}, 30) + if err != nil { + t.Fatal(err) + } + if calls.Load() != 1 { + t.Fatalf("%d requests, want exactly 1", calls.Load()) + } + if gotQ != "mentions:ada repo:acme/widgets repo:acme/other" || gotPer != "30" { + t.Fatalf("q=%q per_page=%q", gotQ, gotPer) + } + if len(hits) != 2 || hits[0].Repo != "acme/widgets" || hits[0].Number != 7 || hits[0].IsPR || !hits[0].UpdatedAt.Equal(time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)) || !hits[1].IsPR || hits[1].Number != 9 { + t.Fatalf("hits = %+v", hits) + } +} + +func TestSearchMentionsRejectsBadInputWithoutARequest(t *testing.T) { + var calls atomic.Int32 + srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { calls.Add(1) })) + defer srv.Close() + c := newTestClient(t, srv, "acme", []string{"widgets"}) + for _, tc := range []struct{ kind, login string }{ + {"author", "ada"}, {MentionSearchKindMentions, ""}, {MentionSearchKindMentions, "a b"}, {MentionSearchKindMentions, "x:y"}, + } { + if _, err := c.SearchMentions(context.Background(), tc.kind, tc.login, []string{"widgets"}, 5); err == nil { + t.Errorf("%+v accepted", tc) + } + } + if hits, err := c.SearchMentions(context.Background(), MentionSearchKindMentions, "ada", nil, 5); err != nil || hits != nil { + t.Errorf("no repos: %v, %v", hits, err) + } + var nilClient *Client + if _, err := nilClient.SearchMentions(context.Background(), MentionSearchKindMentions, "ada", []string{"a/b"}, 5); !errors.Is(err, ErrNoGitHubClient) { + t.Errorf("nil client: %v", err) + } + if calls.Load() != 0 { + t.Fatalf("%d requests for invalid input", calls.Load()) + } +} + +// An error must not carry the searched login or the request URL. +func TestSearchMentionsErrorsNameClassOnly(t *testing.T) { + status := http.StatusInternalServerError + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + http.Error(w, "boom", status) + })) + defer srv.Close() + c := newTestClient(t, srv, "acme", []string{"widgets"}) + _, err := c.SearchMentions(context.Background(), MentionSearchKindMentions, "ada-lovelace", []string{"widgets"}, 5) + if err == nil || strings.Contains(err.Error(), "ada-lovelace") || strings.Contains(err.Error(), "search/issues") || !strings.Contains(err.Error(), "500") { + t.Fatalf("err = %v", err) + } + // A secondary-limit refusal is reported as rate limited. + ResetRateLimitPacingForTest() + t.Cleanup(ResetRateLimitPacingForTest) + srv2 := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Retry-After", "1") + w.Header().Set("X-RateLimit-Remaining", "0") + w.Header().Set("X-RateLimit-Reset", "9999999999") + w.WriteHeader(http.StatusForbidden) + _, _ = w.Write([]byte(`{"message":"You have exceeded a secondary rate limit"}`)) + })) + defer srv2.Close() + c2 := newTestClient(t, srv2, "acme", []string{"widgets"}) + _, err = c2.SearchMentions(context.Background(), MentionSearchKindCommenter, "ada-lovelace", []string{"widgets"}, 5) + if !errors.Is(err, ErrMentionSearchRateLimited) || strings.Contains(err.Error(), "ada-lovelace") { + t.Fatalf("rate limit err = %v", err) + } +} + +func TestOptionalSearchStandDown(t *testing.T) { + ResetRateLimitPacingForTest() + t.Cleanup(ResetRateLimitPacingForTest) + ResetRateLimitBudgetForTest() + t.Cleanup(ResetRateLimitBudgetForTest) + // Other tests in the package leave core readings in the shared REST + // accounting; start this one from an empty store. + prev := sharedRESTAccountingPtr.Load() + sharedRESTAccountingPtr.Store(&restAccountingStore{now: time.Now, coreRemaining: -1}) + t.Cleanup(func() { sharedRESTAccountingPtr.Store(prev) }) + var nilClient *Client + if got := nilClient.OptionalSearchStandDown(); got == "" { + t.Fatal("no client must stand down") + } + c := &Client{} + if got := c.OptionalSearchStandDown(); got != "" { + t.Fatalf("idle client stands down: %q", got) + } + // Secondary-limit caution window. + sharedSlowStartState.mu.Lock() + sharedSlowStartState.cautiousUntil = time.Now().Add(time.Minute) + sharedSlowStartState.mu.Unlock() + if got := c.OptionalSearchStandDown(); got != "caution_window" { + t.Fatalf("caution: %q", got) + } + ResetRateLimitPacingForTest() + // Search bucket nearly spent. + sharedRateLimitBudget.observe("search", mentionSearchLowRemaining, 30) + if got := c.OptionalSearchStandDown(); got != "search_low" { + t.Fatalf("search low: %q", got) + } +}