exec

package
v0.2.7 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: MIT Imports: 14 Imported by: 0

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

View Source
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.

View Source
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

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

func StageNotReady(err error) bool

StageNotReady reports whether err is a stage asking to be run again.

func StageStarted

func StageStarted(ev *session.Event) (stage string, ok bool)

StageStarted reports the stage a lifecycle event announces, and whether ev is one at all. A UI switches its "running" marker on this.

Types

type CycleBudgetError

type CycleBudgetError struct {
	Stage string
	Max   int
}

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) AgentNode

func (f *Factory) AgentNode(s sop.Stage, cfg workflow.NodeConfig) (workflow.Node, error)

func (*Factory) Forget

func (f *Factory) Forget(invocationID string)

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

func (f *Factory) FunctionNode(s sop.Stage, cfg workflow.NodeConfig) (workflow.Node, error)

func (*Factory) ReviewNode

func (f *Factory) ReviewNode(s sop.Stage, r sop.Review, cfg workflow.NodeConfig) (workflow.Node, error)

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.

Jump to

Keyboard shortcuts

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