protocol

type ApplyRequest struct {
	Edits            []EditOp
	ExpectedRevision string
	// Format runs the language formatter over touched files. Defaults on.
	Format bool
	// Check runs one validation afterwards ("build", "typecheck", "tests"),
	// instead of one per edit. Empty skips it.
	Check string
}

type ApplyResponse struct {
	OldRevision  string
	NewRevision  string
	Applied      int
	Changed      []string
	AddedLines   int
	RemovedLines int
	Formatted    []string
	Diagnostics  []Diagnostic
	Checks       CheckReport
	CheckStatus  string
	CheckOutcome ValidationOutcome
	CheckPassed  bool
	CheckSummary string
	Summary      string
	Snippets     []Snippet `json:",omitempty"`
	// Impact is what an impact check traced, nil for any other check.
	Impact *Impact `json:",omitempty"`
}

type CapabilitiesResponse struct {
	Languages     []LanguageCapability
	Git           bool
	Commands      []string
	Validation    []ValidationCapability
	ProjectConfig string
	// Truncated says the language counts stopped at the listing bound.
	Truncated bool
	// Providers lists each capability's registered providers, in the order
	// Jade asks them.
	Providers []ProviderCapability
}

type ChangedFile struct {
	Path    string
	Added   int
	Removed int
	// By is "this session" for a file this session edited, and "outside this
	// session" for one git sees changed that it did not — another session,
	// the user or a tool.
	By string
}

type ChangesResponse struct {
	Revision string
	// Runs are this session's most recent finished validation runs, so edits
	// and their validation read as one record.
	Runs []ValidationRun
	// Files is the single changed-file list. It carries jade's own edit
	// ledger as well as git's diff, so callers never have to reconcile two
	// overlapping path lists — see Manager.mergedChangedFiles.
	Files        []ChangedFile
	TotalAdded   int
	TotalRemoved int
	// Symbols is empty when no changed file is in a language jade can parse;
	// the file-level counts stand on their own in that case rather than the
	// whole response degrading.
	Symbols []SymbolChange
	// SymbolsOmitted is the changed-file count that caused the symbol delta to
	// be skipped, or zero when it was computed. Non-zero means "this response
	// deliberately has no Symbols", which is a different statement from "this
	// tree has no symbol changes" and must never be collapsed into it.
	SymbolsOmitted int
	Summary        string
}

type CheckReport struct {
	// Checked lists distinct checker names, e.g. "gopls", "pyright-langserver".
	Checked []string `json:",omitempty"`
	// Unchecked has one "path: reason" entry per file of a known language
	// that nothing could check. Files with no language are not listed.
	Unchecked []string `json:",omitempty"`
}

type CheckRequest struct {
	Kind string
	// Wait blocks for the result instead of returning a job ID to poll.
	// Defaults on: an agent asking "does it build" wants the answer.
	Wait bool
	// TimeoutSeconds bounds the wait. Ignored when Wait is false.
	TimeoutSeconds int
	// DryRun names the command that would run, without running it.
	DryRun bool
	// Target is a project directory inside the workspace to discover and run
	// the command in, for a repository with several projects. Empty means the
	// workspace root.
	Target string
}

type CheckResponse struct {
	JobID   string
	Kind    string
	Outcome ValidationOutcome
	Status  string
	Passed  bool
	Summary string
	// Command is what ran, or would run for a dry run, e.g. "go vet ./...".
	// Empty when no validation command fits the workspace.
	Command string
}

type CheckpointRequest struct {
	Note string
}

type CheckpointResponse struct {
	ID       string
	Note     string
	Revision string
	Paths    []string
	// Head is the git commit the checkpoint was taken at, or "" without git.
	Head string
}

type CommitInfo struct {
	SHA     string
	Author  string
	Date    string
	Subject string
}

type ContextRequest struct {
	Path       string
	SymbolID   string
	SymbolName string
	Purpose    string
}

