agent

type AfterAgentCallback func(CallbackContext) (*a2a.Message, error)

type Agent interface {
	// Name returns the unique identifier for this agent within the agent tree.
	// Agent name cannot be "user" as it's reserved for end-user input.
	Name() string

	// DisplayName returns the human-readable name of the agent.
	// Used for UI attribution.
	DisplayName() string

	// Description returns a human-readable description of the agent's capability.
	// Used by LLMs to determine whether to delegate control to this agent.
	Description() string

	// Run executes the agent and yields events.
	// The iterator pattern allows clean streaming of results.
	Run(InvocationContext) iter.Seq2[*Event, error]

	// SubAgents returns child agents that this agent can delegate to.
	SubAgents() []Agent

	// Type returns the agent type for introspection.
	// Used by the runner to determine workflow vs delegation semantics.
	Type() AgentType
}

type AgentType string

type ArtifactInfo struct {
	Name    string
	Version int64
}

type ArtifactListResponse struct {
	Artifacts []ArtifactInfo
}

type ArtifactLoadResponse struct {
	Name    string
	Version int64
	Part    a2a.Part
}

type ArtifactSaveResponse struct {
	Name    string
	Version int64
}

type Artifacts interface {
	Save(ctx context.Context, name string, part a2a.Part) (*ArtifactSaveResponse, error)
	List(ctx context.Context) (*ArtifactListResponse, error)
	Load(ctx context.Context, name string) (*ArtifactLoadResponse, error)
	LoadVersion(ctx context.Context, name string, version int) (*ArtifactLoadResponse, error)
}

type BeforeAgentCallback func(CallbackContext) (*a2a.Message, error)

type CallbackContext interface {
	ReadonlyContext

	// Artifacts returns the artifact service.
	Artifacts() Artifacts

	// State returns mutable session state.
	State() State
}

type CancellableTask interface {
	// RegisterExecution registers a child execution for cascade cancellation.
	RegisterExecution(exec *ChildExecution)

	// UnregisterExecution removes a child execution from tracking.
	UnregisterExecution(callID string)

	// CancelExecution cancels a specific child execution.
	CancelExecution(callID string) bool

	// GetID returns the task ID.
	GetID() string
}

type Checkpointable interface {
	Agent

	// CaptureCheckpointState returns the agent's current execution state.
	// Called by the checkpoint manager at strategic points (pre-LLM, post-tool, etc.)
	CaptureCheckpointState() (map[string]any, error)

	// RestoreCheckpointState restores the agent's execution state from a checkpoint.
	// Called by the recovery manager when resuming from a checkpoint.
	RestoreCheckpointState(state map[string]any) error
}

type ChildExecution struct {
	// CallID is the unique identifier for this execution.
	CallID string

	// Name is the tool or agent name.
	Name string

	// Type is either "tool" or "agent".
	Type string

	// Cancel is called to cancel this execution.
	Cancel func() bool
}

type Config struct {
	// Name must be a non-empty string, unique within the agent tree.
	Name string

	// DisplayName is the human-readable name (optional).
	DisplayName string

	// Description of the agent's capability (used for delegation decisions).
	Description string

	// SubAgents are child agents this agent can delegate tasks to.
	SubAgents []Agent

	// BeforeAgentCallbacks are called before the agent starts its run.
	// If any returns non-nil content or error, agent run is skipped.
	BeforeAgentCallbacks []BeforeAgentCallback

	// Run defines the agent's execution logic.
	Run func(InvocationContext) iter.Seq2[*Event, error]

	// AgentType allows specifying the agent type (optional).
	// If empty, defaults to TypeCustomAgent.
	AgentType AgentType

	// AfterAgentCallbacks are called after the agent completes its run.
	AfterAgentCallbacks []AfterAgentCallback
}

type Content struct {
	Parts []a2a.Part
	Role  a2a.MessageRole
}

type Event struct {
	// ID is the unique identifier for this event.
	ID string

	// Timestamp when the event was created.
	Timestamp time.Time

	// InvocationID links this event to its invocation.
	InvocationID string

	// Branch isolates conversation history for parallel agents.
	// Format: "agent_1.agent_2.agent_3" (parent chain).
	Branch string

	// Author is the display name of the agent (or "user"/"system").
	// This is used for UI rendering and attribution.
	Author string

	// AgentID is the unique identifier of the agent that produced this event.
	// Used for internal routing, logic, and state tracking.
	AgentID string

	// Message contains the A2A message content (text, files, data).
	// This maps directly to a2a.Message for seamless translation.
	Message *a2a.Message

	// Actions captures side effects (state changes, transfers, etc).
	Actions EventActions

	// LongRunningToolIDs identifies tools awaiting external completion.
	LongRunningToolIDs []string

	// Partial indicates this is a streaming chunk, not a complete event.
	Partial bool

	// TurnComplete indicates this is the final event of a turn.
	TurnComplete bool

	// Interrupted indicates this event was cut off due to cancellation or timeout.
	// When true, the response may be incomplete. This helps distinguish between:
	// - A complete response that ended naturally (Interrupted=false)
	// - A partial response that was forcibly stopped (Interrupted=true)
	Interrupted bool

	// ErrorCode is a machine-readable error identifier (e.g., "rate_limit", "timeout").
	ErrorCode string

	// ErrorMessage is a human-readable error description.
	ErrorMessage string

	// Thinking captures the model's reasoning process (for thinking-enabled models).
	// This is rendered as a collapsible ThinkingWidget in the UI.
	Thinking *ThinkingState

	// ToolCalls captures tool invocations in this event.
	// Each tool call is rendered as a ToolWidget in the UI.
	ToolCalls []ToolCallState

	// ToolResults captures tool execution results in this event.
	// These update the corresponding ToolWidget status.
	ToolResults []ToolResultState

	// CustomMetadata for application-specific data.
	CustomMetadata map[string]any

	// OnPersisted is a callback invoked after the event is persisted to the session.
	// Used by async agents (like ParallelAgent) to synchronize with the persistence layer.
	// This field is not serialized.
	OnPersisted func() `json:"-"`
}

