agentcore

type ActivityDescriber interface {
	ActivityDescription(args json.RawMessage) string
}

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

type AgentContext struct {
	SystemPrompt string        // single-string system prompt (legacy)
	SystemBlocks []SystemBlock // multi-block system prompt with cache control (takes precedence)
	Messages     []AgentMessage
	Tools        []Tool
}

type AgentMessage interface {
	GetRole() Role
	GetTimestamp() time.Time
	TextContent() string
	ThinkingContent() string
	HasToolCalls() bool
}

type AgentOption func(*Agent)

type AgentState struct {
	SystemPrompt     string
	Messages         []AgentMessage
	Tools            []Tool
	IsRunning        bool
	StreamMessage    AgentMessage        // partial message being streamed, nil when idle
	PendingToolCalls map[string]struct{} // tool call IDs currently executing
	TotalUsage       Usage               // cumulative token usage across all turns
	Error            string
}

type BackgroundTaskEntry struct {
	ID          string
	Type        TaskType
	Description string
	Status      TaskStatus
	StartedAt   time.Time
	EndedAt     time.Time
	OutputFile  string // path to output file on disk
	Error       string
	ExitCode    int // shell: process exit code
	ToolCount   int // number of tool calls executed

	// Shell-specific
	PID     int
	Command string

	// SubAgent-specific
	Agent     string
	Prompt    string // original task prompt
	TokensIn  int
	TokensOut int
	// contains filtered or unexported fields
}

type CallConfig struct {
	ThinkingLevel  ThinkingLevel
	ThinkingBudget int    // max thinking tokens, 0 = use provider default
	APIKey         string // per-call API key override, empty = use model default
	SessionID      string // provider session caching identifier
	MaxTokens      int    // per-call max tokens override, 0 = use model default
	ToolChoice     any    // "auto" / "required" / "none" / {"type":"tool","name":"xxx"}, nil = provider default
}

type CallOption func(*CallConfig)

type ChatModel interface {
	Generate(ctx context.Context, messages []Message, tools []ToolSpec, opts ...CallOption) (*LLMResponse, error)
	GenerateStream(ctx context.Context, messages []Message, tools []ToolSpec, opts ...CallOption) (<-chan StreamEvent, error)
	SupportsTools() bool
}

type CompactReason string

type ConcurrencySafer interface {
	ConcurrencySafe(args json.RawMessage) bool
}

type ContentBlock struct {
	Type     ContentType `json:"type"`
	Text     string      `json:"text,omitempty"`
	Thinking string      `json:"thinking,omitempty"`
	ToolCall *ToolCall   `json:"tool_call,omitempty"`
	Image    *ImageData  `json:"image,omitempty"`
	ToolName string      `json:"tool_name,omitempty"` // tool_reference: referenced tool name
}

type ContentTool interface {
	ExecuteContent(ctx context.Context, args json.RawMessage) ([]ContentBlock, error)
}

type ContentType string

type ContextCommitResult struct {
	Messages       []AgentMessage
	Usage          *ContextUsage
	Changed        bool
	Strategy       string
	CompactedCount int
	KeptCount      int
	SplitTurn      bool
}

type ContextEstimateFn func(msgs []AgentMessage) (tokens, usageTokens, trailingTokens int)

type ContextEstimator interface {
	EstimateContext([]AgentMessage) (tokens, usageTokens, trailingTokens int)
}

type ContextLLMConverter interface {
	ConvertToLLM([]AgentMessage) []Message
}

type ContextManager interface {
	// Project builds the prompt view for a single model call without mutating
	// the caller's runtime baseline.
	Project(ctx context.Context, msgs []AgentMessage) (ContextProjection, error)

	// Compact performs an explicit committed rewrite of msgs. The caller is
	// responsible for replacing its runtime baseline with the returned Messages
	// when Changed is true.
	Compact(ctx context.Context, msgs []AgentMessage, reason CompactReason) (ContextCommitResult, error)

	// RecoverOverflow produces a retryable view after a provider reports
	// context overflow. When ShouldCommit is true, CommitMessages should replace
	// the runtime baseline before continuing.
	RecoverOverflow(ctx context.Context, msgs []AgentMessage, cause error) (ContextRecoveryResult, error)

	// Sync tells the manager what the current runtime baseline is after restore,
	// clear, import, or any other external replacement of messages.
	Sync(msgs []AgentMessage)

	// Usage returns the latest effective context usage remembered by the
	// manager. It may reflect a projected or recovered view rather than the raw
	// runtime baseline.
	Usage() *ContextUsage

	// Snapshot returns the latest active view snapshot remembered by the
	// manager. It is intended for observability and may be nil before the
	// manager has seen any messages.
	Snapshot() *ContextSnapshot
}

