api

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

	// 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
}

type Discovery struct {
	ContractVersion string                     `json:"contract_version"`
	Cassettes       []DiscoveryEntry           `json:"cassettes"`
	Problems        []cassetterunner.Rejection `json:"problems"`

	// Entities is the aggregated entity registry:
	// core-native declarations plus every admitted cassette's [[entities]].
	// It updates as cassettes are admitted and withdrawn, and a consumer
	// keeping a catalog should treat it as advisory — shape-valid entity
	// types are usable whether or not they are currently listed.
	Entities []cassetterunner.AdvertisedEntity `json:"entities"`
}

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"`

	// Audience is the clients that should offer this cassette, empty meaning
	// all of them. Published because the filtering happens in the client, and a
	// client cannot filter on a field it never receives.
	Audience []string `json:"audience"`

	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 Evidence struct {
	Schema        string                `json:"schema"`
	Instance      EvidenceInstance      `json:"instance"`
	Configuration EvidenceConfiguration `json:"configuration"`

	// Cassettes is every source with a cassette identity, ordered by name.
	// A cassette here is not necessarily serving: Admission says whether it
	// is, and a source admitted once keeps its name through a later refusal
	// because the route it published is still mounted.
	Cassettes []EvidenceCassette `json:"cassettes"`

	// UnresolvedSources is every configured source that has produced no
	// cassette, ordered by subject — never fetched, unreachable, or refused
	// on first sight. There is no name to report for these, only what was
	// asked for, which kind of "no" it was, and what went wrong.
	UnresolvedSources []EvidenceUnresolvedSource `json:"unresolved_sources"`

	// CheckedAt is stamped when the request is served, so it dates the
	// answer rather than the state behind it. A reader bounding freshness
	// should use its own read time and keep this only for skew diagnosis:
	// an instance's clock is not something to make a liveness decision on.
	CheckedAt string `json:"checked_at"`
}

type EvidenceCassette struct {
	Name string `json:"name"`

	// Source is the configured document URL with any credential redacted.
	Source string `json:"source"`

	// Admission is the discriminator a registry lookup cannot supply:
	// admitted, rejected, or unresolved.
	Admission cassetterunner.Admission `json:"admission"`

	// ManifestDigest identifies the versioned metadata embedded in the
	// admitted document; OpenAPIDigest identifies the document core
	// republished from it. Both are always present and may be empty — a
	// cassette refused before it ever published has neither.
	ManifestDigest string `json:"manifest_digest"`
	OpenAPIDigest  string `json:"openapi_digest"`

	// OpenAPIStatus is how current the cached document is.
	OpenAPIStatus tapesoapi.Status `json:"openapi_status"`

	// RoutePrefix is where this cassette is mounted. It is reported even for
	// a rejected entry, because a cassette whose refresh was refused keeps
	// serving the document it published — the route is live, and a reader
	// checking that a withdrawn cassette stopped answering needs to see that.
	RoutePrefix string `json:"route_prefix"`

	// AdmittedAt is when the current admission began, absent when this
	// source is not currently admitted.
	AdmittedAt string `json:"admitted_at,omitempty"`

	// Rejection is the current problem, absent when there is none.
	Rejection *EvidenceProblem `json:"rejection,omitempty"`
}

type EvidenceConfiguration struct {
	// SourceListDigest identifies the cassette source list in effect, and
	// SourceCount how many entries it held. See
	// cassetterunner.SourceListDigest for the construction, which is fixed so
	// a reader can compute the same value from its own copy of the intended
	// list and compare.
	SourceListDigest string `json:"source_list_digest"`
	SourceCount      int    `json:"source_count"`

	// LoadedAt is when that list was installed, absent when this process has
	// never been told what to serve. It moves on a reconfiguration that does
	// not restart the process, which is the case nothing outside the process
	// can witness.
	LoadedAt string `json:"loaded_at,omitempty"`

	// ContractVersion is the tapes contract this core serves — the same one
	// the discovery document advertises, so the two cannot disagree about
	// which surface this is.
	ContractVersion string `json:"contract_version"`
}

type EvidenceInstance struct {
	// InstanceID is generated when the process starts. It is the identity
	// that needs no cluster: two answers carrying it are from the same
	// process, and a restart is visible even where the pod name did not
	// change.
	InstanceID string `json:"instance_id"`

	// StartedAt is when this process built its API server.
	StartedAt string `json:"started_at"`

	// The remainder are supplied by the deployment and absent when it
	// supplies nothing.
	PodName     string `json:"pod_name,omitempty"`
	PodUID      string `json:"pod_uid,omitempty"`
	PodIP       string `json:"pod_ip,omitempty"`
	NodeName    string `json:"node_name,omitempty"`
	ReplicaSet  string `json:"replica_set,omitempty"`
	ImageDigest string `json:"image_digest,omitempty"`
}

type EvidenceProblem struct {
	// Subject is what the problem is about: the configured document URL,
	// credential redacted.
	Subject string `json:"subject"`

	// Reason is the human-facing explanation, never parsed. It is empty for
	// a configured source no resolution pass has visited yet, which is a
	// state with a subject but no failure.
	Reason string `json:"reason"`

	// ObservedAt is when the reason was last seen, restamped on every
	// failing pass so a reader can tell a current problem from a stale one.
	ObservedAt string `json:"observed_at,omitempty"`
}

type EvidenceUnresolvedSource struct {
	EvidenceProblem

	// Admission is rejected or unresolved, never admitted — a source core
	// admitted has a cassette identity and is reported in Cassettes. It is
	// always present: an entry here is by construction a source with an
	// admission result and no name.
	Admission cassetterunner.Admission `json:"admission"`
}

type InternalConfig struct {
	// ListenAddr is the address to listen on. Empty is not a default; it is
	// a caller that should not have asked for a listener.
	ListenAddr string

	// Token is the bearer token every request must present.
	Token string
}

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

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 StandaloneTraceDetail struct {
	SessionID string `json:"session_id" oas:"required"`
	TraceDetail
}

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 projection provenance ("wire" | "transcript"). A
	// transcript-only session uses fallback until one usable wire call exists;
	// then its complete projection is wire-derived and transcripts only
	// reconcile structure. Spans inherit this trace-level provenance.
	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"`
}