diff --git a/changelog.d/added-18491-repo-agent-discovery.md b/changelog.d/added-18491-repo-agent-discovery.md new file mode 100644 index 0000000000..e5dc6bb175 --- /dev/null +++ b/changelog.d/added-18491-repo-agent-discovery.md @@ -0,0 +1 @@ +- **Agents declared in a managed repo's `.hive/agents/`** are discovered and held for owner approval, so a project adds an agent with a PR instead of a hive config edit. Every allowlisted managed repo (the same repo-sourced prompt allowlist as `definition_source`: the seed list or an owner-approved repo) is scanned at startup, every 15 minutes (`HIVE_REPO_AGENTS_INTERVAL`) and on a default-branch push touching `.hive/agents/`; each `.yaml` shows up as pending under **Agents → Import → Declared in your repos** and nothing runs until an owner approves it. Approval registers the agent with `definition_source` (marked `discovered`) and, with a sibling `.md`, `prompt_source`; backend, model, mode and tools stay owner-controlled on every later re-apply. Removing the file pauses the agent rather than deleting it. ([#18491](https://github.com/hivecommons/hive/issues/18491)) diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 5ba6f9db19..2243ea8b69 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -7870,6 +7870,364 @@ } } }, + "/api/agents/discovered": { + "get": { + "tags": [ + "Agents" + ], + "summary": "List agents discovered in managed repos", + "description": "Agent definitions found under .hive/agents/*.yaml in managed repos that pass the repo-sourced prompt allowlist, with their approval status. Nothing runs until an owner approves an entry.", + "responses": { + "200": { + "description": "Discovered definitions", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "False when discovery is not running (no GitHub client)." + }, + "pending": { + "type": "integer" + }, + "entries": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "owner/repo:path of the definition file." + }, + "repo": { + "type": "string" + }, + "path": { + "type": "string" + }, + "prompt_path": { + "type": "string", + "description": "Sibling .md that becomes prompt_source on approval, when present." + }, + "name": { + "type": "string", + "description": "Agent key the definition maps to." + }, + "display_name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "emoji": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "invalid", + "approved", + "rejected", + "orphaned" + ] + }, + "agent": { + "type": "string", + "description": "Registered agent, once approved." + }, + "error": { + "type": "string" + }, + "first_seen": { + "type": "string", + "format": "date-time" + }, + "last_seen": { + "type": "string", + "format": "date-time" + }, + "decided_at": { + "type": "string", + "format": "date-time" + }, + "decided_by": { + "type": "string" + }, + "orphaned_at": { + "type": "string", + "format": "date-time" + } + } + } + } + } + } + } + } + } + } + } + }, + "/api/agents/discovered/approve": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Approve a discovered agent", + "description": "Owner-only. Re-reads the definition through the allowlist gate and registers the agent with definition_source (marked discovered) and, when a sibling .md exists, prompt_source. Backend, model and mode come from this request, never the file; tools stay unset for the owner to grant.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string", + "description": "Agent key; defaults to the definition's normalized metadata.name." + }, + "backend": { + "type": "string", + "description": "Defaults to copilot." + }, + "model": { + "type": "string" + }, + "mode": { + "type": "string", + "enum": [ + "ADVISORY", + "ISSUES_ONLY", + "ISSUES_AND_PRS", + "ISSUES_PRS_MERGE", + "NO_GITHUB" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Approved", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "example": "approved" + }, + "name": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Invalid body, mode or agent name" + }, + "403": { + "description": "Owner role required, or the repo is no longer allowlisted" + }, + "404": { + "description": "Unknown entry" + }, + "409": { + "description": "Entry is not pending, or the agent name is taken" + }, + "502": { + "description": "The definition could not be read or parsed" + }, + "503": { + "description": "Discovery is not running" + } + } + } + }, + "/api/agents/discovered/reject": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Reject a discovered agent", + "description": "Owner-only. A rejected definition stays rejected until its file is removed.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Rejected", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "example": "rejected" + }, + "id": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Invalid body" + }, + "403": { + "description": "Owner role required" + }, + "404": { + "description": "Unknown entry" + }, + "409": { + "description": "Entry is not pending" + }, + "503": { + "description": "Discovery is not running" + } + } + } + }, + "/api/agents/discovered/refresh": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Rescan managed repos for agent definitions", + "description": "Owner-only. Rescans every managed repo now instead of waiting for the timer and returns the refreshed list.", + "responses": { + "200": { + "description": "Discovered definitions", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "False when discovery is not running (no GitHub client)." + }, + "pending": { + "type": "integer" + }, + "entries": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "owner/repo:path of the definition file." + }, + "repo": { + "type": "string" + }, + "path": { + "type": "string" + }, + "prompt_path": { + "type": "string", + "description": "Sibling .md that becomes prompt_source on approval, when present." + }, + "name": { + "type": "string", + "description": "Agent key the definition maps to." + }, + "display_name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "emoji": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "invalid", + "approved", + "rejected", + "orphaned" + ] + }, + "agent": { + "type": "string", + "description": "Registered agent, once approved." + }, + "error": { + "type": "string" + }, + "first_seen": { + "type": "string", + "format": "date-time" + }, + "last_seen": { + "type": "string", + "format": "date-time" + }, + "decided_at": { + "type": "string", + "format": "date-time" + }, + "decided_by": { + "type": "string" + }, + "orphaned_at": { + "type": "string", + "format": "date-time" + } + } + } + } + } + } + } + } + }, + "403": { + "description": "Owner role required" + }, + "503": { + "description": "Discovery is not running" + } + } + } + }, "/api/agents/{name}": { "delete": { "tags": [ diff --git a/src/cmd/hive/boot.go b/src/cmd/hive/boot.go index 86b80e6303..0250ccc02e 100644 --- a/src/cmd/hive/boot.go +++ b/src/cmd/hive/boot.go @@ -39,6 +39,7 @@ import ( "github.com/hivecommons/hive/pkg/priorart" "github.com/hivecommons/hive/pkg/promptsrc" "github.com/hivecommons/hive/pkg/questionclose" + "github.com/hivecommons/hive/pkg/repoagents" "github.com/hivecommons/hive/pkg/retro" "github.com/hivecommons/hive/pkg/review/eventdispatch" "github.com/hivecommons/hive/pkg/rotation" @@ -197,6 +198,7 @@ type boot struct { promptFetcher promptsrc.Fetcher defFetcher defsrc.Fetcher definitionResolver *defsrc.Resolver + repoAgents *repoagents.Discoverer // #18491; nil without a GitHub client perspectivesResolver *perspsrc.Resolver pendingTokenSeed []dashboard.TokenSparklineEntry pendingFactSeed []dashboard.FactHistoryEntry diff --git a/src/cmd/hive/boot_repo_agents.go b/src/cmd/hive/boot_repo_agents.go new file mode 100644 index 0000000000..511d39c5e9 --- /dev/null +++ b/src/cmd/hive/boot_repo_agents.go @@ -0,0 +1,98 @@ +package main + +import ( + "os" + "time" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/repoagents" +) + +const ( + // repoAgentsStateEnv overrides where discovered repo agents persist. + repoAgentsStateEnv = "HIVE_REPO_AGENTS_STATE" + defaultRepoAgentsState = "/data/repo-agents.json" + // repoAgentsIntervalEnv overrides the rescan interval (a Go duration). + repoAgentsIntervalEnv = "HIVE_REPO_AGENTS_INTERVAL" + // repoAgentsOrphanTrigger is the pause trigger an orphaned agent records. + repoAgentsOrphanTrigger = "repo-agent-discovery" +) + +// wireRepoAgentDiscovery builds the .hive/agents/ discoverer +// (hivecommons/hive#18491) so the dashboard dependencies carry it, and starts +// its scan loop. It reads managed repos and the repo-sourced prompt allowlist +// from the live config on every pass, reads files through the hive's GitHub +// App client, and pauses an approved agent whose file is removed. Without a +// GitHub client, discovery stays off. +func (b *boot) wireRepoAgentDiscovery() { + if b.cfg == nil || b.ghClient == nil || b.ctx == nil { + return + } + d := repoagents.New(repoagents.Options{ + Client: b.ghClient, + Allow: func(slug string) bool { return b.cfg.GitHubDefinitionAllowed(slug) }, + Repos: func() []string { return managedRepoSlugs(b.cfg) }, + StatePath: envOrDefault(repoAgentsStateEnv, defaultRepoAgentsState), + OnOrphan: b.pauseOrphanedRepoAgent, + Logger: b.logger, + }) + b.repoAgents = d + go d.Run(b.ctx, repoAgentsInterval(b)) +} + +// managedRepoSlugs is project.repos as "owner/repo" slugs. +func managedRepoSlugs(cfg *config.Config) []string { + if cfg == nil { + return nil + } + out := make([]string, 0, len(cfg.Project.Repos)) + for _, r := range cfg.Project.Repos { + if slug := repoagents.RepoSlug(cfg.Project.Org, r); slug != "" { + out = append(out, slug) + } + } + return out +} + +func repoAgentsInterval(b *boot) time.Duration { + raw := os.Getenv(repoAgentsIntervalEnv) + if raw == "" { + return repoagents.DefaultInterval + } + d, err := time.ParseDuration(raw) + if err != nil || d <= 0 { + if b.logger != nil { + b.logger.Warn("invalid repo agent discovery interval, using default", "env", repoAgentsIntervalEnv, "value", raw, "default", repoagents.DefaultInterval) + } + return repoagents.DefaultInterval + } + return d +} + +// pauseOrphanedRepoAgent pauses (never deletes) the agent of a discovered +// definition whose file was removed, as long as that agent still points at +// the removed file. +func (b *boot) pauseOrphanedRepoAgent(e repoagents.Entry) { + if b.agentMgr == nil || b.cfg == nil || e.Agent == "" { + return + } + ac, ok := b.cfg.Agents[e.Agent] + if !ok || !ac.DefinitionSource.IsSet() || ac.DefinitionSource.Slug() != e.Repo || ac.DefinitionSource.Path != e.Path { + return + } + reason := "definition file " + e.Path + " was removed from " + e.Repo + if err := b.agentMgr.PauseBy(e.Agent, repoAgentsOrphanTrigger, reason, repoAgentsOrphanTrigger); err != nil && b.logger != nil { + b.logger.Warn("could not pause orphaned repo agent", "agent", e.Agent, "error", err) + } +} + +// noteRepoAgentPush rescans a repo whose push touched .hive/agents/ on its +// default branch. +func (b *boot) noteRepoAgentPush(event string, payload []byte) { + if event != "push" || b.repoAgents == nil { + return + } + if slug := repoagents.PushRescanRepo(payload); slug != "" { + b.repoAgents.Trigger(slug) + } +} diff --git a/src/cmd/hive/boot_repo_agents_test.go b/src/cmd/hive/boot_repo_agents_test.go new file mode 100644 index 0000000000..013d1bfa6f --- /dev/null +++ b/src/cmd/hive/boot_repo_agents_test.go @@ -0,0 +1,137 @@ +package main + +import ( + "bytes" + "context" + "errors" + "log/slog" + "path/filepath" + "reflect" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/repoagents" +) + +// pauseRecorder records PauseBy calls; every other runtime method is unused +// by the code under test. +type pauseRecorder struct { + hostedRuntime + paused []string + reasons []string + err error +} + +func (p *pauseRecorder) PauseBy(name, trigger, reason, by string) error { + p.paused = append(p.paused, name+"|"+trigger+"|"+by) + p.reasons = append(p.reasons, reason) + return p.err +} + +func TestManagedRepoSlugs(t *testing.T) { + if managedRepoSlugs(nil) != nil { + t.Fatal("nil config should give nil") + } + cfg := &config.Config{Project: config.ProjectConfig{Org: "acme", Repos: []string{"widgets", "other/gadgets", " "}}} + if got, want := managedRepoSlugs(cfg), []string{"acme/widgets", "other/gadgets"}; !reflect.DeepEqual(got, want) { + t.Fatalf("slugs = %v, want %v", got, want) + } +} + +func TestRepoAgentsInterval(t *testing.T) { + var logs bytes.Buffer + b := &boot{logger: slog.New(slog.NewTextHandler(&logs, nil))} + t.Setenv(repoAgentsIntervalEnv, "") + if got := repoAgentsInterval(b); got != repoagents.DefaultInterval { + t.Errorf("unset = %v", got) + } + t.Setenv(repoAgentsIntervalEnv, "5m") + if got := repoAgentsInterval(b); got != 5*time.Minute { + t.Errorf("5m = %v", got) + } + t.Setenv(repoAgentsIntervalEnv, "soon") + if got := repoAgentsInterval(b); got != repoagents.DefaultInterval || logs.Len() == 0 { + t.Errorf("invalid = %v, logged=%d", got, logs.Len()) + } + t.Setenv(repoAgentsIntervalEnv, "-1m") + if got := repoAgentsInterval(&boot{}); got != repoagents.DefaultInterval { + t.Errorf("negative = %v", got) + } +} + +func TestPauseOrphanedRepoAgent(t *testing.T) { + src := &config.DefinitionSourceConfig{Owner: "acme", Repo: "widgets", Path: ".hive/agents/foo.yaml", Discovered: true} + cfg := &config.Config{} + cfg.Agents = map[string]config.AgentConfig{ + "foo": {DefinitionSource: src}, + "moved": {DefinitionSource: &config.DefinitionSourceConfig{Owner: "acme", Repo: "widgets", Path: ".hive/agents/other.yaml"}}, + "plain": {}, + } + rec := &pauseRecorder{} + var logs bytes.Buffer + b := &boot{cfg: cfg, agentMgr: rec, logger: slog.New(slog.NewTextHandler(&logs, nil))} + + entry := repoagents.Entry{Repo: "acme/widgets", Path: ".hive/agents/foo.yaml", Agent: "foo"} + b.pauseOrphanedRepoAgent(entry) + if len(rec.paused) != 1 || rec.paused[0] != "foo|"+repoAgentsOrphanTrigger+"|"+repoAgentsOrphanTrigger { + t.Fatalf("paused = %v", rec.paused) + } + + // Agents that no longer point at the removed file, or are unknown, stay as they are. + for _, e := range []repoagents.Entry{ + {Repo: "acme/widgets", Path: ".hive/agents/foo.yaml", Agent: "moved"}, + {Repo: "acme/widgets", Path: ".hive/agents/foo.yaml", Agent: "plain"}, + {Repo: "acme/widgets", Path: ".hive/agents/foo.yaml", Agent: "gone"}, + {Repo: "acme/widgets", Path: ".hive/agents/foo.yaml"}, + } { + b.pauseOrphanedRepoAgent(e) + } + if len(rec.paused) != 1 { + t.Fatalf("unexpected pauses: %v", rec.paused) + } + + rec.err = errors.New("boom") + b.pauseOrphanedRepoAgent(entry) + if logs.Len() == 0 { + t.Error("pause failure should be logged") + } + (&boot{}).pauseOrphanedRepoAgent(entry) // no runtime: no-op +} + +func TestNoteRepoAgentPush(t *testing.T) { + b := &boot{} + b.noteRepoAgentPush("push", []byte(`{}`)) // no discoverer: no-op + + b.repoAgents = repoagents.New(repoagents.Options{}) + push := []byte(`{"ref":"refs/heads/main","repository":{"full_name":"acme/widgets","default_branch":"main"},"commits":[{"added":[".hive/agents/foo.yaml"]}]}`) + b.noteRepoAgentPush("issues", push) + b.noteRepoAgentPush("push", []byte(`{"ref":"refs/heads/feature","repository":{"full_name":"acme/widgets","default_branch":"main"}}`)) + b.noteRepoAgentPush("push", push) + // Exactly one rescan was queued: fill the rest of the buffer and count. + queued := 1 + for b.repoAgents.Trigger("x/y") { + queued++ + } + const wantQueued = 16 + if queued != wantQueued { + t.Fatalf("queued = %d, want %d (one push rescan plus fillers)", queued, wantQueued) + } +} + +func TestWireRepoAgentDiscovery(t *testing.T) { + (&boot{}).wireRepoAgentDiscovery() // no config, client or ctx: off + + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + t.Setenv(repoAgentsStateEnv, filepath.Join(t.TempDir(), "repo-agents.json")) + cfg := &config.Config{Project: config.ProjectConfig{Org: "acme", Repos: []string{"widgets"}}} + b := &boot{ctx: ctx, cfg: cfg, ghClient: fakeGitHubClient(t), logger: slog.New(slog.NewTextHandler(&bytes.Buffer{}, nil))} + b.wireRepoAgentDiscovery() + if b.repoAgents == nil { + t.Fatal("discoverer not wired") + } + if got := b.repoAgents.List(); len(got) != 0 { + t.Fatalf("a repo off the allowlist was scanned: %+v", got) + } +} diff --git a/src/cmd/hive/forgestate_wire.go b/src/cmd/hive/forgestate_wire.go index 531f089341..335814ce48 100644 --- a/src/cmd/hive/forgestate_wire.go +++ b/src/cmd/hive/forgestate_wire.go @@ -45,6 +45,9 @@ func (b *boot) forgeStateOpenPRs() *github.ForgeStateView { // with the cache off every delivery is a no-op. func (b *boot) webhookDeliveryFunc() func(event, deliveryID string, payload []byte, res github.WebhookEventResult) { return func(event, deliveryID string, payload []byte, res github.WebhookEventResult) { + // A push touching .hive/agents/ rescans that repo's declared + // agents (#18491), whether or not the forge view is up. + b.noteRepoAgentPush(event, payload) view := b.forgeView trigger := b.sweepTrigger if view == nil || trigger == nil { diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 3cb03c5ba8..8a7967ecf3 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -1342,6 +1342,7 @@ func (b *boot) wireBootClosures() { RemergeDerivedReferenceRepos: b.remergeLastDerivedReferenceRepos, OwnerIdentity: b.ownerIdentityStore(), OwnerIdentityChanged: b.ownerIdentityChanged, + RepoAgents: b.repoAgents, ReviewConfigApplied: func(rc config.ReviewConfig) { if b.ghClient == nil { return @@ -3554,6 +3555,9 @@ func (b *boot) bootDashboardAPI() { b.bootDashboardAPIWith(defaultBootDashboardA // bootDashboardAPIWith is bootDashboardAPI with its long-lived effects // injected; see bootDashboardAPIDeps. func (b *boot) bootDashboardAPIWith(deps bootDashboardAPIDeps) { + // Before the dependencies are built, so the dashboard's approval queue + // for repo-declared agents sees the discoverer (#18491). + b.wireRepoAgentDiscovery() deps.registerAPI(b.dashSrv, b.dashboardDependencies()) // The hive's own unblock (blocked sweep, review-backlog block lift) // re-reads the issue into the cached snapshot and the Activity Monitor diff --git a/src/crux/config/agent_runtime.go b/src/crux/config/agent_runtime.go index c1f672eda0..a53f48187f 100644 --- a/src/crux/config/agent_runtime.go +++ b/src/crux/config/agent_runtime.go @@ -59,17 +59,17 @@ func (p *PromptSourceConfig) IsSet() bool { // user-writable dashboard overlay can neither widen the allowlist nor point an // agent at an arbitrary repo the App happens to be installed on. type DefinitionSourceConfig struct { - // Type selects the source kind. Only "github" is currently supported; an - // empty type defaults to "github" when a repo is set. + // Type selects the source kind; only "github" (the default) is supported. Type string `yaml:"type,omitempty" json:"type,omitempty"` Owner string `yaml:"owner,omitempty" json:"owner,omitempty"` Repo string `yaml:"repo,omitempty" json:"repo,omitempty"` Path string `yaml:"path,omitempty" json:"path,omitempty"` Ref string `yaml:"ref,omitempty" json:"ref,omitempty"` - // URL is the human-facing source URL the operator pasted in the import UI - // (e.g. the github.com blob URL). Informational only — Owner/Repo/Path/Ref - // are authoritative for fetching. Kept so the UI can round-trip it. + // URL is the import UI's pasted source URL, kept only so the UI can + // round-trip it; Owner/Repo/Path/Ref are authoritative for fetching. URL string `yaml:"url,omitempty" json:"url,omitempty"` + // Discovered: owner-approved from a repo's .hive/agents/ (#18491); owner keeps backend/model/mode/tools. + Discovered bool `yaml:"discovered,omitempty" json:"discovered,omitempty"` } // Slug returns the "owner/repo" identifier used for allowlist matching, or "" diff --git a/src/docs/agent-configuration.md b/src/docs/agent-configuration.md index de6c2e8e9f..eb864ed619 100644 --- a/src/docs/agent-configuration.md +++ b/src/docs/agent-configuration.md @@ -1136,6 +1136,36 @@ The per-agent `prompt_source` (a kick template fetched from GitHub by `pkg/promp The fetched file must be a valid portable `AgentDefinition`: `kind: AgentDefinition` and a non-empty `metadata.name` are required (`ParseDefinition`, `defsrc.go:138`); everything else is optional. For the full schema and a worked example, see [`../AGENT-DEFINITION.md`](../AGENT-DEFINITION.md) and [`../examples/agents/customized-agent.yaml`](../examples/agents/customized-agent.yaml). +## Agents declared in a managed repo (`.hive/agents/`) + +A managed repo can declare agents itself: each `.hive/agents/.yaml` on its default branch is a portable `AgentDefinition`, and the hive picks it up without a hive config edit ([#18491](https://github.com/hivecommons/hive/issues/18491)). Nothing a repo declares runs until an owner approves it. + +**Which repos are scanned.** Every repo in `project.repos` (a bare name is qualified with `project.org`) that passes the repo-sourced prompt allowlist, `Config.GitHubDefinitionAllowed`, the same gate as `definition_source` and `prompt_source`: the seed allowlist or an owner approval of the repo (see [Owner approval for the hive's own managed repos](#owner-approval-for-the-hives-own-managed-repos)). A repo off the allowlist is never read, and its existing entries are left as they were. Files are read through the hive's GitHub App client, the same path the live definition resolver uses; with no App client, discovery is off. + +**When.** Once at startup, then every 15 minutes (`HIVE_REPO_AGENTS_INTERVAL`, a Go duration, at least `1m`), and on a push webhook to a repo's default branch that touches `.hive/agents/` (a push that lists 20 or more commits always rescans, since GitHub truncates the list). A repo holds at most 50 definition files; extras are ignored with a warning. + +**What an owner sees.** **Agents → Import → Declared in your repos** in the config dialog lists each file with a status (`GET /api/agents/discovered`): + +| Status | Meaning | +|---|---| +| `pending` | Parsed cleanly and waits for an owner. | +| `invalid` | Not a valid `AgentDefinition` (or unreadable); the error is shown. Fix the file and the next scan makes it `pending`. | +| `approved` | Registered as an agent. | +| `rejected` | An owner declined it. It stays declined until the file is removed. | +| `orphaned` | Approved, but the file was removed. The agent is **paused, not deleted**. | + +**Approving** (`POST /api/agents/discovered/approve`, owner only) re-reads the file through the allowlist gate and creates the agent exactly like a keep-linked import, with: + +- `definition_source` pointing at the file, with `discovered: true`; +- `prompt_source` pointing at a sibling `.hive/agents/.md` when the repo has one (otherwise a `spec.promptTemplate` is saved as the kick template, as an import does); +- **backend, model and mode from the owner**, never from the file. They come from the approval request (backend defaults to `copilot`; model and mode stay unset unless given) and can be changed later in the agent's settings. **Tools** start unset for the owner to grant. + +Because `discovered: true` is set, every later reload re-applies the file's other allow-listed fields (the table above) but keeps backend, model, mode and tools as the owner set them (`defsrc.KeepOwnerControlledFields`). A keep-linked import without that marker behaves as before. + +**Removing a file** marks an approved entry `orphaned` and pauses its agent, recorded with trigger `repo-agent-discovery`. The agent and its config are kept: if the file comes back, the entry is tracked again, but the agent stays paused until an owner resumes it. Removing a pending, invalid or rejected file simply drops the entry. A failed directory listing never orphans anything. + +Entries persist in `/data/repo-agents.json` (`HIVE_REPO_AGENTS_STATE` overrides the path). `POST /api/agents/discovered/refresh` rescans now; `POST /api/agents/discovered/reject` declines an entry. + ## Kick templates: what an agent is told to do `kick_template` names a Markdown file resolved from the hive's policies checkout (`/data/policies/examples/kubestellar/agents/`, or the directory your `policies:` config points at), falling back to the defaults embedded in the binary (`src/pkg/policies/defaults/`). It is the agent's **periodic work prompt**: on every kick, the template is loaded, variables like `${ISSUE_LIST}`, `${PR_LIST}`, `${REVIEW_PERSPECTIVES}`, `${AGENT_NAME}`, `${PROJECT_ORG}`, and `${KNOWLEDGE}` are substituted, and the result is dispatched to the agent's session. The shared kick preamble always tells agents that the governor-supplied issue/PR lists are authoritative and that proxy-blocked `gh pr list`, `gh issue list`, and `gh search` discovery should not be used. diff --git a/src/docs/api-reference/agents-and-controls.md b/src/docs/api-reference/agents-and-controls.md index c6e8aef250..b6e2d721d4 100644 --- a/src/docs/api-reference/agents-and-controls.md +++ b/src/docs/api-reference/agents-and-controls.md @@ -37,6 +37,10 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/agents` | Owner only | Agent Create | `pkg/dashboard/api.go:306` | | `POST` | `/api/agents/import` | Owner only | Agent Import | `pkg/dashboard/api.go:307` | | `DELETE` | `/api/agents/{name}` | Owner only | Agent Delete | `pkg/dashboard/api.go:308` | +| `GET` | `/api/agents/discovered` | Dashboard auth/session | Agents declared under `.hive/agents/*.yaml` in allowlisted managed repos, with `status` `pending` / `invalid` / `approved` / `rejected` / `orphaned`; `enabled: false` when discovery is not running ([agent configuration](../agent-configuration.md#agents-declared-in-a-managed-repo-hiveagents)) | `pkg/dashboard/api_repo_agents.go:23` | +| `POST` | `/api/agents/discovered/approve` | Owner only | Register a pending discovered agent: body `{id, name?, backend?, model?, mode?}`; sets `definition_source` (marked `discovered`) and, with a sibling `.md`, `prompt_source`; backend, model and mode come from the request, never the file | `pkg/dashboard/api_repo_agents.go:24` | +| `POST` | `/api/agents/discovered/reject` | Owner only | Decline a pending discovered agent (body `{id}`); stays declined until the file is removed | `pkg/dashboard/api_repo_agents.go:25` | +| `POST` | `/api/agents/discovered/refresh` | Owner only | Rescan every managed repo's `.hive/agents/` now and return the list | `pkg/dashboard/api_repo_agents.go:26` | | `GET` | `/api/agents/{name}/log` | Dashboard auth/session | Agent Full Log | `pkg/dashboard/api.go:107` | | `GET` | `/api/agents/{name}/terminal-urls` | Dashboard auth/session | Agent Terminal URLs | `pkg/dashboard/api.go:111` | diff --git a/src/docs/scale-envelope.md b/src/docs/scale-envelope.md index 7fbcb246b7..e3e391f987 100644 --- a/src/docs/scale-envelope.md +++ b/src/docs/scale-envelope.md @@ -34,7 +34,7 @@ ones to: 2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.** This holds today and is easy to assume backwards: - Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied - (`RankActionableIssues`, `src/pkg/github/client.go:5250-5260`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5286-5296`, descending `AgeMinutes` within each tier). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests). diff --git a/src/internal/testutil/dashboard_import_allowlist.txt b/src/internal/testutil/dashboard_import_allowlist.txt index 61aff277d9..61005b57e4 100644 --- a/src/internal/testutil/dashboard_import_allowlist.txt +++ b/src/internal/testutil/dashboard_import_allowlist.txt @@ -75,6 +75,8 @@ github.com/hivecommons/hive/pkg/policies github.com/hivecommons/hive/pkg/promptsrc github.com/hivecommons/hive/pkg/rebasemerge github.com/hivecommons/hive/pkg/releasenotes +# repoagents: /api/agents/discovered* handlers list and approve the .hive/agents/ discoverer's entries; the discoverer itself routes through Dependencies.RepoAgents (hivecommons/hive#18491). +github.com/hivecommons/hive/pkg/repoagents github.com/hivecommons/hive/pkg/resolve github.com/hivecommons/hive/pkg/retro github.com/hivecommons/hive/pkg/review diff --git a/src/pkg/dashboard/api.go b/src/pkg/dashboard/api.go index 9b4f9658c0..bff7582349 100644 --- a/src/pkg/dashboard/api.go +++ b/src/pkg/dashboard/api.go @@ -561,6 +561,9 @@ func (s *Server) RegisterAPI(deps *Dependencies) { // api_config_prompt_sources.go). s.mux.HandleFunc("GET /api/config/prompt-sources", s.handlePromptSourcesGet) s.mux.HandleFunc("PUT /api/config/prompt-sources/owner-repos", s.handlePromptSourcesOwnerRepoPut) + // Agents discovered in managed repos' .hive/agents/ (#18491, + // api_repo_agents.go): list, approve, reject, rescan. + s.registerRepoAgentRoutes() } var ( diff --git a/src/pkg/dashboard/api_agents.go b/src/pkg/dashboard/api_agents.go index 8e2cc1433a..27bea6d34d 100644 --- a/src/pkg/dashboard/api_agents.go +++ b/src/pkg/dashboard/api_agents.go @@ -397,24 +397,8 @@ func (s *Server) handleAgentImport(w http.ResponseWriter, r *http.Request) { } name := strings.ToLower(strings.ReplaceAll(def.Metadata.Name, " ", "-")) - if strings.ContainsAny(name, " ./\\") || !kickTemplatePattern.MatchString(name+".md") { - jsonError(w, "agent name contains invalid characters", http.StatusBadRequest) - return - } - const maxAgentNameLen = 64 - if len(name) > maxAgentNameLen { - jsonError(w, fmt.Sprintf("agent name must be at most %d characters", maxAgentNameLen), http.StatusBadRequest) - return - } - - if _, exists := s.deps.Config.Agents[name]; exists { - jsonError(w, "agent already exists: "+name, http.StatusConflict) - return - } - - agentsDir := s.deps.Config.Data.AgentsDir - if agentsDir == "" { - jsonError(w, "agents_dir not configured", http.StatusInternalServerError) + if status, err := s.checkNewAgentName(name); err != nil { + jsonError(w, err.Error(), status) return } @@ -444,14 +428,50 @@ func (s *Server) handleAgentImport(w http.ResponseWriter, r *http.Request) { agentCfg.DefinitionSource = defSrc } + if status, err := s.registerDefinedAgent(name, agentCfg, def.Spec.PromptTemplate); err != nil { + jsonError(w, err.Error(), status) + return + } + + s.logger.Info("agent imported via API", "name", name, "source", body.Source) + okResponse(w, map[string]string{"status": "imported", "name": name}) +} + +// maxAgentNameLen bounds an imported or discovered agent's key. +const maxAgentNameLen = 64 + +// checkNewAgentName validates the key a definition-created agent (import or +// an approved repo discovery) will get, and that it can be saved. It returns +// the HTTP status to answer with alongside the error. +func (s *Server) checkNewAgentName(name string) (int, error) { + if name == "" || strings.ContainsAny(name, " ./\\") || !kickTemplatePattern.MatchString(name+".md") { + return http.StatusBadRequest, fmt.Errorf("agent name contains invalid characters") + } + if len(name) > maxAgentNameLen { + return http.StatusBadRequest, fmt.Errorf("agent name must be at most %d characters", maxAgentNameLen) + } + if _, exists := s.deps.Config.Agents[name]; exists { + return http.StatusConflict, fmt.Errorf("agent already exists: %s", name) + } + if s.deps.Config.Data.AgentsDir == "" { + return http.StatusInternalServerError, fmt.Errorf("agents_dir not configured") + } + return http.StatusOK, nil +} + +// registerDefinedAgent saves a definition-created agent's overlay (and its +// prompt template, when the definition carries one), adds it to the live +// config and starts it. Shared by the import handler and the approval of a +// repo-discovered agent so both create agents identically. +func (s *Server) registerDefinedAgent(name string, agentCfg config.AgentConfig, promptTemplate string) (int, error) { + agentsDir := s.deps.Config.Data.AgentsDir if err := config.SaveAgentFile(agentsDir, name, agentCfg); err != nil { s.logger.Error("failed to save imported agent file", "agent", name, "error", err) - jsonError(w, "failed to save agent: "+err.Error(), http.StatusInternalServerError) - return + return http.StatusInternalServerError, fmt.Errorf("failed to save agent: %w", err) } // Save prompt template if provided - if def.Spec.PromptTemplate != "" { + if promptTemplate != "" { templateFileName := name + ".md" agentCfg.KickTemplate = templateFileName @@ -459,7 +479,7 @@ func (s *Server) handleAgentImport(w http.ResponseWriter, r *http.Request) { s.logger.Error("failed to create policies dir for import", "error", err) } else { savePath := filepath.Join(promptTemplateSaveDir, templateFileName) - if err := os.WriteFile(savePath, []byte(def.Spec.PromptTemplate), 0o644); err != nil { + if err := os.WriteFile(savePath, []byte(promptTemplate), 0o644); err != nil { s.logger.Error("failed to save imported prompt template", "agent", name, "error", err) } } @@ -479,8 +499,7 @@ func (s *Server) handleAgentImport(w http.ResponseWriter, r *http.Request) { s.deps.Config.ApplyAgentDefaults(name) if err := s.deps.Config.ExpandAgentReplicas(); err != nil { - jsonError(w, err.Error(), http.StatusBadRequest) - return + return http.StatusBadRequest, err } addedAgents := s.deps.AgentMgr.ReconcileAgents(s.deps.Config.EnabledAgents()) for _, added := range addedAgents { @@ -496,9 +515,7 @@ func (s *Server) handleAgentImport(w http.ResponseWriter, r *http.Request) { s.reInitSubsystems() s.refreshAndPersist() - - s.logger.Info("agent imported via API", "name", name, "source", body.Source) - okResponse(w, map[string]string{"status": "imported", "name": name}) + return http.StatusOK, nil } // promptSourceFetcher returns the GitHub client as a promptsrc.Fetcher, or nil diff --git a/src/pkg/dashboard/api_repo_agents.go b/src/pkg/dashboard/api_repo_agents.go new file mode 100644 index 0000000000..6473343696 --- /dev/null +++ b/src/pkg/dashboard/api_repo_agents.go @@ -0,0 +1,198 @@ +package dashboard + +import ( + "errors" + "fmt" + "net/http" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/repoagents" +) + +// defaultDiscoveredBackend is the backend an approved repo-discovered agent +// gets when the owner names none, the same default the import uses. +const defaultDiscoveredBackend = "copilot" + +// discoveredAgentModes are the modes an owner may pick when approving, the +// same set the agent config editor accepts. +var discoveredAgentModes = map[string]bool{"ADVISORY": true, "ISSUES_ONLY": true, "ISSUES_AND_PRS": true, "ISSUES_PRS_MERGE": true, "NO_GITHUB": true} + +// registerRepoAgentRoutes wires the approval queue for agents discovered in +// managed repos' .hive/agents/ (hivecommons/hive#18491). +func (s *Server) registerRepoAgentRoutes() { + s.mux.HandleFunc("GET /api/agents/discovered", s.handleDiscoveredAgentsList) + s.mux.HandleFunc("POST /api/agents/discovered/approve", s.handleDiscoveredAgentApprove) + s.mux.HandleFunc("POST /api/agents/discovered/reject", s.handleDiscoveredAgentReject) + s.mux.HandleFunc("POST /api/agents/discovered/refresh", s.handleDiscoveredAgentsRefresh) +} + +func (s *Server) repoAgents() *repoagents.Discoverer { + if s.deps == nil { + return nil + } + return s.deps.RepoAgents +} + +// handleDiscoveredAgentsList serves GET /api/agents/discovered. +func (s *Server) handleDiscoveredAgentsList(w http.ResponseWriter, _ *http.Request) { + d := s.repoAgents() + if d == nil { + jsonResponse(w, map[string]any{"enabled": false, "entries": []repoagents.Entry{}}) + return + } + entries := d.List() + pending := 0 + for _, e := range entries { + if e.Status == repoagents.StatusPending { + pending++ + } + } + jsonResponse(w, map[string]any{"enabled": true, "pending": pending, "entries": entries}) +} + +// handleDiscoveredAgentApprove serves POST /api/agents/discovered/approve. +// Owner-only. It re-fetches the file through the allowlist gate, creates the +// agent with definition_source (marked discovered) and, when the repo has a +// sibling .md, prompt_source. Backend, model and mode come from the +// owner's request, never the file; tools are left unset for the owner to grant. +func (s *Server) handleDiscoveredAgentApprove(w http.ResponseWriter, r *http.Request) { + if !requireOwnerRole(w, r) { + return + } + d := s.repoAgents() + if d == nil { + jsonError(w, "repo agent discovery is not running", http.StatusServiceUnavailable) + return + } + var body struct { + ID string `json:"id"` + Name string `json:"name"` + Backend string `json:"backend"` + Model string `json:"model"` + Mode string `json:"mode"` + } + if err := decodeBody(r, &body); err != nil { + jsonError(w, "invalid body: "+err.Error(), http.StatusBadRequest) + return + } + if body.Mode != "" && !discoveredAgentModes[body.Mode] { + jsonError(w, "mode must be one of: ADVISORY, ISSUES_ONLY, ISSUES_AND_PRS, ISSUES_PRS_MERGE, NO_GITHUB", http.StatusBadRequest) + return + } + entry, ok := d.Get(body.ID) + if !ok { + jsonError(w, repoagents.ErrNotFound.Error(), http.StatusNotFound) + return + } + if entry.Status != repoagents.StatusPending { + jsonError(w, fmt.Sprintf("only a pending definition can be approved (this one is %s)", entry.Status), http.StatusConflict) + return + } + if !s.deps.Config.GitHubDefinitionAllowed(entry.Repo) { + jsonError(w, fmt.Sprintf("repo %q is no longer on the repo-sourced prompt allowlist", entry.Repo), http.StatusForbidden) + return + } + def, _, err := d.FetchDefinition(r.Context(), body.ID) + if err != nil { + jsonError(w, "could not read the definition: "+err.Error(), http.StatusBadGateway) + return + } + name := body.Name + if name == "" { + name = repoagents.AgentName(def.Metadata.Name) + } + if status, err := s.checkNewAgentName(name); err != nil { + jsonError(w, err.Error(), status) + return + } + + agentCfg := discoveredAgentConfig(def, entry, body.Backend, body.Model, body.Mode) + if status, err := s.registerDefinedAgent(name, agentCfg, def.Spec.PromptTemplate); err != nil { + jsonError(w, err.Error(), status) + return + } + if _, err := d.Approve(body.ID, name, requestUser(r)); err != nil { + // The agent exists; only the queue entry lagged (a concurrent scan + // moved it). Report it rather than undo a registered agent. + s.logger.Warn("discovered agent registered but its entry was not marked approved", "id", body.ID, "agent", name, "error", err) + } + s.auditFromRequest(r, "approve-discovered-agent", auditDetail("repo", entry.Repo, "path", entry.Path), name) + s.logger.Info("repo-discovered agent approved", "agent", name, "repo", entry.Repo, "path", entry.Path) + okResponse(w, map[string]string{"status": "approved", "name": name}) +} + +// discoveredAgentConfig maps an approved definition to the agent config: the +// import mapping, with backend, model, mode and tools replaced by the owner's +// choices and the source pointers set to the repo file. +func discoveredAgentConfig(def *agentDefinition, e repoagents.Entry, backend, model, mode string) config.AgentConfig { + agentCfg := agentConfigFromDefinition(def) + agentCfg.Backend = valueOrDefault(backend, defaultDiscoveredBackend) + agentCfg.Model = model + agentCfg.Mode = mode + agentCfg.Tools = nil + // An approval is an operator create (#5706), like an import. + agentCfg.PauseOwner = config.FieldOwnerOperator + agentCfg.DefinitionSource = &config.DefinitionSourceConfig{ + Type: "github", + Owner: e.Owner(), + Repo: e.RepoName(), + Path: e.Path, + Discovered: true, + } + if e.PromptPath != "" { + agentCfg.PromptSource = &config.PromptSourceConfig{ + Type: "github", + Owner: e.Owner(), + Repo: e.RepoName(), + Path: e.PromptPath, + } + } + return agentCfg +} + +// handleDiscoveredAgentReject serves POST /api/agents/discovered/reject. +// Owner-only. A rejected definition stays rejected until its file is removed. +func (s *Server) handleDiscoveredAgentReject(w http.ResponseWriter, r *http.Request) { + if !requireOwnerRole(w, r) { + return + } + d := s.repoAgents() + if d == nil { + jsonError(w, "repo agent discovery is not running", http.StatusServiceUnavailable) + return + } + var body struct { + ID string `json:"id"` + } + if err := decodeBody(r, &body); err != nil { + jsonError(w, "invalid body: "+err.Error(), http.StatusBadRequest) + return + } + e, err := d.Reject(body.ID, requestUser(r)) + if err != nil { + status := http.StatusConflict + if errors.Is(err, repoagents.ErrNotFound) { + status = http.StatusNotFound + } + jsonError(w, err.Error(), status) + return + } + s.auditFromRequest(r, "reject-discovered-agent", auditDetail("repo", e.Repo, "path", e.Path), "") + okResponse(w, map[string]string{"status": "rejected", "id": e.ID}) +} + +// handleDiscoveredAgentsRefresh serves POST /api/agents/discovered/refresh. +// Owner-only. It rescans every managed repo now instead of waiting for the +// timer, and answers with the refreshed list. +func (s *Server) handleDiscoveredAgentsRefresh(w http.ResponseWriter, r *http.Request) { + if !requireOwnerRole(w, r) { + return + } + d := s.repoAgents() + if d == nil { + jsonError(w, "repo agent discovery is not running", http.StatusServiceUnavailable) + return + } + d.ScanAll(r.Context()) + s.handleDiscoveredAgentsList(w, r) +} diff --git a/src/pkg/dashboard/api_repo_agents_test.go b/src/pkg/dashboard/api_repo_agents_test.go new file mode 100644 index 0000000000..bcad1dc445 --- /dev/null +++ b/src/pkg/dashboard/api_repo_agents_test.go @@ -0,0 +1,261 @@ +package dashboard + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "strings" + "sync" + "testing" + + "github.com/hivecommons/hive/pkg/repoagents" +) + +type fakeRepoAgentClient struct { + mu sync.Mutex + files map[string]string + readErr error +} + +func (f *fakeRepoAgentClient) ListDirectoryFiles(_ context.Context, owner, repo, dir, _ string) ([]string, error) { + f.mu.Lock() + defer f.mu.Unlock() + prefix := owner + "/" + repo + "/" + dir + "/" + var out []string + for k := range f.files { + if rest, ok := strings.CutPrefix(k, prefix); ok { + out = append(out, rest) + } + } + return out, nil +} + +func (f *fakeRepoAgentClient) GetFileContentRef(_ context.Context, owner, repo, p, _ string) (string, error) { + f.mu.Lock() + defer f.mu.Unlock() + if f.readErr != nil { + return "", f.readErr + } + c, ok := f.files[owner+"/"+repo+"/"+p] + if !ok { + return "", errors.New("not found") + } + return c, nil +} + +const discoveredDef = `apiVersion: hive.kubestellar.io/v1 +kind: AgentDefinition +metadata: + name: Foo Bot + displayName: Foo +spec: + backend: claude + model: opus + mode: ISSUES_ONLY + role: scanner + tools: + preset: full +` + +const discoveredID = "myorg/repo1:.hive/agents/foo.yaml" + +// repoAgentServer is an API server with discovery on and one pending entry +// for myorg/repo1/.hive/agents/foo.yaml (with a sibling foo.md prompt). +func repoAgentServer(t *testing.T) (*Server, *Dependencies, *repoagents.Discoverer, *fakeRepoAgentClient) { + t.Helper() + s, deps := apiServer(t) + deps.Config.Data.AgentsDir = t.TempDir() + enableDefinitionAllowlist(deps, "myorg/repo1") + client := &fakeRepoAgentClient{files: map[string]string{ + "myorg/repo1/.hive/agents/foo.yaml": discoveredDef, + "myorg/repo1/.hive/agents/foo.md": "do foo", + }} + d := repoagents.New(repoagents.Options{ + Client: client, + Allow: deps.Config.GitHubDefinitionAllowed, + Repos: func() []string { return []string{"myorg/repo1"} }, + }) + d.ScanAll(context.Background()) + deps.RepoAgents = d + return s, deps, d, client +} + +func TestDiscoveredAgentsListDisabled(t *testing.T) { + s, _ := apiServer(t) + rec := doGet(s, "/api/agents/discovered") + if rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), `"enabled":false`) { + t.Fatalf("disabled list = %d %s", rec.Code, rec.Body.String()) + } + for _, p := range []string{"/api/agents/discovered/approve", "/api/agents/discovered/reject", "/api/agents/discovered/refresh"} { + if rec := doPost(s, p, map[string]any{"id": "x"}); rec.Code != http.StatusServiceUnavailable { + t.Errorf("%s without discovery = %d, want 503", p, rec.Code) + } + } +} + +func TestDiscoveredAgentsListAndRefresh(t *testing.T) { + s, _, _, client := repoAgentServer(t) + rec := doGet(s, "/api/agents/discovered") + var got struct { + Enabled bool `json:"enabled"` + Pending int `json:"pending"` + Entries []repoagents.Entry `json:"entries"` + } + if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil { + t.Fatal(err) + } + if !got.Enabled || got.Pending != 1 || len(got.Entries) != 1 || got.Entries[0].Name != "foo-bot" { + t.Fatalf("list = %+v", got) + } + + client.mu.Lock() + client.files["myorg/repo1/.hive/agents/bar.yaml"] = strings.Replace(discoveredDef, "Foo Bot", "bar", 1) + client.mu.Unlock() + rec = doPost(s, "/api/agents/discovered/refresh", nil) + if rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), `"pending":2`) { + t.Fatalf("refresh = %d %s", rec.Code, rec.Body.String()) + } + if rec := doPostNoOwner(s, "/api/agents/discovered/refresh", nil); rec.Code != http.StatusForbidden { + t.Errorf("non-owner refresh = %d", rec.Code) + } +} + +// TestDiscoveredAgentApprove: approval registers the agent with the repo +// file as its definition_source (marked discovered), the sibling .md as its +// prompt_source, and the owner's backend/model/mode, not the file's. +func TestDiscoveredAgentApprove(t *testing.T) { + s, deps, d, _ := repoAgentServer(t) + rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID, "model": "gpt-5", "mode": "ADVISORY"}) + if rec.Code != http.StatusOK { + t.Fatalf("approve = %d %s", rec.Code, rec.Body.String()) + } + ac, ok := deps.Config.Agents["foo-bot"] + if !ok { + t.Fatal("agent foo-bot not registered") + } + if ac.Backend != defaultDiscoveredBackend || ac.Model != "gpt-5" || ac.Mode != "ADVISORY" || ac.Tools != nil { + t.Errorf("owner-controlled fields from the file: backend=%q model=%q mode=%q tools=%+v", ac.Backend, ac.Model, ac.Mode, ac.Tools) + } + if ac.Role != "scanner" || ac.DisplayName != "Foo" { + t.Errorf("definition fields not applied: role=%q display=%q", ac.Role, ac.DisplayName) + } + ds := ac.DefinitionSource + if ds == nil || !ds.Discovered || ds.Owner != "myorg" || ds.Repo != "repo1" || ds.Path != ".hive/agents/foo.yaml" { + t.Errorf("definition_source = %+v", ds) + } + ps := ac.PromptSource + if ps == nil || ps.Path != ".hive/agents/foo.md" || ps.Owner != "myorg" { + t.Errorf("prompt_source = %+v", ps) + } + if e, _ := d.Get(discoveredID); e.Status != repoagents.StatusApproved || e.Agent != "foo-bot" { + t.Errorf("entry = %+v", e) + } + + // A second approval of the same entry conflicts. + if rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID}); rec.Code != http.StatusConflict { + t.Errorf("re-approve = %d", rec.Code) + } +} + +func TestDiscoveredAgentApproveCustomNameAndBackend(t *testing.T) { + s, deps, _, _ := repoAgentServer(t) + rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID, "name": "foo2", "backend": "claude"}) + if rec.Code != http.StatusOK { + t.Fatalf("approve = %d %s", rec.Code, rec.Body.String()) + } + if ac := deps.Config.Agents["foo2"]; ac.Backend != "claude" || ac.Model != "" { + t.Errorf("agent = backend %q model %q", ac.Backend, ac.Model) + } +} + +func TestDiscoveredAgentApproveRefusals(t *testing.T) { + t.Run("not owner", func(t *testing.T) { + s, _, _, _ := repoAgentServer(t) + if rec := doPostNoOwner(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID}); rec.Code != http.StatusForbidden { + t.Errorf("got %d", rec.Code) + } + }) + t.Run("bad body", func(t *testing.T) { + s, _, _, _ := repoAgentServer(t) + if rec := doPostRaw(s, "/api/agents/discovered/approve", "{nope"); rec.Code != http.StatusBadRequest { + t.Errorf("got %d", rec.Code) + } + }) + t.Run("bad mode", func(t *testing.T) { + s, _, _, _ := repoAgentServer(t) + if rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID, "mode": "GOD_MODE"}); rec.Code != http.StatusBadRequest { + t.Errorf("got %d", rec.Code) + } + }) + t.Run("unknown id", func(t *testing.T) { + s, _, _, _ := repoAgentServer(t) + if rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": "nope"}); rec.Code != http.StatusNotFound { + t.Errorf("got %d", rec.Code) + } + }) + t.Run("repo dropped off allowlist", func(t *testing.T) { + s, deps, _, _ := repoAgentServer(t) + deps.Config.Variables.Security.GitHubPromptAllowlist = nil + if rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID}); rec.Code != http.StatusForbidden { + t.Errorf("got %d %s", rec.Code, rec.Body.String()) + } + if _, ok := deps.Config.Agents["foo-bot"]; ok { + t.Error("agent registered from a de-allowlisted repo") + } + }) + t.Run("file unreadable", func(t *testing.T) { + s, _, _, client := repoAgentServer(t) + client.readErr = errors.New("boom") + if rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID}); rec.Code != http.StatusBadGateway { + t.Errorf("got %d", rec.Code) + } + }) + t.Run("name taken", func(t *testing.T) { + s, _, _, _ := repoAgentServer(t) + if rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID, "name": "scanner"}); rec.Code != http.StatusConflict { + t.Errorf("got %d", rec.Code) + } + }) + t.Run("bad name", func(t *testing.T) { + s, _, _, _ := repoAgentServer(t) + if rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID, "name": "../etc"}); rec.Code != http.StatusBadRequest { + t.Errorf("got %d", rec.Code) + } + }) +} + +func TestDiscoveredAgentReject(t *testing.T) { + s, deps, d, _ := repoAgentServer(t) + if rec := doPostNoOwner(s, "/api/agents/discovered/reject", map[string]any{"id": discoveredID}); rec.Code != http.StatusForbidden { + t.Errorf("non-owner reject = %d", rec.Code) + } + if rec := doPostRaw(s, "/api/agents/discovered/reject", "{nope"); rec.Code != http.StatusBadRequest { + t.Errorf("bad body = %d", rec.Code) + } + if rec := doPost(s, "/api/agents/discovered/reject", map[string]any{"id": "nope"}); rec.Code != http.StatusNotFound { + t.Errorf("unknown = %d", rec.Code) + } + rec := doPost(s, "/api/agents/discovered/reject", map[string]any{"id": discoveredID}) + if rec.Code != http.StatusOK { + t.Fatalf("reject = %d %s", rec.Code, rec.Body.String()) + } + if e, _ := d.Get(discoveredID); e.Status != repoagents.StatusRejected { + t.Errorf("entry = %+v", e) + } + if _, ok := deps.Config.Agents["foo-bot"]; ok { + t.Error("rejected definition registered an agent") + } + if rec := doPost(s, "/api/agents/discovered/reject", map[string]any{"id": discoveredID}); rec.Code != http.StatusConflict { + t.Errorf("re-reject = %d", rec.Code) + } + if rec := doPost(s, "/api/agents/discovered/approve", map[string]any{"id": discoveredID}); rec.Code != http.StatusConflict { + t.Errorf("approve rejected = %d", rec.Code) + } +} + +func TestRepoAgentsNilDeps(t *testing.T) { + if (&Server{}).repoAgents() != nil { + t.Fatal("nil deps must report no discoverer") + } +} diff --git a/src/pkg/dashboard/deps.go b/src/pkg/dashboard/deps.go index 3d635a6d2e..ed3e2432d7 100644 --- a/src/pkg/dashboard/deps.go +++ b/src/pkg/dashboard/deps.go @@ -28,6 +28,7 @@ import ( "github.com/hivecommons/hive/pkg/inbox" "github.com/hivecommons/hive/pkg/knowledge" "github.com/hivecommons/hive/pkg/nous" + "github.com/hivecommons/hive/pkg/repoagents" "github.com/hivecommons/hive/pkg/review/autoscale" "github.com/hivecommons/hive/pkg/review/eventdispatch" "github.com/hivecommons/hive/pkg/rotation" @@ -233,6 +234,11 @@ type Dependencies struct { // disconnects their account, so the reference-repo policies re-resolve // without a restart. Nil skips. OwnerIdentityChanged func() + // RepoAgents holds the agent definitions discovered under managed repos' + // .hive/agents/ that wait for an owner's approval (hivecommons/hive#18491). + // Nil (most tests, a hive without a GitHub client) reports the feature + // off on GET /api/agents/discovered and answers 503 on its mutations. + RepoAgents *repoagents.Discoverer // RescanReposFunc re-enumerates every watched repository's open issues // and pull requests against the forge, enriches PR CI status, applies the // duplicate-PR claim guard and republishes the dashboard status snapshot diff --git a/src/pkg/dashboard/import_count_test.go b/src/pkg/dashboard/import_count_test.go index 1bc80f097d..8ec2a3495a 100644 --- a/src/pkg/dashboard/import_count_test.go +++ b/src/pkg/dashboard/import_count_test.go @@ -75,8 +75,10 @@ func TestDashboardInternalImportCountRatchet(t *testing.T) { // sealed and opened through (hivecommons/hive#18214), plus pkg/mailallow, // the calendar email allowlist, and pkg/mailin (its stdlib-only wire // subpackage, the hive-mx delivery contract) behind the email-in routes - // (hivecommons/hive#18395). - const maxDashboardInternalImports = 64 + // (hivecommons/hive#18395), plus pkg/repoagents, the .hive/agents/ + // discoverer behind the /api/agents/discovered approval routes + // (hivecommons/hive#18491). + const maxDashboardInternalImports = 65 entries, err := os.ReadDir(".") if err != nil { diff --git a/src/pkg/dashboard/settings_parity_allowlist.txt b/src/pkg/dashboard/settings_parity_allowlist.txt index 356c1c2fd1..2329c6aa3b 100644 --- a/src/pkg/dashboard/settings_parity_allowlist.txt +++ b/src/pkg/dashboard/settings_parity_allowlist.txt @@ -63,6 +63,7 @@ agents..continuous_budget_pct # TODO #11854 agents..continuous_cooldown # TODO #11854 agents..continuous_turn_ceiling # TODO #11854 agents..converse # TODO #11854 +agents..definition_source.discovered # TODO #11854 agents..definition_source.owner # TODO #11854 agents..definition_source.path # TODO #11854 agents..definition_source.ref # TODO #11854 @@ -530,6 +531,7 @@ review.perspective_models..backend # TODO #13243 review.perspective_models..model # TODO #13243 review.perspective_prompts. # TODO #11854 review.perspectives[] # TODO #11854 +review.perspectives_source.discovered # TODO #17975 (shared DefinitionSourceConfig field; meaningful only on agents..definition_source) review.perspectives_source.owner # TODO #17975 review.perspectives_source.path # TODO #17975 review.perspectives_source.ref # TODO #17975 diff --git a/src/pkg/dashboard/static-src/js/config-tabs.js b/src/pkg/dashboard/static-src/js/config-tabs.js index adaa5b2159..12ef03a094 100644 --- a/src/pkg/dashboard/static-src/js/config-tabs.js +++ b/src/pkg/dashboard/static-src/js/config-tabs.js @@ -97,7 +97,9 @@ var quickStarts = AGENT_QUICK_START_TEMPLATES.map(function(t) { return ''; }).join(''); + setTimeout(loadDiscoveredAgents, 0); return '
' + + '
' + '
' + '
Start with a template, then tune it
' + '

Pick a common agent role to prefill the create form, or import/paste a full definition below.

' + @@ -130,6 +132,75 @@ var _pendingImportData = null; + // Agents a managed repo declares under .hive/agents/ (#18491). Nothing + // runs until an owner approves; backend, model, mode and tools stay + // owner-controlled, so Approve registers the agent with the defaults and + // the owner tunes them in the agent's settings afterwards. + var DISCOVERED_AGENT_STATUS_LABELS = {pending: 'Waiting for approval', invalid: 'Invalid definition', approved: 'Approved', rejected: 'Rejected', orphaned: 'File removed, agent paused'}; + + async function loadDiscoveredAgents() { + var box = document.getElementById('discovered-agents'); + if (!box) return; + try { + var resp = await fetch('/api/agents/discovered', {headers:_inceptionAuthHeaders()}); + var d = await resp.json(); + if (!resp.ok) { box.innerHTML = ''; return; } + renderDiscoveredAgents(box, d); + } catch(e) { box.innerHTML = ''; } + } + + function renderDiscoveredAgents(box, d) { + if (!d || !d.enabled) { box.innerHTML = ''; return; } + var entries = (d.entries || []).filter(function(e) { return e.status !== 'approved'; }); + var rows = entries.map(function(e) { + var title = (e.emoji ? esc(e.emoji) + ' ' : '') + esc(e.display_name || e.name || e.path); + var meta = esc(e.repo) + ' · ' + esc(e.path) + ' · ' + esc(DISCOVERED_AGENT_STATUS_LABELS[e.status] || e.status); + var detail = e.error ? '
' + esc(e.error) + '
' : (e.description ? '
' + esc(e.description) + '
' : ''); + var actions = ''; + if (e.status === 'pending') { + actions = ' ' + + ''; + } else if (e.status === 'invalid') { + actions = ''; + } + return '
' + meta + '
' + detail + (actions ? '
' + actions + '
' : '') + '
'; + }).join(''); + box.innerHTML = '
' + + '

Agent definitions found under .hive/agents/ in allowlisted managed repos. Approving registers the agent with a copilot backend; set its model, mode and tools in the agent settings.

' + + (rows || '

None waiting.

') + '
'; + } + + async function discoveredAgentAction(path, id, okMessage) { + try { + var resp = await fetch(path, {method:'POST', headers:_inceptionAuthHeaders(), body:JSON.stringify({id:id})}); + var d = await resp.json(); + if (!resp.ok) { showToast(d.error || 'Request failed', 'error'); return false; } + showToast(okMessage(d), 'success'); + return true; + } catch(e) { showToast('Error: ' + e.message, 'error'); return false; } + } + + async function approveDiscoveredAgent(id) { + var ok = await discoveredAgentAction('/api/agents/discovered/approve', id, function(d) { return 'Agent "' + (d.name || '?') + '" approved'; }); + if (!ok) return; + closeConfigDialog(); + fetch('/api/status').then(r => r.json()).then(render).catch(() => {}); + } + + async function rejectDiscoveredAgent(id) { + if (await discoveredAgentAction('/api/agents/discovered/reject', id, function() { return 'Definition rejected'; })) loadDiscoveredAgents(); + } + + async function refreshDiscoveredAgents() { + var box = document.getElementById('discovered-agents'); + try { + var resp = await fetch('/api/agents/discovered/refresh', {method:'POST', headers:_inceptionAuthHeaders()}); + var d = await resp.json(); + if (!resp.ok) { showToast(d.error || 'Rescan failed', 'error'); return; } + if (box) renderDiscoveredAgents(box, d); + } catch(e) { showToast('Error: ' + e.message, 'error'); } + } + function applyAgentQuickStart(templateID) { var t = AGENT_QUICK_START_TEMPLATES.find(function(x) { return x.id === templateID; }); if (!t || !_configState.isCreate) return; diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 98ef17edbd..05e4762216 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -61788,7 +61788,9 @@

Configure LiteLLM

var quickStarts = AGENT_QUICK_START_TEMPLATES.map(function(t) { return ''; }).join(''); + setTimeout(loadDiscoveredAgents, 0); return '
' + + '
' + '
' + '
Start with a template, then tune it
' + '

Pick a common agent role to prefill the create form, or import/paste a full definition below.

' + @@ -61821,6 +61823,75 @@

Configure LiteLLM

var _pendingImportData = null; + // Agents a managed repo declares under .hive/agents/ (#18491). Nothing + // runs until an owner approves; backend, model, mode and tools stay + // owner-controlled, so Approve registers the agent with the defaults and + // the owner tunes them in the agent's settings afterwards. + var DISCOVERED_AGENT_STATUS_LABELS = {pending: 'Waiting for approval', invalid: 'Invalid definition', approved: 'Approved', rejected: 'Rejected', orphaned: 'File removed, agent paused'}; + + async function loadDiscoveredAgents() { + var box = document.getElementById('discovered-agents'); + if (!box) return; + try { + var resp = await fetch('/api/agents/discovered', {headers:_inceptionAuthHeaders()}); + var d = await resp.json(); + if (!resp.ok) { box.innerHTML = ''; return; } + renderDiscoveredAgents(box, d); + } catch(e) { box.innerHTML = ''; } + } + + function renderDiscoveredAgents(box, d) { + if (!d || !d.enabled) { box.innerHTML = ''; return; } + var entries = (d.entries || []).filter(function(e) { return e.status !== 'approved'; }); + var rows = entries.map(function(e) { + var title = (e.emoji ? esc(e.emoji) + ' ' : '') + esc(e.display_name || e.name || e.path); + var meta = esc(e.repo) + ' · ' + esc(e.path) + ' · ' + esc(DISCOVERED_AGENT_STATUS_LABELS[e.status] || e.status); + var detail = e.error ? '
' + esc(e.error) + '
' : (e.description ? '
' + esc(e.description) + '
' : ''); + var actions = ''; + if (e.status === 'pending') { + actions = ' ' + + ''; + } else if (e.status === 'invalid') { + actions = ''; + } + return '
' + meta + '
' + detail + (actions ? '
' + actions + '
' : '') + '
'; + }).join(''); + box.innerHTML = '
' + + '

Agent definitions found under .hive/agents/ in allowlisted managed repos. Approving registers the agent with a copilot backend; set its model, mode and tools in the agent settings.

' + + (rows || '

None waiting.

') + '
'; + } + + async function discoveredAgentAction(path, id, okMessage) { + try { + var resp = await fetch(path, {method:'POST', headers:_inceptionAuthHeaders(), body:JSON.stringify({id:id})}); + var d = await resp.json(); + if (!resp.ok) { showToast(d.error || 'Request failed', 'error'); return false; } + showToast(okMessage(d), 'success'); + return true; + } catch(e) { showToast('Error: ' + e.message, 'error'); return false; } + } + + async function approveDiscoveredAgent(id) { + var ok = await discoveredAgentAction('/api/agents/discovered/approve', id, function(d) { return 'Agent "' + (d.name || '?') + '" approved'; }); + if (!ok) return; + closeConfigDialog(); + fetch('/api/status').then(r => r.json()).then(render).catch(() => {}); + } + + async function rejectDiscoveredAgent(id) { + if (await discoveredAgentAction('/api/agents/discovered/reject', id, function() { return 'Definition rejected'; })) loadDiscoveredAgents(); + } + + async function refreshDiscoveredAgents() { + var box = document.getElementById('discovered-agents'); + try { + var resp = await fetch('/api/agents/discovered/refresh', {method:'POST', headers:_inceptionAuthHeaders()}); + var d = await resp.json(); + if (!resp.ok) { showToast(d.error || 'Rescan failed', 'error'); return; } + if (box) renderDiscoveredAgents(box, d); + } catch(e) { showToast('Error: ' + e.message, 'error'); } + } + function applyAgentQuickStart(templateID) { var t = AGENT_QUICK_START_TEMPLATES.find(function(x) { return x.id === templateID; }); if (!t || !_configState.isCreate) return; diff --git a/src/pkg/defsrc/defsrc.go b/src/pkg/defsrc/defsrc.go index 889d17dc3e..0fe9b0eb8f 100644 --- a/src/pkg/defsrc/defsrc.go +++ b/src/pkg/defsrc/defsrc.go @@ -404,6 +404,20 @@ func MergeAllowedFields(baked config.AgentConfig, def *AgentDefinition) config.A return mergeAllowedFields(baked, def) } +// KeepOwnerControlledFields returns merged with the fields an owner keeps for +// an agent discovered in a repo's .hive/agents/ (hivecommons/hive#18491) copied +// back from owner: backend, model, mode and tools. A keep-linked import lets +// its definition set these; a discovered file was written by whoever can push +// to the repo, so it may describe the agent but never choose what runs it or +// what it may do. +func KeepOwnerControlledFields(merged, owner config.AgentConfig) config.AgentConfig { + merged.Backend = owner.Backend + merged.Model = owner.Model + merged.Mode = owner.Mode + merged.Tools = owner.Tools + return merged +} + // ApplyToConfig re-resolves every agent that carries a definition_source and // merges the live definition's operator-safe fields over the agent's baked // config in place. Agents without a definition_source are left untouched, and @@ -440,6 +454,9 @@ func ApplyToConfig(ctx context.Context, cfg *config.Config, resolver *Resolver, merged.DefinitionSource = agent.DefinitionSource merged.PromptSource = agent.PromptSource merged.Managed = agent.Managed + if agent.DefinitionSource.Discovered { + merged = KeepOwnerControlledFields(merged, agent) + } cfg.Agents[name] = merged if logger != nil { logger.Info("re-applied live agent definition", "agent", name, "source", res.Source) diff --git a/src/pkg/defsrc/discovered_test.go b/src/pkg/defsrc/discovered_test.go new file mode 100644 index 0000000000..58da5e70e2 --- /dev/null +++ b/src/pkg/defsrc/discovered_test.go @@ -0,0 +1,70 @@ +package defsrc + +import ( + "context" + "testing" + + "github.com/hivecommons/hive/pkg/config" +) + +// TestApplyToConfig_DiscoveredKeepsOwnerControlledFields: an agent approved +// from a repo's .hive/agents/ (hivecommons/hive#18491) re-applies its +// presentation from the repo, but backend, model, mode and tools stay what the +// owner set, even though the live definition names other values. +func TestApplyToConfig_DiscoveredKeepsOwnerControlledFields(t *testing.T) { + f := &stubFetcher{body: validDef + " tools:\n preset: full\n"} + r := NewResolver(f, allowAll, nil) + ownerTools := &config.ToolsConfig{Preset: "readonly"} + cfg := &config.Config{AgentRuntimeConfig: config.AgentRuntimeConfig{ + Agents: map[string]config.AgentConfig{ + "scanner": { + DisplayName: "Baked Scanner", + Backend: "copilot", + Model: "gpt-5", + Mode: "ADVISORY", + Tools: ownerTools, + DefinitionSource: &config.DefinitionSourceConfig{ + Owner: "hivecommons", Repo: "hive", Path: ".hive/agents/scanner.yaml", Discovered: true, + }, + }, + "linked": { + Backend: "copilot", + DefinitionSource: &config.DefinitionSourceConfig{Owner: "hivecommons", Repo: "hive", Path: "agents/linked.yaml"}, + }, + }, + }} + + ApplyToConfig(context.Background(), cfg, r, nil) + + sc := cfg.Agents["scanner"] + if sc.DisplayName != "Live Scanner" { + t.Errorf("presentation not re-applied: %q", sc.DisplayName) + } + if sc.Backend != "copilot" || sc.Model != "gpt-5" || sc.Mode != "ADVISORY" { + t.Errorf("owner-controlled fields changed: backend=%q model=%q mode=%q", sc.Backend, sc.Model, sc.Mode) + } + if sc.Tools != ownerTools { + t.Errorf("tools changed: %+v", sc.Tools) + } + if !sc.DefinitionSource.Discovered { + t.Error("discovered marker lost") + } + + // A keep-linked import is unchanged: its definition still sets backend. + if got := cfg.Agents["linked"].Backend; got != "claude" { + t.Errorf("keep-linked backend = %q, want claude from the definition", got) + } +} + +func TestKeepOwnerControlledFields(t *testing.T) { + tools := &config.ToolsConfig{Preset: "readonly"} + merged := config.AgentConfig{Backend: "claude", Model: "opus", Mode: "ISSUES_ONLY", DisplayName: "New"} + owner := config.AgentConfig{Backend: "copilot", Model: "gpt-5", Mode: "ADVISORY", Tools: tools, DisplayName: "Old"} + got := KeepOwnerControlledFields(merged, owner) + if got.Backend != "copilot" || got.Model != "gpt-5" || got.Mode != "ADVISORY" || got.Tools != tools { + t.Errorf("owner fields not kept: %+v", got) + } + if got.DisplayName != "New" { + t.Errorf("non-owner field overwritten: %q", got.DisplayName) + } +} diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index de6d901b2c..5a956bfbca 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -4466,6 +4466,39 @@ func (c *Client) GetFileContentRef(ctx context.Context, owner, repo, path, ref s return content, nil } +// ListDirectoryFiles returns the names of the regular files directly inside +// the directory at path in owner/repo at an optional git ref (an empty ref uses +// the default branch). Subdirectories, symlinks and submodules are skipped. A +// 404 means the directory does not exist and is reported as (nil, nil), so a +// caller can tell "no such directory" apart from a failed read. It backs the +// repo agent discovery scan of .hive/agents/ (hivecommons/hive#18491). +func (c *Client) ListDirectoryFiles(ctx context.Context, owner, repo, path, ref string) ([]string, error) { + if c == nil { + return nil, ErrNoGitHubClient + } + var opts *gh.RepositoryContentGetOptions + if ref != "" { + opts = &gh.RepositoryContentGetOptions{Ref: ref} + } + fileContent, dirContent, resp, err := c.client.Repositories.GetContents(ctx, owner, repo, path, opts) + if err != nil { + if resp != nil && resp.StatusCode == http.StatusNotFound { + return nil, nil + } + return nil, fmt.Errorf("listing %s/%s/%s: %w", owner, repo, path, err) + } + if fileContent != nil { + return nil, fmt.Errorf("%s/%s/%s is a file, not a directory", owner, repo, path) + } + names := make([]string, 0, len(dirContent)) + for _, entry := range dirContent { + if entry.GetType() == "file" && entry.GetName() != "" { + names = append(names, entry.GetName()) + } + } + return names, nil +} + // PathExistsAtRef reports whether path exists in owner/repo at the given git ref // (branch, tag, or commit SHA). It is used by the advisory digest to verify that // a finding's file reference still exists at the pinned analysis commit (#3704), diff --git a/src/pkg/github/list_directory_files_test.go b/src/pkg/github/list_directory_files_test.go new file mode 100644 index 0000000000..6a8f18966a --- /dev/null +++ b/src/pkg/github/list_directory_files_test.go @@ -0,0 +1,62 @@ +package github + +import ( + "context" + "net/http" + "net/http/httptest" + "reflect" + "strings" + "testing" +) + +func TestListDirectoryFiles(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch { + case strings.HasSuffix(r.URL.Path, "/contents/.hive/agents"): + if got := r.URL.Query().Get("ref"); got != "" && got != "main" { + t.Errorf("ref query = %q, want empty or main", got) + } + _, _ = w.Write([]byte(`[ + {"type":"file","name":"foo.yaml","path":".hive/agents/foo.yaml"}, + {"type":"dir","name":"nested","path":".hive/agents/nested"}, + {"type":"symlink","name":"link.yaml","path":".hive/agents/link.yaml"}, + {"type":"file","name":"foo.md","path":".hive/agents/foo.md"} + ]`)) + case strings.HasSuffix(r.URL.Path, "/contents/README.md"): + _, _ = w.Write([]byte(`{"type":"file","name":"README.md","path":"README.md"}`)) + case strings.HasSuffix(r.URL.Path, "/contents/missing"): + http.Error(w, `{"message":"Not Found"}`, http.StatusNotFound) + default: + http.Error(w, `{"message":"boom"}`, http.StatusInternalServerError) + } + })) + defer server.Close() + c := newTestClient(t, server, "hivecommons", []string{"hive"}) + ctx := context.Background() + + got, err := c.ListDirectoryFiles(ctx, "hivecommons", "hive", ".hive/agents", "") + if err != nil { + t.Fatalf("list: %v", err) + } + if want := []string{"foo.yaml", "foo.md"}; !reflect.DeepEqual(got, want) { + t.Errorf("files = %v, want %v (dirs and symlinks skipped)", got, want) + } + if _, err := c.ListDirectoryFiles(ctx, "hivecommons", "hive", ".hive/agents", "main"); err != nil { + t.Errorf("list at ref: %v", err) + } + + got, err = c.ListDirectoryFiles(ctx, "hivecommons", "hive", "missing", "") + if err != nil || got != nil { + t.Errorf("404: files=%v err=%v, want nil,nil", got, err) + } + if _, err := c.ListDirectoryFiles(ctx, "hivecommons", "hive", "README.md", ""); err == nil { + t.Error("file path: want error, got nil") + } + if _, err := c.ListDirectoryFiles(ctx, "hivecommons", "hive", "boom", ""); err == nil { + t.Error("500: want error, got nil") + } + var nilClient *Client + if _, err := nilClient.ListDirectoryFiles(ctx, "o", "r", "p", ""); err != ErrNoGitHubClient { + t.Errorf("nil client err = %v, want ErrNoGitHubClient", err) + } +} diff --git a/src/pkg/repoagents/repoagents.go b/src/pkg/repoagents/repoagents.go new file mode 100644 index 0000000000..6a6d6bee7a --- /dev/null +++ b/src/pkg/repoagents/repoagents.go @@ -0,0 +1,556 @@ +// Package repoagents discovers agents a managed repo declares under +// .hive/agents/*.yaml and holds them for an owner's approval +// (hivecommons/hive#18491). +// +// A discovered definition never runs on its own. The scan lists the directory +// in every managed repo that passes the repo-sourced prompt allowlist (the same +// seed-only gate definition_source and prompt_source use), parses each file as +// a portable AgentDefinition, and records it as pending. The dashboard shows +// pending entries; an owner's approval creates the agent with definition_source +// (and prompt_source, when a sibling .md exists) pointing at the file, so +// later edits re-apply through pkg/defsrc. Backend, model, mode and tools stay +// owner-controlled: see defsrc.KeepOwnerControlledFields. +// +// When an approved file disappears, the entry is marked orphaned and the agent +// is paused through OnOrphan, never deleted. A repo that drops off the +// allowlist is not scanned at all, so its entries are left exactly as they were. +package repoagents + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "log/slog" + "os" + "path" + "path/filepath" + "sort" + "strings" + "sync" + "time" + + "github.com/hivecommons/hive/pkg/defsrc" +) + +// AgentsDir is the repo directory scanned for agent definitions. +const AgentsDir = ".hive/agents" + +const ( + // DefaultInterval is how often every managed repo is rescanned when no + // interval is configured. Push webhooks rescan a repo sooner. + DefaultInterval = 15 * time.Minute + // MinInterval is the shortest accepted rescan interval, so a typo cannot + // turn the scan into a GitHub API hammer. + MinInterval = time.Minute + // maxFilesPerRepo bounds how many definition files one repo can enqueue. + maxFilesPerRepo = 50 + // scanTimeout bounds one repo's scan. + scanTimeout = 2 * time.Minute + // triggerBuffer is how many webhook-requested rescans may queue; more + // are dropped because the next timer pass covers them. + triggerBuffer = 16 + // pushCommitsCap is the most commits GitHub lists in a push payload; a + // push at the cap may hide changed paths, so it always rescans. + pushCommitsCap = 20 + // stateFileMode keeps the state file owner-readable only. + stateFileMode = 0o600 + stateDirMode = 0o700 +) + +// Status is where a discovered definition stands. +type Status string + +const ( + // StatusPending waits for an owner's approval. + StatusPending Status = "pending" + // StatusInvalid is a file that does not parse as an AgentDefinition. It + // cannot be approved until it is fixed. + StatusInvalid Status = "invalid" + // StatusApproved has a registered agent. + StatusApproved Status = "approved" + // StatusRejected was declined by an owner; it stays declined until the + // file is removed. + StatusRejected Status = "rejected" + // StatusOrphaned is an approved agent whose file was removed. The agent + // is paused, not deleted. + StatusOrphaned Status = "orphaned" +) + +// Entry is one discovered definition file. +type Entry struct { + ID string `json:"id"` + Repo string `json:"repo"` + Path string `json:"path"` + PromptPath string `json:"prompt_path,omitempty"` + Name string `json:"name"` + DisplayName string `json:"display_name,omitempty"` + Description string `json:"description,omitempty"` + Emoji string `json:"emoji,omitempty"` + Status Status `json:"status"` + Agent string `json:"agent,omitempty"` + Error string `json:"error,omitempty"` + FirstSeen time.Time `json:"first_seen"` + LastSeen time.Time `json:"last_seen"` + DecidedAt *time.Time `json:"decided_at,omitempty"` + DecidedBy string `json:"decided_by,omitempty"` + OrphanedAt *time.Time `json:"orphaned_at,omitempty"` +} + +// Owner is the owner half of Entry.Repo. +func (e Entry) Owner() string { + o, _, _ := strings.Cut(e.Repo, "/") + return o +} + +// RepoName is the repo half of Entry.Repo. +func (e Entry) RepoName() string { + _, r, _ := strings.Cut(e.Repo, "/") + return r +} + +// Client reads a repo's directory listing and file contents. It is satisfied +// by *github.Client, which reads through the hive's GitHub App token. +type Client interface { + ListDirectoryFiles(ctx context.Context, owner, repo, path, ref string) ([]string, error) + defsrc.Fetcher +} + +// Options configures a Discoverer. +type Options struct { + // Client may be nil (no GitHub client yet); every scan is then skipped. + Client Client + // Allow is the seed-only repo allowlist check; nil denies every repo. + Allow defsrc.AllowFunc + // Repos returns the managed repos as "owner/repo" slugs. + Repos func() []string + // StatePath is where entries persist; empty keeps them in memory only. + StatePath string + // OnOrphan is called, outside any lock, for each approved entry whose + // file was removed. It pauses the agent. + OnOrphan func(Entry) + Logger *slog.Logger + Now func() time.Time +} + +// Discoverer scans managed repos for agent definitions. Safe for concurrent use. +type Discoverer struct { + opts Options + // saveMu serializes state writes so the newest snapshot always lands last. + saveMu sync.Mutex + mu sync.Mutex + entries map[string]*Entry + trigger chan string +} + +// ErrNotFound is returned for an unknown entry id. +var ErrNotFound = errors.New("discovered agent not found") + +// New builds a Discoverer and loads any persisted entries. +func New(opts Options) *Discoverer { + if opts.Allow == nil { + opts.Allow = func(string) bool { return false } + } + if opts.Now == nil { + opts.Now = time.Now + } + if opts.Logger == nil { + opts.Logger = slog.New(slog.DiscardHandler) + } + d := &Discoverer{opts: opts, entries: map[string]*Entry{}, trigger: make(chan string, triggerBuffer)} + d.load() + return d +} + +// EntryID is the stable id of a definition file. +func EntryID(slug, filePath string) string { return slug + ":" + filePath } + +// RepoSlug qualifies a project.repos entry with org when it has no owner. +func RepoSlug(org, repo string) string { + repo = strings.TrimSpace(repo) + if repo == "" || strings.Contains(repo, "/") || org == "" { + return repo + } + return org + "/" + repo +} + +// AgentName is the agent key a definition name maps to, the same +// normalization the dashboard import uses. +func AgentName(defName string) string { + return strings.ToLower(strings.ReplaceAll(strings.TrimSpace(defName), " ", "-")) +} + +// List returns every entry, sorted by repo then path. +func (d *Discoverer) List() []Entry { + d.mu.Lock() + defer d.mu.Unlock() + out := make([]Entry, 0, len(d.entries)) + for _, e := range d.entries { + out = append(out, *e) + } + sort.Slice(out, func(i, j int) bool { + if out[i].Repo != out[j].Repo { + return out[i].Repo < out[j].Repo + } + return out[i].Path < out[j].Path + }) + return out +} + +// Get returns one entry. +func (d *Discoverer) Get(id string) (Entry, bool) { + d.mu.Lock() + defer d.mu.Unlock() + e, ok := d.entries[id] + if !ok { + return Entry{}, false + } + return *e, true +} + +// FetchDefinition re-reads and parses an entry's file through the allowlist +// gate, so approval registers what the repo holds now, not a stale copy. +func (d *Discoverer) FetchDefinition(ctx context.Context, id string) (*defsrc.AgentDefinition, Entry, error) { + e, ok := d.Get(id) + if !ok { + return nil, Entry{}, ErrNotFound + } + var fetcher defsrc.Fetcher + if d.opts.Client != nil { + fetcher = d.opts.Client + } + def, err := defsrc.FetchOnce(ctx, fetcher, d.opts.Allow, defsrc.Source{Owner: e.Owner(), Repo: e.RepoName(), Path: e.Path}) + return def, e, err +} + +// Approve records that an owner registered the entry as agent. +func (d *Discoverer) Approve(id, agent, by string) (Entry, error) { + return d.decide(id, by, func(e *Entry) error { + if e.Status != StatusPending { + return fmt.Errorf("only a pending definition can be approved (this one is %s)", e.Status) + } + e.Status = StatusApproved + e.Agent = agent + return nil + }) +} + +// Reject records that an owner declined the entry. +func (d *Discoverer) Reject(id, by string) (Entry, error) { + return d.decide(id, by, func(e *Entry) error { + if e.Status != StatusPending && e.Status != StatusInvalid { + return fmt.Errorf("only a pending definition can be rejected (this one is %s)", e.Status) + } + e.Status = StatusRejected + return nil + }) +} + +func (d *Discoverer) decide(id, by string, apply func(*Entry) error) (Entry, error) { + d.mu.Lock() + e, ok := d.entries[id] + if !ok { + d.mu.Unlock() + return Entry{}, ErrNotFound + } + if err := apply(e); err != nil { + d.mu.Unlock() + return Entry{}, err + } + now := d.opts.Now() + e.DecidedAt = &now + e.DecidedBy = by + out := *e + d.mu.Unlock() + d.save() + return out, nil +} + +// Trigger asks Run to rescan slug soon. It never blocks; a full queue drops +// the request because the next timer pass rescans every repo anyway. +func (d *Discoverer) Trigger(slug string) bool { + if slug == "" { + return false + } + select { + case d.trigger <- slug: + return true + default: + return false + } +} + +// Run scans every repo now and every interval after that, plus any repo a +// Trigger names, until ctx is done. +func (d *Discoverer) Run(ctx context.Context, interval time.Duration) { + if interval < MinInterval { + interval = MinInterval + } + d.ScanAll(ctx) + t := time.NewTicker(interval) + defer t.Stop() + for { + select { + case <-ctx.Done(): + return + case <-t.C: + d.ScanAll(ctx) + case slug := <-d.trigger: + if err := d.ScanRepo(ctx, slug); err != nil { + d.opts.Logger.Warn("repo agent discovery: rescan failed", "repo", slug, "error", err) + } + } + } +} + +// ScanAll scans every managed repo. A repo that fails is logged and skipped. +func (d *Discoverer) ScanAll(ctx context.Context) { + if d.opts.Repos == nil { + return + } + for _, slug := range d.opts.Repos() { + if ctx.Err() != nil { + return + } + if err := d.ScanRepo(ctx, slug); err != nil { + d.opts.Logger.Warn("repo agent discovery: scan failed", "repo", slug, "error", err) + } + } +} + +// ScanRepo lists slug's .hive/agents/ and reconciles its entries. A repo that +// is not allowlisted, or a scan without a client, is skipped without touching +// entries. A listing failure returns an error and also leaves entries alone, +// so a transient GitHub error never orphans an agent. +func (d *Discoverer) ScanRepo(ctx context.Context, slug string) error { + owner, repo, ok := strings.Cut(slug, "/") + if !ok || owner == "" || repo == "" { + return fmt.Errorf("repo %q is not owner/repo", slug) + } + if !d.opts.Allow(slug) || d.opts.Client == nil { + return nil + } + ctx, cancel := context.WithTimeout(ctx, scanTimeout) + defer cancel() + names, err := d.opts.Client.ListDirectoryFiles(ctx, owner, repo, AgentsDir, "") + if err != nil { + return err + } + prompts := map[string]bool{} + var defs []string + for _, n := range names { + switch strings.ToLower(path.Ext(n)) { + case ".yaml", ".yml": + defs = append(defs, n) + case ".md": + prompts[n] = true + } + } + sort.Strings(defs) + if len(defs) > maxFilesPerRepo { + d.opts.Logger.Warn("repo agent discovery: too many definitions, ignoring the rest", "repo", slug, "found", len(defs), "max", maxFilesPerRepo) + defs = defs[:maxFilesPerRepo] + } + + type scanned struct { + path, prompt string + def *defsrc.AgentDefinition + parseErr error + fetchErr error + } + results := make([]scanned, 0, len(defs)) + for _, n := range defs { + res := scanned{path: AgentsDir + "/" + n} + if p := strings.TrimSuffix(n, path.Ext(n)) + ".md"; prompts[p] { + res.prompt = AgentsDir + "/" + p + } + raw, ferr := d.opts.Client.GetFileContentRef(ctx, owner, repo, res.path, "") + if ferr != nil { + res.fetchErr = ferr + } else { + res.def, res.parseErr = defsrc.ParseDefinition(raw) + } + results = append(results, res) + } + + now := d.opts.Now() + var orphaned []Entry + d.mu.Lock() + seen := map[string]bool{} + for _, res := range results { + id := EntryID(slug, res.path) + seen[id] = true + e, exists := d.entries[id] + if !exists { + e = &Entry{ID: id, Repo: slug, Path: res.path, Status: StatusPending, FirstSeen: now} + d.entries[id] = e + } + e.LastSeen = now + e.PromptPath = res.prompt + if res.fetchErr != nil { + e.Error = "could not read file: " + res.fetchErr.Error() + if !exists { + e.Status = StatusInvalid + } + continue + } + applyDefinition(e, res.def, res.parseErr) + if e.Status == StatusOrphaned { + // The file came back. The agent stays paused until an owner + // resumes it; the entry tracks the file again. + e.Status = StatusApproved + e.OrphanedAt = nil + } + } + for id, e := range d.entries { + if e.Repo != slug || seen[id] { + continue + } + switch e.Status { + case StatusApproved: + e.Status = StatusOrphaned + at := now + e.OrphanedAt = &at + orphaned = append(orphaned, *e) + case StatusOrphaned: + // Already paused. + default: + delete(d.entries, id) + } + } + d.mu.Unlock() + d.save() + + for _, e := range orphaned { + d.opts.Logger.Info("repo agent discovery: definition removed, pausing agent", "repo", e.Repo, "path", e.Path, "agent", e.Agent) + if d.opts.OnOrphan != nil { + d.opts.OnOrphan(e) + } + } + return nil +} + +// applyDefinition copies a parsed definition's presentation onto e and moves +// it between pending and invalid. Decided entries keep their status. +func applyDefinition(e *Entry, def *defsrc.AgentDefinition, parseErr error) { + if parseErr != nil { + e.Error = parseErr.Error() + if e.Status == StatusPending { + e.Status = StatusInvalid + } + return + } + e.Error = "" + e.Name = AgentName(def.Metadata.Name) + e.DisplayName = def.Metadata.DisplayName + e.Description = def.Metadata.Description + e.Emoji = def.Metadata.Emoji + if e.Status == StatusInvalid { + e.Status = StatusPending + } +} + +// PushRescanRepo reports the repo a push delivery should rescan: a push to the +// repo's default branch that touched .hive/agents/ (or listed too many +// commits to tell). Any other push returns "". +func PushRescanRepo(payload []byte) string { + var p struct { + Ref string `json:"ref"` + Repository struct { + FullName string `json:"full_name"` + DefaultBranch string `json:"default_branch"` + } `json:"repository"` + Commits []struct { + Added []string `json:"added"` + Removed []string `json:"removed"` + Modified []string `json:"modified"` + } `json:"commits"` + } + if err := json.Unmarshal(payload, &p); err != nil { + return "" + } + slug := p.Repository.FullName + if slug == "" || p.Repository.DefaultBranch == "" || p.Ref != "refs/heads/"+p.Repository.DefaultBranch { + return "" + } + if len(p.Commits) == 0 || len(p.Commits) >= pushCommitsCap { + return slug + } + prefix := AgentsDir + "/" + for _, c := range p.Commits { + for _, list := range [][]string{c.Added, c.Removed, c.Modified} { + for _, f := range list { + if strings.HasPrefix(f, prefix) { + return slug + } + } + } + } + return "" +} + +type stateFile struct { + Entries []Entry `json:"entries"` +} + +func (d *Discoverer) snapshot() []Entry { + d.mu.Lock() + defer d.mu.Unlock() + out := make([]Entry, 0, len(d.entries)) + for _, e := range d.entries { + out = append(out, *e) + } + sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID }) + return out +} + +func (d *Discoverer) load() { + if d.opts.StatePath == "" { + return + } + data, err := os.ReadFile(d.opts.StatePath) + if err != nil { + if !errors.Is(err, os.ErrNotExist) { + d.opts.Logger.Warn("repo agent discovery: state unreadable, starting empty", "path", d.opts.StatePath, "error", err) + } + return + } + var st stateFile + if err := json.Unmarshal(data, &st); err != nil { + d.opts.Logger.Warn("repo agent discovery: state corrupt, starting empty", "path", d.opts.StatePath, "error", err) + return + } + for i := range st.Entries { + e := st.Entries[i] + if e.ID == "" { + continue + } + d.entries[e.ID] = &e + } +} + +func (d *Discoverer) save() { + if d.opts.StatePath == "" { + return + } + d.saveMu.Lock() + defer d.saveMu.Unlock() + if err := writeState(d.opts.StatePath, d.snapshot()); err != nil { + d.opts.Logger.Warn("repo agent discovery: state not saved", "path", d.opts.StatePath, "error", err) + } +} + +func writeState(statePath string, entries []Entry) error { + data, err := json.MarshalIndent(stateFile{Entries: entries}, "", " ") + if err != nil { + return err + } + if err := os.MkdirAll(filepath.Dir(statePath), stateDirMode); err != nil { + return err + } + tmp := statePath + ".tmp" + if err := os.WriteFile(tmp, data, stateFileMode); err != nil { + return err + } + return os.Rename(tmp, statePath) +} diff --git a/src/pkg/repoagents/repoagents_test.go b/src/pkg/repoagents/repoagents_test.go new file mode 100644 index 0000000000..7e76890877 --- /dev/null +++ b/src/pkg/repoagents/repoagents_test.go @@ -0,0 +1,471 @@ +package repoagents + +import ( + "context" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/hivecommons/hive/internal/testutil" +) + +type fakeClient struct { + mu sync.Mutex + files map[string]string // "owner/repo/path" -> content + listErr error + readErr map[string]error + lists int +} + +func newFakeClient() *fakeClient { + return &fakeClient{files: map[string]string{}, readErr: map[string]error{}} +} + +func (f *fakeClient) put(slug, p, content string) { + f.mu.Lock() + defer f.mu.Unlock() + f.files[slug+"/"+p] = content +} + +func (f *fakeClient) remove(slug, p string) { + f.mu.Lock() + defer f.mu.Unlock() + delete(f.files, slug+"/"+p) +} + +func (f *fakeClient) ListDirectoryFiles(_ context.Context, owner, repo, dir, _ string) ([]string, error) { + f.mu.Lock() + defer f.mu.Unlock() + f.lists++ + if f.listErr != nil { + return nil, f.listErr + } + prefix := owner + "/" + repo + "/" + dir + "/" + var out []string + for k := range f.files { + if rest, ok := strings.CutPrefix(k, prefix); ok && !strings.Contains(rest, "/") { + out = append(out, rest) + } + } + return out, nil +} + +func (f *fakeClient) GetFileContentRef(_ context.Context, owner, repo, p, _ string) (string, error) { + f.mu.Lock() + defer f.mu.Unlock() + key := owner + "/" + repo + "/" + p + if err := f.readErr[key]; err != nil { + return "", err + } + c, ok := f.files[key] + if !ok { + return "", fmt.Errorf("404 %s", key) + } + return c, nil +} + +func def(name string) string { + return "apiVersion: hive.kubestellar.io/v1\nkind: AgentDefinition\nmetadata:\n name: " + name + + "\n displayName: Foo Agent\n emoji: \"🦊\"\n description: does foo\nspec:\n backend: claude\n model: opus\n" +} + +const slug = "acme/widgets" + +func newTestDiscoverer(t *testing.T, c Client, allow func(string) bool) (*Discoverer, *[]Entry) { + t.Helper() + var orphaned []Entry + d := New(Options{ + Client: c, + Allow: allow, + Repos: func() []string { return []string{slug} }, + StatePath: filepath.Join(t.TempDir(), "state", "repo-agents.json"), + OnOrphan: func(e Entry) { orphaned = append(orphaned, e) }, + Now: func() time.Time { return time.Date(2026, 11, 16, 12, 0, 0, 0, time.UTC) }, + }) + return d, &orphaned +} + +func allowAll(string) bool { return true } + +// TestLifecycle walks the "done when" of #18491: a new file shows up pending, +// approval registers it, deletion pauses it (orphaned), and a returning file +// tracks again without un-pausing. +func TestLifecycle(t *testing.T) { + c := newFakeClient() + c.put(slug, ".hive/agents/foo.yaml", def("Foo Bot")) + c.put(slug, ".hive/agents/foo.md", "prompt") + c.put(slug, ".hive/agents/README.txt", "ignored") + d, orphaned := newTestDiscoverer(t, c, allowAll) + + d.ScanAll(context.Background()) + list := d.List() + if len(list) != 1 { + t.Fatalf("entries = %+v, want 1", list) + } + e := list[0] + if e.Status != StatusPending || e.Name != "foo-bot" || e.DisplayName != "Foo Agent" || e.Emoji != "🦊" || e.Description != "does foo" { + t.Fatalf("pending entry = %+v", e) + } + if e.ID != EntryID(slug, ".hive/agents/foo.yaml") || e.PromptPath != ".hive/agents/foo.md" { + t.Fatalf("id/prompt = %q / %q", e.ID, e.PromptPath) + } + if e.Owner() != "acme" || e.RepoName() != "widgets" { + t.Fatalf("owner/repo = %q/%q", e.Owner(), e.RepoName()) + } + + got, err := d.Approve(e.ID, "foo-bot", "owner1") + if err != nil || got.Status != StatusApproved || got.Agent != "foo-bot" || got.DecidedBy != "owner1" || got.DecidedAt == nil { + t.Fatalf("approve = %+v, %v", got, err) + } + if _, err := d.Approve(e.ID, "foo-bot", "owner1"); err == nil { + t.Fatal("second approve should fail") + } + + // Rescan with the file still there keeps it approved and does not orphan. + if err := d.ScanRepo(context.Background(), slug); err != nil { + t.Fatal(err) + } + if g, _ := d.Get(e.ID); g.Status != StatusApproved || len(*orphaned) != 0 { + t.Fatalf("after rescan: %+v orphaned=%d", g, len(*orphaned)) + } + + c.remove(slug, ".hive/agents/foo.yaml") + if err := d.ScanRepo(context.Background(), slug); err != nil { + t.Fatal(err) + } + g, _ := d.Get(e.ID) + if g.Status != StatusOrphaned || g.OrphanedAt == nil { + t.Fatalf("after delete: %+v", g) + } + if len(*orphaned) != 1 || (*orphaned)[0].Agent != "foo-bot" { + t.Fatalf("OnOrphan calls = %+v", *orphaned) + } + // A second scan does not pause again. + _ = d.ScanRepo(context.Background(), slug) + if len(*orphaned) != 1 { + t.Fatalf("orphan re-fired: %d", len(*orphaned)) + } + + c.put(slug, ".hive/agents/foo.yaml", def("Foo Bot")) + _ = d.ScanRepo(context.Background(), slug) + if g, _ := d.Get(e.ID); g.Status != StatusApproved || g.OrphanedAt != nil { + t.Fatalf("returned file: %+v", g) + } +} + +func TestPersistenceSurvivesRestart(t *testing.T) { + c := newFakeClient() + c.put(slug, ".hive/agents/foo.yaml", def("foo")) + statePath := filepath.Join(t.TempDir(), "repo-agents.json") + d := New(Options{Client: c, Allow: allowAll, StatePath: statePath}) + _ = d.ScanRepo(context.Background(), slug) + if _, err := d.Approve(EntryID(slug, ".hive/agents/foo.yaml"), "foo", "o"); err != nil { + t.Fatal(err) + } + info, err := os.Stat(statePath) + if err != nil { + t.Fatal(err) + } + if info.Mode().Perm() != stateFileMode { + t.Errorf("state mode = %v", info.Mode().Perm()) + } + d2 := New(Options{Client: c, Allow: allowAll, StatePath: statePath}) + if g, ok := d2.Get(EntryID(slug, ".hive/agents/foo.yaml")); !ok || g.Status != StatusApproved || g.Agent != "foo" { + t.Fatalf("reloaded = %+v ok=%v", g, ok) + } +} + +func TestLoadBadState(t *testing.T) { + dir := t.TempDir() + corrupt := filepath.Join(dir, "corrupt.json") + if err := os.WriteFile(corrupt, []byte("{not json"), 0o600); err != nil { + t.Fatal(err) + } + if got := New(Options{StatePath: corrupt}).List(); len(got) != 0 { + t.Fatalf("corrupt state should start empty: %+v", got) + } + noID := filepath.Join(dir, "noid.json") + if err := os.WriteFile(noID, []byte(`{"entries":[{"repo":"a/b"}]}`), 0o600); err != nil { + t.Fatal(err) + } + if got := New(Options{StatePath: noID}).List(); len(got) != 0 { + t.Fatalf("entry without id should be dropped: %+v", got) + } + // A directory where the file should be is unreadable as a file. + if got := New(Options{StatePath: dir}).List(); len(got) != 0 { + t.Fatalf("unreadable state should start empty: %+v", got) + } +} + +func TestSaveFailureIsLoggedNotFatal(t *testing.T) { + dir := t.TempDir() + blocker := filepath.Join(dir, "file") + if err := os.WriteFile(blocker, nil, 0o600); err != nil { + t.Fatal(err) + } + c := newFakeClient() + c.put(slug, ".hive/agents/foo.yaml", def("foo")) + // The parent of the state path is a regular file, so MkdirAll fails. + d := New(Options{Client: c, Allow: allowAll, StatePath: filepath.Join(blocker, "state.json")}) + if err := d.ScanRepo(context.Background(), slug); err != nil { + t.Fatal(err) + } + if len(d.List()) != 1 { + t.Fatal("entries must stay in memory when save fails") + } +} + +func TestInvalidAndRejected(t *testing.T) { + c := newFakeClient() + c.put(slug, ".hive/agents/bad.yml", "kind: Wrong\n") + c.put(slug, ".hive/agents/nope.yaml", def("nope")) + d, _ := newTestDiscoverer(t, c, allowAll) + _ = d.ScanRepo(context.Background(), slug) + + badID := EntryID(slug, ".hive/agents/bad.yml") + bad, _ := d.Get(badID) + if bad.Status != StatusInvalid || bad.Error == "" { + t.Fatalf("bad = %+v", bad) + } + if _, err := d.Approve(badID, "bad", "o"); err == nil { + t.Fatal("invalid entry must not be approvable") + } + // Fixing the file moves it back to pending. + c.put(slug, ".hive/agents/bad.yml", def("bad")) + _ = d.ScanRepo(context.Background(), slug) + if g, _ := d.Get(badID); g.Status != StatusPending || g.Error != "" { + t.Fatalf("fixed = %+v", g) + } + // Breaking it again returns to invalid. + c.put(slug, ".hive/agents/bad.yml", "::: nope") + _ = d.ScanRepo(context.Background(), slug) + if g, _ := d.Get(badID); g.Status != StatusInvalid { + t.Fatalf("rebroken = %+v", g) + } + + nopeID := EntryID(slug, ".hive/agents/nope.yaml") + if g, err := d.Reject(nopeID, "o"); err != nil || g.Status != StatusRejected { + t.Fatalf("reject = %+v %v", g, err) + } + if _, err := d.Reject(nopeID, "o"); err == nil { + t.Fatal("rejecting a rejected entry should fail") + } + _ = d.ScanRepo(context.Background(), slug) + if g, _ := d.Get(nopeID); g.Status != StatusRejected { + t.Fatalf("rejected must stay rejected while the file exists: %+v", g) + } + // Removing a rejected or pending file drops its entry; nothing is paused. + c.remove(slug, ".hive/agents/nope.yaml") + c.remove(slug, ".hive/agents/bad.yml") + _ = d.ScanRepo(context.Background(), slug) + if got := d.List(); len(got) != 0 { + t.Fatalf("entries after removal = %+v", got) + } + if _, err := d.Reject("missing", "o"); !errors.Is(err, ErrNotFound) { + t.Fatalf("unknown id err = %v", err) + } +} + +func TestReadErrors(t *testing.T) { + c := newFakeClient() + c.put(slug, ".hive/agents/foo.yaml", def("foo")) + key := slug + "/.hive/agents/foo.yaml" + c.readErr[key] = errors.New("rate limited") + d, orphaned := newTestDiscoverer(t, c, allowAll) + _ = d.ScanRepo(context.Background(), slug) + id := EntryID(slug, ".hive/agents/foo.yaml") + if g, _ := d.Get(id); g.Status != StatusInvalid || !strings.Contains(g.Error, "rate limited") { + t.Fatalf("unreadable new file = %+v", g) + } + + // An approved entry whose read fails keeps its status. + delete(c.readErr, key) + _ = d.ScanRepo(context.Background(), slug) + if _, err := d.Approve(id, "foo", "o"); err != nil { + t.Fatal(err) + } + c.readErr[key] = errors.New("flaky") + _ = d.ScanRepo(context.Background(), slug) + if g, _ := d.Get(id); g.Status != StatusApproved || g.Error == "" { + t.Fatalf("approved with read error = %+v", g) + } + + // A listing failure never orphans. + c.listErr = errors.New("502") + if err := d.ScanRepo(context.Background(), slug); err == nil { + t.Fatal("listing failure should return an error") + } + d.ScanAll(context.Background()) // logs and continues + if g, _ := d.Get(id); g.Status != StatusApproved || len(*orphaned) != 0 { + t.Fatalf("listing failure changed entry: %+v", g) + } +} + +func TestScanGates(t *testing.T) { + c := newFakeClient() + c.put(slug, ".hive/agents/foo.yaml", def("foo")) + + denied, _ := newTestDiscoverer(t, c, func(string) bool { return false }) + _ = denied.ScanRepo(context.Background(), slug) + if len(denied.List()) != 0 || c.lists != 0 { + t.Fatalf("non-allowlisted repo was read: entries=%d lists=%d", len(denied.List()), c.lists) + } + + nilAllow := New(Options{Client: c}) + _ = nilAllow.ScanRepo(context.Background(), slug) + if len(nilAllow.List()) != 0 { + t.Fatal("nil allow must deny") + } + + noClient := New(Options{Allow: allowAll}) + if err := noClient.ScanRepo(context.Background(), slug); err != nil || len(noClient.List()) != 0 { + t.Fatalf("no client: err=%v entries=%d", err, len(noClient.List())) + } + if _, _, err := noClient.FetchDefinition(context.Background(), "x"); !errors.Is(err, ErrNotFound) { + t.Fatalf("fetch unknown = %v", err) + } + + if err := noClient.ScanRepo(context.Background(), "no-slash"); err == nil { + t.Fatal("bad slug should error") + } + // ScanAll without Repos is a no-op. + noClient.ScanAll(context.Background()) +} + +func TestTooManyFiles(t *testing.T) { + c := newFakeClient() + for i := 0; i < maxFilesPerRepo+5; i++ { + c.put(slug, fmt.Sprintf(".hive/agents/a%03d.yaml", i), def(fmt.Sprintf("a%03d", i))) + } + d, _ := newTestDiscoverer(t, c, allowAll) + _ = d.ScanRepo(context.Background(), slug) + if got := len(d.List()); got != maxFilesPerRepo { + t.Fatalf("entries = %d, want %d", got, maxFilesPerRepo) + } +} + +func TestListSortsByRepoThenPath(t *testing.T) { + c := newFakeClient() + c.put("b/two", ".hive/agents/x.yaml", def("x")) + c.put("a/one", ".hive/agents/z.yaml", def("z")) + c.put("a/one", ".hive/agents/y.yaml", def("y")) + d := New(Options{Client: c, Allow: allowAll, Repos: func() []string { return []string{"b/two", "a/one"} }}) + d.ScanAll(context.Background()) + got := d.List() + if len(got) != 3 || got[0].Path != ".hive/agents/y.yaml" || got[1].Path != ".hive/agents/z.yaml" || got[2].Repo != "b/two" { + t.Fatalf("order = %+v", got) + } +} + +func TestFetchDefinition(t *testing.T) { + c := newFakeClient() + c.put(slug, ".hive/agents/foo.yaml", def("foo")) + d, _ := newTestDiscoverer(t, c, allowAll) + _ = d.ScanRepo(context.Background(), slug) + id := EntryID(slug, ".hive/agents/foo.yaml") + parsed, e, err := d.FetchDefinition(context.Background(), id) + if err != nil || parsed.Metadata.Name != "foo" || e.ID != id { + t.Fatalf("fetch = %+v %+v %v", parsed, e, err) + } + // The allowlist is checked again at fetch time. + locked := New(Options{Client: c, Allow: func(string) bool { return false }}) + locked.entries[id] = &Entry{ID: id, Repo: slug, Path: ".hive/agents/foo.yaml"} + if _, _, err := locked.FetchDefinition(context.Background(), id); err == nil { + t.Fatal("fetch from a de-allowlisted repo must fail") + } +} + +func TestRunScansAndTriggers(t *testing.T) { + c := newFakeClient() + c.put(slug, ".hive/agents/foo.yaml", def("foo")) + d, _ := newTestDiscoverer(t, c, allowAll) + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan struct{}) + go func() { d.Run(ctx, 0); close(done) }() + + waitFor(t, func() bool { return len(d.List()) == 1 }) + c.put(slug, ".hive/agents/bar.yaml", def("bar")) + if !d.Trigger(slug) { + t.Fatal("trigger dropped") + } + waitFor(t, func() bool { return len(d.List()) == 2 }) + // A failing triggered rescan is logged, not fatal. + c.mu.Lock() + c.listErr = errors.New("boom") + c.mu.Unlock() + d.Trigger(slug) + cancel() + <-done + if d.Trigger("") { + t.Fatal("empty slug must not queue") + } +} + +func TestTriggerDropsWhenFull(t *testing.T) { + d := New(Options{}) + for i := 0; i < triggerBuffer; i++ { + if !d.Trigger(slug) { + t.Fatalf("trigger %d dropped early", i) + } + } + if d.Trigger(slug) { + t.Fatal("full queue should drop") + } +} + +func waitFor(t *testing.T, cond func() bool) { + t.Helper() + const waitTimeout = 5 * time.Second + testutil.Eventually(t, waitTimeout, cond, "repo agent scan did not land") +} + +func TestPushRescanRepo(t *testing.T) { + many := strings.Repeat(`{"added":[],"removed":[],"modified":["x"]},`, pushCommitsCap) + many = "[" + strings.TrimSuffix(many, ",") + "]" + cases := []struct { + name, payload, want string + }{ + {"agents file changed", `{"ref":"refs/heads/main","repository":{"full_name":"acme/widgets","default_branch":"main"},"commits":[{"modified":["README.md"]},{"removed":[".hive/agents/foo.yaml"]}]}`, slug}, + {"added counts", `{"ref":"refs/heads/main","repository":{"full_name":"acme/widgets","default_branch":"main"},"commits":[{"added":[".hive/agents/new.yaml"]}]}`, slug}, + {"unrelated change", `{"ref":"refs/heads/main","repository":{"full_name":"acme/widgets","default_branch":"main"},"commits":[{"modified":["src/main.go"]}]}`, ""}, + {"other branch", `{"ref":"refs/heads/feature","repository":{"full_name":"acme/widgets","default_branch":"main"},"commits":[{"added":[".hive/agents/new.yaml"]}]}`, ""}, + {"no commits listed", `{"ref":"refs/heads/main","repository":{"full_name":"acme/widgets","default_branch":"main"},"commits":[]}`, slug}, + {"truncated commit list", `{"ref":"refs/heads/main","repository":{"full_name":"acme/widgets","default_branch":"main"},"commits":` + many + `}`, slug}, + {"no repo", `{"ref":"refs/heads/main","repository":{"default_branch":"main"}}`, ""}, + {"no default branch", `{"ref":"refs/heads/main","repository":{"full_name":"acme/widgets"}}`, ""}, + {"garbage", `not json`, ""}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := PushRescanRepo([]byte(tc.payload)); got != tc.want { + t.Errorf("got %q, want %q", got, tc.want) + } + }) + } +} + +func TestHelpers(t *testing.T) { + if got := RepoSlug("acme", "widgets"); got != slug { + t.Errorf("RepoSlug = %q", got) + } + if got := RepoSlug("acme", "other/widgets"); got != "other/widgets" { + t.Errorf("qualified RepoSlug = %q", got) + } + if got := RepoSlug("", "widgets"); got != "widgets" { + t.Errorf("no-org RepoSlug = %q", got) + } + if got := RepoSlug("acme", " "); got != "" { + t.Errorf("blank RepoSlug = %q", got) + } + if got := AgentName(" Foo Bot "); got != "foo-bot" { + t.Errorf("AgentName = %q", got) + } + if _, ok := New(Options{}).Get("nope"); ok { + t.Error("Get on empty should miss") + } +}