workflow

package
v0.0.5 Latest Latest
Warning

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

Go to latest
Published: Mar 8, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package workflow provides workflow definition, loading, and running.

Index

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 FindStepIndexByID(wf *Workflow, stepID string) int

func Interpolate

func Interpolate(s string, inputs map[string]string, steps map[string]interface{}) (string, error)

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

func ResolveWorkflowFileRef(filePath, workflowDir string) (string, error)

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

func WorkflowHash(wf *Workflow) (string, error)

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.

func List

func List(vaultPath string, vaultCfg *config.VaultConfig) ([]*ListItem, error)

List returns all workflow names and descriptions.

type RunExecutionSummary

type RunExecutionSummary struct {
	ToolsExecuted          int `json:"tools_executed"`
	AgentBoundariesCrossed int `json:"agent_boundaries_crossed"`
}

type RunFailure

type RunFailure struct {
	Code    string    `json:"code"`
	Message string    `json:"message"`
	StepID  string    `json:"step_id,omitempty"`
	At      time.Time `json:"at"`
}

type RunHistoryEvent

type RunHistoryEvent struct {
	StepID   string    `json:"step_id"`
	StepType string    `json:"step_type"`
	Status   string    `json:"status"`
	At       time.Time `json:"at"`
}

type RunListFilter

type RunListFilter struct {
	Workflow string
	Statuses map[RunStatus]bool
}

type RunPruneOptions

type RunPruneOptions struct {
	Statuses  map[RunStatus]bool
	OlderThan *time.Duration
	Now       time.Time
	Apply     bool
}

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 RunStatus

type RunStatus string
const (
	RunStatusRunning       RunStatus = "running"
	RunStatusAwaitingAgent RunStatus = "awaiting_agent"
	RunStatusCompleted     RunStatus = "completed"
	RunStatusFailed        RunStatus = "failed"
	RunStatusCancelled     RunStatus = "cancelled"
)

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 RunStoreWarning struct {
	Code    string `json:"code"`
	RunID   string `json:"run_id,omitempty"`
	File    string `json:"file,omitempty"`
	Message string `json:"message"`
}

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 NewRunner

func NewRunner(vaultPath string, vaultCfg *config.VaultConfig) *Runner

func (*Runner) Run

func (r *Runner) Run(wf *Workflow, inputs map[string]string) (*RunResult, error)

Run executes wf until it reaches an agent step (returning Next) or completes.

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)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL