baseAgent

type AgentSession struct {
	// Use Prompt for session orchestration. Direct Agent runs bypass automatic
	// compaction; their persisted messages are checked on the next session prompt.
	Agent          *agent.Agent
	SessionManager *SessionManager
	// contains filtered or unexported fields
}

type AgentSessionEvent interface {
	agent.AgentEvent
}

type AgentSessionEventListener func(event AgentSessionEvent)

type AuthStore interface {
	APIKey(provider ai.Provider) (string, bool)
}

type BranchSummaryEntry struct {
	SessionEntryBase
	FromID   string `json:"fromId"`
	Summary  string `json:"summary"`
	Details  any    `json:"details,omitempty"`
	FromHook *bool  `json:"fromHook,omitempty"`
}

type BranchSummaryMessage struct {
	Role      string `json:"role"`
	Summary   string `json:"summary"`
	FromID    string `json:"fromId"`
	Timestamp int64  `json:"timestamp"`
}

type CompactFunc func(ctx context.Context, req CompactionRequest) (*CompactionResult, error)

type CompactOptions struct {
	Headers            map[string]string
	CustomInstructions string
	ThinkingLevel      ai.ModelThinkingLevel
	Prompts            SummaryPrompts
}

type CompactionEndEvent struct {
	Type    string            `json:"type"`
	Reason  CompactionReason  `json:"reason"`
	Result  *CompactionResult `json:"result,omitempty"`
	Aborted bool              `json:"aborted"`
	// WillRetry refers to overflow recovery, not queued-message continuation.
	WillRetry    bool   `json:"willRetry"`
	ErrorMessage string `json:"errorMessage,omitempty"`
	// RestoredMessages are steering and follow-up messages, steering first, that
	// were queued for the run a manual compaction aborted. They are removed from
	// the agent and will not be sent; resend them with Prompt to deliver them.
	RestoredMessages []agent.AgentMessage `json:"restoredMessages,omitempty"`
}

type CompactionEntry struct {
	SessionEntryBase
	Summary          string `json:"summary"`
	FirstKeptEntryID string `json:"firstKeptEntryId"`
	TokensBefore     int64  `json:"tokensBefore"`
	Details          any    `json:"details,omitempty"`
	FromHook         *bool  `json:"fromHook,omitempty"`
}

type CompactionHook func(ctx context.Context, req CompactionRequest, next CompactFunc) (*CompactionResult, error)

type CompactionPreparation struct {
	FirstKeptEntryID    string
	MessagesToSummarize []agent.AgentMessage
	TurnPrefixMessages  []agent.AgentMessage
	IsSplitTurn         bool
	TokensBefore        int64
	PreviousSummary     *string
	// PreviousDetails is the previous compaction's Details as JSON, so it reads
	// the same before and after a reload. Decode it with DecodeCompactionDetails.
	PreviousDetails json.RawMessage
	Settings        CompactionSettings
}

type CompactionReason string

type CompactionRequest struct {
	Reason        CompactionReason
	Preparation   *CompactionPreparation
	BranchEntries []SessionEntry
	// Session is the session being compacted, for reading only.
	Session            ReadonlySessionManager
	CustomInstructions string
	// Prompts starts as DefaultSummaryPrompts.
	Prompts SummaryPrompts
}

type CompactionResult struct {
	Summary          string
	FirstKeptEntryID string
	TokensBefore     int64
	// Details is stored on the CompactionEntry and must marshal to JSON. The next
	// compaction receives it as CompactionPreparation.PreviousDetails.
	Details any
}

type CompactionSettings struct {
	Enabled          bool
	ReservedTokens   int64
	KeepRecentTokens int64
}

type CompactionStartEvent struct {
	Type   string           `json:"type"`
	Reason CompactionReason `json:"reason"`
}

type CompactionSummaryMessage struct {
	Role         string `json:"role"`
	Summary      string `json:"summary"`
	TokensBefore int64  `json:"tokensBefore"`
	Timestamp    int64  `json:"timestamp"`
}