type ContextProjection struct {
	Messages       []AgentMessage
	Usage          *ContextUsage
	CommitMessages []AgentMessage
	ShouldCommit   bool
}

type ContextRecoveryResult struct {
	View           []AgentMessage
	CommitMessages []AgentMessage
	Usage          *ContextUsage
	Changed        bool
	ShouldCommit   bool
	Strategy       string
	CompactedCount int
	KeptCount      int
	SplitTurn      bool
}

type ContextSnapshot struct {
	BaselineUsage      *ContextUsage
	Usage              *ContextUsage
	Scope              string
	TranscriptMessages int
	ActiveMessages     int
	SummaryMessages    int
	ToolMessages       int
	ClearedToolResults int
	TrimmedTextBlocks  int
	LastStrategy       string
	LastChanged        bool
	LastCompactedCount int
	LastKeptCount      int
	LastSplitTurn      bool
}

type ContextUsage struct {
	Tokens         int     `json:"tokens"`          // estimated total tokens in context
	ContextWindow  int     `json:"context_window"`  // model's context window size
	Percent        float64 `json:"percent"`         // tokens / contextWindow * 100
	UsageTokens    int     `json:"usage_tokens"`    // from last LLM-reported Usage
	TrailingTokens int     `json:"trailing_tokens"` // chars/4 estimate for trailing messages
}

type ContextWindower interface {
	ContextWindow() int
}

type Cost struct {
	Input      float64 `json:"input"`
	Output     float64 `json:"output"`
	CacheRead  float64 `json:"cache_read"`
	CacheWrite float64 `json:"cache_write"`
	Total      float64 `json:"total"`
}

type DeferActivator interface {
	DeferFilter
	Activate(names ...string)
}

type DeferFilter interface {
	// IsDeferred reports whether the tool is deferred and not yet activated.
	// Unactivated deferred tools are excluded from the API request entirely.
	IsDeferred(toolName string) bool
	// WasDeferred reports whether the tool was originally in the deferred set
	// (regardless of activation). Activated deferred tools are sent with
	// defer_loading: true.
	WasDeferred(toolName string) bool
}

type DeltaKind string

type EndReason string

type Event struct {
	Type               EventType
	Message            AgentMessage    // for message_start/update/end, turn_end
	Delta              string          // text delta for message_update
	DeltaKind          DeltaKind       // for message_update: what kind of delta
	ToolID             string          // for tool_exec_*
	Tool               string          // tool name for tool_exec_*
	ToolLabel          string          // human-readable tool label (from ToolLabeler)
	Args               json.RawMessage // tool args for tool_exec_start/tool_exec_update
	Result             json.RawMessage // tool result for tool_exec_end and preview updates
	Progress           *ProgressPayload
	UpdateKind         ToolExecUpdateKind
	IsError            bool // tool error flag for tool_exec_end
	Preview            json.RawMessage
	PermissionRequest  *permission.Request
	PermissionDecision *permission.Decision
	ToolResults        []ToolResult   // for turn_end: all tool results from this turn
	Err                error          // for error events
	NewMessages        []AgentMessage // for agent_end: messages added during this loop
	RetryInfo          *RetryInfo     // for retry events
	Summary            *RunSummary    // for agent_end: factual run summary
}

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

type EventType string

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

type ImageData struct {
	Data     string `json:"data,omitempty"`
	URL      string `json:"url,omitempty"`
	MimeType string `json:"mime_type,omitempty"`
}

type InjectDisposition string

type InjectResult struct {
	Disposition InjectDisposition
}

type InterruptBehavior string

type InterruptBehaviorer interface {
	InterruptBehavior(args json.RawMessage) InterruptBehavior
}