type ContextResponse struct {
	SymbolID       string
	Symbol         string
	Kind           string
	Path           string
	Purpose        string
	Implementation string
	Callers        []string
	CallerCount    int
	Tests          []string
	TestCount      int
	Types          []string
	TypeCount      int
	Diagnostics    []Diagnostic
	// RecentChange is "added", "modified" or "removed" when this symbol
	// differs from HEAD, empty when it is unchanged.
	RecentChange string
	Summary      string
	// Provenance is how the callers and tests were found: a language server's
	// exact references or the approximate name-matched graph.
	Provenance Provenance
}

type CreateFileRequest struct {
	Path    string
	Content string
}

type DeclareCommandRequest struct {
	Name        string
	Run         string
	Description string
	// Kind makes the command a validation step check runs by kind.
	Kind string
	// Remove deletes the named command instead of declaring it.
	Remove bool
}

type DeclareCommandResponse struct {
	Name string
	Run  string
	// Path is the registry's location relative to the workspace root, so the
	// caller can go read or revert it.
	Path string
	// Replaced reports that an existing command was overwritten. Surfaced
	// rather than silent: clobbering a command another agent declared should
	// be visible in the response.
	Replaced bool
	// Removed reports a deletion.
	Removed   bool
	Available []DeclaredCommand
}

type DeclaredCommand struct {
	Name        string
	Run         string
	Description string
	Kind        string
}

type DeleteFileRequest struct {
	Path string
}

type DeleteSymbolRequest struct {
	Path             string
	SymbolID         string
	SymbolName       string
	ExpectedRevision string
}

type Diagnostic struct {
	Level   DiagnosticLevel
	Path    string
	Line    int
	Column  int
	Message string
}

type DiagnosticLevel string

type DiffRequest struct {
	Target string
	// Since diffs against a git revision other than HEAD — "HEAD~3", a branch
	// name, a commit SHA. Empty means HEAD, the working-tree diff.
	//
	// The question it answers is "what has this branch done", which HEAD
	// cannot express once any of the work is committed: a task that commits
	// midway becomes invisible to a working-tree diff even though nothing has
	// merged.
	Since string
	// Budget, in tokens, pages the patch at whole lines; Continue is a handle
	// from a cut patch.
	Budget   int
	Continue string
}

type DiffResponse struct {
	Target string
	Patch  string
	// OmittedBytes is how much of the patch the size clamp dropped, 0 when
	// it is complete.
	OmittedBytes int
	Summary      string
	// Continue is the handle for the rest of a patch its budget cut.
	Continue string
}

type EditOp struct {
	Op   string
	Path string
	// ExpectedDigest refuses the whole apply if Path changed since the read
	// that returned this digest.
	ExpectedDigest string
	OldText        string
	NewText        string
	SymbolID       string
	SymbolName     string
	StartLine      int
	EndLine        int
	Anchor         string
	Position       string
}

type EditResponse struct {
	OldRevision  string
	NewRevision  string
	Changed      []string
	AddedLines   int
	RemovedLines int
	// Formatted names files the formatter actually rewrote after the edit,
	// empty when nothing moved. Reported rather than silent: an agent should
	// know its edit was adjusted, and a formatter that keeps firing on the
	// same file is a signal the agent is writing badly-shaped code.
	Formatted   []string
	Diagnostics []Diagnostic
	// Checks names what checked the edited files, so an empty Diagnostics
	// list can be read as "nothing wrong" rather than "nothing looked".
	Checks CheckReport
	Jobs   []string
	// Snippets show the edited region as the file now reads, so the caller
	// need not read it back.
	Snippets []Snippet `json:",omitempty"`
}

type Event struct {
	Type    string
	Entity  string
	Payload map[string]string
}

type EventRecord struct {
	Cursor int64
	Event  Event
}

type EventsResponse struct {
	Cursor int64
	Events []EventRecord
}

type FindBatchResponse struct {
	Responses []FindResponse
}

