agent

type AgentDefinition struct {
	// AgentType is the unique agent type identifier
	AgentType string `json:"agentType"`

	// WhenToUse is the description for when to use this agent
	WhenToUse string `json:"whenToUse"`

	// Source indicates where this agent comes from
	Source AgentSource `json:"source"`

	// BaseDir is the base directory (for user/project agents)
	BaseDir string `json:"baseDir,omitempty"`

	// Filename is the original filename (for user/project agents)
	Filename string `json:"filename,omitempty"`

	// Tools is the list of allowed tool patterns (glob patterns)
	// nil or ["*"] means all tools
	Tools []string `json:"tools,omitempty"`

	// DisallowedTools is the list of disallowed tool patterns
	DisallowedTools []string `json:"disallowedTools,omitempty"`

	// Skills is the list of skill names to preload
	Skills []string `json:"skills,omitempty"`

	// MCPservers is the list of MCP server names to connect
	McpServers []string `json:"mcpServers,omitempty"`

	// Model is the model to use (empty = default)
	Model string `json:"model,omitempty"`

	// Effort is the effort level (1-5)
	Effort int `json:"effort,omitempty"`

	// PermissionMode is the permission mode
	PermissionMode types.PermissionMode `json:"permissionMode,omitempty"`

	// MaxTurns is the maximum number of turns
	MaxTurns int `json:"maxTurns,omitempty"`

	// Memory is the memory scope
	Memory string `json:"memory,omitempty"`

	// Background indicates if the agent should run in background
	Background bool `json:"background,omitempty"`

	// Isolation is the isolation mode
	Isolation string `json:"isolation,omitempty"`

	// SystemPromptGetter is the function to get the system prompt
	GetSystemPrompt func() string `json:"-"`
}

type AgentEvent struct {
	// AgentID is the unique identifier for this agent instance
	AgentID string `json:"agentId"`

	// AgentType is the type of agent (general-purpose, explore, plan, verify)
	AgentType string `json:"agentType"`

	// EventType is the type of event
	EventType AgentEventType `json:"eventType"`

	// Timestamp when the event occurred
	Timestamp time.Time `json:"timestamp"`

	// Task is the original task description
	Task string `json:"task,omitempty"`

	// Progress data (for progress events)
	Progress *AgentProgress `json:"progress,omitempty"`

	// Result data (for completed/failed events)
	Result *RunResult `json:"result,omitempty"`

	// Error message (for failed events)
	Error string `json:"error,omitempty"`

	// Turn number (for turn_update events)
	Turn int `json:"turn,omitempty"`

	// Tool name (for tool_use events)
	ToolName string `json:"toolName,omitempty"`

	// Additional metadata
	Metadata map[string]any `json:"metadata,omitempty"`
}

type AgentEventListener func(event AgentEvent)

type AgentEventType string

