workflow

package
v0.60.0 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	OwnerUser        = "user"
	OwnerAgent       = "agent"
	RunClaimed       = "claimed"
	RunMaterializing = "materializing"
	RunDone          = "done"
	RunFailed        = "failed"
)
View Source 
const InputSchemaJSON = `` /* 2691-byte string literal not displayed */
View Source 
const PayloadFormatFrozenV0 = "frozen/v0"
View Source 
const ToolName = "workflow"

Variables

View Source 
var (
	ErrForbidden   = errors.New("workflow access forbidden")
	ErrNotFound    = errors.New("workflow not found")
	ErrUnavailable = errors.New("workflow authorization unavailable")
	ErrInvalidPage = errors.New("workflow pagination is outside the supported range")
)

Errors returned by the Workflow access boundary. Denials are opaque (ErrNotFound) so a foreign or revoked workflow cannot be distinguished from a missing one, preserving the pre-cutover 404 contract.

View Source 
var (
	ErrRunAlreadyFailed        = errors.New("workflow run already failed")
	ErrWorkflowHasRuns         = errors.New("workflow has runs")
	ErrWorkflowHasSchedulerJob = errors.New("workflow has enabled scheduler jobs")
	ErrWorkflowVersionConflict = errors.New("workflow version conflict; retry")
	// ErrInvalidWorkflowInput marks input errors the caller can fix (bad spec
	// name, unknown or missing input, unresolved placeholder) -- mapped to 400.
	ErrInvalidWorkflowInput = errors.New("invalid workflow input")
)

Functions

func DecodeDecomposition 

func DecodeDecomposition(b []byte) (goal.DecompositionContent, error)

func Dispatch 

func Dispatch(ctx context.Context, h Handler, action string, args map[string]any) (any, error)

func InputSchema 

func InputSchema() map[string]any

func ResolveInputs 

func ResolveInputs(specs []InputSpec, provided map[string]string) (map[string]string, error)

func ValidatePlaceholders 

func ValidatePlaceholders(specs []InputSpec, texts ...string) error

ValidatePlaceholders checks every {{inputs.name}} referenced by the given texts against the declared specs, so a typo or an undeclared input fails at save time instead of on every run.

func ValidateSpecs 

func ValidateSpecs(specs []InputSpec) error

ValidateSpecs rejects at save time input specs that could never resolve: a name outside the placeholder charset is unreferencable by {{inputs.name}}, so the workflow would fail on every instantiation.

Types

type Access 

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

Access captures one validated authority for a Workflow use case. Workflow owns the direct rules; transports pass a trusted Authority, never a scoped query.

func (*Access) Delete 

func (a *Access) Delete(ctx context.Context, id string) error

Delete authorizes deleting a workflow, then removes it (blocked when runs or enabled scheduler jobs reference it — those domain errors surface unchanged).

func (*Access) Get 

func (a *Access) Get(ctx context.Context, id string) (Workflow, error)

Get authorizes reading one workflow.

func (*Access) Instantiate 

func (a *Access) Instantiate(ctx context.Context, id string, inputs map[string]string, idempotencyKey string) (Run, bool, error)

Instantiate claims a run and materializes the workflow's goal tree. It checks both the loaded durable workflow and its persisted target agent before claim or materialization; neither request fields nor a stale route can widen access.

func (*Access) List 

func (a *Access) List(ctx context.Context, agentFilter string) ([]Workflow, error)

List lists the caller's workflows and filters every durable row through the same direct read rule. A user actor may narrow the query to one agent; a delegated agent is always confined to its own bound agent regardless of the filter. The query remains owner-scoped even for admins by established contract.

func (*Access) ListRuns 

func (a *Access) ListRuns(ctx context.Context, id string, limit, offset int) ([]RunListItem, int64, error)

ListRuns authorizes reading a workflow, then returns its run page.

func (*Access) SaveGoalAsWorkflow 

func (a *Access) SaveGoalAsWorkflow(ctx context.Context, in SaveInput) (Workflow, error)

SaveGoalAsWorkflow freezes an accepted goal tree into a workflow. The source Goal owns its read decision; its persisted agent determines the workflow's target, and Agent owns the target execute decision.

type FrozenNode 

type FrozenNode struct {
	Child goal.ProposedChild `json:"child"`
	Plan  *FrozenPlan        `json:"plan,omitempty"`
}

type FrozenPlan 

type FrozenPlan struct {
	Children []FrozenNode        `json:"children"`
	Edges    []goal.ProposedEdge `json:"edges"`
}

func DecodeFrozenPlan 

func DecodeFrozenPlan(b []byte) (FrozenPlan, error)

func SubstituteInputs 

func SubstituteInputs(plan FrozenPlan, inputs map[string]string) (FrozenPlan, error)

func (FrozenPlan) FullyFrozen 

func (p FrozenPlan) FullyFrozen() bool

func (FrozenPlan) Hash 

func (p FrozenPlan) Hash() string

func (FrozenPlan) Validate 

func (p FrozenPlan) Validate() error

func (FrozenPlan) ValidateMaxDepth 

func (p FrozenPlan) ValidateMaxDepth(maxDepth int) error

type GetInput 

type GetInput struct {
	Id string `json:"id,omitempty"`
}

type GoalWriter 