type FindRequest struct {
	// Dependency looks in that dependency's source instead of the workspace.
	Dependency string
	Query      string
	// Kind narrows to func, type, method, class and so on. Empty matches any.
	Kind     string
	Limit    int
	MaxLines int
	// Budget, in tokens, pages the answer at whole declarations; Continue is
	// a handle from a cut answer.
	Budget   int
	Continue string
}

type FindResponse struct {
	Query      string
	Results    []FindResult
	Total      int
	Summary    string
	Provenance Provenance
	// Continue is the handle for the next page when a budget cut the answer.
	Continue string
}

type FindResult struct {
	SymbolID  string
	Symbol    string
	Kind      string
	Path      string
	StartLine int
	EndLine   int
	Body      string
	// Truncated says the body was cut at MaxLines, so a reader knows the
	// declaration continues rather than assuming it ended there.
	Truncated bool
}

type Freshness struct {
	IndexedCommit string
	HeadCommit    string
	Drifted       bool
	ChangedPaths  []string
	DirtyPaths    []string
	Unknown       string
}

type GrepBatchResponse struct {
	Responses []GrepResponse
}

type GrepMatch struct {
	Path string
	Line int
	Text string
	// After is the trailing context lines, empty when none were requested.
	After []string
}

type GrepRequest struct {
	Query string
	// Dependency searches that dependency's source instead of the workspace,
	// read-only; matches are reported as dep:<name>/<path>.
	Dependency string
	// Regex treats Query as a regular expression instead of a literal.
	Regex bool
	// IgnoreCase folds case on both sides.
	IgnoreCase bool
	// Glob restricts the search by path, matched against both the base name
	// and the full relative path ("*.go", "internal/code/*").
	Glob string
	// Exclude drops paths containing this substring — the `| grep -v testdata`
	// half of the command this replaces.
	Exclude string
	// Context is how many trailing lines to include per match, like `grep -A`.
	Context int
	// Limit caps returned matches. Total still reports the true count.
	Limit int
	// Budget, in tokens, pages the answer at whole matches; the rest is behind
	// a Continue handle. Zero keeps Limit's behaviour.
	Budget int
	// Continue is a handle from a cut answer: the same call's next page.
	Continue string
}

type GrepResponse struct {
	Query      string
	Matches    []GrepMatch
	Total      int
	Files      int
	Truncated  bool
	Summary    string
	Provenance Provenance
	// Continue is the handle for the next page when a budget cut the answer.
	Continue string
}

type HistoryRequest struct {
	Path       string
	SymbolID   string
	SymbolName string
	Limit      int
	// IncludePatch adds the diff hunks. Off by default: the commit list
	// answers "why does this exist", and the patch is the follow-up.
	IncludePatch bool
	// Budget, in tokens, pages the patch at whole lines; Continue is a handle
	// from a cut patch.
	Budget   int
	Continue string
}

type HistoryResponse struct {
	Path         string
	StartLine    int
	EndLine      int
	Commits      []CommitInfo
	Patch        string
	OmittedBytes int
	Summary      string
	// Continue is the handle for the rest of a patch its budget cut.
	Continue string
}

type Impact struct {
	Declarations int
	Callers      int
	CallerFiles  int
	Tests        []string
}

type InsertRequest struct {
	Path             string
	ExpectedRevision string
	ExpectedDigest   string
	Anchor           string
	Position         string
	Text             string
}

type InspectResponse struct {
	Revision  string
	Outline   []OutlineItem
	Sections  OutlineSections
	Source    string
	Freshness Freshness
	Resolve   SymbolResolution
	// Parser reports how the outline was produced. Zero-valued when the
	// response carries no outline (a plain range read, say).
	Parser ParserInfo
	// Range describes a read whose end line was past the end of the file and
	// was clamped, e.g. "lines 190-312 of 312", or a paged read's page. Empty
	// otherwise.
	Range string
	// Continue is the handle for the rest of a read its budget cut.
	Continue string
	// Digest names the file's whole contents at this read. Pass it as an
	// edit's expectedDigest to have the edit refused if the file changed
	// since, by anyone.
	Digest string
}

