Skip to content

✨ Discover agents declared in a managed repo's .hive/agents/ behind owner approval - #18505

Merged
kubestellar-prow[bot] merged 6 commits into
v5from
feat/18491-repo-agent-discovery
Nov 17, 2026
Merged

kubestellar-prow[bot] merged 6 commits into
v5from
feat/18491-repo-agent-discovery

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Summary

A managed repo can now declare agents itself. Each .hive/agents/<name>.yaml on the default branch of a managed repo that passes the existing repo-sourced prompt allowlist (Config.GitHubDefinitionAllowed, which delegates to GitHubPromptAllowed) is discovered and held for owner approval. Nothing runs until an owner approves.

  • New pkg/repoagents: a discoverer that lists .hive/agents/ through the hive's GitHub App client (new github.Client.ListDirectoryFiles), parses each file with defsrc.ParseDefinition, and tracks entries as pending / invalid / approved / rejected / orphaned. State persists in /data/repo-agents.json (HIVE_REPO_AGENTS_STATE).
  • Refresh: runs at startup, every 15m (HIVE_REPO_AGENTS_INTERVAL), and on push webhooks to the default branch that touch .hive/agents/ (routed through the existing WebhookDelivery hook).
  • Approval (POST /api/agents/discovered/approve, owner only): re-reads the file through the allowlist gate and registers the agent with definition_source (new discovered: true marker) and, if a sibling <name>.md exists, prompt_source. Backend, model and mode come from the owner's request, never the file. Tools start unset. The import handler's registration tail is moved into a shared registerDefinedAgent helper so both paths create agents the same way.
  • Owner-controlled fields stay that way: defsrc.ApplyToConfig keeps backend, model, mode and tools for discovered sources (KeepOwnerControlledFields). Keep-linked imports are unchanged.
  • Removed file: an approved entry becomes orphaned and its agent is paused (PauseBy, trigger repo-agent-discovery), never deleted. A failed listing never orphans anything, and a repo off the allowlist is never read.
  • Dashboard: an "Declared in your repos" panel in the agent Import tab with Approve / Reject / Rescan. Also adds GET /api/agents/discovered, /reject and /refresh, plus openapi entries, the api-reference rows, docs in agent-configuration.md, and a changelog fragment.

Trust gate: this only calls the existing allowlist check, so the owner-allowlist work in #18490 applies here automatically once it lands.

Fixes #18491

Test plan

  • pkg/repoagents: lifecycle (pending, approve, orphan, re-add), invalid/rejected transitions, read/list failures, allowlist gate, persistence, push filter, Run/Trigger
  • pkg/dashboard: list/approve/reject/refresh handlers, including the owner-controlled fields, prompt_source wiring and every refusal path
  • pkg/defsrc: discovered sources keep backend/model/mode/tools on re-apply
  • pkg/github: ListDirectoryFiles
  • cmd/hive: wiring, orphan pause guard, push hook, interval env

🤖 Generated with Claude Code

@kubestellar-prow kubestellar-prow Bot added dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Nov 16, 2026
@hivecommons-hive

hivecommons-hive Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

  • relative links and anchors resolve

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

Review findings from adjudicator-2 (folded here because this head already carries its hive review):

Security delta re-review @ d38e09d (prior head 4f16836)

Prior findings

  • [security] src/pkg/dashboard/api_repo_agents.go:95 approval not pinned to reviewed content (TOCTOU): still present. handleDiscoveredAgentApprove still calls d.FetchDefinition (repoagents.go:213-224), which re-reads the file at approval time. Entry (repoagents.go:81-98) records no content hash or blob SHA, and the request body (api_repo_agents.go:67-73) carries none. An owner who reviews the queue entry, then has a repo writer push a changed file before the click, registers the new prompt_template/Name/description. The approval then pins nothing: DefinitionSource re-applies later edits anyway, but the first-approval review is meaningless for the content the owner actually saw.
  • [correctness] failed orphan pause never retried: still present. repoagents.go:409-414 flips Approved to Orphaned and calls OnOrphan once. If PauseBy fails (boot_repo_agents.go:84-85 only logs), the next scan hits case StatusOrphaned: // Already paused (repoagents.go:415-416), so the agent keeps running. For a security control this is a fail-open.
  • intent-alignment (agent_runtime.go) and style findings: not my perspective, not re-judged.

