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 Journal
• type JournalEntry
• type OpKind
• type Option
• type ProgramOutput
• type Request
• type RequestEnvelope
• type Requirement
• type ResponseEnvelope
• type RunCommandPayload
• type SkillRef
• type TerminalOutcome

Constants

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

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 (
	StatusCompleted         = "completed"
	StatusBlocked           = "blocked"
	StatusRefused           = "refused"
	StatusRequirementFailed = "requirement_failed"
)

Terminal statuses.

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 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 ProgramOutput

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

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 string          `json:"status"`
	Result json.RawMessage `json:"result,omitempty"`
	Reason string          `json:"reason,omitempty"`
}