kit

type AfterToolResultHook struct {
	ToolCallID string
	ToolName   string
	ToolArgs   string
	Result     string
	IsError    bool
}

type AfterToolResultResult struct {
	Result  *string // non-nil overrides the result text
	IsError *bool   // non-nil overrides the error flag
}

type AfterTurnHook struct {
	Response string
	Error    error
}

type AfterTurnResult struct{}

type AgentConfig = agent.AgentConfig

type AnthropicCredentials = auth.AnthropicCredentials

type BeforeCompactHook struct {
	// EstimatedTokens is the estimated token count of the conversation.
	EstimatedTokens int
	// ContextLimit is the model's context window size in tokens.
	ContextLimit int
	// UsagePercent is the fraction of context used (0.0–1.0).
	UsagePercent float64
	// MessageCount is the number of messages in the conversation.
	MessageCount int
	// IsAutomatic is true when compaction was triggered automatically.
	IsAutomatic bool
}

type BeforeCompactResult struct {
	// Cancel, when true, prevents compaction from proceeding.
	Cancel bool
	// Reason is a human-readable explanation when Cancel is true.
	Reason string
	// Summary, when non-empty, replaces the default LLM-generated summary.
	// The extension is responsible for generating a useful summary.
	// Ignored when Cancel is true.
	Summary string
}

type BeforeToolCallHook struct {
	ToolCallID string
	ToolName   string
	ToolArgs   string
}

type BeforeToolCallResult struct {
	Block  bool   // true prevents the tool from running
	Reason string // human-readable reason for blocking
}

type BeforeTurnHook struct {
	Prompt string
}

type BeforeTurnResult struct {
	Prompt       *string // override prompt text in the user message
	SystemPrompt *string // prepend a system message
	InjectText   *string // prepend a user context message
}

type BranchEntry struct {
	ID        string
	ParentID  string
	Type      EntryType // "message", "branch_summary", "model_change", "compaction", "extension_data"
	Role      string    // for messages: "user", "assistant", "system", "tool"
	Content   string    // text content or summary
	Model     string    // model used (for messages and model_change)
	Provider  string    // provider used
	Timestamp time.Time
	Children  []string // child entry IDs (for tree display)

	// RawParts contains the full typed content parts for structured access.
	// Only populated for message entries.
	RawParts []ContentPart
}

type CLIMCPAuthHandler struct {

	// NotifyFunc, when set, is called with status messages instead of
	// writing to the writer. This allows the TUI to display system
	// messages in the chat stream. If nil, messages are written to w.
	NotifyFunc func(serverName, message string)
	// contains filtered or unexported fields
}

type CLIOptions struct {
	// MCPConfig is a pre-loaded MCP config. When set, LoadAndValidateConfig
	// is skipped during Kit creation.
	MCPConfig *config.Config
	// ShowSpinner shows a loading spinner for Ollama models.
	ShowSpinner bool
	// SpinnerFunc provides the spinner implementation (nil = no spinner).
	SpinnerFunc SpinnerFunc
	// UseBufferedLogger buffers debug messages for later display.
	UseBufferedLogger bool
	// ProgressReaderFunc wraps an io.Reader with a progress display for
	// long-running operations such as Ollama model pulls. The returned
	// io.ReadCloser must be closed when done. When nil, progress is not
	// displayed.
	ProgressReaderFunc func(io.Reader) io.ReadCloser
}

type CompactionEntry struct {
	ID               string
	Summary          string
	FirstKeptEntryID string
	TokensBefore     int
	TokensAfter      int
	MessagesRemoved  int
	ReadFiles        []string
	ModifiedFiles    []string
	Timestamp        time.Time
}

type CompactionEvent struct {
	Summary         string
	OriginalTokens  int
	CompactedTokens int
	MessagesRemoved int
	ReadFiles       []string
	ModifiedFiles   []string
}

type CompactionOptions = compaction.CompactionOptions

