agent

type AgentSession = SessionRuntime

type AgentSessionOptions struct {
	// CWD is the working directory for tool execution and resource discovery.
	// Defaults to the SessionManager's CWD if set, else ".".
	CWD string

	// AgentDir is the global config directory (auth.json, models.json, skills,
	// extensions). Defaults to ~/.pi/agent.
	AgentDir string

	// Model selects the initial model. When nil, NewAgentSession restores the
	// session model, then tries the settings default and available models.
	Model *ai.Model

	// ThinkingLevel sets the initial thinking budget. Clamped to the model's
	// supported range. Zero value defaults to "medium" for reasoning models
	// or "off" otherwise.
	ThinkingLevel ai.ModelThinkingLevel

	// ScopedModels restricts model cycling (CycleModel) to this set.
	ScopedModels []ScopedModel

	// StreamFn provides the LLM streaming backend. Defaults to the built-in
	// provider dispatcher when nil.
	StreamFn engine.StreamFn

	// GetAPIKey resolves API keys at request time. With the default StreamFn,
	// a nil resolver is derived from ModelRegistry.
	GetAPIKey engine.GetAPIKeyFunc

	// GetRequestAuth resolves request-time auth (OAuth tokens, Copilot baseURL).
	// When set, takes precedence over GetAPIKey for API key resolution; with
	// the default StreamFn, a nil resolver is derived from ModelRegistry.
	GetRequestAuth engine.GetRequestAuthFunc

	// GetModelHeaders provides per-request headers (e.g. attribution).
	GetModelHeaders engine.GetModelHeadersFunc

	// AvailableModels returns all models the host considers available.
	// Used by CycleModel when ScopedModels is empty.
	AvailableModels func() []ai.Model

	// ModelRegistry provides model resolution, auth checking, available-model
	// discovery, and session model restoration. Created from AgentDir when nil.
	ModelRegistry *config.ModelRegistry

	// NoTools suppresses default tool construction:
	//   "all"     — start with no tools at all
	//   "builtin" — disable default built-ins but keep extension/custom tools
	NoTools string

	// Tools is an allowlist of tool names. When provided, only listed tools
	// are enabled. Applies to built-in, extension, and custom tools.
	// When nil, the default set (read, bash, edit, write) is used unless
	// NoTools changes that.
	Tools []string

	// ExcludeTools is a denylist of tool names. Applied after Tools.
	ExcludeTools []string

	// CustomTools registers additional tool definitions alongside built-ins.
	CustomTools []extensions.ToolDefinition

	// ToolOptions overrides per-tool construction options for built-in tools.
	// Nil fields keep local defaults; settings-derived fields (AutoResizeImages,
	// ShellPath, CommandPrefix) are still applied when unset on the override.
	//
	// The options — including the nested per-tool structs — are captured by
	// the session and re-read whenever tools are rebuilt (also by
	// extension-driven tool rebuilds); they must not be mutated after
	// NewAgentSession returns.
	ToolOptions *tools.ToolsOptions

	// SessionManager controls session persistence. When nil a persistent
	// session is created for CWD (matching upstream default).
	SessionManager *sessionstore.SessionManager

	// Settings controls compaction, retry, and other runtime behavior.
	// When nil a default SettingsManager is created for CWD.
	Settings *config.SettingsManager

	// Resources supplies context files, skills, prompt templates, and the
	// system prompt. ResourceLoader takes precedence when both are provided.
	Resources *Resources

	// ResourceLoader supplies reloadable resources and native extensions. When
	// nil with no Resources override, DefaultResourceLoader is used.
	ResourceLoader ResourceLoader

	// ExtensionRegistry holds registered extensions. When non-nil and
	// non-empty, extensions are bound to the session runtime.
	ExtensionRegistry *extensions.Registry

	// SessionStartEvent metadata emitted when extensions bind.
	SessionStartEvent *extensions.SessionStartEvent

	// DeferExtensionStart leaves session_start activation to
	// [SessionRuntime.BindExtensions]. Runtime hosts use it so setup and host
	// rebinding finish before extensions observe the new session.
	DeferExtensionStart bool

	// ProjectTrustContext is supplied by replacement hosts for the effective
	// CWD so a custom runtime factory can resolve project trust before loading
	// project-scoped services.
	ProjectTrustContext extensions.ProjectTrustContext

	// SlashResolver handles /command and /skill expansion. When nil it is
	// derived from discovered skills and prompt templates.
	SlashResolver *SlashResolver

	// Clock supplies JavaScript Date.now-compatible milliseconds for message
	// and runtime timestamps (agent loop and session runtime). Defaults to the
	// wall clock; embedders and deterministic tests inject a fixed clock. It
	// does not reach a SessionManager passed in by the caller — create that
	// with session.WithClock to pin persisted entry timestamps too.
	Clock func() int64

	// BuiltinToolPrompts overrides the system-prompt contribution of named
	// built-in tools for this session (a present zero value suppresses the
	// contribution). The extension session bridge uses it to mirror upstream's
	// createCodingTools surface, which carries bash's contribution only.
	BuiltinToolPrompts map[string]ToolPromptContribution
}