type CreateAgentSessionOptions struct {
	Model              ai.Model[ai.API]
	ThinkingLevel      ai.ModelThinkingLevel
	SessionManager     *SessionManager
	ModelRegistry      *ModelRegistry
	AuthStore          AuthStore
	CompactionSettings *CompactionSettings
	// CompactionHook wraps manual and automatic compaction. See CompactionHook.
	CompactionHook CompactionHook

	SystemPrompt      *string
	Tools             []agent.AgentTool[any, any]
	ToolExecutionMode *agent.ToolExecutionMode

	/* Optional func to call before each tool call is executed. */
	BeforeToolCall func(
		ctx context.Context,
		call agent.BeforeToolCallContext,
	) (*agent.BeforeToolCallResult, error)

	/* Optional func to call after each tool call is executed. */
	AfterToolCall func(
		ctx context.Context,
		call agent.AfterToolCallContext[any],
	) (*agent.AfterToolCallResult, error)

	/* Optional func to call before each payload is sent to the provider. */
	OnPayload func(
		payload any,
		model ai.Model[ai.API],
	) (any, error)

	/* Optional func to call after each response is received from the provider. */
	OnResponse func(
		response ai.ProviderResponse,
		model ai.Model[ai.API],
	) error
}

type CreateAgentSessionResult struct {
	Session              *AgentSession
	ModelFallbackMessage *string
}

type CustomEntry struct {
	SessionEntryBase
	CustomType string `json:"customType"`
	Data       any    `json:"data,omitempty"`
}

type CustomMessage struct {
	Role       string           `json:"role"`
	CustomType string           `json:"customType"`
	Content    []ai.UserContent `json:"content"`
	Display    bool             `json:"display"`
	Details    any              `json:"details,omitempty"`
	Timestamp  int64            `json:"timestamp"`
}

type CustomMessageEntry struct {
	SessionEntryBase
	CustomType string           `json:"customType"`
	Content    []ai.UserContent `json:"content"`
	Details    any              `json:"details,omitempty"`
	Display    bool             `json:"display"`
}

type CutPointResult struct {
	FirstKeptEntryIndex int
	TurnStartIndex      int
	IsSplitTurn         bool
}

type EnvAuthStore struct{}

type GenerateSummaryOptions struct {
	Headers            map[string]string
	CustomInstructions string
	PreviousSummary    string
	ThinkingLevel      ai.ModelThinkingLevel
	Prompts            SummaryPrompts
}

type LabelEntry struct {
	SessionEntryBase
	TargetID string  `json:"targetId"`
	Label    *string `json:"label,omitempty"`
}

type LoadedSession struct {
	Header SessionHeader
	// Entries holds every branch, in append order.
	Entries []SessionEntry
	// CurrentEntryID is the current position: the entry the next append
	// attaches to. Nil with entries present means "before the first entry",
	// so the next append starts a new root.
	CurrentEntryID *string
}

type ManualCompactionOptions struct {
	CustomInstructions string
}

type MessageDecoder func(data []byte) (agent.AgentMessage, error)

type ModelChangeEntry struct {
	SessionEntryBase
	Provider string `json:"provider"`
	ModelID  string `json:"modelId"`
}

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

type PromptOptions struct {
	Images []ai.ImageContent
	/** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Required if streaming. */
	StreamingBehavior StreamingBehavior
}

type ReadonlySessionManager interface {
	GetSessionID() string
	GetHeader() *SessionHeader
	GetSessionName() *string
	GetLeafID() *string
	GetLeafEntry() SessionEntry
	GetEntry(id string) SessionEntry
	GetChildren(parentID string) []SessionEntry
	GetLabel(id string) *string
	GetBranch(from ...string) []SessionEntry
	GetBranches() []SessionBranch
	GetEntries() []SessionEntry
	GetTree() []*SessionTreeNode
	BuildSessionContext() SessionContext
}

