Files
archie/modules/runs/handover.go
T

269 lines
10 KiB
Go

package runs
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"regexp"
"strings"
"time"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/modules/deliveries"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// maxCallDepth bounds how deep calls nest. A workflow that calls itself is
// not refused when it is saved, so this is also what stops it.
const maxCallDepth = 5
// maxCallWait is how long a waiting call holds out for its child before the
// step fails.
const maxCallWait = 7 * 24 * time.Hour
// callReference prefixes a call's input value that names an input of the
// calling workflow.
const callReference = "inputs."
var refName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
// callSettings start another workflow as a child run.
type callSettings struct {
Workflow string `yaml:"workflow" json:"workflow" jsonschema:"the workflow to start as a child run"`
Inputs map[string]any `yaml:"inputs,omitempty" json:"inputs,omitempty" jsonschema:"callee input names mapped to scalar literals or inputs.<name> references to caller inputs"`
Wait bool `yaml:"wait,omitempty" json:"wait,omitempty" jsonschema:"wait for the child run to finish before continuing"`
Outputs map[string]string `yaml:"outputs,omitempty" json:"outputs,omitempty" jsonschema:"callee output names mapped to outputs.<name> references to caller outputs; requires wait: true"`
}
func (s callSettings) valid() error {
if strings.TrimSpace(s.Workflow) == "" {
return errors.New("workflow is required")
}
for name, value := range s.Inputs {
if _, ok := value.(map[string]any); ok {
return fmt.Errorf("input %q must be a literal or an inputs.<name> reference, not a nested document", name)
}
if ref, ok := value.(string); ok && strings.HasPrefix(ref, callReference) && !isInputReference(ref) {
return fmt.Errorf("input %q reference %q must name an input as inputs.<name>", name, ref)
}
}
switch {
case len(s.Outputs) > 0 && !s.Wait:
return errors.New("outputs on a call that does not wait can never be read: nothing has finished when the caller moves on")
case len(s.Outputs) > 0:
return errors.New("outputs are not supported yet: a workflow can't declare outputs")
}
return nil
}
func (s callSettings) describe() string {
line := fmt.Sprintf("Starts %s as a child run", s.Workflow)
if s.Wait {
line += " and waits for it to finish"
}
return line
}
// isInputReference reports whether a string names an input of the calling
// workflow. A literal that begins with "inputs." but names no input is a
// literal.
func isInputReference(value string) bool {
name, ok := strings.CutPrefix(value, callReference)
return ok && refName.MatchString(name)
}
// callInputs turns the call's settings into the child's input: a reference
// reads the caller's own input, a literal passes through.
func callInputs(call, callerInputs map[string]any) (map[string]any, error) {
resolved := make(map[string]any, len(call))
for name, value := range call {
if ref, ok := value.(string); ok && isInputReference(ref) {
got, present := callerInputs[strings.TrimPrefix(ref, callReference)]
if !present {
return nil, fmt.Errorf("input %q references %q, which the calling run does not carry", name, ref)
}
resolved[name] = got
continue
}
resolved[name] = value
}
return resolved, nil
}
// runCall starts the child, and with wait true suspends the run until the
// child ends. The child is keyed by this run and step, so a replay or a
// restart finds the child it already started. The child's ending signals this
// run, which holds no worker while it waits.
func runCall(_ Deps, rc *Context, p *progress, name string, s callSettings) (StepResult, error) {
if rc.Dry() {
_, err := rc.Step("call-skipped", func(context.Context, string) (string, error) {
return s.Workflow, nil
})
return StepResult{Summary: "would start " + s.Workflow}, err
}
if rc.run.CallDepth+1 > maxCallDepth {
return StepResult{}, fmt.Errorf("call depth %d would pass the limit of %d", rc.run.CallDepth+1, maxCallDepth)
}
inputs, err := callInputs(s.Inputs, p.inputs)
if err != nil {
return StepResult{}, err
}
signal := callSignal(name)
child, err := rc.Step("call-start:"+name, func(ctx context.Context, _ string) (uuid.UUID, error) {
return rc.startRun(ctx, "call:"+rc.run.ID.String()+":"+name, s.Workflow, inputs, signal, rc.run.CallDepth+1)
})
if err != nil {
return StepResult{}, fmt.Errorf("start %q: %w", s.Workflow, err)
}
if !s.Wait {
return StepResult{Summary: fmt.Sprintf("started %q (run %s); no wait", s.Workflow, child)}, nil
}
payload, err := rc.Wait(signal, maxCallWait)
if err != nil {
return StepResult{}, err
}
return calleeResult(s.Workflow, child, payload)
}
// callSignal is the key a call's child signals when it ends.
func callSignal(name string) string { return "call:" + name }
// calleeEnding is what a child run tells its caller.
type calleeEnding struct {
State string `json:"state"`
Detail string `json:"detail"`
Error string `json:"error"`
Result jsontext.Value `json:"result"`
}
// calleeResult turns a child's ending into the call step's result. A child
// that did not succeed fails the step, with its own detail as the reason: a
// parked child will not move without an operator, so the caller does not wait
// for one.
func calleeResult(workflow string, child uuid.UUID, payload jsontext.Value) (StepResult, error) {
var end calleeEnding
if err := json.Unmarshal(payload, &end); err != nil {
return StepResult{}, fmt.Errorf("decode the ending of %q: %w", workflow, err)
}
if end.State != store.StateSucceeded {
return StepResult{}, fmt.Errorf("callee %q (run %s) ended %s: %s", workflow, child, end.State, firstText(end.Error, end.Detail))
}
var fields map[string]any
// A result that is not an object has no fields for a later step to read.
_ = json.Unmarshal(end.Result, &fields)
return StepResult{Summary: fmt.Sprintf("%q (run %s) finished", workflow, child), Result: fields}, nil
}
// startRun queues a run of another workflow for this run, idempotent on key.
func (rc *Context) startRun(ctx context.Context, key, workflow string, input map[string]any, signal string, depth int) (uuid.UUID, error) {
raw, err := json.Marshal(input)
if err != nil {
return uuid.Nil, fmt.Errorf("encode input: %w", err)
}
n, err := rc.resolve(ctx, StartRequest{OrgID: rc.run.OrgID, Workflow: workflow, Input: raw})
if err != nil {
return uuid.Nil, err
}
n.StartKey, n.ParentSignal, n.CallDepth = key, signal, depth
return rc.work.StartFor(ctx, rc.token, rc.run.ID, n)
}
// handoffSettings end the run and start another workflow with the same input.
type handoffSettings struct {
Workflow string `yaml:"workflow" json:"workflow" jsonschema:"the workflow the task is requeued under"`
Detail string `yaml:"detail,omitempty" json:"detail,omitempty" jsonschema:"why the task was handed off"`
}
func (s handoffSettings) valid() error {
if strings.TrimSpace(s.Workflow) == "" {
return errors.New("workflow is required")
}
return nil
}
func (s handoffSettings) describe() string {
return fmt.Sprintf("Ends the run and starts %s with the same input", s.Workflow)
}
// runHandoff completes the run and starts a run of the target workflow on the
// same input. A dry run records the handoff without starting anything.
func runHandoff(_ Deps, rc *Context, p *progress, name string, s handoffSettings) (StepResult, error) {
target := strings.TrimSpace(s.Workflow)
detail := s.Detail
if detail == "" {
detail = "handed off to " + target
}
if rc.Dry() {
if _, err := rc.Step("handoff-skipped", func(context.Context, string) (string, error) { return target, nil }); err != nil {
return StepResult{}, err
}
} else if _, err := rc.Step("handoff:"+name, func(ctx context.Context, _ string) (uuid.UUID, error) {
return rc.startRun(ctx, "handoff:"+rc.run.ID.String()+":"+name, target, p.inputs, "", rc.run.CallDepth)
}); err != nil {
return StepResult{}, fmt.Errorf("hand off to %q: %w", target, err)
}
rc.End(store.StateSucceeded, detail)
return StepResult{Summary: detail}, nil
}
// approveSettings put a plan to an operator and end the run until they decide.
type approveSettings struct {
Plan string `yaml:"plan,omitempty" json:"plan,omitempty" jsonschema:"what the operator decides on; the next workflow reads it as task.plan"`
Document any `yaml:"document,omitempty" json:"document,omitempty" jsonschema:"the plan as structured fields (title, problem, solution, files, acceptance, non_goals, diff_estimate, risks), such as {{ steps.prd.result }}; the plan text is rendered from it"`
Then string `yaml:"then" json:"then" jsonschema:"the workflow the task runs once approved"`
}
func (s approveSettings) valid() error {
if (strings.TrimSpace(s.Plan) == "" && s.Document == nil) || strings.TrimSpace(s.Then) == "" {
return errors.New("plan or document, and then, are required")
}
return nil
}
func (s approveSettings) describe() string {
return fmt.Sprintf("Delivers the plan and waits for approval; %s runs once it is approved", s.Then)
}
// handover is what an approval step records for whoever decides: the plan, in
// text and as the document it was rendered from, and the workflow to run once
// it is approved.
type handover struct {
Plan string `json:"plan"`
Document *planDocument `json:"document,omitzero"`
Then string `json:"then"`
}
// runApprove delivers the plan and ends the run waiting for approval. A dry
// run records the plan without delivering it.
func runApprove(d Deps, rc *Context, _ *progress, name string, s approveSettings) (StepResult, error) {
doc, err := readPlanDocument(s.Document)
if err != nil {
return StepResult{}, err
}
plan := s.Plan
if doc != nil {
plan = doc.markdown()
}
if strings.TrimSpace(plan) == "" {
return StepResult{}, errors.New("the plan is empty")
}
_, err = rc.Step("approve:"+name, func(ctx context.Context, key string) (handover, error) {
out := handover{Plan: plan, Document: doc, Then: strings.TrimSpace(s.Then)}
if rc.Dry() {
return out, nil
}
return out, d.Notifier.Notify(ctx, deliveries.Notification{
RunID: rc.RunID(), Key: key, Title: "Plan awaiting approval", Body: plan,
})
})
if err != nil {
return StepResult{}, err
}
const detail = "plan delivered, awaiting go/no-go"
rc.End(store.StateWaitingApproval, detail)
return StepResult{Summary: detail}, nil
}