type AgentSessionResult struct {
	// Session is the created agent session, ready for prompting.
	Session *AgentSession

	// ExtensionRegistry is the extension registry used (may be nil if no
	// extensions were configured).
	ExtensionRegistry *extensions.Registry

	// ModelFallbackMessage is set when no model can be selected or when a
	// continued session's saved model cannot be restored.
	ModelFallbackMessage string

	// Services contains the cwd-bound services used to build Session.
	Services *AgentSessionServices

	// Diagnostics contains non-fatal creation issues for the host to present.
	Diagnostics []AgentSessionRuntimeDiagnostic
}

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

type AgentSessionRuntimeDiagnostic struct {
	Type    string
	Message string
}

type AgentSessionRuntimeForkResult struct {
	Cancelled    bool
	SelectedText *string
}

type AgentSessionRuntimeSwitchOptions struct {
	CWDOverride                string
	WithSession                func(context.Context, extensions.ReplacedSessionContext) error
	ProjectTrustContextFactory func(string) extensions.ProjectTrustContext
}

type AgentSessionServices struct {
	CWD               string
	AgentDir          string
	SettingsManager   *config.SettingsManager
	ModelRegistry     *config.ModelRegistry
	Resources         *Resources
	ResourceLoader    ResourceLoader
	ExtensionRegistry *extensions.Registry
	Diagnostics       []AgentSessionRuntimeDiagnostic
}

type AgentSettledEvent struct{}

type AutoRetryEndEvent struct {
	Success    bool    `json:"success"`
	Attempt    int     `json:"attempt"`
	FinalError *string `json:"finalError,omitempty"`
}

type AutoRetryStartEvent struct {
	Attempt      int    `json:"attempt"`
	MaxAttempts  int    `json:"maxAttempts"`
	DelayMS      int64  `json:"delayMs"`
	ErrorMessage string `json:"errorMessage"`
}

type BashExecutionUpdateEvent struct {
	ID    *string `json:"id,omitempty"`
	Delta string  `json:"delta"`
}

type BuiltinSlashCommand struct {
	Name         string
	Description  string
	ArgumentHint string
}

type CLIModelResult struct {
	Model          *ai.Model
	ThinkingLevel  *ai.ModelThinkingLevel
	Warning, Error string
}

type CompactionEndEvent struct {
	Reason       string                         `json:"reason"`
	Result       *sessionstore.CompactionResult `json:"result,omitempty"`
	Aborted      bool                           `json:"aborted"`
	WillRetry    bool                           `json:"willRetry"`
	ErrorMessage *string                        `json:"errorMessage,omitempty"`
}

type CompactionStartEvent struct {
	Reason string `json:"reason"`
}

type ConfiguredPackage struct {
	Source        string `json:"source"`
	Scope         string `json:"scope"`
	Filtered      bool   `json:"filtered"`
	InstalledPath string `json:"installedPath,omitempty"`
}

type ContextFile struct {
	Path    string
	Content string
}

type CreateAgentSessionFromServicesOptions struct {
	Services          *AgentSessionServices
	SessionManager    *sessionstore.SessionManager
	SessionStartEvent *extensions.SessionStartEvent
	Model             *ai.Model
	ThinkingLevel     ai.ModelThinkingLevel
	ScopedModels      []ScopedModel
	Tools             []string
	ExcludeTools      []string
	NoTools           string
	CustomTools       []extensions.ToolDefinition
	ToolOptions       *tools.ToolsOptions
}