type AgentProfile struct {
	// ID is a UUID — globally unique across all teams and roles.
	// Generated once at creation; never changes.
	ID string `json:"id"`

	// Nickname is the personal name displayed in the UI and injected into the
	// system prompt so the agent knows what it is called ("You are Maria…").
	Nickname string `json:"nickname"`

	// Role is a functional tag used by the dispatcher to route tasks
	// (e.g. "researcher", "engineer", "manager").
	// Multiple agents can share the same role across different teams.
	Role string `json:"role"`

	// TeamID groups agents into a named team. Empty means no team assigned.
	TeamID string `json:"team_id,omitempty"`

	// SystemPromptTemplate is the base persona injected at session start.
	// The placeholder {{.Nickname}} is replaced with the agent's Nickname at
	// runtime, and a preamble "You are {{.Nickname}}, …" is prepended automatically
	// if the template does not start with "You are".
	SystemPromptTemplate string `json:"system_prompt_template"`

	// Model is the preferred model identifier in "provider:model" format.
	// Empty string means use the global default.
	Model string `json:"model,omitempty"`

	// Skills lists skill file names to preload for this profile.
	Skills []string `json:"skills,omitempty"`

	// Metadata holds arbitrary extension fields.
	Metadata map[string]string `json:"metadata,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type AgentProgress struct {
	// CurrentTurn number
	CurrentTurn int `json:"currentTurn"`

	// MaxTurns limit
	MaxTurns int `json:"maxTurns"`

	// ToolUses so far
	ToolUses int `json:"toolUses"`

	// CurrentOutput so far
	Output string `json:"output"`

	// Percentage complete (estimated)
	PercentComplete float64 `json:"percentComplete"`
}

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

type AgentSource string

type AgentStatus string

type AsyncAgent struct {
	// Unique identifier
	ID string

	// Agent configuration
	Config *RunConfig

	// Nickname is the optional human-friendly name assigned at spawn time.
	// Mirrors Codex's agent_nickname in CollabAgentRef.
	Nickname string

	// Role is the optional role assigned at spawn time (e.g. "reviewer").
	// Mirrors Codex's agent_role in CollabAgentRef.
	Role string

	// SessionID is the engine session ID used by this agent's run. Set after
	// the run completes and exposes the session for resumption via resume_agent.
	SessionID types.SessionID

	// Current status
	Status AgentStatus

	// Context for cancellation
	Ctx    context.Context
	Cancel context.CancelFunc

	// Start time
	StartTime time.Time

	// End time
	EndTime time.Time

	// Current turn count
	CurrentTurn int

	// Current output so far
	CurrentOutput string

	// Tool uses count
	ToolUses int

	// Final result (when completed)
	Result *RunResult

	// Error if failed
	Error error
	// contains filtered or unexported fields
}

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

type BuiltInAgentDefinition struct {
	AgentType       string
	WhenToUse       string
	Tools           []string
	Source          AgentSource
	BaseDir         string
	Model           string
	GetSystemPrompt func() string
	MaxTurns        int
}

type ConversationMemory struct {
	Topic        string            `json:"topic"`
	Participants []string          `json:"participants"`
	KeyPoints    []string          `json:"keyPoints"`
	Questions    []string          `json:"questions"`
	Answers      []string          `json:"answers"`
	TaskProgress map[string]string `json:"taskProgress"`
}

type ErrorMemory struct {
	ErrorType          string            `json:"errorType"`
	ErrorPattern       string            `json:"errorPattern"`
	Frequency          int               `json:"frequency"`
	Solutions          []SolutionPattern `json:"solutions"`
	Context            string            `json:"context"`
	PreventiveMeasures []string          `json:"preventiveMeasures"`
}

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

type MemoryConfig struct {
	MaxEntries           int                   `json:"maxEntries"`
	DefaultTTL           time.Duration         `json:"defaultTTL"`
	LearningEnabled      bool                  `json:"learningEnabled"`
	ImportanceDecay      float64               `json:"importanceDecay"`
	MinImportance        float64               `json:"minImportance"`
	MaxImportance        float64               `json:"maxImportance"`
	EnableSemanticSearch bool                  `json:"enableSemanticSearch"`
	RetentionPolicy      MemoryRetentionPolicy `json:"retentionPolicy"`
}

type MemoryContext struct {
	SessionID    string   `json:"sessionId,omitempty"`
	Task         string   `json:"task,omitempty"`
	Tool         string   `json:"tool,omitempty"`
	Error        string   `json:"error,omitempty"`
	Solution     string   `json:"solution,omitempty"`
	RelatedFiles []string `json:"relatedFiles,omitempty"`
	Intent       string   `json:"intent,omitempty"`
}

type MemoryEntry struct {
	ID           string         `json:"id"`
	Type         MemoryType     `json:"type"`
	Content      string         `json:"content"`
	Context      *MemoryContext `json:"context"`
	Tags         []string       `json:"tags"`
	Importance   float64        `json:"importance"`
	Confidence   float64        `json:"confidence"`
	AccessCount  int            `json:"accessCount"`
	LastAccessed time.Time      `json:"lastAccessed"`
	CreatedAt    time.Time      `json:"createdAt"`
	ExpiresAt    *time.Time     `json:"expiresAt,omitempty"`
}

type MemoryQuery struct {
	Types         []MemoryType   `json:"types"`
	Content       string         `json:"content"`
	Tags          []string       `json:"tags"`
	Context       *MemoryContext `json:"context"`
	Limit         int            `json:"limit"`
	MinImportance float64        `json:"minImportance"`
	MinConfidence float64        `json:"minConfidence"`
	SessionID     string         `json:"sessionId"`
	Tool          string         `json:"tool"`
	TimeRange     *TimeRange     `json:"timeRange,omitempty"`
}

type MemoryRetentionPolicy struct {
	ToolUsageRetention    time.Duration `json:"toolUsageRetention"`
	ConversationRetention time.Duration `json:"conversationRetention"`
	ErrorRetention        time.Duration `json:"errorRetention"`
	ContextRetention      time.Duration `json:"contextRetention"`
	SuccessRetention      time.Duration `json:"successRetention"`
}

type MemorySearchResult struct {
	Entries       []MemoryEntry `json:"entries"`
	Total         int           `json:"total"`
	Query         MemoryQuery   `json:"query"`
	ExecutionTime time.Duration `json:"executionTime"`
}

type MemoryStats struct {
	TotalEntries      int                `json:"totalEntries"`
	EntriesByType     map[MemoryType]int `json:"entriesByType"`
	AverageImportance float64            `json:"averageImportance"`
	AverageConfidence float64            `json:"averageConfidence"`
	TotalAccessCount  int64              `json:"totalAccessCount"`
	MostAccessed      []string           `json:"mostAccessed"`
	OldestEntry       *time.Time         `json:"oldestEntry,omitempty"`
	NewestEntry       *time.Time         `json:"newestEntry,omitempty"`
}

type MemoryType string

type ParameterPattern struct {
	Parameters map[string]any `json:"parameters"`
	Frequency  int            `json:"frequency"`
	Success    bool           `json:"success"`
}

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

type RunConfig struct {
	// AgentType is the agent type
	AgentType string

	// Task is the task description
	Task string

	// Tools is the list of available tools (nil = all tools)
	Tools []tool.Tool

	// ToolFilter is the list of tool name patterns to allow (nil = use Tools field directly)
	ToolFilter []string

	// Engine is an optional pre-created engine
	Engine *engine.Engine

	// MaxTurns is the maximum number of session turns the agent may execute
	// autonomously. Each turn is one SubmitMessage call (which internally runs
	// the full tool-use loop). Default 0 means a single turn (backward compat).
	// Set to 2+ for multi-turn autonomous execution.
	MaxTurns int

	// StopCondition, when set, is evaluated after every turn. The agent stops
	// when it returns true. Receives the turn index (1-based) and the turn
	// output. Default: never stops early (runs until MaxTurns).
	StopCondition func(turn int, output string) bool

	// ContinuationMessage, when set, is called after each non-final turn to
	// produce the user message that starts the next turn. If nil the default
	// message is used: "Continue with the task."
	ContinuationMessage func(turn int, output string) string

	// Context is the parent context
	Context context.Context

	// Callback is called on each turn completion with cumulative tool use count.
	Callback func(turn int, output string, toolUses int)

	// ForkFromMessages is message context inherited from parent
	ForkFromMessages []types.Message

	// IsolationMode is "worktree" or empty
	IsolationMode string

	// WorktreeDir is the worktree directory (for isolation)
	WorktreeDir string

	// EventFn, when set, receives every RuntimeEvent emitted by the sub-agent session.
	// The caller is responsible for tagging events with AgentToolUseID before forwarding.
	EventFn func(types.RuntimeEvent)

	// Registry is an optional agent registry for resolving dynamic (skill-based) agents.
	// When nil, only built-in agents are resolved.
	Registry *AgentRegistry

	// Nickname is the human-friendly name assigned to this agent (e.g. "Orion").
	// Stored in AsyncAgent.Nickname; does not affect execution.
	Nickname string

	// Role is the role this agent was spawned with (e.g. "reviewer").
	// Stored in AsyncAgent.Role; does not affect execution.
	Role string

	// GoalStore, when non-nil, enables goal-aware continuation prompts.
	// After each turn the runner checks for an active goal keyed by GoalSessionID
	// and injects the appropriate prompt (continuation or budget_limit).
	// Mirrors Codex's server-side goal prompt injection in the thread loop.
	GoalStore *goal.Store

	// GoalSessionID is the key used to look up the goal in GoalStore.
	// Usually set to types.ToolContext.SessionID by the caller.
	GoalSessionID string

	// PermissionMode, when non-empty, overrides the session's permission mode.
	// Set to types.PermissionModeBypass for headless background agents so they
	// can execute tools without waiting for interactive prompts.
	PermissionMode types.PermissionMode

	// ResumeFromSessionID, when set, opens an existing persisted session instead
	// of creating a new one. The first message sent to the resumed session is
	// config.Task, continuing where the previous run left off.
	ResumeFromSessionID types.SessionID
}

type RunResult struct {
	// AgentType is the type of agent
	AgentType string `json:"agentType"`

	// Success indicates success
	Success bool `json:"success"`

	// Output is the final output
	Output string `json:"output"`

	// Turns is the number of turns
	Turns int `json:"turns"`

	// ToolUses is the number of tool uses
	ToolUses int `json:"toolUses"`

	// Sources lists every file, URL, and search query the agent consulted.
	// Collected automatically from tool calls — the parent receives this
	// without relying on the sub-agent to format it in its output.
	Sources []SourceRef `json:"sources,omitempty"`

	// WorktreePath is the worktree directory (for isolation mode)
	WorktreePath string `json:"worktreePath,omitempty"`

	// SessionID is the engine session ID for this run. Callers can pass it to
	// RunConfig.ResumeFromSessionID to continue from where this run left off.
	SessionID types.SessionID `json:"session_id,omitempty"`

	// Error is the error if failed
	Error string `json:"error,omitempty"`
}

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

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

type SolutionPattern struct {
	Solution    string   `json:"solution"`
	SuccessRate float64  `json:"successRate"`
	AppliesTo   []string `json:"appliesTo"`
}

type SourceRef struct {
	Type  string `json:"type"`  // "file", "url", "search", "glob", "grep"
	Value string `json:"value"` // path, URL, or query string
}

type TimeRange struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

type ToolUsageMemory struct {
	ToolName             string             `json:"toolName"`
	SuccessfulParameters []ParameterPattern `json:"successfulParameters"`
	FailedParameters     []ParameterPattern `json:"failedParameters"`
	TypicalUsage         string             `json:"typicalUsage"`
	SuccessRate          float64            `json:"successRate"`
	LastUsed             time.Time          `json:"lastUsed"`
	UsageCount           int                `json:"usageCount"`
}

type ValidationIssue struct {
	Category       string `json:"category"`
	Description    string `json:"description"`
	Location       string `json:"location"`
	Recommendation string `json:"recommendation"`
}

type ValidationResult struct {
	Valid       bool              `json:"valid"`
	Severity    string            `json:"severity"`
	Issues      []ValidationIssue `json:"issues"`
	Details     string            `json:"details"`
	AgentType   string            `json:"agentType"`
	AgentSource string            `json:"source"`
}