Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-workflow-dispatch-send-to-profile.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The Activity Monitor offers owners **Send to *profile*** on a row of a model-bound repository whose state the model hands to an agent profile (Send to techdocs-drafter on an accepted TechDocs request, Send to techdocs-verifier on a draft PR), backed by the owner-only `POST /api/workflows/dispatch`, which claims the issue, kicks the agent and records the hand-off (audited `workflow_dispatch`).
89 changes: 89 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -38776,6 +38776,95 @@
}
}
},
"/api/workflows/dispatch": {
"post": {
"tags": [
"Workflows"
],
"summary": "Send a model-owned item to its agent profile",
"description": "Owner only. The stage tracker's \"Send to <profile>\" on a row of a repository bound to a workflow model whose current state the model hands to an agent profile (cncf/techdocs#395: Accepted -> techdocs-drafter, Drafting -> techdocs-verifier). Reads the item fresh, resolves its model state and the hive agent that fills the profile (workflow.dispatch.profiles.<profile>.agent; a profile disabled for automatic dispatch still resolves), takes the agent claim on an issue first, and kicks the agent with the dispatch prompt. Once the kick lands the hand-off is recorded in the dispatch log, so the automatic pass does not repeat it. Audited as workflow_dispatch.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"repo",
"number"
],
"properties": {
"repo": {
"type": "string",
"description": "owner/repo"
},
"number": {
"type": "integer"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Kick delivered",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"sent"
]
},
"ref": {
"type": "string"
},
"model": {
"type": "string"
},
"state": {
"type": "string"
},
"profile": {
"type": "string"
},
"agent": {
"type": "string"
},
"result": {
"type": "object",
"description": "Tracker toast: action dispatched, outcome, next"
}
}
}
}
}
},
"400": {
"description": "Body is not {repo, number}"
},
"403": {
"description": "Not an owner"
},
"404": {
"description": "The bound model does not hand the item's current state to a profile (or workflow.enabled is off)"
},
"409": {
"description": "No enabled agent fills the profile, someone else holds the issue's claim, or the agent is busy"
},
"502": {
"description": "The item could not be read or the kick failed"
},
"503": {
"description": "Dispatch is not wired on this hive"
}
}
}
},
"/api/workflows/enabled": {
"put": {
"tags": [
Expand Down
1 change: 1 addition & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -1125,6 +1125,7 @@ func (b *boot) wireBootClosures() {
},
WorkflowRepoFile: workflowRepoFile(func() *github.Client { return b.ghClient }),
WorkflowProvisionLabels: workflowProvisionLabels(b.cfg, func() *github.Client { return b.ghClient }, b.logger),
WorkflowDispatchPrepare: workflowDispatchPrepare(b.cfg, func() *github.Client { return b.ghClient }, b.logger),
WorkflowEmitChecks: workflowEmitChecks(b.cfg, func() *github.Client { return b.ghClient }),
WorkflowClusterRunner: workflowClusterRunner(),
WorkflowSpecLLM: newWorkflowSpecRunner(func() *config.Config { return b.cfg }),
Expand Down
43 changes: 43 additions & 0 deletions src/cmd/hive/workflow_dispatch.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,16 @@ package main

import (
"context"
"errors"
"fmt"
"log/slog"
"path/filepath"
"sync"
"time"

"github.com/hivecommons/hive/pkg/claims"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/dashboard"
"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/scheduler"
"github.com/hivecommons/hive/pkg/workflowmodel"
Expand Down Expand Up @@ -339,3 +342,43 @@ func releaseWorkflowDispatch(k workflowDispatchKick) { workflowDispatchRT.clearP
func workflowDispatchKickKey(msg scheduler.KickMessage) string {
return msg.Agent + "\x00" + msg.Message
}

// workflowDispatchPrepare is the dashboard's WorkflowDispatchPrepare: the
// owner's "Send to <profile>" through the same steps as the automatic
// pass (fresh item read, model state, agent, claim first, prompt). The
// handler kicks the agent and calls Record once the kick landed, so the
// automatic pass does not hand the same state off again.
func workflowDispatchPrepare(cfg *config.Config, client func() *github.Client, logger *slog.Logger) func(ctx context.Context, repo string, number int, by string, ledger *claims.Ledger) (dashboard.WorkflowDispatchPlan, error) {
return func(ctx context.Context, repo string, number int, by string, ledger *claims.Ledger) (dashboard.WorkflowDispatchPlan, error) {
gh := client()
if cfg == nil || gh == nil {
return dashboard.WorkflowDispatchPlan{}, errors.New("GitHub client unavailable")
}
if !cfg.Workflow.Enabled {
return dashboard.WorkflowDispatchPlan{}, fmt.Errorf("%w (workflow.enabled is off)", dashboard.ErrWorkflowDispatchNotOwned)
}
d, ok, err := gh.WorkflowDispatchForRef(ctx, qualifyClaimRepo(cfg.Project.Org, repo), number)
if err != nil {
return dashboard.WorkflowDispatchPlan{}, err
}
if !ok {
return dashboard.WorkflowDispatchPlan{}, dashboard.ErrWorkflowDispatchNotOwned
}
agent, ok := cfg.WorkflowDispatchAgentForManual(d.Target.Profile)
if !ok {
return dashboard.WorkflowDispatchPlan{}, fmt.Errorf("%w: %s", dashboard.ErrWorkflowDispatchNoAgent, d.Target.Profile)
}
c := scheduler.WorkflowDispatchCandidate{Dispatch: d, Agent: agent, Key: scheduler.WorkflowDispatchKey(d, nil), ManualBy: by}
if !claimForWorkflowDispatch(cfg, ledger, c, logger) {
return dashboard.WorkflowDispatchPlan{}, dashboard.ErrWorkflowDispatchHeld
}
entry := scheduler.WorkflowDispatchEntry{Key: c.Key, Ref: d.Ref(), Profile: d.Target.Profile, State: d.State, Agent: agent, By: by}
return dashboard.WorkflowDispatchPlan{
Ref: d.Ref(), Model: d.Model, State: d.State, Profile: d.Target.Profile, Agent: agent,
Message: scheduler.BuildWorkflowDispatchPrompt(c, cfg.Workflow.Dispatch.Profile(d.Target.Profile).PromptTemplate),
Record: func(at time.Time) {
recordWorkflowDispatchDelivered(cfg, workflowDispatchKick{Entry: entry}, at, logger)
},
}, nil
}
}
1 change: 1 addition & 0 deletions src/docs/api-reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,3 +128,4 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/config/governor/inference-auth` | Owner only | Governor Inference Auth Get | `pkg/dashboard/api.go:278` |
| `PUT` | `/api/config/governor/inference-auth` | Owner only | Governor Inference Auth Set | `pkg/dashboard/api.go:279` |
| `PUT` | `/api/workflows/enabled` | Owner only | Turn model-based stage derivation (`workflow.enabled`, [#17620](https://github.com/hivecommons/hive/issues/17620)) on or off from the dashboard, for hosted hives with no `hive.yaml` access. Body `{enabled: bool}`; persists `hive.yaml`; the stage engine and tracker read the live flag so it applies on the next derivation pass without a restart. Turning on also provisions every bound repository's model labels now (`warnings[]` lists repositories that could not be provisioned; the next sweep retries). Returns `{enabled, changed, bindings[], warnings?[]}`. Audited `workflow_enabled` / `workflow_disabled`; `400` on a non-boolean body | `pkg/dashboard/api_workflows.go:29` |
| `POST` | `/api/workflows/dispatch` | Owner only | Send a model-owned item to its agent profile: the stage tracker's **Send to *profile*** on a row whose bound model hands its current state to a profile ([cncf/techdocs#395](https://github.com/cncf/techdocs/issues/395): Accepted → `techdocs-drafter`, Drafting → `techdocs-verifier`). Body `{repo, number}`. Reads the item fresh, resolves the agent (`workflow.dispatch.profiles.<profile>.agent`; a profile disabled for automatic dispatch still resolves), takes the agent claim on an issue first, kicks the agent, and records the hand-off once the kick lands so the automatic pass does not repeat it. Returns `{status: "sent", ref, model, state, profile, agent, result}`. Audited `workflow_dispatch`; `404` when the model does not hand the state to a profile, `409` when no agent fills it, someone else holds the claim, or the agent is busy | `pkg/dashboard/api_workflows.go:30` |
8 changes: 8 additions & 0 deletions src/docs/design/workflow-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -728,6 +728,14 @@ Every eval cycle, with `workflow.enabled` on:
`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.

**Send to a profile.** The tracker payload's `workflows.repos[repo].dispatch` maps a stage
number to `{profile, state, kinds, reply}`; a row in such a state offers the owner **Send to *profile*** in its ⋯ menu (`stageTrackerWorkflowDispatchAction`), which posts
`POST /api/workflows/dispatch {repo, number}`. cmd/hive's `WorkflowDispatchPrepare` reads the
item fresh (`github.WorkflowDispatchForRef`), resolves the agent with
`Config.WorkflowDispatchAgentForManual` (a profile `disabled` for automatic dispatch still
resolves), claims an issue first and renders the prompt; the handler kicks the agent and, once
the kick lands, records the hand-off under the automatic key, so the pass does not repeat it.

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
Expand Down
16 changes: 13 additions & 3 deletions src/docs/workflows/techdocs-assessment.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,11 +257,21 @@ hand-off, and `workflow.dispatch.enabled: false` stops them all (owned items sta
from the generic lanes either way). `prompt_template` replaces the built-in prompt; see the
design doc for its `${VAR}` placeholders.

### Send to drafter (owner)

On the Activity Monitor, the **⋯** menu of a `cncf/techdocs` row in a dispatched state offers
**Send to techdocs-drafter** (an Accepted issue) or **Send to techdocs-verifier** (a draft PR in
Drafting). It is owner-only and runs the same hand-off on demand: it reads the item fresh,
resolves the agent (a profile set `disabled` for automatic dispatch still resolves), takes the
claim, kicks the agent and records the hand-off (`POST /api/workflows/dispatch`, audited
`workflow_dispatch`). Use it to restart after a discarded draft (a hand-off happens once per
issue and state on its own: retries are a person's choice, spec §5) or to run the verifier
without a `/verify` comment.

### 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:
When no agent fills the profile or the hive predates automatic dispatch, 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**.
Expand Down
13 changes: 12 additions & 1 deletion src/pkg/config/workflow_dispatch.go
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,17 @@ func (c WorkflowDispatchConfig) Profile(name string) WorkflowDispatchProfile {
// profile is disabled, or a configured agent does not exist (a typo never
// falls back to another agent).
func (c *Config) WorkflowDispatchAgent(profile string) (agent string, ok bool) {
return c.workflowDispatchAgent(profile, true)
}

// WorkflowDispatchAgentForManual is WorkflowDispatchAgent for the owner's
// "Send to <profile>": a profile disabled for automatic dispatch still
// resolves, since a person chose to hand the item off.
func (c *Config) WorkflowDispatchAgentForManual(profile string) (agent string, ok bool) {
return c.workflowDispatchAgent(profile, false)
}

func (c *Config) workflowDispatchAgent(profile string, honorDisabled bool) (agent string, ok bool) {
if c == nil {
return "", false
}
Expand All @@ -74,7 +85,7 @@ func (c *Config) WorkflowDispatchAgent(profile string) (agent string, ok bool) {
return "", false
}
set := c.Workflow.Dispatch.Profile(profile)
if set.Disabled {
if set.Disabled && honorDisabled {
return "", false
}
usable := func(name string) bool {
Expand Down
5 changes: 5 additions & 0 deletions src/pkg/config/workflow_dispatch_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,11 @@ func TestWorkflowDispatchAgent(t *testing.T) {
}
})
}
disabled := base()
disabled.Workflow.Dispatch.Profiles = map[string]WorkflowDispatchProfile{"techdocs-verifier": {Disabled: true}}
if got, ok := disabled.WorkflowDispatchAgentForManual("techdocs-verifier"); !ok || got != "alpha" {
t.Fatalf("manual send to a disabled profile = %q %v; want alpha", got, ok)
}
var nilCfg *Config
if _, ok := nilCfg.WorkflowDispatchAgent("x"); ok {
t.Fatal("nil config resolved an agent")
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/api_workflows.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ func (s *Server) registerWorkflowRoutes() {
s.mux.HandleFunc("GET /api/workflows/bindings", s.handleWorkflowBindingsGet)
s.mux.HandleFunc("PUT /api/workflows/bindings", s.handleWorkflowBindingPut)
s.mux.HandleFunc("PUT /api/workflows/enabled", s.handleWorkflowEnabledPut)
s.mux.HandleFunc("POST /api/workflows/dispatch", s.handleWorkflowDispatch)
s.mux.HandleFunc("GET /api/workflows/{name}/{version}", s.handleWorkflowGet)
s.mux.HandleFunc("PUT /api/workflows/{name}/{version}", s.handleWorkflowSave)
s.mux.HandleFunc("DELETE /api/workflows/{name}/{version}", s.handleWorkflowDelete)
Expand Down
134 changes: 134 additions & 0 deletions src/pkg/dashboard/api_workflows_dispatch.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
package dashboard

import (
"context"
"errors"
"fmt"
"net/http"
"strings"
"time"

"github.com/hivecommons/hive/crux"
"github.com/hivecommons/hive/pkg/claims"
)

// POST /api/workflows/dispatch: the owner's "Send to <profile>" on a
// stage-tracker row of a model-bound repository (cncf/techdocs#395).
//
// The automatic pass (cmd/hive/workflow_dispatch.go) hands an item to its
// model profile once per state. This is the same hand-off on demand: the
// restart after a discarded draft, a verifier pass without a `/verify`, or a
// profile turned off for automatic dispatch. cmd/hive prepares it through
// Dependencies.WorkflowDispatchPrepare (fresh item read, model state, agent,
// the agent claim, the prompt); the handler kicks the agent and, once the
// kick lands, records it in the dispatch log so the automatic pass does not
// repeat it.

// WorkflowDispatchPlan is one prepared hand-off.
type WorkflowDispatchPlan struct {
Ref string
Model string
State string
Profile string
Agent string
Message string
// Record writes the delivered hand-off to the dispatch log.
Record func(at time.Time)
}

// Errors WorkflowDispatchPrepare reports; the handler maps them to status
// codes.
var (
// ErrWorkflowDispatchNotOwned: the repository is not bound to a model
// that hands the item's current state to a profile.
ErrWorkflowDispatchNotOwned = errors.New("the bound workflow model does not hand this item's current state to an agent profile")
// ErrWorkflowDispatchNoAgent: no enabled hive agent fills the profile.
ErrWorkflowDispatchNoAgent = errors.New("no enabled agent fills the profile (workflow.dispatch.profiles.<profile>.agent)")
// ErrWorkflowDispatchHeld: someone else holds the issue's claim.
ErrWorkflowDispatchHeld = errors.New("the issue is claimed by someone else")
)

func (s *Server) handleWorkflowDispatch(w http.ResponseWriter, r *http.Request) {
if !requireOwnerRole(w, r) {
return
}
if s.deps == nil || s.deps.WorkflowDispatchPrepare == nil || s.deps.AgentMgr == nil {
jsonError(w, "workflow dispatch is not available on this hive", http.StatusServiceUnavailable)
return
}
var body struct {
Repo string `json:"repo"`
Number int `json:"number"`
}
if err := decodeBody(r, &body); err != nil {
jsonError(w, err.Error(), http.StatusBadRequest)
return
}
body.Repo = strings.TrimSpace(body.Repo)
if body.Repo == "" || body.Number <= 0 {
jsonError(w, "body must be {\"repo\": \"owner/repo\", \"number\": N}", http.StatusBadRequest)
return
}
by := requestUser(r)
plan, err := s.deps.WorkflowDispatchPrepare(r.Context(), body.Repo, body.Number, by, s.IssueClaims())
if err != nil {
jsonError(w, err.Error(), workflowDispatchStatus(err))
return
}
if err := s.deps.AgentMgr.SendKick(plan.Agent, plan.Message); err != nil {
status := http.StatusBadGateway
if errors.Is(err, crux.ErrAgentBusy) {
status = http.StatusConflict

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

If SendKick fails here, the 8h claim taken in Prepare stays held. Release it on error (add a Release func to WorkflowDispatchPlan and call it in this branch), or claim only after the kick.

}
jsonError(w, fmt.Sprintf("kick %s: %v", plan.Agent, err), status)
return
}
if s.deps.Governor != nil {
s.deps.Governor.RecordKick(plan.Agent)
}
if plan.Record != nil {
plan.Record(time.Now())
}
s.auditFromRequest(r, "workflow_dispatch", fmt.Sprintf("%s profile=%s state=%s model=%s", plan.Ref, plan.Profile, plan.State, plan.Model), plan.Agent)
jsonResponse(w, map[string]interface{}{
"status": "sent",
"ref": plan.Ref,
"model": plan.Model,
"state": plan.State,
"profile": plan.Profile,
"agent": plan.Agent,
// result is the tracker's toast: the hand-off is done when the kick
// lands, so the row does not wait for a state change (hours away).
"result": map[string]interface{}{
"action": workflowDispatchResultAction,
"outcome": fmt.Sprintf("Sent to %s (%s).", plan.Agent, plan.Profile),
"next": workflowDispatchNext(plan),
},
})
}

// workflowDispatchResultAction is the tracker result action of a sent
// hand-off.
const workflowDispatchResultAction = "dispatched"

func workflowDispatchNext(plan WorkflowDispatchPlan) string {
if plan.Profile == "" {
return ""
}
return "The " + plan.Profile + " agent works the item now; the row moves when its deliverable lands."
}

func workflowDispatchStatus(err error) int {
switch {
case errors.Is(err, ErrWorkflowDispatchNotOwned):
return http.StatusNotFound
case errors.Is(err, ErrWorkflowDispatchNoAgent), errors.Is(err, ErrWorkflowDispatchHeld):
return http.StatusConflict
case errors.Is(err, context.DeadlineExceeded):
return http.StatusGatewayTimeout
}
return http.StatusBadGateway
}

// workflowDispatchPrepareFunc is Dependencies.WorkflowDispatchPrepare.
type workflowDispatchPrepareFunc = func(ctx context.Context, repo string, number int, by string, ledger *claims.Ledger) (WorkflowDispatchPlan, error)
Loading
Loading