memory

type Annotation struct {
	// Message is the textual annotation provided by the planner or policy engine.
	Message string
	// Labels carries structured metadata associated with the annotation, used for
	// filtering or categorization (e.g., {"severity": "warning"}).
	Labels map[string]string
}

type AssistantMessageData struct {
	// Message is the assistant text content.
	Message string
	// Structured carries optional typed assistant output.
	Structured any
}

type Entry struct {
	ID        string
	Scope     Scope
	Content   string
	Author    string
	Timestamp time.Time
	Sources   []SourceRef
	Labels    map[string]string
	Metadata  map[string]any
}

type Event struct {
	// Type indicates the category of the event (message, tool call, result, etc.).
	Type EventType
	// Timestamp marks when the event occurred, used for ordering and filtering.
	Timestamp time.Time
	// Data holds the event-specific payload encoded as a generic map for storage.
	// Callers should construct and decode it via the typed helpers in
	// `event_data.go` instead of reaching into string keys directly.
	Data any
	// Labels provides structured metadata for filtering, querying, or policy decisions.
	// Examples: {"role": "user"}, {"tool": "search"}, {"error": "timeout"}.
	Labels map[string]string
}

type EventData interface {
	// EventType reports which persisted event kind this payload belongs to.
	EventType() EventType
	// ToMap converts the typed payload into the generic storage representation.
	ToMap() map[string]any
}

type EventType string

type IngestEventsInput struct {
	Scope        Scope
	AgentID      string
	SessionID    string
	RunID        string
	StartOrdinal int
	Events       []Event
	Labels       map[string]string
	Metadata     map[string]any
}

type IngestResult struct {
	Entries   []Entry
	Skipped   int
	Truncated bool
}

type IngestRunInput struct {
	Scope     Scope
	AgentID   string
	SessionID string
	RunID     string
	Events    []Event
	Labels    map[string]string
	Metadata  map[string]any
}

type PlannerNoteData struct {
	// Note is the planner annotation text.
	Note string
}

type PutEntryInput struct {
	Scope     Scope
	Content   string
	Author    string
	Timestamp time.Time
	Sources   []SourceRef
	Labels    map[string]string
	Metadata  map[string]any
}

type Query struct {
	AgentID   string
	RunID     string
	SessionID string
	Labels    map[string]string
	Types     []EventType
	Limit     int
}

type QueryResult struct {
	Events    []Event
	Truncated bool
}

type Reader interface {
	// Events returns all events in chronological order.
	Events() []Event

	// FilterByType returns events matching the given type, preserving chronological order.
	FilterByType(t EventType) []Event

	// Latest returns the most recent event of the given type. The boolean return
	// indicates whether an event was found (false if no events of that type exist).
	Latest(t EventType) (Event, bool)
}

type RetryHintData struct {
	Reason             string
	Tool               tools.Ident
	RestrictToTool     bool
	MissingFields      []string
	ExampleInput       map[string]any
	PriorInput         map[string]any
	ClarifyingQuestion string
	Message            string
}

type Scope struct {
	Namespace  string
	UserID     string
	Visibility Visibility
}

type ScopeInput struct {
	AgentID    string
	SessionID  string
	RunID      string
	Visibility Visibility
	Labels     map[string]string
	Payload    map[string]any
}

type ScopeResolver interface {
	ResolveMemoryScope(ctx context.Context, input ScopeInput) (Scope, error)
}

type ScopeResolverFunc func(ctx context.Context, input ScopeInput) (Scope, error)

type SearchHit struct {
	Entry       Entry
	Score       float64
	Snippet     string
	MatchedRefs []SourceRef
}

type SearchQuery struct {
	Scope  Scope
	Query  string
	Labels map[string]string
	Limit  int
}

type SearchResult struct {
	Hits      []SearchHit
	Truncated bool
}

type Searcher interface {
	Query(ctx context.Context, query Query) (QueryResult, error)
}

