agentjson

package

v0.2.0 Latest Latest Go to latest Published: Aug 1, 2026 License: MIT Imports: 11 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/0xkhdr/specd-cli

Links

Open Source Insights

Documentation ¶

Overview ¶

Package agentjson owns the one bounded, versioned document a headless agent reads. It projects canonical results; it decides no lifecycle, readiness, evidence, authority, or scope question of its own.

Index ¶

Constants
func Encode(envelope Envelope) ([]byte, error)
func Validate(envelope Envelope) error
type Bounded
- func Bound(text, digest, evidence string) Bounded
- func (bounded Bounded) Fields(prefix string) (map[string]any, error)
type Diagnostic
type Envelope
- func Decode(raw []byte) (Envelope, error)
type Exit
- func ExitFor(code int) (Exit, error)
type Next
type Root
type State
type Subject

Constants ¶

View Source

const (
	NextOperation    = "operation"
	NextHumanHandoff = "human_handoff"
	NextTerminal     = "terminal"
	NextBlocked      = "blocked"
)

Next-action variants. Exactly one is legal per envelope.

View Source

const (
	MaxDataKeys    = 40
	MaxStringBytes = 4096
	MaxListItems   = 64
	MaxDiagnostics = 100
)

Bounds keep the document small enough to read and impossible to use as a side channel for source text, transcripts, or unbounded process output.

View Source

const ExcerptLimit = 2048

ExcerptLimit bounds any process output that reaches the envelope. The full stream stays in stage-5 evidence; the envelope carries a sample and a way back to the authoritative record.

View Source

const Schema = "specd.agent/v1"

Schema is the only accepted envelope version. There is no alias and no compatibility reader: an incompatible client is refused, never reinterpreted.

Variables ¶

This section is empty.

Functions ¶

func Encode ¶

func Encode(envelope Envelope) ([]byte, error)

Encode validates and renders one document. An invalid envelope produces no bytes at all: a partial document is never presented as valid.

func Validate ¶

func Validate(envelope Envelope) error

Validate fails closed on every representable inconsistency.

Types ¶

type Bounded ¶

type Bounded struct {
	Excerpt   string
	Truncated bool
	Digest    string
	Evidence  string
}

Bounded is process output as the envelope may carry it: sampled, redacted, and always paired with the digest and evidence reference that make the truncation traceable.

func Bound ¶

func Bound(text, digest, evidence string) Bounded

Bound samples one stream. Binary bytes, control characters, and secret-like text cannot survive it, and an oversized stream is cut, never widened.

ponytail: verification already redacts what it records, so this is the second boundary rather than the only one; fold the two patterns into one owner if a third caller ever needs redaction.

func (Bounded) Fields ¶

func (bounded Bounded) Fields(prefix string) (map[string]any, error)

Fields projects the bounded stream into envelope data keys. An excerpt with no digest or evidence reference is refused: a sample that cannot be traced back to the authoritative record never ships.

type Diagnostic ¶

type Diagnostic struct {
	Code     string `json:"code"`
	Severity string `json:"severity"`
	Message  string `json:"message"`
	Path     string `json:"path,omitempty"`
	Line     int    `json:"line,omitempty"`
	Fix      string `json:"fix"`
}

Diagnostic locates one problem and supplies exactly one repair.

type Envelope ¶

type Envelope struct {
	Schema      string         `json:"schema"`
	OK          bool           `json:"ok"`
	Operation   string         `json:"operation"`
	Root        *Root          `json:"root,omitempty"`
	Subject     *Subject       `json:"subject,omitempty"`
	State       *State         `json:"state,omitempty"`
	Data        map[string]any `json:"data,omitempty"`
	Diagnostics []Diagnostic   `json:"diagnostics,omitempty"`
	Next        Next           `json:"next"`
	Exit        Exit           `json:"exit"`
}

Envelope is the whole agent-facing document. Field order here is the encoded key order, so goldens stay byte-stable.

func Decode ¶

func Decode(raw []byte) (Envelope, error)

Decode reads one document strictly: unknown keys, JSON null, trailing data, and any invalid shape are refusals.

type Exit ¶

type Exit struct {
	Code  int    `json:"code"`
	Class string `json:"class"`
}

Exit is the process outcome class. The three classes stay distinct so a fail-closed refusal is never read as a failed gate or as success.

func ExitFor ¶

func ExitFor(code int) (Exit, error)

ExitFor maps an exit code to its declared class.

type Next ¶

type Next struct {
	Kind        string            `json:"kind"`
	Operation   string            `json:"operation,omitempty"`
	Arguments   map[string]string `json:"arguments,omitempty"`
	Owner       string            `json:"owner,omitempty"`
	Reason      string            `json:"reason,omitempty"`
	Instruction string            `json:"instruction"`
}

Next is the single legal next action. Kind selects the variant; every field outside that variant must be absent, so no envelope offers two moves.

type Root ¶

type Root struct {
	Path string `json:"path"`
}

type State ¶

type State struct {
	Revision uint64 `json:"revision"`
}

type Subject ¶

type Subject struct {
	Change string `json:"change"`
	Task   string `json:"task,omitempty"`
}

Source Files ¶

View all Source files

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