mcpperf

type AllocStat struct {
	// Function is the allocating function's name.
	Function string `json:"function"`
	// File is the BASENAME of the allocating function's source file (path dropped).
	File string `json:"file"`
	// FlatBytes is the bytes attributed to this function alone.
	FlatBytes int64 `json:"flat_bytes"`
	// CumBytes is the bytes attributed to this function and its callees.
	CumBytes int64 `json:"cum_bytes"`
}

type CaptureCPUProfileInput struct {
	DurationSeconds int  `json:"duration_seconds,omitempty" jsonschema:"CPU profiling window in seconds (1-30, default 5)"`
	Limit           int  `json:"limit,omitempty" jsonschema:"number of top functions to return (1-50, default 15)"`
	IncludeRawLink  bool `` /* 147-byte string literal not displayed */
}

type CaptureFlightRecorderInput struct{}

type CaptureFlightRecorderOutput struct {
	CapturedBytes int    `json:"captured_bytes"`
	WindowSummary string `json:"window_summary"`
}

type Deps struct {
	// Snapshot returns the current runtime snapshot DTO. Required.
	Snapshot func() telemetry.RuntimeSnapshot
	// Gatherer gathers the prometheus metric families backing the latency
	// histograms and counters. *prometheus.Registry satisfies it. Required.
	Gatherer prometheus.Gatherer
	// Recorder is the flight recorder seam. Nil-able (recorder not armed).
	Recorder FlightRecorder
	// Profiler is the pprof seam. Required (defaultProfiler in production).
	Profiler Profiler
	// SlowTurns is the slow-turn history seam. Nil-able (history not enabled).
	SlowTurns SlowTurnSource
	// Clock returns the current time, for cooldown accounting and timestamps.
	// Nil falls back to time.Now.
	Clock func() time.Time
	// Logger is used for low-volume operational logging. It MUST NOT be used to
	// log tool inputs or outputs at info level. Nil falls back to a discard logger.
	Logger *slog.Logger
}

type FlightRecorder interface {
	// SnapshotBytes returns the current trace window as parseable trace bytes.
	SnapshotBytes() ([]byte, error)
	// Enabled reports whether the recorder is currently running.
	Enabled() bool
}

type FuncStat struct {
	// Function is the function's name (pprof Function.Name).
	Function string `json:"function"`
	// File is the BASENAME of the function's source file — the absolute path is
	// dropped deliberately, because it leaks $HOME and workspace layout.
	File string `json:"file"`
	// FlatValue is the value attributed to this function alone (self time/space).
	FlatValue int64 `json:"flat_value"`
	// CumValue is the value attributed to this function and everything it called.
	CumValue int64 `json:"cum_value"`
}

type ListSlowTurnsInput struct {
	ThresholdMs int64  `json:"threshold_ms,omitempty" jsonschema:"only turns at least this slow (ms); omit for the source default"`
	Limit       int    `json:"limit,omitempty" jsonschema:"max turns to return (1-20, default 10)"`
	Cursor      string `json:"cursor,omitempty" jsonschema:"opaque pagination cursor from a previous response's nextCursor"`
	Role        string `` /* 134-byte string literal not displayed */
}

type ListSlowTurnsOutput struct {
	Turns      []SlowTurn `json:"turns"`
	NextCursor string     `json:"nextCursor,omitempty"`
	TotalCount int        `json:"totalCount"`
}

type MemstatsProjection struct {
	// HeapAllocsTotalBytes is the cumulative heap-allocation counter (bytes ever
	// allocated since process start) — NOT live heap; live is HeapObjectBytes.
	HeapAllocsTotalBytes uint64 `json:"heap_allocs_total_bytes"`
	HeapObjects          uint64 `json:"heap_objects"`
	HeapObjectBytes      uint64 `json:"heap_object_bytes"`
	TotalMemoryBytes     uint64 `json:"total_memory_bytes"`
	RSSBytes             uint64 `json:"rss_bytes"`
	// Available echoes the snapshot's Available set so a consumer can tell which
	// runtime/metrics-derived fields were actually present this read.
	Available []string `json:"available"`
}

