agentflow

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

type BudgetWarningEvent struct {
	ConsumedTokens int     // Total tokens consumed so far.
	MaxTokens      int     // The configured budget limit.
	Percentage     float64 // Consumption as a fraction (0.0–1.0).
}

type CompactionEvent struct {
	BeforeCount int // Message count before compaction.
	AfterCount  int // Message count after compaction.
	TurnCount   int
}

type Compactor interface {
	// ShouldCompact reports whether the current message history needs compaction.
	// Called at the beginning of each agentic loop iteration before the model call.
	ShouldCompact(messages []Message, usage *Usage) bool

	// Compact reduces the message history to fit within context limits.
	// Returns the compacted messages that replace the original history.
	// The implementation may use summarization, truncation, or any other strategy.
	Compact(ctx context.Context, messages []Message) ([]Message, error)
}

type Config struct {
	// MaxTurns limits the number of agentic loop iterations. Each iteration
	// consists of a model call and optional tool execution. Zero means unlimited.
	MaxTurns int

	// MaxConcurrency limits the number of tools executing in parallel within
	// a single batch. Defaults to DefaultMaxConcurrency.
	MaxConcurrency int

	// SystemPrompt is prepended to the conversation as a system message.
	SystemPrompt string

	// Temperature controls the randomness of the model's output.
	// nil uses the provider's default.
	Temperature *float64

	// MaxTokens limits the maximum tokens in the model's response.
	// Zero uses the provider's default.
	MaxTokens int

	// RetryPolicy configures automatic retries for transient provider errors.
	// nil means no retries.
	RetryPolicy *RetryPolicy

	// EventBufferSize is the capacity of the event channel returned by Agent.Run.
	// Defaults to DefaultEventBufferSize.
	EventBufferSize int

	// OnEvent is an optional synchronous callback invoked for every event
	// before it is sent to the channel. Use for lightweight processing that
	// must see every event. Keep execution fast to avoid blocking the loop.
	OnEvent func(Event)

	// TokenBudget limits total token consumption across all turns.
	// nil means no budget limit.
	TokenBudget *TokenBudget

	// ResultLimiter controls how oversized tool results are handled.
	// Default: TruncateLimiter.
	ResultLimiter ResultLimiter

	// MaxResultChars is the maximum character count for a single tool result.
	// Results exceeding this are passed through the ResultLimiter.
	// Default: DefaultMaxResultChars (50000).
	MaxResultChars int

	// ExecutionMode controls which tools are visible to the model.
	// ModeLocal (default) allows all tools. ModeRemote restricts to remote-safe only.
	ExecutionMode ExecutionMode

	// DisableInputValidation skips JSON Schema validation of tool inputs.
	// Default: false (validation enabled). Set to true if tool schemas are
	// informational only and should not block execution on mismatch.
	DisableInputValidation bool

	// RateLimiter controls the rate of provider API calls. When set, the agent
	// waits for permission before each CreateStream call. nil means no rate limiting.
	RateLimiter RateLimiter

	// ToolRetries is the number of times to retry a failed tool execution before
	// returning the error to the model. Zero means no retries (default). Only
	// retries when the tool returns IsError: true.
	ToolRetries int

	// ToolTimeout sets a maximum duration for individual tool executions.
	// If a tool does not complete within this duration, its context is cancelled
	// and an error result is returned. Zero means no timeout (default).
	ToolTimeout time.Duration

	// ErrorStrategy controls how tool execution errors are handled. When set,
	// it is called after a tool returns IsError: true, allowing error transformation
	// or loop abortion. nil uses default behavior (send error to model as-is).
	ErrorStrategy ErrorStrategy

	// Logger enables structured logging for agent lifecycle events: model calls,
	// retries, compaction, budget warnings, and validation errors. nil disables
	// logging (zero overhead). Use log/slog for structured output.
	Logger *slog.Logger

	// ThinkingPrompt enables agentic thinking for non-native thinking models.
	// When set, the first turn's text output is emitted as EventThinkingDelta
	// instead of EventTextDelta. After the thinking turn completes, AnswerPrompt
	// is injected as a user message to trigger the final answer turn.
	// If the provider natively supports thinking (emits StreamEventThinkingDelta),
	// this feature is automatically disabled for that request.
	// Empty string means disabled (default).
	ThinkingPrompt string

	// AnswerPrompt is injected after the thinking turn to trigger the final answer.
	// Only used when ThinkingPrompt is set.
	AnswerPrompt string

	// ProviderExtras carries provider-specific parameters merged into every
	// request body. Examples: OpenRouter "plugins" for file parsing, Anthropic
	// cache control. Each provider picks the keys it understands.
	ProviderExtras map[string]any
}