type CompactionResult = compaction.CompactionResult

type Config = config.Config

type ContentPart = message.ContentPart

type ContextFile struct {
	Path    string // Absolute filesystem path.
	Content string // Full file content.
}

type ContextPrepareHook struct {
	// Messages is the current context as LLM message objects.
	Messages []LLMMessage
}

type ContextPrepareResult struct {
	// Messages replaces the entire context window. If nil, the original
	// messages are used.
	Messages []LLMMessage
}

type ContextStats struct {
	EstimatedTokens int     // Estimated token count of the current conversation
	ContextLimit    int     // Model's context window size (tokens), 0 if unknown
	UsagePercent    float64 // Fraction of context used (0.0–1.0), 0 if limit unknown
	MessageCount    int     // Number of messages in the conversation
}

type CredentialManager = auth.CredentialManager

type CredentialStore = auth.CredentialStore

type DefaultMCPAuthHandler struct {

	// OnAuthURL, if set, is invoked exactly once per [HandleAuth] call with
	// the authorization URL the user must visit. This is where consumers
	// plug in their UX: open a browser, print to stderr, post to a TUI
	// stream, render a QR code, etc. The handler performs no I/O on the
	// URL itself; if OnAuthURL is nil the URL is silently dropped and the
	// user has no way to complete the flow.
	//
	// OnAuthURL is called synchronously before the handler blocks on the
	// callback. It must not block indefinitely — long-running work should
	// be dispatched to a goroutine.
	OnAuthURL func(serverName, authURL string)
	// contains filtered or unexported fields
}

type DiffBlock struct {
	OldText string `json:"old_text"`
	NewText string `json:"new_text"`
}

type EntryType string

type Event interface {
	EventType() EventType
}

type EventListener func(event Event)

type EventType string

type ExtensionAPI interface {
	// Context management
	SetContext(ctx extensions.Context)
	GetContext() extensions.Context
	UpdateContextModel(model string)

	// Widgets
	SetWidget(config extensions.WidgetConfig)
	RemoveWidget(id string)
	GetWidgets(placement extensions.WidgetPlacement) []extensions.WidgetConfig

	// Header/Footer
	SetHeader(config extensions.HeaderFooterConfig)
	RemoveHeader()
	GetHeader() *extensions.HeaderFooterConfig
	SetFooter(config extensions.HeaderFooterConfig)
	RemoveFooter()
	GetFooter() *extensions.HeaderFooterConfig

	// Editor
	SetEditor(config extensions.EditorConfig)
	ResetEditor()
	GetEditor() *extensions.EditorConfig

	// UI Visibility
	SetUIVisibility(v extensions.UIVisibility)
	GetUIVisibility() *extensions.UIVisibility

	// Tool rendering
	GetToolRenderer(toolName string) *extensions.ToolRenderConfig
	GetMessageRenderer(name string) *extensions.MessageRendererConfig

	// Session data
	GetSessionMessages() []extensions.SessionMessage
	AppendEntry(extType, data string) (string, error)
	GetEntries(extType string) []extensions.ExtensionEntry

	// Status bar
	SetStatus(entry extensions.StatusBarEntry)
	RemoveStatus(key string)
	GetStatusEntries() []extensions.StatusBarEntry

	// Shortcuts
	GetShortcuts() map[string]func()

	// Tools
	GetToolInfos() []extensions.ToolInfo
	SetActiveTools(names []string)

	// Options
	GetOption(name string) string
	SetOption(name, value string)

	// Events
	EmitSessionStart()
	EmitModelChange(newModel, previousModel, source string)
	EmitCustomEvent(name, data string)
	EmitBeforeFork(targetID string, isUserMsg bool, userText string) (cancelled bool, reason string)
	EmitBeforeSessionSwitch(switchReason string) (cancelled bool, reason string)

	// Commands
	Commands() []extensions.CommandDef

	// Lifecycle
	Reload() error
	HasExtensions() bool
}

