feat(workflow): step ids, {{ }} references to earlier results, agent.run result schemas, workflow.finish and on_failure

This commit is contained in:
sam committed 2026-10-05 00:02:07 +11:00
1 parent fba2d4ee09
commit 880a898ecb
7 files changed
+480 -30

No files matched your search

+66 -7
View File
@@ -11,11 +11,15 @@ import (
"github.com/samcharles93/archie-core/internal/domain/agentrun"
)
// AgentRunStepName is the step type that runs one agent mission and finishes
// the workflow with its summary. It needs no repository: the agent works in
// whatever workspace the task has, a worktree or a scratch directory.
// AgentRunStepName is the step type that runs one agent mission. It needs no
// repository: the agent works in whatever workspace the task has, a worktree
// or a scratch directory.
const AgentRunStepName = "agent.run"
// resultToolName is the capture tool through which an agent.run step with a
// result schema returns its structured result.
const resultToolName = "result"
// agentRunSettings are the agent.run step's settings.
type agentRunSettings struct {
// Mission is what the agent is asked to do. The workflow's inputs are
@@ -25,6 +29,12 @@ type agentRunSettings struct {
Role string `yaml:"role"`
// ReadOnly restricts the agent to read-only tools.
ReadOnly bool `yaml:"read_only"`
// Gate is "repository" to hold the agent to the repository's gate
// commands before it may finish; empty means ungated.
Gate string `yaml:"gate"`
// Result is a JSON Schema object. When set, the agent must return a value
// matching it, which later steps read as steps.<id>.result.
Result map[string]any `yaml:"result"`
}
// AgentRunStepType contributes the agent.run step type.
@@ -43,6 +53,13 @@ func newAgentRunStage(settings yaml.Node) (Stage, error) {
if strings.TrimSpace(s.Mission) == "" {
return Stage{}, fmt.Errorf("%s: settings.mission is required", AgentRunStepName)
}
if s.Gate != "" && s.Gate != "repository" {
return Stage{}, fmt.Errorf("%s: settings.gate is repository or empty, not %q", AgentRunStepName, s.Gate)
}
resultTool, err := agentResultTool(s.Result)
if err != nil {
return Stage{}, fmt.Errorf("%s: settings.result: %w", AgentRunStepName, err)
}
role := s.Role
if role == "" {
role = "builder"
@@ -53,10 +70,24 @@ func newAgentRunStage(settings yaml.Node) (Stage, error) {
ReadOnly: s.ReadOnly,
Mission: func(*TaskContext) string { return s.Mission },
OnResult: func(tc *TaskContext, res agentrun.Result) error {
tc.Outcome = Outcome{Status: StatusCompleted, Detail: res.Summary}
return nil
tc.stepResult.Summary = res.Summary
if resultTool == nil {
return nil
}
calls := res.Captures[resultToolName]
if len(calls) != 1 {
return fmt.Errorf("%s returned its result %d times (want exactly once)", AgentRunStepName, len(calls))
}
return json.Unmarshal(calls[0], &tc.stepResult.Result)
},
}.Stage()
}
if s.Gate == "repository" {
agent.Gate = func(tc *TaskContext) agentrun.Gate { return GateFromRepo(tc.Repo, tc.Cfg.Budgets) }
}
if resultTool != nil {
agent.CaptureTools = func(*TaskContext) []agentrun.CaptureTool { return []agentrun.CaptureTool{*resultTool} }
}
stage := agent.Stage()
return Stage{Name: AgentRunStepName, Run: func(ctx context.Context, tc *TaskContext) error {
if tc.Dir == "" {
dir, branch, err := tc.Trees.Prepare(ctx, tc.Task.Owner, tc.Task.Repo, tc.Repo.BaseBranch(), tc.Task.IssueNumber, tc.Task.Title, tc.Task.Body, tc.Task.Labels, PrepareFresh)
@@ -65,10 +96,38 @@ func newAgentRunStage(settings yaml.Node) (Stage, error) {
}
tc.Dir, tc.Branch = dir, branch
}
return agent.Run(ctx, tc)
return stage.Run(ctx, tc)
}}, nil
}
// agentResultTool is the capture tool for a result schema, or nil for none.
func agentResultTool(schema map[string]any) (*agentrun.CaptureTool, error) {
if schema == nil {
return nil, nil
}
if schema["type"] != "object" {
return nil, fmt.Errorf("must be a JSON Schema with type: object")
}
params, err := json.Marshal(schema)
if err != nil {
return nil, err
}
var required []string
if list, ok := schema["required"].([]any); ok {
for _, field := range list {
name, ok := field.(string)
if !ok {
return nil, fmt.Errorf("required lists field names")
}
required = append(required, name)
}
}
return &agentrun.CaptureTool{
Name: resultToolName, Description: "Return this step's result. Call exactly once, before finish.",
Parameters: params, RequiredFields: required, MaxCalls: 1,
}, nil
}
// missionWithInputs appends the task's workflow inputs to a mission as a JSON
// block, so the agent reads them as structured data rather than prose.
func missionWithInputs(t *Task, mission string) string {
+58 -10
View File
@@ -2,6 +2,7 @@ package workflow
import (
"bytes"
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
@@ -27,17 +28,23 @@ type YAMLDefinition struct {
// workflow whose repository is not required may use only these, since it may
// run with no worktree at all. workflow.call needs none of the caller's own:
// the callee's own repository mode decides whether its run clones.
var repoFreeStepTypes = map[string]bool{AgentRunStepName: true, WorkflowCallStepName: true}
var repoFreeStepTypes = map[string]bool{AgentRunStepName: true, WorkflowCallStepName: true, FinishStepName: true}
// NeedsRepository reports whether a step type can run only with a worktree.
func NeedsRepository(stepType string) bool { return !repoFreeStepTypes[stepType] }
// StepRecord selects one registered step type and supplies its typed settings.
type StepRecord struct {
// ID names the step so later steps can reference its result.
ID string `yaml:"id,omitempty" json:"id,omitempty"`
Type string `yaml:"type" json:"type"`
Settings yaml.Node `yaml:"settings,omitempty" json:"-"`
// OnFailure is "park" (the default) or "continue".
OnFailure string `yaml:"on_failure,omitempty" json:"on_failure,omitempty"`
}
const onFailureContinue = "continue"
type StepFactory func(yaml.Node) (Stage, error)
// StepRegistry is the closed set of safe workflow operations available to YAML.
@@ -61,21 +68,42 @@ func ParseDefinition(src string, registry StepRegistry) (YAMLDefinition, error)
return YAMLDefinition{}, fmt.Errorf("workflow %q: %w", definition.ID, err)
}
mode := definition.RepositoryMode()
earlier := map[string]bool{}
for i, step := range definition.Steps {
factory, ok := registry[step.Type]
if !ok {
return YAMLDefinition{}, fmt.Errorf("workflow %q step %d: unknown type %q", definition.ID, i+1, step.Type)
if err := checkStep(step, mode, earlier, registry); err != nil {
return YAMLDefinition{}, fmt.Errorf("workflow %q step %d: %w", definition.ID, i+1, err)
}
if mode != task.RepositoryRequired && NeedsRepository(step.Type) {
return YAMLDefinition{}, fmt.Errorf("workflow %q step %d: %q needs a repository, but the workflow's repository is %s", definition.ID, i+1, step.Type, mode)
}
if _, err := factory(step.Settings); err != nil {
return YAMLDefinition{}, fmt.Errorf("workflow %q step %q settings: %w", definition.ID, step.Type, err)
if step.ID != "" {
earlier[step.ID] = true
}
}
return definition, nil
}
// checkStep validates one step against the vocabulary and the steps before it.
func checkStep(step StepRecord, mode task.RepositoryMode, earlier map[string]bool, registry StepRegistry) error {
if err := checkStepID(step.ID, earlier); err != nil {
return err
}
if step.OnFailure != "" && step.OnFailure != "park" && step.OnFailure != onFailureContinue {
return fmt.Errorf("on_failure is park or continue, not %q", step.OnFailure)
}
factory, ok := registry[step.Type]
if !ok {
return fmt.Errorf("unknown type %q", step.Type)
}
if mode != task.RepositoryRequired && NeedsRepository(step.Type) {
return fmt.Errorf("%q needs a repository, but the workflow's repository is %s", step.Type, mode)
}
if err := checkReferences(step.Settings, earlier); err != nil {
return err
}
if _, err := factory(step.Settings); err != nil {
return fmt.Errorf("%q settings: %w", step.Type, err)
}
return nil
}
// Compile resolves a validated YAML definition to executable stages.
func Compile(definition YAMLDefinition, registry StepRegistry) (Workflow, error) {
stages := make([]Stage, 0, len(definition.Steps))
@@ -88,11 +116,31 @@ func Compile(definition YAMLDefinition, registry StepRegistry) (Workflow, error)
if err != nil {
return Workflow{}, fmt.Errorf("build workflow step %q: %w", step.Type, err)
}
stages = append(stages, stage)
stages = append(stages, compiledStep(step, stage.Name, factory))
}
return Workflow{Name: definition.ID, Stages: stages, Interface: definition.WorkflowInterface}, nil
}
// compiledStep builds the step's stage at run time from its settings with
// every reference resolved, and records what it leaves for later steps.
func compiledStep(step StepRecord, name string, factory StepFactory) Stage {
return Stage{Name: name, ContinueOnFailure: step.OnFailure == onFailureContinue, Run: func(ctx context.Context, tc *TaskContext) error {
tc.stepResult = StepResult{}
stage, err := factory(renderSettings(step.Settings, tc))
if err != nil {
return fmt.Errorf("step %q settings: %w", step.Type, err)
}
err = stage.Run(ctx, tc)
if step.ID != "" {
if tc.stepResults == nil {
tc.stepResults = map[string]StepResult{}
}
tc.stepResults[step.ID] = tc.stepResult
}
return err
}}
}
// ParseAndCompile validates and compiles one definition in a single operation.
func ParseAndCompile(src string, registry StepRegistry) (Workflow, error) {
definition, err := ParseDefinition(src, registry)
+49
View File
@@ -0,0 +1,49 @@
package workflow
import (
"context"
"fmt"
"gopkg.in/yaml.v3"
)
// FinishStepName is the step type that ends the workflow with a chosen outcome.
const FinishStepName = "workflow.finish"
// finishStatuses are the outcomes a workflow.finish step may choose.
var finishStatuses = map[string]string{
"completed": StatusCompleted,
"parked": StatusParked,
"waiting_human": StatusWaitingHuman,
"declined": StatusClosedWontDo,
}
type finishSettings struct {
Status string `yaml:"status"`
Detail string `yaml:"detail"`
}
// FinishStepType contributes the workflow.finish step type.
func FinishStepType() StepType {
return StepType{Name: FinishStepName, Factory: newFinishStage}
}
func newFinishStage(settings yaml.Node) (Stage, error) {
var s finishSettings
if settings.Kind != 0 {
if err := settings.Decode(&s); err != nil {
return Stage{}, fmt.Errorf("%s: %w", FinishStepName, err)
}
}
if s.Status == "" {
s.Status = "completed"
}
status, ok := finishStatuses[s.Status]
if !ok {
return Stage{}, fmt.Errorf("%s: settings.status is completed, parked, waiting_human or declined, not %q", FinishStepName, s.Status)
}
return Stage{Name: FinishStepName, Run: func(_ context.Context, tc *TaskContext) error {
tc.Outcome = Outcome{Status: status, Detail: s.Detail}
return nil
}}, nil
}
+160
View File
@@ -0,0 +1,160 @@
package workflow
import (
"encoding/json"
"fmt"
"maps"
"regexp"
"strings"
"gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/internal/domain/stableid"
)
// StepResult is what a finished step leaves for later steps to reference as
// steps.<id>.summary and steps.<id>.result.<field>.
type StepResult struct {
Summary string `json:"summary"`
Result map[string]any `json:"result,omitempty"`
}
// referencePattern matches {{ path }} in a step's string settings.
var referencePattern = regexp.MustCompile(`\{\{\s*([^{}\s]+)\s*\}\}`)
// checkReferences rejects a reference a run could not resolve: an unknown
// root, or a step id that is not declared by an earlier step.
func checkReferences(settings yaml.Node, earlier map[string]bool) error {
var problem error
walkStrings(&settings, func(value string) string {
for _, match := range referencePattern.FindAllStringSubmatch(value, -1) {
if err := checkReference(match[1], earlier); err != nil && problem == nil {
problem = err
}
}
return value
})
return problem
}
func checkReference(path string, earlier map[string]bool) error {
parts := strings.Split(path, ".")
switch parts[0] {
case "task", "inputs":
if len(parts) < 2 {
return fmt.Errorf("reference {{ %s }} names no field", path)
}
if parts[0] == "task" && !taskFields[parts[1]] {
return fmt.Errorf("reference {{ %s }}: task has no field %q", path, parts[1])
}
return nil
case "steps":
if len(parts) < 3 {
return fmt.Errorf("reference {{ %s }} must name a step and a field, e.g. steps.plan.summary", path)
}
if !earlier[parts[1]] {
return fmt.Errorf("reference {{ %s }}: no earlier step has id %q", path, parts[1])
}
if parts[2] != "summary" && parts[2] != "result" {
return fmt.Errorf("reference {{ %s }}: a step exposes summary and result", path)
}
return nil
}
return fmt.Errorf("reference {{ %s }} must start with task, inputs or steps", path)
}
var taskFields = map[string]bool{"title": true, "body": true, "prompt": true, "repository": true, "kind": true, "issue": true, "pr": true}
// renderSettings returns a copy of settings with every reference replaced by
// its value in this run. A reference to an absent value renders empty: a
// skipped earlier step leaves nothing behind, and that is not an error.
func renderSettings(settings yaml.Node, tc *TaskContext) yaml.Node {
scope := referenceScope(tc)
rendered := deepCopyNode(&settings)
walkStrings(rendered, func(value string) string {
return referencePattern.ReplaceAllStringFunc(value, func(token string) string {
path := referencePattern.FindStringSubmatch(token)[1]
return stringify(lookup(scope, strings.Split(path, ".")))
})
})
return *rendered
}
func referenceScope(tc *TaskContext) map[string]any {
t := tc.Task
steps := make(map[string]any, len(tc.stepResults))
for id, result := range tc.stepResults {
steps[id] = map[string]any{"summary": result.Summary, "result": result.Result}
}
inputs := map[string]any{}
maps.Copy(inputs, t.Inputs)
return map[string]any{
"task": map[string]any{
"title": t.Title, "body": t.Body, "prompt": taskPromptBlock(t),
"repository": tc.Repo.FullName(), "kind": taskKind(t),
"issue": t.IssueNumber, "pr": t.PRNumber,
},
"inputs": inputs,
"steps": steps,
}
}
func lookup(value any, path []string) any {
for _, key := range path {
object, ok := value.(map[string]any)
if !ok {
return nil
}
value = object[key]
}
return value
}
func stringify(value any) string {
switch v := value.(type) {
case nil:
return ""
case string:
return v
default:
encoded, err := json.Marshal(v)
if err != nil {
return fmt.Sprint(v)
}
return string(encoded)
}
}
// walkStrings rewrites every string scalar under node in place.
func walkStrings(node *yaml.Node, rewrite func(string) string) {
if node.Kind == yaml.ScalarNode && node.Tag == "!!str" {
node.Value = rewrite(node.Value)
}
for _, child := range node.Content {
walkStrings(child, rewrite)
}
}
func deepCopyNode(node *yaml.Node) *yaml.Node {
copied := *node
copied.Content = make([]*yaml.Node, len(node.Content))
for i, child := range node.Content {
copied.Content[i] = deepCopyNode(child)
}
return &copied
}
// checkStepID requires each declared step id to be a stable identifier and
// unique within the workflow.
func checkStepID(id string, seen map[string]bool) error {
if id == "" {
return nil
}
if !stableid.Valid(id) {
return fmt.Errorf("step id %q is not a stable identifier", id)
}
if seen[id] {
return fmt.Errorf("step id %q is declared twice", id)
}
return nil
}
+113
View File
@@ -0,0 +1,113 @@
package workflow
import (
"strings"
"testing"
"gopkg.in/yaml.v3"
)
func TestStepReferences(t *testing.T) {
registry := StepRegistry{AgentRunStepName: newAgentRunStage, FinishStepName: newFinishStage}
tests := []struct {
name string
yaml string
wantErr string
// rendered is the second step's mission after the first step left
// summary "the plan" and result {verdict: go}.
rendered string
}{
{
name: "earlier step summary and result resolve",
yaml: `id: w
repository: none
steps:
- id: plan
type: agent.run
settings: {mission: "plan {{ task.title }}"}
- type: agent.run
settings: {mission: "build {{ steps.plan.summary }} / {{ steps.plan.result.verdict }} / {{ steps.plan.result.missing }}"}
`,
rendered: "build the plan / go / ",
},
{
name: "a later step cannot be referenced",
yaml: `id: w
repository: none
steps:
- type: agent.run
settings: {mission: "{{ steps.plan.summary }}"}
- id: plan
type: agent.run
settings: {mission: x}
`,
wantErr: `no earlier step has id "plan"`,
},
{
name: "unknown root is refused",
yaml: `id: w
repository: none
steps:
- type: agent.run
settings: {mission: "{{ secrets.token }}"}
`,
wantErr: "must start with task, inputs or steps",
},
{
name: "duplicate step id is refused",
yaml: `id: w
repository: none
steps:
- {id: a, type: workflow.finish}
- {id: a, type: workflow.finish}
`,
wantErr: `step id "a" is declared twice`,
},
{
name: "on_failure takes park or continue",
yaml: `id: w
repository: none
steps:
- {type: workflow.finish, on_failure: retry}
`,
wantErr: "on_failure is park or continue",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
definition, err := ParseDefinition(tt.yaml, registry)
if tt.wantErr != "" {
if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
t.Fatalf("err = %v, want %q", err, tt.wantErr)
}
return
}
if err != nil {
t.Fatal(err)
}
tc := &TaskContext{Task: &Task{Title: "t"}, stepResults: map[string]StepResult{
"plan": {Summary: "the plan", Result: map[string]any{"verdict": "go"}},
}}
rendered := renderSettings(definition.Steps[1].Settings, tc)
var settings agentRunSettings
if err := rendered.Decode(&settings); err != nil {
t.Fatal(err)
}
if settings.Mission != tt.rendered {
t.Fatalf("mission = %q, want %q", settings.Mission, tt.rendered)
}
if original := yamlString(t, definition.Steps[1].Settings); !strings.Contains(original, "{{ steps.plan.summary }}") {
t.Fatalf("rendering changed the definition: %s", original)
}
})
}
}
func yamlString(t *testing.T, node yaml.Node) string {
t.Helper()
out, err := yaml.Marshal(&node)
if err != nil {
t.Fatal(err)
}
return string(out)
}
+33 -12
View File
@@ -74,6 +74,11 @@ type Trees interface {
// forward by mutating Task (persisted after every stage) and the
// scratch fields below.
type TaskContext struct {
// stepResult is what the running step leaves for later steps;
// stepResults holds each finished step's, by step id.
stepResult StepResult
stepResults map[string]StepResult
Task *Task
Repo config.Repo
Cfg config.Config
@@ -219,6 +224,9 @@ type Outcome struct {
type Stage struct {
Name string
Run func(ctx context.Context, tc *TaskContext) error
// ContinueOnFailure records a failed run and moves to the next stage
// instead of parking.
ContinueOnFailure bool
}
// Workflow is a named, ordered stage list.
@@ -350,21 +358,34 @@ func Run(ctx context.Context, wf Workflow, tc *TaskContext) {
}
publishEvent(tc, finishEvent)
if err != nil {
// Parking here publishes the failure; the store has already
// recorded the step that produced it.
t.ParkReason = fmt.Sprintf("stage %s: %v", stage.Name, err)
park(ctx, tc, t.ParkReason)
return
}
if tc.Outcome.Status != "" {
finish(ctx, tc, log)
if ended := endsRun(ctx, tc, stage, err, log, stageLog); ended {
return
}
}
// A workflow must end with an explicit outcome; not doing so is a
// definition bug, which still must not vanish silently.
park(ctx, tc, "workflow ended without an outcome (definition bug)")
// Running out of steps is success: the last step's summary says what was done.
tc.Outcome = Outcome{Status: StatusCompleted, Detail: tc.stepResult.Summary}
finish(ctx, tc, log)
}
// endsRun applies a recorded stage's result: a failure parks unless the stage
// continues on failure, and an outcome finishes the run.
func endsRun(ctx context.Context, tc *TaskContext, stage Stage, err error, log, stageLog *slog.Logger) bool {
if err != nil && stage.ContinueOnFailure {
stageLog.Warn("stage failed; continuing", "err", err)
return false
}
if err != nil {
// Parking here publishes the failure; the store has already
// recorded the step that produced it.
tc.Task.ParkReason = fmt.Sprintf("stage %s: %v", stage.Name, err)
park(ctx, tc, tc.Task.ParkReason)
return true
}
if tc.Outcome.Status != "" {
finish(ctx, tc, log)
return true
}
return false
}
// publishEvent puts an already-persisted event on the run's bus after its
@@ -42,7 +42,7 @@ type eventSteps struct{}
func (eventSteps) Name() string { return "event" }
func (eventSteps) StepTypes() []workflow.StepType {
return []workflow.StepType{workflow.AgentRunStepType(), workflow.WorkflowCallStepType()}
return []workflow.StepType{workflow.AgentRunStepType(), workflow.WorkflowCallStepType(), workflow.FinishStepType()}
}
// commandSteps provides the command.run step type: operator-authored commands