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

	// ContractVersions is the set of tapes contracts this server serves. A
	// cassette whose depends.core falls outside the set is refused at
	// admission, and the newest entry is what the discovery document
	// advertises as current. Empty means DefaultContractVersions().
	ContractVersions []cassette.ContractVersion

	// 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 Discovery struct {
	ContractVersion string                     `json:"contract_version"`
	Cassettes       []DiscoveryEntry           `json:"cassettes"`
	Problems        []cassetterunner.Rejection `json:"problems"`
}

type DiscoveryDepends struct {
	Core  string   `json:"core"`
	Views []string `json:"views"`
}

type DiscoveryEntry struct {
	Name           string             `json:"name"`
	Version        string             `json:"version,omitempty"`
	DisplayName    string             `json:"display_name,omitempty"`
	Description    string             `json:"description,omitempty"`
	RoutePrefix    string             `json:"route_prefix"`
	Depends        *DiscoveryDepends  `json:"depends,omitempty"`
	Tables         []string           `json:"tables"`
	Config         []DiscoverySetting `json:"config"`
	OpenAPIPath    string             `json:"openapi_path"`
	OpenAPIStatus  tapesoapi.Status   `json:"openapi_status"`
	ManifestDigest string             `json:"manifest_digest"`
}

type DiscoverySetting struct {
	Key         string `json:"key"`
	Type        string `json:"type"`
	Required    bool   `json:"required"`
	Secret      bool   `json:"secret"`
	Default     any    `json:"default,omitempty"`
	Description string `json:"description,omitempty"`
}

type MCPError struct {
	// Code is the JSON-RPC error code.
	Code int `json:"code" oas:"example=-32600"`

	// Message is a short description of the failure.
	Message string `json:"message" oas:"example=invalid request"`
}

type MCPRequest struct {
	// JSONRPC is the protocol version, always "2.0".
	JSONRPC string `json:"jsonrpc" oas:"example=2.0"`

	// ID correlates a response with this request. Absent on notifications.
	ID string `json:"id,omitempty" oas:"example=1"`

	// Method is the MCP method being invoked, such as tools/call.
	Method string `json:"method" oas:"example=tools/call"`

	// Params are the method's arguments.
	Params map[string]any `json:"params,omitempty"`
}

type MCPResponse struct {
	// JSONRPC is the protocol version, always "2.0".
	JSONRPC string `json:"jsonrpc" oas:"example=2.0"`

	// ID is the id of the request this answers.
	ID string `json:"id,omitempty" oas:"example=1"`

	// Result is the method's return value on success.
	Result map[string]any `json:"result,omitempty"`

	// Error describes the failure when the call did not succeed.
	Error *MCPError `json:"error,omitempty"`
}

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" oas:"type=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 harness identity-row label — the harness-supplied session
	// name (a plan slug), or the folded title (rollup.title) as a fallback
	// when no name was captured. This is capture/deriver provenance, NOT a
	// user title: ingest re-sends it every turn. Clients should render
	// DisplayTitle, not Name (PCC-970).
	Name string `json:"name,omitempty"`
	// DisplayName is the user's Console rename (sessions.display_name),
	// empty unless a user set one. Written only by PATCH /v1/sessions/:id,
	// never by ingest, so it survives a live session. It is the top of the
	// DisplayTitle resolution; exposed raw so the edit affordance can seed
	// its input from the user's own title (not the resolved fallback).
	DisplayName string `json:"display_name,omitempty"`
	// DisplayTitle is the server-resolved label clients should render:
	// DisplayName -> rollup.title (generated) -> preview -> Name -> id
	// slice. Resolving once on the server keeps every client (Console,
	// paper CLI) from re-deriving — and diverging on — the precedence
	// (PCC-970). Never empty: it falls back to a short harness id slice, then
	// the session id (the primary key, always set for a stored row).
	DisplayTitle string `json:"display_title"`
	// Live is a runtime presence signal, not a projection fact: true when
	// the session has no recorded end and was seen within the liveness
	// window. Keyed on ended_at + last_seen_at recency (both ingest-fresh),
	// never on the derived status: an interactive session folds to a
	// terminal status (an end_turn assistant reply reads as "completed")
	// after every turn while still open, so status cannot gate liveness.
	// Computed at response time so the console renders it directly instead
	// of inferring "running" itself.
	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; the oas tag states that, because a json.RawMessage
	// carries no shape a reflector could recover.
	Verdict json.RawMessage `json:"verdict" oas:"type=object,nullable"`
	// Input/Output are content-block arrays (llm.ContentBlock), uniform for
	// every kind (tool spans included — no unwrapping). Pinned to [] when
	// empty.
	Input  json.RawMessage `json:"input" oas:"type=array:object"`
	Output json.RawMessage `json:"output" oas:"type=array:object"`
	// Usage (was `metrics`) is an llm.Usage object on the wire — {}-pinned
	// for usage-less spans.
	Usage json.RawMessage `json:"usage" oas:"type=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).
	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"`
}