Merge pull request #783 from samcharles93/feat/operator-pr-review

feat(gateway): operator-triggered PR review with selectable reviewer model
This commit is contained in:
sam authored and GitHub committed 2026-09-09 08:11:17 -07:00
commit 4f744624ec
18 files changed
+1084 -11

No files matched your search

+3
View File
@@ -87,6 +87,9 @@ parked = "archie:parked"
triage = "openai/gpt-5.4"
planner = "openai/gpt-5.4"
builder = "openai/gpt-5.4"
# `reviewer` runs the adversarial self-review stage and operator-triggered PR
# reviews. Omitted, it falls back to `builder`.
# reviewer = "openai/gpt-5.4"
# `embedding` is optional: it powers in-process embedding consumers
# (curators first). Unset, or a credential that fails to resolve, degrades
# to the capability reporting unavailable -- archied still starts.
+80
View File
@@ -0,0 +1,80 @@
# Operator-triggered PR review
Status: proposed (h019.8). Reuses the shipped adversarial-self-review contract
(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /
`workflow.ReviewReport` types from `internal/domain/workflow`. This PRD decides
only what is new: how an operator asks for a review of an *existing* PR, and
how that PR's content reaches the reviewer.
## Problem
The adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`
and reviews the task's own worktree HEAD. There is no way to review a PR that
already exists: one archie opened, a human opened, or one whose findings the
operator wants re-checked after a push.
## Shape
One channel-neutral command — `review_pr` — accepts a repository and PR number
and returns the structured `ReviewReport`. The Web UI chat and Telegram invoke
the same command; neither duplicates review behaviour. The reviewer model is
`models.reviewer` (falling back to `models.builder`), already the rule the
workflow stage uses, so an operator configures it independently of
planner/builder.
## Decisions
1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a
forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,
BaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,
implemented by GitHub and Gitea; the noop forge does not implement it, so
the daemon type-asserts and refuses review with "forge does not support PR
review". Adding to the fat `Forge` interface would churn every test fake for
a capability the noop forge cannot honestly provide.
2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,
baseRef)` clones the repository fully and checks out `origin/<headRef>`.
`Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:
`Diff` resolves `origin/<baseRef>` via the existing `resolveBase`, and
`Snapshot` strips `.git` exactly as the workflow stage does. The head must
already be pushed to the same repository — archie's own PRs always are; a
cross-repo or deleted head is refused with that reason, not half-reviewed.
3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`
builds the same `subagentReviewer` the stage uses, from daemon-level config
rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`
gate (the operator asked explicitly) and the task-run scaffolding.
4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the
channel's identity at construction — the model never names an identity,
matching `task_spawn`/`task_action`. The daemon supplies `ChatPRReviewer`,
a narrow gateway interface; the daemon adapter maps `workflow.ReviewReport`
into a gateway-owned result shape (gateway states what it needs, the daemon
adapts — the `ChatTaskActor` pattern).
5. **Authorization.** Identity-scoped repository allow-list, the
`task_spawn` rule: a chat identity may only review a repo in its
`TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard
operator who may review any configured repository.
6. **Determinism.** One review per (owner, repo, number) at a time: the daemon
holds an in-flight set; a concurrent request for the same PR returns
"review already in progress" rather than launching a second reviewer and
racing on the snapshot.
## Files
- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,
`PullRequestReader`, `GetPullRequest`.
- `internal/worktree/worktree.go` — `CheckoutPR`.
- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.
- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.
- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.
- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.
- `internal/app/archied/{bootstrap.go,main.go,telegram_setup.go}` — composition.
## Not in scope
- Surfacing findings on the PR body or the dashboard (h019.6).
- Reviewer model per-invocation override: configuration via `models.reviewer`
is the selection surface; a per-call override is a later knob.
+25 -5
View File
@@ -24,20 +24,40 @@ func newReviewerFor(req taskrun.Request) workflow.Reviewer {
if !req.Repo.ReviewEnabled {
return nil
}
modelRef := req.Cfg.Models["reviewer"]
if modelRef == "" {
modelRef = req.Cfg.Models["builder"]
}
return NewOperatorReviewer(req.Cfg.Models, req.Providers)
}
// NewOperatorReviewer builds the workflow.Reviewer for an operator-triggered
// review, resolved from daemon-level models and providers rather than a task
// run. It shares newReviewerFor's role->"builder" model fallback but drops
// the Repo.ReviewEnabled gate: the operator asked for the review explicitly,
// so "not opted in" is not a reason to refuse. It returns nil when no model
// resolves (no reviewer/builder model configured) or no provider runtime
// builds, so the caller can report a clear "review not configured" result.
func NewOperatorReviewer(models map[string]string, providers map[string]agentexec.Provider) workflow.Reviewer {
modelRef := ReviewerModel(models)
if modelRef == "" {
return nil
}
rt := agentexec.NewRuntime(req.Providers)
rt := agentexec.NewRuntime(providers)
if rt == nil {
return nil
}
return newSubagentReviewer(rt, modelRef)
}
// ReviewerModel resolves the reviewer role's model with the builder fallback.
// It is the single source of truth for the role->"builder" rule, shared by
// the workflow stage (via NewOperatorReviewer/newReviewerFor) and the
// operator-triggered review's result reporting so the reported model and the
// model actually run cannot diverge.
func ReviewerModel(models map[string]string) string {
if models["reviewer"] != "" {
return models["reviewer"]
}
return models["builder"]
}
// defaultReviewMaxSteps bounds the reviewer's tool loop when neither
// ReviewRequest.MaxSteps nor the repo's configured budget set one.
const defaultReviewMaxSteps = 10
+10 -5
View File
@@ -148,11 +148,15 @@ type boot struct {
// unrelated call.
embeddings domainembedding.Client
toolReg *tools.Registry
chatModels gateway.ModelManager
personas *gateway.PersonaRegistry
chatTasks gateway.TaskCreator
chatController *gateway.StoreTaskController
toolReg *tools.Registry
chatModels gateway.ModelManager
personas *gateway.PersonaRegistry
chatTasks gateway.TaskCreator
chatController *gateway.StoreTaskController
// chatPRReviewer is the operator-triggered PR review capability, built
// once and shared by every channel so a review in flight on one channel
// is deduplicated against the same request on another (single-flight).
chatPRReviewer gateway.ChatPRReviewer
defaultChatIdentity string
updateService *releaseupdate.Service
@@ -559,6 +563,7 @@ func (b *boot) setupGateways(ctx context.Context, cfgPath, overlayPath string) b
return nil
}(),
},
ChatPRReviewer: b.prReviewer(),
DefaultChatIdentity: b.defaultChatIdentity, SessionStore: b.chatSessionStore, Updates: b.updateService,
Secrets: b.secrets,
Bus: b.bus,
+2 -1
View File
@@ -64,7 +64,8 @@ func (b *boot) setupGatewayChat(ctx context.Context, actor gateway.ChatTaskActor
Personas: b.personas, ChatTasks: b.chatTasks, ChatController: b.chatController,
ChatTaskLister: chatTaskListerAdapter{tasks: b.stateStore.Tasks},
ChatTaskLogs: chatTaskLogReaderAdapter{tasks: b.stateStore.TaskByID, taskLogs: b.taskLogs},
ChatTaskActor: actor, DefaultChatIdentity: b.defaultChatIdentity, SessionStore: b.chatSessionStore,
ChatTaskActor: actor, ChatPRReviewer: b.prReviewer(),
DefaultChatIdentity: b.defaultChatIdentity, SessionStore: b.chatSessionStore,
Bus: b.bus, Log: b.log, Secrets: b.secrets,
}
router.LLM, router.LLMStream = makeChatLLMResponder(ctx, "web", setup, b.chatSessionStore, router)
+256
View File
@@ -0,0 +1,256 @@
package archied
import (
"context"
"fmt"
"log/slog"
"os"
"strconv"
"strings"
"sync"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/app/agentworker"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/worktree"
)
// prReviewer implements gateway.ChatPRReviewer for the daemon. It fetches
// an existing PR's metadata, materialises its head in a fresh clone, and runs
// the same adversarial reviewer the workflow stage uses, all synchronously in
// the requesting turn. Authorization is identity-scoped (the task_spawn
// repository allow-list) and one review per PR runs at a time.
type prReviewer struct {
forge forge.PullRequestReader // nil = forge cannot read PRs
trees *worktree.Manager
models map[string]string
providers map[string]agentexec.Provider
maxSteps int
// allowed maps a chat identity to the "owner/name" repos it may review.
// A nil identity is an authenticated dashboard operator, who may review
// any configured repository.
allowed map[string]map[string]bool
log *slog.Logger
mu sync.Mutex
inflight map[string]struct{}
}
var _ gateway.ChatPRReviewer = (*prReviewer)(nil)
// ReviewPR fetches the PR, runs the isolated reviewer against its head, and
// returns the structured findings. It never half-reviews: a missing forge
// capability, an unresolvable head/base, or an absent reviewer model returns
// an error rather than a fabricated result.
func (r *prReviewer) ReviewPR(ctx context.Context, identity *string, repo string, number int) (gateway.PRReviewResult, error) {
owner, name, err := splitOwnerRepo(repo)
if err != nil {
return gateway.PRReviewResult{}, err
}
if err := r.authorize(identity, owner, name); err != nil {
return gateway.PRReviewResult{}, err
}
key := owner + "/" + name + "#" + strconv.Itoa(number)
if !r.begin(key) {
return gateway.PRReviewResult{}, fmt.Errorf("review already in progress for %s", key)
}
defer r.end(key)
if r.forge == nil {
return gateway.PRReviewResult{}, fmt.Errorf("forge does not support pull request review")
}
pr, err := r.forge.GetPullRequest(ctx, owner, name, number)
if err != nil {
return gateway.PRReviewResult{}, err
}
model := agentworker.ReviewerModel(r.models)
if model == "" {
return gateway.PRReviewResult{}, fmt.Errorf("reviewer model is not configured (set models.reviewer, or models.builder as a fallback)")
}
reviewer := agentworker.NewOperatorReviewer(r.models, r.providers)
if reviewer == nil {
return gateway.PRReviewResult{}, fmt.Errorf("no provider runtime configured for the reviewer model %q", model)
}
if r.trees == nil {
return gateway.PRReviewResult{}, fmt.Errorf("worktree manager is not configured")
}
dir, cleanup, err := r.trees.CheckoutPR(ctx, owner, name, pr.HeadRef, pr.BaseRef)
if err != nil {
return gateway.PRReviewResult{}, err
}
defer cleanup()
diff, err := r.trees.Diff(ctx, dir, pr.BaseRef)
if err != nil {
return gateway.PRReviewResult{}, fmt.Errorf("compute PR diff: %w", err)
}
snapshotDir, err := os.MkdirTemp("", "pr-review-snapshot-*")
if err != nil {
return gateway.PRReviewResult{}, fmt.Errorf("create review snapshot directory: %w", err)
}
defer os.RemoveAll(snapshotDir)
if err := r.trees.Snapshot(ctx, dir, snapshotDir); err != nil {
return gateway.PRReviewResult{}, fmt.Errorf("snapshot PR head: %w", err)
}
report := reviewer.Review(ctx, workflow.ReviewRequest{
SnapshotDir: snapshotDir,
Diff: diff,
IssueText: prIssueText(pr),
MaxSteps: r.maxSteps,
})
r.logReview(key, model, report)
return mapReviewResult(repo, number, model, report), nil
}
// authorize enforces the identity-scoped repository allow-list. A nil
// identity (dashboard operator) may review any configured repository.
func (r *prReviewer) authorize(identity *string, owner, repo string) error {
full := owner + "/" + repo
if identity == nil {
for _, set := range r.allowed {
if set[full] {
return nil
}
}
return fmt.Errorf("repository %q is not configured", full)
}
set, ok := r.allowed[*identity]
if !ok {
return fmt.Errorf("identity %q is not configured for PR review", *identity)
}
if !set[full] {
return fmt.Errorf("repository %q is not configured for this identity", full)
}
return nil
}
func (r *prReviewer) begin(key string) bool {
r.mu.Lock()
defer r.mu.Unlock()
if r.inflight == nil {
r.inflight = make(map[string]struct{})
}
if _, ok := r.inflight[key]; ok {
return false
}
r.inflight[key] = struct{}{}
return true
}
func (r *prReviewer) end(key string) {
r.mu.Lock()
defer r.mu.Unlock()
delete(r.inflight, key)
}
func (r *prReviewer) logReview(key, model string, report workflow.ReviewReport) {
if r.log == nil {
return
}
blocking := 0
for _, f := range report.Findings {
if f.Blocking() {
blocking++
}
}
r.log.Info("operator PR review complete",
"pr", key, "model", model, "status", string(report.Status),
"findings", len(report.Findings), "blocking", blocking)
}
// splitOwnerRepo splits "owner/name" with the same validation the gateway's
// task_spawn allow-list uses.
func splitOwnerRepo(s string) (owner, repo string, err error) {
owner, repo, ok := strings.Cut(s, "/")
if !ok || owner == "" || repo == "" {
return "", "", fmt.Errorf("repository %q must be owner/name", s)
}
return owner, repo, nil
}
// prIssueText renders the PR title/body as the review's issue text.
func prIssueText(pr forge.PullRequest) string {
if pr.Body == "" {
return pr.Title
}
return pr.Title + "\n\n" + pr.Body
}
// mapReviewResult adapts a workflow.ReviewReport into the gateway's
// channel-neutral result shape.
func mapReviewResult(repo string, number int, model string, report workflow.ReviewReport) gateway.PRReviewResult {
out := gateway.PRReviewResult{
Repo: repo,
Number: number,
Model: model,
Status: string(report.Status),
Summary: report.Summary,
Reason: report.SkipReason,
Findings: make([]gateway.PRReviewFinding, 0, len(report.Findings)),
}
for _, f := range report.Findings {
out.Findings = append(out.Findings, gateway.PRReviewFinding{
File: f.File,
Line: f.Line,
Defect: f.Defect,
FailureScenario: f.FailureScenario,
Verdict: string(f.Verdict),
Level: string(f.Level),
Category: string(f.Category),
Blocking: f.Blocking(),
})
}
return out
}
// buildReviewAllowlist derives the identity-scoped review allow-list from the
// same profiles task_spawn uses, so a chat identity and the review command
// agree on which repositories the identity may touch.
func buildReviewAllowlist(cfg config.Config) map[string]map[string]bool {
profiles, _ := chatTaskProfiles(cfg)
out := make(map[string]map[string]bool, len(profiles))
for _, p := range profiles {
set := make(map[string]bool, len(p.Repos))
for _, repo := range p.Repos {
set[repo] = true
}
out[p.Identity] = set
}
return out
}
// prReviewer assembles the operator-triggered review capability, or nil when
// the forge cannot read PRs (the noop forge, or a forge with no PR read
// support). A review tool that can never run must not be advertised, matching
// the TaskTools nil-backend rule.
//
// The instance is built once and memoized on the boot struct so every channel
// shares one in-flight set: a review of the same PR requested concurrently
// from the Web UI and Telegram deduplicates instead of running twice.
func (b *boot) prReviewer() gateway.ChatPRReviewer {
if b.chatPRReviewer != nil {
return b.chatPRReviewer
}
forgeReader, _ := b.forgeClient.(forge.PullRequestReader)
if forgeReader == nil {
return nil
}
b.chatPRReviewer = &prReviewer{
forge: forgeReader,
trees: b.trees,
models: b.cfg.Models,
providers: executionProviders(b.cfg),
maxSteps: b.cfg.Budgets.MaxSteps,
allowed: buildReviewAllowlist(b.cfg),
log: b.log,
}
return b.chatPRReviewer
}
+190
View File
@@ -0,0 +1,190 @@
package archied
import (
"context"
"log/slog"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/forge"
)
func TestSplitOwnerRepo(t *testing.T) {
tests := []struct {
in string
owner string
repo string
wantErr bool
}{
{"acme/widget", "acme", "widget", false},
{"acme/widget/service", "acme", "widget/service", false},
{"acme", "", "", true},
{"/widget", "", "", true},
{"acme/", "", "", true},
{"", "", "", true},
}
for _, tt := range tests {
owner, repo, err := splitOwnerRepo(tt.in)
if tt.wantErr {
if err == nil {
t.Errorf("splitOwnerRepo(%q) error = nil, want error", tt.in)
}
continue
}
if err != nil {
t.Errorf("splitOwnerRepo(%q) error = %v", tt.in, err)
continue
}
if owner != tt.owner || repo != tt.repo {
t.Errorf("splitOwnerRepo(%q) = (%q, %q), want (%q, %q)", tt.in, owner, repo, tt.owner, tt.repo)
}
}
}
func TestPRIssueText(t *testing.T) {
tests := []struct {
name string
pr forge.PullRequest
want string
}{
{"title only", forge.PullRequest{Title: "Fix login"}, "Fix login"},
{"title and body", forge.PullRequest{Title: "Fix login", Body: "The form 500s."}, "Fix login\n\nThe form 500s."},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := prIssueText(tt.pr); got != tt.want {
t.Errorf("prIssueText = %q, want %q", got, tt.want)
}
})
}
}
func TestMapReviewResult(t *testing.T) {
report := workflow.ReviewReport{
Status: workflow.ReviewStatusCompleted,
Summary: "checked and cleared",
Findings: []workflow.ReviewFinding{
{File: "a.go", Line: 3, Defect: "nil deref", FailureScenario: "x", Verdict: workflow.ReviewVerdictConfirmed, Level: workflow.ReviewLevelError, Category: workflow.ReviewCategoryNilRisk},
{File: "b.go", Line: 0, Defect: "style", FailureScenario: "y", Verdict: workflow.ReviewVerdictPlausible, Level: workflow.ReviewLevelWarn, Category: workflow.ReviewCategoryOther},
},
}
got := mapReviewResult("acme/widget", 7, "openai/gpt-5", report)
if got.Repo != "acme/widget" || got.Number != 7 || got.Model != "openai/gpt-5" || got.Status != "completed" || got.Summary != "checked and cleared" {
t.Fatalf("result meta = %+v", got)
}
if len(got.Findings) != 2 {
t.Fatalf("findings = %d, want 2", len(got.Findings))
}
if !got.Findings[0].Blocking {
t.Error("confirmed error finding should be blocking")
}
if got.Findings[1].Blocking {
t.Error("plausible warn finding must not be blocking")
}
if got.Findings[0].Line != 3 {
t.Errorf("line = %d, want 3", got.Findings[0].Line)
}
}
func TestMapReviewResultNotRunPreservesReason(t *testing.T) {
report := workflow.NewNotRunReviewReport("no reviewer model configured")
got := mapReviewResult("acme/widget", 7, "", report)
if got.Status != "not_run" || got.Reason != "no reviewer model configured" {
t.Fatalf("not_run result = %+v, want status not_run and reason preserved", got)
}
}
func TestPrReviewerAuthorize(t *testing.T) {
r := &prReviewer{allowed: map[string]map[string]bool{
"": {"acme/widget": true, "acme/core": true},
"archie": {"acme/widget": true},
}}
archie := "archie"
other := "other"
tests := []struct {
name string
identity *string
owner string
repo string
wantErr bool
}{
{"identity own repo", &archie, "acme", "widget", false},
{"identity foreign repo", &archie, "acme", "core", true},
{"unknown identity", &other, "acme", "widget", true},
{"operator any configured", nil, "acme", "core", false},
{"operator unconfigured repo", nil, "acme", "other", true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := r.authorize(tt.identity, tt.owner, tt.repo)
if tt.wantErr && err == nil {
t.Errorf("authorize(%v, %s/%s) error = nil, want error", tt.identity, tt.owner, tt.repo)
}
if !tt.wantErr && err != nil {
t.Errorf("authorize(%v, %s/%s) error = %v, want nil", tt.identity, tt.owner, tt.repo, err)
}
})
}
}
func TestPrReviewerSingleflight(t *testing.T) {
r := &prReviewer{}
key := "acme/widget#7"
if !r.begin(key) {
t.Fatal("first begin = false, want true")
}
if r.begin(key) {
t.Fatal("concurrent begin = true, want false (deterministic single-flight)")
}
r.end(key)
if !r.begin(key) {
t.Fatal("begin after end = false, want true")
}
}
func TestBuildReviewAllowlist(t *testing.T) {
cfg := config.Config{
Identities: []config.IdentityConfig{
{Name: "archie", Repos: []config.Repo{{Owner: "acme", Name: "widget"}}},
},
}
allowed := buildReviewAllowlist(cfg)
if !allowed["archie"]["acme/widget"] {
t.Errorf("allowlist missing acme/widget for identity archie: %+v", allowed)
}
if allowed["archie"]["acme/core"] {
t.Errorf("allowlist leaked acme/core to identity archie: %+v", allowed)
}
if _, ok := allowed["nobody"]; ok {
t.Errorf("allowlist contains unknown identity nobody: %+v", allowed)
}
}
// reviewCapableForge satisfies both forge.Forge (via embedding) and
// forge.PullRequestReader, so boot.prReviewer can be exercised in isolation.
type reviewCapableForge struct {
forge.Forge
}
func (reviewCapableForge) GetPullRequest(context.Context, string, string, int) (forge.PullRequest, error) {
return forge.PullRequest{}, nil
}
// TestPrReviewerIsMemoized pins the cross-channel single-flight fix: every
// gateway must share one prReviewer so a review of the same PR requested from
// two channels at once deduplicates instead of running twice.
func TestPrReviewerIsMemoized(t *testing.T) {
b := &boot{forgeClient: reviewCapableForge{Forge: forge.NewNoop(slog.New(slog.DiscardHandler))}}
first := b.prReviewer()
if first == nil {
t.Fatal("prReviewer() = nil, want a reviewer")
}
if second := b.prReviewer(); first != second {
t.Fatal("prReviewer() returned distinct instances; channels would not share the in-flight set")
}
}
+2
View File
@@ -48,6 +48,7 @@ type telegramSetup struct {
ChatTaskLister gateway.ChatTaskLister
ChatTaskLogs gateway.ChatTaskLogReader
ChatTaskActor gateway.ChatTaskActor
ChatPRReviewer gateway.ChatPRReviewer
DefaultChatIdentity string
SessionStore gateway.SessionStore
Updates telegram.UpdateService
@@ -331,6 +332,7 @@ func newChatTurnRunner(
TaskLogs: s.ChatTaskLogs,
TaskActor: s.ChatTaskActor,
TaskIdentity: s.DefaultChatIdentity,
PRReviewer: s.ChatPRReviewer,
Bus: s.Bus,
BotUser: cfg.BotUser,
Channel: channel,
+22
View File
@@ -79,6 +79,28 @@ type PullRequestForge interface {
PRState(ctx context.Context, owner, repo string, number int) (string, error)
}
// PullRequest is a forge-neutral summary of an existing pull request,
// carrying the inputs the operator-triggered reviewer needs: its identity,
// head/base refs and SHAs, and the title/body that serve as the review's
// issue text.
type PullRequest struct {
Number int
Title string
Body string
HeadRef string
BaseRef string
HeadSHA string
BaseSHA string
State string // "open", "merged", or "closed"
}
// PullRequestReader fetches an existing pull request's metadata. Forge
// implementations that cannot read PRs (the noop forge) do not implement it;
// callers type-assert and refuse review when the capability is absent.
type PullRequestReader interface {
GetPullRequest(ctx context.Context, owner, repo string, number int) (PullRequest, error)
}
// RepoForge is repository-level operations.
type RepoForge interface {
// AcceptInvitations auto-accepts pending repository invitations.
+27
View File
@@ -163,6 +163,33 @@ func (c *GiteaClient) PRState(ctx context.Context, owner, repo string, number in
return string(pr.State), nil
}
// GetPullRequest returns the forge-neutral metadata for an existing PR.
func (c *GiteaClient) GetPullRequest(ctx context.Context, owner, repo string, number int) (PullRequest, error) {
pr, _, err := c.cli.GetPullRequest(owner, repo, int64(number))
if err != nil {
return PullRequest{}, fmt.Errorf("get pull request %s/%s#%d: %w", owner, repo, number, err)
}
// A merged/closed PR whose head branch was deleted returns nil head/base
// from Gitea; dereferencing it would panic.
if pr.Head == nil || pr.Base == nil {
return PullRequest{}, fmt.Errorf("pull request %s/%s#%d has a missing head or base ref", owner, repo, number)
}
state := string(pr.State)
if pr.HasMerged {
state = "merged"
}
return PullRequest{
Number: int(pr.Index),
Title: pr.Title,
Body: pr.Body,
HeadRef: pr.Head.Ref,
BaseRef: pr.Base.Ref,
HeadSHA: pr.Head.Sha,
BaseSHA: pr.Base.Sha,
State: state,
}, nil
}
// CloseIssue closes an issue with an optional final comment.
func (c *GiteaClient) CloseIssue(ctx context.Context, owner, repo string, number int, comment string) error {
if comment != "" {
+36
View File
@@ -156,6 +156,42 @@ func TestGiteaPRState(t *testing.T) {
}
}
func TestGiteaGetPullRequest(t *testing.T) {
c, mux := newTestGiteaClient(t)
mux.HandleFunc("GET /api/v1/repos/o/r/pulls/7", func(w http.ResponseWriter, r *http.Request) {
writeJSON(t, w, map[string]any{
"number": 7, "title": "Add widget", "body": "Why",
"state": "open", "merged": false,
"head": map[string]any{"ref": "feature/widget", "sha": "headsha"},
"base": map[string]any{"ref": "main", "sha": "basesha"},
})
})
pr, err := c.GetPullRequest(t.Context(), "o", "r", 7)
if err != nil {
t.Fatal(err)
}
want := PullRequest{Number: 7, Title: "Add widget", Body: "Why", HeadRef: "feature/widget", BaseRef: "main", HeadSHA: "headsha", BaseSHA: "basesha", State: "open"}
if pr != want {
t.Fatalf("GetPullRequest = %+v, want %+v", pr, want)
}
}
func TestGiteaGetPullRequestMissingHeadDoesNotPanic(t *testing.T) {
c, mux := newTestGiteaClient(t)
// Gitea returns head: null when a PR's head branch was deleted.
mux.HandleFunc("GET /api/v1/repos/o/r/pulls/7", func(w http.ResponseWriter, r *http.Request) {
writeJSON(t, w, map[string]any{
"number": 7, "title": "Add widget", "state": "closed", "merged": true,
"head": nil, "base": nil,
})
})
if _, err := c.GetPullRequest(t.Context(), "o", "r", 7); err == nil {
t.Fatal("GetPullRequest error = nil, want a missing-head/base error rather than a panic")
}
}
func TestGiteaCloseIssueWithComment(t *testing.T) {
c, mux := newTestGiteaClient(t)
var commented, closed bool
+22
View File
@@ -192,6 +192,28 @@ func (c *GitHubClient) PRState(ctx context.Context, owner, repo string, number i
return pr.GetState(), nil
}
// GetPullRequest returns the forge-neutral metadata for an existing PR.
func (c *GitHubClient) GetPullRequest(ctx context.Context, owner, repo string, number int) (PullRequest, error) {
pr, _, err := c.gh.PullRequests.Get(ctx, owner, repo, number)
if err != nil {
return PullRequest{}, fmt.Errorf("get pull request %s/%s#%d: %w", owner, repo, number, err)
}
state := pr.GetState()
if pr.GetMerged() {
state = "merged"
}
return PullRequest{
Number: pr.GetNumber(),
Title: pr.GetTitle(),
Body: pr.GetBody(),
HeadRef: pr.GetHead().GetRef(),
BaseRef: pr.GetBase().GetRef(),
HeadSHA: pr.GetHead().GetSHA(),
BaseSHA: pr.GetBase().GetSHA(),
State: state,
}, nil
}
// CloseIssue closes an issue with a final comment (feasibility "won't do").
func (c *GitHubClient) CloseIssue(ctx context.Context, owner, repo string, number int, comment string) error {
if comment != "" {
+44
View File
@@ -129,6 +129,50 @@ func TestPRState(t *testing.T) {
}
}
func TestGetPullRequest(t *testing.T) {
tests := []struct {
name string
json map[string]any
want PullRequest
}{
{
name: "open",
json: map[string]any{
"number": 7, "title": "Add widget", "body": "Why this matters",
"state": "open", "merged": false,
"head": map[string]any{"ref": "feature/widget", "sha": "headsha"},
"base": map[string]any{"ref": "main", "sha": "basesha"},
},
want: PullRequest{Number: 7, Title: "Add widget", Body: "Why this matters", HeadRef: "feature/widget", BaseRef: "main", HeadSHA: "headsha", BaseSHA: "basesha", State: "open"},
},
{
name: "merged",
json: map[string]any{
"number": 7, "title": "Add widget", "body": "",
"state": "closed", "merged": true,
"head": map[string]any{"ref": "feature/widget", "sha": "headsha"},
"base": map[string]any{"ref": "main", "sha": "basesha"},
},
want: PullRequest{Number: 7, Title: "Add widget", HeadRef: "feature/widget", BaseRef: "main", HeadSHA: "headsha", BaseSHA: "basesha", State: "merged"},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
c, mux := newTestClient(t)
mux.HandleFunc("GET /repos/o/r/pulls/7", func(w http.ResponseWriter, r *http.Request) {
writeJSON(t, w, tt.json)
})
got, err := c.GetPullRequest(t.Context(), "o", "r", 7)
if err != nil {
t.Fatal(err)
}
if got != tt.want {
t.Fatalf("GetPullRequest = %+v, want %+v", got, tt.want)
}
})
}
}
func TestCloseIssueWithComment(t *testing.T) {
c, mux := newTestClient(t)
var commented, edited bool
+102
View File
@@ -0,0 +1,102 @@
package gateway
import (
"context"
"fmt"
"strings"
"github.com/samcharles93/archie-core/internal/tools"
)
// PRReviewResult is the structured outcome of an operator-triggered PR
// review, returned to the channel that requested it. It mirrors
// workflow.ReviewReport without importing the domain package: the gateway
// states what it needs and the daemon adapts between the two (the
// ChatTaskActor pattern). Status is "completed", "not_run", or "skipped";
// a zero-finding "completed" result is a review that ran and cleared, and
// is structurally distinct from "not_run".
type PRReviewResult struct {
Repo string `json:"repo"`
Number int `json:"number"`
Model string `json:"model,omitempty"`
Status string `json:"status"`
Summary string `json:"summary,omitempty"`
// Reason explains why a not_run/skipped review did not execute.
Reason string `json:"reason,omitempty"`
Findings []PRReviewFinding `json:"findings"`
}
// PRReviewFinding is one defect from an operator-triggered review.
type PRReviewFinding struct {
File string `json:"file"`
Line int `json:"line"`
Defect string `json:"defect"`
FailureScenario string `json:"failure_scenario,omitempty"`
Verdict string `json:"verdict"`
Level string `json:"level"`
Category string `json:"category,omitempty"`
Blocking bool `json:"blocking"`
}
// ChatPRReviewer is the surface review_pr needs. The gateway states what it
// needs and the daemon supplies an adapter over the forge, worktree manager
// and reviewer runtime, so this package keeps its independence from
// internal/forge, internal/worktree and internal/domain/workflow.
//
// identity follows the ChatTaskActor convention: nil denotes an
// authenticated dashboard operator who may review any configured
// repository; a non-nil identity is a chat identity scoped to its own
// configured repositories.
type ChatPRReviewer interface {
ReviewPR(ctx context.Context, identity *string, repo string, number int) (PRReviewResult, error)
}
// ReviewTools builds the review_pr chat tool. A nil reviewer omits the tool
// rather than registering one that always fails, so a daemon without
// operator review support advertises nothing.
func ReviewTools(reviewer ChatPRReviewer, identity string) []tools.ToolEntry {
if reviewer == nil {
return nil
}
return []tools.ToolEntry{reviewPRTool(reviewer, identity)}
}
func reviewPRTool(reviewer ChatPRReviewer, identity string) tools.ToolEntry {
return tools.ToolEntry{
Name: "review_pr",
Toolset: "tasks",
Description: "Run the adversarial reviewer against an existing pull request and return its structured findings. " +
"Use it when the user asks to review a PR, re-check one after a push, or see what the reviewer found. " +
"Only a confirmed error-level finding blocks; a clean result reports zero findings explicitly.",
Classification: tools.ClassMutating,
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"repo": map[string]any{
"type": "string",
"description": "Repository of the PR as \"owner/name\". Must be a repository this identity is configured for.",
},
"pr_number": map[string]any{
"type": "integer",
"description": "Pull request number to review.",
},
},
"required": []any{"repo", "pr_number"},
},
Handler: func(ctx context.Context, input map[string]any) (any, error) {
repo := strings.TrimSpace(asString(input["repo"]))
if repo == "" {
return nil, fmt.Errorf("review_pr: repo is required")
}
number, ok := asInt64(input["pr_number"])
if !ok || number <= 0 {
return nil, fmt.Errorf("review_pr: pr_number must be a positive integer")
}
result, err := reviewer.ReviewPR(ctx, &identity, repo, int(number))
if err != nil {
return nil, fmt.Errorf("review_pr: %w", err)
}
return result, nil
},
}
}
+105
View File
@@ -0,0 +1,105 @@
package gateway
import (
"context"
"errors"
"testing"
)
type fakePRReviewer struct {
gotIdentity *string
gotRepo string
gotNumber int
result PRReviewResult
err error
}
func (f *fakePRReviewer) ReviewPR(_ context.Context, identity *string, repo string, number int) (PRReviewResult, error) {
f.gotIdentity = identity
f.gotRepo = repo
f.gotNumber = number
return f.result, f.err
}
func TestReviewToolOmittedWhenReviewerNil(t *testing.T) {
if entries := ReviewTools(nil, "archie"); len(entries) != 0 {
t.Fatalf("ReviewTools(nil) = %d entries, want 0 -- a tool that cannot run must not be advertised", len(entries))
}
}
func TestReviewToolAppearsWhenReviewerNonNil(t *testing.T) {
entries := ReviewTools(&fakePRReviewer{}, "archie")
if len(entries) != 1 {
t.Fatalf("ReviewTools() = %d entries, want 1", len(entries))
}
if err := entries[0].Validate(); err != nil {
t.Fatalf("entry.Validate() = %v", err)
}
}
func TestReviewPRToolBindsIdentityAndReturnsFindings(t *testing.T) {
reviewer := &fakePRReviewer{
result: PRReviewResult{
Repo: "acme/widget", Number: 7, Model: "openai/gpt-5", Status: "completed",
Findings: []PRReviewFinding{{File: "a.go", Line: 3, Defect: "nil deref", FailureScenario: "x", Verdict: "confirmed", Level: "error", Category: "nil-risk", Blocking: true}},
},
}
entry := toolNamed(t, ReviewTools(reviewer, "archie"), "review_pr")
out, err := entry.Handler(context.Background(), map[string]any{
"repo": "acme/widget", "pr_number": float64(7), "identity": "someone-else",
})
if err != nil {
t.Fatal(err)
}
// The model supplied an identity; it must be ignored in favour of the
// bound identity.
if reviewer.gotIdentity == nil || *reviewer.gotIdentity != "archie" {
t.Fatalf("identity = %v, want bound \"archie\"", reviewer.gotIdentity)
}
if reviewer.gotRepo != "acme/widget" || reviewer.gotNumber != 7 {
t.Fatalf("ReviewPR called with (%q, %d), want (acme/widget, 7)", reviewer.gotRepo, reviewer.gotNumber)
}
result, ok := out.(PRReviewResult)
if !ok {
t.Fatalf("handler returned %T, want PRReviewResult", out)
}
if result.Status != "completed" || len(result.Findings) != 1 || !result.Findings[0].Blocking {
t.Fatalf("result = %+v, want completed with one blocking finding", result)
}
}
func TestReviewPRToolValidatesInput(t *testing.T) {
reviewer := &fakePRReviewer{}
entry := toolNamed(t, ReviewTools(reviewer, "archie"), "review_pr")
tests := []struct {
name string
input map[string]any
}{
{"missing repo", map[string]any{"pr_number": float64(7)}},
{"missing number", map[string]any{"repo": "acme/widget"}},
{"zero number", map[string]any{"repo": "acme/widget", "pr_number": float64(0)}},
{"negative number", map[string]any{"repo": "acme/widget", "pr_number": float64(-1)}},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if _, err := entry.Handler(context.Background(), tt.input); err == nil {
t.Fatalf("handler error = nil, want validation error for %v", tt.input)
}
})
}
}
func TestReviewPRToolSurfacesReviewerError(t *testing.T) {
reviewer := &fakePRReviewer{err: errors.New("review already in progress")}
entry := toolNamed(t, ReviewTools(reviewer, "archie"), "review_pr")
if _, err := entry.Handler(context.Background(), map[string]any{
"repo": "acme/widget", "pr_number": float64(7),
}); err == nil {
t.Fatal("handler error = nil, want the reviewer failure surfaced")
}
}
+2
View File
@@ -87,6 +87,7 @@ type TurnRunnerConfig struct {
TaskLogs ChatTaskLogReader
TaskActor ChatTaskActor
TaskIdentity string
PRReviewer ChatPRReviewer
Bus TurnEventPublisher
BotUser string
Channel string
@@ -289,6 +290,7 @@ func (r *TurnRunner) prepareTurn(ctx context.Context, sessionID string, in Inbou
TaskTools(r.TaskLister, r.Tasks, r.TaskLogs, r.TaskActor, r.TaskIdentity),
SessionTools(r.Sessions, r.Router.SessionTracker(), r.Channel, in.Message)...,
)
extraTools = append(extraTools, ReviewTools(r.PRReviewer, r.TaskIdentity)...)
// The dashboard tools (page_index, dashboard_navigate) belong to the web
// UI only: a non-web channel has no dashboard to point at.
extraTools = append(extraTools, PageIndexTools(r.Channel)...)
+107
View File
@@ -0,0 +1,107 @@
package worktree
import (
"context"
"os"
"path/filepath"
"strings"
"testing"
"github.com/go-git/go-git/v6"
gitconfig "github.com/go-git/go-git/v6/config"
"github.com/go-git/go-git/v6/plumbing"
)
// pushHeadBranch pushes a "feature/widget" branch carrying widget.go onto the
// bare remote, giving CheckoutPR a real head to materialise.
func pushHeadBranch(t *testing.T, host string) {
t.Helper()
cloneDir := filepath.Join(t.TempDir(), "clone")
r, err := git.PlainClone(cloneDir, &git.CloneOptions{URL: filepath.Join(host, "acme", "todo.git")})
if err != nil {
t.Fatalf("clone bare remote: %v", err)
}
wt, err := r.Worktree()
if err != nil {
t.Fatalf("worktree: %v", err)
}
if err := wt.Checkout(&git.CheckoutOptions{
Branch: plumbing.NewBranchReferenceName("feature/widget"),
Create: true,
}); err != nil {
t.Fatalf("create feature branch: %v", err)
}
writeSeedCommit(t, r, cloneDir, "widget.go", "package widget\n", "add widget")
if err := r.Push(&git.PushOptions{
RemoteName: git.DefaultRemoteName,
RefSpecs: []gitconfig.RefSpec{"refs/heads/feature/widget:refs/heads/feature/widget"},
}); err != nil {
t.Fatalf("push feature branch: %v", err)
}
}
func TestCheckoutPRMaterializesHeadForDiffAndSnapshot(t *testing.T) {
ctx := context.Background()
host := newLocalRemote(t, "acme", "todo")
pushHeadBranch(t, host)
m := newManager(t, host)
dir, cleanup, err := m.CheckoutPR(ctx, "acme", "todo", "feature/widget", "main")
if err != nil {
t.Fatalf("CheckoutPR error = %v", err)
}
diff, err := m.Diff(ctx, dir, "main")
if err != nil {
t.Fatalf("Diff error = %v", err)
}
if !strings.Contains(diff, "widget.go") {
t.Errorf("Diff = %q, want the widget.go change", diff)
}
snapshotDir := filepath.Join(t.TempDir(), "snap")
if err := m.Snapshot(ctx, dir, snapshotDir); err != nil {
t.Fatalf("Snapshot error = %v", err)
}
content, err := os.ReadFile(filepath.Join(snapshotDir, "widget.go"))
if err != nil {
t.Fatalf("read snapshotted widget.go: %v", err)
}
if string(content) != "package widget\n" {
t.Errorf("snapshotted widget.go = %q, want %q", content, "package widget\n")
}
cleanup()
if _, err := os.Stat(dir); !os.IsNotExist(err) {
t.Errorf("CheckoutPR dir %q still exists after cleanup: %v", dir, err)
}
}
func TestCheckoutPRRefusesMissingHead(t *testing.T) {
host := newLocalRemote(t, "acme", "todo")
m := newManager(t, host)
_, cleanup, err := m.CheckoutPR(context.Background(), "acme", "todo", "feature/nonexistent", "main")
if err == nil {
t.Fatal("CheckoutPR error = nil, want failure for a head branch that is not pushed")
}
if cleanup != nil {
t.Error("cleanup should be nil when CheckoutPR fails before materialising")
}
}
func TestCheckoutPRRefusesMissingBase(t *testing.T) {
host := newLocalRemote(t, "acme", "todo")
pushHeadBranch(t, host)
m := newManager(t, host)
_, cleanup, err := m.CheckoutPR(context.Background(), "acme", "todo", "feature/widget", "no-such-base")
if err == nil {
t.Fatal("CheckoutPR error = nil, want failure for an unresolvable base branch")
}
// On failure CheckoutPR cleans up internally and returns a nil cleanup,
// matching the missing-head path: cleanup is non-nil only on success.
if cleanup != nil {
t.Error("cleanup should be nil on failure; CheckoutPR removes the clone itself")
}
}
+49
View File
@@ -697,6 +697,55 @@ func remoteBase(base string) string {
return "refs/remotes/" + git.DefaultRemoteName + "/" + base
}
// CheckoutPR materialises an existing pull request's head commit in a fresh
// full clone so the caller can Diff it against its base and Snapshot it for
// operator-triggered review. The head must already be pushed to the same
// repository (archie's own PRs always are); a cross-repo or deleted head is
// refused rather than half-reviewed. The returned cleanup removes the clone.
func (m *Manager) CheckoutPR(ctx context.Context, owner, repo, headRef, baseRef string) (dir string, cleanup func(), err error) {
if m.WorkDir != "" {
if err := os.MkdirAll(m.WorkDir, 0o755); err != nil {
return "", nil, fmt.Errorf("create worktree root directory: %w", err)
}
}
dir, err = os.MkdirTemp(m.WorkDir, "pr-review-*")
if err != nil {
return "", nil, fmt.Errorf("create PR review directory: %w", err)
}
cleanup = func() { _ = os.RemoveAll(dir) }
r, err := git.PlainCloneContext(ctx, dir, &git.CloneOptions{
URL: m.cloneURL(owner, repo),
ClientOptions: m.auth(),
})
if err != nil {
cleanup()
return "", nil, fmt.Errorf("clone %s/%s for review: %w", owner, repo, err)
}
headHash, err := r.ResolveRevision(plumbing.Revision(remoteBase(headRef)))
if err != nil {
cleanup()
return "", nil, fmt.Errorf("resolve head branch %q: %w (the PR head must already be pushed to this repository)", headRef, err)
}
wt, err := r.Worktree()
if err != nil {
cleanup()
return "", nil, fmt.Errorf("open review worktree: %w", err)
}
if err := wt.Checkout(&git.CheckoutOptions{Hash: *headHash}); err != nil {
cleanup()
return "", nil, fmt.Errorf("checkout head %q: %w", headRef, err)
}
// Diff resolves origin/<baseRef>; a full clone fetches every branch, so
// it exists. Fail closed now rather than mid-diff with a confusing error.
if _, err := resolveBase(r, baseRef); err != nil {
cleanup()
return "", nil, fmt.Errorf("resolve base branch %q: %w", baseRef, err)
}
return dir, cleanup, nil
}
// resolveBase finds the commit the task branch is compared against.
//
// The fully-qualified remote-tracking ref is tried first because that is