type ExtensionDataEntry struct {
	ID        string
	ExtType   string
	Data      string
	Timestamp time.Time
}

type FileDiffInfo struct {
	Path       string      `json:"path"`             // Absolute file path
	Additions  int         `json:"additions"`        // Lines added
	Deletions  int         `json:"deletions"`        // Lines removed
	IsNew      bool        `json:"is_new,omitempty"` // True if file was created (write only)
	DiffBlocks []DiffBlock `json:"diff_blocks,omitempty"`
}

type Finish = message.Finish

type HookPriority int

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

type LLMFilePart = fantasy.FilePart

type LLMFinishReason = fantasy.FinishReason

type LLMMessage = fantasy.Message

type LLMMessagePart = fantasy.MessagePart

type LLMMessageRole = fantasy.MessageRole

type LLMReasoningPart = fantasy.ReasoningPart

type LLMResponse = fantasy.Response

type LLMTextPart = fantasy.TextPart

type LLMToolCallPart = fantasy.ToolCallPart

type LLMToolResultOutputContent = fantasy.ToolResultOutputContent

type LLMToolResultOutputContentError = fantasy.ToolResultOutputContentError

type LLMToolResultOutputContentText = fantasy.ToolResultOutputContentText

type LLMToolResultPart = fantasy.ToolResultPart

type LLMUsage = fantasy.Usage

type MCPAuthHandler interface {
	// RedirectURI returns the OAuth redirect URI that the callback server
	// will listen on. This is called during MCP transport setup — before any
	// OAuth errors occur — so the redirect URI can be registered with the
	// authorization server.
	RedirectURI() string

	// HandleAuth is called when an MCP server requires OAuth authorization.
	// It receives the server name and an authorization URL that the user must
	// visit. The handler must:
	//   1. Direct the user to authURL (e.g. open browser, display URL)
	//   2. Listen for the OAuth callback on the redirect URI
	//   3. Return the full callback URL (with code and state query params)
	//
	// Return an error to abort the connection to this MCP server.
	// The context controls the overall timeout; implementations should
	// respect ctx.Done().
	HandleAuth(ctx context.Context, serverName string, authURL string) (callbackURL string, err error)
}

type MCPPrompt struct {
	// Name is the prompt name on the MCP server.
	Name string
	// Description is a human-readable description.
	Description string
	// Arguments lists the prompt's expected arguments.
	Arguments []MCPPromptArgument
	// ServerName is the MCP server that provides this prompt.
	ServerName string
}

type MCPPromptArgument struct {
	// Name is the argument name.
	Name string
	// Description is a human-readable description.
	Description string
	// Required indicates whether this argument must be provided.
	Required bool
}

type MCPPromptMessage struct {
	// Role is "user" or "assistant".
	Role string
	// Content is the text content of the message.
	Content string
	// FileParts contains binary attachments extracted from embedded resources,
	// images, or audio content blocks within the prompt message. Empty for
	// text-only messages.
	FileParts []LLMFilePart
}

type MCPPromptResult struct {
	// Description is an optional description returned by the server.
	Description string
	// Messages contains the expanded prompt messages.
	Messages []MCPPromptMessage
}

type MCPResource struct {
	// URI is the unique resource identifier (e.g. "file:///path" or custom scheme).
	URI string
	// Name is a human-readable name for the resource.
	Name string
	// Description is an optional description of the resource.
	Description string
	// MIMEType is the MIME type of the resource, if known.
	MIMEType string
	// ServerName is the MCP server that provides this resource.
	ServerName string
}

type MCPResourceContent struct {
	// URI is the resource URI that was read.
	URI string
	// MIMEType is the MIME type of the content.
	MIMEType string
	// Text is the text content (non-empty for text resources).
	Text string
	// BlobData is the decoded binary content (non-empty for blob resources).
	BlobData []byte
	// IsBlob is true when the content is binary (BlobData is set).
	IsBlob bool
}

