agent

type Agent interface {
	// Plan launches an interactive planning session.
	// If initialPrompt is non-empty, it is sent as the first message.
	// Returns the structured plan when the session ends.
	Plan(ctx context.Context, initialPrompt string, opts PlanOptions) (*Plan, error)

	// Execute runs a task in headless mode (used by workers).
	Execute(ctx context.Context, task TaskSpec, opts ExecOptions) (*ExecResult, error)

	// Review runs a code review on a diff in headless mode (used by the Integrator).
	Review(ctx context.Context, diff string, opts ReviewOptions) (*ReviewResult, error)

	// Discuss launches an interactive agent session with a fully rendered
	// system prompt and an optional initial user prompt. Unlike Plan, it has
	// no structured output — the agent is expected to converse with the user
	// and may make changes if the user asks. Returns nil on a clean exit.
	Discuss(ctx context.Context, opts DiscussOptions) error
}

type DiscussOptions struct {
	RepoRoot      string
	SystemPrompt  string
	InitialPrompt string
}

type ExecOptions struct {
	RepoRoot     string
	SystemPrompt string
	MaxTurns     int // Max agentic turns (0 = agent default)
}

type ExecResult struct {
	ModifiedFiles []string
	Summary       string
}

type Plan struct {
	BatchName string        `json:"batch_name" yaml:"batch_name"`
	Tasks     []PlannedTask `json:"tasks" yaml:"tasks"`
}

type PlanOptions struct {
	RepoRoot     string
	OutputPath   string // Path where the agent writes the plan JSON
	SystemPrompt string
	Context      map[string]string
}

type PlannedTask struct {
	Title                   string   `json:"title" yaml:"title"`
	Description             string   `json:"description" yaml:"description"`
	ImplementationDetails   string   `json:"implementation_details" yaml:"implementation_details"`
	AcceptanceCriteria      []string `json:"acceptance_criteria" yaml:"acceptance_criteria"`
	Scope                   []string `json:"scope" yaml:"scope"`
	Conventions             []string `json:"conventions" yaml:"conventions"`
	ContextFromDependencies []string `json:"context_from_dependencies" yaml:"context_from_dependencies"`
	Complexity              string   `json:"complexity" yaml:"complexity"`     // "low", "medium", "high"
	Type                    string   `json:"type" yaml:"type"`                 // "feature", "bugfix" (default: "feature")
	RunnerLabel             string   `json:"runner_label" yaml:"runner_label"` // Runner label override; empty = use config default
	DependsOn               []int    `json:"depends_on" yaml:"depends_on"`     // Indices into the Tasks slice
	Manual                  bool     `json:"manual" yaml:"manual"`             // Requires human action, not dispatched to workers
}

type ReviewFinding struct {
	Severity    string `json:"severity"` // "HIGH", "MEDIUM", "LOW"
	Description string `json:"description"`
}

type ReviewOptions struct {
	AcceptanceCriteria   []string
	RepoRoot             string
	SystemPrompt         string
	Strictness           string   // "standard", "strict", "lenient" — controls review aggressiveness
	MinFixSeverity       string   // minimum severity that blocks approval: "high", "medium", "low"
	PriorReviewComments  []string // Full text of previous HerdOS review comments on this PR
	UserFeedbackComments []string // User-authored comments on this PR (authoritative)
	// WorkerNoOpVerdicts contains the bodies of structured verdict
	// comments posted by fix workers on the batch PR in previous cycles.
	// Each entry is one full verdict comment body (header + reasoning).
	// The reviewer treats these as authoritative — a worker has read the
	// issue body and verified the code, and concluded no change was
	// needed. Re-flagging the same finding requires NEW concrete evidence.
	WorkerNoOpVerdicts []string
}

type ReviewResult struct {
	Approved bool            `json:"approved"`
	Findings []ReviewFinding `json:"findings"`
	Comments []string        `json:"comments"` // Deprecated: populated from Findings for backward compatibility
	Summary  string          `json:"summary"`
	// IsUnparseable is true when the agent returned output that could
	// not be parsed as the expected JSON contract. The agent layer sets
	// this together with a Summary that begins with "Failed to parse"
	// so callers can detect it without string matching.
	IsUnparseable bool `json:"-"`
}

type TaskSpec struct {
	IssueNumber        int // GitHub issue number (for commit messages)
	Title              string
	Body               string // Full issue body (raw markdown, passed verbatim to agent)
	AcceptanceCriteria []string
	Scope              []string
}