type ContentBlock struct {
	Type ContentBlockType `json:"type"`

	// Text is set when Type == ContentText.
	Text string `json:"text,omitempty"`

	// ToolCall is set when Type == ContentToolCall.
	ToolCall *ToolCall `json:"tool_call,omitempty"`

	// ToolResult is set when Type == ContentToolResult.
	ToolResult *ToolResultBlock `json:"tool_result,omitempty"`

	// Image is set when Type == ContentImage.
	Image *ImageContent `json:"image,omitempty"`

	// Document is set when Type == ContentDocument.
	Document *DocumentContent `json:"document,omitempty"`
}

type ContentBlockType int

type ContentDelta struct {
	Text string
}

type DocumentContent struct {
	// Filename is the original filename (e.g., "report.pdf").
	Filename string `json:"filename"`

	// MediaType is the MIME type (e.g., "application/pdf", "text/plain", "text/csv").
	MediaType string `json:"media_type"`

	// Data is the base64-encoded file content. Set this for inline documents.
	Data string `json:"data,omitempty"`

	// URL is a publicly accessible document URL. Set this for URL-referenced documents.
	URL string `json:"url,omitempty"`
}

type ErrorAction int

type ErrorEvent struct {
	Err       error
	Retrying  bool
	TurnCount int
}

type ErrorStrategy interface {
	// OnToolError is called when a tool returns IsError: true. It receives the
	// tool call and the error result, and returns a (possibly modified) result
	// and an action.
	OnToolError(call *ToolCall, result *ToolResult) (*ToolResult, ErrorAction)
}

type ErrorStrategyFunc func(call *ToolCall, result *ToolResult) (*ToolResult, ErrorAction)

type Event struct {
	Type EventType

	TextDelta        *TextDeltaEvent        // Type == EventTextDelta
	ThinkDelta       *TextDeltaEvent        // Type == EventThinkingDelta
	ToolStart        *ToolStartEvent        // Type == EventToolStart
	ToolProgress     *ProgressEvent         // Type == EventToolProgress
	ToolEnd          *ToolEndEvent          // Type == EventToolEnd
	TurnStart        *TurnStartEvent        // Type == EventTurnStart
	TurnEnd          *TurnEndEvent          // Type == EventTurnEnd
	Message          *Message               // Type == EventMessage
	Error            *ErrorEvent            // Type == EventError
	Usage            *UsageEvent            // Type == EventUsage
	SubAgentStart    *SubAgentStartEvent    // Type == EventSubAgentStart
	SubAgentEnd      *SubAgentEndEvent      // Type == EventSubAgentEnd
	BudgetWarning    *BudgetWarningEvent    // Type == EventBudgetWarning
	Compaction       *CompactionEvent       // Type == EventCompaction
	Retry            *RetryEvent            // Type == EventRetry
	PermissionDenied *PermissionDeniedEvent // Type == EventPermissionDenied
	HookBlocked      *HookBlockedEvent      // Type == EventHookBlocked

	// SubAgentIndex identifies which child agent emitted this event.
	// Zero for the parent agent's own events. Set by SpawnChildren.
	SubAgentIndex int
}

type EventType int

type ExecutionMode int

type HeadTailLimiter struct {
	// HeadRatio is the fraction of maxChars allocated to the head (0.0–1.0).
	// Default: 0.7 (70% head, 30% tail).
	HeadRatio float64
}

type HealthChecker interface {
	// HealthCheck tests whether the provider is reachable and operational.
	// Returns nil if healthy, or an error describing the failure.
	HealthCheck(ctx context.Context) error
}

type Hook interface {
	// Phase returns when this hook should fire.
	Phase() HookPhase

	// Execute runs the hook logic. Returning a non-nil HookAction modifies
	// the pipeline behavior (block execution, modify input, inject messages).
	// Return nil action to proceed without modification.
	Execute(ctx context.Context, hc *HookContext) (*HookAction, error)
}

