workflow

package
v1.3.20 Latest Latest
Warning

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

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

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 MaxHistoryLength = 1000

MaxHistoryLength is the maximum number of state transitions retained in context history. When exceeded, the oldest transitions are discarded.

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 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 RegisterTransitionTool added in v1.3.20 

func RegisterTransitionTool(registry *tools.Registry, state *State)

RegisterTransitionTool registers the workflow__transition tool in the given registry for the specified state's available events. Skips terminal states (no events) and externally orchestrated states.

Both the SDK (WorkflowCapability) and Arena (engine) use this function.

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.

func ParseConfig added in v1.3.20 

func ParseConfig(raw interface{}) (*Spec, error)

ParseConfig parses an untyped workflow config (typically from config.Workflow which is stored as interface{}) into a typed Spec. Returns nil, nil when raw is nil.

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.