ai

type AIClient interface {
	Chat(ctx context.Context, prompt, model string, projCtx *ProjectContext) (string, error)
	GeneratePlan(ctx context.Context, prompt string, projCtx *ProjectContext, model string) (*PlanSummary, error)
	RegenerateStep(ctx context.Context, stepIndex int, newDesc string, currentPlan *PlanSummary, projCtx *ProjectContext, model string) (*PlanSummary, error)
	StreamExecute(ctx context.Context, prompt string, plan *PlanSummary, messages []Message, tools []ToolDefinition, projCtx *ProjectContext, onDelta StreamHandler) (*MessageResponse, error)
	// Turn runs a single agentic model turn. Implementations that cannot
	// support it must return ErrTurnUnsupported.
	Turn(ctx context.Context, req *TurnRequest, onDelta StreamHandler) (*MessageResponse, error)
}

type Agent struct {
	Client    AIClient
	Tools     *ToolExecutor
	Context   *ProjectContext
	Session   *Session
	Model     string
	State     AgentState
	Callbacks AgentCallbacks

	// Verifier runs the project's build/tests after execution and returns
	// (output, ok). Defaults to a Go build when go.mod is present; tests
	// override it. Nil disables verification.
	Verifier func(ctx context.Context) (string, bool)
	// contains filtered or unexported fields
}

type AgentCallbacks struct {
	OnRequestSent        func()
	OnStreamDelta        func(delta string)
	OnStatus             func(text string)
	OnPlanGenerated      func(plan *PlanSummary)
	OnStepUpdate         func(step *PlanStep)
	OnDiffGenerated      func(filePath, diff string)
	OnToolCall           func(toolName string, args map[string]any)
	OnToolResult         func(toolName string, args map[string]any, output string, err error)
	OnExecutionCompleted func(summary string)
}

type AgentState string

type ClarificationQuestion struct {
	ID       string   `json:"id"`
	Question string   `json:"question"`
	Options  []string `json:"options,omitempty"`
	Default  string   `json:"default,omitempty"`
	Selected string   `json:"selected,omitempty"`
}

type ContentBlock struct {
	Type      string         `json:"type"` // "text" | "tool_use" | "tool_result"
	Text      string         `json:"text,omitempty"`
	ID        string         `json:"id,omitempty"`
	Name      string         `json:"name,omitempty"`
	Input     map[string]any `json:"input,omitempty"`
	ToolUseID string         `json:"tool_use_id,omitempty"`
	Content   string         `json:"content,omitempty"`
	IsError   bool           `json:"is_error,omitempty"`
}

type Message struct {
	Role    string `json:"role"`    // "user" | "assistant" | "system"
	Content any    `json:"content"` // string or []ContentBlock
}

type MessageResponse struct {
	ID         string         `json:"id"`
	Model      string         `json:"model"`
	Role       string         `json:"role"`
	Content    []ContentBlock `json:"content"`
	StopReason string         `json:"stop_reason"`
}

type NimbusCloudClient struct {
	ServerURL  string
	Token      string
	HTTPClient *http.Client
}

type PlanPhase struct {
	Name        string   `json:"name"`        // e.g. "Phase 1: Frontend User Interface"
	Description string   `json:"description"` // e.g. "Implement responsive Todo app view"
	Files       []string `json:"files"`       // e.g. ["resources/views/todo.html"]
}

type PlanStep struct {
	ID          int    `json:"id"`
	Phase       string `json:"phase,omitempty"` // e.g. "Phase 1: Frontend UI"
	Action      string `json:"action"`          // "create_file" | "edit_file" | "run_command" | "delete_file" | "clarification_needed"
	Target      string `json:"target"`
	Description string `json:"description"`
	Content     string `json:"content,omitempty"`
	Risk        string `json:"risk"` // "low" | "medium" | "high"
	Approved    bool   `json:"approved"`
	Status      string `json:"status,omitempty"` // "pending" | "running" | "applied" | "failed"
	Error       string `json:"error,omitempty"`
}

