ports

type Clock interface {
	// Now returns the current time in UTC.
	Now() time.Time
}

type GlobalSessionRef struct {
	// ProjectEncodedDir is the encoded project directory name under ~/.claude/projects/,
	// e.g. "-Users-alice-work-clyde".
	ProjectEncodedDir string

	// SessionID is the session identifier (the JSONL filename without extension).
	SessionID session.ID

	// LastActivity is the file mtime — a cheap proxy for the session's last event.
	LastActivity time.Time

	// Path is the absolute path to the JSONL file.
	Path string
}

type GlobalSessionSource interface {
	// AllProjectSessions returns refs to all sessions across all projects,
	// ordered by LastActivity descending. At most maxResults refs are returned.
	// Pass maxResults=0 for no cap (not recommended in production).
	AllProjectSessions(ctx context.Context, maxResults int) ([]GlobalSessionRef, error)
}

type LLMSource interface {
	// Name returns the CLI source name, e.g. "claude-code", "gemini-cli".
	// Used for display in the title bar and for --source flag matching.
	Name() string

	// Sessions returns sessions for the given project working directory.
	Sessions(ctx context.Context, projectCWD string) ([]session.Summary, error)

	// Events returns events for the given session in ascending chronological order.
	Events(ctx context.Context, id session.ID) ([]event.Event, error)

	// AllProjectSessions returns references to sessions across all project
	// directories, ordered by LastActivity descending.
	// maxResults caps the result count (0 = no cap, not recommended in production).
	AllProjectSessions(ctx context.Context, maxResults int) ([]GlobalSessionRef, error)

	// PlanLimits returns the user's subscription plan limits, if detectable.
	// Returns nil when unknown (the caller falls back to hiding limit indicators).
	PlanLimits(ctx context.Context) *PlanLimits
}

type LSPInfo struct {
	// Name is the human-readable display label, e.g. "gopls", "rust-analyzer".
	Name string

	// Binary is the executable name as resolved on PATH, e.g. "/usr/local/bin/gopls".
	// Empty when the source did not preserve the resolved path.
	Binary string

	// Active is true when the binary is available (resolved on PATH).
	// Note: this is "installed and runnable", NOT "claude code is using it".
	// See ClaudeEnabled for that distinction.
	Active bool

	// ClaudeEnabled is true when Claude Code's settings.json enabledPlugins
	// map contains the plugin entry for this LSP (e.g.
	// "gopls-lsp@claude-plugins-official"). When false, the binary may be
	// installed locally but Claude Code is not actually using it — the TUI
	// flags this state with an amber dot so the user notices the gap.
	ClaudeEnabled bool
}

type LSPSource interface {
	LSPs() ([]LSPInfo, error)
}

type MCPEntry struct {
	// Name is the plugin identifier as it appears in the settings file,
	// e.g. "engram@engram" or "claude-code-setup@claude-plugins-official".
	Name string

	// Enabled is true when the plugin is explicitly enabled.
	Enabled bool

	// ToolCount is the number of tools provided by this server.
	// 0 when live inspection is unavailable (V1).
	ToolCount int
}

type MCPSource interface {
	// MCPs returns all configured MCP entries from the underlying settings source.
	MCPs() ([]MCPEntry, error)
}

type PlanLimits struct {
	// Name is the human-readable plan name, e.g. "Max ×5", "Pro", "Free".
	Name string

	// SessionLimit is the maximum tokens per 5-hour rolling window.
	// 0 means no limit is known or the plan has no token-based session cap.
	SessionLimit int64

	// WeeklyLimit is the maximum tokens per 7-day rolling window.
	// 0 means no limit is known or the plan has no weekly token cap.
	WeeklyLimit int64
}

type PlanUsage struct {
	// FiveHour is the rolling 5-hour session window.
	FiveHour PlanWindow

	// SevenDay is the rolling 7-day weekly window across all models.
	SevenDay PlanWindow

	// Tier is the human-readable plan tier name, derived from the
	// credentials file's rateLimitTier (e.g. "max_5x" → "Max 5x").
	// Empty when unknown.
	Tier string

	// FetchedAt is the time the PlanUsage was retrieved.
	FetchedAt time.Time
}

type PlanUsageSource interface {
	Fetch(ctx context.Context) (PlanUsage, error)
}

type PlanWindow struct {
	// Utilization is the 0–100 percentage of plan quota consumed in this window.
	// Values may exceed 100 when the user is over-limit and on extra-usage credits.
	Utilization float64

	// ResetsAt is the wall-clock time when the window resets.
	// Zero when unknown — callers SHOULD treat it as "no countdown".
	ResetsAt time.Time

	// Present is false when the backend response did not include this window
	// (e.g. an A/B-test variant renamed the key). Callers SHOULD hide the
	// bar entirely rather than drawing a 0% value.
	Present bool
}

type ProcessSource interface {
	RunningClaudeSessionIDs(ctx context.Context) ([]session.ID, error)
}

type SessionSource interface {
	// Sessions returns all Sessions belonging to the given Project working
	// directory, ordered by latest activity descending. May be empty.
	Sessions(ctx context.Context, projectCWD string) ([]session.Summary, error)

	// Events returns all Events for the given Session in strictly ascending
	// chronological order. May be empty.
	Events(ctx context.Context, id session.ID) ([]event.Event, error)
}

type SubagentInfo struct {
	// AgentID is the identifier parsed from the JSONL filename, e.g.
	// "agent-a09b7f25bb46ce5bc" from "agent-a09b7f25bb46ce5bc.jsonl".
	AgentID string

	// Description is the human-readable description from the agent's meta.json file.
	// Empty if no meta.json exists.
	Description string

	// AgentType is the type of the agent (e.g. "general-purpose").
	// Empty if no meta.json exists.
	AgentType string
}

type SubagentSource interface {
	// Subagents lists all subagent infos for the given parent session.
	// projectCWD is needed to locate the encoded project directory.
	// Returns an empty slice (no error) when no subagents exist.
	Subagents(ctx context.Context, projectCWD string, parentSessionID string) ([]SubagentInfo, error)

	// SubagentEvents returns all events from the given subagent's JSONL file
	// in file order (ascending chronological). projectCWD and parentSessionID
	// are needed to locate the file.
	SubagentEvents(ctx context.Context, projectCWD string, parentSessionID string, agentID string) ([]event.Event, error)
}