hide

Documentation

Overview

Package hide implements the HideBuffer — an in-process store for large tool outputs. Agents receive bounded cut pages instead of the full raw content, preserving jurisdiction without saturating the context window.

Design rule: paging is not truncation — it is jurisdiction.

Index

• func ToolDefs() []model.ToolDefinition
• type Cut
  • func (c Cut) Format() string
• type Hide
• type HideBuffer
  • func NewHideBuffer(pageSize int) *HideBuffer
  • func (b *HideBuffer) Cut(id string, page int) (Cut, error)
  • func (b *HideBuffer) FirstCut() (Cut, error)
  • func (b *HideBuffer) Get(id string) (*Hide, bool)
  • func (b *HideBuffer) NeedsPaging() bool
  • func (b *HideBuffer) ResolveID(id string) (string, bool)
  • func (b *HideBuffer) Search(id, query string) (Cut, bool, error)
  • func (b *HideBuffer) Store(source, content string) *Hide
• type Store
  • func NewStore(dir string) *Store
  • func (s *Store) Cut(id string, page, pageSizeBytes int) (Cut, error)
  • func (s *Store) Delete(id string) error
  • func (s *Store) Get(id string) (StoreEntry, []byte, error)
  • func (s *Store) List() ([]StoreEntry, error)
  • func (s *Store) LoadIntoBuffer(id string, pageSize int) (*HideBuffer, error)
  • func (s *Store) Put(kind, source string, content []byte, meta map[string]string) (StoreEntry, error)
• type StoreEntry

Functions

func ToolDefs

func ToolDefs() []model.ToolDefinition

ToolDefs returns the three built-in hide navigation tool definitions. These are injected into every turn's tool scope when a HideBuffer is configured.

Types

type Cut

type Cut struct {
	// HideID is the ID of the parent hide.
	HideID string
	// Source is the tool name that produced the parent hide.
	Source string
	// PageNumber is the 1-indexed page number of this cut.
	PageNumber int
	// TotalPages is the total number of pages in the parent hide.
	TotalPages int
	// SizeBytes is the byte count of this cut's Content.
	SizeBytes int
	// Content is the substring of Hide.Content for this page.
	Content string
	// IsFinal is true when PageNumber == TotalPages.
	IsFinal bool
	// ReflectionHint, when non-empty, replaces the default navigation/final-page
	// hint in Format(). Use it to embed per-page instructions (e.g. "list key
	// facts from this page") directly inside the tool result so the model sees
	// them as part of the page content, not as a separate user turn.
	ReflectionHint string
}

Cut is a bounded page view of a hide. PageNumber is 1-indexed.

func (Cut) Format

func (c Cut) Format() string

Format returns a plain-text envelope for this cut suitable for delivery to an LLM. It is token-efficient, self-contained, and includes a navigation hint so the agent knows how to request additional pages.

type Hide

type Hide struct {
	// ID is the unique buffer identifier in the form
	// "hide_<sanitized-source>_<yyyymmdd>_<HHMM>_<4-hex>".
	ID string
	// Source is the tool name that produced this hide.
	Source string
	// Content is the full raw content — never sent to the agent directly.
	Content string
	// CreatedAt is the time the hide was stored.
	CreatedAt time.Time
}

Hide is a stored large raw tool result.

type HideBuffer

type HideBuffer struct {
	ReflectionHint string // optional per-page instruction embedded in non-final Cut headers
	// contains filtered or unexported fields
}

HideBuffer is an in-process store for hides. It is safe for concurrent use.

func NewHideBuffer

func NewHideBuffer(pageSize int) *HideBuffer

NewHideBuffer creates a new HideBuffer. pageSize is the number of bytes in each cut; values <= 0 default to 3800.

func (*HideBuffer) Cut

func (b *HideBuffer) Cut(id string, page int) (Cut, error)

Cut returns a bounded page of a hide. page is 1-indexed. Returns an error when id is not found or page is out of range (< 1 or > TotalPages).

