Help us shape the future of Go! Take the 2026 Go Developer Survey

threadquery

package
v7.73.1 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package threadquery defines authorized, read-only queries over canonical active thread paths. Hosts supply Scope separately from model-authored input.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidQuery      = errors.New("invalid thread query")
	ErrCursorInvalid     = errors.New("thread query cursor is invalid; query again")
	ErrSnapshotLimit     = errors.New("thread query snapshot limit exceeded; narrow the query")
	ErrRecordUnavailable = errors.New("thread query record is unavailable; query again")
)

Functions

This section is empty.

Types

type AggregateInput 

type AggregateInput struct {
	Object  Object `json:"object"`
	Filter  Filter `json:"filter,omitempty"`
	GroupBy string `json:"group_by,omitempty"`
	Sort    Sort   `json:"sort,omitempty"`
	Limit   int    `json:"limit,omitempty"`
	Cursor  string `json:"cursor,omitempty"`
}

GroupBy is thread/role/tool_name/status/day/week/month. Calendar groups use UTC; weeks start Monday. Empty GroupBy requests the exact count only.

type AggregatePage 

type AggregatePage struct {
	Total      int       `json:"total"`
	Groups     []Group   `json:"groups"`
	NextCursor string    `json:"next_cursor,omitempty"`
	ExpiresAt  time.Time `json:"expires_at"`
}

type Chunk 

type Chunk struct {
	Field  string `json:"field"`
	Offset int    `json:"offset"`
	Text   string `json:"text"`
}

Content chunks carry field-local byte offsets. Each chunk is valid UTF-8, at most 16 KiB; all chunks in one response total at most 64 KiB. Continuation is explicit, including at field boundaries. Missing hosted fields stay absent.

type Filter 

type Filter struct {
	ThreadIDs       []identity.ThreadID `json:"thread_ids,omitempty"`
	ParentThreadIDs []identity.ThreadID `json:"parent_thread_ids,omitempty"`
	TurnIDs         []identity.TurnID   `json:"turn_ids,omitempty"`
	RunIDs          []identity.RunID    `json:"run_ids,omitempty"`
	Roles           []string            `json:"roles,omitempty"`
	ToolNames       []string            `json:"tool_names,omitempty"`
	ToolKinds       []string            `json:"tool_kinds,omitempty"`
	Statuses        []string            `json:"statuses,omitempty"`
	Activities      []string            `json:"activities,omitempty"`
	Outcomes        []string            `json:"outcomes,omitempty"`
	Text            TextMatch           `json:"text,omitempty"`
	Title           TextMatch           `json:"title,omitempty"`
	Arguments       TextMatch           `json:"arguments,omitempty"`
	Result          TextMatch           `json:"result,omitempty"`
	Time            TimeRange           `json:"time,omitempty"`
	Created         TimeRange           `json:"created,omitempty"`
	Updated         TimeRange           `json:"updated,omitempty"`
	Completed       TimeRange           `json:"completed,omitempty"`
}

type Group 

type Group struct {
	Key   string `json:"key"`
	Count int    `json:"count"`
}

type Object 

type Object string
const (
	Threads   Object = "threads"
	Messages  Object = "messages"
	ToolCalls Object = "tool_calls"
)

type Page 

type Page struct {
	Records    []Record  `json:"records"`
	Total      int       `json:"total"`
	NextCursor string    `json:"next_cursor,omitempty"`
	ExpiresAt  time.Time `json:"expires_at"`
}

type QueryInput 

type QueryInput struct {
	Object Object `json:"object"`
	Filter Filter `json:"filter,omitempty"`
	Sort   Sort   `json:"sort,omitempty"`
	Limit  int    `json:"limit,omitempty"`
	Cursor string `json:"cursor,omitempty"`
}

type ReadInput 

type ReadInput struct {
	Ref    RecordRef `json:"ref"`
	Cursor string    `json:"cursor,omitempty"`
}

type ReadPage 

type ReadPage struct {
	Record     Record    `json:"record"`
	Chunks     []Chunk   `json:"chunks"`
	NextCursor string    `json:"next_cursor,omitempty"`
	ExpiresAt  time.Time `json:"expires_at"`
}

type Record 

type Record struct {
	Ref            RecordRef         `json:"ref"`
	Object         Object            `json:"object"`
	ThreadID       identity.ThreadID `json:"thread_id"`
	ParentThreadID identity.ThreadID `json:"parent_thread_id,omitempty"`
	TurnID         identity.TurnID   `json:"turn_id,omitempty"`
	RunID          identity.RunID    `json:"run_id,omitempty"`
	ToolCallID     string            `json:"tool_call_id,omitempty"`
	Title          string            `json:"title,omitempty"`
	Role           string            `json:"role,omitempty"`
	ToolName       string            `json:"tool_name,omitempty"`
	ToolKind       string            `json:"tool_kind,omitempty"`
	Status         string            `json:"status,omitempty"`
	Activity       string            `json:"activity,omitempty"`
	Outcome        string            `json:"outcome,omitempty"`
	Time           time.Time         `json:"time"`
	CreatedAt      time.Time         `json:"created_at,omitempty"`
	UpdatedAt      time.Time         `json:"updated_at,omitempty"`
	CompletedAt    time.Time         `json:"completed_at,omitempty"`
	Elapsed        time.Duration     `json:"elapsed_ns,omitempty"`
	Order          int64             `json:"order,omitempty"`
	Snippet        string            `json:"snippet,omitempty"`
}

type RecordRef 

type RecordRef string

RecordRef is an opaque exact reference returned by Query, bound to its scope and snapshot. It cannot be used to authorize a thread or reconstruct history.

type Scope 

type Scope struct {
	Authority string              `json:"-"`
	ThreadIDs []identity.ThreadID `json:"-"`
}

Scope must be reconstructed by the host on every call, including pagination. Authority identifies the user, runtime and namespace; ThreadIDs is the exact currently readable set. Empty sets grant no access. References grant none.

type Sort 

type Sort struct {
	Key        string `json:"key,omitempty"`
	Descending bool   `json:"descending,omitempty"`
}

Sort keys: threads created/updated/title/thread_id; messages time/order; tool_calls time/completed/tool_name/elapsed. Stable identity breaks all ties.

type TextMatch 

type TextMatch struct {
	Contains      string   `json:"contains,omitempty"`
	Keywords      []string `json:"keywords,omitempty"`
	AnyKeyword    bool     `json:"any_keyword,omitempty"`
	Phrase        string   `json:"phrase,omitempty"`
	CaseSensitive bool     `json:"case_sensitive,omitempty"`
}

TextMatch combines its nonempty conditions with AND. Keywords match literal substrings, with OR when AnyKeyword is true. Phrase is a contiguous literal phrase. Matching is Unicode-aware, case-insensitive by default, never fuzzy.

type TimeRange 

type TimeRange struct {
	From time.Time `json:"from,omitempty"`
	To   time.Time `json:"to,omitempty"`
}

TimeRange uses UTC instants with an inclusive From and exclusive To.

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.