type MCPServer = server.MCPServer

type MCPServerConfig = config.MCPServerConfig

type MCPServerStatus struct {
	// Name is the configured server name.
	Name string
	// ToolCount is the number of tools loaded from this server.
	ToolCount int
}

type MCPToken = transport.Token

type MCPTokenStore = transport.TokenStore

type MCPTokenStoreFactory func(serverURL string) (MCPTokenStore, error)

type Message = message.Message

type MessageEndEvent struct {
	Content string
}

type MessageEntry = session.MessageEntry

type MessageRole = message.MessageRole

type MessageStartEvent struct{}

type MessageUpdateEvent struct {
	Chunk string
}

type ModelCost = models.Cost

type ModelInfo = models.ModelInfo

type ModelLimit = models.Limit

type ModelsRegistry = models.ModelsRegistry

type OpenAICredentials = auth.OpenAICredentials

type Options struct {
	Model        string // Override model (e.g., "anthropic/claude-sonnet-4-5-20250929")
	SystemPrompt string // Override system prompt
	ConfigFile   string // Override config file path
	MaxSteps     int    // Override max steps (0 = use default)
	Streaming    bool   // Enable streaming (default from config)
	Quiet        bool   // Suppress debug output
	Tools        []Tool // Custom tool set. If empty, AllTools() is used.
	ExtraTools   []Tool // Additional tools added alongside core/MCP/extension tools.

	// MaxTokens overrides the maximum output tokens per LLM response.
	// 0 = let the precedence chain resolve a value (env → config →
	// per-model → 8192 SDK floor, matching the CLI default). Setting a
	// non-zero value here suppresses automatic right-sizing, matching
	// the CLI's --max-tokens flag semantics. Bump this when generating
	// long outputs (HTML artifacts, large refactors, etc.) to avoid
	// silent truncation mid-tool-call. The cap also applies after
	// model switches via [Kit.SetModel].
	MaxTokens int

	// ThinkingLevel sets the reasoning effort for models that support
	// extended thinking. Valid values: "off", "none", "minimal", "low",
	// "medium", "high". "" = let the precedence chain resolve a level
	// (env → config → per-model → "off"). Use [Kit.SetThinkingLevel]
	// to change at runtime.
	ThinkingLevel string

	// Temperature controls sampling randomness (typically 0.0–2.0).
	// nil = leave provider/per-model default in place. Pointer type
	// so explicit 0.0 (deterministic) is distinguishable from "unset".
	Temperature *float32

	// TopP is the nucleus-sampling cutoff (0.0–1.0).
	// nil = leave provider/per-model default in place.
	TopP *float32

	// TopK limits sampling to the top K tokens.
	// nil = leave provider/per-model default in place.
	TopK *int32

	// FrequencyPenalty discourages repeated tokens (OpenAI-family models).
	// nil = leave provider/per-model default in place.
	FrequencyPenalty *float32

	// PresencePenalty discourages repeating topics (OpenAI-family models).
	// nil = leave provider/per-model default in place.
	PresencePenalty *float32

	// ProviderAPIKey overrides the API key used to authenticate with the
	// model provider. "" = use the value from config or the
	// provider-specific environment variable.
	ProviderAPIKey string

	// ProviderURL overrides the provider endpoint. "" = use the provider's
	// default URL.
	ProviderURL string

	// TLSSkipVerify disables TLS certificate verification on provider
	// HTTP clients. Only set this for self-signed certificates in
	// development. Once enabled here it cannot be disabled via Options
	// (use the config file or env var to opt back out).
	TLSSkipVerify bool

	// SkipConfig, when true, skips loading .kit.yml configuration files.
	// Viper defaults (setSDKDefaults) and environment variables (KIT_*)
	// are still applied. Use this for fully programmatic configuration.
	SkipConfig bool

	// DisableCoreTools, when true, prevents loading any core tools.
	// Use with Tools or ExtraTools to provide only custom tools.
	// If both DisableCoreTools is true and Tools is empty, the agent
	// will have no tools (useful for simple chat completions).
	DisableCoreTools bool

	// Session configuration
	SessionDir  string // Base directory for session discovery (default: cwd)
	SessionPath string // Open a specific session file by path
	Continue    bool   // Continue the most recent session for SessionDir
	NoSession   bool   // Ephemeral mode — in-memory session, no persistence

	// Skills
	Skills    []string // Explicit skill files/dirs to load (empty = auto-discover)
	SkillsDir string   // Override default project-local skills directory
	NoSkills  bool     // Disable skill loading entirely (auto-discovery and explicit)

	// NoExtensions disables Yaegi extension loading entirely.
	NoExtensions bool

	// NoContextFiles disables automatic loading of project context files
	// (e.g. AGENTS.md) from the working directory.
	NoContextFiles bool

	// MCPConfig provides a pre-loaded MCP configuration. When set,
	// LoadAndValidateConfig is skipped during Kit creation — avoiding
	// viper access entirely. This is set automatically for in-process
	// subagents (inheriting the parent's loaded config) and can be used
	// by SDK consumers who build config programmatically.
	MCPConfig *config.Config

	// InProcessMCPServers registers mcp-go servers that run in the same
	// process. Each key is the server name (used to prefix tool names, e.g.
	// "docs__search"). The value must be a *[server.MCPServer].
	//
	// In-process servers bypass subprocess spawning and network I/O entirely.
	// Kit does not take ownership of the servers — the caller is responsible
	// for any cleanup after [Kit.Close].
	//
	// Example:
	//
	//	mcpSrv := server.NewMCPServer("my-tools", "1.0.0",
	//	    server.WithToolCapabilities(true),
	//	)
	//	mcpSrv.AddTool(mcp.NewTool("search", ...), handler)
	//
	//	host, _ := kit.New(ctx, &kit.Options{
	//	    InProcessMCPServers: map[string]*kit.MCPServer{
	//	        "docs": mcpSrv,
	//	    },
	//	})
	InProcessMCPServers map[string]*MCPServer

	// Compaction
	AutoCompact       bool               // Auto-compact when near context limit
	CompactionOptions *CompactionOptions // Config for auto-compaction (nil = defaults)

	// Debug enables debug logging for the SDK.
	Debug bool

	// MCPAuthHandler handles OAuth authorization for remote MCP servers.
	// When set, remote transports (streamable HTTP, SSE) are configured
	// with OAuth support. If the server returns a 401, the handler is
	// invoked to let the user authorize.
	//
	// If nil, OAuth is disabled: remote MCP servers requiring authorization
	// will fail to connect and the underlying authorization-required error
	// is surfaced to the caller. The SDK deliberately does not construct a
	// default handler — doing so would bind a local TCP port and trigger
	// presentation I/O (browser open, stderr writes) without the consumer
	// opting in, which is wrong for library, daemon, or web-app embedders.
	//
	// CLI consumers: pass [NewCLIMCPAuthHandler] to get the standard
	// "open browser + print status" behavior.
	//
	// Custom UX: implement [MCPAuthHandler] directly, or use
	// [DefaultMCPAuthHandler] and set its OnAuthURL hook to plug in your
	// own presentation (TUI modal, QR code, web redirect, etc.).
	MCPAuthHandler MCPAuthHandler

	// MCPTokenStoreFactory, if non-nil, is called to create a token store for
	// each remote MCP server that requires OAuth. The factory receives the
	// server's URL and returns a [MCPTokenStore] implementation.
	//
	// When nil (default), tokens are persisted to a JSON file at
	// $XDG_CONFIG_HOME/.kit/mcp_tokens.json (or ~/.config/.kit/mcp_tokens.json).
	//
	// Use this to store tokens in a database, encrypt them, keep them
	// in-memory, or write them to a custom file path.
	MCPTokenStoreFactory MCPTokenStoreFactory

	// OnMCPServerLoaded, if non-nil, is called when each MCP server finishes
	// loading during Kit initialization. The callback receives the server name,
	// tool count, and any error. Called from a background goroutine; safe to
	// call app.NotifyMCPServerLoaded() from within the callback to display
	// real-time progress in the TUI.
	OnMCPServerLoaded func(serverName string, toolCount int, err error)

	// CLI is optional CLI-specific configuration. SDK users leave this nil.
	CLI *CLIOptions

	// SessionManager allows custom session storage backends.
	// If nil (default), Kit uses the built-in file-based TreeManager.
	// When provided, SessionPath, Continue, and NoSession options are ignored.
	SessionManager SessionManager
}