func (*HideBuffer) FirstCut

func (b *HideBuffer) FirstCut() (Cut, error)

FirstCut returns the first cut (page 1) of the first hide in the buffer. Returns an error when the buffer is empty.

func (*HideBuffer) Get

func (b *HideBuffer) Get(id string) (*Hide, bool)

Get retrieves a Hide by ID. Returns (nil, false) when the ID is not found.

func (*HideBuffer) NeedsPaging

func (b *HideBuffer) NeedsPaging() bool

NeedsPaging reports whether any hide in the buffer has more than one page. Used by callers to decide whether to include hide navigation tools in the model's tool scope — there is no point advertising hide_next when all content fits on page 1.

func (*HideBuffer) ResolveID

func (b *HideBuffer) ResolveID(id string) (string, bool)

ResolveID returns id when it exists, or the only active hide ID when the buffer contains exactly one hide. The fallback is scoped to this buffer so a model cannot navigate arbitrary persisted hides by guessing IDs.

func (*HideBuffer) Search

func (b *HideBuffer) Search(id, query string) (Cut, bool, error)

Search returns the first Cut containing query (case-insensitive byte scan). Returns (cut, true, nil) on hit; (page-1 cut, false, nil) on miss; error on bad id.

func (*HideBuffer) Store

func (b *HideBuffer) Store(source, content string) *Hide

Store adds content to the buffer and returns the newly created Hide.

type Store

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

Store is a file-backed persistent store for raw hides (large inputs). Each hide occupies one subdirectory: <dir>/<id>/meta.json + <dir>/<id>/content. The Store type realizes the HideStore concept from the glossary.

func NewStore

func NewStore(dir string) *Store

NewStore returns a Store rooted at dir. Dir need not exist yet.

func (*Store) Cut

func (s *Store) Cut(id string, page, pageSizeBytes int) (Cut, error)

Cut returns a bounded page of a stored hide without loading the full content. Reads only the required byte range using ReadAt semantics. Reuses the Cut type.

func (*Store) Delete

func (s *Store) Delete(id string) error

Delete removes the hide directory and all its contents from disk.

func (*Store) Get

func (s *Store) Get(id string) (StoreEntry, []byte, error)

Get returns the StoreEntry metadata and raw content for the given hide ID. Returns an os.ErrNotExist-wrapped error when the hide directory, content file, or meta.json file does not exist (including partial-write cases). Returns a different error only when meta.json exists but is malformed JSON.

func (*Store) List

func (s *Store) List() ([]StoreEntry, error)

List returns all StoreEntry values sorted by CreatedAt descending. Silently skips directories with missing or malformed meta.json.

func (*Store) LoadIntoBuffer

func (s *Store) LoadIntoBuffer(id string, pageSize int) (*HideBuffer, error)

LoadIntoBuffer reads the full hide content and returns an in-memory HideBuffer. This is the bridge between the persistent Store and the runner's HideBuffer field. pageSize <= 0 defaults to 3800.

func (*Store) Put

func (s *Store) Put(kind, source string, content []byte, meta map[string]string) (StoreEntry, error)

Put writes content and metadata to disk; returns the generated StoreEntry. Write order: content first, then meta.json. If the process crashes between the two, the directory exists without meta.json — List silently skips it (partial-write guard).

type StoreEntry

type StoreEntry struct {
	// ID is the unique hide identifier.
	ID string `json:"id"`
	// Kind is the hide type label (e.g. "github.pr_review_thread").
	Kind string `json:"kind"`
	// Source is the origin: tool name, webhook path, or "cli".
	Source string `json:"source"`
	// SizeBytes is the byte count of the stored content.
	SizeBytes int64 `json:"size_bytes"`
	// CreatedAt is the Unix timestamp when the hide was written.
	CreatedAt int64 `json:"created_at"`
	// Metadata holds arbitrary key-value labels for this hide.
	Metadata map[string]string `json:"metadata,omitempty"`
}

StoreEntry is the persisted metadata for a stored hide.