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-model-dispatch-targets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Workflow models resolve where each agent profile takes over an item (`spec.agents[].dispatch`, or by convention the grant's first state, on entry or on the gate reply for a reviewing profile), and `workflow.dispatch.profiles.<profile>.agent` maps a profile to a hive agent (default: an agent named after the profile, else a writer, docs or feature agent); the curated TechDocs model hands Accepted to `techdocs-drafter` and `/verify` to `techdocs-verifier`.
61 changes: 61 additions & 0 deletions src/docs/design/workflow-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -646,6 +646,67 @@ three places, all for a repository bound to a non-default model only:
still declares them; labels a model dropped *before* this change shipped are never reclaimed
automatically.

## Agent dispatch

A model's agent grants (`spec.agents`) say which profile may act in which states. The compiler
also resolves where the hive **hands an item to** a profile, and the compiled `Profile` carries
the result as `dispatch` (state id → `DispatchTarget`, `pkg/workflowmodel/dispatch.go`) next to
the grants themselves (`agents`).

**Where and when.** A grant may declare it:

```yaml
agents:
- profile: techdocs-verifier
states: [drafting]
produces: [comment]
dispatch:
states: [drafting] # subset of states; [] = never dispatch automatically
reply: /verify # empty: once on entering the state
instructions: Post the fact-check report as one PR comment.
```

Without a `dispatch` block the convention applies: the grant's **first** state is its entry
state. A profile that produces a pull request or a push is dispatched once on entering it. A
profile that produces neither (a verifier, a reviewer) is dispatched on the reply that releases
the gate out of its entry state into a non-terminal state, when the state declares that reply.
For the curated `cncf-techdocs-assessment` model this gives, with no new field:

| State | Profile | Trigger |
|-------|---------|---------|
| `accepted` (issue) | `techdocs-drafter` | on entry (`triage/accepted`, no covering PR) |
| `drafting` (PR) | `techdocs-verifier` | the reviewer's `/verify` |

Two profiles dispatched in one state, or a dispatch state outside the grant, refuse the compile
(`duplicate-dispatch`, `unknown-state`); a dispatch reply the state does not declare is a
`dispatch-reply-undeclared` warning. The built-in `hive-default` model never dispatches: its
grants describe the fleet that already runs it.

**Deliverable.** For a profile that produces a pull request, the target also names the
deliverable: the first pull-request state among the grant's later states, with the labels and
draft flag that state's first derivation rule requires (TechDocs: a draft PR labeled
`Docs analysis`, landing in `drafting`). The dispatch prompt asks for exactly that.

**Who fills a profile.** A model names roles; a hive names agents. `workflow.dispatch` maps one
to the other (`config.WorkflowDispatchAgent`):

```yaml
workflow:
dispatch:
enabled: true # default; dispatch also needs workflow.enabled
profiles:
techdocs-drafter:
agent: writer # default below
prompt_template: "" # default: the built-in prompt
techdocs-verifier:
disabled: true # never dispatch automatically
```

An unset `agent` resolves to an enabled agent named after the profile, else the first enabled
agent (by name) whose role is `writer`, then `docs`, then `feature`. A configured agent that does
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.

## 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
Expand Down
8 changes: 8 additions & 0 deletions src/hive.yaml.example
Original file line number Diff line number Diff line change
Expand Up @@ -1337,3 +1337,11 @@ data:
# workflow:
# enabled: false # false (default): bindings are columns only
# label_gc: true # delete labels a previous binding provisioned once nothing wears them
# dispatch: # hand model states to agents (docs/design/workflow-models.md#agent-dispatch)
# enabled: true # default; also needs enabled: true above
# profiles:
# techdocs-drafter:
# agent: writer # default: an agent named after the profile, else role writer, docs, feature
# prompt_template: "" # default: the built-in dispatch prompt
# techdocs-verifier:
# disabled: false # true: never dispatch automatically (Send to … still works)
3 changes: 3 additions & 0 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -310,6 +310,9 @@ type WorkflowConfig struct {
// Marketplace configures the spoke's view of the hub workflow catalogue
// (hivecommons/hive#17620 phase 7).
Marketplace MarketplaceConfig `yaml:"marketplace,omitempty" json:"marketplace,omitempty"`
// Dispatch maps a bound model's agent profiles to hive agents
// (workflow_dispatch.go).
Dispatch WorkflowDispatchConfig `yaml:"dispatch,omitempty" json:"dispatch,omitzero"`
}

