Documentation
¶
Overview ¶
Package exec supplies the executable NodeFactory the SOP compiler has been waiting for.
The compiler owns the graph — what runs, in what order, how often it retries, what must be true before an edge is taken. This package owns the mechanics of being a node in that graph: emitting the routing event the scheduler reads, bounding loops the engine will not bound itself, and reporting the lifecycle a UI needs. What a stage actually *does* is a StageRunner, injected by the caller, so the graph can be exercised without a provider, a worktree, or a running agent.
Three engine facts shape everything here, all verified against adk v2.2.0:
- Routing matches session.Event.Routes, never a node's return value. A body that returns "PASS" sets Event.Output and matches no edge at all.
- A returned error does not take the on_fail edge. It marks the node failed, applies RetryConfig, then fails the whole workflow. Failure that the SOP models as a route must therefore be reported as a value, not an error.
- Nothing counts loop activations, so max_cycles is ours to enforce.
Index ¶
- Constants
- func Agent(def *sop.Definition, f sop.NodeFactory) (adkagent.Agent, *sop.Compiled, error)
- func StageStarted(ev *session.Event) (stage string, ok bool)
- type CycleBudgetError
- type Factory
- func (f *Factory) AgentNode(s sop.Stage, cfg workflow.NodeConfig) (workflow.Node, error)
- func (f *Factory) Forget(invocationID string)
- func (f *Factory) FunctionNode(s sop.Stage, cfg workflow.NodeConfig) (workflow.Node, error)
- func (f *Factory) ReviewNode(s sop.Stage, r sop.Review, cfg workflow.NodeConfig) (workflow.Node, error)
- type RunnerFunc
- type StageOutcome
- type StageRequest
- type StageRunner
Constants ¶
const LifecycleAuthor = "sop.stage"
LifecycleAuthor is the author stamped on the "stage started" events this package emits, so a consumer can tell them from model output.
Variables ¶
This section is empty.
Functions ¶
func Agent ¶
func Agent(def *sop.Definition, f sop.NodeFactory) (adkagent.Agent, *sop.Compiled, error)
Agent compiles a SOP definition with f and returns it as an ADK agent, ready to hand to runner.Config.Agent.
It deliberately does not use agent/workflowagent.New, which looks like the obvious entry point. That constructor calls workflow.New(name, edges) with no options, so the SOP's defaults.max_concurrency would be silently dropped, and it keeps the *workflow.Workflow in an unexported wrapper. Building the workflow here keeps both the options and the handle; agent.Config.Run is the sanctioned hook for wrapping any Run function as an agent.
Types ¶
type CycleBudgetError ¶
CycleBudgetError is returned when a stage is activated more times than its max_cycles allows. It is deliberately fatal: a loop that will not converge must stop the run rather than spin.
func (*CycleBudgetError) Error ¶
func (e *CycleBudgetError) Error() string
type Factory ¶
type Factory struct {
Runner StageRunner
// contains filtered or unexported fields
}
Factory builds executable nodes. It implements sop.NodeFactory.
func NewFactory ¶
func NewFactory(r StageRunner) *Factory
NewFactory returns a factory whose nodes run r.
func (*Factory) Forget ¶
Forget releases the cycle counters for one invocation. A long-lived process that never calls it leaks one small entry per node per run.
func (*Factory) FunctionNode ¶
type RunnerFunc ¶
type RunnerFunc func(ctx context.Context, req StageRequest) (StageOutcome, error)
RunnerFunc adapts a function to StageRunner.
func (RunnerFunc) RunStage ¶
func (f RunnerFunc) RunStage(ctx context.Context, req StageRequest) (StageOutcome, error)
type StageOutcome ¶
type StageOutcome struct {
// Route is the value the scheduler matches against this stage's outgoing
// edges: "PASS", "FAIL", sop.RecheckSignal. Empty means "take the forward
// path", which the compiler wires as the Default route for any stage that
// can also fail over.
Route string
// Output is handed to the successor as its input.
Output any
}
StageOutcome is what a runner produced.
type StageRequest ¶
type StageRequest struct {
Stage sop.Stage
// Review is set when this activation is a stage's review checkpoint
// rather than the stage body itself.
Review *sop.Review
// Input is the predecessor's output, or the workflow input for the entry
// stage.
Input any
// Cycle is 1 on a stage's first activation and increments each time the
// graph routes back to it.
Cycle int
}
StageRequest is what a runner is asked to do.
type StageRunner ¶
type StageRunner interface {
RunStage(ctx context.Context, req StageRequest) (StageOutcome, error)
}
StageRunner performs one stage's work.
It returns the route the stage produced rather than an error, because the engine treats an error as fatal to the whole run: a gate that fails is a FAIL route, not a Go error. Reserve the error return for a stage that could not be attempted at all.