Requested fix (concrete)

  1. Add ContentSHA string to Entry, set in applyDefinition/scan from the fetched raw bytes (sha256). Have FetchDefinition return the hash of what it fetched.
  2. In the approve handler, require body.ContentSHA and reject on mismatch:
 	var body struct {
 		ID      string `json:"id"`
+		SHA     string `json:"content_sha"`
 ...
+	if body.SHA == "" || body.SHA != entry.ContentSHA {
+		jsonError(w, "definition changed since it was listed; refresh and review again", http.StatusConflict)
+		return
+	}
 	def, _, err := d.FetchDefinition(r.Context(), body.ID)
+	// and compare the fetched hash to entry.ContentSHA before registering
  1. For orphans: retry the pause while Status == StatusOrphaned and the agent is not yet paused (call OnOrphan for the already-orphaned case, which is idempotent via PauseBy), or only mark Orphaned after OnOrphan returns nil.

Limits of this review: the delta is 234 files / 15k lines, mostly main merged in (inference key resolver, sandbox relays, recordings, etc.). I reviewed only the repo-agent discovery files (repoagents.go, api_repo_agents.go, boot_repo_agents.go); the other merged areas were not examined for this perspective.

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review at head 4f16836. I read the diff plus pkg/defsrc/defsrc.go and cmd/hive/main.go. I found no in-scope blocker. The ApplyToConfig path is the only caller of mergeAllowedFields, and it now keeps the owner-controlled fields for discovered sources. agentMgr is set (main.go:1948) before wireRepoAgentDiscovery runs (main.go:3553). A 404 listing returns (nil, nil), so deleting the whole directory orphans entries, while any other listing error leaves them alone.

Advisory (low, in-scope): a failed orphan pause is never retried.
ScanRepo marks the entry StatusOrphaned and saves it (pkg/repoagents/repoagents.go, the case StatusApproved branch, then d.save()) before OnOrphan runs. On later scans an orphaned entry takes the case StatusOrphaned: // Already paused branch, so OnOrphan is not called again. pauseOrphanedRepoAgent (cmd/hive/boot_repo_agents.go) can return early without pausing. It does so when the agent's definition_source no longer matches, and it only logs when PauseBy fails. A crash between save() and OnOrphan has the same effect. In each case the agent keeps running although its file is gone and the entry shows "orphaned". Retrying OnOrphan on every scan would be wrong, because it would re-pause an agent the owner deliberately resumed. A small fix is to persist the pause outcome (for example a Paused bool on the entry), set only after OnOrphan reports success, and retry only while it is false.

hive/awaiting-ci: rebased onto v5 (one docs-citation conflict resolved to the base side); CI pending — sweep will merge when green.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: 983cfea65

— hive: agent=scanner backend=claude model=claude-sonnet-5-5 claude=2.1.325

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#18562 🐛 Dashboard: keep the Collaborate sidebar group and place it after Dashboard same files src/pkg/dashboard/static/index.html
#18536 ✨ feature: choose remote repository write identity same files dashboard/openapi.json
src/cmd/hive/main.go
src/docs/agent-configuration.md
src/pkg/dashboard/api.go
src/pkg/dashboard/deps.go
src/pkg/dashboard/static/index.html
#18507 ✨ governor: release-feed watcher kicks agents when a tracked upstream dependency releases CONFLICT src/cmd/hive/boot.go (conflict)
src/cmd/hive/main.go
src/docs/agent-configuration.md
src/pkg/dashboard/settings_parity_allowlist.txt

@clubanderson

Copy link
Copy Markdown
Member Author

cc @joerunde: this is part of the hive changes for the spyre-inference deps agent and sandboxed reviewer setup.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style review at 4f16836 (diff read in full for pkg/repoagents, dashboard/api_repo_agents.go, api_agents.go, boot_repo_agents.go). No in-scope blockers; two advisory notes:

  1. src/pkg/dashboard/api_agents.go:~400 — handleAgentImport still inlines strings.ToLower(strings.ReplaceAll(def.Metadata.Name, " ", "-")), while repoagents.AgentName (repoagents.go) is documented as "the same normalization the dashboard import uses". Two copies can drift. Since you already refactored this tail, reuse it:
	name := repoagents.AgentName(def.Metadata.Name)
  1. src/pkg/dashboard/api_repo_agents.go:16 — discoveredAgentModes hard-codes the mode set ("same set the agent config editor accepts"). I could not find the shared source from the diff; if the config package already exposes a validator, use it so a new mode doesn't need two edits. Also the "only a pending definition can be approved" message is duplicated in the handler and Discoverer.Approve.

— hive: agent=adjudicator-4 backend=claude model=claude-sonnet-5-5 claude=2.1.325

@hivecommons-hive

hivecommons-hive Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Review follow-ups (below review.backlog.min_severity: P2)

Non-blocking findings below the backlog filing line are listed here instead of as issues, one comment per PR, updated in place. Tick them off as they are fixed; set review.backlog.min_severity: P3 to file every finding.

  • P3 info intent-alignment — Unrelated comment rewrite in DefinitionSourceConfig (src/crux/config/agent_runtime.go:62): The Type and URL doc comments are reworded alongside the new Discovered field; this churn is unrelated to ✨ Discover agents declared in a managed repo's .hive/agents/ behind owner approval #18491 but harmless.
  • P3 info style — Hard-coded mode allowlist duplicates config editor set (src/pkg/dashboard/api_repo_agents.go:16): discoveredAgentModes copies the mode set; a shared validator would avoid two-place edits.

@github-actions github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 16, 2026
@hivecommons-hive
hivecommons-hive Bot force-pushed the feat/18491-repo-agent-discovery branch from 4f16836 to d38e09d Compare November 16, 2026 23:10
@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Mutation testing

⏱️ The 900s mutation budget ran out, so 2 package(s) were not fully mutated and the results below do not cover them:

  • pkg/github: cut short (partial, no report)
  • pkg/repoagents: skipped (not started)

1 mutant(s) in changed files are not reached by any test (NOT COVERED). A maintainer may apply the mutation/acknowledged label to accept this.

File Line Mutation
src/pkg/dashboard/api_agents.go 482 CONDITIONALS_NEGATION

ℹ️ 1 mutant(s) on added lines were SKIPPED because gremlins v0.6.0 only honours the first lines added lines of each default-context hunk, so non-contiguous edits in one hunk are partly missed. This does not affect the verdict.

File Line Mutation
src/pkg/dashboard/api_agents.go 474 CONDITIONALS_NEGATION

Verdict: uncovered (#17349).

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs-currency (delta 4f16836 → d38e09d)

Docs for #18491 are otherwise current: the agent-configuration section, the four API rows (the api_repo_agents.go:23-26 citations match the route lines), the changelog fragment and openapi are all present.

Finding (in-scope, low): the two new env vars are missing from src/docs/env-vars.md.

  • HIVE_REPO_AGENTS_INTERVAL and HIVE_REPO_AGENTS_STATE are defined at src/cmd/hive/boot_repo_agents.go:15-18. They are documented only in src/docs/agent-configuration.md and the changelog.
  • env-vars.md is the operator reference for every HIVE_* variable. It already lists sibling knobs such as HIVE_REFERENCE_REPOS_DERIVE_INTERVAL (line 129) and HIVE_WORKSPACE_CLEANUP_INTERVAL (line 130). grep REPO_AGENTS over the file at head returns nothing.
  • Fix: add two rows next to line 129:
+| `HIVE_REPO_AGENTS_INTERVAL` | No | `15m` | Go duration between rescans of each allowlisted managed repo's `.hive/agents/` (#18491). Values under `1m` are raised to `1m`. See [agent configuration](agent-configuration.md#agents-declared-in-a-managed-repo-hiveagents). |
+| `HIVE_REPO_AGENTS_STATE` | No | `/data/repo-agents.json` | Path where discovered-agent entries (pending/approved/orphaned…) persist. |

Previous findings:

  • Docs-currency: none open before, none new beyond the above.
  • I did not re-verify the correctness, intent-alignment, security and style findings, which are outside this perspective. I took no position on them.

— hive: agent=adjudicator-5 backend=claude model=claude-sonnet-5-5 claude=2.1.325

…wner approval

Scan every allowlisted managed repo's .hive/agents/*.yaml at startup, on a
timer and on default-branch pushes touching the directory. Each definition
appears as pending in the dashboard's Import tab; nothing runs until an
owner approves it. Approval registers the agent with definition_source
(marked discovered) and, with a sibling <name>.md, prompt_source. Backend,
model, mode and tools stay owner-controlled on every later re-apply. A
removed file pauses the agent (orphaned), never deletes it.

Fixes #18491

Signed-off-by: Andy Anderson <andy@clubanderson.com>
…tion

Signed-off-by: Andy Anderson <andy@clubanderson.com>
…h testutil.Eventually

Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy Anderson <andy@clubanderson.com>
…itation after rebase

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@clubanderson
clubanderson force-pushed the feat/18491-repo-agent-discovery branch from 983cfea to 0e515e0 Compare November 17, 2026 00:33
@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 17, 2026
@clubanderson clubanderson added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Nov 17, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow
kubestellar-prow Bot merged commit 4a7f228 into v5 Nov 17, 2026
98 of 100 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/18491-repo-agent-discovery branch November 17, 2026 00:54
joerunde pushed a commit to joerunde/spyre-inference that referenced this pull request Nov 17, 2026
Checks in the hive `deps` agent's prompt, definition and dependency
targets under `.hive/`, where hive's repo agent discovery looks for
them. The flow is unchanged: bump one dependency group, compile it, open
an issue if that fails, open one PR on success, fix our side when CI is
red, file dependency bugs upstream, recommend a refresh only when a
newer release may fix the bug, never run the test suite and never wait
for CI.

Hive features this now uses, all merged in hive v5:

- `hive-topic claim` from the sandbox, so each group keeps its one-PR
claim (hivecommons/hive#18586).
- `hive-open-issue` from the sandbox for dependency bugs (on
torch-spyre) and compile failures (here). This replaces the `known_bad`
ledger PR. `known_bad` stays in `targets.yaml` as a cap maintainers can
set by hand (hivecommons/hive#18586).
- Fix kicks on the agent's own red bump PR commit on top of it, and
sandbox PRs are credited to `deps`, so red CI kicks `deps` and not
`scanner` (hivecommons/hive#18587). PRs opened before that fix still get
the fix as a patch in the report.
- `${NEW_RELEASES}` from the release-feed watcher
(hivecommons/hive#18507).
- `.hive/agents/` discovery (hivecommons/hive#18505).

Files:

- `.hive/agents/deps.md`: the kick template (`prompt_source`).
- `.hive/agents/deps.yaml`: optional presentation-only definition.
- `.hive/deps/targets.yaml`: dependency groups. Only `deps-torch-spyre`
is enabled.
- `.gitignore`: keeps hive's per-run scratch under `.hive/` ignored and
tracks only `.hive/agents/` and `.hive/deps/`.

This overlaps torch-spyre#1626, which puts the prompt at
`.github/hive/prompts/deps.md` and ignores all of `.hive/`. Its prompt
content is merged into `.hive/agents/deps.md` here. If this lands first,
torch-spyre#1626 can drop its prompt and `.gitignore` hunks.

## Setup after merge (hive owner)

1. **Approve the prompt source.** Settings, Security, Prompt sources. On
the `torch-spyre/spyre-inference` row, click **Approve…** and confirm.
Leave `allow_github_prompt` and `github_prompt_allowlist` alone.
2. **Point the agent at the prompt.** Agents, `deps`, General tab,
**Prompt from GitHub repo**: Owner `torch-spyre`, Repo
`spyre-inference`, File path `.hive/agents/deps.md`, Ref `main`. Save.
Keep the current kick template as the cold-start fallback, and replace
its text with this file so the fallback runs the same flow.
3. **Variables tab** (static, template scope):
- `DEPS_LOCAL_CHECK`: `uv sync --frozen --inexact && uv run --no-sync
python -c 'import torch_spyre, spyre_inference;
print(torch_spyre.__version__)'`
   - `DEPS_MAX_REFRESHES`: `2`
   - `DEPS_UPSTREAM_REPO`: `torch-spyre/torch-spyre`
4. **Cadences tab.** idle, quiet and busy `24h`, surge `pause`.
5. **Optional, release-feed kicks** (YAML only, no Settings control
yet): `governor.release_feeds.agents.deps.sources: [{kind: github_tag,
repo: torch-spyre/torch-spyre}]`, with `cooldown_s: 21600`. Keep the
daily cadence for CI follow-up.
6. **Import tab.** `deps.yaml` will show under "Declared in your repos".
Leave it pending or reject it, because approving it would create a
second `deps` agent.
7. Unpause `deps`.

cc @joerunde

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Signed-off-by: Andy Anderson <andy@clubanderson.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. conflicts-with-open-pr Open PR has a merge conflict with another open PR dco-signoff: yes Indicates the PR's author has signed the DCO. lgtm Indicates that a PR is ready to be merged. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ Discover agents declared in a managed repo's .hive/agents/ behind owner approval

1 participant