type PlanSummary struct {
	Summary            string                  `json:"summary"`
	Overview           string                  `json:"overview,omitempty"`
	NeedsClarification bool                    `json:"needs_clarification,omitempty"`
	Questions          []ClarificationQuestion `json:"questions,omitempty"`
	Phases             []PlanPhase             `json:"phases,omitempty"`
	Steps              []PlanStep              `json:"steps"`
	Details            []string                `json:"details,omitempty"`
}

type ProjectContext struct {
	AppRoot        string   `json:"app_root"`
	ProjectName    string   `json:"project_name"`
	GoModName      string   `json:"go_mod_name,omitempty"`
	GoVersion      string   `json:"go_version,omitempty"`
	NimbusModules  []string `json:"nimbus_modules,omitempty"`
	NimbusJSON     string   `json:"nimbus_json,omitempty"`
	DirectoryTree  string   `json:"directory_tree"`
	GitBranch      string   `json:"git_branch,omitempty"`
	GitDiffSummary string   `json:"git_diff_summary,omitempty"`
	RootFiles      []string `json:"root_files,omitempty"`
	Models         []string `json:"models,omitempty"`
	Controllers    []string `json:"controllers,omitempty"`
	Migrations     []string `json:"migrations,omitempty"`
	RoutesSummary  string   `json:"routes_summary,omitempty"`
	Skills         []Skill  `json:"skills,omitempty"`
	// ActiveSkillFrame holds the most recently loaded skill so the server can
	// keep it in the system prompt rather than the message history.
	ActiveSkillFrame string `json:"active_skill_frame,omitempty"`
	// Instructions holds project-level guidance for the agent, read from
	// AGENTS.md / NIMBUS.md / CLAUDE.md / .nimbus/instructions.md. It is the
	// project's persistent memory: conventions, do's and don'ts, commands.
	Instructions string `json:"instructions,omitempty"`
	// InstructionFiles lists which instruction files were found.
	InstructionFiles []string `json:"instruction_files,omitempty"`
	// Stack summarises non-Go tooling detected (package.json, Vite, Tailwind…).
	Stack []string `json:"stack,omitempty"`
	// OS is the host operating system, so shell commands can be phrased correctly.
	OS string `json:"os,omitempty"`
}

type Session struct {
	ID           string            `json:"id"`
	CreatedAt    time.Time         `json:"created_at"`
	UpdatedAt    time.Time         `json:"updated_at"`
	InitialQuery string            `json:"initial_query"`
	Model        string            `json:"model"`
	Plan         *PlanSummary      `json:"plan,omitempty"`
	ApprovedPlan *PlanSummary      `json:"approved_plan,omitempty"`
	History      []Message         `json:"history"`
	AppliedSteps []int             `json:"applied_steps"`
	LoadedSkills map[string]string `json:"loaded_skills,omitempty"`
	Status       string            `json:"status"` // "planning" | "reviewing" | "executing" | "completed"
	// Findings is the exploration report produced for the current request.
	Findings string `json:"findings,omitempty"`
	// Turns is the conversation memory: one record per completed request,
	// carried into later prompts so follow-ups build on earlier work.
	Turns []TurnRecord `json:"turns,omitempty"`
}

type Skill struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Path        string `json:"path"`
	Source      string `json:"source"` // "project" | "global" | "embedded"
}

type StreamHandler func(delta string)

type ToolDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"input_schema"`
}

type ToolExecutor struct {
	AppRoot string
	// CommandTimeout bounds a single bash invocation.
	CommandTimeout time.Duration
}

type TurnMode string

type TurnRecord struct {
	At           time.Time `json:"at"`
	Prompt       string    `json:"prompt"`
	PlanSummary  string    `json:"plan_summary,omitempty"`
	Outcome      string    `json:"outcome,omitempty"`
	FilesChanged []string  `json:"files_changed,omitempty"`
}

type TurnRequest struct {
	Mode     TurnMode
	Model    string
	Prompt   string // the user's original request
	Messages []Message
	Tools    []ToolDefinition
	Plan     *PlanSummary
	Context  *ProjectContext
}