Also fix repository-free message.send validation (#2046) and add a single-binary development smoke path (#1977). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
307 lines
10 KiB
Go
307 lines
10 KiB
Go
package runs
|
|
|
|
import (
|
|
"context"
|
|
json "encoding/json/v2"
|
|
"errors"
|
|
"fmt"
|
|
"slices"
|
|
"time"
|
|
|
|
"github.com/google/jsonschema-go/jsonschema"
|
|
"gopkg.in/yaml.v3"
|
|
|
|
"github.com/samcharles93/archie-core/modules/deliveries"
|
|
"github.com/samcharles93/archie-core/modules/governance"
|
|
"github.com/samcharles93/archie-core/modules/judgement"
|
|
)
|
|
|
|
// The step types the engine runs.
|
|
const (
|
|
typeAgent = "agent.run"
|
|
typeAction = "connector.action"
|
|
typeApproval = "approval.wait"
|
|
typeNotify = "run.notify"
|
|
typeSleep = "workflow.sleep"
|
|
)
|
|
|
|
// StepType defines a workflow step's settings and implementation.
|
|
type StepType struct {
|
|
Name string `json:"name"`
|
|
// Title is the label shown in workflow editors.
|
|
Title string `json:"title"`
|
|
// NeedsRepository restricts the step type to workflows that require a repository.
|
|
NeedsRepository bool `json:"needs_repository"`
|
|
// Settings is the JSON Schema of the type's settings.
|
|
Settings *jsonschema.Schema `json:"settings"`
|
|
|
|
check func(yaml.Node) error
|
|
describe func(yaml.Node) string
|
|
run func(d Deps, rc *Context, p *progress, name string, settings yaml.Node) (StepResult, error)
|
|
}
|
|
|
|
// define builds a step type whose settings decode strictly into T. valid
|
|
// rejects settings a run could not use.
|
|
func define[T any](name, title string, valid func(T) error, describe func(T) string, run func(Deps, *Context, *progress, string, T) (StepResult, error)) StepType {
|
|
schema, err := jsonschema.For[T](nil)
|
|
if err != nil {
|
|
panic(fmt.Sprintf("step type %s: settings schema: %v", name, err))
|
|
}
|
|
decode := func(node yaml.Node) (T, error) {
|
|
var s T
|
|
if err := decodeSettings(node, &s); err != nil {
|
|
return s, err
|
|
}
|
|
return s, valid(s)
|
|
}
|
|
return StepType{
|
|
Name: name, Title: title, Settings: schema,
|
|
check: func(node yaml.Node) error {
|
|
_, err := decode(node)
|
|
return err
|
|
},
|
|
describe: func(node yaml.Node) string {
|
|
s, err := decode(node)
|
|
if err != nil {
|
|
return title
|
|
}
|
|
return describe(s)
|
|
},
|
|
run: func(d Deps, rc *Context, p *progress, stepName string, node yaml.Node) (StepResult, error) {
|
|
s, err := decode(node)
|
|
if err != nil {
|
|
return StepResult{}, fmt.Errorf("step %q settings: %w", stepName, err)
|
|
}
|
|
return run(d, rc, p, stepName, s)
|
|
},
|
|
}
|
|
}
|
|
|
|
// stepTypes is the closed vocabulary a document may name. It is built once and
|
|
// never changed.
|
|
var stepTypes = vocabulary(
|
|
define(typeAgent, "Run an agent", agentSettings.valid, agentSettings.describe, runAgent),
|
|
define(typeAction, "Run a connector action", actionSettings.valid, actionSettings.describe, runAction),
|
|
define(typeApproval, "Wait for approval", noSettings.valid, func(noSettings) string {
|
|
return "Requests approval for actions held by judgement and runs approved actions"
|
|
}, runApprovalWait),
|
|
define(typeNotify, "Report the findings", notifySettings.valid, notifySettings.describe, runNotify),
|
|
define(typeSleep, "Wait", sleepSettings.valid, sleepSettings.describe, runSleep),
|
|
)
|
|
|
|
func vocabulary(types ...StepType) map[string]StepType {
|
|
out := make(map[string]StepType, len(types))
|
|
for _, t := range types {
|
|
out[t.Name] = t
|
|
}
|
|
return out
|
|
}
|
|
|
|
// StepTypes is the vocabulary, in name order, for editors and the catalog.
|
|
func StepTypes() []StepType {
|
|
out := make([]StepType, 0, len(stepTypes))
|
|
for _, name := range sortedKeys(stepTypes) {
|
|
out = append(out, stepTypes[name])
|
|
}
|
|
return out
|
|
}
|
|
|
|
type agentSettings struct {
|
|
Mission string `yaml:"mission" json:"mission" jsonschema:"the task the agent should perform"`
|
|
Memory bool `yaml:"memory,omitempty" json:"memory,omitempty" jsonschema:"retrieve previous incidents for the target and store new findings"`
|
|
ReadOnly bool `yaml:"read_only,omitempty" json:"read_only,omitempty" jsonschema:"restrict the agent to read-only tools"`
|
|
ExtraRules string `yaml:"extra_rules,omitempty" json:"extra_rules,omitempty" jsonschema:"appended to the agent's system prompt"`
|
|
Model string `yaml:"model,omitempty" json:"model,omitempty" jsonschema:"organisation model alias; omit to use the default"`
|
|
// Result defines the output schema. Later steps can read the validated
|
|
// output at steps.<id>.result.
|
|
Result map[string]any `yaml:"result,omitempty" json:"result,omitempty" jsonschema:"JSON Schema for the object the agent must return; later steps read the result at steps.<id>.result"`
|
|
}
|
|
|
|
func (s agentSettings) valid() error {
|
|
if s.Mission == "" {
|
|
return errors.New("an agent needs a mission")
|
|
}
|
|
if err := governance.ValidateAgentModelAlias(s.Model); err != nil {
|
|
return err
|
|
}
|
|
if s.Result != nil {
|
|
if _, _, err := s.resultSchema(); err != nil {
|
|
return fmt.Errorf("result: %w", err)
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func (s agentSettings) describe() string {
|
|
line := "The agent looks up information and proposes actions for judgement before execution"
|
|
if s.ReadOnly {
|
|
line = "The agent can only use read-only tools"
|
|
}
|
|
if s.Result != nil {
|
|
line += "; it returns a structured result"
|
|
}
|
|
if s.Memory {
|
|
line += "; it retrieves previous incidents and stores new findings"
|
|
}
|
|
return line
|
|
}
|
|
|
|
type actionSettings struct {
|
|
Connector string `yaml:"connector" json:"connector"`
|
|
Name string `yaml:"name" json:"name"`
|
|
Input map[string]any `yaml:"input,omitempty" json:"input,omitempty"`
|
|
}
|
|
|
|
func (s actionSettings) valid() error {
|
|
if s.Connector == "" || s.Name == "" {
|
|
return errors.New("an action needs a connector and a name")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func (s actionSettings) describe() string {
|
|
return fmt.Sprintf("Submits %s %s for judgement and runs it if allowed to run unattended", s.Connector, s.Name)
|
|
}
|
|
|
|
type noSettings struct{}
|
|
|
|
func (noSettings) valid() error { return nil }
|
|
|
|
type notifySettings struct {
|
|
Title string `yaml:"title,omitempty" json:"title,omitempty"`
|
|
}
|
|
|
|
func (notifySettings) valid() error { return nil }
|
|
func (notifySettings) describe() string { return "Reports the run's findings and actions" }
|
|
|
|
// maxSleep bounds a sleep step.
|
|
const maxSleep = 24 * time.Hour
|
|
|
|
// sleepSettings suspend the run for a duration such as "30s".
|
|
type sleepSettings struct {
|
|
For string `yaml:"for" json:"for" jsonschema:"a duration between 1s and 24h, such as 30s"`
|
|
}
|
|
|
|
func (s sleepSettings) valid() error {
|
|
if d, err := time.ParseDuration(s.For); err != nil || d <= 0 || d > maxSleep {
|
|
return errors.New("for is a duration between 1s and 24h, such as 30s")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func (s sleepSettings) describe() string { return "Waits " + s.For }
|
|
|
|
func (s sleepSettings) duration() time.Duration {
|
|
d, _ := time.ParseDuration(s.For)
|
|
return d
|
|
}
|
|
|
|
// runAction executes only actions allowed to run unattended. A later
|
|
// approval step handles actions held for approval.
|
|
func runAction(d Deps, rc *Context, p *progress, name string, s actionSettings) (StepResult, error) {
|
|
input := s.Input
|
|
if input == nil {
|
|
input = map[string]any{}
|
|
}
|
|
in, err := json.Marshal(input)
|
|
if err != nil {
|
|
return StepResult{}, fmt.Errorf("step %q: encode input: %w", name, err)
|
|
}
|
|
decision, err := rc.Step("judge:"+name, func(ctx context.Context, key string) (judgement.Decision, error) {
|
|
return d.Judge.Assess(ctx, rc.request(key, s.Connector, s.Name, in))
|
|
})
|
|
if err != nil {
|
|
return StepResult{}, err
|
|
}
|
|
level := decision.Level.String()
|
|
if !decision.Level.Runs() || !rc.mayExecute(decision) {
|
|
return StepResult{Summary: level, Result: map[string]any{"level": level}}, nil
|
|
}
|
|
out := approvalOutcome{
|
|
Action: decision.Action.Connector + " " + decision.Action.Name,
|
|
Target: decision.Action.Target.Kind + ":" + decision.Action.Target.ID,
|
|
State: "ran", digest: decision.Action.Digest,
|
|
}
|
|
out.Result, out.Error, out.Unknown = runJudged(rc, d.Judge, decision, nil)
|
|
p.outcomes = append(p.outcomes, out)
|
|
p.stopped = p.stopped || out.Unknown
|
|
return StepResult{
|
|
Summary: firstText(out.Error, out.Result, out.State),
|
|
Result: map[string]any{"level": level, "state": out.State, "result": out.Result, "error": out.Error, "unknown": out.Unknown},
|
|
}, nil
|
|
}
|
|
|
|
func runApprovalWait(d Deps, rc *Context, p *progress, _ string, _ noSettings) (StepResult, error) {
|
|
out, err := d.settle(rc, p)
|
|
if err != nil {
|
|
return StepResult{}, err
|
|
}
|
|
return StepResult{Summary: outcomeLines(out)}, nil
|
|
}
|
|
|
|
// settle requests approval for pending actions and runs those approved.
|
|
// A dry run records the intended recipients without contacting them.
|
|
func (d Deps) settle(rc *Context, p *progress) ([]approvalOutcome, error) {
|
|
var (
|
|
out []approvalOutcome
|
|
err error
|
|
)
|
|
if rc.Dry() {
|
|
out, err = settleDry(rc, d.Judge, d.Settings, p.settled)
|
|
} else {
|
|
out, err = settleProposals(rc, d.Judge, d.Approver, d.Settings, p.settled)
|
|
}
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
for _, o := range out {
|
|
p.settled[o.digest] = true
|
|
}
|
|
p.outcomes = append(p.outcomes, out...)
|
|
return out, nil
|
|
}
|
|
|
|
// runNotify records incident history before notifying when memory is enabled
|
|
// and the investigation can finish. A dry run records the notification without
|
|
// sending it.
|
|
func runNotify(d Deps, rc *Context, p *progress, _ string, s notifySettings) (StepResult, error) {
|
|
if p.memory && !p.remembered && !p.stopped && !rc.Dry() {
|
|
review, err := remember(rc, d.Memory, d.Judge, p.outcomes, p.pin.threshold)
|
|
if err != nil {
|
|
return StepResult{}, err
|
|
}
|
|
p.review, p.remembered = review, true
|
|
}
|
|
n := func(key string) deliveries.Notification {
|
|
return findings(rc.RunID(), key, p.agent, s.Title, p.outcomes, p.review)
|
|
}
|
|
if rc.Dry() {
|
|
sent, err := rc.Step("notify", func(_ context.Context, key string) (deliveries.Notification, error) {
|
|
return n(key), nil
|
|
})
|
|
return StepResult{Summary: sent.Title}, err
|
|
}
|
|
_, err := rc.Step("notify", func(ctx context.Context, key string) (bool, error) {
|
|
return true, d.Notifier.Notify(ctx, n(key))
|
|
})
|
|
// The title doesn't depend on the key, so it stays the same on replay.
|
|
return StepResult{Summary: n("").Title}, err
|
|
}
|
|
|
|
// runSleep suspends the run. A dry run records the wait and doesn't take it.
|
|
func runSleep(_ Deps, rc *Context, _ *progress, _ string, s sleepSettings) (StepResult, error) {
|
|
if rc.Dry() {
|
|
_, err := rc.Step("sleep-skipped", func(context.Context, string) (string, error) {
|
|
return s.For, nil
|
|
})
|
|
return StepResult{}, err
|
|
}
|
|
return StepResult{}, rc.Sleep(s.duration())
|
|
}
|
|
|
|
// holds reports whether a step type can propose an action judgement may hold
|
|
// for approval.
|
|
func holds(stepType string) bool {
|
|
return slices.Contains([]string{typeAgent, typeAction}, stepType)
|
|
}
|