Files
archie/modules/runs/vocabulary.go
T

363 lines
12 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"
"github.com/samcharles93/archie-core/modules/runs/internal/store"
)
// The step types the engine runs.
const (
typeAgent = "agent.run"
typeAction = "connector.action"
typeApproval = "approval.wait"
typeNotify = "run.notify"
typeSleep = "workflow.sleep"
typeFinish = "workflow.finish"
typeCall = "workflow.call"
typeHandoff = "workflow.handoff"
typeApprove = "workflow.approve"
typeMessage = "message.send"
)
// 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),
define(typeFinish, "Finish", finishSettings.valid, finishSettings.describe, runFinish),
define(typeCall, "Call workflow", callSettings.valid, callSettings.describe, runCall),
define(typeHandoff, "Hand off", handoffSettings.valid, handoffSettings.describe, runHandoff),
define(typeApprove, "Approval", approveSettings.valid, approveSettings.describe, runApprove),
define(typeMessage, "Send message", messageSettings.valid, messageSettings.describe, runMessage),
)
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, json.Deterministic(true))
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())
}
// finishStatuses are the outcomes a finish step chooses, with the run state
// each one sets.
var finishStatuses = map[string]string{
"completed": store.StateSucceeded,
"parked": store.StateParked,
"waiting_approval": store.StateWaitingApproval,
"declined": store.StateDeclined,
}
// finishSettings end the run with an outcome.
type finishSettings struct {
Status string `yaml:"status,omitempty" json:"status,omitempty" jsonschema:"how the run ends: completed (the default), parked, waiting_approval or declined"`
Detail string `yaml:"detail,omitempty" json:"detail,omitempty" jsonschema:"what the operator reads about the outcome"`
}
func (s finishSettings) valid() error {
if s.Status != "" {
if _, ok := finishStatuses[s.Status]; !ok {
return fmt.Errorf("status is completed, parked, waiting_approval or declined, not %q", s.Status)
}
}
return nil
}
func (s finishSettings) state() string {
if s.Status == "" {
return store.StateSucceeded
}
return finishStatuses[s.Status]
}
func (s finishSettings) describe() string {
status := "completed"
if s.Status != "" {
status = s.Status
}
return "Ends the run as " + status + "; later steps do not run"
}
// runFinish sets the run's outcome: the first step that does ends the run.
func runFinish(_ Deps, rc *Context, _ *progress, _ string, s finishSettings) (StepResult, error) {
rc.End(s.state(), s.Detail)
return StepResult{Summary: s.Detail}, nil
}
// 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)
}