type PasswordPromptEvent struct {
	// Prompt is the message to display to the user.
	Prompt string
	// ResponseCh receives the password from the TUI.
	// The TUI must send exactly one value: (password, false) for submit
	// or ("", true) for cancel.
	ResponseCh chan<- PasswordPromptResponse
}

type PasswordPromptResponse struct {
	Password  string
	Cancelled bool
}

type PromptBuilder = skills.PromptBuilder

type PromptOptions struct {
	// SystemMessage is prepended as a system message before the user prompt.
	// Use it to inject per-call instructions or context without permanently
	// modifying the agent's system prompt.
	SystemMessage string
}

type PromptTemplate = skills.PromptTemplate

type ProviderConfig = models.ProviderConfig

type ProviderInfo = models.ProviderInfo

type ProviderResult = models.ProviderResult

type ReasoningCompleteEvent struct{}

type ReasoningContent = message.ReasoningContent

type ReasoningDeltaEvent struct {
	Delta string
}

type ResponseEvent struct {
	Content string
}

type ResponseHandler = agent.ResponseHandler

type SessionHeader = session.SessionHeader

type SessionInfo = session.SessionInfo

type SessionManager interface {
	// AppendMessage adds a message to the current branch and returns its entry ID.
	// The entry ID is used for tree navigation and must be unique within the session.
	//
	// During generation, AppendMessage is called incrementally after each
	// completed agent step rather than in a batch at the end of the turn.
	// For tool-calling steps, the assistant message (containing tool_use parts)
	// and the tool-role message (containing tool_result parts) are appended
	// together as a pair. This ensures the session never contains an orphaned
	// tool call without its result, which would break subsequent LLM requests.
	AppendMessage(msg LLMMessage) (entryID string, err error)

	// GetMessages returns all messages on the current branch (from root to leaf),
	// including any compaction summaries at the appropriate positions.
	GetMessages() []LLMMessage

	// BuildContext returns the message history to send to the LLM, applying
	// compaction rules and branch summaries as needed.
	// Returns: messages, currentProvider, currentModelID
	BuildContext() (messages []LLMMessage, provider string, modelID string)

	// Branch moves the leaf pointer to the given entry ID, creating a branch point.
	// Subsequent AppendMessage calls extend from this new position.
	// entryID can be empty to reset to root (new conversation branch).
	Branch(entryID string) error

	// GetCurrentBranch returns the path from root to current leaf as entry metadata.
	// Used for UI display and navigation.
	GetCurrentBranch() []BranchEntry

	// GetChildren returns direct child entry IDs for a given parent entry.
	// Used to display branch points in the conversation tree.
	GetChildren(parentID string) []string

	// GetEntry returns a specific entry by ID, or nil if not found.
	GetEntry(entryID string) *BranchEntry

	// GetSessionID returns the unique session identifier (UUID).
	GetSessionID() string

	// GetSessionName returns the user-defined display name, or empty.
	GetSessionName() string

	// SetSessionName sets a display name for the session.
	SetSessionName(name string) error

	// GetCreatedAt returns when the session was created.
	GetCreatedAt() time.Time

	// IsPersisted returns true if this session writes to durable storage.
	IsPersisted() bool

	// AppendCompaction adds a compaction entry that summarizes older messages.
	// firstKeptEntryID is the ID of the first message to preserve in context.
	// readFiles and modifiedFiles track file changes for the compaction summary.
	AppendCompaction(summary string, firstKeptEntryID string,
		tokensBefore, tokensAfter int, messagesRemoved int, readFiles, modifiedFiles []string) (string, error)

	// GetLastCompaction returns the most recent compaction entry on the current
	// branch, or nil if none exists.
	GetLastCompaction() *CompactionEntry

	// AppendExtensionData stores custom extension data in the session tree.
	// Extensions use this to persist state across restarts.
	AppendExtensionData(extType, data string) (string, error)

	// GetExtensionData returns all extension data entries of the given type
	// on the current branch. If extType is empty, returns all extension data.
	GetExtensionData(extType string) []ExtensionDataEntry

	// AppendModelChange records a provider/model switch in the session.
	AppendModelChange(provider, modelID string) (string, error)

	// GetContextEntryIDs returns the entry IDs corresponding to the messages
	// returned by BuildContext, in the same order. Used by compaction to
	// determine which entries to summarize.
	GetContextEntryIDs() []string

	// Close releases resources (database connections, file handles, etc.).
	Close() error
}

