spill

package
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 9 Imported by: 0

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.

Jump to

Keyboard shortcuts

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