agent

type ActiveRun struct {
	Ctx    context.Context
	Cancel context.CancelFunc
	Done   chan struct{}
}

type AfterToolCallContext[TDetails any] struct {
	/** The assistant message that requested the tool call. */
	AssistantMessage ai.AssistantMessage
	/** The raw tool call block from `assistantMessage.content`. */
	ToolCall ai.ToolCall
	/** Validated tool arguments for the target tool schema. */
	Args any
	/** The executed tool result before any `afterToolCall` overrides are applied. */
	Result AgentToolResult[TDetails]
	/** Whether the executed tool result is currently treated as an error. */
	IsError bool
	/** Current agent context at the time the tool call is prepared. */
	Context AgentContext
}

type AfterToolCallResult struct {
	Content   *[]ai.ToolResultContent
	Details   *any
	IsError   *bool
	Terminate *bool
}

type Agent struct {
	ConvertToLLM     ConvertToLLMFunc
	TransformContext TransformContextFunc
	StreamFn         StreamFn
	ResolveAuth      func(ctx context.Context, model ai.Model[ai.API]) (ai.ModelAuth, error)

	OnPayload  func(payload any, model ai.Model[ai.API]) (any, error)
	OnResponse func(response ai.ProviderResponse, model ai.Model[ai.API]) error

	BeforeToolCall  func(context.Context, BeforeToolCallContext) (*BeforeToolCallResult, error)
	AfterToolCall   func(context.Context, AfterToolCallContext[any]) (*AfterToolCallResult, error)
	PrepareNextTurn func(context.Context, PrepareNextTurnContext) (*AgentLoopTurnUpdate, error)

	SessionID       *string
	ThinkingBudgets *ai.ThinkingBudgets
	Transport       ai.Transport
	MaxRetryDelayMs *int64
	ToolExecution   ToolExecutionMode
	// contains filtered or unexported fields
}

type AgentContext struct {
	/** System prompt included with the request. */
	SystemPrompt string
	/** Transcript visible to the model. */
	Messages []AgentMessage
	/** Tools available for this run. */
	Tools []AgentTool[any, any]
}

type AgentEvent interface {
	EventType() string
}

type AgentEventSink func(event AgentEvent) error

type AgentListener func(event AgentEvent, ctx context.Context) error

type AgentLoopConfig struct {
	ai.SimpleStreamOptions
	Model               ai.Model[ai.API]
	Stream              StreamFn             `json:"-"`
	ConvertToLLM        ConvertToLLMFunc     `json:"convert_to_llm"`
	TransformContext    TransformContextFunc `json:"transform_context"`
	ResolveAuth         func(ctx context.Context, model ai.Model[ai.API]) (ai.ModelAuth, error)
	ShouldStopAfterTurn func(ctx ShouldStopAfterTurnContext) bool
	// PrepareNextTurn runs after a turn completes and before the next one
	// starts, and may change the next turn, for example its tools. An error
	// ends the run.
	PrepareNextTurn     func(ctx context.Context, turn PrepareNextTurnContext) (*AgentLoopTurnUpdate, error)
	GetSteeringMessages func(ctx context.Context) []AgentMessage
	GetFollowUpMessages func(ctx context.Context) []AgentMessage
	ToolExecution       *ToolExecutionMode
	BeforeToolCall      func(ctx context.Context, call BeforeToolCallContext) (*BeforeToolCallResult, error)
	AfterToolCall       func(ctx context.Context, call AfterToolCallContext[any]) (*AfterToolCallResult, error)
}

type AgentLoopTurnUpdate struct {
	// Context for the next provider request, such as one with other tools.
	Context *AgentContext
	// Messages to append before the next provider request, with normal
	// lifecycle events.
	Messages []AgentMessage
	// Model for the next provider request.
	Model *ai.Model[ai.API]
	// ThinkingLevel for the next provider request.
	ThinkingLevel *ai.ModelThinkingLevel
}

type AgentMessage interface {
	AgentMessageType() string
}

type AgentOptions struct {
	InitialState *InitialAgentState

	ConvertToLLM     ConvertToLLMFunc
	TransformContext TransformContextFunc
	StreamFn         StreamFn

	// ResolveAuth returns the auth for each model request. It runs before
	// every request, so it can refresh tokens. An error ends the turn with an
	// error message instead of calling the model.
	ResolveAuth func(ctx context.Context, model ai.Model[ai.API]) (ai.ModelAuth, error)

	OnPayload  func(payload any, model ai.Model[ai.API]) (any, error)
	OnResponse func(response ai.ProviderResponse, model ai.Model[ai.API]) error

	BeforeToolCall func(
		ctx context.Context,
		call BeforeToolCallContext,
	) (*BeforeToolCallResult, error)

	AfterToolCall func(
		ctx context.Context,
		call AfterToolCallContext[any],
	) (*AfterToolCallResult, error)

	// PrepareNextTurn runs before every turn of a run but the first, and may
	// change it; see AgentLoopConfig.PrepareNextTurn.
	PrepareNextTurn func(ctx context.Context, turn PrepareNextTurnContext) (*AgentLoopTurnUpdate, error)

	SteeringMode QueueMode
	FollowUpMode QueueMode

	SessionID       *string
	ThinkingBudgets *ai.ThinkingBudgets
	Transport       ai.Transport
	MaxRetryDelayMs *int64
	ToolExecution   ToolExecutionMode
}