// LabelGCEnabled is the effective workflow.label_gc (default true).
Expand Down
110 changes: 110 additions & 0 deletions src/pkg/config/workflow_dispatch.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
package config

import (
"sort"
"strings"
)

// WorkflowDispatchConfig is the `workflow.dispatch:` block: which hive agent
// fills each agent profile a bound workflow model hands items to
// (workflowmodel.DispatchTarget), and the prompt it is kicked with.
//
// workflow:
// dispatch:
// enabled: true # default
// profiles:
// techdocs-drafter:
// agent: writer # default: an agent named after the profile, else writer/docs/feature
// prompt_template: "" # default: the built-in dispatch prompt
// techdocs-verifier:
// disabled: true # never dispatch this profile automatically
type WorkflowDispatchConfig struct {
// Enabled turns automatic dispatch on. Nil means true: a model that
// declares a dispatch target and a fleet with an agent to fill it
// dispatches out of the box. Dispatch also needs workflow.enabled.
Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
// Profiles maps a model profile name to its hive-side settings.
Profiles map[string]WorkflowDispatchProfile `yaml:"profiles,omitempty" json:"profiles,omitempty"`
}

// WorkflowDispatchProfile is one profile's hive-side dispatch settings.
type WorkflowDispatchProfile struct {
// Agent is the hive agent the profile is handed to. Empty resolves by
// default (WorkflowDispatchAgent).
Agent string `yaml:"agent,omitempty" json:"agent,omitempty"`
// PromptTemplate replaces the built-in dispatch prompt. ${VAR}
// placeholders are expanded (docs/design/workflow-models.md lists them).
PromptTemplate string `yaml:"prompt_template,omitempty" json:"prompt_template,omitempty"`
// Disabled keeps the profile from being dispatched automatically; the
// dashboard's owner-only "Send to <profile>" still works.
Disabled bool `yaml:"disabled,omitempty" json:"disabled,omitempty"`
}

// DefaultWorkflowDispatchRoles are the agent roles a profile with no
// configured agent falls back to, in preference order.
var DefaultWorkflowDispatchRoles = []string{"writer", "docs", "feature"}

// DispatchEnabled is the effective workflow.dispatch.enabled (default true).
func (c WorkflowDispatchConfig) DispatchEnabled() bool {
return c.Enabled == nil || *c.Enabled
}

// Profile returns the settings for a model profile (zero when unset).
func (c WorkflowDispatchConfig) Profile(name string) WorkflowDispatchProfile {
if c.Profiles == nil {
return WorkflowDispatchProfile{}
}
return c.Profiles[strings.TrimSpace(name)]
}

// WorkflowDispatchAgent resolves the hive agent that fills a model profile:
// the configured workflow.dispatch.profiles.<profile>.agent when it names an
// enabled agent; else an enabled agent named after the profile; else the
// first enabled agent (by name) whose role is the earliest of
// DefaultWorkflowDispatchRoles. Replica overlays are never chosen: the base
// agent is the one kicked. ok is false when nothing fills the profile, the
// 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) {
if c == nil {
return "", false
}
profile = strings.TrimSpace(profile)
if profile == "" {
return "", false
}
set := c.Workflow.Dispatch.Profile(profile)
if set.Disabled {
return "", false
}
usable := func(name string) bool {
a, exists := c.Agents[name]
return exists && a.Enabled && a.ReplicaOf == ""
}
if want := strings.TrimSpace(set.Agent); want != "" {
return want, usable(want)
}
if usable(profile) {
return profile, true
}
names := make([]string, 0, len(c.Agents))
for name := range c.Agents {
names = append(names, name)
}
sort.Strings(names)
for _, role := range DefaultWorkflowDispatchRoles {
for _, name := range names {
if !usable(name) {
continue
}
r := c.Agents[name].Role
if r == "" {
r = name
}
if strings.EqualFold(r, role) {
return name, true
}
}
}
return "", false
}
66 changes: 66 additions & 0 deletions src/pkg/config/workflow_dispatch_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
package config

