threadquery

package
v7.57.0 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 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.