type MetricSummaryEntry struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Kind        string          `json:"kind"` // "histogram" | "scalar" | "absent"
	Count       uint64          `json:"count,omitempty"`
	Quantiles   []QuantileBound `json:"quantiles,omitempty"`
	Value       float64         `json:"value,omitempty"`
	ByRole      []RoleBreakdown `json:"by_role,omitempty"`
}

type Profiler interface {
	// Lookup returns the named profile's pprof bytes (debug=0, gzipped protobuf)
	// for name in {heap, goroutine, allocs, mutex, block}, or an error if the
	// name is unknown or the profile cannot be written.
	Lookup(name string) ([]byte, error)
	// CPUProfile runs a CPU profile for d and returns its pprof bytes. It blocks
	// for the duration. Only one CPU profile may run process-wide at a time; the
	// caller (the cpuGate) serializes access.
	CPUProfile(d time.Duration) ([]byte, error)
}

type QuantileBound struct {
	// Quantile is the requested rank in [0,1] (e.g. 0.99 for p99).
	Quantile float64 `json:"quantile"`
	// UpperBound is the upper bound of the bucket containing that rank, in the
	// histogram's own unit (seconds for the latency instruments).
	UpperBound float64 `json:"upper_bound"`
}

type QueryMetricInput struct {
	MetricName string  `json:"metric_name,omitempty" jsonschema:"the curated metric to query; omit to list available metric names"`
	Quantile   float64 `` /* 133-byte string literal not displayed */
	Role       string  `` /* 150-byte string literal not displayed */
}

type QueryMetricOutput struct {
	AvailableMetrics []string            `json:"available_metrics,omitempty"`
	Metric           *MetricSummaryEntry `json:"metric,omitempty"`
}

type RoleBreakdown struct {
	Role  string  `json:"role"`
	Count uint64  `json:"count,omitempty"`
	Value float64 `json:"value,omitempty"`
}

type SlowTurn struct {
	// TurnIndex is the monotonic index of the turn within its run.
	TurnIndex int `json:"turn_index"`
	// DurationMs is the turn's model-call wall-clock duration in milliseconds.
	DurationMs int64 `json:"duration_ms"`
	// TTFTMs is the time-to-first-token in milliseconds (0 if not measured).
	TTFTMs int64 `json:"ttft_ms"`
	// InterTokenMaxMs is the worst inter-token gap in milliseconds (0 if not measured).
	InterTokenMaxMs int64 `json:"inter_token_max_ms"`
	// EndedAt is the wall-clock time the turn ended, RFC3339.
	EndedAt time.Time `json:"ended_at"`
	// Role is the BOUNDED engine role family that produced the turn
	// (main|subagent|member|parallel|usermodel|child). It is a closed enum
	// label — never a def/member name or session id — so redaction by shape holds.
	Role string `json:"role,omitempty"`
}

type SlowTurnSource interface {
	// Recent returns recent slow turns, newest first. thresholdMs, if > 0, filters
	// to turns at least that slow; 0 means "use the source default threshold". It
	// returns the whole (bounded) matching set so the tool can report an accurate
	// totalCount and paginate over a stable snapshot — the buffer's fixed size is
	// the cap, not a per-call limit argument.
	Recent(thresholdMs int64) []SlowTurn
}

type TopAllocationsInput struct {
	Limit int `json:"limit,omitempty" jsonschema:"number of top allocating functions to return (1-50, default 15)"`
}

type TopAllocationsOutput struct {
	TotalHeapBytes int64       `json:"total_heap_bytes"`
	Top            []AllocStat `json:"top"`
}

type TopCPUFunctionsInput struct {
	DurationSeconds int `json:"duration_seconds,omitempty" jsonschema:"CPU profiling window in seconds (1-30, default 5)"`
	Limit           int `json:"limit,omitempty" jsonschema:"number of top functions to return (1-50, default 15)"`
}

type TopCPUFunctionsOutput struct {
	DurationSeconds int        `json:"duration_seconds"`
	SampleCount     int        `json:"sample_count"`
	Top             []FuncStat `json:"top"`
}