From 90d06c2455cf15decd260aa731bdc80be29cd256 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 5 Oct 2026 00:02:07 +1100 Subject: [PATCH] feat(workflow): step ids, {{ }} references to earlier results, agent.run result schemas, workflow.finish and on_failure --- internal/domain/workflow/agent_run.go | 73 +++++++- internal/domain/workflow/definition.go | 68 ++++++-- internal/domain/workflow/finish_step.go | 49 ++++++ internal/domain/workflow/step_refs.go | 160 ++++++++++++++++++ internal/domain/workflow/step_refs_test.go | 113 +++++++++++++ internal/domain/workflow/workflow.go | 45 +++-- .../workflowsteps/workflowsteps.go | 2 +- 7 files changed, 480 insertions(+), 30 deletions(-) create mode 100644 internal/domain/workflow/finish_step.go create mode 100644 internal/domain/workflow/step_refs.go create mode 100644 internal/domain/workflow/step_refs_test.go diff --git a/internal/domain/workflow/agent_run.go b/internal/domain/workflow/agent_run.go index a550c5df8..5bbc3fe66 100644 --- a/internal/domain/workflow/agent_run.go +++ b/internal/domain/workflow/agent_run.go @@ -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..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 { diff --git a/internal/domain/workflow/definition.go b/internal/domain/workflow/definition.go index 57ea6d75d..86d345f53 100644 --- a/internal/domain/workflow/definition.go +++ b/internal/domain/workflow/definition.go @@ -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) diff --git a/internal/domain/workflow/finish_step.go b/internal/domain/workflow/finish_step.go new file mode 100644 index 000000000..c29d34991 --- /dev/null +++ b/internal/domain/workflow/finish_step.go @@ -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 +} diff --git a/internal/domain/workflow/step_refs.go b/internal/domain/workflow/step_refs.go new file mode 100644 index 000000000..02215e8c2 --- /dev/null +++ b/internal/domain/workflow/step_refs.go @@ -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..summary and steps..result.. +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 +} diff --git a/internal/domain/workflow/step_refs_test.go b/internal/domain/workflow/step_refs_test.go new file mode 100644 index 000000000..b01624b54 --- /dev/null +++ b/internal/domain/workflow/step_refs_test.go @@ -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) +} diff --git a/internal/domain/workflow/workflow.go b/internal/domain/workflow/workflow.go index bb72fba16..a0969d0b5 100644 --- a/internal/domain/workflow/workflow.go +++ b/internal/domain/workflow/workflow.go @@ -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 diff --git a/internal/infrastructure/workflowsteps/workflowsteps.go b/internal/infrastructure/workflowsteps/workflowsteps.go index 1be075605..e29e5331c 100644 --- a/internal/infrastructure/workflowsteps/workflowsteps.go +++ b/internal/infrastructure/workflowsteps/workflowsteps.go @@ -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