mcpserver

type AskIn struct {
	SessionID string `json:"session_id" jsonschema:"the session whose research should be queried"`
	Question  string `json:"question" jsonschema:"the follow-up question to answer from that session's claims"`
}

type AskOut struct {
	SessionID string `json:"session_id"`
	Question  string `json:"question"`
	Answer    string `json:"answer"`

	// Claims are the ones the answer is built from, so a caller can weigh the
	// evidence rather than the prose (§5.3).
	Claims []Claim `json:"claims"`
	// Citations maps each [n] in the answer to its source.
	Citations []Citation `json:"citations"`

	// AskSessionID is the small session this answer was charged to. Present so
	// the cost is traceable: it will not appear against the session that was
	// queried, whose accounts are closed.
	AskSessionID string `json:"ask_session_id,omitempty"`
	Spent        int64  `json:"spent"`
	// Degraded says why the answer is not synthesized prose, when it is not.
	Degraded string `json:"degraded,omitempty"`
}

type Budget struct {
	Unit   string `json:"unit" jsonschema:"the budget unit: usd or tokens"`
	Amount string `json:"amount" jsonschema:"how much to spend: dollars like 2.50 for usd, a whole number of tokens for tokens"`
}

type CancelOut struct {
	SessionID string `json:"session_id"`
	Cancelled bool   `json:"cancelled"`
	Note      string `json:"note,omitempty"`
}

type Citation struct {
	N           int      `json:"n"`
	Source      string   `json:"source"`
	Quotes      []string `json:"quotes,omitempty"`
	PublishedAt string   `json:"published_at,omitempty"`
}

type Claim struct {
	ID          string  `json:"id"`
	Text        string  `json:"text"`
	Source      string  `json:"source"`
	Quote       string  `json:"quote,omitempty"`
	PublishedAt string  `json:"published_at,omitempty"`
	Confidence  float64 `json:"confidence"`
	Grounded    *bool   `json:"grounded,omitempty"`
}

type Deps struct {
	// Supervisor starts and cancels sessions.
	Supervisor *session.Supervisor
	// Store answers every read. Deliberately not the supervisor: the store is
	// authoritative and survives a restart, while the supervisor only remembers
	// the sessions it is running plus a bounded tail of finished ones. A status
	// query that worked before a daemon restart and failed after would be the
	// worst possible behaviour for a caller told to poll.
	Store store.Store

	// MaxSessionUSD and MaxSessionTokens cap a single session's budget in their
	// respective units. Zero means no ceiling. See config.MaxSessionUSD for why
	// these exist, and checkCeiling for why having only one set is refused.
	MaxSessionUSD    int64
	MaxSessionTokens int64

	// Version is the binary's version, reported to MCP clients in the server
	// handshake. Empty reports "dev".
	Version string

	// LLM answers research.ask. Nil disables synthesis: an ask then returns the
	// relevant claims with citations and no prose, which is the honest response
	// when no call can be made.
	LLM llmProvider
	// Pricing turns an ask's token usage into a ledger cost. Nil takes the
	// default table.
	Pricing *pricing.Table

	// AskTimeout bounds one research.ask. Zero takes DefaultAskTimeout.
	AskTimeout time.Duration

	// Workers is how many leads each session runs at once. Zero takes
	// executor.DefaultWorkers.
	Workers int

	// Defaults applied when a call does not specify.
	MaxSources int
	MaxDepth   int
	MaxLeads   int
	Timeout    time.Duration

	// Search, Fetch and Extract back toolkit mode. Nil leaves the matching tool
	// reporting that it is not configured rather than failing at call time.
	Search  search.Provider
	Fetch   fetch.Fetcher
	Extract extract.Extractor

	// Connectors is the registered local data, for the toolkit's aggregate tools.
	// Nil leaves them reporting that nothing is registered.
	Connectors interface{ List() []connector.Connector }
	// Gate tunes the aggregation gate. The zero value is §12.1's defaults.
	Gate gate.Options

	// Toolkit registers the toolkit tool surface. Off by default: those tools cost
	// every client their definitions in its context window, and a caller who wants
	// autonomous research should not read past them to find research.report.
	Toolkit bool

	Log *slog.Logger
}

type Edge struct {
	From      string  `json:"from"`
	To        string  `json:"to"`
	Kind      string  `json:"kind"`
	Weight    float64 `json:"weight,omitempty"`
	Rationale string  `json:"rationale,omitempty"`
}

type ListIn struct {
	Limit int `json:"limit,omitempty" jsonschema:"how many recent sessions to return; omit for 20"`
}

type ListOut struct {
	Sessions []SessionSummary `json:"sessions"`
}

type ReportIn struct {
	Prompt string `json:"prompt" jsonschema:"the research question"`
	Budget Budget `json:"budget" jsonschema:"what this session may spend"`

	MaxSources int `json:"max_sources,omitempty" jsonschema:"sources to read per lead; omit for the daemon default"`
	MaxDepth   int `json:"max_depth,omitempty" jsonschema:"rounds of follow-up questions the planner may add; omit for the daemon default"`
}

type ReportOut struct {
	SessionID string `json:"session_id"`
	Status    string `json:"status"`
	Unit      string `json:"budget_unit"`
	Budget    int64  `json:"budget"`
	Note      string `json:"note,omitempty"`
}

type ResultOut struct {
	SessionID string `json:"session_id"`
	Status    string `json:"status"`
	ReportMD  string `json:"report_md"`

	Claims []Claim `json:"claims"`
	Edges  []Edge  `json:"edges"`

	// TotalClaims and TotalEdges are what the session holds; the arrays above may
	// be shorter. Reported so a truncated result is visibly truncated — silently
	// returning a prefix is how a caller concludes a session found less than it
	// did.
	TotalClaims int  `json:"total_claims"`
	TotalEdges  int  `json:"total_edges"`
	Truncated   bool `json:"truncated"`

	Note string `json:"note,omitempty"`
}

type SessionRef struct {
	SessionID string `json:"session_id" jsonschema:"the id returned by research.report"`
}

type SessionSummary struct {
	SessionID string `json:"session_id"`
	Status    string `json:"status"`
	Prompt    string `json:"prompt"`
	Unit      string `json:"budget_unit"`
	Budget    int64  `json:"budget"`
	Spent     int64  `json:"spent"`
	Running   bool   `json:"running"`
}

type StatusOut struct {
	SessionID string `json:"session_id"`
	Status    string `json:"status"`
	Prompt    string `json:"prompt"`

	Unit      string `json:"budget_unit"`
	Budget    int64  `json:"budget"`
	Spent     int64  `json:"spent"`
	Remaining int64  `json:"remaining"`

	Claims   int  `json:"claims"`
	Verified int  `json:"claims_verified"`
	Edges    int  `json:"edges"`
	Running  bool `json:"running"`
}