Files
archie/modules/runs/document.go
T

262 lines
7.8 KiB
Go

package runs
import (
"bytes"
_ "embed" // the starter workflow documents
"errors"
"fmt"
"io"
"regexp"
"strings"
"time"
"gopkg.in/yaml.v3"
"github.com/samcharles93/archie-core/internal/platform/prompts"
)
//go:embed workflows/investigate.yaml
var investigateDocument string
// InvestigateDocument is the workflow document that has an agent look into the
// event that started the run, put what it proposes to people, and report.
func InvestigateDocument() string { return investigateDocument }
// Document is a workflow as data: an ordered list of steps the engine
// executes. It is stored, diffed and validated as text.
type Document struct {
Steps []Step `yaml:"steps"`
}
// Step is one step of a document. Exactly one of the kinds is set.
type Step struct {
ID string `yaml:"id"`
Agent *AgentStep `yaml:"agent"`
Action *ActionStep `yaml:"action"`
WaitForApproval *ApprovalStep `yaml:"wait_for_approval"`
Notify *NotifyStep `yaml:"notify"`
Sleep *SleepStep `yaml:"sleep"`
}
// AgentStep runs a tool-using agent on the event. Prompt names one of the
// binary's prompts. Memory gives the agent the lookup of a target's earlier
// incidents and files what the run found and did once it ends.
type AgentStep struct {
Prompt string `yaml:"prompt"`
Memory bool `yaml:"memory"`
}
// ActionStep judges one connector action and runs it if judgement lets it run
// unattended. A string input value written {{event.path}} is replaced by the
// value at that path of the event.
type ActionStep struct {
Connector string `yaml:"connector"`
Name string `yaml:"name"`
Input map[string]any `yaml:"input"`
}
// ApprovalStep puts every action judgement held so far to people, and runs the
// ones they allow.
type ApprovalStep struct{}
// NotifyStep tells people what the run found. Title replaces the default.
type NotifyStep struct {
Title string `yaml:"title"`
}
// SleepStep suspends the run for a duration such as "30s".
type SleepStep struct {
For string `yaml:"for"`
}
// maxSleep bounds a sleep step.
const maxSleep = 24 * time.Hour
var stepID = regexp.MustCompile(`^[a-z][a-z0-9-]{0,62}$`)
// Problem is one thing wrong with a document, at the path of the field.
type Problem struct {
Path string `json:"path"`
Message string `json:"message"`
}
func (p Problem) String() string { return p.Path + ": " + p.Message }
// InvalidError is the problems found in a document.
type InvalidError struct {
Problems []Problem `json:"problems"`
}
func (e *InvalidError) Error() string {
parts := make([]string, len(e.Problems))
for i, p := range e.Problems {
parts[i] = p.String()
}
return "invalid workflow: " + strings.Join(parts, "; ")
}
// ParseDocument reads a document and validates it. Fields it doesn't know are
// an error, so a misspelt option is never silently ignored.
func ParseDocument(body string) (Document, error) {
var doc Document
dec := yaml.NewDecoder(strings.NewReader(body))
dec.KnownFields(true)
if err := dec.Decode(&doc); err != nil {
if errors.Is(err, io.EOF) {
return Document{}, &InvalidError{Problems: []Problem{{Path: "steps", Message: "a workflow needs steps"}}}
}
return Document{}, &InvalidError{Problems: yamlProblems(err)}
}
if err := dec.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
return Document{}, &InvalidError{Problems: []Problem{{Path: "document", Message: "one workflow per document"}}}
}
if problems := doc.validate(); len(problems) > 0 {
return Document{}, &InvalidError{Problems: problems}
}
return doc, nil
}
var unknownField = regexp.MustCompile(`^(line \d+): field (\S+) not found`)
// yamlProblems turns the decoder's errors into one problem each, an unknown
// field at its line.
func yamlProblems(err error) []Problem {
var typed *yaml.TypeError
if !errors.As(err, &typed) {
return []Problem{{Path: "document", Message: strings.TrimPrefix(err.Error(), "yaml: ")}}
}
out := make([]Problem, 0, len(typed.Errors))
for _, e := range typed.Errors {
if m := unknownField.FindStringSubmatch(e); m != nil {
out = append(out, Problem{Path: m[1], Message: "unknown field " + m[2]})
continue
}
out = append(out, Problem{Path: "document", Message: e})
}
return out
}
// checker collects the problems found in a document's steps.
type checker struct {
problems []Problem
ids map[string]bool
proposes, approves, ran bool
}
func (c *checker) add(path, format string, args ...any) {
c.problems = append(c.problems, Problem{Path: path, Message: fmt.Sprintf(format, args...)})
}
func (d Document) validate() []Problem {
c := &checker{ids: map[string]bool{}}
if len(d.Steps) == 0 {
c.add("steps", "a workflow needs steps")
}
for i, s := range d.Steps {
c.step(fmt.Sprintf("steps[%d]", i), s)
}
if c.proposes && !c.approves {
c.add("steps", "an agent or action step needs a wait_for_approval step, since judgement can hold what it proposes")
}
return c.problems
}
func (c *checker) step(at string, s Step) {
switch {
case !stepID.MatchString(s.ID):
c.add(at+".id", "a step id is lowercase letters, digits and hyphens, starting with a letter")
case c.ids[s.ID]:
c.add(at+".id", "step id %q is used twice", s.ID)
}
c.ids[s.ID] = true
if n := s.kinds(); n != 1 {
c.add(at, "a step has exactly one of agent, action, wait_for_approval, notify and sleep, found %d", n)
return
}
c.kind(at, s)
}
func (c *checker) kind(at string, s Step) {
switch {
case s.Agent != nil:
c.proposes = true
if c.ran {
c.add(at+".agent", "only one agent step per workflow")
}
c.ran = true
if _, ok := prompts.Agent(s.Agent.Prompt); !ok {
c.add(at+".agent.prompt", "no prompt named %q", s.Agent.Prompt)
}
case s.Action != nil:
c.proposes = true
if s.Action.Connector == "" || s.Action.Name == "" {
c.add(at+".action", "an action needs a connector and a name")
}
case s.WaitForApproval != nil:
if c.approves {
c.add(at+".wait_for_approval", "only one step can wait for approval")
}
c.approves = true
case s.Sleep != nil:
if dur, err := time.ParseDuration(s.Sleep.For); err != nil || dur <= 0 || dur > maxSleep {
c.add(at+".sleep.for", "a duration between 1s and 24h, such as 30s")
}
}
}
func (s Step) kinds() int {
n := 0
for _, set := range []bool{s.Agent != nil, s.Action != nil, s.WaitForApproval != nil, s.Notify != nil, s.Sleep != nil} {
if set {
n++
}
}
return n
}
// hasAgent reports whether any step runs an agent, and whether one uses memory.
func (d Document) hasAgent() (agent, memory bool) {
for _, s := range d.Steps {
if s.Agent != nil {
agent = true
memory = memory || s.Agent.Memory
}
}
return agent, memory
}
// Describe says in plain language what each step does.
func (d Document) Describe() []string {
out := make([]string, 0, len(d.Steps))
for _, s := range d.Steps {
switch {
case s.Agent != nil:
line := "An agent investigates the event, looking things up and proposing actions, each judged before it runs"
if s.Agent.Memory {
line += "; it recalls earlier incidents and files what it found"
}
out = append(out, line)
case s.Action != nil:
out = append(out, fmt.Sprintf("Runs %s %s once judged", s.Action.Connector, s.Action.Name))
case s.WaitForApproval != nil:
out = append(out, "Waits for approval before anything judgement holds runs")
case s.Notify != nil:
out = append(out, "Reports what it found and did")
case s.Sleep != nil:
out = append(out, "Waits "+s.Sleep.For)
}
}
return out
}
// duration is a sleep step's duration; validation has already accepted it.
func (s SleepStep) duration() time.Duration {
d, _ := time.ParseDuration(s.For)
return d
}
// normalise is the form two documents are compared in.
func normalise(body string) string {
return string(bytes.TrimSpace([]byte(strings.ReplaceAll(body, "\r\n", "\n"))))
}