import "testing"

func TestWorkflowDispatchAgent(t *testing.T) {
off := false
base := func() *Config {
c := &Config{}
c.Agents = map[string]AgentConfig{
"scanner": {Enabled: true, Role: "scanner"},
"zed": {Enabled: true, Role: "feature"},
"alpha": {Enabled: true, Role: "feature"},
"alpha-2": {Enabled: true, Role: "feature", ReplicaOf: "alpha"},
"scribe": {Enabled: false, Role: "writer"},
"architect": {Enabled: true},
}
return c
}
cases := []struct {
name string
mut func(c *Config)
profile string
want string
ok bool
}{
{"role fallback picks the first feature agent by name", nil, "techdocs-drafter", "alpha", true},
{"a disabled writer is skipped", nil, "techdocs-drafter", "alpha", true},
{"enabled writer outranks feature", func(c *Config) { c.Agents["scribe"] = AgentConfig{Enabled: true, Role: "writer"} }, "techdocs-drafter", "scribe", true},
{"agent named after the profile", func(c *Config) { c.Agents["techdocs-drafter"] = AgentConfig{Enabled: true} }, "techdocs-drafter", "techdocs-drafter", true},
{"configured agent wins", func(c *Config) {
c.Workflow.Dispatch.Profiles = map[string]WorkflowDispatchProfile{"techdocs-drafter": {Agent: "architect"}}
}, "techdocs-drafter", "architect", true},
{"configured typo never falls back", func(c *Config) {
c.Workflow.Dispatch.Profiles = map[string]WorkflowDispatchProfile{"techdocs-drafter": {Agent: "nobody"}}
}, "techdocs-drafter", "nobody", false},
{"disabled profile", func(c *Config) {
c.Workflow.Dispatch.Profiles = map[string]WorkflowDispatchProfile{"techdocs-verifier": {Disabled: true}}
}, "techdocs-verifier", "", false},
{"no agent fills it", func(c *Config) {
c.Agents = map[string]AgentConfig{"scanner": {Enabled: true, Role: "scanner"}}
}, "techdocs-drafter", "", false},
{"empty profile", nil, "", "", false},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
c := base()
if tc.mut != nil {
tc.mut(c)
}
got, ok := c.WorkflowDispatchAgent(tc.profile)
if got != tc.want || ok != tc.ok {
t.Fatalf("WorkflowDispatchAgent(%q) = %q %v; want %q %v", tc.profile, got, ok, tc.want, tc.ok)
}
})
}
var nilCfg *Config
if _, ok := nilCfg.WorkflowDispatchAgent("x"); ok {
t.Fatal("nil config resolved an agent")
}
if !(WorkflowDispatchConfig{}).DispatchEnabled() {
t.Fatal("dispatch must default on")
}
if (WorkflowDispatchConfig{Enabled: &off}).DispatchEnabled() {
t.Fatal("enabled: false must turn dispatch off")
}
}
4 changes: 4 additions & 0 deletions src/pkg/dashboard/settings_parity_allowlist.txt
Original file line number Diff line number Diff line change
Expand Up @@ -630,6 +630,10 @@ project.workflow_bindings[].repo # see project.workflow_bindings[].name
project.workflow_bindings[].version # see project.workflow_bindings[].name
project.remote_write_identity # Settings control lands in the follow-up PR for #18516
workflow.label_gc # operator safety knob for model-label garbage collection on rebind; yaml-only, no Settings control planned (RFC #17620)
workflow.dispatch.enabled # workflow-model agent dispatch kill switch; yaml-only (cncf/techdocs#395)
workflow.dispatch.profiles.<key>.agent # which hive agent fills a model profile; yaml-only (cncf/techdocs#395)
workflow.dispatch.profiles.<key>.prompt_template # see workflow.dispatch.profiles.<key>.agent
workflow.dispatch.profiles.<key>.disabled # see workflow.dispatch.profiles.<key>.agent
inbox.sources[] # which voice connector types feed the Inbox; defaults to every configured plaud/wisprflow connector, yaml-only (Inbox RFC)
inbox.rules[].source # auto-routing rules are edited as whole rows in Inbox → Auto-routing via POST /api/inbox/settings, not leaf-path controls (Inbox RFC)
inbox.rules[].title_prefix # see inbox.rules[].source
Expand Down
24 changes: 24 additions & 0 deletions src/pkg/hub/marketplace/curated/curated_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -274,3 +274,27 @@ func TestEntriesSorted(t *testing.T) {
}
}
}

