agent

type Agent struct {
	ID          string
	Name        string
	Description string
	UserID      string

	// Core components
	Model   model.Provider
	Tools   *tool.Registry
	Skills  *skill.Registry
	Memory  *memory.Store
	Storage storage.Storage
	Graph   *graph.CompiledGraph

	// Enhancements
	Knowledge      knowledge.Knowledge
	MemoryManager  *memory.Manager
	Hooks          hooks.Chain
	Guardrails     *guardrails.Engine
	Broker         *stream.Broker          // SSE broker for real-time event streaming
	Tracer         *chronostrace.Collector // execution tracer for span-based observability
	SessionState   map[string]any          // persistent cross-turn state
	OutputSchema   map[string]any          // JSON Schema for structured output
	NumHistoryRuns int                     // number of past runs to inject into context
	ContextCfg     ContextConfig           // context window management and summarization
	MemoryRecall   RecallConfig            // automatic semantic long-term recall policy

	// ContextPinsFn supplies dynamic pinned context evaluated fresh on every
	// turn. Like ContextConfig.PinnedMessages, its output is injected as system
	// context and is never summarized or evicted by compaction — but because it
	// runs per turn it can reflect live state (e.g. the current task plan). It is
	// the decoupled seam the deep-agent preset (WC-A-005) uses to keep the active
	// plan pinned without the SDK depending on the planning toolkit.
	ContextPinsFn func(ctx context.Context) []model.Message

	// System prompt and instructions
	SystemPrompt   string
	Instructions   []string
	InstructionsFn func(ctx context.Context, state map[string]any) []string
	Examples       []Example

	// Reasoning and iteration control
	Reasoning        ReasoningStrategy
	ReasoningConfig  model.ReasoningConfig // provider-native reasoning/thinking settings
	ReasoningModel   model.Provider        // separate, more capable model for reasoning steps
	Debug            bool                  // when set, logs detailed execution info
	MaxIterations    int                   // max tool-calling loop iterations; 0 = default (90)
	Stream           bool                  // preferred CLI response mode
	StreamConfigured bool                  // distinguishes an explicit YAML value from the default

	// MCP servers
	MCPClients []*mcp.Client

	// Multi-agent
	SubAgents              []*Agent
	MaxConcurrentSubAgents int
	Capabilities           []string // advertised capabilities for the protocol bus
	// contains filtered or unexported fields
}

