homegraph 1.5.2 → 1.5.4

package/dist/mcp/explore-dedup.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Cross-call source dedup for `homegraph_explore` (CG-18).
+ *
+ * The session record (CG-17) knows what earlier calls already sent. This module
+ * is the algebra that turns that record into a decision for the call being
+ * rendered: of the line ranges this call WOULD emit, which does the agent
+ * already hold, and what is genuinely new.
+ *
+ * Three rules shape everything here, and all three come from the same place —
+ * an insufficient-feeling response is what sends an agent to Read, and one or
+ * two of those early in a session teach it to abandon homegraph entirely
+ * (CLAUDE.md):
+ *
+ *   1. **A pointer, never a bare omission.** Removed source is replaced by a
+ *      back-reference naming the file, the symbols, and the line span, worded so
+ *      it is unmistakable that the source was already delivered IN THIS
+ *      CONVERSATION and is still current. Silence reads as "homegraph didn't
+ *      find it".
+ *   2. **Only prove-it dedup.** A span is withheld only when the file's bytes
+ *      are byte-identical to what was served (a content fingerprint, not an
+ *      mtime and not the index's drift flag). An edit between calls means the
+ *      agent's copy is wrong, so the source is re-emitted in full.
+ *   3. **Cut chunks, not slivers.** Only a covered run of at least
+ *      {@link EXPLORE_DEDUP.MIN_COVERED_LINES} lines is worth replacing. Below
+ *      that the pointer costs more than the source, and shattering a block into
+ *      one-line fragments produces exactly the ragged output that reads as a
+ *      failure. Everything not withheld is emitted — where the algebra is
+ *      unsure, it re-serves.
+ *
+ * Which way to be wrong, restated for this layer: re-serving something the agent
+ * has is a few hundred wasted chars; withholding something it never saw is a
+ * Read. Every threshold below leans to the first.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPLORE_DEDUP = void 0;
+exports.exploreDedupEnabled = exploreDedupEnabled;
+exports.fileFingerprint = fileFingerprint;
+exports.mergeRanges = mergeRanges;
+exports.intersectRange = intersectRange;
+exports.subtractRange = subtractRange;
+exports.dedupeRange = dedupeRange;
+exports.servedRangesForFile = servedRangesForFile;
+exports.formatSpans = formatSpans;
+exports.formatBackReference = formatBackReference;
+exports.symbolsInSpans = symbolsInSpans;
+const crypto_1 = require("crypto");
+exports.EXPLORE_DEDUP = {
+    /**
+     * Shortest already-served run that may be replaced by a back-reference.
+     *
+     * Sized against what dedup is actually FOR — a later call re-serving a whole
+     * method or file it already sent. A shorter covered run is either a signature
+     * line in a skeleton render or the ±3 lines of context padding around a
+     * cluster, and swapping either for a pointer trades bytes for noise: the
+     * pointer sentence is itself ~140 chars, so under this length dedup would
+     * make the response BIGGER while making it read as full of holes.
+     */
+    MIN_COVERED_LINES: 8,
+    /**
+     * Below this many chars of NEW source, a file's remainder is folded into its
+     * back-reference instead of being fenced on its own.
+     *
+     * The shape this exists for, seen on the CG-17 fixture: a third call whose
+     * only unheld line was the file's trailing blank one, rendered as a code fence
+     * containing `228\t`. A fence holding two lines of nothing reads as a broken
+     * response, and reading as broken is the expensive failure — it is the thing
+     * that sends an agent to Read and keeps it there. So a remainder this small is
+     * dropped rather than shown. It is the one place this module withholds
+     * something the agent has not seen, and it is bounded to ~two lines that sit
+     * directly against source the agent does hold; the file is still named, with
+     * its symbols, so one follow-up explore fetches it whole.
+     */
+    MIN_DELTA_CHARS: 160,
+    /** Line spans named in one pointer before it summarises the rest. */
+    MAX_SPANS_IN_POINTER: 4,
+    /** Symbols named in one pointer before it summarises the rest. */
+    MAX_SYMBOLS_IN_POINTER: 5,
+};
+const OFF = new Set(['0', 'false', 'off', 'no']);
+/**
+ * Kill switch: `HOMEGRAPH_EXPLORE_DEDUP=0` renders every call as if the session
+ * had no history. Read per call (not memoized) so a test can toggle it.
+ */
+function exploreDedupEnabled() {
+    const raw = process.env.HOMEGRAPH_EXPLORE_DEDUP;
+    if (raw === undefined)
+        return true;
+    return !OFF.has(raw.trim().toLowerCase());
+}
+/**
+ * Identity of the bytes a call served for one file.
+ *
+ * This — not the index's drift flag — is what gates dedup. `isFileStaleOnDisk`
+ * answers "did the file change since the last INDEX SYNC", which is a different
+ * question with a different answer: two calls inside one drift window served the
+ * same current bytes (dedup is correct), while a file edited and re-synced
+ * between two calls is never "stale" and yet the agent's copy is now wrong
+ * (dedup would be actively harmful). Length is prefixed so a hash prefix
+ * collision cannot alias two files of different size.
+ */
+function fileFingerprint(content) {
+    return `${content.length}:${(0, crypto_1.createHash)('sha1').update(content).digest('hex').slice(0, 16)}`;
+}
+/** Sort + merge overlapping/adjacent spans into the smallest equivalent set. */
+function mergeRanges(ranges) {
+    const valid = ranges
+        .filter((r) => Number.isFinite(r.start) && Number.isFinite(r.end) && r.end >= r.start && r.start >= 1)
+        .map((r) => ({ start: Math.floor(r.start), end: Math.floor(r.end) }))
+        .sort((a, b) => a.start - b.start || a.end - b.end);
+    const out = [];
+    for (const r of valid) {
+        const last = out[out.length - 1];
+        if (last && r.start <= last.end + 1)
+            last.end = Math.max(last.end, r.end);
+        else
+            out.push({ ...r });
+    }
+    return out;
+}
+/** The parts of `range` that `served` covers. */
+function intersectRange(range, served) {
+    const out = [];
+    for (const s of served) {
+        const start = Math.max(range.start, s.start);
+        const end = Math.min(range.end, s.end);
+        if (end >= start)
+            out.push({ start, end });
+    }
+    return mergeRanges(out);
+}
+/** The parts of `range` that `cut` does NOT cover. */
+function subtractRange(range, cut) {
+    const out = [];
+    let cursor = range.start;
+    for (const c of mergeRanges(cut)) {
+        if (c.end < cursor)
+            continue;
+        if (c.start > range.end)
+            break;
+        if (c.start > cursor)
+            out.push({ start: cursor, end: Math.min(c.start - 1, range.end) });
+        cursor = Math.max(cursor, c.end + 1);
+        if (cursor > range.end)
+            break;
+    }
+    if (cursor <= range.end)
+        out.push({ start: cursor, end: range.end });
+    return out;
+}
+/**
+ * Split one intended span into what to emit and what to point back at.
+ *
+ * Covered runs shorter than {@link EXPLORE_DEDUP.MIN_COVERED_LINES} are left in
+ * the emit set on purpose (rule 3 above) — so a span the agent holds "almost
+ * all of" still comes back whole rather than as a stutter of fragments around
+ * pointers.
+ */
+function dedupeRange(range, served, minCovered = exports.EXPLORE_DEDUP.MIN_COVERED_LINES) {
+    if (served.length === 0 || range.end < range.start)
+        return { emit: [range], covered: [] };
+    const covered = intersectRange(range, served).filter((r) => r.end - r.start + 1 >= minCovered);
+    if (covered.length === 0)
+        return { emit: [range], covered: [] };
+    return { emit: subtractRange(range, covered), covered };
+}
+/**
+ * Every line span this session has already served for one file, but ONLY from
+ * calls that served the SAME BYTES.
+ *
+ * A record with no fingerprint is ignored rather than trusted: it cannot prove
+ * the agent's copy matches the file on disk now, and an unprovable match is
+ * exactly the case where re-serving is right.
+ */
+function servedRangesForFile(prior, filePath, fingerprint) {
+    if (!prior)
+        return [];
+    const spans = [];
+    for (const call of prior.calls) {
+        for (const file of call.files) {
+            if (file.path !== filePath)
+                continue;
+            if (!file.fingerprint || file.fingerprint !== fingerprint)
+                continue;
+            spans.push(...file.ranges);
+        }
+    }
+    return mergeRanges(spans);
+}
+/** `L12`, `L12-40`, capped with a `+N more` tail. */
+function formatSpans(spans) {
+    const shown = spans.slice(0, exports.EXPLORE_DEDUP.MAX_SPANS_IN_POINTER)
+        .map((r) => (r.start === r.end ? `L${r.start}` : `L${r.start}-${r.end}`))
+        .join(', ');
+    const more = spans.length - exports.EXPLORE_DEDUP.MAX_SPANS_IN_POINTER;
+    return more > 0 ? `${shown}, +${more} more span${more === 1 ? '' : 's'}` : shown;
+}
+/**
+ * The line that replaces withheld source.
+ *
+ * It has one job: make the agent reach into its own context instead of into
+ * Read. So it carries the three things needed to find the source it already has
+ * — path, symbols, line spans — plus the two facts that make using it safe:
+ * that it came from THIS conversation, and that the file has not changed since
+ * (which is checked, not asserted — see {@link fileFingerprint}). It never says
+ * "omitted", and it never steers to Read.
+ */
+function formatBackReference(filePath, covered, symbols, opts) {
+    const names = symbols.slice(0, exports.EXPLORE_DEDUP.MAX_SYMBOLS_IN_POINTER);
+    const moreNames = symbols.length - names.length;
+    const symbolPart = names.length > 0
+        ? ` (${names.join(', ')}${moreNames > 0 ? `, +${moreNames} more` : ''})`
+        : '';
+    const head = `> **Already sent earlier in this conversation:** \`${filePath}\` ${formatSpans(covered)}${symbolPart}`;
+    const tail = opts.partial
+        ? ' — unchanged on disk since, so that copy is still exact. Only the NEW lines are shown below; scroll back for the rest. Do NOT Read this file.'
+        : ' — unchanged on disk since, so that copy is still exact and is not repeated here. Use it from your context; do NOT Read this file.';
+    return head + tail;
+}
+/** Symbol names whose definitions fall inside the withheld spans. */
+function symbolsInSpans(nodes, spans) {
+    const out = [];
+    const seen = new Set();
+    for (const n of nodes) {
+        if (n.kind === 'import' || n.kind === 'export')
+            continue;
+        if (!spans.some((s) => n.startLine <= s.end && (n.endLine || n.startLine) >= s.start))
+            continue;
+        if (seen.has(n.name))
+            continue;
+        seen.add(n.name);
+        out.push(n.name);
+    }
+    return out;
+}
+//# sourceMappingURL=explore-dedup.js.map

package/dist/mcp/explore-dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore-dedup.js","sourceRoot":"","sources":["../../src/mcp/explore-dedup.ts"],"names":[],"mappings":"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"}

package/dist/mcp/explore-repeat-guard.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Session-level explore repeat / partial guidance (generic).
+ *
+ * Stops agents from treating `homegraph_explore` as an iterative keyword
+ * searcher: overlapping queries after a successful explore get a short refuse
+ * instead of another multi-kB payload. Partial/busy replies carry concrete
+ * retry anchors extracted from the query — never an empty 242-char shell.
+ *
+ * Failure fuse (post A/B): hard-cap explores per session, require tight
+ * single-Type follow-ups after 2 calls, and bind Partial → named Next anchor.
+ *
+ * Shape-driven only — no product nouns.
+ */
+import type { ExploreCallRecord, ExploreProjectState } from './explore-session-state';
+/**
+ * Significant tokens for bag-overlap (ASCII identifiers + CJK runs ≥2).
+ */
+export declare function exploreQueryTokens(query: string): Set<string>;
+/** Jaccard overlap in [0, 1]. */
+export declare function queryTokenJaccard(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+/**
+ * Bag similarity: max(Jaccard, one-sided containment).
+ * Paraphrases often keep the same English seeds while swapping CJK filler —
+ * pure Jaccard under-fires on those; containment catches them.
+ */
+export declare function queryTokenOverlapScore(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+/**
+ * Concrete anchors an agent can put in a tighter follow-up explore.
+ * Pure string extraction — no DB.
+ */
+export declare function extractRetryAnchorsFromQuery(query: string): string[];
+/** Anchors present in `query` that never appeared in any prior query string. */
+export declare function novelAnchorsVsPriors(query: string, priors: ReadonlyArray<ExploreCallRecord>): string[];
+/**
+ * Follow-up after the soft budget must be a tight Type/file bag — not another
+ * NL paraphrase that merely picks a Type name from a prior inventory.
+ */
+export declare function isTightExploreFollowUp(query: string): boolean;
+/** Pull `Next anchor` name from a Partial response body. */
+export declare function extractNextAnchorFromText(text: string): string | undefined;
+export declare function inferExplorePartialMeta(text: string): {
+    partial: boolean;
+    nextAnchor?: string;
+};
+export interface ExploreRepeatDecision {
+    refuse: boolean;
+    /** Matched prior call when refusing for overlap. */
+    matched?: ExploreCallRecord;
+    reason: 'overlap' | 'call-budget' | 'hard-cap' | 'next-anchor' | 'ok';
+}
+/**
+ * Whether this explore should short-refuse instead of re-running.
+ */
+export declare function decideExploreRepeat(prior: ExploreProjectState | null | undefined, query: string): ExploreRepeatDecision;
+/** Short success-shaped refuse when a repeat explore would waste tokens. */
+export declare function formatExploreRepeatRefuse(decision: ExploreRepeatDecision, query: string): string;
+export interface DepthToolFuseDecision {
+    refuse: boolean;
+    reason: 'partial-depth-cap' | 'partial-no-callers' | 'ok';
+    nextAnchor?: string;
+}
+/** Latest counted explore call (≥400 response bytes), if any. */
+export declare function latestCountedExplore(prior: ExploreProjectState | null | undefined): ExploreCallRecord | undefined;
+/**
+ * Whether `homegraph_node` / callers / callees should short-refuse after a
+ * Partial explore (same failure class as explore×N — depth fan-out).
+ *
+ * After Partial: callers/callees are refused immediately (wrong tool + often a
+ * multi-def token bomb). `homegraph_node` gets one shot, then refuse.
+ */
+export declare function decideDepthToolFuse(prior: ExploreProjectState | null | undefined, depthCallCount: number, toolName?: string): DepthToolFuseDecision;
+/** Success-shaped refuse when Partial already spent its one depth drill. */
+export declare function formatDepthToolRefuse(decision: DepthToolFuseDecision, toolName: string, symbolHint?: string): string;
+/** Candidate Type for Partial **Next anchor** / digest preference. */
+export interface DomainRoleAnchorCandidate {
+    name: string;
+    kind: string;
+    filePath: string;
+    startLine?: number;
+}
+/**
+ * Score a domain Manager/Service for Next-anchor / digest preference.
+ * Prefer query-token overlap + *Manager /manager/ paths; demote weak *Utils /
+ * *Constants / bare *Subscriber helpers without strong token overlap.
+ *
+ * `domainTokens` (from {@link mechanismDomainPathTokens}) carries CJK→ASCII
+ * stems so NL asks like 通知订阅 rank SubscribeManager over screenlock StateManager.
+ */
+export declare function scoreDomainRoleForQuery(candidate: DomainRoleAnchorCandidate, query: string, domainTokens?: readonly string[]): number;
+/** Best domain-role Type for Next anchor, or undefined when inventory empty. */
+export declare function pickBestDomainRoleAnchor(candidates: ReadonlyArray<DomainRoleAnchorCandidate>, query: string, domainTokens?: readonly string[]): DomainRoleAnchorCandidate | undefined;
+/** Format Next anchor caption used in Partial / soft-close footers. */
+export declare function formatNextAnchorCaption(c: DomainRoleAnchorCandidate): string;
+/**
+ * Soft-close opening banner (must match footer — never pair with Partial locator).
+ */
+export declare function formatMechanismSoftCloseHeader(): string;
+/**
+ * Soft-close footer: enough inventory + digest to answer without another explore.
+ * Must NOT contain "Partial locator" so the session fuse treats the call as closed.
+ */
+export declare function formatMechanismSoftCloseFooter(next?: DomainRoleAnchorCandidate): string;
+/** Honest Partial footer with a single Next anchor + ONE Grep. */
+export declare function formatMechanismPartialFooter(nextCaption: string): string;
+/**
+ * Appended when a second counted Partial is emitted in the same session —
+ * stop HomeGraph; do not take a third explore.
+ */
+export declare function formatSecondPartialStopFooter(nextAnchor?: string): string;
+/**
+ * Intent phrases that must ride with a bare Type on Partial retry —
+ * dropping them collapses data-source / event-dispatch surveys into empty compact.
+ */
+export declare function extractRetryIntentHints(query: string): string[];
+/**
+ * Busy/deadline Partial with actionable anchors from the query (no DB).
+ */
+export declare function formatPartialExploreGuidance(opts: {
+    seconds: number;
+    query?: string;
+    why?: string;
+}): string;
+//# sourceMappingURL=explore-repeat-guard.d.ts.map

package/dist/mcp/explore-repeat-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore-repeat-guard.d.ts","sourceRoot":"","sources":["../../src/mcp/explore-repeat-guard.ts"],"names":[],"mappings":"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"}