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)
	// OnUsage reports the tokens a turn consumed and the session total.
	OnUsage func(turn *TokenUsage, session SessionUsage)
}

type AgentState string

type Assessment struct {
	Risk    CommandRisk
	Reason  string // shown in the approval prompt or the refusal
	Subject string // the command or path the verdict is about
}

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

type CommandVerdict struct {
	Risk    CommandRisk
	Command string // the offending segment
	Reason  string // human-readable, shown in the approval prompt
}

type CompactResult struct {
	BeforeTokens int
	AfterTokens  int
	Summarised   int // messages replaced by the summary
}

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 ContextUsage struct {
	Tokens int
	Limit  int
	// ThresholdPercent is how full the window gets before compaction runs.
	// Zero means the default, so a usage built by hand still behaves.
	ThresholdPercent int
}

type GeneratedImage struct {
	Data  []byte // decoded bytes, ready to write to disk
	Model string // the model that drew it
}

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"`
	Usage      *TokenUsage    `json:"usage,omitempty"`
}

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

	// OnRetry is called before each retry so the UI can explain the pause
	// instead of appearing to hang. See retry.go.
	OnRetry retryNotifier
}

type PermissionMode string

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 RetryReporter interface {
	SetRetryHook(func(attempt int, reason string))
}

type RunResult struct {
	// Text is the assistant's final message.
	Text string
	// ChangedFiles lists paths written, edited or deleted during the turn.
	ChangedFiles []string
	// ToolCalls counts tool invocations made during the turn.
	ToolCalls int
	// Verified reports whether the project build was run and passed.
	Verified bool
}

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"`
	// Usage totals every model turn in this session, so a resumed session
	// keeps reporting what it has cost so far.
	Usage SessionUsage `json:"usage"`
	// ContextOverhead is the part of a request that Messages does not
	// account for — the system prompt, the tool schemas and the project
	// context — measured against what the server actually counted. See
	// RecordContextTokens.
	ContextOverhead int `json:"context_overhead,omitempty"`
	// Transcript is what the user saw, kept separately from Messages.
	//
	// Messages is the model's context: compaction rewrites it and pruning
	// drops from it, both of which are right for fitting a context window and
	// wrong for a record of the session. The transcript is append-only, so
	// reopening a session shows the conversation as it happened — including
	// the notices that never went to the model at all.
	Transcript []TranscriptEntry `json:"transcript,omitempty"`
	// Messages is the live conversation: user turns, assistant replies, tool
	// calls and tool results, in order. This is what the model actually sees,
	// and what makes "continue" mean something — it is saved with the session
	// and restored by --resume.
	Messages []Message `json:"messages,omitempty"`
	// contains filtered or unexported fields
}

type SessionUsage struct {
	InputTokens  int     `json:"input_tokens"`
	OutputTokens int     `json:"output_tokens"`
	Requests     int     `json:"requests"`
	CostUSD      float64 `json:"cost_usd,omitempty"`
}

type SettingDef struct {
	Key     string // the JSON key, and the name used by search
	Label   string // shown in the list
	Help    string // one line, shown for the highlighted row
	Kind    SettingKind
	Choices []string // SettingChoice
	Min     int      // SettingInt
	Max     int      // SettingInt
	Step    int      // SettingInt
	Env     string   // the variable that overrides it, if any
	// contains filtered or unexported fields
}

type SettingKind int

type Settings struct {
	// Model is the default model name, or "optimal" to let the server pick.
	Model string `json:"model"`
	// AutoCompact summarises the conversation automatically as it fills.
	AutoCompact bool `json:"auto_compact"`
	// ContextLimit is the assumed context window in tokens.
	ContextLimit int `json:"context_limit"`
	// CompactThresholdPercent is how full the window gets before compaction.
	CompactThresholdPercent int `json:"compact_threshold_percent"`
	// PermissionMode decides how much runs without being confirmed.
	PermissionMode string `json:"permission_mode"`
	// VerifyBuilds runs the project's build after a turn changes code, and
	// hands failures back to the model to repair.
	VerifyBuilds bool `json:"verify_builds"`
	// ExpandDiffs shows full diffs in the transcript rather than a summary.
	ExpandDiffs bool `json:"expand_diffs"`
	// ShowThinking shows the "Thought for Xs" line between turns.
	ShowThinking bool `json:"show_thinking"`
	// StreamOutput prints the reply as it arrives rather than when complete.
	StreamOutput bool `json:"stream_output"`
	// MaxCommandOutput caps the bytes of a command's output fed back.
	MaxCommandOutput int `json:"max_command_output"`
	// PlanFirst routes every request through plan → approve → execute.
	PlanFirst bool `json:"plan_first"`

	// MCPServers is carried through untouched for the MCP client to read.
	// It is declared here so the raw-JSON round trip keeps it, and is not in
	// the registry: a server list is edited as JSON, not toggled in a list.
	MCPServers map[string]json.RawMessage `json:"mcp_servers,omitempty"`
}

type SettingsScope string

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 TokenUsage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	// CostUSD is what the turn cost, when the server prices it. The CLI does
	// not price locally: the server picks the model behind "optimal", so a
	// client-side guess would put a wrong number against real money.
	CostUSD float64 `json:"cost_usd,omitempty"`
}

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

	// ApproveCommand is consulted before running a command the policy flags
	// as consequential (see command_policy.go). Returning false refuses the
	// command; the model reads the refusal and can choose another route.
	//
	// Nil means no one can be asked: interactive callers must set it, and
	// headless callers set AutoApprove instead. Leaving both unset fails
	// closed, so a non-interactive run cannot silently `sudo` its way out of
	// a problem.
	ApproveCommand func(cmd, reason string) bool

	// AutoApprove runs flagged commands without asking (nimbus ai --yes).
	AutoApprove bool

	// MaxCommandOutput caps the bytes of a command's output handed back to
	// the model. Zero means the built-in cap, so a ToolExecutor built without
	// settings is still bounded.
	MaxCommandOutput int

	// GenerateImage draws an image through Nimbus Cloud. The CLI holds no
	// provider keys, so this is injected by the command that owns the cloud
	// client. Nil means the tool is not offered to the model at all, rather
	// than offered and failing when called.
	GenerateImage func(ctx context.Context, prompt, size, model string) ([]byte, string, error)
	// contains filtered or unexported fields
}

type TranscriptEntry struct {
	Role      string            `json:"role"`
	Content   string            `json:"content,omitempty"`
	ToolName  string            `json:"tool_name,omitempty"`
	ToolArgs  map[string]string `json:"tool_args,omitempty"`
	Detail    string            `json:"detail,omitempty"`
	Diff      string            `json:"diff,omitempty"`
	IsError   bool              `json:"is_error,omitempty"`
	ElapsedMS int64             `json:"elapsed_ms,omitempty"`
	At        time.Time         `json:"at"`
}

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
}