workflow

package
v1.3.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 3, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package workflow defines types and logic for PromptPack workflow state machines (RFC 0005).

A workflow is an event-driven state machine layered over a PromptPack's prompts. Each state references a prompt_task and defines transitions via named events.

Index

Constants

View Source 
const TransitionToolName = "workflow__transition"

TransitionToolName is the qualified name of the workflow transition tool.

Variables

View Source 
var (
	// ErrInvalidEvent is returned when an event is not defined for the current state.
	ErrInvalidEvent = errors.New("invalid event for current state")
	// ErrTerminalState is returned when trying to process an event in a terminal state.
	ErrTerminalState = errors.New("current state is terminal (no outgoing transitions)")
)

Functions

func BuildTransitionProviderDescriptor 

func BuildTransitionProviderDescriptor(events []string) *providers.ToolDescriptor

BuildTransitionProviderDescriptor creates a providers.ToolDescriptor (minimal 4-field variant) for use with Arena's provider interface.

func BuildTransitionToolDescriptor 

func BuildTransitionToolDescriptor(events []string) *tools.ToolDescriptor

BuildTransitionToolDescriptor creates a tools.ToolDescriptor for the workflow__transition tool with the given events as an enum constraint.

func SortedEvents 

func SortedEvents(onEvent map[string]string) []string

SortedEvents returns a sorted copy of the event keys from an OnEvent map.

Types

type Context 

type Context struct {
	CurrentState string            `json:"current_state"`
	History      []StateTransition `json:"history"`
	Metadata     map[string]any    `json:"metadata,omitempty"`
	StartedAt    time.Time         `json:"started_at"`
	UpdatedAt    time.Time         `json:"updated_at"`
}

Context holds the runtime state of a workflow execution.

func NewContext 

func NewContext(entryState string, now time.Time) *Context

NewContext creates a new Context initialized at the given entry state.

func (*Context) Clone 

func (ctx *Context) Clone() *Context

Clone returns a deep copy of the Context.

func (*Context) LastTransition 

func (ctx *Context) LastTransition() *StateTransition

LastTransition returns the most recent transition, or nil if none.

func (*Context) RecordTransition 

func (ctx *Context) RecordTransition(from, to, event string, ts time.Time)

RecordTransition records a state transition and updates the current state.

func (*Context) TransitionCount 

func (ctx *Context) TransitionCount() int

TransitionCount returns the number of transitions recorded.

type Orchestration 

type Orchestration string

Orchestration is the control mode for a workflow state. 

const (
	OrchestrationInternal Orchestration = "internal"
	OrchestrationExternal Orchestration = "external"
	OrchestrationHybrid   Orchestration = "hybrid"
)

Orchestration values.

type Persistence 

type Persistence string

Persistence is the storage hint for a workflow state. 

const (
	PersistenceTransient  Persistence = "transient"
	PersistencePersistent Persistence = "persistent"
)

Persistence values.

type Spec 

type Spec struct {
	Version int               `json:"version"`
	Entry   string            `json:"entry"`
	States  map[string]*State `json:"states"`
	Engine  map[string]any    `json:"engine,omitempty"`
}

Spec is the top-level workflow definition from a PromptPack.

type State 

type State struct {
	PromptTask    string            `json:"prompt_task"`
	Description   string            `json:"description,omitempty"`
	OnEvent       map[string]string `json:"on_event,omitempty"`
	Persistence   Persistence       `json:"persistence,omitempty"`
	Orchestration Orchestration     `json:"orchestration,omitempty"`
	Skills        string            `json:"skills,omitempty"`
}

State defines a single state in the workflow state machine.

type StateMachine 

type StateMachine struct {
	// contains filtered or unexported fields
}

StateMachine manages workflow state transitions.

func NewStateMachine 

func NewStateMachine(spec *Spec) *StateMachine

NewStateMachine creates a state machine from a workflow spec. It initializes the context to the entry state.

func NewStateMachineFromContext 

func NewStateMachineFromContext(spec *Spec, ctx *Context) *StateMachine

NewStateMachineFromContext restores a state machine from persisted context.

func (*StateMachine) AvailableEvents 

func (sm *StateMachine) AvailableEvents() []string

AvailableEvents returns the set of valid events for the current state, sorted.

func (*StateMachine) Context 

func (sm *StateMachine) Context() *Context

Context returns a snapshot of the current workflow context for persistence.

func (*StateMachine) CurrentPromptTask 

func (sm *StateMachine) CurrentPromptTask() string

CurrentPromptTask returns the prompt_task for the current state.

func (*StateMachine) CurrentState 

func (sm *StateMachine) CurrentState() string

CurrentState returns the name of the current state.

func (*StateMachine) IsTerminal 

func (sm *StateMachine) IsTerminal() bool

IsTerminal returns true if the current state has no outgoing transitions.

func (*StateMachine) ProcessEvent 

func (sm *StateMachine) ProcessEvent(event string) error

ProcessEvent applies an event and transitions to the target state.

func (*StateMachine) WithTimeFunc 

func (sm *StateMachine) WithTimeFunc(fn TimeFunc) *StateMachine

WithTimeFunc sets a custom time function for deterministic tests.

type StateTransition 

type StateTransition struct {
	From      string    `json:"from"`
	To        string    `json:"to"`
	Event     string    `json:"event"`
	Timestamp time.Time `json:"timestamp"`
}

StateTransition records a single state transition.

type TimeFunc 

type TimeFunc func() time.Time

TimeFunc returns the current time. Override for deterministic tests.

type ValidationResult 

type ValidationResult struct {
	Errors   []string // Blocking: invalid references, missing fields
	Warnings []string // Non-blocking: PascalCase violations, circular refs
}

ValidationResult holds errors and warnings from workflow validation.

func Validate 

func Validate(spec *Spec, promptKeys []string) *ValidationResult

Validate checks a Spec against the available prompt keys. It implements all 10 validation rules from RFC 0005.

func (*ValidationResult) HasErrors 

func (r *ValidationResult) HasErrors() bool

HasErrors returns true if there are blocking validation errors.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.