api

type Config struct {
	// ListenAddr is the address to listen on (e.g., ":8081")
	ListenAddr string

	// VectorDriver for semantic search (optional, enables MCP server)
	VectorDriver vector.Driver

	// Embedder for converting query text to vectors (optional, enables MCP server)
	Embedder embeddings.Embedder

	// SpanSearcher enables GET /v1/search/spans — semantic search over
	// the span projection's embeddings (optional). Requires Embedder.
	SpanSearcher SpanSearcher

	// Pricing is the model pricing table used by /v1/sessions/summary to
	// compute per-session cost. When nil, sessions.DefaultPricing() is used.
	Pricing sessions.PricingTable

	// EnableWebUI serves the minimal browser UI at /. It is disabled by default
	// so API-only servers do not expose a human-facing development UI unless
	// explicitly requested.
	EnableWebUI bool

	// SkillLLM* configure the LLM used by POST /v1/skills/generate. They are
	// populated from the search/embedding credential so skill extraction
	// reuses the same shared key the platform already mounts for search —
	// no separate provider key. An empty Provider/APIKey falls back to the
	// generator's env/credentials resolution at call time.
	SkillLLMProvider string
	SkillLLMModel    string
	SkillLLMAPIKey   string
	SkillLLMBaseURL  string
}

type Metrics struct {
	// contains filtered or unexported fields
}

type ModelUsage struct {
	Model        string  `json:"model"`
	Calls        int64   `json:"calls"`
	InputTokens  int64   `json:"input_tokens"`
	OutputTokens int64   `json:"output_tokens"`
	CostUsd      float64 `json:"cost_usd"`
}

type PayloadMode string

type RawTurnHeaderItem struct {
	ID            int64           `json:"id"`
	Source        string          `json:"source"`
	Provider      string          `json:"provider,omitempty"`
	AgentName     string          `json:"agent_name,omitempty"`
	RequestID     string          `json:"request_id,omitempty"`
	ReceivedAt    time.Time       `json:"received_at"`
	Meta          json.RawMessage `json:"meta,omitempty"`
	RequestBytes  int64           `json:"request_bytes"`
	ResponseBytes int64           `json:"response_bytes"`
}

type RawTurnListResponse struct {
	Items []RawTurnHeaderItem `json:"items"`
}

type Server struct {
	// contains filtered or unexported fields
}

type SessionDetailResponse struct {
	Session SessionItem `json:"session"`
}

type SessionItem struct {
	ID                string     `json:"id"`
	HarnessID         string     `json:"harness_id"`
	HarnessSessionID  string     `json:"harness_session_id"`
	Name              string     `json:"name,omitempty"`
	Cwd               string     `json:"cwd,omitempty"`
	HarnessVersion    string     `json:"harness_version,omitempty"`
	ParentSessionID   string     `json:"parent_session_id,omitempty"`
	StartedAt         time.Time  `json:"started_at"`
	LastSeenAt        time.Time  `json:"last_seen_at"`
	EndedAt           *time.Time `json:"ended_at,omitempty"`
	TurnCount         int        `json:"turn_count"`
	TotalInputTokens  int64      `json:"total_input_tokens"`
	TotalOutputTokens int64      `json:"total_output_tokens"`
	TotalCostUsd      float64    `json:"total_cost_usd"`
	DerivedStatus     string     `json:"derived_status"`
	// Model is the dominant conversation-spine model, folded at derive
	// time; empty until the session first derives.
	Model string `json:"model,omitempty"`
	// ModelUsage is the per-model spend breakdown folded at derive time
	// across every thread (subagent models included), ordered
	// dominant-model-first by cost. The share basis is cost, not call
	// count, so the UI can show "dominant model + per-model %" without a
	// cheap-subagent fan-out skewing it. Populated on the session detail;
	// nil until the session first derives.
	ModelUsage      []ModelUsage   `json:"model_usage,omitempty"`
	HarnessMetadata map[string]any `json:"harness_metadata,omitempty"`
	Preview         string         `json:"preview,omitempty"`
	// AuthSubject is the gateway-stamped JWT subject (WorkOS user id)
	// captured at ingest; empty for rows captured before the edge began
	// stamping it.
	AuthSubject string `json:"auth_subject,omitempty"`
}

type SessionListResponse struct {
	Items      []SessionItem `json:"items"`
	NextCursor string        `json:"next_cursor,omitempty"`
}

type SessionTracesResponse struct {
	Session    SessionItem    `json:"session"`
	Tasks      []TreeTask     `json:"tasks"`
	KindCounts map[string]int `json:"kind_counts"`
	Traces     []TraceDetail  `json:"traces"`
	Links      []SpanLinkItem `json:"links"`
}