type AgentConfig struct {
	ID          string `yaml:"id"`
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`
	UserID      string `yaml:"user_id,omitempty"`

	Model        ModelConfig   `yaml:"model"`
	Storage      StorageConfig `yaml:"storage,omitempty"`
	System       string        `yaml:"system_prompt,omitempty"`
	SystemLegacy string        `yaml:"system,omitempty"` // backward-compatible alias
	Instructions []string      `yaml:"instructions,omitempty"`
	Tools        []ToolConfig  `yaml:"tools,omitempty"`
	Capabilities []string      `yaml:"capabilities,omitempty"`

	// MCPServers lists Model Context Protocol servers whose tools are
	// registered with the agent when ConnectMCP is called after Build.
	MCPServers []mcp.ServerConfig `yaml:"mcp_servers,omitempty"`

	// Skills lists reusable capability bundles this agent advertises. Each
	// skill is registered in the agent's skill.Registry, and its Description
	// (plus any Markdown body loaded from ManifestPath) is appended to the
	// system prompt at Build time so the model knows the skill is available.
	Skills []SkillConfig `yaml:"skills,omitempty"`

	// UseSkills references skills by name from the file-level catalog loaded
	// from FileConfig.SkillsDir (SKILL.md files). Referencing an unknown name
	// aborts the build with a clear error.
	UseSkills []string `yaml:"use_skills,omitempty"`

	OutputSchema     map[string]any      `yaml:"output_schema,omitempty"`
	NumHistoryRuns   int                 `yaml:"num_history_runs,omitempty"`
	Stream           bool                `yaml:"stream,omitempty"`
	StreamConfigured bool                `yaml:"-"`
	Debug            bool                `yaml:"debug,omitempty"`
	Tracing          bool                `yaml:"tracing,omitempty"`
	PermissionMode   tool.PermissionMode `yaml:"permission_mode,omitempty"`
	Reasoning        ReasoningYAML       `yaml:"reasoning,omitempty"`
	Context          ContextYAML         `yaml:"context,omitempty"`

	// Team nesting: an agent config can reference sub-agents by ID
	SubAgents []string `yaml:"sub_agents,omitempty"`

	// Graph declares a durable multi-node graph for this agent (see
	// graphbuild.go). When set, BuildAgent/BuildAll compile it and attach it
	// to the built Agent exactly as Agent.WithGraph would, so Agent.Run
	// automatically creates a session and checkpoints through it — no
	// additional wiring required.
	Graph *GraphConfig `yaml:"graph,omitempty"`

	// Durable opts this agent's compiled graph into being registered with
	// ChronosOS by `chronos serve`/`chronos deploy` (a dashboard.GraphRegistry
	// entry keyed by ID), so its runs are visible/resumable/time-travelable
	// from the dashboard. It does not itself change Agent.Run's behavior —
	// any agent with a Graph already runs durably once Storage is configured;
	// this flag only controls server-side exposure. Requires Graph to be set.
	Durable bool `yaml:"durable,omitempty"`
}

type BuildAllOptions struct {
	// DefaultStorage replaces construction for agents with an empty storage
	// configuration or the same effective configuration as FileConfig.Defaults.
	// Distinct custom configurations and explicit none/memory backends retain
	// their configured behavior. The caller initializes, migrates and closes
	// this shared store; the builder never migrates or closes it.
	DefaultStorage storage.Storage `json:"-"`
}

type BuildOption func(*buildOptions)

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

type ChatSession struct {
	ID       string          `json:"id"`
	AgentID  string          `json:"agent_id"`
	Messages []model.Message `json:"messages"`
	Summary  string          `json:"summary"`
	// contains filtered or unexported fields
}

type ContextConfig struct {
	MaxContextTokens        int     `json:"max_context_tokens" yaml:"max_tokens"`                 // override model default; 0 = use model default
	SummarizeThreshold      float64 `json:"summarize_threshold" yaml:"summarize_threshold"`       // fraction of context window to trigger summarization (default 0.8)
	PreserveRecentTurns     int     `json:"preserve_recent_turns" yaml:"preserve_recent_turns"`   // number of recent user/assistant pairs to keep (default 5)
	MaxToolResultTokens     int     `json:"max_tool_result_tokens" yaml:"max_tool_result_tokens"` // max tokens for tool result before eviction (default 20000)
	MaxToolCallsFromHistory int     `json:"max_tool_calls_from_history" yaml:"max_tool_calls"`    // max tool call pairs to keep in history

	// PersistToolRounds makes session chat append each completed tool round
	// (assistant tool calls plus every result) to the session ledger as it
	// happens, and compact the session inside a long turn when it nears the
	// context window. A turn that errors or pauses mid-loop then leaves its
	// working context in the session for the next turn. Off by default.
	PersistToolRounds bool `json:"persist_tool_rounds" yaml:"persist_tool_rounds"`

	// PinnedMessages are injected as system context on every turn and are never
	// summarized or evicted by compaction. Use them for content that must always
	// be visible to the model (policies, invariants, a fixed brief). Set
	// programmatically via the builder; there is no YAML surface for structured
	// messages, so no yaml tag is advertised.
	PinnedMessages []model.Message `json:"pinned_messages,omitempty"`
}

type ContextYAML struct {
	MaxTokens           int     `yaml:"max_tokens,omitempty"`
	SummarizeThreshold  float64 `yaml:"summarize_threshold,omitempty"`
	PreserveRecentTurns int     `yaml:"preserve_recent_turns,omitempty"`
}

type DeploymentConfig struct {
	Name    string        `yaml:"name,omitempty"`
	Sandbox SandboxConfig `yaml:"sandbox,omitempty"`
}

type EdgeConfig struct {
	From        string            `yaml:"from"`
	To          string            `yaml:"to,omitempty"`
	Conditional bool              `yaml:"conditional,omitempty"`
	RouteKey    string            `yaml:"route_key,omitempty"`
	Routes      map[string]string `yaml:"routes,omitempty"`
	Default     string            `yaml:"default,omitempty"`
}

type EvictionResult struct {
	StorageKey string `json:"storage_key"`
	Preview    string `json:"preview"`
	FullSize   int    `json:"full_size"`
}

type Example struct {
	Input  string `json:"input"`
	Output string `json:"output"`
}

type FileConfig struct {
	Agents []AgentConfig `yaml:"agents"`
	Teams  []TeamConfig  `yaml:"teams,omitempty"`

	// Defaults applied to all agents unless overridden
	Defaults *AgentConfig `yaml:"defaults,omitempty"`

	// SkillsDir is a filesystem path (absolute, or relative to the YAML file's
	// directory) that BuildAll walks at load time for SKILL.md files. Every
	// discovered skill forms a catalog keyed by name; agents opt into catalog
	// skills by listing their names under `use_skills:`.
	SkillsDir string `yaml:"skills_dir,omitempty"`

	// Deployment holds `chronos deploy`-only fields. Ignored by other commands.
	Deployment *DeploymentConfig `yaml:"deployment,omitempty"`

	// Deprecated: top-level `name:` — use `deployment.name` instead. Accepted
	// for one release; NormalizeFileConfig promotes it into Deployment and
	// prints a deprecation warning.
	LegacyName string `yaml:"name,omitempty"`
	// Deprecated: top-level `sandbox:` — use `deployment.sandbox` instead.
	LegacySandbox *SandboxConfig `yaml:"sandbox,omitempty"`
}

type GraphConfig struct {
	Entry  string       `yaml:"entry"`
	Finish string       `yaml:"finish,omitempty"`
	Nodes  []NodeConfig `yaml:"nodes"`
	Edges  []EdgeConfig `yaml:"edges,omitempty"`
}

type ModelConfig struct {
	Provider   string `yaml:"provider"`          // openai, anthropic, gemini, mistral, ollama, azure, groq, together, deepseek, openrouter, fireworks, perplexity, anyscale, compatible
	Model      string `yaml:"model,omitempty"`   // model ID, e.g. "gpt-4o", "claude-sonnet-4-6"
	APIKey     string `yaml:"api_key,omitempty"` // literal or ${ENV_VAR}
	BaseURL    string `yaml:"base_url,omitempty"`
	OrgID      string `yaml:"org_id,omitempty"`
	TimeoutSec int    `yaml:"timeout_sec,omitempty"`

	// Azure-specific
	Endpoint   string `yaml:"endpoint,omitempty"`
	Deployment string `yaml:"deployment,omitempty"`
	APIVersion string `yaml:"api_version,omitempty"`
}

type NodeConfig struct {
	ID        string         `yaml:"id"`
	Type      string         `yaml:"type"`
	Interrupt bool           `yaml:"interrupt,omitempty"`
	Prompt    string         `yaml:"prompt,omitempty"`     // model
	Tool      string         `yaml:"tool,omitempty"`       // tool
	Agent     string         `yaml:"agent,omitempty"`      // subagent
	InputKey  string         `yaml:"input_key,omitempty"`  // tool, subagent
	OutputKey string         `yaml:"output_key,omitempty"` // model, tool, subagent
	Set       map[string]any `yaml:"set,omitempty"`        // passthrough
}

type ReasoningStrategy int

type ReasoningYAML struct {
	Strategy     string `yaml:"strategy,omitempty"` // none, cot, reflection
	Native       bool   `yaml:"native,omitempty"`
	Effort       string `yaml:"effort,omitempty"` // low, medium, high
	BudgetTokens int    `yaml:"budget_tokens,omitempty"`
	Summary      bool   `yaml:"summary,omitempty"`
}

type RecallConfig struct {
	Disabled       bool    `json:"disabled" yaml:"disabled"`               // opt out of semantic recall
	TopK           int     `json:"top_k" yaml:"top_k"`                     // memories to recall per turn; 0 = default 5
	ScoreThreshold float32 `json:"score_threshold" yaml:"score_threshold"` // drop recalled memories below this score; 0 = keep all
}

type RunIdentity struct {
	TenantID           string
	RepositoryID       string
	DeliveryID         string
	TaskID             string
	NodeID             string
	AttemptID          string
	GoalRevision       string
	ArtifactSnapshot   string
	PolicyRevision     string
	RoleID             string
	SessionID          string
	InvocationID       string
	ParentInvocationID string
}

type SandboxConfig struct {
	Backend string `yaml:"backend,omitempty"` // process, container, k8s
	WorkDir string `yaml:"work_dir,omitempty"`
	Image   string `yaml:"image,omitempty"`
	Network string `yaml:"network,omitempty"`
	Timeout string `yaml:"timeout,omitempty"` // e.g. "5m", "30s"
}

type SkillConfig struct {
	Name         string         `yaml:"name"`
	Version      string         `yaml:"version,omitempty"`
	Description  string         `yaml:"description,omitempty"`
	Author       string         `yaml:"author,omitempty"`
	Tags         []string       `yaml:"tags,omitempty"`
	Tools        []string       `yaml:"tools,omitempty"`
	Manifest     map[string]any `yaml:"manifest,omitempty"`
	ManifestPath string         `yaml:"manifest_path,omitempty"` // Markdown file appended to system prompt
}

type StorageConfig struct {
	Backend string `yaml:"backend,omitempty"` // sqlite, postgres (default: sqlite)
	DSN     string `yaml:"dsn,omitempty"`     // connection string or file path

	// Connection-pool tuning for the SQL backends (sqlite, postgres). A zero
	// value leaves the adapter's built-in default in place.
	MaxOpenConns       int `yaml:"max_open_conns,omitempty"`
	MaxIdleConns       int `yaml:"max_idle_conns,omitempty"`
	ConnMaxLifetimeSec int `yaml:"conn_max_lifetime_sec,omitempty"`
}

type TeamConfig struct {
	ID             string   `yaml:"id"`
	Name           string   `yaml:"name"`
	Strategy       string   `yaml:"strategy"`                  // sequential, parallel, router, coordinator, swarm, hierarchy
	Agents         []string `yaml:"agents"`                    // agent IDs (order matters for sequential)
	Coordinator    string   `yaml:"coordinator,omitempty"`     // agent ID: coordinator (coordinator strategy) or root supervisor (hierarchy)
	MaxConcurrency int      `yaml:"max_concurrency,omitempty"` // for parallel strategy
	MaxIterations  int      `yaml:"max_iterations,omitempty"`  // for coordinator strategy
	ErrorStrategy  string   `yaml:"error_strategy,omitempty"`  // fail_fast, collect, best_effort

	// Router selects how the router strategy picks an agent: "model" (default —
	// an LLM reasons over agent descriptions) or "capability" (a zero-LLM
	// heuristic that matches advertised capabilities against state keys).
	Router string `yaml:"router,omitempty"`

	// RouterModel optionally overrides which model drives model-based routing.
	// When its Provider is empty, the router reuses the first member agent's
	// model — set this to route with a cheaper/faster model than the workers.
	RouterModel ModelConfig `yaml:"router_model,omitempty"`

	// InitialAgent is the entry agent for the swarm strategy (defaults to the
	// first listed agent).
	InitialAgent string `yaml:"initial_agent,omitempty"`
	// MaxHandoffs caps peer-to-peer handoffs in the swarm strategy (0 = default).
	MaxHandoffs int `yaml:"max_handoffs,omitempty"`
}

type ToolConfig struct {
	Name                 string          `yaml:"name"`
	Description          string          `yaml:"description"`
	Parameters           map[string]any  `yaml:"parameters,omitempty"` // JSON Schema
	Permission           tool.Permission `yaml:"permission,omitempty"`
	RequiresConfirmation *bool           `yaml:"requires_confirmation,omitempty"`
	RequiresUserInput    *bool           `yaml:"requires_user_input,omitempty"`
}

type ToolHandlerFactory func(tc ToolConfig) (tool.Handler, error)

type ToolLoopAction struct {
	// Stop ends the loop before the next model call. The call returns a
	// response with StopReasonPaused and Message as its content.
	Stop    bool
	Message string
}

type ToolLoopController interface {
	AfterToolRound(ctx context.Context, round ToolRound) (ToolLoopAction, error)
}

type ToolRound struct {
	AgentID string
	// Iteration is the 1-based round number within the current chat call.
	Iteration int
	ToolCalls []model.ToolCall
	// Usage is the usage of the model call that requested ToolCalls.
	Usage model.Usage
}