type HookAction struct {
	// Block, if true, prevents the current operation from proceeding.
	// For PreToolUse: the tool is not executed; BlockReason is sent to the model.
	// For PreModelCall: the model call is skipped; the loop terminates.
	Block       bool
	BlockReason string

	// ModifiedInput, if non-nil, replaces the tool's input before execution.
	// Only effective for PreToolUse hooks.
	ModifiedInput json.RawMessage

	// InjectMessages appends additional messages to the conversation before
	// the next model call. Effective for PostToolUse and OnTurnEnd hooks.
	InjectMessages []Message
}

type HookBlockedEvent struct {
	Phase     HookPhase
	ToolCall  *ToolCall // Non-nil for PreToolUse blocks.
	Reason    string
	TurnCount int
}

type HookContext struct {
	// Phase indicates which lifecycle phase triggered this hook.
	Phase HookPhase

	// ToolCall is set for tool-phase hooks (PreToolUse, PostToolUse).
	ToolCall *ToolCall

	// ToolResult is set for PostToolUse hooks.
	ToolResult *ToolResult

	// Messages is the current conversation history at the time the hook fires.
	Messages []Message

	// TurnCount is the current iteration number of the agentic loop.
	TurnCount int

	// Metadata is a mutable key-value bag that persists across hooks within a
	// single agent run. Hooks can use it to communicate state to each other.
	Metadata map[string]any
}

type HookFunc struct {
	HookPhase HookPhase
	Fn        func(ctx context.Context, hc *HookContext) (*HookAction, error)
}

type HookPhase int

type ImageContent struct {
	// MediaType is the MIME type (e.g., "image/png", "image/jpeg", "image/webp", "image/gif").
	MediaType string `json:"media_type"`

	// Data is the base64-encoded image data. Set this for inline images.
	Data string `json:"data,omitempty"`

	// URL is a publicly accessible image URL. Set this for URL-referenced images.
	URL string `json:"url,omitempty"`
}

type LocalityAware interface {
	Locality() ToolLocality
}

type Message struct {
	Role    Role           `json:"role"`
	Content []ContentBlock `json:"content"`
}

type MultiPhaseHook interface {
	// Phases returns all phases this hook should fire at.
	Phases() []HookPhase

	// Execute runs the hook logic for the given phase.
	Execute(ctx context.Context, hc *HookContext) (*HookAction, error)
}

type NoLimiter struct{}

type Option func(*Agent)

type OrchestrateResult struct {
	Index  int
	Task   string
	Result string
	Error  error
}

type PermissionChecker interface {
	// Check returns the permission decision for a tool invocation. The checker
	// receives both the call details and the tool definition, enabling fine-grained
	// decisions based on the specific input.
	Check(ctx context.Context, call *ToolCall, tool Tool) (PermissionResult, error)
}

type PermissionDeniedEvent struct {
	ToolCall ToolCall
}

type PermissionFunc func(ctx context.Context, call *ToolCall, tool Tool) (PermissionResult, error)

type PermissionResult int

type ProgressEvent struct {
	// ToolCallID identifies which tool invocation this progress belongs to.
	// Set automatically by the executor; tools do not need to set this.
	ToolCallID string

	// Message is a human-readable progress description.
	Message string

	// Data carries tool-specific structured progress information.
	Data any
}

type ProgressFunc func(ProgressEvent)

type Provider interface {
	// CreateStream initiates a streaming model call and returns a Stream that
	// yields events as they arrive from the API. The caller must consume the
	// stream to completion or cancel via context.
	//
	// The Request contains provider-agnostic fields (messages, tools, parameters).
	// Implementations convert these into vendor-specific API formats.
	CreateStream(ctx context.Context, req *Request) (Stream, error)

	// ModelID returns the identifier of the model this provider targets
	// (e.g., "anthropic/claude-sonnet-4-20250514", "openai/gpt-4o").
	ModelID() string
}

type ProviderError struct {
	StatusCode      int
	Message         string
	Retryable       bool
	Err             error
	ResponseHeaders http.Header
}

type RateLimiter interface {
	// Wait blocks until the caller is allowed to proceed. Returns an error
	// if the context is cancelled or the limiter is otherwise unable to grant
	// permission.
	Wait(ctx context.Context) error
}