// TestTechDocsDispatch pins the agent hand-off the hive derives from the
// curated model without any new field (cncf/techdocs#395): the drafter is
// dispatched once when a request is Accepted and must open a draft PR
// labeled Docs analysis; the verifier runs on the reviewer's /verify in
// Drafting.
func TestTechDocsDispatch(t *testing.T) {
p := techdocs(t)
d, ok := p.DispatchFor("accepted")
if !ok || d.Profile != "techdocs-drafter" || d.Reply != "" || !d.AppliesTo(workflowmodel.KindIssue) {
t.Fatalf("accepted dispatch = %+v %v", d, ok)
}
want := &workflowmodel.Deliverable{State: "drafting", Draft: true, Labels: []string{"Docs analysis"}}
if !reflect.DeepEqual(d.Deliverable, want) {
t.Fatalf("drafter deliverable %+v want %+v", d.Deliverable, want)
}
v, ok := p.DispatchFor("drafting")
if !ok || v.Profile != "techdocs-verifier" || v.Reply != "/verify" || !v.AppliesTo(workflowmodel.KindPR) || v.Deliverable != nil {
t.Fatalf("drafting dispatch = %+v %v", v, ok)
}
if len(p.Dispatch) != 2 {
t.Fatalf("dispatch targets %+v", p.Dispatch)
}
}
11 changes: 11 additions & 0 deletions src/pkg/workflowmodel/compile.go
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,10 @@ const (
CodeUnknownEvent = "unknown-event"
CodeNoVersion = "no-version"
CodeInferred = "inferred-element"
// CodeDuplicateDispatch refuses two profiles dispatched in one state;
// CodeDispatchReply warns that a dispatch reply is not a state reply.
CodeDuplicateDispatch = "duplicate-dispatch"
CodeDispatchReply = "dispatch-reply-undeclared"
)

// ErrCompile wraps a compile refused by error diagnostics.
Expand Down Expand Up @@ -84,6 +88,12 @@ type Profile struct {
Replies map[string][]string `json:"replies,omitempty"`
// Labels is the label set to reconcile.
Labels LabelSet `json:"labels,omitzero"`
// Agents are the model's agent grants, as declared.
Agents []AgentGrant `json:"agents,omitempty"`
// Dispatch maps a state id to the profile the hive hands items in that
// state to (dispatch.go). Empty for hive-default and for a model with
// no agent grants.
Dispatch map[string]DispatchTarget `json:"dispatch,omitempty"`
// Diagnostics are the warnings left after a successful compile.
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
// replyEffects maps state id → NormalizeReply(verb) → the transition
Expand Down Expand Up @@ -189,6 +199,7 @@ func (c *compiler) run() {
c.roles()
c.events()
c.derivation()
c.dispatch()
c.inferred()
}

Expand Down
Loading
Loading