protocol

type ApplyRequest ¶

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
}

ApplyRequest performs several edits as one unit.

Deliberately a declarative pipeline and not a scripting DSL: it cannot loop, branch, run arbitrary commands, or read one result to choose the next edit. An arbitrary step-graph executor would be bash with extra syntax — guardrails could not inspect intent, and telemetry would degrade from "17 anchored edits, 2 ambiguous-anchor failures" to "someone ran a script". An agent that needs to decide mid-sequence makes two Apply calls and thinks in between, which is observable.

type ApplyResponse ¶

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
}

ApplyResponse reports the whole unit's outcome.

type ChangedFile ¶

type ChangedFile struct {
	Path    string
	Added   int
	Removed int
}

ChangesResponse returns tracked changed paths and active workspace revision. ChangedFile is one file's added/removed line counts in a numstat-style diff.

type ChangesResponse ¶

type ChangesResponse struct {
	Revision string
	// 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 ¶ added in v0.0.3

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

CheckReport says which checkers ran over edited files and which files went unchecked, with the reason.

type CheckRequest ¶

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
}

CheckRequest runs a validation command on demand — the caller-triggered counterpart to the jobs an edit spawns automatically. Kind is "build", "typecheck" or "tests"; the actual command comes from the same discovery path (Makefile target, npm script, cargo, then the language default).

type CheckResponse ¶

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
}

CheckResponse carries the outcome. Outcome is running when the check was not waited for, and timed out when the wait ran out; JobID is how to follow up on either. A dry run has no outcome.

type CheckpointRequest ¶

type CheckpointRequest struct {
	Note string
}

CheckpointRequest creates a named snapshot of workspace state.

type CheckpointResponse ¶

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
}

CheckpointResponse describes a created or restored workspace checkpoint.

type CommitInfo ¶

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

CommitInfo is one commit that touched a symbol's lines.

type ContextRequest ¶

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

ContextRequest asks jade to assemble everything needed to act on a symbol. Purpose selects which sections are worth their tokens: "modify" (default, widest), "understand", "debug", "test".

type ContextResponse ¶

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
}

ContextResponse is docs/scope.md §14's assembled working set for one symbol — implementation, related types, callers, tests, diagnostics and recent change in a single call instead of four round trips.

The *Count fields report true totals; the accompanying slices are capped. A cap costs detail, never accuracy.

type CreateFileRequest ¶

type CreateFileRequest struct {
	Path    string
	Content string
}

CreateFileRequest creates a brand-new file — docs/scope.md §29's MVP editing operation, alongside DeleteFileRequest, that had no implementation at all until this task.

type DeclareCommandRequest ¶

type DeclareCommandRequest struct {
	Name        string
	Run         string
	Description string
	// Remove deletes the named command instead of declaring it.
	Remove bool
}

DeclareCommandRequest adds or replaces a command in the repo registry.

Declaration is deliberately a separate operation from invocation: it is the privileged one. The shell string is written exactly once, into a file a human can read and a diff will show.

type DeclareCommandResponse ¶

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
}

DeclareCommandResponse confirms what was written and where.

type DeclaredCommand ¶

type DeclaredCommand struct {
	Name        string
	Run         string
	Description string
}

DeclaredCommand is one entry of the repo command registry.

type DeleteFileRequest ¶

type DeleteFileRequest struct {
	Path string
}

DeleteFileRequest removes a file.

type DeleteSymbolRequest ¶

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

DeleteSymbolRequest removes one declaration. The range comes from jade's own parse, so the caller never has to find the closing brace itself — the hand-rolled brace scanning that motivated this tool.

type Diagnostic ¶

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

Diagnostic is a normalized validation message.

type DiagnosticLevel ¶

type DiagnosticLevel string

DiagnosticLevel normalizes error severities from language tools.

const (
	DiagnosticError   DiagnosticLevel = "error"
	DiagnosticWarning DiagnosticLevel = "warning"
	DiagnosticInfo    DiagnosticLevel = "info"
)

type DiffRequest ¶

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
}

DiffRequest asks for the actual patch text. An empty Target diffs the whole working tree; a path diffs just that file.

