engine

Documentation

Overview

Package engine is the supervisor: it owns run creation, subprocess execution, the auto-execution of run_command operations, response acceptance, and terminal handling. Every state change goes through the run log; every refusal goes through the guard.

Index

• type Engine
  • func New(skillDir string) (*Engine, error)
  • func NewWithRunsDir(skillDir, runsDir string) (*Engine, error)
  • func (e *Engine) Continue(runID string) (*Progress, error)
  • func (e *Engine) ListRuns() ([]string, error)
  • func (e *Engine) Log(runID string) (*runlog.Log, error)
  • func (e *Engine) Pending(runID string) (*protocol.RequestEnvelope, error)
  • func (e *Engine) Replay(runID string) (*Progress, error)
  • func (e *Engine) Respond(runID string, result json.RawMessage) (*Progress, error)
  • func (e *Engine) RespondAt(runID string, expected *protocol.RequestEnvelope, result json.RawMessage) (*Progress, error)
  • func (e *Engine) Resume(runID string, respBytes []byte, migrate bool) (*Progress, error)
  • func (e *Engine) StartRun(input json.RawMessage) (*Progress, error)
• type Progress

Types

type Engine

type Engine struct {
	SkillDir string
	RunsDir  string
	// Stderr receives subprocess diagnostics (compile errors etc.).
	Stderr *os.File
}

Engine binds a skill directory to a runs directory.

func New

func New(skillDir string) (*Engine, error)

New creates an engine rooted at the skill directory; run logs live in <skillDir>/.yield/runs.

func NewWithRunsDir

func NewWithRunsDir(skillDir, runsDir string) (*Engine, error)

NewWithRunsDir creates an engine whose durable run state is stored outside the workflow directory. Tests use this to avoid leaving local state behind.

func (*Engine) Continue

func (e *Engine) Continue(runID string) (*Progress, error)

Continue recovers a run after a response was committed but the process stopped before the next frontier was recorded.

func (*Engine) ListRuns

func (e *Engine) ListRuns() ([]string, error)

ListRuns returns known run IDs, newest last.

func (*Engine) Log

func (e *Engine) Log(runID string) (*runlog.Log, error)

Log opens a run's log for inspection.

func (*Engine) Pending

func (e *Engine) Pending(runID string) (*protocol.RequestEnvelope, error)

Pending returns the current unanswered operation without changing the run.

func (*Engine) Replay

func (e *Engine) Replay(runID string) (*Progress, error)

Replay re-executes the program against the full journal and verifies it reproduces the run's recorded frontier — the determinism check.

func (*Engine) Respond

func (e *Engine) Respond(runID string, result json.RawMessage) (*Progress, error)

Respond binds a bare result to the frontier observed when the call began. The frontier is checked again under the run lock before the result is used.

func (*Engine) RespondAt

func (e *Engine) RespondAt(runID string, expected *protocol.RequestEnvelope, result json.RawMessage) (*Progress, error)

RespondAt binds a result only if expected is still the current frontier.

func (*Engine) Resume

func (e *Engine) Resume(runID string, respBytes []byte, migrate bool) (*Progress, error)

Resume validates and accepts a response for the pending operation, then advances. migrate=true explicitly rebinds the run to the current skill digest (the migrate_digest mechanism; divergence detection remains the safety net).

func (*Engine) StartRun

func (e *Engine) StartRun(input json.RawMessage) (*Progress, error)

StartRun creates a run bound to the current skill digest and advances to the first agent-facing operation or terminal.

type Progress

type Progress struct {
	RunID    string
	Envelope *protocol.RequestEnvelope
	Terminal *protocol.TerminalOutcome
}

Advance's result: either the next operation for the agent, or a terminal status.