type GoalWriter interface {
	CreateRoot(ctx context.Context, in goal.CreateInput) (goal.CreatedGoal, error)
	MaterializeFrozenLayer(ctx context.Context, parentID string, content goal.DecompositionContent, frozen goal.FrozenStamp) error
	ActivateFrozenComposite(ctx context.Context, id string) error
	Authorize(ctx context.Context, authority authz.Authority, goalID string, action authz.Action) (goal.AuthorizedGoal, error)
}

GoalWriter is the workflow domain's narrow port into Goal: frozen-tree writes plus Goal's direct source-read authorization. The port is consumer-owned here so no goal→workflow cycle forms; Goal exposes a narrow adapter that satisfies it.

type Handler 

type Handler interface {
	Get(context.Context, GetInput) (any, error)
	List(context.Context, ListInput) (any, error)
	Run(context.Context, RunInput) (any, error)
	Save(context.Context, ToolSaveInput) (any, error)
}

type InputSpec 

type InputSpec struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required"`
	Default     string `json:"default,omitempty"`
}

type InstantiateInput 

type InstantiateInput struct {
	UserID         string
	AgentID        string
	WorkflowID     string
	Inputs         map[string]string
	IdempotencyKey string
}

type ListInput 

type ListInput struct {
}

type Run 

type Run struct {
	ID              string
	WorkflowID      string
	WorkflowVersion int32
	IdempotencyKey  string
	RootGoalID      *string
	Status          string
	Inputs          map[string]string
	PlanHash        string
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

Run is one instantiation of a workflow.

type RunInput 

type RunInput struct {
	Id             string         `json:"id,omitempty"`
	IdempotencyKey string         `json:"idempotency_key,omitempty"`
	Inputs         map[string]any `json:"inputs,omitempty"`
}

type RunListItem 

type RunListItem struct {
	Run
	RootLifecycle   *string
	RootBlockReason *string
	RootDoneReason  *string
}

RunListItem is a run row for the list view, joined with its root goal's outcome fields (a claimed run with no root goal yet leaves them nil).

type RunState 

type RunState struct {
	Found            bool
	Status           string
	IdempotencyKey   string
	RootGoalID       string
	RootGoalTerminal bool
}

RunState is the latest-run snapshot the scheduler adapter needs to decide whether a workflow run is in flight or has reached a terminal root goal.

type SaveInput 

type SaveInput struct {
	UserID  string
	AgentID string
	GoalID  string
	Name    string
	Inputs  []InputSpec
}

type ScheduledWorkflow 

type ScheduledWorkflow struct {
	ID          string
	FullyFrozen bool
}

ScheduledWorkflow is the narrow immutable workflow fact the scheduler needs while validating a job. The scheduler has already established the durable owner and agent values it supplies to this worker-adapter port.

type Service 

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

func New 

func New(db *pgxpool.Pool, goalSvc GoalWriter, agents *agentaccess.Service) *Service

New constructs the Workflow application service. Goal and Agent are the domain-owned ports used by the Authority-based Access boundary.

func (*Service) Authorize 

func (s *Service) Authorize(ctx context.Context, authority authz.Authority, workflowID string, action authz.Action) error

Authorize is Workflow's narrow direct port for another domain. It loads the durable row before applying the same fixed rules as Access; ownership and executor facts cannot be supplied by the caller. A missing or denied workflow is opaque to the caller through authz.ErrNotFound.

func (*Service) Begin 

func (s *Service) Begin(_ context.Context, authority authz.Authority) (*Access, error)

Begin captures validated authority for one Workflow use case.

func (*Service) InstantiateAs 

func (s *Service) InstantiateAs(ctx context.Context, authority authz.Authority, id string, inputs map[string]string, idempotencyKey string) (Run, bool, error)

InstantiateAs authorizes and instantiates a workflow under authority. It is the narrow cross-domain entry point used by scheduler dispatch; request fields never establish ownership or the executor.

func (*Service) LatestRunState 

func (s *Service) LatestRunState(ctx context.Context, workflowID string) (RunState, error)

LatestRunState returns the state of the most recent run for a workflow. Found is false when the workflow has no runs yet.

func (*Service) ValidateScheduledWorkflow 

func (s *Service) ValidateScheduledWorkflow(ctx context.Context, userID, agentID, workflowID string) (ScheduledWorkflow, error)

ValidateScheduledWorkflow returns only the durable workflow facts needed to validate a scheduler-owned workflow job.

type Tool 

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

func NewTool 

func NewTool(svc *Service) *Tool

func (*Tool) Definition 

func (t *Tool) Definition() tools.Definition

func (*Tool) Execute 

func (t *Tool) Execute(ctx context.Context, args map[string]any) (string, error)

type ToolSaveInput 

type ToolSaveInput struct {
	Id     string `json:"id,omitempty"`
	Inputs []any  `json:"inputs,omitempty"`
	Name   string `json:"name,omitempty"`
}

type Workflow 

type Workflow struct {
	ID                 string
	OwnerKind          string
	UserID             *string
	AgentID            *string
	Name               string
	Version            int32
	Intent             string
	AcceptanceContract json.RawMessage
	ConvergencePolicy  json.RawMessage
	Inputs             []InputSpec
	PayloadFormat      string
	Payload            json.RawMessage
	FullyFrozen        bool
	SourceGoalID       *string
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

Workflow is the frozen definition of a reusable goal template.

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.