Plan item 4 of docs/prds/execution-tree-state-machine.md (archie-core-1216), plus the callee half of CancelExecution that plan item 5 deferred until the tree could decide it. Every agent call a stage makes records itself: AgentStage's bridge, the baseline-fix auto-fix run, the adversarial reviewer and a workflow.call each start a child StepExecution of kind agent or call under the stage's own step -- TaskContext.StepID, which the engine sets before the stage body starts and clears when it returns -- and finish it with the call's own outcome and the tokens it accounted. A child's recording write failure parks the execution the same way a stage's does: an agent call that ran unrecorded is the invisibility the step table exists to end. A stage invoked outside the engine's recorded run -- the stage unit tests -- records no child and runs unchanged. The call step is what makes the callee half of the PRD's Cancellation section decidable, and this lands it: a call step closes when its callee ends, so an open call step is a callee the caller waits on (wait:true) and a closed one is a wait:false callee that runs on. CancelExecution reads the open call steps before its sweep closes them and cancels each named callee through its own CancelExecution in the caller's write's aftermath -- the callee's own steps, its own events, its own move to the same destination, and the callee's own wait:true callees beyond it, the depth the enqueue enforces bounding the recursion. A callee that cannot be cancelled is reported and the caller's own record stands. StartStep refuses a call step whose callee is not this run's own (the callee's call_parent_task_id must name the recording execution): a compromised container could otherwise record a step naming a foreign execution and cancel it. StartStepRequest gains called_execution_id (field 6; non-breaking, the column and its named consumer already exist) and StepStart carries it. PRD decisions recorded here: - The reviewer records as one agent child named "review": the Reviewer contract runs one subagent per review, the PRD model's review:1/review:2 are illustrative of depth-1 children. A completed report closes it succeeded, a not-run review failed with the skip reason; the contract carries no usage, so tokens are 0. - A failed-callee call step closes as failed with the callee's detail when the wait ends otherwise; the single open case is the caller itself being cancelled, whose CancelExecution already swept this step -- a late write must not pretend the wait is still the caller's business. - A call step's callee is cancelled to the same destination the caller's action named (parked stays parked, closed_wont_do ends the whole chain), and a callee that cannot be cancelled is reported while the caller's own record stands either way. - The agent child's detail is the result summary on success and the error's text on failure, with the call's own TokensUsed -- the PRD's only usage field, untracked per call for the reviewer contract.
377 lines
14 KiB
Go
377 lines
14 KiB
Go
package workflow
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"maps"
|
|
"regexp"
|
|
"slices"
|
|
"strings"
|
|
"time"
|
|
|
|
"gopkg.in/yaml.v3"
|
|
|
|
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
|
|
"github.com/samcharles93/archie-core/internal/events"
|
|
"github.com/samcharles93/archie-core/internal/taskstate"
|
|
)
|
|
|
|
// WorkflowCallStepName is the step type that starts another workflow as its
|
|
// own run. The callee is a first-class task the State Store derives from the
|
|
// caller's row: its own pinned definition, its own agent profile, its own
|
|
// container and its own outcome (docs/prds/workflow-calls.md).
|
|
const WorkflowCallStepName = "workflow.call"
|
|
|
|
// MaxCallDepth bounds how deep one run may call callees. A cycle is refused
|
|
// at save, so the limit is not a loop guard -- it bounds a legitimate fan-out
|
|
// chain, and every wait:true caller on the path holds its container while it
|
|
// waits, so an unbounded depth would pin unbounded containers.
|
|
const MaxCallDepth = 5
|
|
|
|
// callPollInterval is how often a wait:true caller re-reads its callee's
|
|
// status. A var so tests do not sleep.
|
|
var callPollInterval = 2 * time.Second
|
|
|
|
// workflowCallSettings are the workflow.call step's settings. An inputs value
|
|
// is either a literal or a reference to the calling workflow's declared
|
|
// input, written "inputs.<name>" -- the PRD's `inputs: { src_ip:
|
|
// inputs.src_ip }` shape.
|
|
type workflowCallSettings struct {
|
|
Workflow string `yaml:"workflow"`
|
|
Inputs map[string]any `yaml:"inputs,omitempty"`
|
|
Wait bool `yaml:"wait,omitempty"`
|
|
}
|
|
|
|
// callReference is the prefix an inputs value must carry to be read as a
|
|
// reference to the calling workflow's declared input.
|
|
const callReference = "inputs."
|
|
|
|
// refName is the identifier grammar a reference suffix must match, shared
|
|
// with the workflow interface's input names.
|
|
var refName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
|
|
|
|
// WorkflowCallStepType contributes the workflow.call step type.
|
|
func WorkflowCallStepType() StepType {
|
|
return StepType{Name: WorkflowCallStepName, Factory: newWorkflowCallStage}
|
|
}
|
|
|
|
func newWorkflowCallStage(settings yaml.Node) (Stage, error) {
|
|
var s workflowCallSettings
|
|
if settings.Kind == 0 {
|
|
return Stage{}, fmt.Errorf("%s: settings.workflow is required", WorkflowCallStepName)
|
|
}
|
|
if err := settings.Decode(&s); err != nil {
|
|
return Stage{}, fmt.Errorf("%s: %w", WorkflowCallStepName, err)
|
|
}
|
|
if strings.TrimSpace(s.Workflow) == "" {
|
|
return Stage{}, fmt.Errorf("%s: settings.workflow is required", WorkflowCallStepName)
|
|
}
|
|
for name, value := range s.Inputs {
|
|
if _, ok := value.(map[string]any); ok {
|
|
return Stage{}, fmt.Errorf("%s: input %q must be a literal or an inputs.<name> reference, not a nested document", WorkflowCallStepName, name)
|
|
}
|
|
if ref, ok := value.(string); ok && strings.HasPrefix(ref, callReference) && !refName.MatchString(strings.TrimPrefix(ref, callReference)) {
|
|
return Stage{}, fmt.Errorf("%s: input %q reference %q must name an input as inputs.<name>", WorkflowCallStepName, name, ref)
|
|
}
|
|
}
|
|
return Stage{Name: WorkflowCallStepName, Run: func(ctx context.Context, tc *TaskContext) error {
|
|
return runWorkflowCall(ctx, s, tc)
|
|
}}, nil
|
|
}
|
|
|
|
// runWorkflowCall starts the callee and, with wait true, waits for its
|
|
// terminal state. The callee reports on its own run; the call is recorded on
|
|
// the caller's timeline.
|
|
func runWorkflowCall(ctx context.Context, s workflowCallSettings, tc *TaskContext) error {
|
|
if tc.Calls == nil {
|
|
return fmt.Errorf("%s: this runner carries no callee capability", WorkflowCallStepName)
|
|
}
|
|
if tc.Task.CallDepth+1 > MaxCallDepth {
|
|
return fmt.Errorf("%s: call depth %d would pass the limit of %d", WorkflowCallStepName, tc.Task.CallDepth+1, MaxCallDepth)
|
|
}
|
|
inputs, err := resolveCallInputs(s.Inputs, tc.Task.Inputs)
|
|
if err != nil {
|
|
return fmt.Errorf("%s: %w", WorkflowCallStepName, err)
|
|
}
|
|
callee, err := tc.Calls.StartCall(ctx, tc.Task.ID, s.Workflow, inputs)
|
|
if err != nil {
|
|
return fmt.Errorf("%s: start %q: %w", WorkflowCallStepName, s.Workflow, err)
|
|
}
|
|
started := map[string]any{"callee_task_id": callee.ID, "workflow": s.Workflow, "wait": s.Wait}
|
|
if err := tc.EmitDurable(ctx, events.KindWorkflowCallStarted, WorkflowCallStepName,
|
|
fmt.Sprintf("started %q as task %d", s.Workflow, callee.ID), started); err != nil {
|
|
tc.Log.Warn("workflow call start not persisted", "err", err)
|
|
}
|
|
// The call is a call StepExecution in the caller's tree, recording the
|
|
// callee's execution ID -- the store verifies the callee is this run's
|
|
// own callee, which is what makes "cancel the callees the caller waits
|
|
// on" decidable: an open call step is a waited-on callee, a closed one
|
|
// is a wait:false callee that runs on.
|
|
callStep, _, err := tc.startCallStep(ctx, callee.ID)
|
|
if err != nil {
|
|
return fmt.Errorf("%s: could not be recorded: %w", WorkflowCallStepName, err)
|
|
}
|
|
if !s.Wait {
|
|
// The call step closes at once: the callee runs on, and nothing the
|
|
// caller waits on remains open.
|
|
if err := tc.finishChildStep(ctx, callStep, taskstate.StepSucceeded,
|
|
fmt.Sprintf("started %q (task %d); no wait", s.Workflow, callee.ID), 0); err != nil {
|
|
return fmt.Errorf("%s: could not be closed: %w", WorkflowCallStepName, err)
|
|
}
|
|
return nil
|
|
}
|
|
// The wait ends when the callee ends, however it ended: a successful
|
|
// callee closes the call step as succeeded; a callee that ended otherwise
|
|
// closes it as failed with the callee's detail. The one open case is the
|
|
// caller itself being cancelled -- its CancelExecution already swept this
|
|
// step with the other non-terminal ones, so a late write here must not
|
|
// pretend the wait is still the caller's business.
|
|
waitErr := awaitCallee(ctx, s, tc, callee.ID)
|
|
if waitErr != nil {
|
|
if ctx.Err() == nil {
|
|
if ferr := tc.finishChildStep(ctx, callStep, taskstate.StepFailed, waitErr.Error(), 0); ferr != nil {
|
|
return fmt.Errorf("%s: could not be closed: %w", WorkflowCallStepName, ferr)
|
|
}
|
|
}
|
|
return waitErr
|
|
}
|
|
if err := tc.finishChildStep(ctx, callStep, taskstate.StepSucceeded,
|
|
fmt.Sprintf("%q (task %d) finished", s.Workflow, callee.ID), 0); err != nil {
|
|
return fmt.Errorf("%s: could not be closed: %w", WorkflowCallStepName, err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// startCallStep records the call step for a callee this run just started.
|
|
func (tc *TaskContext) startCallStep(ctx context.Context, calleeTaskID int64) (int64, events.Event, error) {
|
|
if tc.Store == nil {
|
|
return 0, events.Event{}, nil
|
|
}
|
|
stepID, event, err := tc.Store.StartStep(ctx, task.StepStart{
|
|
ExecutionID: tc.Task.ID, Attempt: tc.Task.Attempt, ParentID: tc.StepID,
|
|
Kind: task.StepKindCall, Name: WorkflowCallStepName, CalledExecutionID: calleeTaskID,
|
|
})
|
|
if err != nil {
|
|
return 0, events.Event{}, err
|
|
}
|
|
publishEvent(tc, event)
|
|
return stepID, event, nil
|
|
}
|
|
|
|
// resolveCallInputs turns the call's saved values into the callee's inputs: a
|
|
// reference reads the caller's actual input, a literal passes through.
|
|
func resolveCallInputs(call, callerInputs map[string]any) (map[string]any, error) {
|
|
if len(call) == 0 {
|
|
return nil, nil
|
|
}
|
|
resolved := make(map[string]any, len(call))
|
|
for name, value := range call {
|
|
if ref, ok := value.(string); ok && isCallReference(ref) {
|
|
got, present := callerInputs[strings.TrimPrefix(ref, callReference)]
|
|
if !present {
|
|
return nil, fmt.Errorf("input %q references %q, which the calling workflow's run does not carry", name, ref)
|
|
}
|
|
resolved[name] = got
|
|
continue
|
|
}
|
|
resolved[name] = value
|
|
}
|
|
return resolved, nil
|
|
}
|
|
|
|
// isCallReference reports whether a saved string value is a reference to the
|
|
// calling workflow's declared input. A literal that merely begins with
|
|
// "inputs." but does not name an input reads as the literal it is.
|
|
func isCallReference(value string) bool {
|
|
return strings.HasPrefix(value, callReference) && refName.MatchString(strings.TrimPrefix(value, callReference))
|
|
}
|
|
|
|
// callEnded reports whether a callee status ends the caller's wait. A parked
|
|
// callee ends it too: the callee will not move without an operator, so the
|
|
// caller must not wait for one.
|
|
func callEnded(status string) bool {
|
|
switch status {
|
|
case StatusCompleted, StatusPROpen, StatusMerged, StatusParked, StatusDead, StatusRejected, StatusClosedWontDo:
|
|
return true
|
|
default:
|
|
return false
|
|
}
|
|
}
|
|
|
|
// awaitCallee polls the callee until it is terminal, failing the stage with
|
|
// the callee's detail when the callee did not succeed. The caller's own wall
|
|
// clock bounds the wait.
|
|
func awaitCallee(ctx context.Context, s workflowCallSettings, tc *TaskContext, callTaskID int64) error {
|
|
for {
|
|
status, detail, err := tc.Calls.CallStatus(ctx, tc.Task.ID, callTaskID)
|
|
if err != nil {
|
|
return fmt.Errorf("%s: read task %d: %w", WorkflowCallStepName, callTaskID, err)
|
|
}
|
|
if callEnded(status) {
|
|
if callSucceeded(status) {
|
|
if err := tc.EmitDurable(ctx, events.KindWorkflowCallFinished, WorkflowCallStepName,
|
|
fmt.Sprintf("%q (task %d) finished: %s", s.Workflow, callTaskID, detail),
|
|
map[string]any{"callee_task_id": callTaskID, "workflow": s.Workflow, "status": status, "detail": detail}); err != nil {
|
|
tc.Log.Warn("workflow call finish not persisted", "err", err)
|
|
}
|
|
return nil
|
|
}
|
|
return fmt.Errorf("%s: callee %q (task %d) ended %s: %s", WorkflowCallStepName, s.Workflow, callTaskID, status, detail)
|
|
}
|
|
select {
|
|
case <-ctx.Done():
|
|
return ctx.Err()
|
|
case <-time.After(callPollInterval):
|
|
}
|
|
}
|
|
}
|
|
|
|
// callSucceeded reports whether a callee's terminal state satisfies its
|
|
// caller. pr_open and merged are successes: a repository callee opens its PR
|
|
// and reports on it as its own outcome.
|
|
func callSucceeded(status string) bool {
|
|
switch status {
|
|
case StatusCompleted, StatusPROpen, StatusMerged:
|
|
return true
|
|
default:
|
|
return false
|
|
}
|
|
}
|
|
|
|
// validateWorkflowCalls checks every workflow.call step against the rest of
|
|
// the collection: the callee must exist, the call's inputs must satisfy the
|
|
// callee's declared inputs, and no workflow may reach itself through calls
|
|
// (docs/prds/workflow-calls.md).
|
|
func validateWorkflowCalls(parsed map[string]YAMLDefinition) error {
|
|
calls := make(map[string][]string, len(parsed))
|
|
for id, d := range parsed {
|
|
for i, step := range d.Steps {
|
|
if step.Type != WorkflowCallStepName {
|
|
continue
|
|
}
|
|
s, err := decodeCallSettings(step)
|
|
if err != nil {
|
|
return fmt.Errorf("workflow %q step %d: %w", id, i+1, err)
|
|
}
|
|
callee, ok := parsed[s.Workflow]
|
|
if !ok {
|
|
return fmt.Errorf("workflow %q step %d calls %q, which is not defined", id, i+1, s.Workflow)
|
|
}
|
|
if err := checkCallInputs(id, i, d.WorkflowInterface, callee, s.Inputs); err != nil {
|
|
return err
|
|
}
|
|
calls[id] = append(calls[id], s.Workflow)
|
|
}
|
|
}
|
|
return refuseCallCycles(calls)
|
|
}
|
|
|
|
func decodeCallSettings(step StepRecord) (workflowCallSettings, error) {
|
|
var s workflowCallSettings
|
|
if err := step.Settings.Decode(&s); err != nil {
|
|
return workflowCallSettings{}, err
|
|
}
|
|
return s, nil
|
|
}
|
|
|
|
// checkCallInputs validates one call's saved inputs against the callee's
|
|
// declared inputs, resolving references against the calling workflow's own
|
|
// declared input types. Values are not known at save time -- types are.
|
|
func checkCallInputs(callerID string, index int, caller task.WorkflowInterface, callee YAMLDefinition, inputs map[string]any) error {
|
|
for name, value := range inputs {
|
|
spec, ok := callee.Inputs[name]
|
|
if !ok {
|
|
return fmt.Errorf("workflow %q step %d: input %q is not declared by %q", callerID, index+1, name, callee.ID)
|
|
}
|
|
resolved, err := callInputType(caller, name, value)
|
|
if err != nil {
|
|
return fmt.Errorf("workflow %q step %d: %w", callerID, index+1, err)
|
|
}
|
|
if resolved == "" {
|
|
// A null literal satisfies the type check vacuously; the
|
|
// callee's own run enforces it against the real value.
|
|
continue
|
|
}
|
|
if !task.TypeAccepts(spec.Type, resolved) {
|
|
return fmt.Errorf("workflow %q step %d: input %q is %s, want %s", callerID, index+1, name, resolved, spec.Type)
|
|
}
|
|
}
|
|
for name, spec := range callee.Inputs {
|
|
if _, assigned := inputs[name]; !assigned && spec.Required {
|
|
return fmt.Errorf("workflow %q step %d: input %q is required by %q", callerID, index+1, name, callee.ID)
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// callInputType names the type a saved call value carries at run time: a
|
|
// reference carries the calling workflow's declared input type, a literal its
|
|
// own JSON type. An error means the reference names an input the caller does
|
|
// not declare.
|
|
func callInputType(caller task.WorkflowInterface, name string, value any) (string, error) {
|
|
if ref, ok := value.(string); ok && isCallReference(ref) {
|
|
spec, ok := caller.Inputs[strings.TrimPrefix(ref, callReference)]
|
|
if !ok {
|
|
return "", fmt.Errorf("input %q references %q, which the calling workflow does not declare", name, ref)
|
|
}
|
|
return spec.Type, nil
|
|
}
|
|
if value == nil {
|
|
return "", nil
|
|
}
|
|
return task.ValueType(value), nil
|
|
}
|
|
|
|
// refuseCallCycles walks the call graph from every workflow and refuses one
|
|
// that reaches itself, directly or through other workflows, naming the path.
|
|
func refuseCallCycles(calls map[string][]string) error {
|
|
const (
|
|
unseen = 0
|
|
open = 1
|
|
done = 2
|
|
)
|
|
state := make(map[string]int, len(calls))
|
|
var path []string
|
|
var walk func(id string) error
|
|
walk = func(id string) error {
|
|
state[id] = open
|
|
path = append(path, id)
|
|
defer func() { state[id] = done; path = path[:len(path)-1] }()
|
|
for _, callee := range calls[id] {
|
|
switch state[callee] {
|
|
case open:
|
|
cycle := append(append([]string{}, path[cycleStart(path, callee):]...), callee)
|
|
return fmt.Errorf("workflow %q calls itself through %s", callee, strings.Join(cycle, " -> "))
|
|
case unseen:
|
|
if err := walk(callee); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
// Sorted, not range-order: a map iteration order picks a different DFS
|
|
// root on every run, so an operator reading "calls itself through b ->
|
|
// a -> b" one time and "a -> b -> a" the next would see the same cycle
|
|
// reported two different ways with nothing having changed.
|
|
for _, id := range slices.Sorted(maps.Keys(calls)) {
|
|
if state[id] == unseen {
|
|
if err := walk(id); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// cycleStart finds where the open path enters the cycle, so the reported path
|
|
// runs from the cycle's first workflow rather than from the DFS root.
|
|
func cycleStart(path []string, cycleRoot string) int {
|
|
for i, id := range path {
|
|
if id == cycleRoot {
|
|
return i
|
|
}
|
|
}
|
|
return 0
|
|
}
|