Files
archie/modules/runs/vocabulary.go
T
samandCopilot 64dfad6d53 feat(runs): add typed results and model aliases (#2043)
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>
2026-11-18 23:47:35 +11:00

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)
}