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 StageNotReady(err error) bool
- 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 ShellRunner
- 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.
const RetryExitCode = 75
RetryExitCode is the exit status a stage script uses to say "not yet" rather than "failed".
The distinction cannot be expressed by success and failure alone, and it is the difference between a poll and a defeat: a `watch` stage that finds CI still running has not failed, it simply has no answer yet, and what it wants is the engine's backoff — not the SOP's failure edge. The value is sysexits' EX_TEMPFAIL, which already means exactly this.
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.
func StageNotReady ¶ added in v0.0.85
StageNotReady reports whether err is a stage asking to be run again.
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 ShellRunner ¶ added in v0.0.85
type ShellRunner struct {
// Dir is the working directory for stage scripts. Empty means the
// process's own.
Dir string
// RunDir holds a run's artifacts. It is exported to scripts as
// PI_RUN_DIR, and `produces:` paths resolve inside it.
RunDir string
// Env is extra environment for stage scripts, as "K=V" strings, on top of
// the process environment.
Env []string
// Shell interprets a stage's script. Empty means "bash".
Shell string
// Agent runs an agent stage. When nil, an agent stage fails rather than
// silently passing — a stage that quietly does nothing is the failure mode
// the declarative SOP exists to prevent.
Agent StageRunner
// Observe receives each stage's combined output as it completes, for the
// transcript. Optional.
Observe func(stage, output string)
}
ShellRunner executes the stages a SOP declares as data.
It is the piece that lets a SOP be written in YAML alone. A function stage runs its `run:` script and reports the route its exit status implies; an agent stage is handed to Agent, which the caller supplies because dispatching one needs the orchestrator and this package must not depend on it.
Exit status is the contract:
0 PASS — take the stage's PASS route, or its forward path
RetryExitCode not ready — return an error so the engine backs off and
runs the stage again, which is how polling is expressed
anything else FAIL — take the stage's FAIL route
func (ShellRunner) RunStage ¶ added in v0.0.85
func (r ShellRunner) RunStage(ctx context.Context, req StageRequest) (StageOutcome, error)
RunStage implements StageRunner.
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.