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 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 PlannerNoteData struct {
	// Note is the planner annotation text.
	Note string
}

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 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 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
}

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