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

	// Isolation selects the teammate's filesystem sandbox. Empty or "shared"
	// (the default) runs the teammate in the leader's cwd, sharing the working
	// tree. "worktree" gives it a private git worktree so its writes cannot
	// clobber a peer editing the same files — see team.Isolation. Honoured
	// only for teammate spawns in a git repo; a no-op elsewhere.
	Isolation string

	// 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 buildSubAgents
	// — 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)

	// WorkspaceFS is the file backend the per-agent read/write/edit pool
	// operates on. Threaded so sub-agents share the parent's backend (e.g.
	// editor buffers under ACP). Nil means the local filesystem.
	WorkspaceFS tools.WorkspaceFS

	// SessionID is the parent session's identity, used as the base of each
	// sub-agent's prompt-cache routing key (agentcore appends "#<seq>" per
	// spawn). Empty disables the routing hint; cache breakpoints still apply.
	SessionID string

	// Middlewares wrap each tool execution inside the sub-agent. A sub-agent
	// runs its own loop and does not inherit the parent's middleware stack, so
	// anything that must apply everywhere (output limiting) is threaded here.
	Middlewares []agentcore.ToolMiddleware
}

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, providerExtra map[string]any) (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
	// TelemetryTracer opens agent-run spans and tool spans when telemetry is enabled.
	TelemetryTracer *telemetry.Tracer
	// HookRunner fires lifecycle hooks (notification, etc.). Nil when no hooks configured.
	HookRunner *hooks.Runner
	// Snapshotter records workspace file checkpoints at turn boundaries and
	// powers /undo. Nil disables snapshotting (e.g. outside a git repo).
	Snapshotter Snapshotter

	// Tools is the full set of tools registered with the agent.
	// Used by ToolsByName / RestoreAllTools for plan mode filtering.
	Tools []agentcore.Tool
	// ContextFiles holds the workspace context rendered into system block 2.
	// Session.Reload re-reads it from disk and rebuilds that block; nothing
	// else in the session mutates it.
	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
	// ToolMicrocompact powers the idle cleanup that runs when the prompt cache
	// has expired. Nil disables it. Same strategy instance the ContextEngine
	// uses under token pressure — only the trigger differs.
	ToolMicrocompact *agentctx.ToolResultMicrocompactStrategy
	// SkillAllowsSetter updates temporary tool allows for the active skill.
	SkillAllowsSetter func([]string)

	// ToolOutputRoot is the project's session root. The session appends its own
	// id, so the path follows /new and /resume instead of freezing at boot.
	ToolOutputRoot 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 is system block 1's assembly-time value; a worktree
	// retarget recomputes it for the new root. FrozenInstructions is block 2's;
	// a Reload or retarget recomputes it from ContextFiles + Skills +
	// LocalTools. See config.BuildFrozenSystemParts.
	FrozenIdentity     string
	FrozenInstructions string
	// LocalTools is the session-stable local tool inventory as rendered into
	// block 2. Held so a reload can rebuild that block without re-deriving it
	// from the live tool set, which plan mode filters.
	LocalTools []config.ToolInfo
	// 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

	// InitialDynamic is the assembly-time dynamic block text (MCP tool list +
	// overlays). Stored on the session so teammate spawn can read the current
	// snapshot via DynamicSystemBlock() without re-computing. Updated when
	// the prompt rebuilds (overlay change / MCP refresh).
	InitialDynamic 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
	Goal         goal.State
	GoalPrevious goal.State

	// 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 Snapshotter interface {
	// Track records a checkpoint of the current workspace. changed is false
	// when nothing changed since the last checkpoint.
	Track() (changed bool, err error)
	// Undo reverts the workspace to the most recent checkpoint. ok is false
	// when there is nothing to undo; changed lists the affected paths.
	Undo() (changed []string, ok bool, err error)
	// Redo re-applies the most recently undone change. ok is false when there
	// is nothing to redo (no prior undo, or a new edit invalidated the branch).
	Redo() (changed []string, ok bool, err error)
	// DiffTop returns a numstat diff of what Undo would roll back, or "" when
	// there is nothing to undo.
	DiffTop() (string, error)
	// Rebind repoints the tracker at a session's persisted undo stack: it drops
	// the in-memory stack and loads whatever statePath holds. Called on session
	// switch/new so each session gets its own checkpoint history.
	Rebind(statePath string)
	// RebindWorkspace repoints the tracker at a different workspace (shadow
	// gitDir + workTree) and its sidecar, then reloads the persisted stack.
	// Called on worktree enter/exit, where the whole workspace moves — unlike
	// Rebind, which only swaps the sidecar for a same-cwd session switch.
	RebindWorkspace(gitDir, workTree, statePath string)
	// Close waits for any background snapshot maintenance to finish.
	Close()
}

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
}