envelope

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 31, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package envelope defines domain-neutral JSON tool result envelopes and helpers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppendLimitHint 

func AppendLimitHint(next []string, atLimit bool, hint string) []string

AppendLimitHint appends a paging hint when a list response hit its limit.

func CapSlice 

func CapSlice[T any](items []T, limit int) (out []T, truncated bool)

CapSlice returns at most limit items and reports whether the input was truncated.

func Hint 

func Hint(tool string, parts ...string) string

Hint builds a string continuation hint such as `tool arg=value`.

func HintParam 

func HintParam(key, value string) string

HintParam formats a key=value hint argument using Go quoting rules.

func MarshalIndent 

func MarshalIndent(env *Envelope) ([]byte, error)

MarshalIndent encodes an envelope as indented JSON.

func MarshalText 

func MarshalText(env *Envelope) (string, error)

MarshalText encodes an envelope as indented JSON text.

func PreviewField 

func PreviewField(text string, limit int) (preview string, truncated bool)

PreviewField is an alias for TruncateText.

func SummarizeCount 

func SummarizeCount(count int, unit string, next []string) (summary string, out []string)

SummarizeCount formats a count summary and optional next hints.

func TruncateText 

func TruncateText(text string, limit int) (preview string, truncated bool)

TruncateText returns a preview capped at limit bytes/chars and whether truncation occurred.

Types

type BoundList 

type BoundList[T any] struct {
	Items     []T
	Truncated bool
	Total     int
	Limit     int
}

BoundList is a capped slice with truncation metadata.

func CapSliceMeta 

func CapSliceMeta[T any](items []T, limit int) BoundList[T]

CapSliceMeta returns a capped slice with truncation metadata.

type Builder 

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

Builder constructs an Envelope fluently.

func Success 

func Success(name string) *Builder

Success starts a successful envelope for tool or method name.

func (*Builder) AnswerContext 

func (b *Builder) AnswerContext(context string) *Builder

AnswerContext sets concise LLM-facing synthesis context.

func (*Builder) Build 

func (b *Builder) Build() Envelope

Build returns the constructed envelope.

func (*Builder) Data 

func (b *Builder) Data(data any) *Builder

Data sets structured payload data.

func (*Builder) Diagnostic 

func (b *Builder) Diagnostic(items ...Diagnostic) *Builder

Diagnostic appends diagnostics.

func (*Builder) Method 

func (b *Builder) Method(name string) *Builder

Method sets the method name.

func (*Builder) NextActions 

func (b *Builder) NextActions(actions ...NextAction) *Builder

NextActions sets structured continuations.

func (*Builder) NextHints 

func (b *Builder) NextHints(hints ...string) *Builder

NextHints sets string continuation hints and derives structured next actions.

func (*Builder) Quality 

func (b *Builder) Quality(signals ...QualitySignal) *Builder

Quality appends quality signals.

func (*Builder) Subject 

func (b *Builder) Subject(kind, id string) *Builder

Subject appends one subject reference.

func (*Builder) SubjectRole 

func (b *Builder) SubjectRole(kind, id, role string) *Builder

SubjectRole appends one subject with a role.

func (*Builder) Subjects 

func (b *Builder) Subjects(subjects ...Subject) *Builder

Subjects replaces all subjects.

func (*Builder) Summary 

func (b *Builder) Summary(summary string) *Builder

Summary sets the short user-meaningful summary.

func (*Builder) Tool 

func (b *Builder) Tool(name string) *Builder

Tool sets the tool name.

type Diagnostic 

type Diagnostic struct {
	Code     string `json:"code,omitempty"`
	Message  string `json:"message,omitempty"`
	Severity string `json:"severity,omitempty"`
	Detail   any    `json:"detail,omitempty"`
}

Diagnostic carries implementation detail kept separate from answer content.

type Envelope 

type Envelope struct {
	OK            bool            `json:"ok"`
	Tool          string          `json:"tool,omitempty"`
	Method        string          `json:"method,omitempty"`
	Summary       string          `json:"summary,omitempty"`
	AnswerContext string          `json:"answer_context,omitempty"`
	Subjects      []Subject       `json:"subjects,omitempty"`
	Data          any             `json:"data,omitempty"`
	NextActions   []NextAction    `json:"next_actions,omitempty"`
	Next          []string        `json:"next,omitempty"`
	Quality       []QualitySignal `json:"quality_signals,omitempty"`
	Diagnostics   []Diagnostic    `json:"diagnostics,omitempty"`
	Error         string          `json:"error,omitempty"`
}

Envelope is the agent-facing tool result payload.

func Error 

func Error(summary string, err error) Envelope

Error builds a failure envelope.

func Errorf 

func Errorf(format string, args ...any) Envelope

Errorf builds a failure envelope from a formatted message.

type NextAction 

type NextAction struct {
	Tool string            `json:"tool,omitempty"`
	Hint string            `json:"hint,omitempty"`
	Args map[string]string `json:"args,omitempty"`
}

NextAction describes a capability or continuation the caller can invoke next.

func HintsToActions 

func HintsToActions(hints ...string) []NextAction

HintsToActions converts string hints into structured next actions.

func NextActionFromHint 

func NextActionFromHint(hint string) NextAction

NextActionFromHint parses a simple `tool key=value` hint into a NextAction.

type QualitySignal 

type QualitySignal struct {
	Name  string  `json:"name"`
	Value any     `json:"value,omitempty"`
	Score float64 `json:"score,omitempty"`
	Note  string  `json:"note,omitempty"`
}

QualitySignal carries optional confidence or completeness metadata.

type Subject 

type Subject struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Role string `json:"role,omitempty"`
}

Subject identifies a domain entity referenced by the tool result.

func FilterSubjects 

func FilterSubjects(subjects ...Subject) []Subject

FilterSubjects returns subjects with non-empty kind and id.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.