type DiffResponse ¶

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
}

DiffResponse carries real hunk content — docs/scope.md §22's diff(target?), the "what changed" companion to ChangesResponse's "how much changed".

type EditOp ¶

type EditOp struct {
	Op         string
	Path       string
	OldText    string
	NewText    string
	SymbolID   string
	SymbolName string
	StartLine  int
	EndLine    int
	Anchor     string
	Position   string
}

EditOp is one step in an ApplyRequest. Op selects which fields matter: replace_text (OldText/NewText), replace_range (StartLine/EndLine/NewText), replace_symbol (SymbolID or SymbolName, NewText), delete_symbol (SymbolID or SymbolName), insert (Position, optional Anchor, NewText).

type EditResponse ¶

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
}

EditResponse is the baseline shape for mutation feedback.

type Event ¶

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

Event is a normalized asynchronous status signal.

type EventRecord ¶

type EventRecord struct {
	Cursor int64
	Event  Event
}

EventRecord contains one asynchronous event in the event stream.

type EventsResponse ¶

type EventsResponse struct {
	Cursor int64
	Events []EventRecord
}

EventsResponse returns a page of events and the latest cursor.

type FindBatchResponse ¶ added in v0.0.3

type FindBatchResponse struct {
	Responses []FindResponse
}

FindBatchResponse answers find with several names at once: one FindResponse per name, in the order asked.

Callers writing types against another language's structs usually need two or three declarations together, and sent them as parallel calls — each paying the per-call overhead for what is one question.

type FindRequest ¶

type FindRequest struct {
	Query string
	// Kind narrows to func, type, method, class and so on. Empty matches any.
	Kind     string
	Limit    int
	MaxLines int
}

FindRequest locates declarations by name and returns their bodies in one call — the fused search-and-read that `grep -n "func X" -A 30` provides and jade previously needed two calls (outline, then read_symbol) to match.

type FindResponse ¶

type FindResponse struct {
	Query   string
	Results []FindResult
	Total   int
	Summary string
}

FindResponse returns the matches. Total is the true count even when Results was capped by Limit.

type FindResult ¶

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
}

FindResult is one matching declaration, with its source.

type Freshness ¶

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

Freshness describes whether index data may be stale relative to workspace state.

type GrepMatch ¶

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

GrepMatch is one matching line and its trailing context.

type GrepRequest ¶

type GrepRequest struct {
	Query 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
}

GrepRequest is literal or regex text search across the workspace.

Distinct from SearchRequest, which ranks symbols by name similarity and therefore cannot answer "what reads this struct field", "where is this string literal", or any query with a negative filter. See Index.Grep.

type GrepResponse ¶

type GrepResponse struct {
	Query     string
	Matches   []GrepMatch
	Total     int
	Files     int
	Truncated bool
	Summary   string
}

GrepResponse carries the matches. Total is the true number found even when Limit cut the returned set: a cap must cost detail, never accuracy.

type HistoryRequest ¶

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
}

HistoryRequest asks which commits touched a symbol — docs/scope.md §18's history(symbol) instead of `git log -p` over a whole file.

type HistoryResponse ¶

type HistoryResponse struct {
	Path         string
	StartLine    int
	EndLine      int
	Commits      []CommitInfo
	Patch        string
	OmittedBytes int
	Summary      string
}

HistoryResponse lists the commits that touched one symbol's line range.

type InsertRequest ¶ added in v0.0.2

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

InsertRequest adds text without replacing anything. Anchor follows ReplaceTextRequest's rule — exactly one match or refuse — because inserting beside an arbitrary one of several matches silently places code somewhere the caller never looked. An empty Anchor appends to the end of the file.

type InspectResponse ¶

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". Empty otherwise.
	Range string
}

InspectResponse returns a scoped code view plus freshness metadata.

type JobOutputResponse ¶

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
}

JobOutputResponse returns raw output for explicit expansion requests.

type JobStatusResponse ¶

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

JobStatusResponse returns asynchronous validation job status.

type OutlineItem ¶

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

OutlineItem is a declaration-level view used for progressive disclosure.

type OutlineRequest ¶