type CreateAgentSessionRuntimeFactory func(context.Context, AgentSessionOptions) (*AgentSessionResult, error)

type CreateAgentSessionServicesOptions struct {
	CWD                         string
	AgentDir                    string
	SettingsManager             *config.SettingsManager
	ModelRegistry               *config.ModelRegistry
	ResourceOptions             *ResourceOptions
	ResourceLoaderOptions       *DefaultResourceLoaderOptions
	ResourceLoaderReloadOptions *ResourceLoaderReloadOptions
	ExtensionRegistry           *extensions.Registry
	ExtensionFlagValues         map[string]any
}

type CustomMessage = extensions.CustomMessage

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

type DefaultResourceLoaderOptions struct {
	CWD             string
	AgentDir        string
	SettingsManager *config.SettingsManager

	AdditionalSkillPaths          []string
	AdditionalPromptTemplatePaths []string
	AdditionalThemePaths          []string
	PackageSkillPaths             []string
	PackagePromptTemplatePaths    []string
	PackageThemePaths             []ResourcePath
	ExtensionFactories            []extensions.Factory
	ExtensionRegistry             *extensions.Registry
	NoExtensions                  bool
	NoSkills                      bool
	NoPromptTemplates             bool
	NoThemes                      bool
	NoContextFiles                bool
	SystemPrompt                  *string
	AppendSystemPrompt            []string

	SkillsOverride             func(ResourceSkillsResult) ResourceSkillsResult
	PromptsOverride            func(ResourcePromptsResult) ResourcePromptsResult
	ThemesOverride             func(ResourceThemesResult) ResourceThemesResult
	AgentsFilesOverride        func(ResourceAgentsFilesResult) ResourceAgentsFilesResult
	SystemPromptOverride       func(*string) *string
	AppendSystemPromptOverride func([]string) []string
}

type EntryAppendedEvent struct {
	Entry sessionstore.SessionEntry `json:"entry"`
}

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

type ExtensionAgentSessionServiceOptions struct {
	// CWD is the fallback working directory when a create request carries none.
	CWD string
	// AgentDir is the fallback agent directory (auth.json, models.json,
	// skills). Defaults to DefaultAgentDir().
	AgentDir string
	// StreamFn overrides the streaming backend for every child session (used
	// by tests and embedders with their own provider dispatch). When nil,
	// sessions stream through the resolved model runtime's registry —
	// extension-registered providers included — or the default HTTP
	// dispatcher.
	StreamFn engine.StreamFn
	// Clock supplies Date.now-compatible milliseconds for message, runtime,
	// and persisted-session timestamps of every child session. Defaults to the
	// wall clock; deterministic replay tests inject a fixed clock.
	Clock func() int64
}

type FooterSnapshot struct {
	Display               engine.AgentDisplayState
	Tokens                SessionTokenTotals
	Cost                  float64
	ContextUsage          *harness.ContextUsage
	LatestCacheHitRate    float64
	HasLatestCacheHitRate bool
	AutoCompactEnabled    bool
}

type GitSource struct {
	Repo   string `json:"repo"`
	Host   string `json:"host"`
	Path   string `json:"path"`
	Ref    string `json:"ref,omitempty"`
	Pinned bool   `json:"pinned"`
}

type InputAction string

type InputResult struct {
	Action InputAction
	Text   string
}

type InteractiveModeSettings struct {
	InteractiveSettings
	AgentDir             string
	ProjectTrusted       bool
	GlobalThemePaths     []string
	ProjectThemePaths    []string
	ThemeSetting         string
	ImageAutoResize      bool
	BlockImages          bool
	EnableSkillCommands  bool
	Transport            ai.Transport
	HTTPIdleTimeoutMS    int64
	OutputPad            int
	ExternalEditor       string
	TreeFilterMode       string
	DefaultProjectTrust  string
	ShowTerminalProgress bool
	MermaidRenderingMode string
}

