agent

type AgentDefinition struct {
	// Name is the unique identifier the LLM passes to the subagent tool.
	// Must be non-empty and globally unique after merging — MergeAgents
	// resolves name collisions by source precedence (user > project > builtin).
	Name string

	// Description is shown to the LLM in the subagent tool's schema enum
	// description. Treat it like a docstring: it tells the model WHEN to
	// invoke this agent, not what the agent does internally.
	Description string

	// SystemPrompt is the agent's system prompt. For built-ins it is a Go
	// string literal; for file-loaded agents it is the markdown body that
	// follows the frontmatter.
	SystemPrompt string

	// Tools is an allow-list of tool names. nil or {"*"} means "everything
	// the filter rules allow"; otherwise the listed names are intersected
	// with the filter output. Used by file-loaded agents to scope the
	// surface further than the global filter does.
	Tools []string

	// DisallowedTools is a per-agent deny-list, applied AFTER the global
	// rules. Mapped to FilterOpts.ExtraDisallowed at BuildConfig time.
	DisallowedTools []string

	// Model is "inherit" (use the parent's model), an explicit model name,
	// or empty (defaults to inherit).
	Model string

	// MaxTurns caps the agent's loop. Zero means use the subagent default.
	MaxTurns int

	// Background, when true, marks the agent as one that should run async
	// by default. The subagent tool can still override this per call via
	// its `background` parameter.
	Background bool

	// Provenance — set by the loader, read by tooling that wants to point
	// the user at a definition's origin (`/agents show explore` etc.).
	Source   AgentSource
	BaseDir  string // directory the agent was loaded from, or "builtin"
	Filename string // file path within BaseDir, or "" for built-ins
}

type AgentSource string

type BuildDeps struct {
	// Cwd is the workspace root. Used by sub-agent prompts and by the
	// per-agent tool pool when constructing scoped read/write/edit
	// instances.
	Cwd string

	// MainTools is the parent agent's tool list AS HANDED TO buildSubAgentTool
	// — that is, before the subagent and Skill tools are appended. Every
	// AgentDefinition gets this list re-pooled into independent instances
	// inside BuildConfig (see BuildToolPool's contract).
	MainTools []agentcore.Tool

	// DefaultModel is the parent agent's chat model, used when the
	// AgentDefinition either omits Model or sets it to "inherit".
	DefaultModel agentcore.ChatModel

	// ContextWindow is the parent's context window size, threaded to the
	// per-agent ContextManager so summary thresholds align with the model
	// in use.
	ContextWindow int

	// ResolveModel maps an explicit model name from AgentDefinition.Model
	// to a ChatModel. May be nil when the build pipeline doesn't support
	// per-agent model override; in that case any explicit Model that
	// isn't "inherit" produces an error from BuildConfig.
	ResolveModel func(name string) (agentcore.ChatModel, error)
}

type CacheStats struct {
	Input       int
	ReadTokens  int
	WriteTokens int
	HitRate     float64
	SavedUSD    float64
}

type CompactionKind string

type CompactionResult struct {
	Changed        bool
	TokensBefore   int
	TokensAfter    int
	Reason         string
	Strategy       string
	CompactedCount int
	KeptCount      int
	SplitTurn      bool
}

type CompactionSnapshot struct {
	Kind           CompactionKind
	Strategy       string
	Reason         string
	Changed        bool
	TokensBefore   int
	TokensAfter    int
	CompactedCount int
	KeptCount      int
	SplitTurn      bool
	Timestamp      time.Time
}

type ContextBreakdown struct {
	UserText      int
	AssistantText int
	ToolCalls     int
	ToolResults   int
	Summaries     int
	Images        int
	Total         int
	ContextWindow int

	// TopTools lists the heaviest tools by total (call + result) tokens.
	TopTools []ToolTokenUsage
}

type ContextSuggestion struct {
	Severity string // "warning" or "info"
	Message  string
	Savings  int // estimated token savings, 0 if unknown
}

type ErrorSnapshot struct {
	Category  diag.Category
	Message   string
	Detail    string
	Timestamp time.Time
}

type FilterOpts struct {
	// IsBuiltIn is true when the agent is defined in code, false when loaded
	// from a user-controlled source (.codebot/agents/, plugins).
	IsBuiltIn bool

	// IsAsync is true for background-mode runs. Async agents cannot prompt
	// the user, so they are restricted to the asyncAgentAllowed list.
	IsAsync bool

	// AllowMCP controls whether MCP tools (mcp__*) pass through. Defaults
	// false — call sites that want MCP must opt in.
	AllowMCP bool

	// ExtraDisallowed is a per-agent denylist applied on top of the global
	// rules. Used by built-in agents to scope themselves further (e.g. the
	// explore agent excludes write/edit/bash to stay read-only).
	ExtraDisallowed []string
}

