yield

Documentation

Overview

Package yield is the skill-program SDK. A skill is an ordinary Go main package that calls Main with a deterministic program. Every side effect crosses a yielded primitive; code between yields must be deterministic — that is what makes replay-based resume sound.

Execution model (deterministic re-execution): on every run/resume the program re-executes from the top. Recorded responses are fed back in order; at the first unanswered operation the SDK emits a yield.v1 request envelope on stdout and exits. If a replayed step produces a different operation than the journal recorded, the SDK reports divergence and the run fails loudly — it never silently forks.

Index

• Constants
• func Main(program func(*Context) (Outcome, error))
• type BlockedError
  • func (e *BlockedError) Error() string
• type Context
  • func (c *Context) AgentTask(id, instruction string, contextData any, schema json.RawMessage) json.RawMessage
  • func (c *Context) AskUser(id, question string, options ...Option) string
  • func (c *Context) Blocked(reason string) error
  • func (c *Context) Complete(result any) (Outcome, error)
  • func (c *Context) Refused(reason string) error
  • func (c *Context) Require(ok bool, claim string, evidence any)
  • func (c *Context) RunCommand(id, command string, timeoutSeconds int) protocol.CommandResult
• type Option
• type Outcome
• type RefusedError
  • func (e *RefusedError) Error() string

Constants

const EnvJournal = "YIELD_JOURNAL"

EnvJournal names the environment variable pointing at the journal file the supervisor (yskill) hands to the subprocess.

Functions

func Main

func Main(program func(*Context) (Outcome, error))

Main runs a skill program under the supervisor protocol. It reads the journal named by YIELD_JOURNAL, executes the program, and emits exactly one ProgramOutput on stdout.

Types

type BlockedError

type BlockedError struct{ Reason string }

Blocked ends the run at a true frontier, explicitly.

func (*BlockedError) Error

func (e *BlockedError) Error() string

type Context

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

Context carries the replay cursor and the primitives.

func (*Context) AgentTask

func (c *Context) AgentTask(id, instruction string, contextData any, schema json.RawMessage) json.RawMessage

AgentTask delegates reasoning to the model. schema (JSON Schema bytes, may be nil) is enforced by the supervisor on resume; the returned raw message is schema-valid by construction.

func (*Context) AskUser

func (c *Context) AskUser(id, question string, options ...Option) string

AskUser yields a question to be asked through the host's normal interface and returns the selected value on resume.

func (*Context) Blocked

func (c *Context) Blocked(reason string) error

Blocked returns the terminal blocked error.

func (*Context) Complete

func (c *Context) Complete(result any) (Outcome, error)

Complete finishes the run with a result; evidence is the requirement trail accumulated via Require.

func (*Context) Refused

func (c *Context) Refused(reason string) error

Refused returns the terminal refused error.

func (*Context) Require

func (c *Context) Require(ok bool, claim string, evidence any)

Require binds a claim to evidence. A failed requirement terminates the program immediately with a requirement_failed outcome; completion is structurally unreachable past a failed requirement.

func (*Context) RunCommand

func (c *Context) RunCommand(id, command string, timeoutSeconds int) protocol.CommandResult

RunCommand yields a command that yskill executes itself — the result is observed fact, not the agent's account of it.

type Option

type Option struct {
	Value string
	Label string
}

Option is one allowed answer to an AskUser question.

type Outcome

type Outcome struct {
	Result any
}

Outcome is what a program returns on success.

type RefusedError

type RefusedError struct{ Reason string }

Refused ends the run because the skill declines to proceed.

func (*RefusedError) Error

func (e *RefusedError) Error() string