Documentation
¶
Overview ¶
Package spill implements large-result storage (M42), matching spill/spill, spill-local, and spill-policy. SaveText persists exact text and returns an opaque locator, exact byte count, and retrieval hint; storage failures return errors.
The local backend writes <root>/session-<sha256(sessionId)>/<random>-<safeName> under a private 0700 root, using exclusive creation and 0600 permissions to avoid symlink redirection. Consumer policy spills oversized tool/Bash output and retains a head/tail preview. On save failure it keeps original inline output so a successful tool call does not become an error solely because spilling failed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FileSpillStore ¶
type FileSpillStore struct {
// Root is a private 0700 directory, created automatically by default.
Root string
}
FileSpillStore writes artifacts into private, session-scoped host directories.
func NewFileStore ¶
func NewFileStore(root string) *FileSpillStore
NewFileStore creates a local file backend.
func (*FileSpillStore) ReadText ¶
func (s *FileSpillStore) ReadText(locator SpillLocator) (string, error)
ReadText reads by locator to recover original bytes for consumers or tests.
func (*FileSpillStore) SaveText ¶
func (s *FileSpillStore) SaveText(input SaveTextSpill) (SpillRef, error)
SaveText implements SpillStore using a private session directory.
type SaveTextSpill ¶
type SaveTextSpill struct {
// Owner selects the storage namespace.
Owner SpillOwner `json:"owner"`
// Source describes origin for naming and inspection.
Source SpillSource `json:"source"`
// SuggestedName is a proposed basename, sanitized by the backend into one safe path segment.
SuggestedName string `json:"suggestedName"`
// Content is the complete UTF-8 text to persist unchanged.
Content string `json:"content"`
}
SaveTextSpill requests text persistence.
type SpillLocator ¶
type SpillLocator string
SpillLocator is an opaque model-facing artifact handle. Local backends use paths; remote or database backends may use URIs or keys. Consumers display the retrieval hint rather than parsing the handle.
func (SpillLocator) String ¶
func (l SpillLocator) String() string
String returns the raw handle for formatting and logging.
type SpillOwner ¶
type SpillOwner struct {
// SessionID identifies the session producing the artifact.
SessionID brand.SessionID `json:"sessionId"`
}
SpillOwner selects the storage namespace by producing session.
type SpillRef ¶
type SpillRef struct {
// Locator is an opaque model-facing handle.
Locator SpillLocator `json:"locator"`
// Bytes is the exact encoded byte count.
Bytes int `json:"bytes"`
// RetrievalHint guides model retrieval, such as read <path> or grep ... <path>.
RetrievalHint string `json:"retrievalHint"`
}
SpillRef describes a saved artifact's locator, byte count, and retrieval hint.
func Apply ¶
func Apply(store SpillStore, input SaveTextSpill, text string, maxInlineBytes, previewBytes int) (inline string, ref *SpillRef, err error)
Apply spills text exceeding maxInlineBytes and returns a head/tail preview and reference. Smaller text returns unchanged with a nil reference. Save failures retain the original text and return an error for the caller to classify.
type SpillSource ¶
type SpillSource struct {
// ToolName identifies the producing tool.
ToolName string `json:"toolName"`
// CallID identifies the model call producing the result.
CallID brand.ToolCallID `json:"callId"`
// Label briefly describes the artifact.
Label string `json:"label"`
}
SpillSource identifies the producing tool and call for naming and inspection, not access control.
type SpillStore ¶
type SpillStore interface {
// SaveText persists all content unchanged and returns actual storage failures.
SaveText(input SaveTextSpill) (SpillRef, error)
}
SpillStore is the single-method ctx.spillStore interface.