type InteractiveSettings struct {
	QuietStartup           bool
	DoubleEscapeAction     string
	ClearOnShrink          bool
	HideThinkingBlock      bool
	ShowCacheMissNotices   bool
	ShowImages             bool
	ImageWidthCells        int
	ShowHardwareCursor     bool
	EditorPaddingX         int
	AutocompleteMaxVisible int
	SteeringMode           engine.QueueMode
	FollowUpMode           engine.QueueMode
}

type LoadPromptTemplatesOptions struct {
	CWD             string
	AgentDir        string
	PromptPaths     []string
	IncludeDefaults bool
}

type LoadSkillsFromDirOptions struct {
	Dir    string
	Source string
}

type LoadSkillsOptions struct {
	CWD             string
	AgentDir        string
	SkillPaths      []string
	IncludeDefaults bool
}

type LoadSkillsResult struct {
	Skills      []Skill
	Diagnostics []ResourceDiagnostic
}

type MissingSessionCWDError struct {
	SessionFile string
	SessionCWD  string
	FallbackCWD string
}

type MissingSourceAction string

type ModelCycleResult struct {
	Model         ai.Model              `json:"model"`
	ThinkingLevel ai.ModelThinkingLevel `json:"thinkingLevel"`
	IsScoped      bool                  `json:"isScoped"`
}

type ModelDiagnostic struct {
	Type, Code, Message, Pattern string
}

type ModelMutationOptions struct{ Persist bool }

type NavigateTreeOptions struct {
	Summarize           bool
	CustomInstructions  string
	ReplaceInstructions bool
	Label               string
}

type NavigateTreeResult struct {
	EditorText   string
	Cancelled    bool
	Aborted      bool
	SummaryEntry *sessionstore.SessionEntry
}

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

type PackageManagerOptions struct {
	CWD      string
	AgentDir string
	Settings *config.SettingsManager
}

type PackageUpdate struct {
	Source      string `json:"source"`
	DisplayName string `json:"displayName"`
	Type        string `json:"type"`
	Scope       string `json:"scope"`
}

type PackageUpdateCheck struct {
	Installed int
	Updates   []PackageVersionUpdate
}

type PackageVersionUpdate struct {
	PackageUpdate
	CurrentVersion string
	LatestVersion  string
}

type ParsedModel struct {
	Model         *ai.Model
	ThinkingLevel *ai.ModelThinkingLevel
	Warning       string
}

type ParsedSkillBlock = exporthtml.ParsedSkillBlock

type PathMetadata struct {
	Source  string `json:"source"`
	Scope   string `json:"scope"`
	Origin  string `json:"origin"`
	BaseDir string `json:"baseDir,omitempty"`
}

type ProgressCallback func(ProgressEvent)

type ProgressEvent struct {
	Type    string `json:"type"`
	Action  string `json:"action"`
	Source  string `json:"source"`
	Message string `json:"message,omitempty"`
}

type PromptOptions struct {
	ExpandPromptTemplates *bool
	Images                []*ai.ImageContent
	StreamingBehavior     extensions.DeliveryMode
	Source                extensions.InputSource
	PreflightResult       func(bool)
}

type PromptSource struct {
	Path string
}

type PromptTemplate struct {
	Name         string
	Description  string
	ArgumentHint string
	Content      string
	SourceInfo   SourceInfo
	FilePath     string
}

type QueueUpdateEvent struct {
	Steering []string `json:"steering"`
	FollowUp []string `json:"followUp"`
}

type ResolveProjectTrustedOptions struct {
	CWD           string
	TrustStore    *config.ProjectTrustStore
	TrustOverride *bool
	// "ask" (default), "always", or "never".
	DefaultProjectTrust string
	// Optional extension runner whose project_trust handlers may decide.
	Runner       *extensions.Runner
	TrustContext extensions.Context
	HasUI        bool
	// SelectOption shows the trust prompt and returns the chosen label; the
	// second result is false when the user dismissed the prompt.
	SelectOption     func(title string, options []string) (string, bool)
	OnExtensionError func(message string)
}

type ResolvedPaths struct {
	Extensions []ResolvedResource `json:"extensions"`
	Skills     []ResolvedResource `json:"skills"`
	Prompts    []ResolvedResource `json:"prompts"`
	Themes     []ResolvedResource `json:"themes"`
}

