262 lines
7.8 KiB
Go
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"))))
|
|
}
|