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
	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 (25)

	// MCP servers
	MCPClients []*mcp.Client

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

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"`
	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"`

	OutputSchema   map[string]any `yaml:"output_schema,omitempty"`
	NumHistoryRuns int            `yaml:"num_history_runs,omitempty"`
	Stream         bool           `yaml:"stream,omitempty"`
	Context        ContextYAML    `yaml:"context,omitempty"`

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

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

	// 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 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"`
}

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 ReasoningStrategy int

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 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
}

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