type SpanItem struct {
	ID           string    `json:"id"`
	TraceID      string    `json:"trace_id"`
	SpanID       string    `json:"span_id"`
	ParentSpanID string    `json:"parent_span_id,omitempty"`
	Kind         string    `json:"kind"`
	Name         string    `json:"name"`
	Status       string    `json:"status"`
	StartedAt    time.Time `json:"started_at"`
	StartNS      int64     `json:"start_ns"`
	DurationNS   int64     `json:"duration_ns"`
	// Seq is the span's presentation ordinal within its trace; spans
	// arrive sorted by it. start_ns cannot order spans inside one llm
	// call (parallel tool batches share an instant).
	Seq      int64          `json:"seq"`
	Input    map[string]any `json:"input"`
	Output   map[string]any `json:"output"`
	Metadata map[string]any `json:"metadata"`
	// Metrics is always an object on the wire — the contract fixture
	// pins {} for usage-less spans (agent/tool/event), and the console
	// schema requires it.
	Metrics     json.RawMessage `json:"metrics"`
	ChildrenIDs []string        `json:"children_ids,omitempty"`
}

type SpanLinkItem struct {
	FromTraceID string         `json:"from_trace_id"`
	FromSpanID  string         `json:"from_span_id"`
	FromIO      string         `json:"from_io,omitempty"`
	ToTraceID   string         `json:"to_trace_id"`
	ToSpanID    string         `json:"to_span_id"`
	ToIO        string         `json:"to_io,omitempty"`
	Metadata    map[string]any `json:"metadata"`
}

type SpanSearchOutput struct {
	Query   string             `json:"query"`
	Results []SpanSearchResult `json:"results"`
	Count   int                `json:"count"`
}

type SpanSearchResult struct {
	TraceID   string  `json:"trace_id"`
	SpanID    string  `json:"span_id"`
	SessionID string  `json:"session_id,omitempty"`
	Score     float32 `json:"score"`
	// UserPrompt is the prompt of the turn (trace) the span belongs to.
	UserPrompt string `json:"user_prompt,omitempty"`
	// Snippet previews the matched span's delta-only text.
	Snippet   string    `json:"snippet,omitempty"`
	Model     string    `json:"model,omitempty"`
	StartedAt time.Time `json:"started_at"`
}

type SpanSearcher interface {
	Search(ctx context.Context, orgID string, embedding []float32, topK int) ([]spanembed.Hit, error)
}

type StatsResponse struct {
	SessionCount int `json:"session_count"`
	// StemCount is a node-layer (Merkle leaf) concept with no span
	// equivalent; it is only present on the legacy fallback path.
	StemCount       int     `json:"stem_count,omitempty"`
	TurnCount       int     `json:"turn_count"`
	RootCount       int     `json:"root_count"`
	CompletedCount  int     `json:"completed_count"`
	TotalCost       float64 `json:"total_cost"`
	InputTokens     int64   `json:"input_tokens"`
	OutputTokens    int64   `json:"output_tokens"`
	TotalDurationNs int64   `json:"total_duration_ns"`
	ToolCalls       int     `json:"tool_calls"`
}

type TraceDetail struct {
	Trace TraceItem      `json:"trace"`
	Spans []SpanItem     `json:"spans"`
	Links []SpanLinkItem `json:"links"`
}

type TraceItem struct {
	ID               string `json:"id"`
	TraceID          string `json:"trace_id"`
	SessionID        string `json:"session_id"`
	HarnessID        string `json:"harness_id"`
	HarnessSessionID string `json:"harness_session_id"`
	UserPrompt       string `json:"user_prompt,omitempty"`
	// ResponsePreview is the derive-time fold of the closing
	// conversation-spine llm call's text output — the answer line for
	// collapsed turn cards, so summary consumers never need spans.
	ResponsePreview   string     `json:"response_preview,omitempty"`
	Status            string     `json:"status"`
	StartedAt         time.Time  `json:"started_at"`
	EndedAt           *time.Time `json:"ended_at,omitempty"`
	DurationNS        int64      `json:"duration_ns"`
	TotalInputTokens  int64      `json:"total_input_tokens"`
	TotalOutputTokens int64      `json:"total_output_tokens"`
	// Main* counts conversation-spine calls only; Total − Main is the
	// harness's shadow spend on the turn.
	MainInputTokens     int64          `json:"main_input_tokens"`
	MainOutputTokens    int64          `json:"main_output_tokens"`
	CacheReadTokens     int64          `json:"cache_read_tokens"`
	CacheCreationTokens int64          `json:"cache_creation_tokens"`
	TotalCostUSD        float64        `json:"total_cost_usd"`
	SpanCount           int            `json:"span_count"`
	Metadata            map[string]any `json:"metadata"`
}

type TraceListResponse struct {
	Items []TraceItem `json:"items"`
}

type TreeTask struct {
	ID          string `json:"id"`
	Subject     string `json:"subject"`
	Description string `json:"description,omitempty"`
	Status      string `json:"status"`
	Updates     int    `json:"updates"`
}

type TreeVerdict struct {
	Disposition string `json:"disposition"` // ALLOW | BLOCK
	Stage       int    `json:"stage"`
	Reasoned    bool   `json:"reasoned"`
}