refs

Documentation

Overview

Package refs parses @file references in a message and expands them into real tool-call + result pairs ahead of the user's text: a small file is injected via read, a directory via ls, and a large or non-text file is annotated in place with its shape so the model can choose whether to read it.

Index

• type Expander
  • func NewExpander(reg *tools.Registry, sink agent.Sink, policy tools.PathPolicy) *Expander
  • func (x *Expander) Expand(ctx context.Context, text string) Result
• type Index
  • func NewIndex(root string, policy tools.PathPolicy) *Index
  • func (idx *Index) Candidates(query string, inConversation func(path string) bool) []tui.Completion
• type Ref
  • func Parse(text string) []Ref
• type Result

Types

type Expander

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

Expander turns @ references in a message into synthetic read/ls tool-call + result pairs, or annotates them in place when too large or non-text.

func NewExpander

func NewExpander(reg *tools.Registry, sink agent.Sink, policy tools.PathPolicy) *Expander

NewExpander returns an expander backed by reg. read/ls run through the sink so their display order matches the transcript order. policy resolves @ paths to the same keys read/write/edit use.

func (*Expander) Expand

func (x *Expander) Expand(ctx context.Context, text string) Result

Expand resolves every @ reference in text. Small text files inject a read pair (deduped against the tracker), directories an ls pair regardless of enabled state, and large/non-text files annotate in place. Re-expanding an annotated ref replaces its measurement rather than appending a second.

type Index

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

Index enumerates workspace paths for @ completion, respecting .gitignore via git ls-files in a repo and a skip-listed walk otherwise. It caches the result on a TTL so Complete never blocks on a walk.

func NewIndex

func NewIndex(root string, policy tools.PathPolicy) *Index

NewIndex returns an index rooted at root. The root is resolved through policy so completions match the same keys read/write/edit use.

func (*Index) Candidates

func (idx *Index) Candidates(query string, inConversation func(path string) bool) []tui.Completion

Candidates returns paths matching query, ranked by (a) already in the conversation, (b) recent mtime, (c) fuzzy score. Directories complete with a trailing `/` so accepting one re-opens it deeper. The result is relative to the root for display; a `~` or `~/...` query completes within the user's home directory instead, keeping the leading ~ in each candidate.

type Ref

type Ref struct {
	Path  string // the path as written, without @ or annotation
	Start int    // byte offset of the leading @ in the message
	End   int    // byte offset just past the token (path or annotation)
	Note  string // any absorbed trailing (...), empty when none
}

Ref is one @path token in a message. Note carries any existing `(800 lines, 64kb)` measurement absorbed into the token, which is what makes re-expansion idempotent: expansion recognises it and replaces it rather than appending a second measurement.

func Parse

func Parse(text string) []Ref

Parse returns every @path reference in text. @ matches only at a word boundary (start of line, or after whitespace / `(`, `[`, a quote) so `email@example.com` is prose. The path token stops at whitespace or trailing punctuation, and a trailing `(...)` measurement is absorbed into Note so re-expansion replaces it.

type Result

type Result struct {
	Text    string
	Before  []llm.Message
	Notices []string
}

Result is the outcome of expanding one message's @ references: the rewritten text (with annotations in place), the synthetic messages to append ahead of it, and any notices.