type JobOutputResponse struct {
	ID        string
	Kind      string
	Status    string
	Summary   string
	RawOutput string
	// OmittedBytes is how many bytes the size clamp dropped from the middle
	// of RawOutput, 0 when it is complete. Present so a reader can tell a
	// short job from a clamped one rather than mistaking a truncated tail
	// for the whole story.
	OmittedBytes int
	// Lines is a paged output's page, "lines 1-212 of 900", and Continue the
	// handle for the rest.
	Lines    string
	Continue string
}

type JobStatusResponse struct {
	ID      string
	Kind    string
	Status  string
	Summary string
}

type LanguageCapability struct {
	Language string
	Files    int
	// Structure is how outlines and find read the language, in provenance
	// words: structural · tree-sitter, or text fallback · text scan.
	Structure Provenance
	// Server is the language server that would start; MissingServer the one
	// Jade looks for when none is installed. Both empty: none is known.
	Server        string
	MissingServer string
	Formatter     string
	// ServerState tells the kinds of missing apart: "not supported" (no
	// server known), "not installed", "failed" (installed, would not start or
	// died), and the working states "not started", "running", "indexing".
	// ServerDetail is the failure or the work in progress.
	ServerState  string
	ServerDetail string
	// References is the provenance a references answer for this language
	// would carry now, from the provider that would answer it. An answer never
	// claims more than this.
	References Provenance
}

type OutlineItem struct {
	ID   string
	Kind string
	Name string
	Path string
	From int
	To   int
}

type OutlineRequest struct {
	Path          string
	IndexedCommit string
}

type OutlineSections struct {
	Imports   []string
	Types     []OutlineItem
	Classes   []OutlineItem
	Functions []OutlineItem
	Methods   []OutlineItem
	Other     []OutlineItem
}

type ParserInfo struct {
	// Language is the detected language, or "" when the extension is unknown.
	Language string
	// Parser is "grammar" or "heuristic".
	Parser string
	// Complete is true only for a real grammar parse. When false, absence of a
	// symbol from the outline is not evidence that the symbol is absent from
	// the file.
	Complete bool
	// Note explains the limitation in the caller's terms when Complete is
	// false, and is empty otherwise.
	Note string
}

type Provenance struct {
	Certainty    string
	Source       string
	Completeness string
}

type ProviderCapability struct {
	Capability string
	Providers  []string
}

type RangeResult struct {
	Path       string
	StartLine  int
	EndLine    int
	TotalLines int
	// Clamped reports that the requested end line was past the end of the
	// file and was reduced to the last line.
	Clamped bool
	Source  string
	Error   string
	// Continue is a read_range handle for the rest of a range its page cut.
	Continue string
}

type ReadRangeRequest struct {
	Path          string
	StartLine     int
	EndLine       int
	IndexedCommit string
	// Budget, in tokens, pages the read at whole lines; Continue is a handle
	// from a cut read.
	Budget   int
	Continue string
}

type ReadRangesRequest struct {
	Ranges []ReadRangeRequest
}

type ReadRangesResponse struct {
	Revision string
	Results  []RangeResult
}

type ReadSymbolRequest struct {
	Path          string
	SymbolID      string
	SymbolName    string
	MaxLines      int
	IndexedCommit string
	// Budget, in tokens, pages the body at whole lines; Continue is a handle
	// from a cut body.
	Budget   int
	Continue string
}

type ReferenceLocation struct {
	Path   string
	Line   int
	Column int
	// Symbol names the referencing declaration. It is the approximate
	// path's substitute for a line number: that path dedupes per calling
	// symbol but cannot report where in the file the call sits, so without
	// a name two distinct callers in one file render identically. Empty for
	// language-server results, where Line and Column already distinguish
	// them.
	Symbol string
	// Confidence is empty for language-server results (the Source field
	// already says they are resolved) and carries the graph edge's
	// confidence for approximate ones, so a caller can tell a same-file
	// match from a repository-wide name guess per reference rather than
	// only per response.
	Confidence string
}