type LLMRequest struct {
	Messages []Message
	Tools    []ToolSpec
}

type LLMResponse struct {
	Message Message
}

type LoopConfig struct {
	Model                 ChatModel
	StreamFn              StreamFn      // nil = use Model directly
	MaxTurns              int           // safety limit, default 10
	MaxRetries            int           // LLM call retry limit for retryable errors, default 3
	MaxToolErrors         int           // consecutive tool failure threshold per tool, 0 = unlimited
	StrictMessageSequence bool          // fail fast instead of repairing malformed tool call / result history
	ThinkingLevel         ThinkingLevel // reasoning depth

	// Two-stage pipeline: TransformContext -> ConvertToLLM
	// ContextManager takes precedence when configured.
	ContextManager   ContextManager
	TransformContext func(ctx context.Context, msgs []AgentMessage) ([]AgentMessage, error)
	ConvertToLLM     func(msgs []AgentMessage) []Message

	// CommitContext replaces the runtime message baseline after an explicit
	// committed compaction, a committed projection rewrite, or committed
	// overflow recovery.
	CommitContext func(msgs []AgentMessage, usage *ContextUsage) error

	// PermissionEngine is called after validation/preview and before execution.
	// Returning nil means no extra approval step was required.
	PermissionEngine permission.DecisionEngine

	// GetApiKey resolves the API key before each LLM call.
	// The provider parameter identifies which provider is being called (e.g. "openai", "anthropic").
	// Enables per-provider key resolution, key rotation, OAuth tokens, and multi-tenant scenarios.
	// When nil or returns empty string, the model's default key is used.
	GetApiKey func(provider string) (string, error)

	// ThinkingBudgets maps each ThinkingLevel to a max thinking token count.
	// When set, the resolved budget is passed to the model alongside the level.
	ThinkingBudgets map[ThinkingLevel]int

	// SessionID enables provider-level session caching (e.g. Anthropic prompt cache).
	SessionID string

	// Steering: called after each tool execution to check for user interruptions.
	GetSteeringMessages func() []AgentMessage

	// FollowUp: called when the agent would otherwise stop.
	GetFollowUpMessages func() []AgentMessage

	// MaxRetryDelay caps the wait time between retries (including server-requested Retry-After).
	// Default: 60s. Set to prevent excessively long waits from overloaded providers.
	MaxRetryDelay time.Duration

	// Middlewares are applied around each tool execution (outermost first).
	// Use for logging, timing, argument/result modification, etc.
	Middlewares []ToolMiddleware

	// MaxToolConcurrency limits parallel tool execution.
	// 0 or 1 = sequential (default, backward compatible).
	// >1 = up to N tools execute concurrently within a single turn.
	MaxToolConcurrency int

	// ShouldEmitAbortMarker reports whether an abort marker message should be
	// emitted when the context is cancelled. When nil or returns false, the
	// cancellation is silent (legacy behavior). Set by Agent.Abort().
	ShouldEmitAbortMarker func() bool

	// ToolChoice sets the default tool_choice for every LLM call in this loop.
	// "auto" (default), "required" (must call a tool), "none" (no tools).
	// nil means use provider default.
	ToolChoice any

	// StopAfterTool, if non-nil, is called after each successful (non-error)
	// tool execution. If it returns true, the loop exits immediately with
	// EndReasonStop — even when ToolChoice is "required". Use this to let a
	// terminal tool (e.g. commit_chapter) end the loop without wasting turns.
	StopAfterTool func(toolName string) bool

	// OnMessage, if non-nil, is called after each message is appended to
	// context (assistant, tool result, steering). Use for session logging.
	OnMessage func(msg AgentMessage)

	// ReminderGens are invoked once per turn, just before the LLM request
	// is built. Their output is injected as one-turn system messages between
	// the static system prompt and the conversation history. Reminders are
	// NOT persisted to the agent message history.
	ReminderGens []ReminderGenerator

	// StopGuard is consulted when the LLM would end a run without tool calls.
	// Nil (default) means every stop is allowed.
	StopGuard StopGuard

	// OnMaxTurns selects the behavior when MaxTurns is exhausted.
	// Default (MaxTurnsTerminate) emits an error and ends the run.
	// MaxTurnsSoftRestart resets the turn counter and continues the loop.
	OnMaxTurns MaxTurnsAction
}