type SearcherFunc func(ctx context.Context, query Query) (QueryResult, error)

type Service interface {
	IngestRun(ctx context.Context, input IngestRunInput) (IngestResult, error)
	IngestEvents(ctx context.Context, input IngestEventsInput) (IngestResult, error)
	PutEntry(ctx context.Context, input PutEntryInput) (Entry, error)
	Search(ctx context.Context, query SearchQuery) (SearchResult, error)
}

type Snapshot struct {
	// AgentID identifies the agent that produced this run.
	AgentID string
	// RunID identifies the workflow run associated with this snapshot.
	RunID string
	// Events lists the chronological memory events persisted so far, ordered by
	// Timestamp ascending. Empty if the run has no history yet.
	Events []Event
	// Meta carries implementation-defined metadata such as database cursors,
	// version numbers, or sync tokens. Planners should not rely on these fields.
	Meta map[string]any
}

type SourceKind string

type SourceRef struct {
	Kind           SourceKind
	AgentID        string
	SessionID      string
	RunID          string
	EventOrdinal   int
	EventHash      string
	ToolCallID     string
	ExternalID     string
	IdempotencyKey string
}

type Store interface {
	// LoadRun retrieves the snapshot for the given agent and run. Returns an empty
	// snapshot (not an error) if the run doesn't exist yet, allowing callers to
	// treat absence as empty history. Returns an error only for storage failures
	// or connectivity issues.
	LoadRun(ctx context.Context, agentID, runID string) (Snapshot, error)

	// AppendEvents appends events to the run's history. Events should be written
	// atomically if the backend supports it. Returns an error if the write fails.
	// Implementations may deduplicate or reject events based on timestamps or IDs.
	AppendEvents(ctx context.Context, agentID, runID string, events ...Event) error
}

type ThinkingData struct {
	// Text is the plaintext reasoning content.
	Text string
	// Signature is the provider-issued signature for plaintext reasoning.
	Signature string
	// Redacted holds opaque redacted reasoning bytes.
	Redacted []byte
	// ContentIndex is the provider content block index.
	ContentIndex int
	// Final reports whether the provider finalized this block.
	Final bool
}

type ToolCallData struct {
	// ToolCallID uniquely identifies the invocation.
	ToolCallID string
	// ParentToolCallID links nested tool calls to their parent.
	ParentToolCallID string
	// ToolName is the canonical tool identifier.
	ToolName tools.Ident
	// PayloadJSON is the canonical JSON encoding of the tool input.
	PayloadJSON rawjson.Message
	// Queue is the activity queue where execution was scheduled.
	Queue string
	// ExpectedChildrenTotal records the expected number of child calls.
	ExpectedChildrenTotal int
}

type ToolResultData struct {
	// ToolCallID uniquely identifies the invocation.
	ToolCallID string
	// ParentToolCallID links nested tool calls to their parent.
	ParentToolCallID string
	// ToolName is the canonical tool identifier.
	ToolName tools.Ident
	// ResultJSON is the canonical JSON encoding of the successful result.
	ResultJSON rawjson.Message
	// ServerData carries server-only tool result data that must not be sent to models.
	ServerData rawjson.Message
	// Preview is the already-rendered user-facing result summary.
	Preview string
	// Bounds describes bounded-result metadata when present.
	Bounds *agent.Bounds
	// Duration is the wall-clock tool execution time.
	Duration time.Duration
	// Telemetry carries structured execution metrics when present.
	Telemetry *telemetry.ToolTelemetry
	// RetryHint carries structured repair guidance for failed tool calls.
	RetryHint *RetryHintData
	// ErrorMessage is the plain-text tool failure message.
	ErrorMessage string
	// Artifacts contains persisted artifact references associated with the result.
	Artifacts []artifact.Ref
}

type ToolSource string

type UserMessageData struct {
	// Message is the user-visible text content.
	Message string
	// Structured carries optional typed user payloads.
	Structured any
}

type Visibility string