type OutlineRequest struct {
	Path          string
	IndexedCommit string
}

OutlineRequest asks for declaration-level structure for a file.

type OutlineSections ¶

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

OutlineSections groups outline information by semantic category.

type ParserInfo ¶

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
}

ParserInfo says how a file's symbols were obtained, and — crucially — whether the answer can be trusted to be complete.

jade ships tree-sitter grammars for Go, TypeScript, TSX and Rust. Everything else falls back to a line-oriented heuristic that recognises some declaration shapes and misses others. That fallback is fine; presenting its output as if it were a grammar parse is not. Found live against a Python repository, where outline returned the file's one class and silently omitted its one function — an agent reading that concludes the function does not exist, which is a worse outcome than being told the language is unsupported.

type RangeResult ¶ added in v0.0.3

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
}

RangeResult is one range of a multi-range read. A range that cannot be read carries Error and does not fail the others: one mistyped path should not discard four good reads.

type ReadRangeRequest ¶

type ReadRangeRequest struct {
	Path          string
	StartLine     int
	EndLine       int
	IndexedCommit string
}

ReadRangeRequest reads an arbitrary line range — the read-side escape hatch for content that can't be addressed by symbol (comments, config files, generated code with no clean symbol boundaries), mirroring ReplaceRangeRequest's write-side equivalent.

type ReadRangesRequest ¶ added in v0.0.3

type ReadRangesRequest struct {
	Ranges []ReadRangeRequest
}

ReadRangesRequest reads several ranges, possibly from several files, in one call.

type ReadRangesResponse ¶ added in v0.0.3

type ReadRangesResponse struct {
	Revision string
	Results  []RangeResult
}

ReadRangesResponse is the answer to a multi-range read.

type ReadSymbolRequest ¶

type ReadSymbolRequest struct {
	Path          string
	SymbolID      string
	SymbolName    string
	MaxLines      int
	IndexedCommit string
}

ReadSymbolRequest asks for a bounded symbol body.

type ReferenceLocation ¶

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
}

ReferenceLocation is one place a symbol is referenced. Line/Column are 1-based when they come from a language server; an approximate (name-matched) answer reports 0 for both rather than guessing.

type ReferencesRequest ¶

type ReferencesRequest struct {
	Path       string
	SymbolID   string
	SymbolName string
}

ReferencesRequest asks where a symbol is referenced.

type ReferencesResponse ¶

type ReferencesResponse struct {
	Query      string
	Source     string
	References []ReferenceLocation
	Summary    string
}

ReferencesResponse carries the reference set plus, critically, which engine produced it: "lsp" (compiler-resolved, exact) or "approximate" (name-matched call graph, with documented blind spots). A caller must be able to tell these apart — they are not the same claim.

type RenameRequest ¶

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

RenameRequest renames a symbol across the whole repository.

type ReplaceFileRequest ¶

type ReplaceFileRequest struct {
	Path    string
	Content string
}

ReplaceFileRequest overwrites an existing file's entire contents.

Symmetric with CreateFileRequest: that one refuses when the file exists, this one refuses when it does not. Choosing the tool is what makes the destructive case explicit, so neither needs a force flag.

type ReplaceRangeRequest ¶

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

ReplaceRangeRequest replaces arbitrary source lines at an expected revision.

type ReplaceSymbolRequest ¶

type ReplaceSymbolRequest struct {
	SymbolID         string
	NewCode          string
	ExpectedRevision string
}

ReplaceSymbolRequest replaces a symbol implementation.

type ReplaceTextRequest ¶

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

ReplaceTextRequest replaces an exact, unique string. Anchoring by text rather than by line number means a sequence of edits does not invalidate its own addresses — the reason this exists alongside ReplaceRangeRequest.

type RepositoryMapItem ¶

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

RepositoryMapItem is a single file candidate in a repo-wide relevance map.

type RepositoryMapRequest ¶

type RepositoryMapRequest struct {
	Query     string
	MaxTokens int
}

RepositoryMapRequest asks JADE to rank the most relevant files and symbols for a query while staying under a context budget.

type RepositoryMapResponse ¶

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