type EventActions struct {
	// StateDelta contains key-value changes to session state.
	StateDelta map[string]any

	// ArtifactDelta tracks artifact updates (filename -> version).
	ArtifactDelta map[string]int64

	// SkipSummarization prevents LLM summarization of tool responses.
	SkipSummarization bool

	// TransferToAgent requests control transfer to another agent.
	TransferToAgent string

	// Escalate requests escalation to a higher-level agent.
	Escalate bool

	// RequireInput signals that human input is required (HITL pattern).
	// When true, the task transitions to `input_required` state.
	// This is used by long-running tools that need approval or additional info.
	RequireInput bool

	// InputPrompt is the message shown to the human when RequireInput is true.
	// Should explain what input is needed and why.
	InputPrompt string
}

type Events interface {
	All() iter.Seq[*Event]
	Len() int
	At(i int) *Event
}

type InvocationContext interface {
	// Embed CallbackContext which embeds ReadonlyContext
	// This allows InvocationContext to be used wherever ReadonlyContext
	// or CallbackContext is expected.
	CallbackContext

	// Agent returns the current agent being executed.
	Agent() Agent

	// Session returns the session for this invocation.
	Session() Session

	// Memory provides access to cross-session memory.
	Memory() Memory

	// RunConfig returns the runtime configuration for this invocation.
	RunConfig() *RunConfig

	// EndInvocation signals that the invocation should stop.
	EndInvocation()

	// Ended returns whether the invocation has been ended.
	Ended() bool
}

type InvocationContextParams struct {
	Artifacts   Artifacts
	Memory      Memory
	Session     Session
	Agent       Agent
	Branch      string
	UserContent *Content
	RunConfig   *RunConfig
}

type Memory interface {
	AddSession(ctx context.Context, session Session) error
	Search(ctx context.Context, query string) (*MemorySearchResponse, error)
}

type MemoryResult struct {
	Content  string
	Score    float64
	Metadata map[string]any
}

type MemorySearchResponse struct {
	Results []MemoryResult
}

type ReadonlyContext interface {
	context.Context

	// InvocationID returns the unique ID for this invocation.
	InvocationID() string

	// AgentName returns the current agent's name.
	AgentName() string

	// UserContent returns the user message that started this invocation.
	UserContent() *Content

	// ReadonlyState returns read-only access to session state.
	ReadonlyState() ReadonlyState

	// UserID returns the user identifier.
	UserID() string

	// AppName returns the application name.
	AppName() string

	// SessionID returns the session identifier.
	SessionID() string

	// Branch returns the agent hierarchy path.
	Branch() string
}

type ReadonlyState interface {
	Get(key string) (any, error)
	All() iter.Seq2[string, any]
}

type RunConfig struct {
	// StreamingMode controls event streaming behavior.
	StreamingMode StreamingMode

	// SaveInputBlobsAsArtifacts saves file inputs as artifacts.
	SaveInputBlobsAsArtifacts bool

	// Task provides access to the parent task for cascade cancellation.
	// This is set by the executor when a task is associated with the invocation.
	Task CancellableTask

	// SkipAppendUserMessage skips appending the user message to session.
	// Used for checkpoint recovery where the message already exists in history.
	SkipAppendUserMessage bool
}

type Session interface {
	ID() string
	AppName() string
	UserID() string
	State() State
	Events() Events
}

type State interface {
	Get(key string) (any, error)
	Set(key string, value any) error
	Delete(key string) error
	All() iter.Seq2[string, any]
}

type StreamingMode string

type TempClearable interface {
	// ClearTempKeys removes all keys with the "temp:" prefix.
	// Called automatically after each invocation completes.
	ClearTempKeys()
}

type ThinkingState struct {
	// ID uniquely identifies this thinking block within a conversation.
	ID string `json:"id"`

	// Status indicates the lifecycle state: "active" | "completed".
	Status string `json:"status"`

	// Content is the thinking text (may stream incrementally).
	Content string `json:"content"`

	// Signature is used for multi-turn verification (e.g., Anthropic).
	Signature string `json:"signature,omitempty"`

	// Type categorizes the thinking: "default" | "planning" | "reflection" | "goal".
	Type string `json:"type,omitempty"`
}

type ToolCallState struct {
	// ID uniquely identifies this tool call (matches LLM's tool_use ID).
	ID string `json:"id"`

	// Name is the tool being called.
	Name string `json:"name"`

	// Args are the arguments passed to the tool.
	Args map[string]any `json:"args"`

	// Status indicates lifecycle: "pending" | "working".
	Status string `json:"status"`
}

type ToolResultState struct {
	// ToolCallID links this result to its ToolCallState.
	ToolCallID string `json:"tool_call_id"`

	// Content is the tool's output.
	Content string `json:"content"`

	// Status indicates outcome: "success" | "failed".
	Status string `json:"status"`

	// IsError indicates if Content represents an error message.
	IsError bool `json:"is_error,omitempty"`
}