workflow

package
v1.3.24 Latest Latest
Warning

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

 Go to latest Published: Mar 29, 2026 License: Apache-2.0 Imports: 11 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 ArtifactExecutorMode = "workflow-artifact"

ArtifactExecutorMode is the executor name for Mode-based routing.

View Source 
const ArtifactToolName = "workflow__set_artifact"

ArtifactToolName is the qualified name of the workflow set_artifact tool.

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 TransitionExecutorMode = "workflow-transition"

TransitionExecutorMode is the executor name used for Mode-based routing.

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)")
)
View Source 
var (
	// ErrMaxVisitsExceeded is returned when a state's max_visits limit is reached
	// and no on_max_visits fallback is configured.
	ErrMaxVisitsExceeded = errors.New("max visits exceeded")

	// ErrBudgetExhausted is returned when a workflow-level budget limit is reached.
	ErrBudgetExhausted = errors.New("workflow budget exhausted")
)

Sentinel errors for workflow execution.

Functions

func BuildArtifactToolDescriptor added in v1.3.24 

func BuildArtifactToolDescriptor(spec *Spec) *tools.ToolDescriptor

BuildArtifactToolDescriptor creates a tools.ToolDescriptor for the workflow__set_artifact tool, with artifact names as an enum constraint.

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 RegisterArtifactTool added in v1.3.24 

func RegisterArtifactTool(registry *tools.Registry, spec *Spec)

RegisterArtifactTool registers the workflow__set_artifact tool in the given registry. Only registers if the spec declares artifacts on any state.

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 ArtifactDef added in v1.3.24 

type ArtifactDef struct {
	Type        string `json:"type"`                  // MIME type (e.g., "text/plain", "application/json")
	Description string `json:"description,omitempty"` // What the artifact contains
	Mode        string `json:"mode,omitempty"`        // "replace" (default) or "append"
}

ArtifactDef declares a named artifact slot on a workflow state. Artifacts are workflow-scoped: if two states declare the same name, they reference the same artifact. Values are accessible as {{artifacts.<name>}}.

type ArtifactExecutor added in v1.3.24 

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

ArtifactExecutor implements tools.Executor for workflow__set_artifact. Unlike TransitionExecutor, artifact mutations are safe to apply immediately since they only modify the context map without closing/reopening conversations.

func NewArtifactExecutor added in v1.3.24 

func NewArtifactExecutor(sm *StateMachine) *ArtifactExecutor

NewArtifactExecutor creates an ArtifactExecutor for the given state machine.

func (*ArtifactExecutor) Execute added in v1.3.24 

func (e *ArtifactExecutor) Execute(
	_ context.Context, _ *tools.ToolDescriptor, args json.RawMessage,
) (json.RawMessage, error)

Execute implements tools.Executor. Sets the artifact value on the state machine.

func (*ArtifactExecutor) Name added in v1.3.24 

func (e *ArtifactExecutor) Name() string

Name implements tools.Executor.

type ArtifactSnapshot added in v1.3.24 

type ArtifactSnapshot struct {
	FromState string            `json:"from_state"`
	ToState   string            `json:"to_state"`
	Event     string            `json:"event"`
	Values    map[string]string `json:"values"`
	Timestamp time.Time         `json:"timestamp"`
}

ArtifactSnapshot captures artifact values at a specific state transition.

type Budget added in v1.3.24 

type Budget struct {
	MaxTotalVisits int `json:"max_total_visits,omitempty"`
	MaxToolCalls   int `json:"max_tool_calls,omitempty"`
	MaxWallTimeSec int `json:"max_wall_time_sec,omitempty"`
}

Budget defines workflow-level resource limits from the engine block.

type Context 

type Context struct {
	CurrentState    string             `json:"current_state"`
	History         []StateTransition  `json:"history"`
	Metadata        map[string]any     `json:"metadata,omitempty"`
	VisitCounts     map[string]int     `json:"visit_counts,omitempty"`     // RFC 0009: per-state visit counts
	TotalToolCalls  int                `json:"total_tool_calls,omitempty"` // RFC 0009: workflow-wide tool call count
	Artifacts       map[string]string  `json:"artifacts,omitempty"`        // RFC 0009: current artifact values
	ArtifactHistory []ArtifactSnapshot `json:"artifact_history,omitempty"` // RFC 0009: artifact values at each transition
	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) GetArtifact added in v1.3.24 

func (ctx *Context) GetArtifact(name string) string

GetArtifact returns an artifact value, or empty string if not set.

func (*Context) IncrementToolCalls added in v1.3.24 

func (ctx *Context) IncrementToolCalls(n int)

IncrementToolCalls adds n to the workflow-wide tool call counter.

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) SetArtifact added in v1.3.24 

func (ctx *Context) SetArtifact(name, value, mode string)

SetArtifact sets an artifact value, respecting the mode (replace or append).