RepositoryMapResponse returns the included files and the omitted remainder.

type RetrievalCandidate ¶

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

RetrievalCandidate is a single file/symbol candidate chosen under a token budget.

type RetrievalDocument ¶

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

RetrievalDocument captures tokenized content for one file or symbol in the retrieval index.

type RetrievalIndex ¶

type RetrievalIndex struct {
	Documents []RetrievalDocument
}

RetrievalIndex stores the cached candidate documents used to score queries across a workspace.

type RetrievalRequest ¶

type RetrievalRequest struct {
	Query     string
	MaxTokens int
}

RetrievalRequest asks JADE to choose the most relevant symbols/files under a token budget.

type RetrievalResponse ¶

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

RetrievalResponse returns budget-aware candidate paths for a task.

type RevertRequest ¶

type RevertRequest struct {
	CheckpointID string
}

RevertRequest restores workspace state to a checkpoint.

type RunCommandRequest ¶

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
}

RunCommandRequest invokes one command from the repo's declared registry.

It carries a Name, never a shell string. That is the whole guardrail: a named command is enumerable for telemetry, reviewable because it was declared once into a file that shows up in a diff, and teachable because an unknown name can answer with the list of declared ones. Accepting a shell string here would make this bash with extra steps.

type RunCommandResponse ¶

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
}

RunCommandResponse carries a command's outcome, or — when the request named no command — the list of commands that are declared.

type RunTestsRequest ¶

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
}

RunTestsRequest starts a scoped test run — "all" (whole repo), "file" (the package containing one file), "test" (one test name across all packages), or "changed" (packages containing any currently-changed file). Deliberately conservative per docs/scope.md §33's own guidance, not call-graph-precise affected-test prediction.

type RunTestsResponse ¶

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
}

RunTestsResponse carries the scoped run's outcome. When the caller waited (the default), Status/Passed/Summary hold the verdict; otherwise JobID is how to follow up via job_status/job_output.

type SearchHit ¶

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

SearchHit is one candidate returned by a hybrid search stack.

type SearchNudgeRequest ¶

type SearchNudgeRequest struct {
	Command        string
	OutputLength   int
	FirstInSession bool
}

SearchNudgeRequest asks jade whether a shell search-style command (a raw grep/rg/ag/ack/find/fd invocation the harness already ran) warrants appending index hits below its own output — piggybacking a better answer onto the tool call an agent already chose, rather than trying to make it choose differently. jade cannot observe the tool call itself (it's an MCP server, not the harness); a harness integration supplies Command and the surrounding context after running it.

type SearchNudgeResponse ¶

type SearchNudgeResponse struct {
	Footer string
	Nudged bool
}

SearchNudgeResponse carries the footer to append (if any). Nudged=false means: append nothing, the original output stands as-is.

type SearchRequest ¶

type SearchRequest struct {
	Query string
	Mode  string
	Limit int
}

SearchRequest asks JADE to rank likely symbols/files for a query.

type SearchResponse ¶

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

SearchResponse returns exact/symbol/semantic ranked hits for a query.

type SymbolCandidate ¶

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
}

SymbolCandidate is one possible match for an ambiguous symbol name, with enough detail to choose between them without another call.

Bare IDs were not enough. Two methods named Put in the same file differ only by receiver, and `store.go::Put@48` versus `store.go::Put@72` tells a caller nothing about which is which — so they had to spend a turn fetching one to find out. Measured: that round trip is why jade lost a head-to-head against grep on a real repository (1.36x tokens, 3 calls against 2).

type SymbolChange ¶

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

SymbolChange names one symbol that moved — docs/scope.md §13's "SessionManager.refreshSession modified", the question an agent returning to a file actually has, as opposed to how many lines moved.

type SymbolChangeKind ¶

type SymbolChangeKind string

ChangesResponse returns tracked changed paths and active workspace revision. SymbolChangeKind says how a symbol changed between two versions of a file.

const (
	SymbolAdded    SymbolChangeKind = "added"
	SymbolModified SymbolChangeKind = "modified"
	SymbolRemoved  SymbolChangeKind = "removed"
)

type SymbolGraph ¶

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
}

