From 5f7bbbd224aa9dd6697f88bfd622e69de632c285 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 20:04:29 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20Hand=20workflow-model=20states?= =?UTF-8?q?=20to=20their=20agent=20profiles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The eval cycle now reads the bound model: an item whose state the model hands to a profile (TechDocs Accepted -> techdocs-drafter, Drafting on /verify -> techdocs-verifier) is withheld from every generic lane, claimed for the agent that fills the profile on the issue-claims ledger, and kicked once. The hand-off key (item, profile, state, triggering comment) is written to workflow-dispatch.json on delivery, so neither a later cycle nor a restart repeats it; a failed or deferred kick is retried. Part of the drafter hand-off for cncf/techdocs#395. Signed-off-by: Andy Anderson --- .../added-workflow-model-agent-dispatch.md | 1 + src/cmd/hive/main_eval_cycle.go | 32 +- src/cmd/hive/workflow_dispatch.go | 306 +++++++++++ src/cmd/hive/workflow_dispatch_test.go | 95 ++++ src/docs/design/workflow-models.md | 30 ++ src/docs/workflows/techdocs-assessment.md | 70 ++- src/pkg/github/workflow_dispatch.go | 231 ++++++++ src/pkg/github/workflow_dispatch_test.go | 152 ++++++ src/pkg/scheduler/workflow_dispatch.go | 498 ++++++++++++++++++ src/pkg/scheduler/workflow_dispatch_test.go | 238 +++++++++ 10 files changed, 1637 insertions(+), 16 deletions(-) create mode 100644 changelog.d/added-workflow-model-agent-dispatch.md create mode 100644 src/cmd/hive/workflow_dispatch.go create mode 100644 src/cmd/hive/workflow_dispatch_test.go create mode 100644 src/pkg/github/workflow_dispatch.go create mode 100644 src/pkg/github/workflow_dispatch_test.go create mode 100644 src/pkg/scheduler/workflow_dispatch.go create mode 100644 src/pkg/scheduler/workflow_dispatch_test.go diff --git a/changelog.d/added-workflow-model-agent-dispatch.md b/changelog.d/added-workflow-model-agent-dispatch.md new file mode 100644 index 0000000000..58e4091c65 --- /dev/null +++ b/changelog.d/added-workflow-model-agent-dispatch.md @@ -0,0 +1 @@ +- A repository bound to a workflow model now hands each item to the agent its model names: the curated TechDocs model sends an accepted request (`triage/accepted`, no covering PR) to the `techdocs-drafter` agent once, claiming the issue for it first, and runs `techdocs-verifier` on each `/verify` on the draft PR; model-owned items are withheld from the scanner and other generic lanes, and hand-offs are recorded in `workflow-dispatch.json` so a restart never repeats one (cncf/techdocs#395). diff --git a/src/cmd/hive/main_eval_cycle.go b/src/cmd/hive/main_eval_cycle.go index daefa49be4..fafaa57b9c 100644 --- a/src/cmd/hive/main_eval_cycle.go +++ b/src/cmd/hive/main_eval_cycle.go @@ -990,6 +990,10 @@ func runEvalCycle( }() } kickActionable = dashSrv.IntegrationKickAdmission(kickActionable) + // A workflow-model state handed to an agent profile is that profile's + // work, not the generic lanes' (cncf/techdocs#395): withhold it here, + // before the cache every kick (manual ones included) is built from. + kickActionable = withholdWorkflowOwnedForKicks(cfg, ghClient, kickActionable, logger) sched.SetLastActionable(kickActionable) // The filter compacts agentsDue in place, so snapshot it first to report @@ -1040,6 +1044,20 @@ func runEvalCycle( messages = append(messages, scheduler.KickMessage{Agent: k.Agent, Message: k.Message, IssueRefs: []string{k.PRRef}}) reviewKickByMessage[k.Agent+"\x00"+k.Message] = k } + // Workflow-model hand-offs (cncf/techdocs#395): each owned item is + // claimed for the agent that fills its profile, then kicked once; the + // durable record is written on delivery. They go ahead of the + // governor kicks: a lane takes one kick per pass, and an agent kicked + // every cycle would otherwise defer its hand-off forever. + workflowKickByMessage := map[string]workflowDispatchKick{} + var workflowMessages []scheduler.KickMessage + for _, k := range planWorkflowDispatchKicks(ctx, cfg, ghClient, actionable, dashSrv.IssueClaims(), func(agent string) bool { + return gov.AgentEligibleForCELKick(agent) && !agentMgr.IsPaused(agent) + }, logger) { + workflowMessages = append(workflowMessages, k.Message) + workflowKickByMessage[workflowDispatchKickKey(k.Message)] = k + } + messages = append(workflowMessages, messages...) // A fix kick (a maintainer's changes_requested / `/hive decision`, or // the swarm's) goes ahead of the governor kick for the same agent, or // the governor kick owns the agent and the fix kick times out every @@ -1234,8 +1252,16 @@ func runEvalCycle( persistReviewDispatchStateInProgress(reviewPlan, deliveredReviewKicks, logger) } }, - onDeferred: fixQueue.Deferred, + onDeferred: func(msg scheduler.KickMessage) { + if k, ok := workflowKickByMessage[workflowDispatchKickKey(msg)]; ok { + releaseWorkflowDispatch(k) + } + fixQueue.Deferred(msg) + }, onFailed: func(msg scheduler.KickMessage, err error) { + if k, ok := workflowKickByMessage[workflowDispatchKickKey(msg)]; ok { + releaseWorkflowDispatch(k) + } gov.RecordKickFailure(msg.Agent, err, time.Now()) if k, ok := reviewKickByMessage[reviewKickKey(msg)]; ok { logUndeliveredReviewKick(logger, dashSrv, k, err) @@ -1251,6 +1277,10 @@ func runEvalCycle( } gov.RecordKickForRepoAt(msg.Agent, msg.Repo, deliveredAt) dashSrv.AuditLog("governor", "kick", "trigger=governor-eval", msg.Agent) + if k, ok := workflowKickByMessage[workflowDispatchKickKey(msg)]; ok { + recordWorkflowDispatchDelivered(cfg, k, deliveredAt, logger) + dashSrv.AuditLog("governor", "workflow-dispatch", "item="+k.Entry.Ref+" profile="+k.Entry.Profile+" state="+k.Entry.State, msg.Agent) + } // Record issue-scoped kicks into the lifecycle timeline. Cheap, // guarded, and nil-safe (Record no-ops on a nil dashboard/store). diff --git a/src/cmd/hive/workflow_dispatch.go b/src/cmd/hive/workflow_dispatch.go new file mode 100644 index 0000000000..fa9a94022a --- /dev/null +++ b/src/cmd/hive/workflow_dispatch.go @@ -0,0 +1,306 @@ +package main + +import ( + "context" + "log/slog" + "path/filepath" + "sync" + "time" + + "github.com/hivecommons/hive/pkg/claims" + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/scheduler" + "github.com/hivecommons/hive/pkg/workflowmodel" + wfstore "github.com/hivecommons/hive/pkg/workflowmodel/store" +) + +// Workflow-model agent dispatch, eval-cycle wiring (cncf/techdocs#395). +// +// Per cycle, after the generic kicks are planned from an actionable set +// that no longer offers model-owned items (scheduler.WithholdWorkflowOwned): +// +// 1. collect every enumerated item whose bound model hands its state to a +// profile, plus the open drafts of repositories whose model dispatches +// a pull-request state (the enumeration leaves drafts out); +// 2. plan the hand-offs (scheduler.PlanWorkflowDispatch): the agent that +// fills the profile, the triggering reply for a reply-started profile, +// and the idempotency key; +// 3. for an issue, take the agent claim on the issue-claims ledger FIRST; +// a claim someone else holds stops the hand-off; +// 4. append one kick per hand-off to the cycle's messages. On delivery the +// key is written to the durable dispatch log, so neither a later cycle +// nor a restart repeats it; a failed or deferred kick leaves the key +// free for the next cycle. + +// workflowDispatchLogFile is the durable log under the workflow store root. +const workflowDispatchLogFile = "workflow-dispatch.json" + +// workflowDispatchPendingTTL bounds how long a planned, not yet delivered +// hand-off blocks re-planning in this process. A kick a later gate +// withholds (provider budget, quota hold, upgrade drain) reports nothing, +// so the in-flight mark lapses on its own and the next cycle plans again. +const workflowDispatchPendingTTL = 30 * time.Minute + +// workflowDispatchClaimTTL is the agent claim taken before the drafter is +// kicked: long enough for a draft to reach its PR (the covering PR then +// holds the issue), short enough that an abandoned hand-off frees it. +const workflowDispatchClaimTTL = 8 * time.Hour + +type workflowDispatchRuntime struct { + once sync.Once + log *scheduler.WorkflowDispatchLog + mu sync.Mutex + pending map[string]time.Time + // replies caches LatestDispatchReply per item ref, keyed on the item's + // updated_at: a new comment moves it, so an unchanged item costs no call. + replies map[string]workflowReplyCacheEntry +} + +type workflowReplyCacheEntry struct { + updatedAt time.Time + reply github.DispatchReply + found bool +} + +var workflowDispatchRT = &workflowDispatchRuntime{pending: map[string]time.Time{}, replies: map[string]workflowReplyCacheEntry{}} + +// dispatchLog opens the durable log once per process. +func (rt *workflowDispatchRuntime) dispatchLog(cfg *config.Config, logger *slog.Logger) *scheduler.WorkflowDispatchLog { + rt.once.Do(func() { + path := "" + if cfg != nil { + path = filepath.Join(wfstore.Root(cfg.Data.WorkflowsDir), workflowDispatchLogFile) + } + l, err := scheduler.OpenWorkflowDispatchLog(path) + if err != nil && logger != nil { + logger.Warn("workflow dispatch log unreadable; starting empty", "path", path, "error", err) + } + rt.log = l + }) + return rt.log +} + +func (rt *workflowDispatchRuntime) inFlight(key string, now time.Time) bool { + rt.mu.Lock() + defer rt.mu.Unlock() + at, ok := rt.pending[key] + if ok && now.Sub(at) > workflowDispatchPendingTTL { + delete(rt.pending, key) + return false + } + return ok +} + +func (rt *workflowDispatchRuntime) markPending(key string, now time.Time) { + rt.mu.Lock() + defer rt.mu.Unlock() + rt.pending[key] = now +} + +func (rt *workflowDispatchRuntime) clearPending(key string) { + rt.mu.Lock() + defer rt.mu.Unlock() + delete(rt.pending, key) +} + +// workflowDispatchKick is one planned hand-off and the record its delivery +// writes. +type workflowDispatchKick struct { + Message scheduler.KickMessage + Entry scheduler.WorkflowDispatchEntry +} + +// workflowDispatchActive reports whether the cycle dispatches at all. +func workflowDispatchActive(cfg *config.Config) bool { + return cfg != nil && cfg.Workflow.Enabled && cfg.Workflow.Dispatch.DispatchEnabled() +} + +// withholdWorkflowOwnedForKicks removes model-owned items from the set the +// generic kicks are built from. Model ownership is the model's, so it holds +// whatever workflow.dispatch says; only workflow.enabled (no model derives +// anything) turns it off. +func withholdWorkflowOwnedForKicks(cfg *config.Config, ghClient *github.Client, actionable *github.ActionableResult, logger *slog.Logger) *github.ActionableResult { + if cfg == nil || !cfg.Workflow.Enabled || ghClient == nil { + return actionable + } + out, withheld := scheduler.WithholdWorkflowOwned(actionable, ghClient) + if withheld > 0 && logger != nil { + logger.Info("workflow dispatch: model-owned items withheld from generic kicks", "withheld", withheld) + } + return out +} + +// workflowDispatchItems collects the cycle's model-owned items. +func workflowDispatchItems(ctx context.Context, cfg *config.Config, ghClient *github.Client, actionable *github.ActionableResult, logger *slog.Logger) []github.WorkflowDispatch { + var items []github.WorkflowDispatch + if actionable != nil { + for _, issue := range actionable.Issues.Items { + if d, ok := ghClient.WorkflowDispatchForIssue(issue); ok { + items = append(items, d) + } + } + for _, pr := range actionable.PRs.Items { + if d, ok := ghClient.WorkflowDispatchForPR(pr); ok { + items = append(items, d) + } + } + } + for _, b := range cfg.Project.WorkflowBindings { + p := ghClient.WorkflowModelFor(b.Repo) + if !dispatchesPRState(p) { + continue + } + drafts, err := ghClient.ListWorkflowDraftPRs(ctx, qualifyClaimRepo(cfg.Project.Org, b.Repo)) + if err != nil { + if logger != nil { + logger.Warn("workflow dispatch: listing drafts failed", "repo", b.Repo, "error", err) + } + continue + } + for _, pr := range drafts { + if d, ok := ghClient.WorkflowDispatchForPR(pr); ok { + items = append(items, d) + } + } + } + return items +} + +func dispatchesPRState(p *workflowmodel.Profile) bool { + if p == nil { + return false + } + for _, t := range p.Dispatch { + if t.AppliesTo(workflowmodel.KindPR) { + return true + } + } + return false +} + +// workflowDispatchReplyFor is the cached reply lookup the planner uses. +func workflowDispatchReplyFor(ctx context.Context, ghClient *github.Client) func(d github.WorkflowDispatch) (github.DispatchReply, bool, error) { + rt := workflowDispatchRT + return func(d github.WorkflowDispatch) (github.DispatchReply, bool, error) { + ref := d.Ref() + "|" + d.Target.Reply + at := d.UpdatedAt + rt.mu.Lock() + cached, ok := rt.replies[ref] + rt.mu.Unlock() + if ok && !at.IsZero() && cached.updatedAt.Equal(at) { + return cached.reply, cached.found, nil + } + r, found, err := ghClient.LatestDispatchReply(ctx, d.Repo, d.Number, d.Target.Reply) + if err != nil { + return github.DispatchReply{}, false, err + } + rt.mu.Lock() + rt.replies[ref] = workflowReplyCacheEntry{updatedAt: at, reply: r, found: found} + rt.mu.Unlock() + return r, found, nil + } +} + +// planWorkflowDispatchKicks plans the cycle's hand-offs and claims each +// issue for its agent before returning the kick. +func planWorkflowDispatchKicks(ctx context.Context, cfg *config.Config, ghClient *github.Client, actionable *github.ActionableResult, ledger *claims.Ledger, eligible func(agent string) bool, logger *slog.Logger) []workflowDispatchKick { + if !workflowDispatchActive(cfg) || ghClient == nil { + return nil + } + rt := workflowDispatchRT + dlog := rt.dispatchLog(cfg, logger) + now := time.Now() + items := workflowDispatchItems(ctx, cfg, ghClient, actionable, logger) + if len(items) == 0 { + return nil + } + cands, skips := scheduler.PlanWorkflowDispatch(items, scheduler.WorkflowDispatchPlanDeps{ + Agent: cfg.WorkflowDispatchAgent, + Eligible: eligible, + Reply: workflowDispatchReplyFor(ctx, ghClient), + Done: func(key string) bool { return dlog.Done(key) || rt.inFlight(key, now) }, + }) + for _, s := range skips { + if logger != nil && s.Reason != scheduler.WorkflowSkipDone && s.Reason != scheduler.WorkflowSkipNoReply { + logger.Info("workflow dispatch: item not handed off", "item", s.Ref, "reason", s.Reason) + } + } + var out []workflowDispatchKick + for _, c := range cands { + if !claimForWorkflowDispatch(cfg, ledger, c, logger) { + continue + } + set := cfg.Workflow.Dispatch.Profile(c.Dispatch.Target.Profile) + msg := scheduler.BuildWorkflowDispatchPrompt(c, set.PromptTemplate) + var refs []string + if c.Dispatch.Kind == workflowmodel.KindIssue { + refs = []string{c.Dispatch.Ref()} + } + rt.markPending(c.Key, now) + out = append(out, workflowDispatchKick{ + Message: scheduler.KickMessage{Agent: c.Agent, Message: msg, IssueRefs: refs}, + Entry: scheduler.WorkflowDispatchEntry{ + Key: c.Key, Ref: c.Dispatch.Ref(), Profile: c.Dispatch.Target.Profile, + State: c.Dispatch.State, Agent: c.Agent, By: "governor", + }, + }) + if logger != nil { + logger.Info("workflow dispatch: handing item to agent", "item", c.Dispatch.Ref(), "model", c.Dispatch.Model, + "state", c.Dispatch.State, "profile", c.Dispatch.Target.Profile, "agent", c.Agent) + } + } + return out +} + +// claimForWorkflowDispatch takes the agent claim on an issue before the +// kick. A pull request is not claimed (an issue claim on a PR stages it as +// an issue); its idempotency is the dispatch key alone. With no ledger the +// hand-off proceeds: the item is already withheld from every generic lane. +func claimForWorkflowDispatch(cfg *config.Config, ledger *claims.Ledger, c scheduler.WorkflowDispatchCandidate, logger *slog.Logger) bool { + if c.Dispatch.Kind != workflowmodel.KindIssue || ledger == nil { + return true + } + res, err := ledger.Claim(claims.Request{ + Repo: qualifyClaimRepo(cfg.Project.Org, c.Dispatch.Repo), + Issue: c.Dispatch.Number, + Holder: c.Agent, + HolderID: c.Agent, + Kind: claims.KindAgent, + TTL: workflowDispatchClaimTTL, + }) + if err != nil { + if logger != nil { + logger.Warn("workflow dispatch: claim refused; not handing off", "item", c.Dispatch.Ref(), "agent", c.Agent, "error", err) + } + return false + } + if !res.Outcome.Changed() { + if logger != nil { + logger.Info("workflow dispatch: item held by another claimant; not handing off", "item", c.Dispatch.Ref(), "agent", c.Agent, "outcome", string(res.Outcome)) + } + return false + } + return true +} + +// recordWorkflowDispatchDelivered writes the durable record of a delivered +// hand-off. +func recordWorkflowDispatchDelivered(cfg *config.Config, k workflowDispatchKick, at time.Time, logger *slog.Logger) { + rt := workflowDispatchRT + e := k.Entry + e.At = at + if err := rt.dispatchLog(cfg, logger).Record(e); err != nil && logger != nil { + logger.Warn("workflow dispatch: recording hand-off failed", "item", e.Ref, "error", err) + } + rt.clearPending(e.Key) +} + +// releaseWorkflowDispatch frees a hand-off whose kick did not land. +func releaseWorkflowDispatch(k workflowDispatchKick) { workflowDispatchRT.clearPending(k.Entry.Key) } + +// workflowDispatchKickKey identifies a workflow kick among the cycle's +// messages. +func workflowDispatchKickKey(msg scheduler.KickMessage) string { + return msg.Agent + "\x00" + msg.Message +} diff --git a/src/cmd/hive/workflow_dispatch_test.go b/src/cmd/hive/workflow_dispatch_test.go new file mode 100644 index 0000000000..ac59740e11 --- /dev/null +++ b/src/cmd/hive/workflow_dispatch_test.go @@ -0,0 +1,95 @@ +package main + +import ( + "path/filepath" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/claims" + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/scheduler" + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +func workflowCandidate(kind workflowmodel.ItemKind, number int) scheduler.WorkflowDispatchCandidate { + return scheduler.WorkflowDispatchCandidate{ + Dispatch: github.WorkflowDispatch{Repo: "cncf/techdocs", Number: number, Kind: kind, State: "accepted", + Target: workflowmodel.DispatchTarget{Profile: "techdocs-drafter"}}, + Agent: "writer", + Key: "k", + } +} + +// The claim comes first: a free issue is claimed for the drafter's agent, +// an issue a person holds is not handed off, and a pull request is never +// claimed as an issue. +func TestClaimForWorkflowDispatch(t *testing.T) { + cfg := &config.Config{} + cfg.Project.Org = "cncf" + l, err := claims.New(filepath.Join(t.TempDir(), "claims.json"), claims.DefaultPolicy(), claims.Hooks{}) + if err != nil { + t.Fatal(err) + } + if !claimForWorkflowDispatch(cfg, l, workflowCandidate(workflowmodel.KindIssue, 395), nil) { + t.Fatal("free issue not handed off") + } + c, ok := l.Lookup("cncf/techdocs", 395) + if !ok || c.Holder != "writer" || c.Kind != claims.KindAgent { + t.Fatalf("claim %+v %v", c, ok) + } + // Same agent again (a retry after a deferred kick) renews. + if !claimForWorkflowDispatch(cfg, l, workflowCandidate(workflowmodel.KindIssue, 395), nil) { + t.Fatal("renewal refused") + } + + if _, err := l.Claim(claims.Request{Repo: "cncf/techdocs", Issue: 396, Holder: "nate", Kind: claims.KindHuman}); err != nil { + t.Fatal(err) + } + if claimForWorkflowDispatch(cfg, l, workflowCandidate(workflowmodel.KindIssue, 396), nil) { + t.Fatal("an issue a person holds was handed off") + } + + if !claimForWorkflowDispatch(cfg, l, workflowCandidate(workflowmodel.KindPR, 400), nil) { + t.Fatal("pull request hand-off refused") + } + if _, ok := l.Lookup("cncf/techdocs", 400); ok { + t.Fatal("a pull request was claimed as an issue") + } +} + +func TestWorkflowDispatchPendingLapses(t *testing.T) { + rt := &workflowDispatchRuntime{pending: map[string]time.Time{}, replies: map[string]workflowReplyCacheEntry{}} + now := time.Now() + rt.markPending("k", now) + if !rt.inFlight("k", now.Add(time.Minute)) { + t.Fatal("fresh hand-off not in flight") + } + if rt.inFlight("k", now.Add(workflowDispatchPendingTTL+time.Minute)) { + t.Fatal("in-flight mark never lapses") + } + rt.markPending("k", now) + rt.clearPending("k") + if rt.inFlight("k", now) { + t.Fatal("cleared hand-off still in flight") + } +} + +func TestWorkflowDispatchActive(t *testing.T) { + off := false + cfg := &config.Config{} + if workflowDispatchActive(cfg) { + t.Fatal("active with workflow.enabled off") + } + cfg.Workflow.Enabled = true + if !workflowDispatchActive(cfg) { + t.Fatal("dispatch must default on") + } + cfg.Workflow.Dispatch.Enabled = &off + if workflowDispatchActive(cfg) { + t.Fatal("workflow.dispatch.enabled: false ignored") + } + if workflowDispatchActive(nil) { + t.Fatal("nil config active") + } +} diff --git a/src/docs/design/workflow-models.md b/src/docs/design/workflow-models.md index 87e7b04e54..08dc200556 100644 --- a/src/docs/design/workflow-models.md +++ b/src/docs/design/workflow-models.md @@ -707,6 +707,36 @@ agent (by name) whose role is `writer`, then `docs`, then `feature`. A configure not exist or is disabled fills nothing: a typo never falls back to another agent. Replica overlays are never chosen; the base agent is kicked. +**The dispatch pass** (`pkg/scheduler/workflow_dispatch.go`, `cmd/hive/workflow_dispatch.go`). +Every eval cycle, with `workflow.enabled` on: + +- `scheduler.WithholdWorkflowOwned` removes every issue and pull request whose bound model + hands its current state to a profile from the set the generic kicks (and manual kicks from + the cache) are built from. This holds whatever `workflow.dispatch` says: the item is the + profile's. +- With `workflow.dispatch.enabled` on, the owned items (the enumerated ones, plus the open + drafts of repositories whose model dispatches a pull-request state: the enumeration leaves + drafts out) are planned by `scheduler.PlanWorkflowDispatch`: the agent that fills the + profile, the triggering reply for a reply-started profile (`github.LatestDispatchReply`: the + newest unedited comment whose first line opens with the reply, by a human with write + access; cached on the item's `updated_at`), and the idempotency key + `||[|]`. +- An issue is claimed for that agent on the issue-claims ledger first (agent claim, 8 h); a + claim someone else holds stops the hand-off. A pull request is not claimed. +- The kick goes ahead of the governor kicks (a lane takes one kick per pass). On delivery the + key is written to `workflow-dispatch.json` under the workflow store root and a + `workflow-dispatch` audit row is recorded; a failed or deferred kick frees the key for the + next pass, and an in-flight mark lapses after 30 minutes. + +The built-in prompt names the item, model, state and trigger, the state's guidance +(`dispatch.instructions`, waiting reasons, column hint), the tools and outputs the grant +allows, and the deliverable: for a PR-producing profile a (draft) pull request labeled with +the deliverable state's labels plus the item's stateless model labels, `hive-open-pr --issues +N` and `Refs #N`; for a reviewing profile one comment on the item. Gate labels (`GuardedLabels`) +are never to be applied. `prompt_template` replaces it; placeholders: `${REF}`, `${REPO}`, +`${NUMBER}`, `${TITLE}`, `${URL}`, `${KIND}`, `${MODEL}`, `${STATE}`, `${STATE_LABEL}`, +`${PROFILE}`, `${AGENT}`, `${TRIGGER}`, `${INSTRUCTIONS}`, `${DELIVERABLE}`. + ## Ingest from cluster and from written specs (RFC phase 6) Two more ways into a draft model, beside the repository ingest of phase 3a. Both end in the diff --git a/src/docs/workflows/techdocs-assessment.md b/src/docs/workflows/techdocs-assessment.md index 39f1bcf895..4afe0c32e4 100644 --- a/src/docs/workflows/techdocs-assessment.md +++ b/src/docs/workflows/techdocs-assessment.md @@ -209,21 +209,66 @@ What the operator of the TechDocs hive (authorized repo `cncf/techdocs`) does an ## Starting the drafter (Accepted → Draft) -Nothing dispatches the drafter automatically yet. `techdocs-drafter` and -`techdocs-verifier` are profiles the model declares so the compiler can check that every -agent action is followed by a human gate; they are not hive agents, and the scheduler does -not read the bound model. An accepted issue therefore sits in **Accepted** until someone -starts a draft. The model leaves Accepted only when a pull request covers the issue -(`issue.covered`), which moves it to `draft-open`. +The hive hands the phase to its agents itself. The model grants `techdocs-drafter` the +`accepted` and `drafting` states and `techdocs-verifier` the `drafting` state; the compiler +resolves where each takes over ([Agent dispatch](../design/workflow-models.md#agent-dispatch)): + +| State | Profile | Starts when | +|-------|---------|-------------| +| Accepted (issue) | `techdocs-drafter` | `triage/accepted` is on the issue and no PR covers it | +| Drafting (draft PR) | `techdocs-verifier` | a person with write access comments `/verify` on the draft PR | + +On each pass the hive: + +1. withholds every item in those states from the generic lanes, so the scanner or a feature + agent never picks up an accepted request before the drafter does; +2. resolves the hive agent that fills the profile (`workflow.dispatch.profiles..agent`; + unset: an agent named after the profile, else the first enabled `writer`, `docs` or + `feature` agent by name); +3. for the issue, takes the agent claim on the hive's claim ledger first; a claim someone + else holds (a person working the phase by hand) stops the hand-off; +4. kicks that agent once with the issue, the state's guidance and the deliverable the model + requires: a draft PR in `cncf/techdocs` labeled `Docs analysis` plus the issue's phase + label, named in the PR request (`hive-open-pr --issues N`) and referenced with `Refs #N`, + not marked ready and without the `verified` / `confirmed` gate labels; +5. records the hand-off in `workflow-dispatch.json` under the workflow store root when the + kick lands, so neither a later pass nor a restart repeats it. A kick that could not be + delivered (busy, paused, failed) is retried on a later pass. + +The verifier runs once per `/verify` comment: each new `/verify` from the reviewer is a new +pass, posting its report as a PR comment. A `/hive verify` command is the model-reply path +instead: it applies `verified` directly, which is how a reviewer records a deliberate skip. + +To use it, the hive needs `workflow.enabled: true` and `cncf/techdocs` bound to +`cncf-techdocs-assessment`; dispatch is on by default (`workflow.dispatch.enabled`). Pin the +agents if the default pick is wrong: -A hive owner starts the draft by hand: +```yaml +workflow: + enabled: true + dispatch: + profiles: + techdocs-drafter: {agent: writer} + techdocs-verifier: {agent: reviewer} +``` + +`workflow.dispatch.profiles..disabled: true` stops one profile's automatic +hand-off, and `workflow.dispatch.enabled: false` stops them all (owned items stay withheld +from the generic lanes either way). `prompt_template` replaces the built-in prompt; see the +design doc for its `${VAR}` placeholders. + +### Starting the drafter by hand (fallback) + +When no agent fills the profile, dispatch is off, or a discarded draft should be restarted (a +hand-off happens once per issue and state: retries are a person's choice, spec §5), a hive +owner starts the draft by hand: 1. Check the request is accepted: `triage/accepted` is on the issue, applied by a maintainer with write access to `cncf/techdocs`, and the hive's workflow column shows **Accepted**. 2. On the hive dashboard, signed in with the **owner** role (kicks with a prompt are - owner-only), open the agent card of an agent that may work on `cncf/techdocs` (the - scanner or a feature agent) and type the drafting instruction into its **Send a message - to …** box, then **Send**. Name the issue, the phase and the deliverable, for example: + owner-only), open the agent card of an agent that may work on `cncf/techdocs` and type the + drafting instruction into its **Send a message to …** box, then **Send**. Name the issue, + the phase and the deliverable, for example: ```text Draft the Phase A (assessment) deliverable for cncf/techdocs#395 following the CNCF @@ -241,9 +286,6 @@ A hive owner starts the draft by hand: the reviewer runs or skips the verifier (`/verify`, the `verified` label), marks the PR ready (`/ready`), stakeholders `/confirm`, and an independent approver merges. -If the draft is discarded (`/discard`, PR closed unmerged), the issue returns to Accepted and -the same kick starts a fresh draft. - ## Not representable today These parts of the spec are documented in the model's annotations but not enforced by @@ -255,7 +297,5 @@ the engine: - Phase as a state dimension and the A→C skip — carried by labels; the `open-next-phase-tracking-issue`, `notify-contacts` and `mention-stakeholders` bookkeeping actions are declarative only. -- Dispatching the drafter on Accepted and the verifier on `/verify` — the profiles and - gates exist, the dispatch does not yet (see [Starting the drafter](#starting-the-drafter-accepted--draft)). - Membership of the frozen stakeholder set — the gate exists, the check does not yet. - Data-collection scripts and the strict provenance check — a manual check. diff --git a/src/pkg/github/workflow_dispatch.go b/src/pkg/github/workflow_dispatch.go new file mode 100644 index 0000000000..5e74aa2a91 --- /dev/null +++ b/src/pkg/github/workflow_dispatch.go @@ -0,0 +1,231 @@ +package github + +import ( + "context" + "fmt" + "strings" + "time" + + gh "github.com/google/go-github/v72/github" + + "github.com/hivecommons/hive/pkg/stageengine" + "github.com/hivecommons/hive/pkg/stagelabels" + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +// Workflow-model agent dispatch, forge side (cncf/techdocs#395). +// +// A repository bound to a workflow model derives each item's model state +// (stage_model_owned.go). When the compiled model hands that state to an +// agent profile (workflowmodel.Profile.Dispatch), the item belongs to that +// profile: the scheduler withholds it from every generic lane and the +// dispatch pass (cmd/hive/workflow_dispatch.go) hands it to the hive agent +// configured for the profile. This file answers the two forge questions +// that pass needs: "which profile owns this item now?" (pure, from the +// enumerated item) and, for a profile that waits on a reply, "has a person +// with write access posted it?" (comments, read only for items in such a +// state). + +// WorkflowDispatch is one item whose bound model hands its current state to +// an agent profile. +type WorkflowDispatch struct { + // Repo is the item's repository as the enumeration carries it. + Repo string + Number int + Kind workflowmodel.ItemKind + Title string + URL string + Labels []string + // UpdatedAt is the item's last activity as enumerated; a reply lookup + // is cached on it. + UpdatedAt time.Time + // Model is the bound model as name@version. + Model string + // State is the model state id the item is in. + State string + // Target is the model's dispatch target for State. + Target workflowmodel.DispatchTarget + // Profile is the compiled bound model. + Profile *workflowmodel.Profile +} + +// Ref is the item's "owner/repo#N" reference. +func (d WorkflowDispatch) Ref() string { return fmt.Sprintf("%s#%d", d.Repo, d.Number) } + +// WorkflowModelFor returns the compiled model bound to repo ("owner/repo" or +// a bare name in the client's org), or nil when the repository is unbound, +// workflow models are off, or the binding is the built-in hive-default. +func (c *Client) WorkflowModelFor(repo string) *workflowmodel.Profile { + if c == nil { + return nil + } + owner, name := c.splitRepo(repo) + p := c.stageWorkflowFor(owner, name) + if p == nil || p.Name == hiveDefaultWorkflowName { + return nil + } + return p +} + +// WorkflowDispatchForIssue reports whether the bound model hands the +// issue's current state to an agent profile. Pure over the enumerated +// issue: no forge call. +func (c *Client) WorkflowDispatchForIssue(issue Issue) (WorkflowDispatch, bool) { + p := c.WorkflowModelFor(issue.Repo) + if !p.Dispatches() { + return WorkflowDispatch{}, false + } + owner, name := c.splitRepo(issue.Repo) + f := issueFactsFrom(issueStageInputFrom(issue), func(string, int) stagelabels.Stage { return stagelabels.None }) + f.Ref.Owner, f.Ref.Repo = owner, name + return workflowDispatchFrom(p, stagelabels.IssueItem, f, WorkflowDispatch{ + Repo: issue.Repo, Number: issue.Number, Kind: workflowmodel.KindIssue, + Title: issue.Title, URL: issue.URL, Labels: append([]string(nil), issue.Labels...), UpdatedAt: issue.UpdatedAt, + }) +} + +// WorkflowDispatchForPR is WorkflowDispatchForIssue for an open pull +// request. The facts are the ones a list call carries (labels, draft); a +// model rule that needs checks or reviews to tell its dispatch state apart +// sees them unknown. +func (c *Client) WorkflowDispatchForPR(pr PullRequest) (WorkflowDispatch, bool) { + p := c.WorkflowModelFor(pr.Repo) + if !p.Dispatches() { + return WorkflowDispatch{}, false + } + owner, name := c.splitRepo(pr.Repo) + f := stageengine.Facts{ + Ref: stageengine.Ref{Owner: owner, Repo: name, Number: pr.Number, Kind: stagelabels.PRItem}, + Labels: append([]string(nil), pr.Labels...), + Title: pr.Title, + Open: true, + Draft: pr.Draft, + Park: stageengine.ParkFacts{Holds: stagelabels.Holds(pr.Labels)}, + PR: &stageengine.PRFacts{}, + } + return workflowDispatchFrom(p, stagelabels.PRItem, f, WorkflowDispatch{ + Repo: pr.Repo, Number: pr.Number, Kind: workflowmodel.KindPR, + Title: pr.Title, URL: pr.URL, Labels: append([]string(nil), pr.Labels...), UpdatedAt: pr.UpdatedAt, + }) +} + +func workflowDispatchFrom(p *workflowmodel.Profile, kind stagelabels.Item, f stageengine.Facts, d WorkflowDispatch) (WorkflowDispatch, bool) { + dec := stageengine.DeriveFromModel(p, kind).Derive(f) + if dec.Abstain || dec.ModelState == "" { + return WorkflowDispatch{}, false + } + t, ok := p.DispatchFor(dec.ModelState) + if !ok || !t.AppliesTo(d.Kind) { + return WorkflowDispatch{}, false + } + d.Model, d.State, d.Target, d.Profile = p.Name+"@"+p.Version, dec.ModelState, t, p + return d, true +} + +// ListWorkflowDraftPRs lists the open DRAFT pull requests of repo. The +// enumeration leaves ordinary drafts out of the actionable set (someone's +// work in progress), so a model state that lives on drafts (TechDocs +// Drafting) is only visible through this call. One list call per bound +// repository whose model dispatches a pull-request state. +func (c *Client) ListWorkflowDraftPRs(ctx context.Context, repo string) ([]PullRequest, error) { + if c == nil || c.client == nil { + return nil, nil + } + owner, name := c.splitRepo(repo) + opts := &gh.PullRequestListOptions{State: "open", ListOptions: gh.ListOptions{PerPage: 100}} + var out []PullRequest + for { + prs, resp, err := c.client.PullRequests.List(ctx, owner, name, opts) + if err != nil { + return nil, fmt.Errorf("listing pull requests for %s/%s: %w", owner, name, err) + } + for _, pr := range prs { + if pr == nil || !pr.GetDraft() { + continue + } + out = append(out, PullRequest{ + Repo: repo, + Number: pr.GetNumber(), + Title: pr.GetTitle(), + Author: safeGetLogin(pr.GetUser()), + Labels: issueLabelNames(pr.Labels), + Draft: true, + UpdatedAt: pr.GetUpdatedAt().Time, + URL: pr.GetHTMLURL(), + }) + } + if resp == nil || resp.NextPage == 0 { + break + } + opts.Page = resp.NextPage + } + return out, nil +} + +// DispatchReply is the human reply that starts a reply-triggered dispatch. +type DispatchReply struct { + CommentID int64 + Author string + At time.Time + URL string +} + +// dispatchReplyCandidateLimit bounds how many matching comments, newest +// first, have their author's permission checked. +const dispatchReplyCandidateLimit = 3 + +// LatestDispatchReply returns the newest comment on repo#number whose first +// line opens with reply (`/verify`, case-insensitive, trailing punctuation +// ignored), written by a human with write access and not edited since. A +// `/hive ` command is not a match: the model-reply path answers that +// one and moves the item itself. +func (c *Client) LatestDispatchReply(ctx context.Context, repo string, number int, reply string) (DispatchReply, bool, error) { + reply = strings.TrimSpace(reply) + if c == nil || c.client == nil || reply == "" || number <= 0 { + return DispatchReply{}, false, nil + } + owner, name := c.splitRepo(repo) + comments, err := c.listIssueComments(ctx, owner, name, number) + if err != nil { + return DispatchReply{}, false, err + } + checked := 0 + for i := len(comments) - 1; i >= 0 && checked < dispatchReplyCandidateLimit; i-- { + cm := comments[i] + if cm == nil || !IsDispatchReply(cm.GetBody(), reply) { + continue + } + created := cm.GetCreatedAt().Time + if updated := cm.GetUpdatedAt().Time; updated.After(created) { + continue + } + if !c.isHumanAuthor(cm.GetUser()) { + continue + } + checked++ + login := safeGetLogin(cm.GetUser()) + allowed, err := c.commenterMayUnpark(ctx, owner, name, login, false) + if err != nil { + return DispatchReply{}, false, err + } + if !allowed { + continue + } + return DispatchReply{CommentID: cm.GetID(), Author: login, At: created, URL: cm.GetHTMLURL()}, true, nil + } + return DispatchReply{}, false, nil +} + +// IsDispatchReply reports whether body's first non-empty line opens with +// reply as its own word. +func IsDispatchReply(body, reply string) bool { + line := firstNonEmptyLine(body) + if line == "" || strings.HasPrefix(line, ">") { + return false + } + fields := strings.Fields(line) + if len(fields) == 0 { + return false + } + return strings.EqualFold(strings.TrimRight(fields[0], ".:,;!"), strings.TrimSpace(reply)) +} diff --git a/src/pkg/github/workflow_dispatch_test.go b/src/pkg/github/workflow_dispatch_test.go new file mode 100644 index 0000000000..22cd04fa80 --- /dev/null +++ b/src/pkg/github/workflow_dispatch_test.go @@ -0,0 +1,152 @@ +package github + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/hub/marketplace/curated" + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +// curatedTechdocs compiles the curated cncf-techdocs-assessment model a +// hive binds cncf/techdocs to (curated-2026.11.2). +func curatedTechdocs(t *testing.T) *workflowmodel.Profile { + t.Helper() + entries, errs := curated.Load() + if len(errs) != 0 { + t.Fatal(errs) + } + for _, e := range entries { + if e.Model.Metadata.Name == "cncf-techdocs-assessment" && e.Model.Spec.Meta.Version == "curated-2026.11.2" { + p, _, err := workflowmodel.Compile(e.Model) + if err != nil { + t.Fatal(err) + } + return p + } + } + t.Fatal("curated techdocs model missing") + return nil +} + +func techdocsDispatchClient(t *testing.T) *Client { + t.Helper() + p := curatedTechdocs(t) + c := &Client{org: "cncf"} + c.SetStageWorkflowFor(func(owner, repo string) *workflowmodel.Profile { + if owner == "cncf" && repo == "techdocs" { + return p + } + return nil + }) + return c +} + +func TestWorkflowDispatchForIssue(t *testing.T) { + c := techdocsDispatchClient(t) + accepted := Issue{Repo: "cncf/techdocs", Number: 395, Title: "Assess X", Labels: []string{"Docs analysis", "phase/assessment", "triage/accepted"}} + d, ok := c.WorkflowDispatchForIssue(accepted) + if !ok || d.State != "accepted" || d.Target.Profile != "techdocs-drafter" || d.Kind != workflowmodel.KindIssue { + t.Fatalf("accepted issue dispatch = %+v %v", d, ok) + } + if d.Ref() != "cncf/techdocs#395" || d.Model != "cncf-techdocs-assessment@curated-2026.11.2" { + t.Fatalf("ref %q model %q", d.Ref(), d.Model) + } + // Not yet accepted: the requested state is a person's, not a profile's. + if _, ok := c.WorkflowDispatchForIssue(Issue{Repo: "cncf/techdocs", Number: 396, Labels: []string{"Docs analysis", "needs-triage"}}); ok { + t.Fatal("a requested issue must not dispatch") + } + // On hold: escalated, an administrator's. + if _, ok := c.WorkflowDispatchForIssue(Issue{Repo: "cncf/techdocs", Number: 397, Labels: []string{"triage/accepted", "hold"}}); ok { + t.Fatal("a held issue must not dispatch") + } + // An unbound repository is untouched. + if _, ok := c.WorkflowDispatchForIssue(Issue{Repo: "cncf/other", Number: 1, Labels: []string{"triage/accepted"}}); ok { + t.Fatal("an unbound repository dispatched") + } + var nilClient *Client + if _, ok := nilClient.WorkflowDispatchForIssue(accepted); ok { + t.Fatal("nil client dispatched") + } +} + +func TestWorkflowDispatchForPR(t *testing.T) { + c := techdocsDispatchClient(t) + d, ok := c.WorkflowDispatchForPR(PullRequest{Repo: "cncf/techdocs", Number: 400, Draft: true, Labels: []string{"Docs analysis", "phase/assessment"}}) + if !ok || d.State != "drafting" || d.Target.Profile != "techdocs-verifier" || d.Target.Reply != "/verify" { + t.Fatalf("draft PR dispatch = %+v %v", d, ok) + } + // Verified: in review, the reviewer's. + if _, ok := c.WorkflowDispatchForPR(PullRequest{Repo: "cncf/techdocs", Number: 401, Draft: true, Labels: []string{"Docs analysis", "verified"}}); ok { + t.Fatal("a verified PR must not dispatch") + } + // Not a deliverable: no model state. + if _, ok := c.WorkflowDispatchForPR(PullRequest{Repo: "cncf/techdocs", Number: 402, Draft: true}); ok { + t.Fatal("an unlabeled PR must not dispatch") + } +} + +func TestIsDispatchReply(t *testing.T) { + cases := map[string]bool{ + "/verify": true, + "/VERIFY please": true, + "\n\n/verify.\nthanks": true, + "/hive verify": false, + "> /verify": false, + "please /verify": false, + "/verifying": false, + "": false, + } + for body, want := range cases { + if got := IsDispatchReply(body, "/verify"); got != want { + t.Errorf("IsDispatchReply(%q) = %v; want %v", body, got, want) + } + } +} + +// LatestDispatchReply takes the newest unedited /verify from a human with +// write access; a reader's /verify and a bot's are passed over. +func TestLatestDispatchReply(t *testing.T) { + created := time.Date(2026, 11, 16, 10, 0, 0, 0, time.UTC) + type wireComment struct { + ID int64 `json:"id"` + Body string `json:"body"` + User wireUser `json:"user"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` + HTMLURL string `json:"html_url"` + } + comments := []wireComment{ + {ID: 1, Body: "/verify", User: wireUser{Login: "writer"}, CreatedAt: created, UpdatedAt: created, HTMLURL: "u1"}, + {ID: 2, Body: "/verify", User: wireUser{Login: "reader"}, CreatedAt: created.Add(time.Minute), UpdatedAt: created.Add(time.Minute)}, + {ID: 3, Body: "/verify", User: wireUser{Login: "ci[bot]"}, CreatedAt: created.Add(2 * time.Minute), UpdatedAt: created.Add(2 * time.Minute)}, + {ID: 4, Body: "looks good", User: wireUser{Login: "writer"}, CreatedAt: created.Add(3 * time.Minute), UpdatedAt: created.Add(3 * time.Minute)}, + } + mux := http.NewServeMux() + mux.HandleFunc("/repos/cncf/techdocs/issues/400/comments", func(w http.ResponseWriter, r *http.Request) { + _ = json.NewEncoder(w).Encode(comments) + }) + mux.HandleFunc("/repos/cncf/techdocs/collaborators/writer/permission", func(w http.ResponseWriter, r *http.Request) { + _, _ = w.Write([]byte(`{"permission":"write","role_name":"write"}`)) + }) + mux.HandleFunc("/repos/cncf/techdocs/collaborators/reader/permission", func(w http.ResponseWriter, r *http.Request) { + _, _ = w.Write([]byte(`{"permission":"read","role_name":"read"}`)) + }) + server := httptest.NewServer(mux) + defer server.Close() + c := newTestClient(t, server, "cncf", []string{"techdocs"}) + got, ok, err := c.LatestDispatchReply(context.Background(), "cncf/techdocs", 400, "/verify") + if err != nil || !ok { + t.Fatalf("LatestDispatchReply = %+v %v %v", got, ok, err) + } + if got.CommentID != 1 || got.Author != "writer" || got.URL != "u1" { + t.Fatalf("reply %+v; want comment 1 by writer", got) + } + if _, ok, _ := c.LatestDispatchReply(context.Background(), "cncf/techdocs", 400, ""); ok { + t.Fatal("empty reply matched") + } +} diff --git a/src/pkg/scheduler/workflow_dispatch.go b/src/pkg/scheduler/workflow_dispatch.go new file mode 100644 index 0000000000..a6191cca5d --- /dev/null +++ b/src/pkg/scheduler/workflow_dispatch.go @@ -0,0 +1,498 @@ +package scheduler + +import ( + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "sort" + "strconv" + "strings" + "sync" + "time" + + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +// Workflow-model agent dispatch, scheduler side (cncf/techdocs#395). +// +// A bound model hands some of its states to an agent profile +// (workflowmodel.Profile.Dispatch): TechDocs hands an Accepted request to +// techdocs-drafter and a Drafting PR, on the reviewer's /verify, to +// techdocs-verifier. Such an item is the profile's, not general work: +// +// - WithholdWorkflowOwned takes it out of the set every generic lane's +// kick is built from, so the scanner or a feature agent never grabs an +// Accepted request before the drafter; +// - PlanWorkflowDispatch picks, per item, the hive agent that fills the +// profile and the idempotency key of the hand-off (item, profile, +// state, and the triggering reply for a reply-started profile), so a +// hand-off happens once however many cycles or restarts pass; +// - BuildWorkflowDispatchPrompt renders what the agent is told. +// +// cmd/hive/workflow_dispatch.go wires these to the claim ledger, the kick +// dispatcher and the durable WorkflowDispatchLog. + +// WorkflowDispatchLookup answers "which profile owns this item now?" for +// an enumerated issue or pull request. *github.Client implements it. +type WorkflowDispatchLookup interface { + WorkflowDispatchForIssue(issue github.Issue) (github.WorkflowDispatch, bool) + WorkflowDispatchForPR(pr github.PullRequest) (github.WorkflowDispatch, bool) +} + +// WithholdWorkflowOwned returns actionable without the issues and pull +// requests whose bound model hands their current state to an agent +// profile, and how many it withheld. The input is never mutated: the +// result is a shallow copy with fresh item slices whenever anything is +// withheld, and actionable itself otherwise. +func WithholdWorkflowOwned(actionable *github.ActionableResult, lookup WorkflowDispatchLookup) (*github.ActionableResult, int) { + if actionable == nil || lookup == nil { + return actionable, 0 + } + issues := make([]github.Issue, 0, len(actionable.Issues.Items)) + withheld := 0 + for _, issue := range actionable.Issues.Items { + if _, owned := lookup.WorkflowDispatchForIssue(issue); owned { + withheld++ + continue + } + issues = append(issues, issue) + } + prs := make([]github.PullRequest, 0, len(actionable.PRs.Items)) + prWithheld := 0 + for _, pr := range actionable.PRs.Items { + if _, owned := lookup.WorkflowDispatchForPR(pr); owned { + prWithheld++ + continue + } + prs = append(prs, pr) + } + if withheld+prWithheld == 0 { + return actionable, 0 + } + out := *actionable + out.Issues.Items = issues + out.Issues.Count -= withheld + if out.Issues.Count < 0 { + out.Issues.Count = 0 + } + out.PRs.Items = prs + out.PRs.Count -= prWithheld + if out.PRs.Count < 0 { + out.PRs.Count = 0 + } + return &out, withheld + prWithheld +} + +// WorkflowDispatchKey is the idempotency key of one hand-off: the item, +// the profile and the state, plus the triggering comment for a profile +// started by a reply (each new /verify is a new pass). +func WorkflowDispatchKey(d github.WorkflowDispatch, trigger *github.DispatchReply) string { + key := d.Ref() + "|" + d.Target.Profile + "|" + d.State + if trigger != nil && trigger.CommentID > 0 { + key += "|" + strconv.FormatInt(trigger.CommentID, 10) + } + return key +} + +// WorkflowDispatchCandidate is one hand-off the dispatch pass may make. +type WorkflowDispatchCandidate struct { + Dispatch github.WorkflowDispatch + Agent string + Key string + Trigger *github.DispatchReply +} + +// WorkflowDispatchSkip is an item the plan did not hand off, and why. +type WorkflowDispatchSkip struct { + Ref string + Reason string +} + +// Skip reasons. +const ( + WorkflowSkipNoAgent = "no agent fills the profile" + WorkflowSkipIneligible = "agent paused or not eligible" + WorkflowSkipNoReply = "waiting for the reply" + WorkflowSkipReplyError = "reply lookup failed" + WorkflowSkipDone = "already dispatched" +) + +// WorkflowDispatchPlanDeps are the decisions PlanWorkflowDispatch defers. +type WorkflowDispatchPlanDeps struct { + // Agent resolves the hive agent that fills a profile. + Agent func(profile string) (string, bool) + // Eligible reports whether the agent may be kicked now (not paused, + // governor gate open). Nil admits every agent. + Eligible func(agent string) bool + // Reply returns the newest reply that starts a reply-triggered + // profile on the item; it is called only for such items. + Reply func(d github.WorkflowDispatch) (github.DispatchReply, bool, error) + // Done reports whether a key was already dispatched (durably or in + // flight). + Done func(key string) bool +} + +// PlanWorkflowDispatch decides which owned items to hand off now. Items +// are de-duplicated by reference (an item seen twice is planned once) and +// returned in reference order, so the plan is deterministic. +func PlanWorkflowDispatch(items []github.WorkflowDispatch, deps WorkflowDispatchPlanDeps) ([]WorkflowDispatchCandidate, []WorkflowDispatchSkip) { + seen := map[string]bool{} + sorted := append([]github.WorkflowDispatch(nil), items...) + sort.SliceStable(sorted, func(i, j int) bool { return sorted[i].Ref() < sorted[j].Ref() }) + var out []WorkflowDispatchCandidate + var skips []WorkflowDispatchSkip + for _, d := range sorted { + ref := d.Ref() + if seen[ref] { + continue + } + seen[ref] = true + agent, ok := "", false + if deps.Agent != nil { + agent, ok = deps.Agent(d.Target.Profile) + } + if !ok { + skips = append(skips, WorkflowDispatchSkip{Ref: ref, Reason: WorkflowSkipNoAgent}) + continue + } + if deps.Eligible != nil && !deps.Eligible(agent) { + skips = append(skips, WorkflowDispatchSkip{Ref: ref, Reason: WorkflowSkipIneligible}) + continue + } + var trigger *github.DispatchReply + if d.Target.Reply != "" { + if deps.Reply == nil { + skips = append(skips, WorkflowDispatchSkip{Ref: ref, Reason: WorkflowSkipNoReply}) + continue + } + r, found, err := deps.Reply(d) + if err != nil { + skips = append(skips, WorkflowDispatchSkip{Ref: ref, Reason: WorkflowSkipReplyError + ": " + err.Error()}) + continue + } + if !found { + skips = append(skips, WorkflowDispatchSkip{Ref: ref, Reason: WorkflowSkipNoReply}) + continue + } + trigger = &r + } + key := WorkflowDispatchKey(d, trigger) + if deps.Done != nil && deps.Done(key) { + skips = append(skips, WorkflowDispatchSkip{Ref: ref, Reason: WorkflowSkipDone}) + continue + } + out = append(out, WorkflowDispatchCandidate{Dispatch: d, Agent: agent, Key: key, Trigger: trigger}) + } + return out, skips +} + +// BuildWorkflowDispatchPrompt renders the kick for one hand-off. A +// non-empty template replaces the built-in prompt; ${VAR} placeholders +// (REF, REPO, NUMBER, TITLE, URL, KIND, MODEL, STATE, STATE_LABEL, PROFILE, +// AGENT, TRIGGER, INSTRUCTIONS, DELIVERABLE) are expanded in either. +func BuildWorkflowDispatchPrompt(c WorkflowDispatchCandidate, template string) string { + d := c.Dispatch + vars := workflowPromptVars(c) + if strings.TrimSpace(template) == "" { + template = defaultWorkflowDispatchTemplate(d) + } + pairs := make([]string, 0, len(vars)*2) + for k, v := range vars { + pairs = append(pairs, "${"+k+"}", v) + } + return strings.NewReplacer(pairs...).Replace(template) +} + +func workflowPromptVars(c WorkflowDispatchCandidate) map[string]string { + d := c.Dispatch + trigger := "entering the state" + if c.Trigger != nil { + trigger = fmt.Sprintf("`%s` from %s (%s)", d.Target.Reply, c.Trigger.Author, c.Trigger.URL) + } + label := d.Target.StateLabel + if label == "" { + label = d.State + } + return map[string]string{ + "REF": d.Ref(), + "REPO": d.Repo, + "NUMBER": strconv.Itoa(d.Number), + "TITLE": d.Title, + "URL": d.URL, + "KIND": workflowKindWord(d.Kind), + "MODEL": d.Model, + "STATE": d.State, + "STATE_LABEL": label, + "PROFILE": d.Target.Profile, + "AGENT": c.Agent, + "TRIGGER": trigger, + "INSTRUCTIONS": bulletList(d.Target.Instructions), + "DELIVERABLE": bulletList(workflowDeliverableLines(d)), + } +} + +func workflowKindWord(k workflowmodel.ItemKind) string { + if k == workflowmodel.KindPR { + return "pull request" + } + return "issue" +} + +func defaultWorkflowDispatchTemplate(d github.WorkflowDispatch) string { + var b strings.Builder + b.WriteString("## Workflow hand-off: ${PROFILE} for ${REF}\n\n") + b.WriteString("${REPO} is bound to the workflow model `${MODEL}`. The ${KIND} ${REF} (\"${TITLE}\", ${URL}) is in the model state **${STATE_LABEL}** (`${STATE}`), which the model hands to the `${PROFILE}` profile. You are that profile for this item. ") + if d.Kind == workflowmodel.KindIssue { + b.WriteString("The hive claimed the issue for you before this kick, and no other lane is offered it.") + } else { + b.WriteString("No other lane is offered it.") + } + b.WriteString("\n\nStarted by: ${TRIGGER}.\n\n") + if len(d.Target.Instructions) > 0 { + b.WriteString("What this state asks for:\n${INSTRUCTIONS}\n\n") + } + if len(d.Target.Tools) > 0 { + fmt.Fprintf(&b, "Tools the model grants this profile: %s.\n", strings.Join(d.Target.Tools, ", ")) + } + if len(d.Target.Produces) > 0 { + fmt.Fprintf(&b, "It may produce: %s.\n", strings.Join(d.Target.Produces, ", ")) + } + b.WriteString("\nDeliverable:\n${DELIVERABLE}\n\n") + b.WriteString("Read the ${KIND} and every comment on it first. Stop after the deliverable: each later step is a person's gate.\n") + return b.String() +} + +// workflowDeliverableLines is what the profile hands back, derived from the +// model: a pull request in the bound repository with the labels its +// target state requires, or a report on the item for a reviewing profile. +func workflowDeliverableLines(d github.WorkflowDispatch) []string { + t := d.Target + var lines []string + guarded := guardedLabels(d.Profile) + if t.Deliverable != nil { + labels := append([]string(nil), t.Deliverable.Labels...) + labels = append(labels, carriedLabels(d, labels)...) + pr := "a pull request" + if t.Deliverable.Draft { + pr = "a DRAFT pull request" + } + line := fmt.Sprintf("Work on a topic branch in %s and open %s", d.Repo, pr) + if len(labels) > 0 { + line += " labeled " + backtickJoin(labels) + } + lines = append(lines, line+".") + if d.Kind == workflowmodel.KindIssue { + lines = append(lines, + fmt.Sprintf("Name the issue in the PR request (`hive-open-pr --issues %d`) and reference it in the body with `Refs #%d`, not a closing keyword: the model closes the issue itself.", d.Number, d.Number)) + } + if t.Deliverable.Draft { + lines = append(lines, "Do not mark the pull request ready for review.") + } + } else { + lines = append(lines, fmt.Sprintf("Do the work on %s and post the result as one comment on it.", d.Ref())) + if !producesAny(t.Produces, "push", "pull-request", "pr") { + lines = append(lines, "Do not push commits and do not open a pull request.") + } + } + if len(guarded) > 0 { + lines = append(lines, "Do not apply "+backtickJoin(guarded)+": those labels record a person's gate.") + } + return lines +} + +// carriedLabels are the item's labels the model declares with no state of +// their own (TechDocs' phase/* labels), minus the ones already required. +func carriedLabels(d github.WorkflowDispatch, already []string) []string { + if d.Profile == nil { + return nil + } + plain := map[string]bool{} + for _, e := range d.Profile.Labels.Entries { + if e.State == "" { + plain[strings.ToLower(e.Name)] = true + } + } + have := map[string]bool{} + for _, l := range already { + have[strings.ToLower(l)] = true + } + for _, l := range guardedLabels(d.Profile) { + have[strings.ToLower(l)] = true + } + var out []string + for _, l := range d.Labels { + k := strings.ToLower(l) + if plain[k] && !have[k] { + have[k] = true + out = append(out, l) + } + } + return out +} + +func guardedLabels(p *workflowmodel.Profile) []string { + if p == nil { + return nil + } + seen := map[string]bool{} + var out []string + for _, l := range p.GuardedLabels { + if l == "" || strings.ContainsAny(l, "*?[") || seen[l] { + continue + } + seen[l] = true + out = append(out, l) + } + return out +} + +func producesAny(produces []string, want ...string) bool { + for _, p := range produces { + for _, w := range want { + if strings.EqualFold(strings.TrimSpace(p), w) { + return true + } + } + } + return false +} + +func backtickJoin(items []string) string { + q := make([]string, len(items)) + for i, s := range items { + q[i] = "`" + s + "`" + } + return strings.Join(q, ", ") +} + +func bulletList(lines []string) string { + var b strings.Builder + for i, l := range lines { + if i > 0 { + b.WriteString("\n") + } + b.WriteString("- " + strings.TrimSpace(l)) + } + return b.String() +} + +// WorkflowDispatchEntry is one durable hand-off record. +type WorkflowDispatchEntry struct { + Key string `json:"key"` + Ref string `json:"ref"` + Profile string `json:"profile"` + State string `json:"state"` + Agent string `json:"agent"` + By string `json:"by,omitempty"` + At time.Time `json:"at"` +} + +// workflowDispatchLogMax bounds the durable log; past it the oldest +// records are dropped (an item that old is long out of its state). +const workflowDispatchLogMax = 4096 + +// WorkflowDispatchLog is the durable record of hand-offs, so a restart +// never repeats one. A nil log or an empty path keeps records in memory. +type WorkflowDispatchLog struct { + path string + mu sync.Mutex + entries map[string]WorkflowDispatchEntry +} + +// OpenWorkflowDispatchLog loads the log at path. A missing file is an +// empty log; an unreadable or corrupt one is returned empty with the error, +// so the caller can warn and keep dispatching (a lost record can repeat a +// hand-off once; a refused open would stop them all). +func OpenWorkflowDispatchLog(path string) (*WorkflowDispatchLog, error) { + l := &WorkflowDispatchLog{path: path, entries: map[string]WorkflowDispatchEntry{}} + if path == "" { + return l, nil + } + b, err := os.ReadFile(path) + if errors.Is(err, os.ErrNotExist) { + return l, nil + } + if err != nil { + return l, fmt.Errorf("reading workflow dispatch log %s: %w", path, err) + } + var list []WorkflowDispatchEntry + if err := json.Unmarshal(b, &list); err != nil { + return l, fmt.Errorf("parsing workflow dispatch log %s: %w", path, err) + } + for _, e := range list { + if e.Key != "" { + l.entries[e.Key] = e + } + } + return l, nil +} + +// Done reports whether key was dispatched. +func (l *WorkflowDispatchLog) Done(key string) bool { + if l == nil { + return false + } + l.mu.Lock() + defer l.mu.Unlock() + _, ok := l.entries[key] + return ok +} + +// Record stores e and persists the log atomically. +func (l *WorkflowDispatchLog) Record(e WorkflowDispatchEntry) error { + if l == nil || e.Key == "" { + return nil + } + l.mu.Lock() + defer l.mu.Unlock() + l.entries[e.Key] = e + list := make([]WorkflowDispatchEntry, 0, len(l.entries)) + for _, v := range l.entries { + list = append(list, v) + } + sort.Slice(list, func(i, j int) bool { + if !list[i].At.Equal(list[j].At) { + return list[i].At.After(list[j].At) + } + return list[i].Key < list[j].Key + }) + if len(list) > workflowDispatchLogMax { + for _, v := range list[workflowDispatchLogMax:] { + delete(l.entries, v.Key) + } + list = list[:workflowDispatchLogMax] + } + if l.path == "" { + return nil + } + b, err := json.MarshalIndent(list, "", " ") + if err != nil { + return err + } + if err := os.MkdirAll(filepath.Dir(l.path), 0o750); err != nil { + return err + } + tmp := l.path + ".tmp" + if err := os.WriteFile(tmp, b, 0o600); err != nil { + return err + } + return os.Rename(tmp, l.path) +} + +// Entries returns the records, newest first. +func (l *WorkflowDispatchLog) Entries() []WorkflowDispatchEntry { + if l == nil { + return nil + } + l.mu.Lock() + defer l.mu.Unlock() + out := make([]WorkflowDispatchEntry, 0, len(l.entries)) + for _, v := range l.entries { + out = append(out, v) + } + sort.Slice(out, func(i, j int) bool { return out[i].At.After(out[j].At) }) + return out +} diff --git a/src/pkg/scheduler/workflow_dispatch_test.go b/src/pkg/scheduler/workflow_dispatch_test.go new file mode 100644 index 0000000000..67514b5d44 --- /dev/null +++ b/src/pkg/scheduler/workflow_dispatch_test.go @@ -0,0 +1,238 @@ +package scheduler + +import ( + "errors" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/workflowmodel" +) + +// fakeWorkflowLookup owns issue 395 (Accepted → drafter) and draft PR 400 +// (Drafting → verifier on /verify) of cncf/techdocs; everything else, +// including every other repository, is unowned. +type fakeWorkflowLookup struct{} + +func drafterDispatch() github.WorkflowDispatch { + return github.WorkflowDispatch{ + Repo: "cncf/techdocs", Number: 395, Kind: workflowmodel.KindIssue, Title: "Assess X", + URL: "https://github.com/cncf/techdocs/issues/395", Labels: []string{"Docs analysis", "phase/assessment", "triage/accepted"}, + Model: "cncf-techdocs-assessment@curated-2026.11.2", State: "accepted", + Target: workflowmodel.DispatchTarget{ + Profile: "techdocs-drafter", State: "accepted", StateLabel: "Accepted", + Produces: []string{"pull-request", "push"}, + Instructions: []string{"reviewer to delegate the phase drafter"}, + Deliverable: &workflowmodel.Deliverable{State: "drafting", Draft: true, Labels: []string{"Docs analysis"}}, + }, + Profile: &workflowmodel.Profile{ + GuardedLabels: []string{"triage/accepted", "verified", "confirmed"}, + Labels: workflowmodel.LabelSet{Entries: []workflowmodel.LabelEntry{ + {Name: "Docs analysis"}, {Name: "phase/assessment"}, {Name: "triage/accepted", State: "accepted"}, {Name: "verified", State: "in-review"}, + }}, + }, + } +} + +func verifierDispatch() github.WorkflowDispatch { + return github.WorkflowDispatch{ + Repo: "cncf/techdocs", Number: 400, Kind: workflowmodel.KindPR, Title: "Phase A draft", + Model: "cncf-techdocs-assessment@curated-2026.11.2", State: "drafting", + Target: workflowmodel.DispatchTarget{Profile: "techdocs-verifier", State: "drafting", Reply: "/verify", Produces: []string{"comment"}}, + Profile: &workflowmodel.Profile{GuardedLabels: []string{"verified"}}, + } +} + +func (fakeWorkflowLookup) WorkflowDispatchForIssue(issue github.Issue) (github.WorkflowDispatch, bool) { + if issue.Repo == "cncf/techdocs" && issue.Number == 395 { + return drafterDispatch(), true + } + return github.WorkflowDispatch{}, false +} + +func (fakeWorkflowLookup) WorkflowDispatchForPR(pr github.PullRequest) (github.WorkflowDispatch, bool) { + if pr.Repo == "cncf/techdocs" && pr.Number == 400 { + return verifierDispatch(), true + } + return github.WorkflowDispatch{}, false +} + +// Generic lanes never see a model-owned item; unbound repositories and +// unowned items pass through, and the input is not mutated. +func TestWithholdWorkflowOwned(t *testing.T) { + in := &github.ActionableResult{} + in.Issues.Items = []github.Issue{{Repo: "cncf/techdocs", Number: 395}, {Repo: "cncf/techdocs", Number: 396}, {Repo: "acme/widgets", Number: 395}} + in.Issues.Count = 3 + in.PRs.Items = []github.PullRequest{{Repo: "cncf/techdocs", Number: 400}, {Repo: "acme/widgets", Number: 9}} + in.PRs.Count = 2 + + out, withheld := WithholdWorkflowOwned(in, fakeWorkflowLookup{}) + if withheld != 2 { + t.Fatalf("withheld %d; want 2", withheld) + } + if len(out.Issues.Items) != 2 || out.Issues.Count != 2 || out.Issues.Items[0].Number != 396 || out.Issues.Items[1].Repo != "acme/widgets" { + t.Fatalf("issues %+v", out.Issues) + } + if len(out.PRs.Items) != 1 || out.PRs.Count != 1 || out.PRs.Items[0].Repo != "acme/widgets" { + t.Fatalf("prs %+v", out.PRs) + } + if len(in.Issues.Items) != 3 || len(in.PRs.Items) != 2 || in.Issues.Count != 3 { + t.Fatal("input was mutated") + } + + // Nothing owned: the same result comes back. + plain := &github.ActionableResult{} + plain.Issues.Items = []github.Issue{{Repo: "acme/widgets", Number: 1}} + if got, n := WithholdWorkflowOwned(plain, fakeWorkflowLookup{}); got != plain || n != 0 { + t.Fatalf("unowned set changed: %v %d", got, n) + } + if got, n := WithholdWorkflowOwned(plain, nil); got != plain || n != 0 { + t.Fatal("nil lookup changed the set") + } +} + +func planDeps(done map[string]bool) WorkflowDispatchPlanDeps { + return WorkflowDispatchPlanDeps{ + Agent: func(profile string) (string, bool) { return "writer", profile != "" }, + Done: func(key string) bool { return done[key] }, + } +} + +// The drafter is handed an Accepted issue once; a second plan with the key +// recorded hands nothing. +func TestPlanWorkflowDispatchOnce(t *testing.T) { + done := map[string]bool{} + items := []github.WorkflowDispatch{drafterDispatch(), drafterDispatch()} + cands, _ := PlanWorkflowDispatch(items, planDeps(done)) + if len(cands) != 1 || cands[0].Agent != "writer" || cands[0].Key != "cncf/techdocs#395|techdocs-drafter|accepted" { + t.Fatalf("first plan %+v", cands) + } + done[cands[0].Key] = true + cands, skips := PlanWorkflowDispatch(items, planDeps(done)) + if len(cands) != 0 || len(skips) != 1 || skips[0].Reason != WorkflowSkipDone { + t.Fatalf("second plan %+v skips %+v", cands, skips) + } +} + +func TestPlanWorkflowDispatchGates(t *testing.T) { + deps := planDeps(map[string]bool{}) + deps.Agent = func(string) (string, bool) { return "", false } + if cands, skips := PlanWorkflowDispatch([]github.WorkflowDispatch{drafterDispatch()}, deps); len(cands) != 0 || skips[0].Reason != WorkflowSkipNoAgent { + t.Fatalf("no agent: %+v %+v", cands, skips) + } + deps = planDeps(map[string]bool{}) + deps.Eligible = func(string) bool { return false } + if cands, skips := PlanWorkflowDispatch([]github.WorkflowDispatch{drafterDispatch()}, deps); len(cands) != 0 || skips[0].Reason != WorkflowSkipIneligible { + t.Fatalf("paused agent: %+v %+v", cands, skips) + } +} + +// The verifier waits for /verify; each new /verify comment is a new pass. +func TestPlanWorkflowDispatchReply(t *testing.T) { + done := map[string]bool{} + deps := planDeps(done) + if cands, skips := PlanWorkflowDispatch([]github.WorkflowDispatch{verifierDispatch()}, deps); len(cands) != 0 || skips[0].Reason != WorkflowSkipNoReply { + t.Fatalf("no reply lookup: %+v %+v", cands, skips) + } + var reply github.DispatchReply + found := false + deps.Reply = func(github.WorkflowDispatch) (github.DispatchReply, bool, error) { return reply, found, nil } + if cands, skips := PlanWorkflowDispatch([]github.WorkflowDispatch{verifierDispatch()}, deps); len(cands) != 0 || skips[0].Reason != WorkflowSkipNoReply { + t.Fatalf("no /verify yet: %+v %+v", cands, skips) + } + reply, found = github.DispatchReply{CommentID: 11, Author: "writer", URL: "u"}, true + cands, _ := PlanWorkflowDispatch([]github.WorkflowDispatch{verifierDispatch()}, deps) + if len(cands) != 1 || cands[0].Key != "cncf/techdocs#400|techdocs-verifier|drafting|11" || cands[0].Trigger == nil { + t.Fatalf("after /verify: %+v", cands) + } + done[cands[0].Key] = true + if cands, _ := PlanWorkflowDispatch([]github.WorkflowDispatch{verifierDispatch()}, deps); len(cands) != 0 { + t.Fatalf("same /verify dispatched twice: %+v", cands) + } + reply.CommentID = 12 + if cands, _ := PlanWorkflowDispatch([]github.WorkflowDispatch{verifierDispatch()}, deps); len(cands) != 1 { + t.Fatalf("a new /verify must start a new pass: %+v", cands) + } + deps.Reply = func(github.WorkflowDispatch) (github.DispatchReply, bool, error) { + return github.DispatchReply{}, false, errors.New("boom") + } + if _, skips := PlanWorkflowDispatch([]github.WorkflowDispatch{verifierDispatch()}, deps); !strings.HasPrefix(skips[0].Reason, WorkflowSkipReplyError) { + t.Fatalf("reply error: %+v", skips) + } +} + +// A restart reopens the log and still knows what was dispatched. +func TestWorkflowDispatchLogSurvivesRestart(t *testing.T) { + path := filepath.Join(t.TempDir(), "workflow-dispatch.json") + l, err := OpenWorkflowDispatchLog(path) + if err != nil { + t.Fatal(err) + } + key := WorkflowDispatchKey(drafterDispatch(), nil) + if l.Done(key) { + t.Fatal("fresh log already done") + } + if err := l.Record(WorkflowDispatchEntry{Key: key, Ref: "cncf/techdocs#395", Profile: "techdocs-drafter", State: "accepted", Agent: "writer", At: time.Now()}); err != nil { + t.Fatal(err) + } + reopened, err := OpenWorkflowDispatchLog(path) + if err != nil { + t.Fatal(err) + } + if !reopened.Done(key) || len(reopened.Entries()) != 1 { + t.Fatalf("restart lost the record: %+v", reopened.Entries()) + } + cands, _ := PlanWorkflowDispatch([]github.WorkflowDispatch{drafterDispatch()}, WorkflowDispatchPlanDeps{ + Agent: func(string) (string, bool) { return "writer", true }, + Done: reopened.Done, + }) + if len(cands) != 0 { + t.Fatalf("dispatched again after restart: %+v", cands) + } + var nilLog *WorkflowDispatchLog + if nilLog.Done(key) || nilLog.Record(WorkflowDispatchEntry{Key: key}) != nil { + t.Fatal("nil log misbehaved") + } +} + +func TestBuildWorkflowDispatchPrompt(t *testing.T) { + c := WorkflowDispatchCandidate{Dispatch: drafterDispatch(), Agent: "writer"} + msg := BuildWorkflowDispatchPrompt(c, "") + for _, want := range []string{ + "cncf/techdocs#395", + "techdocs-drafter", + "**Accepted**", + "hive-open-pr --issues 395", + "Refs #395", + "DRAFT pull request labeled `Docs analysis`, `phase/assessment`", + "Do not mark the pull request ready for review.", + "reviewer to delegate the phase drafter", + "claimed the issue for you", + "`verified`", + } { + if !strings.Contains(msg, want) { + t.Errorf("prompt missing %q:\n%s", want, msg) + } + } + if strings.Contains(msg, "${") { + t.Errorf("unexpanded placeholder:\n%s", msg) + } + if strings.Contains(msg, "labeled `Docs analysis`, `phase/assessment`, `triage/accepted`") { + t.Errorf("a gate label was carried over:\n%s", msg) + } + + v := WorkflowDispatchCandidate{Dispatch: verifierDispatch(), Agent: "writer", Trigger: &github.DispatchReply{CommentID: 1, Author: "nate", URL: "https://x/c1"}} + vmsg := BuildWorkflowDispatchPrompt(v, "") + for _, want := range []string{"`/verify` from nate (https://x/c1)", "post the result as one comment", "Do not push commits"} { + if !strings.Contains(vmsg, want) { + t.Errorf("verifier prompt missing %q:\n%s", want, vmsg) + } + } + + custom := BuildWorkflowDispatchPrompt(c, "Draft ${REF} as ${PROFILE} for ${AGENT}") + if custom != "Draft cncf/techdocs#395 as techdocs-drafter for writer" { + t.Fatalf("template %q", custom) + } +} From 9c52609a0f9d572d988e84f35cf5950be15cdbbe Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Mon, 16 Nov 2026 20:16:26 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20List=20a=20bound=20repositor?= =?UTF-8?q?y's=20drafts=20at=20most=20every=20five=20minutes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andy Anderson --- src/cmd/hive/workflow_dispatch.go | 39 +++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/src/cmd/hive/workflow_dispatch.go b/src/cmd/hive/workflow_dispatch.go index fa9a94022a..0c52bfc4c4 100644 --- a/src/cmd/hive/workflow_dispatch.go +++ b/src/cmd/hive/workflow_dispatch.go @@ -42,6 +42,11 @@ const workflowDispatchLogFile = "workflow-dispatch.json" // so the in-flight mark lapses on its own and the next cycle plans again. const workflowDispatchPendingTTL = 30 * time.Minute +// workflowDraftListTTL bounds how often one bound repository's open drafts +// are listed. Webhook-driven cycles can run minutes apart or less; a draft +// that appeared since is picked up within this window. +const workflowDraftListTTL = 5 * time.Minute + // workflowDispatchClaimTTL is the agent claim taken before the drafter is // kicked: long enough for a draft to reach its PR (the covering PR then // holds the issue), short enough that an abandoned hand-off frees it. @@ -55,6 +60,14 @@ type workflowDispatchRuntime struct { // replies caches LatestDispatchReply per item ref, keyed on the item's // updated_at: a new comment moves it, so an unchanged item costs no call. replies map[string]workflowReplyCacheEntry + // drafts caches ListWorkflowDraftPRs per repository for + // workflowDraftListTTL. + drafts map[string]workflowDraftCacheEntry +} + +type workflowDraftCacheEntry struct { + at time.Time + prs []github.PullRequest } type workflowReplyCacheEntry struct { @@ -63,7 +76,29 @@ type workflowReplyCacheEntry struct { found bool } -var workflowDispatchRT = &workflowDispatchRuntime{pending: map[string]time.Time{}, replies: map[string]workflowReplyCacheEntry{}} +var workflowDispatchRT = &workflowDispatchRuntime{pending: map[string]time.Time{}, replies: map[string]workflowReplyCacheEntry{}, drafts: map[string]workflowDraftCacheEntry{}} + +// draftsFor returns repo's open drafts, listing them at most once per +// workflowDraftListTTL. +func (rt *workflowDispatchRuntime) draftsFor(ctx context.Context, ghClient *github.Client, repo string, now time.Time) ([]github.PullRequest, error) { + rt.mu.Lock() + if rt.drafts == nil { + rt.drafts = map[string]workflowDraftCacheEntry{} + } + cached, ok := rt.drafts[repo] + rt.mu.Unlock() + if ok && now.Sub(cached.at) < workflowDraftListTTL { + return cached.prs, nil + } + prs, err := ghClient.ListWorkflowDraftPRs(ctx, repo) + if err != nil { + return nil, err + } + rt.mu.Lock() + rt.drafts[repo] = workflowDraftCacheEntry{at: now, prs: prs} + rt.mu.Unlock() + return prs, nil +} // dispatchLog opens the durable log once per process. func (rt *workflowDispatchRuntime) dispatchLog(cfg *config.Config, logger *slog.Logger) *scheduler.WorkflowDispatchLog { @@ -151,7 +186,7 @@ func workflowDispatchItems(ctx context.Context, cfg *config.Config, ghClient *gi if !dispatchesPRState(p) { continue } - drafts, err := ghClient.ListWorkflowDraftPRs(ctx, qualifyClaimRepo(cfg.Project.Org, b.Repo)) + drafts, err := workflowDispatchRT.draftsFor(ctx, ghClient, qualifyClaimRepo(cfg.Project.Org, b.Repo), time.Now()) if err != nil { if logger != nil { logger.Warn("workflow dispatch: listing drafts failed", "repo", b.Repo, "error", err)