func (*Context) TotalVisits added in v1.3.24 

func (ctx *Context) TotalVisits() int

TotalVisits returns the sum of all per-state visit counts.

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 PendingTransition added in v1.3.24 

type PendingTransition struct {
	Event          string `json:"event"`
	ContextSummary string `json:"context"`
}

PendingTransition captures a deferred workflow transition from a tool call.

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"`
	Terminal      bool                    `json:"terminal,omitempty"`      // RFC 0009: explicit terminal marker
	MaxVisits     int                     `json:"max_visits,omitempty"`    // RFC 0009: max times this state can be entered
	OnMaxVisits   string                  `json:"on_max_visits,omitempty"` // RFC 0009: redirect on max_visits
	Artifacts     map[string]*ArtifactDef `json:"artifacts,omitempty"`     // RFC 0009: artifact slot declarations
}

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) Artifacts added in v1.3.24 

func (sm *StateMachine) Artifacts() map[string]string

Artifacts returns a snapshot of the current artifact values.

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) IncrementToolCalls added in v1.3.24 

func (sm *StateMachine) IncrementToolCalls(n int)

IncrementToolCalls adds n to the workflow-wide tool call counter. Thread-safe; intended to be called by the SDK after tool executions.

func (*StateMachine) IsTerminal 

func (sm *StateMachine) IsTerminal() bool

IsTerminal returns true if the current state is terminal. A state is terminal when explicitly marked (Terminal: true) or when it has no outgoing transitions (backward compatible).

func (*StateMachine) ProcessEvent 

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

ProcessEvent applies an event and transitions to the target state. Returns a TransitionResult describing the transition (including any max_visits redirect). Returns ErrMaxVisitsExceeded when the target state's visit limit is reached and no on_max_visits fallback is set. Returns ErrBudgetExhausted when a workflow-level budget limit is reached.

func (*StateMachine) SetArtifact added in v1.3.24 

func (sm *StateMachine) SetArtifact(name, value string)

SetArtifact sets an artifact value on the workflow context. The mode is looked up from the spec's artifact definitions for the current state. Thread-safe.

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 TransitionExecutor added in v1.3.24 

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

TransitionExecutor implements tools.Executor for workflow__transition. It defers the actual state transition (ProcessEvent) until CommitPending is called, ensuring the full pipeline completes before state changes.

Both SDK and Arena use this executor. After pipeline/turn execution, the consumer calls CommitPending() to apply the transition.

func NewTransitionExecutor added in v1.3.24 

func NewTransitionExecutor(sm *StateMachine, spec *Spec) *TransitionExecutor

NewTransitionExecutor creates a TransitionExecutor for the given state machine.

func (*TransitionExecutor) ClearPending added in v1.3.24 

func (e *TransitionExecutor) ClearPending()

ClearPending discards any pending transition without committing.

func (*TransitionExecutor) CommitPending added in v1.3.24 

func (e *TransitionExecutor) CommitPending() (*TransitionResult, error)

CommitPending applies the pending transition by calling ProcessEvent. Returns nil, nil if no transition is pending. After commit, the pending state is cleared. Thread-safe.

func (*TransitionExecutor) Execute added in v1.3.24 

func (e *TransitionExecutor) Execute(
	_ context.Context, _ *tools.ToolDescriptor, args json.RawMessage,
) (json.RawMessage, error)

Execute implements tools.Executor. Stores the transition request and returns a confirmation to the LLM. Does NOT call ProcessEvent — that happens in CommitPending after the pipeline completes.

func (*TransitionExecutor) Name added in v1.3.24 

func (e *TransitionExecutor) Name() string

Name implements tools.Executor. Returns the mode name for registry routing.

func (*TransitionExecutor) Pending added in v1.3.24 

func (e *TransitionExecutor) Pending() *PendingTransition

Pending returns the current pending transition, or nil if none.

func (*TransitionExecutor) RegisterForState added in v1.3.24 

func (e *TransitionExecutor) RegisterForState(registry *tools.Registry, state *State)

RegisterForState registers the workflow__transition tool in the given registry for the specified state, with Mode set for executor routing. Skips terminal states and externally orchestrated states.

func (*TransitionExecutor) StateMachine added in v1.3.24 

func (e *TransitionExecutor) StateMachine() *StateMachine

StateMachine returns the underlying state machine for metadata access.

type TransitionResult added in v1.3.24 

type TransitionResult struct {
	From           string `json:"from"`
	To             string `json:"to"`
	Event          string `json:"event"`
	Redirected     bool   `json:"redirected,omitempty"`
	RedirectReason string `json:"redirect_reason,omitempty"`
	OriginalTarget string `json:"original_target,omitempty"`
}

TransitionResult is returned by ProcessEvent to communicate what happened. Redirects (e.g., max_visits exceeded → on_max_visits) are successful transitions, not errors.

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.