Documentation
¶
Overview ¶
Package workflow provides workflow definition, loading, and running.
Index ¶
- func ApplyAgentOutputs(wf *Workflow, state *WorkflowRunState, env AgentOutputEnvelope) error
- func ApplyRetentionExpiry(state *WorkflowRunState, cfg config.ResolvedWorkflowRunsConfig, now time.Time)
- func DeleteRunState(vaultPath string, cfg config.ResolvedWorkflowRunsConfig, runID string) error
- func FindStepIndexByID(wf *Workflow, stepID string) int
- func Interpolate(s string, inputs map[string]string, steps map[string]interface{}) (string, error)
- func InterpolateObject(obj map[string]interface{}, inputs map[string]string, ...) (map[string]interface{}, error)
- func ListRunStates(vaultPath string, cfg config.ResolvedWorkflowRunsConfig, filter RunListFilter) ([]*WorkflowRunState, []RunStoreWarning, error)
- func ResolveWorkflowFileRef(filePath, workflowDir string) (string, error)
- func SaveRunState(vaultPath string, cfg config.ResolvedWorkflowRunsConfig, ...) error
- func ValidateAgentOutputs(contract map[string]*config.WorkflowPromptOutput, ...) error
- func WorkflowHash(wf *Workflow) (string, error)
- type AgentOutputEnvelope
- type AgentRequest
- type ListItem
- type RunExecutionSummary
- type RunFailure
- type RunHistoryEvent
- type RunListFilter
- type RunPruneOptions
- type RunPruneResult
- type RunResult
- type RunStatus
- type RunStepSummary
- type RunStoreWarning
- type RunSummary
- type Runner
- type StepOutputEntry
- type StepOutputPage
- type Workflow
- func Get(vaultPath, name string, vaultCfg *config.VaultConfig) (*Workflow, error)
- func Load(vaultPath, name string, ref *config.WorkflowRef) (*Workflow, error)
- func LoadAll(vaultPath string, vaultCfg *config.VaultConfig) ([]*Workflow, error)
- func LoadWithConfig(vaultPath, name string, ref *config.WorkflowRef, vaultCfg *config.VaultConfig) (*Workflow, error)
- type WorkflowRunState
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyAgentOutputs ¶
func ApplyAgentOutputs(wf *Workflow, state *WorkflowRunState, env AgentOutputEnvelope) error
func ApplyRetentionExpiry ¶
func ApplyRetentionExpiry(state *WorkflowRunState, cfg config.ResolvedWorkflowRunsConfig, now time.Time)
func DeleteRunState ¶
func DeleteRunState(vaultPath string, cfg config.ResolvedWorkflowRunsConfig, runID string) error
func FindStepIndexByID ¶
func Interpolate ¶
Interpolate replaces {{inputs.*}} and {{steps.*}} references inside s.
Rules: - Escaping: \{{ and \}} produce literal braces. - Unknown variables are errors (to avoid silent typos).
func InterpolateObject ¶
func InterpolateObject(obj map[string]interface{}, inputs map[string]string, steps map[string]interface{}) (map[string]interface{}, error)
InterpolateObject applies interpolation recursively across a JSON-like object.
If a string value is exactly a single interpolation expression like "{{steps.x}}", the resolved value is preserved as its native type (object/array/bool/number/string).
func ListRunStates ¶
func ListRunStates( vaultPath string, cfg config.ResolvedWorkflowRunsConfig, filter RunListFilter, ) ([]*WorkflowRunState, []RunStoreWarning, error)
func ResolveWorkflowFileRef ¶
ResolveWorkflowFileRef normalizes a workflow file reference and enforces directories.workflow policy. Bare filenames are resolved under workflowDir.
func SaveRunState ¶
func SaveRunState(vaultPath string, cfg config.ResolvedWorkflowRunsConfig, state *WorkflowRunState) error
func ValidateAgentOutputs ¶
func ValidateAgentOutputs(contract map[string]*config.WorkflowPromptOutput, outputs map[string]interface{}) error
func WorkflowHash ¶
Types ¶
type AgentOutputEnvelope ¶
type AgentOutputEnvelope struct {
Outputs map[string]interface{} `json:"outputs"`
}
AgentOutputEnvelope is the required payload for workflow continuation.
type AgentRequest ¶
type AgentRequest struct {
StepID string `json:"step_id"`
Prompt string `json:"prompt"`
Outputs map[string]*config.WorkflowPromptOutput `json:"outputs"`
Example map[string]interface{} `json:"example,omitempty"`
}
AgentRequest is emitted when a workflow reaches an agent step.
type ListItem ¶
type ListItem struct {
Name string `json:"name"`
Description string `json:"description"`
Inputs map[string]*config.WorkflowInput `json:"inputs,omitempty"`
}
ListItem represents a workflow in the list output.
type RunExecutionSummary ¶
type RunFailure ¶
type RunHistoryEvent ¶
type RunListFilter ¶
type RunPruneOptions ¶
type RunPruneResult ¶
type RunPruneResult struct {
Scanned int `json:"scanned"`
Matched int `json:"matched"`
Deleted int `json:"deleted"`
RunIDs []string `json:"run_ids,omitempty"`
Warnings []RunStoreWarning `json:"warnings,omitempty"`
}
func AutoPruneRunStates ¶
func AutoPruneRunStates(vaultPath string, cfg config.ResolvedWorkflowRunsConfig) (*RunPruneResult, error)
func PruneRunStates ¶
func PruneRunStates(vaultPath string, cfg config.ResolvedWorkflowRunsConfig, opts RunPruneOptions) (*RunPruneResult, error)
type RunResult ¶
type RunResult struct {
RunID string `json:"run_id"`
WorkflowName string `json:"workflow_name"`
Status RunStatus `json:"status"`
Revision int `json:"revision"`
Cursor int `json:"cursor"`
AwaitingStepID string `json:"awaiting_step_id,omitempty"`
Inputs map[string]interface{} `json:"inputs"`
StepSummaries []RunStepSummary `json:"step_summaries"`
Next *AgentRequest `json:"next,omitempty"`
CreatedAt string `json:"created_at"`
UpdatedAt string `json:"updated_at"`
ExpiresAt string `json:"expires_at,omitempty"`
CompletedAt string `json:"completed_at,omitempty"`
Result *RunSummary `json:"result,omitempty"`
Failure *RunFailure `json:"failure,omitempty"`
}
RunResult is the output of running a workflow until an agent step or completion.
type RunStepSummary ¶
type RunStepSummary struct {
StepID string `json:"step_id"`
StepType string `json:"step_type"`
Status string `json:"status"`
HasOutput bool `json:"has_output"`
}
RunStepSummary is a lightweight status view for a workflow step.
func BuildStepSummaries ¶
func BuildStepSummaries(wf *Workflow, state *WorkflowRunState) []RunStepSummary
BuildStepSummaries returns per-step status without embedding full step outputs.
type RunStoreWarning ¶ added in v0.0.4
type RunSummary ¶
type RunSummary struct {
TerminalStepID string `json:"terminal_step_id,omitempty"`
Summary *RunExecutionSummary `json:"summary,omitempty"`
}
type Runner ¶
type Runner struct {
ToolFunc func(tool string, args map[string]interface{}) (interface{}, error)
// contains filtered or unexported fields
}
Runner executes workflows step-by-step.
It is intentionally generic: deterministic tool steps are executed via a caller-provided function hook, and agent steps only render prompts (they do not call an LLM).
func (*Runner) RunWithState ¶
func (r *Runner) RunWithState(wf *Workflow, state *WorkflowRunState) (*RunResult, error)
RunWithState executes or resumes a workflow from the provided persisted state.
type StepOutputEntry ¶
type StepOutputEntry struct {
Key string `json:"key"`
Value interface{} `json:"value"`
}
StepOutputEntry represents one key/value entry from an object output page.
type StepOutputPage ¶
type StepOutputPage struct {
Path string `json:"path,omitempty"`
Kind string `json:"kind"`
Offset int `json:"offset"`
Limit int `json:"limit"`
Total int `json:"total"`
Returned int `json:"returned"`
HasMore bool `json:"has_more"`
NextOffset int `json:"next_offset,omitempty"`
Items []interface{} `json:"items,omitempty"`
Entries []StepOutputEntry `json:"entries,omitempty"`
Text string `json:"text,omitempty"`
}
StepOutputPage is a paged view over a selected part of a step output.
func PaginateStepOutput ¶
func PaginateStepOutput(root interface{}, path string, offset, limit int) (*StepOutputPage, error)
PaginateStepOutput returns a deterministic page from step output content.
Supported target types: - arrays/slices (returned via Items) - objects with string keys (returned via Entries, key-sorted) - strings (returned via Text, rune-safe slicing)
When path is non-empty, it is interpreted as dot-separated object keys (e.g. "data.results") relative to the root step output object.
type Workflow ¶
type Workflow struct {
// Name is the workflow identifier (from the key in raven.yaml).
Name string
// Description is a brief summary of what the workflow does.
Description string
// Inputs defines the parameters the workflow accepts.
Inputs map[string]*config.WorkflowInput
// Steps are executed in order.
Steps []*config.WorkflowStep
}
Workflow represents a fully loaded and validated workflow.
func Get ¶
func Get(vaultPath, name string, vaultCfg *config.VaultConfig) (*Workflow, error)
Get retrieves a workflow by name from the vault configuration.
func Load ¶
func Load(vaultPath, name string, ref *config.WorkflowRef) (*Workflow, error)
Load loads a single workflow by name with default config policy.
func LoadAll ¶
func LoadAll(vaultPath string, vaultCfg *config.VaultConfig) ([]*Workflow, error)
LoadAll loads all workflows from the vault configuration.
func LoadWithConfig ¶
func LoadWithConfig(vaultPath, name string, ref *config.WorkflowRef, vaultCfg *config.VaultConfig) (*Workflow, error)
LoadWithConfig loads a single workflow by name using vault-level workflow policy.
type WorkflowRunState ¶
type WorkflowRunState struct {
Version int `json:"version"`
RunID string `json:"run_id"`
WorkflowName string `json:"workflow_name"`
WorkflowHash string `json:"workflow_hash"`
Status RunStatus `json:"status"`
Cursor int `json:"cursor"`
AwaitingStep string `json:"awaiting_step_id,omitempty"`
Inputs map[string]interface{} `json:"inputs"`
Steps map[string]interface{} `json:"steps"`
History []RunHistoryEvent `json:"history,omitempty"`
Failure *RunFailure `json:"failure,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
CompletedAt *time.Time `json:"completed_at,omitempty"`
ExpiresAt *time.Time `json:"expires_at,omitempty"`
Revision int `json:"revision"`
LockedBy *string `json:"locked_by,omitempty"`
LockedAt *time.Time `json:"locked_at,omitempty"`
}
WorkflowRunState is the persisted checkpoint format for workflow runs.
func LoadRunState ¶
func LoadRunState(vaultPath string, cfg config.ResolvedWorkflowRunsConfig, runID string) (*WorkflowRunState, error)
func NewRunState ¶
func NewRunState(wf *Workflow, inputs map[string]interface{}) (*WorkflowRunState, error)