type Skill = skills.Skill

type SpinnerFunc = agent.SpinnerFunc

type SteerConsumedEvent struct {
	Count int
}

type StepUsageEvent struct {
	InputTokens      uint64
	OutputTokens     uint64
	CacheReadTokens  uint64
	CacheWriteTokens uint64
}

type StreamingResponseHandler = agent.StreamingResponseHandler

type StructuredMessage struct {
	ID        string
	ParentID  string
	Role      MessageRole
	Parts     []ContentPart
	Model     string
	Provider  string
	Timestamp string // RFC3339 format
}

type SubagentConfig struct {
	// Prompt is the task/instruction for the subagent (required).
	Prompt string

	// Model overrides the parent's model (e.g. "anthropic/claude-haiku-3-5-20241022").
	// Empty string uses the parent's current model.
	Model string

	// SystemPrompt provides domain-specific instructions for the subagent.
	// Empty string uses a minimal default prompt.
	SystemPrompt string

	// Tools overrides the tool set. If nil, SubagentTools() is used (all
	// core tools except subagent, preventing infinite recursion).
	Tools []Tool

	// NoSession, when true, uses an in-memory ephemeral session. When false
	// (default), the subagent's session is persisted and can be loaded for
	// replay/inspection.
	NoSession bool

	// Timeout limits execution time. Zero means 5 minute default.
	Timeout time.Duration

	// OnEvent, when set, receives all events from the subagent's event bus.
	// This enables the parent to stream subagent tool calls, text chunks,
	// etc. in real time.
	OnEvent func(Event)
}

