protocol

Documentation

Overview

Package protocol defines the yield.v1 wire protocol: the typed operation envelopes a skill program yields to the coding agent, and the response envelopes the agent (or yskill itself) feeds back. Everything that crosses a process boundary is defined here and nowhere else.

Index

• Constants
• func DigestBytes(b []byte) string
• func DigestSkillDir(dir string) (string, error)
• func RequestDigest(r Request) string
• func ValidateResult(schema, result json.RawMessage) error
• type AgentTaskPayload
• type AskUserPayload
• type AskUserResult
• type CommandResult
• type Divergence
• type InvalidProgramOutputError
  • func (e *InvalidProgramOutputError) Error() string
• type Journal
• type JournalEntry
• type OpKind
• type Option
• type OutputKind
• type ProgramOutput
  • func DecodeProgramOutput(raw []byte) (*ProgramOutput, error)
• type Request
• type RequestEnvelope
• type Requirement
• type ResponseEnvelope
• type RunCommandPayload
• type SkillRef
• type TerminalOutcome
• type TerminalStatus

Constants

const Version = "yield.v1"

Version is the protocol identifier carried by every request envelope.

Functions

func DigestBytes

func DigestBytes(b []byte) string

DigestBytes returns the canonical content digest string for a byte slice.

func DigestSkillDir

func DigestSkillDir(dir string) (string, error)

DigestSkillDir computes the skill source digest: sha256 over the sorted relative paths and contents of *.go, SKILL.md, and go.mod files.

func RequestDigest

func RequestDigest(r Request) string

RequestDigest is the canonical digest of a request, used for replay divergence detection: kind, id, payload, and output schema all bind. JSON fields are compacted first so that a request digests identically before and after a round-trip through the log (encoding/json compacts embedded RawMessage on marshal).

func ValidateResult

func ValidateResult(schema, result json.RawMessage) error

ValidateResult checks a completed result against the request's embedded JSON schema. A nil schema accepts any JSON value.

Types

type AgentTaskPayload

type AgentTaskPayload struct {
	Instruction string          `json:"instruction"`
	Context     json.RawMessage `json:"context,omitempty"`
}

AgentTaskPayload delegates a reasoning task to the model.

type AskUserPayload

type AskUserPayload struct {
	Question string   `json:"question"`
	Options  []Option `json:"options,omitempty"`
}

AskUserPayload asks a question through the host's normal interface.

type AskUserResult

type AskUserResult struct {
	Value string `json:"value"`
}

AskUserResult is the expected result shape for ask_user.

type CommandResult

type CommandResult struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	TimedOut bool   `json:"timed_out,omitempty"`
}

CommandResult is the observed outcome of a run_command operation.

type Divergence

type Divergence struct {
	Sequence int    `json:"sequence"`
	Expected string `json:"expected_digest"`
	Got      string `json:"got_digest"`
	Detail   string `json:"detail,omitempty"`
}

Divergence reports that replay produced a different operation at a recorded sequence — nondeterminism leaked between yields. It always fails the run loudly.

type InvalidProgramOutputError

type InvalidProgramOutputError struct {
	Reason string
}

InvalidProgramOutputError means a skill emitted bytes that are not one complete yield.v1 output variant. The engine must not dispatch such output.

func (*InvalidProgramOutputError) Error

func (e *InvalidProgramOutputError) Error() string

type Journal

type Journal struct {
	RunID   string         `json:"run_id"`
	Skill   SkillRef       `json:"skill"`
	Entries []JournalEntry `json:"entries"`
}

Journal is the replay input: the run identity plus all answered operations in sequence order.

type JournalEntry

type JournalEntry struct {
	Request  Request          `json:"request"`
	Response ResponseEnvelope `json:"response"`
}

JournalEntry is one recorded request/response pair handed to the skill subprocess for replay.

type OpKind

type OpKind string

OpKind is the closed set of operations a skill program may yield.

const (
	OpAskUser    OpKind = "ask_user"
	OpAgentTask  OpKind = "agent_task"
	OpRunCommand OpKind = "run_command"
)

type Option

type Option struct {
	Value string `json:"value"`
	Label string `json:"label,omitempty"`
}

type OutputKind

type OutputKind string

Program output types: a skill subprocess emits exactly one ProgramOutput per execution — the next yielded request, a terminal outcome, or a replay divergence report.

const (
	OutputRequest  OutputKind = "request"
	OutputTerminal OutputKind = "terminal"
	OutputDiverged OutputKind = "diverged"
)

type ProgramOutput

type ProgramOutput struct {
	Type         OutputKind       `json:"type"`
	Envelope     *RequestEnvelope `json:"envelope,omitempty"`
	Terminal     *TerminalOutcome `json:"terminal,omitempty"`
	Divergence   *Divergence      `json:"divergence,omitempty"`
	Requirements []Requirement    `json:"requirements,omitempty"`
}

func DecodeProgramOutput

func DecodeProgramOutput(raw []byte) (*ProgramOutput, error)

DecodeProgramOutput is the single admission boundary between an SDK subprocess and engine authority. It accepts exactly one complete variant and rejects unknown fields so future protocol changes fail closed until the IR, decoder, and dispatch logic are upgraded together.

type Request

type Request struct {
	ID           string          `json:"id"`
	Kind         OpKind          `json:"kind"`
	Payload      json.RawMessage `json:"payload"`
	OutputSchema json.RawMessage `json:"output_schema,omitempty"`
}

Request is one yielded operation.

type RequestEnvelope

type RequestEnvelope struct {
	Protocol string   `json:"protocol"`
	RunID    string   `json:"run_id"`
	Skill    SkillRef `json:"skill"`
	Sequence int      `json:"sequence"`
	Request  Request  `json:"request"`
}

RequestEnvelope is what the agent sees: one operation, bound to a run, a sequence number, and the skill digest.

type Requirement

type Requirement struct {
	Claim          string `json:"claim"`
	Passed         bool   `json:"passed"`
	EvidenceDigest string `json:"evidence_digest,omitempty"`
}

Requirement is a claim bound to evidence; a failed requirement prevents run completion.

type ResponseEnvelope

type ResponseEnvelope struct {
	RunID     string          `json:"run_id"`
	Sequence  int             `json:"sequence"`
	RequestID string          `json:"request_id"`
	Status    string          `json:"status"` // "completed" | "failed"
	Result    json.RawMessage `json:"result"`
}

ResponseEnvelope is what comes back for exactly one pending request.

type RunCommandPayload

type RunCommandPayload struct {
	Command        string `json:"command"`
	TimeoutSeconds int    `json:"timeout_seconds,omitempty"`
}

RunCommandPayload names a command yskill executes itself, so the result enters the log as observed fact rather than the agent's transcription.

type SkillRef

type SkillRef struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
	Digest  string `json:"digest"`
}

SkillRef identifies the skill a run is bound to. Digest is the content digest of the skill source; responses against a different digest are rejected unless explicitly migrated.

type TerminalOutcome

type TerminalOutcome struct {
	Status TerminalStatus  `json:"status"`
	Result json.RawMessage `json:"result,omitempty"`
	Reason string          `json:"reason,omitempty"`
}

type TerminalStatus

type TerminalStatus string

Terminal statuses.

const (
	StatusCompleted         TerminalStatus = "completed"
	StatusBlocked           TerminalStatus = "blocked"
	StatusRefused           TerminalStatus = "refused"
	StatusRequirementFailed TerminalStatus = "requirement_failed"
)