type RequestAuth struct {
	APIKey  *string
	Headers map[string]string
}

type SessionBranch struct {
	// LeafID is the branch's last entry. SetLeaf(LeafID) switches to it.
	LeafID string
	// BranchPointID is the nearest entry above the leaf with more than one
	// child, where this branch splits from its siblings. It is nil when the
	// branch splits from another root, or the session has a single branch.
	BranchPointID *string
	// FirstEntryID is the first entry after BranchPointID. The branch's own
	// entries run from it to LeafID.
	FirstEntryID string
	// Label is the label nearest the leaf on the branch's own entries.
	Label *string
	// FirstMessage is the text of the first user message on the branch's own
	// entries. If they have none, as when a reply was regenerated, it is the
	// last user message before them.
	FirstMessage string
	// Active reports whether the current position is on the branch's own
	// entries. At a branch point, before the next append, no branch is active.
	Active bool
}

type SessionContext struct {
	Messages      []agent.AgentMessage
	ThinkingLevel string
	Model         *SessionModel
}

type SessionEntry interface{ GetBase() *SessionEntryBase }

type SessionEntryBase struct {
	Type      string  `json:"type"`
	ID        string  `json:"id"`
	ParentID  *string `json:"parentId"`
	Timestamp string  `json:"timestamp"`
}

type SessionHeader struct {
	Type          string         `json:"type"`
	Version       int            `json:"version,omitempty"`
	ID            string         `json:"id"`
	Timestamp     string         `json:"timestamp"`
	ParentSession *string        `json:"parentSession,omitempty"`
	Name          *string        `json:"name,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

type SessionInfo struct {
	ID string
	// Name is the latest session_info entry's name, or nil if that entry
	// cleared it. Without any session_info entry a store may supply its own
	// name, such as one generated from the first message.
	Name            *string
	ParentSessionID *string
	// Created is the header timestamp.
	Created time.Time
	// Modified is when the store last appended an entry, or Created if it
	// has none.
	Modified time.Time
	// MessageCount counts message entries across every branch.
	MessageCount int
	// FirstMessage is the text of the first user message with any text, in
	// append order, or "" if there is none.
	FirstMessage string
	Metadata     map[string]any
}

type SessionInfoEntry struct {
	SessionEntryBase
	Name *string `json:"name,omitempty"`
}

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

type SessionMessageEntry struct {
	SessionEntryBase
	Message agent.AgentMessage `json:"message"`
}

type SessionModel struct{ Provider, ModelID string }

type SessionQuery struct {
	// Metadata matches sessions whose header metadata has every key with an
	// equal value. Nil or empty matches every session.
	Metadata map[string]any
	// Limit caps the number of sessions returned. Zero means no limit.
	Limit int
}

type SessionStore interface {
	CreateSession(ctx context.Context, header SessionHeader, entries []SessionEntry) error
	AppendEntry(ctx context.Context, sessionID string, entry SessionEntry) error
	SetCurrentEntry(ctx context.Context, sessionID string, expected, entryID *string) error
	LoadSession(ctx context.Context, sessionID string) (LoadedSession, error)
	ListSessions(ctx context.Context, query SessionQuery) ([]SessionInfo, error)
}

type SessionTreeNode struct {
	Entry          SessionEntry       `json:"entry"`
	Children       []*SessionTreeNode `json:"children"`
	Label          *string            `json:"label,omitempty"`
	LabelTimestamp *string            `json:"labelTimestamp,omitempty"`
}

type StreamingBehavior string

type SummaryPrompts struct {
	System string
	// Initial asks for a new summary; Update merges into <previous-summary>.
	Initial    string
	Update     string
	TurnPrefix string
}

type ThinkingLevelChangeEntry struct {
	SessionEntryBase
	ThinkingLevel string `json:"thinkingLevel"`
}