type AgentState struct {
	SystemPrompt  string
	Model         ai.Model[ai.API]
	ThinkingLevel ai.ModelThinkingLevel

	Tools    []AgentTool[any, any]
	Messages []AgentMessage

	IsStreaming      bool
	StreamingMessage AgentMessage
	PendingToolCalls map[string]struct{}
	ErrorMessage     string
}

type AgentTool[TParameters any, TDetails any] struct {
	ai.Tool
	Label string
	// Optional compatibility shim for raw tool-call arguments before validation.
	PrepareArguments func(args any) (TParameters, error)
	/**
	 * Execute the tool call. Return an error on failure, or a result with
	 * IsError set; do not only describe the failure in `content`.
	 */
	Execute func(
		ctx context.Context,
		toolCallID string,
		params TParameters,
		onUpdate AgentToolUpdateCallback[TDetails],
	) (AgentToolResult[TDetails], error)
	ToolExecutionMode *ToolExecutionMode
	// Annotations are optional hints about the tool's behavior, for apps
	// that ask before running some tools. The model does not see them.
	Annotations *ToolAnnotations
}

type AgentToolResult[TDetails any] struct {
	Content []ai.ToolResultContent
	Details TDetails
	// IsError reports a failure without returning an error. The model sees
	// Content as an error result, like a returned error, but Content keeps
	// its images and Details are kept for the UI.
	IsError   bool
	Terminate *bool
}

type AgentToolUpdateCallback[TDetails any] func(partialResult AgentToolResult[TDetails])

type BeforeToolCallContext struct {
	/** The assistant message that requested the tool call. */
	AssistantMessage ai.AssistantMessage
	/** The raw tool call block from `assistantMessage.content`. */
	ToolCall ai.ToolCall
	/** Validated tool arguments for the target tool schema. */
	Args any
	/** Current agent context at the time the tool call is prepared. */
	Context AgentContext
}

type BeforeToolCallResult struct {
	Block  *bool
	Reason *string
}

type ConvertToLLMFunc func(messages []AgentMessage) []ai.Message

type EndEvent struct {
	Type     string         `json:"type"`
	Messages []AgentMessage `json:"messages"`
}

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

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

type FinalizedToolCallEntryFunc func() (FinalizedToolCallOutcome, error)

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

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

type InitialAgentState struct {
	SystemPrompt  *string
	Model         *ai.Model[ai.API]
	ThinkingLevel *ai.ModelThinkingLevel
	Tools         []AgentTool[any, any]
	Messages      []AgentMessage
}

type MessageEndEvent struct {
	Type      string       `json:"type"`
	MessageID string       `json:"messageId"`
	Message   AgentMessage `json:"message"`
}

type MessageStartEvent struct {
	Type      string       `json:"type"`
	MessageID string       `json:"messageId"`
	Message   AgentMessage `json:"message"`
}

type MessageUpdateEvent struct {
	Type                  string       `json:"type"`
	MessageID             string       `json:"messageId"`
	Message               AgentMessage `json:"message"`
	AssistantMessageEvent ai.AssistantMessageEvent
}

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

type PrepareNextTurnContext = ShouldStopAfterTurnContext

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

type PreparedToolCallResult interface {
	EventType() string
}

type QueueMode string

type ShouldStopAfterTurnContext struct {
	Message     ai.AssistantMessage
	ToolResults []ai.ToolResultMessage
	Context     AgentContext
	NewMessages []AgentMessage
}

type StartEvent struct {
	Type string `json:"type"`
}

type StreamFn func(
	ctx context.Context,
	model ai.Model[ai.API],
	modelContext ai.ModelContext,
	options *ai.SimpleStreamOptions,
) (*ai.AssistantMessageEventStream, error)

type ToolAnnotations struct {
	// ReadOnlyHint: the tool does not change its environment.
	ReadOnlyHint *bool `json:"readOnlyHint,omitempty"`
	// DestructiveHint: the tool may make destructive changes, not only
	// additive ones.
	DestructiveHint *bool `json:"destructiveHint,omitempty"`
	// IdempotentHint: calling the tool again with the same arguments has no
	// further effect.
	IdempotentHint *bool `json:"idempotentHint,omitempty"`
	// OpenWorldHint: the tool interacts with an open world of external
	// entities, such as the web.
	OpenWorldHint *bool `json:"openWorldHint,omitempty"`
}

type ToolExecutionEndEvent struct {
	Type       string `json:"type"`
	ToolCallID string `json:"tool_call_id"`
	ToolName   string `json:"tool_name"`
	Result     any    `json:"result"`
	IsError    bool   `json:"is_error"`
}

type ToolExecutionMode string

type ToolExecutionStartEvent struct {
	Type       string `json:"type"`
	ToolCallID string `json:"tool_call_id"`
	ToolName   string `json:"tool_name"`
	ToolArgs   any    `json:"tool_args"`
}

type ToolExecutionUpdateEvent struct {
	Type          string `json:"type"`
	ToolCallID    string `json:"tool_call_id"`
	ToolName      string `json:"tool_name"`
	ToolArgs      any    `json:"tool_args"`
	PartialResult any    `json:"partial_result"`
}

type TransformContextFunc func(ctx context.Context, messages []AgentMessage) []AgentMessage

type TurnEndEvent struct {
	Type        string                 `json:"type"`
	Message     AgentMessage           `json:"message"`
	ToolResults []ai.ToolResultMessage `json:"tool_results"`
}

type TurnStartEvent struct {
	Type string `json:"type"`
}