type ResolvedResource struct {
	Path     string       `json:"path"`
	Enabled  bool         `json:"enabled"`
	Metadata PathMetadata `json:"metadata"`
}

type ResourceAgentsFilesResult struct {
	AgentsFiles []ContextFile
}

type ResourceCollision struct {
	ResourceType string
	Name         string
	WinnerPath   string
	LoserPath    string
}

type ResourceDiagnostic struct {
	Type      string
	Message   string
	Path      string
	Collision *ResourceCollision
}

type ResourceExtensionPaths struct {
	SkillPaths  []ResourcePath
	PromptPaths []ResourcePath
	ThemePaths  []ResourcePath
}

type ResourceLoader interface {
	GetExtensions() *extensions.Registry
	GetSkills() ResourceSkillsResult
	GetPrompts() ResourcePromptsResult
	GetThemes() ResourceThemesResult
	GetAgentsFiles() ResourceAgentsFilesResult
	GetSystemPrompt() *string
	GetSystemPromptSource() *PromptSource
	GetAppendSystemPrompt() []string
	GetAppendSystemPromptSources() []PromptSource
	ExtendResources(ResourceExtensionPaths)
	Reload(context.Context, *ResourceLoaderReloadOptions) error
}

type ResourceLoaderReloadOptions struct {
	ResolveProjectTrust func(context.Context, *extensions.Registry) (bool, error)
}

type ResourceOptions struct {
	CWD               string
	AgentDir          string
	ProjectTrusted    *bool
	NoContextFiles    bool
	NoSkills          bool
	NoPromptTemplates bool
	SystemPrompt      *string
	// Nil means discover APPEND_SYSTEM.md; a non-nil empty slice disables discovery.
	AppendSystemPrompt         []string
	SkillPaths                 []string
	PromptTemplatePaths        []string
	GlobalSkillPaths           []string
	ProjectSkillPaths          []string
	GlobalPromptTemplatePaths  []string
	ProjectPromptTemplatePaths []string
	PackageSkillPaths          []string
	PackagePromptTemplatePaths []string
	SkillPathMetadata          map[string]PathMetadata
	PromptPathMetadata         map[string]PathMetadata
}

type ResourcePath struct {
	Path     string
	Metadata PathMetadata
}

type ResourcePromptsResult struct {
	Prompts     []PromptTemplate
	Diagnostics []ResourceDiagnostic
}

type ResourceSkillsResult struct {
	Skills      []Skill
	Diagnostics []ResourceDiagnostic
}

type ResourceThemesResult struct {
	Themes      []*modetheme.Theme
	Diagnostics []ResourceDiagnostic
}

type Resources struct {
	ContextFiles              []ContextFile
	SystemPrompt              *string
	SystemPromptSource        *PromptSource
	AppendSystemPrompt        []string
	AppendSystemPromptSources []PromptSource
	Skills                    []Skill
	PromptTemplates           []PromptTemplate
	Diagnostics               []ResourceDiagnostic
	// contains filtered or unexported fields
}

type ScopedModel struct {
	Model         ai.Model
	ThinkingLevel *ai.ModelThinkingLevel
}

type SendCustomMessageOptions = extensions.SendMessageOptions

type SendUserMessageOptions = extensions.SendUserMessageOptions

type SessionAgentEndEvent struct {
	Messages  engine.AgentMessages `json:"messages"`
	WillRetry bool                 `json:"willRetry"`
}

type SessionEventType string

type SessionImportFileNotFoundError struct {
	FilePath string
}

type SessionInfoChangedEvent struct {
	Name *string `json:"name,omitempty"`
}

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