type SubagentResult struct {
	// Response is the subagent's final text response.
	Response string
	// SessionID is the subagent's session identifier (for replay).
	SessionID string
	// StopReason is the LLM's finish reason for the subagent's final turn.
	StopReason string
	// Usage contains token usage from the subagent's run.
	Usage *LLMUsage
	// Elapsed is the total execution time.
	Elapsed time.Duration
}

type TextContent = message.TextContent

type Tool = fantasy.AgentTool

type ToolCall = message.ToolCall

type ToolCallContentEvent struct {
	Content string
}

type ToolCallContentHandler = agent.ToolCallContentHandler

type ToolCallDeltaEvent struct {
	ToolCallID string // Stable ID for correlating tool lifecycle events
	Delta      string // JSON fragment of tool arguments
}

type ToolCallEndEvent struct {
	ToolCallID string // Stable ID for correlating tool lifecycle events
}

type ToolCallEvent struct {
	ToolCallID string // Stable ID for correlating tool lifecycle events
	ToolName   string
	ToolKind   string         // Tool classification: "execute", "edit", "read", "search", "agent"
	ToolArgs   string         // JSON-encoded arguments
	ParsedArgs map[string]any // Pre-parsed arguments for convenience (nil on parse failure)
}

type ToolCallHandler = agent.ToolCallHandler

