Documentation
¶
Overview ¶
Package mcpmeta hints.go — calibrated next-call hint helpers.
Calibration philosophy (CLAUDE.md mcpmeta rule):
"Hint populated only when a clear next-call is cheap and obvious. A noisy hint trains the calling agent to ignore the field."
All helpers default to "" (silent) and only fire on tight conditions.
Package mcpmeta provides a small response-envelope helper used by MCP tools to carry timing, optional next-call hints, and optional staleness warnings without forcing every tool to repeat boilerplate.
The envelope is intentionally minimal: a tool may emit zero or more fields. Empty fields are omitted from the JSON payload so the caller sees only what is signal.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractSymbolFromHit ¶
ExtractSymbolFromHit returns the identifier from a declaration-style match line like "foo.go:42:func Bar(...)". Returns "" for non-declaration lines (call sites, string literals, comments, control flow) so HintAfterCodeSearch stays silent rather than suggesting a bogus understand(symbol=...) call.
func HintAfterCodeSearch ¶
HintAfterCodeSearch returns a calibrated chaining hint for any single-symbol-style tool response, or "" when no hint is warranted.
Used by: tool_code_search.go, tool_symbol_search.go, tool_semantic_search.go. The same calibration rules apply across all three: silent on explain-class queries (EN + RU), silent on zero-or-many hits, and silent when no Go-style declaration could be extracted from the hit.
Rules:
- explain-class query (why|how|describe|explain|почему|как|опиши|объясни|расскажи) → silent
- exactly 1 hit → suggest understand(symbol=...) when an identifier was extracted
- 0 or >1 hits → silent (too many to pin one symbol)
func HintAfterDeadCode ¶
HintAfterDeadCode returns a hint to call get_file_health when the worst offender file has more dead symbols than the hotspot threshold, or "" otherwise.
func LiveHead ¶
LiveHead returns the on-disk HEAD SHA for a git repo without spawning git.
It handles both primary checkouts (where .git is a directory) and linked worktrees created by "git worktree add" (where .git is a file containing a "gitdir: <path>" pointer). The algorithm:
- Resolve the real gitdir via gitDir (file or directory).
- Read <gitdir>/HEAD — if detached, return the SHA directly.
- If symbolic ("ref: refs/…"), look up the loose ref file under gitdir.
- Fall back to packed-refs from commonDir(gitdir), since worktrees share the main repo's packed refs via the commondir pointer.
Returns "" + error if none of the above resolves.
Types ¶
type Envelope ¶
type Envelope struct {
DurationMS int64 `json:"duration_ms"`
Hint string `json:"hint,omitempty"`
StaleWarning string `json:"stale_warning,omitempty"`
IndexedSHA string `json:"indexed_sha,omitempty"`
LiveSHA string `json:"live_sha,omitempty"`
}
Envelope is the meta block attached to a tool response.
Empty optional fields are omitted from the JSON payload via the `omitempty` tags on Hint / StaleWarning / IndexedSHA / LiveSHA, so the caller sees only signal. DurationMS is always populated on the Go struct (clamped to >= 1 by Wrap to enforce the "always populated" contract) — but that is a struct-level guarantee, not a wire one: cmd/go-code's response-footer renderer (appendMetaFooter) omits the `<!-- meta: ... -->` footer entirely when Hint and StaleWarning are both empty, so a bare duration_ms with no hint and no staleness never actually reaches the consumer — duration-only telemetry has zero analytic value to an agent that can't act on it.
Convention:
- DurationMS is always populated on the struct, but is rendered to the consumer only when paired with a Hint or StaleWarning — a bare duration is suppressed at the response-footer layer (cmd/go-code).
- Hint is populated only when a clear next-call is cheap and obvious. A noisy hint trains the calling agent to ignore the field.
- StaleWarning is populated only when the indexed commit no longer matches the on-disk HEAD. Silence is the calibrated signal.
func WithFreshness ¶
WithFreshness annotates an envelope with a staleness warning when the caller-supplied indexedSHA (the SHA the embed pipeline indexed, which is the MAIN-BRANCH tip) no longer matches the repo's current main-branch tip. Freshness means "has main advanced past the index?", NOT "does your working tree differ from the index" — the index is keyed on main, so comparing against the working-tree HEAD would false-warn on every feature branch. Silent on match.
Source Files