type SessionRuntimeConfig struct {
	Agent                  *engine.Agent
	SessionManager         *sessionstore.SessionManager
	Settings               *config.SettingsManager
	StreamFn               engine.StreamFn
	GetAPIKey              engine.GetAPIKeyFunc
	GetRequestAuth         engine.GetRequestAuthFunc
	GetModelHeaders        engine.GetModelHeadersFunc
	AvailableModels        func() []ai.Model
	ScopedModels           []ScopedModel
	Complete               harness.CompleteFunc
	Sleep                  func(context.Context, time.Duration) error
	Clock                  func() int64
	SlashResolver          *SlashResolver
	ExtensionRegistry      *extensions.Registry
	ExtensionMode          extensions.Mode
	ExtensionUI            extensions.UI
	ExtensionErrorHandler  func(extensions.ExtensionError)
	ModelRegistry          extensions.ModelRegistry
	RegisterProvider       func(extensions.Provider) error
	RegisterProviderConfig func(string, extensions.ProviderConfig) error
	UnregisterProvider     func(string) error
	BaseTools              []engine.AgentTool
	InitialActiveToolNames []string
	AllowedToolNames       *[]string
	ExcludedToolNames      []string
	RebuildBaseTools       func() ([]engine.AgentTool, error)
	SystemPromptOptions    *SystemPromptOptions
	BuiltinToolPrompts     map[string]ToolPromptContribution
	ResourceLoader         ResourceLoader
	SessionStartEvent      *extensions.SessionStartEvent
	DeferExtensionStart    bool
	SessionStart           *extensions.SessionStartEvent
	DeferSessionStart      bool
}

type SessionStats struct {
	SessionFile       string                `json:"sessionFile,omitempty"`
	SessionID         string                `json:"sessionId"`
	UserMessages      int                   `json:"userMessages"`
	AssistantMessages int                   `json:"assistantMessages"`
	ToolCalls         int                   `json:"toolCalls"`
	ToolResults       int                   `json:"toolResults"`
	TotalMessages     int                   `json:"totalMessages"`
	Tokens            SessionTokenTotals    `json:"tokens"`
	Cost              float64               `json:"cost"`
	ContextUsage      *harness.ContextUsage `json:"contextUsage,omitempty"`
}

type SessionTokenTotals struct {
	Input      int64 `json:"input"`
	Output     int64 `json:"output"`
	CacheRead  int64 `json:"cacheRead"`
	CacheWrite int64 `json:"cacheWrite"`
	Total      int64 `json:"total"`
}

type Skill struct {
	Name                   string
	Description            string
	Content                string
	FilePath               string
	BaseDir                string
	AllowedTools           string
	SourceInfo             SourceInfo
	DisableModelInvocation bool
}

type SlashCommandInfo struct {
	Name        string             `json:"name"`
	Description string             `json:"description,omitempty"`
	Source      SlashCommandSource `json:"source"`
	SourceInfo  SourceInfo         `json:"sourceInfo"`
}

type SlashCommandSource string

type SlashResolver struct {
	Skills            []Skill
	PromptTemplates   []PromptTemplate
	ExtensionCommands []SlashCommandInfo
	ExecuteExtension  func(name, args string) (bool, error)
	InterceptInput    func(text string) (InputResult, error)
	OnError           func(error)
}

type SourceInfo struct {
	Path    string `json:"path"`
	Source  string `json:"source"`
	Scope   string `json:"scope"`
	Origin  string `json:"origin"`
	BaseDir string `json:"baseDir,omitempty"`
}

type SummarizationRetryAttemptStartEvent struct {
	Source string `json:"source"`
	Reason string `json:"reason,omitempty"`
}

type SummarizationRetryFinishedEvent struct{}

type SummarizationRetryScheduledEvent struct {
	Attempt      int    `json:"attempt"`
	MaxAttempts  int    `json:"maxAttempts"`
	DelayMS      int64  `json:"delayMs"`
	ErrorMessage string `json:"errorMessage"`
}

type SystemPromptOptions struct {
	CustomPrompt       *string
	SelectedTools      []string
	ToolSnippets       map[string]string
	PromptGuidelines   []string
	AppendSystemPrompt *string
	CWD                string
	ContextFiles       []ContextFile
	Skills             []Skill
	PackageDir         string
}

type ThinkingLevelChangedEvent struct {
	Level ai.ModelThinkingLevel `json:"level"`
}

type ToolPromptContribution struct {
	Snippet    string
	Guidelines []string
}

type UsageCostBreakdownEntry struct {
	Key    string  `json:"key"`
	Cost   float64 `json:"cost"`
	Tokens int64   `json:"tokens"`
}