type Request struct {
	// Messages is the conversation history including user messages, assistant
	// responses, and tool results from previous iterations.
	Messages []Message

	// SystemPrompt is an optional system-level instruction prepended to the conversation.
	SystemPrompt string

	// Tools is the list of tool definitions available to the model for this request.
	Tools []ToolDefinition

	// MaxTokens limits the maximum number of tokens in the model's response.
	MaxTokens int

	// Temperature controls the randomness of the model's output.
	// nil means the provider's default is used.
	Temperature *float64

	// StopSequences are optional strings that cause the model to stop generating
	// when encountered. Support varies by provider.
	StopSequences []string

	// Metadata carries key-value pairs that providers may propagate as HTTP
	// headers. Use this for trace context propagation (e.g., "traceparent",
	// "tracestate") or custom request tagging. Providers add these as headers
	// prefixed with nothing — keys map directly to header names.
	Metadata map[string]string

	// ProviderExtras carries provider-specific parameters that are merged into
	// the request body. Examples: OpenRouter "plugins" for file parsing,
	// Anthropic cache control, Gemini safety settings. Each provider picks
	// the keys it understands and ignores the rest.
	ProviderExtras map[string]any
}

type ResultLimiter interface {
	// Limit inspects a tool result and returns a potentially modified version.
	// If the result is within acceptable bounds, it is returned unchanged.
	// maxChars is the configured maximum character count.
	Limit(result *ToolResult, maxChars int) *ToolResult
}

type RetryEvent struct {
	Attempt   int           // Current retry attempt (1-based).
	Delay     time.Duration // Delay before this retry.
	Err       error         // The error that triggered the retry.
	TurnCount int
}

type RetryPolicy struct {
	// MaxRetries is the maximum number of retry attempts. Zero means no retries.
	MaxRetries int

	// BaseDelay is the initial delay before the first retry.
	// Subsequent retries use exponential backoff: BaseDelay * 2^attempt.
	BaseDelay time.Duration

	// MaxDelay caps the maximum delay between retries.
	MaxDelay time.Duration
}

type Role string

type Session struct {
	// ID uniquely identifies this session. Generated automatically if empty.
	ID string `json:"id"`

	// Messages is the full conversation history at the time of save.
	Messages []Message `json:"messages"`

	// Metadata is an arbitrary key-value bag for application-specific data
	// (user ID, task description, tags, etc.).
	Metadata map[string]any `json:"metadata,omitempty"`

	// CreatedAt is when the session was first created.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when the session was last saved.
	UpdatedAt time.Time `json:"updated_at"`

	// ModelID records which model was used, for reference when resuming.
	ModelID string `json:"model_id,omitempty"`

	// TurnCount records how many turns were completed before saving.
	TurnCount int `json:"turn_count"`
}

type SessionInfo struct {
	ID        string         `json:"id"`
	CreatedAt time.Time      `json:"created_at"`
	UpdatedAt time.Time      `json:"updated_at"`
	ModelID   string         `json:"model_id,omitempty"`
	TurnCount int            `json:"turn_count"`
	Metadata  map[string]any `json:"metadata,omitempty"`

	// Preview is the first user message text, truncated for display.
	Preview string `json:"preview,omitempty"`
}

type SessionStore interface {
	// Save persists the current conversation state. If a session with the given
	// ID already exists, it is overwritten.
	Save(ctx context.Context, session *Session) error

	// Load retrieves a previously saved session by ID. Returns ErrSessionNotFound
	// if the session does not exist.
	Load(ctx context.Context, id string) (*Session, error)

	// List returns metadata for all stored sessions, ordered by last update time
	// (most recent first).
	List(ctx context.Context) ([]SessionInfo, error)

	// Delete removes a session by ID. Returns nil if the session does not exist.
	Delete(ctx context.Context, id string) error
}

type Stream interface {
	// Next blocks until the next event is available. Returns io.EOF when the
	// stream is complete. Any other error indicates a failure in the stream.
	Next() (StreamEvent, error)

	// Close releases resources associated with the stream. Safe to call
	// multiple times. Must be called even if Next returned an error.
	Close() error

	// Usage returns token usage statistics after the stream completes.
	// Returns nil if the stream has not finished or the provider does not
	// report usage information.
	Usage() *Usage
}

type StreamEvent struct {
	Type StreamEventType

	// Delta is set when Type == StreamEventDelta.
	Delta *ContentDelta

	// ThinkingDelta is set when Type == StreamEventThinkingDelta.
	ThinkingDelta *ContentDelta

	// ToolCall is set when Type == StreamEventToolCall.
	ToolCall *ToolCall

	// Error is set when Type == StreamEventError.
	Error error

	// Usage is set when Type == StreamEventUsage.
	Usage *Usage
}