type ModelFactory func(prov, model, apiKey, baseURL string) (agentcore.ChatModel, error)

type PlanModeSignal struct {
	Active        bool
	PlanFilePath  string
	JustCancelled bool
}

type ReminderSnapshot struct {
	Kind      RuntimeReminderKind
	Mode      string
	Timestamp time.Time
}

type RuntimeMetricsSnapshot struct {
	ReminderTotal         int
	ReminderByKind        map[RuntimeReminderKind]int
	CompactionTotal       int
	CompactionChanged     int
	CompactionSaved       int
	CompactionByKind      map[CompactionKind]int
	CompactionSavedByKind map[CompactionKind]int
	ErrorTotal            int
	ErrorByCategory       map[diag.Category]int
}

type RuntimeReminderKind string

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

type SessionConfig struct {
	Agent          *agentcore.Agent
	ContextManager agentcore.ContextManager
	Store          *storage.Store
	Manager        *storage.Manager
	Registry       *provider.ModelRegistry
	Settings       config.Resolved
	Cwd            string
	TaskStore      *storage.TaskStore
	// CreateModel allows tests/integrations to override model construction.
	// Defaults to provider.CreateModel when nil.
	CreateModel ModelFactory
	// LazyPersist buffers user messages and flushes them only when
	// an assistant response arrives. Disabled by default for safety.
	LazyPersist bool
	// ChatModel is the active ChatModel reference.
	ChatModel agentcore.ChatModel
	// HookRunner fires lifecycle hooks (notification, etc.). Nil when no hooks configured.
	HookRunner *hooks.Runner

	// Tools is the full set of tools registered with the agent.
	// Used by ToolsByName / RestoreAllTools for plan mode filtering.
	Tools []agentcore.Tool
	// ContextFiles holds loaded context files for dynamic system prompt rebuilding.
	// When tools change the prompt is regenerated from these inputs.
	ContextFiles config.ContextFiles
	// Skills holds loaded skills for system prompt injection and /skill: commands.
	Skills []skill.Spec
	// SkillCatalog provides indexed skill lookup and reload support.
	SkillCatalog *skill.Catalog
	// SkillUsage persists cross-session usage statistics for prompt ordering.
	SkillUsage *skill.UsageTracker
	// DeferredToolsPreamble is injected as the first user message (once).
	DeferredToolsPreamble string
	// Reminders are <system-reminder> fragments prepended to each user message.
	Reminders []string
	// PreambleInjected indicates the preamble was already in conversation history (resume).
	PreambleInjected bool
	// SkillAllowsSetter updates temporary tool allows for the active skill.
	SkillAllowsSetter func([]string)

	// FileReadState records read timestamps consumed by write/edit Validators.
	// Held on the Session so Clear / Reset / SwitchSession can drop stale
	// stamps — otherwise the LLM may write based on stamps from a read it
	// no longer has in its conversation history.
	FileReadState *agenttools.FileReadState

	// FrozenIdentity / FrozenInstructions are the process-stable parts of the
	// system prompt (block 1 + block 2). Computed once at assembly time and
	// reused on every rebuild — never recomputed during the session.
	// See config.BuildFrozenSystemParts.
	FrozenIdentity     string
	FrozenInstructions string
	// InitialMCPOverlay seeds the mcp overlay when the assembly already knows
	// the MCP instructions (e.g. MCP managers that connect synchronously).
	// Written directly into the overlay store without triggering a rebuild.
	InitialMCPOverlay string
}

type SessionEvent struct {
	Type       SessionEventType
	AgentEvent *agentcore.Event

	// Session-level fields (populated based on Type)
	ModelName    string
	Provider     string
	Level        agentcore.ThinkingLevel
	SessionID    string
	Error        error
	Reminder     string
	ReminderKind RuntimeReminderKind

	// Retry fields (populated for SEAutoRetryStart / SEAutoRetryEnd)
	RetryAttempt int
	RetryMax     int
	RetryDelay   time.Duration
	RetrySuccess bool

	// Compaction reason: "overflow" or "threshold"
	CompactionReason   string
	CompactionKind     CompactionKind
	CompactionStrategy string
	CompactionChanged  bool
	TokensBefore       int
	TokensAfter        int
	CompactedCount     int
	KeptCount          int
	SplitTurn          bool
}

type SessionEventType string

type SessionMemory struct {
	Content   string
	UpdatedAt time.Time
}

type ToolCallSnapshot struct {
	Tool      string
	ArgsHash  string
	Success   bool
	Timestamp time.Time
}

type ToolTokenUsage struct {
	Name         string
	CallTokens   int
	ResultTokens int
	Total        int
}

type TurnOutcomeSnapshot struct {
	AssistantResponded bool
	ReadOnlyToolCalls  int
	WriteLikeToolCalls int
	TaskMutations      int
	CodeEditToolCalls  int
}