type ReferencesRequest struct {
	Path       string
	SymbolID   string
	SymbolName string
	// Budget, in tokens, pages the answer; Continue is a handle from a cut
	// answer.
	Budget   int
	Continue string
}

type ReferencesResponse struct {
	Query      string
	Source     string
	References []ReferenceLocation
	Summary    string
	Provenance Provenance
	// Continue is the handle for the next page when a budget cut the answer.
	Continue string
}

type RenameRequest struct {
	Path             string
	SymbolID         string
	SymbolName       string
	NewName          string
	ExpectedRevision string
}

type ReplaceFileRequest struct {
	Path    string
	Content string
}

type ReplaceRangeRequest struct {
	Path             string
	ExpectedRevision string
	StartLine        int
	EndLine          int
	NewCode          string
}

type ReplaceSymbolRequest struct {
	SymbolID         string
	NewCode          string
	ExpectedRevision string
}

type ReplaceTextRequest struct {
	Path             string
	ExpectedRevision string
	ExpectedDigest   string
	OldText          string
	NewText          string
}

type RepositoryMapItem struct {
	Path          string
	Score         float64
	EstimatedCost int
	SymbolCount   int
}

type RepositoryMapRequest struct {
	Query     string
	MaxTokens int
}

type RepositoryMapResponse struct {
	Query      string
	MaxTokens  int
	UsedTokens int
	Included   []RepositoryMapItem
	Omitted    []RepositoryMapItem
	Summary    string
	Provenance Provenance
}

type RetrievalCandidate struct {
	Path          string
	Symbol        string
	Reason        string
	Score         float64
	EstimatedCost int
	Kind          string
	StartLine     int
	EndLine       int
}

type RetrievalDocument struct {
	Path      string
	Symbol    string
	Kind      string
	Terms     []string
	Score     float64
	StartLine int
	EndLine   int
}

type RetrievalIndex struct {
	Documents []RetrievalDocument
}

type RetrievalRequest struct {
	Query     string
	MaxTokens int
}

type RetrievalResponse struct {
	Query          string
	MaxTokens      int
	UsedTokens     int
	Candidates     []RetrievalCandidate
	Summary        string
	BudgetExceeded bool
	Provenance     Provenance
}

type RevertRequest struct {
	CheckpointID string
}

type RunCommandRequest struct {
	// Name of the declared command. Empty lists what is declared rather than
	// erroring — an agent that does not know the vocabulary should be able to
	// ask with the tool it already has.
	Name string
	// Wait blocks for the result instead of returning a job ID to poll.
	Wait bool
	// TimeoutSeconds bounds the wait. Ignored when Wait is false.
	TimeoutSeconds int
}

type RunCommandResponse struct {
	Name string
	// Run is the shell string that actually ran, echoed back so the caller can
	// see what a name resolved to without opening the registry file.
	Run     string
	JobID   string
	Outcome ValidationOutcome
	Status  string
	Passed  bool
	Summary string
	// Available is populated when Name was empty, and is the answer to "what
	// can I run here".
	Available []DeclaredCommand
}

type RunTestsRequest struct {
	Scope string
	File  string
	Test  string
	// Wait blocks for the result instead of returning a job ID to poll.
	// The async model is right for long runs; making a short scoped run
	// cost two calls plus a poll is why the native test command wins.
	Wait bool
	// TimeoutSeconds bounds the wait. Ignored when Wait is false.
	TimeoutSeconds int
}

type RunTestsResponse struct {
	JobID string
	// Outcome is the verdict from the closed set; Passed is true exactly when
	// it is OutcomePassed. Status is the job's own state, kept for JSON
	// readers.
	Outcome ValidationOutcome
	Status  string
	Passed  bool
	Summary string
}

type SearchHit struct {
	Path      string
	Symbol    string
	Reason    string
	Score     float64
	Snippet   string
	Kind      string
	StartLine int
	EndLine   int
}

type SearchNudgeRequest struct {
	Command        string
	OutputLength   int
	FirstInSession bool
}

type SearchNudgeResponse struct {
	Footer string
	Nudged bool
}