type StreamEventType int

type SubAgentConfig struct {
	// Provider overrides the parent's provider. nil inherits the parent's.
	Provider Provider

	// Tools overrides the parent's tool set. nil inherits the parent's tools.
	// Use an empty slice to spawn a child with no tools.
	Tools []Tool

	// SystemPrompt overrides the parent's system prompt for the child.
	SystemPrompt string

	// MaxTurns limits the child's loop iterations. Zero inherits the parent's.
	MaxTurns int

	// MaxTokens overrides the response token limit. Zero inherits.
	MaxTokens int

	// MaxConcurrency overrides parallel tool execution limit. Zero inherits.
	MaxConcurrency int

	// Hooks are additional hooks for the child. Parent hooks are NOT inherited
	// to keep child execution isolated.
	Hooks []Hook

	// Permission overrides the parent's permission checker. nil inherits.
	Permission PermissionChecker
}

type SubAgentEndEvent struct {
	Index  int    // Child index matching SubAgentStartEvent.
	Task   string // The original task.
	Result string // The sub-agent's final text response.
}

type SubAgentStartEvent struct {
	Index int    // Child index (0-based) within SpawnChildren.
	Task  string // The task delegated to the sub-agent.
}

type TextDeltaEvent struct {
	Text string
}

type TimeoutAware interface {
	Timeout() time.Duration
}

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

type TokenBudget struct {
	// MaxTokens is the total token limit for the entire agent run.
	// Includes both prompt and completion tokens across all turns.
	MaxTokens int

	// WarningThreshold is the fraction (0.0–1.0) at which a budget warning
	// event is emitted. For example, 0.8 means warn at 80% consumption.
	// Zero disables the warning. Values above 1.0 are clamped to 1.0.
	WarningThreshold float64
}

type Tool interface {
	// Name returns the unique identifier for this tool. Must be alphanumeric
	// with underscores, matching the pattern [a-zA-Z_][a-zA-Z0-9_]*.
	Name() string

	// Description returns a human-readable description sent to the model.
	// A clear, specific description significantly improves tool selection accuracy.
	Description() string

	// InputSchema returns the JSON Schema object describing the tool's input parameters.
	// This schema is sent to the model and used for input validation before execution.
	InputSchema() map[string]any

	// Execute runs the tool with the given validated input. The context carries
	// cancellation signals from the agent loop. Implementations should respect
	// context cancellation for long-running operations.
	//
	// The progress function, if non-nil, can be called to report incremental
	// progress updates that are forwarded to the event stream.
	Execute(ctx context.Context, input json.RawMessage, progress ProgressFunc) (*ToolResult, error)

	// IsConcurrencySafe reports whether this tool can safely execute in parallel
	// with other concurrency-safe tools given the specific input. Read-only tools
	// should return true. Tools that mutate shared state should return false.
	IsConcurrencySafe(input json.RawMessage) bool

	// IsReadOnly reports whether the tool performs only read operations for the
	// given input. Used by permission checkers to make access control decisions.
	IsReadOnly(input json.RawMessage) bool
}

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

type ToolDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"input_schema"`
}

type ToolEndEvent struct {
	ToolCall ToolCall
	Result   ToolResult
	Duration time.Duration
}

type ToolError struct {
	ToolName   string
	ToolCallID string
	Err        error
}

type ToolLocality int

type ToolResult struct {
	// Content is the textual result sent to the model. For successful operations,
	// this contains the output data. For failures, this contains the error description.
	Content string

	// IsError indicates the tool execution failed. The model receives Content as
	// an error message and can adapt its approach (retry, use a different tool, etc.).
	IsError bool

	// Metadata is not sent to the model but is included in ToolEndEvent for
	// observability. Use it for execution metrics, debug data, or audit information.
	Metadata map[string]any
}

type ToolResultBlock struct {
	ToolCallID string `json:"tool_use_id"`
	Content    string `json:"content"`
	IsError    bool   `json:"is_error,omitempty"`
}

type ToolStartEvent struct {
	ToolCall ToolCall
}

type TruncateLimiter struct{}

type TurnEndEvent struct {
	TurnNumber int
	Reason     TurnEndReason
	Messages   []Message // Final conversation history at loop termination.
}

type TurnEndReason string

type TurnStartEvent struct {
	TurnNumber int
}

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type UsageEvent struct {
	Usage     Usage
	TurnCount int
}