type ToolCallStartEvent struct {
	ToolCallID string // Stable ID for correlating tool lifecycle events
	ToolName   string
	ToolKind   string // Tool classification: "execute", "edit", "read", "search", "agent"
}

type ToolExecutionEndEvent struct {
	ToolCallID string
	ToolName   string
	ToolKind   string
}

type ToolExecutionHandler = agent.ToolExecutionHandler

type ToolExecutionStartEvent struct {
	ToolCallID string
	ToolName   string
	ToolKind   string
	ToolArgs   string
}

type ToolOption = core.ToolOption

type ToolOutput struct {
	// Content is the text content returned to the LLM.
	Content string

	// IsError, when true, signals to the LLM that the tool call failed.
	IsError bool

	// Data contains optional binary data (images, audio, etc.).
	Data []byte

	// MediaType is the MIME type for binary Data (e.g. "image/png").
	MediaType string

	// Metadata is optional opaque metadata attached to the response.
	// It is not sent to the LLM but may be consumed by hooks or the UI.
	Metadata any
}

type ToolOutputEvent struct {
	ToolCallID string
	ToolName   string
	Chunk      string
	IsStderr   bool
}

type ToolResult = message.ToolResult

type ToolResultEvent struct {
	ToolCallID string
	ToolName   string
	ToolKind   string
	ToolArgs   string
	ParsedArgs map[string]any // Pre-parsed arguments for convenience
	Result     string
	IsError    bool
	Metadata   *ToolResultMetadata // Optional structured metadata from tool execution
}

type ToolResultHandler = agent.ToolResultHandler

type ToolResultMetadata struct {
	FileDiffs         []FileDiffInfo `json:"file_diffs,omitempty"`          // Present for edit/write tools
	SubagentSessionID string         `json:"subagent_session_id,omitempty"` // Present for subagent tool
}

type TreeManager = session.TreeManager

type TreeNode struct {
	ID        string
	ParentID  string
	Type      string // "message", "branch_summary", "model_change", "extension_data"
	Role      string // for messages: "user", "assistant", "system", "tool"
	Content   string
	Model     string
	Provider  string
	Timestamp string
	Children  []string
}

type TurnEndEvent struct {
	Response string
	Error    error
	// StopReason is the LLM provider's finish reason for the final step of
	// the turn. Compare against the FinishReason* constants — in particular,
	// FinishReasonLength indicates the response was truncated because the
	// agent hit its max_output_tokens budget.
	StopReason string
}

type TurnResult struct {
	// Response is the assistant's final text response.
	Response string

	// StopReason indicates why the turn ended. Derived from the LLM
	// provider's finish reason: FinishReasonStop, FinishReasonLength (max
	// output tokens reached), FinishReasonToolCalls, FinishReasonContentFilter,
	// FinishReasonError, FinishReasonOther, FinishReasonUnknown.
	StopReason string

	// SessionID is the UUID of the session this turn belongs to.
	SessionID string

	// TotalUsage is the aggregate token usage across all steps in the turn
	// (includes tool-calling loop iterations). Nil if the provider didn't
	// report usage.
	TotalUsage *LLMUsage

	// FinalUsage is the token usage from the last API call only. For context
	// window fill, sum all categories: InputTokens + CacheReadTokens +
	// CacheCreationTokens + OutputTokens. With prompt caching, InputTokens
	// alone understates the context (cached tokens are reported separately).
	// Nil if unavailable.
	FinalUsage *LLMUsage

	// Messages is the full updated conversation after the turn, including
	// any tool call/result messages added during the agent loop.
	// Each message carries role and plain-text content.
	Messages []LLMMessage
}

type TurnStartEvent struct {
	Prompt string
}