type SearchRequest struct {
	Query string
	Mode  string
	Limit int
}

type SearchResponse struct {
	Query      string
	Mode       string
	Hits       []SearchHit
	Provenance Provenance
}

type Snippet struct {
	Path      string
	StartLine int
	EndLine   int
	Source    string
}

type SymbolCandidate struct {
	ID   string
	Kind string
	Path string
	Line int
	// Signature is the candidate's declaration line, trimmed. It is the field
	// that actually disambiguates: the receiver and parameters are exactly
	// what a caller is choosing between.
	Signature string
}

type SymbolChange struct {
	Path   string
	Symbol string
	Kind   string
	Change SymbolChangeKind
}

type SymbolChangeKind string

type SymbolGraph struct {
	Nodes []SymbolGraphNode
	Edges []SymbolGraphEdge
	// Source is "approximate" while the graph is built from tree-sitter and
	// name matching, and "lsp" once a language server produces it.
	Source string
	// Limitations spells out what this graph provably cannot see. It is
	// carried in the response rather than left to documentation so the
	// caveat travels with the data: an approximate graph must never be
	// presented as authoritative IDE-grade semantics.
	Limitations []string
}

type SymbolGraphEdge struct {
	From string
	To   string
	Kind string
	// Confidence records how this edge was resolved (see Edge* constants),
	// so a caller can tell a same-file match from a repo-wide name guess
	// rather than treating every edge as equally authoritative.
	Confidence string
}

type SymbolGraphNode struct {
	ID   string
	Path string
	Name string
	Kind string
}

type SymbolResolution struct {
	Status     SymbolResolutionStatus
	Query      string
	SelectedID string
	// CandidateIDs is retained alongside Candidates: it is the machine-usable
	// form, and a caller that already parses it should not have to change.
	CandidateIDs []string
	Candidates   []SymbolCandidate
}

type SymbolResolutionStatus string

type Target struct {
	Type     TargetType
	Path     string
	SymbolID string
	Revision string
	Start    int
	End      int
}

type TargetType string

type TelemetryFailure struct {
	Outcome string
	Count   int
}

type TelemetryRequest struct {
	// Reset clears the log instead of summarizing it, so a measurement run can
	// start from a known state.
	Reset bool
	// Catalog is every tool the server offers, so tools never called can be
	// named. The transport fills it; callers do not.
	Catalog []string
}

type TelemetryResponse struct {
	Tools     []TelemetryToolStats
	Fallbacks []TelemetryFailure
	// Switches, Retries and NeverCalled are the tool-confusion report: an
	// inspect tool followed by a different one on the same target, a tool
	// retried after ambiguous or not_found, and tools with no calls.
	Switches    []TelemetrySwitch
	Retries     []TelemetryRetry
	NeverCalled []string
	TotalCalls  int
	TotalErrors int
	TotalBytes  int64
	Path        string
	Cleared     bool
	Summary     string
}

type TelemetryRetry struct {
	Tool  string
	After string
	Count int
}

type TelemetrySwitch struct {
	From  string
	To    string
	Count int
}

type TelemetryToolStats struct {
	Tool     string
	Calls    int
	Errors   int
	Bytes    int64
	AvgMS    int64
	MaxMS    int64
	Failures []TelemetryFailure
}

type ValidationCapability struct {
	Kind    string
	Command string
}

type ValidationOutcome string

type ValidationRun struct {
	Kind     string
	Outcome  string
	Revision string
}

type WorkspaceTreeEntry struct {
	Path  string
	IsDir bool
}

type WorkspaceTreeRequest struct {
	MaxEntries int
	// Budget, in tokens, pages the listing at whole entries; Continue is a
	// handle from a cut listing.
	Budget   int
	Continue string
}

type WorkspaceTreeResponse struct {
	Root      string
	Entries   []WorkspaceTreeEntry
	Truncated bool
	Summary   string
	// Page names a paged listing's entries, "entries 1-180 of 900 ·
	// continue=c4", and Continue is the handle for the rest.
	Page     string
	Continue string
}