type MaxTurnsAction int

type Message struct {
	Role       Role           `json:"role"`
	Content    []ContentBlock `json:"content"`
	StopReason StopReason     `json:"stop_reason,omitempty"`
	Usage      *Usage         `json:"usage,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	Timestamp  time.Time      `json:"timestamp"`
}

type MessageSequenceIssue struct {
	Kind           MessageSequenceIssueKind
	MessageIndex   int
	AssistantIndex int
	ToolCallID     string
	ToolName       string
}

type MessageSequenceIssueKind string

type PermissionChecker interface {
	CheckPermission(ctx context.Context, req permission.Request) (*permission.Decision, error)
}

type PermissionMetadataProvider interface {
	PermissionMetadata() permission.Metadata
}

type Previewer interface {
	Preview(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

type ProgressPayload struct {
	Kind       ProgressPayloadKind `json:"kind"`
	Agent      string              `json:"agent,omitempty"`
	Tool       string              `json:"tool,omitempty"`
	Summary    string              `json:"summary,omitempty"`
	Delta      string              `json:"delta,omitempty"`
	Thinking   string              `json:"thinking,omitempty"`
	Message    string              `json:"message,omitempty"`
	Turn       int                 `json:"turn,omitempty"`
	Attempt    int                 `json:"attempt,omitempty"`
	MaxRetries int                 `json:"max_retries,omitempty"`
	IsError    bool                `json:"is_error,omitempty"`
	Args       json.RawMessage     `json:"args,omitempty"`
	Meta       json.RawMessage     `json:"meta,omitempty"`
	// DeltaKind distinguishes what kind of content Delta carries when Kind is
	// ProgressToolDelta. Consumers can use this to filter/render text vs
	// tool-call argument JSON differently.
	DeltaKind DeltaKind `json:"delta_kind,omitempty"`
}

type ProgressPayloadKind string

type ProviderNamer interface {
	ProviderName() string
}

type ProxyEvent struct {
	Type       ProxyEventType `json:"type"`
	Delta      string         `json:"delta,omitempty"`
	ToolCallID string         `json:"tool_call_id,omitempty"`
	ToolName   string         `json:"tool_name,omitempty"`
	StopReason StopReason     `json:"stop_reason,omitempty"`
	Usage      *Usage         `json:"usage,omitempty"`
	Err        error          `json:"-"`
}

type ProxyEventType string

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

type ProxyStreamFn func(ctx context.Context, req *LLMRequest) (<-chan ProxyEvent, error)

type QueueMode string

type ReadOnlyer interface {
	ReadOnly(args json.RawMessage) bool
}

type Reminder struct {
	// Source is a logical identifier for the generator emitting this reminder.
	// When multiple reminders from the same turn share a Source, the last one
	// wins; earlier duplicates are dropped.
	Source string
	// Content is the reminder body. It will be wrapped in
	// `<system-reminder>...</system-reminder>` before injection.
	Content string
}

type ReminderGenerator func(ctx context.Context, turn TurnInfo) []Reminder

type RetryInfo struct {
	Attempt    int
	MaxRetries int
	Delay      time.Duration
	Err        error
}

type Role string

type RunSummary struct {
	TurnCount  int
	ToolCalls  int
	ToolErrors int
	EndReason  EndReason
}

type StopDecision struct {
	// Allow=true lets the stop proceed; Allow=false keeps the loop alive.
	Allow bool
	// InjectMessage is delivered as a user message on the next turn when
	// Allow=false && !Escalate. Empty InjectMessage with Allow=false is
	// treated as Allow=true (safe default — never stall silently).
	InjectMessage string
	// Escalate=true ends the run immediately with an error.
	Escalate bool
}

type StopGuard func(ctx context.Context, stop StopInfo) StopDecision

type StopInfo struct {
	// TurnIndex is the index of the turn that just produced the stopping message.
	TurnIndex int
	// Message is the assistant message whose StopReason triggered this check.
	Message Message
}

type StopReason string

type StreamEvent struct {
	Type         StreamEventType
	ContentIndex int     // which content block is being updated
	Delta        string  // text/thinking/toolcall argument delta
	Message      Message // partial (during streaming) or final (done)
	// CompletedToolCall is populated on StreamEventToolCallEnd with the fully
	// reconstructed tool call. It lets the loop start execution immediately
	// without re-parsing the partial assistant message.
	CompletedToolCall *ToolCall
	StopReason        StopReason // finish reason (for done events)
	Err               error      // for error events
}

type StreamEventType string

type StreamFn func(ctx context.Context, req *LLMRequest) (*LLMResponse, error)

type SubAgentConfig struct {
	Name        string
	Description string
	// Model is resolved when each sub-agent run starts. Wrappers that swap
	// the underlying model at runtime are supported and take effect on the
	// next sub-agent run.
	Model        ChatModel
	SystemPrompt string
	Tools        []Tool
	StreamFn     StreamFn
	MaxTurns     int

	// ToolChoice sets the default tool_choice for every LLM call in this
	// sub-agent's loop. nil uses the provider default ("auto").
	ToolChoice any

	// StopAfterTools lists tool names that trigger early loop exit after
	// successful execution. Useful with ToolChoice "required" to let a
	// terminal tool (e.g. "commit_chapter") end the loop cleanly.
	StopAfterTools []string

	// OnMessage, if non-nil, is called after each message is appended to
	// context. The agentName and task are provided for session routing.
	OnMessage func(agentName, task string, msg AgentMessage)

	// Optional context lifecycle hooks for long-running sub-agents.
	ContextManager        ContextManager
	ContextManagerFactory func(model ChatModel) ContextManager
	TransformContext      func(ctx context.Context, msgs []AgentMessage) ([]AgentMessage, error)
	ConvertToLLM          func(msgs []AgentMessage) []Message

	// StopGuardFactory, if non-nil, creates a fresh StopGuard for each run.
	// The factory receives the agent name and task, enabling run-scoped state
	// (e.g. baseline progress captured at dispatch time).
	StopGuardFactory func(agentName, task string) StopGuard
}

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

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

type SystemBlock struct {
	Text         string `json:"text"`
	CacheControl string `json:"cache_control,omitempty"` // e.g. "ephemeral"
}

type TaskNotification struct {
	TaskID      string     `json:"task_id"`
	Type        TaskType   `json:"type"`
	Status      TaskStatus `json:"status"`
	Description string     `json:"description,omitempty"`
	OutputFile  string     `json:"output_file,omitempty"`
	Error       string     `json:"error,omitempty"`
	ExitCode    *int       `json:"exit_code,omitempty"`
	Command     string     `json:"command,omitempty"`
	Agent       string     `json:"agent,omitempty"`
}

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

type TaskStatus string

type TaskType string

type ThinkingLevel string

type Tool interface {
	Name() string
	Description() string
	Schema() map[string]any
	Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

type ToolCall struct {
	ID   string          `json:"id"`
	Name string          `json:"name"`
	Args json.RawMessage `json:"args"`
}

type ToolExecUpdateKind string

type ToolExecuteFunc func(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

type ToolLabeler interface {
	Label() string
}

type ToolMiddleware func(ctx context.Context, call ToolCall, next ToolExecuteFunc) (json.RawMessage, error)

type ToolProgressFunc func(progress ProgressPayload)

type ToolResult struct {
	ToolCallID    string          `json:"tool_call_id"`
	ToolName      string          `json:"-"` // internal: for toolErrors tracking
	Content       json.RawMessage `json:"content,omitempty"`
	ContentBlocks []ContentBlock  `json:"-"` // rich content (images); not serialized
	IsError       bool            `json:"is_error,omitempty"`
	Details       any             `json:"details,omitempty"` // optional metadata for UI display/logging
}

type ToolSpec struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	Parameters   any    `json:"parameters"`
	DeferLoading bool   `json:"defer_loading,omitempty"`
}

type TurnInfo struct {
	// TurnIndex is 0 for the first LLM call in this run, 1 for the second, etc.
	TurnIndex int
}

type Usage struct {
	Input       int   `json:"input"`
	Output      int   `json:"output"`
	CacheRead   int   `json:"cache_read"`
	CacheWrite  int   `json:"cache_write"`
	TotalTokens int   `json:"total_tokens"`
	Cost        *Cost `json:"cost,omitempty"`
}