api

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

	// 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 MainUsage struct {
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`
}

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" swaggertype:"object"`
	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 {
	// Identity — capture-side facts, ingest-written.
	ID               string         `json:"id"`
	HarnessID        string         `json:"harness_id"`
	HarnessSessionID string         `json:"harness_session_id"`
	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"`
	HarnessMetadata  map[string]any `json:"harness_metadata,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"`
	// Name is the session's display label: the value on the identity row —
	// a user rename or the harness-supplied session name — when set,
	// otherwise the folded title (rollup.title) as a fallback. Empty only
	// when the session has neither. It therefore equals rollup.title
	// exactly when no identity-row name exists.
	Name string `json:"name,omitempty"`
	// Live is a runtime presence signal, not a projection fact: true when
	// the session was seen within the liveness window AND the deriver has
	// not marked it terminal. Computed at response time from last_seen_at,
	// so the console renders it directly instead of inferring "running"
	// from recency itself (keeps the console dumb; RFD 00007 §C).
	Live bool `json:"live"`
	// Rollup is the deriver-owned projection over the session's spans.
	Rollup SessionRollup `json:"rollup"`
}

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

type SessionRollup struct {
	Status string `json:"status"`
	// Title is the deriver's folded session title (derived_title),
	// generated from the conversation. Empty until title generation
	// produces one. It never falls back to the identity-row name, so it is
	// the stable descriptive title clients prefer for display; the
	// identity-row label (harness name or rename) is SessionItem.Name.
	Title     string `json:"title,omitempty"`
	Preview   string `json:"preview,omitempty"`
	TurnCount int    `json:"turn_count"`
	// Model is the dominant conversation-spine model; ModelUsage is the
	// per-model spend breakdown across every thread (subagent models
	// included), cost-ordered so the UI can show "dominant model + share"
	// without a cheap-subagent fan-out skewing it.
	Model      string       `json:"model,omitempty"`
	ModelUsage []ModelUsage `json:"model_usage,omitempty"`
	// KindCounts (spans per call_kind) and Tasks (TaskCreate/TaskUpdate
	// folds) are pinned so the rollup shape is uniform across sessions.
	KindCounts map[string]int `json:"kind_counts"`
	Tasks      []TreeTask     `json:"tasks"`
	Usage      SessionUsage   `json:"usage"`
}

type SessionTracesResponse struct {
	Schema  string         `json:"schema"`
	Session SessionItem    `json:"session"`
	Traces  []TraceDetail  `json:"traces"`
	Links   []SpanLinkItem `json:"links"`
}

type SessionUsage struct {
	InputTokens  int64   `json:"input_tokens"`
	OutputTokens int64   `json:"output_tokens"`
	CostUSD      float64 `json:"cost_usd"`
}

type SpanItem struct {
	TraceID      string `json:"trace_id"`
	SpanID       string `json:"span_id"`
	ParentSpanID string `json:"parent_span_id,omitempty"`
	// Seq is the span's presentation ordinal within its trace; spans
	// arrive sorted by it (started_at ties inside one llm call — parallel
	// tool batches share an instant).
	Seq        int64     `json:"seq"`
	Kind       string    `json:"kind"`
	Name       string    `json:"name"`
	Status     string    `json:"status"`
	StartedAt  time.Time `json:"started_at"`
	DurationNS int64     `json:"duration_ns"`
	// Deriver-written taxonomy, promoted from the old metadata grab-bag.
	CallKind   string `json:"call_kind"`
	Model      string `json:"model"`
	StopReason string `json:"stop_reason"`
	ThreadID   string `json:"thread_id"`
	RawTurnID  int64  `json:"raw_turn_id,omitempty"`
	// Verdict is the typed security-monitor disposition (null off
	// permission-check spans), deriver-written. It is a Verdict object or
	// null on the wire; typed as `object` (not the json.RawMessage byte
	// array swag would otherwise emit) via swaggertype.
	Verdict json.RawMessage `json:"verdict" swaggertype:"object" extensions:"x-nullable"`
	// Input/Output are content-block arrays (llm.ContentBlock), uniform for
	// every kind (tool spans included — no unwrapping). Pinned to [] when
	// empty. swaggertype keeps the wire an array-of-object rather than the
	// json.RawMessage byte array swag infers.
	Input  json.RawMessage `json:"input" swaggertype:"array,object"`
	Output json.RawMessage `json:"output" swaggertype:"array,object"`
	// Usage (was `metrics`) is an llm.Usage object on the wire — {}-pinned
	// for usage-less spans.
	Usage json.RawMessage `json:"usage" swaggertype:"object"`
	// Payload marks a preview-truncated span so the console drills in for
	// the full payload; absent in full mode.
	Payload string `json:"payload,omitempty"`
}

type SpanLinkItem struct {
	Kind        string `json:"kind"`
	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"`
}

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.
	// Served explicitly (not omitempty) so a synthetic turn's empty prompt
	// reaches consumers as "" rather than a dropped key — see TraceItem.
	UserPrompt string `json:"user_prompt"`
	// 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"`
	TurnCount       int     `json:"turn_count"`
	CompletedCount  int     `json:"completed_count"`
	TotalCost       float64 `json:"total_cost"`
	InputTokens     int64   `json:"input_tokens"`
	OutputTokens    int64   `json:"output_tokens"`
	TotalDurationMs int64   `json:"total_duration_ms"`
	ToolCalls       int     `json:"tool_calls"`
}

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

type TraceItem struct {
	TraceID string `json:"trace_id"`
	// UserPrompt is served explicitly (not omitempty): a synthetic opener
	// has an empty prompt, and dropping the key turns the empty string
	// into `undefined` on the wire, which breaks consumers that expect a
	// string (e.g. the console's stripHarnessTags). Empty means synthetic.
	UserPrompt string `json:"user_prompt"`
	// 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"`
	// Source is the capture origin of the turn's rows ("wire" |
	// "transcript"), promoted from raw_turns.source. Per-trace, so a
	// session can mix live wire capture and transcript backfill. Today
	// every trace is "wire": transcripts only reconcile fork/parent edges
	// during derivation, they never form a trace on their own. "transcript"
	// becomes real when a session is reconstructed purely from a transcript
	// file with no proxy capture (an OSS backfill path). See RFD 00007 §C.
	Source     string     `json:"source"`
	StartedAt  time.Time  `json:"started_at"`
	EndedAt    *time.Time `json:"ended_at,omitempty"`
	DurationNS int64      `json:"duration_ns"`
	SpanCount  int        `json:"span_count"`
	// Usage is the trace's total token/cost spend over ALL llm spans,
	// shadow calls included; MainUsage is the task slice — the main agent
	// and its subagents (every call_kind=main span, across threads). The
	// difference (Usage − MainUsage) is the harness's shadow spend
	// (permission checks, title-gen, web summaries) on the turn.
	Usage     TraceUsage `json:"usage"`
	MainUsage MainUsage  `json:"main_usage"`
	// Synthetic is a typed deriver signal ("post-compaction" for a
	// compaction continuation, "shadow-opener" for a shadow-only opener),
	// promoted out of the old metadata grab-bag. Absent for genuine
	// prompt-opened turns.
	Synthetic string `json:"synthetic,omitempty"`
}

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

type TraceUsage struct {
	InputTokens         int64   `json:"input_tokens"`
	OutputTokens        int64   `json:"output_tokens"`
	CacheReadTokens     int64   `json:"cache_read_tokens"`
	CacheCreationTokens int64   `json:"cache_creation_tokens"`
	CostUSD             float64 `json:"cost_usd"`
}

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