Files
sam ce70d4f3ee feat(runs): workflow documents take today's step shape, references and when (#2039)
A step is id/type/settings with when and on_failure; the five kinds become
the types agent.run (inline mission), connector.action, approval.wait,
run.notify and workflow.sleep. Documents declare inputs, repository,
instructions, identity and profile; references are {{ task|inputs|steps }}
checked at save. Any number of approval steps, each asking only about what
was held since; actions still held at the end are put to people before the
run finishes. Triggers are refused for a workflow they can't start, and the
workflows API lists, reads and saves documents beside a step-type catalog.

Copied from internal/domain/workflow: definition.go, step_refs.go,
step_flow.go's checks, control_steps.go's when parser, vocabulary.go and
task/interface.go. stableid moves to internal/platform.
2026-11-17 18:43:45 +11:00

167 lines
5.4 KiB
Go

package runs
import (
"fmt"
"regexp"
"slices"
"strings"
)
// RepositoryMode says whether a workflow works on a repository.
type RepositoryMode string
const (
// RepositoryRequired gives the run a worktree of a repository. It is the
// default, so a workflow that declares none keeps working on one.
RepositoryRequired RepositoryMode = "required"
// RepositoryOptional runs with a worktree when the run names a repository,
// and without one when it doesn't.
RepositoryOptional RepositoryMode = "optional"
// RepositoryNone runs with no repository.
RepositoryNone RepositoryMode = "none"
)
// InputSpec declares one workflow input.
type InputSpec struct {
Type string `yaml:"type" json:"type"`
Required bool `yaml:"required,omitempty" json:"required,omitzero"`
}
// OutputSpec declares one workflow output, in the input type vocabulary.
type OutputSpec struct {
Type string `yaml:"type" json:"type"`
Required bool `yaml:"required,omitempty" json:"required,omitzero"`
}
// Interface is what a workflow declares to whatever starts it: the inputs it
// takes, whether it works on a repository, who it acts as, and the
// instructions every agent step of a run follows.
type Interface struct {
Inputs map[string]InputSpec `yaml:"inputs,omitempty"`
Outputs map[string]OutputSpec `yaml:"outputs,omitempty"`
Repository RepositoryMode `yaml:"repository,omitempty"`
// Profile names the agent profile a run's sandbox is built from.
Profile string `yaml:"profile,omitempty"`
// Identity names the identity every run of this workflow acts as,
// whatever started it.
Identity string `yaml:"identity,omitempty"`
// Instructions are the workflow's layer of the instructions every agent
// step of a run follows.
Instructions string `yaml:"instructions,omitempty"`
}
var (
inputName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
inputTypes = []string{"string", "number", "bool", "object", "array", "any"}
)
// problems rejects an unknown repository mode, a malformed input name and an
// unknown input type. Outputs have nothing that writes them yet, so declaring
// one is refused rather than ignored.
func (w Interface) problems() []Problem {
var out []Problem
switch w.Repository {
case "", RepositoryRequired, RepositoryOptional, RepositoryNone:
default:
out = append(out, Problem{Path: "repository", Message: fmt.Sprintf("%q must be none, optional or required", w.Repository)})
}
for _, name := range sortedKeys(w.Inputs) {
spec := w.Inputs[name]
if !inputName.MatchString(name) {
out = append(out, Problem{Path: "inputs." + name, Message: "an input name is a letter or underscore followed by letters, digits or underscores"})
}
if !slices.Contains(inputTypes, spec.Type) {
out = append(out, Problem{Path: "inputs." + name + ".type", Message: fmt.Sprintf("%q must be one of %s", spec.Type, strings.Join(inputTypes, ", "))})
}
}
if len(w.Outputs) > 0 {
out = append(out, Problem{Path: "outputs", Message: "workflow outputs are not supported yet"})
}
return out
}
// mode returns the declared repository mode, defaulting to required.
func (w Interface) mode() RepositoryMode {
if w.Repository == "" {
return RepositoryRequired
}
return w.Repository
}
// unsupported says why a run of this workflow can't start yet: it names an
// identity or a profile, and nothing in the binary acts as one or builds one.
func (w Interface) unsupported() error {
switch {
case w.Identity != "":
return fmt.Errorf("the workflow acts as identity %q, and runs can't act as an identity yet", w.Identity)
case w.Profile != "":
return fmt.Errorf("the workflow runs under profile %q, and runs can't use an agent profile yet", w.Profile)
}
return nil
}
// checkInputs rejects values that don't satisfy the declared inputs: a
// required input that is missing or null, or a value whose type is not the
// declared one. A value for an undeclared input is left alone, since a
// trigger passes the whole event whether or not a workflow reads it.
func (w Interface) checkInputs(values map[string]any) error {
for _, name := range sortedKeys(w.Inputs) {
spec := w.Inputs[name]
v, ok := values[name]
if spec.Required && (!ok || v == nil) {
return fmt.Errorf("input %q is required", name)
}
if got := valueType(v); ok && v != nil && !typeAccepts(spec.Type, got) {
return fmt.Errorf("input %q is %s, want %s", name, got, spec.Type)
}
}
return nil
}
// requires lists the required inputs not among supplied.
func (w Interface) requires(supplied ...string) []string {
var out []string
for _, name := range sortedKeys(w.Inputs) {
if w.Inputs[name].Required && !slices.Contains(supplied, name) {
out = append(out, name)
}
}
return out
}
// typeAccepts reports whether a value of type got may feed an input declared
// as want.
func typeAccepts(want, got string) bool {
return want == "any" || got == "any" || want == got
}
// valueType names the JSON type of a decoded value in the input type
// vocabulary.
func valueType(v any) string {
switch v.(type) {
case nil:
return "null"
case string:
return "string"
case bool:
return "bool"
case float64, float32, int, int32, int64:
return "number"
case map[string]any:
return "object"
case []any:
return "array"
default:
return fmt.Sprintf("%T", v)
}
}
func sortedKeys[V any](m map[string]V) []string {
keys := make([]string, 0, len(m))
for k := range m {
keys = append(keys, k)
}
slices.Sort(keys)
return keys
}