SymbolGraph holds a lightweight call/reference graph for retrieval and impact analysis.

type SymbolGraphEdge ¶

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
}

SymbolGraphEdge is a relationship between symbols, such as calls or references.

type SymbolGraphNode ¶

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

SymbolGraphNode is a symbol in the dependency graph.

type SymbolResolution ¶

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
}

SymbolResolution captures selection outcome and candidates.

type SymbolResolutionStatus ¶

type SymbolResolutionStatus string

SymbolResolutionStatus communicates how symbol selection was resolved.

const (
	ResolutionExact     SymbolResolutionStatus = "exact"
	ResolutionAmbiguous SymbolResolutionStatus = "ambiguous"
	ResolutionNotFound  SymbolResolutionStatus = "not_found"
)

type Target ¶

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

Target is the generic locator used by inspect, modify, validate, and state APIs.

type TargetType ¶

type TargetType string

TargetType identifies what a request points to.

const (
	TargetWorkspace TargetType = "workspace"
	TargetFile      TargetType = "file"
	TargetSymbol    TargetType = "symbol"
	TargetRange     TargetType = "range"
)

type TelemetryFailure ¶

type TelemetryFailure struct {
	Outcome string
	Count   int
}

TelemetryFailure is one failure class and its count.

type TelemetryRequest ¶

type TelemetryRequest struct {
	// Reset clears the log instead of summarizing it, so a measurement run can
	// start from a known state.
	Reset bool
}

TelemetryRequest asks for the recorded tool-usage summary.

type TelemetryResponse ¶

type TelemetryResponse struct {
	Tools       []TelemetryToolStats
	Fallbacks   []TelemetryFailure
	TotalCalls  int
	TotalErrors int
	TotalBytes  int64
	Path        string
	Cleared     bool
	Summary     string
}

TelemetryResponse carries the usage summary.

Fallbacks is the headline: each entry is a class of tool failure that plausibly ended with the caller running a shell command instead, which is the thing jade's whole design bet is about.

type TelemetryToolStats ¶

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

TelemetryToolStats aggregates one tool's recorded calls.

type ValidationOutcome ¶ added in v0.0.3

type ValidationOutcome string

ValidationOutcome is how a check, test run or declared command ended.

The set is closed. Before it, outcomes were free strings beside a Passed bool, and a waited check that ran out of time read "running" — the same as a call that never asked to wait. A caller, the renderer and telemetry can now switch on the outcome exhaustively, and only OutcomePassed is a pass: nothing unavailable, unfinished or killed can render or count as one.

const (
	// OutcomePassed: the command finished, exited zero and reported no
	// failure.
	OutcomePassed ValidationOutcome = "passed"
	// OutcomeFailed: the command finished and reported broken code — a
	// non-zero exit or failure output. A verdict, not a Jade failure.
	OutcomeFailed ValidationOutcome = "failed"
	// OutcomeUnavailable: nothing was validated. No command was discovered
	// for this workspace, or the tool the command runs is not installed.
	OutcomeUnavailable ValidationOutcome = "unavailable"
	// OutcomeRunning: the caller chose not to wait. Poll the job.
	OutcomeRunning ValidationOutcome = "running"
	// OutcomeTimedOut: the caller waited and the command did not finish in
	// time — it may still be running, poll the job — or it was killed for
	// exceeding its own timeout.
	OutcomeTimedOut ValidationOutcome = "timed out"
)

type WorkspaceTreeEntry ¶

type WorkspaceTreeEntry struct {
	Path  string
	IsDir bool
}

WorkspaceTreeEntry is one file or directory in a plain structural listing.

type WorkspaceTreeRequest ¶

type WorkspaceTreeRequest struct {
	MaxEntries int
}

WorkspaceTreeRequest asks for a plain directory/file structure listing — orientation ("what does this repo look like"), not relevance ranking.

type WorkspaceTreeResponse ¶

type WorkspaceTreeResponse struct {
	Root      string
	Entries   []WorkspaceTreeEntry
	Truncated bool
	Summary   string
}

WorkspaceTreeResponse returns a bounded, sorted structural listing.